@martintrojer/murmur 0.1.4 → 0.2.1

package/dist/index.d.ts

@@ -1,192 +1,426 @@
-type AgentState = "working" | "blocked" | "done" | "crashed" | "cleared";
+/**
+ * tmux's three id kinds, kept apart by the type system.
+ *
+ * tmux itself is unambiguous about this and prints a sigil on every id --
+ * `session=$25  window=@75  pane=%89` -- but they are all strings, so murmur
+ * could and did pass one where another was meant. Twice, in shipped code: a
+ * sweep keyed on window liveness deleted ten live agents, and a window cached
+ * at extension startup badged the window a moved pane had left.
+ *
+ * An agent is addressed by its PANE, which keeps its id across `move-pane`,
+ * `break-pane`, and a window closed and reopened. A session and a window are
+ * only where that pane currently lives, and both may differ between two reports
+ * from one agent. So the rule the brands enforce is:
+ *
+ *   only a pane may decide whether an agent exists.
+ *
+ * Branding is a compile-time fiction: at runtime these are the same strings
+ * tmux printed, which is what keeps the snapshot document and every stored row
+ * byte-identical.
+ */
+declare const brand: unique symbol;
+/** A tmux session id, `$N`. Mutable location. */
+type SessionId = string & {
+    readonly [brand]: "session";
+};
+/** A tmux window id, `@N`. Mutable location -- never an agent's identity. */
+type WindowId = string & {
+    readonly [brand]: "window";
+};
+/** A tmux pane id, `%N`. The agent's identity, stable for its whole life. */
+type PaneId = string & {
+    readonly [brand]: "pane";
+};
+declare function asSessionId(raw: string): SessionId;
+declare function asWindowId(raw: string): WindowId;
+declare function asPaneId(raw: string): PaneId;
+
+/**
+ * The three independent facts, as types.
+ *
+ * `activity` is what the pane's own process says it is doing. `attention` is
+ * whether a human is wanted. `freshness` (src/view.ts) is how recently we
+ * reached the node that reported. They are three independent fields, never one
+ * enum, and absence carries meaning: no attention row means "nothing to see",
+ * no agent row means "no agent here".
+ */
+type Activity = "running" | "stopped";
+type AttentionKind = "done" | "blocked" | "crashed";
+/**
+ * Who is waiting on this agent -- a human, or a supervisor that consumes the
+ * result. Not "which harness"; that is `cli`.
+ */
 type Driver = "human" | "orchestrated";
 declare const DEFAULT_DRIVER: Driver;
-type Event = {
-    host_id: string;
-    seq: number;
-    ts: number;
-    agent_id: string;
-    session: string;
-    window: string;
-    pane: string;
+/**
+ * Where a pane currently lives. Location, never identity.
+ *
+ * `pane` is the address and is stable for the life of the pane; `session` and
+ * `window` are only where that pane currently is, and both change under
+ * move-pane and break-pane. Only a pane may decide whether an agent exists,
+ * which is what the brands in ./ids.js enforce.
+ */
+type Location = {
+    session: SessionId;
+    window: WindowId;
+    pane: PaneId;
     session_name: string | null;
     window_name: string | null;
+};
+/** Owner-reported metadata about the agent in a pane. */
+type AgentMeta = {
     agent_name: string | null;
     pi_session: string | null;
     workstream: string | null;
     role: string | null;
-    cli: string | null;
-    driver: Driver | null;
-    kind: string;
-    state: AgentState | string;
-    message: string;
-    pid: number | null;
-    synthetic: boolean;
-    reason: string;
-    extra: Record<string, unknown>;
+    cli: string;
+    driver: Driver;
 };
-type Peer = {
+type PeerRecord = {
     name: string;
     target: string;
     host_id: string | null;
     display_name: string | null;
-    watermark: number;
+    /** The whole validated document, or null when we have never parsed one. */
+    snapshot: Snapshot | null;
+    /** The PEER's clock: when that node built the document. */
+    snapshot_at: number | null;
+    /** OUR clock: when we last reached it. Freshness is computed from this. */
     fetched_at: number | null;
-    /** When a jump last found this peer's tmux server down. Null once it answers. */
-    tmux_down_at: number | null;
+    last_attempt_at: number | null;
+    last_error: string | null;
+    murmur_version: string | null;
+    /** The peer's `murmur_snapshot` value, i.e. the document version it speaks. */
+    snapshot_version: number | null;
 };
-
-type Location = {
-    session: string;
-    window: string;
-    pane: string;
+/**
+ * One node's whole current state. Complete, never a delta: a peer that returns
+ * one has said everything it knows, so absence from it is absence.
+ */
+type Snapshot = {
+    murmur_snapshot: 1;
+    host_id: string;
+    display_name: string;
+    murmur_version: string;
+    generated_at: number;
+    panes: SnapshotPane[];
+};
+type SnapshotPane = {
+    pane: PaneId;
+    session: SessionId;
+    window: WindowId;
     session_name: string | null;
     window_name: string | null;
+    /** Null for an attention-only pane: valid, listable, jumpable. */
+    agent: SnapshotAgent | null;
+    attention: SnapshotAttention[];
 };
-interface Mux {
-    currentWindow(): Location | null;
-    liveWindows(): Set<string> | null;
-    setState(window: string, state: AgentState | null): void;
-    attach(session: string, window: string): boolean;
-    windowNames(): Map<string, string>;
-    windowForPane(pane: string): string | null;
-    panesInWindow(window: string): string[];
-    windowNamed(name: string): string | null;
-    selectWindow(window: string): boolean;
-    newWindow(name: string, command: string): boolean;
-    capture(pane: string, lines?: number): string | null;
-}
-declare const tmux: Mux;
-declare function pidAlive(pid: number): boolean;
-
-interface Channel {
-    exec(target: string, argv: string[]): Promise<string>;
-}
-declare const ssh: Channel;
-declare function hasWarmSocket(target: string): boolean;
-
+type SnapshotAgent = AgentMeta & {
+    agent_id: string;
+    activity: Activity;
+    claimed_at: number;
+    updated_at: number;
+};
+type SnapshotAttention = {
+    kind: AttentionKind;
+    message: string;
+    source: string;
+    requested_at: number;
+};
+/**
+ * Whether a pid is still running. A parameter everywhere it is consulted, so a
+ * test needs no process table.
+ */
 type LiveCheck = (pid: number) => boolean;
-type AgentView = {
+type AgentClaim = {
+    location: Location;
+    owner_pid: number;
+    meta: AgentMeta;
+    now?: number;
+    isAlive?: LiveCheck;
+};
+type ClaimResult = {
+    outcome: "claimed";
     agent_id: string;
-    host_id: string;
-    state: AgentState | null;
-    event: Event | null;
-    workstream: string | null;
-    role: string | null;
-    cli: string | null;
-    driver: Driver;
-    session: string;
-    window: string;
-    pane: string;
-    session_name: string | null;
-    window_name: string | null;
-    agent_name: string | null;
-    pi_session: string | null;
-    fetched_at: number | null;
+} | {
+    outcome: "retained";
+    agent_id: string;
+} | {
+    outcome: "replaced";
+    agent_id: string;
+    previous_agent_id: string;
+} | {
+    outcome: "refused";
+    held_by_pid: number;
 };
-declare function foldAgent(events: Event[], isAlive: LiveCheck): {
-    state: AgentState | null;
-    event: Event | null;
+type ActivityUpdate = {
+    agent_id: string;
+    owner_pid: number;
+    activity: Activity;
+    location: Location;
+    now?: number;
+};
+type AgentRelease = {
+    agent_id: string;
+    owner_pid: number;
 };
-declare function foldAll(events: Event[], isAlive: LiveCheck): AgentView[];
-declare function attentionSort(views: AgentView[]): AgentView[];
-declare function isStale(fetchedAt: number | null, now: number, thresholdMs?: number): boolean;
-
 /**
- * Local storage shape. Bump on any change to the events or peers tables.
+ * Everything an attention writer may say. There is no agent_id, no owner_pid,
+ * no activity and no owner metadata field, and adding one is a contract change.
+ */
+type AttentionRequest = {
+    kind: AttentionKind;
+    location: Location;
+    message: string;
+    source: string;
+    now?: number;
+};
+/**
+ * The only local facts reconciliation is allowed to consult.
  *
- * Distinct from `SCHEMA_VERSION` in export.ts, which versions the *wire*: a
- * node can change how it stores events without changing what it sends, and a
- * wire change should not throw away local history.
+ * `panes` is null when tmux could not answer, which is not evidence of death.
+ * `isAlive` and `now` are parameters so a test needs no process table and no
+ * clock control.
  */
-declare const STORE_VERSION = 2;
-type NewEvent = Omit<Event, "host_id" | "seq" | "ts" | "session_name" | "window_name" | "agent_name" | "pi_session"> & {
-    ts?: number;
-    session_name?: string | null;
-    window_name?: string | null;
-    agent_name?: string | null;
-    pi_session?: string | null;
+type LocalWorld = {
+    panes: Set<PaneId> | null;
+    isAlive?: LiveCheck;
+    now?: number;
+};
+type ReconcileSummary = {
+    crashed: PaneId[];
+    removed: PaneId[];
+    attention_removed: PaneId[];
+};
+type PeerFetch = {
+    ok: true;
+    snapshot: Snapshot;
+    at: number;
+} | {
+    ok: false;
+    error: string;
+    at: number;
 };
+
+type NodeIdentity = {
+    host_id: string;
+    display_name: string;
+};
+/**
+ * This node's identity, or null when it has none.
+ *
+ * A READ, and only a read: nothing mints here. Every command that needs a
+ * host_id fails with "murmur is not initialised on this node; run: murmur init"
+ * rather than bringing a node into existence as a side effect of a status-bar
+ * tick.
+ */
+declare function loadIdentity(): NodeIdentity | null;
+/** Create this node's identity. Only `murmur init` calls it. */
+declare function createIdentity(displayName?: string): NodeIdentity;
+/**
+ * Rename an existing node, keeping its `host_id`.
+ *
+ * `murmur init --name` on an already-initialised node used to ignore the flag
+ * silently, which is the one thing a rename must not do.
+ */
+declare function setDisplayName(displayName: string): NodeIdentity;
+
+/**
+ * The store, and the only place in murmur that holds a database handle or
+ * writes SQL.
+ *
+ * This interface is CLOSED. There is no `append`, no `ingest`, no log read, no
+ * partial-row update, and no local read other than `localPanes` — each of those
+ * shapes let a writer say something it had no standing to say, and each cost a
+ * shipped bug. Attention methods take no agent identity at all, which is what
+ * makes "a notifier cannot corrupt an agent row" structural.
+ */
 interface Store {
-    append(event: NewEvent): Event;
-    ingest(events: Event[]): number;
-    eventsSince(hostId: string, seq: number): Event[];
-    allEvents(): Event[];
-    /**
-     * The most recent event for one agent, or null.
-     *
-     * Exists so the `clear` hook does not have to open its own SQLite handle and
-     * write its own `ORDER BY seq DESC LIMIT 1`, which is what it used to do --
-     * making "store is the only module touching SQL" false, and putting knowledge
-     * of agent_id construction and event ordering in a CLI file where a schema
-     * change would miss it. That path swallows its own errors, so the miss would
-     * have been silent.
-     */
-    latestForAgent(hostId: string, agentId: string): Event | null;
-    maxSeq(hostId: string): number;
-    prune(horizonMs?: number): number;
-    peers(): Peer[];
-    /**
-     * Drop every event for one agent from this node's replica.
-     *
-     * For a remote agent this is a replica eviction, not a claim about truth: the
-     * authoring node still owns it, and a collect re-reads from the watermark if
-     * it is still alive.
-     */
-    forgetAgent(agentId: string): number;
-    forgetHost(hostId: string): number;
-    upsertPeer(peer: Partial<Peer> & {
-        name: string;
-        target: string;
-    }): void;
+    claimAgent(claim: AgentClaim): ClaimResult;
+    setActivity(update: ActivityUpdate): boolean;
+    releaseAgent(release: AgentRelease): boolean;
+    requestAttention(request: AttentionRequest): void;
+    acknowledgePane(pane: PaneId): number;
+    /** The one local read. Joins agents and attention by pane. No reconciliation. */
+    localPanes(): SnapshotPane[];
+    reconcileLocal(world: LocalWorld): ReconcileSummary;
+    buildLocalSnapshot(identity: NodeIdentity, world: LocalWorld): Snapshot;
+    peers(): PeerRecord[];
+    addPeer(name: string, target: string): void;
     removePeer(name: string): boolean;
+    replacePeerSnapshot(name: string, fetch: PeerFetch): void;
     close(): void;
 }
+/**
+ * Open the store. Takes no arguments and mints no identity.
+ *
+ * `openStore` deliberately does NOT read or create `identity.json`: identity is
+ * created only by `murmur init`, so a read path — a status-bar tick, a focus
+ * hook — cannot bring a node into existence as a side effect.
+ */
 declare function openStore(): Store;
 
-type StatusState = "working" | "blocked" | "done" | "crashed" | "idle";
-type Counts = Record<StatusState, number>;
-type Status = {
-    counts: Counts;
-    orchestrated_counts: Counts;
-    agents: (AgentView & {
-        stale: boolean;
-        age_ms: number | null;
-        event_age_ms: number | null;
-        tmux_down: boolean;
-        host: string;
-    })[];
-    peers: {
-        name: string;
-        display_name: string | null;
-        fetched_at: number | null;
-        stale: boolean;
-    }[];
+type Freshness = "fresh" | "stale";
+/**
+ * What a surface paints. Presentation only, derived from the three independent
+ * facts and never stored.
+ */
+type RenderState = "crashed" | "blocked" | "done" | "running" | "idle";
+/**
+ * THE single ordering table: which state matters most, for sorting and for
+ * choosing one word to show.
+ *
+ * `status.ts` and `pick.ts` import this rather than declaring their own copies,
+ * so no two surfaces can sort one list differently.
+ */
+declare const RENDER_PRIORITY: readonly RenderState[];
+/**
+ * The attention kinds only a human can answer, and the second table both
+ * surfaces must agree on.
+ *
+ * `blocked` means waiting for an answer an orchestrator cannot give -- mu places
+ * work, it cannot choose between two approaches. `crashed` means the process
+ * died, which a supervisor may or may not retry. Everything else about an
+ * orchestrated agent is its supervisor's business.
+ *
+ * `pick.ts` uses it to decide which crew rows are visible by default and
+ * `status.ts` to decide which crew states reach the status bar. They were two
+ * literals in two files answering one question, which is how a row that needed a
+ * human became one a human could not see.
+ */
+declare const NEEDS_HUMAN: readonly AttentionKind[];
+/**
+ * One pane, as every surface reads it: address, the three independent facts,
+ * owner metadata, and ages.
+ *
+ * Local and remote panes are the same type, built by the same mapping, because
+ * `Store.localPanes()` and a peer's cached snapshot both return
+ * `SnapshotPane[]`. One mapping means local and remote cannot drift apart.
+ */
+type PaneView = {
+    host_id: string;
+    /** The name the operator typed, or this node's display_name. */
+    host: string;
+    local: boolean;
+    pane: PaneId;
+    session: SessionId;
+    window: WindowId;
+    session_name: string | null;
+    window_name: string | null;
+    /** Null for an attention-only pane, which has no agent row. */
+    activity: Activity | null;
+    attention: AttentionKind[];
+    freshness: Freshness;
+    agent_id: string | null;
+    agent_name: string | null;
+    pi_session: string | null;
+    workstream: string | null;
+    role: string | null;
+    cli: string | null;
+    driver: Driver;
+    /** When the pane's own node last said something. Never `fetched_at`. */
+    updated_at: number | null;
+    /** When that node generated its snapshot. Null for local. */
+    snapshot_at: number | null;
+    /** When we last reached that node. Null for local. */
+    fetched_at: number | null;
 };
 /**
- * Fold the current view. Pure with respect to the network: the caller decides
- * whether to collect first (see `statusWithCollect`).
+ * How long a peer may go unfetched before its panes render stale.
+ *
+ * Re-exported from here rather than imported from the collector by view
+ * consumers, so freshness has one definition. See collector.ts for why sixty
+ * seconds.
+ */
+declare const STALENESS_MS = 60000;
+/**
+ * A duration as the shortest thing worth reading: "5m", "2h", "3d".
+ *
+ * Under a minute is the empty string: an age that changes every second is noise
+ * in a status column. This and `freshness` are the only two places a duration
+ * becomes text or a verdict.
+ */
+declare function age(ms: number | null): string;
+/**
+ * Freshness of a NODE, never of an agent.
+ *
+ * A peer we have never reached is stale rather than fresh: null means the first
+ * collect has not succeeded yet, and an unreachable host you just added must not
+ * render as up to date.
+ */
+declare function freshness(fetchedAt: number | null, now: number, thresholdMs?: number): Freshness;
+/**
+ * One word for a pane. Attention wins over activity, because attention is a
+ * request and activity is a description.
+ *
+ * A running agent with `blocked` attention is a valid and expected state, and
+ * surfaces that can show both, do — this is only for the ones that must pick.
  */
-declare function status(store: Store, now?: number): Status;
+declare function renderState(view: Pick<PaneView, "activity" | "attention">): RenderState;
+/**
+ * Every pane this node knows about: its own, plus one cached snapshot per peer.
+ *
+ * `identity` is non-null because every caller is a command that already requires
+ * `murmur init`, so no pane can be misclassified as remote by an absent one.
+ *
+ * No liveness is probed here, for local or remote. A remote pane's `activity` is
+ * whatever its own node last said; a stale node keeps its last-known fields
+ * verbatim beside an explicit warning.
+ */
+declare function paneViews(store: Store, identity: NodeIdentity, now?: number): PaneView[];
+/**
+ * Attention-first ordering, then the newest news, then address.
+ *
+ * TOTAL on purpose, and that is the whole reason the last two comparisons
+ * exist. Ties on state and age are ordinary rather than exotic -- a pair of
+ * crashed panes reconciled in one transaction shares a `requested_at` exactly --
+ * and `Array.prototype.sort` is stable only with respect to the order it was
+ * GIVEN, which here is whatever SQLite and the peer loop happened to produce. An
+ * unbroken tie therefore makes the list depend on that order: a status bar
+ * reshuffles between two identical ticks, and a picker row moves under the
+ * keypress that was aimed at it.
+ *
+ * Presentation only. No caller may read meaning into the position of a row --
+ * pane order in a snapshot carries none either, so a reader sorts for itself
+ * rather than trusting what it was served.
+ */
+declare function viewSort(views: PaneView[]): PaneView[];
+
+interface Mux {
+    currentWindow(): Location | null;
+    livePanes(): Set<PaneId> | null;
+    setWindowBadge(window: WindowId, state: RenderState | null): void;
+    attach(session: SessionId, window: WindowId): boolean;
+    windowForPane(pane: PaneId): WindowId | null;
+    panesInWindow(window: WindowId): PaneId[];
+    capture(pane: PaneId, lines?: number): string | null;
+    clientName(): string | null;
+    currentTarget(): string | null;
+    sessionNamed(name: string): boolean;
+    newSession(name: string, command: string): boolean;
+    setSessionOption(session: string, option: string, value: string): void;
+    switchClient(client: string | null, session: string): boolean;
+}
+declare const tmux: Mux;
+declare function pidAlive(pid: number): boolean;
 
-type Agent = Status["agents"][number];
 /**
- * The most specific human-readable name an agent has, never a tmux id.
+ * The most specific human-readable name a pane's agent has, never a tmux id.
  *
- * Four sources, most to least specific: mu's agent name, pi's session name,
- * the tmux window name, the tmux session name. The old picker showed window
- * names and that was the thing it did better than raw `$26:@79`; these are all
- * recorded on the event, so this reads the same for a local and a remote agent.
+ * Four sources, most to least specific: mu's agent name, pi's session name, the
+ * tmux window name, the tmux session name. All are recorded by the node that
+ * owns the pane, so this reads the same for a local and a remote pane -- a
+ * reader cannot resolve a remote window id against its own tmux.
  *
  * Falls back to the window id only when a node recorded no names at all, which
- * means a pre-names event or a non-tmux harness.
+ * means a non-tmux harness.
  */
-declare function agentLabel(agent: Agent): string;
+declare function agentLabel(agent: PaneView): string;
 /**
- * Where the agent lives, for the second column. Names only -- the ids are what
+ * Where the pane lives, for the second column. Names only -- the ids are what
  * jumps, not what a human reads.
  */
-declare function agentLocation(agent: Agent): string;
+declare function agentLocation(agent: PaneView): string;
 declare function shellQuote(value: string): string;
 /**
  * The one process call jump makes that is not a tmux command: the remote probe,
@@ -204,67 +438,125 @@ type JumpResult = {
     ok: true;
 } | {
     ok: false;
-    reason: "no_peer" | "unreachable" | "no_tmux" | "window_gone" | "attach_failed";
+    reason: "no_peer" | "unreachable" | "no_tmux" | "pane_gone" | "attach_failed";
     message: string;
 };
-declare function jumpToAgent(store: Store, agent: Agent, mux?: Mux, run?: Runner): JumpResult;
-
 /**
- * How long a peer may go unfetched before it renders stale.
- *
- * Not derived from a collect interval, because murmur has no scheduler: there
- * is no timer here, and `collect` runs only when a command asks for it. In
- * practice the cadence is the operator's tmux `status-interval`, since
- * `murmur status` collects and tmux re-runs it on a tick.
- *
- * So this is a judgement about the operator's setup, not arithmetic on a
- * constant murmur controls. Sixty seconds is comfortably above a default 15s
- * status bar -- a peer needs to miss several ticks before it is called out,
- * which keeps one slow fetch from flickering the HUD. A status bar slower than
- * this will show every peer permanently stale; that is the number to change if
- * so.
+ * Jump to a pane, wherever it lives.
+ *
+ * NEVER MUTATES STATE ON FAILURE. A failure is a report: a reason and a message,
+ * nothing written. The next collect reconciles either way, and only the owning
+ * node can author facts about its own panes.
  */
-declare const STALENESS_MS = 60000;
+declare function jumpToAgent(store: Store, agent: PaneView, mux?: Mux, run?: Runner): JumpResult;
+
+interface Channel {
+    exec(target: string, argv: string[]): Promise<string>;
+}
+declare const ssh: Channel;
+declare function hasWarmSocket(target: string): boolean;
+
 declare const MAX_CONCURRENT_PEERS = 8;
 type CollectResult = {
     peer: string;
     ok: boolean;
-    ingested: number;
+    /** Panes in the snapshot we just stored. Zero is a normal, valid answer. */
+    panes: number;
     error?: string;
+    /**
+     * True when the peer could not be reached at all, as opposed to answering
+     * with something wrong.
+     *
+     * A fleet normally has nodes that are asleep or switched off, so this is the
+     * expected outcome rather than a fault, and callers use it to stay quiet
+     * about the ordinary case while still reporting a peer that is reachable but
+     * broken -- a bad snapshot version, a missing binary, an auth problem.
+     */
+    unreachable?: boolean;
 };
 /**
- * Peers are fetched concurrently and applied serially.
+ * Fetch every peer's snapshot, validate it, and replace the cache whole.
  *
  * Concurrent because an unreachable peer costs the full ssh timeout, and a
- * serial loop charged that to every other peer behind it: three asleep laptops
- * made `murmur status` hang for thirty seconds and let the HUD tick overlap
- * itself. Fanning out makes the whole collect cost the slowest peer, not the
- * sum — capped at MAX_CONCURRENT_PEERS in flight and bounded overall by
- * COLLECT_DEADLINE_MS.
- *
- * Applied serially, in peer order, because better-sqlite3 is synchronous: there
- * is nothing to win by interleaving writes, and keeping the order stable keeps
- * the result list aligned with `store.peers()`.
+ * serial loop charged that to every peer behind it: three asleep laptops made
+ * `murmur status` hang for thirty seconds. Applied serially in peer order,
+ * because better-sqlite3 is synchronous and a stable order keeps the result list
+ * aligned with `store.peers()`.
+ *
+ * One round trip per peer, and never a second: the document is complete, so what
+ * arrives either replaces the cache entirely or does not touch it.
  */
-declare function collect(store: Store, channel: Channel, now?: number, deadline?: Promise<void>): Promise<CollectResult[]>;
-
-declare const SCHEMA_VERSION = 2;
-declare function eventFromWire(wire: Record<string, unknown>): Event;
-declare function exportJsonl(store: Store, since: number, isAlive: LiveCheck, live?: Set<string> | null): string;
+declare function collect(store: Store, channel: Channel, now?: number, deadline?: Promise<void>, mux?: Mux): Promise<CollectResult[]>;
 
-declare function glance(store: Store, agent: Agent, lines?: number): string | null;
-
-type NodeIdentity = {
-    host_id: string;
-    display_name: string;
-};
-declare function loadIdentity(): NodeIdentity | null;
-declare function ensureIdentity(displayName?: string): NodeIdentity;
+declare function glance(store: Store, agent: PaneView, lines?: number): string | null;
 
 declare function stateDir(): string;
 declare function configDir(): string;
+/** The current-state database. The only database murmur holds. */
 declare function dbPath(): string;
 
-declare const VERSION: string;
+/**
+ * A peer answered, and what it said is not a snapshot.
+ *
+ * A distinct type because the collector must be able to tell this from an
+ * unreachable host: a node that serves a bad document is REACHABLE BUT BROKEN,
+ * and an operator needs to see that rather than "asleep, probably".
+ */
+declare class SnapshotInvalidError extends Error {
+    readonly path: string;
+    constructor(path: string, detail: string);
+}
+/**
+ * Parse and totally validate one snapshot document.
+ *
+ * `murmur_snapshot` must be exactly 1: a higher value is rejected too, because
+ * forward compatibility is not offered here and a version mismatch is an
+ * operator-visible pairing problem. Saying so is the honest report; guessing at
+ * a newer document's meaning is not.
+ */
+declare function parseSnapshot(input: string): Snapshot;
+
+type Counts = Record<RenderState, number>;
+type Status = {
+    counts: Counts;
+    orchestrated_counts: Counts;
+    panes: PaneView[];
+    peers: {
+        name: string;
+        display_name: string | null;
+        fetched_at: number | null;
+        snapshot_at: number | null;
+        last_error: string | null;
+        stale: boolean;
+    }[];
+};
+declare function tmuxStatus(view: Status): string;
+/**
+ * The current view. Pure with respect to the network: the caller decides whether
+ * to collect first (see `statusWithCollect`).
+ *
+ * `identity` is required rather than resolved here, because every caller is a
+ * command that already fails without one.
+ */
+declare function status(store: Store, identity: NodeIdentity, now?: number): Status;
+/**
+ * Collect from peers, then read. This is what every user-facing surface wants:
+ * the view reflects the sync that just ran, rather than the one before it.
+ *
+ * Awaiting matters for two reasons. A fire-and-forget collect makes every
+ * invocation show data one run stale. And the callers close the store in a
+ * `finally`, so a collect still in flight lands on a closed handle and reports
+ * "The database connection is not open", which looks like corruption rather
+ * than a race.
+ *
+ * Sync must never fail a command, and on this path it must never print either:
+ * `status` runs on every status-bar tick and `pick` runs inside a
+ * display-popup, so one sleeping laptop would otherwise write ssh diagnostics
+ * to stderr several times a minute, forever. `murmur collect`, which a human
+ * runs deliberately, is the only place that prints.
+ */
+declare function statusWithCollect(store: Store, identity: NodeIdentity, now?: number, channel?: Channel, mux?: Mux): Promise<Status>;
+
+declare const MURMUR_VERSION: string;
 
-export { type Agent, type AgentState, type AgentView, type Channel, type CollectResult, DEFAULT_DRIVER, type Driver, type Event, type JumpResult, type LiveCheck, MAX_CONCURRENT_PEERS, type Mux, type NewEvent, type NodeIdentity, type Peer, SCHEMA_VERSION, STALENESS_MS, STORE_VERSION, type Status, type Store, VERSION, agentLabel, agentLocation, attentionSort, collect, configDir, dbPath, ensureIdentity, eventFromWire, exportJsonl, foldAgent, foldAll, glance, hasWarmSocket, isStale, jumpToAgent, loadIdentity, openStore, pidAlive, shellQuote, ssh, stateDir, status, tmux };
+export { type Activity, type ActivityUpdate, type AgentClaim, type AgentMeta, type AgentRelease, type AttentionKind, type AttentionRequest, type Channel, type ClaimResult, type CollectResult, DEFAULT_DRIVER, type Driver, type Freshness, type JumpResult, type LiveCheck, type LocalWorld, type Location, MAX_CONCURRENT_PEERS, type Mux, NEEDS_HUMAN, type NodeIdentity, type PaneId, type PaneView, type PeerFetch, type PeerRecord, RENDER_PRIORITY, type ReconcileSummary, type RenderState, STALENESS_MS, type SessionId, type Snapshot, type SnapshotAgent, type SnapshotAttention, SnapshotInvalidError, type SnapshotPane, type Status, type Store, MURMUR_VERSION as VERSION, type WindowId, age, agentLabel, agentLocation, asPaneId, asSessionId, asWindowId, collect, configDir, createIdentity, dbPath, freshness, glance, hasWarmSocket, jumpToAgent, loadIdentity, openStore, paneViews, parseSnapshot, pidAlive, renderState, setDisplayName, shellQuote, ssh, stateDir, status, statusWithCollect, tmux, tmuxStatus, viewSort };