charness 0.0.0-stage → 3.0.0

package/dist/adapters/claudeCliAdapter.d.ts

@@ -0,0 +1,1336 @@
+import { EventEmitter } from 'events';
+import type { AgentAdapter, AgentRuntimeInfo, AgentSession, ClaudeSurveyOption, DisplayPrefsReader, ReattachRecap, RecentTurn, ResumeSessionOptions, SeenWatermark, SeenWatermarkWriter, SendInputOptions, ThreadLocaleReader } from '../types';
+import type { SessionKey } from '../sessionKey';
+import { type ToolResultKind } from '../utils/claudeScrapeShapes';
+import { type SerialQueue } from '../utils/serialQueue';
+import { tmuxAsync } from '../utils/tmuxExec';
+import { convertAnsiToMarkdown, cleanOutput } from '../utils/ansiClean';
+import { getNewPaneContent, type NewPaneContent } from '../utils/paneDiff';
+import { type SubagentTailState } from '../utils/claudeSubagentTail';
+import { type RecentRelayWindow } from '../utils/recentRelayWindow';
+import { type ClaudeChunkContext } from '../utils/claudeChunkClassifier';
+/**
+ * @description Per-thread Claude CLI session state.
+ *
+ * One tmux session is spawned per `SessionKey`. The tmux session name embeds
+ * both `chatId` and `threadId` so multiple threads sharing the same `workDir`
+ * stay fully isolated (plan §10.2, D8).
+ */
+export interface ClaudeSession {
+    key: SessionKey;
+    workDir: string;
+    sessionName: string;
+    /** UUID we pass via `--session-id` (or, on resume, via `--resume`). */
+    claudeSessionId: string;
+    queue: SerialQueue;
+    pollTimer: NodeJS.Timeout | null;
+    lastContent: string;
+    isActive: boolean;
+    handledAutoEnter: boolean;
+    handledAutoAccept: boolean;
+    /**
+     * One-shot guard for the auto-retry `apiError` emit. Armed when the terminal
+     * `API Error:` line first classifies as retryable, reset by the same
+     * `newPart.length > 50` rule as the sibling `handled*` flags — so a later,
+     * distinct error in the same session re-arms, but a static error frame
+     * doesn't re-emit on every poll.
+     */
+    handledApiError: boolean;
+    /** Normalized text of last emitted status (for deduplication of spinner updates) */
+    lastStatusText: string;
+    /**
+     * The last text the bot typed into this session via {@link ClaudeCliAdapter.sendInput}
+     * (the preamble-glued prompt, a `/c continue` nudge, a buffered replay — every
+     * typed path). Used by the CONTENT-based echo gate (S1): Claude echoes typed
+     * input back in the pane, and when that echo carries no `❯` (a wrapped row, the
+     * `[Telegram thread context]` preamble, a voice-transcript tail) the shape-only
+     * {@link checkIsInputEchoFrame} misses it and it leaks into the topic. Empty
+     * until the first send.
+     */
+    lastForwardedText: string;
+    /**
+     * Epoch ms of the last {@link lastForwardedText} capture. The content echo gate
+     * only fires within a short window after a send (the echo appears right at
+     * submit), so a much later real reply that coincidentally repeats prompt words
+     * is never suppressed.
+     */
+    lastForwardedTextAt: number;
+    /**
+     * Signature of the last emitted interactive-question block (the option-label
+     * set, ignoring which option is highlighted). Moving the `❯` cursor repaints
+     * the whole box every keystroke; comparing signatures lets us deliver the
+     * question once and suppress the cursor-move repaints. Cleared when real
+     * prose follows (the question is over). See {@link extractClaudeQuestion}.
+     */
+    lastQuestionSignature: string;
+    /**
+     * Consecutive poll diffs (while a question is pending) in which
+     * {@link extractClaudeQuestion} found NO selector on screen. The selector
+     * repaints constantly, so a single scrape can momentarily fail to match while
+     * it is still up; resolving the question (emit `questionGone`) on that lone
+     * null both unpins prematurely AND re-emits a duplicate question + notification
+     * the next poll (the signature was cleared). We only treat the question as gone
+     * after it has been absent for {@link questionAbsentPollThreshold} consecutive
+     * diffs. Reset to 0 on any detection.
+     */
+    questionAbsentPolls: number;
+    /**
+     * Signature of the last AUTO-DISMISSED Claude CLI bare-digit survey (header +
+     * option digits/labels). Same de-dup mechanism as
+     * {@link lastQuestionSignature}: the survey repaints every poll while on
+     * screen, so comparing signatures sends the dismiss keystroke exactly once.
+     * Cleared when the survey leaves the pane, so a genuinely new survey later is
+     * re-dismissed. Drives {@link checkShouldDismissSurvey}. See
+     * {@link extractClaudeSurvey}.
+     */
+    lastSurveySignature: string;
+    /**
+     * Handles for the auto-Enter / auto-Accept `setTimeout`s. Audit S9 / #10:
+     * the callbacks used to fire 300–400 ms after detection regardless of
+     * whether the session was still alive; on rapid stop/start the keystroke
+     * would land in a different invocation (e.g. auto-accepting a permission
+     * prompt belonging to a replacement session). Cleared on `stopSession`;
+     * callbacks also re-check `session.isActive` before issuing tmux keys.
+     */
+    autoEnterTimer: NodeJS.Timeout | null;
+    autoAcceptOuterTimer: NodeJS.Timeout | null;
+    autoAcceptInnerTimer: NodeJS.Timeout | null;
+    /**
+     * Re-entrancy guard for `pollOutput`. Audit S9 / #37: a `tmux capture-pane`
+     * under load can take longer than the 300 ms poll interval, and the next
+     * `setInterval` tick would fire before the previous one finished, leading
+     * to duplicate `output` emissions. With self-rescheduling `setTimeout`
+     * and this flag we serialise polls; ticks that overlap with an in-flight
+     * one are skipped silently.
+     */
+    isPolling: boolean;
+    /**
+     * Tool-result kind still open at the end of the last emitted poll, threaded
+     * into the next poll so a slow command's orphan output (whose `● Bash(…)`
+     * header was suppressed by the line-set diff) is still fenced (B2). See
+     * {@link fenceToolResultBodies}.
+     */
+    openToolKind: ToolResultKind | null;
+    /**
+     * Resume flood-suppression mode. On `--resume`, Claude repaints the ENTIRE
+     * restored transcript into the pane over several polls; relaying that diff
+     * would dump hours of old conversation into the topic. While seeding we
+     * advance the baseline (`lastContent`) every poll but emit NOTHING, so once
+     * the pane stops growing the baseline equals the full restored transcript
+     * and later diffs are genuine new output. The short last-3-turn context block
+     * is posted separately (read from the `.jsonl`). The auto-Enter / auto-Accept
+     * machinery KEEPS running during seeding — we suppress conversation text, not
+     * lifecycle. See {@link getResumeSeedDecision}.
+     */
+    resumeSeeding: boolean;
+    /** Polls elapsed in {@link resumeSeeding} mode — drives the stable/cap exit. */
+    resumeSeedPolls: number;
+    /** Pane content seen on the previous seeding poll, for the "unchanged across 2 polls" exit. */
+    resumeSeedPrevContent: string;
+    /**
+     * Raw `capture-pane` text from the previous poll. When the new capture is
+     * byte-identical we skip `cleanOutput` entirely (S1) — identical raw ⇒
+     * identical cleaned content, so the ~15-regex parse is pure wasted work on
+     * an idle pane. Reset wherever {@link lastContent} resets.
+     */
+    lastRawCapture: string;
+    /**
+     * Current poll delay in ms (S2 adaptive backoff). Starts at
+     * {@link basePollIntervalMs}; {@link getNextPollDelay} grows it toward
+     * {@link maxPollIntervalMs} while the pane stays unchanged and snaps it back
+     * to base on any change or explicit write (see {@link resetPollCadence}).
+     */
+    currentPollDelayMs: number;
+    /** Consecutive unchanged polls — drives {@link getNextPollDelay}'s backoff. */
+    unchangedPollStreak: number;
+    /**
+     * Epoch ms of the last poll whose raw `capture-pane` DIFFERED from the
+     * previous one (i.e. the TUI pane actually changed). Drives the bot's
+     * pane-static idle net via {@link ClaudeCliAdapter.getMsSincePaneChange}: a
+     * genuinely working agent repaints the pane every second (animated spinner +
+     * the TUI's own elapsed timer), so a long gap since the last change means the
+     * agent is idle even if the footer busy signal is stuck. Seeded to "now" at
+     * session creation / adopt so a fresh session never reads as instantly stale.
+     */
+    lastContentChangeAt: number;
+    /**
+     * S7 one-shot: the stored `/effort` level to re-type ONCE the TUI input box
+     * first appears, so a fresh spawn doesn't inherit claude's GLOBAL effort
+     * state (possibly set in another topic). Set at spawn from the per-thread
+     * pref ({@link applyStoredEffortOnSpawn}); `null` when no pref or already
+     * applied. Consumed by the first poll that sees a ready prompt
+     * ({@link checkIsClaudePromptReady}), BEFORE the bot replays buffered prompts
+     * onto the same serial tmux queue. NOT set on adopt/reattach (that claude
+     * process kept its in-TUI effort and may be mid-turn).
+     */
+    pendingEffortReapply: string | null;
+    /**
+     * Last transcript byte size persisted as the seen-{@link SeenWatermark} for
+     * this session (in-memory monotonic high-water mark). The poll loop advances
+     * the watermark to the current transcript EOF on EVERY idle+ready poll (not
+     * just the single busy→ready edge), but writes only when EOF actually grew —
+     * this field is the comparison anchor. `undefined` until the first advance,
+     * treated as `-1` (the first idle poll always writes). Fresh per session object
+     * (start / resume / adopt); correctness across a restart is protected by the
+     * recap's PRE-adopt watermark snapshot, not by seeding this from disk. Lets a
+     * bot restart count the assistant turns produced while it was down, and — vs
+     * the old edge-only gate — corrects a premature mid-turn idle advance and
+     * catches a final assistant line flushed just after the turn ends. See
+     * {@link checkShouldAdvanceWatermark} / {@link ClaudeCliAdapter.advanceClaudeWatermarkIfGrown}.
+     */
+    lastWatermarkOffset?: number;
+    /**
+     * Long-horizon dedup of lines already RELAYED to this topic (incident
+     * 2026-06-10: a TUI re-render of an hours-old ~1400-line diff re-relayed as
+     * a ~12-message flood — {@link getNewPaneContent} only knows the previous
+     * capture, so a redraw of old scrollback looks "new" to it). The poll loop
+     * filters every diff chunk through this window before emitting and records
+     * a chunk ONLY when it was emitted as permanent output (status frames roll
+     * in place; questions/surveys carry their own signature de-dup). Fresh per
+     * session object (start / resume / adopt), dies with the session on stop,
+     * and reset again when resume seeding ends — the window must start empty
+     * AFTER the restored transcript was swallowed. See
+     * `utils/recentRelayWindow.ts` for the locked drop-over-resend tradeoff.
+     */
+    recentRelayWindow: RecentRelayWindow;
+    /**
+     * Sub-agent transcript tail state (`/subagent full` on Claude, plan
+     * 2026-06-11 S3). The poll loop scans
+     * `<projectsRoot>/<slug>/<claudeSessionId>/subagents/` every tick and feeds
+     * file sizes / appended bytes into the pure `claudeSubagentTail` helpers;
+     * this holds the per-file byte offsets + partial-line carries. Fresh per
+     * session object (start / resume / adopt all flow through `createSession`),
+     * so the helper's first-scan EOF seeding kills backlog replay on
+     * resume/adopt — see {@link ClaudeCliAdapter.scanSubagentTranscripts}.
+     */
+    subagentTail: SubagentTailState;
+    /**
+     * Cross-poll classifier context for the verbosity relay (S4). A tool body /
+     * thinking block / sub-agent panel can span the boundary between two scraped
+     * chunks (Claude redraws the whole pane each poll; the diff emits only NEW
+     * lines, so a slow command's body arrives in a later poll without its
+     * header). {@link classifyClaudeChunk} threads this so the later chunk still
+     * tags those orphan lines correctly. Fresh per session object (start /
+     * resume / adopt all flow through `createSession`).
+     */
+    chunkContext: ClaudeChunkContext;
+    /**
+     * Last known pane size (`<width>x<height>`, e.g. `300x50`) from the per-poll
+     * `#{pane_width}x#{pane_height}` query; `null` until the first successful
+     * read. A CHANGE means tmux re-wrapped the whole scrollback (an interactive
+     * `tmux attach`/detach resizes the window — live incident 2026-07-02)
+     * and the poll's giant line-SET diff is repaint, not output. See
+     * {@link getPaneResizeGuardDecision}.
+     */
+    lastPaneSize: string | null;
+    /**
+     * Whether the session is swallowing a resize repaint: baseline advances
+     * every poll but NOTHING is emitted, until a poll sees the capture unchanged
+     * (or the settle cap fires). Same suppress-and-advance shape as
+     * {@link resumeSeeding}, but for pane-size changes.
+     */
+    isResizeSettling: boolean;
+    /** Consecutive suppressed polls spent in {@link isResizeSettling} — drives the cap. */
+    resizeSettlePolls: number;
+    /**
+     * Streaming-table stabilizer state (live incident 2026-06-11, plan
+     * `2026-06-11-claude-wide-table-content-loss`). A wide markdown table re-flows
+     * its column widths as longer cells stream in; the line-SET diff treats each
+     * intermediate layout as "new" and would ship the table once per layout (empty
+     * skeleton → 1 row → full), with the final full frame often dropped under the
+     * coalescer's debounce / a 429. We hold the table back until it settles, then
+     * emit the complete version once. `null` = no table currently held. Reset at
+     * the same lifecycle points as {@link recentRelayWindow} (fresh per session
+     * object via `createSession`, and on the resume-seed exit). See
+     * {@link getTableStabilizationDecision}.
+     */
+    streamingTable: StreamingTableState | null;
+}
+export declare function loadEffortPrefs(): Record<string, string>;
+export declare function saveEffortPref(key: SessionKey, level: string): void;
+/**
+ * @description Tmux session name for a `SessionKey`.
+ *
+ * Format: `claude-<chatId>-<threadId>`. Negative chat ids (forum supergroups
+ * are negative) keep their minus sign — tmux session names accept it. The
+ * format is `parse`-able back to `SessionKey` via {@link parseTmuxSessionName}.
+ */
+declare function buildTmuxSessionName(key: SessionKey): string;
+/**
+ * @description Inverse of {@link buildTmuxSessionName}. Returns `null` for
+ * names that don't match our format (e.g. unrelated tmux sessions a user
+ * started by hand).
+ *
+ * Carefully handles negative chat ids: `claude--1001234-42` is `chatId=-1001234, threadId=42`.
+ */
+declare function parseTmuxSessionName(name: string): SessionKey | null;
+/**
+ * @description Validate a UUID-shaped session id before it ever reaches a
+ * tmux command line. Defence-in-depth (audit S1): even though we now route
+ * every tmux call through argv (no shell interpolation), the UUID is later
+ * concatenated into the `shell-command` we hand to `tmux new-session`,
+ * which tmux execs via `$SHELL -c`. If a non-UUID value ever sneaks in
+ * (corrupted state.json, future user-facing `/resume <id>`), it would land
+ * in that shell. Rejecting up front keeps the surface tight.
+ */
+export declare function checkIsValidUuid(s: string): boolean;
+/**
+ * @description Pure parser — pulls a `--session-id <uuid>` value out of a
+ * claude command line. Lives outside the adapter class so it can be
+ * unit-tested without booting tmux. Quoting in the input is flexible
+ * because `pane_start_command` can come back as `--session-id 'uuid'`,
+ * `--session-id "uuid"`, `--session-id=uuid`, or just `--session-id uuid`,
+ * depending on how the original shell-command was assembled. Returns the
+ * lowercase UUID, or `null` if no valid UUID is found.
+ */
+export declare function parseClaudeSessionIdFromCommand(cmd: string): string | null;
+export { tmuxAsync };
+export { convertAnsiToMarkdown, cleanOutput };
+/**
+ * @description Check if output consists only of transient status lines (spinners, progress).
+ * Uses generic heuristics instead of hardcoded spinner chars/words,
+ * because Claude CLI can change its TUI symbols and wording at any time.
+ *
+ * Key insight: real Claude content is substantial (> 200 chars, multi-sentence).
+ * Status/progress is short, has few lines, and contains indicators like … or time/token stats.
+ */
+export declare function checkIsStatusOutput(text: string): boolean;
+/**
+ * @description A single interactive question Claude scraped from the pane,
+ * rendered for durable delivery.
+ */
+export interface ClaudeQuestion {
+    /**
+     * Header + every numbered option (highlighted one kept), each followed by
+     * its indented description sub-line(s) when the TUI shows any, ready to send.
+     */
+    text: string;
+    /**
+     * Stable across cursor moves — the option-label set, ignoring which option
+     * is currently highlighted. Two `❯`-cursor positions over the same options
+     * yield the same signature, so the bot delivers the question once.
+     */
+    signature: string;
+}
+/**
+ * @description Detect + extract the active interactive question/choice block
+ * from the FULL Claude pane, returning a durable rendering and a
+ * cursor-invariant signature, or `null` when the pane isn't confidently
+ * showing a question.
+ *
+ * Operates on the whole pane (not a poll diff) on purpose: moving the `❯`
+ * cursor repaints only the two changed option lines, so a signature taken
+ * from the diff would be a partial option set and wouldn't match the full
+ * box — the de-dup would fail and every keystroke would re-spam the thread.
+ * Reading the full option group makes the signature stable across cursor
+ * moves. We take the LAST option group (the active prompt sits at the bottom
+ * of the pane) and the header line(s) just above it.
+ *
+ * Conservative (plan §2026-05-30 / S2): requires a `❯` cursor on an option
+ * OR an "Enter to select"-style hint right below the group — a plain numbered
+ * list in prose has neither, so it returns `null` and falls through to the
+ * normal output path. The `❯`-highlighted option text is preserved (the old
+ * `stripTuiElements` path discarded every `^❯` line, losing the selection).
+ *
+ * Two layouts (plan §2026-06-09 question-ux / S4):
+ *  - single-column — options with optional indented description sub-lines,
+ *    which are ATTACHED to their option in the rendering (S1: previously
+ *    discarded);
+ *  - side-by-side (options WITH `preview` content) — each option line carries
+ *    a right-hand preview-box fragment that is CUT off; the preview body is
+ *    deliberately NOT relayed (Telegram gets labels + descriptions, the
+ *    preview is a TUI-only nicety). See {@link PREVIEW_BOX_GLYPH_CLASS} and
+ *    {@link HIGHLIGHTED_OPTION_BOLD_ARTIFACT_REGEX} for the live bug both
+ *    rules close.
+ */
+export declare function extractClaudeQuestion(text: string): ClaudeQuestion | null;
+/** Whether `text` is confidently showing an interactive question/choice block. */
+export declare function checkIsClaudeQuestionBlock(text: string): boolean;
+/**
+ * @description Classify a user reply sent WHILE a selector is on screen. A
+ * "control" reply is meant to drive the selector in place — a bare option
+ * number (1–2 digits) or a single `y`/`n` — so it must be typed straight into
+ * the TUI with no Escape. Anything else (a sentence, a new instruction) is a
+ * free-form message: the bot first sends Escape to cancel the selector, then
+ * forwards it as a fresh turn. Kept pure + exported so the routing decision is
+ * unit-testable without a live tmux session.
+ */
+export declare function checkIsSelectorControlReply(text: string): boolean;
+/**
+ * @description A Claude CLI bare-digit survey scraped from the pane, ready for
+ * answerable delivery. Distinct from {@link ClaudeQuestion} (a real
+ * AskUserQuestion box): a survey is a fixed-shape one-keystroke prompt.
+ */
+export interface ClaudeSurvey {
+    /** Header line, e.g. `How is Claude doing this session?`. */
+    header: string;
+    /** Options parsed from the inline `N: Label` row, in display order. */
+    options: ClaudeSurveyOption[];
+    /**
+     * Stable signature derived ONLY from header + option digits/labels — NOTHING
+     * volatile (no spinner glyph, no elapsed time, no surrounding pane). So the
+     * same survey across polls yields an identical signature → the bot emits it
+     * exactly once (mirrors {@link ClaudeQuestion.signature}).
+     */
+    signature: string;
+}
+/**
+ * @description AIRTIGHT detector for the Claude CLI bare-digit survey. Returns
+ * a survey ONLY when BOTH hold:
+ *
+ *   1. Some line, after stripping an optional leading `● ` bullet, matches
+ *      {@link CLAUDE_SURVEY_HEADER_REGEX} ANCHORED start-to-end (the WHOLE
+ *      line) — so a header quoted mid-sentence is rejected.
+ *   2. The IMMEDIATELY-FOLLOWING non-empty line is an inline option row
+ *      ({@link CLAUDE_SURVEY_OPTION_ROW_REGEX}) parsing to ≥2 options.
+ *
+ * Kept fully SEPARATE from {@link extractClaudeQuestion} (the per-line
+ * AskUserQuestion selector): this is a lighter fixed-shape prompt. The
+ * signature is header + the option digits/labels only (no volatile chrome), so
+ * the same survey across polls de-dups to a single emit.
+ */
+export declare function extractClaudeSurvey(text: string): ClaudeSurvey | null;
+/** Whether `text` is confidently showing a Claude CLI bare-digit survey. */
+export declare function checkIsClaudeSurvey(text: string): boolean;
+/**
+ * @description Whether the poll loop should AUTO-DISMISS the survey on screen
+ * this poll (S4). True only when a survey is present AND its signature differs
+ * from the one we last dismissed — the survey repaints every poll, so the
+ * signature dedup makes us send the dismiss keystroke exactly ONCE per
+ * appearance, and re-dismiss a genuinely new survey later (the caller clears the
+ * stored signature when the survey leaves the pane). Pure + exported so the
+ * once-per-appearance rule is unit-testable without a live session.
+ */
+export declare function checkShouldDismissSurvey(surveySignature: string | null, lastDismissedSignature: string): boolean;
+/**
+ * @description Drop the survey's header + option-row lines from a relay chunk
+ * (S4) so the auto-dismissed survey's chrome never leaks into the topic — those
+ * lines match no tool/spinner/chrome rule and would otherwise classify as prose
+ * and post as a stray message. The CALLER gates this on a survey actually being
+ * detected on the pane this poll, so a legitimate "1: Yes  2: No" list in normal
+ * agent output is never stripped. Pure + exported for unit testing.
+ */
+export declare function stripSurveyChromeLines(text: string): string;
+/**
+ * @description One ordered tmux send-keys step the adapter will enqueue for a
+ * {@link ClaudeCliAdapter.sendInput} call. Extracted as a pure plan so the
+ * "no Enter" decision is unit-testable WITHOUT a live tmux session.
+ *
+ *  - `literal`       — `send-keys -l <input>` (the typed text, literal bytes);
+ *  - `instantEnter`  — `send-keys Enter` immediately (short control reply);
+ *  - `slashEnter`    — `send-keys Enter` deferred so the slash-popup settles;
+ *  - `verifiedEnter` — `send-keys Enter` deferred past the paste-aggregation
+ *    window, plus a post-Enter unsubmitted re-check (a plain prompt).
+ */
+export type ClaudeSendKeyStep = 'literal' | 'instantEnter' | 'slashEnter' | 'verifiedEnter';
+/**
+ * @description Pure plan of the tmux send-keys steps for one `sendInput` call.
+ *
+ * Mirrors the three historical Enter branches (bare slash command → deferred
+ * Enter; short control reply → instant Enter; plain prompt → paste-race
+ * deferred Enter + verification). When `appendEnter === false` ONLY the literal
+ * keystrokes are sent — every Enter branch is skipped (for a keystroke that
+ * auto-submits on its own). `appendEnter` defaults to `true`, so every existing
+ * caller's plan is byte-for-byte unchanged.
+ */
+export declare function getClaudeSendKeysPlan(input: string, appendEnter: boolean): ClaudeSendKeyStep[];
+/** Where a Claude text reply should be routed while a prompt may be on screen. */
+export type ClaudeReplyRoute = 'selector' | 'loginPaste' | 'prompt';
+/**
+ * @description Decide how to route a user TEXT reply for a Claude thread,
+ * given which interactive prompts are currently pending. Pure so the
+ * precedence is unit-testable.
+ *
+ * Precedence (a real AskUserQuestion always wins):
+ *   1. A selector (AskUserQuestion) pending + a bare control reply
+ *      (digit / y / n) → `'selector'` (drive the menu in place).
+ *   2. Else the `/login` "Paste code here" box is on screen → `'loginPaste'`:
+ *      the OAuth code is a long free-form string, so route it VERBATIM into
+ *      the box (see {@link checkIsClaudeLoginPaste}). Without this it falls to
+ *      `'prompt'`, whose Escape cancels the login flow and whose preamble
+ *      corrupts the code (live bug: "login can't be done via the bot").
+ *   3. Else → `'prompt'` (a fresh turn; free-form prose breaks out of any
+ *      pending prompt, mirroring the existing selector break-out behavior).
+ *
+ * Claude's native session SURVEY is NOT routed here: the adapter auto-dismisses
+ * it (Escape) and never surfaces it to the user, so a bare digit typed during a
+ * survey window falls through to `'prompt'` (or `'selector'` when a real
+ * question is also up) — never silently dropped.
+ */
+export declare function getClaudeReplyRoute(input: {
+    isQuestionPending: boolean;
+    isLoginPastePending: boolean;
+    text: string;
+}): ClaudeReplyRoute;
+export declare function checkIsClaudeLoginPaste(paneText: string): boolean;
+/**
+ * @description Per-session state for the streaming-table stabilizer (live
+ * incident 2026-06-11, plan `2026-06-11-claude-wide-table-content-loss`): the
+ * sharp-corner table block currently being held back, and how many polls it has
+ * been held. Held back because a wide markdown table RE-FLOWS its column widths
+ * as longer cells stream in, so every border/row line is byte-distinct between
+ * layouts → {@link getNewPaneContent} (line-SET diff) classifies the whole table
+ * "new" each poll and it would otherwise ship once per intermediate layout
+ * (empty skeleton → 1 row → full). We withhold the table until it settles, then
+ * emit the complete version exactly once.
+ */
+interface StreamingTableState {
+    /** The full last-contiguous sharp-table block text seen on the previous poll. */
+    block: string;
+    /** Consecutive polls this table has been held without settling — runaway guard. */
+    heldPolls: number;
+}
+/**
+ * @description The action {@link getTableStabilizationDecision} tells the poll
+ * loop to take for a re-flowing sharp-corner table.
+ *
+ * - `none`  — no table in flux; emit the poll's delta as usual.
+ * - `hold`  — the table is still laying out; mask its lines out of this poll's
+ *             delta ({@link maskSharpTableLines}) so no intermediate frame ships,
+ *             and carry `nextStreamingTable` forward.
+ * - `emit`  — the table is DONE (prose follows it / the turn went idle / the
+ *             safety cap fired); emit `block` once via the normal fence path and
+ *             clear the held state.
+ */
+interface TableStabilizationDecision {
+    kind: 'none' | 'hold' | 'emit';
+    /** The complete table block to emit, set only for `kind: 'emit'`. */
+    block: string | null;
+    /** Held state to store back on the session (null clears it). */
+    nextStreamingTable: StreamingTableState | null;
+}
+/**
+ * @description Find the LAST contiguous sharp-corner (markdown) table block in a
+ * full pane snapshot, or `null` when none is present. Returns the raw block text
+ * so the stabilizer can compare it across polls. Pure + exported for unit tests.
+ */
+export declare function getLastSharpTableBlock(content: string): string | null;
+/**
+ * @description Whether any REAL prose line follows the last sharp-corner table in
+ * the pane — the "the table is done, content moved past it" signal the stabilizer
+ * uses to emit the held table BEFORE that trailing prose (preserving order).
+ *
+ * Deliberately CONSERVATIVE (errs toward `false`): a line after the table counts
+ * as content only when it is none of the recognised non-content shapes —
+ * blank/whitespace, another sharp-table line, TUI chrome
+ * ({@link checkIsClaudeChromeLine} — covers the `❯ …` input box and its `───`
+ * rules, box-drawing borders, the `⏵⏵ bypass permissions…` footer, nav hints),
+ * any progress/spinner/sub-agent frame ({@link checkIsProgressChunk} per line),
+ * a live spinner tick ({@link SPINNER_TICK_RE}), a `✻ … for Ns` post-thinking
+ * trailer ({@link POST_THINKING_TRAILER_RE}), or a `Thinking for Ns…` header
+ * ({@link THINKING_HEADER_RE}). Reuses the SAME predicates the relay already
+ * trusts as chrome — it never invents a looser matcher — so it cannot
+ * false-positive on the input box / spinner / trailers (the failure mode that
+ * would emit a table prematurely). The turn-idle signal and the hold safety cap
+ * are the backstops when this stays `false`. Pure + exported for unit tests.
+ */
+export declare function checkHasContentAfterLastSharpTable(content: string): boolean;
+/**
+ * @description Drop every sharp-corner table line from a poll's delta text so a
+ * mid-layout table frame never ships while the stabilizer is holding the table.
+ * Only table-shaped lines are removed — surrounding prose streams as usual.
+ * Pure + exported for unit tests.
+ */
+export declare function maskSharpTableLines(deltaText: string): string;
+/**
+ * @description Decide what the poll loop does with a re-flowing sharp-corner
+ * table. A held table is emitted ONLY when the turn is genuinely DONE — never on
+ * a mere "byte-stable for one poll", because Claude streams a table in stages and
+ * briefly PAUSES at an intermediate row count (e.g. 4 rows), which is byte-stable
+ * across a poll yet not the final table. The old "stable one poll → emit" rule
+ * shipped that 4-row intermediate, then the table grew to 6 rows and shipped
+ * again → the topic got two tables (live incident 2026-06-15). Pure + exported
+ * for unit tests. Rules, in order:
+ *
+ *  1. no table in the pane: flush whatever was held, once (table scrolled away /
+ *     message moved on); else no-op.
+ *  2. real PROSE now follows the table (`hasContentAfterTable`) AND the table's
+ *     width has settled (`sameBlock` — byte-stable since the previous poll) → the
+ *     table is done; emit it BEFORE that trailing prose (the poll loop withholds
+ *     the prose this tick), so ordering is table-then-prose. A table still
+ *     re-flowing wider while prose is already on the pane HOLDS instead — only the
+ *     settled width ships (live flood 2026-07-04).
+ *  3. the turn is IDLE (`isTurnIdle`) → emit promptly (covers a table-only
+ *     answer, which never gets trailing prose).
+ *  4. otherwise HOLD — update the held block and advance `heldPolls` only while
+ *     the block is unchanged (a changed/new block resets the counter); past
+ *     {@link maxTableHoldPolls} force-emit so a never-settling pane can't swallow
+ *     the table forever. A still-busy table is held even when byte-identical
+ *     across polls — that is exactly the mid-stream pause.
+ */
+export declare function getTableStabilizationDecision(input: {
+    currentTable: string | null;
+    streamingTable: StreamingTableState | null;
+    hasContentAfterTable: boolean;
+    isTurnIdle: boolean;
+}): TableStabilizationDecision;
+/**
+ * @description Merge two same-language fenced blocks separated by NOTHING but
+ * blank line(s) into one continuous fence (#14). One logical tool output that
+ * {@link fenceToolResultBodies} split into multiple `getFenced` runs renders as
+ * two adjacent `<pre>` ({@link FENCE_REGEX} makes one per fence) — visually two
+ * boxes for one output. A NON-blank line between the fences (a `● Bash(…)`
+ * header, prose) BLOCKS the merge, so DIFFERENT tool calls stay separate; only
+ * blank-separated same-language fences are joined, keeping one blank inside.
+ * Languages must match (or both be empty) so a plain output block and a `ts`
+ * block are never fused.
+ */
+export declare function mergeAdjacentFences(lines: string[]): string[];
+/**
+ * @description Strip Claude TUI chrome from a pane diff and fence tool-result
+ * bodies, returning the cleaned text AND the tool-result kind still open at the
+ * end of the chunk. The caller (`pollOutput`) threads `toolKind` back in as the
+ * next poll's `incomingKind` so a slow command's orphan output is fenced (B2).
+ */
+export declare function stripTuiElementsWithContext(text: string, incomingKind?: ToolResultKind | null): {
+    text: string;
+    toolKind: ToolResultKind | null;
+};
+/**
+ * @description Strip Claude TUI chrome and fence tool-result bodies (B2),
+ * returning just the cleaned text. Thin wrapper over
+ * {@link stripTuiElementsWithContext} for call sites (and tests) that don't
+ * thread the cross-poll tool kind.
+ */
+export declare function stripTuiElements(text: string, incomingKind?: ToolResultKind | null): string;
+/**
+ * @description Turn an absolute workDir into Claude's transcript-folder slug.
+ *
+ * Claude stores per-project transcripts under
+ * `~/.claude/projects/<slug>/<sessionUuid>.jsonl`, where the slug is the
+ * absolute path with every non-alphanumeric character replaced by `-`
+ * (e.g. `/home/user/src/telegramCode` → `-home-user-src-telegramCode`).
+ *
+ * The slug encoding is undocumented and could drift across Claude versions,
+ * so it is used only to *locate* the candidate folder — the authoritative
+ * correctness gate is the `recordedCwd === workDir` filter in
+ * {@link listClaudeSessionsForWorkDir}.
+ */
+export declare function getClaudeProjectSlug(workDir: string): string;
+/**
+ * @description Root of Claude's on-disk transcript store
+ * (`~/.claude/projects`). Single source for every path built from it —
+ * session listing, resume-context reads, and the sub-agent transcript scan.
+ */
+export declare function getClaudeProjectsRoot(): string;
+/**
+ * @description Absolute path of ONE session's transcript
+ * (`<projectsRoot>/<slug>/<sessionId>.jsonl`).
+ *
+ * Single source for the layout: both Claude backends resolve it for the
+ * watermark advance, the runtime-info read, the resume-context turns, and the
+ * reattach recap — a hand-built copy in any of them would silently read nothing
+ * if the layout ever drifts.
+ */
+export declare function getClaudeTranscriptPath(workDir: string, sessionId: string): string;
+/**
+ * @description Read the last `limit` conversational turns (user/assistant
+ * messages with renderable text, oldest→newest) from a Claude `.jsonl`
+ * transcript, for the resume context block.
+ *
+ * Exported and pure (filesystem-only) so it is unit-testable against a temp
+ * `.jsonl`. Streams the whole file via {@link parseClaudeTurnLine}, keeping only
+ * the last `limit` in a rolling window so a huge transcript stays cheap.
+ * Tolerates a half-written trailing line; a missing/unreadable file → `[]`.
+ */
+export declare function readRecentClaudeTurns(filePath: string, limit: number): RecentTurn[];
+/**
+ * @description Combined transcript read for the silent-reattach recap: ONE
+ * `fs.readFileSync` yields BOTH the missed-message count and the recap turn
+ * body, so the transcript is not read twice.
+ *
+ * - `missedCount` — renderable `type:'assistant'` turns appended AFTER byte
+ *   `offset` (the seen-watermark = transcript size at the last turn end), counted
+ *   over the `[offset, EOF)` byte tail. A torn leading line (offset mid-record)
+ *   fails to parse and is skipped. `offset >= size` → `0` (nothing appended /
+ *   transcript truncated or rewritten smaller).
+ * - `turns` — the last `limit` renderable turns of the WHOLE session (NOT just
+ *   the missed region), identical to {@link readRecentClaudeTurns}.
+ * - `headOffset` — the transcript's CURRENT byte size (`buffer.length`), i.e.
+ *   the watermark value meaning "everything currently on disk is accounted for".
+ *   The reattach recap advances the persisted watermark to it for idempotency.
+ *   Absent on an unreadable file (head unknown → the caller omits the watermark).
+ *
+ * Exported and pure (filesystem-only) so it is unit-testable. `fs.readFileSync`
+ * reads the whole file in one call (it handles short reads internally), so a
+ * large `[offset, EOF)` tail never loses its last lines to a partial `read` —
+ * the silent undercount a manual `Buffer.alloc` + `fs.readSync` would hit on
+ * exactly the long-downtime case this feature targets. A missing/unreadable
+ * file → `{ missedCount: 0, turns: [] }` (no `headOffset`).
+ */
+export declare function readClaudeReattachTranscript(filePath: string, offset: number, limit: number): {
+    missedCount: number;
+    turns: RecentTurn[];
+    headOffset?: number;
+};
+/**
+ * @description List resumable Claude sessions for a workDir by reading the
+ * real `~/.claude/projects/<slug>/*.jsonl` transcripts.
+ *
+ * Exported and pure (filesystem-only, no tmux/adapter boot) so it can be
+ * unit-tested against a temp `projectsRoot`. Steps:
+ *
+ *   1. Resolve `<projectsRoot>/<slug>`; if missing → `[]`.
+ *   2. Take the {@link sessionsParseLimit} most-recently-modified `.jsonl`.
+ *   3. Parse each; KEEP only files whose recorded cwd === `workDir`
+ *      (the load-bearing correctness gate — slug collisions / version drift).
+ *   4. id = filename stem, MUST pass {@link checkIsValidUuid} (else skip).
+ *   5. title = summaryTitle ?? firstMeaningfulPrompt ?? id (trimmed, capped).
+ *      `summaryTitle` is legacy (current Claude no longer writes it); the
+ *      primary source is the first REAL prompt topic
+ *      ({@link getSessionTitleCandidate}) — preamble/marker stripped, tooling
+ *      noise skipped — NOT the last (often noise) prompt. A session with no
+ *      meaningful prompt (all turns were command echoes / noise) falls back to
+ *      the bare id. updatedAt = file mtime; createdAt = first timestamp ?? mtime.
+ *
+ * Result is newest-first by mtime.
+ */
+export declare function listClaudeSessionsForWorkDir(projectsRoot: string, workDir: string): AgentSession[];
+/**
+ * @description Whether `input` is a bare slash command (matches
+ * {@link BARE_SLASH_COMMAND_RE} after trimming). Exported so the
+ * popup-settle decision is unit-testable without a live tmux session.
+ */
+export declare function checkIsBareSlashCommand(input: string): boolean;
+/**
+ * @description Whether Claude is mid-turn, judged from a captured pane. A
+ * selector/permission prompt shows `Esc to cancel`, NOT `esc to interrupt`, so
+ * it reads as idle here (correct — we only wait out a running turn). Only the
+ * footer tail is inspected ({@link CLAUDE_BUSY_FOOTER_TAIL_LINES}) and the hint
+ * must carry footer chrome ({@link CLAUDE_BUSY_FOOTER_RE}), so scrollback prose
+ * mentioning the phrase can't false-positive. Exported so the busy detection is
+ * unit-testable without a live tmux session.
+ */
+export declare function checkIsClaudeBusy(paneText: string): boolean;
+/**
+ * @description Sync, in-memory "is this session mid-turn?" decision for the
+ * scheduler's wait-for-idle loop ({@link AgentAdapter.checkIsBusy}). Reuses the
+ * SAME pane predicate {@link interruptAndWaitIdle} polls
+ * ({@link checkIsClaudeBusy} on the `esc to interrupt` footer), evaluated
+ * against the session's last CLEANED pane content instead of a fresh `tmux`
+ * call — so it stays synchronous and adds no tmux load. The cleaned text is
+ * load-bearing: the raw `-e` capture carries ANSI/SGR runs that can split the
+ * footer marker mid-word and make the regex miss (the predicate's other
+ * callers read plain no-`-e` captures for the same reason). A dead/missing
+ * session is never busy. Exported pure so the gate is unit-testable without a
+ * live session.
+ */
+export declare function checkIsClaudeSessionBusy(args: {
+    isActive: boolean;
+    lastContent: string;
+}): boolean;
+/**
+ * @description Whether a cleaned output frame is nothing but the TUI input box
+ * echoing typed text (`❯ <draft>`). The poll can catch the input row between
+ * the literal-text keystrokes and the deferred submit Enter (B5 window), and
+ * that draft echo is pure noise in Telegram — the user already sees their own
+ * message (B7).
+ *
+ * A frame is an echo when its FIRST non-empty line starts with `❯` AND no line
+ * carries a content marker (`●`, `⎿`, or a ``` ``` ``` fence). The old
+ * predicate required EVERY line to start with `❯`, but a long draft wraps in
+ * the input box so only the first row carries `❯` and the continuation rows are
+ * plain — those frames leaked into the topic (B7b). Anchoring on the first line
+ * + a content-marker veto keeps a `❯` inside real tool output (e.g. a pane
+ * capture printed by a Bash command) classified as content, not an echo.
+ *
+ * MAINTENANCE — Claude Code's TUI rendering drifts between versions, back and
+ * forth (the prompt glyph, the echo indentation, the content markers — e.g. the
+ * `●`→`⏺` bullet change noted in `utils/claudeScrapeShapes.ts`). This detector
+ * must tolerate ALL known formatting variants, not assume the current one: when
+ * an echo starts leaking into the topic, WIDEN the predicate to also cover the
+ * new shape (keep the old variants), don't swap one shape for another.
+ */
+export declare function checkIsInputEchoFrame(frameText: string): boolean;
+/**
+ * @description CONTENT-based echo gate (S1), complementing the shape-only
+ * {@link checkIsInputEchoFrame}. The bot types the user's prompt into the Claude
+ * TUI and Claude echoes it back in the pane; when that echo carries NO `❯`
+ * (a wrapped continuation row, the `[Telegram thread context]` preamble, or the
+ * tail of a long voice transcript) the shape gate misses it and it leaks into
+ * the topic as a ghost "bot message" (live 2026-06-28).
+ *
+ * A cleaned frame is the user's own echo when EITHER:
+ *  - it carries the deterministic thread-context preamble signature (the
+ *    `[Telegram thread context]` header — the agent never emits that itself), OR
+ *  - its normalized text is a contiguous slice of the normalized forwarded text
+ *    (a prefix, suffix, or interior run) of at least
+ *    {@link claudeEchoMinMatchChars} — i.e. the whole frame is nothing but a
+ *    chunk of what we just typed.
+ *
+ * The containment DIRECTION is load-bearing: the FRAME must be contained in the
+ * forwarded text, never the reverse — so a genuine reply that QUOTES part of the
+ * prompt and then adds an answer is NOT a substring of the prompt and is kept.
+ * The caller additionally gates this on a short post-forward time window.
+ *
+ * WIDENED (live 2026-07-06): the poll can catch the just-submitted
+ * echo's wrapped row GLUED to the new turn's first spinner tick in ONE frame
+ * (`<echo row>\n\n* Twisting…`). The glued chrome is not part of the forwarded
+ * text, so whole-frame containment failed and the row leaked as a permanent
+ * message. When the whole frame misses, transient-shaped lines (per-line
+ * {@link checkIsStatusOutput}) are dropped and the remaining content is
+ * re-tested — only a frame whose real content is nothing but a slice of the
+ * forwarded text is suppressed, so an answer glued to a spinner is still kept.
+ *
+ * Pure + exported so every observed echo variant is unit-testable. MAINTENANCE:
+ * like {@link checkIsInputEchoFrame}, WIDEN (never swap) when a new echo shape
+ * leaks — keep the old variants.
+ */
+export declare function checkIsForwardedEcho(frameText: string, forwardedText: string): boolean;
+/**
+ * @description Whether a captured pane looks like the typed prompt is still
+ * sitting UNSUBMITTED in Claude's live input box (the B5 paste-race symptom).
+ *
+ * Submission predicate (the load-bearing "did it submit?" check): a prompt has
+ * submitted iff EITHER Claude went busy (`esc to interrupt` in the footer — the
+ * turn started) OR the live input box at the bottom is empty (`❯ ` with no
+ * text — Claude consumed the input and is idle again, e.g. a fast/no-op turn).
+ * It looks UNSUBMITTED only when Claude is idle AND the last `❯`-led input row
+ * still carries the typed text. We deliberately key on the LAST `❯` line: a
+ * SUBMITTED prompt echoes as a `❯ <text>` user-turn block in scrollback, but
+ * the live input box below it is the final `❯` line and is empty — so matching
+ * the last one ignores the harmless scrollback echo.
+ *
+ * Tradeoff (locked in plan B5): if a single verification capture is ambiguous
+ * we err toward reporting unsubmitted and let the caller retry Enter once — a
+ * duplicate Enter on an already-submitted prompt is a harmless no-op in the
+ * Claude TUI (submits an empty input = ignored), whereas a missed submit silently
+ * loses the user's message.
+ *
+ * Exported so the predicate is unit-testable without a live tmux session.
+ */
+export declare function checkLooksUnsubmitted(paneText: string, typedText: string): boolean;
+/**
+ * @description Find the ONE line in a scraped pane that is a terminal
+ * provider / auth error, or `null` if none. `content` is `cleanOutput(raw)`,
+ * which RETAINS the `⎿` result marker. Three accepted shapes:
+ *   a) `API Error: …` at line start — the classic provider row
+ *      (`API Error: … (not your usage limit) · Rate limited`).
+ *   b) a `⎿` result row that also contains `API Error:`
+ *      (`⎿  overloaded · API Error: 429` — the render the old start-anchored gate
+ *      MISSED, which is why a `⎿`-prefixed rate-limit never auto-retried).
+ *   c) a `⎿` result row whose content LEADS with an auth phrase
+ *      (`⎿  Not logged in · Please run /login` — the logged-out render).
+ *   d) a row whose content LEADS with a usage/session-limit phrase AND reads like
+ *      an error ({@link CLAUDE_LIMIT_ROW_SHAPE_RE}) — `You've hit your session
+ *      limit · resets 10:50pm (UTC)` carries no `API Error:` marker at all, so
+ *      (a)–(c) all missed it.
+ * FALSE-POSITIVE GUARD: prose never starts a line with the `⎿` glyph nor with
+ * `API Error:`. But TOOL results (Bash/Read/Grep output) ARE rendered by the TUI
+ * under a `⎿` marker, so a result row that QUOTES an auth phrase deeper in the
+ * line (the agent grepping the bot's own logs/source, or a `gh`/`npm` "not
+ * logged in" line) would fire case (c) if we matched the phrase anywhere. So (c)
+ * — and (d), for the same reason — anchor the phrase to the row START: a real
+ * error row leads with it; a quote embeds it after other text (live 2026-07-03).
+ * The returned line is fed VERBATIM to
+ * {@link classifyAgentApiError}. Exported for unit testing without a live tmux
+ * pane.
+ */
+export declare function getClaudeAgentErrorLine(content: string): string | null;
+/**
+ * @description Whether a captured pane shows the Claude TUI has finished
+ * booting and is ready to accept a typed slash command (S7 readiness signal).
+ *
+ * Ready means: the live input box `❯` is on screen AND no boot-time lifecycle
+ * gate is still up — neither the "Press Enter to continue" / login gate nor the
+ * bypass-permissions warning, both of which `handleAutoLifecycle` dismisses
+ * over the next polls. We do NOT require idle: a fresh spawn is idle, and
+ * gating on "not busy" would only delay the re-apply past the box first
+ * appearing. Keeping the predicate to "input box up, no lifecycle gate" matches
+ * the single observable moment the box first accepts keys. Exported for unit
+ * testing without a live tmux pane.
+ */
+export declare function checkIsClaudePromptReady(paneText: string): boolean;
+/**
+ * @description Pure decision for the seen-watermark advance: persist the
+ * transcript's current EOF as "relayed live up to here" whenever the input box
+ * is ready AND the file grew past the last persisted offset — busy or idle.
+ *
+ * S7 dropped the old `!isBusy` gate. A live Claude adapter relays the pane on
+ * EVERY poll, so EOF-on-growth already means "shown up to here" mid-turn, not
+ * only at turn end; the old idle-only advance left the watermark at the previous
+ * turn end all through a multi-message turn, so a mid-turn restart re-counted
+ * every already-relayed message as a false "missed N" (live 2026-07-04). The
+ * `isReady` gate stays (don't advance before the box is up / while a boot or
+ * lifecycle gate is on screen — that isn't a settled relay), and the growth
+ * guard (`eof > lastOffset`) stays so idle metadata rewrites cost no write and a
+ * smaller rewrite never rewinds the monotonic anchor. `isBusy` is accepted so
+ * the caller passes the poll's busy flag and the truth table documents that busy
+ * no longer blocks; it is intentionally unread.
+ *
+ * Exported so the truth table is unit-testable without a live tmux;
+ * {@link ClaudeCliAdapter.advanceClaudeWatermarkIfGrown} is the thin fs+writer
+ * wrapper. Callers pass `lastOffset = session.lastWatermarkOffset ?? -1` so a
+ * never-advanced session writes on its first ready poll.
+ */
+export declare function checkShouldAdvanceWatermark(args: {
+    isBusy: boolean;
+    isReady: boolean;
+    eof: number;
+    lastOffset: number;
+}): boolean;
+/**
+ * @description Whether Claude is doing work that must NOT be interrupted: a
+ * running sub-agent (Escape would kill the child) or an in-flight compaction
+ * (Escape would abort it and lose the summary). In these states the caller
+ * forwards the prompt without Escape so it queues behind the current turn and
+ * runs once the work finishes. Exported for unit testing without a live tmux.
+ */
+export declare function checkIsClaudeUninterruptible(paneText: string): boolean;
+export { getNewPaneContent, type NewPaneContent };
+/**
+ * @description Input snapshot of one resume-seeding poll, fed to
+ * {@link getResumeSeedDecision}.
+ */
+export interface ResumeSeedState {
+    /** Cleaned pane content captured on THIS poll. */
+    content: string;
+    /** Cleaned pane content captured on the PREVIOUS poll (empty before the first). */
+    prevContent: string;
+    /** Number of polls already spent in seeding mode (0 on the first seeding poll). */
+    polls: number;
+}
+/**
+ * @description Decide whether to stay in resume flood-suppression mode or exit.
+ *
+ * While `keepSeeding` is true, `pollOutput` advances the baseline but emits no
+ * conversation text, so the entire restored transcript Claude repaints on
+ * `--resume` is swallowed instead of dumped into the topic. We exit (and let
+ * the NEXT poll's diff be genuine new output) when either:
+ *
+ *   - the pane is non-empty AND unchanged across two consecutive polls (the
+ *     restored transcript finished painting — the common case), or
+ *   - the hard cap {@link resumeSeedMaxPolls} is hit (paint stuttered forever;
+ *     force-exit so a session can never be wedged into permanent silence).
+ *
+ * Pure + exported so the swallow → exit-on-stable → emit-new transition is
+ * unit-testable without a live tmux pane.
+ */
+export declare function getResumeSeedDecision(state: ResumeSeedState): {
+    keepSeeding: boolean;
+};
+export declare class ClaudeCliAdapter extends EventEmitter implements AgentAdapter {
+    readonly name = "claude";
+    readonly label = "Claude Code";
+    readonly outputsDeltas = true;
+    readonly selfGreetsOnStart = true;
+    /**
+     * Map of serialised `SessionKey` (`"<chatId>:<threadId>"`) → live session.
+     * Keyed by string rather than `SessionKey` object so map lookups work — JS
+     * Map compares object identity, not structural equality.
+     */
+    private sessions;
+    /**
+     * Per-thread display-prefs reader, injected by the bot at boot via
+     * `createAdapter.registerDisplayPrefsReader` (S4; same idiom as the OpenCode
+     * adapter). Consulted on the poll hot path: the relay branches each chunk's
+     * tool / panel segments on `toolResults` (S4), and the transcript scan
+     * fast-forwards (non-`full` `subagent`) or streams (`full`). `null` until
+     * wired → reads fall back to all-fields-`minimal`.
+     */
+    private displayPrefsReader;
+    /** @description Inject the per-thread display-prefs reader (see the field's JSDoc). */
+    setDisplayPrefsReader(reader: DisplayPrefsReader): void;
+    /** Per-thread locale reader, injected at boot via `createAdapter.registerThreadLocaleReader`. */
+    private threadLocaleReader;
+    /** @description Inject the per-thread locale reader (for adapter-side `t(...)` calls). */
+    setThreadLocaleReader(reader: ThreadLocaleReader): void;
+    /** @description Run `fn` inside the thread's locale context so `t(...)` resolves correctly. */
+    private tl;
+    /**
+     * Per-thread seen-watermark writer, injected by the bot at boot via
+     * `createAdapter.registerSeenWatermarkWriter`. Called on every idle+ready poll
+     * whose transcript EOF grew past the last persisted offset (via
+     * {@link ClaudeCliAdapter.advanceClaudeWatermarkIfGrown}) to persist the new
+     * EOF. `null` until wired → {@link advanceSeenWatermark} is a no-op.
+     */
+    private seenWatermarkWriter;
+    /** @description Inject the per-thread seen-watermark writer (see the field's JSDoc). */
+    setSeenWatermarkWriter(writer: SeenWatermarkWriter): void;
+    /** @description Advance the persisted seen-watermark for `key` (no-op until the
+     * writer is wired). */
+    private advanceSeenWatermark;
+    /**
+     * @description Advance the seen-watermark to the transcript's current EOF when
+     * the input box is ready and the file grew since the last write (S7) — the
+     * fs+writer wrapper around {@link checkShouldAdvanceWatermark}. Called every
+     * non-seeding poll with the poll's `isBusy` / `isReady`; it early-returns only
+     * on a NOT-ready poll BEFORE the `fs.stat` (a boot / lifecycle-gate frame isn't
+     * a settled relay). S7 dropped the busy early-return so a BUSY-but-ready poll
+     * mid-turn advances too — the pane is relayed every poll, so tracking EOF as it
+     * grows keeps the watermark at "relayed up to here" instead of stranding it at
+     * the previous turn end (the mid-turn false-"missed N" fix). It still writes
+     * only when EOF actually grew — so idle metadata churn (Claude rewrites
+     * `last-prompt`/`mode`/… for hours) costs no more than one bounded write per
+     * real growth, and a smaller rewrite never rewinds the in-memory anchor
+     * (monotonic). Best-effort — a transcript not yet on disk (UUID just born)
+     * leaves the watermark where it was, the next poll re-tries. The path resolves
+     * the same way {@link getRecentTurns} / {@link getReattachRecap} do.
+     */
+    private advanceClaudeWatermarkIfGrown;
+    /** @description Resolve the thread's full display prefs, defaulting every
+     * field to `minimal` for any read before the bot wires the reader at boot. */
+    private getDisplayPrefs;
+    /** @description Resolve the thread's `/subagent` mode (consulted by the
+     * transcript-tail scan), via the full prefs reader. */
+    private getSubagentMode;
+    private createSession;
+    private enqueueTmux;
+    private enqueueTmuxBestEffort;
+    private stopSessionInternal;
+    /**
+     * @description Schedule the next `pollOutput` for a session. Audit S9 /
+     * #37: replaces `setInterval` so a slow `tmux capture-pane` cannot
+     * cause overlapping invocations. The handle is stored back on
+     * `session.pollTimer` so `stopSession` can cancel the next tick.
+     */
+    private schedulePoll;
+    /**
+     * @description Per-poll-tick scan of the session's on-disk sub-agent
+     * transcripts (`/subagent` on Claude, plan 2026-06-11 S3). Claude writes
+     * each Task-tool child transcript to
+     * `<projectsRoot>/<slug>/<claudeSessionId>/subagents/agent-<agentId>.jsonl`;
+     * the pure `claudeSubagentTail` helpers own all decisions — first-scan EOF
+     * seeding (no backlog replay on resume/adopt), compact-mode fast-forward
+     * without reading, and assistant-text-block extraction (child thinking /
+     * tool_use never rendered). In `full` mode every appended text block is
+     * emitted as a marked output (`meta.isSubagent`) which the bot renders as a
+     * standalone "🤖 ⤷" message outside the parent's continuation chain.
+     *
+     * A missing dir (`ENOENT` — no sub-agent yet, or an older claude version)
+     * short-circuits cheaply but still runs the empty scan, so the first-scan
+     * flag flips and a transcript created later streams from byte 0. Any other
+     * error is logged and swallowed here — this method must never reject, or
+     * the rejection would escape `schedulePoll`'s void'd poll chain.
+     */
+    private scanSubagentTranscripts;
+    /**
+     * @description Snap a session's poll cadence back to base (S2). Called on
+     * every explicit write (keystroke / signal) and on session start/resume so a
+     * fresh prompt never waits up to {@link maxPollIntervalMs} for the next
+     * capture — user-visible latency after a write must stay at base cadence.
+     *
+     * If a poll timer is already pending we re-arm it at the base delay so the
+     * backed-off idle timer can't keep the next capture far in the future. The
+     * existing {@link ClaudeSession.isPolling} guard is respected: a poll already
+     * in flight will reschedule itself from the (now reset) delay, so we never
+     * double-poll.
+     */
+    private resetPollCadence;
+    startSession(key: SessionKey, workDir: string, args?: string, sessionId?: string): Promise<void>;
+    stopSession(key: SessionKey): void;
+    checkIsActive(key: SessionKey): boolean;
+    checkIsBusy(key: SessionKey): boolean;
+    getRuntimeInfo(key: SessionKey): Promise<AgentRuntimeInfo>;
+    /**
+     * @description Ms since the TUI pane last actually changed (raw `capture-pane`
+     * differed), or `null` when there is no live session for this thread. Feeds
+     * the bot's S2 pane-static idle net: a genuinely working agent repaints the
+     * pane every second, so a large value means the agent is idle even if the
+     * footer busy signal is stuck. `null` is never treated as idle.
+     */
+    getMsSincePaneChange(key: SessionKey): number | null;
+    sendInput(key: SessionKey, input: string, options?: SendInputOptions): void;
+    /**
+     * @description Post-Enter verification for a plain prompt (B5). After a short
+     * settle, capture the pane through the session queue and — if the prompt still
+     * looks unsubmitted (see {@link checkLooksUnsubmitted}) — re-send Enter exactly
+     * ONCE. No further retries: a duplicate Enter on an already-submitted prompt is
+     * a harmless no-op, but an unbounded retry loop on a genuinely-stuck pane would
+     * spam keystrokes. Same staleness guards as the deferred Enter.
+     */
+    private scheduleEnterVerification;
+    sendSignal(key: SessionKey, signal: string): void;
+    sendEnter(key: SessionKey): void;
+    sendArrow(key: SessionKey, direction: 'Up' | 'Down'): void;
+    sendTab(key: SessionKey): void;
+    /**
+     * @description S4: auto-dismiss the native Claude session-feedback survey by
+     * sending a single Escape into the pane (Escape clears the survey overlay the
+     * same way it dismisses a selector). Fire-and-forget through the session queue,
+     * like {@link sendEscape}; the caller's {@link checkShouldDismissSurvey}
+     * signature dedup guarantees it fires once per appearance. Never surfaced to
+     * the topic — the survey must not occupy input / disrupt the scrape.
+     */
+    private dismissClaudeSurvey;
+    sendEscape(key: SessionKey): void;
+    /**
+     * @description Interrupt the current turn, then wait until Claude is
+     * actually idle before resolving, so the caller can type a fresh prompt
+     * without it being queued behind the running turn.
+     *
+     * Sends a single Escape — which both cancels an on-screen selector AND
+     * breaks Claude out of the "busy" state — then polls the pane footer until
+     * the `esc to interrupt` hint clears. A fixed post-Escape delay was
+     * unreliable: heavy extended-thinking turns take longer than the old 120 ms
+     * to tear down, so the prompt landed while Claude was still busy and got
+     * queued (the "voice message arrives before the interrupt, then the agent
+     * waits" bug). On timeout we forward anyway rather than drop the message.
+     *
+     * Exception: if Claude is running a sub-agent or compacting context, we do
+     * NOT interrupt — Escape would kill the child / abort the compaction. We
+     * return without Escape so the caller's prompt queues behind the current
+     * turn and runs once that work finishes.
+     */
+    interruptAndWaitIdle(key: SessionKey): Promise<void>;
+    /**
+     * @description Whether a selector is currently on screen. Backed by the same
+     * `lastQuestionSignature` the output pump sets when it scrapes a question
+     * block (see the `extractClaudeQuestion` call in the poll loop) — non-empty
+     * means a question is being shown and awaiting an answer.
+     */
+    isQuestionPending(key: SessionKey): boolean;
+    /**
+     * @description Whether Claude's `/login` OAuth "paste the code" box is on
+     * screen right now, read live off the last captured pane ({@link checkIsClaudeLoginPaste}).
+     * No signature/de-dup is needed — nothing is emitted; this only answers
+     * "should the next text reply be typed verbatim into the paste box?" when a
+     * message arrives, so the bot skips the prompt path (Escape + preamble) that
+     * would otherwise cancel the login and corrupt the code.
+     */
+    isLoginPastePending(key: SessionKey): boolean;
+    /**
+     * @description For Claude CLI, model switching is done via the /model slash command.
+     * Sends "/model <modelId>" as input to the tmux session. Returns `null`
+     * on success (best-effort: claude doesn't ack the change synchronously).
+     * Audit S10 / #39: unified signature with OpenCode adapter.
+     *
+     * Unlike OpenCode, Claude has NO model-pref persistence — model switching is
+     * a TUI keystroke with no on-disk pref to replay at next start. So with no
+     * active session there is nothing to do but refuse, otherwise `sendInput`
+     * silently no-ops and the caller would report a false "model set" success
+     * (reachable today via the ungated numeric-pick path).
+     */
+    setModel(key: SessionKey, modelId: string): Promise<string | null>;
+    getCurrentModel(_key: SessionKey): string | null;
+    /**
+     * @description Set the reasoning effort for this thread by typing claude's
+     * native `/effort <level>` slash command into the running TUI.
+     *
+     * Plan 2026-05-30-effort-command / S3, D2/D6:
+     *
+     * - **Validation** is against the canonical Claude set (`getClaudeAvailableLevels`),
+     *   not per-model: the adapter can't read claude's live model after a
+     *   `/model` switch (`getCurrentModel` returns `null`), so we trust claude
+     *   to clamp an unsupported level for the actual model down to its nearest
+     *   supported one. Caller already filtered against the same canonical list
+     *   when building the picker.
+     * - **Apply** is best-effort via {@link sendInput} (the keystroke path used
+     *   by `setModel`). Returns `null` immediately — claude's TUI doesn't
+     *   acknowledge the change synchronously and we don't poll-and-wait for it.
+     * - **Persist** to the per-thread prefs file so the banner / `/effort`
+     *   picker survives a bot restart (claude's own settings.json is global).
+     *
+     * Returns a short notice instead of `null` when the session isn't running
+     * (we still persist the choice so the next /claude picks it up in the
+     * banner; live apply happens once the agent actually exists).
+     */
+    setEffort(key: SessionKey, level: string): Promise<string | null>;
+    /**
+     * @description Last bot-set effort for this thread, or `null` if none.
+     *
+     * Reads from the on-disk prefs file (not an in-memory cache): the file is
+     * tiny and the read happens only on menu / banner refresh paths, so a
+     * cache would just be drift surface. Whatever claude itself stores in
+     * its global `settings.json` is invisible to us by design (D2).
+     */
+    getEffort(key: SessionKey): string | null;
+    /**
+     * @description ARM the thread's stored `/effort` choice for re-apply on a
+     * FRESH TUI spawn (S7) — deferred, not typed immediately. claude persists
+     * effort GLOBALLY in its own settings.json, so a fresh `startSession` /
+     * `resumeSession` would otherwise inherit the last globally-set level —
+     * possibly chosen in another topic.
+     *
+     * Timing is the whole point: a fresh tmux session returns the instant
+     * `new-session` succeeds, while the claude TUI is still painting its boot
+     * banner — typing into it then interleaves keystrokes with the paint and the
+     * command sits unsubmitted (live bug 2026-06-05). So we do NOT type here; we
+     * stash the level on `session.pendingEffortReapply` and let the poll loop
+     * consume it the FIRST time the pane shows a ready input box
+     * ({@link checkIsClaudePromptReady}). That readiness moment is strictly after
+     * the banner paints and strictly before the box can echo a buffered prompt,
+     * giving the required ordering (effort BEFORE buffered prompts) via the same
+     * serial tmux queue.
+     *
+     * Called at the END of `startSession` / `resumeSession`. NOT called from
+     * `adoptExistingTmuxSession` — that claude process survived the restart with
+     * its in-TUI effort intact and may be mid-turn, so re-applying would be both
+     * unnecessary and risk interleaving with a running stream.
+     *
+     * No stored pref → the bot's default (`defaultEffortLevel` = xhigh) is armed
+     * instead of claude's own default, so a no-pref spawn types `/effort xhigh`
+     * (claude clamps per model — same as a manual `/effort` or an explicit pref).
+     * An explicit per-thread pref still wins and is armed verbatim.
+     */
+    private applyStoredEffortOnSpawn;
+    /**
+     * @description S7 consumption point: once the poll loop sees the TUI input
+     * box is up and no boot gate is left, type the armed `/effort <level>` ONCE
+     * and clear the pending flag (one-shot, can't fire twice). Reuses the exact
+     * keystroke path a manual `/effort` uses ({@link sendInput} with its
+     * bare-slash deferred-Enter handling) so there is no duplicate keystroke
+     * logic. Enqueuing onto the session's serial tmux queue at this ready moment
+     * guarantees the keystroke lands in a usable input box (not the boot paint)
+     * and ahead of any buffered prompt the bot replays onto the same queue.
+     */
+    private consumePendingEffortReapply;
+    /**
+     * @description Effort levels offered by the `/effort` picker for Claude.
+     *
+     * Returns the canonical set unconditionally (plan D2). The `key` argument
+     * is accepted for interface symmetry with OpenCode (whose set depends on
+     * the per-thread current model) but is intentionally unused here.
+     */
+    getAvailableEffortLevels(_key: SessionKey): Promise<string[]>;
+    getFullOutput(key: SessionKey, lines?: number): string | null;
+    /**
+     * @description Expose the Claude `--session-id` UUID for a live session.
+     * The bot calls this right after `startSession()` so the UUID can be
+     * persisted in state.json and reused on later resumes (plan §13.1, D14).
+     */
+    getClaudeSessionId(key: SessionKey): string | null;
+    getSessions(_key: SessionKey, workDir: string): Promise<AgentSession[]>;
+    /**
+     * @description Read the last `limit` conversational turns of a resumable
+     * Claude session for the resume context block. Resolves the same
+     * `~/.claude/projects/<slug>/<sessionId>.jsonl` path the session listing uses
+     * (`key` is unused — Claude scopes transcripts by folder, not by thread) and
+     * delegates to the pure {@link readRecentClaudeTurns}. A missing transcript
+     * (unknown / pruned UUID) yields `[]`, so the caller posts no context block.
+     */
+    getRecentTurns(_key: SessionKey, workDir: string, sessionId: string, limit: number): Promise<RecentTurn[]>;
+    /**
+     * @description Assemble the silent-reattach recap for Claude from the on-disk
+     * transcript via ONE {@link readClaudeReattachTranscript} read: the
+     * missed-message count is the assistant turns appended after the watermark
+     * byte offset, the body is the last {@link resumeContextTurnLimit} turns, and
+     * `isActive` is the best-effort in-memory busy flag (the just-adopted session
+     * seeds `lastContent` from the current pane, so an `esc to interrupt` footer
+     * reads as still-working). The offset is trusted only when the watermark's
+     * `sessionId` matches the session being recapped — a stale watermark from a
+     * different session (`/new`, `/sessions` resume keep the agent row) is treated
+     * as unknown. A `null`/mismatched/offset-less watermark yields
+     * `isWatermarkKnown: false` and `missedCount: 0` (the fallback recap), while
+     * the body still shows the last turns.
+     */
+    getReattachRecap(key: SessionKey, workDir: string, sessionId: string, watermark: SeenWatermark | null): Promise<ReattachRecap>;
+    /**
+     * @description Resume a Claude session by UUID.
+     *
+     * Two fixes vs. the legacy implementation:
+     *
+     * 1. **Required `workDir`.** The old `resumeSession` fell back to
+     *    `process.env.WORK_DIR || '/workspace'`, which is wrong as soon as the
+     *    bot manages multiple folders. The bot now passes the correct workDir
+     *    from the thread binding.
+     *
+     * 2. **Use `--resume <uuid>` instead of `--resume` with no argument.** The
+     *    no-arg form opens an interactive picker that can't be driven from a
+     *    headless tmux pane, which manifested as a silent hang (see plan
+     *    §13.1, fix to claudeCliAdapter.ts:455). If Claude can't find the UUID
+     *    (history pruned, different machine), it just starts a new session;
+     *    we surface that to the user (T8 in plan §16.3).
+     */
+    resumeSession(key: SessionKey, workDir: string, sessionId: string, options?: ResumeSessionOptions): Promise<void>;
+    /**
+     * @description Pick up tmux sessions that outlived the bot process.
+     *
+     * Called by `bot.ts` on startup, BEFORE `bot.launch()`. Scans
+     * `tmux list-sessions` for names matching our `claude-<chatId>-<threadId>`
+     * convention. For each match, returns the parsed key + tmux session name —
+     * the bot then decides which ones to re-adopt (must have a live binding in
+     * state.json) and which are orphans to garbage-collect (plan §10.2 / §13.19, E1).
+     *
+     * This method does NOT itself adopt sessions: it has no knowledge of state.json
+     * or which sessions are still bound. The actual re-attach is done by the bot
+     * calling {@link adoptExistingTmuxSession} for each key it wants to keep.
+     *
+     * Returns an empty array if tmux isn't installed or no matching sessions exist.
+     */
+    listExistingTmuxSessions(): Promise<Array<{
+        key: SessionKey;
+        sessionName: string;
+    }>>;
+    /**
+     * @description Recover the `--session-id <uuid>` flag from a live tmux
+     * session's start command.
+     *
+     * Used by the bot's reattach loop to reconcile state with reality when
+     * `state.agents[key]` is missing a `claudeSessionId` (or names a
+     * different adapter) but a `claude-<chatId>-<threadId>` tmux session is
+     * still running. Previously such cases were treated as orphans and the
+     * tmux session was killed, throwing away the user's live work.
+     *
+     * Implementation: read `pane_start_command` for the session's first
+     * pane and parse the UUID out via {@link parseClaudeSessionIdFromCommand}.
+     * `pane_start_command` survives across restarts because tmux keeps the
+     * original command line for the pane.
+     *
+     * Returns `null` if no UUID can be recovered (caller falls back to
+     * killing the session as an orphan).
+     */
+    recoverSessionIdFromTmux(sessionName: string): Promise<string | null>;
+    /**
+     * @description Adopt a tmux session that survived a bot restart.
+     *
+     * The bot calls this after `listExistingTmuxSessions()` for each
+     * `(key, sessionName)` pair it wants to keep alive. Restores the in-memory
+     * `ClaudeSession` and resumes polling so output flows back to Telegram.
+     *
+     * `workDir` and `claudeSessionId` come from state.json (the bot keeps a
+     * binding `(key → subdir, claudeSessionId)`). If we ever lose them, the
+     * caller should kill the tmux session as an orphan instead.
+     *
+     * Returns `true` on success, `false` if the tmux session disappeared between
+     * the `list` call and now (race with manual `tmux kill-session`).
+     */
+    adoptExistingTmuxSession(key: SessionKey, sessionName: string, workDir: string, claudeSessionId: string): Promise<boolean>;
+    /**
+     * @description Kill a tmux session by name without touching adapter state.
+     *
+     * The bot uses this on startup to garbage-collect orphan tmux sessions
+     * (`claude-<chatId>-<threadId>` names with no corresponding binding in
+     * state.json). See plan §10.2 / §13.19.
+     */
+    killOrphanTmuxSession(sessionName: string): Promise<void>;
+    static parseTmuxSessionName: typeof parseTmuxSessionName;
+    static buildTmuxSessionName: typeof buildTmuxSessionName;
+    private probeSessionAlive;
+    private pollOutput;
+    /**
+     * @description Emit a settled streaming table (S1) as ONE fenced `output`.
+     *
+     * Routes the held block through the SAME fence path as the inline table path
+     * ({@link stripTuiElementsWithContext} fences a sharp-corner table) so the
+     * `<pre>` rendering is byte-identical to today — only the TIMING/dedup change.
+     * Records the raw block in {@link RecentRelayWindow} in the PANE-line domain
+     * (pre-strip) so a later full repaint of the same table is suppressed by the
+     * existing re-render dedup, exactly like the normal permanent-output path.
+     * Emitted with `startsNewParagraph: true` — a table is its own visual block,
+     * so it must not glue onto preceding prose in the append/draft join.
+     */
+    private emitStabilizedTable;
+    /**
+     * @description Auto-handle the two lifecycle prompts Claude can show — the
+     * "Press Enter to continue" gate and the bypass-permissions warning — by
+     * issuing the matching keystrokes. Extracted from {@link pollOutput} so the
+     * resume-seeding path (which suppresses conversation TEXT) can still drive
+     * these prompts; suppression must hide chatter, not the lifecycle.
+     *
+     * Also the detection seam for a terminal provider error / logged-out row
+     * ({@link getClaudeAgentErrorLine}: `API Error: …`, `⎿ … · API Error: …`, or
+     * `⎿ … Please run /login`): when it first classifies, emit one `apiError`
+     * event — the trigger for the auto-retry (transient / usageLimit) OR the
+     * surfaced logged-out notice (auth). Detection scans the NEW pane delta only
+     * (never the full pane / arbitrary conversation text), so a recognized error
+     * row fires exactly once — when it first renders.
+     *
+     * A large new chunk (`newPart.length > 50`) means real conversation moved on,
+     * so the one-shot `handled*` guards are reset to re-arm for a later prompt.
+     */
+    private handleAutoLifecycle;
+    private checkNeedsAutoEnter;
+    private checkNeedsAutoAccept;
+}
+//# sourceMappingURL=claudeCliAdapter.d.ts.map