@opengsd/gsd-core 1.8.0 → 1.9.0

package/gsd-core/bin/gsd-tools.cjs

@@ -268,6 +268,7 @@ const roadmap = require('./lib/roadmap.cjs');
 const { detectAssumptionDelta } = require('./lib/assumption-delta.cjs');
 const verify = require('./lib/verify.cjs');
 const config = require('./lib/config.cjs');
+const estimateCli = require('./lib/estimate-cli.cjs');
 const template = require('./lib/template.cjs');
 const milestone = require('./lib/milestone.cjs');
 const commands = require('./lib/commands.cjs');
@@ -610,6 +611,7 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     let fastModeOverride;
     let attempt;
     let failureClass;
+    let host;
     const positionals = [];
     // #2296: the valid classes come from the classifier's own frozen enum, so
     // this validator can never drift from what `agent classify-failure` emits.
@@ -675,6 +677,13 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
         i++;
         continue;
       }
+      if (a === '--host') {
+        const val = execArgs[i + 1];
+        if (val === undefined || val.startsWith('--')) error('Missing value for --host', ERROR_REASON.USAGE);
+        host = val;
+        i++;
+        continue;
+      }
       if (a === '--raw') continue;
       if (a.startsWith('-')) error(`Unknown flag for resolve-execution: ${a}`, ERROR_REASON.USAGE);
       positionals.push(a);
@@ -687,6 +696,7 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
       fastModeOverride,
       attempt,
       failureClass,
+      host,
     });
   }
 
@@ -1120,6 +1130,357 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
           output({ ok: true, row: mutation.row, variant: mutation.variant }, raw, mutation.row);
   }
 
+  /**
+   * ADR-2782 Phase 5b (#2799) — the seam that lets `invoke_reviewers` iterate declared lanes.
+   *
+   * Replaces ~640 lines of hand-authored per-CLI bash with three subcommands:
+   *   plan    --selected a,b   → resolved lanes (slug, section, availability) as JSON
+   *   invoke  --slug X         → probe + run one lane, writing its review/stub into the run dir
+   *   sections --selected a,b  → ordered `slug<TAB>reviewsSection`, for write_reviews
+   *
+   * Lanes run SEQUENTIALLY (the workflow loops and calls `invoke` once per lane) because the
+   * original legs did — parallel invocation trips provider rate limits.
+   */
+  async function routeReviewLane({ args, cwd, raw, error }) {
+    const cp = require('node:child_process');
+    const fsx = require('node:fs');
+    const os = require('node:os');
+    const { REVIEWER_LANES } = require('./lib/review-lane-descriptor.cjs');
+    const { resolveLanePlan } = require('./lib/review-lane-invocation.cjs');
+    const runner = require('./lib/review-lane-runner.cjs');
+    const cfgLoader = require('./lib/config-loader.cjs');
+
+    const flag = (name) => {
+      const i = args.indexOf(name);
+      return i !== -1 && args[i + 1] && !String(args[i + 1]).startsWith('--') ? args[i + 1] : null;
+    };
+    const sub = args[1];
+    const runDir = flag('--run-dir') || '.';
+    const repoRoot = flag('--repo-root') || cwd;
+
+    // Resolved config, read ONCE. Reading in-process (rather than shelling out to config-get per
+    // key, as the legs did) is what removes the stringly `"null"` sentinel the bash had to test for.
+    // `loadConfigResolved` returns a PROVENANCE WRAPPER (`{config, source, degraded, reason}`),
+    // not the config — using the wrapper directly silently resolves every key to undefined, which
+    // reads exactly like "nothing configured" and drops every model override without an error.
+    let resolved = {};
+    try { resolved = (cfgLoader.loadConfigResolved(cwd) || {}).config || {}; } catch { resolved = {}; }
+    const configGet = (key) => {
+      let cur = resolved;
+      for (const part of String(key).split('.')) {
+        if (cur === null || typeof cur !== 'object') return undefined;
+        cur = Object.prototype.hasOwnProperty.call(cur, part) ? cur[part] : undefined;
+      }
+      return cur;
+    };
+
+    const selected = (flag('--selected') || '')
+      .split(',').map((s) => s.trim()).filter(Boolean);
+    const laneBySlug = new Map(REVIEWER_LANES.map((l) => [l.slug, l]));
+    const chosen = selected.length ? selected : REVIEWER_LANES.map((l) => l.slug);
+
+    if (sub === 'sections') {
+      const rows = chosen
+        .map((s) => laneBySlug.get(s))
+        .filter(Boolean)
+        .map((l) => `${l.slug}\t${l.reviewsSection}`);
+      process.stdout.write(rows.join('\n') + (rows.length ? '\n' : ''));
+      return;
+    }
+
+    // Phase 6 (#2800, closes #2272). The reviewer-flag lists in
+    // plan-review-convergence.md, autonomous.md and next.md were hand-enumerated in three places
+    // and had drifted apart: `--coderabbit` was missing from all three and had been silently
+    // falling back to `--codex`. One declared source, three consumers.
+    //
+    // Emits FLAGS, not slugs: `antigravity` declares two (`--antigravity`, `--agy`), so the flag
+    // count (13) is deliberately not the lane count (12). Same output contract as `sections` —
+    // one token per line, descriptor order, and no trailing newline on an empty result.
+    if (sub === 'flags') {
+      const rows = chosen
+        .map((s) => laneBySlug.get(s))
+        .filter(Boolean)
+        .flatMap((l) => (Array.isArray(l.flags) ? l.flags : []))
+        // Shape-filtered, not merely non-empty. All three consumers read this through an
+        // UNQUOTED `$(gsd_run review-lane flags)` so the newline-separated output word-splits
+        // into loop items — which is the intent. Phase 2 (#2795) admits third-party overlay
+        // lanes into this same descriptor, so an overlay declaring `--foo bar` would inject a
+        // second loop item, and one declaring a glob character would expand against the cwd.
+        // Emitting only well-formed flags keeps that from reaching the shell at all.
+        .filter((f) => typeof f === 'string' && /^--[a-z0-9][a-z0-9-]*$/.test(f));
+      process.stdout.write(rows.join('\n') + (rows.length ? '\n' : ''));
+      return;
+    }
+
+    // Effort argv is resolved per lane by the host's own execution policy, exactly as the legs did
+    // via `resolve-execution … --pick effort_argv_string`. A lane whose slug is not a known host
+    // simply gets none.
+    // Resolved through the SAME `resolve-execution` surface the bash legs used
+    // (`--host <slug> --pick effort_argv_string`), so the host's negotiated effortSurface still
+    // decides whether an argument is emitted and the catalog still owns the syntax (ADR-1239 #2481,
+    // ADR-443's escalation ladder). `cmdResolveExecution` writes to stdout and exits, so it cannot
+    // be called in-process for a value — this spawns the same bounded query the legs did, once per
+    // selected lane. A lane whose slug is not a known host resolves to no effort argument at all.
+    const effortFor = (slug) => {
+      try {
+        const r = cp.spawnSync(
+          process.execPath,
+          [__filename, 'query', 'resolve-execution', 'gsd-plan-checker',
+            // NOT `--raw`: that prints the resolved EFFORT ('low'), ignoring --pick. The picked
+            // field is what carries the host-specific syntax ('--effort low' for claude,
+            // '-c model_reasoning_effort=low' for codex), which is the whole point of asking.
+            '--host', slug, '--pick', 'effort_argv_string'],
+          { cwd, encoding: 'utf8', timeout: 15000, killSignal: 'SIGKILL', maxBuffer: 1024 * 1024 },
+        );
+        if (r.status !== 0) return [];
+        const s = String(r.stdout || '').trim();
+        return s ? s.split(/\s+/).filter(Boolean) : [];
+      } catch { return []; }
+    };
+
+    /**
+     * Per-lane prompt budget (#2797 semantics, preserved exactly).
+     *
+     * `-1` is the UNSET sentinel and falls back to the central `review.max_prompt_tokens`, because
+     * `0` is a legitimate value meaning "do not trim this lane". Treating 0 as unset would silently
+     * switch a user who deliberately disabled trimming onto the global budget.
+     *
+     * Only the budget VALUE is resolved here. Assembly and trimming stay in `prompt-budget`, which
+     * already owns that machinery and is already tested; the workflow calls it and hands the
+     * trimmed file back via `--prompt-file`. Re-implementing it inside the runner would fork a
+     * tested surface for no gain.
+     */
+    const budgetFor = (lane) => {
+      if (!lane.promptBudgetKey) return null;
+      const per = configGet(lane.promptBudgetKey);
+      const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+      if (isNum(per) && per !== -1) return per;
+      const global = configGet('review.max_prompt_tokens');
+      return isNum(global) ? global : null;
+    };
+
+    const plans = chosen.map((slug) => {
+      const lane = laneBySlug.get(slug);
+      if (!lane) return { slug, ok: false, reason: 'malformed_lane', detail: 'no such declared lane' };
+      // Per-lane isolation. resolveLanePlan is documented total, but this map is the seam where a
+      // single throw would take down EVERY selected lane rather than the one that is malformed —
+      // and "a cross-AI review that silently drops a lane" is the failure this epic exists to end,
+      // so losing all of them to one bad manifest is strictly worse. Belt and braces on purpose.
+      let r;
+      try {
+        r = resolveLanePlan({ lane, configGet, runDir, repoRoot, effortArgs: effortFor(slug) });
+      } catch (e) {
+        return { slug, ok: false, reason: 'malformed_lane', detail: `resolver threw: ${e && e.message ? e.message : String(e)}` };
+      }
+      return r.ok
+        ? {
+            slug,
+            ok: true,
+            section: lane.reviewsSection,
+            transport: r.plan.transport,
+            promptBudget: budgetFor(lane),
+            promptPath: r.plan.transport === 'spawn' ? r.plan.stdin : r.plan.promptPath,
+            plan: r.plan,
+          }
+        : { slug, ok: false, reason: r.reason, detail: r.detail };
+    });
+
+    if (sub === 'plan') {
+      output(plans.map(({ plan, ...rest }) => rest), raw);
+      return;
+    }
+
+    if (sub !== 'invoke') {
+      error("Usage: review-lane <plan|invoke|sections|flags> [--selected a,b] [--run-dir D] [--repo-root R]");
+      return;
+    }
+
+    const slug = flag('--slug');
+    if (!slug) { error('review-lane invoke requires --slug'); return; }
+    const entry = plans.find((p) => p.slug === slug);
+    if (!entry || !entry.ok) {
+      output({ slug, ok: false, reason: entry ? entry.reason : 'malformed_lane', detail: entry ? entry.detail : 'unknown lane' }, raw);
+      return;
+    }
+
+    // EVERY spawn bounded — `DEFECT.UNBOUNDED-SUBPROCESS` (CONTEXT.md:772). A frozen sync spawn
+    // cannot be interrupted by --test-force-exit and hangs a whole CI chunk to its 10-minute kill.
+    const deps = {
+      spawn: (binary, argv, opts) => {
+        const r = cp.spawnSync(binary, argv, {
+          input: opts.input,
+          encoding: 'utf8',
+          timeout: opts.timeoutMs,
+          killSignal: 'SIGKILL',
+          maxBuffer: 64 * 1024 * 1024,
+          shell: false, // argv array only — never a shell string (no interpolation of config values)
+        });
+        return {
+          status: r.status,
+          stdout: r.stdout || '',
+          stderr: r.stderr || '',
+          errorCode: r.error && r.error.code ? r.error.code : undefined,
+        };
+      },
+      httpJson: async (url, opts) => {
+        try {
+          const res = await fetch(url, {
+            method: opts.method,
+            headers: opts.body ? { 'Content-Type': 'application/json' } : undefined,
+            body: opts.body,
+            signal: AbortSignal.timeout(opts.timeoutMs),
+          });
+          return { ok: res.ok, status: res.status, body: await res.text() };
+        } catch (e) {
+          return { ok: false, status: 0, body: '', error: e && e.message ? e.message : String(e) };
+        }
+      },
+      readFile: (p) => fsx.readFileSync(p, 'utf8'),
+      writeFile: (p, c) => fsx.writeFileSync(p, c, 'utf8'),
+      exists: (p) => fsx.existsSync(p),
+      // PATH scan rather than spawning `command -v` / `where`. Two reasons: it spawns nothing at
+      // all (a probe that costs a process is a probe you avoid running, which is how the original
+      // Kimi probe ended up unbounded), and `shell: true` with an args array is deprecated in
+      // Node 26 (DEP0190) because the arguments are concatenated rather than escaped.
+      hasBinary: (name) => {
+        if (!name || name.includes('/') || name.includes('\\')) {
+          try { return fsx.statSync(name).isFile(); } catch { return false; }
+        }
+        const exts = process.platform === 'win32'
+          ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';').filter(Boolean)
+          : [''];
+        for (const dir of (process.env.PATH || '').split(path.delimiter).filter(Boolean)) {
+          for (const ext of exts) {
+            const candidate = path.join(dir, name + ext);
+            try {
+              const st = fsx.statSync(candidate);
+              if (st.isFile()) return true;
+            } catch { /* next candidate */ }
+          }
+        }
+        return false;
+      },
+      configGet,
+      homeDir: os.homedir(),
+      warn: (m) => process.stderr.write(`${m}\n`),
+    };
+
+    // ADR-1517 reviewer instances resolve THROUGH a lane rather than being lanes themselves
+    // (ADR-2782 D8), so they reuse this seam with three substitutions instead of duplicating the
+    // lane's invocation. Everything the lane declares — probe, channels, timeout, empty-output
+    // policy, handler — then applies to the instance unchanged, which is the whole reason to route
+    // them here: a cross-cutting fix reaches instances for free.
+    const asIdentity = flag('--as');
+    const instanceModel = flag('--model');
+    const instanceAgent = flag('--agent');
+
+    if (asIdentity) {
+      // Write under the INSTANCE name so two instances of one adapter never overwrite each other.
+      const safe = String(asIdentity).replace(/[^A-Za-z0-9._-]/g, '-');
+      entry.plan.reviewPath = `${runDir.replace(/\/+$/, '')}/gsd-review-${safe}.md`;
+      entry.plan.errPath = `${runDir.replace(/\/+$/, '')}/gsd-review-${safe}.err`;
+      if (entry.plan.transport === 'spawn' && entry.plan.outputTarget.kind === 'file') {
+        // A file-arg lane names its output inside argv; retarget both together or the runner reads
+        // the lane's file while the tool writes the instance's.
+        const old = entry.plan.outputTarget.path;
+        entry.plan.argv = entry.plan.argv.map((a) => (a === old ? entry.plan.reviewPath : a));
+        entry.plan.outputTarget = { kind: 'file', path: entry.plan.reviewPath };
+      }
+    }
+
+    // The instance's own model replaces whatever the lane resolved from config. Opaque
+    // pass-through: it reaches the tool as one argv element and is never shell-interpolated.
+    //
+    // Done by RE-RESOLVING with an overridden config rather than by patching argv afterwards. A
+    // post-hoc splice has to guess where the flag belongs when the lane resolved no model at all
+    // (the placeholder expanded to nothing, so there is no position to find), and guessing puts it
+    // before a subcommand — `opencode --model M run …`, the same defect the argv template exists to
+    // prevent. Re-resolving lets the lane's own `{{model}}` placeholder decide the position.
+    if (instanceModel) {
+      const lane = laneBySlug.get(entry.slug);
+      const key = lane && lane.modelConfigKey;
+      // A lane that declares NO model key accepts no model override at all (`cursor`, `qwen`,
+      // `coderabbit`). `review.reviewer_instances` validates that `cli` is a known slug but never
+      // that the slug accepts a model, so a user can configure {"cli":"cursor","model":"gpt-5"},
+      // get a clean config-set and a clean run, and never learn their model was ignored. Say so —
+      // a review silently produced by a different model than the one configured is exactly the
+      // "looked like it worked" failure this epic exists to end.
+      if (!key) {
+        process.stderr.write(
+          `reviewer instance model '${instanceModel}' ignored: lane '${entry.slug}' accepts no ` +
+          `model override (it declares no modelConfigKey). The review will use the CLI's own default.\n`,
+        );
+      }
+      const overridden = resolveLanePlan({
+        lane,
+        configGet: (k) => (key && k === key ? instanceModel : configGet(k)),
+        runDir,
+        repoRoot,
+        effortArgs: effortFor(entry.slug),
+      });
+      if (overridden.ok) {
+        // Preserve any instance retargeting already applied above.
+        const { reviewPath, errPath } = entry.plan;
+        entry.plan = overridden.plan;
+        if (asIdentity) {
+          entry.plan.reviewPath = reviewPath;
+          entry.plan.errPath = errPath;
+          if (entry.plan.transport === 'spawn' && entry.plan.outputTarget.kind === 'file') {
+            const old = entry.plan.outputTarget.path;
+            entry.plan.argv = entry.plan.argv.map((a) => (a === old ? reviewPath : a));
+            entry.plan.outputTarget = { kind: 'file', path: reviewPath };
+          }
+        }
+      }
+    }
+
+    // `--agent` is OpenCode's native subagent flag and is honoured only by adapters that have the
+    // concept; ignored elsewhere rather than passed to a tool that would reject it.
+    if (instanceAgent && entry.slug === 'opencode' && entry.plan.transport === 'spawn') {
+      const runIdx = entry.plan.argv.indexOf('run');
+      const insertAt = runIdx === -1 ? 0 : runIdx + 1;
+      entry.plan.argv = [
+        ...entry.plan.argv.slice(0, insertAt),
+        '--agent',
+        instanceAgent,
+        ...entry.plan.argv.slice(insertAt),
+      ];
+    }
+
+    // `--prompt-file` lets the caller substitute a budget-trimmed prompt. Applied to whichever
+    // channel this lane actually reads from, so one flag serves both transports.
+    const promptOverride = flag('--prompt-file');
+    if (promptOverride) {
+      if (entry.plan.transport === 'spawn') {
+        if (entry.plan.stdin) entry.plan.stdin = promptOverride;
+      } else {
+        entry.plan.promptPath = promptOverride;
+      }
+    }
+
+    // ADR-2782 D5 rule 4: re-resolve the consented destination at INVOCATION. `undefined` (no
+    // consent record, or a record predating rule 1) means "nothing to compare" and ALLOWS — a
+    // first-party lane ships inside the SHA-pinned distribution and is never consent-gated, so
+    // denying on absence would break every existing local-model user.
+    let consentedHost;
+    if (entry.plan.transport === 'openai-http') {
+      try {
+        const consent = require('./lib/capability-consent.cjs');
+        const projectRoot = require('./lib/project-root.cjs').consentProjectRoot(cwd);
+        // The capability id is kebab; the lane slug may be snake (lm_studio / lm-studio).
+        const capId = String(entry.slug).replace(/_/g, '-');
+        consentedHost = consent.readConsentedReviewerHost({ projectRoot, id: capId });
+      } catch { consentedHost = undefined; }
+    }
+
+    const result = await runner.runLane(entry.plan, deps, {
+      consentedHost,
+      explicitlyRequested: args.includes('--explicit'),
+      repoRoot,
+    });
+    output(result, raw);
+  }
+
   function routeNormalizeTestCommand({ args, cwd, raw, error }) {
     // #1857: rewrite a resolved test command to a one-shot form so a
           // watch-mode runner (vitest/jest) cannot hang a verification gate. Shared
@@ -1178,6 +1539,135 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
           }
   }
 
+  function routeDispatchIsolation({ args, cwd, raw, error }) {
+    // #2584 Phase 3 (#2627): typed query exposing the negotiated
+    // `dispatch.isolation` to the execute-phase wave scheduler, so the
+    // scheduler branches on a declared capability instead of on a runtime id.
+    // Direct sibling of `dispatch-should-flatten` above, which exists (#1708 /
+    // #853) for exactly this reason — it replaced a `RUNTIME === 'codex'`
+    // prose rule.
+    //
+    // Resolves the current runtime (GSD_RUNTIME > config.runtime > 'claude'),
+    // reads registry.runtimes[id].runtime.hostIntegration.dispatch.isolation,
+    // and validates it against the closed vocabulary.
+    //
+    // Fail-closed: unknown runtime, missing/undeclared/out-of-vocabulary value,
+    // or any thrown error yields `none` — sequential execution, never an
+    // unsafe parallel path (ADR-1239, "Fail-closed").
+    //
+    // Output:
+    //   --raw   → prints exactly harness-worktree | orchestrator-worktree | none
+    //   --json  → prints { runtime, isolation, exec }
+    //   default → same as --raw
+    //
+    // `exec` is the resolved orchestratorExec argv/cwd shape, present only for
+    // `orchestrator-worktree`. It requires `--cwd-target` (the GSD-created
+    // worktree path) and optionally `--prompt`; without a target there is
+    // nothing to bind, so `exec` is null.
+    const VALID_ISOLATION = new Set(['harness-worktree', 'orchestrator-worktree', 'none']);
+    let isolation = 'none';
+    let runtimeId = null;
+    let exec = null;
+    let harnessFlag = null;
+    try {
+      const { resolveRuntime } = require('./lib/runtime-slash.cjs');
+      runtimeId = resolveRuntime(cwd);
+
+      const registry = require('./lib/capability-registry.cjs');
+      const runtimeEntry = registry.runtimes != null
+        ? registry.runtimes[runtimeId]
+        : null;
+      const declared = runtimeEntry?.runtime?.hostIntegration?.dispatch?.isolation ?? null;
+      if (typeof declared === 'string' && VALID_ISOLATION.has(declared)) {
+        isolation = declared;
+      }
+
+      if (isolation === 'harness-worktree') {
+        const declaredFlag = runtimeEntry?.runtime?.harnessIsolationFlag ?? null;
+        // A host claiming harness isolation with no declared flag gives the
+        // scheduler nothing to pass — degrade to sequential rather than
+        // dispatch unisolated executors believing they are isolated.
+        if (typeof declaredFlag === 'string' && declaredFlag.length > 0) {
+          harnessFlag = declaredFlag;
+        } else {
+          isolation = 'none';
+        }
+      }
+
+      if (isolation === 'orchestrator-worktree') {
+        const cwdIdx = args.indexOf('--cwd-target');
+        const cwdTarget = cwdIdx !== -1 ? args[cwdIdx + 1] : '';
+        if (cwdTarget) {
+          const promptIdx = args.indexOf('--prompt');
+          const promptArg = promptIdx !== -1 ? args[promptIdx + 1] : undefined;
+          const hostIntegration = require('./lib/host-integration.cjs');
+          const resolution = hostIntegration.resolveOrchestratorExec(
+            runtimeEntry?.runtime?.orchestratorExec,
+            cwdTarget,
+            promptArg,
+          );
+          // A host declaring orchestrator-worktree whose exec descriptor does
+          // not resolve cannot be spawned — degrade to sequential rather than
+          // hand the scheduler an unusable command.
+          if (resolution.ok) {
+            exec = { command: resolution.command, args: resolution.args, cwd: resolution.cwd };
+          } else {
+            isolation = 'none';
+          }
+        }
+      }
+    } catch {
+      isolation = 'none';
+      exec = null;
+      harnessFlag = null;
+    }
+
+    if (args.indexOf('--json') !== -1) {
+      output({ runtime: runtimeId, isolation, exec, harnessFlag }, raw);
+    } else {
+      process.stdout.write(isolation);
+    }
+  }
+
+  function routeResolveDispatchType({ args, cwd, raw, error }) {
+    // #2508 Phase 4 Option A: resolve a requested GSD subagent name to the
+           // type an Agent() call should use on the current runtime. On
+           // named-dispatch runtimes (Claude, OpenCode, …) the name is returned
+           // unchanged; on built-in-only runtimes (kimi-code) it maps to the
+           // closest built-in (coder/explore/plan) by role-suffix heuristic.
+           // The persona rides ${AGENT_SKILLS_*} (Phase 3 / #2510) regardless.
+           //
+           // Output:
+           //   --raw (default) → prints the resolved type (e.g. "gsd-planner" or "plan")
+           //   --json          → prints { runtime, requested, resolved, dispatch }
+           try {
+             const requestedIdx = args.indexOf('--requested');
+             const requested = requestedIdx !== -1 ? args[requestedIdx + 1] : '';
+             const { resolveRuntime } = require('./lib/runtime-slash.cjs');
+             const runtimeId = resolveRuntime(cwd);
+             const registry = require('./lib/capability-registry.cjs');
+             const runtimeEntry = registry.runtimes != null
+               ? registry.runtimes[runtimeId]
+               : null;
+             const dispatch = runtimeEntry?.runtime?.hostIntegration?.dispatch ?? null;
+             const hostIntegration = require('./lib/host-integration.cjs');
+             const resolved = hostIntegration.resolveDispatchType(requested, dispatch);
+             const jsonIdx = args.indexOf('--json');
+             if (jsonIdx !== -1) {
+               output({ runtime: runtimeId, requested, resolved, dispatch }, raw);
+             } else {
+               process.stdout.write(String(resolved));
+             }
+           } catch {
+             // Fail-closed: on any error, echo the requested name unchanged
+             // (named-dispatch is the GSD default; degrading to it preserves
+             // behavior for every runtime already in the field).
+             const requestedIdx = args.indexOf('--requested');
+             const requested = requestedIdx !== -1 ? args[requestedIdx + 1] : '';
+             process.stdout.write(String(requested));
+           }
+  }
+
   function routeAgentSkills({ args, cwd, raw, error }) {
     // --json emits typed IR { agent_type, block, skills_count } for test assertions
           // (#455). Default (no flag) outputs raw XML so workflow shell expansions work.
@@ -1457,8 +1947,10 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
             require('./lib/worktree-base-ref.cjs').cmdWorktreeBaseCheck(cwd, args.slice(2));
           } else if (subcommand === 'set-baseref') {
             require('./lib/worktree-base-ref.cjs').cmdWorktreeSetBaseRef(cwd, args.slice(2));
+          } else if (subcommand === 'create') {
+            worktreeSafety.cmdWorktreeCreate(cwd, args.slice(2));
           } else {
-            error('Unknown worktree subcommand. Available: cleanup-wave, record-agent, reap-orphans, base-check, set-baseref', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+            error('Unknown worktree subcommand. Available: cleanup-wave, record-agent, reap-orphans, base-check, set-baseref, create', ERROR_REASON.SDK_UNKNOWN_COMMAND);
           }
   }
 
@@ -1634,6 +2126,349 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
           process.stdout.write(JSON.stringify(out, null, 2));
   }
 
+  // ─── restore-custom-files (#1854) ───────────────────────────────────────────
+  // The counterpart to detect-custom-files. `backup_custom_files` copies
+  // user-added files into <config-dir>/gsd-user-files-backup/ before the
+  // clean-install wipe; until #1854 nothing ever read them back — the update
+  // workflow just printed "Restore them after the update if needed" and moved
+  // on. (`/gsd:update --reapply` covers the OTHER bucket: shipped files the
+  // user MODIFIED, kept in gsd-local-patches/.)
+  //
+  // Two modes, both emitting the same JSON report:
+  //   plan (default)  — walk the backup, run the compatibility pass, write nothing
+  //   --apply         — same, then copy the eligible entries back
+  //
+  // Invariants: the backup is never deleted; a shipped file is never clobbered;
+  // an existing differing file is never clobbered; one failed entry never
+  // aborts the rest; nothing is written outside the config dir.
+  const RESTORE_OUTCOME = Object.freeze({
+    ELIGIBLE: 'eligible',
+    RESTORED: 'restored',
+    SKIPPED_DESTINATION_MANAGED: 'skipped_destination_managed',
+    SKIPPED_DESTINATION_EXISTS: 'skipped_destination_exists',
+    SKIPPED_COPY_FAILED: 'skipped_copy_failed',
+    SKIPPED_UNSAFE_PATH: 'skipped_unsafe_path',
+  });
+
+  const RESTORE_WARNING = Object.freeze({
+    DESTINATION_MANAGED: 'destination_managed',
+    DESTINATION_EXISTS: 'destination_exists',
+    MISSING_REFERENCED_PATH: 'missing_referenced_path',
+    MISSING_REFERENCED_COMMAND: 'missing_referenced_command',
+    FRONTMATTER_MISSING_FIELD: 'frontmatter_missing_field',
+    WRITE_FAILED: 'write_failed',
+  });
+
+  // Compatibility scanning reads backed-up files whole. Cap the read so a
+  // stray large artifact in the backup cannot balloon memory; oversized files
+  // still restore, they just skip the (advisory) content scan.
+  const RESTORE_SCAN_MAX_BYTES = 1024 * 1024;
+  const RESTORE_BACKUP_DIR_NAME = 'gsd-user-files-backup';
+
+  // Referenced shipped paths (`@gsd-core/workflows/foo.md`) and slash commands
+  // (`/gsd:plan-phase`) are the two references a custom skill most commonly
+  // makes into GSD itself, and the two that a release most commonly renames.
+  const RESTORE_GSD_PATH_RE = /gsd-core\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\.(?:md|cjs|js|json|sh)/g;
+  const RESTORE_SLASH_COMMAND_RE = /\/gsd:[a-z0-9][a-z0-9-]*/g;
+
+  /**
+   * Walk the backup tree, refusing to follow symlinks. Returns entries in
+   * stable sorted order; `unsafe` marks a link we saw but will not traverse
+   * or copy (reported for auditability rather than silently dropped).
+   */
+  function collectBackupEntries(dir, baseDir, out) {
+    let dirents;
+    try {
+      dirents = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return out;
+    }
+    for (const entry of dirents.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+      const fullPath = path.join(dir, entry.name);
+      // Path separators are normalized unconditionally: backslash-shaped
+      // relative paths reach Linux too (backups copied between machines).
+      const relPath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
+      if (entry.isSymbolicLink()) {
+        out.push({ relPath, unsafe: true });
+        continue;
+      }
+      if (entry.isDirectory()) {
+        collectBackupEntries(fullPath, baseDir, out);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      out.push({ relPath, unsafe: false });
+    }
+    return out;
+  }
+
+  // Why these three checks rather than security.cjs's `validatePath`: that seam
+  // resolves symlinks with realpathSync and then tests containment, so a link
+  // whose target sits inside the config dir passes. For a restore that is still
+  // wrong — writing through any link overwrites whatever it points at instead
+  // of materializing a regular file at the backed-up path. These checks reject
+  // links outright, which is strictly stricter than validatePath, not a
+  // reimplementation of it. Do not "simplify" this to validatePath.
+
+  /** True when `target` resolves strictly inside `root`. */
+  function isInsideDir(root, target) {
+    const rel = path.relative(path.resolve(root), path.resolve(target));
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+  }
+
+  /**
+   * True when `target` itself exists and is a symlink. `fs.existsSync` and
+   * `copyFileSync` both FOLLOW links, so a symlinked destination would let a
+   * restore write through to the link's target — outside the config dir —
+   * even though every ancestor is a real directory.
+   */
+  function isSymlinkPath(target) {
+    try {
+      return fs.lstatSync(target).isSymbolicLink();
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * True when the deepest already-existing ancestor of `target` is a symlink.
+   * A symlinked parent directory would let a copy land outside the config dir
+   * even though the joined path looks contained.
+   */
+  function hasSymlinkedAncestor(root, target) {
+    let cursor = path.dirname(path.resolve(target));
+    const stop = path.resolve(root);
+    while (cursor.length >= stop.length && cursor.startsWith(stop)) {
+      let st;
+      try {
+        st = fs.lstatSync(cursor);
+      } catch {
+        cursor = path.dirname(cursor);
+        if (cursor === stop) return false;
+        continue;
+      }
+      if (st.isSymbolicLink()) return true;
+      if (cursor === stop) return false;
+      cursor = path.dirname(cursor);
+    }
+    return false;
+  }
+
+  /**
+   * Best-effort compatibility pass of one backed-up file against the NEWLY
+   * installed release. Every finding is advisory — a warning never blocks a
+   * restore, it just travels with the entry into the report.
+   */
+  function scanRestoreCompatibility(srcPath, relPath, configDir) {
+    const warnings = [];
+    let size = 0;
+    try {
+      size = fs.statSync(srcPath).size;
+    } catch {
+      return warnings;
+    }
+    if (size > RESTORE_SCAN_MAX_BYTES) return warnings;
+
+    let content;
+    try {
+      content = fs.readFileSync(srcPath, 'utf8');
+    } catch {
+      return warnings;
+    }
+
+    const missingPaths = new Set();
+    for (const match of content.match(RESTORE_GSD_PATH_RE) || []) {
+      if (!fs.existsSync(path.join(configDir, match))) missingPaths.add(match);
+    }
+    for (const missing of missingPaths) {
+      warnings.push({
+        code: RESTORE_WARNING.MISSING_REFERENCED_PATH,
+        detail: `references ${missing}, which the installed release does not ship`,
+      });
+    }
+
+    const missingCommands = new Set();
+    for (const match of content.match(RESTORE_SLASH_COMMAND_RE) || []) {
+      const verb = match.slice('/gsd:'.length);
+      if (!fs.existsSync(path.join(configDir, 'commands', 'gsd', `${verb}.md`))) {
+        missingCommands.add(match);
+      }
+    }
+    for (const missing of missingCommands) {
+      warnings.push({
+        code: RESTORE_WARNING.MISSING_REFERENCED_COMMAND,
+        detail: `references ${missing}, which the installed release does not provide`,
+      });
+    }
+
+    // Skills and agents/commands are frontmatter-driven surfaces: a file the
+    // runtime cannot parse is restored-but-dead, which is worth saying out loud.
+    const base = relPath.split('/').pop();
+    const isFrontmatterSurface = base === 'SKILL.md'
+      || relPath.startsWith('agents/')
+      || relPath.startsWith('commands/');
+    if (isFrontmatterSurface) {
+      const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+      const missingFields = [];
+      if (!block) {
+        missingFields.push('name', 'description');
+      } else {
+        if (!/^name:\s*\S/m.test(block[1])) missingFields.push('name');
+        if (!/^description:\s*\S/m.test(block[1])) missingFields.push('description');
+      }
+      if (missingFields.length > 0) {
+        warnings.push({
+          code: RESTORE_WARNING.FRONTMATTER_MISSING_FIELD,
+          detail: `frontmatter is missing required field(s): ${missingFields.join(', ')}`,
+        });
+      }
+    }
+
+    return warnings;
+  }
+
+  function routeRestoreCustomFiles({ args, error }) {
+    // Last-wins so a duplicated flag resolves rather than erroring, matching
+    // the rest of the gsd-tools flag surface.
+    let configDir = null;
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] !== '--config-dir') continue;
+      configDir = args[i + 1] === undefined ? null : args[i + 1];
+    }
+    const apply = args.includes('--apply');
+
+    if (configDir === null || configDir.trim() === '' || configDir.startsWith('--')) {
+      error('Usage: gsd-tools restore-custom-files --config-dir <path> [--apply]', ERROR_REASON.USAGE);
+    }
+    const resolvedConfigDir = path.resolve(configDir);
+    if (!fs.existsSync(resolvedConfigDir)) {
+      error(`Config directory not found: ${resolvedConfigDir}`, ERROR_REASON.USAGE);
+    }
+
+    // lstat, not stat: a symlinked backup root would let the walk read files
+    // from anywhere on disk and present them as the user's own backup.
+    const backupDir = path.join(resolvedConfigDir, RESTORE_BACKUP_DIR_NAME);
+    let backupFound = false;
+    try {
+      backupFound = fs.lstatSync(backupDir).isDirectory();
+    } catch {
+      backupFound = false;
+    }
+
+    // The manifest describes what the NEW release ships. Without it the
+    // destination-managed check has no source of truth — degrade to restoring
+    // without that check rather than refusing to restore the user's own data.
+    let manifestKeys = new Set();
+    let manifestFound = false;
+    const manifestPath = path.join(resolvedConfigDir, 'gsd-file-manifest.json');
+    if (fs.existsSync(manifestPath)) {
+      try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        // Shape, not just type (ADR-227): `files` must be a plain object for
+        // its keys to mean "paths this release ships". An array or a scalar
+        // yields numeric-index keys that silently match nothing, which would
+        // report a usable manifest while the managed-path check is dead.
+        const files = manifest && manifest.files;
+        const isPlainObject = typeof files === 'object'
+          && files !== null
+          && !Array.isArray(files);
+        if (isPlainObject) {
+          manifestKeys = new Set(Object.keys(files));
+          manifestFound = true;
+        }
+      } catch {
+        manifestFound = false;
+      }
+    }
+
+    const entries = [];
+    for (const found of backupFound ? collectBackupEntries(backupDir, backupDir, []) : []) {
+      const { relPath } = found;
+      const srcPath = path.join(backupDir, relPath);
+      const destPath = path.join(resolvedConfigDir, relPath);
+
+      if (found.unsafe
+        || !isInsideDir(resolvedConfigDir, destPath)
+        || isSymlinkPath(destPath)
+        || hasSymlinkedAncestor(resolvedConfigDir, destPath)) {
+        entries.push({
+          path: relPath,
+          outcome: RESTORE_OUTCOME.SKIPPED_UNSAFE_PATH,
+          warnings: [],
+        });
+        continue;
+      }
+
+      const warnings = scanRestoreCompatibility(srcPath, relPath, resolvedConfigDir);
+
+      if (manifestFound && manifestKeys.has(relPath)) {
+        warnings.unshift({
+          code: RESTORE_WARNING.DESTINATION_MANAGED,
+          detail: 'the installed release now ships this path — restoring would overwrite it',
+        });
+        entries.push({ path: relPath, outcome: RESTORE_OUTCOME.SKIPPED_DESTINATION_MANAGED, warnings });
+        continue;
+      }
+
+      // An identical destination is a no-op restore, not a conflict: re-running
+      // the restore after a successful one must stay quiet and idempotent.
+      let destDiffers = false;
+      if (fs.existsSync(destPath)) {
+        try {
+          destDiffers = !fs.readFileSync(destPath).equals(fs.readFileSync(srcPath));
+        } catch {
+          destDiffers = true;
+        }
+      }
+      if (destDiffers) {
+        warnings.unshift({
+          code: RESTORE_WARNING.DESTINATION_EXISTS,
+          detail: 'a different file already exists at this path — restoring would overwrite it',
+        });
+        entries.push({ path: relPath, outcome: RESTORE_OUTCOME.SKIPPED_DESTINATION_EXISTS, warnings });
+        continue;
+      }
+
+      if (!apply) {
+        entries.push({ path: relPath, outcome: RESTORE_OUTCOME.ELIGIBLE, warnings });
+        continue;
+      }
+
+      try {
+        fs.mkdirSync(path.dirname(destPath), { recursive: true });
+        fs.copyFileSync(srcPath, destPath);
+        entries.push({ path: relPath, outcome: RESTORE_OUTCOME.RESTORED, warnings });
+      } catch (err) {
+        const code = err && err.code ? String(err.code) : 'ERROR';
+        entries.push({
+          path: relPath,
+          outcome: RESTORE_OUTCOME.SKIPPED_COPY_FAILED,
+          warnings: warnings.concat([{
+            code: RESTORE_WARNING.WRITE_FAILED,
+            detail: `could not write the destination [${code}] — the backup copy is unchanged`,
+          }]),
+        });
+      }
+    }
+
+    const restoredCount = entries.filter(e => e.outcome === RESTORE_OUTCOME.RESTORED).length;
+    const eligibleCount = entries.filter(
+      e => e.outcome === RESTORE_OUTCOME.ELIGIBLE || e.outcome === RESTORE_OUTCOME.RESTORED,
+    ).length;
+
+    process.stdout.write(JSON.stringify({
+      backup_dir: backupDir,
+      backup_found: backupFound,
+      manifest_found: manifestFound,
+      applied: apply,
+      entries,
+      eligible_count: eligibleCount,
+      restored_count: restoredCount,
+      skipped_count: entries.length - eligibleCount,
+      warning_count: entries.reduce((sum, e) => sum + e.warnings.length, 0),
+    }, null, 2));
+  }
+
   function routeFromGsd2({ args, cwd, raw, error }) {
     const gsd2Import = require('./lib/gsd2-import.cjs');
           gsd2Import.cmdFromGsd2(args.slice(1), cwd, raw);
@@ -2042,6 +2877,11 @@ const HOST_COMMAND_ROUTERS = {
   'config-set': routeConfigSet,
   'config-set-model-profile': routeConfigSetModelProfile,
   'config-get': routeConfigGet,
+  // Phase-effort estimation (#2630, ADR-2629). A PAIR of verbs, so leaves
+  // rather than a family — ADR-2346 promotes to a family only at >=3.
+  'estimate-check': ({ args, cwd, raw }) => estimateCli.cmdEstimateCheck(cwd, args.slice(1), raw),
+  'estimate-calibration': ({ args, cwd, raw }) => estimateCli.cmdEstimateCalibration(cwd, args.slice(1), raw),
+  'estimate-calibrate': ({ args, cwd, raw }) => estimateCli.cmdEstimateCalibrate(cwd, args.slice(1), raw),
   'config-new-project': routeConfigNewProject,
   'config-path': routeConfigPath,
   'migrate-config': routeMigrateConfig,
@@ -2071,6 +2911,8 @@ const HOST_COMMAND_ROUTERS = {
     'quick-tasks-append': routeQuickTasksAppend,
     'normalize-test-command': routeNormalizeTestCommand,
     'dispatch-should-flatten': routeDispatchShouldFlatten,
+    'dispatch-isolation': routeDispatchIsolation,
+    'resolve-dispatch-type': routeResolveDispatchType,
     'agent-skills': routeAgentSkills,
     'skill-manifest': routeSkillManifest,
     'history-digest': routeHistoryDigest,
@@ -2095,8 +2937,10 @@ const HOST_COMMAND_ROUTERS = {
     'learnings': routeLearnings,
     'teams-status': routeTeamsStatus,
     'detect-custom-files': routeDetectCustomFiles,
+    'restore-custom-files': routeRestoreCustomFiles,
     'from-gsd2': routeFromGsd2,
     'prompt-budget': routePromptBudget,
+    'review-lane': routeReviewLane,
     'update-context': routeUpdateContext,
     'classify-confidence': routeClassifyConfidence,
     'package-legitimacy': routePackageLegitimacy,
@@ -2418,7 +3262,7 @@ async function main() {
     'from-gsd2, frontmatter, gap-analysis, generate-claude-md, generate-claude-profile, ' +
     'generate-dev-preferences, generate-slug, graphify, history-digest, init, intel, ' +
     'capability, classify-confidence, git, learnings, list-seeds, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, profile-questionnaire, ' +
-    'profile-sample, progress, project-instruction-file, prompt-budget, quick-tasks-append, requirements, research-plan, research-store, resolve-granularity, resolve-model, roadmap, scaffold, smart-entry, state, ' +
+    'profile-sample, progress, project-instruction-file, prompt-budget, quick-tasks-append, requirements, research-plan, research-store, resolve-granularity, resolve-model, restore-custom-files, roadmap, scaffold, smart-entry, state, ' +
     'task, template, user-story, validate, verify, verify-path-exists, verify-summary, eval, workstream, worktree\n\n' +
     'Global flags:\n' +
     '  --raw              Emit raw output without post-processing\n' +
@@ -2466,6 +3310,9 @@ async function main() {
   const SKIP_ROOT_RESOLUTION = new Set([
     'generate-slug', 'current-timestamp', 'verify-path-exists',
     'verify-summary', 'template', 'frontmatter', 'detect-custom-files',
+    // #1854: restore-custom-files operates on a runtime config dir passed
+    // explicitly via --config-dir; it never reads .planning/.
+    'restore-custom-files',
     'worktree', 'prompt-budget',
     'research-store', 'research-plan', 'package-legitimacy', 'classify-confidence',
     'user-story', // pure string validation — no .planning/ access needed