@deftai/directive-core 0.99.0 → 0.101.0

package/dist/finish-loop/pr-finish-loop.d.ts

@@ -7,6 +7,7 @@
  * - CLEAN + bot merge allowed + --merge → optional wait-mergeable-and-merge
  * - Missing grants → fail closed BLOCKED
  */
+import { type EnforceMergeApprovalHeadInput, type MergeApprovalHeadResult } from "../policy/merge-approval-head.js";
 import { evaluateAgentMerge } from "../policy/require-human-merge.js";
 import type { WatchOptions, WatchResult } from "../pr-watch/types.js";
 import { type PrFinishLoopResult } from "./types.js";
@@ -20,13 +21,23 @@ export interface PrFinishLoopOptions {
     /** Attempt merge when CLEAN and policy allows (default false). */
     readonly merge?: boolean;
     readonly skipGrantGate?: boolean;
+    /** Skip #3235 head-bound plan:approved gate (tests). */
+    readonly skipMergeApprovalHeadGate?: boolean;
     readonly env?: Readonly<Record<string, string | undefined>>;
     readonly now?: Date;
     /** Inject watch for tests. */
     readonly watchFn?: (prNumber: number, repo: string | null, options?: WatchOptions) => WatchResult;
-    /** Inject merge cascade for tests; returns exit code. */
-    readonly mergeFn?: (prNumber: number, repo: string | null) => number;
+    /**
+     * Inject merge cascade for tests; returns exit code.
+     * Optional `matchHeadCommit` pins the merge to the gated head (#3235).
+     */
+    readonly mergeFn?: (prNumber: number, repo: string | null, options?: {
+        readonly matchHeadCommit?: string | null;
+    }) => number;
     readonly agentMergeFn?: typeof evaluateAgentMerge;
+    readonly mergeApprovalHeadFn?: (input: EnforceMergeApprovalHeadInput) => MergeApprovalHeadResult;
+    /** Inject live HEAD fetch (tests); defaults to REST pulls head.sha. */
+    readonly fetchPrHeadShaFn?: (prNumber: number, repo: string | null) => string | null;
     readonly writeProgress?: boolean;
     readonly iteration?: number;
 }

package/dist/finish-loop/pr-finish-loop.js

@@ -7,6 +7,7 @@
  * - CLEAN + bot merge allowed + --merge → optional wait-mergeable-and-merge
  * - Missing grants → fail closed BLOCKED
  */
+import { disablePullRequestAutoMerge, enforceMergeApprovalHead, fetchPrHeadShaRest, } from "../policy/merge-approval-head.js";
 import { evaluateAgentMerge } from "../policy/require-human-merge.js";
 import { EXIT_CLEAN, EXIT_NEW_P0_P1, EXIT_TERMINAL_ERROR, VERDICT_CLEAN, VERDICT_NEW_P0_P1, } from "../pr-watch/constants.js";
 import { watch } from "../pr-watch/watch.js";
@@ -70,7 +71,9 @@ export function runPrFinishLoop(options) {
     }
     // --- pr:watch ---
     const watchFn = options.watchFn ?? watch;
-    const repo = options.repo ?? process.env.GH_REPO ?? null;
+    // Prefer explicit repo; GH_REPO next. Repo is required for head-bound approval
+    // scoping when plan:approved records exist (#3235 cross-repo collision).
+    const repo = options.repo ?? process.env.GH_REPO ?? process.env.GITHUB_REPOSITORY ?? null;
     let watchResult;
     try {
         watchResult = watchFn(prNumber, repo, {
@@ -129,6 +132,61 @@ export function runPrFinishLoop(options) {
             grantId: null,
         };
     }
+    // #3235: head-bound plan:approved vs LIVE PR HEAD (before merge path).
+    // Always re-fetch HEAD. Never fall back to the watch snapshot: a failed live
+    // read + snapshot A would retain auto-merge while GitHub head is B.
+    if (options.skipMergeApprovalHeadGate !== true) {
+        const fetchHead = options.fetchPrHeadShaFn ?? fetchPrHeadShaRest;
+        const liveHead = fetchHead(prNumber, repo);
+        if (liveHead === null || liveHead.trim() === "") {
+            disablePullRequestAutoMerge(prNumber, repo);
+            const message = `pr:finish-loop ACTION_REQUIRED on PR #${prNumber}: cannot read live HEAD ` +
+                "after CLEAN; auto-merge disabled (fail closed, #3235).";
+            log("merge", "stale-merge-approval", message);
+            return {
+                exitCode: EXIT_ACTION_REQUIRED,
+                haltReason: "stale-merge-approval",
+                message,
+                prNumber,
+                watchVerdict: VERDICT_CLEAN,
+                mergeAttempted: false,
+                mergeSkippedReason: "stale-merge-approval",
+                grantId: null,
+            };
+        }
+        const headGateFn = options.mergeApprovalHeadFn ?? enforceMergeApprovalHead;
+        const headGate = headGateFn({
+            prNumber,
+            repo,
+            projectRoot,
+            currentHeadSha: liveHead,
+            disableAutoMergeOnDeny: true,
+        });
+        if (!headGate.allowed) {
+            const message = [
+                `pr:finish-loop ACTION_REQUIRED on PR #${prNumber}: stale or unbound merge approval.`,
+                headGate.message,
+                headGate.recovery ?? "",
+            ]
+                .filter((line) => line.length > 0)
+                .join("\n");
+            log("merge", "stale-merge-approval", message, {
+                approved_head_sha: headGate.approved_head_sha,
+                current_head_sha: headGate.current_head_sha,
+                auto_merge_disabled: headGate.auto_merge_disabled,
+            });
+            return {
+                exitCode: EXIT_ACTION_REQUIRED,
+                haltReason: "stale-merge-approval",
+                message,
+                prNumber,
+                watchVerdict: VERDICT_CLEAN,
+                mergeAttempted: false,
+                mergeSkippedReason: "stale-merge-approval",
+                grantId: null,
+            };
+        }
+    }
     // CLEAN path
     if (options.merge !== true) {
         const message = `pr:finish-loop CLEAN on PR #${prNumber}. Merge not requested ` +
@@ -165,12 +223,62 @@ export function runPrFinishLoop(options) {
             grantId: null,
         };
     }
-    // Optional merge when policy allows
+    // Optional merge when policy allows — re-fetch live HEAD (not watch snapshot)
+    // and pin matchHeadCommit (#3235 TOCTOU).
     if (options.mergeFn !== undefined) {
-        const rc = options.mergeFn(prNumber, repo);
+        const fetchHead = options.fetchPrHeadShaFn ?? fetchPrHeadShaRest;
+        const liveHead = fetchHead(prNumber, repo);
+        if (options.skipMergeApprovalHeadGate !== true) {
+            if (liveHead === null || liveHead.trim() === "") {
+                disablePullRequestAutoMerge(prNumber, repo);
+                const message = `pr:finish-loop ACTION_REQUIRED on PR #${prNumber}: cannot read live HEAD ` +
+                    "before merge; auto-merge disabled (fail closed, #3235).";
+                log("merge", "stale-merge-approval", message);
+                return {
+                    exitCode: EXIT_ACTION_REQUIRED,
+                    haltReason: "stale-merge-approval",
+                    message,
+                    prNumber,
+                    watchVerdict: VERDICT_CLEAN,
+                    mergeAttempted: false,
+                    mergeSkippedReason: "stale-merge-approval",
+                    grantId: null,
+                };
+            }
+            const headGateFn = options.mergeApprovalHeadFn ?? enforceMergeApprovalHead;
+            const recheck = headGateFn({
+                prNumber,
+                repo,
+                projectRoot,
+                currentHeadSha: liveHead,
+                disableAutoMergeOnDeny: true,
+            });
+            if (!recheck.allowed) {
+                const message = [
+                    `pr:finish-loop ACTION_REQUIRED on PR #${prNumber}: stale merge approval at merge time.`,
+                    recheck.message,
+                    recheck.recovery ?? "",
+                ]
+                    .filter((line) => line.length > 0)
+                    .join("\n");
+                log("merge", "stale-merge-approval", message);
+                return {
+                    exitCode: EXIT_ACTION_REQUIRED,
+                    haltReason: "stale-merge-approval",
+                    message,
+                    prNumber,
+                    watchVerdict: VERDICT_CLEAN,
+                    mergeAttempted: false,
+                    mergeSkippedReason: "stale-merge-approval",
+                    grantId: null,
+                };
+            }
+        }
+        const pinnedHead = liveHead;
+        const rc = options.mergeFn(prNumber, repo, { matchHeadCommit: pinnedHead });
         if (rc === 0) {
             const message = `pr:finish-loop MERGED PR #${prNumber}`;
-            log("merge", "merged", message);
+            log("merge", "merged", message, { matchHeadCommit: pinnedHead });
             return {
                 exitCode: EXIT_OK,
                 haltReason: "merged",
@@ -182,7 +290,10 @@ export function runPrFinishLoop(options) {
                 grantId: null,
             };
         }
-        const message = `pr:finish-loop merge attempt failed exit=${rc} for PR #${prNumber}`;
+        // Pin mismatch / merge fail: revoke auto-merge so unapproved head cannot land.
+        disablePullRequestAutoMerge(prNumber, repo);
+        const message = `pr:finish-loop merge attempt failed exit=${rc} for PR #${prNumber}; ` +
+            "disabled auto-merge after pinned-merge failure (#3235).";
         log("merge", "error", message);
         return {
             exitCode: EXIT_BLOCKED,

package/dist/finish-loop/types.d.ts

@@ -8,7 +8,7 @@ export declare const EXIT_OK = 0;
 export declare const EXIT_ACTION_REQUIRED = 1;
 /** BLOCKED (grant/gate), ERRORED, TIMEOUT, config. */
 export declare const EXIT_BLOCKED = 2;
-export type FinishLoopHaltReason = "empty-queue" | "grant-missing" | "grant-expired" | "grant-deny" | "gate-deny" | "max-iterations" | "require-human-merge" | "address-findings" | "agent-implement" | "clean" | "merged" | "error";
+export type FinishLoopHaltReason = "empty-queue" | "grant-missing" | "grant-expired" | "grant-deny" | "gate-deny" | "max-iterations" | "require-human-merge" | "stale-merge-approval" | "address-findings" | "agent-implement" | "clean" | "merged" | "error";
 export type FinishLoopPhase = "gate" | "queue-scan" | "implement" | "pr-open" | "pr-watch" | "address" | "merge" | "halt";
 export interface FinishLoopProgressLine {
     readonly schemaVersion: 1;

package/dist/hooks/dispatcher.d.ts

@@ -142,11 +142,15 @@ export declare function decideHook(input: HookDispatchInput, seams?: HookPolicyS
 /**
  * Render host-facing hook output.
  *
- * Cursor deposits use `failClosed: true`. Cursor treats empty/null stdout as a
- * hook failure and blocks the tool — so Cursor allows must emit explicit
- * `{"permission":"allow"}`. Other hosts keep empty allow so the host permission
- * flow is unchanged — except session.start / session.compact soft re-bind
- * injection (#3171), which surfaces checklist text without a write tool.
+ * Cursor deposits use `failClosed: true` with a tool.before timeout above the
+ * gated-ritual / live agent-hook readiness budget
+ * (`CURSOR_TOOL_BEFORE_TIMEOUT_SECONDS` in init-deposit/agent-hooks; #3246).
+ * Cursor treats empty/null stdout (or a host timeout kill) as a hook failure
+ * and blocks the tool — so Cursor allows must emit explicit
+ * `{"permission":"allow"}` within the deposit timeout. Other hosts keep empty
+ * allow so the host permission flow is unchanged — except session.start /
+ * session.compact soft re-bind injection (#3171), which surfaces checklist
+ * text without a write tool.
  *
  * Cursor stdout always includes `code` (stable machine-readable decision code)
  * so agents can distinguish policy denials from host-integration failures

package/dist/hooks/dispatcher.js

@@ -184,10 +184,10 @@ export function isAllowlistedAssistScratchPath(projectRoot, targetPath) {
 export function isAssistScratchWrite(projectRoot, targetPath, payload, environ = process.env) {
     if (!isAllowlistedAssistScratchPath(projectRoot, targetPath))
         return false;
-    // Structural classification only — compose with #3080 ephemeral markers.
+    // Structural classification only — compose with #3080 / #3259 ephemeral markers.
     if (isAssistPosture(payload, environ))
         return true;
-    if (isEphemeralSpawn(payload))
+    if (isEphemeralSpawn(payload, environ))
         return true;
     return false;
 }
@@ -656,14 +656,18 @@ function inspectMutationGates(input, toolName, seams, options) {
         if (!outsideRoot || isSpawnTool(toolName)) {
             let proposedPathHint;
             if (isSpawnTool(toolName)) {
-                // Multi-path recovery for implement-class spawns (#3080 AC4).
+                // Multi-path recovery for implement-class spawns (#3080 AC4 / #3259 honesty).
+                // Structural markers only — free-text prompt brackets are not sufficient.
                 proposedPathHint =
                     " Recovery: (1) Product implementation — run `deft scope:activate -- <path>` " +
                         "for the approved xBRIEF, then re-run the pre-start_agent gate stack. " +
-                        "(2) Read-only research — spawn with `subagent_type`/`worker_role` explore. " +
-                        "(3) Ephemeral docs/analysis — spawn with `worker_role: ephemeral` " +
-                        "(aliases: docs, assist; see commands.md), or continue in the parent without " +
-                        "a lifecycle story. Do not invent a fake scope only to satisfy this gate.";
+                        "(2) Read-only research — spawn with structural `subagent_type`/`worker_role` explore. " +
+                        "(3) Ephemeral docs/local-dev — set structural tool fields " +
+                        "`worker_role`/`subagent_type` ∈ {ephemeral, docs, assist} (hosts that support them), " +
+                        "or set session assist (`DEFT_SESSION_POSTURE=assist` or `DEFT_HOOK_ASSIST=1`), " +
+                        "or run local-dev Shell (`docker compose` / `pnpm dev`) in the parent without a " +
+                        "lifecycle story. Free-text markers such as `[worker_role: ephemeral]` in the " +
+                        "prompt are NOT sufficient. Do not invent a fake scope only to satisfy this gate.";
             }
             else if (options.proposedLifecycleExempt &&
                 relTarget !== null &&
@@ -895,9 +899,9 @@ export function decideHook(input, seams = {}) {
                 scopePath: null,
             };
         }
-        // Ephemeral/docs/assist: write-capable non-lifecycle spawn; no active xBRIEF (#3080).
-        // Does not authorize push/merge/deploy — those remain on shell/MCP matchers.
-        if (isEphemeralSpawn(input.payload)) {
+        // Ephemeral/docs/assist (+ session assist env #3259): non-lifecycle spawn;
+        // no active xBRIEF. Does not authorize push/merge/deploy — shell/MCP matchers.
+        if (isEphemeralSpawn(input.payload, environ)) {
             return {
                 verdict: "allow",
                 code: "spawn-ephemeral-ready",
@@ -951,11 +955,15 @@ function softAgentsRebindWireText(decision) {
 /**
  * Render host-facing hook output.
  *
- * Cursor deposits use `failClosed: true`. Cursor treats empty/null stdout as a
- * hook failure and blocks the tool — so Cursor allows must emit explicit
- * `{"permission":"allow"}`. Other hosts keep empty allow so the host permission
- * flow is unchanged — except session.start / session.compact soft re-bind
- * injection (#3171), which surfaces checklist text without a write tool.
+ * Cursor deposits use `failClosed: true` with a tool.before timeout above the
+ * gated-ritual / live agent-hook readiness budget
+ * (`CURSOR_TOOL_BEFORE_TIMEOUT_SECONDS` in init-deposit/agent-hooks; #3246).
+ * Cursor treats empty/null stdout (or a host timeout kill) as a hook failure
+ * and blocks the tool — so Cursor allows must emit explicit
+ * `{"permission":"allow"}` within the deposit timeout. Other hosts keep empty
+ * allow so the host permission flow is unchanged — except session.start /
+ * session.compact soft re-bind injection (#3171), which surfaces checklist
+ * text without a write tool.
  *
  * Cursor stdout always includes `code` (stable machine-readable decision code)
  * so agents can distinguish policy denials from host-integration failures

package/dist/hooks/readonly.d.ts

@@ -13,9 +13,12 @@ export declare function isExploreSpawn(payload: unknown): boolean;
  */
 export declare function isAssistPosture(payload: unknown, environ?: NodeJS.ProcessEnv): boolean;
 /**
- * Ephemeral / assist / docs spawns skip active-xBRIEF implementation gates (#3080).
+ * Ephemeral / assist / docs spawns skip active-xBRIEF implementation gates (#3080 / #3259).
  * True only with an explicit allowlisted marker. Absent marker → false (fail closed).
- * When an ephemeral marker conflicts with implement envelope signals, implement wins.
+ * Markers: structural `worker_role`/`subagent_type` ∈ {ephemeral,docs,assist}, OR
+ * session assist env (`DEFT_SESSION_POSTURE` assist-set / `DEFT_HOOK_ASSIST=1`) for spawn.
+ * Free-text prompt strings are never classified. When a marker conflicts with implement
+ * envelope signals, implement wins.
  */
-export declare function isEphemeralSpawn(payload: unknown): boolean;
+export declare function isEphemeralSpawn(payload: unknown, environ?: NodeJS.ProcessEnv): boolean;
 //# sourceMappingURL=readonly.d.ts.map

package/dist/hooks/readonly.js

@@ -123,8 +123,8 @@ export function isAssistPosture(payload, environ = process.env) {
     if (posture !== null && ASSIST_POSTURE_MARKERS.has(normalizePostureToken(posture))) {
         return true;
     }
-    // Shared taxonomy with #3080 ephemeral spawn markers.
-    if (isEphemeralSpawn(payload))
+    // Shared taxonomy with #3080 / #3259 ephemeral spawn markers.
+    if (isEphemeralSpawn(payload, environ))
         return true;
     return false;
 }
@@ -176,34 +176,53 @@ function hasImplementConflictSignal(toolInput, input) {
     return false;
 }
 /**
- * Ephemeral / assist / docs spawns skip active-xBRIEF implementation gates (#3080).
+ * Session assist env tokens that count as structural ephemeral markers for spawn (#3259).
+ * Reuses #1802 ASSIST_POSTURE_MARKERS / DEFT_HOOK_ASSIST — not free-text NLP.
+ */
+function hasSessionAssistEphemeralEnv(environ) {
+    const envPosture = (environ[ASSIST_SESSION_POSTURE_ENV] ?? "").trim();
+    if (envPosture.length > 0 && ASSIST_POSTURE_MARKERS.has(normalizePostureToken(envPosture))) {
+        return true;
+    }
+    return envTruthy(environ, "DEFT_HOOK_ASSIST");
+}
+/**
+ * Ephemeral / assist / docs spawns skip active-xBRIEF implementation gates (#3080 / #3259).
  * True only with an explicit allowlisted marker. Absent marker → false (fail closed).
- * When an ephemeral marker conflicts with implement envelope signals, implement wins.
+ * Markers: structural `worker_role`/`subagent_type` ∈ {ephemeral,docs,assist}, OR
+ * session assist env (`DEFT_SESSION_POSTURE` assist-set / `DEFT_HOOK_ASSIST=1`) for spawn.
+ * Free-text prompt strings are never classified. When a marker conflicts with implement
+ * envelope signals, implement wins.
  */
-export function isEphemeralSpawn(payload) {
+export function isEphemeralSpawn(payload, environ = process.env) {
     const input = record(payload);
-    if (input === null)
-        return false;
-    const toolInput = toolInputRecord(input) ?? input;
-    const subagentType = fieldString(toolInput, "subagent_type") ??
-        fieldString(toolInput, "subagentType") ??
-        fieldString(input, "subagent_type") ??
-        fieldString(input, "subagentType");
-    const workerRole = fieldString(toolInput, "worker_role") ??
-        fieldString(toolInput, "workerRole") ??
-        fieldString(input, "worker_role") ??
-        fieldString(input, "workerRole");
-    const marker = (workerRole !== null && EPHEMERAL_ROLE_MARKERS.has(workerRole.toLowerCase())
-        ? workerRole.toLowerCase()
-        : null) ??
-        (subagentType !== null && EPHEMERAL_ROLE_MARKERS.has(subagentType.toLowerCase())
-            ? subagentType.toLowerCase()
-            : null);
-    if (marker === null)
+    const toolInput = input !== null ? (toolInputRecord(input) ?? input) : null;
+    let hasMarker = false;
+    if (input !== null && toolInput !== null) {
+        const subagentType = fieldString(toolInput, "subagent_type") ??
+            fieldString(toolInput, "subagentType") ??
+            fieldString(input, "subagent_type") ??
+            fieldString(input, "subagentType");
+        const workerRole = fieldString(toolInput, "worker_role") ??
+            fieldString(toolInput, "workerRole") ??
+            fieldString(input, "worker_role") ??
+            fieldString(input, "workerRole");
+        if ((workerRole !== null && EPHEMERAL_ROLE_MARKERS.has(workerRole.toLowerCase())) ||
+            (subagentType !== null && EPHEMERAL_ROLE_MARKERS.has(subagentType.toLowerCase()))) {
+            hasMarker = true;
+        }
+    }
+    // #3259 D1-B: session assist env is a structural ephemeral marker for spawn tools.
+    // Call sites gate "spawn only"; this helper stays pure classification.
+    if (!hasMarker && hasSessionAssistEphemeralEnv(environ)) {
+        hasMarker = true;
+    }
+    if (!hasMarker)
         return false;
-    // Implement signals win over ephemeral markers (fail closed).
-    if (hasImplementConflictSignal(toolInput, input))
+    // Implement signals win over ephemeral markers including session assist env (fail closed).
+    if (input !== null && toolInput !== null && hasImplementConflictSignal(toolInput, input)) {
         return false;
+    }
     return true;
 }
 //# sourceMappingURL=readonly.js.map

package/dist/index.d.ts

@@ -35,6 +35,7 @@ export * as intake from "./intake/index.js";
 export * as layout from "./layout/index.js";
 export * as legacyBridge from "./legacy-bridge/index.js";
 export * as lifecycle from "./lifecycle/index.js";
+export * as literalAcceptance from "./literal-acceptance/index.js";
 export * as metrics from "./metrics/index.js";
 export * as orchestration from "./orchestration/index.js";
 export * as packs from "./packs/index.js";
@@ -47,12 +48,14 @@ export * as prMonitor from "./pr-monitor/index.js";
 export * as prProtectedIssues from "./pr-protected-issues/index.js";
 export * as prWaitMergeable from "./pr-wait-mergeable/index.js";
 export * as preflight from "./preflight/index.js";
+export * as productFirstDoneGate from "./product-first-done-gate/index.js";
 export * as release from "./release/index.js";
 export * as releaseE2e from "./release-e2e/index.js";
 export * as releasePublish from "./release-publish/index.js";
 export * as releaseRollback from "./release-rollback/index.js";
 export * as render from "./render/index.js";
 export * as resolution from "./resolution/index.js";
+export * as runSummary from "./run-summary/index.js";
 export * as scm from "./scm/index.js";
 export * as scope from "./scope/index.js";
 export * as scopeProvenance from "./scope-provenance/index.js";

package/dist/index.js

@@ -36,6 +36,7 @@ export * as intake from "./intake/index.js";
 export * as layout from "./layout/index.js";
 export * as legacyBridge from "./legacy-bridge/index.js";
 export * as lifecycle from "./lifecycle/index.js";
+export * as literalAcceptance from "./literal-acceptance/index.js";
 export * as metrics from "./metrics/index.js";
 export * as orchestration from "./orchestration/index.js";
 export * as packs from "./packs/index.js";
@@ -48,12 +49,14 @@ export * as prMonitor from "./pr-monitor/index.js";
 export * as prProtectedIssues from "./pr-protected-issues/index.js";
 export * as prWaitMergeable from "./pr-wait-mergeable/index.js";
 export * as preflight from "./preflight/index.js";
+export * as productFirstDoneGate from "./product-first-done-gate/index.js";
 export * as release from "./release/index.js";
 export * as releaseE2e from "./release-e2e/index.js";
 export * as releasePublish from "./release-publish/index.js";
 export * as releaseRollback from "./release-rollback/index.js";
 export * as render from "./render/index.js";
 export * as resolution from "./resolution/index.js";
+export * as runSummary from "./run-summary/index.js";
 export * as scm from "./scm/index.js";
 export * as scope from "./scope/index.js";
 export * as scopeProvenance from "./scope-provenance/index.js";

package/dist/init-deposit/agent-hooks.d.ts

@@ -5,6 +5,26 @@ export { DIRECT_WRITE_HOOK_MATCHER, MCP_HOOK_MATCHER, SHELL_HOOK_MATCHER, SPAWN_
 export declare const DEFT_HOOK_COMMAND_MARKER = "deft-hook";
 export declare const LEGACY_DEFT_HOOK_COMMAND_MARKER = "deft hook:dispatch";
 export declare const AGENT_HOOK_PATHS: readonly [".claude/settings.json", ".grok/hooks/deft.json", ".cursor/hooks.json", ".codex/hooks.json"];
+/**
+ * Cursor session.start / session.compact deposit timeout (seconds).
+ * Lightweight ceremony paths — keep tight so stalled hooks fail fast.
+ */
+export declare const CURSOR_SESSION_HOOK_TIMEOUT_SECONDS = 5;
+/**
+ * Cursor preToolUse (tool.before) deposit timeout (seconds).
+ *
+ * Mutation tool.before runs `inspectMutationGates` → gated
+ * `verifySessionRitual`, which re-runs non-cacheable agent-hook readiness on
+ * every boundary. Live readiness alone has a multi-host fixture ceiling of
+ * ~12s (`content/contracts/agent-hook-readiness.md`); the historical deposit
+ * default of 5s was below that budget. Under Cursor `failClosed: true`, a
+ * host timeout kill surfaces as opaque exit-1 with no Directive decision
+ * code (#3246 / related #2864). Keep this above the readiness ceiling plus
+ * dispatch overhead so allow/deny can render within the host budget.
+ */
+export declare const CURSOR_TOOL_BEFORE_TIMEOUT_SECONDS = 30;
+/** Nested Claude/Grok/Codex command-hook default timeout (seconds). */
+export declare const NESTED_HOOK_TIMEOUT_SECONDS = 5;
 export type AgentHookPath = (typeof AGENT_HOOK_PATHS)[number];
 export type AgentHookRegistrationStatus = "healthy" | "disabled" | "missing" | "drifted";
 /** Whether the host receives a compact/resume hook deposit (#2113). */

package/dist/init-deposit/agent-hooks.js

@@ -13,6 +13,26 @@ export const AGENT_HOOK_PATHS = [
     ".cursor/hooks.json",
     ".codex/hooks.json",
 ];
+/**
+ * Cursor session.start / session.compact deposit timeout (seconds).
+ * Lightweight ceremony paths — keep tight so stalled hooks fail fast.
+ */
+export const CURSOR_SESSION_HOOK_TIMEOUT_SECONDS = 5;
+/**
+ * Cursor preToolUse (tool.before) deposit timeout (seconds).
+ *
+ * Mutation tool.before runs `inspectMutationGates` → gated
+ * `verifySessionRitual`, which re-runs non-cacheable agent-hook readiness on
+ * every boundary. Live readiness alone has a multi-host fixture ceiling of
+ * ~12s (`content/contracts/agent-hook-readiness.md`); the historical deposit
+ * default of 5s was below that budget. Under Cursor `failClosed: true`, a
+ * host timeout kill surfaces as opaque exit-1 with no Directive decision
+ * code (#3246 / related #2864). Keep this above the readiness ceiling plus
+ * dispatch overhead so allow/deny can render within the host budget.
+ */
+export const CURSOR_TOOL_BEFORE_TIMEOUT_SECONDS = 30;
+/** Nested Claude/Grok/Codex command-hook default timeout (seconds). */
+export const NESTED_HOOK_TIMEOUT_SECONDS = 5;
 function object(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -90,7 +110,7 @@ function nestedGroup(host, event, matcher) {
             {
                 type: "command",
                 command: command(host, event),
-                timeout: 5,
+                timeout: NESTED_HOOK_TIMEOUT_SECONDS,
             },
         ],
     };
@@ -154,35 +174,47 @@ function mergeCursorConfig(config, path) {
     const session = eventArray(hooks, "sessionStart", path).filter((entry) => !isManagedCursorEntry(entry));
     const preTool = eventArray(hooks, "preToolUse", path).filter((entry) => !isManagedCursorEntry(entry));
     const preCompact = eventArray(hooks, "preCompact", path).filter((entry) => !isManagedCursorEntry(entry));
-    hooks.sessionStart = [...session, { command: command("cursor", "session.start"), timeout: 5 }];
+    hooks.sessionStart = [
+        ...session,
+        {
+            command: command("cursor", "session.start"),
+            timeout: CURSOR_SESSION_HOOK_TIMEOUT_SECONDS,
+        },
+    ];
     hooks.preToolUse = [
         ...preTool,
         {
             command: command("cursor", "tool.before"),
             matcher: DIRECT_WRITE_HOOK_MATCHER,
             failClosed: true,
-            timeout: 5,
+            timeout: CURSOR_TOOL_BEFORE_TIMEOUT_SECONDS,
         },
         {
             command: command("cursor", "tool.before"),
             matcher: SPAWN_HOOK_MATCHER,
             failClosed: true,
-            timeout: 5,
+            timeout: CURSOR_TOOL_BEFORE_TIMEOUT_SECONDS,
         },
         {
             command: command("cursor", "tool.before"),
             matcher: SHELL_HOOK_MATCHER,
             failClosed: true,
-            timeout: 5,
+            timeout: CURSOR_TOOL_BEFORE_TIMEOUT_SECONDS,
         },
         {
             command: command("cursor", "tool.before"),
             matcher: MCP_HOOK_MATCHER,
             failClosed: true,
-            timeout: 5,
+            timeout: CURSOR_TOOL_BEFORE_TIMEOUT_SECONDS,
+        },
+    ];
+    hooks.preCompact = [
+        ...preCompact,
+        {
+            command: command("cursor", "session.compact"),
+            timeout: CURSOR_SESSION_HOOK_TIMEOUT_SECONDS,
         },
     ];
-    hooks.preCompact = [...preCompact, { command: command("cursor", "session.compact"), timeout: 5 }];
     return { ...config, version: 1, hooks };
 }
 function writeJsonIfChanged(projectRoot, path, payload) {
@@ -341,6 +373,14 @@ function hasNestedRegistration(config, host, options = {}) {
     return (preCompact.some((entry) => nestedCommands(entry).includes(compactCommand)) &&
         postCompact.some((entry) => nestedCommands(entry).includes(compactCommand)));
 }
+function isCursorToolBeforeEntry(value, matcher) {
+    const hook = object(value);
+    return (hook?.command === command("cursor", "tool.before") &&
+        hook.matcher === matcher &&
+        hook.failClosed === true &&
+        // #3246: budget must cover gated ritual + live agent-hook readiness.
+        hook.timeout === CURSOR_TOOL_BEFORE_TIMEOUT_SECONDS);
+}
 function hasCursorRegistration(config) {
     const hooks = object(config.hooks);
     if (hooks === null || config.version !== 1)
@@ -349,30 +389,10 @@ function hasCursorRegistration(config) {
     const preTool = Array.isArray(hooks.preToolUse) ? hooks.preToolUse : [];
     const preCompact = Array.isArray(hooks.preCompact) ? hooks.preCompact : [];
     return (session.some((entry) => object(entry)?.command === command("cursor", "session.start")) &&
-        preTool.some((entry) => {
-            const hook = object(entry);
-            return (hook?.command === command("cursor", "tool.before") &&
-                hook.matcher === DIRECT_WRITE_HOOK_MATCHER &&
-                hook.failClosed === true);
-        }) &&
-        preTool.some((entry) => {
-            const hook = object(entry);
-            return (hook?.command === command("cursor", "tool.before") &&
-                hook.matcher === SPAWN_HOOK_MATCHER &&
-                hook.failClosed === true);
-        }) &&
-        preTool.some((entry) => {
-            const hook = object(entry);
-            return (hook?.command === command("cursor", "tool.before") &&
-                hook.matcher === SHELL_HOOK_MATCHER &&
-                hook.failClosed === true);
-        }) &&
-        preTool.some((entry) => {
-            const hook = object(entry);
-            return (hook?.command === command("cursor", "tool.before") &&
-                hook.matcher === MCP_HOOK_MATCHER &&
-                hook.failClosed === true);
-        }) &&
+        preTool.some((entry) => isCursorToolBeforeEntry(entry, DIRECT_WRITE_HOOK_MATCHER)) &&
+        preTool.some((entry) => isCursorToolBeforeEntry(entry, SPAWN_HOOK_MATCHER)) &&
+        preTool.some((entry) => isCursorToolBeforeEntry(entry, SHELL_HOOK_MATCHER)) &&
+        preTool.some((entry) => isCursorToolBeforeEntry(entry, MCP_HOOK_MATCHER)) &&
         preCompact.some((entry) => object(entry)?.command === command("cursor", "session.compact")));
 }
 /** Read-only registration probe shared by verify and doctor. */

package/dist/init-deposit/gitignore.js

@@ -30,6 +30,8 @@ export const CANONICAL_GITIGNORE_BASELINE = [
     ".deft/ritual-state.json",
     ".deft/last-session.json",
     ".deft/routing.local.json",
+    // #3282: opt-in default run-summary JSONL at repo root (collectible; must not dirty trees).
+    ".deft-run-summary.json",
     // Temporary test/local kill-switch — must stay untracked (#3039).
     DEFT_DIRECTIVE_DISABLE_GITIGNORE_LINE,
     "vbrief/.triage-cache/candidates.jsonl",