instar 1.3.665 → 1.3.667

package/dist/monitoring/PermissionPromptAutoResolver.d.ts

@@ -0,0 +1,215 @@
+/**
+ * PermissionPromptAutoResolver — the always-on, unconditional SAFETY FLOOR that
+ * keeps Instar from being silently wedged on an agent-framework approval prompt.
+ *
+ * Spec: docs/specs/framework-permission-prompt-robustness.md
+ * Convergence: docs/specs/reports/framework-permission-prompt-robustness-convergence.md
+ *
+ * The bug it closes (Claude Code 2.1.176–177): a hardcoded Bash safety classifier
+ * pauses a session on a terminal Y/N approval prompt (e.g. "Compound command
+ * contains cd with output redirection — manual approval required … Do you want to
+ * proceed? ❯ 1. Yes / 2. No"). It runs BEFORE all permission rules and hooks, so
+ * `--dangerously-skip-permissions` cannot pre-answer it. A remote agent (Telegram /
+ * dashboard) cannot press a terminal key, so the session freezes forever while still
+ * LOOKING busy — a third liveness state every existing watcher mis-reads.
+ *
+ * The operator directive that governs the design: a low-level command/tool approval
+ * prompt is NEVER a user decision — the agent runs operator-owned sessions with full
+ * machine access. So a prompt-parked session is a DEFECT to auto-clear and detect,
+ * never a "waiting for operator" state.
+ *
+ * TWO PURE DETECTORS + a stateful driver:
+ *   - Layer 2 (`detectApprovalPrompt`, LOAD-BEARING): matches a registered approval
+ *     signature with the ❯ selector cursor sitting on an approve option, at the
+ *     genuine bottom of a non-generating pane → the driver sends `Enter` (confirm the
+ *     highlighted default). Bar-raising MITIGATION, not closure — a text capture
+ *     cannot perfectly tell TUI chrome from displayed content, so the residual is
+ *     bounded by Enter-only + re-capture-before-send + a per-episode attempt cap + a
+ *     terminal defect.
+ *   - Layer 3 (`detectPersistingMenu`, prose-AGNOSTIC observability): matches ANY
+ *     persisting glyph-led numbered menu the resolver did NOT auto-clear (❯-not-on-
+ *     approve, prose-drift, an open non-approval picker) → after a persistence
+ *     threshold it raises the SAME terminal defect. This is what makes "never
+ *     silently stranded" TRUE for the cases Layer 2 declines, and doubles as the
+ *     prompt-string drift detector.
+ *
+ * Signal-vs-authority: the detectors are pure. The ONLY actuation is `sendKey(…,
+ * 'Enter')` (a benign empty submit on a false match) and `raiseDefect` (an Attention
+ * item). No new blocking authority. All I/O is injected (DI), so the detectors +
+ * state machine are fully unit-testable.
+ *
+ * Privacy: the audit logs only the STATIC registry pattern NAMES and a one-way
+ * fingerprint — never the raw tail. Layer 3's dedup key is a one-way digest of the
+ * option labels — the labels themselves are never logged.
+ */
+/** Per-episode consecutive un-cleared sends before Layer 2 declares Terminal. */
+export declare const MAX_ATTEMPTS = 3;
+/** Layer-3 consecutive matched ticks before the persisting-menu Terminal defect. */
+export declare const LAYER3_PERSIST_TICKS = 4;
+/** Per-entry staleness TTL — neither state map can grow with uptime (Bounded Accumulation). */
+export declare const STATE_TTL_MS: number;
+/**
+ * One non-empty line of a captured tail, split into the lead-STRIPPED content
+ * (`text`, via `stripLineLead`) and the separated leading run (`leadGlyphs`, via
+ * `leadGlyphsOf`). `text` lets anchored regexes match the real first token; the
+ * separated `leadGlyphs` lets the detector test for the ❯ selector cursor
+ * specifically (not merely "some glyph", which `wasGlyphLed` answers).
+ */
+export interface PaneTailLine {
+    text: string;
+    leadGlyphs: string;
+}
+/**
+ * Split a raw tmux tail capture into `PaneTailLine`s — dropping whitespace-only
+ * lines (like `liveTail`), mapping each remaining RAW line → its lead-stripped
+ * `text` + its `leadGlyphs`. Pure.
+ */
+export declare function toPaneTailLines(rawTail: string): PaneTailLine[];
+/** A single registered prose pattern carrying its stable symbolic name. */
+export interface ProsePattern {
+    name: string;
+    pattern: RegExp;
+}
+/** The registered signature for one framework. */
+export interface ApprovalSignature {
+    prosePatterns: ProsePattern[];
+    /** Anchored at the start of the post-`N.` option label — an APPROVE verb. */
+    approveLabels: RegExp;
+}
+/**
+ * Approval-prompt signatures, keyed by framework. Only `claude-code` is VERIFIED at
+ * ship; codex/gemini entries are deliberately OMITTED — off until a live prompt is
+ * characterized (Decision 10). The resolver tries EVERY registered signature each
+ * tick (it does not depend on a session's framework field, undefined on legacy
+ * records); a Claude prompt won't match a Codex pattern, so trying all is safe.
+ *
+ * `matchedPatternNames` (what the audit + fingerprint use) are these STATIC `name`s —
+ * never matched tail text — so neither artifact can ever carry pane-derived bytes.
+ */
+export declare const APPROVAL_PROMPT_SIGNATURES: Record<string, ApprovalSignature>;
+/** A Layer-2 match — an answerable, focused approval menu. */
+export interface ApprovalMatch {
+    framework: string;
+    /** The STATIC registry names that matched, sorted. Never tail text. */
+    matchedPatternNames: string[];
+    /** The only key the resolver ever sends. */
+    approveKey: 'Enter';
+    /** hash(framework + sorted matchedPatternNames) — invariant across redraws,
+     *  carries NO tail-derived bytes. */
+    stableFingerprint: string;
+}
+/** A Layer-3 match — a persisting glyph-led menu the resolver will NOT auto-answer. */
+export interface MenuMatch {
+    /** The sorted texts of the numbered option lines (consumed ONLY as hash input). */
+    optionLabels: string[];
+}
+/**
+ * Pure Layer-2 detector. Returns a match ONLY when ALL hold:
+ *   1. ≥2 DISTINCT named prose patterns from the framework's registry matched;
+ *   2. a line whose `leadGlyphs` contains ❯ AND whose `text` is `N.` followed by an
+ *      approve label (the selector cursor is ON an approve option);
+ *   3. the menu is at the genuine bottom (no idle input box below, option line within
+ *      the bottom window) AND the session is not generating.
+ *
+ * Honest residual (spec security#1): a tmux text capture cannot perfectly prove a
+ * `❯ 1. Yes` is TUI chrome vs displayed content. Requirements 1–3 substantially raise
+ * the bar; the residual is bounded by the Enter-only keystroke + re-capture + attempt
+ * cap + Terminal defect in the driver, never by this detector pretending closure.
+ */
+export declare function detectApprovalPrompt(tail: PaneTailLine[], framework: string, isGenerating: boolean): ApprovalMatch | null;
+/**
+ * Pure Layer-3 detector. Prose-agnostic by design (so it catches drift): matches
+ * purely on STRUCTURE — (i) a glyph-led numbered option line, (ii) a generic
+ * blocking affordance (`Esc to cancel` / `Do you want to proceed` / ≥2 numbered
+ * options), (iii) genuine bottom, (iv) not generating. Deliberately matches the
+ * cases Layer 2 declines (❯ not on an approve option, prose-drift) AS WELL AS a
+ * genuinely open non-approval picker (an accepted, benign surface — something IS
+ * waiting for input the agent cannot self-answer, worth one notice).
+ */
+export declare function detectPersistingMenu(tail: PaneTailLine[], isGenerating: boolean): MenuMatch | null;
+/** A Terminal defect raised to the Attention surface (the wiring owns dedup). */
+export interface ResolverDefect {
+    sessionName: string;
+    layer: 'layer2' | 'layer3';
+    /** sessionName + fingerprint (Layer 2) OR sessionName + menuStructureKey (Layer 3). */
+    dedupKey: string;
+    fingerprint?: string;
+    menuStructureKey?: string;
+    /** STATIC names only (Layer 2). */
+    matchedPatternNames?: string[];
+    reason: string;
+}
+/** The outcome of one Layer-2 action, recorded in the audit. */
+export type ResolverOutcome = 'answered' | 'retried' | 'cleared' | 'persisted-terminal' | 'send-failed' | 'race-aborted';
+/** One audit row. NEVER carries raw tail — only the static matched-pattern names. */
+export interface ResolverAuditRow {
+    ts: number;
+    sessionName: string;
+    framework: string;
+    matchedPatternNames: string[];
+    keySent: 'Enter' | null;
+    fingerprint: string;
+    attempt: number;
+    outcome: ResolverOutcome;
+}
+export interface PermissionPromptResolverDeps {
+    /** Send a keystroke to the session's pane. Returns/resolves false on failure. */
+    sendKey: (session: string, key: string) => boolean | Promise<boolean>;
+    /** Re-capture the live tail for the race-guard. Null/throw → race-aborted. */
+    reCaptureTail: (session: string) => Promise<PaneTailLine[] | null>;
+    /** Is the session generating right now? (e.g. looksGeneratingNow on the tail.) */
+    isGenerating: (rawOrTail: string) => boolean;
+    /** Raise the Terminal Attention defect (the wiring dedups + age-escalates). */
+    raiseDefect: (args: ResolverDefect) => void;
+    /** Append one audit row (size-bounded JSONL in the wiring). Must not throw up. */
+    appendAudit: (row: ResolverAuditRow) => void;
+    /** Clock (tests). */
+    now: () => number;
+    /** The emergency off-switch (absent ⇒ false ⇒ floor ON). */
+    emergencyDisabled: () => boolean;
+}
+export declare class PermissionPromptAutoResolver {
+    private readonly deps;
+    /** Layer-2 episode state, keyed (session, stableFingerprint). */
+    private readonly episodes;
+    /** Layer-3 persistence state, keyed (session, menuStructureKey). */
+    private readonly persistMenus;
+    /** Last evaluate/sweep wall-clock — the GuardRegistry liveness read. */
+    private lastTickAt;
+    constructor(deps: PermissionPromptResolverDeps);
+    /**
+     * Per-candidate tick logic for one running session. Captures nothing of its own —
+     * the caller passes the already-in-hand fuller tail. Layer 2 owns a tick it
+     * matched (returns before Layer 3), so the two can never double-raise one wedge.
+     */
+    evaluate(session: string, fullTail: PaneTailLine[]): Promise<void>;
+    /**
+     * Evict every state entry for `session` EXCEPT the one active this tick (the
+     * reset-on-clear rule). An evicted Layer-2 entry that had un-cleared sends and was
+     * not already terminal audits `cleared` (the episode's prompt was answered/gone).
+     */
+    private reconcileSession;
+    private handleLayer2;
+    private handleLayer3;
+    /**
+     * Evict BOTH maps' entries for sessions no longer running, and any entry older
+     * than the per-entry TTL (stale lastTick). Neither map can grow with uptime.
+     * Called each tick.
+     */
+    sweep(runningSessions: Set<string>): void;
+    /** Cheap, no-I/O runtime liveness read for the GuardRegistry (GET /guards). */
+    guardStatus(): {
+        enabled: boolean;
+        lastTickAt: number;
+    };
+    /** Current live state-map sizes (both are provably bounded by the eviction triple). */
+    stateSizes(): {
+        episodes: number;
+        persistMenus: number;
+    };
+    private l2Key;
+    private l3Key;
+    private menuStructureKey;
+    private audit;
+}
+//# sourceMappingURL=PermissionPromptAutoResolver.d.ts.map

package/dist/monitoring/PermissionPromptAutoResolver.d.ts.map

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