@deftai/directive-core 0.98.1 → 0.100.0

package/dist/session/session-start.js

@@ -4,7 +4,9 @@ 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 { hostContentSurfaceToDict, maybeFormatHostContentSurfaceLines, } from "../platform/host-content-surface.js";
 import { detectEnvironmentContext, environmentContextToDict, formatEnvironmentContext, } from "../platform/shell-context.js";
+import { ceremonyDialToDict, formatCeremonyDialStatusLine, mergeCeremonyDialDeferrals, resolveCeremonyDial, resolveSessionCeremonyDialInputs, } from "../policy/ceremony-dial.js";
 import { DEFT_DIRECTIVE_DISABLE_FLAG_NAME, DEFT_DIRECTIVE_DISABLE_STATUS, detectDeftDirectiveDisable, formatDeftDirectiveDisableMessage, isDeftDirectiveDisableActive, } from "../policy/deft-directive-disable.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";
@@ -19,6 +21,7 @@ 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 { emitSessionStartProcessCost } from "./process-cost.js";
 import { probeSessionReleaseAvailability, } from "./release-availability.js";
@@ -33,7 +36,14 @@ export const READ_ONLY_RESULT_MESSAGE = "read-only session posture (alignment on
 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"];
+// verify_tools is mutation readiness recorded on cold path (#3214 / #3156) —
+// included so re-arm refuses after a tools-failed cold start.
+export const QUICK_STEPS = [
+    "alignment",
+    "branch_policy",
+    "triage_welcome",
+    "verify_tools",
+];
 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";
@@ -105,7 +115,13 @@ export function assessRearmEligibility(projectRoot, options = {}) {
         }
     }
     for (const stepName of QUICK_STEPS) {
-        if (!stepPassesForRearm(state.quickSteps[stepName])) {
+        const step = state.quickSteps[stepName];
+        // Legacy ritual-state (pre-#3214 tools persistence) omits verify_tools —
+        // treat missing as pass; explicit failure still refuses re-arm.
+        if (stepName === "verify_tools" && (step === undefined || step === null)) {
+            continue;
+        }
+        if (!stepPassesForRearm(step)) {
             return {
                 eligible: false,
                 reason: `quick step '${stepName}' is missing or failed (full cold session:start required)`,
@@ -340,6 +356,66 @@ function resolveSessionScmReadiness(options, allowOptionalNetwork) {
         };
     }
 }
+function resolveHostContentSurface(projectRoot, options, runtimeMode) {
+    try {
+        const seams = options.hostContentSurfaceSeams ?? {};
+        return maybeFormatHostContentSurfaceLines(projectRoot, {
+            ...seams,
+            environ: seams.environ ?? options.env,
+            runtimeMode: seams.runtimeMode ?? runtimeMode ?? null,
+        });
+    }
+    catch {
+        // best-effort — session start must not abort on host-surface probe failures (#3162)
+        return {
+            report: {
+                contentClass: "unknown",
+                classSource: "probe-error",
+                signals: [],
+                managedSection: {
+                    state: "unknown",
+                    embeddedSha: null,
+                    bodyHash: null,
+                    path: `${projectRoot}/AGENTS.md`,
+                },
+                runtimeMode: null,
+            },
+            lines: [],
+        };
+    }
+}
+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 }));
@@ -351,10 +427,16 @@ function runReadOnlySessionStart(projectRoot, options, instant, environment) {
         : safeDiagnostic;
     // #2275: report SCM availability even on read-only alignment (shallow; no network).
     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,
@@ -376,6 +458,8 @@ 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 };
@@ -418,11 +502,17 @@ function runSessionRearm(projectRoot, options, instant, environment) {
     const alignmentMessage = `${READ_ONLY_ALIGNMENT_MESSAGE} ${userMdLine}`;
     // #2275: re-arm still reports SCM state (shallow; no network).
     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.
@@ -446,6 +536,41 @@ function runSessionRearm(projectRoot, options, instant, environment) {
     }
     const priorQuick = eligibility.state.quickSteps;
     const priorTriage = priorQuick.triage_welcome ?? ritualStep({ ok: true, ts: instant });
+    // Greptile P1: legacy ritual-state without verify_tools must re-run tools —
+    // never invent ok:true. When prior exists, preserve without re-run (#2992).
+    let toolsStep;
+    if (priorQuick.verify_tools && typeof priorQuick.verify_tools === "object") {
+        const priorTools = priorQuick.verify_tools;
+        toolsStep = {
+            ...priorTools,
+            ts: ritualStep({ ok: priorTools.ok === true, ts: instant }).ts,
+            message: typeof priorTools.message === "string"
+                ? priorTools.message
+                : "verify:tools preserved on re-arm",
+        };
+    }
+    else {
+        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 };
+            });
+        const toolsOutcome = verifyToolsFn((line) => lines.push(line));
+        const toolsOk = toolsOutcome.exitCode === 0;
+        toolsStep = ritualStep({
+            ok: toolsOk,
+            ts: instant,
+            message: toolsOk
+                ? "verify:tools re-run on re-arm (legacy ritual lacked tools step)"
+                : `verify:tools failed on re-arm (exit ${toolsOutcome.exitCode})`,
+            exitCode: toolsOutcome.exitCode,
+            durationMs: 0,
+        });
+    }
     const policyOk = policyResult.error === null || policyResult.source === "default-fail-closed";
     const quickSteps = {
         alignment: ritualStep({
@@ -461,6 +586,7 @@ function runSessionRearm(projectRoot, options, instant, environment) {
             exitCode: policyOk ? 0 : 2,
             durationMs: 0,
         }),
+        verify_tools: toolsStep,
         // Preserve prior triage outcome; do not re-run welcome / self-heal on re-arm.
         triage_welcome: {
             ...priorTriage,
@@ -578,6 +704,8 @@ 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,
@@ -659,12 +787,27 @@ export function runSessionStart(projectRoot, options = {}) {
     const overallStarted = performance.now();
     const stepTimings = [];
     const allowOptionalNetwork = resolveSessionStartOptionalNetwork(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 / #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 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,
+    });
+    const ceremonyDialSelection = options.ceremonyDial ?? resolveCeremonyDial(projectRoot, { inputs: resolvedDialInputs });
+    const effectiveDeferrals = mergeCeremonyDialDeferrals(deferrals, ceremonyDialSelection);
+    const skipFatPath = ceremonyDialSelection.profile.skipFatPath;
     const { head: gitHeadValue, error: gitError } = gitHead(projectRoot, runGit);
     if (gitHeadValue === null) {
         const payload = {
             ready: false,
             exit_code: 2,
             ceremony_tier: COLD_CEREMONY_TIER,
+            ceremony_dial: ceremonyDialToDict(ceremonyDialSelection),
             environment: environmentContextToDict(environment),
             message: gitError ?? "could not resolve git HEAD",
         };
@@ -682,9 +825,13 @@ export function runSessionStart(projectRoot, options = {}) {
             lines: [formatEnvironmentContext(environment), payload.message],
         };
     }
-    const quickSteps = recordDeferredSteps(QUICK_STEPS, deferrals, instant);
-    const gatedSteps = recordDeferredSteps(GATED_STEPS, deferrals, instant);
+    const quickSteps = recordDeferredSteps(QUICK_STEPS, effectiveDeferrals, instant);
+    const gatedSteps = recordDeferredSteps(GATED_STEPS, effectiveDeferrals, instant);
     const lines = [];
+    lines.push(formatCeremonyDialStatusLine(ceremonyDialSelection));
+    if (provisionalDial.reasons.length > 0 && options.ceremonyDial === undefined) {
+        lines.push(`[deft ceremony-dial] provisional: ${provisionalDial.reasons.join("; ")}`);
+    }
     // Resolve USER.md via the shared first-hit-wins resolver so the alignment
     // step finds preferences automatically in mismatched / headless sandboxes
     // with zero manual DEFT_USER_PATH (#2271 / #2124). Never throws: an absent
@@ -724,6 +871,22 @@ export function runSessionStart(projectRoot, options = {}) {
     const scm = resolveSessionScmReadiness(options, allowOptionalNetwork);
     lines.push(...formatScmReadinessLines(scm));
     stepTimings.push({ name: "scm_readiness", duration_ms: elapsedMs(scmStepStarted) });
+    // #3162: host content-surface class + managed AGENTS drift (advisory; never blocks).
+    const hostSurfaceStepStarted = performance.now();
+    const hostSurface = resolveHostContentSurface(projectRoot, options, scm.runtimeMode);
+    lines.push(...hostSurface.lines);
+    stepTimings.push({
+        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);
@@ -753,6 +916,11 @@ export function runSessionStart(projectRoot, options = {}) {
     else {
         stepTimings.push({ name: "branch_policy", duration_ms: 0, skipped: true });
     }
+    // #3214 / #3156: verify_tools is mutation readiness — always run, even under
+    // rapid/minimal. Dial skipFatPath only lightens *ceremony* (triage welcome,
+    // optional network, staleness tickler), never readiness gates.
+    // Persist outcome into quick_steps so ritual-state records failure (not only
+    // process exit) — re-arm / later readers must not see a green cold start.
     {
         const stepStarted = performance.now();
         const verifyToolsFn = options.verifyTools ??
@@ -764,10 +932,28 @@ export function runSessionStart(projectRoot, options = {}) {
                 }
                 return { exitCode: result.exitCode };
             });
-        verifyToolsFn((line) => lines.push(line));
-        stepTimings.push({ name: "verify_tools", duration_ms: elapsedMs(stepStarted) });
+        const toolsOutcome = verifyToolsFn((line) => lines.push(line));
+        const durationMs = elapsedMs(stepStarted);
+        const toolsOk = toolsOutcome.exitCode === 0;
+        const toolsMessage = toolsOk
+            ? "verify:tools ok"
+            : `verify:tools failed (exit ${toolsOutcome.exitCode}); session not ready.`;
+        if (!toolsOk) {
+            lines.push(`[deft session] ${toolsMessage}`);
+        }
+        // Record on quick_steps (durable ritual-state) in addition to step timings.
+        quickSteps.verify_tools = ritualStep({
+            ok: toolsOk,
+            ts: instant,
+            message: toolsMessage,
+            exitCode: toolsOutcome.exitCode,
+            command: ["verify:tools"],
+            durationMs,
+        });
+        stepTimings.push({ name: "verify_tools", duration_ms: durationMs });
     }
-    if (!quickSteps.triage_welcome) {
+    // #3214: rapid/minimal skip informational cold-path ceremony only.
+    if (!quickSteps.triage_welcome && !skipFatPath) {
         const stepStarted = performance.now();
         const captured = [];
         const triageCommand = ["triage_welcome.run_default_mode", "--project-root", projectRoot];
@@ -825,7 +1011,8 @@ export function runSessionStart(projectRoot, options = {}) {
         stepTimings.push({ name: "triage_welcome", duration_ms: 0, skipped: true });
     }
     // #2991: npm release probe is optional network — off by default so ritual write is not blocked.
-    if (allowOptionalNetwork) {
+    // #3214: also skipped under rapid/minimal dial (lifecycleWrites light/minimal).
+    if (allowOptionalNetwork && !skipFatPath) {
         const stepStarted = performance.now();
         try {
             const releaseAvailability = (options.probeReleaseAvailability ?? probeSessionReleaseAvailability)(projectRoot, { now: instant });
@@ -838,16 +1025,20 @@ export function runSessionStart(projectRoot, options = {}) {
     }
     else {
         stepTimings.push({ name: "release_probe", duration_ms: 0, skipped: true });
-        lines.push(OPTIONAL_NETWORK_SKIPPED_MESSAGE);
-    }
-    try {
-        const tickler = (options.runStalenessTickler ?? maybeRunStalenessTickler)(projectRoot, {
-            now: instant,
-        });
-        lines.push(...tickler.lines);
+        if (!skipFatPath) {
+            lines.push(OPTIONAL_NETWORK_SKIPPED_MESSAGE);
+        }
     }
-    catch {
-        // Staleness tickler is best-effort and must never block session start.
+    if (!skipFatPath) {
+        try {
+            const tickler = (options.runStalenessTickler ?? maybeRunStalenessTickler)(projectRoot, {
+                now: instant,
+            });
+            lines.push(...tickler.lines);
+        }
+        catch {
+            // Staleness tickler is best-effort and must never block session start.
+        }
     }
     if (!runningInsideDeftRepo(projectRoot) && shouldEmitMigrateNudge(projectRoot)) {
         lines.push(MIGRATE_COMPLETION_NUDGE);
@@ -886,14 +1077,27 @@ export function runSessionStart(projectRoot, options = {}) {
     }
     const writeStarted = performance.now();
     const coldSessionId = (options.newSessionId ?? randomUUID)();
-    const payload = newRitualStatePayload({
-        sessionId: coldSessionId,
-        gitHead: gitHeadValue,
-        worktreePath: worktreePath(projectRoot, runGit),
-        startedAt: instant,
-        quickSteps,
-        gatedSteps,
-    });
+    const dialDict = {
+        ...ceremonyDialToDict(ceremonyDialSelection),
+        provisional: {
+            taskSize: provisionalDial.taskSize,
+            modelTier: provisionalDial.modelTier,
+            projectShape: provisionalDial.projectShape,
+            reasons: [...provisionalDial.reasons],
+        },
+    };
+    const payload = {
+        ...newRitualStatePayload({
+            sessionId: coldSessionId,
+            gitHead: gitHeadValue,
+            worktreePath: worktreePath(projectRoot, runGit),
+            startedAt: instant,
+            quickSteps,
+            gatedSteps,
+        }),
+        // #3214: record dial choice on ritual-state for audit / later re-arm context.
+        ceremony_dial: dialDict,
+    };
     let statePath;
     try {
         statePath = writeRitualState(projectRoot, payload);
@@ -915,6 +1119,7 @@ export function runSessionStart(projectRoot, options = {}) {
     const failed = Object.entries(quickSteps)
         .filter(([, step]) => !step.ok && !step.deferred_reason)
         .map(([name]) => name);
+    // verify_tools is recorded on quick_steps; failure makes ready=false.
     const code = failed.length > 0 ? 1 : 0;
     const totalMs = elapsedMs(overallStarted);
     // #3117: bind live deposit generation when payload surfaces load (cold path).
@@ -947,13 +1152,14 @@ export function runSessionStart(projectRoot, options = {}) {
         ready: code === 0,
         exit_code: code,
         ceremony_tier: COLD_CEREMONY_TIER,
+        ceremony_dial: dialDict,
         state_path: statePath,
         ...(freshnessBind ? { freshness: freshnessBind } : {}),
         quick_steps: quickSteps,
         gated_steps: gatedSteps,
         steps: stepTimings,
         duration_ms: totalMs,
-        optional_network: allowOptionalNetwork,
+        optional_network: allowOptionalNetwork && !skipFatPath,
         user_md: {
             path: userMd.path,
             rung: userMd.rung,
@@ -962,6 +1168,8 @@ 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/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

package/dist/story-ready/evaluate.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { evaluateParentLineage, formatParentLineageLine, } from "../scope/parent-lineage.js";
 import { parseAllocationSection, SOLO_KIND, SWARM_COHORT_KIND, VALID_DISPATCH_KINDS, } from "./allocation.js";
 export const ACTIVE_FOLDER = "active";
 export const ELIGIBLE_STATUS = "running";
@@ -66,7 +67,7 @@ function checkVbrief(vbriefPath) {
                 "is eligible for a story start",
         };
     }
-    return { ok: true };
+    return { ok: true, path, payload: payload };
 }
 function readyMessage(treeNote, suffix) {
     return `OK: ready to start -- ${treeNote}, vBRIEF active+running, ${suffix}`;
@@ -116,6 +117,9 @@ function classifyAllocation(fields, treeNote) {
 /**
  * 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 function evaluate(vbriefPath, options = {}) {
     const gitStatus = options.gitStatus ?? null;
@@ -147,15 +151,49 @@ export function evaluate(vbriefPath, options = {}) {
             message: `not ready: ${vbriefCheck.reason}.`,
         };
     }
+    // #3241 parent lineage (fail closed when parent authors IDs and child lacks coverage).
+    const lineage = evaluateParentLineage({
+        child: vbriefCheck.payload,
+        childPath: vbriefCheck.path,
+        projectRoot: options.projectRoot,
+        skip: options.skipParentLineage === true,
+    });
+    if (!lineage.ok) {
+        return {
+            exitCode: 1,
+            dispatchKind: null,
+            parentLineage: lineage,
+            message: `not ready: ${lineage.message}` +
+                (lineage.defect_class !== null ? ` [defect_class=${lineage.defect_class}]` : "") +
+                `\n${formatParentLineageLine(lineage)}`,
+        };
+    }
+    const lineageNote = lineage.applicable
+        ? `parent lineage OK (${lineage.parent_requirement_ids.length} req IDs` +
+            (lineage.negative_invariant_ids.length > 0
+                ? `, ${lineage.negative_invariant_ids.length} negative invariants`
+                : "") +
+            ")"
+        : null;
     const [found, fields] = options.parsed ?? parseAllocationSection(options.allocationContext ?? null);
     if (!found) {
+        const base = readyMessage(treeNote, "no `## Allocation context` section (solo path, #1371 carve-out).");
         return {
             exitCode: 0,
             dispatchKind: null,
-            message: readyMessage(treeNote, "no `## Allocation context` section (solo path, #1371 carve-out)."),
+            parentLineage: lineage,
+            message: lineageNote !== null ? `${base.replace(/\.$/, "")}; ${lineageNote}.` : base,
         };
     }
-    return classifyAllocation(fields, treeNote);
+    const classified = classifyAllocation(fields, treeNote);
+    return {
+        ...classified,
+        parentLineage: lineage,
+        message: classified.exitCode === 0 && lineageNote !== null
+            ? `${classified.message.replace(/\.$/, "")}; ${lineageNote}.`
+            : classified.message,
+    };
 }
+export { evaluateParentLineage, formatParentLineageLine, } from "../scope/parent-lineage.js";
 export { parseAllocationSection, SOLO_KIND, SWARM_COHORT_KIND };
 //# sourceMappingURL=evaluate.js.map

package/dist/swarm/index.d.ts

@@ -5,6 +5,8 @@ export * from "./finalize-cohort.js";
 export { finalizeCohortMain, parseFinalizeCohortArgv } from "./finalize-cohort-cli.js";
 export * from "./launch.js";
 export { launchMain, parseLaunchArgv } from "./launch-cli.js";
+export * from "./pre-dispatch.js";
+export { parsePreDispatchArgv, preDispatchMain } from "./pre-dispatch-cli.js";
 export * from "./readiness.js";
 export { readinessMain } from "./readiness-cli.js";
 export * from "./routing.js";

package/dist/swarm/index.js

@@ -5,6 +5,8 @@ export * from "./finalize-cohort.js";
 export { finalizeCohortMain, parseFinalizeCohortArgv } from "./finalize-cohort-cli.js";
 export * from "./launch.js";
 export { launchMain, parseLaunchArgv } from "./launch-cli.js";
+export * from "./pre-dispatch.js";
+export { parsePreDispatchArgv, preDispatchMain } from "./pre-dispatch-cli.js";
 export * from "./readiness.js";
 export { readinessMain } from "./readiness-cli.js";
 export * from "./routing.js";

package/dist/swarm/pre-dispatch-cli.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { type CompleteStatus, type PreDispatchAction } from "./pre-dispatch.js";
+export interface ParsedPreDispatchArgv {
+    projectRoot: string;
+    scopeId: string | null;
+    targetId: string | null;
+    workflowId: string | null;
+    action: PreDispatchAction | null;
+    sourceRevision: string | null;
+    attemptId: string | null;
+    status: CompleteStatus | null;
+    workerId: string | null;
+    externalRunId: string | null;
+    json: boolean;
+    help: boolean;
+}
+export declare function parsePreDispatchArgv(argv: string[]): ParsedPreDispatchArgv;
+export declare function preDispatchMain(argv?: string[]): number;
+//# sourceMappingURL=pre-dispatch-cli.d.ts.map