@deftai/directive-core 0.98.1 → 0.100.0

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

package/dist/swarm/pre-dispatch.js

@@ -0,0 +1,373 @@
+/**
+ * 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 { 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 { runText } from "./subprocess.js";
+/** Default workflow id for drive-to:merge-ready implement leaves. */
+export const IMPLEMENT_LEAF_WORKFLOW_ID = "drive-to:merge-ready";
+export const PRE_DISPATCH_ACTIONS = ["begin", "complete", "cancel"];
+export const COMPLETE_STATUSES = ["succeeded", "failed", "cancelled", "blocked"];
+export function resolveSourceRevision(projectRoot, explicit) {
+    if (explicit !== undefined && explicit.trim().length > 0) {
+        return explicit.trim();
+    }
+    const captured = runText(["git", "rev-parse", "HEAD"], { cwd: projectRoot });
+    if (captured.returncode === 0) {
+        const sha = captured.stdout.trim();
+        if (sha.length > 0)
+            return sha;
+    }
+    return "unknown";
+}
+/**
+ * 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 function looksLikeFilesystemTarget(targetId) {
+    const t = targetId.trim();
+    if (t.length === 0)
+        return false;
+    if (isAbsolute(t) || t.startsWith(".") || t.includes("\\"))
+        return true;
+    if (/^[A-Za-z]:[\\/]/.test(t))
+        return true;
+    const lower = t.toLowerCase().replace(/\\/g, "/");
+    return (lower.includes(".deft-scratch/") ||
+        lower.includes("/worktrees/") ||
+        lower.startsWith("worktrees/"));
+}
+/**
+ * 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 function normalizeTargetId(projectRoot, targetId) {
+    const trimmed = targetId.trim();
+    if (trimmed.length === 0)
+        return trimmed;
+    let pathKey = normalize(resolve(projectRoot, trimmed)).replace(/\\/g, "/").toLowerCase();
+    if (pathKey.length > 1 && pathKey.endsWith("/")) {
+        pathKey = pathKey.slice(0, -1);
+    }
+    return pathKey;
+}
+/**
+ * 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 function physicalTargetKey(projectRoot, targetId) {
+    const lexical = normalizeTargetId(projectRoot, targetId);
+    const candidates = [lexical, resolve(projectRoot, targetId.trim()), targetId.trim()];
+    for (const candidate of candidates) {
+        if (candidate.length === 0 || !existsSync(candidate))
+            continue;
+        try {
+            return normalize(realpathSync(candidate)).replace(/\\/g, "/").toLowerCase();
+        }
+        catch {
+            /* try next candidate */
+        }
+    }
+    return lexical;
+}
+/** True when another unit (same scope+workflow, different target key) is active on same physical path. */
+export function hasActiveAliasPeer(projectRoot, scopeId, targetId, workflowId) {
+    const mine = physicalTargetKey(projectRoot, targetId);
+    for (const ledger of listUnitLedgers(projectRoot)) {
+        if (ledger.scopeId !== scopeId || ledger.workflowId !== workflowId)
+            continue;
+        if (ledger.targetId === targetId)
+            continue;
+        if (!hasActiveAttempt(ledger))
+            continue;
+        if (physicalTargetKey(projectRoot, ledger.targetId) === mine) {
+            return true;
+        }
+    }
+    return false;
+}
+function unitFields(input) {
+    return {
+        scopeId: input.scopeId.trim(),
+        targetId: normalizeTargetId(input.projectRoot, input.targetId),
+        workflowId: (input.workflowId ?? IMPLEMENT_LEAF_WORKFLOW_ID).trim(),
+    };
+}
+function baseResult(input, action, partial) {
+    const { scopeId, targetId, workflowId } = unitFields(input);
+    return {
+        exitCode: partial.exitCode,
+        decision: partial.decision,
+        reason: partial.reason,
+        action,
+        scopeId,
+        targetId,
+        workflowId,
+        attempt: partial.attempt ?? null,
+        activeAttemptIds: partial.activeAttemptIds ?? [],
+    };
+}
+function listActiveIds(projectRoot, scopeId, targetId, workflowId) {
+    const ledger = loadUnitLedger(projectRoot, scopeId, targetId, workflowId);
+    if (ledger === null)
+        return [];
+    return activeAttempts(ledger).map((a) => a.attemptId);
+}
+/**
+ * Parse beginAttemptOnDisk-style error messages without a ReDoS-prone regex
+ * (CodeQL: polynomial regex on uncontrolled data).
+ */
+export function parseDecisionFromError(message) {
+    const prefix = "delivery-attempt ";
+    if (!message.startsWith(prefix)) {
+        return { decision: null, reason: message };
+    }
+    const rest = message.slice(prefix.length);
+    const colon = rest.indexOf(":");
+    if (colon <= 0) {
+        return { decision: null, reason: message };
+    }
+    const code = rest.slice(0, colon).trim();
+    // Bound check: decision codes are short fixed tokens (ALLOW_*/DENY_*/BLOCK_*).
+    if (code.length > 64 || code.length < 6) {
+        return { decision: null, reason: message };
+    }
+    if (!code.startsWith("ALLOW_") && !code.startsWith("DENY_") && !code.startsWith("BLOCK_")) {
+        return { decision: null, reason: message };
+    }
+    for (let i = 0; i < code.length; i += 1) {
+        const c = code.charCodeAt(i);
+        const ok = (c >= 65 && c <= 90) || // A-Z
+            (c >= 48 && c <= 57) || // 0-9
+            c === 95; // _
+        if (!ok) {
+            return { decision: null, reason: message };
+        }
+    }
+    const reason = rest.slice(colon + 1).trim();
+    return {
+        decision: code,
+        reason: reason.length > 0 ? reason : message,
+    };
+}
+function runBegin(input) {
+    const { scopeId, targetId, workflowId } = unitFields(input);
+    const sourceRevision = resolveSourceRevision(input.projectRoot, input.sourceRevision);
+    const trigger = input.trigger ?? "automatic";
+    // Exclusive lock → reload → evaluate → begin+save (same decision under lock;
+    // no stale preview decision on the success path).
+    try {
+        return withUnitLock(input.projectRoot, scopeId, targetId, workflowId, () => {
+            // Symlink alias peer: different lexical keys, same physical worktree.
+            if (hasActiveAliasPeer(input.projectRoot, scopeId, targetId, workflowId)) {
+                return baseResult(input, "begin", {
+                    exitCode: EXIT_GATE_FAILED,
+                    decision: "DENY_DUPLICATE_ACTIVE",
+                    reason: "active attempt exists on alias/realpath peer of target",
+                    activeAttemptIds: listActiveIds(input.projectRoot, scopeId, targetId, workflowId),
+                });
+            }
+            const current = loadOrCreateUnitLedger(input.projectRoot, {
+                scopeId,
+                targetId,
+                workflowId,
+                now: input.now,
+            });
+            const decision = evaluatePreDispatch(current, {
+                scopeId,
+                targetId,
+                workflowId,
+                sourceRevision,
+                trigger,
+                now: input.now,
+            });
+            if (!decision.allowed) {
+                if (decision.handoff !== null) {
+                    const blocked = markBlocked(current, decision.decision, decision.handoff.resumeCondition, input.now);
+                    saveUnitLedger(input.projectRoot, blocked);
+                }
+                return baseResult(input, "begin", {
+                    exitCode: EXIT_GATE_FAILED,
+                    decision: decision.decision,
+                    reason: decision.reason,
+                    activeAttemptIds: activeAttempts(current).map((a) => a.attemptId),
+                });
+            }
+            const { ledger, attempt } = beginAttempt(current, {
+                sourceRevision,
+                trigger,
+                status: "running",
+                workerId: input.workerId ?? null,
+                externalRunId: input.externalRunId ?? null,
+                now: input.now,
+                consumeOverride: decision.decision === "ALLOW_OVERRIDE",
+            });
+            saveUnitLedger(input.projectRoot, ledger);
+            return baseResult(input, "begin", {
+                exitCode: EXIT_OK,
+                decision: decision.decision,
+                reason: `allowed; attempt ${attempt.attemptId} begun`,
+                attempt,
+                activeAttemptIds: [attempt.attemptId],
+            });
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const parsed = parseDecisionFromError(message);
+        if (parsed.decision !== null) {
+            return baseResult(input, "begin", {
+                exitCode: EXIT_GATE_FAILED,
+                decision: parsed.decision,
+                reason: parsed.reason,
+                activeAttemptIds: listActiveIds(input.projectRoot, scopeId, targetId, workflowId),
+            });
+        }
+        return baseResult(input, "begin", {
+            exitCode: EXIT_CONFIG_ERROR,
+            decision: null,
+            reason: message,
+            activeAttemptIds: listActiveIds(input.projectRoot, scopeId, targetId, workflowId),
+        });
+    }
+}
+function runComplete(input, action) {
+    const { scopeId, targetId, workflowId } = unitFields(input);
+    const status = action === "cancel" ? "cancelled" : (input.status ?? "succeeded");
+    const ledger = loadUnitLedger(input.projectRoot, scopeId, targetId, workflowId);
+    if (ledger === null) {
+        return baseResult(input, action, {
+            exitCode: EXIT_GATE_FAILED,
+            decision: null,
+            reason: "no delivery-attempt ledger for unit",
+            activeAttemptIds: [],
+        });
+    }
+    const actives = activeAttempts(ledger);
+    if (actives.length === 0 && input.attemptId === undefined && input.externalRunId === undefined) {
+        return baseResult(input, action, {
+            exitCode: EXIT_GATE_FAILED,
+            decision: null,
+            reason: "no active attempt to complete/cancel",
+            activeAttemptIds: [],
+        });
+    }
+    try {
+        const next = completeAttemptOnDisk(input.projectRoot, {
+            scopeId,
+            targetId,
+            workflowId,
+            attemptId: input.attemptId,
+            externalRunId: input.externalRunId ?? null,
+            status,
+            now: input.now,
+        });
+        const closed = next.attempts.find((a) => a.attemptId === input.attemptId) ??
+            next.attempts.filter((a) => a.endedAt !== null).at(-1) ??
+            null;
+        return baseResult(input, action, {
+            exitCode: EXIT_OK,
+            decision: null,
+            reason: `attempt ${closed?.attemptId ?? "?"} marked ${status}`,
+            attempt: closed,
+            activeAttemptIds: activeAttempts(next).map((a) => a.attemptId),
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return baseResult(input, action, {
+            exitCode: EXIT_CONFIG_ERROR,
+            decision: null,
+            reason: message,
+            activeAttemptIds: listActiveIds(input.projectRoot, scopeId, targetId, workflowId),
+        });
+    }
+}
+/**
+ * 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 function swarmPreDispatch(input) {
+    const action = input.action ?? "begin";
+    const { scopeId, targetId, workflowId } = unitFields(input);
+    if (scopeId.length === 0) {
+        return baseResult(input, action, {
+            exitCode: EXIT_CONFIG_ERROR,
+            decision: null,
+            reason: "--scope-id is required (story/issue or xBRIEF plan id)",
+        });
+    }
+    if (targetId.length === 0) {
+        return baseResult(input, action, {
+            exitCode: EXIT_CONFIG_ERROR,
+            decision: null,
+            reason: "--target-id is required (worktree path or branch)",
+        });
+    }
+    if (workflowId.length === 0) {
+        return baseResult(input, action, {
+            exitCode: EXIT_CONFIG_ERROR,
+            decision: null,
+            reason: "--workflow-id must be non-empty",
+        });
+    }
+    if (!PRE_DISPATCH_ACTIONS.includes(action)) {
+        return baseResult(input, "begin", {
+            exitCode: EXIT_CONFIG_ERROR,
+            decision: null,
+            reason: `--action must be one of: ${PRE_DISPATCH_ACTIONS.join(", ")}`,
+        });
+    }
+    if (action === "complete" &&
+        input.status !== undefined &&
+        !COMPLETE_STATUSES.includes(input.status)) {
+        return baseResult(input, action, {
+            exitCode: EXIT_CONFIG_ERROR,
+            decision: null,
+            reason: `--status must be one of: ${COMPLETE_STATUSES.join(", ")}`,
+        });
+    }
+    if (action === "begin")
+        return runBegin(input);
+    return runComplete(input, action);
+}
+/** Human-readable one-line report for CLI stdout. */
+export function formatPreDispatchReport(result) {
+    const unit = `${result.scopeId} / ${result.targetId} / ${result.workflowId}`;
+    const decision = result.decision !== null ? result.decision : "n/a";
+    const active = result.activeAttemptIds.length > 0 ? result.activeAttemptIds.join(",") : "(none)";
+    const lines = [
+        `[swarm:pre-dispatch] action=${result.action} exit=${result.exitCode}`,
+        `  unit: ${unit}`,
+        `  decision: ${decision}`,
+        `  reason: ${result.reason}`,
+        `  active: ${active}`,
+    ];
+    if (result.attempt !== null) {
+        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");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=pre-dispatch.js.map

package/dist/triage/actions/candidates-log.d.ts

@@ -1,6 +1,5 @@
 import { resolveCandidatesLogPath } from "../cache-path.js";
-import type { AuditEntry, CandidatesLog } from "./types.js";
-/** Display/back-compat constant; resolution flows through resolveTriageCachePath (#1703). */
+import type { AuditEntry, CandidatesLog } from "./types.js"; /** Display/back-compat constant; resolution flows through resolveTriageCachePath (#1703). */
 export declare const AUDIT_LOG_REL_PATH = "xbrief/.triage-cache/candidates.jsonl";
 export { resolveCandidatesLogPath };
 /** Read every well-formed audit-log row in insertion order (#1698 shared reader). */

package/dist/triage/actions/candidates-log.js

@@ -1,9 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { containedWrite } from "../../fs/contained-write.js";
 import { resolveCandidatesLogPath, TRIAGE_CANDIDATES_LOG_REL_PATH } from "../cache-path.js";
 import { CandidatesLogError } from "./errors.js";
-/** Display/back-compat constant; resolution flows through resolveTriageCachePath (#1703). */
 export const AUDIT_LOG_REL_PATH = TRIAGE_CANDIDATES_LOG_REL_PATH;
 export { resolveCandidatesLogPath };
 const VALID_DECISIONS = new Set([
@@ -108,6 +108,32 @@ function resolveLogPath(projectRoot, override) {
     }
     return resolveCandidatesLogPath(projectRoot);
 }
+/**
+ * Containment root for candidates-log product writes (#3245).
+ * Prefer project root when the log is nested under it; otherwise parent dir
+ * (matches intake candidates-log parity for override paths outside the tree).
+ */
+function containmentRootForLog(projectRoot, logPath) {
+    const rootAbs = resolve(projectRoot);
+    const logAbs = resolve(logPath);
+    const parent = dirname(logAbs);
+    mkdirSync(parent, { recursive: true });
+    const rel = relative(rootAbs, logAbs);
+    if (rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel)) {
+        return rootAbs;
+    }
+    return resolve(parent);
+}
+/** #3245 / #2980: product append refuses leaf symlink follow (in-tree or escape). */
+function appendAuditLine(projectRoot, logPath, line) {
+    const root = containmentRootForLog(projectRoot, logPath);
+    containedWrite({
+        root,
+        target: logPath,
+        data: line.endsWith("\n") ? line : `${line}\n`,
+        mode: "append",
+    });
+}
 function stableStringify(entry) {
     const sortedKeys = Object.keys(entry).sort();
     const sorted = {};
@@ -186,8 +212,7 @@ export function createCandidatesLog(defaultProjectRoot) {
         append(entry, options) {
             validateEntry(entry);
             const logPath = resolveLogPath(defaultProjectRoot, options?.path);
-            mkdirSync(join(logPath, ".."), { recursive: true });
-            appendFileSync(logPath, `${stableStringify(entry)}\n`, { encoding: "utf8" });
+            appendAuditLine(defaultProjectRoot, logPath, `${stableStringify(entry)}\n`);
             return entry.decision_id;
         },
         latestDecision(issueNumber, repo, options) {
@@ -225,7 +250,13 @@ export function rollbackAuditEntry(decisionId, projectRoot, logPathOverride) {
         }
     }
     if (removed) {
-        writeFileSync(path, kept.join(""), { encoding: "utf8" });
+        // #3245: replace rewrite also refuses leaf symlink follow.
+        containedWrite({
+            root: containmentRootForLog(projectRoot, path),
+            target: path,
+            data: kept.join(""),
+            mode: "replace",
+        });
     }
     return removed;
 }