@deftai/directive-core 0.98.1 → 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

@@ -1,6 +1,9 @@
+import { type HostContentSurfaceSeams } from "../platform/host-content-surface.js";
 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";
@@ -15,7 +18,7 @@ export declare const SESSION_CEREMONY_TIERS: readonly ["cold", "rearm"];
 export type SessionCeremonyTier = (typeof SESSION_CEREMONY_TIERS)[number];
 export declare const COLD_CEREMONY_TIER: SessionCeremonyTier;
 export declare const REARM_CEREMONY_TIER: SessionCeremonyTier;
-export declare const QUICK_STEPS: readonly ["alignment", "branch_policy", "triage_welcome"];
+export declare const QUICK_STEPS: readonly ["alignment", "branch_policy", "triage_welcome", "verify_tools"];
 export declare const GATED_STEPS: readonly ["agent_hooks", "doctor", "cache_fresh"];
 export type GatedStepName = (typeof GATED_STEPS)[number];
 /** Env opt-in for optional session:start network (release probe + triage cache hydrate) (#2991). */
@@ -69,6 +72,16 @@ export interface SessionStartOptions {
     };
     readonly resolveUserMd?: (projectRoot: string) => ResolveUserMdResult;
     readonly probeEnvironment?: () => EnvironmentContext;
+    /**
+     * #3162: host content-surface class + managed-section drift seams (tests inject).
+     * 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[];
     };
@@ -94,6 +107,22 @@ export interface SessionStartOptions {
      * network is enabled. Inject in tests.
      */
     readonly probeScm?: (options: ProbeScmReadinessOptions) => ScmReadinessReport;
+    /**
+     * #3214: ceremony dial inputs (task size × model tier × project shape).
+     * Missing fields are filled by the headless provisional classifier
+     * (env / verb / file-scope / deposit layout) — no plan-item effort (#1581).
+     */
+    readonly ceremonyDialInputs?: CeremonyDialInputs;
+    /**
+     * #3214: optional intake hints for provisional size (prompt/verb/files).
+     * Vanilla deposit session:start runs provisional fill without policy opt-in.
+     */
+    readonly ceremonyDialHints?: Omit<ProvisionalCeremonyEstimateHints, "projectRoot" | "env">;
+    /**
+     * #3214: optional pre-resolved dial (tests). When omitted, resolveCeremonyDial
+     * loads plan.policy.ceremonyDial and applies inputs (after provisional fill).
+     */
+    readonly ceremonyDial?: CeremonyDialSelection;
 }
 /** Format preferred `session:start` recovery command for cold vs re-arm (#2992). */
 export declare function formatSessionStartRecoveryCommand(tier?: SessionCeremonyTier): string;