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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import { subagentReplay } from './subagent-replay'
import fs from 'fs'
import path from 'path'
import { writeFileAtomic } from './fs-atomic'
import { platform } from './platform'
import type { AgentId } from '@shared/agents/config'
import type { AgentState, NormalizedAgentEvent } from '@shared/agents/normalize'
import type { ObservedClaudeAccount } from '@shared/types'
import { WORKING_STALE_MS, isStaleWorking } from '@shared/agents/stale'
import { parseIdentitySeed } from '@shared/agent-identity-seed'
/**
* Mirrors the live per-node agent status to a small JSON file so an EXTERNAL reader (the
* nodeterm mobile host agent) can render running/waiting/blocked/done badges without an IPC
* connection into the renderer. This is a READ-ONLY side-channel: it never feeds back into the
* app and never changes renderer behavior.
*
* The reduction here intentionally mirrors the renderer store `state/agentStatus.ts` for the
* MAIN state only:
* - only `kind:'state'` events (which carry a `state`) move the working/waiting/blocked/done
* state, guarded by the same done-holdoff (a late, non-newTurn `working` must not resurrect a
* turn that just finished);
* - `kind:'session'` (start/end) resets the node to idle (state cleared), like the renderer's
* `setState(id, undefined)`;
* - `subagent-start` / `subagent-end` / `recurring` events do NOT touch the main state — they
* only capture identity (agentId / sessionId), exactly as the renderer routes them to the
* subagent / loop stores instead of `setState`.
* `sessionId`/`agentId` are captured off any event (the renderer calls `setSessionId` on every
* event and threads `agentId` through `setState`).
*/
// Keep in sync with the renderer store's DONE_HOLDOFF_MS: Claude runs hooks in parallel, so a
// late PostToolUse `working` POST can arrive after the `Stop` `done`. Hold `done` against any
// non-newTurn `working` for this long.
export const DONE_HOLDOFF_MS = 3000
// Drop a node's STATE once it hasn't been refreshed in this long, so the file can't advertise a
// stale "working" from a crashed/abandoned session. The node's IDENTITY (agentId/sessionId/
// account/name) outlives it — see IDENTITY_EXPIRE_MS.
export const EXPIRE_MS = 6 * 60 * 60_000
/**
* How long an entry whose state has expired is kept as an IDENTITY-ONLY entry (no `state`, nothing
* state-derived). EXPIRE_MS is about the state, and dropping the whole entry with it was a
* device-measured bug: the phone's chat view finds a node's transcript ONLY through the `sessionId`
* it reads here, so a conversation typed in the terminal and left idle overnight opened on the
* phone as "No conversation yet" until the next prompt fired a hook.
*
* Measured from `updatedAt` (the last STATE commit), deliberately not from the last time an id was
* seen: a node's session id only changes across a session boundary, and every boundary commits a
* state, so "30 days since the node last did anything" is the same clock. Identity-only entries are
* also dropped as soon as their node is known to be gone (`setMirrorLiveNodesProvider`); this TTL
* is the bound when that cannot be known (a folder project that is unavailable, an SSH project
* never connected).
*/
export const IDENTITY_EXPIRE_MS = 30 * 24 * 60 * 60_000
// Coalesce bursty hook POSTs (a single turn fires many tool events) into one disk write.
export const WRITE_DEBOUNCE_MS = 300
export interface MirrorEntry {
/** Tickets introduced concurrently with a picker, retained until reply or explicit reset. */
concurrentApprovalIds?: string[]
/** Live question identity, independent of the short-lived display stash. */
pendingQuestion?: { sessionId: string; toolUseId: string }
/** working/waiting/blocked/done; undefined = idle/unknown (e.g. after a session reset). */
state?: AgentState
agentId?: AgentId
sessionId?: string
/**
* Which Claude account this node was OBSERVED running under (`NormalizedAgentEvent.account`,
* derived by the hook server from the payload's `transcript_path` — see `ObservedClaudeAccount`).
*
* Captured off ANY event, exactly like `agentId`/`sessionId`, and for a sharper reason than
* either: for a hand-launched `claude` in a plain terminal the node's `data.accountId` is
* undefined forever, so this label is the ONLY record of which identity the pane is on. It rides
* the mirror file so a reader with no canvas (the phone) can render the same account chip.
*
* A LABEL, like `stateVerified` is not: nothing may gate on it.
*/
account?: ObservedClaudeAccount
/** The agent's own session name (the `/rename` name, read from its transcript) — published by
* the session-name sweep so a reader with no canvas (the phone) sees the CURRENT name, not
* whatever the node title was when it was last open. Absent until resolved. */
name?: string
/**
* When the state was last asserted (freshness). Drives the done-holdoff and the expiry
* sweep — refreshed by every state/session reduction (incl. same-state working from tool
* events), left alone by identity-only (subagent/recurring) events and holdoff-ignored ones.
*/
updatedAt: number
/** An unanswered Codex `request_user_input` is pending on this node: its turn-end `done`
* must be held as `waiting` (see reduceEntry). Cleared by anything that supersedes the
* ask — a new turn, other tool activity, an interrupt, or a session boundary. */
awaitingInput?: boolean
/**
* Did the hook POST that set the CURRENT `state` present a per-node token this instance minted
* for this node id? Set from `ev.verified` (hook-server.ts), which is a LABEL on the wire and
* must stay one for every other consumer — invariant 2 says /hook/* accepts a tokenless POST
* forever, and `normalize.ts` says outright that no consumer may treat it as reject.
*
* Messaging is the ONE consumer that reads it, and it reads it as a GATE rather than a filter:
* gate 2 admits a target as idle only on a verified `done`, because a gate whose input an
* attacker writes is a comment. Nothing else in the product may start branching on this field
* without re-reading Decision A1 of the messaging design.
*
* `false` after a `true` is meaningful and is written: a legacy event SUPERSEDES an earlier proof
* about a state that has since changed.
*/
stateVerified?: boolean
/**
* The revision of the managed hook script that posted the event behind the current `state`
* (`ev.clientRevision`). `undefined` = no stamp, which is what a script predating per-node
* identity sends — and the ONLY thing that separates "this session cannot read a token" from
* "there is no token for it to read". Those need opposite advice, and before the stamp existed
* they were byte-identical on the wire (Finding F2).
*
* Written on the same edge as `stateVerified` and, like it, moves DOWN as readily as up: an SSH
* project reconnected against an older desktop really is running an older script now.
*/
clientRevision?: number
/** When proof was last seen at all. Never cleared by a later legacy event — "we once saw this
* node prove itself" stays true, and it is what separates a node that CAN verify (retryable)
* from one that never has (not retryable). See the plan's Correction C1 mitigation. */
verifiedAt?: number
/**
* This entry's `state` came off disk at boot, not off a hook event this run. The mirror restores
* with a 6 h expiry and never pushes the restored copy to a listener — it is 6-hour-old evidence
* about a pane that has since done anything at all, including being replaced.
*
* Gate 2 refuses it outright (`targetNotIdleUnknown`), which is why the flag exists: without it a
* restored `done` is indistinguishable from a fresh one and the most dangerous moment in the
* product (just after a relaunch, sessions re-adopted, nothing re-confirmed) would read as the
* safest. Cleared by the first live event.
*/
restored?: true
/**
* The CURRENT `done` was inferred from the CLI going idle at its prompt (Claude's `idle_prompt`
* notification, `normalize.ts` `idle`), not from a turn-end hook.
*
* `normalize.ts` already calls that a RESCUE signal, and `reduceEntry` already honours it as one
* — it may only move a node that is still `working`. What was missing is that the resulting entry
* did not remember WHICH kind of `done` it holds, so a consumer downstream could not tell a turn
* that ended from a CLI that merely went quiet. Gate 2 of agent messaging is the consumer that
* must: a node blocked on an approval is also "idle at its prompt", and delivering into it is
* delivering into a modal. `Canvas.tsx` already discards the idle rescue for an `undefined` node
* for the same reason; messaging must not be the one consumer that trusts it.
*
* Written on the SAME edge as `state`/`stateVerified` (inside `commitState`), so it can never
* describe a state it did not arrive with.
*/
idleInferred?: true
/**
* Eco hibernation: this node's CLI was `/exit`ed while nobody was looking; its tmux session and
* pane live on and the conversation comes back with the provider's `--resume`. The RENDERER owns
* the flag (`agentStatus.setHibernated`, persisted in its localStorage) and reports every change
* over `agent:hibernated` — the mirror only carries it, so an external reader (the phone) can
* render SLEEPING instead of an unexplained idle shell (`setNodeHibernated`). Present = true,
* absent = not hibernated — like `restored`/`idleInferred`, so old files keep their shape.
*
* A hibernated entry is EXEMPT from the expiry sweep: hibernation is precisely "idle for hours",
* so the 6 h staleness rule would erase the one durable fact this field exists to carry. The
* renderer re-reports its persisted set at boot, and a wake (or `clearNode`) drops the flag.
*/
hibernated?: true
/**
* The CURRENT stateless entry was committed by a VERIFIED `SessionStart` this run, and nothing
* has committed a state since. A CLI that has just started or resumed and taken no turn cannot
* be holding an approval, so its `idle_prompt` is allowed to commit a verified, non-inferred
* `done` (see `reduceEffectiveEntry`). Without that, a resumed CLI idling at its prompt was
* unmessageable forever: the boundary left it unverified and only a turn could re-verify it.
* Runtime-only (not in `buildFile`'s allowlist); cleared by every state commit.
*/
sessionStarted?: { sessionId: string; agentId: NormalizedAgentEvent['agentId']; at: number }
/**
* Claude only: the CLI's id (`prompt_id`) for the turn this node is in, from the
* `UserPromptSubmit` that opened it (`NormalizedAgentEvent.turnId`). What lets a transcript
* interrupt marker end exactly THIS turn (`recordTurnInterrupt`) — no hook fires for an
* Esc/Ctrl+C, so the marker is the only signal, and one read back from history names an older
* turn and must change nothing. Runtime-only (not in `buildFile`'s allowlist): after a restart
* no marker can match, which degrades to the stale sweep. Cleared by a
* session boundary.
*/
turnId?: string
/**
* The entry's state EXPIRED (no state commit for EXPIRE_MS) and was stripped: this is an
* IDENTITY-ONLY entry kept so external readers can still find the node's session (see
* IDENTITY_EXPIRE_MS). It carries no `state` and no evidence about one; agent messaging reads it
* as "no current observation", exactly like a node that has never posted. Runtime-only (not in
* `buildFile`'s allowlist — the file says the same thing by omitting `state`); cleared by the next
* state commit.
*/
stateExpired?: true
}
/** This host's Server-Edition install metadata (spec: server-update). Written by the installer
* (`scripts/install-server.sh` → `<dataDir>/install-meta.json`) and surfaced to the phone so it
* can show the installed version / commit and answer "how does this install learn about updates?".
* Set ONLY by the SERVER shell (the desktop app is not an "installed server"); every field is
* optional and the whole block is dropped from SSH slices (it is host-local info). */
export interface MirrorServer {
/** package.json version of the installed checkout, e.g. "0.2.17". */
version?: string
/** Short git commit of the installed checkout, e.g. "1e56f83". */
commit?: string
/** ISO-8601 timestamp of the last successful install/update. */
installedAt?: string
}
/** Host-level launch settings the phone consumes (spec: mobile-agent-launch-parity).
* Additive to MirrorFile v1 — absent on old files, ignored by old readers. */
export interface MirrorSettings {
claudePermissionMode?: string
/** Can `--permission-mode auto` be emitted for **CLAUDE** launches on THIS host? It answers one
* question only — is this host's *claude* CLI ≥ AUTO_PERMISSION_MODE_MIN_VERSION — because that
* is the CLI that exits 1 on the value. It is NOT a per-host verdict on the `auto` mode itself:
* grok has accepted every mode we emit since 1.0.0, so a reader that generalizes this flag to
* every agent will silently start grok sessions in `default` on a host with an old claude. Gate
* on it only for claude (the desktop does exactly that — activePermissionMode in
* renderer/state/permissionMode.ts). */
autoSupported?: boolean
/** Managed accounts usable on THIS host; dirs are absolute on that host. */
claudeAccounts?: { id: string; dir: string }[]
/**
* Which values THIS host's `codex` accepts for `--ask-for-approval`, read from its own `--help`.
* Absent = not probed / not knowable for this host, which means "use `on-request` and `never`
* only" — the two values every codex from 0.146.0 to 0.154.0 takes.
*
* A reader must not emit a value that is not in this list. `untrusted` was removed in codex
* 0.149.0 and clap EXITS on an unknown value, so a phone that launches Manual-mode Codex from a
* hardcoded table gets a dead pane with the CLI's usage error in it (issue #785). It is a
* per-agent, per-host fact for the same reason `autoSupported` is: it answers for *codex* on
* *this* host and generalizes to neither another agent nor another machine.
*/
codexApprovalValues?: string[]
/**
* THIS host's `codex` accepts `--no-daemon` — present only as `true`, when its own `--help` said
* so. A reader launching a plain Codex TUI must then add the flag: from codex-cli 0.157.0 the TUI
* otherwise starts or joins ONE shared app-server per CODEX_HOME that keeps the environment of the
* pane that started it, so the new session's hooks and tool shells run as another node (measured on
* 0.159.2; see shared/agents/codex-daemon.ts). Never together with `--remote` (codex refuses).
* Absent = unknown = emit nothing: clap exits on an unknown option.
*/
codexNoDaemon?: true
/**
* THIS host's `claude` advertises `--session-id` in its own `--help` — present only as `true`.
* A reader that starts a Claude session on this host should then launch it as
* `claude --session-id <fresh uuid>` and hand that id over with the node it registers
* (`agentSessionId` — `RemoteNodeInput` on the relay verb, the same key in the project.json node
* it writes over direct SSH). That is what gives a phone-started node the persisted conversation
* id every canvas-minted node has; without it the node knows its session only once a hook event
* has reached the desktop, and until then has no chat view, no session-name title and nothing
* to cold-restore with.
*
* Absent = unknown = launch the bare command: claude EXITS on an option it does not know. A
* per-agent, per-host fact like its neighbours — it answers for *claude* on *this* host. FIRST
* launch only: `--session-id` with an id that already exists is a launch error, so a relaunch
* of the same node must resume instead.
*/
claudeSessionIdFlag?: true
/**
* The user's custom agents (Settings → Agents), reduced to what a phone needs to chat with one:
* which builtin harness it inherits (the chat capability follows `baseAgent`) and which binary
* names its pane runs as (the pane-owner check before a send). Built ONLY by
* `mirrorCustomAgents` (`core/mirror-custom-agents.ts`) — never the raw `launchCmd`/`args`/`env`,
* which routinely carry API keys and proxy URLs. Absent on old files ⇒ a reader refuses every
* custom node, exactly as before this field existed.
*/
customAgents?: MirrorCustomAgent[]
/**
* `process.platform` of the machine whose sessions this file describes (`darwin` / `linux` /
* `win32`). A phone must not type POSIX shell syntax into a `win32` host's fresh pane — pwsh and
* cmd reject `2>/dev/null`, `env -u`, `VAR=x cmd` — so it asks the host to launch instead
* (`pty.attach { launch }`). Absent on old files and on SSH slices (whose hosts are POSIX).
*/
hostPlatform?: string
}
/**
* The `claudeSessionIdFlag` slot of a settings block, from a probe answer. ONE spelling of "only a
* seen `true`, otherwise absent" for the three writers of that block (desktop mirror, Server
* Edition mirror, the SSH slice) — each passes the probe that answers for the machine its file
* describes. Pinned per site in `mirror-session-id-flag.test.ts`.
*/
export const mirrorClaudeSessionIdFlag = (
supported: boolean | undefined
): Pick<MirrorSettings, 'claudeSessionIdFlag'> => (supported === true ? { claudeSessionIdFlag: true } : {})
/** One custom agent as the mirror advertises it (see MirrorSettings.customAgents). */
export interface MirrorCustomAgent {
/** `custom:<uuid>` — the node's `agentId`. */
id: string
label: string
/** The builtin harness it inherits capabilities from; absent for a baseless custom agent. */
baseAgent?: string
/**
* Plain binary basenames the pane-owner predicate would accept — `binariesFor(id, customAgents)`,
* published only when every name matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$` (enforced by the
* builder). EMPTY when the launch command cannot be named honestly (e.g. `bash -lc …`) or the
* derived name is outside that alphabet (a URL, credential, quoted value or `${env:…}` template);
* a reader must then refuse, never fall back to a guess.
*/
binaries: string[]
}
export interface MirrorFile {
v: 1
updatedAt: number
nodes: Record<
string,
{
/** Absent = unknown: idle, between sessions, or an IDENTITY-ONLY entry whose state expired
* (older than EXPIRE_MS — see IDENTITY_EXPIRE_MS). A reader must never read absence as
* "working"; the identity fields stay valid either way. */
state?: AgentState
agentId?: AgentId
sessionId?: string
/** Observed Claude account (see MirrorEntry.account). Additive — absent on old files and
* on every node that has never posted a claude hook payload. */
account?: ObservedClaudeAccount
/** The agent's own session name (see MirrorEntry.name). Absent until resolved. */
name?: string
/** Eco hibernation (see MirrorEntry.hibernated). Present = true; absent on old files. */
hibernated?: true
updatedAt: number
}
>
/** Host-level launch settings (permission mode, managed accounts). Additive/optional: absent
* on old files and whenever no settings provider is wired — the file shape is then byte-for-byte
* identical to before this block existed. */
settings?: MirrorSettings
/** Local accounts' provider rate-limit usage (spec: mobile-usage-inbox). Additive/optional —
* absent on old files, and dropped from SSH slices (a host answers only for its own creds). */
usage?: MirrorUsage
/** Agent inbox: an event feed + per-node "what it's doing right now" (spec: mobile-usage-inbox).
* Additive/optional. Unlike `usage`, SSH slices KEEP a filtered inbox (their own nodes only). */
inbox?: MirrorInbox
/** This host's Server-Edition install metadata (spec: server-update). Additive/optional — absent
* on old files and whenever no server provider is wired (e.g. the desktop app). Dropped from SSH
* slices (host-local info, like `usage`). */
server?: MirrorServer
}
// ---- Usage block (mobile-usage-inbox) ------------------------------------------------------
/** Snapshot of the shared `UsageLimit`, tolerated LOOSE on purpose: a parallel branch is
* generalizing that type (severity may be `string | null`, windowMinutes may appear). The mirror
* passes entries through verbatim — every field but `kind`/`usedPercent` is optional here, and
* the defensive mapper below (`?? null`) compiles against either shape of the source type. */
export interface MirrorUsageLimit {
kind: string
group?: string | null
usedPercent: number
severity?: string | null
resetsAt?: number | null
windowMinutes?: number | null
scopeLabel?: string | null
isActive?: boolean
}
export interface MirrorUsageAccount {
/** null = the system `~/.claude` account. */
accountId: string | null
/** Account label from settings (managed accounts); null for the system account. */
label: string | null
email: string | null
agentId: string
/** 'ok' | 'unavailable' | 'error' | 'fetching' — passed through from the usage service. */
status: string
updatedAt: number
limits: MirrorUsageLimit[]
}
export interface MirrorUsage {
updatedAt: number
/** System account first, then managed local accounts. */
accounts: MirrorUsageAccount[]
}
/** One cached usage row from the usage service. Deliberately STRUCTURAL (not `import`ed from
* `@shared/types`) so this file does not couple to a `ClaudeUsage` shape a parallel branch is
* mid-flight editing — a real `ClaudeUsage` is assignable to this loose shape. */
export interface UsageSnapshotEntry {
accountId: string | null
usage: {
email?: string | null
updatedAt?: number
status?: string
limits?: ReadonlyArray<{
kind: string
usedPercent: number
group?: string | null
severity?: string | null
resetsAt?: number | null
windowMinutes?: number | null
scopeLabel?: string | null
isActive?: boolean
}>
}
}
/**
* Assemble the `usage` block from the usage service's cached snapshots + the settings account
* list (for labels). Pure. Maps each `UsageLimit` through DEFENSIVELY (`?? null`) so it compiles
* whether the source's `severity` is `string` or `string | null`, and never re-derives severity
* or window from the percentage — those are the provider's call (see claude-usage-map.ts).
* Returns `undefined` when there is nothing to advertise, so the file keeps its old shape.
*/
export function buildMirrorUsage(
snapshot: ReadonlyArray<UsageSnapshotEntry>,
accounts: ReadonlyArray<{ id: string; label?: string | null; email?: string | null }>,
now: number
): MirrorUsage | undefined {
if (snapshot.length === 0) return undefined
const byId = new Map(accounts.map((a) => [a.id, a]))
// System account (accountId null) first, then everything else in given order.
const ordered = [...snapshot].sort((a, b) => {
if (a.accountId === b.accountId) return 0
if (a.accountId === null) return -1
if (b.accountId === null) return 1
return 0
})
const mapped: MirrorUsageAccount[] = ordered.map((e) => {
const acct = e.accountId ? byId.get(e.accountId) : undefined
const u = e.usage
return {
accountId: e.accountId,
label: acct?.label ?? null,
email: u.email ?? acct?.email ?? null,
agentId: 'claude',
status: u.status ?? 'unavailable',
updatedAt: u.updatedAt ?? now,
limits: (u.limits ?? []).map((l) => ({
kind: l.kind,
group: l.group ?? null,
usedPercent: l.usedPercent,
// `?? null` here is the whole point: it type-checks against BOTH a `string` and a
// `string | null` severity (the parallel branch's in-flight generalization).
severity: l.severity ?? null,
resetsAt: l.resetsAt ?? null,
windowMinutes: l.windowMinutes ?? null,
scopeLabel: l.scopeLabel ?? null,
isActive: l.isActive ?? false
}))
}
})
const updatedAt = mapped.reduce((m, a) => Math.max(m, a.updatedAt), 0) || now
return { updatedAt, accounts: mapped }
}
// ---- Inbox block (mobile-usage-inbox) ------------------------------------------------------
/** Feed cap — oldest events fall off the front once the array exceeds this. */
export const INBOX_EVENTS_CAP = 50
export const INBOX_TITLE_MAX = 120
export const INBOX_DETAIL_MAX = 240
/** Cap for the `You: …` prompt line carried on a working start edge (Live Activity + notch). */
export const PROMPT_MAX = 120
export const INBOX_ACTIVITY_MAX = 80
// Question options (spec: interactive-push-live-activities): first question only, ≤4 choices,
// each label clipped to 60 chars.
export const INBOX_QUESTION_OPTIONS_MAX = 4
export const INBOX_OPTION_LABEL_MAX = 60
// Live-update `message` headline cap (needs-you / done event title).
export const LIVE_MESSAGE_MAX = 120
// Bound on the approval/question TITLE-dedup (see produceInboxFromState). A live ask re-asserts
// within seconds, so only an unresolved same-title event YOUNGER than this suppresses a re-assert.
// An OLDER lingering same-title event — e.g. an unresolved generic-title "Waiting for input"
// restored across a restart (loadPersisted keeps unresolved events verbatim), whose node never
// re-passed the state-leave `resolveUnresolvedFor` — must NOT muzzle a genuinely NEW ask forever:
// it is SUPERSEDED (resolved) and the new ask fires.
export const QUESTION_DEDUP_WINDOW_MS = 10 * 60_000
export interface InboxEvent {
/** Monotonic per writer: `${ts}-${seq}`. */
id: string
ts: number
nodeId: string
agentId?: string
sessionId?: string
kind: 'approval' | 'question' | 'done'
/** First line, ≤120 chars. */
title: string
/** ≤240 chars — lastMessage snippet. */
detail?: string
/** done: the user hit Esc/Ctrl-C. */
interrupted?: boolean
/** approval/question: the node has since left blocked/waiting (moves to the phone's archive).
* done: the desktop/browser user READ the finished session (`ackDone`), so the phone marks the
* Inbox card seen and its lingering DONE Live Activity is dismissed. Set on next mirror flush. */
resolved?: boolean
/** question only: the AskUserQuestion choices (first question, ≤4 labels, each ≤60 chars) so the
* phone can render numbered chips / notification actions. Absent for approvals + plain questions
* (spec: interactive-push-live-activities). */
options?: string[]
/** question only: the AskUserQuestion `questions[0].multiSelect` flag — the picker accepts more
* than one choice. Rides the pipeline so the phone renders multi-select chips. Omitted when
* absent/false (spec: interactive-push-live-activities). */
multiSelect?: boolean
/** approval only: the deterministic hook-reply ticket (docs/hook-reply-approvals.md). Present when
* the managed permission hook is holding open for an answer — the phone/canvas write
* `~/.nodeterm/pending/<pendingId>.answer` to answer it. Rides the mirror to the phone; dropped
* from the push-notify body (the phone re-reads the mirror before acting). Absent = legacy prompt. */
pendingId?: string
}
export interface InboxNodeNow {
/** ≤80 chars — "Editing foo.ts", "Running npm test", "Reading bar.ts". */
activity?: string
/** Raw tool name the activity came from. */
tool?: string
/** Context-window fill 0–100 (from context-tail), when known. */
contextPercent?: number
/** ≤PROMPT_MAX — the first line of the user prompt that opened the CURRENT turn ("You: …").
* Set on a new turn, cleared with `activity` when the turn ends, so a phone poll (which has no
* access to the push edges) can render the same line the push carries and the notch shows. */
prompt?: string
updatedAt: number
}
export interface MirrorInbox {
/** Oldest→newest, capped at INBOX_EVENTS_CAP. */
events: InboxEvent[]
/** Per-node "what it's doing right now". */
nodes: Record<string, InboxNodeNow>
}
/**
* Pure reducer: fold one event into a node's entry, mirroring the renderer store's MAIN-state
* semantics. Returns the next entry (never mutates `prev`). `now` is injected for testability.
*/
function resolveGrokStopCancelled(ev: NormalizedAgentEvent): NormalizedAgentEvent {
if (
ev.agentId !== 'grok' ||
ev.kind !== 'state' ||
ev.state !== undefined ||
!ev.cancelReason ||
ev.subagentType !== undefined
) {
return ev
}
// Grok 1.0.13's `10-hooks.md:336,348,354,384` makes this a CLOSED session-level decision.
// A subagent cancellation is returned above because ending its card must not end the parent
// session. Unknown reasons stay identity-only: guessing `done` could turn a future cancel-and-send
// dialect into a false completion while the agent is still working.
switch (ev.cancelReason) {
case 'user_interrupt':
return { ...ev, state: 'done', interrupted: true }
case 'permission_rejected':
case 'permission_cancelled':
case 'max_turns':
case 'no_progress':
// These end the turn, but are not an Esc/Ctrl-C. Keeping them non-interrupted makes the
// non-successful terminal outcome visible instead of suppressing its completion edge.
return { ...ev, state: 'done' }
case 'unknown':
return ev
}
}
export function reduceEntry(
prev: MirrorEntry | undefined,
ev: NormalizedAgentEvent,
now: number
): MirrorEntry {
return reduceEffectiveEntry(prev, resolveGrokStopCancelled(ev), now)
}
function uncorrelatedStartIdle(prev: MirrorEntry | undefined, ev: NormalizedAgentEvent, now: number): boolean {
const started = prev?.sessionStarted
return !!started && ev.kind === 'state' && !!ev.idle &&
(ev.sessionId !== started.sessionId || ev.agentId !== started.agentId ||
prev.sessionId !== started.sessionId || now < started.at)
}
function reduceEffectiveEntry(
prev: MirrorEntry | undefined,
ev: NormalizedAgentEvent,
now: number
): MirrorEntry {
const next: MirrorEntry = prev ? { ...prev } : { updatedAt: now }
// Ignore foreign idle proof before generic identity capture can overwrite the session.
const started = prev?.sessionStarted
if (uncorrelatedStartIdle(prev, ev, now)) return next
/**
* Commit a state onto `next` — and everything that must move WITH it. One function rather than
* the same four lines at each branch, because the alternative was measured: of the three branches
* that commit a state, the `request_user_input` hold set `next.state` and nothing else. A
* verified `waiting` therefore kept `stateVerified: true` after a TOKENLESS `done` re-asserted
* it — replayable indefinitely by any caller, since `/hook/*` is fail-open by contract, with
* `updatedAt` advancing each time so the entry never even expired. A rule three call sites have
* to remember is a rule two of them keep.
*
* `proof` is the evidence for THIS transition, passed in rather than read off `ev` so the one
* caller that means something different has to say so out loud.
*/
const commitState = (
state: AgentState | undefined,
proof: boolean,
idleAfterSessionStart = false
): void => {
next.state = state
next.updatedAt = now
next.stateVerified = proof
if (proof) next.verifiedAt = now
next.clientRevision = ev.clientRevision
delete next.sessionStarted
delete next.stateExpired
// Which KIND of `done` this is, recorded on the same edge as the state itself. `idle` is only
// ever meaningful on a `done`; assigning (not merging) is the point — a later, genuine turn-end
// `done` must clear the marker, or a node would stay tainted for the rest of its session.
// The one idle `done` that is NOT inferred is the one right after a verified session start:
// no turn has run, so no approval can be pending behind the prompt (see `sessionStarted`).
if (state === 'done' && ev.idle && !idleAfterSessionStart) next.idleInferred = true
else delete next.idleInferred
// The entry's STATE now comes from this run, so it is no longer the one restored off disk.
// Cleared HERE and only here: an event that commits no state — a context/usage event, a
// held-off late `working`, the idle rescue — leaves a restored `done` exactly as restored as
// it was. `restored` means "this state came off disk", not "we have heard something since
// boot", and gate 2 will read it as the former.
delete next.restored
}
// Unrelated tool hooks (including untagged child hooks) are not answers. Keep both
// the state and its original evidence/identity until a correlated result or explicit reset.
const resetApprovals = (ev.kind === 'session' && ev.sessionPhase === 'start') ||
(ev.sessionId === prev?.sessionId && (ev.kind === 'session' || ev.newTurn || ev.interrupted))
if (resetApprovals) delete next.concurrentApprovalIds
else {
if (ev.pendingId && ev.state === 'blocked' && ev.askKind === 'approval' &&
(prev?.pendingQuestion || prev?.concurrentApprovalIds?.length)) {
next.concurrentApprovalIds = [...new Set([...(prev?.concurrentApprovalIds ?? []), ev.pendingId])]
}
if (ev.pendingId && ev.state === 'working' && next.concurrentApprovalIds) {
next.concurrentApprovalIds = next.concurrentApprovalIds.filter(id => id !== ev.pendingId)
if (!next.concurrentApprovalIds.length) delete next.concurrentApprovalIds
}
}
const ask = prev?.pendingQuestion
if (ask) {
const sameSession = ev.sessionId === ask.sessionId
const reset = (ev.kind === 'session' && ev.sessionPhase === 'start') ||
(sameSession && (ev.kind === 'session' || ev.newTurn || ev.interrupted))
const answered = sameSession && ev.answeredQuestionId === ask.toolUseId
if (!reset && !answered) return next
delete next.pendingQuestion
}
if (ev.questionId && ev.sessionId) {
next.pendingQuestion = { sessionId: ev.sessionId, toolUseId: ev.questionId }
}
if (next.concurrentApprovalIds?.length && !next.pendingQuestion) {
// A new picker is independent of outstanding child permissions. Other state events
// hold blocked attention; lifecycle events must not refresh that state's evidence.
if (ev.kind === 'state') commitState('blocked', !!ev.verified)
return next
}
// Identity is captured off ANY event (mirrors the renderer's per-event setSessionId +
// agentId threading). agentId is always present on a NormalizedAgentEvent.
if (ev.agentId) next.agentId = ev.agentId
if (ev.sessionId) next.sessionId = ev.sessionId
// The observed Claude account is identity too, and follows the same rule as `agentId`: written
// by any event that carries one, never cleared by one that does not. Only claude events carry it
// (hook-server), and a claude session's config dir is fixed for the life of the process — an
// event without the label is a codex/gemini event or a payload with no transcript_path, neither
// of which is evidence that this node stopped being on the account it was last seen on.
if (ev.account) next.account = ev.account
// The live turn's id rides the event that opens it; nothing else touches it until the next turn
// or a session boundary (below). See `recordTurnInterrupt`.
// A prompt with no usable id (`''`) forgets the old one rather than keeping it.
if (ev.kind === 'state' && ev.turnId !== undefined) {
if (ev.turnId) next.turnId = ev.turnId
else delete next.turnId
}
if (ev.kind === 'state' && ev.state) {
// An `idle` done (Claude went quiet at its prompt) is a RESCUE, not a turn end: it may only
// move a node that is still `working`. A node that is blocked/waiting is ALSO idle at the
// prompt — clearing it there would drop a live approval — and one already done needs nothing.
// ONE exception: a verified idle right after a verified session start, with no state committed
// in between. A just-started or just-resumed CLI at its prompt is genuinely idle — and without
// this it stays unverified until a turn it can only get from a message it cannot receive.
const idleAfterSessionStart =
ev.idle === true &&
ev.verified === true &&
!!started &&
prev.state === undefined
if (ev.idle && prev?.state !== 'working' && !idleAfterSessionStart) return next
// An unanswered Codex `request_user_input`: the ask arrives as waiting+awaitingInput and the
// turn's OWN Stop follows as `done` before the user answers (the ask ends the turn; the answer
// opens a new one). That done must not flip the node green over a live question — hold
// `waiting`. Anything else supersedes the ask: a new turn (the answer), other tool activity,
// an interrupt (the user was right there), a session boundary — all drop the flag, keeping the
// stuck-NEEDS-YOU failure mode this file already defends against (see the `idle` rules) out.
if (ev.awaitingInput) {
next.awaitingInput = true
} else if (prev?.awaitingInput && ev.state === 'done' && !ev.interrupted) {
// The HELD state is still a state this event committed — the entry says `waiting` because
// THIS POST arrived — so its evidence is this POST's evidence, not the ask's from before.
commitState('waiting', ev.verified === true)
return next
} else {
next.awaitingInput = undefined
}
// Done-holdoff: a late, non-newTurn `working` (out-of-order parallel hook, or an in-flight
// tool POST at interrupt) must not resurrect a turn that just finished. Only a genuine new
// turn (UserPromptSubmit) may. Leave state + updatedAt untouched so the window keeps
// measuring from the `done`.
const heldOff =
ev.state === 'working' &&
!ev.newTurn &&
prev?.state === 'done' &&
now - (prev.updatedAt ?? 0) < DONE_HOLDOFF_MS
// Evidence is written on the SAME edge the state is, and only there: a context/usage event
// carrying a verified flag says nothing about how the current state arrived, and a held-off
// working did not change the state whose proof this describes. `clientRevision` is ASSIGNED
// rather than merged — an event with no stamp is a report that this node is running a script
// that cannot send one, which is exactly what a stale entry would hide.
if (!heldOff) commitState(ev.state, ev.verified === true, idleAfterSessionStart)
} else if (ev.kind === 'session') {
// SessionStart / SessionEnd both reset the node to idle (renderer: setState(id, undefined)).
// The proof goes with the state it was about, and `false` is passed EXPLICITLY rather than
// `ev.verified`: this commits idle, and "the idle was verified" is not a claim worth making.
// `verifiedAt` stays — "this node has proven itself at least once" survives a session boundary
// and is what makes a refusal retryable.
commitState(undefined, false)
next.awaitingInput = undefined
delete next.turnId
// The boundary proves nothing about a state (and leaves `verifiedAt` alone), but a VERIFIED
// start arms the idle rescue above.
if (ev.sessionPhase === 'start' && ev.verified === true && ev.sessionId) {
next.sessionStarted = { sessionId: ev.sessionId, agentId: ev.agentId, at: now }
}
}
// subagent-start / subagent-end / recurring: identity captured above, main state untouched.
return next
}
/**
* The identity-only form of an entry whose state expired: agentId, sessionId, account and name,
* with the state and everything state-derived removed. `undefined` when there is no identity worth
* keeping (neither an agentId nor a sessionId). `updatedAt` keeps the state's clock — it is what the
* identity TTL is measured from, and it keeps the entry reading as old to any freshness check.
*/
function identityOnly(e: MirrorEntry): MirrorEntry | undefined {
if (!e.agentId && !e.sessionId) return undefined
return {
...(e.agentId ? { agentId: e.agentId } : {}),
...(e.sessionId ? { sessionId: e.sessionId } : {}),
...(e.account ? { account: e.account } : {}),
...(e.name ? { name: e.name } : {}),
...(e.restored ? { restored: true as const } : {}),
updatedAt: e.updatedAt,
stateExpired: true
}
}
/**
* Age one entry against the two horizons. Pure. Returns the entry unchanged while its state is
* fresh (or it is hibernated — hibernation IS long idleness), its identity-only form past
* EXPIRE_MS, and `undefined` once it should go: past IDENTITY_EXPIRE_MS, or past EXPIRE_MS for a
* node `liveIds` says no longer exists. A FRESH entry is never pruned by existence — a brand-new
* node may not have been saved yet. `liveIds` undefined = unknowable, prune by TTL only.
*/
export function ageEntry(
id: string,
e: MirrorEntry,
now: number,
expireMs = EXPIRE_MS,
liveIds?: ReadonlySet<string>
): MirrorEntry | undefined {
if (e.hibernated || now - e.updatedAt <= expireMs) return e
if (now - e.updatedAt > IDENTITY_EXPIRE_MS) return undefined
if (liveIds && !liveIds.has(id)) return undefined
if (e.stateExpired) return e
return identityOnly(e)
}
/**
* Restrict a mirror doc to the given node ids. Pure. Used by the SSH-host status push: each
* connected host receives ONLY its own project's nodes — the full mirror would leak other
* projects' node/session ids to every host the user is connected to.
*
* Deliberately drops the local `settings` block: a slice carries per-host settings that the SSH
* push injects itself (Task 2 of mobile-agent-launch-parity), never this host's local block.
*
* `usage` is likewise DROPPED (spec: mobile-usage-inbox): the block describes THIS machine's
* local accounts, and a host running nodeterm itself writes its own mirror with its own usage.
* (The desktop CAN now read a host's Claude usage — see core/usage/remote-claude-usage — but
* pushing those numbers back to the very host they were read on would be a round trip to
* nowhere. Surfacing remote usage on the phone means teaching the phone to ask, not padding
* this slice.) `server` (install metadata) is DROPPED for the same
* reason (it describes THIS host's install, not the remote's — a remote nodeterm writes its own).
* `inbox` is KEPT but filtered to the slice's node ids (both the `events` feed and the per-node
* `nodes` map).
*/
export function filterMirrorForNodes(doc: MirrorFile, nodeIds: ReadonlySet<string>): MirrorFile {
const nodes: MirrorFile['nodes'] = {}
for (const [id, e] of Object.entries(doc.nodes)) if (nodeIds.has(id)) nodes[id] = e
const out: MirrorFile = { v: doc.v, updatedAt: doc.updatedAt, nodes }
if (doc.inbox) {
const inboxNodes: Record<string, InboxNodeNow> = {}
for (const [id, n] of Object.entries(doc.inbox.nodes)) if (nodeIds.has(id)) inboxNodes[id] = n
out.inbox = {
events: doc.inbox.events.filter((e) => nodeIds.has(e.nodeId)),
nodes: inboxNodes
}
}
return out
}
/** Prune expired entries and shape the on-disk file. Pure; `now` injected for testability.
* `settings`, when given, is attached as the additive host-level block (absent otherwise, so the
* file shape is identical to before this block existed). */
export function buildFile(
nodes: Record<string, MirrorEntry>,
now: number,
expireMs = EXPIRE_MS,
settings?: MirrorSettings,
usage?: MirrorUsage,
inbox?: MirrorInbox,
server?: MirrorServer,
liveIds?: ReadonlySet<string>
): MirrorFile {
const out: MirrorFile = { v: 1, updatedAt: now, nodes: {} }
for (const [id, entry] of Object.entries(nodes)) {
// Past `expireMs` the STATE goes but the identity stays (see IDENTITY_EXPIRE_MS). A hibernated
// entry never expires at all: hibernation IS long idleness, so the staleness rule would erase
// exactly the durable fact the flag carries (see MirrorEntry.hibernated).
const e = ageEntry(id, entry, now, expireMs, liveIds)
if (!e) continue
// Undefined fields drop out of JSON.stringify — an idle node keeps agentId/sessionId
// without a `state` key.
out.nodes[id] = {
state: e.state,
agentId: e.agentId,
sessionId: e.sessionId,
// Spread-when-present, like `name`/`hibernated`: a node that never posted a claude payload
// keeps the byte-for-byte file shape it had before this field existed.
...(e.account ? { account: e.account } : {}),
...(e.name ? { name: e.name } : {}),
...(e.hibernated ? { hibernated: true as const } : {}),
updatedAt: e.updatedAt
}
}
if (settings) out.settings = settings
if (usage) out.usage = usage
// Only attach a non-empty inbox — an empty one would gratuitously change the old-file shape.
if (inbox && (inbox.events.length > 0 || Object.keys(inbox.nodes).length > 0)) out.inbox = inbox
// Only attach a non-empty server block (all fields absent ⇒ omit, keeping the old-file shape).
if (server && (server.version || server.commit || server.installedAt)) out.server = server
return out
}
// ---- Inbox production (pure helpers) -------------------------------------------------------
/** Clip a string to `max`, appending an ellipsis when it had to cut. */
function clip(s: string, max: number): string {
return s.length > max ? s.slice(0, max - 1) + '…' : s
}
/** First non-empty line of a message, trimmed and clipped. '' when absent/blank. */
export function firstLine(msg: string | undefined, max: number): string {
if (!msg) return ''
const line = (msg.split('\n').find((l) => l.trim()) ?? '').trim()
return clip(line, max)
}
/** Basename of a slash- or backslash-separated path (no `path` import: works on remote paths too). */
function basename(p: string): string {
const parts = p.split(/[\\/]/)
return parts[parts.length - 1] || p
}
/**
* Map a raw hook tool invocation to a human "what it's doing now" line (spec: mobile-usage-inbox).
* Pure; clipped to INBOX_ACTIVITY_MAX. Unknown tools fall back to "Using <tool>".
*
* TWO VOCABULARIES, one function. Claude's names are PascalCase (`Read`, `Bash`) and grok's are
* snake_case (`read_file`, `run_terminal_command`), so they cannot collide and no agent id is needed
* to tell them apart — but only while the match stays EXACT. Do not add case-folding here: `grep`
* and `Grep`, `write` and `Write` differ by case alone, and folding them would silently read grok's
* argument keys out of a claude payload.
*
* The grok names are MEASURED, not derived from the docs: `signals.json.toolsUsed` across 22 real
* sessions (grok 1.0.13, 2026-09-02) yields exactly fifteen. Their ARGUMENT keys are a separate
* question and only two were seen in captured hook payloads — `read_file.target_file` and
* `run_terminal_command.command`. Every other grok case below therefore names the action and stops,
* rather than reading a key nobody has observed: a phrase with no detail is honest, a phrase built
* on a guessed key renders "Editing file" forever the day the guess is wrong.
*/
export function toolActivity(toolName: string, toolInput: Record<string, unknown> | undefined): string {
const ti = toolInput ?? {}
const str = (v: unknown): string => (typeof v === 'string' ? v : '')
let out: string
switch (toolName) {
// ---- grok (snake_case). MEASURED argument keys only. ----
case 'read_file':
out = `Reading ${basename(str(ti.target_file)) || 'file'}`
break
case 'run_terminal_command': {
const cmd = str(ti.command).replace(/\s+/g, ' ').trim()
out = `Running ${cmd ? clip(cmd, 60) : 'command'}`
break
}
case 'search_replace':
out = 'Editing a file'
break
case 'write':
out = 'Writing a file'
break
case 'list_dir':
out = 'Listing a directory'
break
case 'grep':
out = 'Searching the code'
break
case 'web_search':
out = 'Searching the web'
break
case 'web_fetch':
out = 'Fetching a page'
break
case 'todo_write':
out = 'Updating its plan'
break
case 'spawn_subagent':
out = 'Delegating to a subagent'
break
case 'get_command_or_subagent_output':
out = 'Checking a background task'
break
case 'kill_command_or_subagent':
out = 'Stopping a background task'
break
case 'search_tool':
out = 'Looking up an MCP tool'
break
case 'ask_user_question':
out = 'Asking you a question'
break
case 'exit_plan_mode':
out = 'Presenting a plan'
break
// ---- claude (PascalCase) ----
case 'Edit':
case 'Write':
case 'MultiEdit':
out = `Editing ${basename(str(ti.file_path)) || 'file'}`
break
case 'NotebookEdit':
out = `Editing ${basename(str(ti.notebook_path) || str(ti.file_path)) || 'notebook'}`
break
case 'Read':
out = `Reading ${basename(str(ti.file_path) || str(ti.notebook_path)) || 'file'}`
break
case 'Bash':
case 'Shell': { // cursor's shell tool, same `command` key (measured hook payload)
const cmd = str(ti.command).replace(/\s+/g, ' ').trim()
out = `Running ${cmd ? clip(cmd, 60) : 'command'}`
break
}
case 'Grep':
case 'Glob':
out = `Searching ${str(ti.pattern) || '…'}`
break
case 'Task':
out = `Delegating: ${str(ti.description) || str(ti.subagent_type) || '…'}`
break
case 'WebFetch': {
const url = str(ti.url)
let host = url
try {
host = new URL(url).host
} catch {
// not a parseable URL — show the raw string
}
out = `Fetching ${host || '…'}`
break
}
case 'WebSearch':
out = `Fetching ${str(ti.query) || '…'}`
break
default:
// A qualified MCP name is `server__tool` — grok's own dispatcher (`use_tool`) never appears in
// a payload, the resolved call does (10-hooks.md). Naming the tool and its server is more use
// than either half alone, and it is derived from the string itself, so no vocabulary can go
// stale. Everything else keeps the historical "Using <tool>".
{
const mcp = /^([A-Za-z0-9_.-]+)__([A-Za-z0-9_.-]+)$/.exec(toolName)
out = mcp ? `Using ${mcp[2]} (${mcp[1]})` : `Using ${toolName}`
}
}
return clip(out, INBOX_ACTIVITY_MAX)
}
/** Newest UNRESOLVED approval/question event for a node (dedup lookup), or undefined. */
function newestUnresolved(events: ReadonlyArray<InboxEvent>, nodeId: string): InboxEvent | undefined {
for (let i = events.length - 1; i >= 0; i--) {
const e = events[i]
if (e.nodeId === nodeId && !e.resolved && (e.kind === 'approval' || e.kind === 'question')) return e
}
return undefined
}
/**
* Trim the feed to the rolling history `cap`, but PRESERVE the load-bearing per-node events that
* `ackDone` / `isEventUnresolved` / the phone's newest-done depend on — the newest `done` per node
* and the newest UNRESOLVED approval/question per node — even when they fall OUTSIDE the newest-`cap`
* window (audit P2-7). Without this, on a busy multi-agent host a node's `done` (or live ask) ages
* off the front within minutes: `ackDone` then no-ops (a retained DONE card on the phone never
* dismisses) and the phone loses that node's end-reason / newest-done. A RESOLVED ask is not
* protected — it drops with plain history as before — so the retained-past-cap set is bounded by
* ~2 per node. Order (oldest→newest) is preserved, and the wire shape is unchanged: the extra
* survivors ride the same `events` array every reader already walks. Pure — `events` untouched.
*/
export function trimInboxFeed(events: InboxEvent[], cap: number): InboxEvent[] {
if (events.length <= cap) return events
// The newest write per node wins each map (feed is oldest→newest, so a later match overwrites).
const newestDoneId = new Map<string, string>()
const newestUnresolvedAskId = new Map<string, string>()
for (const e of events) {
if (e.kind === 'done') newestDoneId.set(e.nodeId, e.id)
else if (!e.resolved && (e.kind === 'approval' || e.kind === 'question')) {
newestUnresolvedAskId.set(e.nodeId, e.id)
}
}
const protectedIds = new Set<string>([...newestDoneId.values(), ...newestUnresolvedAskId.values()])
// Keep the newest-`cap` window wholesale (history); older events survive only if protected.
const windowStart = events.length - cap
const kept: InboxEvent[] = []
for (let i = 0; i < events.length; i++) {
if (i >= windowStart || protectedIds.has(events[i].id)) kept.push(events[i])
}
return kept
}
// ---- Stateful singleton (production side) --------------------------------------------------
const state = new Map<string, MirrorEntry>()
/** How often the stale-working sweep runs. The window it enforces is WORKING_STALE_MS. */
const STALE_SWEEP_MS = 60_000
let sweepTimer: ReturnType<typeof setInterval> | null = null
let targetFile: string | null = null
let writeTimer: NodeJS.Timeout | null = null
const flushListeners = new Set<(doc: MirrorFile) => void>()
// Supplies the host-level settings block, consulted fresh on every flush (so a mid-session
// permission-mode / account change is picked up without re-wiring). Null = no block written.
let settingsProvider: (() => MirrorSettings | undefined) | null = null
// Supplies the local-accounts usage block, consulted fresh on every flush (so a poll landing
// between flushes is picked up). Null = no `usage` block written (byte-identical old shape).
let usageProvider: (() => MirrorUsage | undefined) | null = null
// Supplies this host's install metadata block (spec: server-update). Set only by the SERVER shell
// (the desktop app leaves it null). Consulted fresh on every flush. Null = no `server` block.
let serverProvider: (() => MirrorServer | undefined) | null = null
// ---- Inbox state (feed + per-node activity) ------------------------------------------------
// The event feed is oldest→newest and capped at INBOX_EVENTS_CAP; `inboxNodes` is the per-node
// "what it's doing right now" (activity from raw tool events + context% from context-tail). Both
// ride the same single write path as the main node map — there is one debounced flush.
let inboxEvents: InboxEvent[] = []
const inboxNodes = new Map<string, InboxNodeNow>()
let inboxSeq = 0
// Fires exactly when a NEW actionable inbox event is appended: approval/question POST-DEDUP (a
// re-asserted identical prompt returns before pushInboxEvent, so it never fires twice) and `done`
// on the turn edge. This is the seam the desktop push-notify service (src/core/push-notify.ts)
// hooks — it is fed the same events the phone's Inbox feed shows. A listener must never throw into
// production; wrapped below.
const inboxActionableListeners = new Set<(e: InboxEvent) => void>()
/**
* Subscribe to newly-appended actionable inbox events (approval/question post-dedup, done on edge).
* Returns an unsubscribe. Additive side-channel — does not change the feed or any disk write.
*/
export function onInboxActionable(cb: (e: InboxEvent) => void): () => void {
inboxActionableListeners.add(cb)
return () => inboxActionableListeners.delete(cb)
}
// ---- Live-update seams (spec: interactive-push-live-activities) -----------------------------
// Two narrow side-channels feed the desktop live-update push stream (src/core/push-notify.ts
// `createLiveUpdatePush`). Neither changes the feed or any disk write.
// - `onNodeStateChange` fires on the MAIN-state EDGES a Live Activity cares about: working start,
// the edge INTO waiting/blocked (mapped to 'needsYou'), and the edge into done — post the same
// done-holdoff / newTurn gating as the badge, so a held-off working never fires a spurious start.
// - `onNodeNowChange` fires when a node's live activity line or context% changes (from
// recordRawToolEvent / recordContextUsage); the sender coalesces these ≥20s per node.
/** A main-state edge worth a Live Activity update. `state` is the phone-facing bucket
* (waiting/blocked collapse to 'needsYou'); `message` is the event headline for needs-you/done. */
export interface NodeStateChange {
nodeId: string
agentId?: string
sessionId?: string
event: 'start' | 'update' | 'end'
state: 'working' | 'needsYou' | 'done'
/** needs-you / done headline, ≤120 chars. Absent for a plain 'start'. */
message?: string
/** needsYou only (spec: interactive-push-live-activities addendum): 'approval' on the edge into
* blocked, 'question' on the edge into waiting. Absent on working/done edges. */
kind?: 'approval' | 'question'
/** question needsYou only: the AskUserQuestion choices from the stash (≤4 × ≤60), so the phone
* can render option buttons straight from the Live Activity. Absent otherwise. */
options?: string[]
/** question needsYou only: the AskUserQuestion `multiSelect` flag from the stash. Omitted when
* absent/false. */
multiSelect?: boolean
/** approval needsYou only: the deterministic hook-reply ticket from the just-produced approval
* event, letting an intent answer the held hook. Absent otherwise. */
pendingId?: string
/** working START edge only: the first line of the user prompt that opened this turn ("You: …"),
* ≤PROMPT_MAX. The one line that says WHAT a session is working on — the notch capsule shows it,
* and it rides the Live Activity so the phone reads the same thing. Absent when the turn started
* without a prompt we saw (a resumed session, a tool-driven working edge). */
prompt?: string
/** done only: this 'end' was produced by the stale-working SWEEP, not by the session itself —
* nobody heard from a `working` node for `WORKING_STALE_MS`, so it is presumed gone (see
* shared/agents/stale.ts). Like `interrupted`, it must never be celebrated as a completion. */
stale?: boolean
/** done only: the turn ended because the user interrupted it (Esc/Ctrl-C) rather than
* finishing — or a session boundary (SessionStart/SessionEnd) reset the node while it was
* still `working`, which is the same story: the run stopped without producing anything.
* Consumers that celebrate a completion (notification, the notch HUD's "finished, unseen"
* highlight) skip it — nothing was accomplished, so there is nothing to go and read. */
interrupted?: boolean
/** done only: this 'end' was produced by an explicit desktop/browser READ of the finished
* session (`ackDone`), NOT the natural turn-end edge. Both send event:'end', which is what the
* phone uses to dismiss the Live Activity — `ack` only distinguishes them for internal
* bookkeeping/tests; the push sender does not need to forward it (end = dismiss). */
ack?: boolean
ts: number
}
/** A per-node "what it's doing now" change (activity line and/or context%). */
export interface NodeNowChange {
nodeId: string
activity?: string
contextPercent?: number
ts: number
}
const nodeStateChangeListeners = new Set<(c: NodeStateChange) => void>()
const nodeNowChangeListeners = new Set<(c: NodeNowChange) => void>()
/** Subscribe to main-state edges (working start / needsYou / done). Returns an unsubscribe. */
export function onNodeStateChange(cb: (c: NodeStateChange) => void): () => void {
nodeStateChangeListeners.add(cb)
return () => nodeStateChangeListeners.delete(cb)
}
/** Subscribe to per-node activity/context% changes. Returns an unsubscribe. */
export function onNodeNowChange(cb: (c: NodeNowChange) => void): () => void {
nodeNowChangeListeners.add(cb)
return () => nodeNowChangeListeners.delete(cb)
}
function fireNodeStateChange(c: NodeStateChange): void {
for (const cb of nodeStateChangeListeners) {
try {
cb(c)
} catch {
// A subscriber must never break production (or its siblings).
}
}
}
function fireNodeNowChange(c: NodeNowChange): void {
for (const cb of nodeNowChangeListeners) {
try {
cb(c)
} catch {
// A subscriber must never break production (or its siblings).
}
}
}
// Per-node stash of the pending needs-you detail, set from the raw-hook seam and attached to the
// next needs-you InboxEvent for that node. Two producers feed it:
// - an AskUserQuestion PreToolUse stashes the option labels + question text (`options`/`question`);
// - a PermissionRequest stashes a derived "what's being approved" summary (`approval`).
// `options` (a real picker) is the QUESTION classification signal; `approval` supplies an approval
// card's title/detail. Cleared on state-leave / new turn / session boundary, and additionally
// time-guarded (STASH_MAX_AGE_MS) so a stash that was never consumed (e.g. a picker that
// auto-resolved) can't be picked up by a genuinely unrelated later needs-you in the same turn.
interface QuestionStash {
/** AskUserQuestion picker: ≤4 labels, each ≤60 chars. Its PRESENCE marks a real question. */
options?: string[]
/** The first question's prompt text, clipped to INBOX_TITLE_MAX. Absent if not present/parseable. */
question?: string
/** AskUserQuestion `questions[0].multiSelect` (tolerant boolean). Absent when not present/false. */
multiSelect?: boolean
/** PermissionRequest: the derived "what's being approved" summary (title + optional detail). */
approval?: { title: string; detail?: string }
/** When the AskUserQuestion PreToolUse / PermissionRequest stashed this — freshness-guard anchor. */
at: number
}
const pendingQuestions = new Map<string, QuestionStash>()
// A stash older than this is ignored (and swept) — see the comment above.
export const STASH_MAX_AGE_MS = 5 * 60_000
/** The node's stash IFF it exists and is fresh (< STASH_MAX_AGE_MS old); a stale one is dropped. */
function freshStash(nodeId: string, now: number): QuestionStash | undefined {
const s = pendingQuestions.get(nodeId)
if (!s) return undefined
if (now - s.at > STASH_MAX_AGE_MS) {
pendingQuestions.delete(nodeId)
return undefined
}
return s
}
/**
* Extract question option labels from an AskUserQuestion `tool_input` (first question only, v1):
* `questions[0].options[].label`, each clipped to 60 chars, ≤4 labels. Pure. FAIL-OPEN — any shape
* mismatch (missing/empty arrays, non-string labels) yields `undefined`.
*/
export function extractQuestionOptions(
toolInput: Record<string, unknown> | undefined
): string[] | undefined {
try {
const questions = (toolInput as { questions?: unknown })?.questions
if (!Array.isArray(questions) || questions.length === 0) return undefined
const options = (questions[0] as { options?: unknown })?.options
if (!Array.isArray(options)) return undefined
const labels: string[] = []
for (const o of options) {
const label = (o as { label?: unknown })?.label
if (typeof label !== 'string' || !label) continue
labels.push(clip(label, INBOX_OPTION_LABEL_MAX))
if (labels.length >= INBOX_QUESTION_OPTIONS_MAX) break
}
return labels.length > 0 ? labels : undefined
} catch {
return undefined
}
}
/**
* Extract the first question's prompt text from an AskUserQuestion `tool_input`
* (`questions[0].question`), clipped to INBOX_TITLE_MAX. Used as the question InboxEvent's title so
* the phone shows the actual question rather than the last assistant line. Pure; FAIL-OPEN — any
* shape mismatch (missing/non-string) yields `undefined`.
*/
export function extractQuestionText(
toolInput: Record<string, unknown> | undefined
): string | undefined {
try {
const questions = (toolInput as { questions?: unknown })?.questions
if (!Array.isArray(questions) || questions.length === 0) return undefined
const q = (questions[0] as { question?: unknown })?.question
if (typeof q !== 'string' || !q) return undefined
return clip(q, INBOX_TITLE_MAX)
} catch {
return undefined
}
}
/**
* Extract the first question's `multiSelect` flag from an AskUserQuestion `tool_input`
* (`questions[0].multiSelect`). Pure; TOLERANT — a non-boolean or any shape mismatch yields
* `undefined` (treated the same as `false` downstream). Rides the stash so the next question event +
* push carry it (spec: interactive-push-live-activities).
*/
export function extractQuestionMultiSelect(
toolInput: Record<string, unknown> | undefined
): boolean | undefined {
try {
const questions = (toolInput as { questions?: unknown })?.questions
if (!Array.isArray(questions) || questions.length === 0) return undefined
const ms = (questions[0] as { multiSelect?: unknown })?.multiSelect
return typeof ms === 'boolean' ? ms : undefined
} catch {
return undefined
}
}
/** mcp tool short name: `mcp__<server>__<tool>` → `<tool>`. Degrades gracefully on odd shapes. */
function mcpShortName(name: string): string {
const parts = name.split('__').filter(Boolean)
return parts.length ? parts[parts.length - 1] : name
}
/** JSON.stringify a value, returning undefined for empty/unserializable objects. */
function safeStringify(v: unknown): string | undefined {
try {
const s = JSON.stringify(v)
return s && s !== '{}' && s !== 'null' ? s : undefined
} catch {
return undefined
}
}
/**
* Derive a human "what is being approved" summary from a PermissionRequest's tool_name/tool_input
* (field report: approval cards showed only "Needs approval"). Pure; FAIL-OPEN — an empty tool name,
* a shape mismatch, or any throw yields `undefined`, so the caller keeps today's lastMessage/generic
* title. `title` is clipped to INBOX_TITLE_MAX, `detail` to INBOX_DETAIL_MAX.
*/
export function buildApprovalSummary(
toolName: string,
toolInput: Record<string, unknown> | undefined
): { title: string; detail?: string } | undefined {
if (!toolName) return undefined
try {
const ti = toolInput ?? {}
const str = (v: unknown): string => (typeof v === 'string' ? v : '')
// Rough line count: newlines + 1 when non-empty (the field-report spec says rough is fine).
const lineCount = (s: string): number => (s ? s.split('\n').length : 0)
let title: string
let detail: string | undefined
switch (toolName) {
case 'Edit':
case 'NotebookEdit': {
const p = str(ti.file_path) || str(ti.notebook_path)
const added = lineCount(str(ti.new_string) || str(ti.new_source))
const removed = lineCount(str(ti.old_string) || str(ti.old_source))
title = `Edit ${basename(p) || 'file'}`
detail = p ? `${p} +${added} −${removed}` : undefined
break
}
case 'Write': {
const p = str(ti.file_path)
const n = lineCount(str(ti.content))
title = `Write ${basename(p) || 'file'}`
detail = p ? `${p} (${n} lines)` : undefined
break
}
case 'Bash': {
const cmd = str(ti.command)
const first = cmd.split('\n')[0] ?? ''
title = 'Run command'
detail = cmd.includes('\n') ? `${first} …` : first || undefined
break
}
case 'Read': {
const p = str(ti.file_path) || str(ti.notebook_path)
title = `Read ${basename(p) || 'file'}`
detail = p || undefined
break
}
case 'WebFetch': {
const url = str(ti.url)
let host = url
try {
host = new URL(url).host
} catch {
// not a parseable URL — show the raw string
}
title = `Fetch ${host || '…'}`
detail = url || undefined
break
}
case 'WebSearch': {
title = 'Search'
detail = str(ti.query) || undefined
break
}
case 'Task': {
title = 'Launch subagent'
detail = str(ti.description) || str(ti.prompt) || undefined
break
}
default: {
title = toolName.startsWith('mcp__') ? `Use ${mcpShortName(toolName)}` : `Use ${toolName}`
detail = safeStringify(ti)
}
}
const t = clip(title, INBOX_TITLE_MAX)
if (!t) return undefined
const d = detail ? clip(detail, INBOX_DETAIL_MAX) : undefined
return d ? { title: t, detail: d } : { title: t }
} catch {
return undefined
}
}
function pushInboxEvent(e: Omit<InboxEvent, 'id'>): void {
const id = `${e.ts}-${++inboxSeq}`
const full: InboxEvent = { id, ...e }
inboxEvents.push(full)
// Cap the feed from the front (oldest fall off), but keep each node's newest done + newest
// unresolved ask past the cut so `ackDone` / `isEventUnresolved` / the phone's newest-done
// don't lose the load-bearing event on a busy multi-agent host (audit P2-7).
inboxEvents = trimInboxFeed(inboxEvents, INBOX_EVENTS_CAP)
// Notify actionable-event subscribers (only reached AFTER the dedup early-returns above it).
for (const cb of inboxActionableListeners) {
try {
cb(full)
} catch {
// A subscriber must never break inbox production (or its siblings).
}
}
}
/**
* Is the inbox event `eventId` on `nodeId` STILL unresolved? The desktop push-notify service's
* presence-aware hold uses this on the present→away flush to drop an event that got resolved while
* it was held: an approval/question the node has since left blocked/waiting for (`resolved:true` via
* `resolveUnresolvedFor`), or a `done` the desktop/browser user already read (`ackDone`). A missing
* event — never seen, or aged off the capped feed — is NOT relevant either (returns false), so a
* held push whose event the mirror no longer tracks is dropped rather than sent late. Pure read.
*/
/**
* The hook-reply tickets the mirror still considers open for ONE node: its unresolved approval
* cards' `pendingId`s plus the approvals held concurrently with a picker. The phone's
* `agent.answer` uses it to bind a ticket to the node it names (a pendingId from another node, or
* one already answered, is refused). Question/plan holds are not here — their pendingId is
* stripped from the inbox card — so those bind through the renderer's `held` instead. Pure read.
*/
export function pendingTicketsFor(nodeId: string): string[] {
const out = new Set<string>()
for (const e of inboxEvents) {
if (e.nodeId === nodeId && !e.resolved && e.kind === 'approval' && e.pendingId) out.add(e.pendingId)
}
for (const id of state.get(nodeId)?.concurrentApprovalIds ?? []) out.add(id)
return [...out]
}
/**
* The ask that is CURRENTLY open on a node — its newest unresolved approval/question card, the same
* pick the phone renders its answer card from (`LiveActivityManager.needsYouContent`). The relay's
* `agent.key` compares it with the kind of answer it is about to type: a question's digit typed
* into a permission prompt ANSWERS it (`2` = "don't ask again"). Undefined = no open ask. Pure read.
*/
export function openAskFor(nodeId: string): { kind: 'approval' | 'question'; pendingId?: string } | undefined {
const e = newestUnresolved(inboxEvents, nodeId)
if (!e) return undefined
return { kind: e.kind as 'approval' | 'question', ...(e.pendingId ? { pendingId: e.pendingId } : {}) }
}
export function isEventUnresolved(nodeId: string, eventId: string): boolean {
for (const e of inboxEvents) {
if (e.id === eventId && e.nodeId === nodeId) return !e.resolved
}
return false
}
/** Settle older attention cards, optionally retaining independent child approval tickets. */
function resolveUnresolvedFor(nodeId: string, keepApprovalIds: readonly string[] = []): void {
for (const e of inboxEvents) {
if (e.nodeId === nodeId && !e.resolved && (e.kind === 'approval' || e.kind === 'question') &&
!(e.kind === 'approval' && e.pendingId && keepApprovalIds.includes(e.pendingId))) {
e.resolved = true
}
}
}
/**
* Wire (or clear with `null`) the provider for the additive host-level settings block. Called
* once from main on launch; absent ⇒ the mirror writes no `settings` key at all.
*/
export function setMirrorSettingsProvider(p: (() => MirrorSettings | undefined) | null): void {
settingsProvider = p
}
/** Read the settings provider, failing open: a throwing/absent provider yields no block and must
* never break the flush. */
function safeSettings(): MirrorSettings | undefined {
try {
return settingsProvider?.() ?? undefined
} catch {
return undefined // provider must never break the flush
}
}
/**
* Wire (or clear with `null`) the provider for the additive `usage` block. Called once per shell
* on launch; absent ⇒ the mirror writes no `usage` key. The provider is consulted fresh on every
* flush, so a usage poll that lands between flushes is picked up without re-wiring.
*/
export function setMirrorUsageProvider(p: (() => MirrorUsage | undefined) | null): void {
usageProvider = p
}
/** Read the usage provider, failing open (a throwing/absent provider yields no block). */
function safeUsage(): MirrorUsage | undefined {
try {
return usageProvider?.() ?? undefined
} catch {
return undefined
}
}
/**
* Wire (or clear with `null`) the provider for the additive `server` install-metadata block
* (spec: server-update). Called once by the SERVER shell on launch; absent ⇒ the mirror writes no
* `server` key (the desktop app's shape is byte-identical to before this block existed).
*/
let liveNodesProvider: (() => ReadonlySet<string> | undefined) | null = null
/**
* Which node ids exist in ANY project (open or closed), so an identity-only entry for a deleted
* node can be dropped (see IDENTITY_EXPIRE_MS). The provider answers `undefined` when it cannot know
* the full set — then nothing is pruned by existence, only by TTL. A throw reads as `undefined`.
*/
export function setMirrorLiveNodesProvider(p: (() => ReadonlySet<string> | undefined) | null): void {
liveNodesProvider = p
}
function safeLiveNodes(): ReadonlySet<string> | undefined {
if (!liveNodesProvider) return undefined
try {
return liveNodesProvider() ?? undefined
} catch {
return undefined
}
}
export function setMirrorServerProvider(p: (() => MirrorServer | undefined) | null): void {
serverProvider = p
}
/** Read the server provider, failing open (a throwing/absent provider yields no block). */
function safeServer(): MirrorServer | undefined {
try {
return serverProvider?.() ?? undefined
} catch {
return undefined
}
}
/**
* Subscribe to every flush's built doc (fires even when the local disk write fails — the doc is
* the product, the file is one consumer of it). Returns an unsubscribe. Feeds the SSH-host
* status push, which mirrors each connected project's slice of this doc onto its host.
*/
export function onMirrorFlush(cb: (doc: MirrorFile) => void): () => void {
flushListeners.add(cb)
return () => flushListeners.delete(cb)
}
/**
* Restore the persisted mirror doc into memory WITHOUT firing any seam. This is what makes the
* in-memory dedups survive a process RESTART.
*
* Field bug (owner screenshot): THREE identical "Finished — <same lastMessage>" APNs pushes, one
* per Server-Edition restart. Root cause: the mirror kept ALL its dedup in memory only, so every
* boot started with an empty `state` map + empty `inboxEvents`. Because the headless service is
* `Type=simple` (KillMode=control-group), a `systemctl restart` SIGTERMs the whole cgroup — the
* app's tmux server included — so its sessions die; each reconnect then cold-restores the node and
* re-launches `claude --resume`, whose completed turn re-emits `Stop` → a `done` carrying the SAME
* `last_assistant_message`. With `prevState === undefined` after boot, `produceInboxFromState`'s
* done-EDGE guard (`nextState === 'done' && prevState !== 'done'`) always fired, re-producing the
* done and re-firing `onInboxActionable` → the duplicate push (and, come the nightly auto-update
* timer, a nightly duplicate for every lingering done).
*
* Restoring `state` so `prevState` survives makes the done-edge guard suppress an identical
* re-`done` on its own; restoring `inboxEvents` makes the approval/question title-dedup
* (`newestUnresolved`) survive too, closing the same class for needs-you re-pushes. A restored
* state is NOT a new event — this NEVER calls a listener, so no push/live-update fires on boot.
* Fail-open: a missing / unreadable / corrupt file leaves memory empty, i.e. bit-for-bit legacy
* behavior. Stale entries are dropped with the SAME expiry sweep `buildFile`/`flush` apply, so a
* "working" from a long-dead session is never resurrected.
*/
/** Minimal shape check for a restored `account` block (see the call site's comment). */
function isObservedAccount(a: unknown): a is ObservedClaudeAccount {
if (!a || typeof a !== 'object') return false
const o = a as Record<string, unknown>
return (
typeof o.configDir === 'string' &&
!!o.configDir &&
(o.accountId === null || typeof o.accountId === 'string') &&
typeof o.known === 'boolean'
)
}
function loadPersisted(file: string): void {
// Only seed empty memory — never clobber a live session (init runs once at boot, but guard so a
// stray re-init can't wipe in-flight state).
if (state.size > 0 || inboxEvents.length > 0) return
let doc: MirrorFile
try {
doc = JSON.parse(fs.readFileSync(file, 'utf-8')) as MirrorFile
} catch {
return // missing / unreadable / corrupt → empty (legacy behavior)
}
if (!doc || typeof doc !== 'object') return
const now = Date.now()
try {
// Main per-node state — apply the same expiry as buildFile so a stale "working" from a crashed
// session isn't resurrected past its window. This is what lets `prevState` survive the restart.
if (doc.nodes && typeof doc.nodes === 'object') {
for (const [id, e] of Object.entries(doc.nodes)) {
if (!e || typeof e !== 'object') continue
const updatedAt = typeof e.updatedAt === 'number' ? e.updatedAt : 0
// Hibernated entries survive the expiry, as in buildFile: hours of idleness is what the
// flag MEANS. (The renderer also re-reports its persisted set at boot — this restore just
// keeps the file honest in the window before that report lands.)
const expired = now - updatedAt > EXPIRE_MS && e.hibernated !== true
// Past EXPIRE_MS only the IDENTITY is restored (as buildFile would write it): the phone's
// chat view still needs the session id, the 6 h rule is about the state. Past the identity
// TTL, or with no identity at all, nothing is.
if (expired && (now - updatedAt > IDENTITY_EXPIRE_MS || (!e.agentId && !e.sessionId))) continue
state.set(id, {
...(expired ? { stateExpired: true as const } : { state: e.state }),
agentId: e.agentId,
sessionId: e.sessionId,
// Identity survives the restart like agentId/sessionId does — for a hand-launched
// claude it is the only record there is. SHAPE-CHECKED rather than trusted: this file
// can be hand-edited or written by another build, and a chip rendered off `{}` would
// read as "no account observed" while occupying the slot of one that was.
...(isObservedAccount(e.account) ? { account: e.account } : {}),
...(e.name ? { name: e.name } : {}),
...(e.hibernated === true ? { hibernated: true as const } : {}),
updatedAt,
// Marked, and FORCED unverified whatever the file said. `buildFile` writes neither field
// — it is an allowlist, which is what keeps `stateVerified` off disk — but a file this
// process did not write (hand-edited, downgraded, or from a future build) must not be
// able to hand gate 2 a proof nothing presented this run. See `restored`.
restored: true,
stateVerified: false
})
}
}
// Inbox feed — restore verbatim (already capped + carries `resolved` flags) so the
// approval/question title-dedup and the done-history survive. Ids continue monotonically from
// the max trailing `-<n>` seen (they are `${ts}-${seq}`; ts differs after a restart, so a
// collision is unlikely, but continuing the seq keeps them clean).
if (doc.inbox && Array.isArray(doc.inbox.events)) {
let events = doc.inbox.events.filter(
(e): e is InboxEvent => !!e && typeof e === 'object' && typeof e.id === 'string'
)
// Same per-node retention as the live cap (audit P2-7): a restored feed keeps each node's
// newest done + newest unresolved ask past the cut, so a restart doesn't strand a DONE card.
inboxEvents = trimInboxFeed(events, INBOX_EVENTS_CAP)
let maxSeq = 0
for (const e of inboxEvents) {
const m = /-(\d+)$/.exec(e.id)
if (m) maxSeq = Math.max(maxSeq, Number(m[1]))
}
inboxSeq = maxSeq
}
// Per-node "doing now" — restore fresh entries only (same expiry as flush()).
if (doc.inbox && doc.inbox.nodes && typeof doc.inbox.nodes === 'object') {
for (const [id, n] of Object.entries(doc.inbox.nodes)) {
if (!n || typeof n !== 'object') continue
const updatedAt = typeof n.updatedAt === 'number' ? n.updatedAt : 0
if (now - updatedAt > EXPIRE_MS) continue
inboxNodes.set(id, n)
}
}
} catch {
// Any shape surprise → keep whatever restored so far (fail-open, never throw at boot).
}
}
/**
* Point the mirror at its file and RESTORE its persisted state into memory. Called once from each
* shell on launch; the path defaults to `<userData>/agent-status.json`. Tests pass an explicit path
* (and thus never touch electron). The restore (see `loadPersisted`) is what makes the in-memory
* dedups survive a restart — without it, a re-produced `done` re-fires the push (the duplicate-APNs
* field bug).
*/
export function initAgentStatusMirror(filePath?: string): void {
targetFile = filePath ?? path.join(platform().userDataDir, 'agent-status.json')
loadPersisted(targetFile)
startStaleSweep()
}
function resolveFile(): string | null {
if (targetFile) return targetFile
try {
targetFile = path.join(platform().userDataDir, 'agent-status.json')
return targetFile
} catch {
return null
}
}
/**
* The stash-priority classification of a needs-you (blocked/waiting) event, computed once by
* `produceInboxFromState` and reused to ENRICH the event the shells broadcast. `kind` is what the
* inbox card was tagged; `pendingId` is the hook-reply ticket the card carries (present only for a
* genuine approval — a question strips it). Absent for non-needs-you events.
*/
interface NeedsYouClassification {
kind: 'question' | 'approval'
pendingId?: string
}
/**
* Fold a normalized agent event into the mirror (main state + inbox feed), schedule a debounced
* write, and RETURN the event the shells should broadcast — ENRICHED for a needs-you edge so the
* ONE stash-priority classification the mirror already computes is the single source of truth for
* the canvas too:
* - a `question` (fresh AskUserQuestion stash) gains `askKind:'question'` and has its `pendingId`
* STRIPPED — so TerminalNode's `blocked && pendingId` gate never renders approve/deny on a
* question (field report: the buttons showed during an AskUserQuestion);
* - a genuine `approval` gains `askKind:'approval'` and keeps its `pendingId` unchanged.
* Grok's state-less `StopCancelled` is projected here too, so the state folded into this mirror is
* the same state both shells broadcast; subagent/unknown cancellations retain their original
* identity-only event. Every other event passes through untouched (same reference). Called with
* EVERY normalized event by both shells.
*/
export function recordAgentEvent(rawEvent: NormalizedAgentEvent): NormalizedAgentEvent {
if (!rawEvent?.nodeId) return rawEvent
subagentReplay.record(rawEvent)
const ev = resolveGrokStopCancelled(rawEvent)
const nodeId = ev.nodeId
const now = Date.now()
const prev = state.get(nodeId)
const prevState = prev?.state
if (uncorrelatedStartIdle(prev, ev, now)) {
// Broadcast no state proof either: a renderer must not show this stale done as fresh.
return { nodeId, kind: 'state', agentId: prev?.sessionStarted?.agentId ?? ev.agentId, sessionId: prev?.sessionId }
}
const next = reduceEffectiveEntry(prev, ev, now)
state.set(nodeId, next)
const questionAnswered = !!prev?.pendingQuestion && !next.pendingQuestion &&
ev.sessionId === prev.pendingQuestion.sessionId && ev.answeredQuestionId === prev.pendingQuestion.toolUseId
if (questionAnswered || (ev.pendingId && ev.state === 'working')) {
for (const card of inboxEvents) {
if (card.nodeId !== nodeId) continue
if ((questionAnswered && card.kind === 'question') ||
(ev.pendingId && card.kind === 'approval' && card.pendingId === ev.pendingId)) card.resolved = true
}
}
if (next.concurrentApprovalIds?.length && !next.pendingQuestion) {
if (ev.kind !== 'state' && ev.kind !== 'session') {
scheduleWrite()
return ev
}
if (ev.pendingId && ev.state === 'blocked' && ev.askKind === 'approval') {
produceInboxFromState(nodeId, ev, prevState, 'blocked', now, true)
}
const pendingId = next.concurrentApprovalIds[next.concurrentApprovalIds.length - 1]
const card = inboxEvents.find(e => e.nodeId === nodeId && e.pendingId === pendingId && !e.resolved)
if (questionAnswered || (ev.pendingId && ev.state === 'working')) {
fireNodeStateChange({ nodeId, agentId: ev.agentId, sessionId: next.sessionId, ts: now,
event: 'update', state: 'needsYou', kind: 'approval', pendingId, message: card?.title ?? 'Needs approval' })
}
scheduleWrite()
return { ...ev, kind: 'state', state: 'blocked', sessionId: next.sessionId, askKind: 'approval', pendingId }
}
// reduceEntry held an unanswered `request_user_input` through its turn-end `done` — rewrite
// the broadcast to what the reducer decided, so every consumer (canvas store, notch, phone)
// agrees the node is still waiting rather than each re-deriving it from the raw done.
let out = ev
if (next.pendingQuestion && prev?.pendingQuestion && next.state) {
if (ev.kind !== 'state' && ev.kind !== 'session') return ev
// A concurrent permission is independent of the held picker. Publish its ticket/card,
// but keep the parent's waiting badge and question correlation until its own answer.
if (ev.pendingId && ev.state === 'blocked' && ev.askKind === 'approval') {
produceInboxFromState(nodeId, ev, prevState, 'blocked', now, true)
scheduleWrite()
return { ...ev, state: next.state, sessionId: next.sessionId }
}
scheduleWrite()
// Broadcast the same held state to Desktop, Server, canvas/board and the phone.
return { ...ev, kind: 'state', state: next.state, sessionId: next.sessionId,
verified: ev.verified, newTurn: undefined, interrupted: undefined,
askKind: 'question', pendingId: undefined }
}
if (ev.kind === 'state' && ev.state === 'done' && next.awaitingInput && next.state === 'waiting') {
out = { ...ev, state: 'waiting' }
}
const classification = produceInboxFromState(nodeId, out, prevState, next.state, now, false,
next.concurrentApprovalIds)
scheduleWrite()
if (!classification) return out
// Enrich the broadcast event from the SAME classification the inbox used. A question drops
// pendingId (approve/deny is wrong UX for a picker); an approval keeps ev.pendingId as-is.
if (classification.kind === 'question') return { ...out, askKind: 'question', pendingId: undefined }
return { ...out, askKind: 'approval' }
}
/**
* Inbox event production off a state transition (spec: mobile-usage-inbox). Reads the transition
* `prevState → nextState` that `reduceEntry` just computed (so the same done-holdoff / newTurn
* semantics gate the feed as gate the badge — no duplicate done inside a holdoff, no resurrection).
*/
function produceInboxFromState(
nodeId: string,
ev: NormalizedAgentEvent,
prevState: AgentState | undefined,
nextState: AgentState | undefined,
now: number,
concurrentApproval = false,
keepApprovalIds: readonly string[] = []
): NeedsYouClassification | undefined {
// Clear any stashed question options on a new turn or session boundary — a stale option set must
// never attach to a later, unrelated question. (State-leave clearing is handled below.)
if (ev.kind === 'session' || (ev.kind === 'state' && ev.state === 'working' && ev.newTurn)) {
pendingQuestions.delete(nodeId)
}
// Leaving needs-you (including a session reset to idle) resolves
// that node's pending approval/question cards; they move to the phone's archive.
if ((prevState === 'blocked' || prevState === 'waiting') && nextState !== 'blocked' && nextState !== 'waiting') {
resolveUnresolvedFor(nodeId)
pendingQuestions.delete(nodeId)
}
const baseEvent = { ts: now, nodeId, agentId: ev.agentId, sessionId: ev.sessionId }
const stateBase = { nodeId, agentId: ev.agentId, sessionId: ev.sessionId, ts: now }
// Working START edge (fresh turn / session open): a Live Activity begins here. reduceEntry's
// done-holdoff means a held-off late working keeps `nextState === 'done'`, so it never reaches
// here — no spurious 'start'.
if (nextState === 'working' && prevState !== 'working') {
// A genuine new turn carries the user's prompt — the "You: …" line every surface shows.
const prompt = ev.newTurn ? firstLine(ev.task, PROMPT_MAX) : ''
if (prompt) {
// Persist it too, so the phone's POLL path (which never sees push edges) reads the same line.
const cur = inboxNodes.get(nodeId)
inboxNodes.set(nodeId, { ...cur, prompt, updatedAt: now })
}
fireNodeStateChange({
...stateBase,
event: 'start',
state: 'working',
...(prompt ? { prompt } : {})
})
}
// approval/question dedup is TITLE-based (not edge-based): a re-asserted needs-you with the SAME
// ask is a no-op, but a genuinely different ask still lands — so the guard can't be a plain
// "same-state, skip". `done` alone is edge-guarded (one per turn).
if (nextState === 'blocked' || nextState === 'waiting') {
// STASH-PRIORITY CLASSIFICATION (fixes: AskUserQuestion always rendered as an approval on the
// phone). A pending AskUserQuestion picker reaches us as a permission-style signal — a
// PermissionRequest hook and/or a Notification `permission_prompt`, both of which normalize to
// `blocked` — even though it is a QUESTION with options, not an approve/deny. So when a fresh
// AskUserQuestion stash exists we produce a `question` (with its options) REGARDLESS of which
// needs-you state the CLI signaled; without a stash we keep today's mapping (blocked→approval,
// waiting→question).
const stash = freshStash(nodeId, now)
// Only a real AskUserQuestion picker (options present) forces the QUESTION classification — an
// approval-only stash (a PermissionRequest summary) must stay an approval.
const options = concurrentApproval ? undefined : stash?.options
// multiSelect rides only a real question (options present) — an approval-only stash never sets it.
const multiSelect = options ? stash?.multiSelect : undefined
const hasQuestion = !!options
const kind: 'approval' | 'question' = hasQuestion || nextState === 'waiting' ? 'question' : 'approval'
const approval = kind === 'approval' ? stash?.approval : undefined
// Title precedence: the stashed summary (AskUserQuestion's own question text for a question, or
// the PermissionRequest's "what's being approved" title for an approval) wins so the phone shows
// the real ask; else the last assistant line, else a kind-appropriate generic.
const title =
(hasQuestion ? stash?.question : approval?.title) ||
firstLine(ev.lastMessage, INBOX_TITLE_MAX) ||
(kind === 'approval' ? 'Needs approval' : 'Waiting for input')
// Detail (approval only — a question renders options, not a detail line). Precedence: the stashed
// summary detail, else the lastMessage line (today's fallback). Dropped when it merely repeats the
// title (the common no-stash case where both derive from lastMessage).
const rawDetail =
kind === 'approval'
? approval?.detail || firstLine(ev.lastMessage, INBOX_DETAIL_MAX) || undefined
: undefined
const detail = rawDetail && rawDetail !== title ? rawDetail : undefined
// pendingId (the deterministic hook-reply ticket) rides ONLY an approval. A stash-question
// suppresses it even when a PermissionRequest fired for the AskUserQuestion tool itself:
// approve/deny on a question is wrong UX — the phone answers with digit send-keys that drive
// the picker directly. That held PermissionRequest (if any) simply times out after 45s and the
// picker shows anyway (acceptable). See docs/hook-reply-approvals.md.
const pendingId = kind === 'approval' ? ev.pendingId : undefined
// needsYou live-update on the EDGE into the needs-you state (a re-assert of the SAME state
// keeps the activity live). Carries the classified kind + options (question) / pendingId
// (approval) so the Live Activity renders straight from this same code path
// (spec: interactive-push-live-activities addendum).
// The live-update headline folds the approval detail in (so Live Activities / push alerts read
// "Edit App.tsx — src/components/App.tsx +2 −2"); a question / detail-less approval is just the title.
const headline = clip(detail ? `${title} — ${detail}` : title, LIVE_MESSAGE_MAX)
// Dedup a re-asserted SAME ask (title match) — BOUNDED (QUESTION_DEDUP_WINDOW_MS): only an
// unresolved same-title event still inside the window suppresses. A stale lingering same-title one
// (restored across a restart, or a long-abandoned turn) is SUPERSEDED — marked resolved so it
// stops muzzling — and the new ask fires. A different-title unresolved event never suppresses:
// that is a genuinely NEW ask. Always return the classification below so the broadcast
// enrichment stays consistent across the re-assert.
const dup = concurrentApproval
? inboxEvents.find(e => e.nodeId === nodeId && e.kind === 'approval' && !e.resolved && e.pendingId === ev.pendingId)
: newestUnresolved(inboxEvents.filter(e =>
!(e.kind === 'approval' && e.pendingId && keepApprovalIds.includes(e.pendingId))), nodeId)
const sameTitle = !!dup && dup.title === title
const freshDup = sameTitle && dup ? now - dup.ts < QUESTION_DEDUP_WINDOW_MS : false
const newAsk = !freshDup
// The needs-you live-update fires on the edge INTO needs-you — and also whenever the ASK
// ITSELF changes while we stay there. An agent asks in sequence: you answer on the desktop, it
// immediately asks the next thing, and the state never leaves `blocked`. Firing only on the
// state edge left the Lock Screen / island showing the ANSWERED question, with its options and
// its hook-reply ticket — stale, and answerable into the wrong ask (field report: "cevap
// vermeme rağmen gitmiyor"). A re-asserted SAME ask still fires nothing.
if (prevState !== nextState || newAsk) {
fireNodeStateChange({
...stateBase,
event: 'update',
state: 'needsYou',
kind,
message: headline,
...(options ? { options } : {}),
...(multiSelect ? { multiSelect: true } : {}),
...(pendingId ? { pendingId } : {})
})
}
if (newAsk) {
// A new parent ask settles older parent asks, but child approval tickets are independent.
// Preserve those tickets while the parent proceeds to another picker; settle older questions
// even when the state never leaves needs-you between them.
if (!concurrentApproval) resolveUnresolvedFor(nodeId, keepApprovalIds)
pushInboxEvent({
...baseEvent,
kind,
title,
...(detail ? { detail } : {}),
...(options ? { options } : {}),
...(multiSelect ? { multiSelect: true } : {}),
...(pendingId ? { pendingId } : {})
})
}
return { kind, pendingId }
} else if (nextState === 'done' && prevState !== 'done') {
// The turn ended: emit one `done` on the edge into done (reduceEntry's holdoff keeps a late
// working from re-entering, and the normalizer collapses an Esc-spam into one done).
const detail = firstLine(ev.lastMessage, INBOX_DETAIL_MAX) || undefined
const title = ev.interrupted ? 'Stopped' : 'Finished'
fireNodeStateChange({
...stateBase,
event: 'end',
state: 'done',
message: title,
...(ev.interrupted ? { interrupted: true } : {})
})
pushInboxEvent({
...baseEvent,
kind: 'done',
title,
...(detail ? { detail } : {}),
...(ev.interrupted ? { interrupted: true } : {})
})
// A finished turn is no longer "doing" anything — clear its live activity line.
clearActivity(nodeId, now)
} else if (
nextState === undefined &&
prevState !== undefined &&
prevState !== 'done' &&
ev.kind === 'session' &&
ev.sessionPhase === 'end'
) {
// The CLI EXITED mid-turn (`/exit`, Ctrl-C, a crash) — the one transition that means "this
// session is over", and the only one that used to emit nothing at all.
//
// `reduceEntry` resets a session event to `state: undefined`, while every `end` above is keyed
// on the edge INTO `done` — so a node that was working or blocked when its agent quit produced
// none. It escaped the rescue too: `sweepStaleWorking` matches `state === 'working'`
// (isStaleWorking), which the reset had just stopped being true, so the 20-minute net written
// for exactly this failure was structurally bypassed. The phone was left holding a Live
// Activity nothing would ever end — a Lock Screen card stuck on "Working…", or worse on
// "Needs you" with Approve/Deny buttons whose hook ticket no longer exists — until iOS's own
// 8 h staleness.
//
// Deliberately narrow: only a session END (a SessionStart also resets to idle, and ending a
// card there would kill the activity of the turn just beginning), only when the node was
// actually mid-turn, and only when the done edge has not already spoken for it.
//
// No inbox card: a finished turn's card comes from the `done` edge, and this transition means
// the session went away, which is not itself news for the feed — the node's pending
// approval/question cards were already resolved by the leave-blocked/waiting branch above.
fireNodeStateChange({
...stateBase,
event: 'end',
state: 'done',
message: 'Ended'
})
clearActivity(nodeId, now)
}
}
/** Clear a node's live activity (keep any contextPercent). Idempotent; no-op if nothing set. */
function clearActivity(nodeId: string, now: number): void {
const n = inboxNodes.get(nodeId)
if (!n || (n.activity === undefined && n.prompt === undefined)) return
// The turn is over: both the tool line AND the "You: …" prompt describe work in progress.
inboxNodes.set(nodeId, { contextPercent: n.contextPercent, updatedAt: now })
}
/** Child hooks must not replace the parent transcript association while a picker is open. */
export function ignoreQuestionHook(nodeId: string, payload: Record<string, unknown>): boolean {
if (payload.agent_id) return true
const ask = state.get(nodeId)?.pendingQuestion
return !!ask && payload.hook_event_name !== 'SessionStart' &&
typeof payload.session_id === 'string' && payload.session_id !== ask.sessionId
}
/**
* Fold a RAW hook tool event into the per-node "what it's doing now" line (spec:
* mobile-usage-inbox). Called from the shells' `setRawListener` for claude events. PreToolUse sets
* the activity; Stop / SessionEnd clear it. Other events are ignored. Schedules a write only when
* the line actually changes (raw POSTs are bursty).
*/
export function recordRawToolEvent(nodeId: string, payload: Record<string, unknown>): void {
// Approval summaries must reach the phone even when the child transcript is excluded.
if (!nodeId || (payload.hook_event_name !== 'PermissionRequest' && ignoreQuestionHook(nodeId, payload))) return
const hook = typeof payload.hook_event_name === 'string' ? payload.hook_event_name : ''
const now = Date.now()
if (hook === 'PreToolUse') {
const toolName = typeof payload.tool_name === 'string' ? payload.tool_name : ''
if (!toolName) return
const toolInput =
payload.tool_input && typeof payload.tool_input === 'object'
? (payload.tool_input as Record<string, unknown>)
: undefined
// AskUserQuestion: stash the choice labels + the question text so the next needs-you event +
// push carry them and are classified as a `question` even when the CLI signals `blocked`
// (spec: interactive-push-live-activities; fixes AskUserQuestion-as-approval). Fail-open — a
// shape mismatch leaves no stash.
if (toolName === 'AskUserQuestion') {
const opts = extractQuestionOptions(toolInput)
if (opts)
pendingQuestions.set(nodeId, {
options: opts,
question: extractQuestionText(toolInput),
multiSelect: extractQuestionMultiSelect(toolInput),
at: now
})
}
const activity = toolActivity(toolName, toolInput)
const cur = inboxNodes.get(nodeId)
if (cur?.activity === activity && cur?.tool === toolName) return // no change
inboxNodes.set(nodeId, {
activity,
tool: toolName,
contextPercent: cur?.contextPercent,
prompt: cur?.prompt,
updatedAt: now
})
fireNodeNowChange({ nodeId, activity, contextPercent: cur?.contextPercent, ts: now })
scheduleWrite()
} else if (hook === 'PermissionRequest') {
// Stash a "what's being approved" summary derived from the tool call so the next needs-you
// approval event/push carries a real title + detail instead of a bare "Needs approval" (field
// report). The raw seam fires BEFORE the normalized blocked event that produces the card, so the
// stash is ready when produceInboxFromState reads it. Fail-open — a shape mismatch leaves no
// stash (the card falls back to lastMessage/generic). Merges onto any fresh AskUserQuestion
// stash so its option labels (the question signal) survive; a stale one is dropped by freshStash.
const toolName = typeof payload.tool_name === 'string' ? payload.tool_name : ''
if (!toolName) return
const toolInput =
payload.tool_input && typeof payload.tool_input === 'object'
? (payload.tool_input as Record<string, unknown>)
: undefined
const summary = buildApprovalSummary(toolName, toolInput)
if (!summary) return
const cur = freshStash(nodeId, now)
pendingQuestions.set(nodeId, { ...(cur ?? {}), approval: summary, at: now })
} else if (hook === 'Stop' || hook === 'SessionEnd') {
const before = inboxNodes.get(nodeId)?.activity
clearActivity(nodeId, now)
if (before !== undefined) {
fireNodeNowChange({ nodeId, activity: undefined, contextPercent: inboxNodes.get(nodeId)?.contextPercent, ts: now })
scheduleWrite()
}
}
}
/**
* Record a node's context-window fill (0–100) from the context-tail (spec: mobile-usage-inbox).
* Called where the shells broadcast IPC.contextUpdate. Schedules a write only on change.
*/
export function recordContextUsage(nodeId: string, percent: number): void {
if (!nodeId || typeof percent !== 'number' || !Number.isFinite(percent)) return
const clamped = Math.min(100, Math.max(0, percent))
const cur = inboxNodes.get(nodeId)
if (cur?.contextPercent === clamped) return
const now = Date.now()
inboxNodes.set(nodeId, {
activity: cur?.activity,
tool: cur?.tool,
contextPercent: clamped,
prompt: cur?.prompt,
updatedAt: now
})
fireNodeNowChange({ nodeId, activity: cur?.activity, contextPercent: clamped, ts: now })
scheduleWrite()
}
/**
* Remove a node (call on permanent destroy — the `×`/delete path, NOT an unmount, park, offscreen
* release or detach: those all leave the tmux session running and the node's status live). Its
* `nodes` entries (main + inbox activity) drop, but its inbox EVENTS stay as feed history — marked
* resolved so the phone archives them. Schedules a write so the file reflects the removal, and
* fires ONE end edge when the node was mid-turn (see below).
*/
export function clearNode(nodeId: string): void {
subagentReplay.clearParent(nodeId)
// Read BEFORE the delete — the end edge below is decided on the state the node died holding.
const prev = state.get(nodeId)
let changed = state.delete(nodeId)
if (inboxNodes.delete(nodeId)) changed = true
pendingQuestions.delete(nodeId)
// History stays; unresolved cards for a gone node can never be answered → archive them.
for (const e of inboxEvents) {
if (e.nodeId === nodeId && !e.resolved && (e.kind === 'approval' || e.kind === 'question')) {
e.resolved = true
changed = true
}
}
// A node deleted MID-TURN owes exactly one end edge, for the same reason the session-ended-
// mid-turn branch in `produceInboxFromState` does: dropping the map entry only makes the mirror
// FILE forget the node, while every LIVE surface is driven by this seam, not by the file. With
// no edge, deleting a working/blocked node left the notch HUD holding its needs-you/done row
// until the 6 h prune — its title collapsing to the literal 'Session' once the entry behind it
// was gone — and left the phone a Live Activity nothing would ever end.
//
// Only when it was actually mid-turn. An already-`done` node fired its own 'end' on the done
// edge, and an idle one (state undefined — never started, or reset by a session boundary) never
// opened a card at all; firing here would be a second 'end' for one card.
//
// No inbox event, by the same rule the mid-turn branch states: the node is GONE, so a feed card
// pointing at it is one the user can neither read nor act on. This is a dismissal, not news.
if (prev?.state && prev.state !== 'done') {
fireNodeStateChange({
nodeId,
...(prev.agentId ? { agentId: prev.agentId } : {}),
...(prev.sessionId ? { sessionId: prev.sessionId } : {}),
event: 'end',
state: 'done',
message: 'Ended',
ts: Date.now()
})
}
if (changed) scheduleWrite()
}
/**
* ACK a node's finished turn: the desktop/browser user READ the finished session (spec: the
* unread-clear funnel in the renderer, gated on the node's latest state being `done`). Two effects,
* both cross-surface:
* - marks the node's UNRESOLVED `done` inbox event(s) `resolved:true` so the phone's Inbox archives
* the card on its next mirror poll (schedules a flush);
* - fires ONE onNodeStateChange 'end' edge (state 'done', `ack:true`) so the live-update push
* (createLiveUpdatePush) POSTs an 'end' the backend fans out to the phone, dismissing the
* lingering DONE Live Activity. The natural turn-end already sent an 'end' at done-time; this
* re-sends it on the READ, which is what actually clears an activity ActivityKit's dismissal
* policy kept on the lock screen.
* NO-OP when the node has no unresolved done event (a stray/duplicate ack — e.g. a second read, or a
* working-state focus that slipped the renderer gate — fires no seam and schedules no write). Pure
* apart from the seam + write; `now` is Date.now for parity with the rest of the module.
*/
/**
* Publish a node's resolved session name into the mirror (the session-name sweep's only writer).
* A no-op when nothing changed or the node is unknown — the sweep asks for the entries first, so
* an unknown id here just means it went away mid-pass. Never touches `updatedAt`: this is not a
* state assertion, and bumping it would defeat the freshness/expiry rules.
*/
export function setNodeSessionName(nodeId: string, name: string): boolean {
const e = state.get(nodeId)
if (!e || !name || e.name === name) return false
state.set(nodeId, { ...e, name })
scheduleWrite()
return true
}
/**
* Record (or clear) a node's Eco hibernation flag — the `agent:hibernated` cast's only writer.
* The renderer owns the flag; this is a mirror of it, like `terminalFocused` in main (see
* MirrorEntry.hibernated). Unlike `setNodeSessionName`, an UNKNOWN node id creates a minimal
* entry: a hibernated session is typically one the mirror has expired (hibernation is hours of
* idleness) or one reported at boot before any hook event of this run — exactly when the flag
* matters most. Clearing an unknown id stays a no-op.
*/
export function setNodeHibernated(nodeId: string, on: boolean): void {
if (typeof nodeId !== 'string' || !nodeId || nodeId.length > 128) return
const e = state.get(nodeId)
if (on) {
if (e?.hibernated) return
state.set(nodeId, e ? { ...e, hibernated: true } : { updatedAt: Date.now(), hibernated: true })
} else {
if (!e?.hibernated) return
const next = { ...e }
delete next.hibernated
state.set(nodeId, next)
}
scheduleWrite()
}
/**
* Seed IDENTITY for nodes the mirror has no session for — the `agent:seed-identity` cast's only
* writer. The renderer's agentStatus store keeps each node's `sessionId`/`agentId` in localStorage
* indefinitely, while this mirror learns them only from hook events; a node idle since before this
* app run (or whose entry was dropped before identity outlived the state) is therefore absent here,
* and the phone — which finds a transcript only by the session id it reads off this file — showed
* "No conversation yet" until the next prompt fired a hook.
*
* The rules, each a refusal:
* - validated by `parseIdentitySeed` (bounded count, safe ids — the values come from hand-editable
* localStorage and the ids are shell-reaching elsewhere);
* - a node the workspace does not know is skipped (a deleted node's stale localStorage entry must
* not be advertised); an unknowable workspace (`undefined`) accepts, bounded by the identity TTL
* and the renderer's own filter;
* - an entry that already carries a `sessionId` is NEVER touched — a hook-fed id is fresher than
* anything localStorage remembers — and neither is one whose `agentId` disagrees;
* - an entry holding a STATE is never filled either, even with no session id: a seeded id is
* last-known and possibly stale, and beside a live state it would read as the id of the session
* that state belongs to (the phone's permission-dialog guard reads it exactly so);
* - a STATELESS entry with no session id (the boot replay's hibernated-only entry, a restored
* stateless one) gets its identity filled, nothing else;
* - a new entry is the IDENTITY-ONLY shape (`stateExpired`, no state, no proof) with `updatedAt`
* set just past EXPIRE_MS, so it reads as OLD to every freshness check. That matters because
* `stateExpired` is not persisted: restored after a restart it is re-derived from the age, so a
* fresh `updatedAt` would come back as a plain stateless entry and join the session-name sweep
* (a transcript read per pass, over ssh for a remote node). The identity TTL then runs from the
* seed — but the renderer re-seeds whenever the entry has been pruned, so in practice the
* identity lives as long as the node and its localStorage entry do.
* Returns how many entries changed. Schedules a write (and so an SSH slice push) only then.
*/
export function seedNodeIdentities(input: unknown): number {
const entries = parseIdentitySeed(input)
if (entries.length === 0) return 0
const liveIds = safeLiveNodes()
const now = Date.now()
let changed = 0
for (const s of entries) {
if (liveIds && !liveIds.has(s.nodeId)) continue
const e = state.get(s.nodeId)
if (e) {
if (e.sessionId || e.state) continue
if (e.agentId && e.agentId !== s.agentId) continue
state.set(s.nodeId, {
...e,
agentId: s.agentId,
sessionId: s.sessionId,
...(!e.account && s.account ? { account: s.account } : {})
})
} else {
state.set(s.nodeId, {
agentId: s.agentId,
sessionId: s.sessionId,
...(s.account ? { account: s.account } : {}),
updatedAt: now - EXPIRE_MS - 1,
stateExpired: true
})
}
changed++
}
if (changed > 0) scheduleWrite()
return changed
}
/** A node's published session name (see MirrorEntry.name), or undefined. */
export function nodeSessionName(nodeId: string): string | undefined {
return state.get(nodeId)?.name
}
/** Shared Desktop/Server transcript rescue. An unrelated result is never an answer. */
export function recordQuestionResult(
nodeId: string, sessionId: string, toolUseId: string
): NormalizedAgentEvent | undefined {
const ask = state.get(nodeId)?.pendingQuestion
if (!ask || ask.sessionId !== sessionId || ask.toolUseId !== toolUseId) return
return recordAgentEvent({ nodeId, agentId: 'claude', sessionId, kind: 'state',
state: 'working', answeredQuestionId: toolUseId })
}
/**
* A Claude transcript recorded an interrupt marker (`parseTurnInterrupts`) for turn `turnId`: the
* event that ends the node's turn, or undefined when the marker is not about the CURRENT turn.
*
* Claude Code sends NO hook when the user interrupts a turn — Esc while it streams, runs a tool or
* shows a permission dialog, or Ctrl+C once (measured on 2.1.285,
* `shared/agents/__fixtures__/claude/interrupt-capture.json`) — and its `idle_prompt` notification,
* which the `idle` rescue listens for, fires after a normal turn but not after an interrupted one.
* Without this the node sat on RUNNING (or NEEDS YOU, for a dismissed dialog) until the 20-minute
* stale sweep: `--after` dependents waited, Eco never saw it idle, the phone showed it working.
*
* It ends the turn only when the marker names the turn the node is in NOW (same session, same
* `turnId`, state still working/blocked/waiting): a marker the tail reads back from history, one
* from a turn that already ended, one from another session, or one arriving after a restart
* (turnId is runtime-only) changes nothing. The id match is only HALF the safety story: on "queue a
* message, then Esc" the CLI tags the marker with the QUEUED prompt's id, which is the current turn
* by then — the tail's scanner therefore drops a marker whose turn it has not seen OPENED before it
* (`createTurnInterruptScanner`, context-tail.ts).
*
* The event is an ordinary interrupted `done` — the shape a `Stop` with `is_interrupt` already
* produced — so every consumer handles it with the rules it already has (no completion alert,
* the question/approval resets). It carries no `verified`: a transcript read is not a hook POST.
*/
export function turnInterruptEvent(
nodeId: string, sessionId: string, turnId: string
): NormalizedAgentEvent | undefined {
const e = state.get(nodeId)
if (!e || e.sessionId !== sessionId || !e.turnId || e.turnId !== turnId) return
if (e.state !== 'working' && e.state !== 'blocked' && e.state !== 'waiting') return
return { nodeId, agentId: e.agentId ?? 'claude', sessionId, kind: 'state', state: 'done', interrupted: true }
}
/** `turnInterruptEvent`, recorded. The shells do NOT call this: they push `turnInterruptEvent`'s
* event through their normal hook-event path, so every consumer of that stream (the Notch HUD,
* agent messaging's receipt watch, station notices, the Server Edition's delivery queue and
* `--after` scheduler) sees the interrupt exactly as it sees a hook. */
export function recordTurnInterrupt(
nodeId: string, sessionId: string, turnId: string
): NormalizedAgentEvent | undefined {
const ev = turnInterruptEvent(nodeId, sessionId, turnId)
return ev ? recordAgentEvent(ev) : undefined
}
/** A node's current main state, or undefined when unknown. Read-only peek for the shells. */
export function nodeState(nodeId: string): AgentState | undefined {
return state.get(nodeId)?.state
}
/**
* The full mirror entry for one node — agent messaging's gate 2 reads this (state, `stateVerified`,
* `restored`, `idleInferred`, `clientRevision`) through `DeliveryDeps.mirrorEntry`. Read-only by
* contract: the reference is live, and a caller that mutates it is corrupting the mirror.
*/
export function mirrorEntry(nodeId: string): MirrorEntry | undefined {
return state.get(nodeId)
}
/**
* Every mirror entry, as a fresh array of `[nodeId, entry]` — the `agent:status-snapshot` a late
* relay tab starts from reads it (core/agent-status-snapshot.ts). Read-only by contract, like
* `mirrorEntry`: the array is a copy, the entries are the live ones.
*/
export function mirrorEntries(): ReadonlyArray<readonly [string, Readonly<MirrorEntry>]> {
return [...state]
}
/**
* Every node whose CURRENT agent session is `sessionId` (usually one; a session resumed in two nodes
* is two). Read-only peek: the relay access policies attribute a `context:update` — keyed by the
* agent session, not the node — to the nodes it describes, so a peer limited to some projects
* receives a meter only for a session that runs in one of them.
*/
export function nodesForAgentSession(sessionId: string): string[] {
const out: string[] = []
if (typeof sessionId !== 'string' || !sessionId) return out
for (const [nodeId, e] of state) if (e.sessionId === sessionId) out.push(nodeId)
return out
}
/**
* The nodes the mirror currently believes are `working`, with the identity a synthetic event needs.
* Read-only peek for the shells — the reconnect resync asks the host about exactly these, because
* `working` is the only state a lost hook event can strand (see remote-ssh/agent-resync-decide.ts).
*/
export function workingNodes(): { nodeId: string; agentId?: string; sessionId?: string }[] {
const out: { nodeId: string; agentId?: string; sessionId?: string }[] = []
for (const [nodeId, e] of state) {
if (e.state === 'working') out.push({ nodeId, agentId: e.agentId, sessionId: e.sessionId })
}
return out
}
/**
* The entries the session-name sweep walks: id + what it needs to resolve and dedupe.
*
* Identity-only entries (`stateExpired`) are left out: before they existed the sweep only ever saw
* nodes active within EXPIRE_MS, and keeping it there keeps its cost (a transcript read — over ssh
* for a remote node — per node per pass) where it was. A node that has done nothing for 6 h has not
* been renamed either; a `/rename` is a prompt, whose hook re-grows the state and re-admits it.
*/
export function sessionNameSweepEntries(): {
nodeId: string
sessionId?: string
agentId?: string
name?: string
}[] {
// NB: the Server Edition's context-link sweep also reads this list (src/server/context-link.ts,
// `agentSessions` default), so it too sees only nodes active within EXPIRE_MS — the same set it
// saw before identity-only entries existed; giving it their session ids is a separate change.
return [...state].filter(([, e]) => !e.stateExpired).map(([nodeId, e]) => ({
nodeId,
sessionId: e.sessionId,
agentId: e.agentId,
name: e.name
}))
}
export function ackDone(nodeId: string): void {
if (!nodeId) return
let latest: InboxEvent | undefined
for (const e of inboxEvents) {
if (e.nodeId === nodeId && e.kind === 'done' && !e.resolved) {
e.resolved = true
latest = e // feed is oldest→newest, so the last match is the newest done
}
}
if (!latest) return
fireNodeStateChange({
nodeId,
agentId: latest.agentId,
sessionId: latest.sessionId,
event: 'end',
state: 'done',
ack: true,
ts: Date.now()
})
scheduleWrite()
}
/**
* The one place that decides a `working` session is gone (shared/agents/stale.ts).
*
* For each node that has been `working` with no event for `staleMs`: move the entry off working and
* fire ONE synthetic end edge, marked `stale` so no consumer treats it as an achievement. Every
* surface that already listens to `onNodeStateChange` inherits the fix — the notch drops the row,
* the phone's Live Activity ENDS instead of sitting on the Lock Screen until iOS's 8 h staleness.
*
* Deliberately NOT done here: no inbox event is pushed (nothing finished, so there is nothing to
* show in the feed or to notify about), and `updatedAt` is left alone — falsifying it would both
* rewrite history and arm the 3 s done-holdoff, which would swallow a real event arriving right
* after a wrong guess. The sweep is self-healing: one later event puts the node back to `working`.
*
* Returns the swept node ids (empty when nothing was stale). `now`/`staleMs` injected for tests.
*/
export function sweepStaleWorking(
now: number = Date.now(),
staleMs: number = WORKING_STALE_MS
): string[] {
const swept: string[] = []
for (const [nodeId, e] of state) {
if (!isStaleWorking(e.state, e.updatedAt, now, staleMs)) continue
state.set(nodeId, { ...e, state: 'done' })
clearActivity(nodeId, now)
swept.push(nodeId)
fireNodeStateChange({
nodeId,
...(e.agentId ? { agentId: e.agentId } : {}),
...(e.sessionId ? { sessionId: e.sessionId } : {}),
event: 'end',
state: 'done',
message: 'Stopped',
stale: true,
ts: now
})
}
return swept
}
function startStaleSweep(): void {
if (sweepTimer) return
sweepTimer = setInterval(() => {
if (sweepStaleWorking().length > 0) scheduleWrite()
}, STALE_SWEEP_MS)
sweepTimer.unref?.()
}
function scheduleWrite(): void {
if (writeTimer) return
writeTimer = setTimeout(() => {
writeTimer = null
void flush()
}, WRITE_DEBOUNCE_MS)
// Never let the mirror keep the app alive on quit.
writeTimer.unref?.()
}
/** Prune + atomically write the file (tmp + rename, mode 0600). Best-effort. */
export async function flush(): Promise<void> {
const file = resolveFile()
if (!file) return
const now = Date.now()
// Age out inbox events on the SAME 6 h horizon as the two prunes below, applied to RESOLVED and
// UNRESOLVED alike. Until this existed the feed's only bound was INBOX_EVENTS_CAP, so an
// unresolved approval on a node nobody ever came back to stayed a red "Needs you" card with the
// tray badge lit forever — a node abandoned mid-approval emits nothing further, so neither the
// state-leave `resolveUnresolvedFor` nor the 50-event cap would ever reach it.
//
// One window for both kinds, deliberately:
// - UNRESOLVED must not get a SHORTER one. An agent can legitimately sit blocked on a human for
// hours, and this card (with its `pendingId` ticket) is how the phone answers the hook that is
// still holding open. Cutting it early would trade a stale badge for lost functionality, which
// is the worse bug.
// - RESOLVED must not get a LONGER one. It is the phone's archive, but the phone keeps its own
// copy of what it has read; this file is a live side-channel, not the archive of record, and
// the cap already bounds history.
// 6 h is the horizon at which the module stops believing anything about a node's STATE (only its
// identity survives it), so an event outliving `state`/`inboxNodes` would be a card about a state
// the mirror has forgotten.
// Well clear of QUESTION_DEDUP_WINDOW_MS (10 min), so the title-dedup is untouched.
//
// Pruned BEFORE the doc is built, unlike the two below: `buildFile` applies the expiry to `nodes`
// itself but passes `inbox` through verbatim, so pruning after it would leave the aged card in
// the FILE for one more flush — and an abandoned node schedules no further writes, so "one more
// flush" can be never.
if (inboxEvents.some((e) => now - e.ts > EXPIRE_MS)) {
inboxEvents = inboxEvents.filter((e) => now - e.ts <= EXPIRE_MS)
}
// Age memory FIRST, with the same rule buildFile applies: an expired state is stripped to its
// identity (so no in-process reader — messaging, triggers, the resync — sees a 6 h-old state),
// and an identity past its TTL or for a node that no longer exists is dropped, so the map itself
// can't grow without bound.
// Ask for the live node set only when some entry is past EXPIRE_MS: only those can be pruned by
// existence, and the provider scans every project (it runs on every flush otherwise — each event
// burst plus the 60 s heartbeat).
let anyExpired = false
for (const e of state.values()) {
if (!e.hibernated && now - e.updatedAt > EXPIRE_MS) {
anyExpired = true
break
}
}
const liveIds = anyExpired ? safeLiveNodes() : undefined
for (const [id, e] of state) {
const aged = ageEntry(id, e, now, EXPIRE_MS, liveIds)
if (!aged) state.delete(id)
else if (aged !== e) state.set(id, aged)
}
const inbox: MirrorInbox = { events: inboxEvents, nodes: Object.fromEntries(inboxNodes) }
const doc = buildFile(Object.fromEntries(state), now, undefined, safeSettings(), safeUsage(), inbox, safeServer(), liveIds)
// Prune stale per-node activity the same way (events stay — they are capped feed history).
for (const [id, n] of inboxNodes) if (now - n.updatedAt > EXPIRE_MS) inboxNodes.delete(id)
for (const cb of flushListeners) {
try {
cb(doc)
} catch {
// A listener must never break the local write (or its sibling listeners).
}
}
try {
await writeFileAtomic(file, JSON.stringify(doc), { mode: 0o600 })
} catch {
// best-effort: listeners already got the doc; a failed local write cleans up its own temp
}
}
// ---- Test helpers --------------------------------------------------------------------------
/** Reset all module state (in-memory map + config + listeners + inbox). Test-only. */
export function _resetForTest(): void {
subagentReplay.clear()
state.clear()
if (sweepTimer) clearInterval(sweepTimer)
sweepTimer = null
targetFile = null
if (writeTimer) clearTimeout(writeTimer)
writeTimer = null
flushListeners.clear()
settingsProvider = null
usageProvider = null
serverProvider = null
liveNodesProvider = null
inboxEvents = []
inboxNodes.clear()
inboxSeq = 0
inboxActionableListeners.clear()
nodeStateChangeListeners.clear()
nodeNowChangeListeners.clear()
pendingQuestions.clear()
}
/** Snapshot the in-memory map. Test-only. */
export function _snapshot(): Record<string, MirrorEntry> {
return Object.fromEntries(state)
}
/** Snapshot the in-memory inbox. Test-only. */
export function _inboxSnapshot(): MirrorInbox {
return { events: inboxEvents.map((e) => ({ ...e })), nodes: Object.fromEntries(inboxNodes) }
}