@deftai/directive-core 0.107.0 → 0.108.0

package/dist/subprocess/max-buffer.js

@@ -15,4 +15,19 @@
  * so an overflow is never silent again.
  */
 export const SUBPROCESS_MAX_BUFFER = 64 * 1024 * 1024;
+/**
+ * Reason text for a failed capture, so an overflow is never blank (#1867 / #3903).
+ *
+ * A spawn-level failure (ENOBUFS past the ceiling, timeout kill, missing
+ * binary) reports no exit status and empty stderr, whether it arrives as a
+ * `spawnSync` result or as a thrown `execFileSync` error. Only then does the
+ * error message stand in for stderr: a process that exited with a status and
+ * chose to say nothing keeps its empty stderr.
+ */
+export function resolveCaptureFailureStderr(capture) {
+    if (capture.captured.trim().length > 0 || typeof capture.status === "number") {
+        return capture.captured;
+    }
+    return capture.message ?? capture.captured;
+}
 //# sourceMappingURL=max-buffer.js.map

package/dist/swarm/complete-cohort.d.ts

@@ -47,6 +47,8 @@ export declare function completeCohort(args: {
     delivery?: CohortDeliveryContext | null;
     /** Optional launch allocation plan id so close-out reads this cohort's occupancy slot. */
     allocationPlanId?: string | null;
+    /** Test seam and explicit ambient-owner source for close-out corroboration. */
+    env?: NodeJS.ProcessEnv;
 }): {
     exitCode: number;
     stdout: string;

package/dist/swarm/complete-cohort.js

@@ -471,25 +471,33 @@ export function completeCohort(args) {
     });
     result.errors.push(...errors);
     if (result.ok && args.dryRun !== true) {
-        const envSession = process.env.DEFT_SESSION_ID?.trim() ?? "";
-        let sessionId = envSession;
-        if (sessionId.length === 0) {
-            const resolved = resolveLaunchOccupancySessionId(projectRoot, {
-                allocationPlanId: args.allocationPlanId ?? null,
-                storyIds: paths.map(storyIdFromPath),
-            });
-            if (resolved.reason === "ok" && resolved.sessionId.length > 0) {
-                sessionId = resolved.sessionId;
-            }
-            else if (readOccupancy(projectRoot) !== null) {
+        const env = args.env ?? process.env;
+        const envSession = env.DEFT_SESSION_ID?.trim() ?? "";
+        const liveOccupancy = readOccupancy(projectRoot);
+        const resolved = resolveLaunchOccupancySessionId(projectRoot, {
+            allocationPlanId: args.allocationPlanId ?? null,
+            storyIds: paths.map(storyIdFromPath),
+        });
+        let sessionId = "";
+        if (liveOccupancy !== null) {
+            if (resolved.reason !== "ok" || resolved.sessionId.length === 0) {
                 result.ok = false;
                 result.errors.push("swarm close-out occupancy record is missing or belongs to a different cohort. " +
-                    "Steal with occupancy:steal --confirm --occupant <id>.");
+                    "Re-establish an aligned owner with session:start --steal --confirm " +
+                    "--occupant <reported-session-id> --session-id=<your-session-id>.");
+            }
+            else if (envSession.length > 0 && envSession !== resolved.sessionId) {
+                result.ok = false;
+                result.errors.push(`swarm close-out ambient owner ${envSession} conflicts with cohort owner ` +
+                    `${resolved.sessionId}; refusing to release a later session's live lease.`);
+            }
+            else {
+                sessionId = resolved.sessionId;
             }
         }
         if (result.ok && sessionId.length > 0) {
             const released = releaseSwarmOccupancy(projectRoot, {
-                env: process.env,
+                env,
                 sessionId,
             });
             if (released.code !== 0) {

package/dist/swarm/index.d.ts

@@ -14,6 +14,7 @@ export { routingSetMain } from "./routing-set-cli.js";
 export * from "./routing-verify.js";
 export { routingVerifyMain } from "./routing-verify-cli.js";
 export * from "./subagent-backend.js";
+export * from "./subagent-status-dir.js";
 export * from "./subprocess.js";
 export * from "./verify-review-clean.js";
 export { verifyReviewCleanMain } from "./verify-review-clean-cli.js";

package/dist/swarm/index.js

@@ -14,6 +14,7 @@ export { routingSetMain } from "./routing-set-cli.js";
 export * from "./routing-verify.js";
 export { routingVerifyMain } from "./routing-verify-cli.js";
 export * from "./subagent-backend.js";
+export * from "./subagent-status-dir.js";
 export * from "./subprocess.js";
 export * from "./verify-review-clean.js";
 export { verifyReviewCleanMain } from "./verify-review-clean-cli.js";

package/dist/swarm/launch-cli.js

@@ -17,54 +17,58 @@ export function parseLaunchArgv(argv) {
     let enforceGatesFlag = false;
     let noAudit = false;
     let projectRoot = ".";
+    let sessionId = null;
+    let parseError = null;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
-        const next = argv[i + 1];
-        if (arg === "--stories" && next !== undefined) {
-            stories.push(next);
+        const takeValue = () => {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                parseError ??= `argument ${arg}: expected one argument`;
+                return null;
+            }
             i += 1;
+            return value;
+        };
+        if (arg === "--stories") {
+            const value = takeValue();
+            if (value !== null)
+                stories.push(value);
         }
-        else if (arg === "--paths" && next !== undefined) {
-            paths.push(next);
-            i += 1;
+        else if (arg === "--paths") {
+            const value = takeValue();
+            if (value !== null)
+                paths.push(value);
         }
-        else if (arg === "--group" && next !== undefined) {
-            group = next;
-            i += 1;
+        else if (arg === "--group") {
+            group = takeValue();
         }
-        else if (arg === "--worktree-map" && next !== undefined) {
-            worktreeMap = next;
-            i += 1;
+        else if (arg === "--worktree-map") {
+            worktreeMap = takeValue();
         }
-        else if (arg === "--base-branch" && next !== undefined) {
-            baseBranch = next;
-            i += 1;
+        else if (arg === "--base-branch") {
+            baseBranch = takeValue() ?? baseBranch;
         }
         else if (arg === "--autonomous") {
             autonomous = true;
         }
-        else if (arg === "--allocation-plan-id" && next !== undefined) {
-            allocationPlanId = next;
-            i += 1;
+        else if (arg === "--allocation-plan-id") {
+            allocationPlanId = takeValue();
         }
-        else if (arg === "--batching-rationale" && next !== undefined) {
-            batchingRationale = next;
-            i += 1;
+        else if (arg === "--batching-rationale") {
+            batchingRationale = takeValue();
         }
-        else if (arg === "--operator-approval" && next !== undefined) {
-            operatorApproval = next;
-            i += 1;
+        else if (arg === "--operator-approval") {
+            operatorApproval = takeValue();
         }
         else if (arg === "--no-create-worktrees") {
             noCreateWorktrees = true;
         }
-        else if (arg === "--output" && next !== undefined) {
-            output = next;
-            i += 1;
+        else if (arg === "--output") {
+            output = takeValue();
         }
-        else if (arg === "--gate-clearances" && next !== undefined) {
-            gateClearancesPath = next;
-            i += 1;
+        else if (arg === "--gate-clearances") {
+            gateClearancesPath = takeValue();
         }
         else if (arg === "--enforce-gates") {
             enforceGatesFlag = true;
@@ -72,12 +76,27 @@ export function parseLaunchArgv(argv) {
         else if (arg === "--no-audit") {
             noAudit = true;
         }
-        else if (arg === "--project-root" && next !== undefined) {
-            projectRoot = next;
-            i += 1;
+        else if (arg === "--project-root") {
+            projectRoot = takeValue() ?? projectRoot;
+        }
+        else if (arg === "--session-id") {
+            const value = takeValue();
+            if (value === null) {
+                // Keep an explicit invalid sentinel so swarmLaunch fails closed rather
+                // than falling back to ambient identity or minting a different owner.
+                sessionId = "";
+            }
+            else {
+                sessionId = value;
+            }
+        }
+        else if (arg?.startsWith("--session-id=") === true) {
+            const value = arg.slice("--session-id=".length);
+            sessionId = value.startsWith("--") ? "" : value;
         }
     }
     return {
+        parseError,
         stories,
         paths,
         group,
@@ -93,6 +112,7 @@ export function parseLaunchArgv(argv) {
         enforceGatesFlag,
         noAudit,
         projectRoot,
+        sessionId,
     };
 }
 export function launchMain(argv = process.argv.slice(2)) {

package/dist/swarm/launch.d.ts

@@ -1,4 +1,5 @@
 import { type ExpectedGithubWorkerPrincipal, type GhRunner, GITHUB_AUTH_MODE_HOST_GH, GITHUB_AUTH_MODE_INJECTED_TOKEN } from "../intake/github-auth-modes.js";
+import { releaseOccupancy } from "../session/occupancy.js";
 import { EXIT_CONFIG_ERROR, EXIT_GATE_FAILED, EXIT_OK } from "./constants.js";
 import { type WorktreeRecord } from "./worktrees.js";
 export interface ResolvedStory {
@@ -19,6 +20,7 @@ export type WorktreeResolverFn = (mapping: readonly Record<string, unknown>[], b
     repoRoot?: string;
 }) => WorktreeRecord[];
 export type RuntimeAuthProbeFn = () => [string, string];
+export type OccupancyReleaseFn = typeof releaseOccupancy;
 export declare const defaultPreflightGate: PreflightGateFn;
 export declare const defaultReadinessGate: ReadinessGateFn;
 export declare const defaultRuntimeAuthProbe: RuntimeAuthProbeFn;
@@ -144,6 +146,8 @@ export declare function buildManifest(resolved: readonly ResolvedStory[], option
 }): Record<string, unknown>[];
 export declare function orderCohort(resolved: readonly ResolvedStory[], _projectRoot: string): ResolvedStory[];
 export interface LaunchArgs {
+    /** CLI parse failure carried into the core so later valid flags cannot erase it. */
+    parseError?: string | null;
     stories?: readonly string[];
     paths?: readonly string[];
     group?: string | null;
@@ -159,10 +163,14 @@ export interface LaunchArgs {
     enforceGatesFlag?: boolean;
     noAudit?: boolean;
     projectRoot?: string;
+    /** Explicit cooperative owner identity, including host-payload canonical IDs (#3611). */
+    sessionId?: string | null;
     preflightGate?: PreflightGateFn;
     readinessGate?: ReadinessGateFn;
     worktreeResolver?: WorktreeResolverFn;
     runtimeAuthProbe?: RuntimeAuthProbeFn;
+    /** Test seam: override occupancy release after a newly minted claim fails. */
+    releaseOccupancyFn?: OccupancyReleaseFn;
     /**
      * Injection seam for the routing-provider environment lookup, mirroring
      * `resolveRoutingPath`'s `environ` parameter (#1877 Greptile follow-up).

package/dist/swarm/launch.js

@@ -5,7 +5,7 @@ import { ENV_EXPECTED_GITHUB_LOGIN, FAILURE_INSTALLATION_IDENTITY_UNVERIFIABLE,
 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";
@@ -695,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 {
@@ -781,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,
@@ -799,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;
@@ -813,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;
@@ -826,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;
@@ -843,17 +886,6 @@ 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
@@ -871,11 +903,7 @@ export function swarmLaunch(args) {
             cwd: projectRoot,
         });
         if (!injection.ok) {
-            return {
-                exitCode: EXIT_GATE_FAILED,
-                stdout: "",
-                stderr: `${injection.detail}\n${injection.remedy}\n`,
-            };
+            return failAfterClaim(EXIT_GATE_FAILED, `${injection.detail}\n${injection.remedy}\n`);
         }
         if (injection.injected) {
             expectedGithubLogin = injection.expectedLogin;
@@ -919,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 {
@@ -939,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;