docs(watching): a restart is not a gap, and here is the measurement

Claimed after a manual test that a session comes back from a server restart
without its badge until it next produces output. Measured instead of assumed,
and it is wrong: a codex session with a background terminal still running had
its label back within about 20 seconds of the restart, with no input from
anyone. Reconciliation re-attaches the pane, the attach repaint carries the
composer glyph, the idle confirmation arms on it, and the probe re-reads the
label — the ordinary path, doing the ordinary thing.

What produced the false claim was a session whose monitor had simply expired
while it sat there. Its footer carries no chip, so `watching: null` was the
right answer and there was nothing missing to restore.

Recorded at the field and in the invariants, because the shape of this invites
exactly one wrong fix: a polling timer to keep a value fresh that the pane
already refreshes by itself.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Michael Grundberg
2026-09-23 08:00:16 +02:00
co-authored by Claude Opus 5
parent b13672596f
commit 9a48c43aa1
2 changed files with 12 additions and 4 deletions
+11 -3
View File
@@ -509,9 +509,17 @@ export class Session extends EventEmitter {
*
* ⚠️ It then FREEZES once `_confirmIdle()` concludes: `activityTimeout` is null from
* there, and nothing looks at the pane again until it produces output. That is
* correct rather than merely tolerable, because the background work ending is itself
* what wakes the agent and repaints the pane. Do not add a timer to keep this fresh;
* it would spend a `capture-pane` per idle session per tick to learn nothing.
* correct rather than merely tolerable, because work ending repaints the pane either
* way — a monitor firing wakes the agent, and codex drops its background-terminal row
* on its own. Do not add a timer to keep this fresh; it would spend a `capture-pane`
* per idle session per tick to learn nothing.
*
* A server restart is not a hole in that either, though it looks like one: this field
* is live state and starts empty. Reconciliation re-attaches the pane, the attach
* repaint carries the composer glyph, and the idle confirmation that arms on it probes
* and re-reads the label with no input from anyone — measured 2026-09-23 on a restarted
* instance, back within ~20 s for a session whose background terminal was still
* running. A session that comes back with no label has no chip on its screen.
*/
private _watching: string | null = null;
/** Lazily compiled `capabilities.workDetect.workingLine`. See _workingLinePattern(). */