Skip to content

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

fix(station-notice): address the #1017 review — stale DROPPED, question-only waits, pane leg to its end

review71f4e4951336
diff --git a/CLAUDE.md b/CLAUDE.md
index bff2eef62..bbeb59be4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -3563,18 +3563,35 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile
with its options (retry or wait / reassign / skip / stop), instead of having to poll `list`.
Load-bearing rules:
- **The trigger is a closed table (`STATION_TRIGGERS`), first match wins:** `dropped` (the
- renderer's DROPPED verdict), `turn-errored` (a verified `done` carrying `errored` — the
- `lastTurnError` rule recomputed over the hook stream), `blocked-unanswered` (blocked/waiting
- continuously for `STATION_BLOCKED_NOTICE_MS` = 15 min, measured from the TRANSITION, AND the
- recipient's own verified state is `done`). An unknown never triggers, and only VERIFIED events
- move a station: a notice leads an orchestrator to retry, reassign or END a workflow, so a
- forgeable event is not evidence. Blocked is 15 min because the human already got NEEDS YOU + a
- notification; an orchestrator reassigning seconds before the user approves doubles the work.
+ renderer's DROPPED verdict, about a station core does not know to be mid-turn or asking),
+ `turn-errored` (a verified `done` carrying `errored`; a verified new turn OR a clean `done`
+ retires it — it describes the LAST turn), `question-unanswered` (the status mirror still holds
+ the station's correlated `pendingQuestion` 15 min after the verified event that asked it,
+ `STATION_QUESTION_NOTICE_MS`, AND the recipient's own verified state is `done`). An unknown
+ never triggers, and only VERIFIED events move a station: a notice leads an orchestrator to
+ retry, reassign or END a workflow, so a forgeable event is not evidence. 15 min because the
+ human already got NEEDS YOU + a notification; an orchestrator reassigning seconds before the
+ user answers doubles the work.
+ - **A permission prompt is NEVER a trigger, and that is a measurement, not caution.** On the main
+ thread Claude paints its dialog CONCURRENTLY with our held hook (docs/hook-reply-approvals.md),
+ and an approval given in the pane fires nothing until the approved tool FINISHES — so neither
+ `blocked` nor a `pendingId` can tell "unanswered" from "approved, twenty-minute build running",
+ and a notice there invites the orchestrator to close a working station. A question can be told
+ apart: its answer is a tool result, and the mirror's `pendingQuestion` is held across unrelated
+ traffic until it arrives. The monitor reads it through `pendingQuestionOf` (required dep)
+ rather than re-deriving it.
- **Once per episode, re-armed ONLY by a successful turn** — a turn that started after the notice
- and ended `done` with no error, no interruption and not the idle-prompt rescue. The condition
- merely clearing does not re-arm: a usage-limited station fails again on every retry, and
- re-notifying each time would be a loop that burns the orchestrator's turns all night. The
- notice says so in its own text.
+ and ended `done` with no error, no interruption and not the idle-prompt rescue — and the re-arm
+ clears every fact the episode was about (error, DROPPED, question), or the next sweep re-fires
+ it. The condition merely clearing does not re-arm: a usage-limited station fails again on
+ every retry, and re-notifying each time would be a loop that burns the orchestrator's turns
+ all night. The notice says so in its own text.
+ - **Core withdraws DROPPED itself, on ANY verified hook event from the node** (the CLI speaking
+ from inside the pane — the renderer's own self-heal in `agentStatus.setState`). It must not
+ wait for the renderer's `reportDropped(false)`: the renderer's record of what it reported and
+ its transient flag both die with a reload (⌘R, a Server Edition tab closing), and a verdict
+ nobody withdraws re-fired on the healthy station after its next successful turn — typed into
+ the orchestrator with "reassign: close it" as an option (the independent review's blocker).
- **The recipient is the OPENER, and a rope alone cannot name it.** An `--after` station is roped
to every station it waited on as well as to its opener, with the same `ctrl-<src>-<dst>` id, so
"the other end of the rope" can be a sibling that opened nothing. The open verbs therefore
@@ -3597,7 +3614,14 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile
`agentMessaging` switch — off by default ⇒ canvas only — runtime pane ownership, flow limits,
idle gate + deliver-on-idle queue, receipt, trace) under an internal verb
`STATION_NOTICE_VERB` that is deliberately NOT in `AGENT_MESSAGE_VERBS`, so neither the IPC
- guard nor the shim can ask for a notice with a body of its choosing. Two differences from
+ guard nor the shim can ask for a notice with a body of its choosing. The pane leg is followed to
+ its END so the chip never says "queued" about a message that landed or lapsed: a queued
+ notice's flush or expiry comes back through `AgentMessagingDeps.onQueuedResult` (called from
+ `createDeliveryQueue`, read at call time). Two outcomes get exactly ONE more attempt, each
+ because it would otherwise lose the pane leg for a reason unrelated to the notice:
+ `rateLimited` (the station `send`s its result, then errors seconds later — the pair budget is
+ spent) retries after the limiter's wait, capped at 60 s; an expiry (the orchestrator stayed busy
+ past the queue's 5-min TTL) is offered again on the orchestrator's next verified `done`. Two differences from
`send`, both because the APP is the author: the body is `stationNoticeBody` (fixed text from
the table; the only station-influenced string is the title, `oneLine`d, capped at 80, quoted,
and labelled data — NO station output is ever quoted), and the Server Edition's creator check
@@ -3605,8 +3629,10 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile
deliberate: the app typing into an agent's session is the capability that switch grants.
- **DROPPED is the renderer's fact** (it needs `hibernated`/`paused`), forwarded as EDGES by
`lib/stationNoticeWiring.ts` over `stationNotice.reportDropped`; the monitor never measures a
- pane. That channel is in `HOST_ONLY_CHANNELS`: a relay guest never measured the host's panes
- (its tab takes the inert stub), so a raw report from one is a spoofed verdict. It is therefore only as available as the liveness check, which asks for WATCHED nodes:
+ pane. Both request channels are in `HOST_ONLY_CHANNELS`: a relay guest never measured the
+ host's panes (its tab takes the inert stub), so a raw DROPPED report from one is a spoofed
+ verdict, and `station-notice:list` is unscoped — every project's failed-station ids and titles
+ — which a guest bound to one project must not read. It is therefore only as available as the liveness check, which asks for WATCHED nodes:
a station that dies off screen is noticed when it next comes into view, and a Server Edition
with no browser tab attached reports no DROPPED at all. Widening the check to unwatched
stations costs one pane read per finished station per 30 s (an ssh exec on SSH projects) and
diff --git a/src/core/agents/agent-messaging.ts b/src/core/agents/agent-messaging.ts
index 23676bc5d..d7a816c4b 100644
--- a/src/core/agents/agent-messaging.ts
+++ b/src/core/agents/agent-messaging.ts
@@ -134,6 +134,13 @@ export interface AgentMessagingDeps {
* injected. Absent ⇒ never hibernated, and only a `targetBusy` refusal queues.
*/
isHibernated?(nodeId: string): boolean
+ /**
+ * How a QUEUED delivery finally ended: its flush outcome, or `expired`. Absent ⇒ nobody asks. The
+ * station-failure monitor uses it so a queued notice's chip reports what actually happened rather
+ * than "queued" forever (station-notice.ts); read at call time, so a shell may assign it after
+ * `createDeliveryQueue` has run.
+ */
+ onQueuedResult?(req: QueuedDeliveryRequest, outcome: AgentMessageOutcome): void
}
/**
@@ -260,8 +267,18 @@ export function createDeliveryQueue(
now
}),
// The sender leg: a durable line where the sender's operator will see it.
- onExpired: (req) => senderBoardLog(req, 'expired'),
- onFlushed: (req, outcome) => senderBoardLog(req, outcome.kind),
+ onExpired: (req, info) => {
+ senderBoardLog(req, 'expired')
+ deps.onQueuedResult?.(req, {
+ kind: 'expired',
+ traceId: info.traceId,
+ queuedForMs: info.queuedForMs
+ })
+ },
+ onFlushed: (req, outcome) => {
+ senderBoardLog(req, outcome.kind)
+ deps.onQueuedResult?.(req, outcome)
+ },
// Injected so a test pins TTL expiry deterministically; production uses the default setTimeout.
...(opts.schedule ? { schedule: opts.schedule } : {})
},
diff --git a/src/core/agents/station-notice.test.ts b/src/core/agents/station-notice.test.ts
index e166c3ee7..85f84a6b8 100644
--- a/src/core/agents/station-notice.test.ts
+++ b/src/core/agents/station-notice.test.ts
@@ -12,7 +12,7 @@ import {
type StationNoticeEvent
} from './station-notice'
import {
- STATION_BLOCKED_NOTICE_MS,
+ STATION_QUESTION_NOTICE_MS,
stationNoticeBody,
stationRecipient,
type StationCanvas,
@@ -20,8 +20,10 @@ import {
} from '../../shared/station-notice'
import type { BoardLogEntry } from '../../shared/types'
import {
+ createDeliveryQueue,
deliverStationNotice,
isDeliverRequest,
+ onMessagingAgentEvent,
type AgentMessagingDeps
} from './agent-messaging'
import { resetMessageFlow } from './agent-message-flow'
@@ -55,29 +57,40 @@ interface Harness {
published: StationNoticeView[][]
delivered: { stationNodeId: string; recipientNodeId: string; body: string }[]
clock: { now: number }
+ /** What the status mirror holds unanswered, per node (`pendingQuestion.toolUseId`). */
+ questions: Map<string, string>
+ /** Timers the monitor scheduled, run by hand. */
+ timers: { ms: number; fn: () => void }[]
}
-function harness(over: Partial<StationNoticeDeps> = {}, outcome?: AgentMessageOutcome): Harness {
+const QUEUED: AgentMessageOutcome = { kind: 'queued', position: 1, ttlMs: 1, traceId: 't' }
+
+/** `outcomes` are answered in order (the last one repeats); default: always queued. */
+function harness(over: Partial<StationNoticeDeps> = {}, outcomes: AgentMessageOutcome[] = [QUEUED]): Harness {
const clock = { now: 1_000_000 }
const logs: Harness['logs'] = []
const published: Harness['published'] = []
const delivered: Harness['delivered'] = []
+ const questions = new Map<string, string>()
+ const timers: Harness['timers'] = []
const monitor = new StationNoticeMonitor({
now: () => clock.now,
recipientFor: (id) => stationRecipient(canvases(), id),
+ pendingQuestionOf: (id) => questions.get(id),
appendBoardLog: async (projectId, entry) => {
logs.push({ projectId, entry })
return true
},
deliver: async (n) => {
delivered.push(n)
- return outcome ?? { kind: 'queued', position: 1, ttlMs: 1, traceId: 't', traced: 'memory' }
+ return outcomes[Math.min(delivered.length - 1, outcomes.length - 1)]
},
publish: (views) => published.push(views),
exists: () => true,
+ schedule: (ms, fn) => void timers.push({ ms, fn }),
...over
})
- return { monitor, logs, published, delivered, clock }
+ return { monitor, logs, published, delivered, clock, questions, timers }
}
const ev = (nodeId: string, over: Partial<StationNoticeEvent> = {}): StationNoticeEvent => ({
@@ -120,11 +133,16 @@ describe('each trigger tells the opener', () => {
])
})
- it('blocked-unanswered: past the threshold, and only once the orchestrator is idle', async () => {
+ const ask = (h: Harness, id = 'q1'): void => {
+ h.questions.set('st1', id) // the mirror records the question first (recordAgentEvent)…
+ h.monitor.onAgentEvent(ev('st1', { state: 'waiting', questionId: id })) // …then the monitor sees it
+ }
+
+ it('question-unanswered: past the threshold, and only once the orchestrator is idle', async () => {
const h = harness()
h.monitor.onAgentEvent(ev('orch', { state: 'working' }))
- h.monitor.onAgentEvent(ev('st1', { state: 'blocked' }))
- h.clock.now += STATION_BLOCKED_NOTICE_MS - 1
+ ask(h)
+ h.clock.now += STATION_QUESTION_NOTICE_MS - 1
h.monitor.sweep()
expect(h.delivered).toEqual([])
h.clock.now += 1
@@ -135,21 +153,44 @@ describe('each trigger tells the opener', () => {
h.monitor.sweep()
await flush()
expect(h.delivered.map((d) => d.body)).toEqual([
- stationNoticeBody({ id: 'st1', title: 'Worker' }, 'blocked-unanswered')
+ stationNoticeBody({ id: 'st1', title: 'Worker' }, 'question-unanswered')
])
})
- it('a same-state event does not restart the needs-you clock', async () => {
+ it('unrelated traffic while the question stands does not restart its clock', async () => {
const h = harness()
h.monitor.onAgentEvent(ev('orch', { state: 'done' }))
- h.monitor.onAgentEvent(ev('st1', { state: 'waiting' }))
- h.clock.now += STATION_BLOCKED_NOTICE_MS / 2
- h.monitor.onAgentEvent(ev('st1', { state: 'blocked' })) // still needs-you: same episode of waiting
- h.clock.now += STATION_BLOCKED_NOTICE_MS / 2
+ ask(h)
+ h.clock.now += STATION_QUESTION_NOTICE_MS / 2
+ // A child's permission request lands on the parent node; the mirror still holds the question.
+ h.monitor.onAgentEvent(ev('st1', { state: 'blocked' }))
+ h.clock.now += STATION_QUESTION_NOTICE_MS / 2
h.monitor.sweep()
await flush()
expect(h.delivered).toHaveLength(1)
})
+
+ it('an answered question (the mirror dropped it) is never reported', async () => {
+ const h = harness()
+ h.monitor.onAgentEvent(ev('orch', { state: 'done' }))
+ ask(h)
+ h.questions.delete('st1') // the tool result arrived; the node then idles without a new event here
+ h.clock.now += STATION_QUESTION_NOTICE_MS * 2
+ h.monitor.sweep()
+ await flush()
+ expect(h.delivered).toEqual([])
+ })
+
+ it('a PERMISSION prompt is never reported, however long it stands (approved in-pane looks the same)', async () => {
+ const h = harness()
+ h.monitor.onAgentEvent(ev('orch', { state: 'done' }))
+ h.monitor.onAgentEvent(ev('st1', { state: 'blocked' }))
+ h.monitor.onAgentEvent(ev('st1', { state: 'waiting' })) // an elicitation: no question id either
+ h.clock.now += STATION_QUESTION_NOTICE_MS * 4
+ h.monitor.sweep()
+ await flush()
+ expect(h.delivered).toEqual([])
+ })
})
describe('unknown never triggers', () => {
@@ -164,9 +205,26 @@ describe('unknown never triggers', () => {
it('an orchestrator with no verified state never counts as idle', async () => {
const h = harness()
- h.monitor.onAgentEvent(ev('st1', { state: 'blocked' }))
- h.clock.now += STATION_BLOCKED_NOTICE_MS * 2
+ h.questions.set('st1', 'q1')
+ h.monitor.onAgentEvent(ev('st1', { state: 'waiting', questionId: 'q1' }))
+ h.clock.now += STATION_QUESTION_NOTICE_MS * 2
+ h.monitor.sweep()
+ expect(h.delivered).toEqual([])
+ })
+
+ it('a DROPPED report about a station core knows is mid-turn is not believed — then or later', async () => {
+ const h = harness()
+ h.monitor.onAgentEvent(ev('st1', { state: 'working', newTurn: true }))
+ h.monitor.reportDropped('st1', true)
h.monitor.sweep()
+ await flush()
+ expect(h.delivered).toEqual([])
+ // The turn ends cleanly: that `done` is the CLI speaking, so the stale verdict is gone with it
+ // — it must not fire now that the station is no longer mid-turn, nor on any later sweep.
+ h.monitor.onAgentEvent(ev('st1', { state: 'done' }))
+ h.clock.now += 30_000
+ h.monitor.sweep()
+ await flush()
expect(h.delivered).toEqual([])
})
@@ -221,6 +279,45 @@ describe('once per episode — re-armed only by a successful turn', () => {
expect(h.delivered).toHaveLength(1)
})
+ it('a stale DROPPED verdict never re-fires: any verified event withdraws it (review blocker)', async () => {
+ const h = harness()
+ h.monitor.onAgentEvent(ev('st1', { state: 'done' }))
+ h.monitor.reportDropped('st1', true)
+ await flush()
+ expect(h.delivered).toHaveLength(1)
+ // The renderer reloads here: its record of the report and its transient flag are gone, so
+ // nobody will ever send `reportDropped(false)`. The user resumes the station by hand…
+ h.monitor.onAgentEvent(ev('st1', { kind: 'session', sessionPhase: 'start' }))
+ // …and it completes a turn: the episode re-arms.
+ h.monitor.onAgentEvent(ev('st1', { state: 'working', newTurn: true }))
+ h.monitor.onAgentEvent(ev('st1', { state: 'done' }))
+ expect(h.monitor.list()).toEqual([])
+ for (let i = 0; i < 3; i++) {
+ h.clock.now += 30_000
+ h.monitor.sweep()
+ }
+ await flush()
+ expect(h.delivered).toHaveLength(1)
+ expect(h.monitor.list()).toEqual([])
+ })
+
+ it('an error retired by a successful turn that had no newTurn does not re-fire (review blocker)', async () => {
+ const h = harness()
+ h.monitor.onAgentEvent(ev('st1', { state: 'working', newTurn: true }))
+ h.monitor.onAgentEvent(ev('st1', { state: 'done', errored: true }))
+ await flush()
+ expect(h.delivered).toHaveLength(1)
+ // A task-notification prompt starts a turn WITHOUT `newTurn`; it succeeds.
+ h.monitor.onAgentEvent(ev('st1', { state: 'working' }))
+ h.monitor.onAgentEvent(ev('st1', { state: 'done' }))
+ expect(h.monitor.list()).toEqual([])
+ h.clock.now += 30_000
+ h.monitor.sweep()
+ h.monitor.onAgentEvent(ev('st1', { state: 'done', idle: true }))
+ await flush()
+ expect(h.delivered).toHaveLength(1)
+ })
+
it('a clean done with NO turn since the notice does not re-arm', async () => {
const h = harness()
h.monitor.reportDropped('st1', true)
@@ -282,14 +379,15 @@ describe('who is told', () => {
expect(g.delivered).toEqual([])
})
- it('a long-blocked station nobody opened does not re-read the canvases on every sweep', () => {
+ it('a long-waiting station nobody opened does not re-read the canvases on every sweep', () => {
const recipientFor = vi.fn(() => undefined)
const h = harness({ recipientFor })
- h.monitor.onAgentEvent(ev('loner', { state: 'blocked' }))
+ h.questions.set('loner', 'q1')
+ h.monitor.onAgentEvent(ev('loner', { state: 'waiting', questionId: 'q1' }))
// Before the threshold nothing is resolved at all.
h.monitor.sweep()
expect(recipientFor).not.toHaveBeenCalled()
- h.clock.now += STATION_BLOCKED_NOTICE_MS
+ h.clock.now += STATION_QUESTION_NOTICE_MS
for (let i = 0; i < 4; i++) {
h.monitor.sweep()
h.clock.now += 30_000
@@ -368,6 +466,72 @@ function messagingDeps(over: Partial<AgentMessagingDeps> = {}) {
return { deps, sent, paneReads }
}
+describe('the pane leg is followed to its end', () => {
+ const told: AgentMessageOutcome = {
+ kind: 'delivered',
+ traceId: 't2',
+ traced: 'memory',
+ receipt: 'observed',
+ signal: 'newTurn'
+ }
+ const notice = { verb: STATION_NOTICE_VERB, sourceNodeId: 'st1', targetNodeId: 'orch' }
+
+ it('a queued notice reports how it finally ended — never "queued" forever', async () => {
+ const h = harness()
+ h.monitor.onAgentEvent(ev('st1', { state: 'done', errored: true }))
+ await flush()
+ expect(h.monitor.list()[0].pane).toBe('queued')
+ // Someone else's queued message, and a plain `send`, are not this notice.
+ h.monitor.onQueuedResult({ ...notice, sourceNodeId: 'reader' }, told)
+ h.monitor.onQueuedResult({ ...notice, verb: 'send' }, told)
+ expect(h.monitor.list()[0].pane).toBe('queued')
+ h.monitor.onQueuedResult(notice, told)
+ expect(h.monitor.list()[0]).toMatchObject({ pane: 'told', paneDetail: 'delivered' })
+ })
+
+ it('an expired notice is offered ONCE more, on the orchestrator\'s next verified idle', async () => {
+ const h = harness({}, [QUEUED, QUEUED, told])
+ h.monitor.onAgentEvent(ev('st1', { state: 'done', errored: true }))
+ await flush()
+ h.monitor.onQueuedResult(notice, { kind: 'expired', traceId: 'x', queuedForMs: 300_000 })
+ expect(h.monitor.list()[0]).toMatchObject({ pane: 'not-sent', paneDetail: 'expired:will-retry' })
+ h.monitor.onAgentEvent(ev('orch', { state: 'done', verified: false })) // not evidence
+ await flush()
+ expect(h.delivered).toHaveLength(1)
+ h.monitor.onAgentEvent(ev('orch', { state: 'done' }))
+ await flush()
+ expect(h.delivered).toHaveLength(2)
+ // The second attempt queued again and expired again: that is the end of it.
+ h.monitor.onQueuedResult(notice, { kind: 'expired', traceId: 'y', queuedForMs: 300_000 })
+ h.monitor.onAgentEvent(ev('orch', { state: 'done' }))
+ await flush()
+ expect(h.delivered).toHaveLength(2)
+ expect(h.monitor.list()[0]).toMatchObject({ pane: 'not-sent', paneDetail: 'expired' })
+ })
+
+ it('a rate-limited notice is retried once, after the wait the limiter names', async () => {
+ const limited: AgentMessageOutcome = { kind: 'rateLimited', retryAfterMs: 7000 }
+ const h = harness({}, [limited, told])
+ h.monitor.onAgentEvent(ev('st1', { state: 'done', errored: true }))
+ await flush()
+ expect(h.timers.map((t) => t.ms)).toEqual([7250])
+ expect(h.monitor.list()[0].pane).toBeUndefined() // still being told
+ h.timers[0].fn()
+ await flush()
+ expect(h.delivered).toHaveLength(2)
+ expect(h.monitor.list()[0]).toMatchObject({ pane: 'told' })
+
+ const g = harness({}, [limited])
+ g.monitor.onAgentEvent(ev('st1', { state: 'done', errored: true }))
+ await flush()
+ g.timers[0].fn()
+ await flush()
+ expect(g.delivered).toHaveLength(2)
+ expect(g.timers).toHaveLength(1) // once
+ expect(g.monitor.list()[0]).toMatchObject({ pane: 'not-sent', paneDetail: 'rateLimited' })
+ })
+})
+
describe('the pane leg is the messaging service, with every gate', () => {
beforeEach(() => {
resetMessageFlow()
@@ -426,6 +590,23 @@ describe('the pane leg is the messaging service, with every gate', () => {
expect(m2.paneReads).toEqual([])
})
+ it('a busy orchestrator: queued, flushed on its next idle, and the chip follows (real queue)', async () => {
+ let orchState: MirrorEntry = { ...idle, state: 'working' }
+ const m = messagingDeps({ mirrorEntry: (id) => (id === 'orch' ? orchState : idle) })
+ const queue = createDeliveryQueue(m.deps)
+ m.deps.queue = queue
+ const h = harness({ deliver: (n) => deliverStationNotice(n, m.deps) })
+ m.deps.onQueuedResult = (req, outcome) => h.monitor.onQueuedResult(req, outcome)
+ h.monitor.onAgentEvent(ev('st1', { state: 'done', errored: true }))
+ await vi.waitFor(() => expect(h.monitor.list()[0]?.pane).toBe('queued'))
+ expect(m.sent).toEqual([])
+ orchState = idle
+ await onMessagingAgentEvent({ nodeId: 'orch', state: 'done', verified: true }, queue)
+ await vi.waitFor(() => expect(h.monitor.list()[0]?.pane).toBe('told'))
+ expect(m.sent).toHaveLength(1)
+ queue.resetForTests()
+ })
+
it('a renderer cannot ask for a notice with a body of its choosing', () => {
expect(
isDeliverRequest({ verb: STATION_NOTICE_VERB, sourceNodeId: 'st1', targetNodeId: 'orch', body: 'x' })
diff --git a/src/core/agents/station-notice.ts b/src/core/agents/station-notice.ts
index 74a899155..2dd77ffe6 100644
--- a/src/core/agents/station-notice.ts
+++ b/src/core/agents/station-notice.ts
@@ -5,10 +5,14 @@
*
* ── WHERE THE FACTS COME FROM ───────────────────────────────────────────────────────────────────
*
- * - `turn-errored` and `blocked-unanswered` are recomputed HERE from the same normalized events the
- * canvas badge and the phone mirror consume (`StopFailure` → `errored` on a `done`; a verified
- * `newTurn` clears it — the renderer's `lastTurnError` rule, restated over the stream because
- * both shells need it and the Server Edition may have no renderer attached at all).
+ * - `turn-errored` is recomputed HERE from the same normalized events the canvas badge and the
+ * phone mirror consume (`StopFailure` → `errored` on a `done`), because both shells need it and
+ * the Server Edition may have no renderer attached at all. It describes the LAST turn: a verified
+ * new turn or a clean `done` retires it.
+ * - `question-unanswered` reads the status mirror's `pendingQuestion` (`pendingQuestionOf`) — the
+ * ONE place a Claude question is correlated by session and tool-use id and held across unrelated
+ * hook traffic until its answer arrives — and times it from the verified event that asked it.
+ * Permission prompts are deliberately not a trigger (see `STATION_QUESTION_NOTICE_MS`).
* - `dropped` is the RENDERER's pane measurement (`terminal/agent-liveness.ts`), reported in through
* `reportDropped`. Core cannot make that call itself: telling a killed CLI from our own Eco exit or
* a Pause needs `hibernated`/`paused`, which exist only in the renderer's store. It is therefore
@@ -16,6 +20,12 @@
* so a station that dies off screen is noticed when it next comes into view. On the Server
* Edition a browser tab that shows the node reports it the same way; a server with no tab
* attached reports no DROPPED at all.
+ * Core WITHDRAWS the verdict itself on any verified hook event from the node — the CLI speaking
+ * from inside the pane is the one proof it is alive (the renderer's own self-heal in
+ * `agentStatus.setState`). It must not wait for the renderer to withdraw it: the renderer's record
+ * of what it reported, and its transient flag, both die with a reload (⌘R, or a Server Edition
+ * tab closing), and a verdict nobody withdraws re-fires on the healthy station after its next
+ * successful turn — typed into the orchestrator with "reassign: close it" as an option.
*
* Only VERIFIED events move a station here (`verified === true`: the POST presented this node's own
* token). A notice leads an orchestrator to retry, reassign or END a workflow, so an event anyone on
@@ -25,11 +35,21 @@
*
* An episode opens when a row of the table first matches and the recipient is resolved; it is
* re-armed ONLY by a successful turn — a turn that STARTED after the notice and ended in a `done`
- * that was not an error, not an interruption and not the idle-prompt rescue. Not by the failure
- * condition merely clearing: a usage-limit station retried by its orchestrator errors again at
- * once, and re-notifying on every error would turn the notice into a loop that burns the
- * orchestrator's turns all night. The notice itself says so, so the orchestrator knows it will not
- * hear again.
+ * that was not an error, not an interruption and not the idle-prompt rescue — and the re-arm clears
+ * every fact the episode was about. Not by the failure condition merely clearing: a usage-limit
+ * station retried by its orchestrator errors again at once, and re-notifying on every error would
+ * turn the notice into a loop that burns the orchestrator's turns all night. The notice itself says
+ * so, so the orchestrator knows it will not hear again.
+ *
+ * ── THE PANE LEG, TO ITS END ────────────────────────────────────────────────────────────────────
+ *
+ * One notice, but its DELIVERY is followed to a final answer, so the chip never reports a stale
+ * "queued": a queued notice's flush or expiry comes back through `onQueuedResult`. Two outcomes get
+ * exactly one more attempt, because each would otherwise lose the pane leg for a reason that has
+ * nothing to do with the notice: `rateLimited` (the station `send`s its result, then errors seconds
+ * later — the pair budget is spent) is retried once after the wait the limiter names, and an expiry
+ * (the orchestrator stayed busy longer than the queue's TTL) is retried once on the orchestrator's
+ * next verified `done`.
*
* Transient by design, like `lastTurnError` and `dropped`: after a restart nothing here remembers a
* notice, and nothing needs to — every fact that could re-trigger one is transient too.
@@ -38,7 +58,7 @@ import type { NormalizedAgentEvent } from '../../shared/agents/normalize'
import type { AgentState } from '../../shared/agents/normalize'
import type { BoardLogEntry } from '../../shared/types'
import {
- STATION_BLOCKED_NOTICE_MS,
+ STATION_QUESTION_NOTICE_MS,
stationFailure,
stationNoticeBody,
type StationFailureReason,
@@ -46,6 +66,7 @@ import {
type StationNoticeView,
type StationRecipient
} from '../../shared/station-notice'
+import { STATION_NOTICE_VERB } from '../../shared/agents/agent-messaging'
import type { AgentMessageOutcome } from './agent-message-decide'
import type { CorePlatform } from '../platform'
import { IPC } from '../../shared/ipc'
@@ -57,10 +78,14 @@ import { isSafeNodeId } from '../../shared/safe-id'
* simply has no orchestrator (a user opened it by hand) and the episode stays closed silently. */
export const STATION_RECIPIENT_GRACE_MS = 2 * 60_000
-/** The sweep cadence: the blocked threshold is crossed by time passing, and the grace retry above
+/** The sweep cadence: the question threshold is crossed by time passing, and the grace retry above
* needs a clock. 30 s is far below both windows and costs nothing when no station is tracked. */
export const STATION_SWEEP_MS = 30_000
+/** The longest a rate-limited notice waits for its one retry. The limiter names its own wait (the
+ * pair budget is `PAIR_MIN_INTERVAL_MS`, 10 s); this only bounds a surprising answer. */
+export const STATION_RATE_RETRY_MAX_MS = 60_000
+
/** The author of the board-log line — the app, like every other trace it writes. */
const NOTICE_AUTHOR = { name: 'nodeterm', color: '#8b8b8b' } as const
@@ -70,6 +95,10 @@ export interface StationNoticeDeps {
* canvases (the `openedBy` + rope rule). Server Edition: its creator ledger — only a station the
* recipient opened during THIS server run. */
recipientFor(stationNodeId: string): StationRecipient | undefined
+ /** The tool-use id of the question the status mirror holds UNANSWERED for this node
+ * (`mirrorEntry(id)?.pendingQuestion?.toolUseId`), or undefined. Required: a shell that left it
+ * out would compile and never report a waiting station. */
+ pendingQuestionOf(nodeId: string): string | undefined
/** The canvas leg's durable line, on the recipient's card. `false` = no reachable log. */
appendBoardLog(projectId: string, entry: BoardLogEntry): Promise<boolean>
/** The pane leg: `deliverStationNotice` over the shell's messaging deps. Absent ⇒ canvas only. */
@@ -83,12 +112,24 @@ export interface StationNoticeDeps {
/** Is this node still on some canvas? A node that left drops its notice and its tracking. */
exists(nodeId: string): boolean
newId?(): string
+ /** A one-shot timer (the rate-limit retry). Injected so a test drives it; defaults to an
+ * unref'd `setTimeout`. */
+ schedule?(ms: number, fn: () => void): void
}
/** The event fields the monitor reads — deliberately narrow, like the delivery receipt's. */
export type StationNoticeEvent = Pick<
NormalizedAgentEvent,
- 'nodeId' | 'kind' | 'state' | 'newTurn' | 'errored' | 'verified' | 'interrupted' | 'idle' | 'sessionPhase'
+ | 'nodeId'
+ | 'kind'
+ | 'state'
+ | 'newTurn'
+ | 'errored'
+ | 'verified'
+ | 'interrupted'
+ | 'idle'
+ | 'sessionPhase'
+ | 'questionId'
>
interface Episode {
@@ -99,19 +140,26 @@ interface Episode {
resolveUntil: number
pane?: StationNoticePane
paneDetail?: string
+ /** The one extra attempt each of these gets has been spent. */
+ rateRetried?: boolean
+ expiryRetried?: boolean
+ /** An expired notice waiting for the orchestrator's next verified `done`. */
+ awaitingIdle?: boolean
}
interface Tracked {
state?: AgentState
errored?: boolean
dropped?: boolean
- needsYouSince?: number
+ /** The question this node asked (verified), and when. The mirror decides whether it is still
+ * unanswered; this only remembers the moment it was asked. */
+ question?: { id: string; since: number }
episode?: Episode
/** A turn started after the notice — the first half of "a later successful turn". */
turnSinceNotice?: boolean
- /** When a long-blocked station last resolved to NO recipient. Resolving reads every persisted
+ /** When a long-waiting station last resolved to NO recipient. Resolving reads every persisted
* canvas, and a station nobody opened stays unattributed, so the sweep asks again only after
- * `STATION_RECIPIENT_GRACE_MS` rather than every 30 s for as long as it stays blocked. */
+ * `STATION_RECIPIENT_GRACE_MS` rather than every 30 s for as long as its question stands. */
recipientMissAt?: number
}
@@ -151,44 +199,48 @@ export class StationNoticeMonitor {
}
/** Feed one normalized hook event. Every event, from every node: the recipient's own state is
- * what the blocked row asks about. */
+ * what the question row asks about, and its `done` is what an expired notice waits for. */
onAgentEvent(e: StationNoticeEvent): void {
if (!e?.nodeId || e.verified !== true) return
const t = this.track(e.nodeId)
+ const now = this.deps.now()
+ // ANY verified hook event is the CLI reporting from inside its pane, so a standing DROPPED
+ // verdict is withdrawn here, whatever the kind — see the header for why core must not leave
+ // this to the renderer.
+ t.dropped = false
+ if (e.questionId && t.question?.id !== e.questionId) t.question = { id: e.questionId, since: now }
if (e.kind === 'session' && e.sessionPhase === 'end') {
// An orderly exit: the station's CLI announced its own end. Not a failure, and there is no
// longer a state to reason about.
t.state = undefined
- t.needsYouSince = undefined
+ t.question = undefined
return
}
if (e.kind !== 'state' || !e.state) return
// The idle-prompt rescue may only move a WORKING node (the renderer's and the mirror's rule):
// blocked/waiting is also "idle at the prompt", and a rescue must not clear a live question.
if (e.idle === true && t.state !== 'working') return
- const prev = t.state
- const now = this.deps.now()
if (e.newTurn === true) {
t.errored = false
if (t.episode) t.turnSinceNotice = true
}
if (e.state === 'working' && t.episode) t.turnSinceNotice = true
+ const cleanDone =
+ e.state === 'done' && e.errored !== true && e.interrupted !== true && e.idle !== true
if (e.state === 'done' && e.errored === true) t.errored = true
+ // `errored` describes the LAST turn, so a turn that ended cleanly retires it — including one
+ // that began without a `newTurn` (a task-notification prompt is exactly that).
+ else if (cleanDone) t.errored = false
t.state = e.state
- const needsYou = e.state === 'blocked' || e.state === 'waiting'
- if (!needsYou) t.needsYouSince = undefined
- else if (prev !== 'blocked' && prev !== 'waiting') t.needsYouSince = now
- if (
- t.episode &&
- t.turnSinceNotice &&
- e.state === 'done' &&
- e.errored !== true &&
- e.interrupted !== true &&
- e.idle !== true
- ) {
- // A later successful turn: the episode is over, the chip goes, the next failure is news.
+ if (e.state === 'done') this.offerExpiredTo(e.nodeId)
+ if (t.episode && t.turnSinceNotice && cleanDone) {
+ // A later successful turn: the episode is over, the chip goes, the next failure is news —
+ // and nothing the episode was about may outlive it, or the next sweep re-fires it.
t.episode = undefined
t.turnSinceNotice = false
+ t.errored = false
+ t.dropped = false
+ t.question = undefined
this.publish()
return
}
@@ -203,6 +255,32 @@ export class StationNoticeMonitor {
if (t.dropped) this.evaluate(nodeId, t)
}
+ /**
+ * How a QUEUED notice finally ended — the messaging queue's flush outcome or its expiry, wired by
+ * each shell through `AgentMessagingDeps.onQueuedResult`. Anything that is not this monitor's
+ * current notice for that pair is ignored.
+ */
+ onQueuedResult(
+ req: { verb?: unknown; sourceNodeId: string; targetNodeId: string },
+ outcome: AgentMessageOutcome
+ ): void {
+ if (req.verb !== STATION_NOTICE_VERB) return
+ const ep = this.nodes.get(req.sourceNodeId)?.episode
+ if (!ep?.recipient || ep.recipient.recipientNodeId !== req.targetNodeId || ep.pane !== 'queued')
+ return
+ if (outcome.kind === 'expired' && !ep.expiryRetried) {
+ // The orchestrator stayed busy past the queue's TTL. It has not read the notice, and the
+ // episode says it will never be told again — so offer it once more at its next idle moment.
+ ep.expiryRetried = true
+ ep.awaitingIdle = true
+ ep.pane = 'not-sent'
+ ep.paneDetail = 'expired:will-retry'
+ this.publish()
+ return
+ }
+ this.settle(req.sourceNodeId, ep, outcome)
+ }
+
/** The current notices, as every renderer should draw them. */
list(): StationNoticeView[] {
const out: StationNoticeView[] = []
@@ -223,7 +301,7 @@ export class StationNoticeMonitor {
return out.sort((a, b) => a.at - b.at)
}
- /** Time-driven work: the blocked threshold, the recipient grace retry, and pruning. */
+ /** Time-driven work: the question threshold, the recipient grace retry, and pruning. */
sweep(): void {
const now = this.deps.now()
let changed = false
@@ -273,23 +351,23 @@ export class StationNoticeMonitor {
private evaluate(stationNodeId: string, t: Tracked): void {
if (t.episode) return // once per episode
const now = this.deps.now()
+ // The mirror is the authority on whether the question still stands: it holds it across
+ // unrelated hook traffic and drops it on the answer, an interrupt or a session boundary.
+ if (t.question && this.deps.pendingQuestionOf(stationNodeId) !== t.question.id)
+ t.question = undefined
const obs = {
state: t.state,
lastTurnErrored: t.errored,
dropped: t.dropped,
- needsYouSince: t.needsYouSince
+ questionSince: t.question?.since
}
// The table is asked twice at most: first without the recipient (DROPPED and ERRORED do not
// depend on it — and resolving a recipient reads the persisted canvases, so a station that
- // matches nothing never pays for it), then, only for a long-blocked station, with its
+ // matches nothing never pays for it), then, only for an old enough question, with its
// recipient's state.
let reason = stationFailure(obs, { now })
let recipient: StationRecipient | undefined
- if (
- !reason &&
- t.needsYouSince !== undefined &&
- now - t.needsYouSince >= STATION_BLOCKED_NOTICE_MS
- ) {
+ if (!reason && t.question && now - t.question.since >= STATION_QUESTION_NOTICE_MS) {
if (t.recipientMissAt !== undefined && now - t.recipientMissAt < STATION_RECIPIENT_GRACE_MS)
return
recipient = this.deps.recipientFor(stationNodeId)
@@ -335,22 +413,63 @@ export class StationNoticeMonitor {
}
void this.deps.appendBoardLog(recipient.projectId, entry).catch(() => false)
this.publish()
+ this.sendPane(stationNodeId, ep)
+ }
+
+ /** One attempt at the pane leg; its result settles the chip, or earns the one rate-limit retry. */
+ private sendPane(stationNodeId: string, ep: Episode): void {
const deliver = this.deps.deliver
- if (!deliver) return
+ const recipient = ep.recipient
+ if (!deliver || !recipient) return
const body = stationNoticeBody({ id: stationNodeId, title: recipient.stationTitle }, ep.reason)
void deliver({ stationNodeId, recipientNodeId: recipient.recipientNodeId, body })
- .then((o) => paneResult(o))
- .catch(() => ({ pane: 'not-sent' as const, paneDetail: 'error' }))
- .then((r) => {
+ .then(
+ (o) => o,
+ () => null
+ )
+ .then((o) => {
// The episode may have been re-armed (or the node forgotten) while the delivery ran; only
// the episode this delivery belonged to takes its result.
if (this.nodes.get(stationNodeId)?.episode !== ep) return
- ep.pane = r.pane
- if (r.paneDetail) ep.paneDetail = r.paneDetail
- this.publish()
+ if (o?.kind === 'rateLimited' && !ep.rateRetried) {
+ ep.rateRetried = true
+ const wait = Math.min(Math.max(0, o.retryAfterMs), STATION_RATE_RETRY_MAX_MS) + 250
+ this.schedule(wait, () => {
+ if (this.nodes.get(stationNodeId)?.episode === ep) this.sendPane(stationNodeId, ep)
+ })
+ return
+ }
+ this.settle(stationNodeId, ep, o)
})
}
+ private settle(stationNodeId: string, ep: Episode, o: AgentMessageOutcome | null): void {
+ if (this.nodes.get(stationNodeId)?.episode !== ep) return
+ const r = o ? paneResult(o) : { pane: 'not-sent' as const, paneDetail: 'error' }
+ ep.pane = r.pane
+ ep.paneDetail = r.paneDetail
+ this.publish()
+ }
+
+ /** The recipient went idle: deliver the notices that expired waiting for exactly that. */
+ private offerExpiredTo(recipientNodeId: string): void {
+ for (const [stationNodeId, t] of this.nodes) {
+ const ep = t.episode
+ if (!ep?.awaitingIdle || ep.recipient?.recipientNodeId !== recipientNodeId) continue
+ ep.awaitingIdle = false
+ ep.pane = undefined
+ ep.paneDetail = undefined
+ this.publish()
+ this.sendPane(stationNodeId, ep)
+ }
+ }
+
+ private schedule(ms: number, fn: () => void): void {
+ if (this.deps.schedule) return this.deps.schedule(ms, fn)
+ const h = setTimeout(fn, ms)
+ ;(h as { unref?: () => void }).unref?.()
+ }
+
private publish(): void {
const views = this.list()
const key = JSON.stringify(views)
diff --git a/src/core/canvas-control-core.ts b/src/core/canvas-control-core.ts
index 376ebe105..b4eec8b5a 100644
--- a/src/core/canvas-control-core.ts
+++ b/src/core/canvas-control-core.ts
@@ -23,8 +23,8 @@ import { offScreenGuidanceLines } from '@shared/control-off-screen'
import { codexThreadIdentityResolverSh } from './codex-thread-identity-sh'
import { ISSUE_SESSION_COLUMNS, issueLaunchPrompt, parseIssueArg } from '../shared/github-issue-ref'
import {
- STATION_BLOCKED_NOTICE_MS,
STATION_NOTICE_COMMON_OPTIONS,
+ STATION_QUESTION_NOTICE_MS,
STATION_TRIGGERS
} from '../shared/station-notice'
import { STATION_NOTICE_FROM } from '../shared/agents/agent-messaging'
@@ -56,7 +56,7 @@ function messagingGuidanceLines(): string[] {
* changes. `canvas-control-core.test.ts` walks the real table against both.
*/
function stationNoticeDocLines(): string[] {
- const minutes = Math.round(STATION_BLOCKED_NOTICE_MS / 60_000)
+ const minutes = Math.round(STATION_QUESTION_NOTICE_MS / 60_000)
return [
'Station notices — when a station YOU opened stops:',
'- nodeterm tells the agent that OPENED a station (the node its rope comes from) when that station',
@@ -65,8 +65,10 @@ function stationNoticeDocLines(): string[] {
' a retry stays silent, so decide what to do the first time.',
'- A station counts as stopped in exactly these cases:',
...STATION_TRIGGERS.map((row) => ` - \`${row.reason}\`: ${row.label}.`),
- ` (\`blocked-unanswered\` is sent only while YOU are idle: the user sees NEEDS YOU the moment the`,
- ` station blocks, and you hear after ${minutes} minutes if nobody has answered.)`,
+ ` (\`question-unanswered\` is sent only while YOU are idle: the user sees NEEDS YOU the moment the`,
+ ` station asks, and you hear after ${minutes} minutes if nobody has answered. A PERMISSION prompt`,
+ ' is never a notice: an approval given in the station\'s own pane is invisible until the approved',
+ ' tool finishes, so a long approved tool would look exactly like a prompt nobody answered.)',
'- Where it shows up: always as a STATION FAILED chip on your node and a line in your card\'s',
' activity. It is typed into YOUR session only when the project\'s agent-messaging switch is on',
' (off by default), as a framed message whose `from:` line reads',
diff --git a/src/main/canvas-control-core.test.ts b/src/main/canvas-control-core.test.ts
index 8b8da0c13..e682fd964 100644
--- a/src/main/canvas-control-core.test.ts
+++ b/src/main/canvas-control-core.test.ts
@@ -14,8 +14,8 @@ import {
} from '../core/agents/hook-sandbox-hint-sh'
import { RETRYABLE } from '../core/agents/agent-message-decide'
import {
- STATION_BLOCKED_NOTICE_MS,
STATION_NOTICE_COMMON_OPTIONS,
+ STATION_QUESTION_NOTICE_MS,
STATION_TRIGGERS
} from '../shared/station-notice'
import { STATION_NOTICE_FROM } from '../shared/agents/agent-messaging'
@@ -695,7 +695,9 @@ describe('parseControlRequest', () => {
expect(section).toMatch(/agent-messaging switch is on[\s\S]*off by default/)
expect(section).toContain(`\`${STATION_NOTICE_FROM} (<station id>)\``)
expect(section).toMatch(/quotes nothing the station produced/)
- expect(section).toContain(`you hear after ${Math.round(STATION_BLOCKED_NOTICE_MS / 60_000)} minutes`)
+ expect(section).toContain(`you hear after ${Math.round(STATION_QUESTION_NOTICE_MS / 60_000)} minutes`)
+ // …and the honest limit: a permission prompt is never a notice.
+ expect(section).toMatch(/A PERMISSION prompt[\s\S]*is never a notice/)
// The Server Edition's ownership rule, in the same words it keeps for every verb.
expect(section).toMatch(/stations you opened during this server run/)
}
diff --git a/src/main/index.ts b/src/main/index.ts
index afe40be20..2a871ae7c 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -1915,6 +1915,9 @@ app.whenReady().then(async () => {
const stationNotices = new StationNoticeMonitor({
now: () => Date.now(),
recipientFor: (id) => stationRecipient(workspaceStore.persistedCanvases(), id),
+ // The mirror's correlated, unanswered question — the one fact that says a station is really
+ // waiting on a human (station-notice.ts: permission prompts are not a trigger).
+ pendingQuestionOf: (id) => mirrorEntry(id)?.pendingQuestion?.toolUseId,
appendBoardLog: (projectId, entry) => appendBoardLogVia(boardLogRouter, projectId, entry),
deliver: (notice) => deliverStationNotice(notice, messagingDeps),
publish: (views) => sendToMain(IPC.stationNoticeChanged, views),
@@ -1923,6 +1926,9 @@ app.whenReady().then(async () => {
exists: (id) => workspaceStore.projectIdsForNode(id).length > 0
})
stationNotices.start()
+ // A queued notice's final outcome (flushed or expired) comes back here, so its chip never says
+ // "queued" about a message that has since landed or lapsed.
+ messagingDeps.onQueuedResult = (req, outcome) => stationNotices.onQueuedResult(req, outcome)
registerStationNoticeIpc(corePlatform, () => stationNotices)
ipcMain.handle(IPC.dialogSelectFolder, async () => {
diff --git a/src/main/station-notice-wiring.test.ts b/src/main/station-notice-wiring.test.ts
index 09a272adc..05bb38156 100644
--- a/src/main/station-notice-wiring.test.ts
+++ b/src/main/station-notice-wiring.test.ts
@@ -32,6 +32,12 @@ describe('both shells feed the station-failure monitor', () => {
expect(src).toContain('stationRecipient(workspaceStore.persistedCanvases(), id)')
// …and the pane leg is the messaging service with every gate, not a raw write.
expect(src).toContain('deliverStationNotice(notice, messagingDeps)')
+ // The question row's one fact, and the queued notice's final outcome — both optional-looking
+ // hookups a shell can drop and still compile.
+ expect(src).toContain('pendingQuestionOf: (id) => mirrorEntry(id)?.pendingQuestion?.toolUseId')
+ expect(src).toContain(
+ 'messagingDeps.onQueuedResult = (req, outcome) => stationNotices.onQueuedResult(req, outcome)'
+ )
})
it('Server Edition: the canvas-control runtime feeds it and asks its creator ledger', () => {
@@ -41,6 +47,10 @@ describe('both shells feed the station-failure monitor', () => {
)
expect(cc).toContain('factory.openerOf(stationNodeId)')
expect(cc).toContain('deliverStationNotice(notice, messaging)')
+ expect(cc).toContain('pendingQuestionOf: (nodeId) => mirrorEntry(nodeId)?.pendingQuestion?.toolUseId')
+ expect(cc).toContain(
+ 'messaging.onQueuedResult = (req, outcome) => stationNotices.onQueuedResult(req, outcome)'
+ )
const idx = read('server/index.ts')
expect(idx).toContain('registerStationNoticeIpc(platform, () => canvasControl?.stationNotices ?? null)')
})
diff --git a/src/server/canvas-control.ts b/src/server/canvas-control.ts
index 96c4fae50..6055cd813 100644
--- a/src/server/canvas-control.ts
+++ b/src/server/canvas-control.ts
@@ -244,12 +244,14 @@ export async function initServerCanvasControl(
stationNodeId,
factory.openerOf(stationNodeId)
),
+ pendingQuestionOf: (nodeId) => mirrorEntry(nodeId)?.pendingQuestion?.toolUseId,
appendBoardLog: (projectId, entry) => deps.boardLog.append(projectId, entry),
deliver: (notice) => deliverStationNotice(notice, messaging),
publish: (views) => platform().broadcast(IPC.stationNoticeChanged, views),
exists: (nodeId) => deps.workspaceStore.projectIdsForNode(nodeId).length > 0
})
stationNotices.start()
+ messaging.onQueuedResult = (req, outcome) => stationNotices.onQueuedResult(req, outcome)
const actions: ServerEditionControlActions = {
openProject: (sourceNodeId, args, verified) =>
diff --git a/src/shared/host-control.test.ts b/src/shared/host-control.test.ts
index 22174d4e5..e1b7770a4 100644
--- a/src/shared/host-control.test.ts
+++ b/src/shared/host-control.test.ts
@@ -34,10 +34,11 @@ describe('isHostOnlyChannel', () => {
expect(isHostOnlyChannel(IPC.ptyLaunchHeadless)).toBe(true)
})
- it('covers station-notice:dropped — a guest may not report a pane verdict about the host\'s nodes', () => {
+ it('covers both station-notice request channels', () => {
+ // A guest may not report a pane verdict about the host's nodes…
expect(isHostOnlyChannel(IPC.stationNoticeDropped)).toBe(true)
- // Reading the list acts on nothing.
- expect(isHostOnlyChannel(IPC.stationNoticeList)).toBe(false)
+ // …nor list every project's failed stations: a guest scoped to one project must not read the rest.
+ expect(isHostOnlyChannel(IPC.stationNoticeList)).toBe(true)
})
it('leaves the read-only/lifecycle channels alone — the gate is on ACTION, not on the namespace', () => {
diff --git a/src/shared/host-control.ts b/src/shared/host-control.ts
index cbff00758..d82b95811 100644
--- a/src/shared/host-control.ts
+++ b/src/shared/host-control.ts
@@ -29,6 +29,8 @@ import { IPC } from './ipc'
* its own session, that one of its stations died. It is a pane measurement only the HOST's
* renderer makes (a relay tab takes the inert stub), so a guest sending it is claiming a fact
* about the host's panes it never measured.
+ * - `station-notice:list` — every project's failed-station ids and titles, unscoped. A relay tab
+ * never asks (it takes the inert stub), and a guest bound to ONE project must not read the rest.
*
* DELIBERATELY NOT LISTED: `project-setup:subscribe`/`unsubscribe` and the `project-setup:event:*`
* push. They neither start nor authorize anything, and a peer that can see the canvas can already
@@ -46,7 +48,8 @@ export const HOST_ONLY_CHANNELS: ReadonlySet<string> = new Set([
IPC.projectSetupConsentSubmit,
IPC.projectSetupRequestTrust,
IPC.ptyLaunchHeadless,
- IPC.stationNoticeDropped
+ IPC.stationNoticeDropped,
+ IPC.stationNoticeList
])
/** What a refused peer is told. One wording, so the two shells answer identically. */
diff --git a/src/shared/station-notice.test.ts b/src/shared/station-notice.test.ts
index b3062d43d..6c0c3ef62 100644
--- a/src/shared/station-notice.test.ts
+++ b/src/shared/station-notice.test.ts
@@ -1,7 +1,7 @@
import { describe, it, expect } from 'vitest'
import {
- STATION_BLOCKED_NOTICE_MS,
STATION_NOTICE_COMMON_OPTIONS,
+ STATION_QUESTION_NOTICE_MS,
STATION_NOTICE_TITLE_MAX,
STATION_TRIGGERS,
sanitizeStationNotices,
@@ -21,33 +21,40 @@ describe('the trigger table — closed, and an unknown never triggers', () => {
expect(stationFailure({ state: 'done', lastTurnErrored: true }, { now: T0 })).toBe('turn-errored')
})
- it('dropped: the renderer verdict alone', () => {
+ it('dropped: the renderer verdict, about a station core does not know to be alive', () => {
expect(stationFailure({ dropped: true }, { now: T0 })).toBe('dropped')
+ expect(stationFailure({ dropped: true, state: 'done' }, { now: T0 })).toBe('dropped')
+ // A stale verdict about a station core KNOWS is mid-turn or asking says nothing.
+ for (const state of ['working', 'blocked', 'waiting'] as const)
+ expect(stationFailure({ dropped: true, state }, { now: T0 })).toBeNull()
// …and it outranks an errored turn: nothing is running at all.
expect(stationFailure({ state: 'done', lastTurnErrored: true, dropped: true }, { now: T0 })).toBe(
'dropped'
)
})
- it('blocked-unanswered: past the threshold AND the recipient idle — all three required', () => {
- const since = T0 - STATION_BLOCKED_NOTICE_MS
- for (const state of ['blocked', 'waiting'] as const) {
- expect(
- stationFailure({ state, needsYouSince: since }, { now: T0, recipientState: 'done' })
- ).toBe('blocked-unanswered')
- // One millisecond short of the threshold.
- expect(
- stationFailure({ state, needsYouSince: since + 1 }, { now: T0, recipientState: 'done' })
- ).toBeNull()
- // A working orchestrator is not stalled on anything.
- expect(
- stationFailure({ state, needsYouSince: since }, { now: T0, recipientState: 'working' })
- ).toBeNull()
- // An orchestrator whose state is unknown is NOT idle.
- expect(stationFailure({ state, needsYouSince: since }, { now: T0 })).toBeNull()
- // A needs-you station whose entry moment is unknown never crosses a threshold.
- expect(stationFailure({ state }, { now: T0, recipientState: 'done' })).toBeNull()
- }
+ it('question-unanswered: an old enough question AND the recipient idle — both required', () => {
+ const since = T0 - STATION_QUESTION_NOTICE_MS
+ expect(
+ stationFailure({ state: 'waiting', questionSince: since }, { now: T0, recipientState: 'done' })
+ ).toBe('question-unanswered')
+ // One millisecond short of the threshold.
+ expect(
+ stationFailure({ state: 'waiting', questionSince: since + 1 }, { now: T0, recipientState: 'done' })
+ ).toBeNull()
+ // A working orchestrator is not stalled on anything.
+ expect(
+ stationFailure({ state: 'waiting', questionSince: since }, { now: T0, recipientState: 'working' })
+ ).toBeNull()
+ // An orchestrator whose state is unknown is NOT idle.
+ expect(stationFailure({ state: 'waiting', questionSince: since }, { now: T0 })).toBeNull()
+ })
+
+ it('a permission prompt is never a trigger, however long it has stood', () => {
+ // An approval given in the pane fires nothing until the approved tool finishes, so "blocked"
+ // cannot be told from "approved and running" — there is no row that reads it.
+ for (const state of ['blocked', 'waiting'] as const)
+ expect(stationFailure({ state }, { now: T0 * 10, recipientState: 'done' })).toBeNull()
})
it('nothing else is a failure — unknown, working, a successful done, a short wait', () => {
@@ -61,7 +68,7 @@ describe('the trigger table — closed, and an unknown never triggers', () => {
})
it('the table is exactly three reasons', () => {
- expect(STATION_TRIGGERS.map((r) => r.reason)).toEqual(['dropped', 'turn-errored', 'blocked-unanswered'])
+ expect(STATION_TRIGGERS.map((r) => r.reason)).toEqual(['dropped', 'turn-errored', 'question-unanswered'])
})
})
@@ -227,6 +234,9 @@ describe('the wire and the chip text', () => {
/agent messaging is off for this project/
)
expect(stationNoticePaneText({ pane: 'told' })).toMatch(/told in its session/)
+ expect(stationNoticePaneText({ pane: 'not-sent', paneDetail: 'expired:will-retry' })).toMatch(
+ /offered once more when that session next goes idle/
+ )
expect(stationNoticePaneText({ pane: 'queued' })).toMatch(/next goes idle/)
expect(stationNoticePaneText({})).toMatch(/Telling/)
})
diff --git a/src/shared/station-notice.ts b/src/shared/station-notice.ts
index bcca32cdc..aafa81dc0 100644
--- a/src/shared/station-notice.ts
+++ b/src/shared/station-notice.ts
@@ -28,29 +28,38 @@ import { oneLine } from './one-line'
import { isSafeNodeId } from './safe-id'
/** The closed set of reasons. A reason that is not in this union cannot produce a notice. */
-export type StationFailureReason = 'turn-errored' | 'dropped' | 'blocked-unanswered'
+export type StationFailureReason = 'turn-errored' | 'dropped' | 'question-unanswered'
/**
- * How long a station must sit on a question or a permission prompt — continuously, measured from
- * the TRANSITION into needs-you — before its orchestrator is told, and only while that orchestrator
- * is itself idle.
+ * How long a station's QUESTION must stay unanswered — measured from the moment it was asked —
+ * before its orchestrator is told, and only while that orchestrator is itself idle.
*
- * Why this trigger exists at all: a blocked station is not a failure the orchestrator can fix (it
- * has no verb that answers a permission prompt, and `write` is confirm-gated), but an orchestrator
- * that is idle and waiting on it will wait forever, which is the exact overnight stall this feature
- * is for. Told, it can reassign the work, skip the station, or stop and tell the user — and the
- * notice says which station is waiting, which is the thing the user needs when they come back.
+ * Why this trigger exists at all: a station waiting on a question is not a failure the orchestrator
+ * can fix (it has no verb that answers one, and `write` is confirm-gated), but an orchestrator that
+ * is idle and waiting on the station will wait forever, which is the exact overnight stall this
+ * feature is for. Told, it can reassign the work, skip the station, or stop and tell the user — and
+ * the notice says which station is waiting, which is the thing the user needs when they come back.
+ *
+ * Why a QUESTION and not a permission prompt. A question (Claude's `AskUserQuestion`) is answered
+ * by a tool result the moment the user picks an option, so the status mirror's `pendingQuestion` —
+ * correlated by session and tool-use id, and held across unrelated hook traffic — is a fact about
+ * whether it is still unanswered. A permission prompt has no such fact: on the main thread Claude
+ * paints its dialog CONCURRENTLY with our held hook (docs/hook-reply-approvals.md), and an approval
+ * given in the pane fires nothing until the approved tool FINISHES. A twenty-minute build approved
+ * in the pane reads exactly like a prompt nobody answered, and a notice there would invite the
+ * orchestrator to reassign or close a station that is working. So permission prompts are not a
+ * trigger at all — a false "your station is stuck" is worse than none.
*
* Why 15 minutes: the human already gets NEEDS YOU, an unread dot and (in the background) an OS
- * notification the moment the station blocks. A person at the desk answers inside a few minutes;
+ * notification the moment the station asks. A person at the desk answers inside a few minutes;
* waking the orchestrator sooner would only race them — an orchestrator that reassigns a task
- * seconds before the user approves the prompt has doubled the work. Fifteen minutes is past any
- * "I was reading the diff" pause and short of "the user went home".
+ * seconds before the user answers has doubled the work. Fifteen minutes is past any "I was reading
+ * the diff" pause and short of "the user went home".
*
* Why only while the orchestrator is idle: a WORKING orchestrator is not stalled on anything, will
* `list` again on its own, and a notice would only land in its queue behind whatever it is doing.
*/
-export const STATION_BLOCKED_NOTICE_MS = 15 * 60_000
+export const STATION_QUESTION_NOTICE_MS = 15 * 60_000
/** What core knows about a station when it asks the table. Every field is optional because every
* one of them can be unknown, and an unknown MUST NOT trigger (the table below never reads an
@@ -65,9 +74,9 @@ export interface StationObservation {
/** The DROPPED verdict: the CLI left the pane and nothing accounted for it (the renderer's
* pane measurement, `terminal/agent-liveness.ts`). */
dropped?: boolean
- /** When the station ENTERED blocked/waiting (the transition time, not the latest same-state
- * event). `undefined` when it is not in a needs-you state, or when that moment is unknown. */
- needsYouSince?: number
+ /** When the station asked the question the status mirror still holds unanswered
+ * (`pendingQuestion`). `undefined` when there is none, or when the ask was not observed. */
+ questionSince?: number
}
export interface StationFailureContext {
@@ -97,13 +106,15 @@ export interface StationTrigger {
* First matching row wins. DROPPED is first because it is the strongest fact (nothing is running
* at all) and a station that errored and was then killed should be reported as the thing the
* orchestrator can least recover from by itself. Everything else — a `working` station, a `done`
- * station whose turn succeeded, a station whose state is unknown, a station that is blocked for
- * less than the threshold or blocked while its orchestrator is busy — matches no row and triggers
- * nothing.
+ * station whose turn succeeded, a station whose state is unknown, a question younger than the
+ * threshold or one asked while the orchestrator is busy, a permission prompt of any age — matches
+ * no row and triggers nothing.
*
* Deliberately NOT a row: a station that exited cleanly (`/exit`, SessionEnd), one we exited
* ourselves (Eco hibernation, Pause), a launch that is still queued. Those are decisions somebody
- * made, not failures, and the DROPPED verdict already refuses hibernated and paused nodes.
+ * made, not failures, and the DROPPED verdict already refuses hibernated and paused nodes. Nor a
+ * permission prompt — see `STATION_QUESTION_NOTICE_MS` for why "unanswered" cannot be told from
+ * "approved and running" there.
*/
export const STATION_TRIGGERS: readonly StationTrigger[] = [
{
@@ -113,7 +124,13 @@ export const STATION_TRIGGERS: readonly StationTrigger[] = [
retry:
'`send` cannot reach it — nothing is running in its pane. Ask the user to click the ' +
"station's DROPPED chip, which resumes the conversation, then retry.",
- fires: (obs) => obs.dropped === true
+ // The verdict is only ever raised about a `done` station; a station core KNOWS to be mid-turn
+ // or asking is alive, whatever a stale report says.
+ fires: (obs) =>
+ obs.dropped === true &&
+ obs.state !== 'working' &&
+ obs.state !== 'blocked' &&
+ obs.state !== 'waiting'
},
{
reason: 'turn-errored',
@@ -125,16 +142,15 @@ export const STATION_TRIGGERS: readonly StationTrigger[] = [
fires: (obs) => obs.state === 'done' && obs.lastTurnErrored === true
},
{
- reason: 'blocked-unanswered',
- label: `it has been waiting for a human answer (a question or a permission prompt) for over ${Math.round(STATION_BLOCKED_NOTICE_MS / 60_000)} minutes`,
+ reason: 'question-unanswered',
+ label: `it asked the user a question over ${Math.round(STATION_QUESTION_NOTICE_MS / 60_000)} minutes ago and it is still unanswered`,
option: 'wait',
retry:
- 'you cannot answer its prompt from here. Tell the user which station is waiting and what ' +
- 'for; it continues on its own once they answer.',
+ 'you cannot answer its question from here. Tell the user which station is waiting on an ' +
+ 'answer; it continues on its own once they answer.',
fires: (obs, ctx) =>
- (obs.state === 'blocked' || obs.state === 'waiting') &&
- typeof obs.needsYouSince === 'number' &&
- ctx.now - obs.needsYouSince >= STATION_BLOCKED_NOTICE_MS &&
+ typeof obs.questionSince === 'number' &&
+ ctx.now - obs.questionSince >= STATION_QUESTION_NOTICE_MS &&
ctx.recipientState === 'done'
}
]
@@ -323,9 +339,11 @@ export function stationNoticePaneText(view: Pick<StationNoticeView, 'pane' | 'pa
case 'queued':
return "Queued for the orchestrator's session; it is typed in when that session next goes idle."
case 'not-sent':
- return view.paneDetail === 'notPermitted:switch-off' || view.paneDetail === 'messaging-off'
- ? 'Not typed into the orchestrator\'s session: agent messaging is off for this project (Settings → Agents). Shown on the canvas only.'
- : `Not typed into the orchestrator's session (${view.paneDetail ?? 'refused'}). Shown on the canvas only.`
+ if (view.paneDetail === 'notPermitted:switch-off' || view.paneDetail === 'messaging-off')
+ return 'Not typed into the orchestrator\'s session: agent messaging is off for this project (Settings → Agents). Shown on the canvas only.'
+ if (view.paneDetail === 'expired:will-retry')
+ return "Not typed in yet: the orchestrator stayed busy longer than a message may wait. It is offered once more when that session next goes idle."
+ return `Not typed into the orchestrator's session (${view.paneDetail ?? 'refused'}). Shown on the canvas only.`
default:
return 'Telling the orchestrator…'
}