@deftai/directive-core 0.104.0 → 0.106.0

package/dist/session/ritual-entrypoint.js

@@ -46,12 +46,27 @@ function parseProjectRoot(argv) {
     }
     return ".";
 }
+function parseOptionalForIssue(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] !== "--for-issue")
+            continue;
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith("-"))
+            return null;
+        const parsed = Number.parseInt(next, 10);
+        return Number.isNaN(parsed) ? null : parsed;
+    }
+    return null;
+}
 /** CLI-shaped cache-fresh entrypoint (mirrors scripts/preflight_cache.py main). */
 export function runCacheFreshMain(argv) {
     const projectRoot = parseProjectRoot(argv);
     const allowMissingBootstrap = argv.includes("--allow-missing-bootstrap");
     const quiet = argv.includes("--quiet");
-    const result = evaluate(projectRoot, { allowMissingBootstrap });
+    const workSelection = argv.includes("--work-selection");
+    const skipDriftProbe = argv.includes("--skip-drift-probe") && !workSelection;
+    const forIssue = parseOptionalForIssue(argv);
+    const result = evaluate(projectRoot, { allowMissingBootstrap, skipDriftProbe, forIssue });
     if (result.code === 0) {
         if (!quiet) {
             if (result.message.startsWith("⚠")) {

package/dist/session/session-ready.d.ts

@@ -12,6 +12,7 @@
  * remaining hard blocker is printed once).
  */
 import type { GitRunner } from "./git.js";
+import { type ApplyOccupancyInput, type OccupancyDecision } from "./occupancy.js";
 import { type SessionStartOptions, type SessionStartResult } from "./session-start.js";
 import { type InspectSessionRitualOptions, type RitualRunner, type VerifyResult, type VerifySessionRitualOptions } from "./verify-session-ritual.js";
 export declare const SESSION_READY_FAST_PATH = "fast";
@@ -45,6 +46,7 @@ export interface SessionReadyOptions {
     readonly inspectRitual?: (projectRoot: string, options: InspectSessionRitualOptions) => VerifyResult;
     readonly verifyRitual?: (projectRoot: string, options: VerifySessionRitualOptions) => VerifyResult;
     readonly runStart?: (projectRoot: string, options: SessionStartOptions) => SessionStartResult;
+    readonly applyOccupancy?: (projectRoot: string, input: ApplyOccupancyInput) => OccupancyDecision;
     readonly fetchAll?: CacheFetchAllSeam;
     readonly inferRepo?: (projectRoot: string) => string | null;
     /** Skip cache recovery even when cache_fresh failed (tests). */

package/dist/session/session-ready.js

@@ -15,6 +15,7 @@ import { execFileSync } from "node:child_process";
 import { join } from "node:path";
 import { cacheFetchAll } from "../cache/fetch.js";
 import { formatFrameworkCommand } from "../render/framework-commands.js";
+import { applyWorktreeOccupancy, } from "./occupancy.js";
 import { runSessionStart, } from "./session-start.js";
 import { inspectSessionRitual, verifySessionRitual, } from "./verify-session-ritual.js";
 export const SESSION_READY_FAST_PATH = "fast";
@@ -95,6 +96,54 @@ export function runSessionReady(projectRoot, options = {}) {
     const start = options.runStart ?? runSessionStart;
     const fetchAll = options.fetchAll ?? cacheFetchAll;
     const inferRepo = options.inferRepo ?? ((root) => inferSessionReadyRepo(root, env));
+    const applyOccupancy = options.applyOccupancy ?? applyWorktreeOccupancy;
+    const occupancyInput = (write) => ({
+        env,
+        now,
+        steal: options.sessionStartOptions?.steal,
+        confirm: options.sessionStartOptions?.confirm,
+        occupant: options.sessionStartOptions?.occupant,
+        newSessionId: options.sessionStartOptions?.newSessionId,
+        intent: options.sessionStartOptions?.occupancyIntent ?? "mutation",
+        write,
+    });
+    const previewOccupancy = applyOccupancy(projectRoot, occupancyInput(false));
+    if (previewOccupancy.code !== 0) {
+        const message = previewOccupancy.message;
+        lines.push(message);
+        return {
+            code: previewOccupancy.code,
+            message,
+            path: SESSION_READY_FAILED,
+            lines,
+            steps,
+            duration_ms: elapsedMs(started),
+        };
+    }
+    const claimOnSuccess = () => applyOccupancy(projectRoot, occupancyInput(true));
+    const finishReady = (path, message) => {
+        const claimed = claimOnSuccess();
+        if (claimed.code !== 0) {
+            lines.push(claimed.message);
+            return {
+                code: claimed.code,
+                message: claimed.message,
+                path: SESSION_READY_FAILED,
+                lines,
+                steps,
+                duration_ms: elapsedMs(started),
+            };
+        }
+        lines.push(message);
+        return {
+            code: 0,
+            message,
+            path,
+            lines,
+            steps,
+            duration_ms: elapsedMs(started),
+        };
+    };
     const verifyOpts = {
         tier: "gated",
         posture: "mutation",
@@ -127,16 +176,7 @@ export function runSessionReady(projectRoot, options = {}) {
                 duration_ms: elapsedMs(started),
             };
         }
-        const message = "OK session ready (gated ritual already fresh).";
-        lines.push(message);
-        return {
-            code: 0,
-            message,
-            path: SESSION_READY_FAST_PATH,
-            lines,
-            steps,
-            duration_ms: elapsedMs(started),
-        };
+        return finishReady(SESSION_READY_FAST_PATH, "OK session ready (gated ritual already fresh).");
     }
     // --- Ensure quick-tier ritual state when missing / stale / drifted ---
     const quickInspect = inspect(projectRoot, {
@@ -175,16 +215,7 @@ export function runSessionReady(projectRoot, options = {}) {
     steps.push("verify:session-ritual:gated");
     let verifyResult = verify(projectRoot, verifyOpts);
     if (isGatedVerifyActuallyReady(verifyResult)) {
-        const message = "OK session ready (gated ritual verified).";
-        lines.push(message);
-        return {
-            code: 0,
-            message,
-            path: SESSION_READY_VERIFIED,
-            lines,
-            steps,
-            duration_ms: elapsedMs(started),
-        };
+        return finishReady(SESSION_READY_VERIFIED, "OK session ready (gated ritual verified).");
     }
     if (verifyResult.code === 0 && verifyResult.bypassed) {
         const message = bypassedReadyFailure(verifyResult);
@@ -241,16 +272,7 @@ export function runSessionReady(projectRoot, options = {}) {
         steps.push("verify:session-ritual:gated:retry");
         verifyResult = verify(projectRoot, { ...verifyOpts, forceGatedSteps: [] });
         if (isGatedVerifyActuallyReady(verifyResult)) {
-            const message = "OK session ready (recovered via cache refresh).";
-            lines.push(message);
-            return {
-                code: 0,
-                message,
-                path: SESSION_READY_RECOVERED,
-                lines,
-                steps,
-                duration_ms: elapsedMs(started),
-            };
+            return finishReady(SESSION_READY_RECOVERED, "OK session ready (recovered via cache refresh).");
         }
         if (verifyResult.code === 0 && verifyResult.bypassed) {
             const message = bypassedReadyFailure(verifyResult);

package/dist/session/session-start.d.ts

@@ -1,3 +1,4 @@
+import { type LifecycleVisibleResult } from "../lifecycle-visible/evaluate.js";
 import { type HostContentSurfaceSeams } from "../platform/host-content-surface.js";
 import { type EnvironmentContext } from "../platform/shell-context.js";
 import { type CeremonyDialInputs, type CeremonyDialSelection, type ProvisionalCeremonyEstimateHints } from "../policy/ceremony-dial.js";
@@ -6,6 +7,7 @@ import { type ProbeScmReadinessOptions, type ScmReadinessReport } from "../scm/r
 import { type ResolveUserMdResult } from "../user-config/resolve-user-md.js";
 import { type DetectHardEffortBudgetInput } from "./effort-budget.js";
 import type { GitRunner } from "./git.js";
+import { type ApplyOccupancyInput, type OccupancyDecision } from "./occupancy.js";
 import { type OrientationBundle, type RunOrientationOptions } from "./orientation-compression.js";
 import { type ReleaseAvailabilityProbeOptions } from "./release-availability.js";
 import { type RitualState, ritualStatePath } from "./ritual-sentinel.js";
@@ -63,6 +65,12 @@ export interface SessionStartOptions {
     readonly writeHistory?: boolean;
     readonly runGit?: GitRunner;
     readonly newSessionId?: () => string;
+    /** #3433: steal the worktree occupancy lease. Requires confirm + occupant. */
+    readonly steal?: boolean;
+    readonly confirm?: boolean;
+    readonly occupant?: string;
+    readonly occupancyIntent?: ApplyOccupancyInput["intent"];
+    readonly applyOccupancy?: (projectRoot: string, input: ApplyOccupancyInput) => OccupancyDecision;
     readonly runTriageWelcome?: (projectRoot: string, options: {
         writeHistory: boolean;
         now: Date;
@@ -110,6 +118,11 @@ export interface SessionStartOptions {
      * network is enabled. Inject in tests.
      */
     readonly probeScm?: (options: ProbeScmReadinessOptions) => ScmReadinessReport;
+    /**
+     * #3505: per-clone lifecycle-root visibility (ignore / skip-worktree).
+     * Warn-only; never blocks session:start. Inject in tests.
+     */
+    readonly probeLifecycleVisible?: (projectRoot: string, runGit: GitRunner) => LifecycleVisibleResult;
     /**
      * #3214: ceremony dial inputs (task size × model tier × project shape).
      * Missing fields are filled by the headless provisional classifier

package/dist/session/session-start.js

@@ -1,9 +1,9 @@
-import { randomUUID } from "node:crypto";
 import { runningInsideDeftRepo } from "../doctor/paths.js";
 import { emitSessionEvalReadback } from "../eval/readback.js";
 import { bindSessionGeneration } from "../freshness/bind.js";
 import { readLiveGeneration } from "../freshness/generation.js";
 import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposit/migrate.js";
+import { evaluateLifecycleVisible, formatLifecycleVisibleSessionLines, } from "../lifecycle-visible/evaluate.js";
 import { hostContentSurfaceToDict, maybeFormatHostContentSurfaceLines, } from "../platform/host-content-surface.js";
 import { detectEnvironmentContext, environmentContextToDict, formatEnvironmentContext, } from "../platform/shell-context.js";
 import { ceremonyDialToDict, formatCeremonyDialStatusLine, mergeCeremonyDialDeferrals, resolveCeremonyDial, resolveSessionCeremonyDialInputs, } from "../policy/ceremony-dial.js";
@@ -26,8 +26,9 @@ import { verifyRequiredTools } from "../verify-env/verify-tools.js";
 import { ceremonyDialEvidenceToDict, collectCeremonyDialConsumerEvidence, formatCeremonyDialEvidenceLine, mergeCeremonyDialInputsWithConsumerEvidence, } from "./ceremony-dial-evidence.js";
 import { effortBudgetToDict, maybeFormatEffortBudgetLines, resolveProductionHostEffortDescriptor, } from "./effort-budget.js";
 import { defaultGitRunner, gitHead, gitIsAncestor, worktreePath } from "./git.js";
-import { runOrientationCompression, } from "./orientation-compression.js";
-import { emitSessionStartProcessCost } from "./process-cost.js";
+import { applyWorktreeOccupancy, } from "./occupancy.js";
+import { resolveSessionCompact, runOrientationCompression, } from "./orientation-compression.js";
+import { emitSessionStartProcessCost, formatSessionStartCeremonyCostLine } from "./process-cost.js";
 import { probeSessionReleaseAvailability, } from "./release-availability.js";
 import { newRitualStatePayload, readRitualState, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
 import { timestampIso } from "./time.js";
@@ -50,6 +51,18 @@ export const QUICK_STEPS = [
     "verify_tools",
 ];
 export const GATED_STEPS = ["agent_hooks", "doctor", "cache_fresh"];
+/** Per-clone ignore/index hide of lifecycle roots — warn-only (#3505). */
+function pushLifecycleVisibleAdvisory(lines, projectRoot, options, runGit) {
+    try {
+        const probe = options.probeLifecycleVisible ??
+            ((root, git) => evaluateLifecycleVisible({ projectRoot: root, runGit: git }));
+        const result = probe(projectRoot, runGit);
+        lines.push(...formatLifecycleVisibleSessionLines(result));
+    }
+    catch {
+        // best-effort — session:start must not abort on a clone-local advisory
+    }
+}
 /** Standing one-liner when coverageDebt/checkResume is non-default (#3314). */
 function pushCoverageCheckResumeDisclosure(lines, projectRoot) {
     try {
@@ -433,6 +446,46 @@ function resolveEffortBudget(options) {
         };
     }
 }
+function occupancyInput(options, now, write) {
+    return {
+        env: options.env,
+        now,
+        newSessionId: options.newSessionId,
+        steal: options.steal,
+        confirm: options.confirm,
+        occupant: options.occupant,
+        intent: options.occupancyIntent ?? "mutation",
+        write,
+    };
+}
+function runOccupancy(projectRoot, options, now, write) {
+    const apply = options.applyOccupancy ?? applyWorktreeOccupancy;
+    return apply(projectRoot, occupancyInput(options, now, write));
+}
+function occupancyDeniedResult(occupancy, environment) {
+    return {
+        code: occupancy.code,
+        payload: {
+            ready: false,
+            exit_code: occupancy.code,
+            posture: MUTATION_POSTURE,
+            occupancy: {
+                action: occupancy.action,
+                session_id: occupancy.sessionId,
+                occupant_id: occupancy.record?.sessionId ?? null,
+            },
+            environment: environmentContextToDict(environment),
+            message: occupancy.message,
+        },
+        lines: occupancy.message.split("\n"),
+    };
+}
+function persistOccupancyOrDeny(projectRoot, options, now, environment) {
+    const occupancy = runOccupancy(projectRoot, options, now, true);
+    if (occupancy.code !== 0)
+        return occupancyDeniedResult(occupancy, environment);
+    return occupancy;
+}
 function runReadOnlySessionStart(projectRoot, options, instant, environment) {
     const lines = [];
     const resolveUserMd = options.resolveUserMd ?? ((root) => resolveUserMdPath({ projectRoot: root }));
@@ -454,6 +507,8 @@ function runReadOnlySessionStart(projectRoot, options, instant, environment) {
     lines.push(...formatScmReadinessLines(scm));
     lines.push(...hostSurface.lines);
     lines.push(...effortBudget.lines);
+    const runGit = options.runGit ?? defaultGitRunner;
+    pushLifecycleVisibleAdvisory(lines, projectRoot, options, runGit);
     const resultPayload = {
         ready: true,
         exit_code: 0,
@@ -509,6 +564,10 @@ function runSessionRearm(projectRoot, options, instant, environment) {
             lines: [formatEnvironmentContext(environment), message],
         };
     }
+    const plannedOccupancy = runOccupancy(projectRoot, options, instant, options.steal === true);
+    if (plannedOccupancy.code !== 0) {
+        return occupancyDeniedResult(plannedOccupancy, environment);
+    }
     const resolveUserMd = options.resolveUserMd ?? ((root) => resolveUserMdPath({ projectRoot: root }));
     const userMd = resolveUserMd(projectRoot);
     const safePath = userMd.path.replace(/\r?\n/g, " ");
@@ -532,6 +591,7 @@ function runSessionRearm(projectRoot, options, instant, environment) {
         ...effortBudget.lines,
         REARM_SKIPPED_FAT_PATH_MESSAGE,
     ];
+    pushLifecycleVisibleAdvisory(lines, projectRoot, options, runGit);
     // Light branch-policy disclosure (local only) so re-arm still surfaces policy state.
     const policyResult = resolvePolicy(projectRoot);
     const policyMessage = disclosureLine(policyResult);
@@ -606,7 +666,12 @@ function runSessionRearm(projectRoot, options, instant, environment) {
     };
     const gatedSteps = restampSteps(eligibility.state.gatedSteps, instant);
     const writeStarted = performance.now();
-    const rearmSessionId = (options.newSessionId ?? randomUUID)();
+    const persistedOccupancy = persistOccupancyOrDeny(projectRoot, options, instant, environment);
+    if ("payload" in persistedOccupancy) {
+        return persistedOccupancy;
+    }
+    // #3433: keep DEFT_SESSION_ID / occupant id. Do not mint a new UUID on re-arm.
+    const rearmSessionId = persistedOccupancy.sessionId;
     // Fresh payload (no rearm_needed / compact_resume_at) clears compact markers (#2992).
     const writePayload = {
         ...newRitualStatePayload({
@@ -690,6 +755,10 @@ function runSessionRearm(projectRoot, options, instant, environment) {
         optionalNetwork: false,
         steps: stepTimings,
     }, { projectRoot });
+    // #3508: operator-visible CLI process time. ⊗ not #3286 Later graduation input.
+    if (!resolveSessionCompact({ compact: options.compact, env: options.env })) {
+        lines.push(formatSessionStartCeremonyCostLine(REARM_CEREMONY_TIER, totalMs));
+    }
     return {
         code,
         payload: {
@@ -714,6 +783,10 @@ function runSessionRearm(projectRoot, options, instant, environment) {
             scm: scmReadinessToDict(scm),
             host_content_surface: hostContentSurfaceToDict(hostSurface.report),
             effort_budget: effortBudgetToDict(effortBudget.budget),
+            occupancy: {
+                action: persistedOccupancy.action,
+                session_id: rearmSessionId,
+            },
             message: code === 0 ? "session ritual re-armed" : "session ritual re-arm failed",
         },
         lines,
@@ -847,6 +920,10 @@ export function runSessionStart(projectRoot, options = {}) {
             lines: [formatEnvironmentContext(environment), payload.message],
         };
     }
+    const plannedOccupancy = runOccupancy(projectRoot, options, instant, options.steal === true);
+    if (plannedOccupancy.code !== 0) {
+        return occupancyDeniedResult(plannedOccupancy, environment);
+    }
     const quickSteps = recordDeferredSteps(QUICK_STEPS, effectiveDeferrals, instant);
     const gatedSteps = recordDeferredSteps(GATED_STEPS, effectiveDeferrals, instant);
     const lines = [];
@@ -919,6 +996,12 @@ export function runSessionStart(projectRoot, options = {}) {
         name: "effort_budget",
         duration_ms: elapsedMs(effortBudgetStepStarted),
     });
+    const lifecycleVisibleStarted = performance.now();
+    pushLifecycleVisibleAdvisory(lines, projectRoot, options, runGit);
+    stepTimings.push({
+        name: "lifecycle_visible",
+        duration_ms: elapsedMs(lifecycleVisibleStarted),
+    });
     if (!quickSteps.branch_policy) {
         const stepStarted = performance.now();
         const result = resolvePolicy(projectRoot);
@@ -1214,7 +1297,11 @@ export function runSessionStart(projectRoot, options = {}) {
         lines.push(consentPrompt.trimEnd());
     }
     const writeStarted = performance.now();
-    const coldSessionId = (options.newSessionId ?? randomUUID)();
+    const persistedOccupancy = persistOccupancyOrDeny(projectRoot, options, instant, environment);
+    if ("payload" in persistedOccupancy) {
+        return persistedOccupancy;
+    }
+    const coldSessionId = persistedOccupancy.sessionId;
     const dialDict = {
         ...ceremonyDialToDict(ceremonyDialSelection),
         start_tier: ceremonyDialSelection.depth,
@@ -1298,10 +1385,9 @@ export function runSessionStart(projectRoot, options = {}) {
                     }
                     : {}),
             });
-            // #3356: always emit a denominator when the destination is live so
-            // share = ritual_events / denominator is computable from the stream.
-            // Prefer DEFT_TOTAL_TOOL_TURNS, then DEFT_MAX_TURNS / host maxTurns,
-            // else this session:start CLI invocation (1).
+            // #3399: emit a denominator only when a host/harness value is known.
+            // Prefer DEFT_TOTAL_TOOL_TURNS (harness_actual), then DEFT_MAX_TURNS /
+            // host maxTurns (host_planned). Unset → no event; share is unevaluable.
             emitter.emitSessionToolTurnDenominator(effortBudget.budget.maxTurns);
             // #3319: evaluate escalate-on-evidence only when #3274 is live. A pin
             // emits nothing so never-evaluated stays distinguishable from declined.
@@ -1386,6 +1472,10 @@ export function runSessionStart(projectRoot, options = {}) {
         scm: scmReadinessToDict(scm),
         host_content_surface: hostContentSurfaceToDict(hostSurface.report),
         effort_budget: effortBudgetToDict(effortBudget.budget),
+        occupancy: {
+            action: persistedOccupancy.action,
+            session_id: coldSessionId,
+        },
         message: code === 0 ? "session ritual recorded" : "session ritual failed",
     };
     // #2994: local process-cost event (best-effort; never blocks ceremony).
@@ -1397,6 +1487,10 @@ export function runSessionStart(projectRoot, options = {}) {
         optionalNetwork: allowOptionalNetwork,
         steps: stepTimings,
     }, { projectRoot });
+    // #3508: operator-visible CLI process time. ⊗ not #3286 Later graduation input.
+    if (!resolveSessionCompact({ compact: options.compact, env: options.env })) {
+        lines.push(formatSessionStartCeremonyCostLine(COLD_CEREMONY_TIER, totalMs));
+    }
     return { code, payload: resultPayload, lines };
 }
 export { ritualStatePath };

package/dist/session/verify-ac-session-cache.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Same-session verify:ac result cache (#3387).
+ *
+ * Disk-backed so check composition (spawned verify:ac) can serve from_cache
+ * after a green run in the same session when plan + product hash still match.
+ */
+export declare const VERIFY_AC_SESSION_CACHE_DIR = ".deft/verify-ac-session-cache";
+export declare const AC_SERVED_FROM: readonly ["bank", "cache", "executed"];
+export type AcServedFrom = (typeof AC_SERVED_FROM)[number];
+export interface CachedVerifyAcSnapshot {
+    readonly ok: boolean;
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly commands: readonly unknown[];
+    readonly runs: readonly unknown[];
+    readonly rejected?: readonly unknown[];
+    readonly sourceRung: string;
+    readonly noneStated: boolean;
+    readonly acceptance: unknown;
+    readonly resolution: string;
+    readonly resolvedCommandCount: number;
+}
+export interface VerifyAcSessionCacheRecord {
+    readonly sessionId: string;
+    readonly scopeId: string;
+    readonly productStateHash: string;
+    readonly cachedAt: string;
+    readonly snapshot: CachedVerifyAcSnapshot;
+}
+export declare function verifyAcSessionCacheDir(projectRoot: string): string;
+export declare function verifyAcSessionCachePath(projectRoot: string, sessionId: string, scopeId: string): string;
+export declare function resolveVerifyAcSessionId(env?: Readonly<Record<string, string | undefined>>, explicit?: string | null): string | null;
+export declare function readVerifyAcSessionCache(projectRoot: string, sessionId: string, scopeId: string): VerifyAcSessionCacheRecord | null;
+export declare function writeVerifyAcSessionCache(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly scopeId: string;
+    readonly productStateHash: string;
+    readonly snapshot: CachedVerifyAcSnapshot;
+    readonly now?: string;
+}): VerifyAcSessionCacheRecord;
+//# sourceMappingURL=verify-ac-session-cache.d.ts.map

package/dist/session/verify-ac-session-cache.js

@@ -0,0 +1,126 @@
+/**
+ * Same-session verify:ac result cache (#3387).
+ *
+ * Disk-backed so check composition (spawned verify:ac) can serve from_cache
+ * after a green run in the same session when plan + product hash still match.
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
+import { sanitizeScopeIdForFilename } from "./ac-pass-banking.js";
+export const VERIFY_AC_SESSION_CACHE_DIR = ".deft/verify-ac-session-cache";
+export const AC_SERVED_FROM = ["bank", "cache", "executed"];
+function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+export function verifyAcSessionCacheDir(projectRoot) {
+    return join(resolve(projectRoot), ...VERIFY_AC_SESSION_CACHE_DIR.split("/"));
+}
+export function verifyAcSessionCachePath(projectRoot, sessionId, scopeId) {
+    const safeSession = sanitizeScopeIdForFilename(sessionId);
+    const safeScope = sanitizeScopeIdForFilename(scopeId);
+    return join(verifyAcSessionCacheDir(projectRoot), `${safeSession}-${safeScope}.json`);
+}
+export function resolveVerifyAcSessionId(env, explicit) {
+    const injected = explicit?.trim() ?? "";
+    if (injected.length > 0)
+        return injected;
+    const fromEnv = typeof env?.DEFT_SESSION_ID === "string" ? env.DEFT_SESSION_ID.trim() : "";
+    return fromEnv.length > 0 ? fromEnv : null;
+}
+function parseSnapshot(raw) {
+    const rec = asRecord(raw);
+    if (rec === null)
+        return null;
+    if (typeof rec.ok !== "boolean")
+        return null;
+    if (rec.code !== 0 && rec.code !== 1 && rec.code !== 2)
+        return null;
+    if (typeof rec.message !== "string")
+        return null;
+    if (!Array.isArray(rec.commands) || !Array.isArray(rec.runs))
+        return null;
+    if (typeof rec.sourceRung !== "string")
+        return null;
+    if (typeof rec.noneStated !== "boolean")
+        return null;
+    if (typeof rec.resolution !== "string")
+        return null;
+    if (typeof rec.resolvedCommandCount !== "number")
+        return null;
+    return {
+        ok: rec.ok,
+        code: rec.code,
+        message: rec.message,
+        commands: rec.commands,
+        runs: rec.runs,
+        rejected: Array.isArray(rec.rejected) ? rec.rejected : undefined,
+        sourceRung: rec.sourceRung,
+        noneStated: rec.noneStated,
+        acceptance: rec.acceptance,
+        resolution: rec.resolution,
+        resolvedCommandCount: rec.resolvedCommandCount,
+    };
+}
+export function readVerifyAcSessionCache(projectRoot, sessionId, scopeId) {
+    const path = verifyAcSessionCachePath(projectRoot, sessionId, scopeId);
+    if (!existsSync(path))
+        return null;
+    let text;
+    try {
+        text = readFileSync(path, { encoding: "utf8" });
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        const rec = asRecord(parsed);
+        if (rec === null)
+            return null;
+        if (rec.sessionId !== sessionId || rec.scopeId !== scopeId)
+            return null;
+        if (typeof rec.productStateHash !== "string" || rec.productStateHash.length === 0) {
+            return null;
+        }
+        const snapshot = parseSnapshot(rec.snapshot);
+        if (snapshot === null || snapshot.ok !== true)
+            return null;
+        return {
+            sessionId,
+            scopeId,
+            productStateHash: rec.productStateHash,
+            cachedAt: typeof rec.cachedAt === "string" ? rec.cachedAt : "",
+            snapshot,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeVerifyAcSessionCache(input) {
+    const root = resolve(input.projectRoot);
+    const path = verifyAcSessionCachePath(root, input.sessionId, input.scopeId);
+    const dir = verifyAcSessionCacheDir(root);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const record = {
+        sessionId: input.sessionId,
+        scopeId: input.scopeId,
+        productStateHash: input.productStateHash,
+        cachedAt: input.now ?? new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+        snapshot: input.snapshot,
+    };
+    containedWrite({
+        root,
+        target: path,
+        data: `${JSON.stringify(record, null, 2)}\n`,
+        mode: "replace",
+        mkdir: true,
+    });
+    return record;
+}
+//# sourceMappingURL=verify-ac-session-cache.js.map

package/dist/session/verify-session-ritual.d.ts

@@ -6,6 +6,26 @@ export { formatCacheFetchAllRecoveryCommand, recoveryHintForStaleFailure, } from
 export declare const ENV_SKIP = "DEFT_SESSION_RITUAL_SKIP";
 export { ENTRYPOINT_TIMEOUT_EXIT_CODE, ENTRYPOINT_TIMEOUT_SECONDS, } from "./ritual-entrypoint.js";
 export declare const GATED_ENTRYPOINT_COMMANDS: Readonly<Record<GatedStepName, readonly string[]>>;
+/** Explicit skip flag threaded through the gated `cache_fresh` argv (#3507). */
+export declare const SKIP_DRIFT_PROBE_FLAG = "--skip-drift-probe";
+/** Explicit work-selection flag threaded through the gated `cache_fresh` argv (#3507). */
+export declare const WORK_SELECTION_FLAG = "--work-selection";
+/** Distinct ritual-state field — never `deferred_reason` (#3507). */
+export declare const DRIFT_PROBE_SKIPPED_NO_WORK_SELECTION = "skipped-no-work-selection";
+export type WorkSelectionKind = "none" | "active-story" | "triage-queue" | "ordered-plan" | "for-issue" | "explicit-flag";
+export interface WorkSelectionSignal {
+    readonly inPlay: boolean;
+    readonly kind: WorkSelectionKind;
+}
+export type DetectWorkSelection = (projectRoot: string) => WorkSelectionSignal;
+/**
+ * Default work-selection detector for the gated `cache_fresh` seam (#3507).
+ * Active story xBRIEF (scope:activate residue), unexhausted ordered-plan /
+ * triage sequence. `--for-issue` is a positive evaluate override, not this
+ * detector — the gated argv never carries it.
+ */
+export declare function detectWorkSelection(projectRoot: string): WorkSelectionSignal;
+export declare function resolveGatedEntrypointCommand(stepName: GatedStepName, projectRoot: string, detect?: DetectWorkSelection): string[];
 export interface VerifyResult {
     readonly code: number;
     readonly message: string;
@@ -28,6 +48,12 @@ export type RitualRunner = (command: readonly string[], projectRoot: string) =>
 };
 /** Human recovery line after a failed ritual probe (#2992 / #2993). */
 export declare function formatRitualRecoveryInstruction(tier?: SessionCeremonyTier): string;
+/**
+ * Sanctioned audited defer copy for gated `cache_fresh` failure (#3506 / #3507).
+ * Independent of the #3507 work-selection argv seam — defer is still the
+ * operator-audited escape, not the drift-probe skip.
+ */
+export declare function formatCacheFreshDeferSoftPath(): string;
 export interface VerifySessionRitualOptions {
     readonly tier?: "quick" | "gated";
     readonly now?: Date;
@@ -53,6 +79,8 @@ export interface VerifySessionRitualOptions {
      * {@link checkActiveCliAgainstTarget}.
      */
     readonly checkActiveCli?: (targetVersion: string | null, seams?: ActiveCliCheckSeams) => ActiveCliCheckResult;
+    /** Injectable work-selection detector for gated `cache_fresh` (#3507). */
+    readonly detectWorkSelection?: DetectWorkSelection;
 }
 export interface InspectSessionRitualOptions {
     readonly tier?: "quick" | "gated";