fix(guard): switching to Build no longer hijacks the session back to Goal

[devinoldenburg]

Closes #428

When using the goal agent and then switching to Build, it temporarily works. However, once the build response finishes, it automatically switches back to the goal agent, attempting to run reviews and also switching the main agent.

Root cause

When a user switches a goal session off the goal agent (to Build/Plan, or via an action that cycles the agent), chat.params / chat.message faithfully set state.active = false. But the idle handler's "is this still a Goal session?" check ignored that deactivation:

// plugins/goal-guard/guard.js — resolveIdleSession()
const goalSession =
  state.active ||
  Boolean(state.contract) ||              // ← stale contract re-activates
  goalSessionActiveForAgent("goal", state); // ← TAUTOLOGY: always returns true

• Boolean(state.contract) — the contract persists from the prior goal, so a stale contract re-activated the session.
• goalSessionActiveForAgent("goal", state) is tautological — goalSessionActiveForAgent returns true unconditionally when its first argument is the primary "goal" agent (see agents.js), so once a session had ever been a goal, the idle path treated it as a goal forever, no matter how many times the user switched away.

The result: on the Build turn's idle, canProgrammaticReview evaluated to true, the guard launched a programmatic review cycle, and launchReviewBatch — which pins the batch to PRIMARY_AGENT — switched the user's main agent back to goal, exactly the symptom in the bug report.

The fix

Two changes, both small and surgical:

1. Honor explicit deactivation in the idle path (root cause)

plugins/goal-guard/guard.js — resolveIdleSession() now requires state.active for a session to be eligible for programmatic review or auto-continue:

const goalSession = state.active;

A stale contract (or any other persisted goal state) can no longer re-activate a session the user explicitly paused. Switching back to the goal agent (or running /goal) re-activates it as before, and reviews then resume with all of the contract, evidence, and review-cycle state intact.

2. Defense-in-depth in launchReviewBatch

plugins/goal-guard/review-runner.js — launchReviewBatch() now refuses to run on a state.active === false session, surfacing as a SessionBusyError so the outer retry loop defers cleanly. This guarantees that even a future regression in the idle-path eligibility check can never reach the call that pins the batch to PRIMARY_AGENT and switches the user's main agent back to goal. state is the live store record, so a fresh agent switch is reflected here even if it happened after the caller's eligibility check.

Why this is the smallest correct change

• The other two terms in the old goalSession expression were either always-true (the tautology) or ignored deactivation (the contract). Removing them is strictly more correct — state.active was already the source of truth everywhere else (auto-continue, the state.dirty && state.active and state.active && !completionAllowed log branches, sidebar scoping, etc.).
• The worker-handoff path (goal-implementer, goal-explorer, …) is preserved: those agents keep state.active = true via goalSessionActiveForAgent in chat.params/chat.message, so programmatic reviews still run after a worker handoff — covered by the existing programmatic review runs when a goal worker subagent was the last agent on the session test.
• Re-activation on switching back to goal is unchanged and explicitly tested.

Regression coverage

Three new tests, all named REGRESSION [issue #428]:

Test	File	Asserts
a goal session switched to Build is NOT re-activated on idle (no reviews, no agent switch)	tests/plugin.test.mjs	The exact reported flow — /goal → switch to Build → prompt Build → idle → 0 reviewer subtasks launched, no agent: "goal" prompt sent, goal state preserved.
companion: switching back to Goal re-activates and programmatic review resumes	tests/plugin.test.mjs	Goal → Build (idle inert) → back to Goal → idle runs ≥5 reviewers. The fix does not over-fire.
a deactivated session never launches a reviewer batch (defense-in-depth in launchReviewBatch)	tests/programmatic-review.test.mjs	The defense-in-depth guard refuses to launch on a Build session; re-activation recovers cleanly.

Verification

• ✅ npm test — 676/676 pass (673 baseline + 3 new). Includes the existing programmatic review runs when a goal worker subagent was the last agent on the session parity test, which still passes.
• ✅ npm run lint — no new diagnostics (64 warnings / 60 infos are pre-existing on main, verified via git stash).
• ✅ node scripts/validate-opencode-config.mjs — OpenCode Goal Mode package validation passed.

Files changed

 plugins/goal-guard/guard.js         |  23 ++++++--    (root-cause fix + comment)
 plugins/goal-guard/review-runner.js |  17 ++++++      (defense-in-depth)
 tests/plugin.test.mjs               | 111 ++++++++++++++++++++++++++++   (2 regression tests)
 tests/programmatic-review.test.mjs  |  21 ++++++      (1 defense-in-depth test)
 README.md                           |  12 +++-        (troubleshooting note clarified)
 CHANGELOG.md                        |  33 +++++++++++  (Unreleased fix entry)
 6 files changed, 210 insertions(+), 7 deletions(-)

Docs

• README.md troubleshooting — the "Goal Mode stopped after switching agents" entry now explicitly lists everything that halts when paused (sidebar, completion rewrites, auto-continue, and programmatic reviews), with a direct callout that the guard will never switch the main agent back to goal on its own.
• CHANGELOG.md — new ## Unreleased → ### Fix: switching to Build no longer hijacks the session back to Goal (issue #428) entry following the established format (root cause + fix narrative for release readers).

Closes #428.