@opengsd/gsd-core 1.7.0 → 1.9.0

package/gsd-core/bin/lib/worktree-safety.cjs

@@ -19,6 +19,8 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
 // providing a deterministic failure path when git stalls (locked index, hung
 // remote, stalled NFS mount, etc.).  Callers can override via deps.timeout.
 const DEFAULT_GIT_TIMEOUT_MS = 10000;
+const WORKTREE_AGENT_BRANCH_RE = /^(worktree-)?agent-[A-Za-z0-9._/-]+$/;
+const WORKTREE_AGENT_BRANCH_PATTERN = WORKTREE_AGENT_BRANCH_RE.source;
 /**
  * Execute a git command via the shell-projection seam, with a derived
  * `timedOut` field. Tests inject mocks via deps.execGit using the new
@@ -302,7 +304,7 @@ function normalizeCleanupManifestEntry(entry) {
     const expectedBase = typeof e.expected_base === 'string' ? e.expected_base : '';
     if (!worktreePath || !branch || !expectedBase)
         return null;
-    if (!/^worktree-agent-[A-Za-z0-9._/-]+$/.test(branch))
+    if (!WORKTREE_AGENT_BRANCH_RE.test(branch))
         return null;
     const rawAllowedBases = Array.isArray(e.allowed_bases) ? e.allowed_bases : [];
     const allowedBases = Array.from(new Set([expectedBase, ...rawAllowedBases.filter((base) => typeof base === 'string' && base.length > 0)]));
@@ -449,20 +451,18 @@ function rescueSummaryArtifacts(worktreePath, repoRoot, deps) {
         // the executor's content could be lost.  cat-file -e HEAD:<path> returns
         // exit 0 only when the object exists in the committed HEAD tree.
         //
-        // Fail-closed on timeout/fatal git errors: if we cannot determine whether
-        // the file is committed, do NOT rescue it (rescuing an actually-committed
-        // file would re-create the untracked collision; the merge will surface the
-        // issue).  The cleanup will be blocked by merge_failed in the worst case,
-        // which is the observable behaviour before this fix and is recoverable.
+        // #2556: rescue whenever the object is NOT confirmed committed (any non-zero
+        // exit). `git cat-file -e` returns 128 — NOT 1 — for an absent path (the
+        // normal uncommitted-SUMMARY state), so the previous `!== 1` check never
+        // rescued and the untracked file was silently discarded by `worktree remove
+        // --force`. Data safety wins: an un-rescued untracked SUMMARY is lost, while
+        // a spurious rescue is usually a no-op — the destination check below skips the
+        // copy when the main tree already holds identical content (which is also what
+        // guards the #706 merge collision). A divergent dest is overwritten, but only
+        // uncommitted main-tree content could be lost (committed content is git-recoverable).
         const catFileResult = execGit(['-C', worktreePath, 'cat-file', '-e', `HEAD:${relPath}`], { cwd: repoRoot });
-        if (catFileResult.exitCode !== 1) {
-            // Rescue only when cat-file definitively reports the object is absent (exit 1).
-            //   exit 0  → object exists (committed on HEAD) — merge will carry it, skip.
-            //   exit 128 → fatal git error (corrupt store, unborn HEAD, etc.) — uncertain,
-            //              fail-closed: do NOT rescue to avoid recreating the #706 collision.
-            //   timedOut / null / other → unreliable result — same fail-closed policy.
-            // In all non-1 cases the merge will either succeed naturally (0) or surface
-            // the problem safely (128/timeout), which is the recoverable pre-fix behaviour.
+        if (catFileResult.exitCode === 0) {
+            // exit 0 → the SUMMARY is committed on HEAD; the merge will carry it, so skip rescue.
             continue;
         }
         const dest = node_path_1.default.join(repoRoot, relPath);
@@ -751,7 +751,7 @@ function planWorktreeRecordAgent(manifestRaw, fields) {
         return {
             ok: false,
             reason: 'invalid_entry',
-            hint: `Entry failed cleanup-manifest validation: --path/--branch/--base must be non-empty and --branch must match ^worktree-agent-[A-Za-z0-9._/-]+$ (got branch="${branch}"). Fix the field and re-run.`,
+            hint: `Entry failed cleanup-manifest validation: --path/--branch/--base must be non-empty and --branch must match ${WORKTREE_AGENT_BRANCH_PATTERN} (accepts both agent-<id> and worktree-agent-<id> namespaces; got branch="${branch}"). Fix the field and re-run.`,
             entry: null,
             manifest: null,
         };
@@ -893,6 +893,348 @@ function cmdWorktreeRecordAgent(cwd, args = [], deps = {}) {
     write(`${JSON.stringify({ ok: true, reason: 'ok', entry: plan.entry, manifest_path: resolved }, null, 2)}\n`);
     return { ok: true, reason: 'ok', entry: plan.entry, manifest_path: resolved };
 }
+/**
+ * Pure planner for `worktree create`. Validates the four required fields
+ * (write-strict, same missing-field-hint style as `planWorktreeRecordAgent`),
+ * then runs the candidate entry through the SAME `normalizeCleanupManifestEntry`
+ * validation the cleanup-wave reader and record-agent use — so a worktree this
+ * verb creates is guaranteed manageable by cleanup-wave/reap-orphans, and an
+ * entry that would fail the reader's branch-namespace guard is rejected here,
+ * fail-closed, before any git command runs.
+ */
+function planWorktreeCreate(fields) {
+    const agentId = (fields.agentId || '').trim();
+    const worktreePath = (fields.worktreePath || '').trim();
+    const branch = (fields.branch || '').trim();
+    const base = (fields.base || '').trim();
+    const missing = [];
+    if (!agentId)
+        missing.push('--agent-id');
+    if (!worktreePath)
+        missing.push('--path');
+    if (!branch)
+        missing.push('--branch');
+    if (!base)
+        missing.push('--base');
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            reason: 'missing_field',
+            hint: `worktree create requires ${missing.join(', ')}. Re-run with all of --agent-id, --path, --branch, --base set to non-empty (non-whitespace) values.`,
+            entry: null,
+        };
+    }
+    const candidate = {
+        agent_id: agentId,
+        worktree_path: worktreePath,
+        branch,
+        expected_base: base,
+    };
+    const entry = normalizeCleanupManifestEntry(candidate);
+    if (!entry) {
+        return {
+            ok: false,
+            reason: 'invalid_entry',
+            hint: `Entry failed cleanup-manifest validation: --path/--branch/--base must be non-empty and --branch must match ${WORKTREE_AGENT_BRANCH_PATTERN} (accepts both agent-<id> and worktree-agent-<id> namespaces; got branch="${branch}"). Fix the field and re-run.`,
+            entry: null,
+        };
+    }
+    // #2584 FIX 4 — git argument-injection guard: a value starting with '-'
+    // could be parsed by git as a FLAG rather than a positional argument (e.g.
+    // base="--upload-pack=x", path="-f"). `git worktree add` / `git rev-parse`
+    // support for a `--` end-of-options separator is inconsistent across git
+    // versions, so rejecting a leading dash outright — not relying on `--` — is
+    // the portable fix.
+    if (branch.startsWith('-') || base.startsWith('-') || worktreePath.startsWith('-')) {
+        return {
+            ok: false,
+            reason: 'unsafe_leading_dash',
+            hint: `--branch/--base/--path must not start with "-" (a leading dash would be parsed by git as a flag, not a value). Got branch="${branch}" base="${base}" path="${worktreePath}".`,
+            entry: null,
+        };
+    }
+    // #2584 FIX 4 — path-traversal guard: reject a ".." path segment in --path.
+    // Absolute paths ARE allowed (the orchestrator legitimately uses them —
+    // Phase-3 root confinement is out of Phase-2 scope); only a literal ".."
+    // component is rejected. Split on BOTH separators so the guard is effective
+    // on a Windows-style path too.
+    if (worktreePath.split(/[/\\]/).includes('..')) {
+        return {
+            ok: false,
+            reason: 'unsafe_path_traversal',
+            hint: `--path must not contain a ".." path segment (got: "${worktreePath}").`,
+            entry: null,
+        };
+    }
+    return { ok: true, reason: 'ok', entry };
+}
+/**
+ * Best-effort bounded rollback of a partial/orphaned worktree (#2584 FIX 3,
+ * scope narrowed by FIX 5). Invoked ONLY when a `git worktree add` TIMED OUT
+ * mid-operation — a SIGTERM'd `add` can leave a `.git/worktrees/<name>` admin
+ * entry / directory on disk that got past validation into the file checkout,
+ * so the partial is genuinely THIS call's own creation and is safe to
+ * best-effort remove immediately. It is deliberately NOT invoked on a clean
+ * non-zero `add` exit (see FIX 5) — the most common such failure is a
+ * COLLISION (the path/branch is already a registered worktree), git fails
+ * FAST there having created nothing, and the branch namespace this verb
+ * writes into (`worktree-agent-*`/`agent-*`) is exactly the concurrent-
+ * executor namespace, so a colliding path is very plausibly a LIVE PEER
+ * executor whose uncommitted work `--force` would destroy. Also invoked from
+ * `cmdWorktreeCreate` when a successful `add` is followed by a manifest-write
+ * failure (#2584 FIX 1) — that path proves THIS call created the worktree, so
+ * removing it is safe. This is immediate best-effort hygiene, not the only
+ * safety net: `reapOrphanWorktrees` scans the `.git/worktrees/` admin
+ * directory directly (a genuine directory-scan backstop, not manifest-only),
+ * so any partial this call cannot reach is still eventually discovered and
+ * reaped there. The result is intentionally ignored and a throw is
+ * swallowed: this is best-effort cleanup, never a new source of truth, and
+ * must never mask or block the caller's own degraded-but-honest return.
+ */
+function rollbackPartialWorktree(execGit, worktreePath, repoRoot) {
+    try {
+        execGit(['worktree', 'remove', '--force', worktreePath], { cwd: repoRoot });
+    }
+    catch {
+        // best-effort only — a throwing rollback must never mask the original failure.
+    }
+}
+/**
+ * Execute a `planWorktreeCreate` plan via bounded git. Fail-closed at every
+ * step — a timeout or a non-zero exit degrades to a structured result rather
+ * than throwing, and the base must resolve BEFORE any worktree is created (no
+ * partial/orphaned worktree on a bad base). Returns `cwd` — the working
+ * directory Phase 3's executor spawn will pass through.
+ */
+function executeWorktreeCreatePlan(plan, repoRoot, deps = {}) {
+    const execGit = deps.execGit || execGitDefault;
+    if (!plan || !plan.ok || !plan.entry) {
+        return {
+            ok: false,
+            reason: plan ? plan.reason : 'missing_plan',
+        };
+    }
+    const { worktree_path: worktreePath, branch, expected_base: base } = plan.entry;
+    const normalizedPath = (0, shell_command_projection_cjs_1.posixNormalize)(worktreePath);
+    // 1. Verify the base resolves BEFORE creating anything (fail-closed). Nothing
+    //    has been created on this path yet, so there is nothing to roll back.
+    const baseCheck = execGit(['rev-parse', '--verify', '--quiet', `${base}^{commit}`], { cwd: repoRoot });
+    if (baseCheck.timedOut) {
+        return { ok: false, reason: 'git_timeout', worktree_path: normalizedPath, branch, base };
+    }
+    if (!gitResultOk(baseCheck)) {
+        return { ok: false, reason: 'base_unresolved', worktree_path: normalizedPath, branch, base, stderr: baseCheck.stderr || '' };
+    }
+    // 2. Create the worktree + branch together.
+    const addResult = execGit(['worktree', 'add', '-b', branch, worktreePath, base], { cwd: repoRoot });
+    if (addResult.timedOut) {
+        // #2584 FIX 3: a SIGTERM'd `add` can leave a partial worktree on disk.
+        rollbackPartialWorktree(execGit, worktreePath, repoRoot);
+        return { ok: false, reason: 'git_timeout', worktree_path: normalizedPath, branch, base };
+    }
+    if (addResult.exitCode !== 0) {
+        // #2584 FIX 5: deliberately NO rollback here. A clean non-zero exit is
+        // most commonly a COLLISION (path/branch already a registered worktree),
+        // and git fails FAST on that — it creates nothing. A colliding path in
+        // this branch namespace is very plausibly a LIVE PEER executor;
+        // `git worktree remove --force` on it would destroy real, uncommitted
+        // work. The safe response to a clean failure is to fail loudly and leave
+        // whatever is already on disk untouched.
+        return { ok: false, reason: 'worktree_add_failed', worktree_path: normalizedPath, branch, base, stderr: addResult.stderr || '' };
+    }
+    return {
+        ok: true,
+        reason: 'created',
+        worktree_path: normalizedPath,
+        branch,
+        base,
+        cwd: normalizedPath,
+    };
+}
+/**
+ * CLI command: create a git worktree + branch off `--base`, then append the
+ * validated manifest entry so the worktree is immediately manageable by
+ * `worktree cleanup-wave` / `worktree reap-orphans`.
+ *
+ * Usage: worktree create --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha>
+ *
+ * #2584 FIX 1 — ORDERING CONTRACT: every manifest read/parse/shape-validate/
+ * plan step runs BEFORE the git side effect (step 5). The ONLY manifest
+ * operation that can run AFTER `git worktree add` has succeeded is the final
+ * guarded write (step 6), and a failure there triggers a best-effort rollback
+ * of the just-created worktree — so a malformed/mis-shaped manifest, or a
+ * `writeFile` IO error, can never leave a REAL worktree on disk with no
+ * manifest entry (cleanup-wave/reap-orphans only discover worktrees via the
+ * manifest, never a directory scan) or an uncaught throw.
+ */
+function cmdWorktreeCreate(cwd, args = [], deps = {}) {
+    const flag = (name) => {
+        const i = args.indexOf(name);
+        return i >= 0 && i + 1 < args.length ? args[i + 1] : '';
+    };
+    const write = deps.write || ((s) => process.stdout.write(s));
+    const writeErr = deps.writeErr || ((s) => process.stderr.write(s));
+    const manifestPath = flag('--manifest');
+    if (!manifestPath) {
+        writeErr('Usage: worktree create --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> [--root <dir>]\n');
+        process.exitCode = 2;
+        return { ok: false, reason: 'usage' };
+    }
+    // 1. Read the manifest (no side effect yet).
+    const resolved = node_path_1.default.resolve(cwd, manifestPath);
+    const readFile = deps.readFile || ((p) => node_fs_1.default.readFileSync(p, 'utf8'));
+    let manifestRaw;
+    try {
+        manifestRaw = readFile(resolved);
+    }
+    catch (err) {
+        const hint = `Manifest not found or unreadable at ${manifestPath}. The orchestrator must initialize it ({"orchestrator_root": "...", "worktrees": []}) before creating agent worktrees.`;
+        writeErr(`[gsd] worktree.create: manifest_read_failed — ${hint}\n`);
+        write(`${JSON.stringify({ ok: false, reason: 'manifest_read_failed', hint, error: err.message }, null, 2)}\n`);
+        process.exitCode = 1;
+        return { ok: false, reason: 'manifest_read_failed', hint };
+    }
+    // 2. Parse + shape-validate the manifest BEFORE any git command runs.
+    //    Mirrors planWorktreeRecordAgent's shell-acceptance rules (canonical
+    //    {worktrees:[]} object OR a bare top-level array).
+    let parsed;
+    try {
+        parsed = JSON.parse(manifestRaw);
+    }
+    catch {
+        const hint = 'Manifest is not valid JSON. The orchestrator must initialize it as {"orchestrator_root": "...", "worktrees": []} before creating agent worktrees.';
+        writeErr(`[gsd] worktree.create: invalid_manifest_json — ${hint}\n`);
+        write(`${JSON.stringify({ ok: false, reason: 'invalid_manifest_json', hint }, null, 2)}\n`);
+        process.exitCode = 1;
+        return { ok: false, reason: 'invalid_manifest_json', hint };
+    }
+    let worktrees;
+    let writeBack;
+    if (Array.isArray(parsed)) {
+        worktrees = parsed;
+        writeBack = worktrees;
+    }
+    else if (parsed && typeof parsed === 'object') {
+        const container = parsed;
+        if (container.worktrees === undefined)
+            container.worktrees = [];
+        if (!Array.isArray(container.worktrees)) {
+            const hint = 'Manifest "worktrees" must be an array. Re-initialize as {"orchestrator_root": "...", "worktrees": []}.';
+            writeErr(`[gsd] worktree.create: manifest_shape_invalid — ${hint}\n`);
+            write(`${JSON.stringify({ ok: false, reason: 'manifest_shape_invalid', hint }, null, 2)}\n`);
+            process.exitCode = 1;
+            return { ok: false, reason: 'manifest_shape_invalid', hint };
+        }
+        worktrees = container.worktrees;
+        writeBack = container;
+    }
+    else {
+        const hint = 'Manifest must be a JSON object {"worktrees": []} or a top-level array.';
+        writeErr(`[gsd] worktree.create: manifest_shape_invalid — ${hint}\n`);
+        write(`${JSON.stringify({ ok: false, reason: 'manifest_shape_invalid', hint }, null, 2)}\n`);
+        process.exitCode = 1;
+        return { ok: false, reason: 'manifest_shape_invalid', hint };
+    }
+    // 3. Plan (pure, no I/O) — still before any git command.
+    const plan = planWorktreeCreate({
+        agentId: flag('--agent-id'),
+        worktreePath: flag('--path'),
+        branch: flag('--branch'),
+        base: flag('--base'),
+    });
+    if (!plan.ok || !plan.entry) {
+        writeErr(`[gsd] worktree.create: ${plan.reason} — ${plan.hint || ''}\n`);
+        write(`${JSON.stringify({ ok: false, reason: plan.reason, hint: plan.hint }, null, 2)}\n`);
+        process.exitCode = 1;
+        return { ok: false, reason: plan.reason, hint: plan.hint };
+    }
+    // 3b. Optional root confinement (#2627, Phase 3 — the confinement Phase 2
+    //     deferred here from planWorktreeCreate's path-traversal guard).
+    //     planWorktreeCreate rejects a literal ".." SEGMENT, but a plain absolute
+    //     path outside the project contains no ".." and passes. Phase 3 makes the
+    //     orchestrator SPAWN executor processes into these paths, so an
+    //     unconfined --path is a write primitive aimed anywhere on the filesystem.
+    //
+    //     The root is DECLARED by the caller (`--root`) rather than inferred: agent
+    //     worktrees legitimately live outside the orchestrator's own root (a lane
+    //     orchestrator creates siblings under the repo's .claude/worktrees/), so
+    //     there is no layout this module could derive without guessing. Absent
+    //     `--root` the behavior is exactly as shipped in Phase 2 — the
+    //     orchestrator-worktree scheduler path always passes it.
+    //
+    //     Lexical by design: the worktree does not exist yet, so there is nothing
+    //     to realpath, and resolving only the root would not close a symlinked-leaf
+    //     hole. Pairs with the leading-dash and ".."-segment guards above.
+    const rootFlag = flag('--root');
+    if (rootFlag) {
+        const absRoot = node_path_1.default.resolve(cwd, rootFlag);
+        const absWorktree = node_path_1.default.resolve(cwd, plan.entry.worktree_path);
+        const rel = node_path_1.default.relative(absRoot, absWorktree);
+        // rel === ''           → the worktree IS the root (would clobber the checkout)
+        // rel === '..' / '../…' → escapes the root
+        // path.isAbsolute(rel) → a different Windows drive or UNC root
+        if (rel === '' || rel === '..' || rel.startsWith(`..${node_path_1.default.sep}`) || node_path_1.default.isAbsolute(rel)) {
+            const hint = `--path must resolve INSIDE --root (root="${absRoot}", path="${absWorktree}"). A worktree outside the declared root is unreachable by manifest-scoped cleanup and would let a spawned executor write outside the project.`;
+            writeErr(`[gsd] worktree.create: path_outside_root — ${hint}\n`);
+            write(`${JSON.stringify({ ok: false, reason: 'path_outside_root', hint }, null, 2)}\n`);
+            process.exitCode = 1;
+            return { ok: false, reason: 'path_outside_root', hint };
+        }
+    }
+    // 4. Compute the deduped final manifest STRING in memory now — the ONLY
+    //    manifest work left is the guarded write in step 6, after git succeeds.
+    //    #2584 FIX 2: the on-disk entry is the SAME minimal 4-field shape
+    //    `cmdWorktreeRecordAgent` writes — never the full normalized entry with
+    //    the derived `allowed_bases` — so the two verbs never write divergent
+    //    shapes into the same manifest (the reader re-derives `allowed_bases`
+    //    from `expected_base` on load, exactly as it does for record-agent).
+    const recorded = {
+        agent_id: plan.entry.agent_id,
+        worktree_path: plan.entry.worktree_path,
+        branch: plan.entry.branch,
+        expected_base: plan.entry.expected_base,
+    };
+    const dedupeKey = `${recorded.worktree_path}\0${recorded.branch}`;
+    const alreadyPresent = worktrees.some((existing) => {
+        const normalized = normalizeCleanupManifestEntry(existing);
+        return normalized !== null && `${normalized.worktree_path}\0${normalized.branch}` === dedupeKey;
+    });
+    if (!alreadyPresent) {
+        worktrees.push(recorded);
+    }
+    const manifestToWrite = `${JSON.stringify(writeBack, null, 2)}\n`;
+    // 5. NOW run the git side effect. Every manifest problem above is caught
+    //    before this point, so a malformed/mis-shaped manifest can never leave
+    //    an unmanifested worktree on disk. `executeWorktreeCreatePlan` itself
+    //    best-effort rolls back a partial worktree on its own add-timeout /
+    //    add-failed paths (#2584 FIX 3).
+    const result = executeWorktreeCreatePlan(plan, cwd, deps);
+    if (!result.ok) {
+        writeErr(`[gsd] worktree.create: ${result.reason} — ${result.stderr || ''}\n`);
+        write(`${JSON.stringify({ ok: false, reason: result.reason, stderr: result.stderr }, null, 2)}\n`);
+        process.exitCode = 1;
+        return { ok: false, reason: result.reason, stderr: result.stderr };
+    }
+    // 6. Write the pre-computed manifest string, guarded. A write failure here
+    //    means a REAL worktree now exists with NO manifest entry — roll it back
+    //    (best-effort) rather than leaving an orphan cleanup-wave/reap-orphans
+    //    can never reach (#2584 FIX 1). Never throws past this function.
+    const writeFile = deps.writeFile || ((p, content) => node_fs_1.default.writeFileSync(p, content, 'utf8'));
+    try {
+        writeFile(resolved, manifestToWrite);
+    }
+    catch (err) {
+        const execGit = deps.execGit || execGitDefault;
+        rollbackPartialWorktree(execGit, plan.entry.worktree_path, cwd);
+        const hint = `The worktree was created but the manifest write failed (${err.message}); rolled back the worktree via a best-effort 'git worktree remove --force'.`;
+        writeErr(`[gsd] worktree.create: manifest_write_failed — ${hint}\n`);
+        write(`${JSON.stringify({ ok: false, reason: 'manifest_write_failed', hint, error: err.message }, null, 2)}\n`);
+        process.exitCode = 1;
+        return { ok: false, reason: 'manifest_write_failed', hint };
+    }
+    write(`${JSON.stringify({ ok: true, reason: 'created', entry: recorded, cwd: result.cwd, manifest_path: resolved }, null, 2)}\n`);
+    return { ok: true, reason: 'created', entry: recorded, cwd: result.cwd, manifest_path: resolved };
+}
 /**
  * Reap orphaned linked worktrees whose lock owner process is dead, whose
  * branch tip is fully merged into the default branch, and whose lock file
@@ -1180,6 +1522,9 @@ module.exports = {
     cmdWorktreeCleanupWave,
     planWorktreeRecordAgent,
     cmdWorktreeRecordAgent,
+    planWorktreeCreate,
+    executeWorktreeCreatePlan,
+    cmdWorktreeCreate,
     reapOrphanWorktrees,
     cmdWorktreeReapOrphans,
     resolveWorktreeRoot,

package/gsd-core/bin/shared/config-defaults.manifest.json

@@ -33,6 +33,7 @@
     "_auto_chain_active": false,
     "node_repair": true,
     "node_repair_budget": 2,
+    "smart_zone_tokens": 100000,
     "ui_phase": true,
     "ui_safety_gate": true,
     "text_mode": false,

package/gsd-core/bin/shared/config-schema.manifest.json

@@ -19,6 +19,7 @@
     "workflow.auto_advance",
     "workflow.node_repair",
     "workflow.node_repair_budget",
+    "workflow.smart_zone_tokens",
     "workflow.human_verify_mode",
     "workflow.text_mode",
     "workflow.research_before_questions",
@@ -48,9 +49,6 @@
     "planning.commit_docs",
     "planning.search_gitignored",
     "planning.sub_repos",
-    "review.ollama_host",
-    "review.lm_studio_host",
-    "review.llama_cpp_host",
     "review.default_reviewers",
     "review.max_prompt_tokens",
     "review.max_prompt_tokens_per_reviewer",
@@ -72,6 +70,7 @@
     "statusline.show_last_command",
     "statusline.context_position",
     "statusline.show_context_tokens",
+    "statusline.state_format",
     "statusline.show_git",
     "workflow.max_discuss_passes",
     "features.thinking_partner",
@@ -116,11 +115,6 @@
       "source": "^agent_skills\\.[a-zA-Z0-9_-]+$",
       "description": "agent_skills.<agent-type>"
     },
-    {
-      "topLevel": "review",
-      "source": "^review\\.models\\.[a-zA-Z0-9_-]+$",
-      "description": "review.models.<cli-name>"
-    },
     {
       "topLevel": "features",
       "source": "^features\\.[a-zA-Z0-9_]+$",
@@ -148,8 +142,8 @@
     },
     {
       "topLevel": "dynamic_routing",
-      "source": "^dynamic_routing\\.(enabled|escalate_on_failure|max_escalations|tier_models\\.(light|standard|heavy))$",
-      "description": "dynamic_routing.<enabled|escalate_on_failure|max_escalations|tier_models.<light|standard|heavy>>"
+      "source": "^dynamic_routing\\.(enabled|escalate_on_failure|max_escalations|provider_escalation|tier_models\\.(light|standard|heavy))$",
+      "description": "dynamic_routing.<enabled|escalate_on_failure|max_escalations|provider_escalation|tier_models.<light|standard|heavy>>"
     },
     {
       "topLevel": "model_overrides",
@@ -176,11 +170,6 @@
       "source": "^fast_mode\\.agent_overrides\\.[a-zA-Z0-9_-]+$",
       "description": "fast_mode.agent_overrides.<agent-id>"
     },
-    {
-      "topLevel": "review",
-      "source": "^review\\.max_prompt_tokens_per_reviewer\\.[a-zA-Z0-9_-]+$",
-      "description": "review.max_prompt_tokens_per_reviewer.<reviewer-slug>"
-    },
     {
       "topLevel": "review",
       "source": "^review\\.reviewer_instances\\.[a-zA-Z0-9_-]+\\.(cli|model|agent)$",

package/gsd-core/bin/shared/model-catalog.json

@@ -52,6 +52,11 @@
       "sonnet": null,
       "haiku": null
     },
+    "kimi-code": {
+      "opus": null,
+      "sonnet": null,
+      "haiku": null
+    },
     "cursor": {
       "opus": null,
       "sonnet": null,

package/gsd-core/bin/shared/runtime-aliases.manifest.json

@@ -63,6 +63,11 @@
   "kimi": [
     "kimi"
   ],
+  "kimi-code": [
+    "kimi-code",
+    "kimicode",
+    "kimi_code"
+  ],
   "codebuddy": [
     "codebuddy",
     "codebuddy-cli"

package/gsd-core/references/api-coverage.md

@@ -24,13 +24,26 @@ treated as an external-API integration when **either**:
 1. a `COVERAGE.md` matrix is present in the phase directory (the planner produced
    one at `plan:pre`), **or**
 2. the phase scope shows a strong external-API-integration signal (an integration
-   verb co-occurring with an external-API noun, or an explicit `<Service>
-   API|SDK|REST|GraphQL` surface) and no matrix yet exists.
-
-Non-API phases (refactors, bug fixes, internal-only work, features that merely
-*mention* an existing internal API) do **not** fire the gate — the trigger
-requires a compound signal, so a bare word like "api" in "the public API of
-UserController" is intentionally ignored.
+   verb and an external-API noun **in the same clause**, or an explicit
+   `<Service> API|SDK|REST|GraphQL` surface naming a real service) and no matrix
+   yet exists.
+
+The detector is deliberately **fail-closed**: it leans toward firing, because a
+false positive is dismissed by a one-line `COVERAGE.md` "no external API
+integration" declaration, whereas a false *negative* silently lets a real
+external-API phase past this blocking gate — strictly worse. So it suppresses
+only prose that is unambiguously not external integration. A bare word like
+"api" in "the public API of UserController" is ignored (no integration verb +
+named service); the clause boundary is the whole relationship test, so an
+integration verb and an API noun in **different** clauses do not pair. Since
+#2365 the detector also excludes non-prose spans before matching: fenced code
+blocks, inline `` `code` `` spans, and path-shaped tokens (a first-party
+`src/app/api/profile/route.ts` route is a file path, not an external API, while
+an external host like `api.stripe.com/v1` still counts). In the
+`<Service> API` surface position it rejects capitalized sentence starters
+("The API"), locality/protocol descriptors ("Internal API", "REST API"),
+compound modifiers ("Resolver-only API"), and first-party-qualified services
+("internal Payments API") — a real vendor name is none of these.
 
 ## The two touch points
 
@@ -70,6 +83,23 @@ must be non-empty and unique; every decision must be `INTEGRATE` or `OPT-OUT`;
 every `OPT-OUT` must have a reason. Violations block the seal with a precise
 error.
 
+### Declaring "no external API integration" (#2365)
+
+A phase that integrates no external API/SDK/service — but was still asked for a
+matrix (e.g. the detector over-fired, or a team wants the decision on record) —
+declares it instead of fabricating a row:
+
+```markdown
+No external API integration: UI-only phase, no third-party surface.
+```
+
+The reason is **required**, exactly like an `OPT-OUT` reason — the declaration
+is a reasoned decision, not a bypass. A `COVERAGE.md` containing both the
+declaration and coverage rows is contradictory and blocks the seal. When the
+detector still finds integration signals in the phase scope, the declaration
+wins (it is the human overrule for a fallible detector) but the gate output
+surfaces the overridden signals so the contradiction is visible, not silent.
+
 ## A second integration against the same need
 
 A second platform for an existing capability (e.g. adding YouTube alongside

package/gsd-core/references/checkpoints.md

@@ -474,7 +474,7 @@ npm run dev &
 DEV_SERVER_PID=$!
 
 # Wait for ready (max 30s) — uses fetch() for cross-platform compatibility
-timeout 30 bash -c 'until node -e "fetch(\"http://localhost:3000\").then(r=>{process.exit(r.ok?0:1)}).catch(()=>process.exit(1))" 2>/dev/null; do sleep 1; done'
+gsd_run run-with-timeout 30 -- bash -c 'until node -e "fetch(\"http://localhost:3000\").then(r=>{process.exit(r.ok?0:1)}).catch(()=>process.exit(1))" 2>/dev/null; do sleep 1; done'
 ```
 
 **Port conflicts:** Kill stale process (`lsof -ti:3000 | xargs kill`) or use alternate port (`--port 3001`).

package/gsd-core/references/common-bug-patterns.md

@@ -97,6 +97,19 @@ Checklist of frequent bug patterns to scan before forming hypotheses. Ordered by
 3. **Each checked pattern is a hypothesis candidate** — verify or eliminate with evidence
 4. **If no pattern matches**, proceed to open-ended investigation
 
+### Pattern categories → bug taxonomy (Phase 1.75)
+
+The categories here feed bug-class classification (see `debugger-bug-taxonomy.md`):
+
+| Pattern category | Typical bug_class |
+|---|---|
+| Null / Undefined, Off-by-One, State, Import, Type, Regex, Error Handling, Scope | Bohrbug (deterministic) |
+| Async / Timing (intermittent, leaked timer, init order) | Heisenbug / Concurrency |
+| Environment / Config (works-here-not-there) | Heisenbug / Mandelbug (or config-as-root-cause) |
+| Data Shape / API Contract | Bohrbug (or Mandelbug if volume-dependent) |
+
+The taxonomy routes the investigation technique (SBFL + bisect for Bohrbugs; record-replay/stability for Heisenbugs; atomicity/order/deadlock checklist for Concurrency).
+
 ### Symptom-to-Category Quick Map
 
 | Symptom | Check First |

package/gsd-core/references/context-budget.md

@@ -83,3 +83,43 @@ Either list works — `enabledMcpjsonServers` is an explicit allow-list, `disabl
 ### Composition with model_profile
 
 Trimming MCPs and tuning `model_profile` are independent levers that **compound**. Disabling a 25k-token MCP saves 25k per turn whether you're running `quality` (opus everywhere) or `budget` (sonnet/haiku); the savings are additive, not in lieu of model tuning. Don't pick one — do both, and audit MCPs first because the per-turn savings show up immediately and stack across every subagent the orchestrator spawns.
+
+---
+
+# Phase Sizing (gsd-planner)
+
+## Estimate Emission (#2631, ADR-2629)
+
+Every plan carries an `estimate` block. It is the quantitative reason a phase must be sliced — tracer-first says *slice thin*, the estimate says *how thin, for this codebase*.
+
+**Compute it:**
+1. Sum `estimateTokens`-scale cost across the plan: implementation + the files each task reads + verification output. Roughly chars/4 over what the executor will actually touch.
+2. Run `estimate-calibration` and **multiply your raw figure by its `factor`.** It is the measured estimate-vs-actual ratio for THIS project — a factor of 1 means there is not yet enough history to correct.
+3. `confidence` is **derived, not judged**: it is the `confidence` value from the same calibration query, keyed to the sample count (`low` <3, `med` 3–5, `high` ≥6). **Do not rate your own certainty.** Self-rated confidence was measured in this project and found weak (`references/honest-verifier.md:25-29`); every signal here routes on measured history instead.
+
+**Over budget?** The plan-checker flags a plan whose estimate exceeds `workflow.smart_zone_tokens`. This is advisory — it never blocks. When flagged, re-slice: a tracer plus expansion slices, each inside the budget. Prefer more, smaller plans over one that spends the agent's best early-context tokens and finishes degraded.
+
+## Context Budget Rules
+
+Plans should complete within ~50% context (not 80%). No context anxiety, quality maintained start to finish, room for unexpected complexity.
+
+**Each plan: 2-3 tasks maximum.**
+
+| Context Weight | Tasks/Plan | Context/Task | Total |
+|----------------|------------|--------------|-------|
+| Light (CRUD, config) | 3 | ~10-15% | ~30-45% |
+| Medium (auth, payments) | 2 | ~20-30% | ~40-50% |
+| Heavy (migrations, multi-subsystem) | 1-2 | ~30-40% | ~30-50% |
+
+## Split Signals
+
+**ALWAYS split if:**
+- More than 3 tasks
+- Multiple subsystems (DB + API + UI = separate plans)
+- Any task with >5 file modifications
+- Checkpoint + implementation in same plan
+- Discovery + implementation in same plan
+
+**CONSIDER splitting:** >5 files total, natural semantic boundaries, context cost estimate exceeds 40% for a single plan. See `<planner_authority_limits>` for prohibited split reasons.
+
+See @~/.claude/gsd-core/references/planner-guidance.md for Granularity Calibration table (Coarse/Standard/Fine plans-per-phase).