@deftai/directive-core 0.99.0 → 0.101.0

package/dist/session/session-start.js

@@ -14,6 +14,7 @@ import { humanMergeDisclosureLine, resolveHumanMergePolicy, } from "../policy/re
 import { resolvePolicy } from "../policy/resolve.js";
 import { maybeFormatProductSignalConsentPrompt } from "../product-signal/consent-prompt.js";
 import { formatFrameworkCommand } from "../render/framework-commands.js";
+import { RunSummaryEmitter } from "../run-summary/emit.js";
 import { formatScmReadinessLines, probeScmReadiness, scmReadinessToDict, } from "../scm/readiness.js";
 import { maybeRunStalenessTickler } from "../staleness-tickler/run.js";
 import { runDefaultMode } from "../triage/welcome/default-mode.js";
@@ -21,11 +22,14 @@ import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
 import { emitSessionValueReadback } from "../value/readback.js";
 import { verifyRequiredTools } from "../verify-env/verify-tools.js";
 import { maybeFormatCoverageCheckResumeNudge } from "./coverage-check-resume-nudge.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 { probeSessionReleaseAvailability, } from "./release-availability.js";
 import { newRitualStatePayload, readRitualState, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
 import { timestampIso } from "./time.js";
+import { runToolchainPreflight, toolchainPreflightToDict, } from "./toolchain-preflight.js";
 export const SESSION_POSTURES = ["read-only", "mutation"];
 export const READ_ONLY_POSTURE = "read-only";
 export const MUTATION_POSTURE = "mutation";
@@ -383,6 +387,38 @@ function resolveHostContentSurface(projectRoot, options, runtimeMode) {
         };
     }
 }
+function resolveEffortBudget(options) {
+    try {
+        const seams = options.effortBudgetSeams ?? {};
+        const environ = seams.environ ?? options.env ?? process.env;
+        // Production host adapter (#3266 / #1461): always resolve a descriptor from env
+        // (and CLI-forwarded seams) so host-native max-turns/budget signals are not lost.
+        const productionHost = resolveProductionHostEffortDescriptor(environ);
+        const hostDescriptor = seams.hostDescriptor !== undefined && seams.hostDescriptor !== null
+            ? { ...productionHost, ...seams.hostDescriptor }
+            : productionHost;
+        return maybeFormatEffortBudgetLines({
+            environ,
+            hostDescriptor,
+        });
+    }
+    catch {
+        // best-effort — session start must not abort on effort-budget probe failures (#3266)
+        return {
+            budget: {
+                detected: false,
+                posture: "unbounded",
+                kind: "none",
+                maxTurns: null,
+                maxBudget: null,
+                remainingTurns: null,
+                remainingBudget: null,
+                sources: [],
+            },
+            lines: [],
+        };
+    }
+}
 function runReadOnlySessionStart(projectRoot, options, instant, environment) {
     const lines = [];
     const resolveUserMd = options.resolveUserMd ?? ((root) => resolveUserMdPath({ projectRoot: root }));
@@ -396,11 +432,14 @@ function runReadOnlySessionStart(projectRoot, options, instant, environment) {
     const scm = resolveSessionScmReadiness(options, false);
     // #3162: host content-surface class + managed drift (advisory).
     const hostSurface = resolveHostContentSurface(projectRoot, options, scm.runtimeMode);
+    // #3266: hard effort-budget detection (advisory; bank-the-pass guidance).
+    const effortBudget = resolveEffortBudget(options);
     lines.push(READ_ONLY_ALIGNMENT_MESSAGE);
     lines.push(userMdLine);
     lines.push(formatEnvironmentContext(environment));
     lines.push(...formatScmReadinessLines(scm));
     lines.push(...hostSurface.lines);
+    lines.push(...effortBudget.lines);
     const resultPayload = {
         ready: true,
         exit_code: 0,
@@ -423,6 +462,7 @@ function runReadOnlySessionStart(projectRoot, options, instant, environment) {
         environment: environmentContextToDict(environment),
         scm: scmReadinessToDict(scm),
         host_content_surface: hostContentSurfaceToDict(hostSurface.report),
+        effort_budget: effortBudgetToDict(effortBudget.budget),
         message: READ_ONLY_RESULT_MESSAGE,
     };
     return { code: 0, payload: resultPayload, lines };
@@ -467,12 +507,15 @@ function runSessionRearm(projectRoot, options, instant, environment) {
     const scm = resolveSessionScmReadiness(options, false);
     // #3162: host content-surface class + managed drift (advisory).
     const hostSurface = resolveHostContentSurface(projectRoot, options, scm.runtimeMode);
+    // #3266: hard effort-budget detection (advisory).
+    const effortBudget = resolveEffortBudget(options);
     const lines = [
         READ_ONLY_ALIGNMENT_MESSAGE,
         userMdLine,
         formatEnvironmentContext(environment),
         ...formatScmReadinessLines(scm),
         ...hostSurface.lines,
+        ...effortBudget.lines,
         REARM_SKIPPED_FAT_PATH_MESSAGE,
     ];
     // Light branch-policy disclosure (local only) so re-arm still surfaces policy state.
@@ -665,6 +708,7 @@ function runSessionRearm(projectRoot, options, instant, environment) {
             environment: environmentContextToDict(environment),
             scm: scmReadinessToDict(scm),
             host_content_surface: hostContentSurfaceToDict(hostSurface.report),
+            effort_budget: effortBudgetToDict(effortBudget.budget),
             message: code === 0 ? "session ritual re-armed" : "session ritual re-arm failed",
         },
         lines,
@@ -749,9 +793,10 @@ export function runSessionStart(projectRoot, options = {}) {
     // #3214 / #3156: select ritual (ceremony) depth before building deferral maps.
     // Rapid/minimal auto-defer informational cold steps only; mutation readiness
     // (doctor, cache_fresh, agent_hooks, verify_tools) stays constant.
-    // Two-stage + provisional intake (#3214 design note / #1581 ordering): fill
+    // Two-stage + provisional intake (#3214 / #3263 / #1581 ordering): fill
     // missing size/tier/shape from env/verb/files/deposit BEFORE resolve — never
-    // block on plan-item effort (post-planning only). Cold incomplete → rapid.
+    // block on plan-item effort (post-planning only). Cold incomplete size is
+    // tier-conditional (#3263): mid/low → standard; frontier/unknown → rapid.
     const { inputs: resolvedDialInputs, provisional: provisionalDial } = resolveSessionCeremonyDialInputs(projectRoot, options.ceremonyDialInputs, {
         ...options.ceremonyDialHints,
         env: options.env,
@@ -837,6 +882,14 @@ export function runSessionStart(projectRoot, options = {}) {
         name: "host_content_surface",
         duration_ms: elapsedMs(hostSurfaceStepStarted),
     });
+    // #3266: hard effort-budget detection (advisory; bank-the-pass guidance).
+    const effortBudgetStepStarted = performance.now();
+    const effortBudget = resolveEffortBudget(options);
+    lines.push(...effortBudget.lines);
+    stepTimings.push({
+        name: "effort_budget",
+        duration_ms: elapsedMs(effortBudgetStepStarted),
+    });
     if (!quickSteps.branch_policy) {
         const stepStarted = performance.now();
         const result = resolvePolicy(projectRoot);
@@ -902,6 +955,120 @@ export function runSessionStart(projectRoot, options = {}) {
         });
         stepTimings.push({ name: "verify_tools", duration_ms: durationMs });
     }
+    // #3282 / #3286: orientation compression — compose doctor + toolchain preflight
+    // (+ agents:refresh / cache-fresh deposit-sha fast-paths) as inline sections with
+    // per-section status lines. Composition of existing steps, not a new monolith.
+    // Read-only posture never reaches here (#2176). Dual-path Later (`deft orient`)
+    // remains open — see orientation bundle.later.
+    let toolchainPreflightResult = null;
+    let orientationBundle = null;
+    {
+        const stepStarted = performance.now();
+        if (options.orientation === null) {
+            // Explicit skip (tests): still honour legacy preflight-only path when set.
+            if (options.toolchainPreflight === null) {
+                stepTimings.push({ name: "orientation", duration_ms: 0, skipped: true });
+                stepTimings.push({ name: "toolchain_preflight", duration_ms: 0, skipped: true });
+            }
+            else if (options.toolchainPreflight !== undefined) {
+                toolchainPreflightResult = options.toolchainPreflight;
+                lines.push(...toolchainPreflightResult.lines);
+                stepTimings.push({
+                    name: "toolchain_preflight",
+                    duration_ms: elapsedMs(stepStarted),
+                });
+            }
+            else {
+                stepTimings.push({ name: "orientation", duration_ms: 0, skipped: true });
+            }
+        }
+        else if (options.orientation !== undefined) {
+            orientationBundle = options.orientation;
+            toolchainPreflightResult = orientationBundle.preflight;
+            lines.push(...orientationBundle.lines);
+            for (const section of orientationBundle.sections) {
+                stepTimings.push({
+                    name: section.name,
+                    duration_ms: section.durationMs,
+                    ...(section.status === "skipped" ? { skipped: true } : {}),
+                });
+                // Record gated ritual steps so verify:session-ritual can skip re-runs.
+                // Do not overwrite explicit --defer (deferred_reason) records.
+                if ((section.name === "doctor" || section.name === "cache_fresh") &&
+                    !gatedSteps[section.name]?.deferred_reason) {
+                    gatedSteps[section.name] = ritualStep({
+                        ok: section.ok,
+                        ts: instant,
+                        message: section.lines[0] ?? section.status,
+                        exitCode: section.exitCode,
+                        durationMs: section.durationMs,
+                        command: section.name === "doctor" ? ["doctor"] : ["verify:cache-fresh"],
+                    });
+                }
+            }
+            stepTimings.push({ name: "orientation", duration_ms: elapsedMs(stepStarted) });
+        }
+        else {
+            try {
+                // Skip composed doctor/cache_fresh work when those gated steps are deferred.
+                const doctorDeferred = Boolean(gatedSteps.doctor?.deferred_reason);
+                const cacheDeferred = Boolean(gatedSteps.cache_fresh?.deferred_reason);
+                orientationBundle = runOrientationCompression({
+                    projectRoot,
+                    frameworkRoot: options.frameworkRoot ?? projectRoot,
+                    compact: options.compact,
+                    env: options.env,
+                    now: instant,
+                    toolchainPreflight: options.toolchainPreflight,
+                    toolchainPreflightOptions: options.toolchainPreflightOptions,
+                    includeDoctor: !doctorDeferred,
+                    includeCacheFresh: !cacheDeferred,
+                    ...options.orientationOptions,
+                });
+                toolchainPreflightResult = orientationBundle.preflight;
+                lines.push(...orientationBundle.lines);
+                for (const section of orientationBundle.sections) {
+                    stepTimings.push({
+                        name: section.name,
+                        duration_ms: section.durationMs,
+                        ...(section.status === "skipped" ? { skipped: true } : {}),
+                    });
+                    if ((section.name === "doctor" || section.name === "cache_fresh") &&
+                        !gatedSteps[section.name]?.deferred_reason) {
+                        gatedSteps[section.name] = ritualStep({
+                            ok: section.ok,
+                            ts: instant,
+                            message: section.lines[0] ?? section.status,
+                            exitCode: section.exitCode,
+                            durationMs: section.durationMs,
+                            command: section.name === "doctor" ? ["doctor"] : ["verify:cache-fresh"],
+                        });
+                    }
+                }
+                stepTimings.push({ name: "orientation", duration_ms: elapsedMs(stepStarted) });
+            }
+            catch {
+                // fail-open: orientation composition must not abort session:start —
+                // fall back to preflight-only (#3282).
+                try {
+                    if (options.toolchainPreflight !== null) {
+                        toolchainPreflightResult =
+                            options.toolchainPreflight ??
+                                runToolchainPreflight({
+                                    projectRoot,
+                                    frameworkRoot: options.frameworkRoot ?? projectRoot,
+                                    ...options.toolchainPreflightOptions,
+                                });
+                        lines.push(...toolchainPreflightResult.lines);
+                    }
+                }
+                catch {
+                    // ignore
+                }
+                stepTimings.push({ name: "orientation", duration_ms: elapsedMs(stepStarted) });
+            }
+        }
+    }
     // #3214: rapid/minimal skip informational cold-path ceremony only.
     if (!quickSteps.triage_welcome && !skipFatPath) {
         const stepStarted = performance.now();
@@ -1036,6 +1203,7 @@ export function runSessionStart(projectRoot, options = {}) {
             reasons: [...provisionalDial.reasons],
         },
     };
+    const preflightDict = toolchainPreflightResult !== null ? toolchainPreflightToDict(toolchainPreflightResult) : null;
     const payload = {
         ...newRitualStatePayload({
             sessionId: coldSessionId,
@@ -1047,6 +1215,8 @@ export function runSessionStart(projectRoot, options = {}) {
         }),
         // #3214: record dial choice on ritual-state for audit / later re-arm context.
         ceremony_dial: dialDict,
+        // #3282: durable preflight snapshot for harness / later check degraded mode.
+        ...(preflightDict !== null ? { toolchain_preflight: preflightDict } : {}),
     };
     let statePath;
     try {
@@ -1070,8 +1240,45 @@ export function runSessionStart(projectRoot, options = {}) {
         .filter(([, step]) => !step.ok && !step.deferred_reason)
         .map(([name]) => name);
     // verify_tools is recorded on quick_steps; failure makes ready=false.
+    // #3282: toolchain preflight degraded mode does NOT flip ready=false by itself —
+    // agents still proceed with a named skip report at check time.
     const code = failed.length > 0 ? 1 : 0;
     const totalMs = elapsedMs(overallStarted);
+    // #3282 / #3286: event-driven run-summary (dial + preflight + orientation call
+    // count for dual-path Later graduation trigger) — fail-open, silent when unset.
+    if (options.emitRunSummary !== false) {
+        try {
+            const emitter = new RunSummaryEmitter({
+                projectRoot,
+                sessionId: coldSessionId,
+                env: options.env,
+            });
+            emitter.emitSessionStart({
+                ceremony_dial: dialDict,
+                preflight: preflightDict ?? undefined,
+                ceremony_tier: COLD_CEREMONY_TIER,
+                ready: code === 0,
+                exit_code: code,
+                ...(orientationBundle !== null
+                    ? {
+                        orientation_call_count: orientationBundle.orientationCallCount,
+                        orientation_compact: orientationBundle.compact,
+                        deposit_sha: orientationBundle.depositSha,
+                        orientation_later_status: orientationBundle.later.status,
+                        orientation_sections: orientationBundle.sections.map((s) => ({
+                            name: s.name,
+                            status: s.status,
+                            ok: s.ok,
+                            sha_match: s.shaMatch,
+                        })),
+                    }
+                    : {}),
+            });
+        }
+        catch {
+            // fail-open
+        }
+    }
     // #3117: bind live deposit generation when payload surfaces load (cold path).
     let freshnessBind = null;
     try {
@@ -1103,6 +1310,24 @@ export function runSessionStart(projectRoot, options = {}) {
         exit_code: code,
         ceremony_tier: COLD_CEREMONY_TIER,
         ceremony_dial: dialDict,
+        ...(preflightDict !== null ? { toolchain_preflight: preflightDict } : {}),
+        ...(orientationBundle !== null
+            ? {
+                orientation: {
+                    deposit_sha: orientationBundle.depositSha,
+                    compact: orientationBundle.compact,
+                    call_count: orientationBundle.orientationCallCount,
+                    later: orientationBundle.later,
+                    sections: orientationBundle.sections.map((s) => ({
+                        name: s.name,
+                        status: s.status,
+                        ok: s.ok,
+                        sha_match: s.shaMatch,
+                        exit_code: s.exitCode,
+                    })),
+                },
+            }
+            : {}),
         state_path: statePath,
         ...(freshnessBind ? { freshness: freshnessBind } : {}),
         quick_steps: quickSteps,
@@ -1119,6 +1344,7 @@ export function runSessionStart(projectRoot, options = {}) {
         environment: environmentContextToDict(environment),
         scm: scmReadinessToDict(scm),
         host_content_surface: hostContentSurfaceToDict(hostSurface.report),
+        effort_budget: effortBudgetToDict(effortBudget.budget),
         message: code === 0 ? "session ritual recorded" : "session ritual failed",
     };
     // #2994: local process-cost event (best-effort; never blocks ceremony).

package/dist/session/toolchain-preflight.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Done-gate toolchain preflight at session start (#3282).
+ *
+ * Verifies the framework done-gate's own toolchain (task binary, package
+ * manager, node, optional CLI dist) up front so agents get a named cause +
+ * remedy in one turn instead of reverse-engineering `directive check` failures.
+ *
+ * Never bootstraps tooling the PRODUCT does not need. Failures name cause and
+ * remedy without embedding env values.
+ */
+export declare const TOOLCHAIN_PREFLIGHT_TOOLS: readonly ["task", "pnpm", "node", "git"];
+export type ToolchainPreflightTool = (typeof TOOLCHAIN_PREFLIGHT_TOOLS)[number];
+export type ToolchainPreflightStatus = "ok" | "missing" | "degraded";
+export interface ToolchainPreflightFinding {
+    readonly tool: ToolchainPreflightTool | "cli_dist";
+    readonly present: boolean;
+    /** Machine-stable cause code (never embeds env values). */
+    readonly cause: string | null;
+    /** Operator/agent remedy command or instruction. */
+    readonly remedy: string | null;
+}
+export interface ToolchainPreflightResult {
+    readonly status: ToolchainPreflightStatus;
+    readonly ok: boolean;
+    /** True when missing tools would force check into degraded/skip mode. */
+    readonly degraded: boolean;
+    readonly findings: readonly ToolchainPreflightFinding[];
+    /** Human lines for session:start stdout (named cause + remedy). */
+    readonly lines: readonly string[];
+    /**
+     * Gate ids that check should skip when this preflight is degraded.
+     * Product-ordering of remaining gates is owned by #3284.
+     */
+    readonly skipGateIds: readonly string[];
+}
+export interface ToolchainPreflightOptions {
+    readonly projectRoot?: string;
+    readonly frameworkRoot?: string;
+    /** which(name) seam for tests. */
+    readonly which?: (name: string) => string | null;
+    /** existsSync seam for tests. */
+    readonly exists?: (path: string) => boolean;
+    /**
+     * When true (default), also probe for a built CLI dist under frameworkRoot
+     * (framework-source dogfood). Consumers without a local dist are fine when
+     * a global `deft`/`directive` is on PATH.
+     */
+    readonly probeCliDist?: boolean;
+}
+/**
+ * Gates that specifically need a package manager / built dist.
+ * When task/node is missing, the orchestrator skips *all* scheduled gates
+ * (dynamic from gate-lists), not this static list — avoids hardcode drift.
+ */
+export declare const PNPM_DEPENDENT_GATE_IDS: readonly string[];
+/** Sentinel skip id meaning "every gate in the active check composition". */
+export declare const SKIP_ALL_GATES = "*";
+/**
+ * Run done-gate toolchain preflight. Pure probe — never installs or builds.
+ */
+export declare function runToolchainPreflight(options?: ToolchainPreflightOptions): ToolchainPreflightResult;
+/** Serialize preflight for run-summary / ritual-state (no env values). */
+export declare function toolchainPreflightToDict(result: ToolchainPreflightResult): Record<string, unknown>;
+//# sourceMappingURL=toolchain-preflight.d.ts.map

package/dist/session/toolchain-preflight.js

@@ -0,0 +1,151 @@
+/**
+ * Done-gate toolchain preflight at session start (#3282).
+ *
+ * Verifies the framework done-gate's own toolchain (task binary, package
+ * manager, node, optional CLI dist) up front so agents get a named cause +
+ * remedy in one turn instead of reverse-engineering `directive check` failures.
+ *
+ * Never bootstraps tooling the PRODUCT does not need. Failures name cause and
+ * remedy without embedding env values.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { defaultWhich } from "../doctor/which.js";
+export const TOOLCHAIN_PREFLIGHT_TOOLS = ["task", "pnpm", "node", "git"];
+const REMEDY = {
+    task: "Install go-task: https://taskfile.dev/installation/ (e.g. winget install Task.Task / brew install go-task)",
+    pnpm: "Enable pnpm via corepack: corepack enable && corepack prepare pnpm@latest --activate",
+    node: "Install Node 20+ (see .nvmrc); then corepack enable",
+    git: "Install Git: https://git-scm.com/downloads",
+};
+const CAUSE = {
+    task: "go-task binary not found on PATH",
+    pnpm: "pnpm binary not found on PATH",
+    node: "node binary not found on PATH",
+    git: "git binary not found on PATH",
+};
+/**
+ * Gates that specifically need a package manager / built dist.
+ * When task/node is missing, the orchestrator skips *all* scheduled gates
+ * (dynamic from gate-lists), not this static list — avoids hardcode drift.
+ */
+export const PNPM_DEPENDENT_GATE_IDS = [
+    "toolchain:check",
+    "toolchain:check-consumer",
+    "ts:check-lane",
+];
+/** Sentinel skip id meaning "every gate in the active check composition". */
+export const SKIP_ALL_GATES = "*";
+function probeTool(tool, which) {
+    const present = which(tool) !== null;
+    return {
+        tool,
+        present,
+        cause: present ? null : CAUSE[tool],
+        remedy: present ? null : REMEDY[tool],
+    };
+}
+function probeCliDist(frameworkRoot, which, exists) {
+    const globalCli = which("deft") !== null || which("directive") !== null;
+    if (globalCli) {
+        return { tool: "cli_dist", present: true, cause: null, remedy: null };
+    }
+    if (frameworkRoot) {
+        const distBin = join(frameworkRoot, "packages", "cli", "dist", "bin.js");
+        if (exists(distBin)) {
+            return { tool: "cli_dist", present: true, cause: null, remedy: null };
+        }
+        return {
+            tool: "cli_dist",
+            present: false,
+            cause: "CLI dist missing and no global deft/directive on PATH",
+            remedy: "Run `task build` (framework source) or `npm i -g @deftai/directive@latest`",
+        };
+    }
+    return {
+        tool: "cli_dist",
+        present: false,
+        cause: "no global deft/directive on PATH",
+        remedy: "Install: npm i -g @deftai/directive@latest",
+    };
+}
+function formatFindingLine(finding) {
+    if (finding.present) {
+        return `[deft preflight] ${finding.tool}: ok`;
+    }
+    const cause = finding.cause ?? "missing";
+    const remedy = finding.remedy ?? "install the tool";
+    return `[deft preflight] ${finding.tool}: MISSING — cause: ${cause}; remedy: ${remedy}`;
+}
+/**
+ * Run done-gate toolchain preflight. Pure probe — never installs or builds.
+ */
+export function runToolchainPreflight(options = {}) {
+    const which = options.which ?? defaultWhich;
+    const exists = options.exists ?? existsSync;
+    const findings = [];
+    for (const tool of TOOLCHAIN_PREFLIGHT_TOOLS) {
+        findings.push(probeTool(tool, which));
+    }
+    if (options.probeCliDist !== false) {
+        findings.push(probeCliDist(options.frameworkRoot ?? options.projectRoot, which, exists));
+    }
+    const missingCritical = findings.filter((f) => !f.present && (f.tool === "task" || f.tool === "pnpm" || f.tool === "node"));
+    const taskMissing = findings.some((f) => f.tool === "task" && !f.present);
+    const pnpmMissing = findings.some((f) => f.tool === "pnpm" && !f.present);
+    const nodeMissing = findings.some((f) => f.tool === "node" && !f.present);
+    const skip = new Set();
+    if (taskMissing || nodeMissing) {
+        // Dynamic: orchestrator expands SKIP_ALL_GATES to the live gate list.
+        skip.add(SKIP_ALL_GATES);
+    }
+    else if (pnpmMissing) {
+        for (const id of PNPM_DEPENDENT_GATE_IDS) {
+            skip.add(id);
+        }
+    }
+    const degraded = missingCritical.length > 0;
+    const ok = !degraded;
+    const status = ok ? "ok" : "degraded";
+    const lines = [];
+    lines.push(`[deft preflight] toolchain status: ${status}`);
+    for (const finding of findings) {
+        if (!finding.present) {
+            lines.push(formatFindingLine(finding));
+        }
+    }
+    if (ok) {
+        lines.push("[deft preflight] done-gate toolchain ready (task, pnpm, node)");
+    }
+    else {
+        lines.push("[deft preflight] degraded mode: directive check will skip toolchain-dependent gates " +
+            "with a named skip report rather than bootstrapping product-unneeded tooling (#3282)");
+        if (skip.size > 0) {
+            lines.push(`[deft preflight] gates subject to skip when degraded: ${[...skip].sort().join(", ")}`);
+        }
+    }
+    return {
+        status,
+        ok,
+        degraded,
+        findings,
+        lines,
+        skipGateIds: [...skip].sort(),
+    };
+}
+/** Serialize preflight for run-summary / ritual-state (no env values). */
+export function toolchainPreflightToDict(result) {
+    return {
+        status: result.status,
+        ok: result.ok,
+        degraded: result.degraded,
+        findings: result.findings.map((f) => ({
+            tool: f.tool,
+            present: f.present,
+            cause: f.cause,
+            remedy: f.remedy,
+        })),
+        skip_gate_ids: [...result.skipGateIds],
+    };
+}
+//# sourceMappingURL=toolchain-preflight.js.map

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

@@ -1,3 +1,4 @@
+import { type ActiveCliCheckResult, type ActiveCliCheckSeams } from "./active-cli.js";
 import { type GitRunner } from "./git.js";
 import { type DirectivePosture } from "./posture.js";
 import { type GatedStepName, type SessionCeremonyTier } from "./session-start.js";
@@ -39,6 +40,19 @@ export interface VerifySessionRitualOptions {
     readonly handoffText?: string | null;
     /** Re-run selected gated prerequisites even when their recorded step is green. */
     readonly forceGatedSteps?: readonly GatedStepName[];
+    /**
+     * #3233: engine version the post-upgrade / ritual check must match on the
+     * shell-active CLI. When null/omitted, still fail closed on multi-prefix
+     * version skew (active older than another PATH candidate).
+     */
+    readonly targetEngineVersion?: string | null;
+    /** Injectable active-CLI seams for hermetic tests (#3233). */
+    readonly activeCliSeams?: ActiveCliCheckSeams;
+    /**
+     * Override the active-CLI probe entirely (tests). Defaults to
+     * {@link checkActiveCliAgainstTarget}.
+     */
+    readonly checkActiveCli?: (targetVersion: string | null, seams?: ActiveCliCheckSeams) => ActiveCliCheckResult;
 }
 export interface InspectSessionRitualOptions {
     readonly tier?: "quick" | "gated";

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

@@ -1,5 +1,7 @@
 import { existsSync } from "node:fs";
+import { readCorePackageVersion } from "../engine-version.js";
 import { formatFrameworkCommand } from "../render/framework-commands.js";
+import { checkActiveCliAgainstTarget, } from "./active-cli.js";
 import { defaultGitRunner, gitHead, gitIsAncestor, worktreePath } from "./git.js";
 import { pythonJsonDump } from "./json.js";
 import { ENV_SESSION_POSTURE, readOnlyPostureMessage, resolveSessionPosture, ritualStateIsPostureAuthority, } from "./posture.js";
@@ -389,6 +391,37 @@ export function verifySessionRitual(projectRoot, options = {}) {
                 ritualStateRequired,
             };
         }
+        // #3233: after gated entrypoints, verify the shell-active deft/directive
+        // is not a stale higher-precedence shadow of a multi-prefix install.
+        // Independent target = explicit option, else in-process publishable engine
+        // (never the active CLI's own version — see resolveDefaultActiveCliTarget).
+        const targetEngineVersion = options.targetEngineVersion ?? null;
+        const checkActiveCli = options.checkActiveCli ?? checkActiveCliAgainstTarget;
+        let inProcessVersion = null;
+        try {
+            inProcessVersion = readCorePackageVersion();
+        }
+        catch {
+            inProcessVersion = null;
+        }
+        const activeCliSeams = {
+            inProcessVersion,
+            ...options.activeCliSeams,
+        };
+        const activeCli = checkActiveCli(targetEngineVersion, activeCliSeams);
+        if (!activeCli.ok) {
+            return {
+                code: activeCli.code === 0 ? 1 : activeCli.code,
+                message: activeCli.lines.length > 0 ? activeCli.lines.join("\n") : activeCli.message,
+                tier,
+                statePath,
+                bypassed: false,
+                wouldFailCode: null,
+                posture,
+                ritualStateRequired,
+                recoveryTier: "cold",
+            };
+        }
     }
     const evaluated = evaluateLoadedState(projectRoot, state, {
         tier,

package/dist/story-ready/evaluate.d.ts

@@ -1,4 +1,5 @@
 import { type PathLike } from "node:fs";
+import { type ParentLineageResult } from "../scope/parent-lineage.js";
 import { type ParsedAllocation, parseAllocationSection, SOLO_KIND, SWARM_COHORT_KIND } from "./allocation.js";
 export declare const ACTIVE_FOLDER = "active";
 export declare const ELIGIBLE_STATUS = "running";
@@ -7,17 +8,27 @@ export interface EvaluateResult {
     readonly exitCode: 0 | 1 | 2;
     readonly message: string;
     readonly dispatchKind: string | null;
+    /** #3241 parent-lineage probe (present when vBRIEF checks ran). */
+    readonly parentLineage?: ParentLineageResult;
 }
 export interface EvaluateOptions {
     readonly gitStatus?: string | null;
     readonly allocationContext?: string | null;
     readonly allowDirty?: boolean;
     readonly parsed?: ParsedAllocation;
+    /** Project root for resolving child planRef → parent (#3241). */
+    readonly projectRoot?: string;
+    /** Skip parent-lineage check (tests / opt-out). Default false. */
+    readonly skipParentLineage?: boolean;
 }
 /**
  * Pure evaluator — returns exit code + human message. Faithful to
  * `scripts/preflight_story_start.evaluate`.
+ *
+ * #3241: after structural active+running checks, re-check parent requirement
+ * lineage (coverage map + behavioral deltas) when the parent authors IDs.
  */
 export declare function evaluate(vbriefPath: PathLike, options?: EvaluateOptions): EvaluateResult;
+export { evaluateParentLineage, formatParentLineageLine, type ParentLineageResult, } from "../scope/parent-lineage.js";
 export { parseAllocationSection, SOLO_KIND, SWARM_COHORT_KIND };
 //# sourceMappingURL=evaluate.d.ts.map