@deftai/directive-core 0.88.0 → 0.90.0

package/dist/session/session-start.js

@@ -5,23 +5,40 @@ import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposi
 import { detectEnvironmentContext, environmentContextToDict, formatEnvironmentContext, } from "../platform/shell-context.js";
 import { disclosureLine } from "../policy/disclosure.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 { humanMergeDisclosureLine, resolveHumanMergePolicy, } from "../policy/require-human-merge.js";
 import { resolvePolicy } from "../policy/resolve.js";
 import { maybeFormatProductSignalConsentPrompt } from "../product-signal/consent-prompt.js";
+import { formatFrameworkCommand } from "../render/framework-commands.js";
 import { maybeRunStalenessTickler } from "../staleness-tickler/run.js";
 import { runDefaultMode } from "../triage/welcome/default-mode.js";
 import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
 import { emitSessionValueReadback } from "../value/readback.js";
 import { verifyRequiredTools } from "../verify-env/verify-tools.js";
-import { defaultGitRunner, gitHead, worktreePath } from "./git.js";
+import { defaultGitRunner, gitHead, gitIsAncestor, worktreePath } from "./git.js";
+import { emitSessionStartProcessCost } from "./process-cost.js";
 import { probeSessionReleaseAvailability, } from "./release-availability.js";
-import { newRitualStatePayload, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
+import { newRitualStatePayload, readRitualState, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
 export const SESSION_POSTURES = ["read-only", "mutation"];
 export const READ_ONLY_POSTURE = "read-only";
 export const MUTATION_POSTURE = "mutation";
 export const READ_ONLY_ALIGNMENT_MESSAGE = "Deft Directive active -- AGENTS.md loaded.";
 export const READ_ONLY_RESULT_MESSAGE = "read-only session posture (alignment only; no ritual-state write)";
+/** Cold (full) vs re-arm (clock/HEAD refresh) ceremony tiers (#2992). */
+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"];
+/** 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). */
+export const OPTIONAL_NETWORK_SKIPPED_MESSAGE = "[deft session] optional network skipped (release probe, triage cache hydrate/self-heal); " +
+    "pass --with-network or set DEFT_SESSION_START_NETWORK=1 to enable.";
+/** Re-arm skips fat cold-path work when prior ritual is still structurally valid (#2992). */
+export const REARM_SKIPPED_FAT_PATH_MESSAGE = "[deft session] re-arm tier: refreshed ritual clock + HEAD/worktree bind; " +
+    "skipped verify:tools, triage welcome, release probe, and staleness tickler.";
+/** When --rearm is requested but state requires a full cold ceremony (#2992). */
+export const REARM_INELIGIBLE_PREFIX = "session re-arm refused — full cold session:start required:";
 const STEP_ALIASES = {
     branch: "branch_policy",
     "branch-policy": "branch_policy",
@@ -30,6 +47,89 @@ const STEP_ALIASES = {
     triage: "triage_welcome",
     "triage-welcome": "triage_welcome",
 };
+/** Format preferred `session:start` recovery command for cold vs re-arm (#2992). */
+export function formatSessionStartRecoveryCommand(tier = "cold") {
+    if (tier === "rearm") {
+        return formatFrameworkCommand(["session:start", "--rearm"]);
+    }
+    return formatFrameworkCommand(["session:start"]);
+}
+function stepPassesForRearm(step) {
+    if (!step || typeof step !== "object")
+        return false;
+    if (step.deferred_reason)
+        return true;
+    return step.ok === true;
+}
+/**
+ * Whether a prior ritual can be re-armed without a full cold ceremony (#2992).
+ * Requires valid state, same worktree, continuous (or identical) HEAD, and
+ * previously-passing quick steps.
+ */
+export function assessRearmEligibility(projectRoot, options = {}) {
+    const runGit = options.runGit ?? defaultGitRunner;
+    const [state, err] = readRitualState(projectRoot);
+    if (state === null) {
+        return {
+            eligible: false,
+            reason: err ?? "ritual state missing (first install / cold path required)",
+        };
+    }
+    const { head: currentHead, error: headError } = gitHead(projectRoot, runGit);
+    if (currentHead === null) {
+        return { eligible: false, reason: headError ?? "could not resolve git HEAD" };
+    }
+    const currentWorktree = worktreePath(projectRoot, runGit);
+    if (state.worktreePath !== currentWorktree) {
+        return {
+            eligible: false,
+            reason: `ritual state belongs to a different worktree (${state.worktreePath})`,
+        };
+    }
+    if (state.gitHead !== currentHead) {
+        const forward = gitIsAncestor(projectRoot, state.gitHead, currentHead, runGit);
+        if (forward === null) {
+            return { eligible: false, reason: "could not verify git history for session re-arm" };
+        }
+        if (!forward) {
+            return {
+                eligible: false,
+                reason: "git HEAD changed discontinuously (full cold session:start required)",
+            };
+        }
+    }
+    for (const stepName of QUICK_STEPS) {
+        if (!stepPassesForRearm(state.quickSteps[stepName])) {
+            return {
+                eligible: false,
+                reason: `quick step '${stepName}' is missing or failed (full cold session:start required)`,
+            };
+        }
+    }
+    return { eligible: true, state, currentHead, currentWorktree };
+}
+function restampSteps(steps, now) {
+    const out = {};
+    for (const [name, step] of Object.entries(steps)) {
+        out[name] = {
+            ...step,
+            ts: ritualStep({ ok: step.ok === true, ts: now }).ts,
+        };
+    }
+    return out;
+}
+/** Resolve whether optional session:start network work is enabled (#2991). */
+export function resolveSessionStartOptionalNetwork(options = {}) {
+    if (options.allowOptionalNetwork === true)
+        return true;
+    if (options.allowOptionalNetwork === false)
+        return false;
+    const env = options.env ?? process.env;
+    return env[ENV_SESSION_START_NETWORK] === "1";
+}
+function elapsedMs(started) {
+    return Math.max(0, Math.round(performance.now() - started));
+}
 function normaliseStepName(name) {
     return STEP_ALIASES[name] ?? name;
 }
@@ -228,12 +328,174 @@ function runReadOnlySessionStart(projectRoot, options, instant, environment) {
     };
     return { code: 0, payload: resultPayload, lines };
 }
+function runSessionRearm(projectRoot, options, instant, environment) {
+    const overallStarted = performance.now();
+    const runGit = options.runGit ?? defaultGitRunner;
+    const eligibility = assessRearmEligibility(projectRoot, { runGit });
+    if (!eligibility.eligible) {
+        const coldCmd = formatSessionStartRecoveryCommand("cold");
+        const message = `${REARM_INELIGIBLE_PREFIX} ${eligibility.reason}. Run \`${coldCmd}\`.`;
+        // #2994: still record failed attempt duration for process-cost rollups.
+        emitSessionStartProcessCost({
+            ceremonyTier: REARM_CEREMONY_TIER,
+            durationMs: elapsedMs(overallStarted),
+            exitCode: 1,
+            ready: false,
+            optionalNetwork: false,
+        }, { projectRoot });
+        return {
+            code: 1,
+            payload: {
+                ready: false,
+                exit_code: 1,
+                ceremony_tier: REARM_CEREMONY_TIER,
+                rearm_eligible: false,
+                environment: environmentContextToDict(environment),
+                message,
+            },
+            lines: [formatEnvironmentContext(environment), message],
+        };
+    }
+    const resolveUserMd = options.resolveUserMd ?? ((root) => resolveUserMdPath({ projectRoot: root }));
+    const userMd = resolveUserMd(projectRoot);
+    const safePath = userMd.path.replace(/\r?\n/g, " ");
+    const safeDiagnostic = userMd.diagnostic.replace(/\r?\n/g, " ");
+    const userMdLine = userMd.found
+        ? `USER.md resolved (${userMd.rung}): ${safePath}`
+        : safeDiagnostic;
+    const alignmentMessage = `${READ_ONLY_ALIGNMENT_MESSAGE} ${userMdLine}`;
+    const lines = [
+        READ_ONLY_ALIGNMENT_MESSAGE,
+        userMdLine,
+        formatEnvironmentContext(environment),
+        REARM_SKIPPED_FAT_PATH_MESSAGE,
+    ];
+    // Light branch-policy disclosure (local only) so re-arm still surfaces policy state.
+    const policyResult = resolvePolicy(projectRoot);
+    const policyMessage = disclosureLine(policyResult);
+    lines.push(policyMessage);
+    const humanMerge = resolveHumanMergePolicy(projectRoot);
+    const humanMergeLine = humanMergeDisclosureLine(humanMerge);
+    if (humanMergeLine !== null) {
+        lines.push(humanMergeLine);
+    }
+    const priorQuick = eligibility.state.quickSteps;
+    const priorTriage = priorQuick.triage_welcome ?? ritualStep({ ok: true, ts: instant });
+    const policyOk = policyResult.error === null || policyResult.source === "default-fail-closed";
+    const quickSteps = {
+        alignment: ritualStep({
+            ok: true,
+            ts: instant,
+            message: alignmentMessage,
+            durationMs: 0,
+        }),
+        branch_policy: ritualStep({
+            ok: policyOk,
+            ts: instant,
+            message: policyMessage,
+            exitCode: policyOk ? 0 : 2,
+            durationMs: 0,
+        }),
+        // Preserve prior triage outcome; do not re-run welcome / self-heal on re-arm.
+        triage_welcome: {
+            ...priorTriage,
+            ts: ritualStep({ ok: priorTriage.ok === true, ts: instant }).ts,
+            message: typeof priorTriage.message === "string"
+                ? priorTriage.message
+                : "triage welcome preserved on re-arm",
+        },
+    };
+    const gatedSteps = restampSteps(eligibility.state.gatedSteps, instant);
+    const writeStarted = performance.now();
+    // Fresh payload (no rearm_needed / compact_resume_at) clears compact markers (#2992).
+    const writePayload = {
+        ...newRitualStatePayload({
+            sessionId: (options.newSessionId ?? randomUUID)(),
+            gitHead: eligibility.currentHead,
+            worktreePath: eligibility.currentWorktree,
+            startedAt: instant,
+            quickSteps,
+            gatedSteps,
+        }),
+        ceremony_tier: REARM_CEREMONY_TIER,
+    };
+    let statePath;
+    try {
+        statePath = writeRitualState(projectRoot, writePayload);
+    }
+    catch (cause) {
+        // #2994: still record failed attempt when ritual-state write throws.
+        emitSessionStartProcessCost({
+            ceremonyTier: REARM_CEREMONY_TIER,
+            durationMs: elapsedMs(overallStarted),
+            exitCode: 2,
+            ready: false,
+            optionalNetwork: false,
+            steps: [
+                { name: "alignment", duration_ms: 0 },
+                { name: "branch_policy", duration_ms: 0 },
+                { name: "verify_tools", duration_ms: 0, skipped: true },
+                { name: "triage_welcome", duration_ms: 0, skipped: true },
+                { name: "release_probe", duration_ms: 0, skipped: true },
+                { name: "ritual_write", duration_ms: elapsedMs(writeStarted) },
+            ],
+        }, { projectRoot });
+        throw cause;
+    }
+    const stepTimings = [
+        { name: "alignment", duration_ms: 0 },
+        { name: "branch_policy", duration_ms: 0 },
+        { name: "verify_tools", duration_ms: 0, skipped: true },
+        { name: "triage_welcome", duration_ms: 0, skipped: true },
+        { name: "release_probe", duration_ms: 0, skipped: true },
+        { name: "ritual_write", duration_ms: elapsedMs(writeStarted) },
+    ];
+    const totalMs = elapsedMs(overallStarted);
+    const failed = Object.entries(quickSteps)
+        .filter(([, step]) => !step.ok && !step.deferred_reason)
+        .map(([name]) => name);
+    const code = failed.length > 0 ? 1 : 0;
+    // #2994: local process-cost event (best-effort; never blocks ceremony).
+    emitSessionStartProcessCost({
+        ceremonyTier: REARM_CEREMONY_TIER,
+        durationMs: totalMs,
+        exitCode: code,
+        ready: code === 0,
+        optionalNetwork: false,
+        steps: stepTimings,
+    }, { projectRoot });
+    return {
+        code,
+        payload: {
+            ready: code === 0,
+            exit_code: code,
+            ceremony_tier: REARM_CEREMONY_TIER,
+            rearm_eligible: true,
+            state_path: statePath,
+            quick_steps: quickSteps,
+            gated_steps: gatedSteps,
+            steps: stepTimings,
+            duration_ms: totalMs,
+            optional_network: false,
+            user_md: {
+                path: userMd.path,
+                rung: userMd.rung,
+                found: userMd.found,
+                diagnostic: userMd.diagnostic,
+            },
+            environment: environmentContextToDict(environment),
+            message: code === 0 ? "session ritual re-armed" : "session ritual re-arm failed",
+        },
+        lines,
+    };
+}
 export function runSessionStart(projectRoot, options = {}) {
     const posture = options.posture ?? MUTATION_POSTURE;
     const instant = options.now ?? new Date();
     const deferrals = options.deferrals ?? {};
     const runGit = options.runGit ?? defaultGitRunner;
     const environment = (options.probeEnvironment ?? detectEnvironmentContext)();
+    const ceremonyTier = options.ceremonyTier ?? COLD_CEREMONY_TIER;
     // #2926: official root opt-out wins locally — skip Directive session ritual.
     // disabled = skip ritual (exit 0 clean / 1 inconsistent). ready stays false so
     // automation does not treat opt-out as "session fully initialized for work".
@@ -266,13 +528,30 @@ export function runSessionStart(projectRoot, options = {}) {
     if (posture === READ_ONLY_POSTURE) {
         return runReadOnlySessionStart(projectRoot, options, instant, environment);
     }
+    // #2992: re-arm path refreshes clock/bind without fat cold ceremony.
+    if (ceremonyTier === REARM_CEREMONY_TIER) {
+        return runSessionRearm(projectRoot, options, instant, environment);
+    }
+    const overallStarted = performance.now();
+    const stepTimings = [];
+    const allowOptionalNetwork = resolveSessionStartOptionalNetwork(options);
     const { head: gitHeadValue, error: gitError } = gitHead(projectRoot, runGit);
     if (gitHeadValue === null) {
         const payload = {
             ready: false,
+            exit_code: 2,
+            ceremony_tier: COLD_CEREMONY_TIER,
             environment: environmentContextToDict(environment),
             message: gitError ?? "could not resolve git HEAD",
         };
+        // #2994: still record failed attempt duration for process-cost rollups.
+        emitSessionStartProcessCost({
+            ceremonyTier: COLD_CEREMONY_TIER,
+            durationMs: elapsedMs(overallStarted),
+            exitCode: 2,
+            ready: false,
+            optionalNetwork: allowOptionalNetwork,
+        }, { projectRoot });
         return {
             code: 2,
             payload,
@@ -289,6 +568,7 @@ export function runSessionStart(projectRoot, options = {}) {
     const resolveUserMd = options.resolveUserMd ?? ((root) => resolveUserMdPath({ projectRoot: root }));
     const userMd = resolveUserMd(projectRoot);
     if (!quickSteps.alignment) {
+        const stepStarted = performance.now();
         const message = "Deft Directive active -- AGENTS.md loaded.";
         // Sanitize newlines on the data-derived path/diagnostic before they land in
         // the ritual-step message / terminal output (matches doctor's CWE-116
@@ -299,42 +579,66 @@ export function runSessionStart(projectRoot, options = {}) {
         const userMdLine = userMd.found
             ? `USER.md resolved (${userMd.rung}): ${safePath}`
             : safeDiagnostic;
+        const durationMs = elapsedMs(stepStarted);
         quickSteps.alignment = ritualStep({
             ok: true,
             ts: instant,
             message: `${message} ${userMdLine}`,
+            durationMs,
         });
+        stepTimings.push({ name: "alignment", duration_ms: durationMs });
         lines.push(message);
         lines.push(userMdLine);
     }
+    else {
+        stepTimings.push({ name: "alignment", duration_ms: 0, skipped: true });
+    }
     lines.push(formatEnvironmentContext(environment));
     if (!quickSteps.branch_policy) {
+        const stepStarted = performance.now();
         const result = resolvePolicy(projectRoot);
         const message = disclosureLine(result);
         const ok = result.error === null || result.source === "default-fail-closed";
+        lines.push(message);
+        // Human merge gate disclosure (#1193) — surface when ON (or env bypass active).
+        const humanMerge = resolveHumanMergePolicy(projectRoot);
+        const humanMergeLine = humanMergeDisclosureLine(humanMerge);
+        if (humanMergeLine !== null) {
+            lines.push(humanMergeLine);
+        }
+        const branchSync = defaultBranchSync(projectRoot, runGit);
+        if (branchSync.warning) {
+            lines.push(branchSync.warning);
+        }
+        const durationMs = elapsedMs(stepStarted);
         quickSteps.branch_policy = ritualStep({
             ok,
             ts: instant,
             message,
             exitCode: ok ? 0 : 2,
+            durationMs,
         });
-        lines.push(message);
-        const branchSync = defaultBranchSync(projectRoot, runGit);
-        if (branchSync.warning) {
-            lines.push(branchSync.warning);
-        }
+        stepTimings.push({ name: "branch_policy", duration_ms: durationMs });
+    }
+    else {
+        stepTimings.push({ name: "branch_policy", duration_ms: 0, skipped: true });
+    }
+    {
+        const stepStarted = performance.now();
+        const verifyToolsFn = options.verifyTools ??
+            ((output) => {
+                const toolLines = [];
+                const result = verifyRequiredTools({ outputFn: (line) => toolLines.push(line) });
+                for (const line of toolLines) {
+                    output(line);
+                }
+                return { exitCode: result.exitCode };
+            });
+        verifyToolsFn((line) => lines.push(line));
+        stepTimings.push({ name: "verify_tools", duration_ms: elapsedMs(stepStarted) });
     }
-    const verifyToolsFn = options.verifyTools ??
-        ((output) => {
-            const toolLines = [];
-            const result = verifyRequiredTools({ outputFn: (line) => toolLines.push(line) });
-            for (const line of toolLines) {
-                output(line);
-            }
-            return { exitCode: result.exitCode };
-        });
-    verifyToolsFn((line) => lines.push(line));
     if (!quickSteps.triage_welcome) {
+        const stepStarted = performance.now();
         const captured = [];
         const triageCommand = ["triage_welcome.run_default_mode", "--project-root", projectRoot];
         try {
@@ -343,6 +647,13 @@ export function runSessionStart(projectRoot, options = {}) {
                     const outcome = runDefaultMode(root, {
                         output: welcomeOpts.output,
                         writeHistory: welcomeOpts.writeHistory,
+                        now: welcomeOpts.now,
+                        // #2991: default hot path skips ensureTriageCacheHydrated / maybeSelfHealCache.
+                        selfHealFn: allowOptionalNetwork
+                            ? undefined
+                            : () => {
+                                /* no network cache work on hot path */
+                            },
                     });
                     return { exitCode: outcome.exitCode };
                 });
@@ -353,33 +664,51 @@ export function runSessionStart(projectRoot, options = {}) {
             });
             const ok = outcome.exitCode === 0;
             const message = captured.join("\n").trim() || "triage welcome completed";
+            const durationMs = elapsedMs(stepStarted);
             quickSteps.triage_welcome = ritualStep({
                 ok,
                 ts: instant,
                 message,
                 exitCode: outcome.exitCode,
                 command: triageCommand,
+                durationMs,
             });
+            stepTimings.push({ name: "triage_welcome", duration_ms: durationMs });
             lines.push(...captured);
         }
         catch (exc) {
             const message = `triage welcome failed: ${String(exc)}`;
+            const durationMs = elapsedMs(stepStarted);
             quickSteps.triage_welcome = ritualStep({
                 ok: false,
                 ts: instant,
                 message,
                 exitCode: 2,
                 command: triageCommand,
+                durationMs,
             });
+            stepTimings.push({ name: "triage_welcome", duration_ms: durationMs });
             lines.push(message);
         }
     }
-    try {
-        const releaseAvailability = (options.probeReleaseAvailability ?? probeSessionReleaseAvailability)(projectRoot, { now: instant });
-        lines.push(...releaseAvailability.lines);
+    else {
+        stepTimings.push({ name: "triage_welcome", duration_ms: 0, skipped: true });
     }
-    catch {
-        // Release availability is a best-effort operator advisory, never a session blocker.
+    // #2991: npm release probe is optional network — off by default so ritual write is not blocked.
+    if (allowOptionalNetwork) {
+        const stepStarted = performance.now();
+        try {
+            const releaseAvailability = (options.probeReleaseAvailability ?? probeSessionReleaseAvailability)(projectRoot, { now: instant });
+            lines.push(...releaseAvailability.lines);
+        }
+        catch {
+            // Release availability is a best-effort operator advisory, never a session blocker.
+        }
+        stepTimings.push({ name: "release_probe", duration_ms: elapsedMs(stepStarted) });
+    }
+    else {
+        stepTimings.push({ name: "release_probe", duration_ms: 0, skipped: true });
+        lines.push(OPTIONAL_NETWORK_SKIPPED_MESSAGE);
     }
     try {
         const tickler = (options.runStalenessTickler ?? maybeRunStalenessTickler)(projectRoot, {
@@ -415,6 +744,7 @@ export function runSessionStart(projectRoot, options = {}) {
     if (consentPrompt.length > 0) {
         lines.push(consentPrompt.trimEnd());
     }
+    const writeStarted = performance.now();
     const payload = newRitualStatePayload({
         sessionId: (options.newSessionId ?? randomUUID)(),
         gitHead: gitHeadValue,
@@ -423,17 +753,39 @@ export function runSessionStart(projectRoot, options = {}) {
         quickSteps,
         gatedSteps,
     });
-    const statePath = writeRitualState(projectRoot, payload);
+    let statePath;
+    try {
+        statePath = writeRitualState(projectRoot, payload);
+    }
+    catch (cause) {
+        // #2994: still record failed attempt when ritual-state write throws.
+        stepTimings.push({ name: "ritual_write", duration_ms: elapsedMs(writeStarted) });
+        emitSessionStartProcessCost({
+            ceremonyTier: COLD_CEREMONY_TIER,
+            durationMs: elapsedMs(overallStarted),
+            exitCode: 2,
+            ready: false,
+            optionalNetwork: allowOptionalNetwork,
+            steps: stepTimings,
+        }, { projectRoot });
+        throw cause;
+    }
+    stepTimings.push({ name: "ritual_write", duration_ms: elapsedMs(writeStarted) });
     const failed = Object.entries(quickSteps)
         .filter(([, step]) => !step.ok && !step.deferred_reason)
         .map(([name]) => name);
     const code = failed.length > 0 ? 1 : 0;
+    const totalMs = elapsedMs(overallStarted);
     const resultPayload = {
         ready: code === 0,
         exit_code: code,
+        ceremony_tier: COLD_CEREMONY_TIER,
         state_path: statePath,
         quick_steps: quickSteps,
         gated_steps: gatedSteps,
+        steps: stepTimings,
+        duration_ms: totalMs,
+        optional_network: allowOptionalNetwork,
         user_md: {
             path: userMd.path,
             rung: userMd.rung,
@@ -443,6 +795,15 @@ export function runSessionStart(projectRoot, options = {}) {
         environment: environmentContextToDict(environment),
         message: code === 0 ? "session ritual recorded" : "session ritual failed",
     };
+    // #2994: local process-cost event (best-effort; never blocks ceremony).
+    emitSessionStartProcessCost({
+        ceremonyTier: COLD_CEREMONY_TIER,
+        durationMs: totalMs,
+        exitCode: code,
+        ready: code === 0,
+        optionalNetwork: allowOptionalNetwork,
+        steps: stepTimings,
+    }, { projectRoot });
     return { code, payload: resultPayload, lines };
 }
 export { ritualStatePath };

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

@@ -1,5 +1,6 @@
 import { type GitRunner } from "./git.js";
 import { type DirectivePosture } from "./posture.js";
+import { 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";
@@ -13,12 +14,19 @@ export interface VerifyResult {
     readonly wouldFailCode: number | null;
     readonly posture: DirectivePosture;
     readonly ritualStateRequired: boolean;
+    /**
+     * Preferred session:start recovery when code !== 0 (#2992).
+     * `rearm` when age/compact stale on an otherwise valid bind; `cold` otherwise.
+     */
+    readonly recoveryTier?: SessionCeremonyTier | null;
 }
 export type RitualRunner = (command: readonly string[], projectRoot: string) => {
     code: number;
     stdout: string;
     stderr: string;
 };
+/** Human recovery line after a failed ritual probe (#2992 / #2993). */
+export declare function formatRitualRecoveryInstruction(tier?: SessionCeremonyTier): string;
 export interface VerifySessionRitualOptions {
     readonly tier?: "quick" | "gated";
     readonly now?: Date;