@deftai/directive-core 0.99.0 → 0.101.0

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

@@ -0,0 +1,136 @@
+/**
+ * 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;
+    /**
+     * Minimum remaining fraction of max turns/cost required to deepen after AC bank
+     * (#3285). Default 0.2 (20%). Set null to skip the surplus fraction gate and
+     * use only the absolute reserve.
+     */
+    readonly surplusThreshold?: 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,352 @@
+/**
+ * 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;
+    // #3285: default 20% surplus of max remaining after bank; null disables.
+    const surplusThreshold = input.surplusThreshold === undefined ? 0.2 : input.surplusThreshold;
+    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-only";
+    }
+    // Surplus fraction gate (#3285): remaining/max must meet threshold on every
+    // known max+remaining axis. When max is unknown, absolute reserve alone applies.
+    if (surplusThreshold !== null) {
+        if (budget.remainingTurns !== null &&
+            budget.maxTurns !== null &&
+            budget.maxTurns > 0 &&
+            budget.remainingTurns / budget.maxTurns < surplusThreshold) {
+            return "stated-only";
+        }
+        if (budget.remainingBudget !== null &&
+            budget.maxBudget !== null &&
+            budget.maxBudget > 0 &&
+            budget.remainingBudget / budget.maxBudget < surplusThreshold) {
+            return "stated-only";
+        }
+    }
+    return "stated-then-deepen";
+}
+/**
+ * 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,8 +1,14 @@
+export * from "./ac-pass-banking.js";
+export * from "./active-cli.js";
 export * from "./compact-ritual.js";
 export * from "./coverage-check-resume-nudge.js";
+export * from "./deposit-sha.js";
+export * from "./effort-budget.js";
 export * from "./git.js";
 export * from "./json.js";
 export * from "./openclaw-soft-rebind-deposit.js";
+export * from "./orientation-compression.js";
+export * from "./orientation-state.js";
 export * from "./posture.js";
 export * from "./process-cost.js";
 export * from "./resume-conditions.js";
@@ -11,5 +17,6 @@ export * from "./session-ready.js";
 export * from "./session-start.js";
 export * from "./session-start-hook.js";
 export * from "./time.js";
+export * from "./toolchain-preflight.js";
 export * from "./verify-session-ritual.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/session/index.js

@@ -1,8 +1,14 @@
+export * from "./ac-pass-banking.js";
+export * from "./active-cli.js";
 export * from "./compact-ritual.js";
 export * from "./coverage-check-resume-nudge.js";
+export * from "./deposit-sha.js";
+export * from "./effort-budget.js";
 export * from "./git.js";
 export * from "./json.js";
 export * from "./openclaw-soft-rebind-deposit.js";
+export * from "./orientation-compression.js";
+export * from "./orientation-state.js";
 export * from "./posture.js";
 export * from "./process-cost.js";
 export * from "./resume-conditions.js";
@@ -11,5 +17,6 @@ export * from "./session-ready.js";
 export * from "./session-start.js";
 export * from "./session-start-hook.js";
 export * from "./time.js";
+export * from "./toolchain-preflight.js";
 export * from "./verify-session-ritual.js";
 //# sourceMappingURL=index.js.map

package/dist/session/orientation-compression.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Orientation compression Now path (#3286 / dual-path #2899).
+ *
+ * Composes doctor + toolchain preflight into session:start as inline sections
+ * with per-section status lines; offers deposit-sha fast-paths for
+ * agents:refresh and verify:cache-fresh; formats compact (opt-in) vs verbose
+ * (default). Does NOT implement unified `deft orient` (Later remains open).
+ */
+import type { DoctorSeams } from "../doctor/types.js";
+import { applyAgentsRefresh } from "../platform/agents-md.js";
+import { type EvaluateOptions, evaluate as evaluateCacheFresh } from "../preflight-cache/evaluate.js";
+import { type ComputeDepositShaOptions } from "./deposit-sha.js";
+import { type OrientationState } from "./orientation-state.js";
+import { type ToolchainPreflightOptions, type ToolchainPreflightResult } from "./toolchain-preflight.js";
+/** Env opt-in for compact orientation output (#3286). Verbose remains default. */
+export declare const ENV_SESSION_COMPACT = "DEFT_SESSION_COMPACT";
+/** Dual-path Later graduation status — Now ships without closing Later (#2899). */
+export declare const ORIENTATION_LATER_STATUS: "open";
+export declare const ORIENTATION_LATER_COMMAND = "deft orient";
+export declare const ORIENTATION_GRADUATION_TRIGGER: string;
+export type OrientationSectionName = "doctor" | "preflight" | "agents_refresh" | "cache_fresh";
+export type OrientationSectionStatus = "ok" | "dirty" | "degraded" | "error" | "skipped" | "sha_match";
+export interface OrientationSectionResult {
+    readonly name: OrientationSectionName;
+    readonly status: OrientationSectionStatus;
+    readonly ok: boolean;
+    readonly exitCode: number;
+    readonly lines: readonly string[];
+    readonly shaMatch: boolean;
+    readonly depositSha?: string;
+    readonly durationMs: number;
+    readonly detail?: Record<string, unknown>;
+}
+export interface OrientationBundle {
+    readonly depositSha: string;
+    readonly compact: boolean;
+    readonly sections: readonly OrientationSectionResult[];
+    readonly lines: readonly string[];
+    /** Count of orientation surfaces touched this session (for run-summary #3282 trigger). */
+    readonly orientationCallCount: number;
+    readonly later: {
+        readonly status: typeof ORIENTATION_LATER_STATUS;
+        readonly command: typeof ORIENTATION_LATER_COMMAND;
+        readonly trigger: typeof ORIENTATION_GRADUATION_TRIGGER;
+    };
+    readonly preflight: ToolchainPreflightResult | null;
+    readonly state: OrientationState;
+}
+export interface RunOrientationOptions {
+    readonly projectRoot: string;
+    readonly frameworkRoot?: string;
+    readonly compact?: boolean;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly now?: Date;
+    readonly depositShaOptions?: ComputeDepositShaOptions;
+    readonly toolchainPreflight?: ToolchainPreflightResult | null;
+    readonly toolchainPreflightOptions?: ToolchainPreflightOptions;
+    /** Skip doctor (tests) or inject structured result. */
+    readonly doctorSection?: OrientationSectionResult | null;
+    readonly doctorSeams?: DoctorSeams;
+    /** Skip agents:refresh or inject. */
+    readonly agentsRefreshSection?: OrientationSectionResult | null;
+    /** Skip cache_fresh or inject. */
+    readonly cacheFreshSection?: OrientationSectionResult | null;
+    readonly cacheFreshOptions?: EvaluateOptions;
+    /** When true (default), persist orientation-state for next-session fast-path. */
+    readonly persistState?: boolean;
+    /** Disable individual sections (tests / re-arm). */
+    readonly includeDoctor?: boolean;
+    readonly includePreflight?: boolean;
+    readonly includeAgentsRefresh?: boolean;
+    readonly includeCacheFresh?: boolean;
+}
+/** Resolve compact flag: explicit option wins, else DEFT_SESSION_COMPACT. */
+export declare function resolveSessionCompact(options?: Pick<RunOrientationOptions, "compact" | "env">): boolean;
+/** Compact machine lines (one per section). Verbose default keeps prose. */
+export declare function formatOrientationCompactLines(sections: readonly OrientationSectionResult[]): string[];
+export declare function formatOrientationVerboseLines(sections: readonly OrientationSectionResult[]): string[];
+/**
+ * Doctor orientation section — throttle status when clean/recent; otherwise
+ * run doctor and surface a per-section status line (#3286 compose).
+ */
+export declare function runDoctorOrientationSection(projectRoot: string, options?: {
+    now?: Date;
+    seams?: DoctorSeams;
+    doctorRunner?: (args: readonly string[], seams?: DoctorSeams) => number;
+}): OrientationSectionResult;
+export declare function runPreflightOrientationSection(projectRoot: string, options?: {
+    frameworkRoot?: string;
+    result?: ToolchainPreflightResult | null;
+    preflightOptions?: ToolchainPreflightOptions;
+}): {
+    section: OrientationSectionResult | null;
+    preflight: ToolchainPreflightResult | null;
+};
+/**
+ * agents:refresh orientation section (#3286).
+ * Always plans against live AGENTS.md so local managed-section edits are
+ * detected (deposit fingerprint alone is insufficient). Content-current →
+ * one-line sha-match phrasing; deposit-sha is recorded for orientation telemetry.
+ */
+export declare function runAgentsRefreshOrientationSection(projectRoot: string, options: {
+    depositSha: string;
+    prior?: OrientationState | null;
+    now?: Date;
+    apply?: typeof applyAgentsRefresh;
+}): OrientationSectionResult;
+/**
+ * verify:cache-fresh orientation section (#3286).
+ * Always runs the live evaluate (age + drift). Deposit fingerprint is recorded
+ * for orientation telemetry only — it must not suppress triage-cache freshness.
+ * When evaluate is already clean, surface a one-line sha-match-style no-op only
+ * if the message is the canonical deposit phrase (not used for shortcuts).
+ */
+export declare function runCacheFreshOrientationSection(projectRoot: string, options: {
+    depositSha: string;
+    prior?: OrientationState | null;
+    now?: Date;
+    evaluateOptions?: EvaluateOptions;
+    evaluateFn?: typeof evaluateCacheFresh;
+}): OrientationSectionResult;
+/**
+ * Run the composed orientation sections for a mutation cold session:start.
+ */
+export declare function runOrientationCompression(options: RunOrientationOptions): OrientationBundle;
+export { computeDepositSha, DEPOSIT_SHA_MATCH_NOOP, depositShaMatches, formatDepositShaMatchLine, } from "./deposit-sha.js";
+//# sourceMappingURL=orientation-compression.d.ts.map