@deftai/directive-core 0.107.0 → 0.108.0

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

@@ -56,6 +56,11 @@ export interface MarkRitualStaleAfterCompactResult {
  * Invalidate an existing mutation ritual after host context compaction/resume (#2113).
  * Reuses ritual-state age semantics — no parallel policy stack.
  * Marks rearm_needed so recovery messaging prefers session:start --rearm when cold is unnecessary (#2992).
+ *
+ * Fail-open on an unbindable actor (#3769, operator amend 2026-08-28): compact
+ * carries no acting identity and runs inside a hook budget, so a skipped write
+ * has no surface a human reliably sees. The accepted cost is that an
+ * unidentified compact re-arms whoever owns the record.
  */
 export declare function markRitualStaleAfterCompact(projectRoot: string, input?: {
     now?: Date;

package/dist/session/ritual-sentinel.js

@@ -209,6 +209,11 @@ export const RITUAL_STALE_EPOCH = new Date("1970-01-01T00:00:00Z");
  * Invalidate an existing mutation ritual after host context compaction/resume (#2113).
  * Reuses ritual-state age semantics — no parallel policy stack.
  * Marks rearm_needed so recovery messaging prefers session:start --rearm when cold is unnecessary (#2992).
+ *
+ * Fail-open on an unbindable actor (#3769, operator amend 2026-08-28): compact
+ * carries no acting identity and runs inside a hook budget, so a skipped write
+ * has no surface a human reliably sees. The accepted cost is that an
+ * unidentified compact re-arms whoever owns the record.
  */
 export function markRitualStaleAfterCompact(projectRoot, input = {}) {
     const now = input.now ?? new Date();

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

@@ -22,6 +22,8 @@ export declare const SESSION_READY_FAILED = "failed";
 export type SessionReadyPath = typeof SESSION_READY_FAST_PATH | typeof SESSION_READY_RECOVERED | typeof SESSION_READY_VERIFIED | typeof SESSION_READY_FAILED;
 export interface SessionReadyResult {
     readonly code: number;
+    /** One resolved owner carried through preview, verification, and claim (#3611). */
+    readonly sessionId: string;
     readonly message: string;
     readonly path: SessionReadyPath;
     readonly lines: readonly string[];
@@ -40,9 +42,11 @@ export interface SessionReadyOptions {
     readonly runGit?: GitRunner;
     readonly runner?: RitualRunner;
     readonly env?: NodeJS.ProcessEnv;
+    /** Explicit lifecycle owner resolved by the host/session bridge (#3611). */
+    readonly sessionId?: string;
     /** When set, overrides DEFT_TRIAGE_REPO / git remote inference for cache recovery. */
     readonly repo?: string | null;
-    readonly sessionStartOptions?: Omit<SessionStartOptions, "now" | "runGit" | "env">;
+    readonly sessionStartOptions?: Omit<SessionStartOptions, "now" | "runGit" | "env" | "sessionId">;
     readonly inspectRitual?: (projectRoot: string, options: InspectSessionRitualOptions) => VerifyResult;
     readonly verifyRitual?: (projectRoot: string, options: VerifySessionRitualOptions) => VerifyResult;
     readonly runStart?: (projectRoot: string, options: SessionStartOptions) => SessionStartResult;

package/dist/session/session-ready.js

@@ -15,7 +15,7 @@ import { execFileSync } from "node:child_process";
 import { join } from "node:path";
 import { cacheFetchAll } from "../cache/fetch.js";
 import { formatFrameworkCommand } from "../render/framework-commands.js";
-import { applyWorktreeOccupancy, } from "./occupancy.js";
+import { applyWorktreeOccupancy, resolveOccupancySessionId, } from "./occupancy.js";
 import { runSessionStart, } from "./session-start.js";
 import { inspectSessionRitual, verifySessionRitual, } from "./verify-session-ritual.js";
 export const SESSION_READY_FAST_PATH = "fast";
@@ -91,28 +91,39 @@ export function runSessionReady(projectRoot, options = {}) {
     const env = options.env ?? process.env;
     const lines = [];
     const steps = [];
+    // #3611: resolve once before any occupancy preview or nested lifecycle call.
+    // A nested start must report the same persisted owner; adopting a different
+    // result would silently split the invocation's identity.
+    const sessionId = resolveOccupancySessionId({
+        sessionId: options.sessionId,
+        env,
+        newSessionId: options.sessionStartOptions?.newSessionId,
+    });
+    let nestedStartClaimedOccupancy = false;
     const inspect = options.inspectRitual ?? inspectSessionRitual;
     const verify = options.verifyRitual ?? verifySessionRitual;
     const start = options.runStart ?? runSessionStart;
     const fetchAll = options.fetchAll ?? cacheFetchAll;
     const inferRepo = options.inferRepo ?? ((root) => inferSessionReadyRepo(root, env));
     const applyOccupancy = options.applyOccupancy ?? applyWorktreeOccupancy;
-    const occupancyInput = (write) => ({
+    const occupancyInput = (write, steal) => ({
+        sessionId,
         env,
         now,
-        steal: options.sessionStartOptions?.steal,
+        steal,
         confirm: options.sessionStartOptions?.confirm,
         occupant: options.sessionStartOptions?.occupant,
-        newSessionId: options.sessionStartOptions?.newSessionId,
         intent: options.sessionStartOptions?.occupancyIntent ?? "mutation",
         write,
     });
-    const previewOccupancy = applyOccupancy(projectRoot, occupancyInput(false));
+    const requestedSteal = options.sessionStartOptions?.steal === true;
+    const previewOccupancy = applyOccupancy(projectRoot, occupancyInput(false, requestedSteal));
     if (previewOccupancy.code !== 0) {
         const message = previewOccupancy.message;
         lines.push(message);
         return {
             code: previewOccupancy.code,
+            sessionId,
             message,
             path: SESSION_READY_FAILED,
             lines,
@@ -120,13 +131,14 @@ export function runSessionReady(projectRoot, options = {}) {
             duration_ms: elapsedMs(started),
         };
     }
-    const claimOnSuccess = () => applyOccupancy(projectRoot, occupancyInput(true));
+    const claimOnSuccess = () => applyOccupancy(projectRoot, occupancyInput(true, nestedStartClaimedOccupancy ? false : requestedSteal));
     const finishReady = (path, message) => {
         const claimed = claimOnSuccess();
         if (claimed.code !== 0) {
             lines.push(claimed.message);
             return {
                 code: claimed.code,
+                sessionId,
                 message: claimed.message,
                 path: SESSION_READY_FAILED,
                 lines,
@@ -134,9 +146,39 @@ export function runSessionReady(projectRoot, options = {}) {
                 duration_ms: elapsedMs(started),
             };
         }
+        // The verified ritual can change while the final occupancy claim is being
+        // persisted. Re-read only the exact bound ritual owner after the claim;
+        // never return success with a lease/ritual split (#3611). Files remain a
+        // cooperative gate, so this narrows rather than eliminates TOCTOU.
+        const postClaimRitual = inspect(projectRoot, {
+            tier: "gated",
+            posture: "mutation",
+            now,
+            runGit: options.runGit,
+        });
+        if (postClaimRitual.code !== 0 || postClaimRitual.boundSessionId !== sessionId) {
+            const actual = postClaimRitual.boundSessionId ?? "<unbound>";
+            const detail = postClaimRitual.code === 0
+                ? `post-claim ritual owner ${actual}`
+                : `post-claim ritual inspection failed: ${postClaimRitual.message}`;
+            const failure = `session:ready ${detail}, but occupancy is held by ${sessionId}. ` +
+                "Readiness remains fail-closed. Re-run session:start with the same explicit " +
+                "--session-id to align ritual and occupancy state.";
+            lines.push(failure);
+            return {
+                code: postClaimRitual.code === 0 ? 1 : postClaimRitual.code,
+                sessionId,
+                message: failure,
+                path: SESSION_READY_FAILED,
+                lines,
+                steps,
+                duration_ms: elapsedMs(started),
+            };
+        }
         lines.push(message);
         return {
             code: 0,
+            sessionId,
             message,
             path,
             lines,
@@ -144,6 +186,22 @@ export function runSessionReady(projectRoot, options = {}) {
             duration_ms: elapsedMs(started),
         };
     };
+    const ownerAlignmentFailure = (actualOwner, context = "verified ritual") => {
+        const actual = actualOwner ?? "<unbound>";
+        const message = `session:ready ${context} owner ${actual}, but the resolved occupancy owner is ` +
+            `${sessionId}. Refusing to claim a mismatched lease. Re-run session:start with the ` +
+            "same explicit --session-id to align ritual and occupancy state.";
+        lines.push(message);
+        return {
+            code: 1,
+            sessionId,
+            message,
+            path: SESSION_READY_FAILED,
+            lines,
+            steps,
+            duration_ms: elapsedMs(started),
+        };
+    };
     const verifyOpts = {
         tier: "gated",
         posture: "mutation",
@@ -159,7 +217,10 @@ export function runSessionReady(projectRoot, options = {}) {
         now,
         runGit: options.runGit,
     });
-    if (gatedInspect.code === 0) {
+    // A confirmed owner transition must also rewrite ritual state. Even a green
+    // legacy ritual cannot take the fast path, because stealing only in the
+    // final occupancy claim would leave lease and ritual owners mismatched.
+    if (gatedInspect.code === 0 && gatedInspect.boundSessionId === sessionId && !requestedSteal) {
         steps.push("verify:session-ritual:gated");
         const refreshed = verify(projectRoot, verifyOpts);
         if (!isGatedVerifyActuallyReady(refreshed)) {
@@ -169,6 +230,7 @@ export function runSessionReady(projectRoot, options = {}) {
             lines.push(message);
             return {
                 code: refreshed.code === 0 ? 1 : refreshed.code,
+                sessionId,
                 message,
                 path: SESSION_READY_FAILED,
                 lines,
@@ -176,6 +238,9 @@ export function runSessionReady(projectRoot, options = {}) {
                 duration_ms: elapsedMs(started),
             };
         }
+        if (refreshed.boundSessionId !== sessionId) {
+            return ownerAlignmentFailure(refreshed.boundSessionId);
+        }
         return finishReady(SESSION_READY_FAST_PATH, "OK session ready (gated ritual already fresh).");
     }
     // --- Ensure quick-tier ritual state when missing / stale / drifted ---
@@ -185,13 +250,14 @@ export function runSessionReady(projectRoot, options = {}) {
         now,
         runGit: options.runGit,
     });
-    if (quickInspect.code !== 0) {
+    if (quickInspect.code !== 0 || quickInspect.boundSessionId !== sessionId || requestedSteal) {
         steps.push("session:start");
         const startResult = start(projectRoot, {
             ...options.sessionStartOptions,
             now,
             runGit: options.runGit,
             env,
+            sessionId,
             writeHistory: options.sessionStartOptions?.writeHistory ?? false,
         });
         for (const line of startResult.lines) {
@@ -203,6 +269,7 @@ export function runSessionReady(projectRoot, options = {}) {
             lines.push(message);
             return {
                 code: startResult.code,
+                sessionId,
                 message,
                 path: SESSION_READY_FAILED,
                 lines,
@@ -210,11 +277,26 @@ export function runSessionReady(projectRoot, options = {}) {
                 duration_ms: elapsedMs(started),
             };
         }
+        const startedOccupancy = startResult.payload.occupancy;
+        if (startedOccupancy !== null &&
+            typeof startedOccupancy === "object" &&
+            !Array.isArray(startedOccupancy)) {
+            const persistedSessionId = startedOccupancy.session_id;
+            if (typeof persistedSessionId === "string" && persistedSessionId.trim().length > 0) {
+                if (persistedSessionId.trim() !== sessionId) {
+                    return ownerAlignmentFailure(persistedSessionId.trim(), "nested session:start");
+                }
+                nestedStartClaimedOccupancy = true;
+            }
+        }
     }
     // --- Gated verify (lazy doctor + cache_fresh) ---
     steps.push("verify:session-ritual:gated");
     let verifyResult = verify(projectRoot, verifyOpts);
     if (isGatedVerifyActuallyReady(verifyResult)) {
+        if (verifyResult.boundSessionId !== sessionId) {
+            return ownerAlignmentFailure(verifyResult.boundSessionId);
+        }
         return finishReady(SESSION_READY_VERIFIED, "OK session ready (gated ritual verified).");
     }
     if (verifyResult.code === 0 && verifyResult.bypassed) {
@@ -222,6 +304,7 @@ export function runSessionReady(projectRoot, options = {}) {
         lines.push(message);
         return {
             code: 1,
+            sessionId,
             message,
             path: SESSION_READY_FAILED,
             lines,
@@ -238,6 +321,7 @@ export function runSessionReady(projectRoot, options = {}) {
             lines.push(message);
             return {
                 code: 1,
+                sessionId,
                 message,
                 path: SESSION_READY_FAILED,
                 lines,
@@ -262,6 +346,7 @@ export function runSessionReady(projectRoot, options = {}) {
             lines.push(message);
             return {
                 code: 1,
+                sessionId,
                 message,
                 path: SESSION_READY_FAILED,
                 lines,
@@ -272,6 +357,9 @@ export function runSessionReady(projectRoot, options = {}) {
         steps.push("verify:session-ritual:gated:retry");
         verifyResult = verify(projectRoot, { ...verifyOpts, forceGatedSteps: [] });
         if (isGatedVerifyActuallyReady(verifyResult)) {
+            if (verifyResult.boundSessionId !== sessionId) {
+                return ownerAlignmentFailure(verifyResult.boundSessionId);
+            }
             return finishReady(SESSION_READY_RECOVERED, "OK session ready (recovered via cache refresh).");
         }
         if (verifyResult.code === 0 && verifyResult.bypassed) {
@@ -279,6 +367,7 @@ export function runSessionReady(projectRoot, options = {}) {
             lines.push(message);
             return {
                 code: 1,
+                sessionId,
                 message,
                 path: SESSION_READY_FAILED,
                 lines,
@@ -293,6 +382,7 @@ export function runSessionReady(projectRoot, options = {}) {
     lines.push(message);
     return {
         code: verifyResult.code,
+        sessionId,
         message,
         path: SESSION_READY_FAILED,
         lines,

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

@@ -10,7 +10,7 @@ import type { GitRunner } from "./git.js";
 import { type ApplyOccupancyInput, type OccupancyDecision } from "./occupancy.js";
 import { type OrientationBundle, type RunOrientationOptions } from "./orientation-compression.js";
 import { type ReleaseAvailabilityProbeOptions } from "./release-availability.js";
-import { type RitualState, ritualStatePath } from "./ritual-sentinel.js";
+import { type RitualState, ritualStatePath, writeRitualState } from "./ritual-sentinel.js";
 import { type ToolchainPreflightOptions, type ToolchainPreflightResult } from "./toolchain-preflight.js";
 export declare const SESSION_POSTURES: readonly ["read-only", "mutation"];
 export type SessionPosture = (typeof SESSION_POSTURES)[number];
@@ -76,6 +76,10 @@ export interface SessionStartOptions {
     readonly now?: Date;
     readonly writeHistory?: boolean;
     readonly runGit?: GitRunner;
+    /** Test seam for deterministic ritual persistence failures. */
+    readonly writeRitualState?: typeof writeRitualState;
+    /** Explicit lifecycle owner resolved by the host/session bridge (#3611). */
+    readonly sessionId?: string;
     readonly newSessionId?: () => string;
     /** #3433: steal the worktree occupancy lease. Requires confirm + occupant. */
     readonly steal?: boolean;

package/dist/session/session-start.js

@@ -26,7 +26,7 @@ import { verifyRequiredTools } from "../verify-env/verify-tools.js";
 import { ceremonyDialEvidenceToDict, collectCeremonyDialConsumerEvidence, formatCeremonyDialEvidenceLine, mergeCeremonyDialInputsWithConsumerEvidence, } from "./ceremony-dial-evidence.js";
 import { effortBudgetToDict, maybeFormatEffortBudgetLines, resolveProductionHostEffortDescriptor, } from "./effort-budget.js";
 import { defaultGitRunner, gitHead, gitIsAncestor, worktreePath } from "./git.js";
-import { applyWorktreeOccupancy, } from "./occupancy.js";
+import { applyWorktreeOccupancy, resolveOccupancySessionId, } from "./occupancy.js";
 import { resolveSessionCompact, runOrientationCompression, } from "./orientation-compression.js";
 import { emitSessionStartProcessCost, formatSessionStartCeremonyCostLine } from "./process-cost.js";
 import { probeSessionReleaseAvailability, } from "./release-availability.js";
@@ -110,6 +110,13 @@ const STEP_ALIASES = {
     triage: "triage_welcome",
     "triage-welcome": "triage_welcome",
 };
+function ritualPersistenceTransitionError(cause, sessionId) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    return new Error(`Occupancy is now held by session ${sessionId}, but ritual-state persistence failed: ${detail}. ` +
+        "Direct writes remain fail-closed until both owners align. Re-run " +
+        "`deft session:start --rearm --session-id=<same-session-id>` when re-arm is eligible; " +
+        "otherwise run `deft session:start --session-id=<same-session-id>` for a cold ceremony.");
+}
 /** Format preferred `session:start` recovery command for cold vs re-arm (#2992). */
 export function formatSessionStartRecoveryCommand(tier = "cold") {
     if (tier === "rearm") {
@@ -386,6 +393,7 @@ function resolveSessionScmReadiness(options, allowOptionalNetwork) {
             authState: "unknown",
             githubAuthMode: "host-gh",
             runtimeMode: "local-unsandboxed",
+            runtimeModeReason: null,
             injectedTokenPresent: false,
             depth: allowOptionalNetwork ? "deep" : "shallow",
             detail: "SCM readiness probe failed unexpectedly; treating SCM-dependent gates as skipped",
@@ -463,11 +471,11 @@ function resolveEffortBudget(options) {
         };
     }
 }
-function occupancyInput(options, now, write) {
+function occupancyInput(options, sessionId, now, write) {
     return {
+        sessionId,
         env: options.env,
         now,
-        newSessionId: options.newSessionId,
         steal: options.steal,
         confirm: options.confirm,
         occupant: options.occupant,
@@ -475,9 +483,9 @@ function occupancyInput(options, now, write) {
         write,
     };
 }
-function runOccupancy(projectRoot, options, now, write) {
+function runOccupancy(projectRoot, options, sessionId, now, write) {
     const apply = options.applyOccupancy ?? applyWorktreeOccupancy;
-    return apply(projectRoot, occupancyInput(options, now, write));
+    return apply(projectRoot, occupancyInput(options, sessionId, now, write));
 }
 function occupancyDeniedResult(occupancy, environment) {
     return {
@@ -497,8 +505,8 @@ function occupancyDeniedResult(occupancy, environment) {
         lines: occupancy.message.split("\n"),
     };
 }
-function persistOccupancyOrDeny(projectRoot, options, now, environment) {
-    const occupancy = runOccupancy(projectRoot, options, now, true);
+function persistOccupancyOrDeny(projectRoot, options, sessionId, now, environment) {
+    const occupancy = runOccupancy(projectRoot, options, sessionId, now, true);
     if (occupancy.code !== 0)
         return occupancyDeniedResult(occupancy, environment);
     return occupancy;
@@ -553,7 +561,7 @@ function runReadOnlySessionStart(projectRoot, options, instant, environment) {
     };
     return { code: 0, payload: resultPayload, lines };
 }
-function runSessionRearm(projectRoot, options, instant, environment) {
+function runSessionRearm(projectRoot, options, sessionId, instant, environment) {
     const overallStarted = performance.now();
     const runGit = options.runGit ?? defaultGitRunner;
     const eligibility = assessRearmEligibility(projectRoot, { runGit });
@@ -581,7 +589,7 @@ function runSessionRearm(projectRoot, options, instant, environment) {
             lines: [formatEnvironmentContext(environment), message],
         };
     }
-    const plannedOccupancy = runOccupancy(projectRoot, options, instant, options.steal === true);
+    const plannedOccupancy = runOccupancy(projectRoot, options, sessionId, instant, false);
     if (plannedOccupancy.code !== 0) {
         return occupancyDeniedResult(plannedOccupancy, environment);
     }
@@ -683,7 +691,7 @@ function runSessionRearm(projectRoot, options, instant, environment) {
     };
     const gatedSteps = restampSteps(eligibility.state.gatedSteps, instant);
     const writeStarted = performance.now();
-    const persistedOccupancy = persistOccupancyOrDeny(projectRoot, options, instant, environment);
+    const persistedOccupancy = persistOccupancyOrDeny(projectRoot, options, sessionId, instant, environment);
     if ("payload" in persistedOccupancy) {
         return persistedOccupancy;
     }
@@ -703,7 +711,7 @@ function runSessionRearm(projectRoot, options, instant, environment) {
     };
     let statePath;
     try {
-        statePath = writeRitualState(projectRoot, writePayload);
+        statePath = (options.writeRitualState ?? writeRitualState)(projectRoot, writePayload);
     }
     catch (cause) {
         // #2994: still record failed attempt when ritual-state write throws.
@@ -722,7 +730,7 @@ function runSessionRearm(projectRoot, options, instant, environment) {
                 { name: "ritual_write", duration_ms: elapsedMs(writeStarted) },
             ],
         }, { projectRoot });
-        throw cause;
+        throw ritualPersistenceTransitionError(cause, rearmSessionId);
     }
     const stepTimings = [
         { name: "alignment", duration_ms: 0 },
@@ -878,9 +886,16 @@ export function runSessionStart(projectRoot, options = {}) {
     if (posture === READ_ONLY_POSTURE) {
         return runReadOnlySessionStart(projectRoot, options, instant, environment);
     }
+    // #3611: resolve once per mutation invocation. Every occupancy evaluation,
+    // persistence write, and ritual-state payload below receives this exact ID.
+    const sessionId = resolveOccupancySessionId({
+        sessionId: options.sessionId,
+        env: options.env,
+        newSessionId: options.newSessionId,
+    });
     // #2992: re-arm path refreshes clock/bind without fat cold ceremony.
     if (ceremonyTier === REARM_CEREMONY_TIER) {
-        return runSessionRearm(projectRoot, options, instant, environment);
+        return runSessionRearm(projectRoot, options, sessionId, instant, environment);
     }
     const overallStarted = performance.now();
     const stepTimings = [];
@@ -937,7 +952,7 @@ export function runSessionStart(projectRoot, options = {}) {
             lines: [formatEnvironmentContext(environment), payload.message],
         };
     }
-    const plannedOccupancy = runOccupancy(projectRoot, options, instant, options.steal === true);
+    const plannedOccupancy = runOccupancy(projectRoot, options, sessionId, instant, false);
     if (plannedOccupancy.code !== 0) {
         return occupancyDeniedResult(plannedOccupancy, environment);
     }
@@ -1314,7 +1329,7 @@ export function runSessionStart(projectRoot, options = {}) {
         lines.push(consentPrompt.trimEnd());
     }
     const writeStarted = performance.now();
-    const persistedOccupancy = persistOccupancyOrDeny(projectRoot, options, instant, environment);
+    const persistedOccupancy = persistOccupancyOrDeny(projectRoot, options, sessionId, instant, environment);
     if ("payload" in persistedOccupancy) {
         return persistedOccupancy;
     }
@@ -1348,7 +1363,7 @@ export function runSessionStart(projectRoot, options = {}) {
     };
     let statePath;
     try {
-        statePath = writeRitualState(projectRoot, payload);
+        statePath = (options.writeRitualState ?? writeRitualState)(projectRoot, payload);
     }
     catch (cause) {
         // #2994: still record failed attempt when ritual-state write throws.
@@ -1361,7 +1376,7 @@ export function runSessionStart(projectRoot, options = {}) {
             optionalNetwork: allowOptionalNetwork,
             steps: stepTimings,
         }, { projectRoot });
-        throw cause;
+        throw ritualPersistenceTransitionError(cause, coldSessionId);
     }
     stepTimings.push({ name: "ritual_write", duration_ms: elapsedMs(writeStarted) });
     const failed = Object.entries(quickSteps)

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

@@ -9,13 +9,15 @@
  * remedy without embedding env values.
  */
 import { type CheckGateSpec } from "../check/gate-lists.js";
+import { type PackageManager, type PackageManagerResolutionSource } from "../resolution/package-manager.js";
+/** Maintainer toolchain remains pnpm-based. Consumer tools are selected dynamically. */
 export declare const TOOLCHAIN_PREFLIGHT_TOOLS: readonly ["task", "pnpm", "node", "git"];
-export type ToolchainPreflightTool = (typeof TOOLCHAIN_PREFLIGHT_TOOLS)[number];
+export type ToolchainPreflightTool = "task" | PackageManager | "node" | "git";
 export type ToolchainPreflightStatus = "ok" | "missing" | "degraded";
 /** How a missing tool affects check dispatch (#3335). */
 export type ToolchainPreflightImpact = "none" | "degraded";
 export interface ToolchainPreflightFinding {
-    readonly tool: ToolchainPreflightTool | "cli_dist";
+    readonly tool: ToolchainPreflightTool | "package_manager" | "cli_dist";
     readonly present: boolean;
     /** Machine-stable cause code (never embeds env values). */
     readonly cause: string | null;
@@ -40,6 +42,10 @@ export interface ToolchainPreflightResult {
      * Product-ordering of remaining gates is owned by #3284.
      */
     readonly skipGateIds: readonly string[];
+    /** Closed manager selected for this project, or null on strict selection failure. */
+    readonly packageManager?: PackageManager | null;
+    /** Selection provenance; maintainer source is deliberately fixed to pnpm. */
+    readonly packageManagerSource?: PackageManagerResolutionSource | "maintainer" | null;
 }
 export interface ToolchainPreflightOptions {
     readonly projectRoot?: string;
@@ -61,17 +67,21 @@ export interface ToolchainPreflightOptions {
      * frameworkRoot vs projectRoot (#3335 / #3324).
      */
     readonly consumerDeposit?: boolean;
+    /** Environment map used for consumer package-manager precedence. */
+    readonly env?: NodeJS.ProcessEnv;
 }
 /**
  * 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 PACKAGE_MANAGER_DEPENDENT_GATE_IDS: readonly string[];
+/** @deprecated use PACKAGE_MANAGER_DEPENDENT_GATE_IDS. */
 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.
+ * Run done-gate toolchain preflight. Read-only probe — never installs or builds.
  */
 export declare function runToolchainPreflight(options?: ToolchainPreflightOptions): ToolchainPreflightResult;
 /** Serialize preflight for run-summary / ritual-state (no env values). */