@sorenllm/opencode-forge 0.11.2 → 0.12.0

package/README.md

@@ -150,8 +150,8 @@ and the plugin's command of that name is not registered.
    (otherwise the name lingers in the agent list).
 4. Done — all runtime injections (agents, tool hiding, commands) are gone
    with the plugin; nothing was ever written to your config
-   (the hide was runtime-only). Your `.opencode/plan/` and `.opencode/goal/`
-   files are yours; delete them yourself if you want.
+   (the hide was runtime-only). Your `.opencode/plan/`, `.opencode/goal/`,
+   and `.opencode/crew/` files are yours; delete them yourself if you want.
  5. Optional runtime debris: delete `<tmp>/opencode-forge/` (job logs, the
     job registry ledger, the watchdog ledger, and any leftover dispatch
     ledger from older versions — the file ledger table above lists
@@ -165,6 +165,7 @@ What this plugin touches, exhaustively:
 | --- | --- | --- |
 | `<project>/.opencode/plan/*.md` | plan files | user data — kept forever, uninstall never deletes |
 | `<project>/.opencode/goal/*.md` | goal files (contract, Check Log, Turn Ledger) | user data — kept forever, uninstall never deletes |
+| `<project>/.opencode/crew/*.md` | crew records (declared plan + arm/convert/abandon/close history; written at `crew_begin` registration, appended at each transition; record-only — never a resume mechanism) | user data — kept forever, uninstall never deletes |
 | merged config object (RAM only) | forge agent, static `forge-<id>` subagents, tool-partition injections (forge family shell hide, non-forge forge-tool hide, native build/plan/general/explore minimal entries), `command.plan`, `command.goal`, `command.crew`, goal permission keys, `permission.forge_shell`, `permission.crew_close` | vanishes when the plugin is removed; nothing is written to disk |
 | `<tmp>/opencode-forge/jobs/<jobId>.log` | job output tee (full output; oldest rotated out above 50 files) | runtime debris — delete freely, also after uninstall |
 | `<tmp>/opencode-forge/jobs/ledger.jsonl` | job registry ledger (bounded: 1 MB reset, 200 entries) | runtime debris — delete freely, also after uninstall |
@@ -536,23 +537,69 @@ mid-session never rewrites a running session).
 ## Crew workflow (`/crew`)
 
 `/crew <objective>` is the third state-activation command next to `/plan` and
-`/goal`: it enters crew orchestration discipline for the session. The flow:
+`/goal`: it enters crew orchestration discipline for the session. The macro
+contract above the crew may come from an approved plan, an OpenSpec change, or
+inline text — the discipline is identical in all three cases and never
+requires a plan. The flow:
 
 1. **Register** the declared plan: `crew_begin {objective, subtasks}` — one
    titled subtask each, optionally naming the intended `forge-*` agent.
-2. **Execute in waves** of parallel native `task` calls (results return
-   in-turn; the next wave launches only after the previous wave's results).
-3. **Missing role?** Run the subtask through a native task call anyway and
+   Registration enters a **PENDING** crew: execution has not started. The
+   registration output confirms the roster **with its origin** (which
+   forge.json layer the dispatchable set materialized from), points at the
+   crew record file, presents the three execution-mode choices, and stops the
+   turn. Reconnaissance task calls are free BEFORE registration.
+2. **The pause is mechanical**: while the crew pends, every `task` dispatch is
+   refused by an interception belt. The user chooses:
+   - **supervised waves now** — `crew_begin {execution: "waves"}` lifts the
+     belt and the wave discipline runs;
+   - **convert to a goal contract** — `crew_begin {execution: "goal"}` ends
+     the crew as a conversion record and the session drafts `goal_write`
+     (arm=true) folding the declared subtasks into criteria/checks; the arm
+     dialog is the user's gate;
+   - **standby** — no call; the crew waits until armed or abandoned.
+3. **Execute in waves** (armed crews only) of parallel native `task` calls
+   (results return in-turn; the next wave launches only after the previous
+   wave's results). GUI / computer-use subtasks are mutually exclusive within
+   a wave (the desktop is a singleton; non-GUI subtasks still parallelize
+   freely), and GUI walkthroughs use the `computer` tool rather than DIY
+   shell screenshot pipelines.
+4. **Missing role?** Run the subtask through a native task call anyway and
    tell the user — suggest configuring the missing role.
-4. **Verify** each subtask against its acceptance-evidence statement;
+5. **Verify** each subtask against its acceptance-evidence statement;
    retry a failure at most once.
-5. **Close** with `crew_close` — a hard, ask-gated gate cross-checking the
+6. **Close** with `crew_close` — a hard, ask-gated gate cross-checking the
    report against the DECLARED plan: every declared subtask needs a
    PASS/FAIL verdict with evidence; an undeclared subtask in the report
    refuses the close (fold discoveries into an existing verdict, or discard
-   and re-crew); a FAIL needs both failure reports. The close output is the
-   crew's record — crew state is in-memory and a host restart ends it
-   honestly.
+   and re-crew); a FAIL needs both failure reports.
+7. **Re-shard exit**: `crew_close {abandon: true, reason}` abandons the crew
+   — ask-gated like the close, no verdict requirements, usable from PENDING
+   (standby cancel) and EXECUTING (wrong decomposition) alike. The session is
+   immediately free for a fresh `crew_begin` with the corrected plan.
+
+**Crew record**: registration writes `.opencode/crew/<date>-<slug>.md` under
+the session anchor with the declared plan; arm / convert / abandon / close
+append to it. It is inspectable history and a compaction-recovery anchor —
+NOT a resume mechanism: crew state is in-memory and a host restart ends it
+honestly (a stale record is inert).
+
+**Goal-delegated orchestration**: while a live ACTIVE goal governs the
+session, the pause folds into the goal's own authorization —
+`crew_begin {objective, subtasks, execution: "waves"}` in ONE call is legal
+(born armed, never pends), `crew_close` (report and abandon) are ask-free
+(the goal's arm/complete/budget gates are the user boundary), and
+`execution: "goal"` is refused (already governed). The goal continuation
+brief carries the own-the-crew-layer directive, so an armed loop can crew,
+re-shard (`abandon` + fresh one-call registration), and close without a human
+turn. Neither harness requires its slash command — the ask dialogs are the
+authorization surfaces; the templates are discipline carriers.
+
+**Artifact anchoring** (plan / goal / crew alike): a git-repo session anchors
+artifacts at the repo root; a plain-folder session anchors at the folder
+itself (a rootish guard keeps degenerate global-project worktrees from
+landing files on the drive root or the launch anchor). The anchor follows the
+session's workspace, never the objective's scope.
 
 **Not initialized?** `/crew` on a host with zero usable forge agents refuses
 with one-time setup guidance: the two file paths, a copy-paste template, and

package/dist/index.js

@@ -15684,6 +15684,57 @@ function loaderForAnchor(anchor) {
   return l;
 }
 var crews = new Map;
+function crewRecordPathFor(worktree, objective) {
+  const dir = join6(worktree, ".opencode", "crew");
+  const date5 = localDateNow();
+  const slug = slugifyGoal(objective) || "crew";
+  let name = `${date5}-${slug}.md`;
+  let n = 2;
+  while (existsSync3(join6(dir, name)))
+    name = `${date5}-${slug}-${n++}.md`;
+  return join6(dir, name);
+}
+function writeCrewRecord(path, objective, anchor, subtasks) {
+  mkdirSync5(join6(path, ".."), { recursive: true });
+  writeFileSync5(path, [
+    `# Crew Record: ${objective}`,
+    "",
+    `- registered: ${nowIso()}`,
+    `- anchor: ${anchor}`,
+    "",
+    `## Declared plan (${subtasks.length})`,
+    ...subtasks.map((s, i) => `${i + 1}. ${s.title}${s.agent ? ` → ${s.agent}` : ""}`),
+    ""
+  ].join(`
+`) + `
+`, "utf8");
+}
+function appendCrewRecord(path, heading, lines) {
+  if (!path)
+    return;
+  try {
+    appendFileSync(path, [`## ${nowIso()} — ${heading}`, ...lines, ""].join(`
+`) + `
+`, "utf8");
+  } catch {}
+}
+function governingGoalFor(sessionID) {
+  if (!sessionID)
+    return false;
+  const state = stateForBan(sessionID);
+  if (!state)
+    return false;
+  const goal = resolveLiveGoal(state);
+  return Boolean(goal && goal.doc.status === "active" && goal.doc.session === sessionID);
+}
+function crewPendingChoiceLines() {
+  return [
+    "[forge:crew] The crew is PENDING — execution has NOT started. Present the execution-mode choice to the user and END YOUR TURN (every task dispatch is refused while the crew pends):",
+    `  1. supervised waves NOW — when the user says go, call crew_begin {execution: "waves"} and run the wave discipline;`,
+    `  2. convert to a goal contract — call crew_begin {execution: "goal"} (the crew ends as a conversion record; no extra dialog here), then draft goal_write with arm=true folding the declared subtasks into criteria/checks — the arm dialog is the user's gate;`,
+    `  3. standby — no call; the crew waits until armed or abandoned.`
+  ];
+}
 var modelsDevCatalog = null;
 var depthFindingNotes = new Map;
 var crewCommandSnapshot = null;
@@ -16516,21 +16567,23 @@ function crewOrchestrationTemplate(agentIds) {
     "",
     `Configured forge subagents (task-tool vocabulary): ${agentIds.map((id) => `forge-${id}`).join(", ")}`,
     "",
-    "You are entering CREW ORCHESTRATION discipline for this session (single subject: do not switch agents). Follow it exactly:",
+    "You are entering CREW ORCHESTRATION discipline for this session (single subject: do not switch agents). The macro contract above the crew may come from an approved plan, a spec change, or inline text — the discipline is identical in all three cases and never requires a plan. Follow it exactly:",
     "",
-    "1. REGISTER: call `crew_begin` with the objective AND the declared subtask plan (subtasks[]: one {title} per subtask, optionally naming the intended forge-* agent). If crew_begin refuses (a crew is already active here, or a plan draft is active), STOP and tell the user why — never start a second crew. Reconnaissance first if you need it to decompose well; a wrong plan is fixed by discarding and re-crewing, never by improvising outside the declared plan.",
-    "2. WAVES, NEVER FLOODS: execute subtasks in waves of parallel native `task` calls (subagent_type = the matching forge-* agent; a wave's results return within the calling turn). Launch the next wave ONLY after the previous wave's results are in.",
-    "3. MISSING ROLE: when a subtask needs a role no configured forge-* agent matches, run that subtask through a native task call anyway AND tell the user about the gap — suggest configuring the missing role in forge.json.",
-    "4. VERIFY: judge each subtask strictly against its acceptance-evidence statement from the task result text. A result that does not meet the statement is a failure even if the worker sounded confident.",
-    "5. RETRY AT MOST ONCE: a failed subtask may be retried once with an adjusted prompt or agent. If the retry also fails, record the subtask as FAIL with BOTH failure reports visible (attempts[]). Do not retry twice, do not paper over a failure.",
-    "6. CLOSE: when every declared subtask has a verdict, call `crew_close` with the full report (title/verdict/evidence per subtask; attempts[] for FAILs). The gate cross-checks your report against the declared plan — a declared subtask missing from the report refuses the close, and so does an undeclared one. The user confirms the closing dialog."
+    "1. REGISTER: call `crew_begin` with the objective AND the declared subtask plan (subtasks[]: one {title} per subtask, optionally naming the intended forge-* agent). Reconnaissance BEFORE registration is free (task calls included). If crew_begin refuses (a crew is already active here, or a plan draft is active), STOP and tell the user why — never start a second crew. A wrong plan is fixed by abandoning and re-crewing (crew_close {abandon: true, reason}), never by improvising outside the declared plan.",
+    `2. THE PAUSE: registration enters a PENDING crew — execution has NOT started. STOP and present the user the three execution-mode choices (supervised waves now / convert to a goal contract / standby), then END YOUR TURN. Arm per the user's choice: waves → crew_begin {execution: "waves"}; conversion → crew_begin {execution: "goal"} followed by goal_write (arm=true — its dialog is the user's gate) folding the declared subtasks into criteria/checks; standby → no call. EXCEPTION: while a live active goal governs this session, register with execution: "waves" in the SAME call — the crew is born armed (the goal contract already authorized orchestration) and crew_close / abandon stay ask-free under that goal.`,
+    "3. WAVES, NEVER FLOODS (armed crews only): execute subtasks in waves of parallel native `task` calls (subagent_type = the matching forge-* agent; a wave's results return within the calling turn). Launch the next wave ONLY after the previous wave's results are in. GUI / computer-use subtasks are mutually exclusive within a wave (the desktop is a singleton resource — at most ONE in flight; non-GUI subtasks still parallelize freely), and GUI walkthroughs use the `computer` tool rather than DIY shell screenshot pipelines.",
+    "4. MISSING ROLE: when a subtask needs a role no configured forge-* agent matches, run that subtask through a native task call anyway AND tell the user about the gap — suggest configuring the missing role in forge.json.",
+    "5. VERIFY: judge each subtask strictly against its acceptance-evidence statement from the task result text. A result that does not meet the statement is a failure even if the worker sounded confident.",
+    "6. RETRY AT MOST ONCE: a failed subtask may be retried once with an adjusted prompt or agent. If the retry also fails, record the subtask as FAIL with BOTH failure reports visible (attempts[]). Do not retry twice, do not paper over a failure.",
+    "7. CLOSE: when every declared subtask has a verdict, call `crew_close` with the full report (title/verdict/evidence per subtask; attempts[] for FAILs). The gate cross-checks the report against the declared plan — a declared subtask missing from the report refuses the close, and so does an undeclared one. The user confirms the closing dialog (ask-free while a goal governs the session)."
   ].join(`
 `);
 }
 var crewBeginTool = tool({
-  description: "Register this session's crew (from /crew) with its DECLARED subtask plan. Refuses when a crew is already active in the session, while a plan draft is active, or when subtasks are missing/duplicated. Crew state is in-memory: a host restart ends it honestly.",
+  description: `Register this session's crew (from /crew) with its DECLARED subtask plan — the crew starts PENDING: the execution-mode choice (waves / convert to goal / standby) is the user's. Dual-purpose: called with {execution} ONLY (no objective/subtasks) it ARMS the pending crew — "waves" lifts the dispatch belt, "goal" ends the crew as a conversion record (the following goal_write arm dialog is the user's gate). One-call register+arm ({objective, subtasks, execution:"waves"}) is legal ONLY while a live active goal governs the session (born armed, never pends). Refuses: active crew, plan draft, missing/duplicated subtasks. Crew state is in-memory: a host restart ends it honestly.`,
   args: {
-    objective: tool.schema.string().describe("One-line crew objective (from /crew)"),
+    objective: tool.schema.string().optional().describe("One-line crew objective (from /crew) — required on registration, ABSENT on the arm call"),
+    execution: tool.schema.string().optional().describe('Arm action: "waves" (supervised waves — lifts the belt) or "goal" (convert to a goal contract). Alone = arm the pending crew; with objective+subtasks = one-call born-armed registration, legal only under a governing active goal.'),
     subtasks: tool.schema.array(tool.schema.object({
       title: tool.schema.string().describe("Short unique subtask title — the crew_close report must use these exact titles"),
       agent: tool.schema.string().optional().describe("Intended forge-* agent id for this subtask, when one matches")
@@ -16550,23 +16603,69 @@ var crewBeginTool = tool({
     const sessionLoaded = anchor && anchor !== hostAnchorDir ? loaderForAnchor(anchor).load() : hostLoaded;
     const sessionProject = sessionLoaded?.projectPath ?? null;
     if (hostIds.length === 0) {
-      const paths = forgeConfigPaths({ projectDir: hostAnchorDir || undefined, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() });
-      const lines = [
+      const paths2 = forgeConfigPaths({ projectDir: hostAnchorDir || undefined, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() });
+      const lines2 = [
         "[forge:crew] CREW IS NOT INITIALIZED on this host: no forge subagents are materialized. Crew orchestration is unavailable until the user sets it up.",
-        `Two layers, MERGED (the project layer overrides the global one per agent id): ${paths.project} (nearest .opencode/forge.json walking up from the workspace) OR ${paths.global}.`,
+        `Two layers, MERGED (the project layer overrides the global one per agent id): ${paths2.project} (nearest .opencode/forge.json walking up from the workspace) OR ${paths2.global}.`,
         'Template (JSONC): {"agents": {"research": {"model": "provider/model", "thoughtLevel": "low", "prompt": "short role description"}}}',
         "Agent ids are plain role words WITHOUT the `forge-` prefix — the plugin materializes each id as `forge-<id>` (a prefixed id is auto-stripped with a warning).",
         "The user may configure it themselves, or ask you to write the file — only on their explicit go-ahead. When you write it, give every agent a SHORT prompt from the role the user asked for (one or two sentences; long only on explicit request) — without a prompt, custom ids get a generic one-liner and will not know their job. Newly added agents need a host restart; thoughtLevel edits apply without one."
       ];
       if (sessionLoaded && Object.keys(sessionLoaded.agents).length > 0 && sessionProject) {
-        lines.push(`NOTE: this session's workspace DOES have a forge.json (${sessionProject}) with usable agents — but this host instance was launched from ${hostAnchorDir || "a different directory"}, so they are not in the task vocabulary. Relaunch opencode in that workspace, or add the agents to the global layer.`);
+        lines2.push(`NOTE: this session's workspace DOES have a forge.json (${sessionProject}) with usable agents — but this host instance was launched from ${hostAnchorDir || "a different directory"}, so they are not in the task vocabulary. Relaunch opencode in that workspace, or add the agents to the global layer.`);
       }
-      throw new Error(lines.join(`
+      throw new Error(lines2.join(`
 `));
     }
-    if (!args.objective?.trim())
-      throw new Error("crew_begin requires a non-empty objective (from /crew <objective>).");
+    const execution = typeof args.execution === "string" ? args.execution.trim().toLowerCase() : "";
+    if (execution && execution !== "waves" && execution !== "goal") {
+      throw new Error('[forge:crew] execution must be "waves" or "goal".');
+    }
+    const objectiveText = String(args.objective ?? "").trim();
     const raw = Array.isArray(args.subtasks) ? args.subtasks : [];
+    if (execution && !objectiveText && raw.length === 0) {
+      const crew = crews.get(context.sessionID);
+      if (!crew) {
+        throw new Error("[forge:crew] No active crew to arm (crew state is in-memory and dies on host restart). Register one first: crew_begin {objective, subtasks}.");
+      }
+      if (crew.mode !== "pending") {
+        throw new Error(`[forge:crew] This crew is already armed (${crew.mode}) — execute "${crew.objective}" instead of re-arming.`);
+      }
+      if (execution === "goal" && governingGoalFor(context.sessionID)) {
+        throw new Error('[forge:crew] execution:"goal" is refused under a governing goal — this session already runs inside an active goal contract. Run supervised waves (arm or one-call register), or pause/discard the goal first if conversion is truly intended.');
+      }
+      if (execution === "goal") {
+        crews.delete(context.sessionID);
+        appendCrewRecord(crew.recordPath, "converted to goal", [
+          "The crew ends here as a conversion record; the objective moves to a goal contract.",
+          ...crew.subtasks.map((s, i) => `${i + 1}. ${s.title}${s.agent ? ` → ${s.agent}` : ""}`)
+        ]);
+        return {
+          title: `crew converted: ${crew.objective.slice(0, 60)}`,
+          output: [
+            `[forge:crew] Crew ended as a CONVERSION record: ${crew.objective}`,
+            "Now draft the goal contract: goal_write with arm=true, folding the declared subtasks below into its criteria and verification checks. The arm confirmation dialog is the user's gate for the whole autonomous path — do not ask again here.",
+            `Declared subtasks to fold in (${crew.subtasks.length}):`,
+            ...crew.subtasks.map((s, i) => `  ${i + 1}. ${s.title}${s.agent ? ` → ${s.agent}` : ""}`)
+          ].join(`
+`)
+        };
+      }
+      crew.mode = "executing";
+      appendCrewRecord(crew.recordPath, "armed (waves)", ["The user chose supervised waves; the dispatch belt is lifted."]);
+      return {
+        title: `crew armed: ${crew.objective.slice(0, 60)}`,
+        output: [
+          `[forge:crew] Crew ARMED for supervised waves: ${crew.objective}`,
+          `Declared plan (${crew.subtasks.length}):`,
+          ...crew.subtasks.map((s, i) => `  ${i + 1}. ${s.title}${s.agent ? ` → ${s.agent}` : ""}`),
+          "Proceed with the wave discipline: waves of parallel native task calls (next wave after the previous results) → per-subtask evidence verdicts → at most one retry → crew_close with the full report covering every declared subtask."
+        ].join(`
+`)
+      };
+    }
+    if (!objectiveText)
+      throw new Error("crew_begin requires a non-empty objective (from /crew <objective>).");
     if (raw.length === 0)
       throw new Error("[forge:crew] crew_begin requires subtasks[] — declare the plan before executing (decompose the objective into titled subtasks).");
     const seen = new Set;
@@ -16586,7 +16685,28 @@ var crewBeginTool = tool({
     if (existing) {
       throw new Error(`[forge:crew] This session already has an active crew: "${existing.objective}" (started ${existing.startedAt}). Finish and close it with crew_close before starting another.`);
     }
-    crews.set(context.sessionID, { objective: args.objective.trim(), startedAt: nowIso(), subtasks });
+    if (execution === "waves" && !governingGoalFor(context.sessionID)) {
+      throw new Error("[forge:crew] crew_begin cannot self-arm outside a governing goal: register with {objective, subtasks} only — the pause is the user's decision point, armed by a follow-up crew_begin {execution} call per their choice.");
+    }
+    if (execution === "goal") {
+      throw new Error('[forge:crew] execution:"goal" converts an already-registered PENDING crew — register the plan first (no execution), then convert. Under a governing goal, only "waves" one-call arming is legal (the loop already owns the goal).');
+    }
+    const governed = execution === "waves";
+    const anchorDir = anchor || hostWorktree;
+    let recordPath = null;
+    let recordNote = "";
+    if (anchorDir) {
+      try {
+        recordPath = crewRecordPathFor(anchorDir, objectiveText);
+        writeCrewRecord(recordPath, objectiveText, anchorDir, subtasks);
+        recordNote = `Crew record (inspectable history; NOT a resume mechanism): ${relFrom(anchorDir, recordPath)}`;
+      } catch {
+        recordPath = null;
+        recordNote = "Crew record could not be written (fail-soft; the crew still runs).";
+      }
+    }
+    crews.set(context.sessionID, { objective: objectiveText, startedAt: nowIso(), subtasks, mode: governed ? "executing" : "pending", recordPath });
+    appendCrewRecord(recordPath, governed ? "registered (born armed under a governing goal)" : "registered (pending)", subtasks.map((s, i) => `${i + 1}. ${s.title}${s.agent ? ` → ${s.agent}` : ""}`));
     let disclosure = "";
     if (sessionProject && sessionProject !== (hostLoaded?.projectPath ?? null)) {
       const localOnly = Object.keys(sessionLoaded?.agents ?? {}).filter((id) => !hostIds.includes(id));
@@ -16595,34 +16715,62 @@ var crewBeginTool = tool({
 [forge:crew] NOTE: this session's workspace has its own forge.json (${sessionProject}) defining ${localOnly.map((id) => `forge-${id}`).join(", ")} — NOT dispatchable on this host (launched from ${hostAnchorDir || "a different directory"}). Relaunch opencode in that workspace to use them, or fold them into the global layer.`;
       }
     }
+    const paths = forgeConfigPaths({ projectDir: hostAnchorDir || undefined, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() });
+    const originDesc = hostLoaded?.projectPath ? `the project layer ${hostLoaded.projectPath}${hostLoaded.source === "project+global" ? ` merged with the global layer (${paths.global})` : ""}` : `the global layer (${paths.global})`;
+    const lines = [
+      governed ? `[forge:crew] Crew registered UNDER THE GOVERNING GOAL — born armed, never pends. Objective: ${objectiveText}` : `[forge:crew] Crew registered PENDING for this session (execution has NOT started). Objective: ${objectiveText}`,
+      `Declared plan (${subtasks.length}):`,
+      ...subtasks.map((s, i) => `  ${i + 1}. ${s.title}${s.agent ? ` → ${s.agent}` : ""}`),
+      `Dispatchable roster origin: ${originDesc} — materialized by this host instance${hostAnchorDir ? ` (launched from ${hostAnchorDir})` : ""}.`,
+      ...recordNote ? [recordNote] : [],
+      ...disclosure ? [disclosure] : []
+    ];
+    if (governed) {
+      lines.push("Goal-delegated orchestration: the governing goal contract already authorized this crew — run the wave discipline NOW (crew gates stay internal to the loop; crew_close and abandon are ask-free under this goal), and re-shard via crew_close {abandon: true, reason} + a fresh one-call crew_begin when the decomposition proves wrong.", "Wave discipline: waves of parallel native task calls (next wave after the previous results) → per-subtask evidence verdicts → at most one retry → crew_close with the full report covering every declared subtask.");
+    } else {
+      lines.push(...crewPendingChoiceLines());
+    }
     return {
-      title: `crew registered: ${args.objective.trim().slice(0, 60)}`,
-      output: [
-        `[forge:crew] Crew registered for this session. Objective: ${args.objective.trim()}`,
-        `Declared plan (${subtasks.length}):`,
-        ...subtasks.map((s, i) => `  ${i + 1}. ${s.title}${s.agent ? ` → ${s.agent}` : ""}`),
-        "Proceed with the discipline: waves of parallel native task calls (next wave after the previous results) → per-subtask evidence verdicts → at most one retry → crew_close with the full report covering every declared subtask.",
-        ...disclosure ? [disclosure] : []
-      ].join(`
+      title: `crew registered: ${objectiveText.slice(0, 60)}`,
+      output: lines.join(`
 `)
     };
   }
 });
 var crewCloseTool = tool({
-  description: "Close this session's crew with the final report (ask-level user confirmation). The gate cross-checks the report against the declared subtask plan: every declared subtask needs a verdict (PASS/FAIL) and an evidence statement; an undeclared subtask in the report refuses the close; FAIL requires both failure reports (attempt + the one retry). On success the crew ends and the summary is the tool output (there is no persistent crew record).",
+  description: "Close this session's crew. Two paths: (a) final report — the gate cross-checks the report against the declared subtask plan (every declared subtask needs a verdict and an evidence statement; an undeclared subtask refuses the close; FAIL requires both failure reports); (b) abandon {abandon: true, reason} — the re-shard exit: no verdict requirements, ends the crew with an abandonment record, frees the session for a fresh crew_begin. Both paths are ask-gated UNLESS a live active goal governs the session (then ask-free — the goal's own gates are the user boundary).",
   args: {
     report: tool.schema.array(tool.schema.object({
       title: tool.schema.string().describe("Subtask title — must match a title declared at crew_begin"),
       verdict: tool.schema.string().describe("PASS or FAIL"),
       evidence: tool.schema.string().describe("Acceptance evidence: what the result contained that satisfies the acceptance statement"),
       attempts: tool.schema.array(tool.schema.string()).optional().describe("For FAIL: both failure reports (attempt and retry)")
-    })).describe("The full crew report — one entry per declared subtask")
+    })).optional().describe("The full crew report — one entry per declared subtask (not needed when abandoning)"),
+    abandon: tool.schema.boolean().optional().describe("true = abandon the crew (re-shard / standby-cancel): ends it with an abandonment record, no verdicts required"),
+    reason: tool.schema.string().optional().describe("Why the crew is abandoned (recorded in the crew record)")
   },
   execute: async (args, context) => {
     noteToolAgent(context);
     const crew = crews.get(context.sessionID);
     if (!crew)
       throw new Error("[forge:crew] No active crew in this session (crew state is in-memory and dies on host restart). Start one with /crew <objective>.");
+    if (args.abandon === true) {
+      const reason = String(args.reason ?? "").trim() || "(no reason given)";
+      if (!governingGoalFor(context.sessionID))
+        await gate(context.ask, "crew_close", `Abandon crew: ${crew.objective}`);
+      crews.delete(context.sessionID);
+      appendCrewRecord(crew.recordPath, "abandoned", [`mode at abandon: ${crew.mode}`, `reason: ${reason}`, "The session is free for a fresh crew_begin (re-shard or new objective)."]);
+      return {
+        title: `crew abandoned: ${crew.objective.slice(0, 60)}`,
+        output: [
+          `[forge:crew] Crew ABANDONED: ${crew.objective}`,
+          `mode at abandon: ${crew.mode}`,
+          `reason: ${reason}`,
+          "The session is free for a fresh crew_begin — register the corrected plan next (it starts PENDING again unless a governing goal arms it in the same call)."
+        ].join(`
+`)
+      };
+    }
     const report = args.report ?? [];
     const check2 = validateCrewReport(report, crew.subtasks);
     if (!check2.ok) {
@@ -16631,16 +16779,21 @@ ${check2.gaps.map((g) => `- ${g}`).join(`
 `)}
 The crew stays active; complete or correct the report and call crew_close again.`);
     }
-    await gate(context.ask, "crew_close", `Close crew: ${crew.objective}`);
+    if (!governingGoalFor(context.sessionID))
+      await gate(context.ask, "crew_close", `Close crew: ${crew.objective}`);
     crews.delete(context.sessionID);
     const fails = report.filter((r) => String(r.verdict).toUpperCase() === "FAIL").length;
+    appendCrewRecord(crew.recordPath, "closed", [
+      `subtasks: ${report.length} (PASS ${report.length - fails}, FAIL ${fails})`,
+      ...report.map((r) => `- ${r.title}: ${String(r.verdict).toUpperCase()} — ${String(r.evidence).slice(0, 200)}`)
+    ]);
     return {
       title: `crew closed: ${crew.objective.slice(0, 60)}`,
       output: [
         `[forge:crew] Crew closed: ${crew.objective}`,
         `subtasks: ${report.length} (PASS ${report.length - fails}, FAIL ${fails})`,
         ...report.map((r) => `- ${r.title}: ${String(r.verdict).toUpperCase()} — ${String(r.evidence).slice(0, 200)}`),
-        "This output is the crew's record (crew state is in-memory; nothing persists)."
+        crew.recordPath ? `Crew record (history): ${crew.recordPath}` : "This output is the crew's record (crew state is in-memory; nothing persists)."
       ].join(`
 `)
     };
@@ -16723,6 +16876,7 @@ ${d.checks.map((c, i) => `${i + 1}. ${c.kind === "shell" ? `shell \`${c.cmd}\``
 `)}`,
     d.constraints.trim() ? `Constraints: ${d.constraints.trim()}` : "",
     `Budget: ${d.turnsUsed}/${d.maxTurns} turns used. Work the criteria now; call goal_check when you believe they hold, then goal_complete (it re-runs every check itself and asks the user). If genuinely blocked, call goal_pause with the blocker — do not spin.`,
+    `Crew layer: you own it under this goal — when parallel decomposition serves a criterion, register crews with crew_begin {objective, subtasks, execution: "waves"} in ONE call (born armed; no pause mid-loop), dispatch forge-* waves, and re-shard a wrong decomposition via crew_close {abandon: true, reason} plus a fresh registration. Crew gates stay internal to this loop.`,
     `Goal file: ${relFrom(state.worktree, goal.path)}`
   ].filter((s) => s.length > 0).join(`
 `);
@@ -17098,6 +17252,10 @@ var server = async (input, options) => {
             throw new Error(`[forge:partition] Dispatch refused: "${target}" is a forge-family worker and the current agent ("${speaker}") is outside the forge family. Use the native general/explore subagents, or switch to the forge agent to dispatch forge-* workers.`);
           }
         }
+        const pendingCrew = input2.sessionID ? crews.get(input2.sessionID) : undefined;
+        if (pendingCrew && pendingCrew.mode === "pending") {
+          throw new Error(`[forge:crew] Dispatch refused: the crew "${pendingCrew.objective}" is PENDING (registered, not armed). Present the execution-mode choice to the user — supervised waves now / convert to a goal contract / standby — then arm per their choice with crew_begin {execution: "waves" | "goal"}. Reconnaissance task calls are free only BEFORE registration.`);
+        }
       }
       if ((input2.tool === "write" || input2.tool === "edit") && input2.sessionID) {
         const speaker = sessionAgents.get(input2.sessionID);
@@ -17284,7 +17442,8 @@ var server = async (input, options) => {
         return;
       const crewActive = crews.get(input2.sessionID);
       if (crewActive && !output.system.some((s) => s.startsWith("[forge:crew-active]"))) {
-        output.system.push(`[forge:crew-active] A crew is ACTIVE in this session: "${crewActive.objective}" (started ${crewActive.startedAt}). A second /crew must be refused; finish with crew_close when every subtask has a verdict.`);
+        const modeText = crewActive.mode === "pending" ? "PENDING (present the execution-mode choice; every task dispatch is refused until armed)" : "armed (executing)";
+        output.system.push(`[forge:crew-active] A crew is ${modeText} in this session: "${crewActive.objective}" (started ${crewActive.startedAt}). A second /crew must be refused; finish with crew_close when every subtask has a verdict, or crew_close {abandon: true, reason} to re-shard.`);
       }
       if (!forgeDisabled && jobStage() < 2 && !output.system.some((s) => s.startsWith("[forge:job-guidance]"))) {
         output.system.push(jobsKeepBuiltinShell ? "[forge:job-guidance] Long-running or possibly non-exiting shell commands (dev servers, watchers, installers, anything spawning detached children) go through forge_shell, never the builtin shell: it returns on idle/success/exit with a jobId instead of blocking indefinitely; manage jobs with forge_jobs. Delegated agents: collect your job results with forge_jobs poll before yielding your conclusion." : "[forge:job-guidance] Every shell command — quick ones included — goes through forge_shell: the builtin shell/bash tools are refused on this agent, so never try them first. forge_shell returns on exit/success/idle with a jobId instead of blocking indefinitely; long-running or non-exiting commands use run_in_background. Manage jobs with forge_jobs. Delegated agents: collect your job results with forge_jobs poll before yielding your conclusion.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sorenllm/opencode-forge",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Single general-purpose forge agent for opencode: static worker subagents defined in forge.json (pinned model + thoughtLevel pair, or an Auto worker inheriting the parent model; dispatched through the native task tool — TUI-visible), a plan harness (file-backed plans with approve/close confirmation gates and a hard draft write-ban), a goal harness (autonomous, host-verified objectives), a /crew orchestration command (declared-plan waves with an evidence-checked close gate), a job supervisor (forge_shell with exit-bound completion, idle/success early return, background jobs with poll/log/kill/handoff), and a builtin-shell hang watchdog.",
   "type": "module",
   "main": "./dist/index.js",