tmux-ide 2.7.0 → 2.9.0-beta.5

package/packages/daemon/dist/tui/chrome/welcome.js

@@ -0,0 +1,117 @@
+/**
+ * The first-run WELCOME card — shown ONCE, the moment tmux-ide first adopts a
+ * session.
+ *
+ * The discovery problem: once a session is adopted, the whole TUI is one
+ * keystroke away (the home cockpit, the switcher, the actions menu, the cheat
+ * sheet), but a brand-new user has no way to know those keys exist. The welcome
+ * card is the pointer: a tiny hero that names the four "unlock" keys and then
+ * gets out of the way forever.
+ *
+ * "Once" is enforced by a marker file (`~/.tmux-ide/welcomed`, overridable via
+ * `TMUX_IDE_HOME` so tests — and the dev box — never see it unexpectedly). The
+ * card is ALSO gated by config (`welcome.show`), so it can be suppressed without
+ * touching the marker.
+ *
+ * {@link buildWelcomeText} is PURE (tested); {@link maybeShowWelcomePopup} and
+ * the marker helpers wire the io. The CLI `welcome` command prints the card and
+ * waits for any key (see bin/cli.ts).
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { DEFAULT_KEYS, getAppConfig } from "../../lib/app-config.js";
+// --- ANSI styling — the CLI's bold/dim/cyan pattern (matches ./cheatsheet.ts). ---
+const bold = (s) => `\x1b[1m${s}\x1b[22m`;
+const dim = (s) => `\x1b[2m${s}\x1b[22m`;
+const head = (s) => `\x1b[1;36m${s}\x1b[0m`;
+/**
+ * Render a tmux key name for humans: `M-` → `⌥`, `C-` → `^`, `S-` → `⇧`. Keeps
+ * the card's key hints sourced from the real `M-…` config values (same helper as
+ * the cheat sheet).
+ */
+function renderKey(tmuxKey) {
+    return tmuxKey.replace(/M-/g, "⌥").replace(/C-/g, "^").replace(/S-/g, "⇧");
+}
+/**
+ * Absolute path to the "already welcomed" marker: `<home>/welcomed`, where
+ * `<home>` is `TMUX_IDE_HOME` when set (tests / per-run overrides), else
+ * `~/.tmux-ide`. The env override lets a live test point the marker at a scratch
+ * dir so it never touches — or is confused by — the real user's marker.
+ */
+export function welcomeMarkerPath() {
+    const home = process.env.TMUX_IDE_HOME ?? join(homedir(), ".tmux-ide");
+    return join(home, "welcomed");
+}
+/**
+ * Whether the first-run welcome should show: the marker file is ABSENT and the
+ * config hasn't disabled it (`welcome.show !== false`). A missing/garbage config
+ * defaults `welcome.show` to true (see app-config), so a fresh install shows it.
+ */
+export function shouldShowWelcome() {
+    return !existsSync(welcomeMarkerPath()) && getAppConfig().welcome.show;
+}
+/**
+ * Create the marker file so the welcome shows only once. Best-effort — a marker
+ * we can't write means the card may show again, but it must never crash adopt.
+ */
+export function markWelcomed() {
+    const path = welcomeMarkerPath();
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, new Date().toISOString());
+    }
+    catch {
+        // can't write the marker — degrade to "may show again", never throw
+    }
+}
+/**
+ * PURE — the welcome card text (ANSI-styled), sized for a small ~60×12 popup. A
+ * tiny hero naming the FOUR keys that unlock the whole TUI, sourced from the live
+ * key config so a rebind relabels the card. Ends with the "shows once" note so
+ * the user knows it won't nag.
+ */
+export function buildWelcomeText(keys = DEFAULT_KEYS) {
+    const lines = [
+        head(" You're in tmux-ide"),
+        dim(" your terminal, now a fleet you can see and steer."),
+        "",
+        " Four keys unlock everything:",
+        `   ${bold("right-click")}   the actions menu — anywhere`,
+        `   ${bold(renderKey(keys.home).padEnd(11))}   the home cockpit`,
+        `   ${bold(renderKey(keys.popup).padEnd(11))}   switch session`,
+        `   ${bold(renderKey(keys.cheatsheet).padEnd(11))}   all keys (the cheat sheet)`,
+        "",
+        dim(" This card shows once — press any key to close."),
+    ];
+    return lines.join("\n");
+}
+/**
+ * io — float the one-time welcome card on the CURRENT tmux client, best-effort.
+ *
+ * Called at the end of {@link ../chrome/statusline.ts adoptSession}. Gated by
+ * {@link shouldShowWelcome} (marker + config) AND by being inside a tmux client
+ * — outside tmux there's nowhere to float the popup, so we neither show it nor
+ * burn the one-shot (the marker stays, so the next in-tmux adopt still shows it).
+ *
+ * The popup is spawned DETACHED and unref'd so it never blocks the adopt: a
+ * `display-popup -E` would otherwise keep the tmux CLI alive until the user
+ * pressed a key. `spawn` inherits `$TMUX`, so the popup lands on the invoking
+ * client. The marker is written immediately after the spawn attempt so a rapid
+ * `adopt --all` shows the card exactly once, not once per session.
+ */
+export function maybeShowWelcomePopup() {
+    if (!shouldShowWelcome())
+        return;
+    if (!process.env.TMUX)
+        return;
+    try {
+        const child = spawn("tmux", ["display-popup", "-E", "-w", "60", "-h", "12", "tmux-ide welcome"], { stdio: "ignore", detached: true });
+        child.unref();
+    }
+    catch {
+        // tmux missing / no client — best-effort, still mark so we don't retry forever
+    }
+    markWelcomed();
+}

package/packages/daemon/dist/tui/compiled.d.ts

@@ -0,0 +1,86 @@
+export type TuiLaunch = {
+    mode: "bun";
+    bin: "bun";
+    argv: string[];
+} | {
+    mode: "binary";
+    bin: string;
+    argv: string[];
+} | {
+    mode: "unavailable";
+    reasons: string[];
+};
+export interface TuiResolveInput {
+    /** Dispatcher surface token: team | explorer | changes | preview | config | setup | sidebar. */
+    surface: string;
+    /** The checkout `.tsx` entry for this surface. */
+    scriptPath: string;
+    /** Surface flags (`--session=…`, `--dir=…`, `--theme=…`, …). */
+    args: string[];
+    /** Whether {@link scriptPath} exists (checkout present). */
+    checkoutExists: boolean;
+    /** Whether the `bun` runtime is on PATH. */
+    bunAvailable: boolean;
+    /** Absolute path to the compiled `tmux-ide-tui`, or null if not found. */
+    compiledBinary: string | null;
+    /** Explicit development override; ordinary launches prefer the fast binary. */
+    preferSource?: boolean;
+}
+export interface TuiLaunchAcquisitionOptions {
+    readonly log?: (message: string) => void;
+    readonly download?: (options: {
+        readonly log?: (message: string) => void;
+    }) => Promise<{
+        readonly path: string;
+        readonly bytes: number;
+    }>;
+}
+/**
+ * Build the environment for every standalone OpenTUI surface.
+ *
+ * `TERM=xterm-256color` alone makes OpenTUI synchronize the terminal's mutable
+ * ANSI 0-15 palette. Several embedded hosts remap bright-white slot 15 to their
+ * dark default, turning light semantic surfaces black. The app renders 24-bit
+ * colors, so advertise that capability explicitly and never let an inherited
+ * NO_COLOR disable it. Hosted launches already enforce the same contract in
+ * their shell command line.
+ */
+export declare function openTuiLaunchEnvironment(inherited: NodeJS.ProcessEnv, overlay?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Ensure an installed OpenTUI app has a runnable native dispatcher.
+ *
+ * Development checkouts with Bun and installs that already have an exact-version
+ * binary stay entirely local. Only the otherwise-unavailable installed path
+ * acquires the matching release artifact. Keeping this decision beside
+ * {@link resolveTuiLaunch} prevents the CLI and package gate from inventing a
+ * second launch policy.
+ */
+export declare function ensureTuiLaunchAvailable(input: TuiResolveInput, options?: TuiLaunchAcquisitionOptions): Promise<TuiLaunch>;
+/**
+ * PURE — decide how to launch a surface. Bun-from-checkout wins when both are
+ * present (dev); the compiled binary is the installed fallback; otherwise the
+ * caller surfaces an actionable message built from `reasons`.
+ */
+export declare function resolveTuiLaunch(input: TuiResolveInput): TuiLaunch;
+/**
+ * io — locate the compiled `tmux-ide-tui`. Honors `TMUX_IDE_TUI_BIN` (absolute
+ * override, e.g. for tests / custom installs), then probes bin- and
+ * module-relative candidates. Returns null when none exists.
+ */
+export declare function findCompiledTui(): string | null;
+/** io — is the `bun` runtime callable? */
+export declare function isBunAvailable(): boolean;
+/**
+ * A config-free cwd for the standalone Bun executable.
+ *
+ * Even a `bun build --compile` executable asks Bun to load `bunfig.toml` from
+ * its process cwd before the embedded application starts. Running the binary
+ * from a tmux-ide checkout therefore tries to resolve the checkout's
+ * `@opentui/solid/preload` as a runtime dependency and aborts before our
+ * dispatcher can run. The real project cwd is already carried explicitly via
+ * `TMUX_IDE_CWD` / `--dir`, so compiled surfaces start in this private,
+ * deliberately config-free directory instead.
+ */
+export declare function compiledTuiRuntimeDir(home?: string): string;
+/** io — create and return the private cwd used by compiled TUI surfaces. */
+export declare function ensureCompiledTuiRuntimeDir(home?: string): string;

package/packages/daemon/dist/tui/compiled.js

@@ -0,0 +1,165 @@
+/**
+ * Resolution for the TUI surfaces across BOTH distribution modes.
+ *
+ * Dev checkout: the surfaces are OpenTUI/Solid `.tsx` spawned by `bun` (the
+ * bunfig preload supplies the JSX transform). Installed via npm/pnpm/bun: there
+ * is no checkout and no `bun`, so we fall back to the compiled `tmux-ide-tui`
+ * binary (see scripts/build-tui.mjs) which bundles every surface behind a
+ * `<surface> [flags]` argv dispatcher and needs no runtime.
+ *
+ * Order is "compiled first, source fallback": interactive startup should not
+ * pay Bun's 1s+ TypeScript/JSX module load on every launch. Developers can set
+ * `TMUX_IDE_TUI_SOURCE=1` to opt into live `.tsx` sources. {@link findCompiledTui}
+ * probes the shipped/local compiled binary first, then a per-platform binary
+ * downloaded at runtime into `~/.tmux-ide/bin/` (see lib/tui-binary.ts).
+ *
+ * {@link resolveTuiLaunch} is a PURE decision (unit-tested); {@link findCompiledTui}
+ * and {@link isBunAvailable} are the thin io probes that feed it.
+ */
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+import { downloadTuiBinary, findDownloadedTui } from "../lib/tui-binary.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Build the environment for every standalone OpenTUI surface.
+ *
+ * `TERM=xterm-256color` alone makes OpenTUI synchronize the terminal's mutable
+ * ANSI 0-15 palette. Several embedded hosts remap bright-white slot 15 to their
+ * dark default, turning light semantic surfaces black. The app renders 24-bit
+ * colors, so advertise that capability explicitly and never let an inherited
+ * NO_COLOR disable it. Hosted launches already enforce the same contract in
+ * their shell command line.
+ */
+export function openTuiLaunchEnvironment(inherited, overlay = {}) {
+    const environment = {
+        ...inherited,
+        ...overlay,
+        COLORTERM: "truecolor",
+    };
+    delete environment.NO_COLOR;
+    return environment;
+}
+/**
+ * Ensure an installed OpenTUI app has a runnable native dispatcher.
+ *
+ * Development checkouts with Bun and installs that already have an exact-version
+ * binary stay entirely local. Only the otherwise-unavailable installed path
+ * acquires the matching release artifact. Keeping this decision beside
+ * {@link resolveTuiLaunch} prevents the CLI and package gate from inventing a
+ * second launch policy.
+ */
+export async function ensureTuiLaunchAvailable(input, options = {}) {
+    const current = resolveTuiLaunch(input);
+    if (current.mode !== "unavailable")
+        return current;
+    let downloaded;
+    try {
+        downloaded = await (options.download ?? downloadTuiBinary)({ log: options.log });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Automatic OpenTUI runtime acquisition failed: ${message}\n` +
+            "Retry with `tmux-ide update --tui-binary`, then run `tmux-ide app` again.", { cause: error });
+    }
+    const prepared = resolveTuiLaunch({ ...input, compiledBinary: downloaded.path });
+    if (prepared.mode === "unavailable") {
+        throw new Error("OpenTUI runtime was downloaded but could not be selected. " +
+            "Run `tmux-ide doctor`, then retry `tmux-ide update --tui-binary`.");
+    }
+    return prepared;
+}
+/**
+ * PURE — decide how to launch a surface. Bun-from-checkout wins when both are
+ * present (dev); the compiled binary is the installed fallback; otherwise the
+ * caller surfaces an actionable message built from `reasons`.
+ */
+export function resolveTuiLaunch(input) {
+    if (input.compiledBinary && !input.preferSource) {
+        return { mode: "binary", bin: input.compiledBinary, argv: [input.surface, ...input.args] };
+    }
+    if (input.checkoutExists && input.bunAvailable) {
+        return { mode: "bun", bin: "bun", argv: [input.scriptPath, ...input.args] };
+    }
+    if (input.compiledBinary) {
+        return { mode: "binary", bin: input.compiledBinary, argv: [input.surface, ...input.args] };
+    }
+    const reasons = [];
+    if (!input.checkoutExists) {
+        reasons.push("the TUI widget sources are absent (reinstall tmux-ide — releases since v2.6.1 ship them)");
+    }
+    if (!input.bunAvailable) {
+        reasons.push("the `bun` runtime is not installed (https://bun.sh)");
+    }
+    reasons.push("no compiled `tmux-ide-tui` binary was found (build one with `pnpm build:tui`, download it with `tmux-ide update --tui-binary`, or reinstall a release that ships it)");
+    return { mode: "unavailable", reasons };
+}
+// Candidate locations for the compiled binary, relative to an anchor dir. The
+// installed tarball ships it at packages/daemon/dist/tui/tmux-ide-tui and the
+// bin is bin/cli.js, so a bin-anchored `../packages/daemon/dist/...` hits it;
+// the other rels cover unbundled daemon layouts and a co-located binary.
+const BINARY_RELS = [
+    "../packages/daemon/dist/tui/tmux-ide-tui",
+    "../../dist/tui/tmux-ide-tui",
+    "../dist/tui/tmux-ide-tui",
+    "dist/tui/tmux-ide-tui",
+    "tmux-ide-tui",
+];
+/**
+ * io — locate the compiled `tmux-ide-tui`. Honors `TMUX_IDE_TUI_BIN` (absolute
+ * override, e.g. for tests / custom installs), then probes bin- and
+ * module-relative candidates. Returns null when none exists.
+ */
+export function findCompiledTui() {
+    const override = process.env.TMUX_IDE_TUI_BIN;
+    if (override)
+        return existsSync(override) ? override : null;
+    const anchors = [];
+    if (process.argv[1])
+        anchors.push(dirname(process.argv[1]));
+    anchors.push(__dirname);
+    for (const anchor of anchors) {
+        for (const rel of BINARY_RELS) {
+            const candidate = resolve(anchor, rel);
+            if (existsSync(candidate))
+                return candidate;
+        }
+    }
+    // Last: a per-platform binary fetched at runtime by `tmux-ide update
+    // --tui-binary` into `~/.tmux-ide/bin/` — the fallback for an npm install with
+    // no bun and no shipped compiled binary. Version-stamped, so it only matches
+    // the running version (see lib/tui-binary.ts).
+    return findDownloadedTui();
+}
+/** io — is the `bun` runtime callable? */
+export function isBunAvailable() {
+    try {
+        execFileSync("bun", ["--version"], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A config-free cwd for the standalone Bun executable.
+ *
+ * Even a `bun build --compile` executable asks Bun to load `bunfig.toml` from
+ * its process cwd before the embedded application starts. Running the binary
+ * from a tmux-ide checkout therefore tries to resolve the checkout's
+ * `@opentui/solid/preload` as a runtime dependency and aborts before our
+ * dispatcher can run. The real project cwd is already carried explicitly via
+ * `TMUX_IDE_CWD` / `--dir`, so compiled surfaces start in this private,
+ * deliberately config-free directory instead.
+ */
+export function compiledTuiRuntimeDir(home = homedir()) {
+    return join(home, ".tmux-ide", "runtime", "compiled-tui");
+}
+/** io — create and return the private cwd used by compiled TUI surfaces. */
+export function ensureCompiledTuiRuntimeDir(home = homedir()) {
+    const dir = compiledTuiRuntimeDir(home);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}

package/packages/daemon/dist/tui/detect/agent-resolution.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The ONE authority-first status decision every surface shares.
+ *
+ * "What is an agent's status" is decided here and nowhere else: a fresh
+ * `@agent_state` stamp (parsed with the staleness guard in {@link parseAuthority})
+ * OUTRANKS scraping; otherwise the caller's own scrape verdict is used. The
+ * caller supplies that verdict via a callback because the IO and any surface-
+ * specific bookkeeping differ — the cockpit folds its scrape through the
+ * cross-tick {@link StatusTracker}; the desktop projection reads a pre-resolved
+ * probe verdict — but the DECISION (authority beats scrape, plus the `since`
+ * stamp and the status source) is identical, so it lives once, here.
+ *
+ * Everything in this module is PURE. The scrape callback may do IO, but it is
+ * invoked ONLY when authority is absent or stale, which is exactly where the
+ * expensive capture/scrape is wanted.
+ */
+import { type AgentStatus } from "./classify.ts";
+/** Where a resolved status came from — an authority stamp, scraping, or neither. */
+export type AgentStatusSource = "authority" | "scrape" | "unknown";
+/** The resolved status plus its provenance and (authority-only) `since` stamp. */
+export interface ResolvedAgentStatus {
+    readonly status: AgentStatus;
+    readonly source: AgentStatusSource;
+    /** The authority state's own epoch ("since"); null for a scraped status. */
+    readonly since: number | null;
+}
+/**
+ * Resolve a pane's status authority-first. PURE.
+ *
+ * - A fresh `@agent_state` stamp wins → `source: "authority"`, `since` = its epoch.
+ * - Otherwise `scrape()` is invoked and its verdict is used → `source: "scrape"`,
+ *   or `source: "unknown"` when the scrape itself couldn't classify the pane.
+ *
+ * `scrape` is only called on the authority-absent/stale path, so a fresh stamp
+ * never triggers a capture round-trip.
+ */
+export declare function resolveAgentStatus(input: {
+    readonly authorityRaw: string | undefined;
+    readonly nowSec: number;
+    readonly scrape: () => AgentStatus;
+}): ResolvedAgentStatus;
+/**
+ * The sanitized self-reported display metadata a pane surfaces, gated on
+ * authority freshness. PURE.
+ *
+ * `@agent_status_text` / `@agent_display_name` carry no epoch of their own — they
+ * ride the pane's `@agent_state` stamp — so they are trusted ONLY while that
+ * stamp is fresh (`authorityFresh`). A stale/absent stamp drops them rather than
+ * letting them lie beside a scraped status. Each value passes through
+ * {@link sanitizeAgentText} (ANSI stripped, controls collapsed, clamped). Fields
+ * are omitted (not null) so callers can spread them additively.
+ */
+export declare function agentDisplayMetadata(statusTextRaw: string | undefined, displayNameRaw: string | undefined, authorityFresh: boolean): {
+    statusText?: string;
+    displayName?: string;
+};

package/packages/daemon/dist/tui/detect/agent-resolution.js

@@ -0,0 +1,60 @@
+/**
+ * The ONE authority-first status decision every surface shares.
+ *
+ * "What is an agent's status" is decided here and nowhere else: a fresh
+ * `@agent_state` stamp (parsed with the staleness guard in {@link parseAuthority})
+ * OUTRANKS scraping; otherwise the caller's own scrape verdict is used. The
+ * caller supplies that verdict via a callback because the IO and any surface-
+ * specific bookkeeping differ — the cockpit folds its scrape through the
+ * cross-tick {@link StatusTracker}; the desktop projection reads a pre-resolved
+ * probe verdict — but the DECISION (authority beats scrape, plus the `since`
+ * stamp and the status source) is identical, so it lives once, here.
+ *
+ * Everything in this module is PURE. The scrape callback may do IO, but it is
+ * invoked ONLY when authority is absent or stale, which is exactly where the
+ * expensive capture/scrape is wanted.
+ */
+import { parseAuthority, parseAuthorityEpoch, sanitizeAgentText, } from "./classify.js";
+/**
+ * Resolve a pane's status authority-first. PURE.
+ *
+ * - A fresh `@agent_state` stamp wins → `source: "authority"`, `since` = its epoch.
+ * - Otherwise `scrape()` is invoked and its verdict is used → `source: "scrape"`,
+ *   or `source: "unknown"` when the scrape itself couldn't classify the pane.
+ *
+ * `scrape` is only called on the authority-absent/stale path, so a fresh stamp
+ * never triggers a capture round-trip.
+ */
+export function resolveAgentStatus(input) {
+    const authority = parseAuthority(input.authorityRaw, input.nowSec);
+    if (authority !== null) {
+        return {
+            status: authority,
+            source: "authority",
+            since: parseAuthorityEpoch(input.authorityRaw),
+        };
+    }
+    const status = input.scrape();
+    return { status, source: status === "unknown" ? "unknown" : "scrape", since: null };
+}
+/**
+ * The sanitized self-reported display metadata a pane surfaces, gated on
+ * authority freshness. PURE.
+ *
+ * `@agent_status_text` / `@agent_display_name` carry no epoch of their own — they
+ * ride the pane's `@agent_state` stamp — so they are trusted ONLY while that
+ * stamp is fresh (`authorityFresh`). A stale/absent stamp drops them rather than
+ * letting them lie beside a scraped status. Each value passes through
+ * {@link sanitizeAgentText} (ANSI stripped, controls collapsed, clamped). Fields
+ * are omitted (not null) so callers can spread them additively.
+ */
+export function agentDisplayMetadata(statusTextRaw, displayNameRaw, authorityFresh) {
+    if (!authorityFresh)
+        return {};
+    const statusText = sanitizeAgentText(statusTextRaw);
+    const displayName = sanitizeAgentText(displayNameRaw);
+    return {
+        ...(statusText !== undefined ? { statusText } : {}),
+        ...(displayName !== undefined ? { displayName } : {}),
+    };
+}

package/packages/daemon/dist/tui/detect/classify.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The 4-state agent classifier.
+ *
+ * Turns snapshot + manifest evidence into a final per-pane status. The
+ * instantaneous half (`classifyInstant`) is pure: it maps a single snapshot
+ * through a manifest to blocked/working/idle/unknown. The `done` state,
+ * however, is inherently cross-tick — an agent is "done" only when it WAS
+ * working and has since gone quiet without being viewed. That temporal logic
+ * lives in the small stateful `StatusTracker`, which layers `done` + seen
+ * acknowledgement on top of the instantaneous state.
+ */
+import type { AgentManifest } from "./manifest.ts";
+import type { PaneSnapshot } from "./snapshot.ts";
+/** The final per-pane status surfaced to the TUI. */
+export type AgentStatus = "blocked" | "working" | "done" | "idle" | "unknown";
+/** The instantaneous status derivable from a single snapshot (no history). */
+export type InstantState = "blocked" | "working" | "idle" | "unknown";
+/**
+ * Parse an authoritative `@agent_state` pane option (`"<state>:<epoch>"`,
+ * written by lifecycle-hook integrations or any self-reporting agent).
+ * PURE — returns the reported status, or null when the value is absent,
+ * malformed, or stale (working/blocked past {@link AUTHORITY_STALE_SECONDS}).
+ * A fresh authority report OUTRANKS screen-manifest scraping.
+ */
+export declare function parseAuthority(raw: string | undefined, nowSec: number): AgentStatus | null;
+/** Display-metadata budget — `@agent_status_text` / `@agent_display_name`
+ *  values are clamped to this many characters (ellipsis included). */
+export declare const AGENT_TEXT_MAX = 32;
+/**
+ * Sanitize a self-reported display-metadata pane option
+ * (`@agent_status_text` / `@agent_display_name`) — PURE, never throws.
+ *
+ * ANSI escape sequences are stripped, remaining control characters become
+ * spaces, runs of whitespace collapse to one space, and the result is clamped
+ * to {@link AGENT_TEXT_MAX} characters (with a trailing ellipsis when cut).
+ * Returns undefined for an absent or effectively-empty value, so callers can
+ * spread the field additively (`...(text ? { statusText: text } : {})`).
+ *
+ * Freshness is NOT judged here: the metadata options carry no epoch of their
+ * own — they ride the pane's `@agent_state` stamp, and the caller surfaces
+ * them only while {@link parseAuthority} reports that stamp fresh.
+ */
+export declare function sanitizeAgentText(raw: string | undefined): string | undefined;
+/**
+ * Extract the epoch STAMP from an `@agent_state` value (`"<state>:<epoch>"`) —
+ * the "since" timestamp of the reported state. PURE — returns the epoch, or
+ * null when the value is absent or its stamp isn't a finite number. Staleness
+ * is NOT considered here (that's {@link parseAuthority}'s job); callers pair
+ * this with a fresh `parseAuthority` result to surface a state's `since`.
+ */
+export declare function parseAuthorityEpoch(raw: string | undefined): number | null;
+/**
+ * Classify a single snapshot against a manifest — PURE, never throws.
+ *
+ * - no manifest → `"unknown"` (we can't reason about an unrecognized command)
+ * - manifest reports `blocked` → `"blocked"`
+ * - manifest reports `working` → `"working"`
+ * - manifest reports `done` or nothing → `"idle"`
+ *
+ * A manifest-detected `done` is deliberately collapsed to `idle` here; the
+ * real, cross-tick `done` is produced by {@link StatusTracker}.
+ */
+export declare function classifyInstant(snapshot: PaneSnapshot & {
+    title?: string;
+}, manifest: AgentManifest | undefined): InstantState;
+/**
+ * Convenience wrapper: pick the manifest for a pane command, then classify.
+ * Returns `"unknown"` when no manifest applies to the command.
+ */
+export declare function classifyPaneCommand(snapshot: PaneSnapshot & {
+    title?: string;
+}, command: string, manifests?: AgentManifest[]): InstantState;
+/**
+ * Stateful layer that adds `done` + seen-acknowledgement on top of the
+ * instantaneous state. Deterministic given its call sequence.
+ */
+export interface StatusTracker {
+    /**
+     * Fold a fresh instantaneous state into the pane's history and return the
+     * final status. `opts.seen` marks the pane as currently viewed/attached,
+     * which acknowledges (and suppresses) a pending `done`.
+     */
+    update(paneId: string, instant: InstantState, opts?: {
+        seen?: boolean;
+    }): AgentStatus;
+    /** Acknowledge a pane — clears any pending `done`. */
+    markSeen(paneId: string): void;
+    /** Drop a pane's state entirely (e.g. its session closed). */
+    forget(paneId: string): void;
+}
+/**
+ * Create a {@link StatusTracker}.
+ *
+ * State transitions (given the previous tick's bookkeeping):
+ * - `working` → clear `doneUnseen`, remember working → `"working"`.
+ * - `blocked` → clear `doneUnseen` (blocked outranks a pending done) →
+ *   `"blocked"`.
+ * - `idle`:
+ *   - a working→idle transition sets `doneUnseen`.
+ *   - `doneUnseen` && not seen → `"done"`.
+ *   - otherwise → `"idle"`.
+ * - `unknown` → `"unknown"` (leaves `doneUnseen` untouched).
+ *
+ * `opts.seen === true` always clears `doneUnseen`, and downgrades a would-be
+ * `done` to `"idle"` — seeing a finished pane acknowledges it.
+ */
+export declare function createStatusTracker(): StatusTracker;