@deftai/directive-core 0.106.0 → 0.108.0

package/dist/swarm/launch.js

@@ -1,11 +1,11 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { containedWrite } from "../fs/contained-write.js";
-import { inferGithubAuthMode } from "../intake/github-auth-modes.js";
+import { ENV_EXPECTED_GITHUB_LOGIN, FAILURE_INSTALLATION_IDENTITY_UNVERIFIABLE, FAILURE_MISSING_INJECTED_TOKEN, findInjectedToken, GITHUB_AUTH_MODE_HOST_GH, GITHUB_AUTH_MODE_INJECTED_TOKEN, inferGithubAuthMode, validateGithubAuthForWorker, } from "../intake/github-auth-modes.js";
 import { getPlatformCapabilities } from "../intake/platform-capabilities.js";
 import { hasArtifactSuffix, resolveLifecycleFolder, stripArtifactSuffix, } from "../layout/resolve.js";
 import { evaluate as preflightEvaluate } from "../preflight/evaluate.js";
-import { applyWorktreeOccupancy } from "../session/occupancy.js";
+import { applyWorktreeOccupancy, releaseOccupancy } from "../session/occupancy.js";
 import { issueNumbersFromPlan, scopeMetadataRank } from "../triage/queue/scope-walk.js";
 import { selectionOrderingKey } from "../triage/queue/selection.js";
 import { DEFAULT_BASE_BRANCH, EXIT_CONFIG_ERROR, EXIT_GATE_FAILED, EXIT_OK, GATE_ADVISE, GATE_ENFORCE, LEAF_CODING_WORKER_ROLE, } from "./constants.js";
@@ -25,6 +25,164 @@ export const defaultRuntimeAuthProbe = () => {
     const report = getPlatformCapabilities();
     return [report.runtimeMode, inferGithubAuthMode(report)];
 };
+const CREDENTIAL_VALUE_PATTERN = /^(ghp_|gho_|ghu_|ghs_|github_pat_)/i;
+const INJECTION_MISSING_CREDENTIAL = "GH_TOKEN (or GITHUB_TOKEN / GH_ENTERPRISE_TOKEN)";
+const INJECTION_DISPATCHER_REMEDY = "Dispatcher-side remedy: load an approved user-bearing worker credential into the dispatcher environment, then call prepareWorkerCredentialInjection before spawn. Do not fall back to the host gh token or continue under the maintainer identity. Installation credentials are not injectable; see #3693.";
+const HELD_WORKER_TOKEN_VARS = [
+    "GH_TOKEN",
+    "GITHUB_TOKEN",
+    "GH_ENTERPRISE_TOKEN",
+    "GITHUB_ENTERPRISE_TOKEN",
+];
+function looksLikeCredentialValue(value) {
+    return CREDENTIAL_VALUE_PATTERN.test(value.trim());
+}
+function assertNoCredentialValue(value, label) {
+    if (looksLikeCredentialValue(value)) {
+        throw new Error(`${label} must not contain a credential value`);
+    }
+}
+function sanitizeEnvelopeField(value, label) {
+    const cleaned = value.replace(/\r?\n/g, " ").trim();
+    assertNoCredentialValue(cleaned, label);
+    return cleaned;
+}
+/**
+ * Bind validation to the selected token. Stamp it into every gh token slot and
+ * drop GH_CONFIG_DIR so a host/enterprise config cannot authenticate as someone
+ * else. GH_HOST stays: it selects the API host, not the secret.
+ */
+function isolateHeldWorkerToken(environ, token) {
+    const isolated = { ...environ };
+    for (const name of HELD_WORKER_TOKEN_VARS) {
+        isolated[name] = token;
+    }
+    delete isolated.GH_CONFIG_DIR;
+    return isolated;
+}
+function boundWorkerSpawnEnv(token, expectedLogin) {
+    return {
+        GH_TOKEN: token,
+        GITHUB_TOKEN: token,
+        GH_ENTERPRISE_TOKEN: token,
+        [ENV_EXPECTED_GITHUB_LOGIN]: expectedLogin,
+    };
+}
+/**
+ * Dispatch-envelope half of the runtime / GitHub auth-mode contract (#1557 / #1351).
+ * Policy labels only — never a token value.
+ */
+export function formatDispatchAuthEnvelope(fields) {
+    const runtimeMode = sanitizeEnvelopeField(fields.runtimeMode, "runtime_mode");
+    const githubAuthMode = sanitizeEnvelopeField(fields.githubAuthMode, "github_auth_mode");
+    const lines = [
+        "## Runtime and GitHub auth mode",
+        "",
+        `- runtime_mode: ${runtimeMode}`,
+        `- github_auth_mode: ${githubAuthMode}`,
+    ];
+    if (fields.expectedGithubLogin !== undefined && fields.expectedGithubLogin !== null) {
+        const login = sanitizeEnvelopeField(fields.expectedGithubLogin, "expected_github_login");
+        if (login.length > 0) {
+            lines.push(`- expected_github_login: ${login}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+function blockedInjection(fields) {
+    const detail = fields.detail.startsWith("BLOCKED") ? fields.detail : `BLOCKED: ${fields.detail}`;
+    return {
+        ok: false,
+        blocked: true,
+        githubAuthMode: fields.githubAuthMode,
+        runtimeMode: fields.runtimeMode,
+        missingCredential: fields.missingCredential ?? INJECTION_MISSING_CREDENTIAL,
+        remedy: INJECTION_DISPATCHER_REMEDY,
+        detail,
+        failureKind: fields.failureKind,
+        envelopeSection: formatDispatchAuthEnvelope({
+            runtimeMode: fields.runtimeMode ?? "unknown",
+            githubAuthMode: fields.githubAuthMode,
+        }),
+    };
+}
+/**
+ * Validate a held user-bearing worker credential and prepare spawn-time injection (#1351).
+ *
+ * Comparison is opt-in on the validator. This path always stamps
+ * `DEFT_EXPECTED_GITHUB_LOGIN` after a successful user-principal check so the
+ * worker envelope does not inherit "any user token is approved."
+ *
+ * Installation credentials fail closed via the existing validator (#3693).
+ * Token values belong only in the returned `spawnEnv` — never in prompts,
+ * transcripts, or manifest entries.
+ */
+export function prepareWorkerCredentialInjection(request) {
+    const environ = request.environ ?? process.env;
+    const runtimeMode = request.runtimeMode ?? null;
+    const token = findInjectedToken(environ);
+    const grokBuild = request.dispatchPath === "grok-build";
+    const effectiveMode = grokBuild || token !== null ? GITHUB_AUTH_MODE_INJECTED_TOKEN : request.githubAuthMode;
+    if (effectiveMode === GITHUB_AUTH_MODE_HOST_GH && token === null) {
+        return {
+            ok: true,
+            injected: false,
+            githubAuthMode: GITHUB_AUTH_MODE_HOST_GH,
+            runtimeMode,
+            expectedLogin: null,
+            spawnEnv: {},
+            envelopeSection: formatDispatchAuthEnvelope({
+                runtimeMode: runtimeMode ?? "local-unsandboxed",
+                githubAuthMode: GITHUB_AUTH_MODE_HOST_GH,
+            }),
+        };
+    }
+    if (token === null) {
+        return blockedInjection({
+            githubAuthMode: GITHUB_AUTH_MODE_INJECTED_TOKEN,
+            runtimeMode,
+            failureKind: FAILURE_MISSING_INJECTED_TOKEN,
+            missingCredential: INJECTION_MISSING_CREDENTIAL,
+            detail: "missing worker credential GH_TOKEN (or GITHUB_TOKEN / GH_ENTERPRISE_TOKEN) for a write-requiring injected-token dispatch",
+        });
+    }
+    const isolatedEnviron = isolateHeldWorkerToken(environ, token);
+    const validated = validateGithubAuthForWorker(GITHUB_AUTH_MODE_INJECTED_TOKEN, {
+        environ: isolatedEnviron,
+        runtimeReport: { runtimeMode: runtimeMode ?? "cloud-headless" },
+        repo: request.repo,
+        runGh: request.runGh,
+        expectedPrincipal: request.expectedPrincipal,
+        cwd: request.cwd,
+    });
+    if (!validated.ok || validated.login === null || validated.login.trim().length === 0) {
+        const installation = validated.failureKind === FAILURE_INSTALLATION_IDENTITY_UNVERIFIABLE;
+        return blockedInjection({
+            githubAuthMode: GITHUB_AUTH_MODE_INJECTED_TOKEN,
+            runtimeMode,
+            failureKind: validated.failureKind,
+            detail: installation
+                ? `${validated.detail} Installation credentials are not injectable (#3693).`
+                : validated.detail,
+        });
+    }
+    const expectedLogin = validated.login.trim();
+    assertNoCredentialValue(expectedLogin, "expected_github_login");
+    const spawnEnv = boundWorkerSpawnEnv(token, expectedLogin);
+    return {
+        ok: true,
+        injected: true,
+        githubAuthMode: GITHUB_AUTH_MODE_INJECTED_TOKEN,
+        runtimeMode,
+        expectedLogin,
+        spawnEnv,
+        envelopeSection: formatDispatchAuthEnvelope({
+            runtimeMode: runtimeMode ?? "cloud-headless",
+            githubAuthMode: GITHUB_AUTH_MODE_INJECTED_TOKEN,
+            expectedGithubLogin: expectedLogin,
+        }),
+    };
+}
 function loadJson(path) {
     try {
         const data = JSON.parse(readFileSync(path, "utf8"));
@@ -498,6 +656,10 @@ export function buildManifest(resolved, options) {
         if (options.githubAuthMode !== undefined && options.githubAuthMode !== null) {
             entry.github_auth_mode = options.githubAuthMode;
         }
+        if (options.expectedGithubLogin !== undefined && options.expectedGithubLogin !== null) {
+            assertNoCredentialValue(options.expectedGithubLogin, "expected_github_login");
+            entry.expected_github_login = options.expectedGithubLogin;
+        }
         manifest.push(entry);
     }
     return manifest;
@@ -533,7 +695,23 @@ function splitCsv(values) {
     return out;
 }
 export function swarmLaunch(args) {
+    if (args.parseError !== undefined && args.parseError !== null) {
+        return {
+            exitCode: EXIT_CONFIG_ERROR,
+            stdout: "",
+            stderr: `Error: ${args.parseError}\n`,
+        };
+    }
     const projectRoot = resolve(args.projectRoot ?? process.cwd());
+    if (args.sessionId !== undefined &&
+        args.sessionId !== null &&
+        (args.sessionId.trim().length === 0 || args.sessionId.trim().startsWith("--"))) {
+        return {
+            exitCode: EXIT_CONFIG_ERROR,
+            stdout: "",
+            stderr: "Error: --session-id requires a non-empty owner identity.\n",
+        };
+    }
     const tokens = [...splitCsv(args.stories ?? []), ...splitCsv(args.paths ?? [])];
     if (tokens.length === 0) {
         return {
@@ -619,17 +797,52 @@ export function swarmLaunch(args) {
     }
     const operatorApproval = args.operatorApproval ??
         `task swarm:launch (${args.autonomous ? "autonomous" : "interactive"})`;
+    const occupancy = applyWorktreeOccupancy(projectRoot, {
+        sessionId: args.sessionId ?? undefined,
+        env: args.environ ?? process.env,
+        intent: "swarm",
+    });
+    if (occupancy.code !== 0) {
+        return {
+            exitCode: EXIT_GATE_FAILED,
+            stdout: "",
+            stderr: `${occupancy.message}\n`,
+        };
+    }
+    // Heartbeat on an existing owner is not a new claim -- only release a lease
+    // this process just minted (#3649 paired failure clause).
+    const newlyClaimed = occupancy.action === "claimed";
+    const failAfterClaim = (exitCode, stderr) => {
+        if (newlyClaimed) {
+            const recovery = "Occupancy release failed after this launch error; the lease may still be live. " +
+                "The occupant may release (occupancy:release / session:end). A replacement owner must " +
+                "run session:start --steal --confirm --occupant <reported-session-id> " +
+                "--session-id=<your-session-id> to align lease and ritual state.";
+            try {
+                const release = args.releaseOccupancyFn ?? releaseOccupancy;
+                const decision = release(projectRoot, {
+                    sessionId: occupancy.sessionId,
+                    env: args.environ ?? process.env,
+                });
+                if (decision.code !== 0) {
+                    stderr = `${stderr}\n${recovery} ${decision.message}\n`;
+                }
+            }
+            catch (exc) {
+                // Do not replace the original structured launch error; tell the operator
+                // the lease may still deny later sessions (#3649 Greptile P1).
+                stderr = `${stderr}\n${recovery} ${String(exc)}\n`;
+            }
+        }
+        return { exitCode, stdout: "", stderr };
+    };
     let worktreeRecordMap = new Map();
     if (args.worktreeMap !== undefined && args.worktreeMap !== null) {
         const resolver = args.worktreeResolver ?? resolveWorktreeMap;
         try {
             const payload = JSON.parse(readFileSync(args.worktreeMap, "utf8"));
             if (!Array.isArray(payload)) {
-                return {
-                    exitCode: EXIT_CONFIG_ERROR,
-                    stdout: "",
-                    stderr: `Error: --worktree-map ${args.worktreeMap} must contain a JSON array of records.\n`,
-                };
+                return failAfterClaim(EXIT_CONFIG_ERROR, `Error: --worktree-map ${args.worktreeMap} must contain a JSON array of records.\n`);
             }
             const records = resolver(payload, args.baseBranch ?? DEFAULT_BASE_BRANCH, !(args.noCreateWorktrees ?? false), {
                 repoRoot: projectRoot,
@@ -637,11 +850,7 @@ export function swarmLaunch(args) {
             worktreeRecordMap = new Map(records.map((r) => [r.story_id, r]));
         }
         catch (exc) {
-            return {
-                exitCode: EXIT_CONFIG_ERROR,
-                stdout: "",
-                stderr: `Error: worktree map resolution failed: ${String(exc)}\n`,
-            };
+            return failAfterClaim(EXIT_CONFIG_ERROR, `Error: worktree map resolution failed: ${String(exc)}\n`);
         }
     }
     let runtimeMode;
@@ -651,7 +860,7 @@ export function swarmLaunch(args) {
         [runtimeMode, githubAuthMode] = probe();
     }
     catch (exc) {
-        return { exitCode: EXIT_CONFIG_ERROR, stdout: "", stderr: `Error: ${String(exc)}\n` };
+        return failAfterClaim(EXIT_CONFIG_ERROR, `Error: ${String(exc)}\n`);
     }
     let resolvedModel = null;
     let modelSource = null;
@@ -664,11 +873,7 @@ export function swarmLaunch(args) {
         // would emit an exit-0 manifest with no model and no error to follow. Match
         // verify:routing, which treats the same state as a config error (#1739).
         if (route.source === "invalid") {
-            return {
-                exitCode: EXIT_CONFIG_ERROR,
-                stdout: "",
-                stderr: `Error: routing gate misconfigured: ${route.error ?? "invalid routing decision"}\n`,
-            };
+            return failAfterClaim(EXIT_CONFIG_ERROR, `Error: routing gate misconfigured: ${route.error ?? "invalid routing decision"}\n`);
         }
         if (route.decided) {
             resolvedModel = route.model;
@@ -681,16 +886,28 @@ export function swarmLaunch(args) {
             ? dispatchProviderFor(backend.backend_id)
             : null;
     const workerRoleValue = routingFile !== null || backend !== null ? LEAF_CODING_WORKER_ROLE : null;
-    const occupancy = applyWorktreeOccupancy(projectRoot, {
-        env: args.environ ?? process.env,
-        intent: "swarm",
-    });
-    if (occupancy.code !== 0) {
-        return {
-            exitCode: EXIT_GATE_FAILED,
-            stdout: "",
-            stderr: `${occupancy.message}\n`,
-        };
+    const launchEnviron = args.environ ?? process.env;
+    let expectedGithubLogin = null;
+    // Only the injected-token launch path auto-validates (and fail-closes on a
+    // missing token). An ambient GH_TOKEN on a host-gh probe is often the
+    // maintainer workaround, not a worker credential; local-hybrid injection is
+    // the explicit prepareWorkerCredentialInjection call.
+    if (githubAuthMode === GITHUB_AUTH_MODE_INJECTED_TOKEN) {
+        const injection = prepareWorkerCredentialInjection({
+            environ: launchEnviron,
+            githubAuthMode,
+            runtimeMode,
+            dispatchPath: "grok-build",
+            runGh: args.runGh,
+            expectedPrincipal: args.expectedPrincipal,
+            cwd: projectRoot,
+        });
+        if (!injection.ok) {
+            return failAfterClaim(EXIT_GATE_FAILED, `${injection.detail}\n${injection.remedy}\n`);
+        }
+        if (injection.injected) {
+            expectedGithubLogin = injection.expectedLogin;
+        }
     }
     const manifest = buildManifest(ordered, {
         projectRoot,
@@ -708,6 +925,7 @@ export function swarmLaunch(args) {
         modelSource,
         runtimeMode,
         githubAuthMode,
+        expectedGithubLogin,
         occupancySessionId: occupancy.sessionId,
     });
     const rendered = `${JSON.stringify(manifest, null, 2)}\n`;
@@ -729,11 +947,7 @@ export function swarmLaunch(args) {
         });
     }
     catch (exc) {
-        return {
-            exitCode: EXIT_CONFIG_ERROR,
-            stdout: "",
-            stderr: `Error: could not persist launch occupancy_session_id: ${String(exc)}\n`,
-        };
+        return failAfterClaim(EXIT_CONFIG_ERROR, `Error: could not persist launch occupancy_session_id: ${String(exc)}\n`);
     }
     if (args.output !== undefined && args.output !== null) {
         try {
@@ -749,11 +963,7 @@ export function swarmLaunch(args) {
             });
         }
         catch (exc) {
-            return {
-                exitCode: EXIT_CONFIG_ERROR,
-                stdout: "",
-                stderr: `Error: could not write --output ${args.output}: ${String(exc)}\n`,
-            };
+            return failAfterClaim(EXIT_CONFIG_ERROR, `Error: could not write --output ${args.output}: ${String(exc)}\n`);
         }
     }
     void args.noAudit;

package/dist/swarm/pre-dispatch-cli.js

@@ -85,7 +85,8 @@ Before spawning a peer implement leaf: run with default --action begin.
   exit 1  active deny / gate block (do not spawn)
   exit 2  config / usage error
 
-Takeover: --action cancel, then pre-dispatch begin again (not concurrent dual active).
+Takeover after REDISPATCH_OK: --action cancel, then pre-dispatch begin again
+(not concurrent dual active; a killed worker stays running until cancelled).
 Terminal: --action complete [--status succeeded|failed|cancelled|blocked]
 
 Options:

package/dist/swarm/pre-dispatch.js

@@ -12,6 +12,7 @@ import { existsSync, realpathSync } from "node:fs";
 import { isAbsolute, normalize, resolve } from "node:path";
 import { activeAttempts, beginAttempt, completeAttemptOnDisk, evaluatePreDispatch, hasActiveAttempt, listUnitLedgers, loadOrCreateUnitLedger, loadUnitLedger, markBlocked, saveUnitLedger, withUnitLock, } from "../delivery-attempt/index.js";
 import { EXIT_CONFIG_ERROR, EXIT_GATE_FAILED, EXIT_OK } from "./constants.js";
+import { ensureSubagentStatusDir, looksLikeWorktreeDir } from "./subagent-status-dir.js";
 import { runText } from "./subprocess.js";
 /** Default workflow id for drive-to:merge-ready implement leaves. */
 export const IMPLEMENT_LEAF_WORKFLOW_ID = "drive-to:merge-ready";
@@ -170,6 +171,14 @@ function runBegin(input) {
     const { scopeId, targetId, workflowId } = unitFields(input);
     const sourceRevision = resolveSourceRevision(input.projectRoot, input.sourceRevision);
     const trigger = input.trigger ?? "automatic";
+    // Arm heartbeat scratch so verify:subagent-alive can return REDISPATCH_OK
+    // instead of exit 2 ("scratch dir does not exist") after a host-kill (#3730).
+    // A bare relative worktree name (`b3730`) is opaque to the branch-vs-path
+    // heuristic, so accept an on-disk worktree as the second arming signal.
+    const armTarget = resolve(input.projectRoot, input.targetId.trim());
+    if (looksLikeFilesystemTarget(input.targetId) || looksLikeWorktreeDir(armTarget)) {
+        ensureSubagentStatusDir(armTarget);
+    }
     // Exclusive lock → reload → evaluate → begin+save (same decision under lock;
     // no stale preview decision on the success path).
     try {
@@ -366,7 +375,7 @@ export function formatPreDispatchReport(result) {
         lines.push(`  attempt: ${result.attempt.attemptId} status=${result.attempt.status}`);
     }
     if (result.exitCode === EXIT_GATE_FAILED && result.decision === "DENY_DUPLICATE_ACTIVE") {
-        lines.push("  hint: do not spawn; resume the live leaf, or takeover = cancel then pre-dispatch begin");
+        lines.push("  hint: do not spawn; a killed worker stays running until cancelled.", "  Takeover: task swarm:pre-dispatch -- --scope-id <id> --target-id <target> --action cancel", "  then the same command without --action (begin). REDISPATCH_OK does not lift DENY_DUPLICATE_ACTIVE.");
     }
     return lines.join("\n");
 }

package/dist/swarm/subagent-status-dir.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Arm the shipped sub-agent heartbeat path (#3730 / #1365 / #2824).
+ *
+ * `verify:subagent-alive` exits 2 when the scratch directory is missing, which
+ * looks like "never started" instead of REDISPATCH_OK. Parents mkdir at
+ * worktree create and at pre-dispatch begin so a later missing record is
+ * exit 1. Does not write heartbeat records or liveness onto the C2 manifest.
+ */
+/**
+ * True when a resolved path is an on-disk git worktree, i.e. it carries a `.git`
+ * entry (a file for `git worktree add` trees, a directory for the main clone).
+ *
+ * Arming cannot key off `looksLikeFilesystemTarget` alone: that predicate exists
+ * to keep branch refs opaque and so answers false for a bare relative worktree
+ * name like `b3730`, leaving the liveness gate at its exit-2 config error for a
+ * supported dispatch form. Existence alone is too loose in the other direction —
+ * a branch named `docs` resolves onto the real `docs/` tree and would mkdir a
+ * stray scratch dir in the source checkout. The `.git` marker separates the two.
+ */
+export declare function looksLikeWorktreeDir(resolvedPath: string): boolean;
+/**
+ * Create `<worktree>/.deft-scratch/subagent-status/` when the worktree exists.
+ * Returns the directory path, or null when the worktree is not on disk yet
+ * (do not mkdir a stray tree for a branch-name target).
+ */
+export declare function ensureSubagentStatusDir(worktreeRoot: string): string | null;
+//# sourceMappingURL=subagent-status-dir.d.ts.map

package/dist/swarm/subagent-status-dir.js

@@ -0,0 +1,42 @@
+/**
+ * Arm the shipped sub-agent heartbeat path (#3730 / #1365 / #2824).
+ *
+ * `verify:subagent-alive` exits 2 when the scratch directory is missing, which
+ * looks like "never started" instead of REDISPATCH_OK. Parents mkdir at
+ * worktree create and at pre-dispatch begin so a later missing record is
+ * exit 1. Does not write heartbeat records or liveness onto the C2 manifest.
+ */
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { defaultScratchDir } from "../orchestration/subagent-monitor.js";
+/**
+ * True when a resolved path is an on-disk git worktree, i.e. it carries a `.git`
+ * entry (a file for `git worktree add` trees, a directory for the main clone).
+ *
+ * Arming cannot key off `looksLikeFilesystemTarget` alone: that predicate exists
+ * to keep branch refs opaque and so answers false for a bare relative worktree
+ * name like `b3730`, leaving the liveness gate at its exit-2 config error for a
+ * supported dispatch form. Existence alone is too loose in the other direction —
+ * a branch named `docs` resolves onto the real `docs/` tree and would mkdir a
+ * stray scratch dir in the source checkout. The `.git` marker separates the two.
+ */
+export function looksLikeWorktreeDir(resolvedPath) {
+    const trimmed = resolvedPath.trim();
+    if (trimmed.length === 0)
+        return false;
+    return existsSync(join(trimmed, ".git"));
+}
+/**
+ * Create `<worktree>/.deft-scratch/subagent-status/` when the worktree exists.
+ * Returns the directory path, or null when the worktree is not on disk yet
+ * (do not mkdir a stray tree for a branch-name target).
+ */
+export function ensureSubagentStatusDir(worktreeRoot) {
+    const trimmed = worktreeRoot.trim();
+    if (trimmed.length === 0 || !existsSync(trimmed))
+        return null;
+    const dir = defaultScratchDir(trimmed);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+//# sourceMappingURL=subagent-status-dir.js.map

package/dist/swarm/worktrees.d.ts

@@ -21,6 +21,9 @@ export declare class WorktreeMapConfigError extends Error {
 export declare class WorktreePathEscapeError extends WorktreeMapError {
     name: string;
 }
+export declare class WorktreeRevisionMismatchError extends WorktreeMapError {
+    name: string;
+}
 export type GitRunner = (args: readonly string[], cwd: string) => TextCaptureResult;
 export declare const defaultGitRunner: GitRunner;
 /** Case-normalized comparison key for worktree-path equality. */
@@ -30,9 +33,20 @@ export interface WorktreeRecord {
     readonly worktree_path: string;
     readonly base_branch: string;
 }
-/** Parse `git worktree list --porcelain` into `{compareKey: branch|null}`. */
-export declare function parseWorktreePorcelain(text: string): Map<string, string | null>;
-/** Resolve a story-to-worktree mapping into normalized C3 records (frozen contract). */
+/** One `git worktree list --porcelain` record. `head` is the commit OID or null. */
+export interface WorktreePorcelainEntry {
+    readonly branch: string | null;
+    readonly head: string | null;
+}
+/** Parse `git worktree list --porcelain` into `{compareKey: {branch, head}}`. */
+export declare function parseWorktreePorcelain(text: string): Map<string, WorktreePorcelainEntry>;
+/**
+ * Resolve a story-to-worktree mapping into normalized C3 records (frozen contract).
+ *
+ * Registered paths are reused only when their porcelain HEAD OID matches the
+ * requested base OID. That comparison is a snapshot at resolution time — not a
+ * pin on the worker's start revision (`swarm:launch` emits a manifest and stops).
+ */
 export declare function resolveWorktreeMap(mapping: readonly Record<string, unknown>[], baseBranch: string, createMissing?: boolean, options?: {
     repoRoot?: string;
     git?: GitRunner;

package/dist/swarm/worktrees.js

@@ -2,6 +2,7 @@ import { mkdirSync, readFileSync } from "node:fs";
 import { isAbsolute, resolve as pathResolve } from "node:path";
 import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { C3_FIELDS } from "./constants.js";
+import { ensureSubagentStatusDir } from "./subagent-status-dir.js";
 import { runText } from "./subprocess.js";
 export class WorktreeMapError extends Error {
     name = "WorktreeMapError";
@@ -24,6 +25,9 @@ export class WorktreeMapConfigError extends Error {
 export class WorktreePathEscapeError extends WorktreeMapError {
     name = "WorktreePathEscapeError";
 }
+export class WorktreeRevisionMismatchError extends WorktreeMapError {
+    name = "WorktreeRevisionMismatchError";
+}
 export const defaultGitRunner = (args, cwd) => runText(["git", ...args], { cwd });
 function resolvePath(raw, repoRoot) {
     const candidate = isAbsolute(raw) ? raw : pathResolve(repoRoot, raw);
@@ -44,14 +48,15 @@ function assertWorktreePathContained(repoRoot, worktreePath) {
 export function compareKey(pathStr) {
     return pathStr.replace(/\\/g, "/").toLowerCase();
 }
-/** Parse `git worktree list --porcelain` into `{compareKey: branch|null}`. */
+/** Parse `git worktree list --porcelain` into `{compareKey: {branch, head}}`. */
 export function parseWorktreePorcelain(text) {
     const registered = new Map();
     let currentPath = null;
     let currentBranch = null;
+    let currentHead = null;
     const flush = () => {
         if (currentPath !== null) {
-            registered.set(compareKey(currentPath), currentBranch);
+            registered.set(compareKey(currentPath), { branch: currentBranch, head: currentHead });
         }
     };
     for (const line of text.split("\n")) {
@@ -59,6 +64,11 @@ export function parseWorktreePorcelain(text) {
             flush();
             currentPath = pathResolve(line.slice("worktree ".length).trim());
             currentBranch = null;
+            currentHead = null;
+        }
+        else if (line.startsWith("HEAD ")) {
+            const oid = line.slice("HEAD ".length).trim().toLowerCase();
+            currentHead = oid.length > 0 ? oid : null;
         }
         else if (line.startsWith("branch ")) {
             const ref = line.slice("branch ".length).trim();
@@ -82,6 +92,24 @@ function gitWorktreeList(repoRoot, git) {
     }
     return parseWorktreePorcelain(proc.stdout);
 }
+function resolveCommitOid(repoRoot, revision, git) {
+    let proc;
+    try {
+        proc = git(["rev-parse", "--verify", "--end-of-options", `${revision}^{commit}`], repoRoot);
+    }
+    catch (exc) {
+        throw new WorktreeMapConfigError(`could not resolve base '${revision}' to a commit OID in ${repoRoot}: ${String(exc)}`);
+    }
+    if (proc.returncode !== 0) {
+        throw new WorktreeMapConfigError(`could not resolve base '${revision}' to a commit OID in ${repoRoot} ` +
+            `(rc=${proc.returncode}): ${proc.stderr.trim() || "<no stderr>"}`);
+    }
+    const oid = (proc.stdout.trim().split(/\s+/)[0] ?? "").toLowerCase();
+    if (!/^[0-9a-f]{40,64}$/.test(oid)) {
+        throw new WorktreeMapConfigError(`git rev-parse for base '${revision}' did not return a commit OID: ${JSON.stringify(oid)}`);
+    }
+    return oid;
+}
 function createWorktree(repoRoot, worktreePath, baseBranch, git) {
     mkdirSync(pathResolve(worktreePath, ".."), { recursive: true });
     let proc;
@@ -96,7 +124,13 @@ function createWorktree(repoRoot, worktreePath, baseBranch, git) {
             `(rc=${proc.returncode}): ${proc.stderr.trim() || "<no stderr>"}`);
     }
 }
-/** Resolve a story-to-worktree mapping into normalized C3 records (frozen contract). */
+/**
+ * Resolve a story-to-worktree mapping into normalized C3 records (frozen contract).
+ *
+ * Registered paths are reused only when their porcelain HEAD OID matches the
+ * requested base OID. That comparison is a snapshot at resolution time — not a
+ * pin on the worker's start revision (`swarm:launch` emits a manifest and stops).
+ */
 export function resolveWorktreeMap(mapping, baseBranch, createMissing = true, options = {}) {
     if (!Array.isArray(mapping)) {
         throw new WorktreeMapConfigError(`worktree map must be a list of records, got ${typeof mapping}`);
@@ -154,14 +188,24 @@ export function resolveWorktreeMap(mapping, baseBranch, createMissing = true, op
         });
     }
     const registered = gitWorktreeList(root, git);
+    const requestedOid = resolveCommitOid(root, trimmedBase, git);
     for (const entry of resolved) {
-        if (registered.has(entry._key)) {
+        const existing = registered.get(entry._key);
+        if (existing !== undefined) {
+            const actualOid = existing.head ?? "";
+            if (actualOid !== requestedOid) {
+                throw new WorktreeRevisionMismatchError(`registered worktree '${entry.worktree_path}' HEAD OID is ${actualOid || "(missing)"} ` +
+                    `but requested base '${trimmedBase}' resolves to ${requestedOid}; ` +
+                    `this is a snapshot check at resolution time, not a pin on the worker's start revision`);
+            }
+            ensureSubagentStatusDir(entry._abs);
             continue;
         }
         if (!createMissing) {
             throw new MissingWorktreeError(`story '${entry.story_id}' maps to '${entry.worktree_path}' which is not a registered git worktree and create_missing is disabled`);
         }
         createWorktree(root, entry._abs, trimmedBase, git);
+        ensureSubagentStatusDir(entry._abs);
     }
     return resolved.map(({ story_id, worktree_path, base_branch }) => ({
         story_id,

package/dist/triage/actions/index.d.ts

@@ -38,6 +38,10 @@ export declare function reset(issueNumber: number, repo: string, deps: TriageAct
     actor?: string | null;
     projectRoot?: string;
 }): string;
+/** Success line for ``triage:accept``, plus the optional design-critique affordance (#3708). */
+export declare function formatAcceptOutput(issueNumber: number, repo: string, decisionId: string, options?: {
+    autoPromote?: boolean;
+}): string;
 /** Format a decision entry for CLI ``status`` / ``history`` output. */
 export declare function formatDecision(entry: AuditEntry | null): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/triage/actions/index.js

@@ -407,6 +407,12 @@ export function reset(issueNumber, repo, deps, options = {}) {
     });
     return deps.candidatesLog.append(entry, { path: logPath });
 }
+/** Success line for ``triage:accept``, plus the optional design-critique affordance (#3708). */
+export function formatAcceptOutput(issueNumber, repo, decisionId, options = {}) {
+    const promoteNote = options.autoPromote === true ? " + auto-promote" : "";
+    return (`accept #${issueNumber} (${repo}) -> ${decisionId}${promoteNote}\n` +
+        "optional: deft-directive-design-critique (declining writes nothing)");
+}
 /** Format a decision entry for CLI ``status`` / ``history`` output. */
 export function formatDecision(entry) {
     if (entry === null) {