@deftai/directive-core 0.99.0 → 0.100.0

package/dist/session/effort-budget.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Hard effort-budget detection and bank-the-pass guidance (#3266).
+ *
+ * When a host/harness declares max-turns or max-cost, agents must bank the
+ * *stated* acceptance pass before self-imposed deepening. Detection is
+ * advisory at session start (env / flags / host capability pointer #1461);
+ * skill text in deft-directive-build and pre-pr owns the behavioral rule.
+ *
+ * Composes dual-stop (#2442): dual-stop is the failure/budget envelope;
+ * this module is the success-side analog (do not gold-plate past the bar
+ * when remaining budget cannot also fund a fix for deeper findings).
+ *
+ * Fail-loud (#1006): when deepening is skipped for budget, summaries must
+ * say so — never silent gold-plate or silent skip.
+ */
+/** Canonical max-turns env (hard turn budget). */
+export declare const ENV_MAX_TURNS = "DEFT_MAX_TURNS";
+/** Canonical max cost/budget env (opaque cost units from the host). */
+export declare const ENV_MAX_BUDGET = "DEFT_MAX_BUDGET";
+/** Remaining turns when the host updates mid-run. */
+export declare const ENV_REMAINING_TURNS = "DEFT_REMAINING_TURNS";
+/** Remaining cost units when the host updates mid-run. */
+export declare const ENV_REMAINING_BUDGET = "DEFT_REMAINING_BUDGET";
+/**
+ * Explicit hard-cap flag when the host has a limit but does not expose a number
+ * (truthy → hard-capped with unknown numeric ceiling).
+ */
+export declare const ENV_HARD_BUDGET = "DEFT_HARD_BUDGET";
+/**
+ * Optional JSON host capability fragment for effort caps (#1461 / #3266).
+ * Example: `{"maxTurns":120,"maxBudget":10,"hardBudget":true}`.
+ * Production session:start merges this when `effortBudgetSeams.hostDescriptor` is unset.
+ */
+export declare const ENV_HOST_EFFORT_BUDGET = "DEFT_HOST_EFFORT_BUDGET";
+/** Additional env keys accepted as max-turns aliases (harness / CLI common). */
+export declare const MAX_TURNS_ENV_ALIASES: readonly ["DEFT_MAX_TURNS", "MAX_TURNS", "AGENT_MAX_TURNS", "DEFT_AGENT_MAX_TURNS", "CURSOR_MAX_TURNS"];
+/** Additional env keys accepted as max-budget/cost aliases. */
+export declare const MAX_BUDGET_ENV_ALIASES: readonly ["DEFT_MAX_BUDGET", "MAX_BUDGET", "AGENT_BUDGET", "DEFT_AGENT_BUDGET", "AGENT_MAX_BUDGET"];
+export type EffortBudgetKind = "none" | "max-turns" | "max-cost" | "both" | "hard-flag";
+/** Whether the session is under a detectable hard cap. */
+export type EffortBudgetPosture = "unbounded" | "hard-capped";
+/**
+ * Recommended self-verification depth given budget + stated-AC status.
+ * - stated-only: bank the stated bar; do not start self-imposed suites
+ * - stated-then-deepen: stated bar first; deepen only with remaining budget
+ * - unconstrained-deepen: no hard budget signal; dual-stop still applies
+ */
+export type VerificationDepthPolicy = "stated-only" | "stated-then-deepen" | "unconstrained-deepen";
+export interface HardEffortBudget {
+    readonly detected: boolean;
+    readonly posture: EffortBudgetPosture;
+    readonly kind: EffortBudgetKind;
+    /** Hard max turns when known; null if only a flag or cost cap is present. */
+    readonly maxTurns: number | null;
+    /** Hard max cost units when known (opaque host units). */
+    readonly maxBudget: number | null;
+    /** Remaining turns when the host exposes them; else equals maxTurns. */
+    readonly remainingTurns: number | null;
+    /** Remaining cost units when exposed; else equals maxBudget. */
+    readonly remainingBudget: number | null;
+    /** Env keys / host signals that contributed. */
+    readonly sources: readonly string[];
+}
+export interface DetectHardEffortBudgetInput {
+    readonly environ?: Readonly<Record<string, string | undefined>>;
+    /**
+     * Optional host capability descriptor fragment (#1461 pointer).
+     * Accepts maxTurns / max_turns / maxBudget / max_budget / hardBudget.
+     */
+    readonly hostDescriptor?: Readonly<Record<string, unknown>> | null;
+}
+export interface RecommendVerificationDepthInput {
+    readonly budget: HardEffortBudget;
+    /** Whether stated acceptance criteria (issue/xBRIEF AC) are already met. */
+    readonly statedAcceptanceMet: boolean;
+    /**
+     * Reserve for a fix after a deeper finding (turns). Default 3 — if remaining
+     * is below this, do not start self-imposed deepening.
+     */
+    readonly deepenReserveTurns?: number;
+    /** Reserve for a fix after a deeper finding (cost units). Default null (ignore). */
+    readonly deepenReserveBudget?: number | null;
+}
+/**
+ * Parse host effort-budget descriptor from env JSON (#1461 / #3266 production wire).
+ * Returns null when unset or unparseable (fail-open).
+ */
+export declare function parseHostEffortBudgetEnv(environ?: Readonly<Record<string, string | undefined>>): Readonly<Record<string, unknown>> | null;
+/**
+ * Production host-adapter: translate host/harness native signals into a descriptor
+ * object for detectHardEffortBudget (#1461 / #3266).
+ *
+ * Sources (later keys fill gaps only):
+ * 1. `DEFT_HOST_EFFORT_BUDGET` JSON (`maxTurns` / `maxBudget` / `hardBudget`)
+ * 2. Common harness env aliases already accepted as max-turns / max-budget
+ * 3. Explicit hard-budget flag env
+ *
+ * session:start CLI and resolveEffortBudget always call this so descriptor-only
+ * host caps are not lost when the host never set DEFT_HOST_EFFORT_BUDGET.
+ */
+export declare function resolveProductionHostEffortDescriptor(environ?: Readonly<Record<string, string | undefined>>): Readonly<Record<string, unknown>>;
+/**
+ * Detect a hard turn/cost budget from env and optional host descriptor (#3266).
+ * Defaults to unbounded when no signal is present.
+ * When `hostDescriptor` is omitted, falls back to `DEFT_HOST_EFFORT_BUDGET` JSON.
+ */
+export declare function detectHardEffortBudget(input?: DetectHardEffortBudgetInput): HardEffortBudget;
+/**
+ * Recommend self-verification depth: bank stated AC before deepening (#3266).
+ */
+export declare function recommendVerificationDepth(input: RecommendVerificationDepthInput): VerificationDepthPolicy;
+/**
+ * Operator-visible note when self-imposed deepening is skipped for budget (#1006).
+ */
+export declare function formatDeepeningSkippedNote(budget: HardEffortBudget, reason?: string): string;
+/** Session-start / JSON payload shape. */
+export declare function effortBudgetToDict(budget: HardEffortBudget): Record<string, unknown>;
+/**
+ * Format operator-facing effort-budget lines for session:start (#3266).
+ * Always emits one summary line; adds bank-the-pass guidance when hard-capped.
+ */
+export declare function formatEffortBudgetLines(budget: HardEffortBudget): string[];
+/**
+ * Detect + format; fail-open for session-start callers.
+ */
+export declare function maybeFormatEffortBudgetLines(input?: DetectHardEffortBudgetInput): {
+    budget: HardEffortBudget;
+    lines: string[];
+};
+//# sourceMappingURL=effort-budget.d.ts.map

package/dist/session/effort-budget.js

@@ -0,0 +1,334 @@
+/**
+ * Hard effort-budget detection and bank-the-pass guidance (#3266).
+ *
+ * When a host/harness declares max-turns or max-cost, agents must bank the
+ * *stated* acceptance pass before self-imposed deepening. Detection is
+ * advisory at session start (env / flags / host capability pointer #1461);
+ * skill text in deft-directive-build and pre-pr owns the behavioral rule.
+ *
+ * Composes dual-stop (#2442): dual-stop is the failure/budget envelope;
+ * this module is the success-side analog (do not gold-plate past the bar
+ * when remaining budget cannot also fund a fix for deeper findings).
+ *
+ * Fail-loud (#1006): when deepening is skipped for budget, summaries must
+ * say so — never silent gold-plate or silent skip.
+ */
+/** Canonical max-turns env (hard turn budget). */
+export const ENV_MAX_TURNS = "DEFT_MAX_TURNS";
+/** Canonical max cost/budget env (opaque cost units from the host). */
+export const ENV_MAX_BUDGET = "DEFT_MAX_BUDGET";
+/** Remaining turns when the host updates mid-run. */
+export const ENV_REMAINING_TURNS = "DEFT_REMAINING_TURNS";
+/** Remaining cost units when the host updates mid-run. */
+export const ENV_REMAINING_BUDGET = "DEFT_REMAINING_BUDGET";
+/**
+ * Explicit hard-cap flag when the host has a limit but does not expose a number
+ * (truthy → hard-capped with unknown numeric ceiling).
+ */
+export const ENV_HARD_BUDGET = "DEFT_HARD_BUDGET";
+/**
+ * Optional JSON host capability fragment for effort caps (#1461 / #3266).
+ * Example: `{"maxTurns":120,"maxBudget":10,"hardBudget":true}`.
+ * Production session:start merges this when `effortBudgetSeams.hostDescriptor` is unset.
+ */
+export const ENV_HOST_EFFORT_BUDGET = "DEFT_HOST_EFFORT_BUDGET";
+/** Additional env keys accepted as max-turns aliases (harness / CLI common). */
+export const MAX_TURNS_ENV_ALIASES = [
+    ENV_MAX_TURNS,
+    "MAX_TURNS",
+    "AGENT_MAX_TURNS",
+    "DEFT_AGENT_MAX_TURNS",
+    "CURSOR_MAX_TURNS",
+];
+/** Additional env keys accepted as max-budget/cost aliases. */
+export const MAX_BUDGET_ENV_ALIASES = [
+    ENV_MAX_BUDGET,
+    "MAX_BUDGET",
+    "AGENT_BUDGET",
+    "DEFT_AGENT_BUDGET",
+    "AGENT_MAX_BUDGET",
+];
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+function envTruthy(value) {
+    return TRUTHY.has((value ?? "").trim().toLowerCase());
+}
+function parsePositiveNumber(raw) {
+    if (raw === undefined)
+        return null;
+    const text = raw.trim();
+    if (!text)
+        return null;
+    const n = Number(text);
+    if (!Number.isFinite(n) || n < 0)
+        return null;
+    return n;
+}
+function firstNumericFromEnv(environ, keys) {
+    for (const key of keys) {
+        const value = parsePositiveNumber(environ[key]);
+        if (value !== null) {
+            return { value, source: `env:${key}` };
+        }
+    }
+    return { value: null, source: null };
+}
+function hostNumeric(host, keys) {
+    if (!host)
+        return { value: null, source: null };
+    for (const key of keys) {
+        const raw = host[key];
+        if (typeof raw === "number" && Number.isFinite(raw) && raw >= 0) {
+            return { value: raw, source: `host:${key}` };
+        }
+        if (typeof raw === "string") {
+            const n = parsePositiveNumber(raw);
+            if (n !== null)
+                return { value: n, source: `host:${key}` };
+        }
+    }
+    return { value: null, source: null };
+}
+function hostTruthy(host, keys) {
+    if (!host)
+        return null;
+    for (const key of keys) {
+        const raw = host[key];
+        if (raw === true)
+            return `host:${key}`;
+        if (typeof raw === "string" && envTruthy(raw))
+            return `host:${key}`;
+        if (typeof raw === "number" && raw === 1)
+            return `host:${key}`;
+    }
+    return null;
+}
+/**
+ * Parse host effort-budget descriptor from env JSON (#1461 / #3266 production wire).
+ * Returns null when unset or unparseable (fail-open).
+ */
+export function parseHostEffortBudgetEnv(environ = process.env) {
+    const raw = (environ[ENV_HOST_EFFORT_BUDGET] ?? "").trim();
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // fail-open
+    }
+    return null;
+}
+/**
+ * Production host-adapter: translate host/harness native signals into a descriptor
+ * object for detectHardEffortBudget (#1461 / #3266).
+ *
+ * Sources (later keys fill gaps only):
+ * 1. `DEFT_HOST_EFFORT_BUDGET` JSON (`maxTurns` / `maxBudget` / `hardBudget`)
+ * 2. Common harness env aliases already accepted as max-turns / max-budget
+ * 3. Explicit hard-budget flag env
+ *
+ * session:start CLI and resolveEffortBudget always call this so descriptor-only
+ * host caps are not lost when the host never set DEFT_HOST_EFFORT_BUDGET.
+ */
+export function resolveProductionHostEffortDescriptor(environ = process.env) {
+    const out = {
+        ...(parseHostEffortBudgetEnv(environ) ?? {}),
+    };
+    if (out.maxTurns === undefined) {
+        const turns = firstNumericFromEnv(environ, MAX_TURNS_ENV_ALIASES);
+        if (turns.value !== null)
+            out.maxTurns = turns.value;
+    }
+    if (out.maxBudget === undefined) {
+        const budget = firstNumericFromEnv(environ, MAX_BUDGET_ENV_ALIASES);
+        if (budget.value !== null)
+            out.maxBudget = budget.value;
+    }
+    if (out.hardBudget === undefined && envTruthy(environ[ENV_HARD_BUDGET])) {
+        out.hardBudget = true;
+    }
+    // Remaining counters as soft descriptor fields (detection also reads them).
+    if (out.remainingTurns === undefined) {
+        const rem = firstNumericFromEnv(environ, [ENV_REMAINING_TURNS, "REMAINING_TURNS"]);
+        if (rem.value !== null)
+            out.remainingTurns = rem.value;
+    }
+    if (out.remainingBudget === undefined) {
+        const rem = firstNumericFromEnv(environ, [ENV_REMAINING_BUDGET, "REMAINING_BUDGET"]);
+        if (rem.value !== null)
+            out.remainingBudget = rem.value;
+    }
+    return out;
+}
+/**
+ * Detect a hard turn/cost budget from env and optional host descriptor (#3266).
+ * Defaults to unbounded when no signal is present.
+ * When `hostDescriptor` is omitted, falls back to `DEFT_HOST_EFFORT_BUDGET` JSON.
+ */
+export function detectHardEffortBudget(input = {}) {
+    const environ = input.environ ?? process.env;
+    const host = input.hostDescriptor !== undefined
+        ? (input.hostDescriptor ?? null)
+        : parseHostEffortBudgetEnv(environ);
+    const sources = [];
+    if (host !== null && input.hostDescriptor === undefined) {
+        sources.push(`env:${ENV_HOST_EFFORT_BUDGET}`);
+    }
+    const turnsEnv = firstNumericFromEnv(environ, MAX_TURNS_ENV_ALIASES);
+    const budgetEnv = firstNumericFromEnv(environ, MAX_BUDGET_ENV_ALIASES);
+    const turnsHost = hostNumeric(host, ["maxTurns", "max_turns", "maxTurnLimit"]);
+    const budgetHost = hostNumeric(host, ["maxBudget", "max_budget", "maxCost", "max_cost"]);
+    // Prefer explicit DEFT_* then first alias; host fills gaps only.
+    const maxTurns = turnsEnv.value ?? turnsHost.value;
+    const maxBudget = budgetEnv.value ?? budgetHost.value;
+    if (turnsEnv.source)
+        sources.push(turnsEnv.source);
+    else if (turnsHost.source)
+        sources.push(turnsHost.source);
+    if (budgetEnv.source)
+        sources.push(budgetEnv.source);
+    else if (budgetHost.source)
+        sources.push(budgetHost.source);
+    const remainingTurnsEnv = firstNumericFromEnv(environ, [ENV_REMAINING_TURNS, "REMAINING_TURNS"]);
+    const remainingBudgetEnv = firstNumericFromEnv(environ, [
+        ENV_REMAINING_BUDGET,
+        "REMAINING_BUDGET",
+    ]);
+    if (remainingTurnsEnv.source)
+        sources.push(remainingTurnsEnv.source);
+    if (remainingBudgetEnv.source)
+        sources.push(remainingBudgetEnv.source);
+    const remainingTurns = remainingTurnsEnv.value ?? maxTurns;
+    const remainingBudget = remainingBudgetEnv.value ?? maxBudget;
+    let hardFlag = false;
+    if (envTruthy(environ[ENV_HARD_BUDGET])) {
+        hardFlag = true;
+        sources.push(`env:${ENV_HARD_BUDGET}`);
+    }
+    else {
+        const hostFlag = hostTruthy(host, ["hardBudget", "hard_budget", "hasHardBudget"]);
+        if (hostFlag) {
+            hardFlag = true;
+            sources.push(hostFlag);
+        }
+    }
+    // Remaining-only signals still imply a hard cap even when max is unknown (#3266 Greptile).
+    const hasTurns = maxTurns !== null || remainingTurnsEnv.value !== null;
+    const hasCost = maxBudget !== null || remainingBudgetEnv.value !== null;
+    let kind = "none";
+    if (hasTurns && hasCost)
+        kind = "both";
+    else if (hasTurns)
+        kind = "max-turns";
+    else if (hasCost)
+        kind = "max-cost";
+    else if (hardFlag)
+        kind = "hard-flag";
+    const detected = kind !== "none";
+    return {
+        detected,
+        posture: detected ? "hard-capped" : "unbounded",
+        kind,
+        maxTurns,
+        maxBudget,
+        remainingTurns: detected ? remainingTurns : null,
+        remainingBudget: detected ? remainingBudget : null,
+        sources,
+    };
+}
+/**
+ * Recommend self-verification depth: bank stated AC before deepening (#3266).
+ */
+export function recommendVerificationDepth(input) {
+    const { budget, statedAcceptanceMet } = input;
+    if (!budget.detected) {
+        return "unconstrained-deepen";
+    }
+    if (!statedAcceptanceMet) {
+        // Hard budget + AC open → only work that banks the stated pass.
+        return "stated-only";
+    }
+    const reserveTurns = input.deepenReserveTurns ?? 3;
+    const reserveBudget = input.deepenReserveBudget ?? null;
+    const turnsOk = budget.remainingTurns === null || budget.remainingTurns >= reserveTurns;
+    const costOk = reserveBudget === null ||
+        budget.remainingBudget === null ||
+        budget.remainingBudget >= reserveBudget;
+    // hard-flag with no numbers: after AC is met, allow stated-then-deepen only
+    // when remaining is unknown — agent still must fail-loud if it skips.
+    if (budget.kind === "hard-flag") {
+        return "stated-then-deepen";
+    }
+    if (turnsOk && costOk) {
+        return "stated-then-deepen";
+    }
+    return "stated-only";
+}
+/**
+ * Operator-visible note when self-imposed deepening is skipped for budget (#1006).
+ */
+export function formatDeepeningSkippedNote(budget, reason) {
+    const detail = reason?.trim() ||
+        "remaining budget is insufficient to both deepen verification and fix a found defect";
+    const sources = budget.sources.length > 0 ? ` sources=${budget.sources.join(",")}` : "";
+    const rem = budget.remainingTurns !== null
+        ? ` remaining_turns=${budget.remainingTurns}`
+        : budget.remainingBudget !== null
+            ? ` remaining_budget=${budget.remainingBudget}`
+            : "";
+    return (`[deft effort-budget] deepening_skipped=true reason=${detail}` +
+        ` posture=${budget.posture} kind=${budget.kind}${rem}${sources} (#3266/#1006)`);
+}
+/** Session-start / JSON payload shape. */
+export function effortBudgetToDict(budget) {
+    return {
+        detected: budget.detected,
+        posture: budget.posture,
+        kind: budget.kind,
+        max_turns: budget.maxTurns,
+        max_budget: budget.maxBudget,
+        remaining_turns: budget.remainingTurns,
+        remaining_budget: budget.remainingBudget,
+        sources: [...budget.sources],
+    };
+}
+/**
+ * Format operator-facing effort-budget lines for session:start (#3266).
+ * Always emits one summary line; adds bank-the-pass guidance when hard-capped.
+ */
+export function formatEffortBudgetLines(budget) {
+    if (!budget.detected) {
+        return [
+            "[deft effort-budget] posture=unbounded — no hard max-turns/max-budget signal " +
+                `(env ${ENV_MAX_TURNS}/${ENV_MAX_BUDGET} or host descriptor) (#3266)`,
+        ];
+    }
+    const parts = [`[deft effort-budget] posture=${budget.posture}`, `kind=${budget.kind}`];
+    if (budget.maxTurns !== null)
+        parts.push(`max_turns=${budget.maxTurns}`);
+    if (budget.remainingTurns !== null && budget.remainingTurns !== budget.maxTurns) {
+        parts.push(`remaining_turns=${budget.remainingTurns}`);
+    }
+    if (budget.maxBudget !== null)
+        parts.push(`max_budget=${budget.maxBudget}`);
+    if (budget.remainingBudget !== null && budget.remainingBudget !== budget.maxBudget) {
+        parts.push(`remaining_budget=${budget.remainingBudget}`);
+    }
+    if (budget.sources.length > 0)
+        parts.push(`sources=${budget.sources.join(",")}`);
+    const lines = [`${parts.join(" ")} (#3266)`];
+    lines.push("[deft effort-budget] bank stated acceptance pass before self-imposed deepening; " +
+        "scale verification depth with remaining budget; fail-loud when deepening is skipped (#3266/#1006)");
+    return lines;
+}
+/**
+ * Detect + format; fail-open for session-start callers.
+ */
+export function maybeFormatEffortBudgetLines(input = {}) {
+    const budget = detectHardEffortBudget(input);
+    return { budget, lines: formatEffortBudgetLines(budget) };
+}
+//# sourceMappingURL=effort-budget.js.map

package/dist/session/index.d.ts

@@ -1,5 +1,7 @@
+export * from "./active-cli.js";
 export * from "./compact-ritual.js";
 export * from "./coverage-check-resume-nudge.js";
+export * from "./effort-budget.js";
 export * from "./git.js";
 export * from "./json.js";
 export * from "./openclaw-soft-rebind-deposit.js";

package/dist/session/index.js

@@ -1,5 +1,7 @@
+export * from "./active-cli.js";
 export * from "./compact-ritual.js";
 export * from "./coverage-check-resume-nudge.js";
+export * from "./effort-budget.js";
 export * from "./git.js";
 export * from "./json.js";
 export * from "./openclaw-soft-rebind-deposit.js";

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

@@ -3,6 +3,7 @@ import { type EnvironmentContext } from "../platform/shell-context.js";
 import { type CeremonyDialInputs, type CeremonyDialSelection, type ProvisionalCeremonyEstimateHints } from "../policy/ceremony-dial.js";
 import { type ProbeScmReadinessOptions, type ScmReadinessReport } from "../scm/readiness.js";
 import { type ResolveUserMdResult } from "../user-config/resolve-user-md.js";
+import { type DetectHardEffortBudgetInput } from "./effort-budget.js";
 import type { GitRunner } from "./git.js";
 import { type ReleaseAvailabilityProbeOptions } from "./release-availability.js";
 import { type RitualState, ritualStatePath } from "./ritual-sentinel.js";
@@ -76,6 +77,11 @@ export interface SessionStartOptions {
      * Fail-open advisory only — never blocks session:start.
      */
     readonly hostContentSurfaceSeams?: HostContentSurfaceSeams;
+    /**
+     * #3266: hard effort-budget detection seams (env / host descriptor).
+     * Fail-open advisory only — never blocks session:start.
+     */
+    readonly effortBudgetSeams?: DetectHardEffortBudgetInput;
     readonly probeReleaseAvailability?: (projectRoot: string, options: ReleaseAvailabilityProbeOptions) => {
         lines: readonly string[];
     };

package/dist/session/session-start.js

@@ -21,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";
@@ -383,6 +384,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 +429,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 +459,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 +504,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 +705,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 +790,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 +879,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);
@@ -1119,6 +1169,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/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";