@deftai/directive-core 0.94.0 → 0.95.0

package/dist/init-deposit/refresh.js

@@ -17,12 +17,14 @@ import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
 import { readCorePackageVersion } from "../engine-version.js";
+import { readLiveGeneration, stampLiveGeneration } from "../freshness/generation.js";
 import { resolveLifecycleRoot } from "../layout/resolve.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 { runOrgForceOnMigration } from "../policy/org-force-on-migration.js";
 import { checkLocalEngineIntegrity, classify, ENGINE_PACKAGE, plan, renderGlobalInstall, resolveEngine, } from "../resolution/index.js";
 import { depositOpenClawL2ProductCommands } from "../slash/openclaw-deposit.js";
 import { gitPorcelain } from "../story-ready/git.js";
+import { agentHookReadinessJson, evaluateAgentHookReadiness, evaluateAgentHookReadinessSafely, } from "../verify-env/agent-hook-readiness.js";
 import { removeStaleMigratedFrameworkNarrative } from "../xbrief-migrate/migrate-project.js";
 import { writeAgentHookDeposit } from "./agent-hooks.js";
 import { ensureInitGitignoreLines, isDepositTrackedInGit } from "./gitignore.js";
@@ -332,9 +334,12 @@ export function buildVersionSkewNotice(engineVersion, contentVersion, previousDe
     }
     return null;
 }
-export function buildUpdateSummaryJson(result, options, updateState) {
+export function buildUpdateSummaryJson(input) {
+    const { result, options, updateState, readiness } = input;
     return {
-        success: true,
+        success: readiness ? readiness.code === 0 : true,
+        deposit_completed: true,
+        ...(readiness ? { agent_hook_readiness: agentHookReadinessJson(readiness) } : {}),
         action: "upgrade",
         ...(updateState ? { update_state: updateState } : {}),
         version: result.engineVersion,
@@ -416,6 +421,27 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         // VERSION already matches (e.g. pre-#2804 additive deposits). Does not re-stamp.
         await reconcileDepositToContentPackage(deftDir, contentRoot, io);
         migrateLegacyInstallManifest(projectDir, join(deftDir, "VERSION"));
+        // #3117: ensure a readable live generation token exists without advancing
+        // when the payload did not swap (already-current). stampLiveGeneration is a
+        // no-op write when the token already matches (keeps git clean under #2118).
+        // If generation is missing or behind VERSION (e.g. prior stamp failed after
+        // VERSION rewrite), fail closed — do not report success with a stale token.
+        const priorGen = readLiveGeneration(projectDir);
+        const generationMatches = priorGen !== null &&
+            normalizeVersion(priorGen.contentVersion) === normalizeVersion(contentVersion);
+        try {
+            stampLiveGeneration(projectDir, {
+                contentVersion,
+                stampedBy: "directive-update",
+                increment: false,
+            });
+        }
+        catch (err) {
+            if (!generationMatches) {
+                throw err;
+            }
+            // Token already matches content; ensure write failure is non-fatal noise.
+        }
     }
     else {
         // Full-tree replace (or injected seam). Additive copy is no longer the default.
@@ -426,12 +452,13 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         // additive seams. Throws => no VERSION rewrite (refuse stamp until clean).
         await reconcileDepositToContentPackage(deftDir, contentRoot, io);
         const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));
+        const stampedAt = nowIso();
         const manifestFields = {
             ref: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
             sha: "content-package",
             tag: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
             installRoot: CANONICAL_INSTALL_ROOT,
-            fetchedAt: nowIso(),
+            fetchedAt: stampedAt,
             fetchedBy: "directive-update",
             ...(previousManagedBy ? { managedBy: previousManagedBy } : {}),
         };
@@ -440,6 +467,15 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         // .deft/core/VERSION has been rewritten (folded in from install-upgrade so no
         // manifest behavior is lost by the redirect). Best-effort; never fatal.
         migrateLegacyInstallManifest(projectDir, writtenManifestPath);
+        // #3117: monotonic live generation MUST advance after a successful payload
+        // swap. Suppressing stamp failure would leave a prior bound/live match
+        // reporting `current` while the on-disk payload already changed (Greptile P1).
+        stampLiveGeneration(projectDir, {
+            contentVersion,
+            stampedBy: "directive-update",
+            increment: true,
+            nowIso: stampedAt,
+        });
     }
     // #2595: payload freshness and consumer derivative freshness are independent.
     // Always repair these cheap projections, including on the #2118 no-op path.
@@ -653,17 +689,24 @@ export async function runRefreshDepositCli(options) {
     }
     try {
         const result = await runRefreshDeposit(options, io, options.seams);
+        const readiness = evaluateAgentHookReadinessSafely(result.projectDir, options.seams?.evaluateAgentHookReadiness ?? evaluateAgentHookReadiness);
         const state = result.alreadyCurrent
             ? "current"
             : classification?.state;
         if (options.jsonOut) {
-            options.writeOut(`${JSON.stringify(buildUpdateSummaryJson(result, options, state), null, 2)}\n`);
+            options.writeOut(`${JSON.stringify(buildUpdateSummaryJson({ result, options, updateState: state, readiness }), null, 2)}\n`);
             printUpdateComplete(result, { printf: options.writeErr }, state);
         }
         else {
             printUpdateComplete(result, io, state);
         }
-        return 0;
+        const readinessOut = options.jsonOut
+            ? options.writeErr
+            : readiness.stream === "stderr"
+                ? options.writeErr
+                : options.writeOut;
+        readinessOut(`\n${readiness.message}\n`);
+        return readiness.code;
     }
     catch (cause) {
         if (cause instanceof LegacyLayoutRefusedError) {

package/dist/policy/index.d.ts

@@ -31,12 +31,15 @@ export declare const FIELD_TRIAGE_SCOPE_IGNORES = "plan.policy.triageScopeIgnore
 export declare const FIELD_TRIAGE_RANKING_LABELS = "plan.policy.triageRankingLabels";
 export declare const FIELD_TRIAGE_AUTO_CLASSIFY = "plan.policy.triageAutoClassify";
 export declare const FIELD_TRIAGE_HOLD_MARKERS = "plan.policy.triageHoldMarkers";
+export declare const FIELD_TRIAGE_LABEL_MIRROR = "plan.policy.triageLabelMirror";
 export declare const FIELD_SWARM_SUBAGENT_BACKEND = "plan.policy.swarmSubagentBackend";
 export declare const DEFAULT_SESSION_RITUAL_STALENESS_HOURS = 4;
 export declare const DEFAULT_TRIAGE_SCOPE_VALUE: readonly Record<string, unknown>[];
 export declare const DEFAULT_TRIAGE_SCOPE_IGNORES_VALUE: readonly unknown[];
 export declare const DEFAULT_TRIAGE_RANKING_LABELS_VALUE: readonly string[];
 export declare const DEFAULT_TRIAGE_AUTO_CLASSIFY_VALUE: readonly unknown[];
+/** Default for #1423 Tier-1 label mirror: enabled with `triaged` idempotency marker. */
+export declare const DEFAULT_TRIAGE_LABEL_MIRROR_VALUE: Readonly<Record<string, unknown>>;
 export declare const KNOWN_SUBAGENT_BACKEND_IDS: Set<string>;
 export interface PolicyField {
     readonly name: string;

package/dist/policy/index.js

@@ -46,6 +46,7 @@ export const FIELD_TRIAGE_SCOPE_IGNORES = "plan.policy.triageScopeIgnores";
 export const FIELD_TRIAGE_RANKING_LABELS = "plan.policy.triageRankingLabels";
 export const FIELD_TRIAGE_AUTO_CLASSIFY = "plan.policy.triageAutoClassify";
 export const FIELD_TRIAGE_HOLD_MARKERS = "plan.policy.triageHoldMarkers";
+export const FIELD_TRIAGE_LABEL_MIRROR = "plan.policy.triageLabelMirror";
 export const FIELD_SWARM_SUBAGENT_BACKEND = "plan.policy.swarmSubagentBackend";
 // deliveryBranch also exported from delivery-branch.js via export *
 export const DEFAULT_SESSION_RITUAL_STALENESS_HOURS = 4;
@@ -55,6 +56,13 @@ export const DEFAULT_TRIAGE_SCOPE_VALUE = [
 export const DEFAULT_TRIAGE_SCOPE_IGNORES_VALUE = [];
 export const DEFAULT_TRIAGE_RANKING_LABELS_VALUE = [];
 export const DEFAULT_TRIAGE_AUTO_CLASSIFY_VALUE = [];
+/** Default for #1423 Tier-1 label mirror: enabled with `triaged` idempotency marker. */
+export const DEFAULT_TRIAGE_LABEL_MIRROR_VALUE = {
+    enabled: true,
+    idempotencyLabel: "triaged",
+    alwaysLabels: ["triaged"],
+    actionLabels: {},
+};
 export const KNOWN_SUBAGENT_BACKEND_IDS = new Set(["composer", "cursor-cloud", "grok-build"]);
 const FALLBACK_HOLD_MARKERS = [
     "do not implement",
@@ -139,6 +147,32 @@ function inspectWipCap(data) {
         source: "default",
     };
 }
+function inspectTriageLabelMirrorField(data) {
+    const policyBlock = getPolicyBlock(data);
+    if ("triageLabelMirror" in policyBlock) {
+        const raw = policyBlock.triageLabelMirror;
+        if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+            return {
+                name: FIELD_TRIAGE_LABEL_MIRROR,
+                current: raw,
+                default: { ...DEFAULT_TRIAGE_LABEL_MIRROR_VALUE },
+                source: "typed",
+            };
+        }
+        return {
+            name: FIELD_TRIAGE_LABEL_MIRROR,
+            current: { ...DEFAULT_TRIAGE_LABEL_MIRROR_VALUE },
+            default: { ...DEFAULT_TRIAGE_LABEL_MIRROR_VALUE },
+            source: "default-on-error",
+        };
+    }
+    return {
+        name: FIELD_TRIAGE_LABEL_MIRROR,
+        current: { ...DEFAULT_TRIAGE_LABEL_MIRROR_VALUE },
+        default: { ...DEFAULT_TRIAGE_LABEL_MIRROR_VALUE },
+        source: "default",
+    };
+}
 function inspectSessionRitualStalenessHours(data) {
     const policyBlock = getPolicyBlock(data);
     if ("sessionRitualStalenessHours" in policyBlock) {
@@ -362,6 +396,7 @@ const REGISTERED_POLICIES = [
     (data) => listFieldInspector(data, "triageHoldMarkers", FIELD_TRIAGE_HOLD_MARKERS, defaultHoldMarkers(), {
         emptyIsTyped: true,
     }),
+    inspectTriageLabelMirrorField,
     inspectSwarmSubagentBackend,
     inspectDeliveryBranchField,
     inspectMinGreptileConfidenceField,

package/dist/release-e2e/greenfield-python-free-smoke.js

@@ -152,9 +152,14 @@ export function rehearseGreenfieldPythonFreeSmoke(repoRoot, seams = {}, options
             return [false, `greenfield smoke: expected global deft at ${deft}`];
         }
         const pyFree = pythonFreePathEnv(envBase);
+        const installedBin = join(npmPrefix, "bin");
+        const installedEnv = {
+            ...pyFree,
+            PATH: `${installedBin}:${pyFree.PATH ?? ""}`,
+        };
         [ok, reason] = runStep(spawn, "directive init", deft, ["init", "--yes", "--repo-root", projectDir], {
             cwd: work,
-            env: pyFree,
+            env: installedEnv,
             timeoutMs: 120_000,
         }, onProgress);
         if (!ok)
@@ -173,8 +178,7 @@ export function rehearseGreenfieldPythonFreeSmoke(repoRoot, seams = {}, options
             return [false, "greenfield smoke: repo-root Python run shim present after init"];
         }
         const checkEnv = {
-            ...pyFree,
-            PATH: `${join(npmPrefix, "bin")}:${pyFree.PATH ?? ""}`,
+            ...installedEnv,
             DEFT_SESSION_RITUAL_SKIP: "1",
         };
         onProgress?.("greenfield smoke: running consumer task deft:check (engine-invoke path)");

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

@@ -1,6 +1,10 @@
+import { type AgentHookReadinessResult } from "../verify-env/agent-hook-readiness.js";
 export declare const ENTRYPOINT_TIMEOUT_SECONDS = 300;
 export declare const ENTRYPOINT_TIMEOUT_EXIT_CODE = 124;
 export type RitualEntrypointFn = (argv: readonly string[]) => number;
+export interface DefaultRitualRunnerSeams {
+    readonly evaluateAgentHookReadiness?: (projectRoot: string) => AgentHookReadinessResult;
+}
 /** Run an in-process ritual entrypoint with stdout/stderr capture. */
 export declare function callMain(mainFn: RitualEntrypointFn, argv: readonly string[], _options?: {
     label?: string;
@@ -11,8 +15,8 @@ export declare function callMain(mainFn: RitualEntrypointFn, argv: readonly stri
 };
 /** CLI-shaped cache-fresh entrypoint (mirrors scripts/preflight_cache.py main). */
 export declare function runCacheFreshMain(argv: readonly string[]): number;
-/** Default gated-tier runner: in-process doctor + cache-fresh (mirrors verify_session_ritual.py). */
-export declare function defaultRitualRunner(command: readonly string[], projectRoot: string): {
+/** Default gated-tier runner: in-process hook readiness, doctor, and cache freshness. */
+export declare function defaultRitualRunner(command: readonly string[], projectRoot: string, seams?: DefaultRitualRunnerSeams): {
     code: number;
     stdout: string;
     stderr: string;

package/dist/session/ritual-entrypoint.js

@@ -1,5 +1,6 @@
 import { cmdDoctor } from "../doctor/main.js";
 import { evaluate } from "../preflight-cache/evaluate.js";
+import { evaluateAgentHookReadinessSafely, } from "../verify-env/agent-hook-readiness.js";
 export const ENTRYPOINT_TIMEOUT_SECONDS = 300;
 export const ENTRYPOINT_TIMEOUT_EXIT_CODE = 124;
 /** Run an in-process ritual entrypoint with stdout/stderr capture. */
@@ -66,9 +67,21 @@ export function runCacheFreshMain(argv) {
     }
     return result.code;
 }
-/** Default gated-tier runner: in-process doctor + cache-fresh (mirrors verify_session_ritual.py). */
-export function defaultRitualRunner(command, projectRoot) {
+/** Default gated-tier runner: in-process hook readiness, doctor, and cache freshness. */
+export function defaultRitualRunner(command, projectRoot, seams = {}) {
     const [verb, ...rest] = command;
+    if (verb === "verify:hooks-installed") {
+        const evaluateReadiness = seams.evaluateAgentHookReadiness
+            ? (root) => evaluateAgentHookReadinessSafely(root, seams.evaluateAgentHookReadiness)
+            : evaluateAgentHookReadinessSafely;
+        const result = evaluateReadiness(projectRoot);
+        const output = `${result.message}\n`;
+        return {
+            code: result.code,
+            stdout: result.stream === "stdout" ? output : "",
+            stderr: result.stream === "stderr" ? output : "",
+        };
+    }
     if (verb === "doctor") {
         return callMain((argv) => cmdDoctor(argv), ["--project-root", projectRoot, ...rest]);
     }

package/dist/session/session-ready.js

@@ -90,12 +90,20 @@ export function runSessionReady(projectRoot, options = {}) {
     const env = options.env ?? process.env;
     const lines = [];
     const steps = [];
-    const inspect = options.inspectRitual ?? ((root, opts) => inspectSessionRitual(root, opts));
-    const verify = options.verifyRitual ?? ((root, opts) => verifySessionRitual(root, opts));
-    const start = options.runStart ?? ((root, opts) => runSessionStart(root, opts));
+    const inspect = options.inspectRitual ?? inspectSessionRitual;
+    const verify = options.verifyRitual ?? verifySessionRitual;
+    const start = options.runStart ?? runSessionStart;
     const fetchAll = options.fetchAll ?? cacheFetchAll;
     const inferRepo = options.inferRepo ?? ((root) => inferSessionReadyRepo(root, env));
-    // --- Fast path: already green for PreToolUse gated inspect ---
+    const verifyOpts = {
+        tier: "gated",
+        posture: "mutation",
+        now,
+        runGit: options.runGit,
+        runner: options.runner,
+        forceGatedSteps: ["agent_hooks"],
+    };
+    // --- Fast path: inspect is green, but refresh functional hook readiness before returning. ---
     const gatedInspect = inspect(projectRoot, {
         tier: "gated",
         posture: "mutation",
@@ -103,6 +111,22 @@ export function runSessionReady(projectRoot, options = {}) {
         runGit: options.runGit,
     });
     if (gatedInspect.code === 0) {
+        steps.push("verify:session-ritual:gated");
+        const refreshed = verify(projectRoot, verifyOpts);
+        if (!isGatedVerifyActuallyReady(refreshed)) {
+            const message = refreshed.code === 0 && refreshed.bypassed
+                ? bypassedReadyFailure(refreshed)
+                : `${refreshed.message}\n  Remaining blocker after session:ready. Fix the step above, then re-run \`${readyCommand()}\`.`;
+            lines.push(message);
+            return {
+                code: refreshed.code === 0 ? 1 : refreshed.code,
+                message,
+                path: SESSION_READY_FAILED,
+                lines,
+                steps,
+                duration_ms: elapsedMs(started),
+            };
+        }
         const message = "OK session ready (gated ritual already fresh).";
         lines.push(message);
         return {
@@ -138,7 +162,7 @@ export function runSessionReady(projectRoot, options = {}) {
                 `session:start failed (exit ${startResult.code}). Recovery: run \`${readyCommand()}\` again after fixing the blocker.`;
             lines.push(message);
             return {
-                code: startResult.code === 0 ? 1 : startResult.code,
+                code: startResult.code,
                 message,
                 path: SESSION_READY_FAILED,
                 lines,
@@ -149,13 +173,6 @@ export function runSessionReady(projectRoot, options = {}) {
     }
     // --- Gated verify (lazy doctor + cache_fresh) ---
     steps.push("verify:session-ritual:gated");
-    const verifyOpts = {
-        tier: "gated",
-        posture: "mutation",
-        now,
-        runGit: options.runGit,
-        runner: options.runner,
-    };
     let verifyResult = verify(projectRoot, verifyOpts);
     if (isGatedVerifyActuallyReady(verifyResult)) {
         const message = "OK session ready (gated ritual verified).";
@@ -222,7 +239,7 @@ export function runSessionReady(projectRoot, options = {}) {
             };
         }
         steps.push("verify:session-ritual:gated:retry");
-        verifyResult = verify(projectRoot, verifyOpts);
+        verifyResult = verify(projectRoot, { ...verifyOpts, forceGatedSteps: [] });
         if (isGatedVerifyActuallyReady(verifyResult)) {
             const message = "OK session ready (recovered via cache refresh).";
             lines.push(message);
@@ -253,7 +270,7 @@ export function runSessionReady(projectRoot, options = {}) {
         `  Remaining blocker after session:ready. Fix the step above, then re-run \`${readyCommand()}\`.`;
     lines.push(message);
     return {
-        code: verifyResult.code === 0 ? 1 : verifyResult.code,
+        code: verifyResult.code,
         message,
         path: SESSION_READY_FAILED,
         lines,

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

@@ -16,7 +16,8 @@ export type SessionCeremonyTier = (typeof SESSION_CEREMONY_TIERS)[number];
 export declare const COLD_CEREMONY_TIER: SessionCeremonyTier;
 export declare const REARM_CEREMONY_TIER: SessionCeremonyTier;
 export declare const QUICK_STEPS: readonly ["alignment", "branch_policy", "triage_welcome"];
-export declare const GATED_STEPS: readonly ["doctor", "cache_fresh"];
+export declare const GATED_STEPS: readonly ["agent_hooks", "doctor", "cache_fresh"];
+export type GatedStepName = (typeof GATED_STEPS)[number];
 /** Env opt-in for optional session:start network (release probe + triage cache hydrate) (#2991). */
 export declare const ENV_SESSION_START_NETWORK = "DEFT_SESSION_START_NETWORK";
 /** Human-readable skip notice when optional network is off the hot path (#2991). */

package/dist/session/session-start.js

@@ -1,6 +1,8 @@
 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 { detectEnvironmentContext, environmentContextToDict, formatEnvironmentContext, } from "../platform/shell-context.js";
 import { DEFT_DIRECTIVE_DISABLE_FLAG_NAME, DEFT_DIRECTIVE_DISABLE_STATUS, detectDeftDirectiveDisable, formatDeftDirectiveDisableMessage, isDeftDirectiveDisableActive, } from "../policy/deft-directive-disable.js";
@@ -20,6 +22,7 @@ import { defaultGitRunner, gitHead, gitIsAncestor, worktreePath } from "./git.js
 import { emitSessionStartProcessCost } 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";
 export const SESSION_POSTURES = ["read-only", "mutation"];
 export const READ_ONLY_POSTURE = "read-only";
 export const MUTATION_POSTURE = "mutation";
@@ -30,7 +33,7 @@ export const SESSION_CEREMONY_TIERS = ["cold", "rearm"];
 export const COLD_CEREMONY_TIER = "cold";
 export const REARM_CEREMONY_TIER = "rearm";
 export const QUICK_STEPS = ["alignment", "branch_policy", "triage_welcome"];
-export const GATED_STEPS = ["doctor", "cache_fresh"];
+export const GATED_STEPS = ["agent_hooks", "doctor", "cache_fresh"];
 /** Env opt-in for optional session:start network (release probe + triage cache hydrate) (#2991). */
 export const ENV_SESSION_START_NETWORK = "DEFT_SESSION_START_NETWORK";
 /** Human-readable skip notice when optional network is off the hot path (#2991). */
@@ -148,6 +151,10 @@ export function parseDeferrals(rawValues) {
         const name = raw.slice(0, eq);
         const reason = raw.slice(eq + 1);
         const stepName = normaliseStepName(name.trim());
+        if (stepName === "agent_hooks") {
+            errors.push('ritual step "agent_hooks" is not deferrable');
+            continue;
+        }
         if (!allowed.has(stepName)) {
             errors.push(`unknown ritual step ${JSON.stringify(name)}; expected one of ${JSON.stringify([...allowed].sort())}`);
             continue;
@@ -454,10 +461,11 @@ function runSessionRearm(projectRoot, options, instant, environment) {
     };
     const gatedSteps = restampSteps(eligibility.state.gatedSteps, instant);
     const writeStarted = performance.now();
+    const rearmSessionId = (options.newSessionId ?? randomUUID)();
     // Fresh payload (no rearm_needed / compact_resume_at) clears compact markers (#2992).
     const writePayload = {
         ...newRitualStatePayload({
-            sessionId: (options.newSessionId ?? randomUUID)(),
+            sessionId: rearmSessionId,
             gitHead: eligibility.currentHead,
             worktreePath: eligibility.currentWorktree,
             startedAt: instant,
@@ -502,6 +510,32 @@ function runSessionRearm(projectRoot, options, instant, environment) {
         .filter(([, step]) => !step.ok && !step.deferred_reason)
         .map(([name]) => name);
     const code = failed.length > 0 ? 1 : 0;
+    // #3117: bind live deposit generation into session context on re-arm (host-agnostic).
+    let freshnessBind = null;
+    try {
+        const bound = bindSessionGeneration(projectRoot, {
+            sessionId: rearmSessionId,
+            nowIso: timestampIso(instant),
+            payloadLoaded: true,
+        });
+        freshnessBind = {
+            bound_generation: bound.bound.boundGeneration,
+            live_generation: bound.live.generation,
+            content_version: bound.live.contentVersion,
+            path: bound.path,
+        };
+        lines.push(`[deft freshness] bound generation ${bound.bound.boundGeneration} ` +
+            `(live deposit v${bound.live.contentVersion})`);
+        lines.push(`[deft freshness] set DEFT_SESSION_ID=${rearmSessionId} for bare freshness:report/bind ` +
+            `(or pass --session-id; required for multi-agent trusted readiness)`);
+    }
+    catch {
+        const live = readLiveGeneration(projectRoot);
+        if (live !== null) {
+            lines.push(`[deft freshness] live generation ${live.generation} present; session bind deferred ` +
+                `(run \`deft freshness:bind\` after loading payload surfaces)`);
+        }
+    }
     // #2994: local process-cost event (best-effort; never blocks ceremony).
     emitSessionStartProcessCost({
         ceremonyTier: REARM_CEREMONY_TIER,
@@ -519,6 +553,7 @@ function runSessionRearm(projectRoot, options, instant, environment) {
             ceremony_tier: REARM_CEREMONY_TIER,
             rearm_eligible: true,
             state_path: statePath,
+            ...(freshnessBind ? { freshness: freshnessBind } : {}),
             quick_steps: quickSteps,
             gated_steps: gatedSteps,
             steps: stepTimings,
@@ -829,8 +864,9 @@ export function runSessionStart(projectRoot, options = {}) {
         lines.push(consentPrompt.trimEnd());
     }
     const writeStarted = performance.now();
+    const coldSessionId = (options.newSessionId ?? randomUUID)();
     const payload = newRitualStatePayload({
-        sessionId: (options.newSessionId ?? randomUUID)(),
+        sessionId: coldSessionId,
         gitHead: gitHeadValue,
         worktreePath: worktreePath(projectRoot, runGit),
         startedAt: instant,
@@ -860,11 +896,38 @@ export function runSessionStart(projectRoot, options = {}) {
         .map(([name]) => name);
     const code = failed.length > 0 ? 1 : 0;
     const totalMs = elapsedMs(overallStarted);
+    // #3117: bind live deposit generation when payload surfaces load (cold path).
+    let freshnessBind = null;
+    try {
+        const bound = bindSessionGeneration(projectRoot, {
+            sessionId: coldSessionId,
+            nowIso: timestampIso(instant),
+            payloadLoaded: true,
+        });
+        freshnessBind = {
+            bound_generation: bound.bound.boundGeneration,
+            live_generation: bound.live.generation,
+            content_version: bound.live.contentVersion,
+            path: bound.path,
+        };
+        lines.push(`[deft freshness] bound generation ${bound.bound.boundGeneration} ` +
+            `(live deposit v${bound.live.contentVersion})`);
+        lines.push(`[deft freshness] set DEFT_SESSION_ID=${coldSessionId} for bare freshness:report/bind ` +
+            `(or pass --session-id; required for multi-agent trusted readiness)`);
+    }
+    catch {
+        const live = readLiveGeneration(projectRoot);
+        if (live !== null) {
+            lines.push(`[deft freshness] live generation ${live.generation} present; session bind deferred ` +
+                `(run \`deft freshness:bind\` after loading payload surfaces)`);
+        }
+    }
     const resultPayload = {
         ready: code === 0,
         exit_code: code,
         ceremony_tier: COLD_CEREMONY_TIER,
         state_path: statePath,
+        ...(freshnessBind ? { freshness: freshnessBind } : {}),
         quick_steps: quickSteps,
         gated_steps: gatedSteps,
         steps: stepTimings,

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

@@ -1,10 +1,10 @@
 import { type GitRunner } from "./git.js";
 import { type DirectivePosture } from "./posture.js";
-import { type SessionCeremonyTier } from "./session-start.js";
+import { type GatedStepName, type SessionCeremonyTier } from "./session-start.js";
 export { formatCacheFetchAllRecoveryCommand, recoveryHintForStaleFailure, } from "./cache-recovery.js";
 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<string, readonly string[]>>;
+export declare const GATED_ENTRYPOINT_COMMANDS: Readonly<Record<GatedStepName, readonly string[]>>;
 export interface VerifyResult {
     readonly code: number;
     readonly message: string;
@@ -37,6 +37,8 @@ export interface VerifySessionRitualOptions {
     readonly posture?: DirectivePosture;
     readonly envPosture?: string | undefined;
     readonly handoffText?: string | null;
+    /** Re-run selected gated prerequisites even when their recorded step is green. */
+    readonly forceGatedSteps?: readonly GatedStepName[];
 }
 export interface InspectSessionRitualOptions {
     readonly tier?: "quick" | "gated";

package/dist/session/verify-session-ritual.js

@@ -11,6 +11,7 @@ export { formatCacheFetchAllRecoveryCommand, recoveryHintForStaleFailure, } from
 export const ENV_SKIP = "DEFT_SESSION_RITUAL_SKIP";
 export { ENTRYPOINT_TIMEOUT_EXIT_CODE, ENTRYPOINT_TIMEOUT_SECONDS, } from "./ritual-entrypoint.js";
 export const GATED_ENTRYPOINT_COMMANDS = {
+    agent_hooks: ["verify:hooks-installed", "--scope=agent", "--live"],
     doctor: ["doctor"],
     cache_fresh: ["verify:cache-fresh"],
 };
@@ -26,16 +27,11 @@ function stepPasses(step) {
 }
 function failedStepMessage(tierName, stepName, step) {
     const coldCmd = formatSessionStartRecoveryCommand("cold");
-    if (step === null || step === undefined) {
+    if (step === undefined) {
         return (`session ritual ${tierName} step '${stepName}' is missing. ` +
             `Run \`${coldCmd}\` before implementation dispatch.`);
     }
-    if (typeof step === "object" &&
-        step !== null &&
-        step.deferred_reason) {
-        return "";
-    }
-    const message = typeof step === "object" && step !== null ? step.message : null;
+    const message = step.message;
     const suffix = typeof message === "string" && message.length > 0 ? `: ${message}` : "";
     return `session ritual ${tierName} step '${stepName}' failed${suffix}`;
 }
@@ -53,9 +49,9 @@ export function formatRitualRecoveryInstruction(tier = "cold") {
         `(one-shot: session:start + gated ritual + cache recovery as needed).`);
 }
 function runGatedStep(projectRoot, payload, stepName, runner, now) {
-    const command = [...(GATED_ENTRYPOINT_COMMANDS[stepName] ?? [])];
+    const command = [...GATED_ENTRYPOINT_COMMANDS[stepName]];
     const { code, stdout, stderr } = runner(command, projectRoot);
-    const message = stdout.trim() || stderr.trim() || `${command[0] ?? stepName} exited ${code}`;
+    const message = stdout.trim() || stderr.trim() || `${command[0]} exited ${code}`;
     const gated = payload.gated_steps ?? {};
     gated[stepName] = ritualStep({
         ok: code === 0,
@@ -354,11 +350,15 @@ export function verifySessionRitual(projectRoot, options = {}) {
         const gated = { ...payload.gated_steps };
         payload.gated_steps = gated;
         const runCmd = options.runner ?? defaultRitualRunner;
+        const forced = new Set(options.forceGatedSteps ?? []);
         for (const stepName of GATED_STEPS) {
             const step = gated[stepName];
-            if (step?.deferred_reason)
+            if (step?.deferred_reason && stepName !== "agent_hooks")
                 continue;
-            if (stepPasses(step))
+            // Hook readiness is a live mutation prerequisite, not a cacheable doctor
+            // result. Re-run it at every gated boundary so registration/shim drift
+            // cannot remain hidden behind an earlier green ritual record.
+            if (stepName !== "agent_hooks" && stepPasses(step) && !forced.has(stepName))
                 continue;
             const writeError = runGatedStep(projectRoot, payload, stepName, runCmd, instant);
             if (writeError !== null) {

package/dist/slash/product-set.js

@@ -109,9 +109,12 @@ export const PRODUCT_COMMANDS = Object.freeze([
     {
         logicalId: "/deft:checkpoint",
         filenameStem: "deft-checkpoint",
+        // description documents the save path; wrappers load the strategy doc (same as continue).
+        // ⊗ Point dispatchPath at xbrief/continue.xbrief.json — that file is the checkpoint *output*,
+        // not the instruction doc; first invoke fails when it does not exist yet (#3105).
         description: "Save session state to xbrief/continue.xbrief.json",
         dispatchKind: "session",
-        dispatchPath: "xbrief/continue.xbrief.json",
+        dispatchPath: "resilience/continue-here.md",
     },
 ]);
 /**

package/dist/swarm/verify-review-clean.d.ts

@@ -1,7 +1,6 @@
-import type { CiGateOptions } from "../pr-merge-readiness/ci-gate.js";
-import type { SlizardGateOptions } from "../pr-merge-readiness/slizard-gate.js";
+import { type ComputeGateOptions } from "../pr-merge-readiness/compute.js";
 import type { RunGhFn } from "../pr-merge-readiness/types.js";
-type ReviewGateOptions = CiGateOptions & SlizardGateOptions;
+type ReviewGateOptions = ComputeGateOptions;
 import { EXIT_EXTERNAL_ERROR, EXIT_OK, EXIT_UNCLEAN } from "./constants.js";
 export interface CohortResolutionError {
     vbrief_path: string;
@@ -15,6 +14,8 @@ export interface CohortPRResult {
     clean: boolean;
     ci_summary: Record<string, unknown> | null;
     slizard_summary: Record<string, unknown> | null;
+    via?: string;
+    partial_data?: Record<string, unknown>;
 }
 export interface CohortResult {
     repo: string | null;