Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

71.2 KB
Raw Blame
import { create, type StoreApi, type UseBoundStore } from 'zustand'
import { WORKING_STALE_MS } from '@shared/agents/stale'
import type { AgentId } from '@shared/agents/config'
import type { AgentState } from '@shared/agents/normalize'
import type { HeldPermission } from '@shared/agents/permission-answer'
import type { NodeTerminalApi, ObservedClaudeAccount } from '@shared/types'
import type { WakeContext } from '../terminal/wake-identity'

/**
 * Transient per-node status for agent (e.g. Claude Code) sessions, driven by the agent's hooks.
 * `unread`, `session`, `sessionId`, `agentId`, `account`, `loop`, `hibernated` and `lastSeen` are
 * persisted to localStorage so they survive a reload/restart; the live `state` (working/waiting/…)
 * is not (it'd be stale on relaunch), and neither are its two clocks (`stateAt`, `lastEventAt`).
 * `lastSeen` is a THIRD clock that exists only to be persisted: when the last hook event landed and
 * which state it asserted, restored as a "last seen" label and a sort key — never as a state, and
 * never as an idle clock (see its field comment).
 * `agentId` is durable because a PLAIN terminal's agent identity exists nowhere else: an
 * explicit agent node re-derives it from `data.agentId`, but a hand-launched `claude` in a
 * plain terminal is only known here, and its context links must keep classifying across
 * restarts (tmux keeps the session — and the agent — alive through them). `account` is durable
 * for exactly that reason too — see its field comment.
 *
 * ONE STORE PER CORE (stage 4): `createAgentStatusSession(persistKey?)` builds an isolated
 * instance — node ids are per-core, so status tables from two cores must never mix. The module
 * keeps a DEFAULT instance for the local core and re-exports its members under the historical
 * names, so the existing single-session consumers are untouched. The session registry resolves
 * a store through `agentStatusForApi(api)` — memoized BY API IDENTITY like presence, and seeded
 * with `window.nodeTerminal → defaultAgentStatus`, so the local session (and any path handed a
 * repeat api) structurally gets the one existing store, never a parallel twin.
 *
 * PERSISTENCE IS PER-KEY, AND ONLY THE DEFAULT HAS ONE. This is deliberately the opposite call
 * from presence's shared ME_KEY: {name, color} is who the HUMAN is (one per person, shared
 * across sessions), but agent status is per-NODE state on a SPECIFIC core — a remote core's
 * unread/sessionId for `nt-x` is not this machine's `nt-x` (tmux persistKeys are unique within
 * one core only), and `save()` rewrites the WHOLE table, so a remote session sharing
 * `nodeterm.agentStatus` would clobber the local nodes' persisted unread/session/loop on its
 * first write. So: the default instance keeps the historical key (bit-for-bit today's
 * behavior, legacy migration included); a keyless instance persists NOTHING (remote status is
 * rebuilt from the remote core's hooks on reconnect — a durable per-remote key needs a stable
 * session identity, which sub-stage 4c owns); the `persistKey` parameter is how 4c opts a
 * session into its own namespaced key without touching this file.
 */
export interface AgentNodeStatus {
  /** Live activity; undefined = idle/unknown. */
  state?: AgentState
  /**
   * When the LAST hook event asserted the current state (freshness, not transition time).
   * Never rendered — drives the done-holdoff guard, the stale-working sweeper, and the
   * interrupt-inference baseline. Same-state events refresh it in place (no re-render).
   */
  stateAt?: number
  /**
   * Did the hook POST that set the current `state` carry a per-node token? Mirrors
   * `MirrorEntry.stateVerified` (core/agent-status-mirror.ts), which is where the messaging gate
   * actually reads it — this copy exists so the UI can SHOW identity state, not so anything can
   * gate on it. TRANSIENT, deliberately excluded from the durable whitelist in `save()`: a relaunch
   * has seen no events, and a restored `true` would assert proof that was never presented this run.
   */
  stateVerified?: boolean
  /**
   * When this node last CHANGED state (or was explicitly woken) — rendered as the status group's
   * relative age and also read as the idle clock by `terminal/hibernation-policy.ts`. Deliberately
   * not `stateAt`: that one is refreshed by every same-state event (freshness), while "how long in
   * this state" means "how long since the transition". TRANSIENT — never persisted: a relaunch has
   * seen no events yet, and a stale stamp read as "idle since before the restart" would hibernate a
   * session the moment the app came back. Absent ⇒ unknown idle ⇒ never a hibernation candidate.
   */
  lastEventAt?: number
  /**
   * When the LAST hook event for this node landed, and the state it asserted — the one status clock
   * that survives an app restart. PERSISTED under its OWN small key (`<persistKey>.lastSeen`, see
   * `saveClocks`) — never inside the main table, whose write cadence stays exactly what it was.
   * Bounded: `LAST_SEEN_MAX` newest, `LAST_SEEN_MAX_AGE_MS` old at most, dropped with the node by
   * `remove` (a deletion path that bypasses `remove` leaves a clock that ages out; it can never make
   * a row, since rows come from canvas nodes). The age-out is also the boot sweep's grace: an entry
   * whose node is in no project is dropped once its clock is gone (`orphanStatusIds`,
   * lib/unreadBadge.ts).
   *
   * It is a record of the PAST, restored as nothing else:
   *  - NOT as `state`: after a relaunch nothing has reported, a turn may have started or ended while
   *    the app was down (the hook server was down with it), so the state stays unknown until the
   *    next hook event. `lastSeen.state` is shown as "what it was last seen doing", and acted on in
   *    exactly ONE place: a user-confirmed bulk pause (`idleForPause`, lib/bulkPause.ts) treats an
   *    unknown-state session as pausable only when it was last seen `done`. That is weak evidence
   *    on purpose: the user asked for the pause, the runner still proves the agent owns its pane,
   *    and without it every session after a restart would be unpausable. Nothing AUTOMATIC reads it.
   *  - NOT as `lastEventAt`: that field is the Eco idle clock AND the `idleKnown` signal for the
   *    offscreen release deferral, and a restored stamp read as "idle since before the restart"
   *    would make a session with an unknown state look hours idle. Eco stays inert for a session
   *    with no hook event in this run, deliberately — see `hibernation-policy.ts` ("A restored clock
   *    is not an idle proof").
   * Its readers are the sessions sidebar's order and age label (`sessionList.ts`), which use it only
   * while `lastEventAt` is unset, and the bulk-pause gate above. `lastSeen.restored` (set on load, never written) is what says the
   * clock is from BEFORE the restart; any hook event in this run replaces the object without it.
   *
   * Written on EVERY hook event, same-state ones included (in place, no re-render — the fast path's
   * rule — except the first event after a restart, which re-renders so the row re-sorts and loses
   * its "restored" label), and saved on a trailing debounce (`LAST_SEEN_SAVE_DEBOUNCE_MS`, capped by
   * `LAST_SEEN_SAVE_MAX_WAIT_MS`) plus `pagehide`, so a busy turn costs no write per tool event.
   */
  lastSeen?: LastSeen
  /**
   * When this node last launched a BACKGROUND shell task (Claude's `Bash` with
   * `run_in_background: true`). Such a task lives inside the CLI process, so `/exit` — Eco
   * hibernation and the bulk in-place restart both type it — kills it silently, with no output and
   * no error. The stamp is what those two exclude on.
   *
   * Second writer: a Claude `Stop` whose `background_tasks` inventory still lists running work
   * (async subagents, background shells — `NormalizedAgentEvent.backgroundTaskIds`). A background
   * subagent that ends its turn while its own work runs fires SubagentStop, so its card reads done
   * while it is only paused; the inventory is what still says the CLI holds live work.
   *
   * TRANSIENT — never persisted, same rationale as `lastEventAt`: after a relaunch Eco is inert
   * until a turn happens anyway, and any turn's `working` would have cleared this. A stale stamp
   * restored from disk would exempt the node from Eco for good.
   */
  backgroundTaskAt?: number
  /**
   * The agent CLI was exited to reclaim its RAM ("Eco" mode) and its conversation is waiting to be
   * resumed when the node is next viewed. PERSISTED beside unread/session/sessionId: the tmux
   * session outlives the app, so after a relaunch this flag is the only thing that knows the pane
   * holds a shell rather than a live CLI.
   */
  hibernated?: boolean
  /**
   * What the pane's foreground command settled to once the CLI let go of it — recorded at the
   * moment of hibernation, persisted beside the flag, and dropped with it.
   *
   * The wake refuses to type a launch line into a pane it does not recognize as a shell, and its
   * allowlist (`isShellCommand`) knows zsh/bash/fish/pwsh/cmd/nu/… but not `xonsh` or `elvish`. The EXIT
   * half has a second, allowlist-free signal for exactly those users (the foreground command
   * stopped being the CLI, twice in a row) — so without this the wake is STRICTER than the exit,
   * and an `xonsh` user could be hibernated and then never woken: the chip would refuse forever.
   * Remembering what we exited TO closes that gap, and it is narrow by construction: it permits
   * one specific string, on one specific node, recorded by us.
   *
   * It is a RECORD, not just a string, because the name alone was not enough: a pane whose agent
   * was reached over an interactive `ssh` presents the same local shell after that ssh dies as it
   * would if the CLI had run here, so the wake typed the resume into the wrong machine's login
   * shell (issue #823). The pane identity travels with the name, and — more importantly — this
   * field is only ever written by an exit that first PROVED the agent owned the pane. An entry
   * without one is refused rather than guessed at, which is also how pre-fix records retire.
   */
  hibernatedContext?: WakeContext
  /**
   * The last hibernation attempt found no agent in this node's pane, so nothing was exited
   * (`decideHibernateExit` → `'not-in-this-pane'`: the pane holds a plain shell, or an interactive
   * `ssh` whose agent lives on another machine — see wake-identity.ts).
   *
   * TRANSIENT, and read by the sweep's PLAN, not only by the exit. That placement is the whole
   * point: the plan is a deterministic sort-and-slice over the oldest-idle nodes, and a node in
   * this state stays `done`, offscreen and idle forever — so it would sit at the head of that
   * order and occupy a batch slot on every single pass, refusing each time, while no eligible node
   * behind it was ever reached. That is the identical starvation the policy's `remote` field is
   * excluded at plan time to avoid; this is the same rule for the same reason.
   *
   * Withdrawn by any live hook event (the CLI is demonstrably back in the pane) — see `setState`.
   */
  paneUnverified?: boolean
  /**
   * Why the last wake refused, in one sentence for the chip's tooltip. Transient: it describes the
   * pane as it was a moment ago, and a stale reason on a pane that has since been fixed would be a
   * worse lie than no reason at all. Cleared by a resume, by any live hook event, and by the next
   * wake that does not refuse.
   */
  wakeBlocked?: string
  /**
   * The user (or Eco's idle sweep, when `settings.agentHibernationPersistAcrossRestart` is on)
   * explicitly PAUSED this node: its CLI was exited (and, for the deeper "pause & end session"
   * choice, its tmux session recycled too) and it must NOT auto-resume on the next reveal or on
   * a cold restart — only an explicit Resume brings it back. PERSISTED, and — unlike `hibernated`
   * — deliberately NOT cleared by a `fresh` cold restore: that self-heal is what lets Eco's
   * ordinary hibernation "come back automatically when reopened", which is exactly the behavior
   * this flag exists to opt a node OUT of. Cleared only by an explicit resume or by a genuine
   * live hook event (see `setState`'s self-heal) — the same self-heal `hibernated` gets, for the
   * same reason: a live state is proof the CLI is running, so a standing `paused` would be wrong.
   */
  paused?: boolean
  /**
   * This node's agent CLI left its pane and NOTHING accounted for it — no SessionEnd hook, no
   * `hibernated`, no `paused`. In practice: the process was killed (the OOM killer, a `pkill`, a
   * host that ran out of memory), or a cold-restore `--resume` failed and fell back to a bare
   * shell. The decision is the pure `terminal/agent-liveness.ts`; this field is only where the
   * node records the verdict so its header and the kanban card can render the DROPPED chip.
   *
   * TRANSIENT, like `state` and for a stronger reason than the other clocks: it is a claim about a
   * pane, and a pane's contents are re-measurable in milliseconds. Persisting it would let a stale
   * verdict survive into a run where the session had been resumed by hand — a chip on a healthy
   * node with nothing left to disprove it, since the check that would clear it only runs for nodes
   * it can still see.
   */
  dropped?: boolean
  /**
   * This node's CLI announced its own exit (any SessionEnd hook: `/exit`, `/quit`,
   * Ctrl+D) and nothing has started a session since.
   *
   * It exists because a SessionEnd used to be recorded only as `state: undefined`, which is also
   * what an agent that is merely idle looks like. `agentId` is durable and outlives the CLI, so
   * `agentProcessInPane` read every exited agent as still running, and the memory levers refused
   * forever to release a non-persistent pane that held nothing but a shell.
   *
   * TRANSIENT, like `dropped`: it is a claim about a pane in this app run. Cleared by the next
   * SessionStart and by any state transition, since only a live CLI fires those.
   */
  sessionEnded?: boolean
  /** Which agent this node is running (claude/codex/gemini/…), when known. */
  agentId?: AgentId
  /**
   * Which Claude account this node's session was OBSERVED running under, off any hook event that
   * carried one (`NormalizedAgentEvent.account`, derived from the hook's `transcript_path`).
   *
   * PERSISTED beside `agentId`, and durable for the same reason: a hand-launched
   * `CLAUDE_CONFIG_DIR=~/.claude-2 claude` in a PLAIN terminal has its identity nowhere else —
   * the node carries no `data.accountId`, and tmux keeps the session alive across an app restart
   * that will see no further event until the user next talks to it. Without this the chip and the
   * account-scoped transcript readers would silently fall back to the system account after every
   * relaunch.
   *
   * Deliberately NOT cleared at a session end (same rule as `agentId`): identity survives turn
   * boundaries, and a new session in the same pane overwrites it with its own observation.
   *
   * A LABEL, never a gate — see `ObservedClaudeAccount` in shared/types.
   */
  account?: ObservedClaudeAccount
  /** A turn finished / needs attention while the user wasn't looking. */
  unread: boolean
  /** Claude's own session name/title (from the terminal title), shown beside the title. */
  session?: string
  /** Claude session id (from hooks) — used to resume/branch the conversation. */
  sessionId?: string
  /**
   * Deterministic hook-reply approval ticket (docs/hook-reply-approvals.md). Set while the node is
   * `blocked` on a Claude permission request whose managed hook is holding open; the header's
   * Approve/Deny buttons answer it. TRANSIENT — never persisted, and cleared the moment the node
   * leaves `blocked` (so the buttons vanish once the decision lands). Absent = legacy prompt path.
   */
  pendingId?: string
  /**
   * The request the node's managed hook is HOLDING (answer-file ticket + tool name), so a surface
   * can offer controls that fit it — approve a plan with a follow-on mode, answer a question —
   * through a structured `answerPermission`. Unlike `pendingId` it survives the mirror's question
   * classification (which strips `pendingId` from a picker so approve/deny never lights there), and
   * it is kept while the node is in EITHER needs-you state (`blocked` or `waiting`; a held picker is
   * broadcast as `waiting`). TRANSIENT, cleared as soon as the node leaves needs-you. It can outlive
   * the hold itself (the hook times out with no event), which is why an answer to a stale one is
   * simply refused by core (`answerPermission` resolves false).
   */
  held?: HeldPermission
  /**
   * The station's LAST turn ended on an API/model error (issue #521) — set from the agent's own
   * `StopFailure` hook, cleared by the next genuine new turn.
   *
   * An annotation beside `state`, never a fifth `AgentState`: an errored station **is** idle, so
   * the two facts coexist. Before it existed, a station whose first turn died was byte-identical
   * to one that had finished — the orchestrator's `--after` dependents fired on an upstream that
   * had produced nothing, and started a whole dependency chain on bad ground. That is what
   * `depSatisfied` now refuses (`renderer/lib/pendingLaunch.ts`).
   *
   * TRANSIENT, like `state` itself, and for the same reason `lastEventAt` is: after a relaunch no
   * hook has spoken, nothing armed can fire anyway, and a verdict restored from disk would
   * describe a turn from another app run.
   *
   * `at` only. Whether the hook payload carries the failure text has not been measured, and
   * `last_assistant_message` is the previous assistant turn rather than the error — see
   * `NormalizedAgentEvent.errored`. Reading the error itself is still owed.
   */
  lastTurnError?: { at: number }
  /**
   * The station's LAST turn was interrupted by the user (Esc / Ctrl+C) instead of finishing — from
   * an interrupted `done` (`NormalizedAgentEvent.interrupted`: the transcript marker Claude writes,
   * a `Stop` with `is_interrupt`, or the `idle_prompt` rescue).
   *
   * Read by exactly one rule: `--after` does not release a dependent on it (`depSatisfied`). The
   * turn the dependent was waiting for did not produce its result — the person stopped it,
   * usually to redirect it — so starting the next station on it is the same mistake #521 closed
   * for an errored turn. It is deliberately NOT `lastTurnError`: an interrupt is not a failure, so
   * the TURN FAILED chip, the station-failure notice, team progress and issue runs stay as they
   * were. ▶ still runs the dependent by hand.
   *
   * Cleared by the next genuine new turn, and by any `done` that is not interrupted (a turn that
   * then ends normally — an injected `<task-notification>` turn has no newTurn — is the last turn
   * now). TRANSIENT, like `lastTurnError`.
   */
  lastTurnInterrupted?: { at: number }
  /** Set when running /loop, /schedule or /cron (heuristic); shown as a connected node. */
  loop?: {
    count: number
    kind: 'loop' | 'schedule' | 'cron'
    /**
     * The user dismissed the CARD, but the job itself is still out there. Only `cron`/`schedule`
     * ever carry this: those outlive turns, sessions and app restarts, so "I don't want to look at
     * this card" and "this job is gone" are different statements — and the card's × has always
     * said so ("does not remove the job"). An in-session `/loop` still clears outright; it dies
     * with its session anyway.
     *
     * It matters beyond the card: `loop` is the ONLY record that this node has a wakeup pending,
     * and it is what stops Eco mode from hibernating it (`/exit` kills the CLI process, and the
     * scheduled wakeup dies with it — a silently cancelled job). Clearing the entry on dismiss
     * dropped that guard while the job lived on, so the fact is now retained and only the RENDER
     * filters on it. A real end (CronDelete) still clears the entry.
     */
    dismissed?: boolean
    /** Schedule expression (cron) shown as a sub-label. */
    schedule?: string
    /** The task/prompt — shown in full and re-issued by the node's Play button. */
    task?: string
    /** Per-iteration summaries (in-session /loop). */
    items: string[]
  }
}

/**
 * The next `lastTurnInterrupted` for one `setState` edge: `'set'` to stamp it now, the previous value
 * to keep it, `undefined` to clear it. Pure. A new turn clears; an interrupted `done` sets; any
 * other `done` clears (that turn ended normally); every other edge keeps.
 */
export function interruptVerdict(
  prev: { at: number } | undefined,
  state: AgentState | undefined,
  newTurn?: boolean,
  interrupted?: boolean
): { at: number } | 'set' | undefined {
  if (newTurn) return undefined
  if (state === 'done') return interrupted === true ? 'set' : undefined
  return prev
}

/**
 * Does this event record `lastTurnInterrupted`? An interrupted `done` does — EXCEPT the `idle`
 * rescue (Claude's `idle_prompt`), which is flagged interrupted only so it raises no completion
 * alert. Measured on 2.1.285, `idle_prompt` follows a NORMAL Stop and not an interrupted turn, so a
 * rescue that moves a working node means the Stop POST was lost (a flapping SSH tunnel) on a turn
 * that finished normally — holding its `--after` dependents would be wrong.
 */
export function recordsTurnInterrupt(e: { interrupted?: boolean; idle?: boolean }): boolean {
  return e.interrupted === true && e.idle !== true
}

export interface AgentStatusStore {
  byId: Record<string, AgentNodeStatus>
  /** The terminal node the user is currently focused in (for unread decisions). */
  activeId: string | null
  setActive(id: string, active: boolean): void
  /** `newTurn` marks a genuine UserPromptSubmit — the only working that may follow a fresh done.
   *  `pendingId` (deterministic approvals) is retained only while `state === 'blocked'`; any other
   *  state clears it, so the header's Approve/Deny buttons disappear as soon as the node moves on.
   *  `verified` is the identity evidence for THIS transition (see `stateVerified`); a caller that
   *  omits it asserts nothing, which is why it is trailing and optional.
   *  `errored` says this `done` came from the agent's `StopFailure` hook (see `lastTurnError`);
   *  `newTurn` retires the previous turn's verdict, so the two are read on the same edge. */
  setState(
    id: string,
    state: AgentState | undefined,
    agentId?: AgentId,
    newTurn?: boolean,
    pendingId?: string,
    verified?: boolean,
    errored?: boolean,
    held?: HeldPermission,
    interrupted?: boolean
  ): void
  /**
   * Subscribe to EVERY hook event `setState` records for node `id` — same-state ones included, and
   * only once the store already reflects it. A zustand selector cannot see those: the same-state
   * fast path refreshes `stateAt` IN PLACE and returns the same state object, so no subscriber is
   * notified (deliberately — a notification per tool event would re-run every header's selector).
   * This side channel is how the ⌘M panel refreshes its tail while a turn runs. Returns unsubscribe.
   */
  onHookEvent(id: string, cb: () => void): () => void
  /** Clear `working` entries whose last event is older than `staleMs` (lost-Stop safety net). */
  sweepStaleWorking(staleMs?: number): void
  setSession(id: string, session: string): void
  /** Record — or, with `undefined`, FORGET — this node's agent session id. Forgetting is what a
   *  cold-restore resume does when the CLI reports the conversation does not exist (issue #707):
   *  keeping a proven-dead id would make the next cold restore replay the same failed `--resume`. */
  setSessionId(id: string, sessionId: string | undefined): void
  /** Record the Claude account a hook event says this node is running under. Persisted; see
   *  `account`. Idempotent — a re-assert of the same account writes nothing. */
  setAccount(id: string, account: ObservedClaudeAccount): void
  /** Mark the node's agent CLI as exited-for-RAM (true) or live again (false). Persisted.
   *  Waking also restarts the idle clock (`lastEventAt`), so a quiet resumed session is not
   *  re-hibernated on the next sweep. */
  setHibernated(id: string, on: boolean): void
  /** Record the pane this node's CLI let go of (`null` = forget: a stale record must never permit
   *  a wake into a pane we did not measure). See `hibernatedContext`. */
  setHibernatedContext(id: string, ctx: WakeContext | null): void
  /** Record (or withdraw) "the last hibernation attempt found no agent in this pane". Transient;
   *  see `paneUnverified`. Withdrawn automatically by any live hook event. */
  setPaneUnverified(id: string, on: boolean): void
  /** Record (or clear) why the last wake refused, for the chip's tooltip. See `wakeBlocked`. */
  setWakeBlocked(id: string, reason: string | null): void
  /** Mark the node explicitly paused (true) or resumed (false). Persisted; see `paused`. Waking
   *  restarts the idle clock, same as `setHibernated` — a resumed session must not read as having
   *  been idle since before the pause. */
  setPaused(id: string, on: boolean): void
  /** Record (or withdraw) the verdict that this node's CLI died unannounced. Transient; see
   *  `dropped`. Cheap to call repeatedly — it bails when the flag already reads that way. */
  setDropped(id: string, on: boolean): void
  /** Record (or withdraw) that this node's CLI announced its exit. Transient; see `sessionEnded`.
   *  Bails when the flag already reads that way. */
  setSessionEnded(id: string, on: boolean): void
  /** Record that this node just launched a background shell task (see `backgroundTaskAt`).
   *  Transient — nothing is written to localStorage. */
  markBackgroundTask(id: string): void
  markUnread(id: string): void
  /**
   * Drop a node's unread flag. By default a clear of a FINISHED (done) node also ACKs the read
   * cross-surface (dismisses the paired phone's DONE Live Activity via the mirror's `ackDone`).
   * Pass `{ external: true }` for a clear that was ITSELF driven by a phone read-ack the host swept
   * (`agent:unread-clear`): it must NOT re-ack, or host→renderer→ackDone would loop.
   */
  clearUnread(id: string, opts?: { external?: boolean }): void
  /** Start (active=true, resets) or stop a /loop, /schedule or /cron indicator. */
  setLoop(
    id: string,
    active: boolean,
    kind?: 'loop' | 'schedule' | 'cron',
    opts?: { schedule?: string; task?: string }
  ): void
  /** Hide a cron/schedule CARD while keeping the fact that the job exists (see `loop.dismissed`).
   *  No-op if the node has no loop entry. */
  dismissLoopCard(id: string): void
  /** Record a /loop iteration (count++ and append its summary). No-op if not looping. */
  bumpLoop(id: string, message?: string): void
  remove(id: string): void
  /** Drop several entries with ONE write of each key (the boot sweep of orphaned entries —
   *  `orphanStatusIds` in lib/unreadBadge.ts decides which). Ids not in the table are ignored. */
  removeMany(ids: readonly string[]): void
}

/** The persisted "last seen" clock (see `AgentNodeStatus.lastSeen`). */
export interface LastSeen {
  /** Epoch ms of the last hook event this machine received for the node. */
  at: number
  /** The state that event asserted; undefined = the event left the state unknown (a SessionStart
   *  or SessionEnd). */
  state?: AgentState
  /** TRANSIENT, set on load only: this clock came off disk, from before the app restarted. Never
   *  written back — every hook event in this run builds a fresh object without it. */
  restored?: true
}

/** At most this many persisted clocks (newest kept): a canvas that has churned through thousands of
 *  nodes must not grow the clock key forever. */
export const LAST_SEEN_MAX = 1000
/** A clock older than this is dropped on load: "last seen 4 months ago" orders nothing useful, and
 *  an entry that old most likely belongs to a node deleted by a path that never reached `remove`. */
export const LAST_SEEN_MAX_AGE_MS = 90 * 24 * 60 * 60_000
/** A persisted clock more than this far in the FUTURE is refused, not clamped: localStorage is
 *  hand-editable, and a future stamp would pin a row to the top of its section for good. The slack
 *  covers an ordinary clock correction between two runs. */
export const LAST_SEEN_FUTURE_SLACK_MS = 5 * 60_000
/** Trailing debounce for the clock key: written once the hook events have been quiet this long… */
export const LAST_SEEN_SAVE_DEBOUNCE_MS = 5000
/** …or at the latest this long after the first unsaved event, so a canvas that is never quiet still
 *  persists its clocks (a crash then loses at most this window). The key is ~47 bytes per clock. */
export const LAST_SEEN_SAVE_MAX_WAIT_MS = 30_000
/** The clocks' own localStorage key, beside (never inside) the main table. */
export const lastSeenKey = (persistKey: string): string => `${persistKey}.lastSeen`

const AGENT_STATES: ReadonlySet<string> = new Set<AgentState>(['working', 'waiting', 'blocked', 'done'])

/**
 * Read a persisted `lastSeen` back — or nothing. Pure and exported for the corrupt-input tests. The
 * value is hand-editable input: a non-object, a non-finite / non-positive / too-old / future `at`
 * yields no clock at all; an unknown `state` keeps the clock and drops the state (the time is still
 * a fact about the node, the label just cannot name what it was doing).
 */
export function readLastSeen(v: unknown, nowMs: number): LastSeen | undefined {
  if (!v || typeof v !== 'object') return undefined
  const { at, state } = v as { at?: unknown; state?: unknown }
  if (typeof at !== 'number' || !Number.isFinite(at) || at <= 0) return undefined
  if (at > nowMs + LAST_SEEN_FUTURE_SLACK_MS) return undefined
  if (nowMs - at > LAST_SEEN_MAX_AGE_MS) return undefined
  return typeof state === 'string' && AGENT_STATES.has(state)
    ? { at, state: state as AgentState }
    : { at }
}

/** The ids whose `lastSeen` may be written: the `LAST_SEEN_MAX` newest. Pure, for the bound test. */
export function lastSeenKeep(byId: Record<string, { lastSeen?: LastSeen }>): Set<string> {
  const withClock = Object.entries(byId).filter(([, v]) => v.lastSeen)
  if (withClock.length <= LAST_SEEN_MAX) return new Set(withClock.map(([id]) => id))
  withClock.sort((a, b) => b[1].lastSeen!.at - a[1].lastSeen!.at)
  return new Set(withClock.slice(0, LAST_SEEN_MAX).map(([id]) => id))
}

const EMPTY: AgentNodeStatus = { unread: false }
/** The DEFAULT (local-core) persistence key. Only the default instance uses it. */
const KEY = 'nodeterm.agentStatus'
const LEGACY_KEY = 'nodeterm.claudeStatus'

// Claude Code runs hooks in PARALLEL, so the last PostToolUse's POST can arrive after the
// Stop's POST — hold done against any non-newTurn working for this long.
export const DONE_HOLDOFF_MS = 3000
// Last-resort net for a lost Stop POST / crashed CLI: a working entry that saw no event at
// all for this long decays to idle. Long on purpose:
// a single silent tool run (e.g. a long build) fires no hooks between Pre- and PostToolUse,
// so anything shorter would flip genuinely-running turns to idle.
// One rule, three surfaces — the window lives in shared/agents/stale.ts and the mirror's sweep is
// the decider (it fires a synthetic end edge). This local sweeper stays as the renderer's own
// safety net for a badge whose events never reached the mirror.
export const STALE_WORKING_MS = WORKING_STALE_MS
// Esc/Ctrl-C interrupt inference: how long to wait for a hook event before concluding the
// turn was cancelled without a final Stop.
export const INTERRUPT_SETTLE_MS = 1500

/** One-time localStorage migration from the old key. Runs before the default store hydrates —
 *  and ONLY for the default key: a namespaced or keyless instance must never adopt legacy data
 *  that belongs to the local core. */
function migrateLegacyKey(): void {
  try {
    if (!localStorage.getItem(KEY)) {
      const legacy = localStorage.getItem(LEGACY_KEY)
      if (legacy) localStorage.setItem(KEY, legacy)
    }
  } catch {
    /* ignore */
  }
}

/** One session's agent status: its store plus the interrupt-inference helper bound to it. */
export interface AgentStatusSession {
  store: UseBoundStore<StoreApi<AgentStatusStore>>
  /**
   * Esc/Ctrl-C interrupt inference: Claude Code fires NO hook when the user
   * cancels a turn (measured on 2.1.285), so a node interrupted mid-work would sit on "working"
   * forever. The core now ends such a turn from the transcript's interrupt marker
   * (`recordTurnInterrupt`), for every surface; this renderer-only GUESS stays because it is the
   * one thing that covers a cancel BEFORE the first token, which the CLI rewinds without writing
   * a marker at all — and it covers only keystrokes typed into THIS terminal. Called
   * from the terminal's input path on a lone Esc / Ctrl-C: wait one settle window; if the
   * node is still `working` and NOT ONE hook event arrived since the keystroke (stateAt
   * unchanged), conclude the turn was cancelled and flip it to done. A wrong guess
   * self-corrects: the next real hook event sets working again (it's past the holdoff).
   */
  inferInterruptAfterSettle(id: string, settleMs?: number): void
}

/**
 * Build the agent-status store for ONE core. `persistKey` is the localStorage key this
 * instance hydrates from and saves to; `undefined` = in-memory only (load returns nothing,
 * save is a no-op — the instance never touches localStorage). See the module docblock for
 * why only the default instance has a key today.
 *
 * The two callbacks are this store's only reports OUT, and both are injected so that only the
 * store that describes this machine's own core has them: `ackDone` (a read of a finished session,
 * see `clearUnread`) and `reportHibernated` (the SLEEPING flag, see `setHibernated`). Absent = the
 * fact stays in this store. A relay tab's store gets neither (`agentStatusForApi`).
 */
export function createAgentStatusSession(
  persistKey?: string,
  ackDone?: (nodeId: string) => void,
  reportHibernated?: (nodeId: string, on: boolean) => void
): AgentStatusSession {
  if (persistKey === KEY) migrateLegacyKey()

  function load(): Record<string, AgentNodeStatus> {
    const out = loadMain()
    if (!persistKey) return out
    // The clocks ride their own key (see `lastSeen`). Restored as a CLOCK marked `restored`, never
    // as `state` or `lastEventAt`.
    try {
      const raw = localStorage.getItem(lastSeenKey(persistKey))
      const data: unknown = raw ? JSON.parse(raw) : undefined
      if (data && typeof data === 'object' && !Array.isArray(data)) {
        const nowMs = Date.now()
        for (const [id, v] of Object.entries(data as Record<string, unknown>)) {
          const seen = readLastSeen(v, nowMs)
          if (!seen) continue
          out[id] = { ...(out[id] ?? EMPTY), lastSeen: { ...seen, restored: true } }
        }
      }
    } catch {
      /* an unreadable clock key costs the clocks, never the table */
    }
    return out
  }

  function loadMain(): Record<string, AgentNodeStatus> {
    if (!persistKey) return {}
    try {
      const raw = localStorage.getItem(persistKey)
      if (!raw) return {}
      const data = JSON.parse(raw) as Record<string, Partial<AgentNodeStatus>>
      const out: Record<string, AgentNodeStatus> = {}
      if (!data || typeof data !== 'object') return {}
      for (const [id, v] of Object.entries(data)) {
        if (!v || typeof v !== 'object') continue
        out[id] = { unread: !!v.unread, session: v.session, sessionId: v.sessionId, agentId: v.agentId }
        // Minimal shape check, like `loop` below: this file is on disk and hand-editable, and a
        // half-written entry must not put a chip on a node claiming an identity it never had.
        if (
          v.account &&
          typeof v.account === 'object' &&
          typeof v.account.configDir === 'string' &&
          typeof v.account.known === 'boolean'
        ) {
          out[id].account = {
            configDir: v.account.configDir,
            accountId: typeof v.account.accountId === 'string' ? v.account.accountId : null,
            known: v.account.known,
            // `remote` MUST round-trip. This loader rebuilds the object field by field, so a field
            // it forgets is silently dropped — and for this one the dropped value reads as LOCAL,
            // which puts a Link button back on an SSH host's config dir at the first reload and
            // matches it against local accounts again. The absent-is-local default is only correct
            // for an entry written before the field existed, where nothing remote was ever
            // recorded; a `false` is not stored, so those entries hydrate byte-identically.
            ...(v.account.remote ? { remote: true } : {})
          }
        }
        // Only when set: an absent flag stays absent, so an entry saved before this field
        // existed hydrates byte-identically (and `hibernated: false` never grows in the file).
        if (v.hibernated) out[id].hibernated = true
        // Alongside EITHER flag: `hibernated` is the ordinary case (the pane we exited TO), but a
        // `paused` node with `hibernated` unset needs it just as much — the deep "pause & end
        // session" choice, and a shallow pause whose tmux session died in a reboot (`fresh` clears
        // `hibernated` but not `paused`), both leave the wake with a brand-new pane to recognize,
        // and this is the only record of what that pane turned out to be (see the cold-restore
        // gate in TerminalNode.tsx). Meaningless (and, as a wake permission, unwanted) once
        // NEITHER flag holds.
        if (v.hibernated || v.paused) {
          // Shape-checked, not trusted: localStorage is hand-editable, and this record is what
          // authorises a write into a pane. A partial or mistyped one is dropped entirely (⇒ the
          // wake's `'no-proof'` refusal), never half-applied — the same rule the `loop` entry
          // below follows, for a much cheaper mistake.
          const c = v.hibernatedContext
          if (c && typeof c.command === 'string' && typeof c.panePid === 'number' && c.panePid > 0)
            out[id].hibernatedContext = {
              command: c.command,
              panePid: c.panePid,
              paneId: typeof c.paneId === 'string' ? c.paneId : undefined
            }
        }
        // Independent of `hibernated`: the deep "pause & end session" choice recycles the tmux
        // session, so a paused node can perfectly well hydrate with `hibernated` unset.
        if (v.paused) out[id].paused = true
        // A recurring job (cron/schedule — and tmux keeps in-session loops alive too) outlives
        // the app: restore its card. Minimal shape check so a corrupt entry can't break load.
        if (v.loop && typeof v.loop === 'object' && v.loop.kind) {
          out[id].loop = {
            count: v.loop.count ?? 0,
            kind: v.loop.kind,
            schedule: v.loop.schedule,
            task: v.loop.task,
            items: Array.isArray(v.loop.items) ? v.loop.items : []
          }
          // A dismissed card must STAY dismissed across a restart — and the fact it hides
          // (a live cron/schedule job) must stay readable to the hibernation guard.
          if (v.loop.dismissed) out[id].loop.dismissed = true
        }
      }
      return out
    } catch {
      return {}
    }
  }

  // Persist only the durable fields (not the live `state`).
  function save(byId: Record<string, AgentNodeStatus>): void {
    if (!persistKey) return
    try {
      const out: Record<string, Partial<AgentNodeStatus>> = {}
      for (const [id, v] of Object.entries(byId)) {
        if (
          v.unread ||
          v.session ||
          v.sessionId ||
          v.loop ||
          v.agentId ||
          v.account ||
          v.hibernated ||
          v.paused
        ) {
          out[id] = {
            unread: v.unread,
            session: v.session,
            sessionId: v.sessionId,
            agentId: v.agentId,
            // Durable beside `agentId`, and for the same reason (see the field comment): a plain
            // terminal's observed account exists nowhere else, and the tmux session that knows it
            // outlives the app.
            account: v.account,
            loop: v.loop,
            hibernated: v.hibernated,
            // Never written without a flag it belongs to (see `hibernatedContext`'s load comment).
            hibernatedContext: v.hibernated || v.paused ? v.hibernatedContext : undefined,
            paused: v.paused
          }
        }
      }
      localStorage.setItem(persistKey, JSON.stringify(out))
    } catch {
      // ignore quota / serialization errors
    }
  }

  // The clock key (see `lastSeen`): its own small record, so a hook event never rewrites the main
  // table (which carries loop items and is shared, per key, by every Server Edition tab).
  function saveClocks(byId: Record<string, AgentNodeStatus>): void {
    cancelClockSave()
    if (!persistKey) return
    try {
      const out: Record<string, { at: number; state?: AgentState }> = {}
      // A fresh object of exactly the two fields: `restored` and anything else never ride out.
      for (const id of lastSeenKeep(byId)) {
        const c = byId[id].lastSeen!
        out[id] = c.state ? { at: c.at, state: c.state } : { at: c.at }
      }
      localStorage.setItem(lastSeenKey(persistKey), JSON.stringify(out))
    } catch {
      // ignore quota / serialization errors
    }
  }
  // A TRAILING debounce with a max wait: each event pushes the write back by the debounce window,
  // but never past `LAST_SEEN_SAVE_MAX_WAIT_MS` after the first unsaved event.
  let clockSaveTimer: ReturnType<typeof setTimeout> | undefined
  let clockDirtySince: number | undefined
  function cancelClockSave(): void {
    if (clockSaveTimer !== undefined) clearTimeout(clockSaveTimer)
    clockSaveTimer = undefined
    clockDirtySince = undefined
  }
  function scheduleClockSave(): void {
    if (!persistKey) return
    const now = Date.now()
    if (clockDirtySince === undefined) clockDirtySince = now
    if (clockSaveTimer !== undefined) clearTimeout(clockSaveTimer)
    const wait = Math.max(
      0,
      Math.min(LAST_SEEN_SAVE_DEBOUNCE_MS, clockDirtySince + LAST_SEEN_SAVE_MAX_WAIT_MS - now)
    )
    clockSaveTimer = setTimeout(() => saveClocks(store.getState().byId), wait)
  }
  // A quit/reload inside the debounce window must not lose the newest clock.
  if (persistKey && typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
    window.addEventListener('pagehide', () => {
      if (clockSaveTimer !== undefined) saveClocks(store.getState().byId)
    })
  }

  // `onHookEvent` listeners, per node id. Outside zustand on purpose (see the interface).
  const hookEventSubs = new Map<string, Set<() => void>>()
  const pulse = (id: string): void => {
    const subs = hookEventSubs.get(id)
    if (!subs) return
    for (const cb of [...subs]) {
      // Runs inside Canvas's hook-event handler, after the store write: one throwing listener must
      // neither abort that handler nor starve the listeners after it.
      try {
        cb()
      } catch (e) {
        console.warn('[agentStatus] onHookEvent listener threw', e)
      }
    }
  }

  const store = create<AgentStatusStore>((set) => ({
    byId: load(),
    activeId: null,

    onHookEvent: (id, cb) => {
      let subs = hookEventSubs.get(id)
      if (!subs) hookEventSubs.set(id, (subs = new Set()))
      subs.add(cb)
      return () => {
        subs.delete(cb)
        if (subs.size === 0 && hookEventSubs.get(id) === subs) hookEventSubs.delete(id)
      }
    },

    setActive: (id, active) =>
      set((s) => {
        if (active) return s.activeId === id ? s : { activeId: id }
        return s.activeId === id ? { activeId: null } : s
      }),

    setState: (id, state, agentId, newTurn, pendingId, verified, errored, held, interrupted) => {
      set((s) => {
        const prev = s.byId[id] ?? EMPTY
        const now = Date.now()
        // Does this event change the last-turn verdict (issue #521)? Read up front because the
        // same-state fast path below mutates IN PLACE to avoid a re-render — which is exactly what
        // a badge appearing or disappearing needs, so an event that moves this must not take it.
        const turnErrorMoves =
          errored === true || (newTurn === true && prev.lastTurnError !== undefined)
        // The interrupt verdict moves on the same kinds of edge (see `lastTurnInterrupted`).
        const interruptNext = interruptVerdict(prev.lastTurnInterrupted, state, newTurn, interrupted)
        const turnInterruptMoves = (interruptNext === undefined) !== (prev.lastTurnInterrupted === undefined)
        // Done-holdoff: a late working event (parallel hook curls arrive out of order, or a
        // tool POST that was in flight when the user interrupted) must not resurrect a turn
        // that just finished. Only a genuine new turn (UserPromptSubmit) may.
        if (
          state === 'working' &&
          !newTurn &&
          prev.state === 'done' &&
          now - (prev.stateAt ?? 0) < DONE_HOLDOFF_MS
        ) {
          return s
        }
        // A re-asserted `blocked` carrying a NEW pendingId (Claude re-asks) must break the fast
        // path so the header buttons retarget the new answer file — otherwise treat same-state as
        // a freshness-only refresh.
        const samePendingWhileBlocked =
          state !== 'blocked' || (pendingId ?? prev.pendingId) === prev.pendingId
        // Same for a NEW held request (a held picker re-asserts `waiting`, where pendingId is absent).
        const needsYou = state === 'blocked' || state === 'waiting'
        const sameHeld = !needsYou || !held || held.pendingId === prev.held?.pendingId
        if (
          prev.state === state &&
          (agentId === undefined || prev.agentId === agentId) &&
          samePendingWhileBlocked &&
          sameHeld &&
          !turnErrorMoves &&
          !turnInterruptMoves
        ) {
          // Same-state event: refresh freshness in place — stateAt is never rendered, and a
          // new object here would re-render every node header on each tool event.
          // OWN entries only: for an id with no entry of its own, a plain lookup of a name
          // `Object.prototype` owns (`__proto__`, `constructor`, …) answers the prototype's value,
          // and the in-place writes below would then land on `Object.prototype` (or `Object`) for
          // the whole renderer. A relay host's ids are refused before they get here
          // (`isHostNodeId`); this is the store's own guard, and for every real id it is the same
          // lookup as before.
          const own = Object.hasOwn(s.byId, id) ? s.byId[id] : undefined
          if (own?.lastSeen?.restored) {
            // The FIRST event after a restart for a node whose state is still unknown (a
            // SessionStart from a cold-restore resume, say) is same-state by construction. Not in
            // place: the row must lose its "restored" label and re-sort NOW, not whenever another
            // node's event happens to replace `byId`. The idle clock is deliberately left unset —
            // an unknown state is not an idle one.
            scheduleClockSave()
            return {
              byId: {
                ...s.byId,
                [id]: { ...own, stateAt: now, stateVerified: verified === true, lastSeen: { at: now, state } }
              }
            }
          }
          if (own) {
            own.stateAt = now
            // "Last seen" is the last hook EVENT, so a same-state one moves it too — in place, like
            // `stateAt`, and saved on the trailing debounce rather than once per tool event.
            own.lastSeen = { at: now, state }
            scheduleClockSave()
            // The evidence rides along, in place and for the same reason: a re-assert of the SAME
            // state by a legacy POST must not leave an earlier `true` standing, or this copy would
            // disagree with the mirror the gate actually reads.
            own.stateVerified = verified === true
          }
          return s
        }
        // The ONE place a state transition is recorded, so it is also the one place the idle
        // clock is stamped (the same-state fast path above deliberately does not touch it —
        // see `lastEventAt`).
        const next = { ...prev, state, stateAt: now, lastEventAt: now, lastSeen: { at: now, state } }
        // Written on the same edge the state is — the evidence describes THIS transition, and an
        // absent argument is not evidence.
        next.stateVerified = verified === true
        if (agentId !== undefined) next.agentId = agentId
        // Retain the approval ticket only while blocked; any other state clears it (transient).
        next.pendingId = state === 'blocked' ? (pendingId ?? prev.pendingId) : undefined
        // The held request rides both needs-you states (see `held`); anything else ends the hold.
        next.held = needsYou ? (held ?? prev.held) : undefined
        // The last-turn verdict (issue #521). A genuine new turn retires it — the station is being
        // asked something else, and the old failure no longer describes what it is doing. Anything
        // else LEAVES IT STANDING (it rides the spread): the intermediate transitions between the
        // error and the next prompt say nothing about whether that turn produced anything.
        if (newTurn) next.lastTurnError = undefined
        else if (errored) next.lastTurnError = { at: now }
        next.lastTurnInterrupted = interruptNext === 'set' ? { at: now } : interruptNext
        // A LIVE state is proof the CLI is running, so the hibernated flag is simply wrong and is
        // dropped here — the one self-heal this flag has. It is set by a controller that watched
        // the CLI let go of the pane, but the world moves on without us: the user relaunches the
        // agent by hand, a wake lands and its `--resume` starts reporting, or a resume we could
        // not confirm turns out to have worked. Left standing, the flag is not cosmetic: it
        // renders RUNNING and SLEEPING side by side, and (because a hibernated node is skipped by
        // the sweep) exempts that session from Eco for good.
        // `done` deliberately does NOT clear it — a hibernated node's last known state IS done,
        // and a late Stop POST arriving after the exit would undo the hibernation we just did.
        //
        // ---- a different field, and the opposite rule ----
        //
        // The BACKGROUND-TASK guard is dropped at the START OF THE NEXT TURN — `done` → `working`,
        // and nothing else.
        //
        // Not on `done` itself: that is the launching turn ending while the task runs on, which is
        // precisely the window Eco / the bulk restart would kill it in. A turn start is safe
        // because Claude delivers a finished background task back as a <task-notification>, whose
        // own turn is exactly this `working` — so by the time one begins, the task has reported.
        //
        // Not on EVERY `working` transition either, because `blocked`/`waiting` → `working` is a
        // MID-TURN RESUMPTION. A background Bash whose command needs approval runs
        // UserPromptSubmit(working) → PreToolUse(stamp) → PermissionRequest(blocked) → approve →
        // PostToolUse(working): that last edge would clear the stamp milliseconds after it was
        // set, for exactly the task this guard exists for.
        //
        // And NOT from an unknown previous state, which is the same hole from the other side:
        // `undefined` is reachable MID-TURN — a renderer reload starts with an empty table, and
        // `sweepStaleWorking` blanks a working entry after the stale window — so post-reload a
        // background launch would stamp an entry with no state, and the very next tool event's
        // `working` would read as a turn start and delete it. Requiring `done` makes the miss
        // fail SAFE: every real turn ends Stop → `done`, so the clear still happens, at most one
        // turn late.
        //
        // Deliberately NOT keyed on `newTurn`: the <task-notification> prompt is explicitly not
        // flagged as one (see normalizeClaude), so the intended clear would never fire.
        if (state === 'working' && prev.state === 'done') next.backgroundTaskAt = undefined
        const alive = state === 'working' || state === 'blocked' || state === 'waiting'
        if (alive && prev.hibernated) {
          next.hibernated = undefined
          next.hibernatedContext = undefined // goes with the flag, always
        }
        // Same self-heal, same reasoning: a live hook event is proof the CLI is running, whatever
        // brought it back (our own resume, or the user typing the launch line by hand) — a standing
        // `paused` would be wrong, and (unlike a cold restart) this IS evidence, not a guess.
        if (alive && prev.paused) {
          next.paused = undefined
          // Goes with the flag, UNLESS `hibernated` still owns it (shallow pause clears both flags
          // together above, in which case this is already undefined) — the deep-pause case has no
          // `hibernated` to protect it, so without this an in-memory record describing a pane that
          // is now demonstrably running something else would linger, and stand as permission for
          // the next deep pause to be typed into recognizing a pane it never measured.
          if (!next.hibernated) next.hibernatedContext = undefined
        }
        // A hook event of ANY kind — `done` included — is the CLI reporting from inside the pane,
        // which is exactly the fact both of these withdraw. `paneUnverified` said "no agent is in
        // this pane"; a hook event says otherwise, and without this the node would stay out of the
        // sweep's plan for the rest of the run. `wakeBlocked` described a refusal that is now moot.
        // Gated on neither `alive` nor `newTurn`: a `done` POST still comes from a live CLI.
        if (prev.paneUnverified) next.paneUnverified = undefined
        if (prev.wakeBlocked) next.wakeBlocked = undefined
        // A hook event of ANY kind is proof the CLI is alive — it is the CLI that fired it — so a
        // standing DROPPED verdict is withdrawn here, `done` included. That is the one self-heal
        // above which deliberately does NOT gate on `alive`: `done` must not clear `hibernated`
        // (a late Stop POST would undo a hibernation we just performed), but it absolutely does
        // disprove "this pane has no CLI in it". Nothing is saved — the flag is transient.
        if (prev.dropped) next.dropped = undefined
        // Same reasoning: a state transition is fired by a live CLI, so "it exited" no longer holds.
        if (prev.sessionEnded) next.sessionEnded = undefined
        const byId = { ...s.byId, [id]: next }
        // `state` itself is transient, so a plain transition writes nothing — but dropping a
        // PERSISTED flag has to reach disk, or a relaunch would restore a hibernated/paused node
        // that has been demonstrably running since.
        if (alive && (prev.hibernated || prev.paused)) save(byId)
        scheduleClockSave()
        return { byId }
      })
      // After the set: a listener reads the store and must see this event applied.
      pulse(id)
    },

    sweepStaleWorking: (staleMs = STALE_WORKING_MS) =>
      set((s) => {
        const now = Date.now()
        let changed = false
        const byId = { ...s.byId }
        for (const [id, v] of Object.entries(byId)) {
          if (v.state === 'working' && now - (v.stateAt ?? 0) > staleMs) {
            // This is a real transition to Unknown, even though it did not arrive through a hook.
            // Stamp both clocks so the sidebar age and Eco idle clock begin at the transition.
            byId[id] = { ...v, state: undefined, stateAt: now, lastEventAt: now }
            changed = true
          }
        }
        return changed ? { byId } : s
      }),

    setSession: (id, session) =>
      set((s) => {
        const prev = s.byId[id] ?? EMPTY
        if (prev.session === session) return s
        const byId = { ...s.byId, [id]: { ...prev, session } }
        save(byId)
        return { byId }
      }),

    setSessionId: (id, sessionId) =>
      set((s) => {
        const prev = s.byId[id] ?? EMPTY
        if (prev.sessionId === sessionId) return s
        const byId = { ...s.byId, [id]: { ...prev, sessionId } }
        save(byId)
        return { byId }
      }),

    setAccount: (id, account) =>
      set((s) => {
        const prev = s.byId[id] ?? EMPTY
        const cur = prev.account
        // Same-account events are the common case (every hook POST of every turn carries one), so
        // bail before allocating: a new object here would re-render every consumer of this node's
        // status on each tool event, for a value that did not change.
        if (
          cur &&
          cur.configDir === account.configDir &&
          cur.accountId === account.accountId &&
          cur.known === account.known
        ) {
          return s
        }
        const byId = { ...s.byId, [id]: { ...prev, account } }
        save(byId)
        return { byId }
      }),

    setHibernated: (id, on) =>
      set((s) => {
        const prev = s.byId[id] ?? EMPTY
        if (!!prev.hibernated === on) return s
        // The renderer owns this flag; the core only mirrors it (agent-status mirror → SLEEPING on
        // the phone). Reported on the same edge the store changes, through the injected callback:
        // only the default store has one, because only its node ids are this desktop's own. A relay
        // tab's pause reported here put the HOST's node id into THIS desktop's mirror, where a
        // hibernated entry never expires and survives a restart, and nothing ever reported it
        // false. Guarded because tests (and any non-preload context) run this store without a
        // bridge.
        try {
          reportHibernated?.(id, on)
        } catch {
          /* the mirror is a side-channel; a failed report must never break the store */
        }
        // Cleared by dropping the key, not by storing `false`: `save` skips entries that carry
        // nothing durable, so a woken node leaves no residue behind in localStorage.
        // The recorded pane belongs to THIS hibernation: it goes with the flag, in both
        // directions. Kept past a wake it would be a standing permission to type into whatever
        // that string names, long after we measured it.
        const next: AgentNodeStatus = {
          ...prev,
          hibernated: on ? true : undefined,
          // Hibernating KEEPS what the exit closure just recorded; waking drops it.
          hibernatedContext: on ? prev.hibernatedContext : undefined,
          // A wake that succeeded answers whatever the last refusal said.
          wakeBlocked: on ? prev.wakeBlocked : undefined
        }
        // Waking RESTARTS the idle clock. Without this, a node whose conversation was resumed but
        // whose CLI then sits quiet (an agent that fires no hook until you talk to it) still
        // carries the `lastEventAt` from before it was hibernated — hours old — so the very next
        // sweep, 60 s later, would quit the session the user just came back to. Hibernating does
        // not touch the clock: nothing happened in that session, and the flag itself is what keeps
        // the sweep off it.
        if (!on) next.lastEventAt = Date.now()
        const byId = { ...s.byId, [id]: next }
        save(byId)
        return { byId }
      }),

    setHibernatedContext: (id, ctx) =>
      set((s) => {
        const prev = s.byId[id] ?? EMPTY
        const next = ctx ?? undefined
        // Value equality, not identity: the caller builds a fresh object from every pane read, and
        // an identity compare would write (and persist) on each one.
        if (
          prev.hibernatedContext?.command === next?.command &&
          prev.hibernatedContext?.panePid === next?.panePid &&
          prev.hibernatedContext?.paneId === next?.paneId
        )
          return s
        const byId = { ...s.byId, [id]: { ...prev, hibernatedContext: next } }
        save(byId)
        return { byId }
      }),

    setPaneUnverified: (id, on) =>
      set((s) => {
        const prev = s.byId[id] ?? EMPTY
        const next = on ? true : undefined
        if (prev.paneUnverified === next) return s
        // Transient: no `save`. It describes this run's reading of a live pane, and a persisted
        // copy would keep a node out of the sweep across a restart on evidence nobody re-took.
        return { byId: { ...s.byId, [id]: { ...prev, paneUnverified: next } } }
      }),

    setWakeBlocked: (id, reason) =>
      set((s) => {
        const prev = s.byId[id] ?? EMPTY
        const next = reason ?? undefined
        if (prev.wakeBlocked === next) return s
        return { byId: { ...s.byId, [id]: { ...prev, wakeBlocked: next } } }
      }),

    setPaused: (id, on) =>
      set((s) => {
        const prev = s.byId[id] ?? EMPTY
        if (!!prev.paused === on) return s
        // Cleared by dropping the key, not by storing `false` — same reasoning as `setHibernated`:
        // `save` skips entries with nothing durable, so a resumed node leaves no residue.
        const next: AgentNodeStatus = { ...prev, paused: on ? true : undefined }
        // Resuming restarts the idle clock — a session that sat paused for hours must not read as
        // having been idle that whole time on the very next Eco sweep.
        if (!on) {
          next.lastEventAt = Date.now()
          // Drop the recorded pane too, UNLESS `hibernated` still owns it (a resume normally clears
          // both flags together, in which case `setHibernated(id, false)` already dropped this —
          // but `setPaused` must be correct standing alone, for the deep-pause case where
          // `hibernated` was never set and this is the only owner).
          if (!prev.hibernated) next.hibernatedContext = undefined
          next.wakeBlocked = undefined
        }
        const byId = { ...s.byId, [id]: next }
        save(byId)
        return { byId }
      }),

    setDropped: (id, on) =>
      set((s) => {
        const prev = s.byId[id] ?? EMPTY
        // Bail when nothing changes: the liveness check re-asks on every reveal and on a timer, so
        // the overwhelmingly common call is "still fine, still fine" — and a fresh entry object
        // each time would re-render the node (and the minimap) for no news.
        if (!!prev.dropped === on) return s
        // Transient: cleared by dropping the key, and NO `save()` — see the field comment. An entry
        // holding nothing else durable must not be conjured onto disk by a pane reading.
        return { byId: { ...s.byId, [id]: { ...prev, dropped: on ? true : undefined } } }
      }),

    setSessionEnded: (id, on) =>
      set((s) => {
        const prev = s.byId[id] ?? EMPTY
        if (!!prev.sessionEnded === on) return s
        // Transient, no `save()`: see the field comment.
        return { byId: { ...s.byId, [id]: { ...prev, sessionEnded: on ? true : undefined } } }
      }),

    markBackgroundTask: (id) =>
      set((s) => {
        const prev = s.byId[id] ?? EMPTY
        // Transient (see `backgroundTaskAt`) — no save(): a stamp restored from disk would exempt
        // the node from Eco forever.
        return { byId: { ...s.byId, [id]: { ...prev, backgroundTaskAt: Date.now() } } }
      }),

    markUnread: (id) =>
      set((s) => {
        const prev = s.byId[id] ?? EMPTY
        if (prev.unread) return s
        const byId = { ...s.byId, [id]: { ...prev, unread: true } }
        save(byId)
        return { byId }
      }),

    clearUnread: (id, opts) =>
      set((s) => {
        const prev = s.byId[id]
        if (!prev) return s
        // Cross-surface ACK: opening a session marks its finish read EVERYWHERE — the notch
        // capsule's green blob, the paired phone's lingering DONE Live Activity, and its Inbox
        // Finished card (all via the core mirror's `ackDone`). This is READ state only: the live
        // workflow state remains `done` until a genuine new turn begins.
        //
        // Deliberately gated on NOTHING but the external flag:
        //  - not on the unread flag, because a session you were LOOKING at when it finished never
        //    got marked unread (the `watching` gate in Canvas), so opening it is the only local
        //    read signal there will ever be;
        //  - not on the node's current state, because a node whose PREVIOUS turn finished while a
        //    new one is already running left the phone showing a Finished card for a result the
        //    user had open on screen.
        // `ackDone` is a no-op when the node has no unresolved done event, and it only ever
        // resolves `done` events — a live approval/question card is untouched.
        //
        // SUPPRESSED for an `external` clear — one the host drove FROM a phone read-ack it swept
        // (`agent:unread-clear`): re-acking would loop host→renderer→ackDone straight back.
        if (!opts?.external) ackDone?.(id)
        if (!prev.unread) return s
        const byId = { ...s.byId, [id]: { ...prev, unread: false } }
        save(byId)
        return { byId }
      }),

    setLoop: (id, active, kind = 'loop', opts) =>
      set((s) => {
        const prev = s.byId[id] ?? EMPTY
        if (active) {
          const byId = {
            ...s.byId,
            [id]: {
              ...prev,
              loop: { count: 0, kind, schedule: opts?.schedule, task: opts?.task, items: [] }
            }
          }
          save(byId)
          return { byId }
        }
        if (!prev.loop) return s
        const { loop: _drop, ...rest } = prev
        const byId = { ...s.byId, [id]: rest }
        save(byId)
        return { byId }
      }),

    dismissLoopCard: (id) =>
      set((s) => {
        const prev = s.byId[id]
        if (!prev?.loop || prev.loop.dismissed) return s
        const byId = { ...s.byId, [id]: { ...prev, loop: { ...prev.loop, dismissed: true } } }
        save(byId)
        return { byId }
      }),

    bumpLoop: (id, message) =>
      set((s) => {
        const prev = s.byId[id]
        // Only count in-session /loop turns; /schedule and /cron run in the background.
        if (!prev?.loop || prev.loop.kind !== 'loop') return s
        const items = message
          ? [...prev.loop.items, message.trim().slice(0, 4000)].slice(-100)
          : prev.loop.items
        const byId = {
          ...s.byId,
          [id]: { ...prev, loop: { ...prev.loop, count: prev.loop.count + 1, items } }
        }
        save(byId)
        return { byId }
      }),

    remove: (id) =>
      set((s) => {
        if (!(id in s.byId)) return s
        const byId = { ...s.byId }
        delete byId[id]
        save(byId)
        // Now, not on the debounce: the deleted node's clock must not outlive it on disk.
        if (s.byId[id].lastSeen) saveClocks(byId)
        return { byId }
      }),

    removeMany: (ids) =>
      set((s) => {
        const present = ids.filter((id) => id in s.byId)
        if (present.length === 0) return s
        const byId = { ...s.byId }
        let clocks = false
        for (const id of present) {
          if (byId[id].lastSeen) clocks = true
          delete byId[id]
        }
        save(byId)
        if (clocks) saveClocks(byId)
        return { byId }
      })
  }))

  function inferInterruptAfterSettle(id: string, settleMs = INTERRUPT_SETTLE_MS): void {
    const st = store.getState().byId[id]
    if (st?.state !== 'working') return
    const baseline = st.stateAt
    setTimeout(() => {
      const cur = store.getState()
      const now = cur.byId[id]
      if (now?.state === 'working' && now.stateAt === baseline) {
        // Recorded as an INTERRUPTED done, like the transcript marker the core reads a moment
        // later (`recordTurnInterrupt`): a guess that released `--after` dependents would race
        // the authoritative signal and could start them on unfinished work. A wrong guess heals —
        // the turn's next hook puts it back to working and its normal `done` clears the verdict.
        cur.setState(id, 'done', now.agentId, undefined, undefined, undefined, undefined, undefined, true)
      }
    }, settleMs)
  }

  return { store, inferInterruptAfterSettle }
}

/** One instance per api OBJECT — the one-store-per-core guarantee, keyed on identity exactly
 *  like presence's (a WeakMap, so a dropped api never pins its store). Seeded below with
 *  `window.nodeTerminal → defaultAgentStatus`. */
const instanceByApi = new WeakMap<NodeTerminalApi, AgentStatusSession>()

/**
 * The agent-status store for ONE core (one api). MEMOIZED BY API IDENTITY: the session
 * registry resolves its store here, so ANY session handed the local api — the local session
 * itself, a loopback debug session, a test double — shares the default (persisted) instance
 * rather than growing a parallel table the canvas listener isn't driving. A DIFFERENT api (a
 * different core, a different node-id space) gets a fresh KEYLESS instance: a remote core's
 * status must never clobber the local user's persisted unread/session under `KEY` (see the
 * module docblock). A nullish api (node-environment tests) is not memoizable and gets a
 * fresh inert instance.
 */
export function agentStatusForApi(api: NodeTerminalApi): AgentStatusSession {
  const existing = api ? instanceByApi.get(api) : undefined
  if (existing) return existing
  // Keyless — remote status is never persisted (4a) — and with NO done-read ack: reading a remote
  // session's finish clears unread on this desktop only (product decision 1). Nothing is sent back
  // to that core (no `ackDone`, no `agent:ack-done`), so the host's own read state — its notch,
  // its paired phone's Live Activity — stays as it was. And with NO hibernated report: a pause
  // made on a team tab is this desktop's own view of the host's node. It is not the host's fact
  // (v1 never tells the host), and it is not this desktop's either — its mirror (and the phone
  // that reads it) describes this machine's nodes, and the host's node id has no place there.
  const session = createAgentStatusSession(undefined, undefined, undefined)
  if (api) instanceByApi.set(api, session)
  return session
}

/**
 * The DEFAULT instance — the local core's agent status, persisted under the historical key
 * (with the one-time legacy-key migration). Every historical export below resolves to this
 * exact object, so the existing single-session consumers are untouched. Seeding the WeakMap
 * with `window.nodeTerminal` (safe at module load for the boot-order reason documented in
 * localSession.ts; the `typeof window` guard covers node-environment tests) is what makes
 * `agentStatusForApi(window.nodeTerminal)` — the session registry's local session — resolve
 * here, never to a parallel twin.
 */
// The default (local core) acks the finished-session read to `window.nodeTerminal.ackDone` — guarded
// for node-environment tests where no preload exists (the callback is invoked later, at clear time).
const defaultAgentStatus = createAgentStatusSession(
  KEY,
  (id) => {
    if (typeof window !== 'undefined') window.nodeTerminal?.ackDone?.(id)
  },
  // The SLEEPING flag, to this desktop's own mirror. Read at report time, like the ack: `window`
  // has no bridge in node-environment tests, and the store's own try/catch keeps a throwing one
  // from breaking the write.
  (id, on) => {
    if (typeof window !== 'undefined') window.nodeTerminal?.reportHibernated?.(id, on)
  }
)
export { defaultAgentStatus }
if (typeof window !== 'undefined' && window.nodeTerminal) {
  instanceByApi.set(window.nodeTerminal as NodeTerminalApi, defaultAgentStatus)
}

export const useAgentStatus = defaultAgentStatus.store
export const inferInterruptAfterSettle = defaultAgentStatus.inferInterruptAfterSettle