@deftai/directive-core 0.98.0 → 0.99.0

package/dist/session/session-start.js

@@ -4,7 +4,9 @@ import { emitSessionEvalReadback } from "../eval/readback.js";
 import { bindSessionGeneration } from "../freshness/bind.js";
 import { readLiveGeneration } from "../freshness/generation.js";
 import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposit/migrate.js";
+import { hostContentSurfaceToDict, maybeFormatHostContentSurfaceLines, } from "../platform/host-content-surface.js";
 import { detectEnvironmentContext, environmentContextToDict, formatEnvironmentContext, } from "../platform/shell-context.js";
+import { ceremonyDialToDict, formatCeremonyDialStatusLine, mergeCeremonyDialDeferrals, resolveCeremonyDial, resolveSessionCeremonyDialInputs, } from "../policy/ceremony-dial.js";
 import { DEFT_DIRECTIVE_DISABLE_FLAG_NAME, DEFT_DIRECTIVE_DISABLE_STATUS, detectDeftDirectiveDisable, formatDeftDirectiveDisableMessage, isDeftDirectiveDisableActive, } from "../policy/deft-directive-disable.js";
 import { disclosureLine } from "../policy/disclosure.js";
 import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_FLAG_NAME, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY, } from "../policy/no-deft-directive.js";
@@ -33,7 +35,14 @@ export const READ_ONLY_RESULT_MESSAGE = "read-only session posture (alignment on
 export const SESSION_CEREMONY_TIERS = ["cold", "rearm"];
 export const COLD_CEREMONY_TIER = "cold";
 export const REARM_CEREMONY_TIER = "rearm";
-export const QUICK_STEPS = ["alignment", "branch_policy", "triage_welcome"];
+// verify_tools is mutation readiness recorded on cold path (#3214 / #3156) —
+// included so re-arm refuses after a tools-failed cold start.
+export const QUICK_STEPS = [
+    "alignment",
+    "branch_policy",
+    "triage_welcome",
+    "verify_tools",
+];
 export const GATED_STEPS = ["agent_hooks", "doctor", "cache_fresh"];
 /** Env opt-in for optional session:start network (release probe + triage cache hydrate) (#2991). */
 export const ENV_SESSION_START_NETWORK = "DEFT_SESSION_START_NETWORK";
@@ -105,7 +114,13 @@ export function assessRearmEligibility(projectRoot, options = {}) {
         }
     }
     for (const stepName of QUICK_STEPS) {
-        if (!stepPassesForRearm(state.quickSteps[stepName])) {
+        const step = state.quickSteps[stepName];
+        // Legacy ritual-state (pre-#3214 tools persistence) omits verify_tools —
+        // treat missing as pass; explicit failure still refuses re-arm.
+        if (stepName === "verify_tools" && (step === undefined || step === null)) {
+            continue;
+        }
+        if (!stepPassesForRearm(step)) {
             return {
                 eligible: false,
                 reason: `quick step '${stepName}' is missing or failed (full cold session:start required)`,
@@ -340,6 +355,34 @@ function resolveSessionScmReadiness(options, allowOptionalNetwork) {
         };
     }
 }
+function resolveHostContentSurface(projectRoot, options, runtimeMode) {
+    try {
+        const seams = options.hostContentSurfaceSeams ?? {};
+        return maybeFormatHostContentSurfaceLines(projectRoot, {
+            ...seams,
+            environ: seams.environ ?? options.env,
+            runtimeMode: seams.runtimeMode ?? runtimeMode ?? null,
+        });
+    }
+    catch {
+        // best-effort — session start must not abort on host-surface probe failures (#3162)
+        return {
+            report: {
+                contentClass: "unknown",
+                classSource: "probe-error",
+                signals: [],
+                managedSection: {
+                    state: "unknown",
+                    embeddedSha: null,
+                    bodyHash: null,
+                    path: `${projectRoot}/AGENTS.md`,
+                },
+                runtimeMode: null,
+            },
+            lines: [],
+        };
+    }
+}
 function runReadOnlySessionStart(projectRoot, options, instant, environment) {
     const lines = [];
     const resolveUserMd = options.resolveUserMd ?? ((root) => resolveUserMdPath({ projectRoot: root }));
@@ -351,10 +394,13 @@ function runReadOnlySessionStart(projectRoot, options, instant, environment) {
         : safeDiagnostic;
     // #2275: report SCM availability even on read-only alignment (shallow; no network).
     const scm = resolveSessionScmReadiness(options, false);
+    // #3162: host content-surface class + managed drift (advisory).
+    const hostSurface = resolveHostContentSurface(projectRoot, options, scm.runtimeMode);
     lines.push(READ_ONLY_ALIGNMENT_MESSAGE);
     lines.push(userMdLine);
     lines.push(formatEnvironmentContext(environment));
     lines.push(...formatScmReadinessLines(scm));
+    lines.push(...hostSurface.lines);
     const resultPayload = {
         ready: true,
         exit_code: 0,
@@ -376,6 +422,7 @@ function runReadOnlySessionStart(projectRoot, options, instant, environment) {
         },
         environment: environmentContextToDict(environment),
         scm: scmReadinessToDict(scm),
+        host_content_surface: hostContentSurfaceToDict(hostSurface.report),
         message: READ_ONLY_RESULT_MESSAGE,
     };
     return { code: 0, payload: resultPayload, lines };
@@ -418,11 +465,14 @@ function runSessionRearm(projectRoot, options, instant, environment) {
     const alignmentMessage = `${READ_ONLY_ALIGNMENT_MESSAGE} ${userMdLine}`;
     // #2275: re-arm still reports SCM state (shallow; no network).
     const scm = resolveSessionScmReadiness(options, false);
+    // #3162: host content-surface class + managed drift (advisory).
+    const hostSurface = resolveHostContentSurface(projectRoot, options, scm.runtimeMode);
     const lines = [
         READ_ONLY_ALIGNMENT_MESSAGE,
         userMdLine,
         formatEnvironmentContext(environment),
         ...formatScmReadinessLines(scm),
+        ...hostSurface.lines,
         REARM_SKIPPED_FAT_PATH_MESSAGE,
     ];
     // Light branch-policy disclosure (local only) so re-arm still surfaces policy state.
@@ -446,6 +496,41 @@ function runSessionRearm(projectRoot, options, instant, environment) {
     }
     const priorQuick = eligibility.state.quickSteps;
     const priorTriage = priorQuick.triage_welcome ?? ritualStep({ ok: true, ts: instant });
+    // Greptile P1: legacy ritual-state without verify_tools must re-run tools —
+    // never invent ok:true. When prior exists, preserve without re-run (#2992).
+    let toolsStep;
+    if (priorQuick.verify_tools && typeof priorQuick.verify_tools === "object") {
+        const priorTools = priorQuick.verify_tools;
+        toolsStep = {
+            ...priorTools,
+            ts: ritualStep({ ok: priorTools.ok === true, ts: instant }).ts,
+            message: typeof priorTools.message === "string"
+                ? priorTools.message
+                : "verify:tools preserved on re-arm",
+        };
+    }
+    else {
+        const verifyToolsFn = options.verifyTools ??
+            ((output) => {
+                const toolLines = [];
+                const result = verifyRequiredTools({ outputFn: (line) => toolLines.push(line) });
+                for (const line of toolLines) {
+                    output(line);
+                }
+                return { exitCode: result.exitCode };
+            });
+        const toolsOutcome = verifyToolsFn((line) => lines.push(line));
+        const toolsOk = toolsOutcome.exitCode === 0;
+        toolsStep = ritualStep({
+            ok: toolsOk,
+            ts: instant,
+            message: toolsOk
+                ? "verify:tools re-run on re-arm (legacy ritual lacked tools step)"
+                : `verify:tools failed on re-arm (exit ${toolsOutcome.exitCode})`,
+            exitCode: toolsOutcome.exitCode,
+            durationMs: 0,
+        });
+    }
     const policyOk = policyResult.error === null || policyResult.source === "default-fail-closed";
     const quickSteps = {
         alignment: ritualStep({
@@ -461,6 +546,7 @@ function runSessionRearm(projectRoot, options, instant, environment) {
             exitCode: policyOk ? 0 : 2,
             durationMs: 0,
         }),
+        verify_tools: toolsStep,
         // Preserve prior triage outcome; do not re-run welcome / self-heal on re-arm.
         triage_welcome: {
             ...priorTriage,
@@ -578,6 +664,7 @@ function runSessionRearm(projectRoot, options, instant, environment) {
             },
             environment: environmentContextToDict(environment),
             scm: scmReadinessToDict(scm),
+            host_content_surface: hostContentSurfaceToDict(hostSurface.report),
             message: code === 0 ? "session ritual re-armed" : "session ritual re-arm failed",
         },
         lines,
@@ -659,12 +746,26 @@ export function runSessionStart(projectRoot, options = {}) {
     const overallStarted = performance.now();
     const stepTimings = [];
     const allowOptionalNetwork = resolveSessionStartOptionalNetwork(options);
+    // #3214 / #3156: select ritual (ceremony) depth before building deferral maps.
+    // Rapid/minimal auto-defer informational cold steps only; mutation readiness
+    // (doctor, cache_fresh, agent_hooks, verify_tools) stays constant.
+    // Two-stage + provisional intake (#3214 design note / #1581 ordering): fill
+    // missing size/tier/shape from env/verb/files/deposit BEFORE resolve — never
+    // block on plan-item effort (post-planning only). Cold incomplete → rapid.
+    const { inputs: resolvedDialInputs, provisional: provisionalDial } = resolveSessionCeremonyDialInputs(projectRoot, options.ceremonyDialInputs, {
+        ...options.ceremonyDialHints,
+        env: options.env,
+    });
+    const ceremonyDialSelection = options.ceremonyDial ?? resolveCeremonyDial(projectRoot, { inputs: resolvedDialInputs });
+    const effectiveDeferrals = mergeCeremonyDialDeferrals(deferrals, ceremonyDialSelection);
+    const skipFatPath = ceremonyDialSelection.profile.skipFatPath;
     const { head: gitHeadValue, error: gitError } = gitHead(projectRoot, runGit);
     if (gitHeadValue === null) {
         const payload = {
             ready: false,
             exit_code: 2,
             ceremony_tier: COLD_CEREMONY_TIER,
+            ceremony_dial: ceremonyDialToDict(ceremonyDialSelection),
             environment: environmentContextToDict(environment),
             message: gitError ?? "could not resolve git HEAD",
         };
@@ -682,9 +783,13 @@ export function runSessionStart(projectRoot, options = {}) {
             lines: [formatEnvironmentContext(environment), payload.message],
         };
     }
-    const quickSteps = recordDeferredSteps(QUICK_STEPS, deferrals, instant);
-    const gatedSteps = recordDeferredSteps(GATED_STEPS, deferrals, instant);
+    const quickSteps = recordDeferredSteps(QUICK_STEPS, effectiveDeferrals, instant);
+    const gatedSteps = recordDeferredSteps(GATED_STEPS, effectiveDeferrals, instant);
     const lines = [];
+    lines.push(formatCeremonyDialStatusLine(ceremonyDialSelection));
+    if (provisionalDial.reasons.length > 0 && options.ceremonyDial === undefined) {
+        lines.push(`[deft ceremony-dial] provisional: ${provisionalDial.reasons.join("; ")}`);
+    }
     // Resolve USER.md via the shared first-hit-wins resolver so the alignment
     // step finds preferences automatically in mismatched / headless sandboxes
     // with zero manual DEFT_USER_PATH (#2271 / #2124). Never throws: an absent
@@ -724,6 +829,14 @@ export function runSessionStart(projectRoot, options = {}) {
     const scm = resolveSessionScmReadiness(options, allowOptionalNetwork);
     lines.push(...formatScmReadinessLines(scm));
     stepTimings.push({ name: "scm_readiness", duration_ms: elapsedMs(scmStepStarted) });
+    // #3162: host content-surface class + managed AGENTS drift (advisory; never blocks).
+    const hostSurfaceStepStarted = performance.now();
+    const hostSurface = resolveHostContentSurface(projectRoot, options, scm.runtimeMode);
+    lines.push(...hostSurface.lines);
+    stepTimings.push({
+        name: "host_content_surface",
+        duration_ms: elapsedMs(hostSurfaceStepStarted),
+    });
     if (!quickSteps.branch_policy) {
         const stepStarted = performance.now();
         const result = resolvePolicy(projectRoot);
@@ -753,6 +866,11 @@ export function runSessionStart(projectRoot, options = {}) {
     else {
         stepTimings.push({ name: "branch_policy", duration_ms: 0, skipped: true });
     }
+    // #3214 / #3156: verify_tools is mutation readiness — always run, even under
+    // rapid/minimal. Dial skipFatPath only lightens *ceremony* (triage welcome,
+    // optional network, staleness tickler), never readiness gates.
+    // Persist outcome into quick_steps so ritual-state records failure (not only
+    // process exit) — re-arm / later readers must not see a green cold start.
     {
         const stepStarted = performance.now();
         const verifyToolsFn = options.verifyTools ??
@@ -764,10 +882,28 @@ export function runSessionStart(projectRoot, options = {}) {
                 }
                 return { exitCode: result.exitCode };
             });
-        verifyToolsFn((line) => lines.push(line));
-        stepTimings.push({ name: "verify_tools", duration_ms: elapsedMs(stepStarted) });
+        const toolsOutcome = verifyToolsFn((line) => lines.push(line));
+        const durationMs = elapsedMs(stepStarted);
+        const toolsOk = toolsOutcome.exitCode === 0;
+        const toolsMessage = toolsOk
+            ? "verify:tools ok"
+            : `verify:tools failed (exit ${toolsOutcome.exitCode}); session not ready.`;
+        if (!toolsOk) {
+            lines.push(`[deft session] ${toolsMessage}`);
+        }
+        // Record on quick_steps (durable ritual-state) in addition to step timings.
+        quickSteps.verify_tools = ritualStep({
+            ok: toolsOk,
+            ts: instant,
+            message: toolsMessage,
+            exitCode: toolsOutcome.exitCode,
+            command: ["verify:tools"],
+            durationMs,
+        });
+        stepTimings.push({ name: "verify_tools", duration_ms: durationMs });
     }
-    if (!quickSteps.triage_welcome) {
+    // #3214: rapid/minimal skip informational cold-path ceremony only.
+    if (!quickSteps.triage_welcome && !skipFatPath) {
         const stepStarted = performance.now();
         const captured = [];
         const triageCommand = ["triage_welcome.run_default_mode", "--project-root", projectRoot];
@@ -825,7 +961,8 @@ export function runSessionStart(projectRoot, options = {}) {
         stepTimings.push({ name: "triage_welcome", duration_ms: 0, skipped: true });
     }
     // #2991: npm release probe is optional network — off by default so ritual write is not blocked.
-    if (allowOptionalNetwork) {
+    // #3214: also skipped under rapid/minimal dial (lifecycleWrites light/minimal).
+    if (allowOptionalNetwork && !skipFatPath) {
         const stepStarted = performance.now();
         try {
             const releaseAvailability = (options.probeReleaseAvailability ?? probeSessionReleaseAvailability)(projectRoot, { now: instant });
@@ -838,16 +975,20 @@ export function runSessionStart(projectRoot, options = {}) {
     }
     else {
         stepTimings.push({ name: "release_probe", duration_ms: 0, skipped: true });
-        lines.push(OPTIONAL_NETWORK_SKIPPED_MESSAGE);
-    }
-    try {
-        const tickler = (options.runStalenessTickler ?? maybeRunStalenessTickler)(projectRoot, {
-            now: instant,
-        });
-        lines.push(...tickler.lines);
+        if (!skipFatPath) {
+            lines.push(OPTIONAL_NETWORK_SKIPPED_MESSAGE);
+        }
     }
-    catch {
-        // Staleness tickler is best-effort and must never block session start.
+    if (!skipFatPath) {
+        try {
+            const tickler = (options.runStalenessTickler ?? maybeRunStalenessTickler)(projectRoot, {
+                now: instant,
+            });
+            lines.push(...tickler.lines);
+        }
+        catch {
+            // Staleness tickler is best-effort and must never block session start.
+        }
     }
     if (!runningInsideDeftRepo(projectRoot) && shouldEmitMigrateNudge(projectRoot)) {
         lines.push(MIGRATE_COMPLETION_NUDGE);
@@ -886,14 +1027,27 @@ export function runSessionStart(projectRoot, options = {}) {
     }
     const writeStarted = performance.now();
     const coldSessionId = (options.newSessionId ?? randomUUID)();
-    const payload = newRitualStatePayload({
-        sessionId: coldSessionId,
-        gitHead: gitHeadValue,
-        worktreePath: worktreePath(projectRoot, runGit),
-        startedAt: instant,
-        quickSteps,
-        gatedSteps,
-    });
+    const dialDict = {
+        ...ceremonyDialToDict(ceremonyDialSelection),
+        provisional: {
+            taskSize: provisionalDial.taskSize,
+            modelTier: provisionalDial.modelTier,
+            projectShape: provisionalDial.projectShape,
+            reasons: [...provisionalDial.reasons],
+        },
+    };
+    const payload = {
+        ...newRitualStatePayload({
+            sessionId: coldSessionId,
+            gitHead: gitHeadValue,
+            worktreePath: worktreePath(projectRoot, runGit),
+            startedAt: instant,
+            quickSteps,
+            gatedSteps,
+        }),
+        // #3214: record dial choice on ritual-state for audit / later re-arm context.
+        ceremony_dial: dialDict,
+    };
     let statePath;
     try {
         statePath = writeRitualState(projectRoot, payload);
@@ -915,6 +1069,7 @@ export function runSessionStart(projectRoot, options = {}) {
     const failed = Object.entries(quickSteps)
         .filter(([, step]) => !step.ok && !step.deferred_reason)
         .map(([name]) => name);
+    // verify_tools is recorded on quick_steps; failure makes ready=false.
     const code = failed.length > 0 ? 1 : 0;
     const totalMs = elapsedMs(overallStarted);
     // #3117: bind live deposit generation when payload surfaces load (cold path).
@@ -947,13 +1102,14 @@ export function runSessionStart(projectRoot, options = {}) {
         ready: code === 0,
         exit_code: code,
         ceremony_tier: COLD_CEREMONY_TIER,
+        ceremony_dial: dialDict,
         state_path: statePath,
         ...(freshnessBind ? { freshness: freshnessBind } : {}),
         quick_steps: quickSteps,
         gated_steps: gatedSteps,
         steps: stepTimings,
         duration_ms: totalMs,
-        optional_network: allowOptionalNetwork,
+        optional_network: allowOptionalNetwork && !skipFatPath,
         user_md: {
             path: userMd.path,
             rung: userMd.rung,
@@ -962,6 +1118,7 @@ export function runSessionStart(projectRoot, options = {}) {
         },
         environment: environmentContextToDict(environment),
         scm: scmReadinessToDict(scm),
+        host_content_surface: hostContentSurfaceToDict(hostSurface.report),
         message: code === 0 ? "session ritual recorded" : "session ritual failed",
     };
     // #2994: local process-cost event (best-effort; never blocks ceremony).

package/dist/swarm/index.d.ts

@@ -5,6 +5,8 @@ export * from "./finalize-cohort.js";
 export { finalizeCohortMain, parseFinalizeCohortArgv } from "./finalize-cohort-cli.js";
 export * from "./launch.js";
 export { launchMain, parseLaunchArgv } from "./launch-cli.js";
+export * from "./pre-dispatch.js";
+export { parsePreDispatchArgv, preDispatchMain } from "./pre-dispatch-cli.js";
 export * from "./readiness.js";
 export { readinessMain } from "./readiness-cli.js";
 export * from "./routing.js";

package/dist/swarm/index.js

@@ -5,6 +5,8 @@ export * from "./finalize-cohort.js";
 export { finalizeCohortMain, parseFinalizeCohortArgv } from "./finalize-cohort-cli.js";
 export * from "./launch.js";
 export { launchMain, parseLaunchArgv } from "./launch-cli.js";
+export * from "./pre-dispatch.js";
+export { parsePreDispatchArgv, preDispatchMain } from "./pre-dispatch-cli.js";
 export * from "./readiness.js";
 export { readinessMain } from "./readiness-cli.js";
 export * from "./routing.js";

package/dist/swarm/pre-dispatch-cli.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { type CompleteStatus, type PreDispatchAction } from "./pre-dispatch.js";
+export interface ParsedPreDispatchArgv {
+    projectRoot: string;
+    scopeId: string | null;
+    targetId: string | null;
+    workflowId: string | null;
+    action: PreDispatchAction | null;
+    sourceRevision: string | null;
+    attemptId: string | null;
+    status: CompleteStatus | null;
+    workerId: string | null;
+    externalRunId: string | null;
+    json: boolean;
+    help: boolean;
+}
+export declare function parsePreDispatchArgv(argv: string[]): ParsedPreDispatchArgv;
+export declare function preDispatchMain(argv?: string[]): number;
+//# sourceMappingURL=pre-dispatch-cli.d.ts.map

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

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * CLI for task swarm:pre-dispatch (#3228).
+ *
+ * Exit codes:
+ *   0 — allow (begin succeeded / complete-cancel succeeded)
+ *   1 — gate deny (e.g. DENY_DUPLICATE_ACTIVE) or complete with no active attempt
+ *   2 — config / usage error
+ */
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { EXIT_CONFIG_ERROR } from "./constants.js";
+import { COMPLETE_STATUSES, formatPreDispatchReport, PRE_DISPATCH_ACTIONS, swarmPreDispatch, } from "./pre-dispatch.js";
+export function parsePreDispatchArgv(argv) {
+    const out = {
+        projectRoot: ".",
+        scopeId: null,
+        targetId: null,
+        workflowId: null,
+        action: null,
+        sourceRevision: null,
+        attemptId: null,
+        status: null,
+        workerId: null,
+        externalRunId: null,
+        json: false,
+        help: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            out.help = true;
+        }
+        else if (arg === "--json") {
+            out.json = true;
+        }
+        else if (arg === "--project-root" && argv[i + 1] !== undefined) {
+            out.projectRoot = argv[i + 1] ?? ".";
+            i += 1;
+        }
+        else if ((arg === "--scope-id" || arg === "--scope") && argv[i + 1] !== undefined) {
+            out.scopeId = argv[i + 1] ?? null;
+            i += 1;
+        }
+        else if ((arg === "--target-id" || arg === "--target") && argv[i + 1] !== undefined) {
+            out.targetId = argv[i + 1] ?? null;
+            i += 1;
+        }
+        else if ((arg === "--workflow-id" || arg === "--workflow") && argv[i + 1] !== undefined) {
+            out.workflowId = argv[i + 1] ?? null;
+            i += 1;
+        }
+        else if (arg === "--action" && argv[i + 1] !== undefined) {
+            out.action = (argv[i + 1] ?? null);
+            i += 1;
+        }
+        else if ((arg === "--source-revision" || arg === "--revision") && argv[i + 1] !== undefined) {
+            out.sourceRevision = argv[i + 1] ?? null;
+            i += 1;
+        }
+        else if (arg === "--attempt-id" && argv[i + 1] !== undefined) {
+            out.attemptId = argv[i + 1] ?? null;
+            i += 1;
+        }
+        else if (arg === "--status" && argv[i + 1] !== undefined) {
+            out.status = (argv[i + 1] ?? null);
+            i += 1;
+        }
+        else if (arg === "--worker-id" && argv[i + 1] !== undefined) {
+            out.workerId = argv[i + 1] ?? null;
+            i += 1;
+        }
+        else if (arg === "--external-run-id" && argv[i + 1] !== undefined) {
+            out.externalRunId = argv[i + 1] ?? null;
+            i += 1;
+        }
+    }
+    return out;
+}
+const USAGE = `Usage: task swarm:pre-dispatch -- --scope-id <id> --target-id <worktree|branch> [options]
+
+Pre-dispatch gate for implement leaves (#3228 / #3143 DENY_DUPLICATE_ACTIVE).
+Before spawning a peer implement leaf: run with default --action begin.
+  exit 0  allow (attempt begun)
+  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).
+Terminal: --action complete [--status succeeded|failed|cancelled|blocked]
+
+Options:
+  --scope-id, --scope <id>         Unit scope (story/issue or xBRIEF plan id)
+  --target-id, --target <id>       Unit target (worktree path or branch)
+  --workflow-id, --workflow <id>   Default: drive-to:merge-ready
+  --action begin|complete|cancel   Default: begin
+  --source-revision <sha>          Default: git rev-parse HEAD
+  --attempt-id <id>                For complete/cancel
+  --status <status>                For complete: ${COMPLETE_STATUSES.join("|")}
+  --worker-id <id>                 Optional worker stamp on begin
+  --external-run-id <id>           Optional external run id
+  --project-root <path>            Project root (ledger under .deft/delivery-attempts/)
+  --json                           Machine-readable result on stdout
+  -h, --help                       Show this help
+`;
+export function preDispatchMain(argv = process.argv.slice(2)) {
+    const parsed = parsePreDispatchArgv(argv);
+    if (parsed.help) {
+        process.stdout.write(USAGE);
+        return EXIT_CONFIG_ERROR;
+    }
+    if (parsed.action !== null &&
+        !PRE_DISPATCH_ACTIONS.includes(parsed.action)) {
+        process.stderr.write(`Error: --action must be one of: ${PRE_DISPATCH_ACTIONS.join(", ")}.\n`);
+        return EXIT_CONFIG_ERROR;
+    }
+    if (parsed.status !== null && !COMPLETE_STATUSES.includes(parsed.status)) {
+        process.stderr.write(`Error: --status must be one of: ${COMPLETE_STATUSES.join(", ")}.\n`);
+        return EXIT_CONFIG_ERROR;
+    }
+    const result = swarmPreDispatch({
+        projectRoot: resolve(parsed.projectRoot),
+        scopeId: parsed.scopeId ?? "",
+        targetId: parsed.targetId ?? "",
+        workflowId: parsed.workflowId ?? undefined,
+        action: parsed.action ?? undefined,
+        sourceRevision: parsed.sourceRevision ?? undefined,
+        attemptId: parsed.attemptId ?? undefined,
+        status: parsed.status ?? undefined,
+        workerId: parsed.workerId,
+        externalRunId: parsed.externalRunId,
+    });
+    if (parsed.json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(`${formatPreDispatchReport(result)}\n`);
+    }
+    return result.exitCode;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(preDispatchMain());
+}
+//# sourceMappingURL=pre-dispatch-cli.js.map

package/dist/swarm/pre-dispatch.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Swarm implement-leaf pre-dispatch gate (#3228).
+ *
+ * Wires #3143 delivery-attempt DENY_DUPLICATE_ACTIVE onto the swarm re-dispatch
+ * path: before starting a peer implement leaf on a unit, if a non-terminal
+ * attempt already exists → exit non-zero and do not spawn.
+ *
+ * Takeover is two steps: cancel (complete status=cancelled) the prior attempt,
+ * then pre-dispatch begin again — never concurrent dual active.
+ */
+import { type AttemptTrigger, type DeliveryAttemptRecord, type PreDispatchDecision } from "../delivery-attempt/index.js";
+import { EXIT_CONFIG_ERROR, EXIT_GATE_FAILED, EXIT_OK } from "./constants.js";
+/** Default workflow id for drive-to:merge-ready implement leaves. */
+export declare const IMPLEMENT_LEAF_WORKFLOW_ID = "drive-to:merge-ready";
+export declare const PRE_DISPATCH_ACTIONS: readonly ["begin", "complete", "cancel"];
+export type PreDispatchAction = (typeof PRE_DISPATCH_ACTIONS)[number];
+export declare const COMPLETE_STATUSES: readonly ["succeeded", "failed", "cancelled", "blocked"];
+export type CompleteStatus = (typeof COMPLETE_STATUSES)[number];
+export interface SwarmPreDispatchInput {
+    readonly projectRoot: string;
+    readonly scopeId: string;
+    readonly targetId: string;
+    readonly workflowId?: string;
+    readonly action?: PreDispatchAction;
+    readonly sourceRevision?: string;
+    readonly attemptId?: string;
+    readonly status?: CompleteStatus;
+    readonly workerId?: string | null;
+    readonly externalRunId?: string | null;
+    readonly trigger?: AttemptTrigger;
+    readonly now?: string;
+}
+export interface SwarmPreDispatchResult {
+    readonly exitCode: typeof EXIT_OK | typeof EXIT_GATE_FAILED | typeof EXIT_CONFIG_ERROR;
+    readonly decision: PreDispatchDecision | null;
+    readonly reason: string;
+    readonly action: PreDispatchAction;
+    readonly scopeId: string;
+    readonly targetId: string;
+    readonly workflowId: string;
+    readonly attempt: DeliveryAttemptRecord | null;
+    readonly activeAttemptIds: readonly string[];
+}
+export declare function resolveSourceRevision(projectRoot: string, explicit?: string): string;
+/**
+ * True when targetId should be treated as a filesystem path (worktree), not an
+ * opaque branch/ref id. Branch names with `/` (e.g. `feat/foo`) stay opaque.
+ */
+export declare function looksLikeFilesystemTarget(targetId: string): boolean;
+/**
+ * Canonical unit target for ledger keys so relative/absolute/separator/case
+ * variants of the same worktree do not split gate state (#3228 Greptile P1).
+ *
+ * Always resolve under projectRoot to a stable absolute lexical key (even
+ * before the path exists). Do **not** realpath: following a symlink that is
+ * created between dispatches would change the key and split ledgers.
+ * Case-fold prevents case-insensitive FS splits. Existence never changes
+ * the ledger key.
+ */
+export declare function normalizeTargetId(projectRoot: string, targetId: string): string;
+/**
+ * Best-effort physical identity for alias peer checks. Ledger keys stay lexical
+ * (stable); when a path exists, realpath groups symlink aliases that point at
+ * the same worktree so sequential begins still DENY.
+ */
+export declare function physicalTargetKey(projectRoot: string, targetId: string): string;
+/** True when another unit (same scope+workflow, different target key) is active on same physical path. */
+export declare function hasActiveAliasPeer(projectRoot: string, scopeId: string, targetId: string, workflowId: string): boolean;
+/**
+ * Parse beginAttemptOnDisk-style error messages without a ReDoS-prone regex
+ * (CodeQL: polynomial regex on uncontrolled data).
+ */
+export declare function parseDecisionFromError(message: string): {
+    decision: PreDispatchDecision | null;
+    reason: string;
+};
+/**
+ * Swarm pre-dispatch gate for implement leaves.
+ *
+ * - begin (default): evaluate #3143 gate; on allow, beginAttempt; exit 0 / 1 / 2
+ * - complete: terminal success/fail/blocked
+ * - cancel: terminal cancel (takeover step 1)
+ */
+export declare function swarmPreDispatch(input: SwarmPreDispatchInput): SwarmPreDispatchResult;
+/** Human-readable one-line report for CLI stdout. */
+export declare function formatPreDispatchReport(result: SwarmPreDispatchResult): string;
+//# sourceMappingURL=pre-dispatch.d.ts.map