@xenosystem/blocks 0.3.0 → 0.4.1

package/dist/ops/index.d.ts

@@ -0,0 +1,2235 @@
+import { PanelModule, PanelManifest } from '@xenosystem/panel-sdk';
+import { ReactNode } from 'react';
+import { ThrottleClock } from '@xenosystem/tree-core';
+
+/**
+ * The `xeno.core.console` contract.
+ *
+ * ## The gap every incumbent has: text lines, not records
+ *
+ * Every surveyed console stores a rendered string. That makes filtering a substring match, makes a
+ * structured payload impossible to expand, and makes multiplexing two sources into one view a
+ * concatenation rather than a join. A **record** carries its own level, source, scope and payload,
+ * so all three become trivial.
+ *
+ * @module
+ */
+/** Severity. Ordered from least to most severe — `LEVEL_ORDER` is the index. */
+type XenoLogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+/** Severity order, least to most severe. */
+declare const LEVEL_ORDER: readonly XenoLogLevel[];
+/** One structured log record. */
+interface XenoLogRecord {
+    /** Stable id — identity for `recordActivate`, selection and de-duplication bookkeeping. */
+    id: string;
+    /** Epoch ms. */
+    ts: number;
+    /** Severity. */
+    level: XenoLogLevel;
+    /** The human line. */
+    message: string;
+    /**
+     * Which stream this came from.
+     *
+     * **Multiplexing is the feature that makes this serve a BUILDER** rather than one app's stdout:
+     * panel logs, graph execution and host events land in one view, each filterable on its own.
+     */
+    source?: string;
+    /** A finer grouping within a source — a node id, a panel id, a request id. */
+    scope?: string;
+    /** Structured payload, rendered as an expandable tree. Redacted before display. */
+    data?: unknown;
+    /**
+     * How many identical records this row stands for.
+     *
+     * Set by the panel's ADJACENT-RUN collapsing, never by the host.
+     */
+    count?: number;
+}
+/**
+ * A partial update to ONE record, addressed by its `id`.
+ *
+ * ## Why an update-by-id channel exists at all
+ *
+ * **A record whose text grows is not expressible by `append` or `replace`.** One record per token
+ * is wrong — `collapseAdjacent` will not merge them, because it requires an identical `message`,
+ * so a streamed sentence renders as one row per token. `replace` of the whole buffer per token is
+ * the thousand-array-copies non-starter this module's header already refuses. A growing line
+ * therefore needs a third channel, and every streaming producer has one: a build log, a
+ * long-running job's output, a download progress line, a model response.
+ *
+ * ## What a patch may NOT carry
+ *
+ * `id` and `count` are absent from this interface by design, and stripped at runtime as well.
+ *
+ * - 🔴 **`id`** is the virtualized row key AND the argument the panel hands back through
+ *   `recordActivate`. A patch that could move it would remount the row mid-stream — losing its
+ *   expansion state and its scroll anchor — and would silently repoint the host's reveal hook at a
+ *   different line.
+ * - **`count`** belongs to the panel, not the host ({@link XenoLogRecord.count} says so), and a
+ *   host-set count would be overwritten by the next projection anyway.
+ *
+ * ⚠️ A patch cannot UNSET a field. `{ scope: undefined }` is indistinguishable from an absent key
+ * in JavaScript, so an absent key always means "leave this alone".
+ */
+interface XenoLogPatch {
+    /** New severity. An unrecognised level is ignored — it would corrupt the level counts. */
+    level?: XenoLogLevel;
+    /** Replace the message outright. */
+    message?: string;
+    /**
+     * Concatenate onto the message — the streaming channel.
+     *
+     * Applied AFTER `message`, so one patch can reset a line and start streaming into it again.
+     */
+    appendMessage?: string;
+    /** Move the record to another stream. */
+    source?: string;
+    /** Re-scope it — a request id that only became known once the response arrived. */
+    scope?: string;
+    /** Replace the structured payload. Redacted like everything else; send `null` to empty it. */
+    data?: unknown;
+    /**
+     * Restate the timestamp.
+     *
+     * ⚠️ Does NOT reorder the buffer. Records sit in arrival order, which is what makes a console
+     * readable; a patch that could move a line would make the view jump under a reader's eyes.
+     */
+    ts?: number;
+}
+/**
+ * An append-oriented update.
+ *
+ * **A console that re-pushes its whole buffer per line is a non-starter** — at a thousand lines a
+ * second that is a thousand array copies. `append` is the hot path for a new line, `patch` is the
+ * hot path for a line that is still GROWING; `replace` exists for a source that genuinely
+ * restarts, and `clear` for one that resets.
+ */
+interface XenoLogDelta {
+    /** Monotonic revision. A delta whose rev is not greater than the current one is dropped. */
+    rev?: number;
+    /** Records to append, oldest first. The common case. */
+    append?: XenoLogRecord[];
+    /**
+     * Partial updates keyed by record id — the hot path for a line that is still being written.
+     *
+     * Applied AFTER `append`, so a single delta can open a record and deliver its first chunk.
+     *
+     * 🔴 **A patch for an id the buffer does not hold is DROPPED, never upserted.** A console record
+     * cannot be invented from a partial: it would have no `ts` to place it in an arrival-ordered
+     * buffer and no `level` to filter it by, so an upsert would have to FABRICATE a severity — and a
+     * log line whose severity the panel made up is the one lie a console must never tell. A producer
+     * that can deliver out of order must `append` the record first (an empty message is fine), which
+     * is what "opening a stream" means everywhere else. Dropped patches are counted and shown,
+     * because a silently ignored wire is indistinguishable from a dead one.
+     */
+    patch?: Record<string, XenoLogPatch>;
+    /** Replace the whole buffer (a source restarted). */
+    replace?: XenoLogRecord[];
+    /** Drop everything. `clear` wins over `append` in the same delta. */
+    clear?: boolean;
+    /** Restrict `replace`/`clear` to one source, leaving the others intact. */
+    source?: string;
+}
+/** A named stream, for the per-source filter UI. */
+interface XenoLogSource {
+    id: string;
+    /** Display label. Defaults to the id. */
+    label?: string;
+    /** Whether its records are currently shown. */
+    enabled: boolean;
+    /** How many records it has contributed. */
+    count: number;
+}
+/** The active filter. */
+interface XenoLogFilter {
+    /** Minimum severity to show. */
+    minLevel?: XenoLogLevel;
+    /** Case-insensitive substring over message, source and scope. */
+    search?: string;
+    /** Sources to hide. Absent ⇒ all shown. */
+    mutedSources?: string[];
+}
+/** The panel's serialized state. **Records are never persisted** — a log is not a document. */
+interface ConsolePanelState {
+    filter: XenoLogFilter;
+    follow: boolean;
+    collapse: boolean;
+}
+/** What the controller exposes to its view. */
+interface ConsoleViewState {
+    /** Visible rows, after filtering and collapsing. */
+    rows: XenoLogRecord[];
+    /** Every known source, for the filter chips. */
+    sources: XenoLogSource[];
+    /** The active filter. */
+    filter: XenoLogFilter;
+    /** Counts per level across the WHOLE buffer, so a filter chip can show what it would reveal. */
+    counts: Record<XenoLogLevel, number>;
+    /** Total records held (before filtering). */
+    total: number;
+    /** Following the tail. */
+    follow: boolean;
+    /** Collapsing adjacent duplicates. */
+    collapse: boolean;
+    /** Records dropped by the ring buffer since the last clear. */
+    dropped: number;
+    /**
+     * Patches that addressed no record, since the last clear.
+     *
+     * Surfaced rather than swallowed: a producer that patches an id it never appended sees nothing
+     * happen, and "the wire is mis-keyed" and "the wire is dead" look identical from the outside.
+     * This is the one number that tells them apart.
+     */
+    droppedPatches: number;
+}
+/** What the panel emits when a record is opened. */
+interface XenoLogActivate {
+    recordId: string;
+    source?: string;
+    scope?: string;
+}
+/** Is `level` at least as severe as `min`? */
+declare function meetsLevel(level: XenoLogLevel, min: XenoLogLevel | undefined): boolean;
+/** Does a record match a search term? Searches message, source and scope — not the payload. */
+declare function matchesSearch$1(record: XenoLogRecord, term: string): boolean;
+/**
+ * Collapse ADJACENT identical records into one row carrying a count.
+ *
+ * Adjacent-run, not global: a hundred identical errors in a row are one row with `×100`, but the
+ * same error recurring after other output stays a separate row — collapsing globally would hide
+ * *when* it happened, which is usually the whole question.
+ *
+ * Two records are identical when their level, message, source and scope all match. The payload is
+ * deliberately excluded: two records that read the same but carry different data are still the same
+ * event repeating, and hashing payloads on the hot path would cost more than the feature saves.
+ *
+ * @param records - Records in display order.
+ * @returns Collapsed rows; each carries `count` (always ≥ 1).
+ */
+declare function collapseAdjacent(records: readonly XenoLogRecord[]): XenoLogRecord[];
+/**
+ * How much already-clean tail is re-scanned together with an appended fragment.
+ *
+ * 🔴 **This constant IS the security invariant of streaming.** Redaction runs per fragment, and a
+ * secret does not respect a fragment boundary: `"token=eyJhbGciOi"` is not token-shaped and
+ * `"JIUzI1NiJ9.eyJzdWIiOjF9.sig"` is not either, but concatenated they are a JWT. Redacting each
+ * arrival in isolation would therefore assemble, in the buffer, a credential neither half could be
+ * caught as — the half-clean record. So an append is redacted over `[tail of what is already
+ * there] + [the new fragment]`, and the window has to be at least as long as the longest thing a
+ * detector must see whole.
+ *
+ * 1024 is far above what the shape detectors need: they fire EAGERLY, so a run of opaque
+ * characters is masked the moment it reaches 40 and never gets the chance to grow. The window
+ * exists for the value-driven pass, which matches an exact registered secret and therefore needs
+ * the whole of it in view — which is why the controller widens the window to the longest secret
+ * the host declares rather than trusting this number alone.
+ */
+declare const REDACTION_CARRY = 1024;
+/** Marks a message whose head was dropped by {@link truncateLogMessage}. */
+declare const MESSAGE_ELISION = "\u2026";
+/**
+ * Append `addition` to `existing`, re-redacting across the join.
+ *
+ * The already-clean head is left untouched — it was scanned when it arrived, and rescanning the
+ * whole message on every fragment turns a streamed line into O(n²) work, which is the same
+ * complaint this module's header makes about re-pushing the buffer.
+ *
+ * ⚠️ `redact` must be IDEMPOTENT, because the carry window is scanned once per fragment. The SDK's
+ * `redactForLog` is: it replaces a match with `«redacted»`, which matches neither detector.
+ *
+ * @param existing - Text already in the buffer, already redacted.
+ * @param addition - The newly arrived fragment, NOT yet redacted.
+ * @param redact - The redactor to run over the join window.
+ * @param carry - Window size; see {@link REDACTION_CARRY}.
+ * @returns The joined, redacted text.
+ *
+ * @example
+ * ```ts
+ * // Neither half is token-shaped; the join is, and is caught.
+ * spliceRedactedAppend('token=eyJhbGciOi', 'JIUzI1NiJ9.eyJzdWIiOjF9.sig', redactForLog)
+ * // → 'token=«redacted»'
+ * ```
+ */
+declare function spliceRedactedAppend(existing: string, addition: string, redact: (text: string) => string, carry?: number): string;
+/**
+ * Cap a message, keeping the NEWEST text.
+ *
+ * 🔴 The ring buffer bounds how many records are held; nothing bounded how large ONE of them could
+ * get. A producer streaming into a single record forever is an unbounded allocation inside a
+ * structure whose whole promise is that it is bounded — and it is invisible, because the record
+ * count never moves. Keeping the tail matches the ring buffer's own rule: a console is a window on
+ * recent output.
+ *
+ * ⚠️ Order matters where this is used: a message is redacted and only THEN truncated, so the cap
+ * counts redacted characters. Truncating first would measure raw text — and `«redacted»` is ten
+ * characters where the JWT it replaced was two hundred — leaving a retained window whose real
+ * length depends on how much of it happened to be a secret. That window is exactly what the next
+ * fragment's redaction scan is drawn from, so it must not vary. The other half of the same
+ * guarantee is the controller's clamp: a cap shorter than {@link REDACTION_CARRY} would let
+ * truncation eat the window outright.
+ *
+ * @param text - The message.
+ * @param max - Maximum length including the elision marker.
+ * @returns `text`, or its last `max - 1` characters behind {@link MESSAGE_ELISION}.
+ */
+declare function truncateLogMessage(text: string, max: number): string;
+/** Format a record as one copyable line. */
+declare function formatRecord(record: XenoLogRecord): string;
+/** Stringify a payload without throwing on a cycle. */
+declare function safeJson(value: unknown): string;
+
+/**
+ * The Console controller.
+ *
+ * ## 🔴 Redaction is not optional here
+ *
+ * This panel is the **single most likely place in the catalog for a secret to be displayed**: a log
+ * line is exactly where a token ends up, and unlike a log FILE this one is on screen. Every record
+ * is passed through `@xenosystem/panel-sdk`'s `redactForLog` **before it enters the buffer**, so the
+ * unredacted value is never stored, never searched, never copied, and never reaches
+ * `recordActivate`. Redacting at render time would leave the secret in memory and in the clipboard.
+ *
+ * 🔴 **A streamed record is redacted across every fragment boundary, not per fragment.** A secret
+ * split by an `appendMessage` — `"eyJhbGciOi"` then `"JIUzI1NiJ9.…"` — is invisible to a redactor
+ * that only ever sees one half, and would land in the buffer fully assembled: the half-clean
+ * record. `spliceRedactedAppend` is where that is prevented, and the message cap is clamped so
+ * truncation can never shorten the window it depends on.
+ *
+ * @module
+ */
+
+/** The host seam. */
+interface ConsoleHostBridge {
+    emit(portId: string, value: unknown): void;
+    /** Known secret values, re-read per record so a rotated vault needs no re-wiring. */
+    getSecrets?: () => Iterable<string>;
+}
+/** Construction options. */
+interface ConsoleControllerOptions {
+    host: ConsoleHostBridge;
+    initial?: Partial<ConsolePanelState>;
+    /** Ring-buffer capacity. Default 5000 — a console is not an archive. */
+    maxRecords?: number;
+    /**
+     * Maximum characters in ONE record's message. Default 65536.
+     *
+     * 🔴 `maxRecords` bounds how many lines are held and bounded nothing else until streaming
+     * existed: a producer appending into a single record forever grows without limit while the
+     * record count never moves, so the leak is invisible to every counter the panel shows. Clamped
+     * to at least twice {@link REDACTION_CARRY} — a cap short enough to eat the redaction window
+     * would let truncation re-open the split-secret hole the window exists to close.
+     */
+    maxMessageChars?: number;
+    /** Collapse adjacent duplicates. Default `true`. */
+    collapse?: boolean;
+    /** Follow the tail. Default `true`. */
+    follow?: boolean;
+}
+/** The Console panel controller. */
+declare class ConsoleController {
+    private readonly host;
+    private readonly listeners;
+    private readonly maxRecords;
+    private readonly maxMessageChars;
+    private records;
+    /**
+     * Record id → ABSOLUTE position, where absolute = array index + {@link origin}.
+     *
+     * Patching by id has to be O(1) or streaming is worse than the thing it replaces: a linear scan
+     * of a 5 000-record buffer per fragment, at a thousand fragments a second, is five million
+     * comparisons a second to update one line. (`runs/src/controller.ts` keeps the same index for the
+     * same reason.)
+     *
+     * The absolute/origin split is what makes the ring buffer cheap. The buffer trims from the FRONT,
+     * so storing raw array indices would mean decrementing every entry on every trim — O(n) per
+     * append once the buffer is full. An offset moves the whole map in one addition instead.
+     *
+     * ⚠️ Records with no id, or an empty one, are not indexed and therefore cannot be patched. That
+     * is the honest outcome: `id` is what "addressed" means here, and there is nothing else to
+     * address them by.
+     */
+    private index;
+    /** Absolute position of `records[0]`. */
+    private origin;
+    private filter;
+    private follow;
+    private collapse;
+    private rev;
+    private dropped;
+    private droppedPatches;
+    private snapshot;
+    constructor(options: ConsoleControllerOptions);
+    subscribe: (listener: () => void) => (() => void);
+    getState: () => ConsoleViewState;
+    private notify;
+    /**
+     * Apply a delta.
+     *
+     * @param delta - Append / patch / replace / clear.
+     * @returns `true` if applied; `false` if dropped as stale.
+     */
+    apply(delta: XenoLogDelta): boolean;
+    /**
+     * Apply the `patch` map of a delta.
+     *
+     * ⚠️ Every field is checked, not cast. A wire is a user-editable connection, so the wrong shape
+     * arriving is a normal mis-wire rather than an exceptional condition — and the failure mode here
+     * is not a throw but silent corruption: a `level` of `"shout"` would add a key to the level
+     * counts that no filter can ever match and no chip can ever reveal.
+     */
+    private applyPatches;
+    /**
+     * Fold a patch into a record, redacting what the patch brought in.
+     *
+     * 🔴 The append path redacts across the JOIN, not the fragment — {@link spliceRedactedAppend}
+     * carries the reasoning. Truncation runs last so the cap counts redacted characters; see
+     * {@link truncateLogMessage} for why measuring raw text would make the retained window vary.
+     *
+     * ⚠️ `source` is deliberately NOT redacted, matching `sanitize` on the append path: it is a
+     * stream name the host chose, and redacting it would break the per-source mute chips it keys.
+     */
+    private merge;
+    /** Array position of `id`, or `-1` when it is unknown or has been evicted. */
+    private positionOf;
+    /**
+     * Index a record.
+     *
+     * ⚠️ Last-wins when a host re-uses an id, which the contract forbids but nothing prevents. For a
+     * PATCH that is the right answer — a producer that re-used an id is talking about the line it
+     * just wrote, not one that scrolled past — and it also keeps eviction correct, because the ring
+     * trims from the front and so retires the older twin first.
+     */
+    private remember;
+    /** Drop an index entry, but only if it still points at the position being evicted. */
+    private forget;
+    /**
+     * Rebuild the whole index.
+     *
+     * Only for `clear` and `replace`, which remove from the middle and so invalidate every position
+     * after the hole. Those are cold paths — a source restarting — and paying O(n) there is what buys
+     * O(1) on the hot ones.
+     */
+    private reindex;
+    /** Append records directly — sugar for the common case. */
+    append(records: readonly XenoLogRecord[]): boolean;
+    /**
+     * Redact a record on the way IN.
+     *
+     * Not at render: redacting late leaves the secret in the buffer, in search results, and in
+     * whatever `copy` puts on the clipboard.
+     */
+    private sanitize;
+    /** Replace the filter. */
+    setFilter(filter: XenoLogFilter): void;
+    /** Set the search term. */
+    setSearch(search: string): void;
+    /** Set the minimum severity. */
+    setLevel(minLevel: XenoLogLevel | undefined): boolean;
+    /** Show or hide one source. */
+    toggleSource(source: string, enabled?: boolean): void;
+    /** The visible rows, filtered and (optionally) collapsed. */
+    rows(): XenoLogRecord[];
+    /** Every source seen, with its contribution count and current visibility. */
+    sources(): XenoLogSource[];
+    /** Follow the tail. Auto-disabled by the view when the user scrolls up. */
+    setFollow(follow: boolean): void;
+    /** Collapse adjacent duplicates. */
+    setCollapse(collapse: boolean): void;
+    /** Drop every record. Emits nothing — clearing a view is not an event a host acts on. */
+    clear(): void;
+    /**
+     * A record was opened.
+     *
+     * **This is what makes the panel useful in a builder**: clicking a log line tells the host which
+     * node or panel produced it, so it can reveal the offender.
+     */
+    activate(recordId: string): boolean;
+    /** The copyable text of a record — already redacted, because the buffer is. */
+    copyText(recordId: string): string | null;
+    /** The copyable text of everything currently visible. */
+    copyVisible(): string;
+    /** Ask the host to open a context menu. */
+    requestContextMenu(recordId: string, x: number, y: number): void;
+    /** The raw buffer, for `get_records`. */
+    all(): XenoLogRecord[];
+    /** Serialize. Filter and toggles — **never the records**; a log is not a document. */
+    serialize(): ConsolePanelState;
+    /** Restore. Does not emit. */
+    deserialize(state: Partial<ConsolePanelState>): void;
+    /** Drop listeners and the buffer. */
+    dispose(): void;
+}
+
+/**
+ * The `PanelModule` — view wired inside the package (one React copy).
+ *
+ * @module
+ */
+
+/** Everything a renderer needs: the controller plus the resolved config. */
+interface ConsoleRenderContext {
+    controller: ConsoleController;
+    config: {
+        rowHeight: number;
+        showTimestamps: boolean;
+        emptyHint?: string;
+    };
+}
+/** Options for {@link createConsolePanel}. */
+interface CreateConsolePanelOptions {
+    /**
+     * Known secret values, re-read per record.
+     *
+     * Supply it when the host has a vault: the shape-driven backstop catches an unregistered token,
+     * but an exact value the host already knows is caught even when it looks ordinary.
+     */
+    getSecrets?: () => Iterable<string>;
+    /** Override the view. Rarely needed — mounting inside the package keeps React singular. */
+    render?: (root: HTMLElement, context: ConsoleRenderContext) => () => void;
+}
+/**
+ * Build the Console panel module.
+ *
+ * @param options - Secret source and optional renderer override.
+ * @returns The module.
+ */
+declare function createConsolePanel(options?: CreateConsolePanelOptions): PanelModule;
+/** The default Console panel module — view already wired. Register THIS. */
+declare const consolePanel: PanelModule;
+
+/**
+ * The `xeno.core.console` manifest.
+ *
+ * Capabilities: `storage.local` only. The panel receives records; it never opens a stream itself.
+ *
+ * @module
+ */
+
+/** The canonical manifest id. */
+declare const CONSOLE_PANEL_ID = "xeno.core.console";
+/** The `xeno.core.console` manifest. */
+declare const consoleManifest: PanelManifest;
+
+/**
+ * The Console panel view — virtualized, follow-tail, per-source chips.
+ *
+ * Composes `@xenosystem/workbench/primitives`; the host must ensure `@xenosystem/workbench/primitives.css` is
+ * present.
+ *
+ * @module
+ */
+
+/** Props for {@link ConsolePanelView}. */
+interface ConsolePanelViewProps {
+    controller: ConsoleController;
+    rowHeight?: number;
+    showTimestamps?: boolean;
+    emptyHint?: string;
+}
+/** The Console panel view. */
+declare function ConsolePanelView({ controller, rowHeight, showTimestamps, emptyHint, }: ConsolePanelViewProps): ReactNode;
+
+/**
+ * The `xeno.core.runs` contract.
+ *
+ * ## 🔴 The boundary: runs is NOT history and NOT versions
+ *
+ * Three genuinely different things that keep getting conflated:
+ *
+ * | Panel | Models | Ordered by | The user question |
+ * |---|---|---|---|
+ * | **`xeno.core.runs`** | *executions* — things that started, progressed and ended | when they ran | "did it work, and what happened?" |
+ * | `xeno.core.history` | an *undo stack* — reversible document edits | position in a stack, with a cursor | "how do I get back?" |
+ * | `xeno.core.versions` | *document snapshots* | when they were saved | "what did this look like then?" |
+ *
+ * A run is **not undoable** and cancelling one is not going back. The conflation is not
+ * hypothetical: xeno-workflow's execution-history panel lives in a directory literally named
+ * `components/history/`, and its failed-runs panel is a *second panel* for what is one archetype
+ * filtered to `status: 'failed'` (§ landmine L2 below).
+ *
+ * @module
+ */
+/**
+ * Run lifecycle — **the single source the whole contract is derived from.**
+ *
+ * The vocabulary unions what the incumbents each had: workflow contributed
+ * `running | success | error | cancelled` plus trigger and duration, browser's downloads
+ * contributed `paused` and progress, post's approvals contributed multi-step lifecycle, and
+ * `queued` / `blocked` come from every queue that has ever had a backlog. `requested`,
+ * `awaiting-decision` and `awaiting-permission` join them from the same survey: a hosted run is
+ * asked for before any queue accepts it, an approvals queue stops on a human, and a sandboxed one
+ * stops on a grant. xeno-agent-interface's own run lifecycle carries `starting`,
+ * `waiting_for_user` and `waiting_for_permission` for exactly these three — the names here are the
+ * generic form of that, because a build waiting on a reviewer and a download waiting on a folder
+ * grant are the same fact.
+ *
+ * 🔴 **Widening this union used to be a THREE-PLACE edit with nothing making the places agree.**
+ * The union was written out here, restated as a hardcoded literal in `RunsController.getState` to
+ * seed `counts`, and restated a third time in `ALL_STATUSES`. Either restatement could silently
+ * fall behind: a status missing from the `counts` seed made `counts[status] += 1` evaluate
+ * `undefined + 1`, so a real status rendered as a `NaN` chip and its runs vanished from the
+ * filter. Everything is now derived from this one tuple.
+ */
+declare const RUN_STATUSES: readonly ["requested", "queued", "running", "paused", "blocked", "awaiting-decision", "awaiting-permission", "succeeded", "failed", "cancelled"];
+/** Run lifecycle. */
+type XenoRunStatus = (typeof RUN_STATUSES)[number];
+/**
+ * What a status says about whether the run will move on its own.
+ *
+ * Three classes, not two, and the third is the one consumers keep getting wrong:
+ *
+ * - `active` — it will progress without anyone doing anything.
+ * - `waiting` — non-terminal, but nothing happens until something OUTSIDE the run acts.
+ * - `terminal` — finished, whatever the outcome.
+ *
+ * A dashboard that folds `waiting` into `active` reports a healthy pipeline while every run in it
+ * is stopped on a permission prompt nobody has seen.
+ */
+type XenoRunLifecycle = 'active' | 'waiting' | 'terminal';
+/**
+ * Which class is this status in?
+ *
+ * 🔴 An unrecognised string answers `waiting`, not `active` and not `terminal`. A host one version
+ * ahead of this build sends a status nothing here has heard of, and every other answer is worse:
+ * `terminal` files a still-executing run into the success-rate denominator and offers Retry for
+ * work that is still running; `active` claims it is progressing. `waiting` is the honest reading —
+ * it has not finished and it is not moving by itself as far as we can tell.
+ */
+declare function lifecycleOf(status: XenoRunStatus): XenoRunLifecycle;
+/**
+ * Statuses a run cannot leave. **Derived from {@link RUN_LIFECYCLE}, never restated.**
+ *
+ * **Terminal vs non-terminal belongs in the contract, not in each consumer.** workflow's
+ * `analyticsModel` computes success rate over terminal runs only — a rate that counted the three
+ * runs still executing would tick downward every time work started, which is the opposite of what
+ * it means. Every consumer needs that distinction, so it is defined once.
+ */
+declare const TERMINAL_STATUSES: ReadonlySet<XenoRunStatus>;
+/** Has this run finished, one way or another? */
+declare function isTerminal(status: XenoRunStatus): boolean;
+/** Is this run still going to change on its own? */
+declare function isActive(status: XenoRunStatus): boolean;
+/** Is this run stopped on something outside itself — a person, a grant, an upstream job? */
+declare function isWaiting(status: XenoRunStatus): boolean;
+/** A typed failure. Never a bare string — a consumer must be able to branch and to group. */
+interface XenoRunError {
+    /** Machine code, and the key the failure view groups by. */
+    code: string;
+    /** Host-authored sentence, rendered verbatim. */
+    message: string;
+    /** Extra context (a stack, a node id, a response body excerpt). */
+    detail?: string;
+    /** Whether retrying might succeed. Drives whether Retry is offered at all. */
+    retryable?: boolean;
+}
+/**
+ * One step of a run — **recursively**.
+ *
+ * Modelled as a nested list rather than a second panel: workflow expands a run to per-node
+ * input/output, post shows multi-step approval progress. Same shape, one panel.
+ *
+ * 🔴 **A step owns steps, so the model is a TREE and not two levels.** Until 0.2.0 a step was a
+ * leaf, which made real nested execution unrepresentable — a workflow whose node is itself a
+ * workflow, a build that fans out to sub-builds, a run that spawns a child run with its own steps.
+ * Every one of those had to be flattened by the host into a single list of siblings, which throws
+ * away the only thing the user was looking for: *which* stage the failure is under. The recursion
+ * is generic on purpose; nothing here knows what a step contains.
+ *
+ * ⚠️ **Sibling ids must be unique.** A step is addressed by the path of ids from its run down to
+ * it ({@link XenoRunPath}), so two siblings sharing an id make that address ambiguous; resolution
+ * takes the first and the projection still renders both, but a patch aimed at the second will
+ * never reach it. Uniqueness is the host's to guarantee — nothing can recover it after the fact.
+ */
+interface XenoRunStep {
+    id: string;
+    label: string;
+    status: XenoRunStatus;
+    startedAt?: number;
+    endedAt?: number;
+    /** `0`–`1`. */
+    progress?: number;
+    error?: XenoRunError;
+    /** Pre-formatted detail lines — the host formats, the panel places. */
+    detail?: Record<string, string>;
+    /**
+     * Nested steps.
+     *
+     * ⚠️ Nothing stops a host handing back a structure that points at one of its own ancestors —
+     * step objects are shared by reference and a producer that reuses one builds a cycle without
+     * meaning to. The projection guards against it ({@link XenoRunTruncation}); a consumer walking
+     * this field itself must do the same, or the walk does not terminate.
+     */
+    steps?: XenoRunStep[];
+}
+/**
+ * The address of one step: the run id, then each step id down the tree.
+ *
+ * A bare `stepId` is only unambiguous while the model is two levels deep. Once a step owns steps,
+ * `'compile'` may name a step under `plan`, under `verify`, or both.
+ */
+type XenoRunPath = readonly string[];
+/**
+ * Separator for the string form of a {@link XenoRunPath}.
+ *
+ * 🔴 **NUL, and it is not decoration.** Any printable separator collides: joined with a space,
+ * `('a b', 'c')` and `('a', 'b c')` produce the same key. That is not hypothetical — `xeno-shell`
+ * shipped it, where `core/acl.ts` joined grant keys with a space while `mountBroker.grantKeyOf`
+ * used NUL, so two different grants could authorise each other. Both use NUL now, and so does this.
+ */
+declare const RUN_PATH_SEPARATOR = "\0";
+/**
+ * Path → the key used for expansion state and as a React key.
+ *
+ * ⚠️ A one-element path encodes to the id itself, unchanged. That is what makes a `RunsPanelState`
+ * serialized before 0.2.0 — `expanded: ['r1']`, a list of bare run ids — restore correctly: those
+ * strings ARE the encoded run-level paths, byte for byte.
+ */
+declare function encodeRunPath(path: XenoRunPath): string;
+/** The inverse of {@link encodeRunPath}. */
+declare function decodeRunPath(key: string): string[];
+/** Why a subtree was cut short in the projection. */
+type XenoRunTruncation = 'cycle' | 'depth';
+/** Default depth cap for the projection. Deep enough for real nesting, shallow enough to bound. */
+declare const DEFAULT_MAX_STEP_DEPTH = 32;
+/** One run. */
+interface XenoRun {
+    /** Stable id — identity for patches, actions and activation. */
+    id: string;
+    /** Display label. */
+    label: string;
+    status: XenoRunStatus;
+    /**
+     * Epoch ms. **Runs are ordered by this, newest first** — it is the sort key, and it is required.
+     *
+     * 🔴 It is *when the run entered the list*, which is not the same as when it began executing.
+     * That distinction used to be missing, and the gap showed as a contradiction: a `queued` run has
+     * not started, yet the field is mandatory, so every host put its enqueue time here anyway and
+     * the panel then reported a run that waited ten minutes and ran for two seconds as having taken
+     * ten minutes and two seconds. The field's meaning is now the one every host was already using;
+     * {@link XenoRun.executionStartedAt} carries the other fact, and {@link durationOf} prefers it.
+     *
+     * ⚠️ Keeping it required is deliberate. Ordering is what this panel IS, and a sort key that may
+     * be absent has to be defaulted somewhere — which is how a queued run ends up at the epoch, at
+     * the bottom of the list, exactly where nobody looks for the thing they just asked for.
+     */
+    startedAt: number;
+    /**
+     * Epoch ms at which work actually began — absent while the run is still `requested` or `queued`.
+     *
+     * Absent means "no execution start is known", which {@link durationOf} treats exactly as it did
+     * before this field existed: it falls back to `startedAt`. A host that never sets it sees no
+     * change at all.
+     */
+    executionStartedAt?: number;
+    /** Epoch ms. Present iff terminal. */
+    endedAt?: number;
+    /** `0`–`1`. Absent means indeterminate, which is different from `0`. */
+    progress?: number;
+    /** Which stream produced it — the multiplex key, as in the console. */
+    source?: string;
+    /** What started it (`'manual'`, `'schedule'`, `'webhook'`, a user id). */
+    trigger?: string;
+    /** Sub-runs. */
+    steps?: XenoRunStep[];
+    /** Set when `status === 'failed'`. */
+    error?: XenoRunError;
+    /** How many times this has already been retried. */
+    retryCount?: number;
+    /** The host permits cancellation. Absent ⇒ inferred from the status. */
+    canCancel?: boolean;
+    /** The host permits retry. Absent ⇒ inferred from the status and `error.retryable`. */
+    canRetry?: boolean;
+    /** Pre-formatted extra fields for the row. */
+    fields?: Record<string, string>;
+}
+/**
+ * One step's worth of change, addressed by path.
+ *
+ * 🔴 **The path is an ARRAY and never a joined string, at the contract boundary.** A joined key
+ * has to pick a separator, and every printable choice collides with an id that contains it — see
+ * {@link RUN_PATH_SEPARATOR}. Producers build these ids from node names, file paths and user text,
+ * so "no id will contain a slash" is a promise nobody can keep. An array cannot collide.
+ */
+interface XenoRunStepPatch {
+    /** Which run the step belongs to. */
+    runId: string;
+    /** Step ids from the run's own `steps` down to the target. Must be non-empty. */
+    path: XenoRunPath;
+    /** Merged shallowly onto the addressed step. `id` is identity and is never overwritten. */
+    patch: Partial<XenoRunStep>;
+}
+/** New steps for a run, or for a step inside one. */
+interface XenoRunStepAppend {
+    /** Which run. */
+    runId: string;
+    /** Path to the PARENT step. Absent or empty ⇒ the run's own top-level `steps`. */
+    path?: XenoRunPath;
+    /**
+     * The steps to add.
+     *
+     * ⚠️ Upsert, not blind push: a step whose id already exists among that parent's children is
+     * REPLACED where it stands. A producer re-announcing a step it already announced is ordinary —
+     * a reconnect, a resend, a retry — and appending blindly turns each of those into a duplicate
+     * row and a second, unreachable address for the same work.
+     */
+    steps: XenoRunStep[];
+}
+/**
+ * An append/patch-oriented update.
+ *
+ * **Live progress must not thrash.** A downloads-style panel re-pushing twenty rows at 60 Hz is the
+ * failure mode: 1 200 array copies a second, every one of them discarding structural sharing. So
+ * `patch` addresses runs BY ID and carries only what changed.
+ *
+ * 🔴 **`patch` alone did not finish the job, and per-step streaming defeated it.** It is applied as
+ * a shallow spread, so the only way to move one step's progress bar was to resend the run's whole
+ * `steps` array — reintroducing exactly the array copying the delta exists to prevent, one level
+ * down, and discarding structural sharing for every untouched sibling and subtree. `patchSteps`
+ * and `appendSteps` address a step directly and copy only the spine from the run down to it.
+ */
+interface XenoRunDelta {
+    /** Monotonic revision. A delta whose rev has not advanced is dropped. */
+    rev?: number;
+    /** New runs. */
+    append?: XenoRun[];
+    /** Partial updates, keyed by run id. The hot path for progress. */
+    patch?: Record<string, Partial<XenoRun>>;
+    /**
+     * New steps, addressed to a run or to a step inside one. Applied before {@link patchSteps}, so a
+     * producer may announce a step and set its progress in a single delta.
+     */
+    appendSteps?: XenoRunStepAppend[];
+    /**
+     * Per-step updates. The hot path for a nested run.
+     *
+     * ⚠️ Kept out of `patch` rather than folded into it. `patch` is keyed by run id; a step id that
+     * happened to equal a run id would silently address the wrong thing, and the two are minted by
+     * different producers with no reason to be distinct.
+     */
+    patchSteps?: XenoRunStepPatch[];
+    /** Ids to drop. */
+    remove?: string[];
+    /** Replace the whole list (a source restarted). */
+    replace?: XenoRun[];
+    /** Drop everything. Wins over `append` in the same delta. */
+    clear?: boolean;
+    /** Restrict `replace`/`clear` to one source. */
+    source?: string;
+}
+/** The active filter. */
+interface XenoRunFilter {
+    /** Statuses to show. Absent/empty ⇒ all. */
+    statuses?: XenoRunStatus[];
+    /** Sources to hide. */
+    mutedSources?: string[];
+    /** Case-insensitive substring over label, source, trigger and error code. */
+    search?: string;
+}
+/**
+ * An intent the panel emits. The panel never executes or cancels anything itself.
+ *
+ * ⚠️ `stepId` and `stepPath` are two views of one target and are always emitted together.
+ * `stepId` is the LAST element of `stepPath`, which is what it already meant when the model was
+ * two levels deep — so a host reading only `stepId` behaves exactly as it did, and a host that
+ * reads `stepPath` can tell `verify ▸ compile` from `plan ▸ compile`.
+ */
+interface XenoRunAction {
+    runId: string;
+    action: 'cancel' | 'retry';
+    /** The targeted step's own id — the last element of {@link stepPath}. */
+    stepId?: string;
+    /** The full address of the targeted step, from the run's own `steps` down. */
+    stepPath?: XenoRunPath;
+}
+/** A run was opened — the reveal hook, same idea as the console's `recordActivate`. */
+interface XenoRunActivate {
+    runId: string;
+    source?: string;
+    /** The activated step's own id — the last element of {@link stepPath}. */
+    stepId?: string;
+    /** The full address of the activated step. */
+    stepPath?: XenoRunPath;
+}
+/** Aggregate counters, computed over TERMINAL runs where that is the meaningful denominator. */
+interface XenoRunStats {
+    total: number;
+    /** Runs that have finished. */
+    terminal: number;
+    /** Still going to change on its own. */
+    active: number;
+    /**
+     * Non-terminal, but stopped on something outside the run — a person, a grant, an upstream job.
+     *
+     * Counted separately from `active` because folding the two together is how a dashboard reports a
+     * busy pipeline in which nothing is moving. `total` is therefore `terminal + active + waiting`
+     * for any run whose status this build recognises.
+     */
+    waiting: number;
+    succeeded: number;
+    failed: number;
+    cancelled: number;
+    /**
+     * Successes ÷ terminal runs, or `null` when nothing has finished.
+     *
+     * `null` rather than `0`: "no runs have finished" and "every finished run failed" are different
+     * facts, and showing 0 % for the first is a lie the user acts on.
+     */
+    successRate: number | null;
+    /** Mean duration of terminal runs with both timestamps, in ms. `null` when none. */
+    meanDurationMs: number | null;
+}
+/** The panel's serialized state. **Runs are never persisted** — an execution log is not a document. */
+interface RunsPanelState {
+    filter: XenoRunFilter;
+    /**
+     * Encoded paths ({@link encodeRunPath}) of everything expanded — runs and steps alike.
+     *
+     * ⚠️ A run-level entry encodes to the bare run id, so state written before 0.2.0 restores
+     * unchanged. Entries that no longer resolve are kept rather than pruned: a run that has scrolled
+     * out of the ring buffer and comes back should come back expanded.
+     */
+    expanded: string[];
+}
+/** Shared by every row of the projection. */
+interface XenoRunRowBase {
+    /**
+     * Unique within one projection — safe as a React key.
+     *
+     * Normally the encoded path. ⚠️ It is NOT the address: two siblings sharing an id would produce
+     * one key for two rows, and React would drop one of them silently, so a duplicate gets a
+     * disambiguating suffix. Address a row by {@link XenoRunRowBase.stepPath}, never by its key.
+     */
+    key: string;
+    /** The run this row belongs to, whether it is the run row or a step under it. */
+    runId: string;
+    /** The owning run — present on every row, because a step's actions are run-scoped. */
+    run: XenoRun;
+    /** `0` for the run row, `1` for its own steps, and so on. */
+    depth: number;
+    /** Step ids from the run down to this row. Empty on a run row. */
+    stepPath: XenoRunPath;
+    /** Does this row own steps? True even when the subtree was cut — the children exist. */
+    hasChildren: boolean;
+    /** Are its children currently in the projection? */
+    expanded: boolean;
+    /**
+     * Set when this row's children were NOT walked, and why.
+     *
+     * 🔴 A cut subtree is surfaced rather than swallowed. A cycle silently rendered as a leaf is
+     * indistinguishable from a step that genuinely has no children, and a user debugging a nested
+     * run would read "nothing under here" as a fact about their pipeline.
+     */
+    truncated?: XenoRunTruncation;
+}
+/** A run's own row. */
+interface XenoRunRunRow extends XenoRunRowBase {
+    kind: 'run';
+    depth: 0;
+}
+/** One step's row, at any depth. */
+interface XenoRunStepRow extends XenoRunRowBase {
+    kind: 'step';
+    step: XenoRunStep;
+}
+/**
+ * One rendered line — a run or a step at any depth.
+ *
+ * 🔴 **The tree is flattened HERE, in the controller, and not by a recursive render.** A recursive
+ * component cannot be windowed: virtualization needs to answer "what is the nth visible row?" in
+ * O(1), and with the tree walked inside the view that question has no answer without walking it
+ * again. Flattening also gives the depth cap and the cycle guard one home instead of one per
+ * consumer — this panel already ships to more than one host.
+ */
+type XenoRunRow = XenoRunRunRow | XenoRunStepRow;
+/** What the controller exposes to its view. */
+interface RunsViewState {
+    /** Visible runs, newest first. */
+    runs: XenoRun[];
+    /**
+     * The same runs flattened to rows, with the expanded steps spliced in beneath each.
+     *
+     * Derived from `runs` and the expansion set; `runs` is unchanged and still the whole runs. A
+     * consumer that only ever rendered `runs` is unaffected.
+     */
+    rows: XenoRunRow[];
+    /** Every source seen, for the filter chips. */
+    sources: {
+        id: string;
+        label: string;
+        enabled: boolean;
+        count: number;
+    }[];
+    filter: XenoRunFilter;
+    /** Counts per status across the WHOLE list, so a chip shows what it would reveal. */
+    counts: Record<XenoRunStatus, number>;
+    /** Aggregates. */
+    stats: XenoRunStats;
+    /** Run ids whose steps are expanded. */
+    expanded: string[];
+    /** Total held before filtering. */
+    total: number;
+    /** Runs dropped by the ring buffer. */
+    dropped: number;
+}
+/**
+ * Every status, in lifecycle order. **The tuple itself** — this used to be a hand-kept copy of it.
+ *
+ * ⚠️ The order is the reading order of a run's life and the render order of the filter chips, which
+ * is why {@link RUN_STATUSES} is declared as an ordered tuple rather than derived from the
+ * lifecycle table's keys.
+ */
+declare const ALL_STATUSES: readonly XenoRunStatus[];
+/**
+ * May this run be cancelled?
+ *
+ * An explicit `canCancel` wins; otherwise only a non-terminal run can be. A Cancel button on a
+ * finished run is worse than no button — it implies the run is still doing something.
+ */
+declare function canCancel(run: XenoRun): boolean;
+/**
+ * May this run be retried?
+ *
+ * An explicit `canRetry` wins; otherwise a failed or cancelled run may be, unless the error says
+ * the failure is not retryable.
+ */
+declare function canRetry(run: XenoRun): boolean;
+/**
+ * How long the WORK took — elapsed for a running one, final for a terminal one. `null` if
+ * unknowable.
+ *
+ * Measured from {@link XenoRun.executionStartedAt} when the host reports one, and from
+ * `startedAt` otherwise. ⚠️ The fallback is what makes this unchanged for every existing host: a
+ * run with no `executionStartedAt` produces exactly the number it produced before the field
+ * existed. A host that does set it stops reporting queue time as run time.
+ */
+declare function durationOf(run: XenoRun, now: number): number | null;
+/**
+ * How long the run WAITED before work began, in ms. `null` when that is not knowable.
+ *
+ * The other half of the split, and the one a queue owner actually asks for. A run still waiting
+ * reports its wait so far; a run that never reported an execution start reports `null` rather than
+ * `0`, because "it never waited" and "we were never told" are different facts and only one of them
+ * is worth putting on a dashboard.
+ */
+declare function queueDurationOf(run: XenoRun, now: number): number | null;
+/** Does a run match a search term? */
+declare function matchesSearch(run: XenoRun, term: string): boolean;
+/** Compute aggregates over a run list. */
+declare function computeStats(runs: readonly XenoRun[]): XenoRunStats;
+/** Format a duration compactly: `820ms`, `4.2s`, `3m 05s`, `1h 12m`. */
+declare function formatDuration(ms: number): string;
+
+/**
+ * The Runs controller.
+ *
+ * Intents only: the panel emits `cancel` / `retry` and the host performs them. It never executes,
+ * never cancels, never retries — and, critically, **never optimistically flips a status**. A run
+ * shown as `cancelled` because the panel assumed so, when the host actually refused, is a lie the
+ * user acts on.
+ *
+ * @module
+ */
+
+/** The host seam. */
+interface RunsHostBridge {
+    emit(portId: string, value: unknown): void;
+    /** Wall clock, injectable for tests. */
+    now?: () => number;
+    /** Timer seam, injectable for tests. */
+    clock?: ThrottleClock;
+}
+/** Construction options. */
+interface RunsControllerOptions {
+    host: RunsHostBridge;
+    initial?: Partial<RunsPanelState>;
+    /** Ring capacity. Default 500 — a runs list is recent activity, not an archive. */
+    maxRuns?: number;
+    /**
+     * Minimum ms between re-projections. Default 100.
+     *
+     * The failure mode this exists for: twenty download rows patching at 60 Hz is 1 200 notifications
+     * a second, every one of them re-filtering and re-sorting the whole list.
+     */
+    throttleMs?: number;
+    /**
+     * How deep below a run the row projection may walk. Default 32.
+     *
+     * A bound, not a preference — see `flattenRunRows`. Nesting past this is cut and the cut is
+     * reported on the row, never silently rendered as a leaf.
+     */
+    maxDepth?: number;
+}
+/** The Runs panel controller. */
+declare class RunsController {
+    private readonly host;
+    private readonly listeners;
+    private readonly maxRuns;
+    private readonly maxDepth;
+    private readonly now;
+    private readonly notifyThrottled;
+    /** Runs by id — patching by id is O(1), which is the whole point of the delta. */
+    private readonly byId;
+    private order;
+    private filter;
+    private expanded;
+    private rev;
+    private dropped;
+    private snapshot;
+    constructor(options: RunsControllerOptions);
+    subscribe: (listener: () => void) => (() => void);
+    getState: () => RunsViewState;
+    /** Invalidate and notify immediately. */
+    private flush;
+    /** Invalidate now, notify on the throttle — the hot path. */
+    private notify;
+    /** Emit any pending notification immediately. Call before reading in a test. */
+    flushNow(): void;
+    /**
+     * Apply a delta.
+     *
+     * @param delta - append / patch / remove / replace / clear.
+     * @returns `true` if applied; `false` if dropped as stale.
+     */
+    apply(delta: XenoRunDelta): boolean;
+    private insert;
+    /**
+     * Merge a patch into one step of one run.
+     *
+     * 🔴 The run object is replaced but its untouched subtrees are SHARED — `patchStepAtPath` copies
+     * only the spine. This is the whole reason per-step addressing exists: the alternative a host had
+     * was resending `steps` wholesale on every tick, which is the array-copy storm the delta was
+     * designed to prevent, reintroduced one level down.
+     *
+     * @returns `true` when the address resolved and the patch landed.
+     */
+    private applyStepPatch;
+    /**
+     * Add steps to a run, or to a step inside one.
+     *
+     * An unresolvable PARENT is refused rather than created, for the same reason a patch for an
+     * unknown run is: a parent conjured from an append has no label and no status, so it renders as
+     * a row that will never resolve into anything.
+     *
+     * @returns `true` when the parent resolved and the steps landed.
+     */
+    private applyStepAppend;
+    /** Ring-buffer the OLDEST runs away, never the newest. */
+    private trim;
+    /** Every run, newest first. */
+    all(): XenoRun[];
+    /** Replace the filter. */
+    setFilter(filter: XenoRunFilter): void;
+    /** Set the search term. */
+    setSearch(search: string): void;
+    /**
+     * Show only these statuses. Empty/absent shows everything.
+     *
+     * **A dead-letter view is `statuses: ['failed']` plus a search — not a second panel.** That is
+     * exactly how one incumbent ended up maintaining two panels for one archetype.
+     */
+    setStatuses(statuses: readonly XenoRunStatus[]): void;
+    /** Show or hide one source. */
+    toggleSource(source: string, enabled?: boolean): void;
+    /** The visible runs, newest first. */
+    visible(): XenoRun[];
+    /** Every source seen. */
+    sources(): RunsViewState['sources'];
+    /**
+     * Ask the host to cancel a run.
+     *
+     * Refuses a run that cannot be cancelled, and **does not flip the status locally**: the run
+     * becomes `cancelled` when the host says so, not when the panel asks.
+     */
+    cancel(runId: string, step?: string | XenoRunPath): boolean;
+    /** Ask the host to retry a run. */
+    retry(runId: string, step?: string | XenoRunPath): boolean;
+    /**
+     * Clear TERMINAL runs from the view.
+     *
+     * Only terminal ones: clearing a running download would remove the row while the transfer
+     * continues, and the user would have no way back to it.
+     *
+     * @returns How many were removed.
+     */
+    clearTerminal(): number;
+    /** A run was opened — the reveal hook. */
+    activate(runId: string, step?: string | XenoRunPath): boolean;
+    /**
+     * Expand or collapse a run, or one step inside it.
+     *
+     * @param runId - The run.
+     * @param stepPath - Address of a step within it. Absent ⇒ the run's own row.
+     * @returns `true` when the target existed and its state flipped.
+     *
+     * ⚠️ The key for a run is its bare id, so a `RunsPanelState` written before step expansion
+     * existed restores unchanged — those stored strings ARE the encoded run-level paths.
+     *
+     * 🔴 A step path is resolved before it is stored. An address that names nothing would otherwise
+     * accumulate in a set that is serialized, so a host with a churning step tree would grow its
+     * persisted state without bound and never be able to tell which entries still meant anything.
+     */
+    toggleExpanded(runId: string, stepPath?: XenoRunPath): boolean;
+    /** Ask the host to open a context menu. */
+    requestContextMenu(runId: string, x: number, y: number): void;
+    /** Serialize. Filter and expansion — **never the runs**; an execution log is not a document. */
+    serialize(): RunsPanelState;
+    /** Restore. Does not emit. */
+    deserialize(state: Partial<RunsPanelState>): void;
+    /** Drop listeners, timers and the buffer. */
+    dispose(): void;
+}
+
+/**
+ * The `PanelModule` — view wired inside the package (one React copy).
+ *
+ * @module
+ */
+
+/** Everything a renderer needs: the controller plus the resolved config. */
+interface RunsRenderContext {
+    controller: RunsController;
+    config: {
+        showStats: boolean;
+        showProgress: boolean;
+        rowHeight: number;
+        emptyHint?: string;
+    };
+}
+/** Options for {@link createRunsPanel}. */
+interface CreateRunsPanelOptions {
+    /** Override the view. Rarely needed — mounting inside the package keeps React singular. */
+    render?: (root: HTMLElement, context: RunsRenderContext) => () => void;
+}
+/**
+ * Build the Runs panel module.
+ *
+ * @param options - Optional renderer override.
+ * @returns The module.
+ */
+declare function createRunsPanel(options?: CreateRunsPanelOptions): PanelModule;
+/** The default Runs panel module — view already wired. Register THIS. */
+declare const runsPanel: PanelModule;
+
+/**
+ * The `xeno.core.runs` manifest.
+ *
+ * Capabilities: `storage.local` only. The panel emits intents; the host executes and cancels.
+ *
+ * @module
+ */
+
+/** The canonical manifest id. */
+declare const RUNS_PANEL_ID = "xeno.core.runs";
+/** The `xeno.core.runs` manifest. */
+declare const runsManifest: PanelManifest;
+
+/**
+ * Step-tree operations: resolve an address, patch through it, append under it, and flatten the
+ * whole thing to rows.
+ *
+ * 🔴 **Every function here copies the SPINE and shares everything else.** That is the entire point.
+ * The delta shape exists because re-pushing a list at 60 Hz costs 1 200 array copies a second, and
+ * a step tree reintroduces that failure one level down: a `structuredClone` of the run, or a
+ * rebuild of `steps` on every progress tick, is exactly as expensive as resending the list and
+ * throws away structural sharing for every untouched sibling and subtree. Patching a step four
+ * levels down copies four arrays and four objects — the path — and nothing else.
+ *
+ * @module
+ */
+
+/**
+ * Follow an address to the step it names.
+ *
+ * ⚠️ First match wins when siblings share an id. Not a preference — there is nothing else to do
+ * with an ambiguous address, and inventing a rule ("the last one", "the running one") would make
+ * which step a patch reaches depend on the order the host happened to emit them in.
+ *
+ * @param steps - The list to search, i.e. the parent's children.
+ * @param path - Step ids, root first. An empty path resolves to nothing.
+ * @returns The step, or `null` when any segment is missing.
+ */
+declare function resolveStepPath(steps: readonly XenoRunStep[] | undefined, path: XenoRunPath): XenoRunStep | null;
+/**
+ * Merge a patch into the step at `path`, copying only the spine.
+ *
+ * @param steps - The run's own `steps`.
+ * @param path - Address of the target, run-relative.
+ * @param patch - Fields to merge. `id` is identity and is never overwritten.
+ * @returns A new `steps` array, or `null` when the path does not resolve.
+ *
+ * 🔴 Returning `null` rather than creating the missing step is the same invariant the run-level
+ * `patch` already holds: *a patch for something unknown is ignored, never upserted*. Inventing a
+ * step from a partial is how a tree fills with half-formed nodes after a reconnect — and a step
+ * conjured that way has no status, so it renders as a row nothing can ever complete.
+ */
+declare function patchStepAtPath(steps: readonly XenoRunStep[] | undefined, path: XenoRunPath, patch: Partial<XenoRunStep>): XenoRunStep[] | null;
+/**
+ * Add steps under `path`, copying only the spine.
+ *
+ * @param steps - The run's own `steps`.
+ * @param path - Address of the PARENT. Empty means the run itself.
+ * @param incoming - Steps to add; one whose id already exists there replaces it in place.
+ * @returns A new `steps` array, or `null` when the parent path does not resolve.
+ *
+ * ⚠️ Upsert-by-id, and replacing *in place* rather than moving the step to the end: the order of a
+ * run's steps is the order the work happened in, and a re-announced step that jumps to the bottom
+ * of its list rewrites that history in front of the user while they are reading it.
+ */
+declare function appendStepsAtPath(steps: readonly XenoRunStep[] | undefined, path: XenoRunPath, incoming: readonly XenoRunStep[]): XenoRunStep[] | null;
+/** Options for {@link flattenRunRows}. */
+interface FlattenOptions {
+    /** Encoded paths that are open. See {@link encodeRunPath}. */
+    expanded: ReadonlySet<string>;
+    /** How deep below a run the walk may go. Default {@link DEFAULT_MAX_STEP_DEPTH}. */
+    maxDepth?: number;
+}
+/**
+ * Project runs and their expanded steps into one flat, ordered list of rows.
+ *
+ * 🔴 **Two independent things stop this walk, and both are load-bearing.**
+ *
+ * A **depth cap** bounds a legitimately deep tree — a build of builds of builds — so a pathological
+ * but acyclic structure cannot produce a projection the view spends a whole frame budget on.
+ *
+ * A **cycle guard** bounds an illegal one. Steps are plain objects handed over by reference, and a
+ * producer that reuses one — a retry that re-attaches the parent's own step object, a memoised
+ * builder — creates a structure that is finite in memory and infinite to walk. The depth cap alone
+ * would technically terminate, but it would emit 32 rows of the same three steps repeating, which
+ * reads as real data. Tracking ancestor IDENTITY — not id, which a host may legitimately repeat
+ * across branches — cuts it at the first repeat and says so.
+ *
+ * ⚠️ Both cuts are only ever reached through an EXPANDED row: a collapsed subtree is never walked,
+ * so a cycle in a collapsed run costs nothing at all.
+ *
+ * @param runs - Visible runs, already filtered and ordered.
+ * @param options - Expansion set and depth cap.
+ * @returns Rows in render order: each run, then its open subtree, then the next run.
+ */
+declare function flattenRunRows(runs: readonly XenoRun[], options: FlattenOptions): XenoRunRow[];
+
+/**
+ * The Runs panel view.
+ *
+ * Composes `@xenosystem/workbench/primitives`; the host must ensure `@xenosystem/workbench/primitives.css` is
+ * present. `ProportionBar` carries progress — it is exactly the right mark, and it means the panel
+ * ships no chart code of its own.
+ *
+ * @module
+ */
+
+/** Props for {@link RunsPanelView}. */
+interface RunsPanelViewProps {
+    controller: RunsController;
+    showStats?: boolean;
+    showProgress?: boolean;
+    emptyHint?: string;
+    /** Injectable clock, so a duration column is testable. */
+    now?: () => number;
+}
+/** The Runs panel view. */
+declare function RunsPanelView({ controller, showStats, showProgress, emptyHint, now, }: RunsPanelViewProps): ReactNode;
+
+/**
+ * The Terminal contract.
+ *
+ * The panel owns the **emulator surface**. The host owns the **PTY**. Nothing here spawns,
+ * signals, or kills a process, and there is no type in this file through which a process handle
+ * could travel.
+ *
+ * @module
+ */
+/** A terminal instance's identity. Multi-instance is a first-class requirement, not a later mode. */
+type XenoTerminalId = string;
+/** Where a terminal is in its lifecycle, as the HOST reports it. */
+type XenoTerminalStatus = 
+/** No session requested yet. */
+'idle'
+/** The panel has asked; the host has not confirmed. */
+ | 'starting'
+/** Live. */
+ | 'running'
+/** The process ended. */
+ | 'exited'
+/** The host could not start or keep it. */
+ | 'failed';
+/** A terminal's host-reported state. */
+interface XenoTerminalSession {
+    id: XenoTerminalId;
+    /** Tab label. */
+    title?: string;
+    status: XenoTerminalStatus;
+    /** Working directory, for the title bar. */
+    cwd?: string;
+    /** Exit code, when `status === 'exited'`. */
+    exitCode?: number | null;
+    /** Signal that ended it. */
+    signal?: string;
+    /** Host-authored sentence, rendered verbatim. */
+    message?: string;
+    /**
+     * Whether the host has a real PTY behind this session.
+     *
+     * `false` means a pipe fallback: no TTY, so resize is a no-op and line editing happens in the
+     * shell rather than the terminal. The surveyed `xeno-shell` degrades this way when `node-pty`
+     * fails to load, and it tells the user; `xeno-agent-interface` fails outright instead. Carrying
+     * the flag is what lets a panel say which one is happening.
+     */
+    pty?: boolean;
+}
+/** A write into a terminal, addressed by instance. */
+interface XenoTerminalData {
+    id: XenoTerminalId;
+    /** Raw bytes as a string, escape sequences intact. Never pre-parsed, never sanitized. */
+    data: string;
+}
+/** Everything the panel asks the host to do. */
+type XenoTerminalIntent = 
+/**
+ * Start a session.
+ *
+ * `cols`/`rows` are **always a real measurement** — see {@link measuredSize}. The panel does not
+ * ask until it can say how big the terminal is.
+ */
+{
+    type: 'start';
+    id: XenoTerminalId;
+    cols: number;
+    rows: number;
+    cwd?: string;
+}
+/** User input, straight through — control characters included. */
+ | {
+    type: 'input';
+    id: XenoTerminalId;
+    data: string;
+}
+/** The emulator resized. */
+ | {
+    type: 'resize';
+    id: XenoTerminalId;
+    cols: number;
+    rows: number;
+}
+/** Ask the host to end the session. */
+ | {
+    type: 'stop';
+    id: XenoTerminalId;
+}
+/**
+ * Ask the host to replay its buffer.
+ *
+ * The reattach path: a panel remounted into a live session has an empty screen and the scrollback
+ * lives wherever the host kept it.
+ */
+ | {
+    type: 'snapshot';
+    id: XenoTerminalId;
+};
+/** Persisted panel state. */
+interface TerminalPanelState {
+    /** Which instance was in front. */
+    activeId?: XenoTerminalId | null;
+    /** Font size override. */
+    fontSize?: number;
+}
+/** One terminal, as the view sees it. */
+interface TerminalInstanceView {
+    session: XenoTerminalSession;
+    active: boolean;
+    /** Last measured grid, or `null` before the first fit. */
+    cols: number | null;
+    rows: number | null;
+}
+/** What the view renders. */
+interface TerminalViewState {
+    instances: TerminalInstanceView[];
+    activeId: XenoTerminalId | null;
+    fontSize: number;
+    /** Search query, when the find bar is open. */
+    search: string | null;
+}
+/** The xterm theme, in xterm's own shape. */
+interface XenoTerminalTheme {
+    background?: string;
+    foreground?: string;
+    cursor?: string;
+    cursorAccent?: string;
+    selectionBackground?: string;
+    black?: string;
+    red?: string;
+    green?: string;
+    yellow?: string;
+    blue?: string;
+    magenta?: string;
+    cyan?: string;
+    white?: string;
+    brightBlack?: string;
+    brightRed?: string;
+    brightGreen?: string;
+    brightYellow?: string;
+    brightBlue?: string;
+    brightMagenta?: string;
+    brightCyan?: string;
+    brightWhite?: string;
+}
+/**
+ * The terminal palette's KEYS. The VALUES live one rung down — `@xenosystem/elements/tokens` `terminal`,
+ * emitted by elements-react's theme as `--xeno-terminal-<kebab>` — because a block may carry no colour
+ * literal (the no-chrome gate). Until 2026-09-18 this file held all twenty-one as hex; it now reads them
+ * from the element the terminal mounts in (`readTerminalTheme`). A key whose var is absent is simply not
+ * set, and xterm falls back to its own default for it — visible, never a wrong colour.
+ *
+ * **A complete sixteen-colour palette, not a partial one.** The surveyed `xeno-shell` set five keys and
+ * let the other eleven fall back, so a `ls --color` in that terminal rendered in xterm's blues and greens
+ * rather than the product's. The token set is complete; this list is what makes the read complete too.
+ */
+declare const XENO_TERMINAL_THEME_KEYS: readonly ["background", "foreground", "cursor", "cursorAccent", "selectionBackground", "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "brightBlack", "brightRed", "brightGreen", "brightYellow", "brightBlue", "brightMagenta", "brightCyan", "brightWhite"];
+/** `background` → `--xeno-terminal-background`, `brightBlack` → `--xeno-terminal-bright-black`. */
+declare function terminalThemeVar(key: keyof XenoTerminalTheme): string;
+/**
+ * Read the palette from the custom properties in scope at `element` (the `.xeno` theme). Keys whose
+ * var is not set are omitted. Pure over `getComputedStyle`, so it is testable with a stub.
+ */
+declare function readTerminalTheme(element: {
+    ownerDocument?: {
+        defaultView?: {
+            getComputedStyle(el: unknown): {
+                getPropertyValue(name: string): string;
+            };
+        } | null;
+    } | null;
+} | null | undefined): XenoTerminalTheme;
+/** The emulator seam — everything the panel needs from xterm, and nothing more. */
+interface XenoTerminalEmulator {
+    /** Attach to a DOM element. */
+    open(element: HTMLElement): void;
+    /** Write host output. */
+    write(data: string): void;
+    /** Clear the screen and scrollback. */
+    clear(): void;
+    /** Re-fit to the element. Returns the new grid, or `null` if it could not measure. */
+    fit(): {
+        cols: number;
+        rows: number;
+    } | null;
+    /** Current grid. */
+    size(): {
+        cols: number;
+        rows: number;
+    };
+    /** User keystrokes. Returns an unsubscribe. */
+    onData(handler: (data: string) => void): () => void;
+    /** Grid changes. Returns an unsubscribe. */
+    onResize(handler: (size: {
+        cols: number;
+        rows: number;
+    }) => void): () => void;
+    /** Find in the scrollback. Optional — not every emulator has a search addon. */
+    search?(query: string, direction: 'next' | 'previous'): boolean;
+    /** Change font size. */
+    setFontSize?(size: number): void;
+    /** Release everything. */
+    dispose(): void;
+}
+/**
+ * Is a measured grid usable?
+ *
+ * **The third answer to a problem both incumbents got wrong.** `xeno-agent-interface` spawns every
+ * PTY at a fixed 80×24 and lets the first resize correct it, so a full-screen TUI or a progress bar
+ * renders once at the wrong size. `xeno-shell` calls `fit()` synchronously right after `open()` —
+ * before layout has necessarily settled — and its own comment admits the follow-up resize is a race
+ * patch. Neither waits for a real measurement.
+ *
+ * This panel does: no `start` intent is emitted until `fit()` reports a plausible grid, exactly as
+ * the viewport panel refuses to report a zero-sized surface. The problem is the same one and so is
+ * the fix.
+ *
+ * @param size - A measured grid, or `null`.
+ * @returns Whether it can be sent to a PTY.
+ */
+declare function measuredSize(size: {
+    cols: number;
+    rows: number;
+} | null): boolean;
+/** Is this session live enough to accept input? */
+declare function isLive(status: XenoTerminalStatus): boolean;
+/** A short label for a session's state, or `null` while it is simply running. */
+declare function statusLabel(session: XenoTerminalSession): string | null;
+
+/**
+ * The Terminal controller — instances, the emulator seam, and intents.
+ *
+ * Zero dependency on xterm. The emulator arrives through {@link XenoTerminalEmulator}, which keeps
+ * this file testable without a DOM and keeps 345 KB of third-party runtime out of the package's
+ * own graph. See the doc pack for the bundling rationale.
+ *
+ * @module
+ */
+
+/** The host seam. */
+interface TerminalHostBridge {
+    emit(portId: string, value: unknown): void;
+    makeId?: () => string;
+}
+/** Construction options. */
+interface TerminalControllerOptions {
+    host: TerminalHostBridge;
+    /** Scrollback lines held by the emulator. Default 5000. */
+    scrollback?: number;
+    /** Font size. Default 12. */
+    fontSize?: number;
+    /**
+     * Ask the host to stop a session when its instance is closed in the UI. Default `true`.
+     *
+     * **This is a policy, and it must be chosen rather than inherited.** The two surveyed
+     * implementations chose opposite defaults: `xeno-agent-interface` deliberately decouples PTY
+     * lifetime from component lifetime ("each tab owns its process until the tab is explicitly
+     * closed") while `xeno-shell` couples them through a React `key`, so switching connection kills
+     * the session. Closing a tab is an explicit user act, so stopping is the honest default —
+     * unmounting is not, and never stops anything here.
+     */
+    stopOnClose?: boolean;
+}
+/** The Terminal panel controller. */
+declare class TerminalController {
+    private readonly host;
+    private readonly makeId;
+    private readonly stopOnClose;
+    readonly scrollback: number;
+    private instances;
+    private order;
+    private activeId;
+    private fontSize;
+    private search;
+    private readonly listeners;
+    private snapshot;
+    constructor(options: TerminalControllerOptions);
+    subscribe: (listener: () => void) => (() => void);
+    getState: () => TerminalViewState;
+    private notify;
+    private emit;
+    /**
+     * Open a terminal instance.
+     *
+     * **No `start` intent is emitted here.** The panel cannot say how big the terminal is until an
+     * emulator has attached and measured, and a PTY started at a guessed size renders its first
+     * screen wrong. `start` goes out from {@link attach}, once.
+     *
+     * @param id - An explicit id, or one is minted.
+     * @param session - Opening session fields.
+     * @returns The instance id.
+     */
+    open(id?: XenoTerminalId, session?: Partial<XenoTerminalSession>): XenoTerminalId;
+    /**
+     * Close an instance.
+     *
+     * @param id - The instance.
+     * @returns Whether it existed.
+     */
+    close(id: XenoTerminalId): boolean;
+    /** Bring an instance to the front. */
+    setActive(id: XenoTerminalId | null): void;
+    /** Instance ids, in open order. */
+    ids(): XenoTerminalId[];
+    /**
+     * Attach an emulator to an instance and wire it up.
+     *
+     * Emits `start` **only once a real grid has been measured** — the fix for a mistake both
+     * incumbents make in opposite directions (a fixed 80×24 guess, or a synchronous fit before
+     * layout settles).
+     *
+     * @param id - The instance.
+     * @param emulator - The emulator.
+     * @param element - Where it mounts.
+     * @returns A detach function.
+     */
+    attach(id: XenoTerminalId, emulator: XenoTerminalEmulator, element: HTMLElement): () => void;
+    /**
+     * Re-fit an instance, and start it if it has never been measured before.
+     *
+     * @param id - The instance.
+     * @returns The measured grid, or `null`.
+     */
+    fit(id: XenoTerminalId): {
+        cols: number;
+        rows: number;
+    } | null;
+    /**
+     * Detach an instance's emulator.
+     *
+     * **Never stops the session.** A panel can unmount because a tab was hidden, a layout changed,
+     * or React StrictMode double-invoked an effect; killing a shell for any of those would lose work
+     * the user did not ask to lose.
+     *
+     * @param id - The instance.
+     */
+    detach(id: XenoTerminalId): void;
+    /** Ask the host to replay its buffer — the reattach path. */
+    requestSnapshot(id: XenoTerminalId): boolean;
+    /**
+     * Write host output into a terminal.
+     *
+     * @param payload - `{id, data}`.
+     * @returns Whether the instance exists.
+     */
+    write(payload: XenoTerminalData): boolean;
+    /**
+     * Update a session's host-reported state.
+     *
+     * The panel never sets `running` or `exited` itself — it asked, and it waits to be told.
+     *
+     * @param session - Fields to merge, keyed by `id`.
+     * @returns Whether the instance exists.
+     */
+    setSession(session: Partial<XenoTerminalSession> & {
+        id: XenoTerminalId;
+    }): boolean;
+    /** Replace a terminal's contents — used when a snapshot arrives. */
+    replace(id: XenoTerminalId, data: string): boolean;
+    /** Set the font size on every attached emulator. */
+    setFontSize(size: number): void;
+    /** Open, update, or close the find bar. */
+    setSearch(query: string | null): void;
+    /** Run a search in the active terminal. */
+    find(direction?: 'next' | 'previous'): boolean;
+    /** The active instance's session, if any. */
+    active(): XenoTerminalSession | null;
+    /**
+     * Serialize.
+     *
+     * Which tab was in front, and the font size. **Never the scrollback** — terminal output routinely
+     * contains tokens, connection strings and keys that a user pasted or a tool printed, and `.xapp`
+     * is a plain JSON file. `XENO AUTH - SPEC.md` L9 keeps secrets out of exactly this kind of store.
+     */
+    serialize(): TerminalPanelState;
+    /** Restore view preferences. Sessions are not restored — the host re-declares them. */
+    deserialize(state: unknown): void;
+    /**
+     * Tear down.
+     *
+     * Detaches every emulator and **stops nothing**. Sessions outlive the panel by design; the host
+     * decides when a process dies.
+     */
+    dispose(): void;
+}
+
+/**
+ * The `PanelModule` — view wired inside the package (one React copy).
+ *
+ * @module
+ */
+
+/** Everything a renderer needs: the controller plus the resolved config. */
+interface TerminalRenderContext {
+    controller: TerminalController;
+    config: {
+        multiInstance: boolean;
+    };
+}
+/** Options for {@link createTerminalPanel}. */
+interface CreateTerminalPanelOptions {
+    /**
+     * Build an emulator.
+     *
+     * Defaults to the dynamically-imported xterm adapter, so a consumer that never mounts a terminal
+     * never downloads one. A host with its own xterm instance passes a seam over that instead.
+     */
+    createEmulator?: () => Promise<XenoTerminalEmulator>;
+    /** Override the view. */
+    render?: (root: HTMLElement, context: TerminalRenderContext) => () => void;
+}
+/**
+ * Build the Terminal panel module.
+ *
+ * @param options - Emulator factory and optional renderer override.
+ * @returns The module.
+ */
+declare function createTerminalPanel(options?: CreateTerminalPanelOptions): PanelModule;
+/** The default Terminal panel module — view wired, xterm lazily imported. Register THIS. */
+declare const terminalPanel: PanelModule;
+
+/**
+ * The `xeno.core.terminal` manifest.
+ *
+ * Capabilities: `storage.local` only — and this is the panel where that deserves an explanation.
+ *
+ * A terminal's natural host binding is process I/O, which is the most powerful thing any panel in
+ * the catalog sits next to. There is deliberately **no `process.*` capability**, here or in the
+ * SDK: the panel emits intents and renders a stream, and the host spawns, signals and kills. That
+ * boundary is what lets this panel run unchanged in an `iframe-quickjs` sandbox — where it can only
+ * ever be a host-brokered stream, which is exactly what it already is everywhere else.
+ *
+ * @module
+ */
+
+/** The canonical manifest id. */
+declare const TERMINAL_PANEL_ID = "xeno.core.terminal";
+/** The `xeno.core.terminal` manifest. */
+declare const terminalManifest: PanelManifest;
+
+/**
+ * The Terminal panel view.
+ *
+ * **Where primitives fit and where they do not.** The tab strip, status chips and find bar use
+ * `Toolbar`/`Badge`/`SearchField`/`TextButton`. The terminal body does not use a primitive at all —
+ * it is a bare `<div>` that xterm owns outright, and wrapping it in anything that sets padding,
+ * overflow or transform breaks the emulator's own measurement. That div is deliberately plain.
+ *
+ * @module
+ */
+
+/** Props for {@link TerminalPanelView}. */
+interface TerminalPanelViewProps {
+    controller: TerminalController;
+    /**
+     * Build an emulator. Async so the default xterm adapter can be dynamically imported.
+     *
+     * Omit it and the panel renders its chrome with an explanatory empty state rather than a blank
+     * rectangle — a terminal with no emulator is a configuration mistake, and it should say so.
+     */
+    createEmulator?: () => Promise<XenoTerminalEmulator>;
+    multiInstance?: boolean;
+}
+/** The Terminal panel view. */
+declare function TerminalPanelView({ controller, createEmulator, multiInstance, }: TerminalPanelViewProps): ReactNode;
+
+/**
+ * The Diff contract.
+ *
+ * The host computes the comparison; the panel renders it and emits decisions. No diff engine and
+ * no editor ships in this package — see the doc pack.
+ *
+ * @module
+ */
+/** What happened to a line. */
+type XenoDiffLineKind = 'context' | 'added' | 'removed';
+/**
+ * A run of text within a line, for word-level marks.
+ *
+ * Optional throughout. `xeno-docs` computes word-level segments with its own LCS; Monaco produces
+ * inline marks internally; the inline tool card produces none at all. A panel that *required*
+ * segments would exclude two of the three surveyed producers, and a panel that could not render
+ * them would throw away the one thing the prose diff does better than the code diff.
+ */
+interface XenoDiffSegment {
+    text: string;
+    kind: 'equal' | 'insert' | 'delete';
+}
+/** One rendered line. */
+interface XenoDiffLine {
+    kind: XenoDiffLineKind;
+    /** 1-based line number in the original. Absent on an added line. */
+    oldLineNumber?: number;
+    /** 1-based line number in the modified file. Absent on a removed line. */
+    newLineNumber?: number;
+    text: string;
+    /** Word-level marks within `text`. Rendered when present, ignored when not. */
+    segments?: XenoDiffSegment[];
+}
+/**
+ * How a hunk's decision stands, **as the host reports it**.
+ *
+ * - `undecided` — nothing asked.
+ * - `pending` — the panel emitted a decision; the host has not confirmed.
+ * - `applied` — the host committed it.
+ * - `failed` — the host tried and could not.
+ * - `conflict` — **the file changed underneath the review.** Distinct from `failed` because the
+ *   remedy is different: a failure may be retried as-is, a conflict means the hunk no longer
+ *   describes the file and the decision has to be made again against fresh content.
+ */
+type XenoDiffDecisionState = 'undecided' | 'pending' | 'applied' | 'failed' | 'conflict';
+/** What a reviewer decided about a hunk. */
+type XenoDiffAction = 'accept' | 'reject' | 'comment';
+/** A decision, as the host reports it back. */
+interface XenoDiffDecision {
+    hunkId: string;
+    path: string;
+    action: XenoDiffAction;
+    state: XenoDiffDecisionState;
+    comment?: string;
+    /** Host-authored sentence, rendered verbatim. Where a conflict explains itself. */
+    message?: string;
+    updatedAt?: number;
+}
+/** A contiguous change region. */
+interface XenoDiffHunk {
+    /**
+     * Stable within the current model.
+     *
+     * The surveyed host **re-derives hunk ids from immutable content snapshots on every request
+     * rather than trusting a stale id** — the panel round-trips whatever it was given and never
+     * synthesizes one, so that discipline survives the trip through the UI.
+     */
+    id: string;
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+    lines: XenoDiffLine[];
+    /** Optional header (`@@ -1,7 +1,9 @@`, or a function signature). */
+    header?: string;
+}
+/** Why a file has no rendered hunks. Never conflated with "no changes". */
+type XenoDiffFileOmission = 'binary' | 'tooLarge' | 'unreadable' | 'identical';
+/** One file's comparison. */
+interface XenoDiffFile {
+    path: string;
+    /** Previous path, when renamed. */
+    oldPath?: string;
+    status: 'added' | 'removed' | 'modified' | 'renamed';
+    hunks: XenoDiffHunk[];
+    /** Language hint for a syntax seam. Never used to load anything by itself. */
+    language?: string;
+    /**
+     * Why `hunks` is empty, when it is empty for a reason other than equality.
+     *
+     * 🔴 The find-panel landmine, in a second costume: an empty hunk list rendered as "no changes"
+     * is a wrong answer wearing the costume of an empty one. A binary file, a file past the diff
+     * engine's size ceiling, and a file that is genuinely identical must not look alike — the first
+     * two mean "not compared", and a reviewer who reads them as "unchanged" approves something
+     * nobody looked at.
+     */
+    omitted?: XenoDiffFileOmission;
+    /** Counts, when the host knows them. */
+    additions?: number;
+    deletions?: number;
+}
+/** Whether the comparison has been computed at all. */
+type XenoDiffStatus = 'idle' | 'computing' | 'ready' | 'failed';
+/** The whole comparison. */
+interface XenoDiffModel {
+    files: XenoDiffFile[];
+    status?: XenoDiffStatus;
+    /** Host-authored sentence for `failed`. */
+    message?: string;
+    /** Labels for the two sides. */
+    oldLabel?: string;
+    newLabel?: string;
+    /** Monotonic revision; an older model is ignored. */
+    rev?: number;
+}
+/** How the comparison is laid out. */
+type XenoDiffView = 'unified' | 'split';
+/** A decision intent. The panel decides nothing itself. */
+interface XenoDiffDecisionIntent {
+    path: string;
+    hunkId: string;
+    action: XenoDiffAction;
+    comment?: string;
+}
+/** "Reveal this hunk in the editor." */
+interface XenoDiffNavigate {
+    path: string;
+    hunkId: string;
+    /** Line to reveal, in the modified file where one exists. */
+    line?: number;
+}
+/** The syntax-highlighting seam. */
+interface XenoDiffHighlighter {
+    /**
+     * Turn a line of code into segments.
+     *
+     * Deliberately the same `XenoDiffSegment`-shaped idea as word marks, but with a token class
+     * instead of a change kind, so the renderer composes the two without either knowing about the
+     * other.
+     *
+     * @param text - The line.
+     * @param language - The file's language hint.
+     * @returns Token runs, or `null` to render plain.
+     */
+    highlight(text: string, language?: string): {
+        text: string;
+        token?: string;
+    }[] | null;
+}
+/** Persisted panel state. */
+interface DiffPanelState {
+    view?: XenoDiffView;
+    /** Collapsed file paths. */
+    collapsed?: string[];
+    wrap?: boolean;
+    showWhitespace?: boolean;
+}
+/** A file as the view receives it. */
+interface DiffFileView {
+    file: XenoDiffFile;
+    collapsed: boolean;
+    /** Decisions for this file's hunks, keyed by hunk id. */
+    decisions: Record<string, XenoDiffDecision>;
+    additions: number;
+    deletions: number;
+}
+/** What the view renders. */
+interface DiffViewState {
+    files: DiffFileView[];
+    status: XenoDiffStatus;
+    message: string | null;
+    view: XenoDiffView;
+    wrap: boolean;
+    showWhitespace: boolean;
+    oldLabel: string;
+    newLabel: string;
+    /** Totals across every file. */
+    totals: {
+        files: number;
+        additions: number;
+        deletions: number;
+        hunks: number;
+    };
+    /** Decision progress, when any decision exists. */
+    review: {
+        decided: number;
+        total: number;
+        conflicts: number;
+        pending: number;
+    } | null;
+    /** Genuinely nothing changed — as opposed to nothing computed. */
+    identical: boolean;
+    /** The currently focused hunk, for keyboard navigation. */
+    cursor: {
+        path: string;
+        hunkId: string;
+    } | null;
+}
+/**
+ * Is a decision settled enough to render as done?
+ *
+ * Only `applied`. A `pending` decision has been asked for and not confirmed; rendering it as
+ * accepted is the same class of lie as a consent panel flipping a switch before the host answers.
+ *
+ * @param state - The decision state.
+ * @returns Whether the host has confirmed it.
+ */
+declare function isSettled(state: XenoDiffDecisionState): boolean;
+/**
+ * Does this decision need the reviewer's attention again?
+ *
+ * `conflict` does and `failed` does; they are separated because the remedies differ.
+ *
+ * @param state - The decision state.
+ * @returns Whether the reviewer must act.
+ */
+declare function needsAttention(state: XenoDiffDecisionState): boolean;
+/**
+ * Count added and removed lines in a file.
+ *
+ * Derived when the host does not supply counts, because a header that says "+0 −0" over a file
+ * full of changes is worse than no header.
+ *
+ * @param file - The file.
+ * @returns Additions and deletions.
+ */
+declare function countChanges(file: XenoDiffFile): {
+    additions: number;
+    deletions: number;
+};
+/**
+ * Pair a hunk's lines into left/right rows for a split view.
+ *
+ * Removed and added lines align pairwise; the shorter side is padded with `null` so both columns
+ * stay in step. A naive split that renders each column independently drifts as soon as a hunk has
+ * unequal counts, and the two halves then disagree about which line is which.
+ *
+ * @param hunk - The hunk.
+ * @returns Aligned rows.
+ */
+declare function splitRows(hunk: XenoDiffHunk): {
+    left: XenoDiffLine | null;
+    right: XenoDiffLine | null;
+}[];
+/** Every hunk in the model, flattened in file order — the traversal order for next/previous. */
+declare function flattenHunks(model: XenoDiffModel): {
+    path: string;
+    hunkId: string;
+}[];
+/** A short label for why a file has no hunks. */
+declare function omissionLabel(omission: XenoDiffFileOmission): string;
+
+/**
+ * The Diff controller — the model, the decisions, and the hunk cursor.
+ *
+ * @module
+ */
+
+/** The host seam. */
+interface DiffHostBridge {
+    emit(portId: string, value: unknown): void;
+}
+/** Construction options. */
+interface DiffControllerOptions {
+    host: DiffHostBridge;
+    /** Opening layout. Default `unified`. */
+    view?: XenoDiffView;
+    /** Offer accept/reject. Default `false` — most diffs are read-only. */
+    review?: boolean;
+}
+/** The Diff panel controller. */
+declare class DiffController {
+    private readonly host;
+    private readonly reviewEnabled;
+    private model;
+    private rev;
+    private decisions;
+    private view;
+    private collapsed;
+    private wrap;
+    private showWhitespace;
+    private cursor;
+    private readonly listeners;
+    private snapshot;
+    constructor(options: DiffControllerOptions);
+    subscribe: (listener: () => void) => (() => void);
+    getState: () => DiffViewState;
+    private notify;
+    private key;
+    /**
+     * Install a comparison.
+     *
+     * @param model - The host-computed diff.
+     * @returns Whether it was applied (an older `rev` is ignored).
+     */
+    setModel(model: XenoDiffModel): boolean;
+    /** Set the comparison's status without replacing the model. */
+    setStatus(status: XenoDiffStatus, message?: string): void;
+    /**
+     * Record a host-reported decision outcome.
+     *
+     * The **only** way a decision reaches `applied`. The panel writes `pending` when it asks, and
+     * nothing else.
+     *
+     * @param decision - The outcome.
+     * @returns Whether it was recorded.
+     */
+    setDecision(decision: XenoDiffDecision): boolean;
+    /** Record several at once. */
+    setDecisions(decisions: readonly XenoDiffDecision[]): void;
+    /**
+     * Decide a hunk.
+     *
+     * Emits an intent and marks the decision `pending`. **It does not apply anything and does not
+     * render as accepted.** The surveyed host runs a two-phase confirm and a checkpointed filesystem
+     * transaction whose outcome may be `applied`, `failed` or `conflict`; a panel that showed a tick
+     * on click would be asserting the outcome of work that has not started.
+     *
+     * @param path - The file.
+     * @param hunkId - The hunk.
+     * @param action - accept, reject or comment.
+     * @param comment - For `comment`, or a note on either.
+     * @returns Whether an intent was emitted.
+     */
+    decide(path: string, hunkId: string, action: XenoDiffAction, comment?: string): boolean;
+    /** Clear a decision locally so it can be re-made — the remedy for a conflict. */
+    clearDecision(path: string, hunkId: string): boolean;
+    /** Every recorded decision. */
+    allDecisions(): XenoDiffDecision[];
+    /** Move to the next hunk, across file boundaries. */
+    nextHunk(): {
+        path: string;
+        hunkId: string;
+    } | null;
+    /** Move to the previous hunk. */
+    previousHunk(): {
+        path: string;
+        hunkId: string;
+    } | null;
+    private moveCursor;
+    /** Point at a specific hunk. */
+    focusHunk(path: string, hunkId: string): boolean;
+    private emitNavigate;
+    /** Unified or split. */
+    setView(view: XenoDiffView): void;
+    /** Collapse or expand a file. */
+    setCollapsed(path: string, collapsed: boolean): void;
+    /** Soft-wrap long lines. */
+    setWrap(wrap: boolean): void;
+    /** Render whitespace characters. */
+    setShowWhitespace(show: boolean): void;
+    /** Ask the host for a context menu. */
+    requestContextMenu(path: string, hunkId: string, x: number, y: number): void;
+    /**
+     * Serialize.
+     *
+     * View preferences only. **Never the model and never the decisions** — the model is a comparison
+     * of content that has almost certainly moved on, and a restored decision would claim a review
+     * outcome the host never confirmed.
+     */
+    serialize(): DiffPanelState;
+    /** Restore view preferences. */
+    deserialize(state: unknown): void;
+    /** Tear down. */
+    dispose(): void;
+}
+
+/**
+ * The `PanelModule` — view wired inside the package (one React copy).
+ *
+ * @module
+ */
+
+/** Everything a renderer needs: the controller plus the resolved config. */
+interface DiffRenderContext {
+    controller: DiffController;
+    config: {
+        review: boolean;
+    };
+}
+/** Options for {@link createDiffPanel}. */
+interface CreateDiffPanelOptions {
+    /**
+     * Syntax seam.
+     *
+     * Deliberately an injected interface rather than a bundled editor. Monaco is ~4 MB and the
+     * surveyed apps already ship it; a shared panel that bundled its own would be a second copy in
+     * every consumer. No highlighter simply means plain text — never a missing panel.
+     */
+    highlighter?: XenoDiffHighlighter;
+    /** Override the view. */
+    render?: (root: HTMLElement, context: DiffRenderContext) => () => void;
+}
+/**
+ * Build the Diff panel module.
+ *
+ * @param options - Highlighter and optional renderer override.
+ * @returns The module.
+ */
+declare function createDiffPanel(options?: CreateDiffPanelOptions): PanelModule;
+/** The default Diff panel module — view already wired, no highlighter. Register THIS. */
+declare const diffPanel: PanelModule;
+
+/**
+ * The `xeno.core.diff` manifest.
+ *
+ * Capabilities: `storage.local` only. The panel reads no file and writes no file — the host
+ * computes the comparison and the host applies every decision, inside its own transaction.
+ *
+ * @module
+ */
+
+/** The canonical manifest id. */
+declare const DIFF_PANEL_ID = "xeno.core.diff";
+/** The `xeno.core.diff` manifest. */
+declare const diffManifest: PanelManifest;
+
+/**
+ * The Diff panel view.
+ *
+ * **Where primitives fit and where they do not.** Toolbar, badges, section headers and the empty
+ * states are primitives. The diff body is not: a two-column, line-numbered, monospaced grid whose
+ * rows must align across both columns has no primitive, and the one thing it must never be is a
+ * `RowList` — those rows are variable-height and this grid's correctness depends on them not being.
+ *
+ * @module
+ */
+
+/** Props for {@link DiffPanelView}. */
+interface DiffPanelViewProps {
+    controller: DiffController;
+    /** Optional syntax seam. No highlighter means plain text, never a missing panel. */
+    highlighter?: XenoDiffHighlighter;
+    review?: boolean;
+}
+/** The Diff panel view. */
+declare function DiffPanelView({ controller, highlighter, review }: DiffPanelViewProps): ReactNode;
+
+export { ALL_STATUSES, CONSOLE_PANEL_ID, ConsoleController, type ConsoleControllerOptions, type ConsoleHostBridge, type ConsolePanelState, ConsolePanelView, type ConsolePanelViewProps, type ConsoleRenderContext, type ConsoleViewState, type CreateConsolePanelOptions, type CreateDiffPanelOptions, type CreateRunsPanelOptions, type CreateTerminalPanelOptions, DEFAULT_MAX_STEP_DEPTH, DIFF_PANEL_ID, DiffController, type DiffControllerOptions, type DiffFileView, type DiffHostBridge, type DiffPanelState, DiffPanelView, type DiffPanelViewProps, type DiffRenderContext, type DiffViewState, type FlattenOptions, LEVEL_ORDER, MESSAGE_ELISION, REDACTION_CARRY, RUNS_PANEL_ID, RUN_PATH_SEPARATOR, RUN_STATUSES, RunsController, type RunsControllerOptions, type RunsHostBridge, type RunsPanelState, RunsPanelView, type RunsPanelViewProps, type RunsRenderContext, type RunsViewState, TERMINAL_PANEL_ID, TERMINAL_STATUSES, TerminalController, type TerminalControllerOptions, type TerminalHostBridge, type TerminalInstanceView, type TerminalPanelState, TerminalPanelView, type TerminalPanelViewProps, type TerminalRenderContext, type TerminalViewState, XENO_TERMINAL_THEME_KEYS, type XenoDiffAction, type XenoDiffDecision, type XenoDiffDecisionIntent, type XenoDiffDecisionState, type XenoDiffFile, type XenoDiffFileOmission, type XenoDiffHighlighter, type XenoDiffHunk, type XenoDiffLine, type XenoDiffLineKind, type XenoDiffModel, type XenoDiffNavigate, type XenoDiffSegment, type XenoDiffStatus, type XenoDiffView, type XenoLogActivate, type XenoLogDelta, type XenoLogFilter, type XenoLogLevel, type XenoLogPatch, type XenoLogRecord, type XenoLogSource, type XenoRun, type XenoRunAction, type XenoRunActivate, type XenoRunDelta, type XenoRunError, type XenoRunFilter, type XenoRunLifecycle, type XenoRunPath, type XenoRunRow, type XenoRunRunRow, type XenoRunStats, type XenoRunStatus, type XenoRunStep, type XenoRunStepAppend, type XenoRunStepPatch, type XenoRunStepRow, type XenoRunTruncation, type XenoTerminalData, type XenoTerminalEmulator, type XenoTerminalId, type XenoTerminalIntent, type XenoTerminalSession, type XenoTerminalStatus, type XenoTerminalTheme, appendStepsAtPath, canCancel, canRetry, collapseAdjacent, computeStats, consoleManifest, consolePanel, countChanges, createConsolePanel, createDiffPanel, createRunsPanel, createTerminalPanel, decodeRunPath, diffManifest, diffPanel, durationOf, encodeRunPath, flattenHunks, flattenRunRows, formatDuration, formatRecord, isActive, isLive, isSettled, isTerminal, isWaiting, lifecycleOf, matchesSearch as matchesRunSearch, matchesSearch$1 as matchesSearch, measuredSize, meetsLevel, needsAttention, omissionLabel, patchStepAtPath, queueDurationOf, readTerminalTheme, resolveStepPath, runsManifest, runsPanel, safeJson, spliceRedactedAppend, splitRows, statusLabel, terminalManifest, terminalPanel, terminalThemeVar, truncateLogMessage };