@0xmaxma/claude-gateway 1.3.25 → 1.3.31

package/dist/agent/incident.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * Incident core (Epic #195, Phase 2).
+ *
+ * Pure decision logic for the incident-reporting layer that sits on top of the
+ * turn-trace watchdog (Phase 1). Given a stall incident, this module decides:
+ *   - its fingerprint (what makes two stalls "the same problem"),
+ *   - whether/how to escalate a repeat (quiet → repeat → recommend-investigate),
+ *   - how to scrub evidence before any of it can leave the machine,
+ *   - how to summarise a set of incidents into a digest line/report.
+ *
+ * Like turn-trace.ts and orphan-wake.ts, this file performs NO IO and imports
+ * no runtime code (only types, which are erased), so every rule here is
+ * unit-testable without a filesystem, a clock, or a live session. The store
+ * (incident-store.ts) owns persistence and calls into these functions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ESCALATION = exports.REDACTION = void 0;
+exports.computeFingerprint = computeFingerprint;
+exports.fingerprintHash = fingerprintHash;
+exports.decideEscalation = decideEscalation;
+exports.maxEscalationLevel = maxEscalationLevel;
+exports.scrubText = scrubText;
+exports.summarizeIncidents = summarizeIncidents;
+exports.formatDigestLine = formatDigestLine;
+/** Placeholder substituted for any redacted span in a scrubbed export. */
+exports.REDACTION = '‹redacted›';
+/**
+ * Compute the dedup fingerprint. Two stalls are "the same problem" when they
+ * hit the same pipeline stage with the same failure attribution on the same CLI
+ * version — a new CLI version is treated as a distinct problem so a regression
+ * introduced by an upgrade does not silently fold into an old fingerprint.
+ */
+function computeFingerprint(input) {
+    const cls = input.failureClass ?? 'none';
+    const ver = normalizeVersion(input.cliVersion);
+    return `${input.stage}:${cls}:${ver}`;
+}
+/** Normalise a version string to a fingerprint-safe token; empty → 'unknown'. */
+function normalizeVersion(v) {
+    const t = (v ?? '').trim();
+    return t.length > 0 ? t : 'unknown';
+}
+/**
+ * Deterministic, dependency-free hash (FNV-1a → base36). Used to derive a short
+ * filesystem-safe prefix for an incident id from its fingerprint. Not used for
+ * anything security-sensitive — only stable naming/dedup.
+ */
+function fingerprintHash(fingerprint) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < fingerprint.length; i++) {
+        h ^= fingerprint.charCodeAt(i);
+        // FNV prime multiply, kept in 32-bit range via Math.imul.
+        h = Math.imul(h, 0x01000193);
+    }
+    // >>> 0 to interpret as unsigned before stringifying.
+    return (h >>> 0).toString(36);
+}
+exports.DEFAULT_ESCALATION = {
+    windowMs: 24 * 60 * 60 * 1000, // 24 h
+    investigateThreshold: 3,
+};
+/**
+ * Decide how to escalate given the running occurrence count for a fingerprint
+ * and whether the user was already notified at 'investigate' level.
+ *
+ *   - 1st occurrence            → quiet notify (one short heads-up)
+ *   - repeats below threshold   → silent increment (no re-notify)
+ *   - Nth (N ≥ threshold), once → recommend investigation (louder notify)
+ *   - after that                → silent (already recommended)
+ *
+ * Pure: the caller supplies the count and prior-notify state.
+ */
+function decideEscalation(occurrences, alreadyInvestigateNotified, cfg = exports.DEFAULT_ESCALATION) {
+    if (occurrences <= 1) {
+        return { level: 'quiet', notify: true };
+    }
+    if (occurrences >= cfg.investigateThreshold && !alreadyInvestigateNotified) {
+        return { level: 'investigate', notify: true };
+    }
+    return { level: 'repeat', notify: false };
+}
+/** The maximum of two escalation levels (for tracking the highest reached). */
+function maxEscalationLevel(a, b) {
+    const rank = { quiet: 0, repeat: 1, investigate: 2 };
+    return rank[a] >= rank[b] ? a : b;
+}
+// ─── Scrubbing ──────────────────────────────────────────────────────────────
+/**
+ * Patterns for content that must never leave the machine, independent of any
+ * caller-supplied literals. Conservative by design: each pattern targets a
+ * recognisable secret/PII shape, not free text, to avoid mangling useful
+ * diagnostic content. Order matters — more specific patterns run first.
+ */
+const SECRET_PATTERNS = [
+    // Telegram bot token: <digits>:<35+ token chars>
+    /\b\d{6,}:[A-Za-z0-9_-]{30,}\b/g,
+    // Anthropic / OpenAI style keys: sk-... (and sk-ant-...)
+    /\bsk-[A-Za-z0-9-]{16,}\b/g,
+    // Slack tokens: xox[baprs]-...
+    /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
+    // GitHub tokens: ghp_/gho_/ghu_/ghs_/ghr_ + 36 chars
+    /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g,
+    // Bearer tokens in headers
+    /\bBearer\s+[A-Za-z0-9._-]{16,}\b/gi,
+    // Email addresses
+    /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+];
+/**
+ * Scrub text destined for an exported/persisted artifact. Removes:
+ *   1. every caller-supplied literal (chat ids, usernames) — matched verbatim,
+ *   2. recognisable secret/PII shapes (tokens, keys, emails).
+ *
+ * Literals are escaped before use so a value like `a.b` cannot act as a regex.
+ * Pure and idempotent enough for repeated application (placeholder is inert).
+ */
+function scrubText(text, redactions = []) {
+    if (!text)
+        return text;
+    let out = text;
+    // Caller literals first (longest first so a longer id containing a shorter
+    // one is fully removed rather than partially).
+    const literals = [...new Set(redactions.filter((r) => r && r.length >= 2))].sort((a, b) => b.length - a.length);
+    for (const lit of literals) {
+        out = out.split(lit).join(exports.REDACTION);
+    }
+    for (const re of SECRET_PATTERNS) {
+        out = out.replace(re, exports.REDACTION);
+    }
+    return out;
+}
+/**
+ * Summarise the incidents whose most-recent occurrence lands in
+ * `[now - sinceMs, now]`. Pure — the store supplies the manifests it read.
+ */
+function summarizeIncidents(manifests, sinceMs, now) {
+    const cutoff = now - sinceMs;
+    const summary = {
+        total: 0,
+        occurrences: 0,
+        openCount: 0,
+        byStage: {},
+        byFailureClass: {},
+        byCliVersion: {},
+    };
+    for (const m of manifests) {
+        if (m.lastAt < cutoff)
+            continue;
+        summary.total++;
+        summary.occurrences += m.occurrences;
+        if (m.status === 'open')
+            summary.openCount++;
+        bump(summary.byStage, m.stage);
+        bump(summary.byFailureClass, m.failureClass ?? 'none');
+        bump(summary.byCliVersion, m.cliVersion || 'unknown');
+    }
+    return summary;
+}
+function bump(rec, key) {
+    rec[key] = (rec[key] ?? 0) + 1;
+}
+/**
+ * One-line, human-friendly digest. Zero-incident periods produce a short "all
+ * clear" line rather than nothing, so the digest itself is a liveness signal.
+ */
+function formatDigestLine(summary, label = 'daily') {
+    if (summary.total === 0) {
+        return `🩺 ${label} digest: no turn-trace incidents`;
+    }
+    const stages = Object.entries(summary.byStage)
+        .sort((a, b) => b[1] - a[1])
+        .map(([s, n]) => `${s}×${n}`)
+        .join(', ');
+    return (`🩺 ${label} digest: ${summary.total} incident(s), ` +
+        `${summary.occurrences} occurrence(s), ${summary.openCount} open — ${stages}`);
+}
+//# sourceMappingURL=incident.js.map

package/dist/agent/incident.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"incident.js","sourceRoot":"","sources":["../../src/agent/incident.ts"],"names":[],"mappings":"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"}

package/dist/agent/recovery-executor.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Recovery executor (Epic #195, Phase 3b).
+ *
+ * This is the orchestration core that turns a watchdog-detected stall into an
+ * actual recovery attempt. It runs in the AGENT RUNNER process — the only place
+ * that owns the live control surfaces (session stdin, restart, safe-mode) — but
+ * it is written as a PURE function with every side effect injected, so tests
+ * drive the full decision path without touching a real session or CLI.
+ *
+ * Trust + safety model (why the pieces are split the way they are):
+ *   - The classify step (triage.ts) treats screen text as UNTRUSTED data and
+ *     validates the model reply against a CLOSED schema.
+ *   - The decide step (recovery-policy.ts) clamps the proposed action to a
+ *     per-stage whitelist and enforces a per-turn budget + cooldown.
+ *   - This execute step maps the *already-validated, already-whitelisted* action
+ *     to an injected effect. A missing effect is a no-op failure, never a guess.
+ *
+ * Everything is gated by `autoRecover`: when it is off the executor does nothing
+ * but report that it was skipped, so the whole feature ships dark. Safe-mode
+ * auto-fallback is deliberately NOT routed through here — it is a reversible
+ * backend flip the runner applies on hard PTY failure regardless of this flag.
+ */
+import { type TriageSpawn } from './triage';
+import { type RecoveryAction, type BudgetState, type BudgetConfig } from './recovery-policy';
+import type { RecoveryOutcome } from './incident';
+/**
+ * The concrete side effects the executor may invoke. Every method is optional:
+ * an action whose effect is not provided is reported as unsupported rather than
+ * silently succeeding. Keystroke effects (esc/enter/…) are delivered to the PTY
+ * wrapper via the control channel; the restart/backend effects act on the
+ * session/receiver. All may be async.
+ */
+export interface RecoveryEffects {
+    esc?(): Promise<void> | void;
+    escEsc?(): Promise<void> | void;
+    enter?(): Promise<void> | void;
+    selectOption?(option: number): Promise<void> | void;
+    bridgeMenu?(): Promise<void> | void;
+    redeliverForward?(): Promise<void> | void;
+    restartSession?(): Promise<void> | void;
+    restartReceiver?(): Promise<void> | void;
+    fallbackHeadless?(): Promise<void> | void;
+    /**
+     * C1: re-inject the last user message so the user does not have to retype it
+     * after a recovery. The implementation MUST guard against duplicates — resend
+     * only when the stalled turn produced no output — and returns whether it
+     * actually resent. The executor never forces a resend; it only asks.
+     */
+    resendLast?(): Promise<boolean> | boolean;
+}
+/** What the watchdog hands the executor for one stalled turn. */
+export interface RecoveryRequest {
+    /** Incident id the outcome is recorded against (opaque to the executor). */
+    incidentId: string;
+    agentId: string;
+    chatId: string;
+    sessionId: string;
+    /** Pipeline stage that stalled (drives the action whitelist). */
+    stage: string;
+    failureClass: string | null;
+    /** Identifies the turn for budget accounting (resets budget when it changes). */
+    turnKey: string;
+}
+export interface RecoveryDeps {
+    /** Master gate. When false the executor does nothing but report `skipped`. */
+    autoRecover: boolean;
+    effects: RecoveryEffects;
+    now: () => number;
+    /** Per-turn budget accounting, injected so it can persist across calls. */
+    budget: {
+        get(turnKey: string): BudgetState;
+        set(state: BudgetState): void;
+        config?: BudgetConfig;
+    };
+    /**
+     * Optional local `claude -p` triage. When omitted, the executor falls back to
+     * the deterministic per-stage default action (still whitelist-checked).
+     */
+    triageSpawn?: TriageSpawn;
+    /**
+     * Collect scrubbed evidence for triage (screen snapshot / status text). The
+     * caller is responsible for scrubbing; the executor passes it through as data.
+     */
+    gatherEvidence?: () => Promise<{
+        screenText?: string;
+        statusText?: string;
+    } | null>;
+    /** C1 gate: attempt a guarded resend after a successful unblocking action. */
+    resendAfterRecover?: boolean;
+    /** Optional structured logger. */
+    log?: (msg: string, meta?: Record<string, unknown>) => void;
+}
+/** Full result of one recovery attempt (richer than the persisted schema). */
+export interface RecoveryResult {
+    incidentId: string;
+    stage: string;
+    /** The action actually taken (may be clamped to notify-only). */
+    action: RecoveryAction;
+    option?: number;
+    /** True if an effect was invoked (notify-only / skip / clamp are false). */
+    executed: boolean;
+    /** True if the invoked effect completed without throwing. */
+    ok: boolean;
+    reason: string;
+    /** True if the last user message was resent (C1). */
+    resent: boolean;
+    at: number;
+}
+/**
+ * Run one recovery attempt. ALWAYS resolves (never throws): any failure degrades
+ * to a safe, recorded outcome. The returned RecoveryResult is what the caller
+ * persists to the incident bundle and may surface to the user.
+ */
+export declare function runRecovery(req: RecoveryRequest, deps: RecoveryDeps): Promise<RecoveryResult>;
+/** Map a full result to the compact schema persisted in the incident bundle. */
+export declare function toRecoveryOutcome(r: RecoveryResult): RecoveryOutcome;
+//# sourceMappingURL=recovery-executor.d.ts.map

package/dist/agent/recovery-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-executor.d.ts","sourceRoot":"","sources":["../../src/agent/recovery-executor.ts"],"names":[],"mappings":"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"}

package/dist/agent/recovery-executor.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * Recovery executor (Epic #195, Phase 3b).
+ *
+ * This is the orchestration core that turns a watchdog-detected stall into an
+ * actual recovery attempt. It runs in the AGENT RUNNER process — the only place
+ * that owns the live control surfaces (session stdin, restart, safe-mode) — but
+ * it is written as a PURE function with every side effect injected, so tests
+ * drive the full decision path without touching a real session or CLI.
+ *
+ * Trust + safety model (why the pieces are split the way they are):
+ *   - The classify step (triage.ts) treats screen text as UNTRUSTED data and
+ *     validates the model reply against a CLOSED schema.
+ *   - The decide step (recovery-policy.ts) clamps the proposed action to a
+ *     per-stage whitelist and enforces a per-turn budget + cooldown.
+ *   - This execute step maps the *already-validated, already-whitelisted* action
+ *     to an injected effect. A missing effect is a no-op failure, never a guess.
+ *
+ * Everything is gated by `autoRecover`: when it is off the executor does nothing
+ * but report that it was skipped, so the whole feature ships dark. Safe-mode
+ * auto-fallback is deliberately NOT routed through here — it is a reversible
+ * backend flip the runner applies on hard PTY failure regardless of this flag.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRecovery = runRecovery;
+exports.toRecoveryOutcome = toRecoveryOutcome;
+const triage_1 = require("./triage");
+const recovery_policy_1 = require("./recovery-policy");
+const ACTION_EFFECT = {
+    esc: 'esc',
+    'esc-esc': 'escEsc',
+    enter: 'enter',
+    'select-option': 'selectOption',
+    'bridge-menu': 'bridgeMenu',
+    'redeliver-forward': 'redeliverForward',
+    'restart-session': 'restartSession',
+    'restart-receiver': 'restartReceiver',
+    'fallback-headless': 'fallbackHeadless',
+};
+/**
+ * Actions after which a guarded resend of the last user message makes sense: the
+ * ones that unblock a claude turn which was still waiting for input. Delivery/
+ * transport actions (redeliver-forward, restart-receiver) already move the
+ * pending output themselves, so a resend there would double-submit.
+ */
+const RESEND_ELIGIBLE = new Set([
+    'esc',
+    'esc-esc',
+    'enter',
+    'select-option',
+    'bridge-menu',
+    'restart-session',
+    'fallback-headless',
+]);
+/**
+ * Run one recovery attempt. ALWAYS resolves (never throws): any failure degrades
+ * to a safe, recorded outcome. The returned RecoveryResult is what the caller
+ * persists to the incident bundle and may surface to the user.
+ */
+async function runRecovery(req, deps) {
+    const at = deps.now();
+    const base = { incidentId: req.incidentId, stage: req.stage, at };
+    // Master gate: feature ships dark. Detection/incident/notify already ran in
+    // the caller; here we simply do nothing and say so.
+    if (!deps.autoRecover) {
+        return { ...base, action: 'notify-only', executed: false, ok: true, reason: 'skipped: autoRecover disabled', resent: false };
+    }
+    // 1) Evidence → 2) triage (classify) → 3) policy (decide). None of these act.
+    let verdict = null;
+    if (deps.triageSpawn) {
+        let bundle = { stage: req.stage, failureClass: req.failureClass };
+        try {
+            const ev = deps.gatherEvidence ? await deps.gatherEvidence() : null;
+            if (ev)
+                bundle = { ...bundle, screenText: ev.screenText, statusText: ev.statusText };
+        }
+        catch {
+            // Evidence gathering is best-effort; triage can still classify from stage.
+        }
+        verdict = await (0, triage_1.runTriage)({ spawn: deps.triageSpawn, bundle });
+    }
+    const plan = (0, recovery_policy_1.selectRecoveryAction)({ stage: req.stage, failureClass: req.failureClass, verdict });
+    // notify-only never consumes budget and invokes no effect — the caller owns
+    // the user-facing notice, so the executor just records the decision.
+    if (plan.action === 'notify-only' || plan.action === 'none') {
+        return { ...base, action: 'notify-only', executed: false, ok: true, reason: plan.reason, resent: false };
+    }
+    // 4) Budget + cooldown. An actionable plan blocked by budget clamps to
+    // notify-only (recorded with the action it wanted) and consumes nothing more.
+    const cfg = deps.budget.config ?? recovery_policy_1.DEFAULT_BUDGET;
+    const verdictBudget = (0, recovery_policy_1.checkBudget)(deps.budget.get(req.turnKey), req.turnKey, at, cfg);
+    if (!verdictBudget.allowed) {
+        deps.budget.set(verdictBudget.next);
+        return {
+            ...base,
+            action: 'notify-only',
+            executed: false,
+            ok: true,
+            reason: `clamped: ${verdictBudget.reason} (wanted ${plan.action})`,
+            resent: false,
+        };
+    }
+    deps.budget.set(verdictBudget.next);
+    // 5) Execute the whitelisted action via its injected effect.
+    const effectKey = ACTION_EFFECT[plan.action];
+    const effect = effectKey ? deps.effects[effectKey] : undefined;
+    const result = {
+        ...base,
+        action: plan.action,
+        option: plan.option,
+        executed: false,
+        ok: false,
+        reason: plan.reason,
+        resent: false,
+    };
+    if (!effect) {
+        result.reason = `unsupported: no effect for ${plan.action}`;
+        deps.log?.('recovery: unsupported action', { action: plan.action, stage: req.stage });
+        return result;
+    }
+    try {
+        if (plan.action === 'select-option' && typeof plan.option === 'number') {
+            await effect(plan.option);
+        }
+        else {
+            await effect();
+        }
+        result.executed = true;
+        result.ok = true;
+        deps.log?.('recovery: executed', { action: plan.action, stage: req.stage, incidentId: req.incidentId });
+    }
+    catch (err) {
+        result.executed = true;
+        result.ok = false;
+        result.reason = `effect threw: ${err.message}`;
+        deps.log?.('recovery: effect failed', { action: plan.action, error: err.message });
+        return result;
+    }
+    // 6) C1 guarded resend. Only after a successful unblocking action, and only if
+    // the effect implementation confirms the turn produced no output.
+    if (deps.resendAfterRecover && RESEND_ELIGIBLE.has(plan.action) && deps.effects.resendLast) {
+        try {
+            result.resent = Boolean(await deps.effects.resendLast());
+        }
+        catch {
+            result.resent = false;
+        }
+    }
+    return result;
+}
+/** Map a full result to the compact schema persisted in the incident bundle. */
+function toRecoveryOutcome(r) {
+    const bits = [r.reason];
+    if (r.resent)
+        bits.push('resent');
+    return {
+        action: r.option !== undefined ? `${r.action}:${r.option}` : r.action,
+        at: r.at,
+        // `ok` means "no failure occurred" — true for a successful execution AND for
+        // a benign non-action (skipped / notify-only / budget-clamp), false only when
+        // an effect was attempted and threw or was unsupported. Using r.ok directly
+        // (which is already false only on those failure paths) keeps notify-only
+        // decisions from being miscounted as failed recoveries in the digest.
+        ok: r.ok,
+        detail: bits.join('; '),
+    };
+}
+//# sourceMappingURL=recovery-executor.js.map

package/dist/agent/recovery-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-executor.js","sourceRoot":"","sources":["../../src/agent/recovery-executor.ts"],"names":[],"mappings":"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"}

package/dist/agent/recovery-policy.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Recovery policy (Epic #195, Phase 3).
+ *
+ * Turns a (schema-validated) triage verdict into an actual recovery action —
+ * but only after enforcing three independent guards, so a compromised or
+ * mistaken triage step can never drive an unsafe intervention:
+ *
+ *   1. Per-stage whitelist. Each pipeline stage permits only a small set of
+ *      actions (a `dispatch` stall may redeliver or restart the receiver; a
+ *      `progress` PTY wedge may press esc or restart the session). An action
+ *      the stage does not permit is clamped to `notify-only`, regardless of
+ *      what triage proposed.
+ *   2. Budget + cooldown. Interventions are capped per turn and spaced by a
+ *      cooldown, so a flapping stall cannot trigger an unbounded action loop.
+ *   3. Safe-mode escalation. Repeated PTY-stage failures recommend flipping the
+ *      agent to the headless backend instead of retrying the same wedge.
+ *
+ * All functions are pure — no IO, no clock reads (the caller passes `now`).
+ * The executor that actually presses keys / restarts / flips backend lives in
+ * the runner; this module decides, it never acts.
+ */
+import type { TriageVerdict, TriageAction } from './triage';
+/** A recovery action the executor understands (same closed vocabulary as triage). */
+export type RecoveryAction = TriageAction;
+/** A selected recovery, ready for the executor. */
+export interface RecoveryPlan {
+    action: RecoveryAction;
+    /** Present only for `select-option`. */
+    option?: number;
+    /** Why this action (audit/logging). */
+    reason: string;
+}
+/** The safe no-op plan. */
+export declare const NOTIFY_ONLY_PLAN: RecoveryPlan;
+/**
+ * Actions permitted per stalled stage. Deliberately conservative: destructive
+ * or cross-cutting actions (restart-receiver, fallback-headless) are only
+ * allowed where they make sense. `notify-only` is always implicitly allowed.
+ */
+export declare const STAGE_ALLOWED_ACTIONS: Record<string, ReadonlyArray<RecoveryAction>>;
+/**
+ * Decide the recovery plan for a stalled stage given an optional triage verdict.
+ * If a verdict is supplied, its action is honoured ONLY if the stage permits it;
+ * otherwise the plan clamps to notify-only. With no verdict, a conservative
+ * default action for the stage is used (still whitelist-checked).
+ */
+export declare function selectRecoveryAction(input: {
+    stage: string;
+    failureClass: string | null;
+    verdict?: TriageVerdict | null;
+}): RecoveryPlan;
+/** Conservative default action when no triage verdict is available. */
+export declare function defaultActionForStage(stage: string): RecoveryAction;
+export declare const DEFAULT_MAX_INTERVENTIONS_PER_TURN = 3;
+export declare const DEFAULT_COOLDOWN_MS = 30000;
+export interface BudgetConfig {
+    maxPerTurn: number;
+    cooldownMs: number;
+}
+export declare const DEFAULT_BUDGET: BudgetConfig;
+/**
+ * Immutable budget state for one turn. A turn is identified by `turnKey`
+ * (e.g. chatId + signal timestamp); when the key changes the budget resets.
+ */
+export interface BudgetState {
+    turnKey: string;
+    attempts: number;
+    lastAt: number;
+}
+export declare function initialBudget(turnKey: string): BudgetState;
+export interface BudgetVerdict {
+    allowed: boolean;
+    reason: string;
+    /** The state to persist for the next check (reset if the turn changed). */
+    next: BudgetState;
+}
+/**
+ * Decide whether an intervention is allowed now, and return the state to keep.
+ * Resets the counter when the turn changes; enforces the per-turn cap and the
+ * cooldown between attempts. Pure — the caller supplies `now`.
+ */
+export declare function checkBudget(state: BudgetState, turnKey: string, now: number, cfg?: BudgetConfig): BudgetVerdict;
+export declare const DEFAULT_SAFE_MODE_THRESHOLD = 3;
+/**
+ * Whether repeated PTY-stage failures should escalate to safe mode (flip the
+ * agent to the headless backend). Pure.
+ */
+export declare function shouldEnterSafeMode(consecutivePtyFailures: number, threshold?: number): boolean;
+/**
+ * Whether safe mode should be lifted. Safe mode is a reactive fallback; it is
+ * cleared explicitly — on a successful PTY turn after a fix, or on user command.
+ */
+export declare function shouldExitSafeMode(input: {
+    manualRestore?: boolean;
+    healthyPtyTurnObserved?: boolean;
+}): boolean;
+//# sourceMappingURL=recovery-policy.d.ts.map

package/dist/agent/recovery-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-policy.d.ts","sourceRoot":"","sources":["../../src/agent/recovery-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAE3D,qFAAqF;AACrF,MAAM,MAAM,cAAc,GAAG,YAAY,CAAA;AAEzC,mDAAmD;AACnD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,cAAc,CAAA;IACtB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAA;CACf;AAED,2BAA2B;AAC3B,eAAO,MAAM,gBAAgB,EAAE,YAG9B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,CAuB/E,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,CAAA;CAC/B,GAAG,YAAY,CA6Bf;AAED,uEAAuE;AACvE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAiBnE;AAID,eAAO,MAAM,kCAAkC,IAAI,CAAA;AACnD,eAAO,MAAM,mBAAmB,QAAS,CAAA;AAEzC,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,eAAO,MAAM,cAAc,EAAE,YAG5B,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAE1D;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,2EAA2E;IAC3E,IAAI,EAAE,WAAW,CAAA;CAClB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,YAA6B,GACjC,aAAa,CAgBf;AAID,eAAO,MAAM,2BAA2B,IAAI,CAAA;AAE5C;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,sBAAsB,EAAE,MAAM,EAC9B,SAAS,GAAE,MAAoC,GAC9C,OAAO,CAET;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,sBAAsB,CAAC,EAAE,OAAO,CAAA;CACjC,GAAG,OAAO,CAEV"}