@deftai/directive-core 0.99.0 → 0.100.0

package/dist/doctor/main.js

@@ -1,22 +1,18 @@
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { VBRIEF_VERSION } from "@deftai/directive-types";
 import { evaluate as evaluateAgentsMdAdvisory } from "../agents-md-advisory/evaluate.js";
 import { evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, } from "../check/consumer-gate-integrity.js";
 import { contentRoot } from "../content-root.js";
-import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { DEFT_DIRECTIVE_DISABLE_FLAG_NAME, DEFT_DIRECTIVE_DISABLE_STATUS, DEFT_DIRECTIVE_DISABLE_TRACKED_WARNING, detectDeftDirectiveDisable, formatDeftDirectiveDisableMessage, isDeftDirectiveDisableActive, } from "../policy/deft-directive-disable.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";
 import { describeShadowedPlanExtension, detectShadowedPlanExtensions, } from "../policy/plan-extensions.js";
 import { loadProjectDefinition } from "../policy/resolve.js";
 import { checkLocalEngineIntegrity, classify, detectPackageManager, evaluateSkew, reconcileVersions, plan as resolvePlan, } from "../resolution/index.js";
-import { classifyXbriefSchemaDistance } from "../staleness-tickler/probe-xbrief.js";
 import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
 import { evaluateAgentHooks } from "../verify-env/agent-hooks.js";
 import { probeAgentHooksLive } from "../verify-env/agent-hooks-live-probe.js";
-import { readDeclaredArtifactVersion } from "../xbrief-migrate/transforms.js";
 import { agentsRefreshPlan, hasV3ManagedMarker } from "./agents-md.js";
-import { runChecks } from "./checks.js";
+import { checkXbriefEnvelopeMajorVersion, runChecks, XBRIEF_ENVELOPE_MAJOR_CHECK, XBRIEF_ENVELOPE_MIGRATE_COMMAND, } from "./checks.js";
 import { CONSUMER_FRAMEWORK_DIRS, EXPECTED_CONTENT_DIRS, EXPECTED_FRAMEWORK_DIRS, NETWORK_DISCLOSURE_LINE, PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE, TASKFILE_INCLUDE_SNIPPET, UV_INSTALL_URL, } from "./constants.js";
 import { decideThrottle, formatIsoZ, readState, renderDoctorStatusLine, writeState, } from "./doctor-state.js";
 import { formatAllowedFlagsHint, formatUnknownFlagsError, parseDoctorFlags } from "./flags.js";
@@ -33,8 +29,6 @@ import { runLocalSignpostChecks } from "./signpost-checks.js";
 import { classifyTaskfileInclude, formatGatesSurfaceDualRemediation, formatMissingIncludeSnippet, GATES_SURFACE_DEFT_REMEDIATION, includesBlockHasDeftTaskfile, resolveConsumerTaskfile, } from "./taskfile.js";
 import { defaultWhich } from "./which.js";
 const DEFAULT_RESOLUTION_PLATFORMS = ["linux", "darwin", "win32"];
-/** Next-action command for project-envelope behind-major (#2971). */
-const XBRIEF_ENVELOPE_MIGRATE_COMMAND = "deft migrate:xbrief";
 /**
  * Read the `packageManager` field (Corepack) from a project package.json, or
  * null when absent/unreadable. Lets the doctor detect a pnpm project that has
@@ -653,6 +647,11 @@ function runInstallIntegrityChecks(projectRoot, sink, addFinding, seams) {
             const name = String(entry.name ?? "install-integrity");
             const status = String(entry.status ?? "");
             const detail = String(entry.detail ?? "");
+            // Authoritative envelope-major emission is runXbriefEnvelopeVersionCheck
+            // (runs for framework repo + consumers). Skip install-integrity duplicate.
+            if (name === XBRIEF_ENVELOPE_MAJOR_CHECK) {
+                continue;
+            }
             if (status === "pass") {
                 sink.success(`${name}: pass`);
                 continue;
@@ -954,105 +953,99 @@ function runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFindin
     });
 }
 /**
- * Fail closed when PROJECT-DEFINITION under an xbrief/ layout still declares
- * envelope 0.6 while the framework schema is 0.8 (#2971). Greenfield (no
- * project definition yet) and current 0.8 envelopes pass. Unreadable paths
- * (test seams / permission) skip rather than false-positive fail. Behind-major
- * records `deft migrate:xbrief` as the next action — layout rename alone is not
- * enough. Distinct from deposited-schema (`stale-xbrief-schema-deposit`) which
- * must NOT route to migrate:xbrief when only framework schema files are stale.
+ * Fail closed when any scanned project xbrief lifecycle `*.xbrief.json` envelope
+ * declares a schema major behind the framework target (#2971 / #3243). Greenfield
+ * (no envelopes) skips. Behind-major records `deft migrate:xbrief` as the next
+ * action (hybrid in-place rewrite on already-xbrief trees — #3236). Distinct from
+ * deposited-schema (`stale-xbrief-schema-deposit`) which must NOT route to
+ * migrate:xbrief when only framework schema files are stale.
  */
 export function runXbriefEnvelopeVersionCheck(projectRoot, sink, addFinding, seams) {
-    const checkName = "xbrief-envelope-version";
-    const isFile = seams.isFile ?? ((p) => existsSync(p));
-    const readText = seams.readText ?? readTextSafe;
-    const targetVersion = VBRIEF_VERSION;
+    const checkName = XBRIEF_ENVELOPE_MAJOR_CHECK;
     if (seams.probeXbriefEnvelope) {
         const probe = seams.probeXbriefEnvelope(projectRoot);
         emitXbriefEnvelopeFinding(checkName, probe, sink, addFinding);
         return;
     }
-    let definitionPath;
-    try {
-        definitionPath = resolveProjectDefinitionPath(projectRoot);
-    }
-    catch {
-        // Pure vbrief/-only trees are already covered by layout migrate signposts.
-        const skipMessage = `${checkName}: skip -- legacy-only layout (use layout migrate first)`;
-        sink.info(skipMessage);
-        addFinding({
-            severity: "skip",
-            message: skipMessage,
-            check: checkName,
-            status: "skip",
-            reason: "legacy-only-layout",
-        });
-        return;
-    }
-    if (!isFile(definitionPath)) {
-        const skipMessage = `${checkName}: skip -- no PROJECT-DEFINITION yet (greenfield)`;
-        sink.info(skipMessage);
-        addFinding({
-            severity: "skip",
-            message: skipMessage,
-            check: checkName,
-            status: "skip",
-            reason: "no-project-definition",
-        });
-        return;
-    }
-    const text = readText(definitionPath);
-    if (text === null) {
-        // Unreadable path (permissions or injectable seams) is not proof of 0.6.
-        const skipMessage = `${checkName}: skip -- PROJECT-DEFINITION unreadable`;
+    const result = checkXbriefEnvelopeMajorVersion(projectRoot, {
+        ...(seams.readText ? { readText: seams.readText } : {}),
+        ...(seams.isFile ? { isFile: seams.isFile } : {}),
+        ...(seams.isDir ? { isDir: seams.isDir } : {}),
+    });
+    const data = (result.data ?? {});
+    const targetVersion = typeof data.target_version === "string"
+        ? data.target_version
+        : String(data.target_version ?? "");
+    const declaredFromData = data.declared_versions;
+    const declaredVersion = Array.isArray(declaredFromData)
+        ? (declaredFromData.find((v) => typeof v === "string") ?? null)
+        : null;
+    if (result.status === "skip") {
+        const skipMessage = `${checkName}: skip -- ${result.detail}`;
         sink.info(skipMessage);
         addFinding({
             severity: "skip",
             message: skipMessage,
             check: checkName,
             status: "skip",
-            reason: "unreadable",
+            reason: typeof data.reason === "string" ? data.reason : "skip",
+            target_version: targetVersion || undefined,
         });
         return;
     }
-    let declaredVersion = null;
-    try {
-        const parsed = JSON.parse(text);
-        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
-            declaredVersion = readDeclaredArtifactVersion(parsed);
-        }
-        else {
-            const skipMessage = `${checkName}: skip -- PROJECT-DEFINITION is not a JSON object`;
-            sink.info(skipMessage);
+    if (result.status === "pass") {
+        const status = typeof data.status === "string" ? data.status : "current";
+        if (status === "behind-minor") {
+            // Major-only check (#3243) does not fail closed, but surface an advisory
+            // when the shared scan observed behind-minor distance.
+            const warnMessage = `${checkName}: behind-minor -- ${result.detail}. Prefer \`${XBRIEF_ENVELOPE_MIGRATE_COMMAND}\` when convenient.`;
+            sink.warn(warnMessage);
             addFinding({
-                severity: "skip",
-                message: skipMessage,
+                severity: "warning",
+                message: warnMessage,
                 check: checkName,
-                status: "skip",
-                reason: "invalid-json-shape",
+                status: "behind-minor",
+                suggestion: XBRIEF_ENVELOPE_MIGRATE_COMMAND,
+                target_version: targetVersion || undefined,
+                next_command: XBRIEF_ENVELOPE_MIGRATE_COMMAND,
             });
             return;
         }
-    }
-    catch {
-        const skipMessage = `${checkName}: skip -- PROJECT-DEFINITION JSON parse failed`;
-        sink.info(skipMessage);
+        const okMessage = `${checkName}: ${result.detail}`;
+        sink.success(okMessage);
         addFinding({
             severity: "skip",
-            message: skipMessage,
+            message: okMessage,
             check: checkName,
-            status: "skip",
-            reason: "parse-error",
+            status: "current",
+            target_version: targetVersion || undefined,
         });
         return;
     }
-    const distance = classifyXbriefSchemaDistance(declaredVersion, targetVersion);
-    emitXbriefEnvelopeFinding(checkName, {
-        declaredVersion,
-        targetVersion,
-        distance,
-        stale: distance !== "current",
-    }, sink, addFinding);
+    // fail / error → behind-major fail closed (migratable 0.6 or non-migratable)
+    const status = typeof data.status === "string" ? data.status : "behind-major";
+    const nextCommand = typeof data.next_command === "string"
+        ? data.next_command
+        : data.next_command === null
+            ? null
+            : XBRIEF_ENVELOPE_MIGRATE_COMMAND;
+    const suggestion = typeof data.suggestion === "string"
+        ? data.suggestion
+        : (nextCommand ?? `set xBRIEFInfo.version to framework target`);
+    const message = `${checkName}: ${result.detail}`;
+    sink.error(message);
+    addFinding({
+        severity: "error",
+        message,
+        check: checkName,
+        status,
+        suggestion,
+        declared_version: declaredVersion,
+        target_version: targetVersion || undefined,
+        next_command: nextCommand,
+        sample_paths: data.sample_paths,
+        behind_major_count: data.behind_major_count,
+    });
 }
 function emitXbriefEnvelopeFinding(checkName, probe, sink, addFinding) {
     if (probe.distance === "current") {

package/dist/doctor/which.d.ts

@@ -1,3 +1,22 @@
-/** Default PATH lookup mirroring Python `shutil.which`. */
+export interface WhichAllOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    readonly exists?: (path: string) => boolean;
+    /** Optional executable predicate (defaults to file + X_OK on posix). */
+    readonly isExecutable?: (path: string) => boolean;
+}
+/**
+ * Enumerate every PATH match for `name` (PATH order, first = highest precedence).
+ * Pure PATH scan — no shell locator — so tests and win32/posix stay hermetic and
+ * gated ritual never executes a PATH-substituted `which`/`where` (#3233).
+ * Only files (posix: executable bit) are accepted — not bare directories.
+ */
+export declare function whichAllFromPath(name: string, options?: WhichAllOptions): string[];
+/**
+ * All PATH matches for `name` without shelling out (#3233 security).
+ * Alias of {@link whichAllFromPath} — never runs bare `which` / `where`.
+ */
+export declare function defaultWhichAll(name: string, options?: WhichAllOptions): string[];
+/** Default PATH lookup mirroring Python `shutil.which` (first match only). */
 export declare function defaultWhich(name: string): string | null;
 //# sourceMappingURL=which.d.ts.map

package/dist/doctor/which.js

@@ -1,5 +1,71 @@
 import { execFileSync } from "node:child_process";
-/** Default PATH lookup mirroring Python `shutil.which`. */
+import { accessSync, constants, existsSync, statSync } from "node:fs";
+import { posix, win32 } from "node:path";
+function defaultIsExecutable(path, platform) {
+    try {
+        const st = statSync(path);
+        // Directories named `deft` must not shadow later executables (#3233 Greptile).
+        if (st.isDirectory())
+            return false;
+        if (!st.isFile() && !st.isSymbolicLink())
+            return false;
+        if (platform === "win32") {
+            return true;
+        }
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Enumerate every PATH match for `name` (PATH order, first = highest precedence).
+ * Pure PATH scan — no shell locator — so tests and win32/posix stay hermetic and
+ * gated ritual never executes a PATH-substituted `which`/`where` (#3233).
+ * Only files (posix: executable bit) are accepted — not bare directories.
+ */
+export function whichAllFromPath(name, options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const exists = options.exists ?? existsSync;
+    const isExecutable = options.isExecutable ?? ((p) => defaultIsExecutable(p, platform));
+    const pathValue = env.PATH ?? env.Path ?? "";
+    if (pathValue === "") {
+        return [];
+    }
+    const isWindows = platform === "win32";
+    const exts = isWindows ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";") : [""];
+    const sep = isWindows ? ";" : ":";
+    const joinPath = isWindows ? win32.join : posix.join;
+    const seen = new Set();
+    const out = [];
+    for (const dir of pathValue.split(sep)) {
+        if (dir === "")
+            continue;
+        for (const ext of exts) {
+            const candidate = joinPath(dir, `${name}${ext}`);
+            const key = isWindows ? candidate.toLowerCase() : candidate;
+            if (seen.has(key))
+                continue;
+            if (exists(candidate) && isExecutable(candidate)) {
+                seen.add(key);
+                out.push(candidate);
+                // One match per PATH directory (first PATHEXT hit wins on win32).
+                break;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * All PATH matches for `name` without shelling out (#3233 security).
+ * Alias of {@link whichAllFromPath} — never runs bare `which` / `where`.
+ */
+export function defaultWhichAll(name, options = {}) {
+    return whichAllFromPath(name, options);
+}
+/** Default PATH lookup mirroring Python `shutil.which` (first match only). */
 export function defaultWhich(name) {
     const locator = process.platform === "win32" ? "where" : "which";
     try {

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