@deftai/directive-core 0.98.1 → 0.100.0

package/dist/eval/version-pin.d.ts

@@ -0,0 +1,99 @@
+/**
+ * #3215 — pin and record framework version per eval cell; refuse mixed-version aggregation.
+ * Extends #3081 empiricism; wires into the #1584 shared-benchmark manifest shape when present.
+ */
+/** Repo-relative path for the #1584 shared-benchmark manifest. */
+export declare const SHARED_BENCHMARK_MANIFEST_REL = "evals/shared-benchmark.json";
+/** How the framework version was resolved at eval run start. */
+export type FrameworkVersionSource = "package.json" | "override";
+/** Policy when a treatment cell contains disagreeing framework versions. */
+export type MixedVersionPolicy = "refuse" | "flag";
+/** Resolved framework version pin captured once at eval run start. */
+export interface FrameworkVersionPin {
+    readonly frameworkVersion: string;
+    readonly source: FrameworkVersionSource;
+    readonly resolvedAt: string;
+}
+/** Minimal run identity for cell purity checks (version + treatment grouping). */
+export interface VersionedEvalRun {
+    readonly frameworkVersion: string;
+    readonly treatment?: string;
+    readonly model?: string;
+    readonly harness?: string;
+    readonly runId?: string;
+}
+/** Result of checking whether one treatment cell is version-pure. */
+export interface CellVersionPurity {
+    readonly pure: boolean;
+    readonly frameworkVersion: string | null;
+    readonly versions: readonly string[];
+    readonly runCount: number;
+    readonly treatment: string;
+    readonly message: string;
+}
+export interface AggregateCellOptions {
+    readonly runs: readonly VersionedEvalRun[];
+    /** Treatment key when runs omit `treatment` (e.g. model or with_skill). */
+    readonly treatment?: string;
+    /** Default `refuse`: mixed cells block aggregation. `flag` allows with purity evidence. */
+    readonly policy?: MixedVersionPolicy;
+}
+export interface AggregateCellResult {
+    readonly purity: CellVersionPurity;
+    readonly allowed: boolean;
+    readonly policy: MixedVersionPolicy;
+    readonly frameworkVersion: string | null;
+}
+/** Version block stamped onto a #1584-shaped shared-benchmark manifest. */
+export interface SharedBenchmarkVersionBlock {
+    readonly frameworkVersion: string;
+    readonly frameworkVersionSource: FrameworkVersionSource;
+    readonly frameworkVersionResolvedAt: string;
+    readonly versionPurityGate: "#3215";
+}
+/**
+ * Resolve the directive framework version once at eval run start.
+ * Prefers an explicit override (tests / pinned doctor output); else package.json pin.
+ */
+export declare function resolveFrameworkVersionPin(options?: {
+    readonly override?: string;
+    readonly now?: () => Date;
+}): FrameworkVersionPin;
+/**
+ * Cell-level purity: all runs in one treatment must share a single framework version.
+ * Empty run sets are vacuously pure.
+ */
+export declare function evaluateCellVersionPurity(runs: readonly VersionedEvalRun[], treatment?: string): CellVersionPurity;
+/**
+ * Aggregate (or refuse) runs for one treatment under the mixed-version policy.
+ * `refuse` (default) sets `allowed=false` when versions disagree; `flag` allows with evidence.
+ */
+export declare function aggregateCellWithVersionPurity(options: AggregateCellOptions): AggregateCellResult;
+/**
+ * Group runs by treatment (or model×harness fallback) and evaluate purity per cell.
+ */
+export declare function evaluateLedgerVersionPurity(runs: readonly VersionedEvalRun[]): {
+    readonly pure: boolean;
+    readonly cells: readonly CellVersionPurity[];
+    readonly summary: string;
+};
+/**
+ * Merge a framework version pin into a #1584-shaped shared-benchmark manifest object.
+ * Stamps top-level `frameworkVersion` plus metadata for external consumers.
+ */
+export declare function wireFrameworkVersionIntoManifest(manifest: Record<string, unknown>, pin: FrameworkVersionPin): Record<string, unknown>;
+/** Load `evals/shared-benchmark.json` when present; otherwise null. */
+export declare function loadSharedBenchmarkManifest(projectRoot: string): Record<string, unknown> | null;
+/**
+ * When a #1584 shared-benchmark manifest exists under the project root, return it
+ * with the framework version pin wired in. When `persist` is true, write the
+ * wired manifest back to disk so subsequent consumers see the pin (#3215 Greptile).
+ */
+export declare function applyVersionPinToSharedBenchmark(projectRoot: string, pin: FrameworkVersionPin, options?: {
+    readonly persist?: boolean;
+}): {
+    readonly applied: boolean;
+    readonly persisted: boolean;
+    readonly manifest: Record<string, unknown> | null;
+};
+//# sourceMappingURL=version-pin.d.ts.map

package/dist/eval/version-pin.js

@@ -0,0 +1,181 @@
+/**
+ * #3215 — pin and record framework version per eval cell; refuse mixed-version aggregation.
+ * Extends #3081 empiricism; wires into the #1584 shared-benchmark manifest shape when present.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { readCorePackageVersion } from "../engine-version.js";
+import { containedWrite } from "../fs/contained-write.js";
+/** Repo-relative path for the #1584 shared-benchmark manifest. */
+export const SHARED_BENCHMARK_MANIFEST_REL = "evals/shared-benchmark.json";
+function toIsoZ(date) {
+    return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/**
+ * Resolve the directive framework version once at eval run start.
+ * Prefers an explicit override (tests / pinned doctor output); else package.json pin.
+ */
+export function resolveFrameworkVersionPin(options) {
+    const now = options?.now ?? (() => new Date());
+    const override = options?.override?.trim();
+    if (override !== undefined && override.length > 0) {
+        return {
+            frameworkVersion: override,
+            source: "override",
+            resolvedAt: toIsoZ(now()),
+        };
+    }
+    return {
+        frameworkVersion: readCorePackageVersion(),
+        source: "package.json",
+        resolvedAt: toIsoZ(now()),
+    };
+}
+/**
+ * Cell-level purity: all runs in one treatment must share a single framework version.
+ * Empty run sets are vacuously pure.
+ */
+export function evaluateCellVersionPurity(runs, treatment) {
+    const label = treatment?.trim() ||
+        runs.find((r) => typeof r.treatment === "string" && r.treatment.length > 0)?.treatment ||
+        "default";
+    const versions = [
+        ...new Set(runs.map((r) => r.frameworkVersion.trim()).filter((v) => v.length > 0)),
+    ].sort();
+    if (runs.length === 0) {
+        return {
+            pure: true,
+            frameworkVersion: null,
+            versions: [],
+            runCount: 0,
+            treatment: label,
+            message: `Cell "${label}": no runs (vacuously pure).`,
+        };
+    }
+    if (versions.length <= 1) {
+        const version = versions[0] ?? null;
+        return {
+            pure: true,
+            frameworkVersion: version,
+            versions,
+            runCount: runs.length,
+            treatment: label,
+            message: `Cell "${label}": version-pure (v${version ?? "unknown"}, ${runs.length} run(s)).`,
+        };
+    }
+    return {
+        pure: false,
+        frameworkVersion: null,
+        versions,
+        runCount: runs.length,
+        treatment: label,
+        message: `Cell "${label}": mixed framework versions [${versions.join(", ")}] across ${runs.length} run(s) — mixed-version aggregation blocked (#3215).`,
+    };
+}
+/**
+ * Aggregate (or refuse) runs for one treatment under the mixed-version policy.
+ * `refuse` (default) sets `allowed=false` when versions disagree; `flag` allows with evidence.
+ */
+export function aggregateCellWithVersionPurity(options) {
+    const policy = options.policy ?? "refuse";
+    const purity = evaluateCellVersionPurity(options.runs, options.treatment);
+    const allowed = purity.pure || policy === "flag";
+    return {
+        purity,
+        allowed,
+        policy,
+        frameworkVersion: purity.frameworkVersion,
+    };
+}
+/**
+ * Group runs by treatment (or model×harness fallback) and evaluate purity per cell.
+ */
+export function evaluateLedgerVersionPurity(runs) {
+    const groups = new Map();
+    for (const run of runs) {
+        const key = run.treatment?.trim() ||
+            [run.model ?? "", run.harness ?? ""].filter((p) => p.length > 0).join("@") ||
+            "default";
+        const list = groups.get(key) ?? [];
+        list.push(run);
+        groups.set(key, list);
+    }
+    const cells = [...groups.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, group]) => evaluateCellVersionPurity(group, key));
+    const pure = cells.every((c) => c.pure);
+    const mixed = cells.filter((c) => !c.pure);
+    const summary = cells.length === 0
+        ? "Version purity: no cells."
+        : pure
+            ? `Version purity: all ${cells.length} cell(s) pure.`
+            : `Version purity: ${mixed.length}/${cells.length} cell(s) mixed — ${mixed.map((c) => c.treatment).join(", ")}.`;
+    return { pure, cells, summary };
+}
+/**
+ * Merge a framework version pin into a #1584-shaped shared-benchmark manifest object.
+ * Stamps top-level `frameworkVersion` plus metadata for external consumers.
+ */
+export function wireFrameworkVersionIntoManifest(manifest, pin) {
+    const priorMeta = typeof manifest.metadata === "object" &&
+        manifest.metadata !== null &&
+        !Array.isArray(manifest.metadata)
+        ? { ...manifest.metadata }
+        : {};
+    const versionBlock = {
+        frameworkVersion: pin.frameworkVersion,
+        frameworkVersionSource: pin.source,
+        frameworkVersionResolvedAt: pin.resolvedAt,
+        versionPurityGate: "#3215",
+    };
+    return {
+        ...manifest,
+        frameworkVersion: pin.frameworkVersion,
+        metadata: {
+            ...priorMeta,
+            ...versionBlock,
+        },
+    };
+}
+/** Load `evals/shared-benchmark.json` when present; otherwise null. */
+export function loadSharedBenchmarkManifest(projectRoot) {
+    const path = resolve(projectRoot, SHARED_BENCHMARK_MANIFEST_REL);
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * When a #1584 shared-benchmark manifest exists under the project root, return it
+ * with the framework version pin wired in. When `persist` is true, write the
+ * wired manifest back to disk so subsequent consumers see the pin (#3215 Greptile).
+ */
+export function applyVersionPinToSharedBenchmark(projectRoot, pin, options) {
+    const existing = loadSharedBenchmarkManifest(projectRoot);
+    if (existing === null) {
+        return { applied: false, persisted: false, manifest: null };
+    }
+    const manifest = wireFrameworkVersionIntoManifest(existing, pin);
+    const shouldPersist = options?.persist === true;
+    if (!shouldPersist) {
+        return { applied: true, persisted: false, manifest };
+    }
+    // #2980: product write sink routes through containedWrite.
+    containedWrite({
+        root: resolve(projectRoot),
+        target: SHARED_BENCHMARK_MANIFEST_REL,
+        data: `${JSON.stringify(manifest, null, 2)}\n`,
+        mode: "replace",
+    });
+    return { applied: true, persisted: true, manifest };
+}
+//# sourceMappingURL=version-pin.js.map

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