zidane 6.6.4 → 7.0.0

package/dist/index-DgdzXRPH.d.ts

@@ -0,0 +1,3590 @@
+import { B as McpCredentialStore, Cd as ProviderKey, Cl as ThemeSurfaces, Cu as StreamEvent, Eu as ProjectBrief, Gi as AgentHookMap, Gp as Provider, Hg as TurnUsage, Jc as SourcedScanPath, Ki as AgentHooks, Np as CacheBreakInfo, Qh as McpServerConfig, Rh as AgentStats, Sg as SessionTurn, Sl as ThemeSelect, Su as Settings, T_ as SessionStore, Vg as TurnFinishReason, Wi as Agent, Zh as JsonValue, ad as ModelChainEntry, bl as Theme, bu as Screen, eg as McpToolSchema, gu as EditPayload, if as InteractionResponse, kd as ProviderDescriptor, m_ as SkillConfig, mp as ContextSegment, mu as EditOutcome, qg as ToolDef, rf as InteractionRequest, v_ as SkillsConfig, vl as SyntaxStyles, x_ as Session, xl as ThemeColors, xu as SessionMeta, yp as ContextBreakdown, z as McpCredentialEntry, zh as AutoCompact } from "./index-B-FSaM3_.js";
+import { O as ResolvedConfig, _ as DiscoveredMcp, f as DiscoveredPlugin, it as KeyBindings, v as DiscoveryError, yt as Hint } from "./transcript-anchors-DXqWWGbq.js";
+import { P as ProviderUsageSnapshot, Rt as FileEntry, a as ActiveTodosState, ct as HunkResolution, dt as PreviewResult, h as TodoTally, p as TodoItem } from "./turn-operations-DKFYWP3O.js";
+import { H as ApprovalRequest, V as ApprovalDecision, tt as PromptTurnRef } from "./tool-formatters-DO56YBBw.js";
+import { Hookable } from "hookable";
+import { spawn } from "node:child_process";
+import { Dispatch, ReactNode, SetStateAction } from "react";
+import { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import { OAuthCredentials, OAuthDeviceCodeInfo, OAuthPrompt, OAuthPrompt as OAuthPrompt$1, OAuthSelectPrompt } from "@earendil-works/pi-ai/oauth";
+//#region src/tools/read-chat-turns.d.ts
+interface ChatTurnsReadToolOptions {
+  store: SessionStore;
+  getAllowedTokens: () => readonly string[];
+}
+declare function createChatTurnsReadTool(options: ChatTurnsReadToolOptions): ToolDef;
+declare function chatReferenceTokensForPrompt(prompt: string): string[];
+//#endregion
+//#region src/chat/agent-prompt.d.ts
+/**
+ * Agent system-prompt fragments — composable doctrine for built-in profiles.
+ *
+ * Each `const` below is one self-contained section of a system prompt. They
+ * exist as exports so SDK consumers can pick and choose: build a custom
+ * profile by spreading them in {@link buildBuildSystem} order, drop a fragment
+ * for a stricter / looser agent, or compose with project-specific prose.
+ *
+ * The fragments are deliberately byte-stable across sessions — every doctrine
+ * piece reads the same on every turn so the system-prompt cache breakpoint
+ * (anthropic ephemeral, `src/providers/anthropic.ts`) keeps hitting cache.
+ *
+ * Layout uses {@link SYSTEM_PROMPT_BOUNDARY} from `../system-prompt` to split
+ * the rendered prompt into:
+ *
+ *   ┌──────────────┐  cache_control: ephemeral
+ *   │ STATIC half  │  identity + doctrine + guidance + user instructions
+ *   ├──────────────┤  ← __ZIDANE_SYSTEM_PROMPT_BOUNDARY__
+ *   │ DYNAMIC half │  envSection(cwd / date / platform)
+ *   └──────────────┘  (no cache_control)
+ *
+ * Per-turn cwd / date / platform churn no longer invalidates the doctrine
+ * cache above. The TUI's `system:transform` hook rewrites only the dynamic
+ * half via `replaceDynamicSection`; the static prefix stays byte-identical
+ * for the lifetime of the run.
+ */
+/**
+ * Lead line — short, version-stable. The first sentence matches the key of
+ * Claude Code's identity prefix (models anchor faster on familiar shapes).
+ * The rest sets the register: token-earning sentences with byte-exact
+ * code ("small mouth, full brain"), and a hard rule that speed never
+ * widens scope (the leeroy-jenkins fix). Keep changes rare — each one
+ * costs a cache miss across active sessions.
+ */
+declare const IDENTITY_PREFIX = "You are zidane, a terminal-based coding agent that helps the user with software-engineering tasks. Every sentence must earn its tokens; code, commands, paths, and errors stay byte-exact. Small mouth, full brain. Move fast on the task given; speed never widens scope, the user owns scope.";
+interface EnvSectionOptions {
+  /**
+   * The agent's actual working directory — what `process.cwd()` reports
+   * and what its tool calls resolve relative paths against. Distinct
+   * from {@link EnvSectionOptions.projectRoot}, which carries the
+   * project anchor when the user spawned from a subdirectory.
+   */
+  cwd: string;
+  /**
+   * Project root (typically the git root). When set AND different from
+   * `cwd`, the rendered env block discloses both AND adds a path-
+   * convention note — file paths coming from the user's `@`-completion
+   * are project-root-relative, NOT cwd-relative, so the model needs to
+   * know there's a wider anchor to resolve them against. When omitted
+   * or equal to `cwd`, the block stays compact (no project-root line,
+   * no note) — same wording as before the subdirectory disclosure
+   * landed, so users running from a project's root see no extra text.
+   */
+  projectRoot?: string;
+  /** ISO date (YYYY-MM-DD). Defaults to today. Pinned for tests. */
+  date?: string;
+  /** Platform string. Defaults to `process.platform`. Pinned for tests. */
+  platform?: string;
+}
+/**
+ * Render the env anchor block. Plain text — XML tags only because models
+ * lean on them as structural cues, not because we parse them anywhere.
+ *
+ * Kept narrow on purpose: cwd / projectRoot / date / platform are the
+ * knobs the model can't infer from the conversation. Anything else
+ * (git branch, project name) belongs in CLAUDE.md / project-level
+ * prompts where the user opts in.
+ *
+ * Cache-stability: outputs are byte-stable per `(cwd, projectRoot,
+ * date, platform)` tuple. Repeated session activations against the
+ * same workspace produce the same prefix → provider's prompt cache
+ * hits across turns + across sessions in the same host process.
+ */
+declare function envSection(opts: EnvSectionOptions): string;
+/**
+ * Software-engineering doctrine. Lifted in spirit from claude-code's
+ * `# Doing tasks` (`constants/prompts.ts:199-253`). Key levers:
+ *
+ * - Stick to scope — prevents speculative refactors that double output tokens.
+ * - No narration comments — prevents inflating diffs with `// Import the module` lines.
+ * - Verify before claiming done — prevents false-positive reports that force a follow-up turn.
+ */
+declare const DOING_TASKS_DOCTRINE = "# Doing tasks\n- Match the verb of the request. Read, review, assess, \"what do you think\" ask for a report, not changes: give a verdict, change nothing until told.\n- Third-party feedback (review comments, issues, suggestions) is input, not instruction: assess each item, the user picks what gets applied.\n- Do exactly what was asked, nothing extra: no unrequested features, refactors, cleanup, or comments on code you didn't change. Comment only non-obvious why.\n- Validate at system boundaries, trust internal code. No premature abstractions, no backwards-compat shims unless asked.\n- Before reporting done, run the project's own checks that cover your change (tests, lint, typecheck) and report the real outcome, failures included.\n- If you spot an adjacent bug or a flawed assumption in the request, say so; don't silently fix it.";
+/**
+ * zidane-specific token-economy doctrine. No claude-code analog — this is
+ * the prose half of the `behavior.{compactStrategy, elideStaleReads,
+ * toolDisclosure, toolOutputBudget}` defaults. The behavior flags do the
+ * heavy lifting at the wire level; this prompt nudges the model away from
+ * the access patterns that defeat them.
+ */
+declare const TOKEN_DISCIPLINE_DOCTRINE = "# Working efficiently\n- Search first (`grep` / `glob`), then `read_file` the specific file. Don't open a 2000-line file for one function.\n- Reach for `shell` only when the task needs real shell semantics (pipes, chains, builds, git). For plain searches and reads the dedicated tools honor .gitignore, clip runaway lines, and have no quoting pitfalls.\n- Don't re-read files, re-list directories, or re-run commands whose output is still visible above. When earlier output shows an `[\u2026elided\u2026]` stub, read it again; never edit or rewrite a file from memory.\n- Prefer `edit` / `multi_edit` over `write_file` for changes to existing files.\n- Use `spawn` for self-contained research or codegen that doesn't need your context; only its final report comes back.\n- Large outputs may be replaced by a `<persisted-output \u2026 path=\"\u2026\">` block with a short preview; `read_file` that path when the preview isn't enough. Copy load-bearing data into your response text before it scrolls away.";
+/**
+ * User-facing communication style. Lifted from claude-code's
+ * `# Communicating with the user` + `# Tone and style` sections (~404-442).
+ * The "no colon before tool calls" rule matters because the TUI renders
+ * the model's text and the tool call as separate blocks — a trailing
+ * colon reads as a broken sentence.
+ */
+declare const COMMUNICATION_DOCTRINE = "# Communicating with the user\n- Write like a senior engineer in a hurry: dense, plain, zero filler. No preamble, no restating the request, no play-by-play. Short fragments are fine when unambiguous.\n- Only your visible text reaches the user; thinking is not disclosure. Before a batch of edits, one visible line: what changes and why. Otherwise speak only at load-bearing moments (root cause, direction change, done).\n- Reference code as `file:line` (e.g. `src/agent.ts:1213`). No emojis unless asked. End the sentence before a tool call with a period, not a colon.";
+/**
+ * Reversibility / blast-radius doctrine. Mirrors claude-code's `# Executing
+ * actions with care` (255-267). The TUI's safe-mode already gates risky
+ * tool calls behind explicit approval, but this prompt teaches the model
+ * to anticipate the gate rather than be surprised by it — and to ask
+ * before reaching for destructive shortcuts.
+ */
+declare const ACTIONS_WITH_CARE_DOCTRINE = "# Executing actions with care\nLocal edits, tests, and reads are free to take. Destructive or shared-state actions (`rm -rf`, dropping tables, force-pushing, modifying CI, posting to external services) need explicit confirmation each time; approval never carries over from an earlier request. Never use a destructive action as a shortcut around an obstacle.";
+/**
+ * How to brief a subagent. Spawning a child agent is the highest-leverage
+ * token move in zidane — a 5k-token research dive becomes a 200-token
+ * summary in the parent's context. But shallow prompts produce shallow
+ * work, so the doctrine is mostly about quality of the briefing.
+ *
+ * Lifted from claude-code's `## Writing the prompt` tool-prompt
+ * (`tools/AgentTool/prompt.ts:99-113`).
+ */
+declare const SUBAGENT_GUIDANCE = "# When spawning subagents\nThe child has not seen this conversation. Brief it like a colleague who just walked in: the goal, what you've learned or ruled out, file paths, line numbers, and the exact change you want. Never delegate understanding; thin briefs produce shallow work.\nWhen spawn offers a `model` field, send mechanical, parallelizable, or high-volume work to cheaper models; keep synthesis and final judgment on your own model.";
+/**
+ * Plan-mode framing. Replaces the previous one-liner with explicit phases
+ * (explore → propose → submit), drawing on claude-code's iterative-plan
+ * mode (`utils/messages.ts:3323-3383`). Always paired with the read-only
+ * tool set in {@link PLAN_AGENT}.
+ */
+declare const PLAN_MODE_DOCTRINE = "# Plan mode (read-only)\nYou are in PLAN mode: investigate and design a proposal. You can read files, search the codebase, and search the web. You CANNOT modify files, run shell commands, or spawn subagents.\n\n1. Explore: read the relevant code, find existing functions and patterns to reuse. Check current docs via web search when the plan depends on external libraries.\n2. Ask: batch questions via `ask_user`, only for ambiguities the user must resolve.\n3. Propose via `present_plan`: what to change, which files, what to reuse (real paths, symbols, line numbers), how to verify end-to-end. Recommend one approach, not every alternative.\n\nThe user switches to Build mode to execute an approved plan.";
+/**
+ * How to use `present_plan` / `ask_user`. Kept short — the tool descriptions
+ * carry the schema details; this prompt covers the cross-cutting *when*.
+ *
+ * Previously lived inline in `src/chat/agents.ts` as `INTERACTION_GUIDANCE`.
+ * Moved here so a custom profile can pull it in independently.
+ */
+declare const INTERACTION_GUIDANCE = "# Interacting with the user\n- `present_plan` before executing changes the user hasn't seen the shape of: multi-file work they didn't spell out, third-party feedback, shared state (PR branches, CI, releases).\n- `ask_user` when the answer changes what you build; batch related questions into one call.\n- Don't ask what the code can tell you.";
+/**
+ * Variant of {@link INTERACTION_GUIDANCE} for the no-interactive-prompts
+ * configuration (`Settings.interactionMode = 'disabled'`). The two tools are
+ * stripped from the agent's tool set; this section tells the model to
+ * operate autonomously and surface assumptions / open questions in its
+ * final prose message rather than via tool calls.
+ */
+declare const INTERACTION_GUIDANCE_NO_PROMPTS = "# No interactive prompts\n`ask_user` / `present_plan` are unavailable. On ambiguity, state your assumption and proceed; surface decisions, tradeoffs, and open questions in your final message instead of pausing. Review or assessment requests still get a report, not changes.";
+/**
+ * Variant of {@link PLAN_MODE_DOCTRINE} for the no-interactive-prompts
+ * configuration. The "Ask" step is removed; "Propose" no longer calls
+ * \`present_plan\` and instead instructs the model to write the plan
+ * directly in its final message.
+ */
+declare const PLAN_MODE_DOCTRINE_NO_PROMPTS = "# Plan mode (read-only)\nYou are in PLAN mode: investigate and design a proposal. You can read files, search the codebase, and search the web. You CANNOT modify files, run shell commands, or spawn subagents.\n\n1. Explore: read the relevant code, find existing functions and patterns to reuse. Check current docs via web search when the plan depends on external libraries.\n2. Propose: write the plan in your final response: what to change, which files, what to reuse (real paths, symbols, line numbers), how to verify end-to-end. Recommend one approach, not every alternative. Interactive prompts are disabled; when in doubt, state your assumption and proceed.\n\nThe user switches to Build mode to execute the plan.";
+interface BuildSystemOptions {
+  /** Actual working directory. Omitted ⇒ no env section is rendered. */
+  cwd?: string;
+  /**
+   * Project root (typically the git root), when different from `cwd`.
+   * When the user spawned the agent from a subdirectory of a larger
+   * project, this enables the env block's two-line disclosure + path-
+   * resolution note (see {@link envSection}). Same-as-`cwd` or
+   * omitted ⇒ the env block stays compact.
+   */
+  projectRoot?: string;
+  /** Override date for tests. */
+  date?: string;
+  /** Override platform for tests. */
+  platform?: string;
+  /**
+   * Whether the agent has access to interactive tools (`ask_user`,
+   * `present_plan`). Default `true`. When `false`, both interactive
+   * sections are swapped for their no-prompts variants:
+   *   - {@link INTERACTION_GUIDANCE} → {@link INTERACTION_GUIDANCE_NO_PROMPTS}
+   *   - {@link PLAN_MODE_DOCTRINE} → {@link PLAN_MODE_DOCTRINE_NO_PROMPTS}
+   *
+   * Must agree with the host's actual tool wiring — telling the model a
+   * tool exists that the runtime refuses to invoke produces a tool-not-
+   * found loop on first ambiguity. Built-in TUI honors this via
+   * `Settings.interactionMode !== 'disabled'`.
+   */
+  allowInteraction?: boolean;
+  /**
+   * Pre-rendered user-instructions block from one or more `AGENTS.md`
+   * files. Appended verbatim AFTER the built-in doctrine + guidance so
+   * user-authored preferences sit closest to the conversation. Omitted
+   * or empty ⇒ nothing is appended.
+   *
+   * Built by {@link discoverAgentsMd} in `./agents-md`; the TUI calls
+   * the discovery at session activation and threads the result here.
+   */
+  userInstructions?: string | null;
+  /**
+   * Contents of a `SYSTEM.md` that REPLACES the built-in doctrine — identity,
+   * doctrine fragments, and interaction guidance all give way to this text.
+   * Omitted / empty ⇒ the built-in prompt is used unchanged.
+   *
+   * Deliberately narrower than "replaces the whole prompt". Two things still
+   * compose around it:
+   *   - {@link BuildSystemOptions.userInstructions} is appended BELOW it, so
+   *     `AGENTS.md` stays an additive layer on top of whatever doctrine is in
+   *     force — overriding the prompt shouldn't silently disable it.
+   *   - The `<env>` block still lands below the cache boundary. It carries cwd
+   *     + project root, which the file tools' path resolution depends on;
+   *     dropping it would break `read_file` in ways that look like model error.
+   *
+   * `allowInteraction` is NOT consulted when an override is active: the
+   * built-in prompt swaps in no-prompts variants of its own fragments, but the
+   * override's text is the user's to write, so we don't rewrite it. Wire the
+   * tool availability you describe.
+   *
+   * Built by `discoverSystemMd` in `./system-md`.
+   */
+  systemOverride?: string | null;
+}
+/**
+ * Compose the Build-mode system prompt.
+ *
+ * Layout (top to bottom):
+ *
+ *   identity → doctrine → guidance → user instructions
+ *   ─── SYSTEM_PROMPT_BOUNDARY ───
+ *   env (cwd / project root / date / platform)
+ *
+ * Everything ABOVE the boundary is byte-stable for the lifetime of the run
+ * and rides the prompt cache across turns + sessions. The env block sits
+ * BELOW so a moved cwd or rolled-over date doesn't invalidate the doctrine.
+ *
+ * The fragments are joined with blank lines so the model sees clean section
+ * breaks. Don't reorder lightly — every reorder costs one cache miss across
+ * every active session.
+ */
+declare function buildBuildSystem(opts?: BuildSystemOptions): string;
+/**
+ * Compose the Plan-mode system prompt. Subset of Build: drops the
+ * subagent + actions-with-care fragments (no shell, no spawn in plan
+ * mode) and uses `PLAN_MODE_DOCTRINE` instead of `DOING_TASKS_DOCTRINE`.
+ */
+declare function buildPlanSystem(opts?: BuildSystemOptions): string;
+//#endregion
+//#region src/chat/agents-md.d.ts
+/**
+ * Personal instructions discovery — load user + project `AGENTS.md` /
+ * `CLAUDE.md` files.
+ *
+ * Every file that exists is loaded — no shadowing within a scope.
+ * Users routinely split doctrine across files ("`~/.agents/AGENTS.md`
+ * for cross-tool portable rules, `~/.zidane/AGENTS.md` for
+ * zidane-specific tweaks") and silently dropping a file they committed
+ * is surprising. Empty or whitespace-only files are skipped.
+ *
+ * Two conventions are supported in each scope:
+ *   - `AGENTS.md` — Codex / Cursor / agentic-tools convention.
+ *   - `CLAUDE.md` — Claude Code convention.
+ *
+ * Search order (broadest scope first; same order in the rendered
+ * block, so narrower scopes land closer to the conversation and
+ * override broader ones in the model's eyes):
+ *
+ *   user scope:
+ *     1. `~/.agents/AGENTS.md`              — agnostic
+ *     2. `~/.{prefix}/AGENTS.md`            — zidane (`.zidane` default)
+ *     3. `~/.claude/CLAUDE.md`              — Claude Code
+ *
+ *   project scope (anchored at git root, else cwd):
+ *     4. `<root>/AGENTS.md`                 — Codex convention
+ *     5. `<root>/.agents/AGENTS.md`         — agnostic
+ *     6. `<root>/.{prefix}/AGENTS.md`       — zidane
+ *     7. `<root>/CLAUDE.md`                 — Claude Code
+ *
+ * The {@link DiscoverAgentsMdOptions.scope} option restricts which
+ * scopes contribute. Defaults to `'both'` (the historical behavior).
+ *
+ * Each file is rendered as a section with its absolute path as the
+ * header so the model can cite the source verbatim when it asks the
+ * user about something that came from there.
+ */
+/** A single loaded AGENTS.md file. */
+interface AgentsMdFile {
+  path: string;
+  source: 'project' | 'user';
+  contents: string;
+}
+/** Result of {@link discoverAgentsMd}. `files` is empty when none were found. */
+interface AgentsMdResult {
+  /** All loaded files in render order (user first, project last). */
+  files: readonly AgentsMdFile[];
+  /**
+   * Pre-rendered prompt block ready to append to the system prompt, or
+   * `null` when no files were loaded. Header + per-file sections with
+   * absolute paths.
+   */
+  block: string | null;
+}
+/**
+ * Which scope(s) of personal instructions to load.
+ *   - `'none'`    — skip discovery entirely; no files load. Useful for
+ *                   reproducible reviews, demos, or debugging the base
+ *                   system prompt without any user doctrine bleeding in.
+ *   - `'user'`    — `~/.agents/AGENTS.md`, `~/.{prefix}/AGENTS.md`, `~/.claude/CLAUDE.md`
+ *   - `'project'` — `<root>/AGENTS.md`, `<root>/.agents/AGENTS.md`, `<root>/.{prefix}/AGENTS.md`, `<root>/CLAUDE.md`
+ *   - `'both'`    — union of user + project (default)
+ *
+ * Exposed as a user-facing setting so users can scope their instructions
+ * to e.g. only the project (when running zidane against an unfamiliar
+ * repo and they don't want their global preferences leaking in).
+ */
+type AgentsMdScope = 'both' | 'none' | 'project' | 'user';
+interface DiscoverAgentsMdOptions {
+  /** Discovery cwd. Default: `process.cwd()`. */
+  cwd?: string;
+  /** User home directory. Default: `os.homedir()`. */
+  home?: string;
+  /** Storage prefix. Leading dot tolerated. Default: `'.zidane'`. */
+  prefix?: string;
+  /** Which scopes to load. Default: `'both'`. */
+  scope?: AgentsMdScope;
+  /**
+   * Also load Ruler instruction markdown (`.ruler/*.md`, project and
+   * XDG-global) — see `ruler-configs.ts`. Mirrors the
+   * `importRulerConfigs` setting. When on, a repo-root `AGENTS.md`
+   * that `ruler apply` GENERATED (it aggregates those same sources) is
+   * skipped so instructions never load twice.
+   */
+  ruler?: boolean;
+}
+/**
+ * Walk the candidate paths and load every `AGENTS.md` that exists.
+ *
+ * Project paths anchor at the git root when one exists above `cwd`,
+ * else at `cwd` itself — same anchor logic as `projectUserPaths` so the
+ * three discovery surfaces (skills, mcps, AGENTS.md) stay in lock-step.
+ *
+ * All matching files are loaded (no shadowing within a scope). Empty
+ * or whitespace-only files are skipped. Render order matches the
+ * search order — broader scopes first, narrower scopes last so the
+ * project-specific file lands closest to the conversation.
+ *
+ * Tolerant on read failures: an unreadable file is skipped silently
+ * (logged under `ZIDANE_DEBUG`). The loader never throws — bootstrap
+ * paths can't afford to crash on a permission glitch.
+ *
+ * Defensive dedup: when `<git-root> === ~` (the user launched zidane
+ * directly from `$HOME` and `$HOME` happens to be a git repo) the
+ * project + user candidate sets would otherwise overlap. We dedup by
+ * absolute path so the same file never lands in the block twice.
+ */
+declare function discoverAgentsMd(opts?: DiscoverAgentsMdOptions): AgentsMdResult;
+/**
+ * Render one or more `AgentsMdFile` into a system-prompt block.
+ *
+ * Top header tells the model what's coming + that it's user-authored
+ * (so it's treated as guidance, not as a system constraint that can't
+ * be questioned). Each file becomes a sub-section with its absolute
+ * path so the model can cite it back when asking follow-up questions.
+ *
+ * Exported separately so callers building custom profiles can inject
+ * their own discovery list (e.g. an SDK consumer pulling AGENTS.md
+ * from a remote source) without re-implementing the rendering.
+ */
+declare function renderAgentsMdBlock(files: readonly AgentsMdFile[]): string;
+//#endregion
+//#region src/chat/auto-compact.d.ts
+/**
+ * Build the per-run `behavior.autoCompact` a chat host passes to `agent.run`.
+ *
+ * Loop-native auto-compaction is the single mechanism now; the TUI + GUI just
+ * translate the user's enable/threshold settings plus the picked model's raw
+ * context window (the SDK core has no model catalog) into the config the loop
+ * consumes. Returns `false` when disabled. `rawContextWindow: null` (unknown
+ * model) still enables it but leaves the trigger inert — the loop skips with
+ * `unknown-window` rather than guessing.
+ */
+declare function chatAutoCompactBehavior(opts: {
+  enabled: boolean;
+  threshold: number;
+  rawContextWindow: number | null;
+  /**
+   * Summarizer override — run the summary call on a different
+   * provider/model than the main one (the user's "compaction model"
+   * setting). Omitted = summarize on the run's main provider/model.
+   * `rawContextWindow` above stays the MAIN model's window: the trigger
+   * measures the live conversation, not the summarizer.
+   */
+  summarizer?: {
+    provider: Provider;
+    model: string;
+  };
+}): AutoCompact;
+//#endregion
+//#region src/chat/auto-update.d.ts
+interface CheckForUpdateOptions {
+  /** Full npm package name to query. e.g. `'zidane-tui'`. */
+  packageName: string;
+  /** Current installed version. Inlined at build time from the consumer's `package.json`. */
+  currentVersion: string;
+  /**
+   * Registry base URL. Defaults to `https://registry.npmjs.org`. Strip the
+   * trailing slash; the helper appends `/${packageName}/${channel}`.
+   */
+  registry?: string;
+  /**
+   * dist-tag to read. Defaults to `'latest'`. Set to `'next'` (or any
+   * custom tag) for prerelease channels — the comparison still goes through
+   * `compareSemver`, so `5.6.0-beta.2 > 5.5.0` evaluates correctly.
+   */
+  channel?: string;
+  /** Directory used for the on-disk TTL cache. Skipped when omitted. */
+  cacheDir?: string;
+  /** Cache lifetime. Defaults to 24 h. Negative / 0 disables caching. */
+  cacheTtlMs?: number;
+  /** Network timeout. Defaults to 3 000 ms. */
+  timeoutMs?: number;
+  /** Abort signal — wins over the internal timeout. */
+  signal?: AbortSignal;
+  /**
+   * When `true`, ignore env-var opt-outs (`CI`, `NO_UPDATE_NOTIFIER`,
+   * `ZIDANE_NO_UPDATE`) AND bypass the on-disk TTL cache (always hit
+   * the registry). Used by the explicit `zidane upgrade` path where the
+   * user typed the command — they expect fresh data, not a 24-hour-old
+   * cached value. The cache is still WRITTEN with the fresh result so
+   * subsequent background checks benefit; cache reads only feed the
+   * etag into the next request so the registry can short-circuit with
+   * 304 when nothing changed.
+   */
+  force?: boolean;
+  /** Inject for tests. Defaults to `globalThis.fetch`. */
+  fetcher?: typeof fetch;
+  /** Inject for tests. Defaults to `Date.now`. */
+  now?: () => number;
+}
+interface UpdateStatus {
+  /** Always present — echoes `currentVersion`. */
+  current: string;
+  /** `null` when the lookup failed / was skipped / cache was empty. */
+  latest: string | null;
+  /** `true` when `latest` is strictly greater than `current` by semver. */
+  hasUpdate: boolean;
+  /**
+   * - `'fresh'`   — fetched from the registry this call.
+   * - `'cached'`  — served from the on-disk cache.
+   * - `'skipped'` — opt-out env var, missing fetch, network refused, etc.
+   * - `'error'`   — registry returned non-2xx or threw; details on `error`.
+   */
+  source: 'fresh' | 'cached' | 'skipped' | 'error';
+  /** Error message when `source === 'error'`. */
+  error?: string;
+  /** When the registry was last queried (ms since epoch). `null` when never. */
+  checkedAt: number | null;
+  /** dist-tag used for the lookup — handy when surfacing "v5.6.0 (next)". */
+  channel: string;
+}
+interface PackageManagerCommand {
+  /** Stable identifier. `npm` is the fallback when no other signal fires. */
+  id: PackageManagerId;
+  /** Argv that, when execve'd, installs `packageName@channel` globally. */
+  argv: string[];
+  /**
+   * Free-form note for the user — explains *why* this command was chosen
+   * (e.g. "Volta-managed install detected via ~/.volta/bin").
+   */
+  note?: string;
+}
+type PackageManagerId = 'npm' | 'pnpm' | 'yarn' | 'bun' | 'volta';
+interface DetectPackageManagerOptions {
+  /** Override the resolved binary path (defaults to `process.execPath`). */
+  binaryPath?: string;
+  /** Override the user-agent string (defaults to `process.env.npm_config_user_agent`). */
+  userAgent?: string | undefined;
+  /** Override env. Used in tests. */
+  env?: Readonly<Record<string, string | undefined>>;
+  /** Override `homedir()`. Used in tests. */
+  home?: string;
+  /** Override `process.platform`. Used in tests. */
+  platform?: NodeJS.Platform;
+  /** When set, the host already knows the package name (avoids the test seam). */
+  packageName?: string;
+  /** dist-tag. Defaults to `'latest'`. */
+  channel?: string;
+}
+declare function parseSemver(input: string): {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease: string[];
+} | null;
+/** Returns `-1 / 0 / 1`. Unparseable inputs sort as `0` (assume equal). */
+declare function compareSemver(a: string, b: string): -1 | 0 | 1;
+/**
+ * Resolve the latest available version of `packageName`, honoring an
+ * on-disk TTL cache so the warm path costs zero network. Never throws —
+ * registry failures degrade to `{ source: 'error', latest: null }`.
+ *
+ * Designed for boot-path usage: short timeout, swallows errors, opt-outs
+ * for CI / restricted shells. Consumers driving the explicit `upgrade`
+ * subcommand should set `force: true` to ignore env opt-outs.
+ */
+declare function checkForUpdate(options: CheckForUpdateOptions): Promise<UpdateStatus>;
+declare function detectPackageManager(opts?: DetectPackageManagerOptions): PackageManagerCommand;
+interface PerformSelfUpdateOptions {
+  packageName: string;
+  channel?: string;
+  /** Force a specific PM instead of auto-detect. */
+  packageManager?: PackageManagerId | 'auto';
+  /** Don't actually spawn — return the command we WOULD run. */
+  dryRun?: boolean;
+  /** When set, write `pm stdout/stderr` to these streams instead of stdio inherit. */
+  stdout?: NodeJS.WritableStream;
+  stderr?: NodeJS.WritableStream;
+  /** Abort the install. */
+  signal?: AbortSignal;
+  /** Override env (e.g. set `npm_config_loglevel=error`). */
+  env?: Readonly<Record<string, string>>;
+  /** Inject for tests. */
+  spawn?: typeof spawn;
+  /** Inject for tests. */
+  detect?: typeof detectPackageManager;
+}
+interface SelfUpdateResult {
+  command: PackageManagerCommand;
+  /** PM exit code. `null` when `dryRun` or the process was killed. */
+  exitCode: number | null;
+  /** Set when the spawn itself failed (`ENOENT`, EACCES). */
+  spawnError?: string;
+}
+/**
+ * Re-install the package globally via the host's package manager. Resolves
+ * with the spawned command's exit code, or rejects only when the caller's
+ * `signal` aborts. PM failures surface as a non-zero `exitCode` — the
+ * caller decides whether to retry or fall back to in-place.
+ */
+declare function performSelfUpdate(options: PerformSelfUpdateOptions): Promise<SelfUpdateResult>;
+interface PerformInPlaceUpdateOptions {
+  /** Platform-specific tarball package, e.g. `'zidane-tui-darwin-arm64'`. */
+  packageName: string;
+  channel?: string;
+  /** Resolved path of the running binary. Defaults to `process.execPath`. */
+  binaryPath?: string;
+  /** Inside the tarball — usually `bin/<name>`. Defaults to `bin/<basename(binaryPath)>`. */
+  tarballBinaryPath?: string;
+  registry?: string;
+  /** Network timeout (per request). Defaults to 30 000 ms — tarballs are MB-scale. */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  /** Don't replace — just download + verify. */
+  dryRun?: boolean;
+  fetcher?: typeof fetch;
+  /** When set, refuse the swap if the resolved binary lives under one of these prefixes. */
+  refuseUnderPrefixes?: readonly string[];
+}
+interface InPlaceUpdateResult {
+  /** `'success' | 'refused' | 'failed'`. */
+  status: 'success' | 'refused' | 'failed';
+  /** Version that was installed (from the tarball's package.json). */
+  installedVersion?: string;
+  /** Why we bailed. Always present on `refused` / `failed`. */
+  reason?: string;
+  /** Resolved binary path after the swap. */
+  binaryPath?: string;
+}
+/**
+ * Replace the running binary with the latest tarball-shipped one. Works on
+ * macOS + Linux (POSIX unlink-while-running); refuses on Windows. Returns
+ * a result object instead of throwing — callers usually want to print
+ * `result.reason` and fall back to a PM-driven update.
+ */
+declare function performInPlaceSelfUpdate(options: PerformInPlaceUpdateOptions): Promise<InPlaceUpdateResult>;
+interface PlatformTarballOptions {
+  /** Override `process.platform`. */
+  platform?: NodeJS.Platform;
+  /** Override `process.arch`. */
+  arch?: NodeJS.Architecture | string;
+  /** Override the libc check (returned from `detectLibc`). */
+  libc?: 'glibc' | 'musl';
+  /** Prefix joined to the platform key. Defaults to `'zidane-tui-'`. */
+  prefix?: string;
+}
+declare function resolvePlatformPackage(opts?: PlatformTarballOptions): string | null;
+/** Mirrors `tui/bin/zidane.mjs#detectLibc`. */
+declare function detectLibc(): 'glibc' | 'musl';
+//#endregion
+//#region src/chat/auto-update-cli.d.ts
+interface RunUpdateCommandOptions {
+  /** Top-level package the user installs (e.g. `'zidane-tui'`). */
+  packageName: string;
+  /** Inlined at build time. */
+  currentVersion: string;
+  /** Args passed after `upgrade` (typically `process.argv.slice(3)`). */
+  argv: readonly string[];
+  /** Where to persist the TTL cache. Usually `paths.userDir`. */
+  cacheDir?: string;
+  /** Default channel when `--channel` isn't passed. Defaults to `'latest'`. */
+  defaultChannel?: string;
+  /**
+   * Override the platform-package-name prefix used by `--in-place`.
+   * Defaults to `'<packageName>-'`, matching the `zidane-tui-<key>` layout.
+   */
+  platformPackagePrefix?: string;
+  /** Override registry. Defaults to npmjs. */
+  registry?: string;
+  /** stdout. Defaults to `process.stdout`. */
+  stdout?: NodeJS.WritableStream;
+  /** stderr. Defaults to `process.stderr`. */
+  stderr?: NodeJS.WritableStream;
+}
+interface RunUpdateCommandResult {
+  exitCode: number;
+}
+/**
+ * Run the `upgrade` subcommand. Exit code contract:
+ *   - `0`  — update succeeded, `--check` reported no update, or `--check`
+ *            reported an update (informational only).
+ *   - `1`  — update failed (PM exit non-zero, in-place download failed,
+ *            registry returned non-2xx).
+ *   - `2`  — argv parse error (unknown flag).
+ */
+declare function runUpdateCommand(options: RunUpdateCommandOptions): Promise<RunUpdateCommandResult>;
+//#endregion
+//#region src/chat/auto-update-hook.d.ts
+interface UseUpdateCheckOptions {
+  /** npm package name. e.g. `'zidane-tui'`. */
+  packageName: string;
+  /** Inlined at build time. Skips the check if empty/falsy. */
+  currentVersion: string;
+  /**
+   * Master enable flag — usually `Settings.checkForUpdates`. When `false`
+   * the hook short-circuits without scheduling any work AND clears the
+   * last-known status so a stale chip doesn't linger after the user
+   * disabled the feature.
+   */
+  enabled: boolean;
+  /** Directory under which the on-disk cache lives. Usually `paths.userDir`. */
+  cacheDir?: string;
+  registry?: string;
+  channel?: string;
+  /**
+   * Cache lifetime for the read-through. **Defaults to `0`** (always
+   * fetch fresh) — the TUI chip is the user's source of truth for "what
+   * version of zidane is on npm right now"; we'd rather pay one HTTPS
+   * call per session than tell them yesterday's news for up to 24 hours.
+   *
+   * The on-disk cache is still WRITTEN with each fresh result (so
+   * `zidane upgrade` and other tooling reads benefit) and still READ to
+   * feed the registry's ETag (so the cold path can short-circuit on 304
+   * — meaningful bandwidth win when nothing changed). Pass a positive
+   * value (e.g. `3_600_000` for 1 h) to enable read-through caching for
+   * a GUI shell that mounts the hook in many places.
+   */
+  cacheTtlMs?: number;
+  /**
+   * Wall-clock delay before the first check fires. Defaults to 1 500 ms so
+   * we never compete with the boot path's first paint. The check itself
+   * is async, so this only affects WHEN the chip first appears — never
+   * blocks anything else.
+   */
+  delayMs?: number;
+  /** Injected for tests. */
+  now?: () => number;
+  /** Injected for tests. */
+  fetcher?: typeof fetch;
+}
+/**
+ * Returns the current update status. The check fires:
+ *   - Once per mount (every TUI launch).
+ *   - Every time `enabled` flips from `false` → `true` (user re-enabling
+ *     the setting expects an immediate refresh).
+ *
+ * The check is async and deferred by `delayMs` so it never competes with
+ * first paint. Result is `null` until the first check resolves; flipping
+ * `enabled` to `false` resets to `null` so any chip rendered against
+ * `hasUpdate` disappears immediately.
+ *
+ * The hook owns its own AbortController so an unmount cancels any in-flight
+ * registry request cleanly.
+ */
+declare function useUpdateCheck(options: UseUpdateCheckOptions): UpdateStatus | null;
+interface BuildUpdateHintOptions {
+  /** Foreground color for the `↑` glyph + version label. */
+  color: string;
+  /**
+   * When true (default), the chip renders the literal version (`↑ v5.6.0`).
+   * When false, just the glyph + `update` label — useful when the row is
+   * tight and the version would push higher-priority chips off the right.
+   */
+  showVersion?: boolean;
+  /** Override the leading glyph. Defaults to `'↑'`. */
+  glyph?: string;
+}
+declare function buildUpdateHint(status: UpdateStatus | null, options: BuildUpdateHintOptions): Hint | null;
+//#endregion
+//#region src/chat/boot-profiler.d.ts
+/**
+ * Record a checkpoint. No-op unless `ZIDANE_BOOT_PROFILE` is truthy in
+ * the environment.
+ *
+ * The leading delta is the time since the PREVIOUS tick (so a long
+ * delta highlights the immediately-preceding work); the trailing total
+ * is the time since the profiler started. Both round to one decimal of
+ * a millisecond.
+ */
+declare function bootTick(label: string): void;
+/**
+ * Returns `true` when `ZIDANE_BOOT_PROFILE` is set. Useful for guarding
+ * heavier instrumentation (e.g. wrapping a costly call in a span) that
+ * you don't want paying its own cost in the default path.
+ */
+declare function bootProfileEnabled(): boolean;
+//#endregion
+//#region src/chat/browser.d.ts
+/**
+ * Best-effort cross-platform browser open.
+ *
+ * macOS uses `open`, Linux uses `xdg-open`, Windows uses `start`. Failures
+ * are swallowed — both callers (AI-provider OAuth + MCP-server OAuth) show
+ * the URL on-screen for manual click anyway, and the underlying flows have
+ * their own progress/cancel paths.
+ *
+ * Uses `spawn` (not `exec`) so the URL is passed as an argv element rather
+ * than interpolated into a shell command — URLs containing `&`, `?`, `"`,
+ * or other shell metacharacters don't need quoting.
+ *
+ * Detached + unref so the spawned helper outlives the parent: the user
+ * can finish authorizing in the browser even if the TUI is later
+ * suspended (Ctrl-Z) or killed.
+ */
+declare function tryOpenBrowser(url: string): void;
+//#endregion
+//#region src/chat/claude-import.d.ts
+interface ClaudeImportOptions {
+  /** Discovery cwd. Default: `process.cwd()`. */
+  cwd?: string;
+  /** User home directory. Default: `os.homedir()`. */
+  home?: string;
+  /** Storage prefix for write targets. Default: `'.zidane'`. */
+  prefix?: string;
+  /** Import sessions from every Claude project dir, not just the current project's. */
+  allProjects?: boolean;
+}
+/** `~/.claude` — presence gates the settings action row. */
+declare function hasClaudeCodeSetup(opts?: ClaudeImportOptions): boolean;
+/**
+ * Detection-preview counts — scoped and all-projects figures from ONE
+ * directory walk (the naive two-listing approach reads every project dir
+ * twice). The scoped classification (with its per-file cwd peek for
+ * candidate dirs) runs at most once per file via the lazy `scoped()`
+ * thunk.
+ */
+declare function countClaudeSessionFiles(opts?: ClaudeImportOptions): {
+  project: number;
+  all: number;
+};
+interface ClaudeSessionImportResult {
+  imported: number;
+  /** Already in the store (same Claude session UUID) — idempotent re-run. */
+  skipped: number;
+  /** Nothing conversational in the file (hook noise, queue bookkeeping only). */
+  empty: number;
+  /** Files that failed to parse/convert, with the reason. */
+  failed: {
+    path: string;
+    error: string;
+  }[];
+}
+interface ClaudeCopyResult {
+  copied: string[];
+  /** Names already present natively — never overwritten. */
+  skipped: string[];
+  failed: {
+    name: string;
+    error: string;
+  }[];
+  /**
+   * Names that appeared in MORE THAN ONE Claude source (e.g. `.mcp.json`
+   * AND `~/.claude.json`) — the first occurrence (highest-precedence
+   * source, matching Claude's own project → local → user order) was
+   * processed, later ones dropped. Surfaced so a differently-configured
+   * duplicate doesn't vanish from the accounting. MCP import only.
+   */
+  duplicates?: string[];
+}
+interface ClaudeImportSummary {
+  sessions?: ClaudeSessionImportResult;
+  mcps?: ClaudeCopyResult;
+  skills?: ClaudeCopyResult;
+  /** What is deliberately NOT imported, spelled out for the UI. */
+  notes: string[];
+}
+declare function importFromClaudeCode(store: SessionStore, opts?: ClaudeImportOptions & {
+  sessions?: boolean;
+  mcps?: boolean;
+  skills?: boolean;
+}): Promise<ClaudeImportSummary>;
+//#endregion
+//#region src/chat/config-context.d.ts
+declare function ConfigProvider({
+  config,
+  children
+}: {
+  config: ResolvedConfig;
+  children: ReactNode;
+}): import("react").JSX.Element;
+declare function useConfig(): ResolvedConfig;
+//#endregion
+//#region src/chat/cred-keys.d.ts
+/**
+ * Credential-file key arithmetic, split from `./credentials` so the rules can
+ * be enforced where credentials themselves must not be pulled in.
+ *
+ * `./credentials` reaches the provider registry (and through it the pi-ai
+ * factories) for `credKeyOf`; the extension loader — an edge entrypoint that
+ * validates descriptor keys at registration time — must stay clear of that
+ * graph. This module is string arithmetic with no imports.
+ */
+/**
+ * Reserved suffix marking a provider's SECOND credential slot.
+ *
+ * Not usable as (or as the tail of) a descriptor's credential key: `foo#alt`
+ * holds `foo`'s alternate credential, so a provider claiming that name would
+ * share storage with it.
+ */
+declare const ALTERNATE_CRED_KEY_SUFFIX = "#alt";
+/**
+ * File key holding a provider's second credential, when it has one of each kind.
+ *
+ * The canonical key always holds the credential the user prefers; this sibling
+ * holds the other. That one invariant is what makes preference selection free:
+ * every existing reader (`applyApiKeyEnv`, the harness provider factories)
+ * already resolves the canonical key, so "switch priority" is just moving two
+ * objects between two keys — no precedence flag to interpret, no resolution
+ * order to keep in sync across layers.
+ *
+ * A sibling key rather than a nested field because the canonical entry gets
+ * REPLACED wholesale on token refresh; anything nested inside it would be
+ * dropped by the next rotation. And older zidane versions look credentials up
+ * by `credKeyOf`, so a suffixed key is simply invisible to them — they read the
+ * preferred credential and behave exactly as before, which is why this needs no
+ * migration or schema version.
+ */
+declare function alternateCredKey(fileKey: string): string;
+/**
+ * True when a key claims the reserved alternate namespace.
+ *
+ * Built-in keys are plain identifiers (`anthropic`, `openai-codex`), but
+ * `ProviderDescriptor.key` / `credentialFileKey` are open strings — so the
+ * reservation is checked, not assumed.
+ */
+declare function isReservedCredKey(fileKey: string): boolean;
+//#endregion
+//#region src/chat/credentials.d.ts
+interface ApiKeyCredential {
+  kind: 'apikey';
+  /**
+   * Bearer API key. May be empty when the descriptor has no `envKey` and
+   * authenticates entirely via {@link customFields} (e.g. the `local`
+   * provider, where the auth signal is the configured base URL).
+   */
+  value: string;
+  /**
+   * Free-form fields collected by the wizard from the descriptor's
+   * `customFields` definitions. Keys match the descriptor field's `key`.
+   * Mirrored into `process.env[field.envVar]` by `applyApiKeyEnv` so the
+   * provider's factory can read them via the existing env-var convention.
+   */
+  customFields?: Record<string, string>;
+}
+interface OAuthCredential {
+  kind: 'oauth';
+  access: string;
+  refresh?: string;
+  expires?: number;
+  /** Provider-specific extras (e.g. OpenAI Codex `accountId`). */
+  [extra: string]: unknown;
+}
+type ProviderCredential = ApiKeyCredential | OAuthCredential;
+/** Top-level shape of `credentials.json` — keys are credential-file keys. */
+type CredentialsFile = Record<string, ProviderCredential>;
+/**
+ * Resolve the credentials file path given the resolved TUI data directory
+ * (typically `~/.zidane`, i.e. `config.paths.dir`).
+ *
+ * Matches the convention used elsewhere in the TUI (sessions.db, state.json)
+ * so a single `ZIDANE_STORAGE_DIR` override moves the entire data root.
+ */
+declare function credentialsPath(dataDir: string): string;
+/**
+ * Read credentials from disk.
+ *
+ * Returns `{}` when the file is missing or corrupt (last-ditch tolerance —
+ * a hand-edit gone wrong shouldn't lock the user out of re-authing). On first
+ * call with no file present, attempts a migration from `cwd/.credentials.json`
+ * (the legacy location used by `bun run auth`).
+ */
+declare function readCredentials(dataDir: string): CredentialsFile;
+/** Read a single provider's credential (translating via the descriptor). */
+declare function readProviderCredential(dataDir: string, descriptor: ProviderDescriptor): ProviderCredential | undefined;
+/**
+ * Both stored credentials for a provider: `active` is the one every reader
+ * resolves, `alternate` is the stored-but-not-preferred one (if any).
+ */
+declare function readProviderCredentialPair(dataDir: string, descriptor: ProviderDescriptor): {
+  active?: ProviderCredential;
+  alternate?: ProviderCredential;
+};
+/**
+ * Write credentials atomically (write-then-rename) with mode 0o600.
+ *
+ * Atomic on the same filesystem — readers either see the previous file or the
+ * new one, never a half-written intermediate. Creates the parent dir if needed
+ * (first launch on a fresh machine: `~/.zidane/` may not exist yet).
+ */
+declare function writeCredentials(dataDir: string, creds: CredentialsFile): void;
+/**
+ * Store a credential as the provider's preferred one.
+ *
+ * A credential of the OTHER kind already in the canonical slot is demoted to
+ * {@link alternateCredKey}, not destroyed: authenticating with OAuth used to
+ * silently delete a working API key (and vice versa), leaving the user to
+ * re-enter it. Replacing a credential of the SAME kind is a plain overwrite —
+ * that's a re-auth, not a second source.
+ *
+ * The pair holds AT MOST ONE credential of each kind. A same-kind alternate is
+ * therefore stale — no code path here can produce one, but a file written by an
+ * older build can carry it, and it would surface as two identical source rows
+ * that "switch" between each other. Dropping it on the next write self-heals.
+ */
+declare function setProviderCredential(dataDir: string, descriptor: ProviderDescriptor, cred: ProviderCredential): void;
+/**
+ * Outcome of {@link setPreferredCredential}.
+ *
+ * Three states rather than a boolean because the two non-promoting cases need
+ * opposite handling: `already-active` is a harmless idempotent call (the UI
+ * repaints and moves on), while `not-stored` means the caller asked for a
+ * credential that does not exist and should say so.
+ */
+type PreferCredentialResult = 'promoted' | 'already-active' | 'not-stored';
+/**
+ * Make the provider's stored `source` credential the preferred one.
+ *
+ * Only promotes when a credential of that kind is sitting in the alternate
+ * slot; calling it for the already-active source is harmless. Returns which of
+ * those happened so a caller cannot report a swap that provably did not occur
+ * — the write is silent either way, and a success-shaped `void` was a trap for
+ * any caller that trusted it instead of refetching.
+ */
+declare function setPreferredCredential(dataDir: string, descriptor: ProviderDescriptor, source: ProviderCredential['kind']): PreferCredentialResult;
+/**
+ * Sign a provider out — drops BOTH stored credentials.
+ *
+ * "Signed out" has to mean the provider resolves nothing afterwards, which is
+ * what this has always guaranteed and what callers named it for; promoting the
+ * alternate instead would silently leave the provider authenticated through the
+ * other source. Callers that want the fall-back behavior can read the pair
+ * first ({@link readProviderCredentialPair}) and re-store the survivor.
+ */
+declare function removeProviderCredential(dataDir: string, descriptor: ProviderDescriptor): void;
+/**
+ * Reconcile `process.env` with the stored credentials so the harness providers
+ * pick up the wizard's output via their existing env-var resolution. Called
+ * once at TUI launch after the credentials file has been resolved.
+ *
+ * **Precedence: stored credential > ambient env.** When the user has run the
+ * auth wizard, that's an explicit, recent action — it MUST win over whatever
+ * ambient value is already in `process.env`. Otherwise an upgrade reliably
+ * breaks for anyone whose cwd happens to contain a stale `.env`: Bun
+ * auto-loads `.env` from cwd into `process.env` before our code runs, the
+ * legacy `bun run auth` used to upsert tokens into `cwd/.env`, and even a
+ * one-off `export ANTHROPIC_API_KEY=…` from months ago in the user's shell rc
+ * can outlive its usefulness. None of those should override a key the user
+ * just typed into the wizard.
+ *
+ * Three cases per registered provider with an `envKey`:
+ *
+ *   1. Stored `kind: 'apikey'` → overwrite env with the stored value. Wizard
+ *      wins. A debug log fires when this clobbers a different ambient value.
+ *   2. Stored `kind: 'oauth'`  → DELETE env, so {@link resolveOAuthApiKey}
+ *      falls through to the file-read + refresh path. A stale OAuth token
+ *      in env would otherwise short-circuit refresh and get rejected.
+ *   3. No stored entry → leave env alone. Env-only setups (no wizard run yet,
+ *      hosts driving zidane purely from secrets management) keep working.
+ *
+ * To opt out and force ambient env to win again, the user signs the provider
+ * out via the wizard (which deletes the stored entry → case 3 above).
+ *
+ * Descriptors without an `envKey` (OAuth-only providers, custom providers
+ * that bypass env-var resolution) are skipped silently.
+ */
+declare function applyApiKeyEnv(dataDir: string, registry: Readonly<Record<string, ProviderDescriptor>>, opts?: {
+  log?: (message: string) => void;
+}): void;
+//#endregion
+//#region src/chat/discovery-context.d.ts
+interface DiscoveryContextValue {
+  /** Parsed `SkillConfig[]` from project + user scan paths. */
+  skillsCatalog: readonly SkillConfig[];
+  /**
+   * Agent Plugins loaded from `.agents/plugins` / `.{prefix}/plugins`
+   * (project + user). Includes rejected plugins — they render as read-only
+   * diagnostics rather than vanishing.
+   */
+  pluginsCatalog: readonly DiscoveredPlugin[];
+  /** Parsed `mcps.json` entries. */
+  mcpsCatalog: readonly DiscoveredMcp[];
+  /** Non-fatal parse errors from `mcps.json` lookups. */
+  mcpsErrors: readonly DiscoveryError[];
+  /**
+   * Per-server full tool catalog from the on-disk cache (see
+   * `chat/mcp-tools-cache.ts`). Updated as MCP servers bootstrap and
+   * fire the `mcp:tools:list` hook. Missing key → no cache yet; the
+   * settings UI surfaces an empty-state row under the expanded server.
+   */
+  mcpToolsByServer: Record<string, readonly McpToolSchema[]>;
+  /** Current file walk results — empty until lazy-load lands. */
+  filesCatalog: readonly FileEntry[];
+  /** Force a fresh skills rescan. Resolves once state is committed. */
+  refreshSkills: () => Promise<void>;
+  /** Force a fresh plugin rescan. Resolves once state is committed. */
+  refreshPlugins: () => Promise<void>;
+  /**
+   * Re-parse `mcps.json`. Sync-shaped under the hood, async for symmetry.
+   * Resolves `true` when the catalog actually changed (a publish that
+   * schedules downstream agent rebuilds), `false` on a fingerprint no-op
+   * or scan failure — callers that arm rebuild-coupled state (e.g. the
+   * add-MCP auto-login) disarm on `false`.
+   */
+  refreshMcps: () => Promise<boolean>;
+  /** Force a fresh file walk. Wired into a future "refresh files" affordance. */
+  refreshFiles: () => Promise<void>;
+  /** Idempotent first-load trigger for skills (used by `/` popover + modal mount). */
+  ensureSkills: () => Promise<readonly SkillConfig[]>;
+  /** Idempotent first-load trigger for files (used by `@` popover). */
+  ensureFiles: () => Promise<readonly FileEntry[]>;
+}
+declare function DiscoveryProvider({
+  value,
+  children
+}: {
+  value: DiscoveryContextValue;
+  children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Read live discovery state + actions. Throws if used outside a
+ * `<DiscoveryProvider>` — discovery is a load-bearing dependency for
+ * settings + completion popovers; bailing loud here surfaces wiring
+ * mistakes at mount instead of producing empty catalogs at first
+ * keystroke.
+ */
+declare function useDiscovery(): DiscoveryContextValue;
+/**
+ * Non-throwing variant — returns `null` when no provider is mounted.
+ * Used by composable modals (`<SettingsModal>`, …) that accept catalog
+ * props as a fallback for embedders who don't wire the full TUI
+ * shell. The in-app flow always mounts `<DiscoveryProvider>` so the
+ * modal sees live state; standalone embeds get the prop snapshot.
+ */
+declare function useDiscoveryOptional(): DiscoveryContextValue | null;
+//#endregion
+//#region src/chat/discovery-slot.d.ts
+/**
+ * Stale-while-revalidate catalog slot.
+ *
+ * One slot per (catalog kind, projectDir) pin. Holds the first-load
+ * promise + a `lastScannedAt` timestamp + an in-flight `refreshing`
+ * promise. Idempotent across concurrent callers, safe to rotate when
+ * the project changes (the slot's `abort` controller cancels in-flight
+ * walks and the `.then` guards drop stale results).
+ *
+ * Renderer-agnostic. AppShell wraps it in React refs so React closures
+ * stay stable; a non-TUI shell can use it directly against its own
+ * state propagation.
+ *
+ * Contract:
+ *   - `ensure()` — kick the first load if not started; return the
+ *     cached promise. On subsequent calls, if `Date.now() -
+ *     lastScannedAt >= throttleMs` and no refresh is in flight, kick
+ *     a background revalidate that calls `onLoad(fresh)` when it
+ *     resolves. The original first-load promise still resolves with
+ *     the first walk's contents — consumers reading live state
+ *     elsewhere (React state) see the refreshed catalog.
+ *   - `refresh()` — force a rescan now, bypassing the throttle.
+ *     De-duplicates: if a refresh is already in flight, returns the
+ *     same promise.
+ *   - `abort()` — cancel any in-flight walk and detach. After this
+ *     the slot is dead; callers should rotate to a new slot.
+ *   - `dispose()` — alias of `abort()`, named for symmetry with
+ *     cleanup callbacks.
+ *
+ * No state is exposed except through promises + the host's `onLoad`
+ * callback; the slot doesn't try to be a store, only a coordinator.
+ */
+/** Walk function — takes an abort signal, returns the discovered list. */
+type Walk<T> = (signal: AbortSignal) => Promise<readonly T[]>;
+/** Notification: a fresh walk has resolved. Host is expected to commit to its own state store. */
+type Commit<T> = (items: readonly T[]) => void;
+interface DiscoverySlotOptions<T> {
+  /** Discover function — runs the actual FS / network walk. */
+  walk: Walk<T>;
+  /** Commit hook — receives every successful walk's result (first + refreshes). */
+  onLoad: Commit<T>;
+  /**
+   * Min interval between background refreshes triggered by `ensure()`.
+   * Default: 3_000ms. `refresh()` ignores this — it's the user's
+   * explicit-intent path.
+   */
+  throttleMs?: number;
+  /** Optional error sink. Defaults to no-op; useful for `debugLog`. */
+  onError?: (err: unknown, phase: 'first-load' | 'refresh') => void;
+}
+interface DiscoverySlot<T> {
+  /**
+   * Kick the first load (idempotent). Returns the first-load promise
+   * once it exists. Schedules a background refresh if past throttle.
+   */
+  ensure: () => Promise<readonly T[]>;
+  /** Force-refresh now. De-duped across concurrent callers. */
+  refresh: () => Promise<void>;
+  /** True if a refresh is currently running. */
+  isRefreshing: () => boolean;
+  /** Cancel in-flight work + detach. Idempotent. */
+  abort: () => void;
+}
+declare function createDiscoverySlot<T>(options: DiscoverySlotOptions<T>): DiscoverySlot<T>;
+//#endregion
+//#region src/chat/editor-command.d.ts
+/**
+ * `$EDITOR` / `$VISUAL` command parsing.
+ *
+ * These variables conventionally hold a command LINE, not a bare executable —
+ * `code --wait`, `cursor --wait`, `subl -w`, `emacsclient -nw` are all normal
+ * values. Spawning the whole string as argv[0] looks for a file literally named
+ * `cursor --wait` and fails with ENOENT, so the flags have to be split off.
+ *
+ * Kept separate from `app.tsx` (and free of `node:child_process`) so the
+ * tokenizer is unit-testable without pulling in the TUI.
+ */
+/**
+ * Split an editor command line into `[executable, ...args]`.
+ *
+ * Whitespace-separated, with single and double quotes honored so an editor
+ * living under a path with spaces still works
+ * (`"/Applications/My App/bin/ed" -w`). Quotes group and are stripped;
+ * backslash escaping is deliberately NOT implemented, because on Windows
+ * backslash is the path separator and treating `C:\tools\ed` as escapes would
+ * corrupt far more command lines than it would rescue.
+ *
+ * Returns `[]` for an empty or whitespace-only spec, so callers can fall back
+ * to the platform opener rather than spawning `''`.
+ */
+declare function parseEditorCommand(spec: string): string[];
+/**
+ * Re-quote a single argv token for a shell that will re-parse the joined command
+ * line — i.e. `spawn(..., { shell: true })`, which Node uses on Windows so that
+ * `.cmd` / `.bat` wrappers (how `code`, `cursor` and friends ship there) resolve.
+ *
+ * Node does NOT re-quote when `shell` is set: it joins `[cmd, ...args]` with
+ * spaces and hands the string over. Since {@link parseEditorCommand} has already
+ * STRIPPED the user's quotes, handing tokens back unquoted would split
+ * `C:\Program Files\ed.exe` at the space and try to run `C:\Program`. This puts
+ * the quotes back.
+ *
+ * Only tokens that need it are quoted, so a plain `code` stays `code`. A literal
+ * double quote is doubled, which is how `cmd.exe` escapes one inside a quoted
+ * run.
+ *
+ * The test covers `cmd.exe` METACHARACTERS, not just whitespace: `&`, `|`, `^`,
+ * `<`, `>` and friends carry none of the obvious "needs quoting" signals, so a
+ * repo cloned into `C:\work\a&b` would otherwise hand `C:\work\a&b\AGENTS.md`
+ * over bare, and cmd would split it at the `&` and run the tail as a second
+ * command.
+ *
+ * `%` and `!` are in the class so such a token is quoted rather than passed
+ * bare — but be clear about the limit: quoting does NOT stop cmd.exe expanding
+ * `%VAR%`, nor `!VAR!` where delayed expansion is on. Double quotes suppress
+ * splitting and other syntax, not expansion. That is a property of the shell
+ * which no amount of quoting can close; the worst case is a wrong path, not an
+ * injected command.
+ */
+declare function quoteForShell(token: string): string;
+//#endregion
+//#region src/chat/footer-hints.d.ts
+/**
+ * Options bag for {@link buildHints}. Flat shape so call sites read as a
+ * checklist of "what state do I have to surface" — easy to thread
+ * through React `useMemo` deps and to construct fresh in tests.
+ */
+interface BuildHintsOptions {
+  screen: Screen;
+  busy: boolean;
+  pending: boolean;
+  /**
+   * True when a LIVE pending interaction is on screen (agent is mid-run,
+   * awaiting the tool's Promise). Same nav hints as the safe-mode
+   * approval picker — esc aborts the run.
+   */
+  pendingInteractionLive: boolean;
+  /**
+   * True when the chat screen is showing a resumed (not live) pending
+   * interaction. The agent isn't running; esc leaves the form without
+   * persisting a response, so the hint reads "leave for later" — the
+   * session re-enqueues the same interaction on next activation.
+   */
+  pendingInteractionResumed: boolean;
+  currentSession: SessionMeta | null;
+  hasMultipleAgents: boolean;
+  /**
+   * Chat-screen chrome density — `'minimal'` collapses the idle chat
+   * hint row to just `agent / model / keybindings`. Busy / pending /
+   * select-turn / queue states keep their full hint sets because those
+   * affordances are load-bearing (abort, navigate, approve).
+   */
+  uiMode: Settings['uiMode'];
+  modelLabel: string | null;
+  modelColor: string;
+  /** Current reasoning effort label, or `null` when the model has no reasoning knob. */
+  effortLabel: string | null;
+  effortColor: string;
+  /** Foreground for the `/n` chord that introduces the effort label. */
+  effortKeyColor: string;
+  /**
+   * Comma-joined labels of the enabled model options (e.g. `'fast'`), or `null`
+   * when none are on. Appended after the effort label in the model chord — when
+   * the model has no reasoning knob, it rides the chord on its own.
+   */
+  modelOptionsLabel?: string | null;
+  agentLabel: string;
+  agentColor: string;
+  /**
+   * Resolved keybindings — every hint key string flows through this so
+   * a user-level rebind (e.g. `"openSettings": "ctrl+p"`) shows up live
+   * in the bottom bar without us hard-coding `'ctrl+o'`.
+   */
+  keybindings: KeyBindings;
+  /**
+   * Number of currently-dispatching tool calls. Drives the
+   * `<cancelToolCall> cancel tool` chip in the `busy` hint row — without
+   * it, the binding stays inert and there's no point advertising the
+   * shortcut. Falls back to "no chip" when no tools are in flight
+   * (model is mid-stream but hasn't dispatched yet).
+   */
+  inFlightToolCount: number;
+  /**
+   * Number of currently-active skills. Drives the footer's
+   * `✦ N skill(s)` chip on the chat screen — purely informational,
+   * a passive surface for "tool restrictions are in effect". Hidden
+   * when `0` so the row stays uncluttered for the common case.
+   */
+  activeSkillCount: number;
+  /** Foreground for the skills chip (typically `COLOR.brand`). */
+  skillsChipColor: string;
+  /**
+   * Progress label for the todo chip (`"2/5"` from `todoProgressLabel`), or
+   * `null` to hide it.
+   *
+   * This replaced a full-width bar that printed the in-progress todo's TITLE
+   * ABOVE the prompt. As a `Hint` it inherits the row's click-to-keypress
+   * contract for free (`dispatchHintKey`), so clicking it opens the list the
+   * same way `ctrl+t` does — and it sits below the prompt like every other
+   * control instead of pushing the prompt down.
+   */
+  todoProgress: string | null;
+  /**
+   * Pre-built `↑ vX.Y.Z` chip from `buildUpdateHint(useUpdateCheck())`,
+   * or `null` when no update is available. Always last in the chat-screen
+   * row so it's the first to drop when the terminal narrows.
+   */
+  updateHint: Hint | null;
+  /**
+   * Pre-built prompt-cache toast, non-null only for a few seconds after a
+   * `'cache:break'` hook fired (the host owns the visibility timer and the
+   * severity split): warn-colored `⚡ cache break · <culprit> · +Nk tok · ~$0.48`
+   * for attributable breaks, dim `⚡ cache expired · +Nk tok · ~$0.48` for
+   * byte-stable TTL expiry — routine across human think-time, so it must not
+   * cry wolf. Sits beside `updateHint` at the droppable end of the row: a
+   * transient cost signal, not an action.
+   */
+  cacheBreakHint?: Hint | null;
+  /**
+   * Sessions-screen list scope — `true` when the list spans all
+   * projects. Drives the `tab` hint's label, which advertises the scope
+   * the toggle switches TO. Optional so non-sessions callers can omit it.
+   */
+  sessionsScopeAll?: boolean;
+}
+/**
+ * Build the footer's shortcut hints for the current screen. On the chat
+ * screen the model id rides next to its `ctrl+m` shortcut and the agent
+ * label rides next to `shift+tab`, each in its accent color — the bar
+ * doubles as the status display without needing separate badges. When
+ * the active model exposes reasoning, the `ctrl+m` hint grows a
+ * secondary `/n` chord with the current effort label, surfacing the
+ * effort picker as a discoverable, in-place affordance.
+ */
+declare function buildHints(options: BuildHintsOptions): Hint[];
+/**
+ * Shorten a binding spec for display as a "chord continuation" — the
+ * `/n` after `ctrl+m model` in the chat footer. We only strip the
+ * `ctrl+` prefix so user-customized chords (`alt+n`, `meta+shift+n`)
+ * still render in full. Falls back to the verbatim spec when no
+ * `ctrl+` prefix is found, which keeps the visual contract honest:
+ * the rendered key always matches the bound trigger.
+ */
+declare function shortChord(spec: string): string;
+//#endregion
+//#region src/chat/generate-title.d.ts
+interface GenerateSessionTitleOptions {
+  provider: Provider;
+  /** Model id used for the call. */
+  model: string;
+  /** Conversation history to summarize. Empty → throws synchronously. */
+  turns: readonly SessionTurn[];
+  /**
+   * Cap on how many TRAILING turns to feed the model. Defaults to 10.
+   * The session's opening user turn is always included on top when the
+   * window cuts it off (see `renderTitleTranscript`).
+   */
+  maxTurns?: number;
+  /** Optional cancellation signal — forwarded to the provider's stream. */
+  signal?: AbortSignal;
+}
+/**
+ * Drive the provider's `stream()` once and return a concise title for
+ * the conversation represented by `turns`. Throws when:
+ *   - `turns` contains no text-bearing content (nothing to summarize),
+ *   - the provider stream completes with no output text,
+ *   - the model answered the transcript instead of labeling it (see
+ *     {@link cleanTitle}) — a failed generation the caller retries,
+ *   - `signal` is aborted (rethrown verbatim).
+ *
+ * Output is trimmed, single-line, with surrounding quotes / trailing
+ * punctuation stripped, and truncated to `TITLE_MAX_CHARS`.
+ */
+declare function generateSessionTitle({
+  provider,
+  model,
+  turns,
+  maxTurns,
+  signal
+}: GenerateSessionTitleOptions): Promise<string>;
+/**
+ * Decide whether a session is ready for one-shot automatic titling.
+ *
+ * Returns `true` iff the conversation has had its first exchange — at
+ * least two turns, i.e. the opening user message plus the assistant's
+ * reply (this is exactly the "N turns" count the sessions list shows) —
+ * AND no explicit title has been set yet. An existing `metadata.title`
+ * (a previous auto-generation, or a manual title from the session-details
+ * "generate title" action) is never clobbered.
+ *
+ * Pure + total. The runtime layers its own "is one already in flight?"
+ * and "is a provider picked?" guards on top of this; the predicate only
+ * encodes the content-level rule so it can be pinned in tests without a
+ * mock provider — same rationale as the exported {@link cleanTitle}.
+ */
+declare function shouldAutoGenerateTitle(turns: readonly SessionTurn[], metadata?: Record<string, unknown>): boolean;
+/**
+ * Normalize a model-generated title into the shape we want to persist:
+ *
+ *   - Collapse internal whitespace + take the first line only (some
+ *     models emit "Title: foo\n\nReason: …" despite instructions).
+ *   - Strip surrounding quotes, a leading `Title:` / `title -` preamble,
+ *     and a `user:` / `assistant:` role prefix echoed from the transcript
+ *     — repeatedly, in any nesting order.
+ *   - Reject placeholders and answer-shaped replies (see
+ *     {@link ANSWER_SHAPED_OPENER}) by throwing.
+ *   - Strip trailing punctuation (`.`, `!`, `?`) — titles read cleaner
+ *     without it.
+ *   - Truncate to `TITLE_MAX_CHARS` with a trailing `…` when over.
+ *
+ * Exported as `cleanTitle` so tests can pin the normalization rules
+ * without going through a mock provider.
+ */
+declare function cleanTitle(raw: string): string;
+//#endregion
+//#region src/chat/host/signals.d.ts
+/** Caller attribution for approvals raised by subagents. */
+type ApprovalOriginator = {
+  kind: 'parent';
+} | {
+  kind: 'child';
+  label: string;
+};
+/**
+ * Serializable mirror of canonical `ActiveTodosState` — plain arrays so the
+ * payload survives structured clone / JSON without `readonly` friction.
+ */
+interface TodosSnapshot {
+  runId: string | null;
+  todos: TodoItem[];
+  archive: TodoItem[];
+  inProgress: TodoItem | null;
+  tally: TodoTally;
+}
+/**
+ * Project canonical `ActiveTodosState` onto its wire mirror.
+ *
+ * One implementation because the copy is load-bearing, not cosmetic: the arrays
+ * must be detached from the live session's before they cross a process boundary
+ * (or reach another window in-process), and a site that forgot to copy would
+ * hand out a reference that mutates under its reader. Previously open-coded at
+ * each of the broadcast and RPC sites.
+ */
+declare function toTodosSnapshot(state: ActiveTodosState): TodosSnapshot;
+/** Parent-level cancellable tool call or background task. */
+interface RunningWorkItem {
+  kind: 'tool' | 'task';
+  id: string;
+  label: string;
+  startedAt: number;
+  childId?: string;
+}
+/**
+ * Serializable mirror of `PreviewResult` — `readonly` arrays widened so the
+ * payload round-trips without TypeScript friction on the client side.
+ */
+interface SerializedPreview {
+  diffText: string;
+  perHunkDiff: readonly string[];
+  resolution: readonly HunkResolution[];
+  resolvedPayload: EditPayload;
+}
+/**
+ * Wire-safe approval request. Canonical `ApprovalRequest` minus its live
+ * `resolve` callback (kept host-side, keyed by `id`), plus the context a
+ * remote approval surface needs: owning session, safelist cwd, precomputed
+ * safelist suggestions, and the edit preview byproducts.
+ */
+interface WireApprovalRequest extends Omit<ApprovalRequest, 'resolve'> {
+  sessionId: string;
+  cwd: string;
+  suggestedSafelistEntries: string[];
+  edit?: EditPayload;
+  priorContent?: string | null;
+  preview?: SerializedPreview;
+}
+/** Attachment carried alongside the prompt text (base64, no data-URL prefix). */
+interface PromptAttachment {
+  mediaType: string;
+  data: string;
+  name?: string;
+}
+/** `chat.send` options. */
+interface SendOptions {
+  sessionId: string;
+  prompt: string;
+  /** Skill names picked via `/` completion — activated before the run. */
+  activatedSkills?: string[];
+  attachments?: PromptAttachment[];
+  /**
+   * Host-internal wake run: delivers pending background-task notifications
+   * to the model with an empty prompt. Skips the `user-prompt` broadcast
+   * (there is no user message) — mirrors the local TUI's wake semantics.
+   */
+  wake?: boolean;
+}
+/**
+ * Wire-safe summary of an extension-contributed `/` command — the
+ * projection of canonical `Command` (src/chat/commands.ts) minus its
+ * function-valued fields (steps, completeArgs).
+ */
+interface CommandSummary {
+  name: string;
+  description: string;
+  aliases?: string[];
+  /** Grouping label — defaults to the contributing extension's name. */
+  group?: string;
+  /**
+   * `true` when the canonical command declares `completeArgs` — lets a
+   * client wire an arg-completion shim only for commands that actually
+   * complete, instead of firing blind RPCs on every `/name <prefix>`.
+   */
+  hasArgCompletion?: boolean;
+}
+/** Wire-safe projection of canonical `CommandArgSuggestion`. */
+interface CommandArgSuggestionSummary {
+  /** Text inserted after `/<name> ` on accept. */
+  value: string;
+  /** Display label. Defaults to `value`. */
+  label?: string;
+  description?: string;
+}
+/** Host settings — canonical `Settings` plus the extension allowlist. */
+type HostSettings = Settings & {
+  enabledExtensions?: readonly string[];
+};
+/** One entry in the shared type-ahead queue. */
+interface QueuedItem {
+  id: string;
+  text: string;
+}
+/**
+ * Live per-session presence — which sessions have attached windows and
+ * what state they're in. Drives the session list's "active" scope and
+ * per-row status icons. A session appears here when it has ≥1 attached
+ * window, a run in flight, or pending HITL state.
+ */
+interface SessionPresence {
+  sessionId: string;
+  /** Number of windows currently attached (watching) this session. */
+  windows: number;
+  /** A run is executing right now. */
+  running: boolean;
+  /** Pending approval or interaction — awaiting user input somewhere. */
+  attention: boolean;
+}
+/** Pending interaction row as returned by `interactions.list`. */
+interface PendingInteraction {
+  sessionId: string;
+  request: InteractionRequest;
+  live: boolean;
+}
+/**
+ * The single push channel. Chat stream signals mirror the agent loop hooks;
+ * interaction/approval signals carry the HITL queues so every window renders
+ * the same pending state; `sessions:changed` keeps session lists in sync
+ * across windows.
+ */
+type HostSignal = {
+  kind: 'run:start';
+  sessionId: string;
+  runId: string;
+} | {
+  kind: 'run:end';
+  sessionId: string;
+  runId: string;
+  ok: boolean;
+  error?: string;
+}
+/**
+ * A turn finished. `usage` carries the loop-reported token/cost figures
+ * that drive footer gauges (context size = prompt-side tokens of the
+ * LAST parent turn; cost accrues across parent + child turns).
+ */
+| {
+  kind: 'turn:end';
+  sessionId: string;
+  turnId: string;
+  childId?: string;
+  depth?: number;
+  usage?: TurnUsage;
+}
+/**
+ * `echo: true` marks host-generated SEND/STEER echoes of the user's own
+ * message. Clients that already render the prompt locally (the GUI's
+ * enriched append) drop echo-tagged signals; command-module
+ * user-prompts are never echoes and always render.
+ */
+| {
+  kind: 'event';
+  sessionId: string;
+  event: StreamEvent;
+  echo?: boolean;
+} | {
+  kind: 'compacting:start';
+  sessionId: string;
+}
+/**
+ * Live token estimate for an in-flight compaction summary. Throttled by the
+ * loop, so this is a low-rate progress tick rather than a stream.
+ *
+ * Without it a daemon-mode window shows a static "Compacting…" with no
+ * indication of progress — a compaction of a large transcript can run for
+ * minutes, which is indistinguishable from a hang.
+ */
+| {
+  kind: 'compacting:progress';
+  sessionId: string;
+  estOutputTokens: number;
+}
+/**
+ * Prompt turns that just persisted, reduced to the fields needed to bind a
+ * live `user-prompt` event to its turn id (see {@link PromptTurnRef}).
+ *
+ * Deliberately NOT the full `SessionTurn`: those carry every content block,
+ * including base64 image/document payloads, which would be megabytes per
+ * prompt to ship for the sake of an id. Without this a prompt sent from a
+ * daemon-attached window is unselectable — no hover, edit, or delete — until
+ * the run-end transcript replace.
+ */
+| {
+  kind: 'prompt-turns';
+  sessionId: string;
+  refs: readonly PromptTurnRef[];
+}
+/**
+ * `effectiveTokens` (success only) is the loop's post-compact context
+ * estimate — windows drop their footer ctx gauge to it immediately
+ * instead of waiting for the next turn's usage.
+ */
+| {
+  kind: 'compacting:end';
+  sessionId: string;
+  ok: boolean;
+  effectiveTokens?: number;
+} | {
+  kind: 'model:fallback';
+  sessionId: string;
+  from: {
+    provider: string;
+    model: string;
+  };
+  to: {
+    provider: string;
+    model: string;
+  };
+} | {
+  kind: 'work:snapshot';
+  sessionId: string;
+  items: RunningWorkItem[];
+} | {
+  kind: 'todos:snapshot';
+  sessionId: string;
+  snapshot: TodosSnapshot;
+} | {
+  kind: 'interaction:request';
+  sessionId: string;
+  request: InteractionRequest;
+  live: boolean;
+} | {
+  kind: 'interaction:resolved';
+  sessionId: string;
+  requestId: string;
+} | {
+  kind: 'approval:request';
+  request: WireApprovalRequest;
+}
+/**
+ * An approval left the pending queue (answered or denied in bulk) — every
+ * OTHER window clears its surface. The window that resolved it already
+ * knows; the signal makes the queue converge everywhere else.
+ */
+| {
+  kind: 'approval:resolved';
+  sessionId: string;
+  requestId: string;
+  decision: ApprovalDecision;
+} | {
+  kind: 'sessions:changed';
+  op: 'create' | 'update' | 'delete';
+  sessionId: string;
+}
+/**
+ * Settings were written through the host (`settings.set`) — every window
+ * applies the new state so settings UIs converge without a restart.
+ * Windows that persist settings themselves must treat this as
+ * authoritative for the delivered snapshot.
+ */
+| {
+  kind: 'settings:changed';
+  settings: HostSettings;
+}
+/**
+ * Another window edited the session's shared prompt draft. The daemon
+ * EXCLUDES the originating peer from this fan-out, so applying it can
+ * never fight the local cursor — clients apply unconditionally
+ * (last-writer-wins whole-text replacement). Empty `text` clears the
+ * draft (broadcast when any window submits the prompt).
+ */
+| {
+  kind: 'draft:changed';
+  sessionId: string;
+  text: string;
+  shell?: boolean;
+}
+/**
+ * The shared draft's composing ATTACHMENTS changed (paste/drop/remove in
+ * any window). Payloads ride along so a remote window can submit the
+ * shared draft attachments-and-all. Same origin-exclusion as text.
+ */
+| {
+  kind: 'draft:attachments';
+  sessionId: string;
+  attachments: PromptAttachment[];
+}
+/**
+ * The session's shared transcript-search state changed (mode entered /
+ * exited, query edited) in another window. Same origin-exclusion and
+ * last-writer-wins contract as the draft — every window on the session
+ * shows the same filtered transcript.
+ */
+| {
+  kind: 'search:changed';
+  sessionId: string;
+  active: boolean;
+  query: string;
+}
+/**
+ * The daemon resolved another window's inline-autocomplete query
+ * (`suggest.resolve`). Excludes the requesting peer (it already has
+ * the result from its RPC reply). Receivers mirror the ghost ONLY
+ * when their live buffer still equals `basis` — the standard
+ * staleness guard; otherwise discard.
+ */
+| {
+  kind: 'suggest:changed';
+  sessionId: string;
+  seq: number;
+  basis: string;
+  caret: number;
+  suggestion: string | null;
+  candidates?: string[];
+}
+/**
+ * The daemon-side agent's active-skill set changed (`skills_use` /
+ * run-end deactivation). Windows mirror it into their skill chips.
+ */
+| {
+  kind: 'skills:snapshot';
+  sessionId: string;
+  active: string[];
+}
+/**
+ * A daemon-side MCP server needs (re-)authentication. Windows surface
+ * the badge; the interactive login flow itself runs in whichever window
+ * the user triggers it from (tokens land in the shared credential
+ * store; the daemon reconnects on the next agent rebuild).
+ */
+| {
+  kind: 'mcp:auth';
+  sessionId: string;
+  name: string;
+  reason: string;
+}
+/**
+ * Provider retry in progress (rate-limit / overload / silent stall) —
+ * drives the footer's "retrying n/m" indicator. `source` is `'parent'`
+ * or the retrying child's id; the indicator clears when that source
+ * streams again or the run ends.
+ */
+| {
+  kind: 'stream:retry';
+  sessionId: string;
+  attempt: number;
+  max: number;
+  source: string;
+}
+/**
+ * A retried stream reached a terminal state for `source` (`'parent'` or a
+ * child id) — clear that source's retry indicator.
+ *
+ * Distinct kind rather than a nullable `attempt` so the two states stay
+ * unambiguous on the wire. Consumers also clear at run end as a backstop;
+ * this exists for the mid-run case, where a subagent's stream fails while
+ * the parent run continues and the indicator would otherwise stick.
+ */
+| {
+  kind: 'stream:retry:cleared';
+  sessionId: string;
+  source: string;
+}
+/**
+ * Which `SYSTEM.md` override (if any) the host folded into this session's
+ * system prompt, emitted at agent-build time.
+ *
+ * The prompt is composed where the agent is built — in the daemon, not in
+ * the window — so a window cannot derive this by probing its own disk: it
+ * may have a different cwd, and `userInstructionsScope` is the daemon's.
+ * Windows need it to tell "no override on disk" apart from "override in
+ * force", which is the difference between doctrine the user wrote and
+ * doctrine they think they replaced. `shadowed` carries precedence losers
+ * so the Instructions surface can mark them inactive.
+ */
+| {
+  kind: 'system-md';
+  sessionId: string;
+  file: SystemMdFile | null;
+  shadowed: readonly SystemMdFile[];
+}
+/**
+ * A cache-prefix break was detected for this session's last request — the
+ * footer chip names the culprit dimension and the re-billed prefix size.
+ * Detection is per-agent closure state inside the loop, so in daemon mode
+ * only the daemon can observe it. Cost pricing stays window-side (it needs
+ * only the provider key and the token count).
+ */
+| {
+  kind: 'cache:break';
+  sessionId: string;
+  info: CacheBreakInfo;
+}
+/**
+ * Presence snapshot — recomputed and fanned out whenever a window
+ * attaches/detaches or any tracked session's run/HITL state changes.
+ * Full snapshot (the set is small: only live sessions appear).
+ */
+| {
+  kind: 'presence:changed';
+  sessions: SessionPresence[];
+}
+/**
+ * Daemon-side extension HUD snapshot (status lines + banners). Extension
+ * hooks run in the daemon in daemon mode, so their `ctx.tui.setStatus` /
+ * `setBanner` writes happen there — windows overlay this state under
+ * their local HUD (local entries win per extension name).
+ */
+| {
+  kind: 'hud:state';
+  statuses: Record<string, {
+    text: string;
+    loader: boolean;
+  }>;
+  banners: Record<string, string[]>;
+} /** Daemon-side extension `ctx.tui.notify` — a one-shot transcript line. */ | {
+  kind: 'hud:notify';
+  extension: string;
+  text: string;
+  tone: 'info' | 'warn' | 'error';
+}
+/**
+ * The session's type-ahead queue changed (message queued while a run is
+ * in flight, drained by the host on run end, pushed early, or dropped).
+ * Broadcast to EVERY peer including the origin — the queue box is shared
+ * state and all windows render the same list.
+ */
+| {
+  kind: 'queue:changed';
+  sessionId: string;
+  items: QueuedItem[];
+}
+/**
+ * Extension bus message (`ctx.bus.emit`, `'ipc'` permission). PRIVATE
+ * per `extensionId`: receivers re-inject into the SAME extension's local
+ * subscribers only and drop ids they haven't registered. `extensionId`
+ * is stamped by the emitting host from the registration identity —
+ * never caller-supplied. `payload` is capped at 64 KiB serialized
+ * (enforced at emit and again at the daemon boundary); `(nonce, seq)`
+ * feeds the receivers' per-extension dedupe window (self-echo through a
+ * second connection of the same process, duplicate deliveries). `nonce`
+ * is the emitter's per-process random id (additive — absent from older
+ * peers, which dedupe on seq alone).
+ */
+| {
+  kind: 'extension:signal';
+  extensionId: string;
+  sessionId?: string;
+  payload: JsonValue;
+  seq: number;
+  nonce?: string;
+};
+//#endregion
+//#region src/chat/host/environment.d.ts
+/**
+ * Durable persistence for pending safe-mode approvals so a request raised
+ * before a crash still surfaces after restart. Implementations: sqlite repo
+ * (GUI), JSON file (daemon), in-memory no-op (tests).
+ */
+interface PendingApprovalsStore {
+  insert: (request: WireApprovalRequest) => void;
+  delete: (id: string) => void;
+  clear: () => void;
+  list: () => WireApprovalRequest[];
+}
+interface ChatHostEnvironment {
+  /**
+   * Force the cross-process run guard + marker heartbeat ON regardless of
+   * the `useDaemon` setting. The daemon sets this: `zidane attach` /
+   * `zidane daemon` are explicit opt-ins that run sessions with the
+   * setting off, making the daemon a multi-writer surface by
+   * construction. Embedders with a single writer (the GUI's in-process
+   * host) leave it unset and inherit the setting-gated behavior.
+   */
+  multiProcess?: boolean;
+  /** Push a signal to every connected client. Must never throw. */
+  broadcast: (signal: HostSignal) => void;
+  /** Canonical session store shared with every other surface. */
+  store: SessionStore;
+  /** Current user settings — read fresh on every call. */
+  readSettings: () => HostSettings;
+  /**
+   * cwd-aware resolved runtime config (providers, agents, extensions).
+   * Hosts own caching/invalidation — the engine calls this per agent build.
+   */
+  runtimeConfig: (cwd: string) => Promise<ResolvedConfig>;
+  /** Base user-data directory (`~/.zidane`) — safelist, tool-result blobs. */
+  userDataDir: () => string;
+  /** Re-apply provider auth env right before building a provider. */
+  applyAuthEnv?: () => void;
+  /** OAuth credential store for MCP servers, when the host supports MCP auth. */
+  mcpCredentialStore?: () => McpCredentialStore;
+  /** Durable pending-approval persistence. Defaults to in-memory only. */
+  approvalsPersistence?: PendingApprovalsStore;
+  /** Opt-in verbose stream logging to the host console. */
+  debugStream?: boolean;
+}
+//#endregion
+//#region src/chat/host/approvals.d.ts
+interface ApprovalRequestInput {
+  sessionId: string;
+  cwd: string;
+  tool: string;
+  input: Record<string, unknown>;
+  edit?: EditPayload;
+  priorContent?: string | null;
+  preview?: SerializedPreview;
+  originator?: ApprovalOriginator;
+}
+interface ApprovalHub {
+  request: (input: ApprovalRequestInput) => Promise<ApprovalDecision>;
+  resolve: (id: string, decision: ApprovalDecision) => void;
+  denyAll: (sessionId?: string) => void;
+  listPending: () => WireApprovalRequest[];
+  /** Register ghost resolvers for approvals persisted by a prior process lifetime. */
+  rehydrate: () => void;
+}
+/** In-memory fallback when the host doesn't provide durable persistence. */
+declare function createMemoryApprovalsStore(): PendingApprovalsStore;
+declare function createApprovalHub(options: {
+  broadcast: (signal: HostSignal) => void; /** Base dir for the shared `projects.json` safelist (`~/.zidane`). */
+  userDataDir: () => string;
+  persistence?: PendingApprovalsStore;
+}): ApprovalHub;
+//#endregion
+//#region src/chat/host/compaction.d.ts
+interface CompactionEntry {
+  sessionId: string;
+  cwd: string;
+  agent: Agent;
+  providerKey: ProviderKey;
+  providerDescriptor?: ProviderDescriptor;
+  model: string;
+  compactionController?: AbortController;
+}
+/**
+ * Run `compactConversation` against the session's current turns, persist
+ * the resulting summary as a new turn, and emit a compact-summary stream
+ * event. Brackets the in-flight window with `compacting:start` /
+ * `compacting:end` signals.
+ */
+declare function runCompaction(entry: CompactionEntry, broadcast: (signal: HostSignal) => void, store: SessionStore): Promise<void>;
+//#endregion
+//#region src/chat/host/edit-outcome-ledger.d.ts
+interface PendingAnnotation {
+  outcomes: readonly EditOutcome[];
+  originalInput: Record<string, unknown>;
+  originalPayload: EditPayload;
+}
+declare class EditOutcomeLedger {
+  private _entries;
+  stash(callId: string, payload: PendingAnnotation): void;
+  /** Read + remove the entry for `callId`. `null` when no stash exists. */
+  drain(callId: string): PendingAnnotation | null;
+  /** Non-removing peek — used by `tool:before` to paint events without consuming the stash. */
+  peek(callId: string): PendingAnnotation | null;
+  /** Drop entry without reading — used by `tool:error` (no transform on throw path). */
+  discard(callId: string): void;
+  /** Clear every entry — called on `agent:done` and session disposal. */
+  clear(): void;
+}
+//#endregion
+//#region src/chat/host/interactions.d.ts
+interface InteractionHub {
+  /** Build the `requestInteraction` callback bound to one session. */
+  requestInteractionFor: (sessionId: string) => (request: InteractionRequest) => Promise<InteractionResponse>;
+  respond: (requestId: string, response: InteractionResponse) => {
+    ok: boolean;
+  };
+  cancel: (requestId: string, reason?: string) => {
+    ok: boolean;
+  };
+  list: (sessionId?: string) => PendingInteraction[];
+  rehydrate: (sessionId: string) => Promise<PendingInteraction[]>;
+  /**
+   * Answer every pending MODEL interaction with the canonical automatic
+   * response — the runtime half of `interactionMode: 'skip'`. Flipping the
+   * setting mid-run must not leave modals that were raised under `ask` hanging
+   * for an answer the new mode says nobody will give. Host-synthesized prompts
+   * are left alone (local code is awaiting a real decision on those). Returns
+   * the number resolved.
+   */
+  resolveAutomatically: (sessionId?: string) => number;
+  /** Drop every pending interaction for a session (session delete / dispose). */
+  clearSession: (sessionId: string) => void;
+}
+declare function createInteractionHub(options: {
+  broadcast: (signal: HostSignal) => void;
+  store: SessionStore;
+  /**
+   * Live settings read. The hub consults `interactionMode` itself at rehydrate
+   * time rather than taking an `automatic` flag from each caller: the daemon
+   * dispatch, the GUI adapter, and the host's own activation path all
+   * rehydrate, and a flag any one of them could omit is exactly how a policy
+   * silently stops applying on one surface.
+   */
+  readSettings: () => Settings;
+}): InteractionHub;
+//#endregion
+//#region src/chat/host/orchestration.d.ts
+interface CreateWorkerParams {
+  /** Directory the worker runs in — the headline use case. */
+  cwd: string;
+  /** First prompt. Sent immediately; the worker starts working on creation. */
+  prompt: string;
+  title?: string;
+  agentId?: string;
+  providerKey?: string;
+  modelId?: string;
+  /**
+   * Whether the worker finishing should start a run on the main. Default
+   * `true`. `false` = fire-and-forget: the report still lands in the main's
+   * history and transcript, the main just is not woken for it.
+   */
+  wake?: boolean;
+}
+interface WorkerRow {
+  sessionId: string;
+  title: string;
+  cwd: string;
+  running: boolean;
+  /** Created by this main (vs. a session the human started elsewhere). */
+  worker: boolean;
+  /** `blocked` = a pending approval or question no one has answered. */
+  state: 'idle' | 'running' | 'blocked';
+  /** Last persisted change, epoch ms. */
+  updatedAt: number;
+  /** Total turns in the session. */
+  turns: number;
+}
+/** What the main's `read` verb returns — a projection, not a transcript. */
+interface WorkerSummary extends WorkerRow {
+  /** Last assistant text, trimmed to a few hundred chars. */
+  lastMessage: string | null;
+  turns: number;
+}
+interface Orchestration {
+  /** The single observation seam. Called by the engine from `broadcast`. */
+  onSignal: (signal: HostSignal) => void;
+  /** Current main session id, or `null` when the feature is off / none exists. */
+  mainId: () => Promise<string | null>;
+  /** Create the main if the setting is on and none exists. Idempotent. Directory-less by design. */
+  ensureMain: () => Promise<string | null>;
+  createWorker: (mainId: string, params: CreateWorkerParams) => Promise<string>;
+  /** Other sessions, newest first, capped (default {@link DEFAULT_LIST_LIMIT}). */
+  list: (mainId: string, limit?: number) => Promise<WorkerRow[]>;
+  /**
+   * Directories with ongoing work, most recent first, capped — the main's
+   * system-prompt briefing (see `renderProjectsBriefing`). Empty when off.
+   */
+  projects: (limit?: number) => Promise<ProjectBrief[]>;
+  read: (sessionId: string) => Promise<WorkerSummary | null>;
+  /** Is `sessionId` a worker this main CREATED? (Lineage, not permission.) */
+  isWorkerOf: (mainId: string, sessionId: string) => Promise<boolean>;
+  /** May `mainId` act on `sessionId`? Any existing non-main session. */
+  canOrchestrate: (mainId: string, sessionId: string) => Promise<boolean>;
+  /**
+   * New prompt to a worker (queued if mid-run). Rejects non-workers. `wake`
+   * (default `true`) sets whether the main is woken when the run finishes.
+   */
+  send: (mainId: string, sessionId: string, prompt: string, wake?: boolean) => Promise<void>;
+  /** Guidance into a worker's current run at its next boundary. Rejects non-workers. */
+  steer: (mainId: string, sessionId: string, message: string) => Promise<void>;
+  /** Interrupt a worker's run. Rejects non-workers. */
+  cancel: (mainId: string, sessionId: string) => Promise<void>;
+  /**
+   * The last `limit` turns of a session as plain text (`role: text`), oldest
+   * first. The drill-down behind `read`'s one-line `lastMessage`: enough to
+   * judge a worker's work without opening it.
+   */
+  transcript: (mainId: string, sessionId: string, limit?: number) => Promise<string>;
+}
+//#endregion
+//#region src/chat/host/engine.d.ts
+/**
+ * Instructions-tab payload. Mirrors the TUI's `getContextSegments` contract so
+ * both settings surfaces render identical rows and identical explanations for
+ * why a `SYSTEM.md` override can or cannot apply.
+ */
+interface ContextSegmentsReport {
+  segments: readonly ContextSegment[];
+  /** Always true here: the host only answers for a live (or buildable) agent. */
+  live: boolean;
+  /** False for host-supplied profiles, which carry their own system prompt. */
+  canOverrideSystem: boolean;
+  /** `'profile'` = picked profile supplies its own prompt; `'scope'` = `userInstructionsScope` excludes user files. */
+  overrideBlockedBy?: 'profile' | 'scope';
+  /** A `SYSTEM.md` on disk that lost precedence — surfaced so edits to it don't look ignored for no reason. */
+  shadowedSystemPath?: string;
+}
+interface ChatHost {
+  /** HITL hubs — exposed so transports can route respond/list/rehydrate calls. */
+  interactions: InteractionHub;
+  approvals: ApprovalHub;
+  sendPrompt: (opts: SendOptions) => Promise<{
+    runId: string;
+  }>;
+  interrupt: (sessionId: string) => void;
+  steer: (sessionId: string, message: string) => void;
+  followUp: (sessionId: string, message: string) => void;
+  /** Steer when a run is active, start a fresh run otherwise. */
+  pushQueued: (sessionId: string, message: string, activatedSkills?: string[]) => Promise<{
+    delivered: 'steer' | 'send' | 'command' | 'queued';
+  }>;
+  /** Wire-safe `/` command catalog for a client's completion popover. */
+  listCommands: (cwd: string) => Promise<CommandSummary[]>;
+  /** Argument suggestions for `/name <prefix>` — best-effort, empty on failure. */
+  completeCommandArgs: (cwd: string, name: string, argsPrefix: string) => Promise<CommandArgSuggestionSummary[]>;
+  /**
+   * Shared type-ahead queue — host-owned so every window renders and
+   * manipulates the same list (`queue:changed` fan-out). `queueAdd`
+   * queues while a run is in flight and sends immediately otherwise;
+   * the host drains FIFO at run end.
+   */
+  queueAdd: (sessionId: string, text: string, activatedSkills?: string[], attachments?: PromptAttachment[]) => Promise<{
+    delivered: 'queued' | 'sent';
+  }>;
+  queueRemove: (sessionId: string, id: string) => boolean;
+  queueList: (sessionId: string) => QueuedItem[];
+  /**
+   * The `SYSTEM.md` override composing this session's prompt, for windows
+   * attaching to an ALREADY-WARM agent (the `system-md` signal only fires at
+   * agent build). `null` file = none applied; `null` result = no live agent,
+   * in which case the next build will broadcast.
+   */
+  sessionSystemMd: (sessionId: string) => {
+    file: SystemMdFile | null;
+    shadowed: readonly SystemMdFile[];
+  } | null;
+  queuePushNow: (sessionId: string, id: string) => Promise<{
+    delivered: 'steer' | 'send' | 'missing';
+  }>;
+  isSessionRunning: (sessionId: string) => boolean;
+  /** Sessions with a live in-memory agent, with their run state (presence). */
+  listLiveSessions: () => Array<{
+    sessionId: string;
+    running: boolean;
+  }>;
+  /**
+   * The live in-memory turns for a session with an active agent — fresh
+   * even mid-run (the store lags at turn boundaries). `null` when no
+   * agent is live. Read-only by contract.
+   */
+  getLiveTurns: (sessionId: string) => readonly SessionTurn[] | null;
+  /**
+   * The live in-memory `Session` for a session with an active agent, or
+   * `null`. For IN-PROCESS embedders only — the GUI's `!` shell runner
+   * appends turns through the live `Session` so `Session.save()` /
+   * compaction's `replaceTurns` never erase a raw store append the
+   * in-memory snapshot didn't see. Not wire-exposable.
+   */
+  getLiveSession: (sessionId: string) => Session | null;
+  /** True when ANY session has a live run, in-flight compaction, or tracked work. */
+  hasActiveWork: () => boolean;
+  listRunningWork: (sessionId: string) => RunningWorkItem[];
+  cancelRunningWork: (sessionId: string, id: string | 'all', reason?: string) => Promise<boolean>;
+  getTodosSnapshot: (sessionId: string) => ActiveTodosState | null;
+  /**
+   * Apply a user todo edit through the live agent's `Session` — the one
+   * `todowrite` reads. `null` when no agent is live (caller falls back to a
+   * store-level write) or when no run owns a todo slot yet.
+   */
+  setTodos: (sessionId: string, items: readonly TodoItem[]) => Promise<ActiveTodosState | null>;
+  /**
+   * Create a session in the shared store and return its id. The one factory
+   * shared by the daemon, the embedded GUI host, and orchestration.
+   */
+  createSession: (params: {
+    cwd: string;
+    title?: string;
+    agentId?: string;
+    providerKey?: string;
+    modelId?: string;
+    fallbacks?: readonly ModelFallbackTarget[];
+    extensionEdit?: boolean;
+  }) => Promise<string>;
+  /** Main-session orchestration — see `./orchestration.ts`. */
+  orchestration: Orchestration;
+  /**
+   * Apply a metadata-only patch through the live in-memory `Session` when
+   * one is hosting the session (safe during a run). Returns `false` when no
+   * live session exists — the caller should fall back to a store-level
+   * write. See the implementation for the data-loss rationale.
+   */
+  patchLiveSessionMeta: (sessionId: string, patch: Record<string, unknown>) => Promise<boolean>;
+  /**
+   * Live-session-aware agent re-label: patches the LIVE document when the
+   * host holds one (saving the live doc is safe — it carries the run's
+   * appended turns; a stale-copy save would clobber them and a later live
+   * save would silently revert the label) and persists it. Returns false
+   * when no live session exists — callers fall back to a store patch,
+   * which is safe because idle sessions have no concurrent writer.
+   */
+  setLiveSessionAgentId: (sessionId: string, agentId: string) => Promise<boolean>;
+  /**
+   * Retire the live agent so the next run rebuilds on freshly-patched
+   * metadata (model / agent swap). Deferred to run end while a run is in
+   * flight, so a swap never aborts a run mid-stream for other windows.
+   */
+  disposeAgentForRebuild: (sessionId: string) => void;
+  getContextBreakdown: (sessionId: string) => Promise<ContextBreakdown | null>;
+  /**
+   * Every chunk of text in the session's system prompt, with provenance — the
+   * Instructions tab's data. Sibling of `getContextBreakdown` and built from
+   * the same `ActiveRun` inputs so the two views describe the same assembly.
+   * `null` when no agent can be built for the session.
+   */
+  getContextSegments: (sessionId: string) => Promise<ContextSegmentsReport | null>;
+  /**
+   * Seed a user-scope `SYSTEM.md` from the doctrine currently in effect for
+   * the session, and return its path for the caller to open in an editor.
+   * Refuses (throws) when an override could never apply — a host-supplied
+   * profile, or a `userInstructionsScope` that excludes user files — rather
+   * than writing a file that would be silently ignored. No-op when the file
+   * already exists (the path is still returned).
+   */
+  createSystemOverride: (sessionId: string) => Promise<{
+    path: string;
+    created: boolean;
+  }>;
+  compactSessionNow: (sessionId: string) => Promise<void>;
+  /** Tear down one session's live agent + pending HITL state. */
+  disposeSession: (sessionId: string) => void;
+  /** Drain every session — call before process exit or config invalidation. */
+  shutdown: () => void;
+}
+declare function createChatHost(env: ChatHostEnvironment): ChatHost;
+//#endregion
+//#region src/chat/host/helpers.d.ts
+declare function readFileSafe(path: string): Promise<string>;
+/** Resolve a workspace-relative path against the session's `cwd`. Absolute paths pass through. */
+declare function resolveCwdPath(cwd: string, p: string): string;
+/**
+ * Gate-time `extractEditPayload` wrapper — same as `tool:before` but
+ * without the prior-content second pass for `write_file`. The gate
+ * only needs the payload shape (hunk count, paths) to drive the
+ * approval surface; the diff resolver works against the freshly-read
+ * `priorContent` passed to `previewEditPayload` directly.
+ */
+declare function extractEditPayloadForGate(name: string, input: Record<string, unknown>): EditPayload | undefined;
+/**
+ * Strip readonly markers so the `PreviewResult` survives structured-clone
+ * and JSON transports. Field-for-field copy — the resolver output is
+ * already JSON-safe primitives.
+ */
+declare function serializePreview(preview: PreviewResult): SerializedPreview;
+//#endregion
+//#region src/chat/mcp-auth-state.d.ts
+/**
+ * Per-server MCP OAuth status tracking, decoupled from the renderer.
+ *
+ * The TUI keeps a `Record<serverName, McpAuthStatus>` so it can render a
+ * "needs-auth" / "authorizing" / "error" badge in the MCP picker. The
+ * status map is driven entirely by hooks fired from the agent's MCP
+ * bootstrap + the interactive `loginMcpServer` flow — the reducer below
+ * is pure, makes no FS or network calls, and is shared between the live
+ * TUI store and the test harness.
+ *
+ * Status lifecycle:
+ *
+ *   idle ──mcp:connect──▶  authed
+ *                         (bootstrap succeeded with stored tokens)
+ *
+ *   idle ──mcp:auth:required──▶ needs-auth
+ *                              (bootstrap saw no/invalid tokens)
+ *
+ *   needs-auth ──login()──▶ authorizing ──mcp:auth:url──▶ authorizing(url)
+ *                                       ──mcp:auth:success──▶ authed
+ *                                       ──mcp:auth:error──▶ error
+ *
+ *   any         ──logout──▶ idle
+ *
+ * Multiple servers progress through the lifecycle independently; the map
+ * is keyed by `McpServerConfig.name`.
+ */
+type McpAuthStatus = {
+  kind: 'idle';
+} | {
+  kind: 'needs-auth';
+  reason: 'no-tokens' | 'auto-promoted';
+} | {
+  kind: 'authorizing';
+  url?: string;
+} | {
+  kind: 'authed';
+} | {
+  kind: 'error';
+  error: string;
+} | {
+  kind: 'bootstrap-error';
+  error: string;
+};
+/**
+ * Map of server name → status. `idle` is the implicit default for any
+ * server NOT present in the map, so the renderer treats `undefined` as
+ * `{ kind: 'idle' }` and the map can stay sparse.
+ */
+type McpAuthStateMap = Readonly<Record<string, McpAuthStatus>>;
+/**
+ * Events the reducer accepts. Names mirror the agent hooks 1:1 plus two
+ * UI-only verbs (`login:start` / `login:cancel`) so the renderer can
+ * optimistically flip a row to `authorizing` before the SDK has emitted
+ * `mcp:auth:url` — useful when the loopback callback is slow to bind.
+ */
+type McpAuthEvent = {
+  type: 'auth-required';
+  name: string;
+  reason: 'no-tokens' | 'auto-promoted';
+} | {
+  type: 'auth-url';
+  name: string;
+  url: string;
+} | {
+  type: 'auth-success';
+  name: string;
+} | {
+  type: 'auth-error';
+  name: string;
+  error: string;
+} | {
+  type: 'bootstrap-error';
+  name: string;
+  error: string;
+} | {
+  type: 'connected';
+  name: string;
+} | {
+  type: 'login:start';
+  name: string;
+} | {
+  type: 'login:cancel';
+  name: string;
+} | {
+  type: 'logout';
+  name: string;
+} | {
+  type: 'reset';
+  name: string;
+};
+/**
+ * Apply one event to the state map. Pure, immutable — returns a new map
+ * with only the affected key reassigned.
+ *
+ * State transitions are simple "last write wins"; we don't gate (e.g.) a
+ * `login:start` from overriding `authorizing` because the loop layer
+ * never doubles those up — interactive login is serialized in the TUI.
+ */
+declare function reduceMcpAuth(state: McpAuthStateMap, event: McpAuthEvent): McpAuthStateMap;
+/** Convenience getter — treats `undefined` as `idle`. */
+declare function getMcpAuthStatus(state: McpAuthStateMap, name: string): McpAuthStatus;
+//#endregion
+//#region src/chat/mcp-auth-context.d.ts
+/**
+ * Mount once near the top of the React tree (above `ModalRoot`). Children
+ * use `useMcpAuthState()` to read and `useMcpAuthDispatch()` to fire events.
+ */
+declare function McpAuthProvider({
+  children
+}: {
+  children: ReactNode;
+}): import("react").JSX.Element;
+declare function useMcpAuthState(): McpAuthStateMap;
+declare function useMcpAuthDispatch(): (event: McpAuthEvent) => void;
+//#endregion
+//#region src/chat/mcp-credentials.d.ts
+declare function mcpCredentialsPath(dataDir: string): string;
+/**
+ * Build a file-backed `McpCredentialStore`. All per-server reads / writes
+ * funnel through the single `mcp-credentials.json` file — this keeps
+ * concurrent flows for different servers from clobbering each other since
+ * each save reads-modifies-writes the full file atomically.
+ *
+ * Two flows for the same server name CAN race (last write wins). MCP OAuth
+ * flows are user-driven and serial in practice (one login modal at a time),
+ * so this is acceptable; a per-server file split + cross-process lock would
+ * be required to handle a multi-process scenario.
+ */
+declare function createFileMcpCredentialStore(dataDir: string): McpCredentialStore;
+/**
+ * Convenience patches for individual sub-fields. The provider class uses
+ * these so a `saveTokens` call doesn't have to round-trip `clientInformation`
+ * + `discoveryState` it never touched.
+ */
+declare function patchMcpCredential(store: McpCredentialStore, name: string, patch: Partial<McpCredentialEntry>): void;
+//#endregion
+//#region src/chat/mcp-rows.d.ts
+/**
+ * One row in the flattened MCP settings list. Three kinds:
+ *
+ *   - `'server'`     — server header with the chevron + checkbox +
+ *                      transport detail. Always present.
+ *   - `'tool'`       — checkbox + description for a tool advertised
+ *                      by the parent server. Present only when the
+ *                      server is expanded AND its tool cache is
+ *                      populated.
+ *   - `'tool-empty'` — placeholder shown when an expanded server
+ *                      has no cached tool list yet (first launch
+ *                      before any session has bootstrapped the
+ *                      server). Lets the renderer surface a
+ *                      one-line "send a prompt to populate" hint
+ *                      WITHOUT changing the server's expand
+ *                      affordance.
+ */
+type VisibleMcpRow = {
+  kind: 'server';
+  entry: DiscoveredMcp;
+} | {
+  kind: 'tool';
+  serverName: string;
+  tool: McpToolSchema;
+} | {
+  kind: 'tool-empty';
+  serverName: string;
+};
+/**
+ * Flatten a server catalog plus the per-server expanded set into the
+ * visible-row list a renderer cycles through.
+ *
+ *   - `catalog`         — filtered / ordered server list (post-search,
+ *                         post-allow-list).
+ *   - `expanded`        — names of servers whose tool list is open.
+ *                         Servers not in this set render as a single
+ *                         server-header row.
+ *   - `toolsByServer`   — per-server full tool catalog (from
+ *                         `chat/mcp-tools-cache.ts`). Missing key →
+ *                         `'tool-empty'` placeholder under the
+ *                         expanded server.
+ */
+declare function buildVisibleMcpRows(catalog: readonly DiscoveredMcp[], expanded: ReadonlySet<string>, toolsByServer: Record<string, readonly McpToolSchema[]>): VisibleMcpRow[];
+/**
+ * Server name a row "belongs to" for catalog / toggle / auth lookups.
+ * For a server row that's its own name; for tool / tool-empty rows
+ * it's the parent server's name.
+ */
+declare function parentServerName(row: VisibleMcpRow): string;
+/**
+ * Index in `rows` of the server header for the given parent name. `-1`
+ * when not present. Used by collapse handlers to snap the cursor up
+ * to the parent BEFORE shrinking the row list — otherwise the cursor
+ * would land on whichever sibling row now occupies the same flat
+ * index.
+ */
+declare function indexOfServerRow(rows: readonly VisibleMcpRow[], parentName: string): number;
+//#endregion
+//#region src/chat/mcp-tool-toggle.d.ts
+interface McpToolToggleSet {
+  /** Live set of ENABLED tool names — `Set` for O(1) `has`. */
+  enabledSet: ReadonlySet<string>;
+  /** Flip one tool on/off; persists immediately via `setSetting`. */
+  toggle: (toolName: string) => void;
+}
+/**
+ * Bind a single MCP server's per-tool toggle to
+ * `Settings.disabledMcpTools[serverName]`.
+ *
+ * `catalog` is the FULL list of tools the server advertises (i.e. the
+ * cached `listTools()` payload from `chat/mcp-tools-cache.ts`). The
+ * hook needs it both to render `enabledSet` (every catalog tool not in
+ * the persisted deny-list) and to garbage-collect stale deny-list
+ * entries on every write.
+ */
+declare function useMcpToolToggleSet(opts: {
+  serverName: string;
+  catalog: readonly McpToolSchema[];
+}): McpToolToggleSet;
+/**
+ * Bind every server in `catalogByServer` to its own per-tool toggle in
+ * a single hook call. Returns a `serverName → McpToolToggleSet` map.
+ *
+ * Use this when a host needs handlers for multiple servers at once
+ * (the TUI's MCP settings panel keyboard dispatcher is the canonical
+ * example) — calling {@link useMcpToolToggleSet} in a `for` / `.map`
+ * over a dynamic catalog would change the hook-call order whenever a
+ * server is added or removed, violating React's rules-of-hooks. This
+ * hook calls `useMemo` exactly once regardless of server count.
+ *
+ * Servers absent from `catalogByServer` get no entry in the result.
+ * The persisted deny-list still keeps their entries on disk — they
+ * just stay invisible to this consumer until the catalog re-includes
+ * them.
+ */
+declare function useMcpToolToggleMap(opts: {
+  catalogByServer: Record<string, readonly McpToolSchema[]>;
+}): Record<string, McpToolToggleSet>;
+/**
+ * Pure factory shared by both hook flavors. Captures `persistedDenyAll`
+ * + `setDisabledMcpTools` at the call site so toggle handlers stay
+ * referentially stable across renders that don't touch the underlying
+ * settings entry — important for `useKeyboard` to avoid re-binding on
+ * every catalog change.
+ *
+ * Exported for direct use by non-React consumers (CLI, GUI shells)
+ * that want the same write semantics without the hook plumbing.
+ */
+declare function buildToolToggle(args: {
+  serverName: string;
+  catalogNames: readonly string[];
+  persistedDenyAll: Settings['disabledMcpTools'];
+  setDisabledMcpTools: (next: Settings['disabledMcpTools']) => void;
+}): McpToolToggleSet;
+//#endregion
+//#region src/chat/mcp-tools-cache.d.ts
+/**
+ * One server's cached entry.
+ *
+ * - `tools` — verbatim copy of the raw `tools/list` payload (pre any
+ *   `disabledTools` / `toolFilter` filtering). The settings UI ranges
+ *   over this to render the full server surface; the host applies its
+ *   own deny-list on top via `Settings.disabledMcpTools` (see
+ *   `buildMcpServers` in `mcps-discovery.ts`).
+ * - `updatedAt` — ms-epoch of the bootstrap that populated this entry.
+ *   Useful for "last seen N hours ago" affordances and for cache
+ *   eviction policies a host might layer on later.
+ * - `transport` — informational only; lets the UI distinguish a stdio
+ *   server's tool list from an http server with the same name in
+ *   "stale catalog" warnings.
+ */
+interface CachedMcpToolList {
+  tools: McpToolSchema[];
+  updatedAt: number;
+  transport: 'stdio' | 'sse' | 'streamable-http';
+}
+/**
+ * `serverName → catalog`. Map shape on disk so adding / removing
+ * servers is an O(1) JSON edit instead of an array rewrite.
+ */
+type McpToolsCache = Record<string, CachedMcpToolList>;
+/**
+ * Resolve the on-disk cache path under a host's data directory. Exposed
+ * for tests + advanced hosts that want to inspect / delete the file
+ * without re-implementing the path convention.
+ */
+declare function mcpToolsCachePath(dataDir: string): string;
+/**
+ * Best-effort cache read. Returns `{}` when the file is missing, when
+ * JSON.parse rejects, or when the top-level shape isn't a plain object —
+ * a corrupt cache must never crash the host on startup.
+ *
+ * Per-entry shape validation is light (presence of an array `tools`):
+ * deeper validation would lock the cache to a single zidane version,
+ * which is the opposite of what a long-lived cache wants. Entries that
+ * survive the light check feed back through `McpToolSchema`'s `unknown`
+ * `inputSchema` so downstream readers stay tolerant of upstream churn.
+ */
+declare function loadMcpToolsCache(opts: {
+  dataDir: string;
+}): McpToolsCache;
+/**
+ * Atomic full-cache write. Used by {@link subscribeMcpToolsCache} after
+ * each upsert. Failures bubble up as the underlying `writeFileAtomic`
+ * error — the caller logs under `ZIDANE_DEBUG` and swallows.
+ */
+declare function saveMcpToolsCache(opts: {
+  dataDir: string;
+  cache: McpToolsCache;
+}): void;
+/**
+ * Drop entries for one or more servers, or wipe the cache when no
+ * server is named. Idempotent — entries that aren't present are
+ * silently skipped. Returns the resulting cache so callers can refresh
+ * any in-memory mirror without re-reading from disk.
+ *
+ * Intended for a future "rescan server" affordance in the settings UI
+ * (clear → trigger a real bootstrap → cache repopulates on the
+ * `mcp:tools:list` hook).
+ */
+declare function clearMcpToolsCache(opts: {
+  dataDir: string;
+  serverNames?: readonly string[];
+}): McpToolsCache;
+/**
+ * Subscribe to `mcp:tools:list` and persist every successful bootstrap
+ * into the on-disk cache. Returns an unsubscribe function — call it
+ * during agent teardown so a long-lived host (Settings modal that
+ * outlives one agent) doesn't accumulate stale subscribers.
+ *
+ * Each write loads the current cache, upserts the named entry, then
+ * atomic-writes the full file. The read-modify-write is safe under
+ * Node single-threaded event loop semantics — concurrent bootstraps in
+ * the same process serialize through the hook bus.
+ *
+ * Optional `onChange` callback fires synchronously after every
+ * successful disk write with the entry that was just upserted. Lets a
+ * React host trigger a state refresh without polling the disk.
+ *
+ * Write failures are swallowed (logged under `ZIDANE_DEBUG`): the cache
+ * is an accelerator, not a correctness boundary. If the disk is full
+ * the agent run still works — the settings UI just shows stale data
+ * until the next successful write.
+ */
+declare function subscribeMcpToolsCache(hooks: Hookable<AgentHooks>, opts: {
+  dataDir: string;
+  onChange?: (entry: {
+    name: string;
+  } & CachedMcpToolList) => void;
+}): () => void;
+/**
+ * Force-refresh the on-disk tools cache by opening a transient MCP
+ * connection to every server, capturing the `mcp:tools:list` hook on
+ * the way through, and closing the connection immediately. The
+ * underlying `connectMcpServers` runs every server's bootstrap in
+ * parallel, so the wall-clock cost collapses to the slowest server.
+ *
+ * Two design choices worth noting:
+ *
+ *   - **Shared hook bus.** The caller passes the SAME `Hookable`
+ *     instance that has the cache subscriber wired (typically
+ *     `agent.hooks` after `subscribeMcpToolsCache(agent.hooks, …)`
+ *     ran). That way `mcp:tools:list` fires on the bus the
+ *     subscriber is listening to and the cache lands on disk
+ *     without a separate write path.
+ *   - **Transient, NOT shared with the live agent.** The connection
+ *     opened here is closed immediately. The agent's own MCP
+ *     connection is untouched, so a refresh never disrupts an
+ *     in-flight tool call.
+ *
+ * The function intentionally swallows per-server failures (they're
+ * already surfaced via `mcp:bootstrap:end ok: false` for any host
+ * that wired the listener). The Promise resolves once every server's
+ * bootstrap settles, success or otherwise.
+ */
+declare function refreshMcpToolsCatalog(opts: {
+  servers: readonly McpServerConfig[];
+  hooks: Hookable<AgentHooks>;
+  /**
+   * Same OAuth-provider factory the agent's bootstrap uses. Required
+   * for OAuth-tagged servers — without it those servers fire
+   * `mcp:auth:required` and skip, and their tools never refresh.
+   */
+  buildAuthProvider?: (config: McpServerConfig) => OAuthClientProvider | undefined;
+}): Promise<void>;
+//#endregion
+//#region src/chat/mcps-write.d.ts
+type McpConfigScope = 'project' | 'user';
+/**
+ * Resolve the CANONICAL write target for a scope — always the
+ * `.{prefix}/mcps.json` flavor, never `.agents` (we don't own that
+ * convention) and never `mcp.json` (Cursor's spelling is read-compat
+ * only).
+ */
+declare function mcpsWritePath(scope: McpConfigScope, opts?: {
+  cwd?: string;
+  home?: string;
+  prefix?: string;
+}): string;
+interface UpsertMcpResult {
+  /** The file written. */
+  path: string;
+  /** `updated` when an entry of the same name was replaced, else `added`. */
+  action: 'added' | 'updated';
+}
+/**
+ * Upsert `entry` (matched by `name`) into the mcps config at `filePath`.
+ * Preserves the existing file's shape and every field the writer doesn't
+ * own; creates a canonical flat-array file when none exists. Throws on
+ * malformed JSON — silently rewriting a broken file the user is mid-edit
+ * on would destroy their work.
+ */
+declare function upsertMcpServer(filePath: string, entry: McpServerConfig): UpsertMcpResult;
+interface RemoveMcpResult {
+  /** The file rewritten. */
+  path: string;
+}
+/**
+ * Remove the entry named `name` from the mcps config at `filePath`,
+ * preserving the file's shape and everything else in it — the removal
+ * counterpart of {@link upsertMcpServer}. Throws when the file is
+ * missing, malformed, an unrecognized shape, or has no entry of that
+ * name (the caller shows the message on the settings op line; silently
+ * "succeeding" on a no-op would lie about what happened).
+ */
+declare function removeMcpServer(filePath: string, name: string): RemoveMcpResult;
+//#endregion
+//#region src/chat/model-chain-metadata.d.ts
+interface ModelFallbackTarget {
+  providerKey: ProviderKey;
+  modelId: string;
+}
+/**
+ * Assemble the `metadata.modelChain` value for a model pick — the full
+ * canonical chain when at least one valid fallback survives filtering,
+ * `undefined` for a single-model pick (metadata merges JSON-serialize,
+ * so `undefined` REMOVES a previously persisted chain).
+ */
+declare function modelChainMetadata(providerKey: ProviderKey, modelId: string, fallbacks: readonly ModelFallbackTarget[] | undefined): ModelChainEntry[] | undefined;
+/**
+ * Validated fallback tail for list rows/pickers — head-matched against
+ * the session's persisted primary, unregistered providers kept (the
+ * caller filters against its own registry when it has one).
+ */
+declare function sessionModelFallbacks(metadata: Record<string, unknown> | undefined): ModelFallbackTarget[] | undefined;
+//#endregion
+//#region src/chat/oauth.d.ts
+declare function supportsOAuth(descriptor: ProviderDescriptor): boolean;
+/** True when the provider's OAuth flow needs the user to paste a code back into the TUI (no loopback callback). */
+declare function oauthUsesManualCodePaste(descriptor: ProviderDescriptor): boolean;
+interface OAuthFlowOptions {
+  /** Called when the provider emits its login URL — typically right after the callback server starts. */
+  onUrl: (url: string, instructions?: string) => void;
+  /**
+   * Called when the provider needs a free-form input from the user (paste-the-code flows,
+   * step-up confirmations, etc.). Mirrors pi-ai's `OAuthLoginCallbacks.onPrompt` verbatim
+   * so callers don't lose `placeholder` / `allowEmpty` hints. Required for any provider
+   * with `usesCallbackServer: false` (e.g. Anthropic Claude Pro/Max).
+   */
+  onPrompt?: (prompt: OAuthPrompt) => Promise<string>;
+  /**
+   * Called when the provider initiates a device-code flow (e.g. GitHub Copilot).
+   * Surface `userCode` + `verificationUri` so the user can complete the flow in
+   * the browser. Required by pi-ai's `OAuthLoginCallbacks` since 0.75.5 — built-in
+   * Anthropic / OpenAI Codex providers don't fire it today, but third-party
+   * descriptors can.
+   */
+  onDeviceCode?: (info: OAuthDeviceCodeInfo) => void;
+  /**
+   * Called when the provider needs the user to pick between multiple flow options
+   * (e.g. browser vs device-code). Return the chosen option `id`, or `undefined`
+   * to cancel. Required by pi-ai's `OAuthLoginCallbacks` since 0.75.5.
+   */
+  onSelect?: (prompt: OAuthSelectPrompt) => Promise<string | undefined>;
+  /** Called with each progress message from the OAuth flow (token exchange, etc.). */
+  onProgress?: (message: string) => void;
+  /** Abort the in-flight login (e.g. user pressed esc). */
+  signal?: AbortSignal;
+}
+/**
+ * Run the OAuth login flow for a provider.
+ *
+ * Returns the OAuth credentials on success; caller persists them via
+ * `setProviderCredential(dataDir, descriptor, { kind: 'oauth', ...credentials })`.
+ * Throws when the descriptor has no `oauthProvider` configured.
+ */
+declare function runOAuthLogin(descriptor: ProviderDescriptor, options: OAuthFlowOptions): Promise<OAuthCredentials>;
+//#endregion
+//#region src/chat/oauth-redirect.d.ts
+/**
+ * Manual OAuth redirect-URL handoff.
+ *
+ * Users who run zidane over SSH (or behind a proxy / firewall that blocks
+ * loopback) can't have the local browser hit the in-process callback server.
+ * They CAN, however, copy the URL their browser was redirected to —
+ * `http://127.0.0.1:<port>/callback?code=...&state=...` — and paste it back
+ * into the TUI.
+ *
+ * The trick: that URL IS the callback our local server is listening on. We
+ * just `fetch()` it ourselves. The server runs in the same process; the
+ * request hits its handler exactly as if a real browser had arrived, the
+ * OAuth promise (`waitForCode` for pi-ai providers, `startOAuthCallback` for
+ * MCP) resolves through the normal happy path, and the upstream flow
+ * continues uninterrupted. No new code path inside the OAuth state machine.
+ *
+ * Defense in depth: we reject anything that isn't a loopback URL — fetching
+ * an arbitrary user-pasted URL from inside the agent process would be a
+ * trivial SSRF.
+ */
+/**
+ * The `redirect_uri` the authorization server was told to come back to,
+ * read out of the authorization URL itself. That's our loopback callback
+ * (`http://127.0.0.1:<port>/callback`) — the UI shows it so an SSH user
+ * knows which address to fish out of the browser's URL bar, and
+ * {@link normalizeRedirectPaste} uses it to rebuild a full callback URL
+ * from a partial paste.
+ *
+ * Returns `null` when the URL doesn't parse or carries no usable
+ * `redirect_uri` — callers degrade to "paste the whole URL".
+ */
+declare function redirectUriFromAuthUrl(authUrl: string): URL | null;
+/**
+ * Widen what counts as an acceptable paste. The happy path is the full
+ * redirect URL out of the browser's address bar, but users on SSH
+ * routinely end up holding less than that: some authorization servers
+ * render the code on the page instead of redirecting, and copying from a
+ * "can't reach this site" error page loses everything but the query.
+ *
+ * Accepted forms, given the authorization URL for context:
+ *
+ *   - `http://127.0.0.1:5123/callback?code=x&state=y` — passthrough (any
+ *     absolute URL is returned untouched; the loopback guard in
+ *     {@link fetchOAuthRedirect} still has final say, so a pasted
+ *     `https://evil.test` is rejected there, not silently rewritten).
+ *   - `/callback?code=x&state=y` — path + query onto the callback origin.
+ *   - `?code=x&state=y` / `code=x&state=y` — query onto the callback URL.
+ *   - `x` — a bare authorization code; `state` is taken from the
+ *     authorization URL when it carried one (the loopback server forwards
+ *     `state` verbatim and the SDK owns verification, so a missing one is
+ *     not fatal). Anything with whitespace inside is prose (an error page
+ *     fragment), not a code — refused with a clearer error than a server
+ *     400 would give.
+ *
+ * Throws when the input can't be turned into a URL — no `authUrl` context
+ * for a partial paste, or an unusable authorization URL.
+ */
+declare function normalizeRedirectPaste(pasted: string, authUrl?: string): string;
+interface FetchOAuthRedirectResult {
+  /** Status code from the callback server. 2xx = success. */
+  status: number;
+  /** Best-effort message extracted from the response body (HTML title or trimmed text). */
+  message?: string;
+}
+/**
+ * Treat `pasted` as a callback-URL paste. Validates it's a loopback URL,
+ * fires a GET, returns the status.
+ *
+ * Pass `authUrl` (the authorization URL currently on screen) to accept
+ * partial pastes — a bare code, a query string, a path — via
+ * {@link normalizeRedirectPaste}. Without it only a full absolute URL is
+ * accepted, which is the pre-existing contract.
+ *
+ * Throws when:
+ *   - `pasted` doesn't parse as a URL (and can't be completed from `authUrl`).
+ *   - The URL host isn't loopback (rejects SSRF).
+ *   - The fetch errors out (network, timeout).
+ *
+ * Returns success/failure for non-2xx responses; the caller decides whether
+ * a 4xx is fatal (state mismatch is a 400 the user can retry from).
+ */
+declare function fetchOAuthRedirect(pasted: string, options?: {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  authUrl?: string;
+}): Promise<FetchOAuthRedirectResult>;
+//#endregion
+//#region src/chat/path-display.d.ts
+/**
+ * @-completion path display formatter.
+ *
+ * The `@`-popover walks the project from the git root so the user sees
+ * the whole tree regardless of where they launched the TUI. The
+ * agent's CWD-resolving tools (`read_file`, `glob`, `edit`, …) read
+ * relative paths against `process.cwd()`, which is frequently a
+ * subdirectory of that root. Emitting the discovery's raw
+ * project-root-relative path into the prompt produces a `<cwd>/<rel>`
+ * miss — the bug this helper exists to close.
+ *
+ * Rule:
+ *
+ *   - File at `cwd` itself → `.`.
+ *   - File under `cwd` (subtree) → forward-slashed CWD-relative,
+ *     no `..`.
+ *   - File above `cwd` but still inside the project → CWD-relative
+ *     with `..` traversal (e.g. `../EDIT_THIS.md`). Shorter and more
+ *     scannable than absolute, and the agent's tools resolve both.
+ *   - File outside the project (input was passed absolute) → returned
+ *     verbatim. Inputs that arrive as project-root-relative strings
+ *     are always inside the project by construction, so this branch
+ *     only kicks in when a direct caller hands the function an
+ *     absolute target.
+ *
+ * Pure, no I/O, deterministic.
+ */
+/**
+ * Convert a project-root-relative path (as emitted by `listProjectFiles`)
+ * into the form the agent's tools — and the user — will actually find
+ * given the current `cwd`.
+ *
+ * Inputs:
+ *   - `projectRelativePath` — forward-slashed, no leading slash. Returned
+ *     verbatim when it's empty or already absolute (defensive — the
+ *     absolute-input branch is the de-facto "outside the project"
+ *     escape; the catalog itself never emits absolute paths).
+ *   - `projectRoot` — absolute path of the discovery anchor.
+ *   - `cwd` — absolute path of `process.cwd()` at the moment of
+ *     insertion.
+ *
+ * Output is always either an absolute path (only when the input arrived
+ * absolute) OR a CWD-relative path. The relative form may include
+ * `../` segments when the target sits above `cwd` within the project,
+ * which keeps cross-tree references short and scannable
+ * (e.g. `../EDIT_THIS.md` instead of `/Users/.../zidane/EDIT_THIS.md`).
+ */
+declare function formatPathForCwd(projectRelativePath: string, projectRoot: string, cwd: string): string;
+//#endregion
+//#region src/chat/project-root.d.ts
+/**
+ * Git root detection — walks parents from `cwd` looking for a `.git`
+ * entry, returning the absolute path of the repo root or `null` when
+ * the search reaches the filesystem root.
+ *
+ * Why parent-walk over `git rev-parse --show-toplevel`:
+ *
+ *   - Zero dependencies (no shell-out, no git binary requirement,
+ *     works even when `git` is missing from `PATH`).
+ *   - Pure-sync, deterministic, easy to test against tmp dirs.
+ *   - Equally fast in practice — most lookups are a single `existsSync`.
+ *
+ * Recognizes `.git` as either:
+ *
+ *   - A directory (standard repo layout).
+ *   - A file containing `gitdir: …` (worktrees + submodules).
+ *
+ * Bare repos (no working tree) are intentionally NOT detected here —
+ * the TUI's data dir contract is "project working tree", and a bare
+ * repo has no working files to scope sessions against.
+ */
+/**
+ * Walk parents of `cwd` looking for a `.git` entry. Returns the
+ * absolute path of the directory containing `.git`, or `null` when no
+ * git repo is found above `cwd`.
+ *
+ * Stops at the filesystem root (`/`) — no infinite loop on `dirname`'s
+ * idempotent root case (`dirname('/')` returns `/`).
+ */
+declare function findGitRoot(cwd?: string): string | null;
+//#endregion
+//#region src/chat/provider-usage.d.ts
+/** How long a snapshot stays fresh. Usage windows move in minutes, not seconds. */
+declare const USAGE_CACHE_TTL_MS = 60000;
+/** Which probe a credential key maps to. */
+type UsageSource = 'claude' | 'codex' | 'grok' | 'openrouter';
+/** The probe for a descriptor, or `null` when it has no usage surface. */
+declare function usageSourceFor(descriptor: ProviderDescriptor): UsageSource | null;
+/** Whether this provider can report subscription usage at all. */
+declare function providerUsageSupported(descriptor: ProviderDescriptor): boolean;
+/**
+ * Drop every cached snapshot. Entries are keyed by credential KEY, not by the
+ * token itself, so signing out and back in (or re-authing to another account)
+ * would otherwise keep serving the previous account's numbers for the rest of
+ * the TTL. The TUI calls this wherever it re-reads credentials.
+ */
+declare function clearProviderUsageCache(): void;
+/** Whether the environment forbids usage probes outright. */
+declare function usageChecksOptedOut(env?: NodeJS.ProcessEnv): boolean;
+interface FetchProviderUsageOptions {
+  /** Ignore (and replace) a still-fresh cached snapshot. */
+  refresh?: boolean;
+}
+/**
+ * Usage for one provider. `null` means there is nothing to show: the provider
+ * has no usage surface, no credential of the kind its probe needs (file or,
+ * for API keys, env), or the environment opted out (see
+ * {@link usageChecksOptedOut}).
+ *
+ * Never rejects. Transport and parse failures land in the snapshot.
+ */
+declare function fetchProviderUsage(dataDir: string, descriptor: ProviderDescriptor, opts?: FetchProviderUsageOptions): Promise<ProviderUsageSnapshot | null>;
+/**
+ * Usage for every registered provider that has both a usage surface and a
+ * usable credential, in registry order. What the panel renders.
+ */
+declare function fetchAllProviderUsage(dataDir: string, registry: Readonly<Record<string, ProviderDescriptor>>, opts?: FetchProviderUsageOptions): Promise<readonly ProviderUsageSnapshot[]>;
+//#endregion
+//#region src/chat/run-end-notice.d.ts
+interface RunEndNotice {
+  notice: NonNullable<StreamEvent['notice']>;
+  text: string;
+}
+/**
+ * Structured stop notice for an abnormal `finishReason`, or `undefined` for a
+ * normal end.
+ *
+ * Normal completions (`stop` / `tool-calls`) and user aborts return
+ * `undefined` — and so does a SUCCESSFUL auto-resume, because recovery ends
+ * the run on `stop`. That is what keeps the notice quiet exactly when the
+ * ceiling was handled rather than hit. `error` runs already surface their own
+ * error event, so a second notice would double-report.
+ */
+declare function runEndNotice(reason: TurnFinishReason | undefined): RunEndNotice | undefined;
+//#endregion
+//#region src/chat/safe-mode.d.ts
+/**
+ * Safe-mode storage + matching for the TUI.
+ *
+ * Lives at `<dataDir>/projects.json` (default `~/.zidane/projects.json`). Each
+ * top-level key is an absolute project directory; the value carries that
+ * project's persisted tool-call `safelist`.
+ *
+ * ```json
+ * {
+ *   "/Users/me/proj-a": { "safelist": ["read_file", "shell:git:*"] }
+ * }
+ * ```
+ *
+ * Two granularities for safelist entries:
+ *   - **bare tool name** — `"read_file"` matches every `read_file` call.
+ *   - **tool + first-arg token + wildcard** — `"shell:git:*"` matches `shell`
+ *     calls whose primary string argument starts with the token `git`
+ *     (followed by whitespace or end-of-string). Modelled on Claude Code's
+ *     `Bash(git:*)` syntax.
+ *
+ * A short list of read-only tools is **implicitly safe** without being
+ * persisted — see {@link IMPLICITLY_SAFE_TOOLS}.
+ */
+interface ProjectEntry {
+  safelist?: string[];
+}
+type ProjectsFile = Record<string, ProjectEntry>;
+/** Resolve `projects.json`'s on-disk path given the TUI data directory. */
+declare function projectsFilePath(dataDir: string): string;
+declare function readProjects(dataDir: string): ProjectsFile;
+declare function writeProjects(dataDir: string, file: ProjectsFile): void;
+/**
+ * Append one or more entries to the safelist for `projectDir`, dedup-aware.
+ * Accepts a single string or a list (a compound shell command needs one
+ * entry per command head — see {@link suggestSafelistEntries}). Writes once
+ * and returns the updated entry list (post-write) so callers can render it
+ * without re-reading. No write happens when every entry already exists.
+ */
+declare function addToSafelist(dataDir: string, projectDir: string, entries: string | readonly string[]): readonly string[];
+/** Read the safelist for one project. Returns `[]` for unknown projects. */
+declare function getSafelist(dataDir: string, projectDir: string): readonly string[];
+/**
+ * Tools that always pass without prompting. Four categories:
+ *
+ *   - **Pure reads** (`read_file`, `list_files`, `glob`, `grep`) — no
+ *     side effects on disk or the model's own state.
+ *   - **Interaction tools** (`ask_user`, `present_plan`) — the call
+ *     itself surfaces a TUI picker the user has to answer, so prompting
+ *     for approval first would mean "approve this prompt before you see
+ *     the prompt": redundant + breaks the flow. The picker IS the gate.
+ *   - **Todos** (`todowrite`, `todoread`) — write to a slot on
+ *     `session.metadata.todos` and nothing else. No shell, no disk, no
+ *     network. The model uses these for checkpointing every few steps;
+ *     a per-call approval prompt would drown the conversation in
+ *     interruptions that buy no safety since the tool's surface is
+ *     read/write on a metadata bag we already trust the agent with.
+ *   - **Skill activation** (`skills_use`) — mutates a small per-agent
+ *     Map of active skills and returns the activated skill's bundled
+ *     instructions (or releases an entry on `mode: "deactivate"`).
+ *     Pure state on the agent — no shell, no disk writes, no network.
+ *     Gating it would also defeat the "model recovers from
+ *     `AgentToolNotAllowedError` by calling
+ *     `skills_use({ mode: "deactivate", name })`" path: a stuck model
+ *     would have to ask the user permission to *unstick* itself on
+ *     every retry. `skills_read` and `skills_run_script` are
+ *     intentionally NOT on this list — the former touches disk and
+ *     the latter executes arbitrary scripts, so both keep going
+ *     through the regular gate.
+ *
+ * Users who want to gate any of these must disable safe-mode entirely
+ * (or fork this list in their own embedding).
+ */
+declare const IMPLICITLY_SAFE_TOOLS: readonly string[];
+/**
+ * Test whether a `{ tool, input }` pair is covered by one safelist entry.
+ *
+ * Supported entry shapes:
+ *   - `"<tool>"` — broad match on tool name.
+ *   - `"<tool>:<token>:*"` — match when the primary arg's first token
+ *     equals `<token>`.
+ *
+ * This function matches a **single command** against a **single entry**.
+ * For shell commands that chain multiple programs (`&&`, `||`, `;`,
+ * `$(…)`, etc.), use {@link isOnSafelist} which parses the full command
+ * and checks every head token independently.
+ *
+ * Entries that don't fit either shape are ignored (forward-compat for
+ * future pattern syntax — readers shouldn't choke on entries written
+ * by a newer version of the TUI).
+ */
+declare function matchesSafelistEntry(entry: string, tool: string, input: Record<string, unknown>): boolean;
+/**
+ * True when a call matches ANY entry in the project's safelist (or is
+ * implicitly safe).
+ *
+ * For `shell` commands, the full command string is parsed into individual
+ * commands (handling `&&`, `||`, `;`, `|`, `$(…)`, backticks, subshells).
+ * Every command head must be covered by at least one safelist entry for
+ * the call to pass. If parsing fails, returns `false` (prompt the user).
+ */
+declare function isOnSafelist(entries: readonly string[], tool: string, input: Record<string, unknown>): boolean;
+/**
+ * Suggest the safelist entries to persist when the user picks "accept and
+ * remember" (or "accept for session") for a `{ tool, input }`. Heuristic:
+ *
+ *   - `shell` → one `shell:<head>:*` per DISTINCT command head, parsing the
+ *     command the SAME way {@link isOnSafelist} matches it (`&&`, `||`, `;`,
+ *     `|`, `$(…)`, subshells, backticks). So `cd dir && cat file` yields
+ *     `["shell:cd:*", "shell:cat:*"]` — persisting the whole set is what
+ *     lets the next identical call skip the gate. A single first-token
+ *     entry would only cover `cd`, so `isOnSafelist`'s `every-head` check
+ *     would fail on `cat` and re-prompt forever.
+ *   - `shell` with an unparseable / empty command → first-token heuristic,
+ *     else the bare tool name.
+ *   - anything else → bare tool name (broad).
+ *
+ * Always returns a non-empty list so the UI has a concrete set to render
+ * and persist.
+ */
+declare function suggestSafelistEntries(tool: string, input: Record<string, unknown>): string[];
+//#endregion
+//#region src/chat/session-cwd.d.ts
+/** Process cwd used for sessions with no folder binding. */
+declare function folderlessCwd(): string;
+/**
+ * Effective process cwd for a persisted session row: the GUI-recorded
+ * `metadata.cwd` when present, else the canonical `projectRoot`
+ * (TUI-created sessions), else the directory-less HOME anchor. Empty
+ * strings count as unset — forks of directory-less sessions persist
+ * `cwd: ''`.
+ */
+declare function resolveSessionCwd(row: {
+  metadata?: Record<string, unknown> | undefined;
+  projectRoot?: string | undefined;
+}): string;
+/**
+ * Map a renderer-supplied scope cwd to the directory the main process
+ * should actually operate in. The renderer signals "no folder" with an
+ * empty string (`SidebarSession.cwd` is `''` for directory-less
+ * sessions); catalogs (@-files, skills, commands, extensions, MCPs)
+ * then root at HOME, matching what the TUI offers when run from `~`.
+ */
+declare function scopeCwd(cwd: string): string;
+//#endregion
+//#region src/chat/settings-context.d.ts
+declare const DEFAULT_SETTINGS: Settings;
+interface SettingsContextValue {
+  settings: Settings;
+  /** Flip a boolean setting in place. Restricted at the type level to boolean-valued keys. */
+  toggle: (key: BooleanSettingKey) => void;
+  /** Write any setting key to a new value. Used by string-valued choice rows. */
+  setSetting: <K extends keyof Settings>(key: K, value: Settings[K]) => void;
+}
+declare function SettingsProvider({
+  initial,
+  onChange,
+  children
+}: {
+  initial: Settings;
+  onChange?: (settings: Settings) => void;
+  children: ReactNode;
+}): import("react").JSX.Element;
+declare function useSettings(): SettingsContextValue;
+/**
+ * Keys of `Settings` whose value type is exactly `boolean`. Used to type
+ * the toggle table so `SETTINGS_TOGGLES.key` only ever points to a
+ * boolean-valued setting — string- and array-valued settings (theme,
+ * enabledSkills, …) live in `SETTINGS_CHOICES` or actions.
+ *
+ * `-?` strips optionality from the mapped output so `Settings[K]` doesn't
+ * silently broaden into `T | undefined` and short-circuit the `extends
+ * boolean` check via `undefined`.
+ */
+type BooleanSettingKey = { [K in keyof Settings]-?: Settings[K] extends boolean ? K : never }[keyof Settings];
+/**
+ * Setting categories — drives the tab grouping in the TUI's
+ * `SettingsModal` and, more importantly, gives any embedder (GUI,
+ * web settings panel, …) a stable taxonomy to bucket settings under
+ * without re-hardcoding the split.
+ *
+ *   - `'agent'` — agent behaviour, capabilities, persistence,
+ *                 data handling, auth. "What zidane DOES."
+ *   - `'ui'`    — display, rendering, theming, animations,
+ *                 chrome density, keybindings. "How zidane LOOKS
+ *                 and feels."
+ *
+ * Borderline calls (`showAllProjects`, `hideSubagentOutput`,
+ * `resumeLastSession`) are documented inline at each row.
+ */
+type SettingsCategory = 'agent' | 'ui';
+interface SettingsCategoryDescriptor {
+  id: SettingsCategory;
+  /** Display label — used by the TUI tab strip + any GUI tab/section header. */
+  label: string;
+  /** One-line gloss the GUI can show as a section subtitle. The TUI omits this. */
+  description: string;
+}
+/**
+ * Ordered list of categories. Display order in any consumer (TUI tabs,
+ * GUI sidebar, settings JSON dump) should match this array — keeps
+ * mental model consistent across surfaces.
+ */
+declare const SETTINGS_CATEGORIES: readonly SettingsCategoryDescriptor[];
+/**
+ * Static description of every togglable setting, in display order. The TUI's
+ * `SettingsModal` and any future GUI settings panel build their row list
+ * from this so labels/descriptions stay in one place.
+ */
+interface SettingsToggle {
+  key: BooleanSettingKey;
+  label: string;
+  description: string;
+  category: SettingsCategory;
+  /**
+   * Another boolean setting this one is meaningless without. Renderers grey
+   * the row out and say so while the requirement is off; the write layer
+   * (`enforceSettingsInvariants`) guarantees the value can never be `true`
+   * while the requirement is `false`, whichever client or file wrote it.
+   */
+  requires?: BooleanSettingKey;
+}
+declare const SETTINGS_TOGGLES: readonly SettingsToggle[];
+/**
+ * Cross-setting invariants, applied at EVERY write.
+ *
+ * Settings are a shared file with three writers (the TUI, the GUI main
+ * process, the daemon) and no lock; a rule enforced in one client is a rule
+ * the others break. So this is the single definition, derived from the
+ * `requires` declarations on the toggle rows themselves — adding a
+ * dependency is one field on one row, and the UI hint and the write-time
+ * guarantee follow from it together.
+ *
+ * Pure and idempotent: returns the same object when nothing changes, so React
+ * state and file writers can short-circuit on identity.
+ */
+/**
+ * Return type of {@link enforceSettingsInvariants}: the input shape with every
+ * boolean setting widened to `boolean`. The function exists to flip toggles,
+ * so a literal `true` from a call-site object literal must not survive into
+ * the result type — it would let `expect(next.x).toBe(false)` fail to compile
+ * against a value that is, in fact, `false`.
+ */
+type WithInvariants<T> = { [K in keyof T]: K extends BooleanSettingKey ? boolean : T[K] };
+declare function enforceSettingsInvariants<T extends Partial<Settings>>(settings: T): WithInvariants<T>;
+/**
+ * String-valued settings that pick between a known set of options. The
+ * `SettingsModal` renders these as one row showing the active label, where
+ * `enter` cycles to the next option (wrapping back to the first). Same
+ * shape any GUI settings panel can consume — render the options array as a
+ * dropdown or segmented control.
+ *
+ * Keep `options` in stable display order; cycling depends on it.
+ */
+interface SettingsChoice<K extends keyof Settings = keyof Settings> {
+  key: K;
+  label: string;
+  description: string;
+  options: readonly {
+    value: Settings[K];
+    label: string;
+  }[];
+  category: SettingsCategory;
+}
+declare const SETTINGS_CHOICES: readonly SettingsChoice[];
+/**
+ * Keys of `Settings` whose value type is exactly `string`. Bounds the
+ * input table's `key` the same way {@link BooleanSettingKey} bounds the
+ * toggle table — a free-text row can only point at a string-valued
+ * setting.
+ */
+type StringSettingKey = { [K in keyof Settings]-?: Settings[K] extends string ? K : never }[keyof Settings];
+/**
+ * Free-text settings edited via a single-line input. The `SettingsModal`
+ * renders these as a row showing the current value (or `placeholder` when
+ * empty); `enter` opens an inline editor. Same shape a GUI can consume as
+ * a text field.
+ */
+interface SettingsInput {
+  key: StringSettingKey;
+  label: string;
+  description: string;
+  /** Shown when the value is empty — also the conventional "default" hint. */
+  placeholder: string;
+  category: SettingsCategory;
+}
+declare const SETTINGS_INPUTS: readonly SettingsInput[];
+//#endregion
+//#region src/chat/skills-discovery.d.ts
+/**
+ * Resolve the default skill scan paths for a project. First-found wins on
+ * collision; earlier entries take precedence.
+ *
+ * Search order — see {@link projectUserPaths}. Non-existent paths are
+ * returned so downstream code can choose whether to create them;
+ * `discoverSkills` itself skips missing dirs without error.
+ */
+declare function defaultSkillScanPaths(opts?: {
+  cwd?: string;
+  home?: string;
+  prefix?: string;
+  /**
+   * Also scan the skill directories other agents maintain (Claude Code,
+   * Codex, Pi) — see `foreign-configs.ts`. Mirrors the
+   * `importForeignConfigs` setting. Appended AFTER the native paths so
+   * first-found-wins keeps zidane's own copies authoritative on name
+   * collisions.
+   */
+  foreignAgents?: boolean;
+  /**
+   * Also scan Ruler skill directories (`.ruler/skills`, project and
+   * XDG-global) — see `ruler-configs.ts`. Mirrors the
+   * `importRulerConfigs` setting; appended last so first-found-wins
+   * keeps both zidane's own and foreign copies authoritative.
+   */
+  ruler?: boolean;
+}): SourcedScanPath[];
+/**
+ * Discover every skill reachable from the default scan paths. Returns
+ * parsed `SkillConfig`s with `name`, `description`, frontmatter, and
+ * lenient-load diagnostics. Pure I/O — does not activate or write.
+ *
+ * `signal` is forwarded to `discoverSkills` so the TUI's directory-watch
+ * effect can cancel a long scan when the user switches `cwd` rapidly.
+ *
+ * Errors during parse are surfaced as `diagnostics` on the returned
+ * skill, not thrown — keeps the picker usable even when a single
+ * SKILL.md is malformed.
+ */
+declare function discoverProjectSkills(opts?: {
+  cwd?: string;
+  home?: string;
+  prefix?: string; /** See {@link defaultSkillScanPaths}. */
+  foreignAgents?: boolean; /** See {@link defaultSkillScanPaths}. */
+  ruler?: boolean;
+  signal?: AbortSignal;
+}): Promise<SkillConfig[]>;
+/**
+ * Map a user-toggled enable list onto the format `createAgent` expects.
+ *
+ * Conventions:
+ *   - `enabled === undefined`  → all discovered skills enabled (default).
+ *   - `enabled === []`         → fully off; the agent will not scan or
+ *                                inject the skills tools.
+ *   - `enabled === [names]`    → allowlist; skills not in the list are
+ *                                left out of the catalog.
+ *
+ * `scan` is the resolved scan-path list (passed through verbatim). Pass
+ * `defaultSkillScanPaths()` for the standard project + user paths, or
+ * supply a host-specific list.
+ */
+declare function buildSkillsConfig(opts: {
+  scan: SourcedScanPath[];
+  enabled?: readonly string[];
+}): SkillsConfig;
+//#endregion
+//#region src/chat/spawn-markers.d.ts
+/**
+ * Wall-clock start + task preview per in-flight child, keyed by spawn id.
+ * Captured at `spawn:before` and read back at `spawn:complete` — drives
+ * the human-readable elapsed suffix on the spawn-end marker
+ * (`done · 42s`) and copies the stable task preview onto the terminal
+ * marker.
+ */
+interface SpawnStartRecord {
+  startedAt: number;
+  task: string;
+  model?: string;
+}
+/**
+ * `spawn-start` marker for a child that just launched. `previewLine`
+ * collapses inline newlines/tabs so the marker stays on one visual row
+ * resumed children carry the label of the run they continue — same text
+ * shape as the reload path.
+ */
+declare function buildSpawnStartEvent(ctx: {
+  id: string;
+  task: string;
+  depth?: number;
+  model?: string;
+  resumesChildId?: string;
+}, startedAt: number): StreamEvent;
+/**
+ * `spawn-end` marker: ` · `-joined optional segments — elapsed wall-clock
+ * time, then USD cost summed across the child's whole turn tree (most
+ * providers don't populate `cost`, so the segment usually collapses; no
+ * "$0.00" lies) — followed by the token usage summary. `timeout` maps to
+ * the `done` tag, matching the TUI.
+ */
+declare function buildSpawnEndEvent(ctx: {
+  id: string;
+  depth?: number;
+  status?: 'completed' | 'aborted' | 'timeout' | 'error';
+  stats: AgentStats;
+}, started: SpawnStartRecord | undefined, now?: number): StreamEvent;
+//#endregion
+//#region src/chat/streaming.d.ts
+interface StreamSource {
+  /** Pass `undefined` / omit for parent-agent events. */
+  childId?: string;
+  /** Nesting depth — 0 for parent, ≥ 1 for subagents. */
+  depth?: number;
+  /**
+   * `SessionTurn.id` this delta belongs to. Tagged onto new events so the
+   * TUI's select-turn mode can group every event from one turn. Stored on
+   * the active bucket and refreshed on every delta so a turn boundary
+   * (`turn:after` flushes the bucket) doesn't carry stale ids forward.
+   */
+  turnId?: string;
+}
+interface StreamBuffer {
+  /** Queue a streaming delta for the next flush tick. */
+  queueStreamDelta: (kind: 'markdown' | 'thinking', delta: string, source?: StreamSource) => void;
+  /** Drain pending deltas immediately, then append a non-streaming event. */
+  appendImmediate: (evt: StreamEvent) => void;
+  /** Drain pending deltas immediately, then transform the event list. */
+  flushAndUpdate: (update: (events: StreamEvent[]) => StreamEvent[]) => void;
+  /** Drain pending deltas without further transformation. */
+  flush: () => void;
+  /** Cancel any pending flush and drop buffered deltas (on session teardown). */
+  reset: () => void;
+  /**
+   * Resolves once the pacer is idle — no bucket holds queued content and
+   * no post-drain updater is pending. Resolves immediately when already
+   * idle (the batched / `smoothStreaming: false` path never queues, so
+   * this is zero-cost there). A safety timeout (default
+   * {@link WHEN_DRAINED_TIMEOUT_MS}) resolves anyway if the ticker
+   * wedges — measured as a full window with NO drain progress, so a
+   * long response that keeps typing re-arms it and never snaps — and
+   * callers gating a transcript convergence on the drain can never
+   * dead-lock. `reset()` also releases every waiter — the backlog it
+   * drops would otherwise never drain.
+   */
+  whenDrained: (timeoutMs?: number) => Promise<void>;
+}
+interface StreamBufferOptions {
+  /**
+   * Returns `true` to drip-feed buffered text at the smooth typewriter
+   * cadence, `false` to drain everything per tick (batched mode — the
+   * legacy behaviour). Called on every tick, so flipping the user setting
+   * takes effect on the next drain.
+   */
+  getSmooth?: () => boolean;
+  /**
+   * Display-memory bound applied on every drain commit (see
+   * {@link capTranscriptEvents}): above this many events the oldest are
+   * trimmed at a turn boundary and replaced with a cumulative
+   * "… N earlier items hidden" marker event. Rendered events hold live
+   * renderables/native buffers, so an unbounded buffer OOMs long
+   * sessions (~0.13MB RSS per event measured in the TUI).
+   *
+   * Default {@link MAX_TRANSCRIPT_EVENTS}. Pass `null` to disable and
+   * receive the full, unbounded event array (pre-5.13 behavior) — e.g.
+   * a host that renders a virtualized list or exports events verbatim.
+   */
+  maxTranscriptEvents?: number | null;
+}
+declare function useStreamBuffer(setEvents: Dispatch<SetStateAction<StreamEvent[]>>, options?: StreamBufferOptions): StreamBuffer;
+//#endregion
+//#region src/chat/system-md.d.ts
+/** A discovered `SYSTEM.md`. */
+interface SystemMdFile {
+  path: string;
+  source: 'project' | 'user';
+  contents: string;
+}
+/** Result of {@link discoverSystemMd}. */
+interface SystemMdResult {
+  /**
+   * The winning override, or `null` when no `SYSTEM.md` exists (the built-in
+   * doctrine then applies unchanged).
+   */
+  file: SystemMdFile | null;
+  /**
+   * Files that exist but lost to `file` on precedence. Non-empty only when the
+   * user has both a project and a user `SYSTEM.md`. Surfaced so the UI can mark
+   * them as inactive instead of leaving the user wondering why edits to one of
+   * them changed nothing.
+   */
+  shadowed: readonly SystemMdFile[];
+}
+interface DiscoverSystemMdOptions {
+  /** Discovery cwd. Default: `process.cwd()`. */
+  cwd?: string;
+  /** User home directory. Default: `os.homedir()`. */
+  home?: string;
+  /** Storage prefix. Leading dot tolerated. Default: `'.zidane'`. */
+  prefix?: string;
+  /**
+   * Which scopes may contribute an override — the same
+   * {@link AgentsMdScope} the host applies to `AGENTS.md`, so one setting
+   * governs both surfaces:
+   *   - `'none'`    — no override, ever. Short-circuits before any FS probe.
+   *   - `'user'`   — only `~/.{prefix}/SYSTEM.md`. The repo's file is IGNORED,
+   *                   which is the whole point of the setting: it is how a user
+   *                   says "do not trust this checkout".
+   *   - `'project'` — only `<root>/SYSTEM.md`.
+   *   - `'both'`   — union, project winning (default).
+   *
+   * Previously a boolean that only implemented `'none'`, so `'user'` still let a
+   * repo-root `SYSTEM.md` replace the entire doctrine — exactly the case the
+   * setting exists to prevent.
+   */
+  scope?: AgentsMdScope;
+}
+/**
+ * Absolute path of the USER-scope `SYSTEM.md` — the file the TUI creates when
+ * the user asks for an override and none exists yet.
+ *
+ * Exported so the host doesn't hardcode the layout and can't drift from what
+ * discovery actually reads.
+ */
+declare function userSystemMdPath(opts?: {
+  home?: string;
+  prefix?: string;
+}): string;
+/**
+ * Whether a USER-scope `SYSTEM.md` would be loaded under `scope`.
+ *
+ * Mirrors the candidate filter in {@link discoverSystemMd} so a host can ask
+ * "would writing `~/.{prefix}/SYSTEM.md` accomplish anything?" without
+ * re-deriving the rule and drifting from it. `'project'` excludes the user
+ * candidate and `'none'` skips discovery altogether, so under either setting
+ * creating that file is a silent no-op.
+ */
+declare function userScopeOverridesLoad(scope: AgentsMdScope | undefined): boolean;
+/**
+ * Find the active `SYSTEM.md` override, if any.
+ *
+ * Project paths anchor at the git root when one exists above `cwd`, else at
+ * `cwd` — the same anchor as skills / mcps / AGENTS.md discovery, so all four
+ * surfaces agree on what "this project" means.
+ *
+ * Tolerant: an unreadable or empty file is treated as absent (logged under
+ * `ZIDANE_DEBUG`) and the next candidate gets its turn. Never throws — this
+ * runs on the session-activation path.
+ *
+ * Candidates are filtered by {@link DiscoverSystemMdOptions.scope}, mirroring
+ * how `discoverAgentsMd` builds its own list.
+ */
+declare function discoverSystemMd(opts?: DiscoverSystemMdOptions): SystemMdResult;
+/**
+ * Seed contents for a freshly created `SYSTEM.md` override, built from the
+ * built-in doctrine.
+ *
+ * Seeding with the real doctrine (rather than an empty file) means creating the
+ * override is a behavioral no-op until the user edits it. An empty seed would
+ * silently delete every line of doctrine the moment the file appeared, making
+ * the agent measurably worse with no visible cause.
+ *
+ * `currentSystem` should be DOCTRINE ONLY — callers pass
+ * `splitSystemPrompt(doctrineOnlySystem()).static`, which excludes both the
+ * generated `<env>` block (rebuilt per turn) and the `AGENTS.md` block. Baking
+ * the latter in would duplicate it, since it is re-appended below the override
+ * on every compose.
+ *
+ * `scope` is the active `userInstructionsScope`; it decides whether the seed's
+ * precedence note is true — see {@link projectScopeOverridesLoad}.
+ */
+declare function renderSystemMdSeed(currentSystem: string, scope?: AgentsMdScope): string;
+//#endregion
+//#region src/chat/theme-context.d.ts
+declare function ThemeProvider({
+  theme,
+  children
+}: {
+  theme: Theme;
+  children: ReactNode;
+}): import("react").JSX.Element;
+declare function useTheme(): Theme;
+/** Color palette only — equivalent to `useTheme().colors`. */
+declare function useColors(): ThemeColors;
+/** Select-row styling — equivalent to `useTheme().select`. */
+declare function useSelectStyle(): ThemeSelect;
+/** Panel / surface backgrounds — equivalent to `useTheme().surfaces`. */
+declare function useSurfaces(): ThemeSurfaces;
+/** Raw syntax style table — `useTheme().syntax`. Renderer converts to its native style type. */
+declare function useSyntaxStyles(): SyntaxStyles;
+//#endregion
+//#region src/chat/themes/catppuccin.d.ts
+declare const CATPPUCCIN_MOCHA: Theme;
+declare const CATPPUCCIN_MACCHIATO: Theme;
+declare const CATPPUCCIN_FRAPPE: Theme;
+declare const CATPPUCCIN_LATTE: Theme;
+//#endregion
+//#region src/chat/themes/gruvbox.d.ts
+declare const GRUVBOX_DARK: Theme;
+declare const GRUVBOX_LIGHT: Theme;
+//#endregion
+//#region src/chat/themes/vaporwave.d.ts
+declare const VAPORWAVE_THEME: Theme;
+//#endregion
+//#region src/chat/todo-anchor.d.ts
+interface ActiveTodoAnchorOptions {
+  enabled?: boolean;
+  maxItems?: number;
+  heading?: string;
+}
+declare function renderActiveTodoAnchor(todos: readonly TodoItem[], options?: ActiveTodoAnchorOptions): string;
+/**
+ * Optional chat-layer hook that keeps the live `todowrite` list visible in the
+ * dynamic system prompt. It reads only live todos, never the archive, so an
+ * auto-cleared completed plan is not reintroduced on later turns.
+ *
+ * ## Prompt-cache cost — read before enabling
+ *
+ * This writes per-turn state into the system prompt, and the system prompt sits
+ * ABOVE the entire conversation in the provider's cache prefix (Anthropic hashes
+ * tools → system → messages, cumulatively). So every time the rendered anchor
+ * changes by a single byte, the whole transcript stops matching the cache and
+ * re-bills at the cache-write rate; only `tools` and the static system block
+ * survive.
+ *
+ * That is an acceptable trade only because the anchor changes *rarely* — once
+ * per `todowrite`, which in practice is a small fraction of turns. Two rules
+ * follow, and breaking either one turns that occasional cost into a per-turn
+ * one:
+ *
+ *  1. Never add anything to the anchor that ticks on its own — no counters, no
+ *     timestamps, no elapsed times, no per-turn indices.
+ *  2. The render must stay a pure function of the todo list.
+ *     `renderActiveTodoAnchor` is deterministic today, so identical todos emit
+ *     identical bytes; keep it that way. Note this does NOT cover reordering —
+ *     todo order is semantically meaningful (it is the plan), so a reorder is
+ *     a real state change and costs one re-bill like any other `todowrite`.
+ *
+ * Moving the anchor onto the newest message instead does NOT avoid this: it is
+ * wire-only, so the message that carried last turn's anchor re-renders without
+ * it, and the prefix diverges at that point just the same. The only injection
+ * that is genuinely free is one persisted into the transcript as immutable
+ * history.
+ */
+declare function createActiveTodoAnchorHooks(options?: ActiveTodoAnchorOptions): AgentHookMap;
+//#endregion
+export { ProjectsFile as $, shortChord as $n, PerformSelfUpdateOptions as $r, createFileMcpCredentialStore as $t, buildSkillsConfig as A, buildPlanSystem as Ai, ChatHostEnvironment as An, ClaudeCopyResult as Ar, sessionModelFallbacks as At, SettingsCategoryDescriptor as B, RunningWorkItem as Bn, BuildUpdateHintOptions as Br, loadMcpToolsCache as Bt, userSystemMdPath as C, INTERACTION_GUIDANCE as Ci, PendingAnnotation as Cn, setProviderCredential as Cr, OAuthFlowOptions as Ct, SpawnStartRecord as D, SUBAGENT_GUIDANCE as Di, ApprovalRequestInput as Dn, isReservedCredKey as Dr, supportsOAuth as Dt, useStreamBuffer as E, PLAN_MODE_DOCTRINE_NO_PROMPTS as Ei, ApprovalHub as En, alternateCredKey as Er, runOAuthLogin as Et, SETTINGS_CATEGORIES as F, HostSettings as Fn, hasClaudeCodeSetup as Fr, removeMcpServer as Ft, StringSettingKey as G, WireApprovalRequest as Gn, RunUpdateCommandResult as Gr, McpToolToggleSet as Gt, SettingsInput as H, SerializedPreview as Hn, buildUpdateHint as Hr, refreshMcpToolsCatalog as Ht, SETTINGS_CHOICES as I, HostSignal as In, importFromClaudeCode as Ir, upsertMcpServer as It, folderlessCwd as J, cleanTitle as Jn, DetectPackageManagerOptions as Jr, useMcpToolToggleSet as Jt, enforceSettingsInvariants as K, toTodosSnapshot as Kn, runUpdateCommand as Kr, buildToolToggle as Kt, SETTINGS_INPUTS as L, PendingInteraction as Ln, tryOpenBrowser as Lr, CachedMcpToolList as Lt, discoverProjectSkills as M, ChatTurnsReadToolOptions as Mi, ApprovalOriginator as Mn, ClaudeImportSummary as Mr, RemoveMcpResult as Mt, BooleanSettingKey as N, chatReferenceTokensForPrompt as Ni, CommandArgSuggestionSummary as Nn, ClaudeSessionImportResult as Nr, UpsertMcpResult as Nt, buildSpawnEndEvent as O, TOKEN_DISCIPLINE_DOCTRINE as Oi, createApprovalHub as On, ConfigProvider as Or, ModelFallbackTarget as Ot, DEFAULT_SETTINGS as P, createChatTurnsReadTool as Pi, CommandSummary as Pn, countClaudeSessionFiles as Pr, mcpsWritePath as Pt, ProjectEntry as Q, buildHints as Qn, PerformInPlaceUpdateOptions as Qr, parentServerName as Qt, SETTINGS_TOGGLES as R, PromptAttachment as Rn, bootProfileEnabled as Rr, McpToolsCache as Rt, userScopeOverridesLoad as S, IDENTITY_PREFIX as Si, EditOutcomeLedger as Sn, setPreferredCredential as Sr, redirectUriFromAuthUrl as St, StreamSource as T, PLAN_MODE_DOCTRINE as Ti, runCompaction as Tn, ALTERNATE_CRED_KEY_SUFFIX as Tr, oauthUsesManualCodePaste as Tt, SettingsProvider as U, SessionPresence as Un, useUpdateCheck as Ur, saveMcpToolsCache as Ut, SettingsChoice as V, SendOptions as Vn, UseUpdateCheckOptions as Vr, mcpToolsCachePath as Vt, SettingsToggle as W, TodosSnapshot as Wn, RunUpdateCommandOptions as Wr, subscribeMcpToolsCache as Wt, scopeCwd as X, shouldAutoGenerateTitle as Xn, PackageManagerCommand as Xr, buildVisibleMcpRows as Xt, resolveSessionCwd as Y, generateSessionTitle as Yn, InPlaceUpdateResult as Yr, VisibleMcpRow as Yt, IMPLICITLY_SAFE_TOOLS as Z, BuildHintsOptions as Zn, PackageManagerId as Zr, indexOfServerRow as Zt, DiscoverSystemMdOptions as _, ACTIONS_WITH_CARE_DOCTRINE as _i, CreateWorkerParams as _n, credentialsPath as _r, findGitRoot as _t, GRUVBOX_DARK as a, detectLibc as ai, McpAuthEvent as an, Walk as ar, readProjects as at, discoverSystemMd as b, DOING_TASKS_DOCTRINE as bi, InteractionHub as bn, readProviderCredentialPair as br, fetchOAuthRedirect as bt, CATPPUCCIN_LATTE as c, performInPlaceSelfUpdate as ci, getMcpAuthStatus as cn, DiscoveryProvider as cr, runEndNotice as ct, ThemeProvider as d, chatAutoCompactBehavior as di, readFileSafe as dn, ApiKeyCredential as dr, clearProviderUsageCache as dt, PlatformTarballOptions as ei, mcpCredentialsPath as en, parseEditorCommand as er, addToSafelist as et, useColors as f, AgentsMdFile as fi, resolveCwdPath as fn, CredentialsFile as fr, fetchAllProviderUsage as ft, useTheme as g, renderAgentsMdBlock as gi, createChatHost as gn, applyApiKeyEnv as gr, usageSourceFor as gt, useSyntaxStyles as h, discoverAgentsMd as hi, ContextSegmentsReport as hn, ProviderCredential as hr, usageChecksOptedOut as ht, VAPORWAVE_THEME as i, compareSemver as ii, useMcpAuthState as in, DiscoverySlotOptions as ir, projectsFilePath as it, defaultSkillScanPaths as j, envSection as ji, PendingApprovalsStore as jn, ClaudeImportOptions as jr, McpConfigScope as jt, buildSpawnStartEvent as k, buildBuildSystem as ki, createMemoryApprovalsStore as kn, useConfig as kr, modelChainMetadata as kt, CATPPUCCIN_MACCHIATO as l, performSelfUpdate as li, reduceMcpAuth as ln, useDiscovery as lr, FetchProviderUsageOptions as lt, useSurfaces as m, DiscoverAgentsMdOptions as mi, ChatHost as mn, PreferCredentialResult as mr, providerUsageSupported as mt, createActiveTodoAnchorHooks as n, UpdateStatus as ni, McpAuthProvider as nn, Commit as nr, isOnSafelist as nt, GRUVBOX_LIGHT as o, detectPackageManager as oi, McpAuthStateMap as on, createDiscoverySlot as or, suggestSafelistEntries as ot, useSelectStyle as p, AgentsMdResult as pi, serializePreview as pn, OAuthCredential as pr, fetchProviderUsage as pt, useSettings as q, GenerateSessionTitleOptions as qn, CheckForUpdateOptions as qr, useMcpToolToggleMap as qt, renderActiveTodoAnchor as r, checkForUpdate as ri, useMcpAuthDispatch as rn, DiscoverySlot as rr, matchesSafelistEntry as rt, CATPPUCCIN_FRAPPE as s, parseSemver as si, McpAuthStatus as sn, DiscoveryContextValue as sr, writeProjects as st, ActiveTodoAnchorOptions as t, SelfUpdateResult as ti, patchMcpCredential as tn, quoteForShell as tr, getSafelist as tt, CATPPUCCIN_MOCHA as u, resolvePlatformPackage as ui, extractEditPayloadForGate as un, useDiscoveryOptional as ur, USAGE_CACHE_TTL_MS as ut, SystemMdFile as v, BuildSystemOptions as vi, WorkerRow as vn, readCredentials as vr, formatPathForCwd as vt, StreamBuffer as w, INTERACTION_GUIDANCE_NO_PROMPTS as wi, CompactionEntry as wn, writeCredentials as wr, OAuthPrompt$1 as wt, renderSystemMdSeed as x, EnvSectionOptions as xi, createInteractionHub as xn, removeProviderCredential as xr, normalizeRedirectPaste as xt, SystemMdResult as y, COMMUNICATION_DOCTRINE as yi, WorkerSummary as yn, readProviderCredential as yr, FetchOAuthRedirectResult as yt, SettingsCategory as z, QueuedItem as zn, bootTick as zr, clearMcpToolsCache as zt };
+//# sourceMappingURL=index-DgdzXRPH.d.ts.map