@sorenllm/opencode-forge 0.12.0 → 0.14.0

package/README.md

@@ -31,7 +31,18 @@ OpenSpec spec workflows remain a third, separate lane.
 ```
 
 - Plan files: `.opencode/plan/<date>-<slug>.md` in your project, frontmatter
-  state machine `draft → approved → done` (exit: `abandoned`).
+  state machine `draft → approved → done`, exits `abandoned` (plain discard) and
+  `superseded` (`plan_discard {reason, supersede: "<successor path>"}` —
+  the exit for work whose execution moves to another harness, e.g.
+  `.opencode/crew/2026-10-01-....md`, rather than ends). Every terminal
+  transition appends a dated narrative section to the file body in the same
+  write as the status flip: close = each acceptance criterion's
+  pass/evidence; discard/supersede = the reason verbatim (`(none given)`
+  when absent; a supersession also records the successor path). Appended
+  sections are parser-inert — status reads frontmatter only, tick
+  counts read the Task List only — and a superseded plan's Task List
+  stays the frozen decision snapshot: closure IS the supersession, and
+  crew/goal results never tick it.
 - While a plan is in draft, `write` / `edit` / `bash` / `task` are **denied
   at the permission layer** — including your own `allow` config, and for
   every agent in that session (the draft protects shared session state; see
@@ -172,7 +183,7 @@ What this plugin touches, exhaustively:
 | `<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 |
 
@@ -418,26 +429,61 @@ 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 re-read at
+every real materialization — host boot, a first config build, or an
+opencode config reload — without a restart; a new session alone does
+not re-read them (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": {
@@ -497,12 +543,18 @@ 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** — only a real materialization re-reads the pool
+files into the `forge-*` vocabulary; the anchor set itself only ever grows.
+Materialization triggers (2026-10-01 live finding): host boot (a freshly
+started CLI process reads the files as they are), the FIRST config build
+for a directory on this host, and opencode config file reloads. A NEW
+session on a long-lived shared host (serve-type) does NOT re-materialize:
 
 | 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) |
+| `thoughtLevel` on an existing agent | no (applies to NEW sessions of that agent; running sessions keep their frozen depth) — depth lookups resolve the pool files fresh at every dispatch, independent of materialization |
+| agent added / removed / edited, any pool file created or deleted | no restart — but not at the next session either: the materialized `forge-*` set rebuilds only at the next REAL materialization (host boot, opencode config reload, or a first config build); on a long-lived shared host pool changes wait for that rebuild or a restart. The crew gate and depth lookups resolve the pool files fresh regardless |
+| a NEW directory joining the host (the first session of another project on the shared host) | no restart — that first config build itself re-initializes the plugin and appends the anchor and its pools (append-only; existing pools never flip) |
 
 ### Dispatching
 
@@ -544,11 +596,21 @@ requires a plan. The flow:
 
 1. **Register** the declared plan: `crew_begin {objective, subtasks}` — one
    titled subtask each, optionally naming the intended `forge-*` agent.
+   When the macro contract descends from a plan artifact, pass its path as
+   the optional `lineage` argument — recorded as a first-class `lineage:`
+   line in the crew record header and disclosed in the registration output
+   (explicit argument only; never inferred from a recently discarded plan).
    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.
+   registration output LEADS with the crew record path line (same
+   first-block prominence as the plan tools' `Plan created:`) and the
+   PENDING pause text instructs the model to relay that path to the user
+   alongside the choice — so you can verify the record really landed on
+   disk (an earlier output order buried the path line, and the model
+   reliably drops what it buries — leading with it is the fix). The
+   output then confirms the roster **grouped by pool with its origins**
+   (which forge.json families the dispatchable set materialized from, the
+   primary marked), 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
@@ -601,13 +663,18 @@ 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
-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.
+**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 real materialization — no
+restart needed; on a shared host, the first session in a NEW workspace adds
+that anchor and its pools automatically (a new session in an existing
+workspace does not re-read the files — see the apply-timing table
+above).
 
 ### 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";
 
@@ -12346,12 +12346,13 @@ class PlanError extends Error {
     this.name = "PlanError";
   }
 }
-var TERMINAL = ["done", "abandoned"];
+var TERMINAL = ["done", "abandoned", "superseded"];
 var LEGAL_TRANSITIONS = {
-  draft: ["approved", "abandoned"],
-  approved: ["done", "abandoned"],
+  draft: ["approved", "abandoned", "superseded"],
+  approved: ["done", "abandoned", "superseded"],
   done: [],
-  abandoned: []
+  abandoned: [],
+  superseded: []
 };
 var SECTION_ORDER = [
   "Goal",
@@ -12499,6 +12500,7 @@ function matchSectionHeader(line) {
 }
 function splitSections(body) {
   const sections = new Map;
+  const claimed = new Set;
   let current = null;
   const buf = [];
   const flush = () => {
@@ -12509,12 +12511,14 @@ function splitSections(body) {
   };
   for (const line of body.split(/\r?\n/)) {
     const header = matchSectionHeader(line);
-    if (header !== null) {
-      flush();
-      current = header;
-    } else if (current !== null) {
-      buf.push(line);
+    if (header === null || claimed.has(header)) {
+      if (current !== null)
+        buf.push(line);
+      continue;
     }
+    flush();
+    claimed.add(header);
+    current = header;
   }
   flush();
   return sections;
@@ -12525,7 +12529,7 @@ var ACCEPT_RE = /^\s*(\d+)[.、)]\s*(.+)$/;
 function parsePlan(text) {
   const { fm, body } = parseFrontmatter(text);
   const status = fm.status ?? "draft";
-  if (!["draft", "approved", "done", "abandoned"].includes(status)) {
+  if (!["draft", "approved", "done", "abandoned", "superseded"].includes(status)) {
     throw new PlanError(`Unknown plan status: ${fm.status}`);
   }
   const sections = splitSections(body);
@@ -12612,11 +12616,35 @@ function transitionStatus(text, to, now) {
   if (from === to)
     throw new PlanError(`Plan is already ${to}`);
   if (!canTransition(from, to)) {
-    throw new PlanError(`Illegal status transition: ${from} -> ${to} (legal path: draft -> approved -> done; draft/approved -> abandoned)`);
+    throw new PlanError(`Illegal status transition: ${from} -> ${to} (legal path: draft -> approved -> done; draft/approved -> abandoned/superseded)`);
   }
   const next = text.replace(/^status:.*$/m, `status: ${to}`);
   return setUpdated(next, now);
 }
+function appendTerminalSection(text, kind, opts = {}, now = new Date().toISOString()) {
+  if (!["closed", "abandoned", "superseded"].includes(kind)) {
+    throw new PlanError(`Unknown terminal section kind: ${kind}`);
+  }
+  const lines = [`## ${now} — ${kind}`, ""];
+  const reason = (opts.reason ?? "").trim();
+  lines.push(`reason: ${reason.length > 0 ? reason : "(none given)"}`);
+  const successor = (opts.successor ?? "").trim();
+  if (successor.length > 0)
+    lines.push(`successor: ${successor}`);
+  if (opts.checks && opts.checks.length > 0) {
+    lines.push("checks:");
+    for (const c of opts.checks) {
+      lines.push(`- ${c.pass ? "PASS" : "FAIL"} — ${c.criterion.trim()}`);
+      lines.push(`  evidence: ${c.evidence.trim() || "(none)"}`);
+    }
+  }
+  const base = text.replace(/\r?\n$/, "");
+  return `${base}
+
+${lines.join(`
+`)}
+`;
+}
 function progressOf(doc2) {
   return { total: doc2.tasks.length, done: doc2.tasks.filter((t) => t.done).length };
 }
@@ -15104,7 +15132,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 +15484,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 +15559,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 +15581,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";
@@ -15597,7 +15847,7 @@ var PLAN_COMMAND_TEMPLATE = [
   "Route on the argument above (decide silently; do not recite this routing text to the user):",
   "- Argument empty: for every non-terminal plan (status draft or approved) in the directory above, read its frontmatter and task checkboxes, then report to the user: path, status, progress (x/y ticked). Ask whether to resume one or start something new.",
   '- Argument "resume": pick the most recently updated non-terminal plan, summarize its remaining unticked tasks to the user in one short list, then continue executing it — tick each task the moment it is done (plan_tick). If none exists, say so.',
-  '- Argument "discard": call the plan_discard tool, then tell the user the plan was abandoned and writes are restored.',
+  '- Argument "discard": call the plan_discard tool with a short reason, then tell the user the plan was abandoned and writes are restored. If the work is NOT ending but moving to another harness — crew orchestration (/crew) or a goal contract (/goal) — pass supersede with the successor artifact path (e.g. ".opencode/crew/2026-10-01-....md") so the plan is marked superseded instead, with the successor recorded in the plan file.',
   "- Any other argument: treat it as the task goal — you are now in planning mode for this goal. Follow the plan discipline below end to end.",
   "",
   "## Plan discipline",
@@ -15610,7 +15860,7 @@ var PLAN_COMMAND_TEMPLATE = [
   "4. Execution (tick as you go): work tasks in order; call plan_tick with the task number immediately after EACH task's work is actually done — never batch ticks, never tick ahead of reality (tick timestamps are an audit trail). If the plan turns out wrong mid-execution, do not silently improvise: tell the user what changed and either finish the affected task or ask about revising (/plan with the same goal re-enters planning).",
   "5. Completion (plan_close): when all tasks are ticked, self-check EVERY acceptance criterion with concrete evidence (file:line, command output, test result), then call plan_close with one check per criterion, pass/fail honest — a failing check refuses the close, and that is the design working, not an inconvenience. The user confirms closure in a dialog.",
   "",
-  "Boundaries: /plan discard abandons the plan (terminal, file kept as history, writes restored); /plan resume continues an unfinished plan from its remaining tasks. Work expected to span multiple sessions or days of multi-file change is spec work (e.g. OpenSpec), not plan work — say so once and let the user choose.",
+  "Boundaries: /plan discard abandons the plan (terminal, file kept as history, writes restored) — pass supersede (the successor artifact path) when the work moves to crew/goal rather than ends, marking it superseded; /plan resume continues an unfinished plan from its remaining tasks. Work expected to span multiple sessions or days of multi-file change is spec work (e.g. OpenSpec), not plan work — say so once and let the user choose.",
   ""
 ].join(`
 `);
@@ -15665,8 +15915,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 || "-";
@@ -15694,13 +15971,14 @@ function crewRecordPathFor(worktree, objective) {
     name = `${date5}-${slug}-${n++}.md`;
   return join6(dir, name);
 }
-function writeCrewRecord(path, objective, anchor, subtasks) {
+function writeCrewRecord(path, objective, anchor, subtasks, lineage) {
   mkdirSync5(join6(path, ".."), { recursive: true });
   writeFileSync5(path, [
     `# Crew Record: ${objective}`,
     "",
     `- registered: ${nowIso()}`,
     `- anchor: ${anchor}`,
+    ...lineage ? [`- lineage: ${lineage}`] : [],
     "",
     `## Declared plan (${subtasks.length})`,
     ...subtasks.map((s, i) => `${i + 1}. ${s.title}${s.agent ? ` → ${s.agent}` : ""}`),
@@ -15730,6 +16008,7 @@ function governingGoalFor(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):",
+    `RELAY FIRST: tell the user the crew record path (it leads this output) alongside this choice — the record is on disk from the registration moment, and the user must hear it.`,
     `  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.`
@@ -15874,7 +16153,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);
@@ -15941,7 +16220,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);
@@ -16034,28 +16313,40 @@ var planCloseTool = tool({
 Fix the implementation and retry, or revise the plan first.`);
     }
     await gate(context.ask, "plan_close", `Close plan: ${active.doc.goal}`);
-    writeFileSync5(active.path, transitionStatus(readFileSync8(active.path, "utf8"), "done", nowIso()));
+    const closedAt = nowIso();
+    const closed = appendTerminalSection(transitionStatus(readFileSync8(active.path, "utf8"), "done", closedAt), "closed", { reason: "completion gate passed (user confirmed)", checks: args.checks }, closedAt);
+    writeFileSync5(active.path, closed);
     context.metadata({ title: `Plan done: ${active.doc.goal}` });
     return {
       title: "plan done",
-      output: `Plan completed and closed (done): ${relFrom(state.worktree, active.path)}. All ${args.checks.length} self-checks passed.`
+      output: `Plan completed and closed (done): ${relFrom(state.worktree, active.path)}. All ${args.checks.length} self-checks passed. Terminal section "## ${closedAt} — closed" appended with the per-criterion verdicts.`
     };
   }
 });
 var planDiscardTool = tool({
-  description: "Abandon the session's active plan (draft/approved -> abandoned) and lift the draft write ban. Terminal: the file stays in .opencode/plan/ as history. Invoke via /plan discard or directly when the user cancels the task.",
+  description: "Abandon the session's active plan (draft/approved -> abandoned) and lift the draft write ban. Pass `supersede` (the successor artifact's path or identifier, e.g. a .opencode/crew/ or .opencode/goal/ file) when the work is not ending but moving to another harness (crew orchestration, a goal contract): the plan then becomes superseded instead of abandoned, with the successor recorded. Either way a dated terminal section carrying the reason verbatim (a missing reason lands as `reason: (none given)`) is appended to the file in the SAME write as the status flip, and the file stays in .opencode/plan/ as history. Invoke via /plan discard or directly when the user cancels the task.",
   args: {
-    reason: tool.schema.string().optional().describe("Short reason recorded in the reply")
+    reason: tool.schema.string().optional().describe("Short reason recorded in the reply and in the appended terminal section, verbatim"),
+    supersede: tool.schema.string().optional().describe("Successor artifact's path or identifier (crew record, goal contract, ...); when present the plan becomes superseded instead of abandoned and this value is persisted as the successor reference")
   },
-  execute: async (_args, context) => {
+  execute: async (args, context) => {
     const state = ensureSession(context.sessionID, worktreeFor(context));
     const active = resolveActivePlan(state);
     if (!active)
       throw new PlanError("No plan to abandon in this workspace.");
-    writeFileSync5(active.path, transitionStatus(readFileSync8(active.path, "utf8"), "abandoned", nowIso()));
+    const successor = (args.supersede ?? "").trim();
+    const superseding = successor.length > 0;
+    const target = superseding ? "superseded" : "abandoned";
+    const exitedAt = nowIso();
+    const next = appendTerminalSection(transitionStatus(readFileSync8(active.path, "utf8"), target, exitedAt), superseding ? "superseded" : "abandoned", { reason: args.reason, ...superseding ? { successor } : {} }, exitedAt);
+    writeFileSync5(active.path, next);
     state.planPath = undefined;
-    context.metadata({ title: `Plan abandoned: ${active.doc.goal}` });
-    return { title: "plan abandoned", output: `Plan abandoned: ${relFrom(state.worktree, active.path)}. Write operations are restored.` };
+    const section = `## ${exitedAt} — ${target}`;
+    context.metadata({ title: superseding ? `Plan superseded: ${active.doc.goal}` : `Plan abandoned: ${active.doc.goal}` });
+    return {
+      title: superseding ? "plan superseded" : "plan abandoned",
+      output: superseding ? `Plan superseded (not abandoned): ${relFrom(state.worktree, active.path)}. Terminal section "${section}" appended (successor: ${successor}). Write operations are restored.` : `Plan abandoned: ${relFrom(state.worktree, active.path)}. Terminal section "${section}" appended. Write operations are restored.`
+    };
   }
 });
 function goalDirOf(worktree) {
@@ -16065,7 +16356,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)) {
@@ -16174,7 +16465,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,
@@ -16546,30 +16837,38 @@ 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.",
+  "",
+  '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).",
+  "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). 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). 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.",
+    '1. REGISTER: call `crew_begin` with the objective AND the declared subtask plan (subtasks[]: one {title} per subtask, optionally naming the intended forge-* agent). When the macro contract descends from a plan artifact, pass its path as the optional `lineage` argument (e.g. lineage: ".opencode/plan/2026-10-01-my-plan.md") — the descent is recorded as a first-class line in the crew record header; lineage is never inferred. 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.",
@@ -16587,32 +16886,37 @@ var crewBeginTool = tool({
     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")
-    })).describe("The declared subtask plan — decompose the objective into these before any execution; crew_close cross-checks the report against exactly this list")
+    })).describe("The declared subtask plan — decompose the objective into these before any execution; crew_close cross-checks the report against exactly this list"),
+    lineage: tool.schema.string().optional().describe("Free-text origin of the macro contract — e.g. the plan artifact path this crew descends from (.opencode/plan/<date>-<slug>.md). Recorded as a first-class lineage: line in the crew record header and disclosed in the registration output. Explicit argument only — never inferred from recently-terminal plans.")
   },
   execute: async (args, context) => {
     noteToolAgent(context);
     const state = stateForBan(context.sessionID);
     const active = state ? resolveActivePlan(state) : null;
     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.");
+      throw new Error("[forge:crew] A plan is in draft; crew orchestration is denied during planning. Three exits: " + "plan_approve puts the plan to user approval (an APPROVED plan does not block /crew — only a draft does); " + "/plan discard abandons the plan outright; " + '/plan discard {supersede: "<successor path or id>"} moves the work into this crew (the plan becomes superseded, the successor recorded).');
     }
-    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 paths2 = forgeConfigPaths({ projectDir: hostAnchorDir || undefined, homeDir: process.env.FORGE_TEST_FORGE_HOME ?? homedir() });
+      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. Crew orchestration is unavailable until the user sets it up.",
-        `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."
+        `[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) {
-        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.`);
+      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(lines2.join(`
 `));
@@ -16692,13 +16996,14 @@ var crewBeginTool = tool({
       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 lineage = String(args.lineage ?? "").trim();
     const anchorDir = anchor || hostWorktree;
     let recordPath = null;
     let recordNote = "";
     if (anchorDir) {
       try {
         recordPath = crewRecordPathFor(anchorDir, objectiveText);
-        writeCrewRecord(recordPath, objectiveText, anchorDir, subtasks);
+        writeCrewRecord(recordPath, objectiveText, anchorDir, subtasks, lineage || undefined);
         recordNote = `Crew record (inspectable history; NOT a resume mechanism): ${relFrom(anchorDir, recordPath)}`;
       } catch {
         recordPath = null;
@@ -16708,21 +17013,29 @@ var crewBeginTool = tool({
     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 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 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 = [
+      ...recordNote ? [recordNote] : [],
+      ...lineage ? [`Lineage: ${lineage}`] : [],
       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] : [],
+      `Dispatchable roster origin — ${families.length} pool${families.length === 1 ? "" : "s"} across the host anchor set${hostAnchors.length > 0 ? ` (anchors: ${hostAnchors.join(", ")})` : ""}:`,
+      ...familyLines,
       ...disclosure ? [disclosure] : []
     ];
     if (governed) {
@@ -17040,7 +17353,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;
@@ -17151,23 +17466,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;
       }
@@ -17212,12 +17521,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 };
       }
@@ -17320,7 +17630,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 : "";
@@ -17348,7 +17658,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 ?? {};
@@ -17514,20 +17831,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,64 +1,64 @@
-{
-  "name": "@sorenllm/opencode-forge",
-  "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",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js"
-    },
-    "./server": {
-      "import": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "bundle": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && bun build ./plugin.ts --outfile ./dist/index.js --target node --format esm",
-    "test": "node --test tests/*.test.mjs",
-    "typecheck": "tsc --noEmit"
-  },
-  "keywords": [
-    "opencode",
-    "opencode-plugin",
-    "subagents",
-    "plan",
-    "planning",
-    "workflow",
-    "single-agent",
-    "goal",
-    "crew",
-    "orchestration",
-    "background-jobs",
-    "shell",
-    "watchdog"
-  ],
-  "license": "MIT",
-  "author": "chengsongren",
-  "homepage": "https://github.com/ChengZiiii/opencode-forge#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ChengZiiii/opencode-forge.git"
-  },
-  "bugs": {
-    "url": "https://github.com/ChengZiiii/opencode-forge/issues"
-  },
-  "peerDependencies": {
-    "@opencode-ai/plugin": "^1.18.0"
-  },
-  "devDependencies": {
-    "@opencode-ai/plugin": "^1.18.0",
-    "@types/node": "^22.13.9",
-    "typescript": "^5.8.2"
-  },
-  "engines": {
-    "opencode": "^1.18.0"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  }
-}
+{
+  "name": "@sorenllm/opencode-forge",
+  "version": "0.14.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",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "bundle": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && bun build ./plugin.ts --outfile ./dist/index.js --target node --format esm",
+    "test": "node --test tests/*.test.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "subagents",
+    "plan",
+    "planning",
+    "workflow",
+    "single-agent",
+    "goal",
+    "crew",
+    "orchestration",
+    "background-jobs",
+    "shell",
+    "watchdog"
+  ],
+  "license": "MIT",
+  "author": "chengsongren",
+  "homepage": "https://github.com/ChengZiiii/opencode-forge#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChengZiiii/opencode-forge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ChengZiiii/opencode-forge/issues"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.18.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.18.0",
+    "@types/node": "^22.13.9",
+    "typescript": "^5.8.2"
+  },
+  "engines": {
+    "opencode": "^1.18.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}