gsd-pi 2.78.1-dev.e9d88a536 → 2.78.1-dev.eccf86e27

package/dist/resources/extensions/gsd/db/unit-dispatches.js

@@ -0,0 +1,322 @@
+// gsd-2 + Unit dispatch ledger (DB-backed coordination, Phase B)
+//
+// Records every auto-mode unit dispatch (plan-slice, run-task, summarize, …)
+// with worker_id, fencing token, status lifecycle, and retry metadata. The
+// ledger is the substrate Phase C will consume to migrate stuck-state.json
+// and paused-session.json out of the runtime/ directory.
+//
+// Codex review MEDIUM B2: partial unique index
+//   idx_unit_dispatches_active_per_unit ON unit_dispatches(unit_id)
+//   WHERE status IN ('claimed','running')
+// enforces that two workers cannot simultaneously claim the same unit.
+// recordDispatchClaim relies on the index to fail fast at INSERT time
+// rather than racing in application code.
+import { randomUUID } from "node:crypto";
+import { _getAdapter, isDbAvailable, transaction, insertAuditEvent, } from "../gsd-db.js";
+function isAlreadyActiveConstraintError(err) {
+    const code = err && typeof err === "object" && "code" in err
+        ? String(err.code ?? "")
+        : "";
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/\bFOREIGN KEY\b/i.test(msg)) {
+        return false;
+    }
+    if (code === "SQLITE_CONSTRAINT" || code === "SQLITE_CONSTRAINT_UNIQUE") {
+        return true;
+    }
+    return /\bUNIQUE\b|\bconstraint failed\b/i.test(msg);
+}
+/**
+ * Insert a new dispatch row in `claimed` state. Atomic guard against
+ * double-claim (B2): the partial unique index
+ * idx_unit_dispatches_active_per_unit refuses the INSERT if any row for
+ * the same unit_id already has status IN ('claimed','running').
+ */
+export function recordDispatchClaim(input) {
+    if (!isDbAvailable()) {
+        throw new Error("recordDispatchClaim: DB unavailable");
+    }
+    const now = new Date().toISOString();
+    return transaction(() => {
+        const db = _getAdapter();
+        const lease = db.prepare(`SELECT fencing_token
+       FROM milestone_leases
+       WHERE milestone_id = :milestone_id
+         AND worker_id = :worker_id
+         AND fencing_token = :token
+         AND status = 'held'`).get({
+            ":milestone_id": input.milestoneId,
+            ":worker_id": input.workerId,
+            ":token": input.milestoneLeaseToken,
+        });
+        if (!lease) {
+            return {
+                ok: false,
+                error: "stale_lease",
+                milestoneId: input.milestoneId,
+                workerId: input.workerId,
+                milestoneLeaseToken: input.milestoneLeaseToken,
+            };
+        }
+        try {
+            const result = db.prepare(`INSERT INTO unit_dispatches (
+          trace_id, turn_id, worker_id, milestone_lease_token,
+          milestone_id, slice_id, task_id,
+          unit_type, unit_id, status, attempt_n,
+          started_at, max_attempts
+        ) VALUES (
+          :trace_id, :turn_id, :worker_id, :milestone_lease_token,
+          :milestone_id, :slice_id, :task_id,
+          :unit_type, :unit_id, 'claimed', :attempt_n,
+          :started_at, :max_attempts
+        )`).run({
+                ":trace_id": input.traceId,
+                ":turn_id": input.turnId ?? null,
+                ":worker_id": input.workerId,
+                ":milestone_lease_token": input.milestoneLeaseToken,
+                ":milestone_id": input.milestoneId,
+                ":slice_id": input.sliceId ?? null,
+                ":task_id": input.taskId ?? null,
+                ":unit_type": input.unitType,
+                ":unit_id": input.unitId,
+                ":attempt_n": input.attemptN ?? 1,
+                ":started_at": now,
+                ":max_attempts": input.maxAttempts ?? 3,
+            });
+            const id = Number(result.lastInsertRowid ?? 0);
+            insertAuditEvent({
+                eventId: randomUUID(),
+                traceId: input.traceId,
+                turnId: input.turnId ?? undefined,
+                category: "orchestration",
+                type: "dispatch-claimed",
+                ts: now,
+                payload: {
+                    dispatchId: id,
+                    unitId: input.unitId,
+                    unitType: input.unitType,
+                    workerId: input.workerId,
+                    attemptN: input.attemptN ?? 1,
+                },
+            });
+            return { ok: true, dispatchId: id };
+        }
+        catch (err) {
+            if (!isAlreadyActiveConstraintError(err))
+                throw err;
+            // Partial unique index rejected the INSERT — surface the existing
+            // active dispatch so callers can decide what to do.
+            const existing = db.prepare(`SELECT id, status, worker_id FROM unit_dispatches
+         WHERE unit_id = :unit_id AND status IN ('claimed','running')
+         ORDER BY id DESC LIMIT 1`).get({ ":unit_id": input.unitId });
+            return {
+                ok: false,
+                error: "already_active",
+                existingId: existing?.id ?? 0,
+                existingStatus: existing?.status ?? "claimed",
+                existingWorker: existing?.worker_id ?? "unknown",
+            };
+        }
+    });
+}
+/** Transition a `claimed` dispatch into `running`. */
+export function markRunning(dispatchId) {
+    if (!isDbAvailable())
+        return;
+    const db = _getAdapter();
+    db.prepare(`UPDATE unit_dispatches SET status = 'running'
+     WHERE id = :id AND status = 'claimed'`).run({ ":id": dispatchId });
+}
+/** Transition a dispatch into `completed`. */
+export function markCompleted(dispatchId, opts) {
+    if (!isDbAvailable())
+        return;
+    const now = new Date().toISOString();
+    const db = _getAdapter();
+    let changes = 0;
+    transaction(() => {
+        const result = db.prepare(`UPDATE unit_dispatches
+       SET status = 'completed', ended_at = :ended_at,
+           exit_reason = :exit_reason,
+           verification_evidence_id = :evidence_id
+       WHERE id = :id
+         AND status IN ('claimed','running')`).run({
+            ":id": dispatchId,
+            ":ended_at": now,
+            ":exit_reason": opts?.exitReason ?? null,
+            ":evidence_id": opts?.verificationEvidenceId ?? null,
+        });
+        changes =
+            typeof result.changes === "number"
+                ? result.changes
+                : 0;
+    });
+    if (changes < 1)
+        return;
+    insertAuditEvent({
+        eventId: randomUUID(),
+        traceId: dispatchId.toString(),
+        category: "orchestration",
+        type: "dispatch-completed",
+        ts: now,
+        payload: { dispatchId },
+    });
+}
+/** Transition a dispatch into `failed`, optionally scheduling a retry. */
+export function markFailed(dispatchId, opts) {
+    if (!isDbAvailable())
+        return;
+    const now = new Date();
+    const nowIso = now.toISOString();
+    const nextRunIso = opts.retryAfterMs
+        ? new Date(now.getTime() + opts.retryAfterMs).toISOString()
+        : null;
+    const db = _getAdapter();
+    let changes = 0;
+    transaction(() => {
+        const result = db.prepare(`UPDATE unit_dispatches
+       SET status = 'failed', ended_at = :ended_at,
+           error_summary = :error_summary,
+           last_error_code = :last_error_code,
+           last_error_at = :last_error_at,
+           retry_after_ms = :retry_after_ms,
+           next_run_at = :next_run_at
+       WHERE id = :id
+         AND status IN ('claimed','running')`).run({
+            ":id": dispatchId,
+            ":ended_at": nowIso,
+            ":error_summary": opts.errorSummary,
+            ":last_error_code": opts.errorCode ?? null,
+            ":last_error_at": nowIso,
+            ":retry_after_ms": opts.retryAfterMs ?? null,
+            ":next_run_at": nextRunIso,
+        });
+        changes =
+            typeof result.changes === "number"
+                ? result.changes
+                : 0;
+    });
+    if (changes < 1)
+        return;
+    insertAuditEvent({
+        eventId: randomUUID(),
+        traceId: dispatchId.toString(),
+        category: "orchestration",
+        type: "dispatch-failed",
+        ts: nowIso,
+        payload: { dispatchId, errorSummary: opts.errorSummary, retryAfterMs: opts.retryAfterMs ?? null },
+    });
+}
+/** Transition a dispatch into `stuck`. */
+export function markStuck(dispatchId, reason) {
+    if (!isDbAvailable())
+        return;
+    const now = new Date().toISOString();
+    const db = _getAdapter();
+    const result = transaction(() => {
+        return db.prepare(`UPDATE unit_dispatches
+       SET status = 'stuck', ended_at = :ended_at, exit_reason = :reason
+       WHERE id = :id
+         AND status IN ('claimed','running')`).run({ ":id": dispatchId, ":ended_at": now, ":reason": reason });
+    });
+    const changes = typeof result.changes === "number"
+        ? result.changes
+        : 0;
+    if (changes <= 0)
+        return;
+    insertAuditEvent({
+        eventId: randomUUID(),
+        traceId: dispatchId.toString(),
+        category: "orchestration",
+        type: "dispatch-stuck",
+        ts: now,
+        payload: { dispatchId, reason },
+    });
+}
+/** Transition a dispatch into `paused`. */
+export function markPaused(dispatchId) {
+    if (!isDbAvailable())
+        return;
+    const now = new Date().toISOString();
+    const db = _getAdapter();
+    db.prepare(`UPDATE unit_dispatches
+     SET status = 'paused', ended_at = :ended_at
+     WHERE id = :id AND status IN ('claimed','running')`).run({ ":id": dispatchId, ":ended_at": now });
+}
+/** Transition a dispatch into `canceled`. */
+export function markCanceled(dispatchId, reason) {
+    if (!isDbAvailable())
+        return;
+    const now = new Date().toISOString();
+    const db = _getAdapter();
+    db.prepare(`UPDATE unit_dispatches
+     SET status = 'canceled', ended_at = :ended_at, exit_reason = :reason
+     WHERE id = :id AND status IN ('pending','claimed','running')`).run({ ":id": dispatchId, ":ended_at": now, ":reason": reason });
+}
+/**
+ * Fetch the most recent N dispatches for a unit. Used by recordDispatchClaim
+ * callers to compute attempt_n and by detect-stuck.ts (B3) to consult
+ * retry budget before tripping the stuck verdict.
+ */
+export function getRecentForUnit(unitId, limit = 10) {
+    if (!isDbAvailable())
+        return [];
+    const db = _getAdapter();
+    return db.prepare(`SELECT * FROM unit_dispatches WHERE unit_id = :unit_id ORDER BY id DESC LIMIT :limit`).all({ ":unit_id": unitId, ":limit": limit });
+}
+/**
+ * Fetch the latest dispatch for a unit, regardless of status. Returns null
+ * if the unit has never been dispatched.
+ */
+export function getLatestForUnit(unitId) {
+    if (!isDbAvailable())
+        return null;
+    const db = _getAdapter();
+    const row = db.prepare(`SELECT * FROM unit_dispatches WHERE unit_id = :unit_id ORDER BY id DESC LIMIT 1`).get({ ":unit_id": unitId });
+    return row ?? null;
+}
+/**
+ * Phase C — return the most recent unit_id values for a worker, oldest-first.
+ *
+ * Drop-in replacement for the persistence side of stuck-state.json's
+ * `recentUnits` field. The auto-loop uses this to seed loopState.recentUnits
+ * on session start so the stuck-detector window survives a session restart
+ * (#3704). Returned in oldest-first order to match the in-memory window
+ * shape that detect-stuck.ts expects.
+ */
+export function getRecentUnitKeysForWorker(workerId, limit = 20) {
+    if (!isDbAvailable())
+        return [];
+    const db = _getAdapter();
+    const rows = db.prepare(`SELECT unit_id FROM unit_dispatches
+     WHERE worker_id = :worker_id
+     ORDER BY started_at DESC, id DESC
+     LIMIT :limit`).all({ ":worker_id": workerId, ":limit": limit });
+    // Reverse so callers consume oldest-first (sliding-window semantics).
+    return rows.reverse().map((r) => ({ key: r.unit_id }));
+}
+export function getRecentUnitKeysForProjectRoot(projectRootRealpath, limit = 20) {
+    if (!isDbAvailable())
+        return [];
+    const db = _getAdapter();
+    const rows = db.prepare(`SELECT ud.unit_id
+     FROM unit_dispatches ud
+     INNER JOIN workers w ON w.worker_id = ud.worker_id
+     WHERE w.project_root_realpath = :project_root_realpath
+     ORDER BY ud.started_at DESC, ud.id DESC
+     LIMIT :limit`).all({
+        ":project_root_realpath": projectRootRealpath,
+        ":limit": limit,
+    });
+    return rows.reverse().map((r) => ({ key: r.unit_id }));
+}
+/**
+ * Fetch dispatches for a milestone filtered by status. Useful for janitors
+ * + dashboards.
+ */
+export function getDispatchesByStatus(milestoneId, status) {
+    if (!isDbAvailable())
+        return [];
+    const db = _getAdapter();
+    return db.prepare(`SELECT * FROM unit_dispatches WHERE milestone_id = :mid AND status = :status ORDER BY id`).all({ ":mid": milestoneId, ":status": status });
+}

package/dist/resources/extensions/gsd/db-writer.js

@@ -7,7 +7,7 @@
 //
 // Critical invariant: generated markdown must round-trip through
 // parseDecisionsTable() and parseRequirementsSections() with field fidelity.
-import { resolve } from 'node:path';
+import { isAbsolute, relative, resolve } from 'node:path';
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import { resolveGsdRootFile } from './paths.js';
 import { saveFile } from './files.js';
@@ -16,6 +16,7 @@ import { logWarning, logError } from './workflow-logger.js';
 import { invalidateStateCache } from './state.js';
 import { clearPathCache } from './paths.js';
 import { clearParseCache } from './files.js';
+import { createWorkspace, scopeMilestone } from './workspace.js';
 // ─── Freeform Detection ───────────────────────────────────────────────────
 /**
  * Detect whether a DECISIONS.md file is in canonical table format
@@ -614,40 +615,102 @@ export async function updateRequirementInDb(id, updates, basePath) {
     }
 }
 /**
- * Save an artifact to DB and write the corresponding markdown file to disk.
+ * Save a root-level artifact (no milestone) to DB and write to disk,
+ * routing path construction through workspace.contract.projectGsd directly.
+ * Use this instead of saveArtifactToDbByScope when milestone_id is absent.
+ */
+export async function saveArtifactToDbForWorkspace(workspace, opts) {
+    try {
+        const db = await import('./gsd-db.js');
+        const gsdDir = workspace.contract.projectGsd;
+        const fullPath = resolve(gsdDir, opts.path);
+        const rel0 = relative(gsdDir, fullPath);
+        if (rel0.startsWith('..') || isAbsolute(rel0)) {
+            throw new GSDError(GSD_IO_ERROR, `saveArtifactToDbForWorkspace: path escapes .gsd/ directory: ${opts.path}`);
+        }
+        let contentToPersist = opts.content;
+        if (opts.artifact_type === 'REQUIREMENTS' && opts.path === 'REQUIREMENTS.md') {
+            const activeRequirements = db.getActiveRequirements();
+            if (activeRequirements.length === 0) {
+                throw new GSDError(GSD_STALE_STATE, 'saveArtifactToDbForWorkspace: REQUIREMENTS final save requires active DB-backed requirements');
+            }
+            contentToPersist = generateRequirementsMd(activeRequirements);
+        }
+        let skipDiskWrite = false;
+        if (!isRootCanonicalArtifact(opts) && existsSync(fullPath)) {
+            const existingSize = statSync(fullPath).size;
+            const newSize = Buffer.byteLength(contentToPersist, 'utf-8');
+            if (existingSize > 0 && newSize < existingSize * 0.5) {
+                logWarning('projection', `new content (${newSize}B) is <50% of existing projection (${existingSize}B), preserving disk file while DB remains authoritative`, { fn: 'saveArtifactToDbForWorkspace', path: opts.path });
+                skipDiskWrite = true;
+            }
+        }
+        db.insertArtifact({
+            path: opts.path,
+            artifact_type: opts.artifact_type,
+            milestone_id: null,
+            slice_id: null,
+            task_id: null,
+            full_content: contentToPersist,
+        });
+        if (!skipDiskWrite) {
+            try {
+                await saveFile(fullPath, contentToPersist);
+            }
+            catch (diskErr) {
+                logWarning('projection', 'artifact projection write failed; DB artifact remains committed', { fn: 'saveArtifactToDbForWorkspace', path: opts.path, error: String(diskErr.message) });
+            }
+        }
+        invalidateStateCache();
+        clearPathCache();
+        clearParseCache();
+    }
+    catch (err) {
+        logError('manifest', 'saveArtifactToDbForWorkspace failed', { fn: 'saveArtifactToDbForWorkspace', error: String(err.message) });
+        throw err;
+    }
+}
+/**
+ * Save an artifact to DB and write the corresponding markdown file to disk,
+ * routing all path construction through the workspace contract.
+ *
  * The path is relative to .gsd/ (e.g. "milestones/M001/slices/S06/tasks/T01-SUMMARY.md").
- * The full file path is computed as basePath + '.gsd/' + path.
+ * The full file path is computed as scope.workspace.contract.projectGsd + '/' + path.
  */
-export async function saveArtifactToDb(opts, basePath) {
+export async function saveArtifactToDbByScope(scope, opts) {
+    // Guard: an empty milestoneId produces malformed paths (milestoneDir = join(gsd, "milestones", "")).
+    // Callers that have no milestone should use saveArtifactToDbForWorkspace instead.
+    if (!scope.milestoneId) {
+        throw new GSDError(GSD_IO_ERROR, `saveArtifactToDbByScope: milestoneId is empty — use saveArtifactToDbForWorkspace for root artifacts`);
+    }
     try {
         const db = await import('./gsd-db.js');
+        // Use contract.projectGsd as the canonical .gsd directory — never a hand-rolled basePath join.
+        const gsdDir = scope.workspace.contract.projectGsd;
+        const fullPath = resolve(gsdDir, opts.path);
         // Guard against path traversal before any reads/writes
-        const gsdDir = resolve(basePath, '.gsd');
-        const fullPath = resolve(basePath, '.gsd', opts.path);
-        if (!fullPath.startsWith(gsdDir)) {
-            throw new GSDError(GSD_IO_ERROR, `saveArtifactToDb: path escapes .gsd/ directory: ${opts.path}`);
+        const rel1 = relative(gsdDir, fullPath);
+        if (rel1.startsWith('..') || isAbsolute(rel1)) {
+            throw new GSDError(GSD_IO_ERROR, `saveArtifactToDbByScope: path escapes .gsd/ directory: ${opts.path}`);
         }
         let contentToPersist = opts.content;
         if (opts.artifact_type === 'REQUIREMENTS' && opts.path === 'REQUIREMENTS.md') {
             const activeRequirements = db.getActiveRequirements();
             if (activeRequirements.length === 0) {
-                throw new GSDError(GSD_STALE_STATE, 'saveArtifactToDb: REQUIREMENTS final save requires active DB-backed requirements');
+                throw new GSDError(GSD_STALE_STATE, 'saveArtifactToDbByScope: REQUIREMENTS final save requires active DB-backed requirements');
             }
             contentToPersist = generateRequirementsMd(activeRequirements);
         }
         // Shrinkage guard: if the projection file already exists and the new
         // content is significantly smaller (<50%), preserve the richer file on
         // disk, but keep the DB row authoritative with the caller-provided content.
-        // The disk file is a stale projection until the next explicit render.
-        // Root canonical artifacts are exempt because their content is rendered
-        // from canonical DB state, and cleanup/consolidation is often intentionally
-        // much smaller than a malformed accumulated file.
+        // Root canonical artifacts are exempt (rendered from canonical DB state).
         let skipDiskWrite = false;
         if (!isRootCanonicalArtifact(opts) && existsSync(fullPath)) {
             const existingSize = statSync(fullPath).size;
             const newSize = Buffer.byteLength(contentToPersist, 'utf-8');
             if (existingSize > 0 && newSize < existingSize * 0.5) {
-                logWarning('projection', `new content (${newSize}B) is <50% of existing projection (${existingSize}B), preserving disk file while DB remains authoritative`, { fn: 'saveArtifactToDb', path: opts.path });
+                logWarning('projection', `new content (${newSize}B) is <50% of existing projection (${existingSize}B), preserving disk file while DB remains authoritative`, { fn: 'saveArtifactToDbByScope', path: opts.path });
                 skipDiskWrite = true;
             }
         }
@@ -665,7 +728,7 @@ export async function saveArtifactToDb(opts, basePath) {
                 await saveFile(fullPath, contentToPersist);
             }
             catch (diskErr) {
-                logWarning('projection', 'artifact projection write failed; DB artifact remains committed', { fn: 'saveArtifactToDb', path: opts.path, error: String(diskErr.message) });
+                logWarning('projection', 'artifact projection write failed; DB artifact remains committed', { fn: 'saveArtifactToDbByScope', path: opts.path, error: String(diskErr.message) });
             }
         }
         // Invalidate file-read caches so deriveState() sees the updated markdown.
@@ -675,7 +738,24 @@ export async function saveArtifactToDb(opts, basePath) {
         clearParseCache();
     }
     catch (err) {
-        logError('manifest', 'saveArtifactToDb failed', { fn: 'saveArtifactToDb', error: String(err.message) });
+        logError('manifest', 'saveArtifactToDbByScope failed', { fn: 'saveArtifactToDbByScope', error: String(err.message) });
         throw err;
     }
 }
+/**
+ * Save an artifact to DB and write the corresponding markdown file to disk.
+ * The path is relative to .gsd/ (e.g. "milestones/M001/slices/S06/tasks/T01-SUMMARY.md").
+ * The full file path is computed as basePath + '.gsd/' + path.
+ *
+ * @deprecated Use saveArtifactToDbByScope instead, which routes through the
+ * workspace contract for canonical path resolution.
+ * TODO(C-future): remove this legacy wrapper once all callers are migrated.
+ */
+export async function saveArtifactToDb(opts, basePath) {
+    const workspace = createWorkspace(basePath);
+    const milestoneId = opts.milestone_id;
+    if (milestoneId) {
+        return saveArtifactToDbByScope(scopeMilestone(workspace, milestoneId), opts);
+    }
+    return saveArtifactToDbForWorkspace(workspace, opts);
+}

package/dist/resources/extensions/gsd/delegation-policy.js

@@ -0,0 +1,155 @@
+// Delegation policy — codifies which GSD MCP tools are safe to run as
+// background sub-agents while the foreground /gsd flow continues. Verdicts
+// are derived from the round-1 and round-2 evaluations recorded in this
+// branch's PR description; the rationale field on each entry preserves
+// the reason so future changes have to revisit the analysis explicitly.
+//
+// Default-deny: unknown tools are never backgroundable.
+//
+// ─── Tool-name vs unit-type namespaces ───────────────────────────────────
+// Entries are keyed by canonical MCP tool name (`gsd_*`). The optional
+// `unitType` field is a *secondary* index for the dispatcher's convenience
+// — it bridges this policy to `auto-dispatch.ts`' `DispatchAction.unitType`
+// values. The two namespaces are not 1:1:
+//
+//   - Some tools have no corresponding unit type (e.g. `gsd_doctor`,
+//     `gsd_plan_task`) and intentionally omit `unitType`.
+//   - Some unit types share a tool — e.g. `execute-task`, `execute-task-simple`,
+//     and `reactive-execute` all invoke `gsd_execute`. The current shape
+//     allows only one `unitType` per entry, so those units fall through to
+//     `getVerdictByUnitType() === null` (→ `backgroundable: false`) even
+//     though `gsd_execute` itself is GOOD. This is the intended default-deny
+//     posture until a future PR wires actual background dispatch and
+//     decides whether each unit-level orchestration is safe — the unit
+//     wraps a prompt, harness setup, and post-processing on top of the
+//     tool, and the tool's safety doesn't transfer automatically.
+//
+// Auto-dispatch produces 20 distinct unit types; only 5 are explicitly
+// classified here. The other 15 default-deny:
+//   complete-milestone, complete-slice, discuss-milestone, discuss-project,
+//   discuss-requirements, execute-task, execute-task-simple, gate-evaluate,
+//   reactive-execute, refine-slice, research-decision, research-milestone,
+//   research-project, research-slice, rewrite-docs, run-uat
+//
+// Adding a `unitType` mapping (or a future `unitTypes: string[]`) to an
+// existing entry is the place to lift any of these out of default-deny
+// when the analysis has been done.
+const POLICY = {
+    gsd_plan_slice: {
+        toolName: "gsd_plan_slice",
+        unitType: "plan-slice",
+        verdict: "good",
+        rationale: "Self-contained, no user prompts, atomic DB tx; existing slice-parallel-orchestrator pattern transfers cleanly.",
+        constraints: [
+            "Lock the slice from further user discussion once dispatched (context is frozen at dispatch time).",
+            "Foreground must not derive state for that slice while the transaction is in flight.",
+            "Foreground must await background completion before any tool reads the planned tasks/gates.",
+        ],
+    },
+    gsd_execute: {
+        toolName: "gsd_execute",
+        // No `unitType` set on purpose — the underlying tool is safe, but the
+        // unit-level orchestrations that invoke it (`execute-task`,
+        // `execute-task-simple`, `reactive-execute`) wrap additional prompt and
+        // harness work whose safety is a separate analysis. Default-deny those
+        // units until that analysis is recorded; adding `unitType` here would
+        // promote them silently.
+        verdict: "good",
+        rationale: "No DB writes; UUID-isolated stdout/stderr/meta files; existing reactive-execute parallel-subagent precedent.",
+    },
+    gsd_validate_milestone: {
+        toolName: "gsd_validate_milestone",
+        unitType: "validate-milestone",
+        verdict: "good",
+        rationale: "Verdict pre-computed by parallel reviewers; atomic DB tx plus isolated VALIDATION.md write; no user interaction.",
+    },
+    gsd_reassess_roadmap: {
+        toolName: "gsd_reassess_roadmap",
+        unitType: "reassess-roadmap",
+        verdict: "good",
+        rationale: "Narrower mutation scope than plan_milestone; structural guards prevent modification of completed slices.",
+    },
+    gsd_doctor: {
+        toolName: "gsd_doctor",
+        verdict: "risky",
+        rationale: "Diagnostic-only mode (fix=false) is safe to background; fix=true writes STATE.md/ROADMAP.md without session-lock coordination and can race the foreground flow.",
+        constraints: [
+            "Background only with fix=false (diagnostic-only).",
+            "Apply fixes synchronously, only when no foreground unit is dispatched.",
+        ],
+    },
+    gsd_plan_milestone: {
+        toolName: "gsd_plan_milestone",
+        unitType: "plan-milestone",
+        verdict: "risky",
+        rationale: "Inputs require CONTEXT.md from discuss-milestone, so initial questioning is already done by the time it can start; TOCTOU guards and projection coherence make concurrency unsafe.",
+    },
+    gsd_replan_slice: {
+        toolName: "gsd_replan_slice",
+        unitType: "replan-slice",
+        verdict: "risky",
+        rationale: "Blocks the replanning→executing state transition on a gate that waits for S##-REPLAN.md; background failure leaves the flow stuck.",
+    },
+    gsd_plan_task: {
+        toolName: "gsd_plan_task",
+        verdict: "no",
+        rationale: "plan-slice prompt explicitly forbids calling gsd_plan_task separately; per-task granularity multiplies manifest writes and projection re-renders with no payoff.",
+    },
+};
+// Alias map keyed on the secondary name; resolves to the canonical entry above.
+// Sourced from packages/mcp-server/src/workflow-tools.ts alias registrations
+// (gsd_milestone_validate, gsd_roadmap_reassess, gsd_slice_replan, gsd_task_plan).
+const ALIASES = {
+    gsd_milestone_validate: "gsd_validate_milestone",
+    gsd_roadmap_reassess: "gsd_reassess_roadmap",
+    gsd_slice_replan: "gsd_replan_slice",
+    gsd_task_plan: "gsd_plan_task",
+};
+function resolveCanonical(name) {
+    return ALIASES[name] ?? name;
+}
+export function getDelegationVerdict(toolName) {
+    return POLICY[resolveCanonical(toolName)] ?? null;
+}
+export function isBackgroundable(toolName) {
+    const entry = getDelegationVerdict(toolName);
+    return entry?.verdict === "good";
+}
+export function listBackgroundableTools() {
+    return Object.values(POLICY)
+        .filter((entry) => entry.verdict === "good")
+        .map((entry) => entry.toolName)
+        .sort();
+}
+export function getVerdictByUnitType(unitType) {
+    for (const entry of Object.values(POLICY)) {
+        if (entry.unitType === unitType)
+            return entry;
+    }
+    return null;
+}
+/**
+ * Annotates a dispatch action in place with `backgroundable: true` when its
+ * unitType has a `good` verdict in the policy. Stop/skip actions pass through
+ * unchanged. Default-deny: unknown unit types resolve to `false`.
+ *
+ * **Mutation contract.** The `backgroundable` field is written directly onto
+ * the passed action object. This is intentional — every dispatch path in
+ * `auto-dispatch.ts` constructs a fresh action object per `where(ctx)` /
+ * `evaluateDispatch(ctx)` invocation, so in-place mutation cannot leak across
+ * dispatch cycles. Future dispatch rules MUST follow that convention: never
+ * cache or share `DispatchAction` objects across calls. If you need to cache,
+ * either freeze the cached object (`Object.freeze`) and clone on read, or
+ * stop calling `annotateBackgroundable` on the shared instance. The annotator
+ * always recomputes from the policy on every call (no internal cache), so
+ * repeated invocations on the same object will overwrite stale values
+ * deterministically — see the `annotateBackgroundable recomputes on each call`
+ * test for the contract pin.
+ */
+export function annotateBackgroundable(action) {
+    if (action.action !== "dispatch")
+        return action;
+    const verdict = getVerdictByUnitType(action.unitType);
+    action.backgroundable = verdict?.verdict === "good";
+    return action;
+}