@sorenllm/opencode-forge 0.11.1 → 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 |
@@ -428,6 +429,12 @@ workspace-local file that the host was not launched on is NOT silently
 ignored: `/crew` names it and tells you to relaunch there (or fold the
 agents into the global layer).
 
+**Id naming**: use plain role words (`research`, `coder`, …) — the plugin
+materializes every id as `forge-<id>` itself. A `forge-`-prefixed id in the
+file would double up (`forge-coder` → agent `forge-forge-coder`); the loader
+auto-strips the prefix (all repetitions) with a warning so existing files
+keep working, but rename the entries to silence it.
+
 ```jsonc
 {
   // forge subagents — definitions; see the restart table below for apply timing
@@ -530,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

@@ -15358,12 +15358,21 @@ function validateAgentSet(raw) {
     findings.push({ level: "error", code: "agents-not-object", message: 'forge.json "agents" must be an object mapping agent ids to definitions — the agent set is empty' });
     return { agents, findings };
   }
-  for (const [id, entry] of Object.entries(raw)) {
-    const label = `agents.${id}`;
+  for (const [rawId, entry] of Object.entries(raw)) {
+    let label = `agents.${rawId}`;
+    let id = rawId;
+    if (rawId.startsWith("forge-")) {
+      id = rawId.replace(/^(forge-)+/, "");
+      findings.push({ level: "warn", code: "agent-id-forge-prefix", message: `${label}: the forge- prefix is added automatically at materialization — stripped to "${id}"; rename the entry to silence this warning` });
+    }
     if (!AGENT_ID_RE.test(id)) {
       findings.push({ level: "error", code: "agent-id-invalid", message: `${label}: agent id must match [a-z0-9-] — entry skipped` });
       continue;
     }
+    if (agents[id] !== undefined) {
+      findings.push({ level: "error", code: "agent-id-collision", message: `${label}: normalizes to "${id}" which is already defined — entry skipped (first definition wins)` });
+      continue;
+    }
     if (!isRecord(entry)) {
       findings.push({ level: "error", code: "agent-not-object", message: `${label}: definition must be an object — entry skipped` });
       continue;
@@ -15675,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;
@@ -16491,9 +16551,9 @@ var CREW_INIT_TEMPLATE = [
   "1. The user configures it themselves: create either layer — MERGED, the project layer overrides the global one per agent id (the project file is the nearest .opencode/forge.json walking up from the workspace root):",
   "{paths}",
   "",
-  "2. Or, ONLY if the user explicitly asks you to configure it in this conversation, you may write the file yourself through the normal write path. NEVER write forge.json without that explicit go-ahead. When you configure it: give EVERY agent a SHORT prompt derived from the role the user asked for — one or two sentences describing its job (the user trims or extends from there); write a long prompt ONLY when the user explicitly asks for that agent.",
+  "2. Or, ONLY if the user explicitly asks you to configure it in this conversation, you may write the file yourself through the normal write path. NEVER write forge.json without that explicit go-ahead. When you configure it: name ids as PLAIN role words WITHOUT the `forge-` prefix — the plugin materializes every id as `forge-<id>` automatically (a `forge-`-prefixed id doubles up as `forge-forge-coder` and is auto-stripped with a warning). Give EVERY agent a SHORT prompt derived from the role the user asked for — one or two sentences describing its job (the user trims or extends from there); write a long prompt ONLY when the user explicitly asks for that agent.",
   "",
-  "Template (JSONC — comments allowed): `model` + `thoughtLevel` are an ATOMIC PAIR — set BOTH to pin the brain and depth (model = exact provider/model identity; thoughtLevel = none/low/medium/high/max or a native level name), or NEITHER for an Auto worker that inherits the parent session's model; exactly one of the two is rejected. Optional per agent: `prompt` — a short role description; an explicit prompt FULLY overrides the built-in role (only the ids `research` and `review` carry built-ins; any other id without a prompt gets a generic one-liner and will not know its job).",
+  "Template (JSONC — comments allowed): ids are plain role words (research, coder, ...) — the plugin adds the `forge-` prefix at materialization; `model` + `thoughtLevel` are an ATOMIC PAIR — set BOTH to pin the brain and depth (model = exact provider/model identity; thoughtLevel = none/low/medium/high/max or a native level name), or NEITHER for an Auto worker that inherits the parent session's model; exactly one of the two is rejected. Optional per agent: `prompt` — a short role description; an explicit prompt FULLY overrides the built-in role (only the ids `research` and `review` carry built-ins; any other id without a prompt gets a generic one-liner and will not know its job).",
   "{template}",
   "",
   "After the file is saved: NEW agents require a host restart to appear in the task tool; thoughtLevel edits on existing agents apply without restart. Until then, crew stays unavailable."
@@ -16507,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")
@@ -16541,22 +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;
@@ -16576,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));
@@ -16585,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) {
@@ -16621,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(`
 `)
     };
@@ -16713,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(`
 `);
@@ -17088,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);
@@ -17274,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.1",
+  "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",