@sorenllm/opencode-forge 0.11.2 → 0.13.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,13 +165,14 @@ 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 |
 | `<tmp>/opencode-forge/jobs/registry.json` | persistent survivor registry (bounded: 100 entries) | runtime debris — after uninstall, kill any still-running `survive` jobs yourself first |
 | `<tmp>/opencode-forge/watchdog/log.jsonl` | watchdog interventions ledger (bounded: 200 entries, oldest rotated) | runtime debris — delete freely, also after uninstall |
 | `<tmp>/opencode-forge/dispatch/ledger.jsonl` | dispatch ledger — **no longer written** (the dispatch engine was removed); only present as inert debris from older versions | runtime debris — delete freely |
-| the nearest `.opencode/forge.json` on the workspace's ancestor chain, `~/.config/opencode/forge.json` | your static subagent definitions (JSONC), two MERGED layers (project overrides global per agent id). **User data — the plugin only reads it, never writes or migrates it** | yours — version the project one, keep the global one out of sync tools if it holds machine-specific models |
+| `.opencode/forge.json` files (the nearest on each host anchor's ancestor chain, every one in an anchor's subtree, and `~/.config/opencode/forge.json`) | your static subagent definitions (JSONC) — pool families MERGED over the global layer per agent id (primary anchor's root pool plain ids, others namespaced). **User data — the plugin only reads them, never writes or migrates them** | yours — version the project ones, keep the global one out of sync tools if it holds machine-specific models |
 | `~/.cache/opencode/packages/...` | installed package copy | written by the `opencode plugin` installer, not the plugin |
 | `~/.config/opencode/opencode.json` | `plugin` array entry | written by the installer |
 
@@ -417,26 +418,60 @@ discovered by walking up:
 
 The two layers **merge**: agents combine, and on an id collision the project
 definition wins wholesale (one definition per id — no cross-layer field
-blending). A broken file empties only its own layer (error finding with the
-parse location); the other layer still applies. Both layers hot-apply —
-edits, and files appearing or disappearing on the ancestor chain, take
-effect without a host restart (new agents still need the restart to enter
-the task vocabulary; see the apply-timing table below).
+blending). A broken file empties only its own layer/pool (error finding with
+the parse location); everything else still applies. Both layers hot-apply —
+edits, and files appearing or disappearing, take effect at the next config
+hook without a host restart (see the apply-timing table below).
+
+**Hierarchical pools on a shared host.** Agent frontends (paseo and friends)
+routinely share ONE opencode host process across projects, re-initializing
+plugins with different directories. The plugin therefore keeps an
+**append-only anchor set**: every host initialization appends its directory
+(first one = the *primary anchor*), and pools resolve from the union —
+anchor flips can only ever ADD pools, never remove them. Per anchor the
+family is:
+
+- the **root pool** — the nearest forge.json walking up from that anchor
+  (merged over the global layer per agent id);
+- every **sub-pool** — a `.opencode/forge.json` anywhere in the anchor's
+  subdirectories, discovered by a bounded breadth-first scan (lexicographic
+  sibling order; dependency dirs like `node_modules`/`.git`/`dist` are
+  skipped; 2,000-directory budget per anchor).
+
+The **primary anchor's root pool keeps plain `forge-<id>` ids** (a
+single-project host is unchanged); every other family materializes
+**namespaced** as `forge-<ns>-<id>`. `ns` is the file's optional `pool`
+field, else the sanitized directory name. Pool identity is the absolute file
+path — the same file reached through two anchors materializes exactly once;
+namespace and materialized-id collisions resolve deterministically with an
+error finding, never by silent shadowing. The `/crew` roster and the
+`crew_begin` registration output list the dispatchable agents **grouped by
+pool** with each pool's origin path, the primary marked.
+
+| axis | follows | survives restart? |
+| --- | --- | --- |
+| pools (the `forge-*` vocabulary) | host directories — the anchor set | the set re-seeds from the spawn anchor only |
+| session artifacts (plan/goal/crew records) | the session's own workspace | files on disk are the source of truth |
 
-One host instance materializes one pool (from its launch anchor) — a
-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).
+A forge.json in a directory NO host anchor covers is NOT silently ignored:
+`/crew` names it as the residual mismatch and tells you a host
+initialization in that workspace adds its pools (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.
+materializes every id as `forge-<id>` itself (namespaced pools:
+`forge-<ns>-<id>`). 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. The namespace infix is never parsed back
+out of a materialized id.
 
 ```jsonc
 {
-  // forge subagents — definitions; see the restart table below for apply timing
+  // sub-pool files only: namespace for this family's ids (forge-<ns>-<id>).
+  // Short, stable, [a-z0-9-] up to 24 chars — ids survive directory renames.
+  // Invalid values degrade to a warning + the directory-derived namespace.
+  // "pool": "aa",
   "agents": {
     // PINNED worker: model + thoughtLevel form an ATOMIC PAIR — set BOTH
     "research": {
@@ -496,12 +531,14 @@ A rejected entry costs only itself — its siblings materialize normally.
 > error finding naming the missing half. Fix per entry: add the missing
 > `thoughtLevel`, or delete `model` to make it an Auto worker.
 
-**What applies when** — edits take hold per field:
+**What applies when** — file truth is hot; only the anchor set is frozen at
+host start:
 
 | change | needs a host restart? |
 | --- | --- |
 | `thoughtLevel` on an existing agent | no (applies to NEW sessions of that agent; running sessions keep their frozen depth) |
-| agent added / removed, or `model` / `prompt` / `permission` changed | yes (materialization runs on the config hook) |
+| agent added / removed / edited, any pool file created or deleted | no restart — applies at the next config hook (materialization re-runs there; the crew gate and depth lookups always resolve fresh) |
+| a NEW directory joining the host (another project's session on the shared host) | no restart — the re-initialization itself adds the anchor and its pools |
 
 ### Dispatching
 
@@ -536,31 +573,81 @@ 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 **grouped by pool with its
+   origins** (which forge.json families the dispatchable set materialized
+   from, the primary marked), 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.
-
-**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
-the choice of configuring it yourself OR having the session AI do it — the
-latter only on your explicit go-ahead in that conversation, through the
-normal visible write path. This is the plugin's only configuration
-invitation. After saving the file, restart opencode to materialize the
-agents.
+   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 pools across its whole
+anchor set refuses with one-time setup guidance: the two file paths, a
+copy-paste template, and the choice of configuring it yourself OR having the
+session AI do it — the latter only on your explicit go-ahead in that
+conversation, through the normal visible write path (when the AI writes a
+sub-pool file it also proposes a short stable `pool` namespace so ids
+survive directory renames). This is the plugin's only configuration
+invitation. Saved files apply at the next config hook — no restart needed;
+on a shared host, opening a session in a new workspace adds that anchor and
+its pools automatically.
 
 ### Debris note
 

package/dist/index.js

@@ -12335,7 +12335,7 @@ function tool(input) {
 tool.schema = exports_external;
 // plugin.ts
 import { execFileSync as execFileSync3 } from "node:child_process";
-import { appendFileSync, existsSync as existsSync3, mkdirSync as mkdirSync5, readdirSync as readdirSync4, readFileSync as readFileSync8, statSync as statSync5, writeFileSync as writeFileSync5 } from "node:fs";
+import { appendFileSync, existsSync as existsSync3, mkdirSync as mkdirSync5, readdirSync as readdirSync5, readFileSync as readFileSync8, realpathSync, statSync as statSync5, writeFileSync as writeFileSync5 } from "node:fs";
 import { isAbsolute, join as join6, relative } from "node:path";
 import { tmpdir as tmpdir3, homedir } from "node:os";
 
@@ -15104,7 +15104,7 @@ function resolvePinnedDepth(thoughtLevel, family, ladder) {
 }
 
 // src/forge-config.ts
-import { readFileSync as readFileSync7, statSync as statSync4 } from "node:fs";
+import { readdirSync as readdirSync4, readFileSync as readFileSync7, statSync as statSync4 } from "node:fs";
 function sanitizeJsonc(text) {
   const out = [];
   let i = 0;
@@ -15456,6 +15456,25 @@ function parentDirOf(p) {
   const parent = s.slice(0, i + 1);
   return parent === "" ? null : parent;
 }
+function forgeCandidateAt(dir) {
+  const sep2 = dir.includes("\\") && !dir.includes("/") ? "\\" : "/";
+  const base = dir.endsWith("/") || dir.endsWith("\\") ? dir : `${dir}${sep2}`;
+  return `${base}.opencode${sep2}forge.json`;
+}
+function discoverProjectFileWith(stat, anchor) {
+  let dir = (anchor ?? "").trim();
+  if (!dir)
+    return null;
+  for (;; ) {
+    const candidate = forgeCandidateAt(dir);
+    if (stat(candidate) !== null)
+      return candidate;
+    const parent = parentDirOf(dir);
+    if (parent === null || parent === dir)
+      return null;
+    dir = parent;
+  }
+}
 function createForgeConfigLoader(deps) {
   const stat = deps.stat ?? ((path) => {
     try {
@@ -15512,28 +15531,9 @@ function createForgeConfigLoader(deps) {
     cache.set(path, { mtimeMs: st.mtimeMs, size: st.size, result });
     return result;
   };
-  const candidateAt = (dir) => {
-    const sep2 = dir.includes("\\") && !dir.includes("/") ? "\\" : "/";
-    const base = dir.endsWith("/") || dir.endsWith("\\") ? dir : `${dir}${sep2}`;
-    return `${base}.opencode${sep2}forge.json`;
-  };
-  const discoverProjectFile = (anchor) => {
-    let dir = (anchor ?? "").trim();
-    if (!dir)
-      return null;
-    for (;; ) {
-      const candidate = candidateAt(dir);
-      if (stat(candidate) !== null)
-        return candidate;
-      const parent = parentDirOf(dir);
-      if (parent === null || parent === dir)
-        return null;
-      dir = parent;
-    }
-  };
   return {
     load() {
-      const projectPath = discoverProjectFile(deps.projectDir ?? "");
+      const projectPath = discoverProjectFileWith(stat, deps.projectDir ?? "");
       const project = projectPath ? readCandidate(projectPath, "project") : null;
       const global = globalPath ? readCandidate(globalPath, "global") : null;
       if (project && global) {
@@ -15553,6 +15553,228 @@ function createForgeConfigLoader(deps) {
     }
   };
 }
+var POOL_SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "out", "target", ".cache", "venv", ".venv", "__pycache__", "coverage"]);
+var POOL_SCAN_BUDGET = 2000;
+function sanitizeNamespace(name) {
+  const collapsed = name.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  return collapsed || "pool";
+}
+function validatePoolField(v) {
+  if (typeof v !== "string")
+    return { ok: false };
+  const trimmed = v.trim();
+  if (trimmed.length < 1 || trimmed.length > 24 || !/^[a-z0-9-]+$/.test(trimmed))
+    return { ok: false };
+  return { ok: true, ns: trimmed };
+}
+function dirBasename(dir) {
+  let s = dir;
+  while (s.length > 1 && (s.endsWith("/") || s.endsWith("\\")))
+    s = s.slice(0, -1);
+  const i = Math.max(s.lastIndexOf("/"), s.lastIndexOf("\\"));
+  return i < 0 ? s : s.slice(i + 1);
+}
+function codepointCompare(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function createPoolResolver(deps) {
+  const stat = deps.stat ?? ((path) => {
+    try {
+      const s = statSync4(path);
+      return { mtimeMs: s.mtimeMs, size: s.size };
+    } catch {
+      return null;
+    }
+  });
+  const readFile = deps.readFile ?? ((path) => readFileSync7(path, "utf8"));
+  const readdir = deps.readdir ?? ((dir) => {
+    try {
+      return readdirSync4(dir, { withFileTypes: true }).map((d) => ({ name: d.name, dir: d.isDirectory() }));
+    } catch {
+      return null;
+    }
+  });
+  const budget = typeof deps.scanBudget === "number" && deps.scanBudget > 0 ? deps.scanBudget : POOL_SCAN_BUDGET;
+  const globalPath = forgeConfigPaths({ homeDir: deps.homeDir }).global;
+  const fileCache = new Map;
+  const readPool = (path) => {
+    const st = stat(path);
+    if (st === null) {
+      fileCache.delete(path);
+      return null;
+    }
+    const hit = fileCache.get(path);
+    if (hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size)
+      return hit.parsed;
+    let parsed = null;
+    const text = readFile(path);
+    const doc2 = parseForgeJsonc(text);
+    if (!doc2.ok) {
+      parsed = {
+        agents: {},
+        declaredPool: null,
+        findings: [
+          {
+            level: "error",
+            code: "config-parse-error",
+            message: `${path}: ${doc2.error.message}${doc2.error.line !== undefined ? ` (line ${doc2.error.line}, column ${doc2.error.column})` : ""} — this pool contributes no agents until the file parses`
+          }
+        ]
+      };
+    } else if (doc2.config !== undefined && !isRecord(doc2.config)) {
+      parsed = { agents: {}, declaredPool: null, findings: [{ level: "error", code: "config-not-object", message: `${path}: top level must be an object — this pool contributes no agents` }] };
+    } else {
+      const top = doc2.config === undefined ? undefined : doc2.config;
+      const validated = validateAgentSet(top === undefined ? undefined : top.agents);
+      parsed = { agents: validated.agents, declaredPool: top === undefined ? null : top.pool, findings: validated.findings };
+    }
+    fileCache.set(path, { mtimeMs: st.mtimeMs, size: st.size, parsed });
+    return parsed;
+  };
+  const dirCache = new Map;
+  const listDir = (dir) => {
+    const st = stat(dir);
+    if (st === null) {
+      dirCache.delete(dir);
+      return null;
+    }
+    const hit = dirCache.get(dir);
+    if (hit && hit.mtimeMs === st.mtimeMs)
+      return hit;
+    const listing = readdir(dir);
+    const children = listing === null ? null : [...listing].sort((a, b) => codepointCompare(a.name, b.name));
+    let poolFile = null;
+    const candidate = forgeCandidateAt(dir);
+    if (stat(candidate) !== null)
+      poolFile = candidate;
+    const entry = { mtimeMs: st.mtimeMs, children, poolFile };
+    dirCache.set(dir, entry);
+    return entry;
+  };
+  const scanSubtree = (anchor) => {
+    const files = [];
+    const seen = new Set;
+    let opened = 0;
+    const sep2 = anchor.includes("\\") && !anchor.includes("/") ? "\\" : "/";
+    const joinDir = (parent, name) => parent.endsWith("/") || parent.endsWith("\\") ? `${parent}${name}` : `${parent}${sep2}${name}`;
+    const queue = [anchor];
+    while (queue.length > 0 && opened < budget) {
+      const dir = queue.shift();
+      if (seen.has(dir))
+        continue;
+      seen.add(dir);
+      const entry = listDir(dir);
+      opened++;
+      if (entry === null || entry.children === null)
+        continue;
+      const isAnchor = dir === anchor;
+      if (!isAnchor && entry.poolFile !== null)
+        files.push(entry.poolFile);
+      for (const child of entry.children) {
+        if (!child.dir)
+          continue;
+        if (POOL_SKIP_DIRS.has(child.name) || child.name === ".opencode")
+          continue;
+        queue.push(joinDir(dir, child.name));
+      }
+    }
+    return files;
+  };
+  return {
+    resolve(anchorsInput) {
+      const anchors = [];
+      for (const a of anchorsInput) {
+        const t = (a ?? "").trim();
+        if (t && !anchors.includes(t))
+          anchors.push(t);
+      }
+      const findings = [];
+      const globalParsed = globalPath ? readPool(globalPath) : null;
+      if (globalParsed)
+        findings.push(...globalParsed.findings);
+      const primaryRootFile = anchors.length > 0 ? discoverProjectFileWith(stat, anchors[0]) : null;
+      const uniqueFiles = new Set;
+      if (primaryRootFile)
+        uniqueFiles.add(primaryRootFile);
+      for (const anchor of anchors) {
+        for (const f of scanSubtree(anchor))
+          uniqueFiles.add(f);
+        if (anchor !== anchors[0]) {
+          const rootFile = discoverProjectFileWith(stat, anchor);
+          if (rootFile)
+            uniqueFiles.add(rootFile);
+        }
+      }
+      const plainPoolFile = primaryRootFile ?? (globalParsed !== null && globalPath ? globalPath : null);
+      const orderedFiles = [plainPoolFile, ...[...uniqueFiles].filter((f) => f !== plainPoolFile).sort(codepointCompare)].filter((f) => f !== null);
+      const families = [];
+      for (const file2 of orderedFiles) {
+        const parsed = readPool(file2);
+        if (parsed && file2 !== globalPath)
+          findings.push(...parsed.findings);
+        const isPrimary = plainPoolFile !== null && file2 === plainPoolFile;
+        let declaredPool = null;
+        if (!isPrimary && parsed) {
+          const v = validatePoolField(parsed.declaredPool);
+          if (parsed.declaredPool !== undefined && parsed.declaredPool !== null) {
+            if (v.ok) {
+              declaredPool = v.ns;
+            } else {
+              findings.push({ level: "warn", code: "pool-field-invalid", message: `${file2}: invalid "pool" field ${JSON.stringify(String(parsed.declaredPool))} (expected [a-z0-9-], 1-24 chars) — falling back to the directory-derived namespace` });
+            }
+          }
+        }
+        families.push({ file: file2, parsed, ns: null, declaredPool, primary: isPrimary });
+      }
+      const allDeclared = new Set;
+      for (const f of families)
+        if (f.declaredPool)
+          allDeclared.add(f.declaredPool);
+      const usedNs = new Map;
+      for (const f of families) {
+        if (f.primary)
+          continue;
+        const base = f.declaredPool ?? sanitizeNamespace(dirBasename(parentDirLabel(parentDirLabel(f.file))));
+        let ns = base;
+        let suffix = 2;
+        while ((usedNs.has(ns) || ns !== base && allDeclared.has(ns)) && suffix < 100) {
+          ns = `${base}-${suffix++}`;
+        }
+        const owner = usedNs.get(base);
+        if (owner !== undefined && owner !== f.file) {
+          findings.push({ level: "error", code: "pool-namespace-collision", message: `namespace "${base}" is already used by ${owner} — ${f.file} materializes under "${ns}" instead` });
+        }
+        f.ns = ns;
+        usedNs.set(ns, f.file);
+      }
+      const agents = {};
+      const origins = [];
+      for (const f of families) {
+        const merged = { ...globalParsed?.agents ?? {}, ...f.parsed?.agents ?? {} };
+        const ids = [];
+        for (const rawId of Object.keys(merged)) {
+          const matId = f.ns === null ? rawId : `${f.ns}-${rawId}`;
+          const existing = agents[matId];
+          if (existing !== undefined) {
+            findings.push({ level: "error", code: "materialized-id-collision", message: `materialized agent forge-${matId} from ${f.file} collides with the one from ${existing.file} — the earlier pool in resolution order wins, this agent is skipped` });
+            continue;
+          }
+          agents[matId] = { materializedId: matId, def: merged[rawId], ns: f.ns, file: f.file };
+          ids.push(matId);
+        }
+        origins.push({ file: f.file, ns: f.ns, declaredPool: f.declaredPool, primary: f.primary, materializedIds: ids });
+      }
+      return { families: origins, agents, findings };
+    }
+  };
+}
+function parentDirLabel(filePath) {
+  let s = filePath;
+  while (s.length > 1 && (s.endsWith("/") || s.endsWith("\\")))
+    s = s.slice(0, -1);
+  const i = Math.max(s.lastIndexOf("/"), s.lastIndexOf("\\"));
+  return i < 0 ? s : s.slice(0, i);
+}
 
 // plugin.ts
 var FORGE_AGENT = "forge";
@@ -15665,8 +15887,35 @@ function noteToolAgent(context) {
   }
 }
 var forgeDisabled = false;
-var forgeLoader = null;
-var forgeLoaderDir = null;
+var hostAnchors = [];
+var poolResolver = null;
+var poolResolution = null;
+function normalizeAnchorDir(dir) {
+  let p = (dir ?? "").trim();
+  if (!p)
+    return "";
+  try {
+    p = realpathSync(p);
+  } catch {}
+  if (process.platform === "win32")
+    return p.replace(/\//g, "\\").toLowerCase();
+  return p;
+}
+function rememberHostAnchor(dir) {
+  const normalized = normalizeAnchorDir(dir);
+  if (!normalized)
+    return;
+  if (!hostAnchors.includes(normalized))
+    hostAnchors.push(normalized);
+  if (!poolResolver) {
+    poolResolver = createPoolResolver({ homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() });
+  }
+}
+function resolvePools() {
+  if (!poolResolver || hostAnchors.length === 0)
+    return null;
+  return poolResolver.resolve(hostAnchors);
+}
 var sessionAnchorLoaders = new Map;
 function loaderForAnchor(anchor) {
   const key = anchor || "-";
@@ -15684,6 +15933,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;
@@ -15823,7 +16123,7 @@ function readPlanDir(worktree) {
   const dir = planDirOf(worktree);
   if (!existsSync3(dir))
     return [];
-  return readdirSync4(dir).filter((f) => f.endsWith(".md")).map((name) => ({ name, text: readFileSync8(join6(dir, name), "utf8") }));
+  return readdirSync5(dir).filter((f) => f.endsWith(".md")).map((name) => ({ name, text: readFileSync8(join6(dir, name), "utf8") }));
 }
 function ensureSession(sessionID, worktree) {
   const existing = sessions.get(sessionID);
@@ -15890,7 +16190,7 @@ var planWriteTool = tool({
     } else {
       const dir = planDirOf(state.worktree);
       mkdirSync5(dir, { recursive: true });
-      path = join6(dir, planFileName(localDate(), slugify(args.goal), readdirSync4(dir).filter((f) => f.endsWith(".md"))));
+      path = join6(dir, planFileName(localDate(), slugify(args.goal), readdirSync5(dir).filter((f) => f.endsWith(".md"))));
       mode = "created";
     }
     const text = renderPlan(args, now, created);
@@ -16014,7 +16314,7 @@ function readGoalDir(worktree) {
   const dir = goalDirOf(worktree);
   if (!existsSync3(dir))
     return [];
-  return readdirSync4(dir).filter((f) => f.endsWith(".md")).map((name) => ({ name, text: readFileSync8(join6(dir, name), "utf8") }));
+  return readdirSync5(dir).filter((f) => f.endsWith(".md")).map((name) => ({ name, text: readFileSync8(join6(dir, name), "utf8") }));
 }
 function resolveSessionGoal(state) {
   if (state.goalPath && existsSync3(state.goalPath)) {
@@ -16123,7 +16423,7 @@ var goalWriteTool = tool({
     }
     const dir = goalDirOf(state.worktree);
     mkdirSync5(dir, { recursive: true });
-    const name = goalFileName(localDateNow(), slugifyGoal(args.goal), readdirSync4(dir).filter((f) => f.endsWith(".md")));
+    const name = goalFileName(localDateNow(), slugifyGoal(args.goal), readdirSync5(dir).filter((f) => f.endsWith(".md")));
     const path = join6(dir, name);
     const text = renderGoal(input, {
       now,
@@ -16495,42 +16795,52 @@ var CREW_INIT_TEMPLATE = [
   "",
   "FAMILY GUARD (step 0, before anything else): if you do not have the crew_begin tool in your available tools, you are not in a forge session — STOP now and tell the user that /crew belongs to the forge agent, who should switch to forge (Tab) and rerun it there.",
   "",
-  "CREW IS NOT INITIALIZED: no forge subagents are configured (no usable forge.json agents). Refuse to enter orchestration and tell the user this feature needs a one-time setup, offering BOTH options:",
+  "CREW IS NOT INITIALIZED: no forge subagents are materialized across the whole host anchor set (zero pools). Refuse to enter orchestration and tell the user this feature needs a one-time setup, offering BOTH options:",
   "",
-  "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):",
+  "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; a .opencode/forge.json in any anchor subdirectory additionally forms a namespaced sub-pool family, its ids materializing as forge-<ns>-<id>):",
   "{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: 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.",
+  "Two axes, distinct: POOLS follow host directories (the host's anchor set); SESSION ARTIFACTS (plan/goal/crew records) follow the session. A forge.json in a directory no host anchor covers is not dispatchable on this host.",
   "",
-  "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).",
+  '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. For sub-pool files, ALSO include a proposed short stable `pool` namespace (a [a-z0-9-] word up to 24 chars — e.g. "aa" for a devAa specialist pool) so the materialized ids survive directory renames.',
+  "",
+  "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). Optional top level: `pool` — the file's namespace.",
   "{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."
+  "After the file is saved: file edits, creations, and deletions apply at the next config hook — NO host restart is needed. Only the anchor set itself is fixed at host start: host re-initializations add anchors and pools, they never remove them."
 ].join(`
 `);
-function crewOrchestrationTemplate(agentIds) {
+function crewOrchestrationTemplate(resolution) {
+  const families = resolution?.families ?? [];
+  const familyLines = families.map((f) => {
+    const label = f.primary ? "root pool (PRIMARY, plain ids)" : `pool ${f.ns} (forge-${f.ns}-*)`;
+    return `  - ${label}: ${f.file} — ${f.materializedIds.map((id) => `forge-${id}`).join(", ") || "no agents"}`;
+  });
   return [
     '(forge crew orchestration. Argument: "$ARGUMENTS")',
     "",
     "FAMILY GUARD (step 0, before anything else): if you do not have the crew_begin tool in your available tools, you are not in a forge session — STOP now and tell the user that /crew belongs to the forge agent, who should switch to forge (Tab) and rerun it there.",
     "",
-    `Configured forge subagents (task-tool vocabulary): ${agentIds.map((id) => `forge-${id}`).join(", ")}`,
+    "Configured forge subagents (task-tool vocabulary), grouped by pool:",
+    ...familyLines.length > 0 ? familyLines : ["  (none)"],
     "",
-    "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")
@@ -16543,30 +16853,80 @@ var crewBeginTool = tool({
     if (active && active.doc.status === "draft") {
       throw new Error("[forge:crew] A plan is in draft; crew orchestration is denied during planning. Call plan_approve for user approval, or /plan discard to abandon the plan.");
     }
-    const hostLoaded = forgeLoader?.load();
-    const hostIds = hostLoaded ? Object.keys(hostLoaded.agents) : [];
+    const resolution = resolvePools();
+    const hostIds = resolution ? Object.keys(resolution.agents) : [];
     const anchor = sessionAnchor(context);
-    const hostAnchorDir = forgeLoaderDir ?? "";
-    const sessionLoaded = anchor && anchor !== hostAnchorDir ? loaderForAnchor(anchor).load() : hostLoaded;
+    const sessionLoaded = anchor ? loaderForAnchor(anchor).load() : null;
     const sessionProject = sessionLoaded?.projectPath ?? null;
+    const foldPath = (p) => process.platform === "win32" ? p.replace(/\//g, "\\").toLowerCase() : p;
+    const sessionCovered = sessionProject === null || (resolution?.families.some((f) => foldPath(f.file) === foldPath(sessionProject)) ?? false);
     if (hostIds.length === 0) {
-      const paths = forgeConfigPaths({ projectDir: hostAnchorDir || undefined, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() });
-      const lines = [
-        "[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}.`,
-        '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."
+      const primaryAnchorDir = hostAnchors[0] ?? hostWorktree;
+      const anchorNote = hostAnchors.length > 1 ? `host anchors: ${hostAnchors.join(", ")}` : `launched from ${primaryAnchorDir || "an unresolvable directory"}`;
+      const paths = forgeConfigPaths({ projectDir: primaryAnchorDir || 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 across the whole anchor set (${anchorNote}). 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}. Sub-pool files (.opencode/forge.json in an anchor's subdirectories) contribute additional namespaced families.`,
+        "Two axes, distinct: POOLS follow host directories (the anchor set above); SESSION ARTIFACTS (plan/goal/crew records) follow the session. A forge.json in an unanchored directory is not dispatchable on this host.",
+        `Template (JSONC): top-level optional "pool" names this file's namespace (short stable [a-z0-9-] up to 24 chars — sub-pool ids materialize as forge-<ns>-<id>); {"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>` (namespaced pools: `forge-<ns>-<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), and INCLUDE a proposed short stable `pool` namespace for sub-pool files so ids survive directory renames. File edits, creations, and deletions apply at the next config hook — no host restart; only the anchor set itself is fixed at host start (re-initializations add pools, never remove)."
       ];
-      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.`);
+      if (sessionLoaded && Object.keys(sessionLoaded.agents).length > 0 && sessionProject && !sessionCovered) {
+        lines2.push(`NOTE: this session's workspace DOES have a forge.json (${sessionProject}) with usable agents — but NO host anchor covers it (${anchorNote}). A host initialization in that workspace adds its pools; or fold the agents into 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,43 +16946,99 @@ 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));
+    if (sessionProject && !sessionCovered) {
+      const localOnly = Object.keys(sessionLoaded?.agents ?? {});
       if (localOnly.length > 0) {
         disclosure = `
-[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.`;
-      }
+[forge:crew] NOTE: this session's workspace has its own forge.json (${sessionProject}) defining ${localOnly.map((id) => `forge-<ns>-${id} (namespaced by its pool)`).join(", ")} — NOT dispatchable on this host (no anchor covers it; anchors: ${hostAnchors.join(", ") || "none"}). A host initialization in that workspace adds its pools, or fold the agents into the global layer.`;
+      }
+    }
+    const familyLines = [];
+    const families = resolution?.families ?? [];
+    for (const f of families.slice(0, 8)) {
+      const label = f.primary ? "root pool (PRIMARY, plain ids)" : `pool ${f.ns} (forge-${f.ns}-*)`;
+      familyLines.push(`   - ${label}: ${f.file} — ${f.materializedIds.map((id) => `forge-${id}`).join(", ") || "no agents"}`);
+    }
+    if (families.length > 8)
+      familyLines.push(`   - …and ${families.length - 8} more pools`);
+    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 — ${families.length} pool${families.length === 1 ? "" : "s"} across the host anchor set${hostAnchors.length > 0 ? ` (anchors: ${hostAnchors.join(", ")})` : ""}:`,
+      ...familyLines,
+      ...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 +17047,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 +17144,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(`
 `);
@@ -16886,7 +17308,9 @@ function scheduleIdleContinuation(client, sessionID) {
   }, IDLE_DEBOUNCE_MS));
 }
 var server = async (input, options) => {
-  hostWorktree = effectiveWorktree(input.worktree, input.directory) || input.directory || "";
+  const effectiveInitDir = effectiveWorktree(input.worktree, input.directory) || input.directory || "";
+  hostWorktree = effectiveInitDir;
+  rememberHostAnchor(effectiveInitDir);
   const client = input.client;
   jobClient = input.client;
   const jobsOpts = options?.jobs;
@@ -16997,23 +17421,17 @@ var server = async (input, options) => {
         if (permSection[gateKey] !== "deny")
           permSection[gateKey] = "ask";
       }
-      if (!forgeLoader || forgeLoaderDir !== hostWorktree) {
-        forgeLoader = createForgeConfigLoader({
-          projectDir: hostWorktree,
-          homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir()
-        });
-        forgeLoaderDir = hostWorktree;
-      }
-      const loaded = forgeLoader.load();
-      for (const finding of loaded.findings) {
+      const resolution = resolvePools();
+      poolResolution = resolution;
+      for (const finding of resolution?.findings ?? []) {
         console.warn(`[forge:config] ${finding.level}: ${finding.message}`);
       }
       materializedSnapshot = {};
-      for (const [agentId, def] of Object.entries(loaded.agents)) {
-        const id = `forge-${agentId}`;
+      for (const [matId, agent] of Object.entries(resolution?.agents ?? {})) {
+        const id = `forge-${matId}`;
         if (agentSection[id] !== undefined)
           continue;
-        const entry = forgeAgentDef(agentId, def);
+        const entry = forgeAgentDef(matId, agent.def);
         agentSection[id] = entry;
         materializedSnapshot[id] = entry;
       }
@@ -17058,12 +17476,13 @@ var server = async (input, options) => {
       cfg.command ??= {};
       const existingCrew = cfg.command["crew"];
       if (!existingCrew || String(existingCrew.template ?? "").startsWith("(forge crew")) {
-        const agentIds = Object.keys(loaded.agents);
-        const template = agentIds.length > 0 ? crewOrchestrationTemplate(agentIds) : CREW_INIT_TEMPLATE.replaceAll("{paths}", `   - ${forgeConfigPaths({ projectDir: forgeLoaderDir ?? undefined, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() }).project}
-   - ${forgeConfigPaths({ projectDir: forgeLoaderDir ?? undefined, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() }).global}`).replaceAll("{template}", JSON.stringify({ agents: { research: { model: "provider/model", thoughtLevel: "low", prompt: "short role description — what this agent does" } } }, null, 2).split(`
+        const agentCount = Object.keys(resolution?.agents ?? {}).length;
+        const primaryAnchorDir = hostAnchors[0] ?? undefined;
+        const template = agentCount > 0 ? crewOrchestrationTemplate(resolution ?? null) : CREW_INIT_TEMPLATE.replaceAll("{paths}", `   - ${forgeConfigPaths({ projectDir: primaryAnchorDir, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() }).project}
+   - ${forgeConfigPaths({ projectDir: primaryAnchorDir, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() }).global}`).replaceAll("{template}", JSON.stringify({ pool: "short-stable-namespace (optional, [a-z0-9-] up to 24 chars — only meaningful for sub-pool files)", agents: { research: { model: "provider/model", thoughtLevel: "low", prompt: "short role description — what this agent does" } } }, null, 2).split(`
 `).map((l) => "   " + l).join(`
 `));
-        const description = agentIds.length > 0 ? "forge crew orchestration: register a declared subtask plan, execute it in waves of parallel native task calls, close with an evidence-checked report" : "forge crew orchestration — NOT INITIALIZED: no forge subagents configured; invoking it shows the one-time setup guidance";
+        const description = agentCount > 0 ? "forge crew orchestration: register a declared subtask plan, execute it in waves of parallel native task calls, close with an evidence-checked report" : "forge crew orchestration — NOT INITIALIZED: no forge subagents configured; invoking it shows the one-time setup guidance";
         cfg.command["crew"] = { template, description };
         crewCommandSnapshot = { template, description };
       }
@@ -17098,6 +17517,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);
@@ -17162,7 +17585,7 @@ var server = async (input, options) => {
         return;
       }
       const agentId = agentName.slice("forge-".length);
-      const def = forgeLoader?.load().agents[agentId];
+      const def = resolvePools()?.agents[agentId]?.def;
       if (!def?.thoughtLevel)
         return;
       const providerID = typeof raw.model?.providerID === "string" ? raw.model.providerID : "";
@@ -17190,7 +17613,14 @@ var server = async (input, options) => {
         modelsDevCatalog = c;
       },
       crewCommand: () => crewCommandSnapshot,
-      materialized: () => materializedSnapshot
+      materialized: () => materializedSnapshot,
+      resetAnchors: () => {
+        hostAnchors.length = 0;
+        poolResolver = null;
+        poolResolution = null;
+      },
+      anchors: () => [...hostAnchors],
+      resolveNow: () => resolvePools()
     },
     "permission.ask": async (input2, output) => {
       const meta = input2.metadata ?? {};
@@ -17284,7 +17714,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.");
@@ -17355,20 +17786,20 @@ async function v2Setup(ctx) {
         });
       }
       try {
-        const loader = createForgeConfigLoader({ projectDir: process.cwd(), homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() });
-        const loaded = loader.load();
-        for (const [agentId, def] of Object.entries(loaded.agents)) {
-          const id = `forge-${agentId}`;
+        const resolver = createPoolResolver({ homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() });
+        const resolution = resolver.resolve([process.cwd()]);
+        for (const [matId, agent] of Object.entries(resolution.agents)) {
+          const id = `forge-${matId}`;
           if (draft.get(id) !== undefined)
             continue;
-          const v1def = forgeAgentDef(agentId, def);
-          draft.update(id, (agent) => {
-            agent.description = v1def.description;
-            agent.system = v1def.prompt;
-            agent.mode = v1def.mode;
+          const v1def = forgeAgentDef(matId, agent.def);
+          draft.update(id, (agentDraft) => {
+            agentDraft.description = v1def.description;
+            agentDraft.system = v1def.prompt;
+            agentDraft.mode = v1def.mode;
             if (v1def.model !== undefined)
-              agent.model = v1def.model;
-            agent.permission = v1def.permission;
+              agentDraft.model = v1def.model;
+            agentDraft.permission = v1def.permission;
           });
         }
       } catch {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sorenllm/opencode-forge",
-  "version": "0.11.2",
+  "version": "0.13.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",