instar 1.3.985 → 1.3.987

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-26T17:59:55.648Z",
-  "instarVersion": "1.3.985",
+  "generatedAt": "2026-07-26T19:26:36.562Z",
+  "instarVersion": "1.3.987",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -1538,7 +1538,7 @@
       "type": "subsystem",
       "domain": "sessions",
       "sourcePath": "src/core/SessionManager.ts",
-      "contentHash": "4fb46f8df9bd47f899f51c13d25057a158d21b00bacec8bbecd75b3414c64b95",
+      "contentHash": "3f88cbed25892776b9eaa258ff68b7eb7b8b676713ea01280899ee8f5b282e96",
       "since": "2025-01-01"
     },
     "subsystem:auto-updater": {

package/upgrades/1.3.986.md

@@ -0,0 +1,153 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+**A session's startup banner — and a session's startup QUESTION — were read as an input prompt, so
+a message could be typed into a pane that could not receive it, and the delivery was logged as a
+success.**
+
+`SessionManager.detectClaudePrompt` decided a pane was accepting input if the last six
+non-blank lines contained `❯`, `›`, `bypass permissions`, or a mention of `/effort`,
+`/model` or `/fast`. That last clause matched a bare slash-command mention **anywhere, in
+any context, including prose**.
+
+Claude Code's startup banner advertises slash commands in prose. The pane that caused the
+incident carried, verbatim:
+
+> `…Fable 5 draws down usage faster than Opus 4.8. Run /model and`
+> `select Fable to use it. Learn more: https://support.claude.com/…`
+
+so the probe matched a promotional line and declared a still-painting pane ready.
+
+**Observed (topic 29723, 2026-07-26).** Inbound message at `17:44:49Z`, session respawned,
+pointer prompt injected at `17:45:00Z` — but that session's own start hook did not complete
+until `17:45:15Z`. The paste landed fifteen seconds early, was swallowed by the TUI redraw,
+and the injector wrote `Injected initial message into "…" (915 chars, after stabilization
+delay)`. A success line for a delivery that did not happen. The message reached the agent
+only because the start hook's unanswered-message backstop re-reads recent history — an
+unrelated path that happens to cover this hole and cannot be relied on to.
+
+**The slash-command clauses are deleted, not tuned.** A first attempt kept them and required
+"status-bar shape" (line-start or directly after an interpunct). Second-pass review falsified that:
+the banner uses the same shape — `· /memory to free up context` and `+1 more · /status` are BANNER
+lines — so the discrimination was still vocabulary, and `· /model to opt in` matched outright. The
+line-start branch also reinstated the very dependency it claimed to remove: at a fixed pane width, a
+copy edit shifting the wrap by ~14 characters puts the command at column 0 and the defect returns. A
+signal that cannot separate an ADVERT for a command from a STATUS BAR showing one carries no
+readiness information. The structural markers were widened instead — `? for shortcuts`,
+`shift+tab to cycle` and `auto-accept edits` join `bypass permissions`, so a session in auto-accept
+mode no longer depends on the prompt glyph being visible.
+
+**Second defect, found by the operator: a startup question read as ready.** Claude Code paints the
+same `❯` on a menu's focused option that it uses for the input box. This is strictly worse than the
+banner — text typed at a banner is lost, but Enter at a menu SELECTS AN OPTION, so an arriving
+message can answer a permission question on the operator's behalf. A focused menu is now its own
+state, never ready.
+
+**The verdict is no longer a boolean.** Three consumers ask this question and one of them KILLS a
+live session when the answer is not-ready. "Still painting" and "waiting on an answer" want opposite
+responses from it, so the probe now names which state it saw and each caller applies its own policy;
+the destructive caller leaves a menu alone, waits a bounded moment for the always-on auto-resolver to
+clear it, and only then treats the session as stuck.
+
+Classification moved into a small pure module so the incident's literal pane text is a
+regression fixture rather than a paraphrase.
+
+## What to Tell Your User
+
+If you ever messaged me, watched a session start, and then saw it sit there doing nothing with
+your message apparently lost — this was one way that happened. I was deciding I was awake by
+looking for certain command names on screen, and my own startup banner mentions those command
+names while advertising a feature. So I read "still starting up" as "ready", typed your message
+into a screen that was still drawing itself, and recorded it as delivered.
+
+There is a second case, sharper than the first. Sessions sometimes start by asking a question,
+and the marker drawn beside the selected answer is the same one drawn for the input box. So a
+session waiting on a question also read as ready. At a banner, a message typed too early is
+simply lost. At a question it is not lost — pressing Enter picks an answer, so an arriving
+message could have answered a permission question on your behalf. That can no longer happen.
+
+I now wait for the actual input box, or for a footer that only exists once the app is running,
+and I treat a question on screen as somewhere not to type.
+
+One honest limit: this makes typing too early far less likely, but I still report a message as
+delivered on the basis of having typed it, not on the basis of it appearing. Confirming that
+typed text actually arrived is a separate change, recorded and not bundled here.
+
+## Summary of New Capabilities
+
+- A pane showing only a startup banner is no longer classified as ready for input, so a message
+  is not injected before the session can receive it.
+- A focused selection menu is recognised as its own state and is never ready, so an arriving
+  message cannot select an option in a question meant for the operator.
+- Slash-command mentions no longer count as a readiness signal in any form — the discrimination
+  moved to markers that only exist once the TUI is running.
+- All three permission-mode footers are recognised (`bypass permissions`, `? for shortcuts`,
+  `auto-accept edits`, `shift+tab to cycle`), where previously only one was — so a session in
+  auto-accept mode no longer depends on the prompt glyph being visible.
+- The readiness verdict names which state it saw rather than answering yes/no, so the caller that
+  kills a stuck session no longer kills one that is merely waiting on a question.
+- The readiness decision is a pure, separately-testable function, so the pane text from a real
+  incident is carried as a regression fixture instead of being described.
+
+## Evidence
+
+**Reproduction (before),** real pane text against the pre-fix clause:
+
+| input | pre-fix verdict | correct verdict |
+|---|---|---|
+| the 2026-07-26 boot banner (contains `Run /model and`) | `ready` | not ready |
+| `Do you want to proceed?` + `❯ 1. Yes` / `2. No` | `ready` | menu (never ready) |
+| `Do you trust the files in this folder?` + two options | `ready` | menu (never ready) |
+| `Run /fast to enable faster output on this plan.` | `ready` | not ready |
+
+**Also falsified — the intermediate "status-bar shape" attempt,** kept here because it is the
+reason the clause was deleted rather than narrowed:
+
+| input | "shape" verdict | correct verdict |
+|---|---|---|
+| `⚠ Fable 5 promotional access ends soon · /model to opt in` | `ready` | not ready |
+| `  · /model to switch between Opus and Fable` | `ready` | not ready |
+| soft-wrapped banner putting `/model` at column 0 | `ready` | not ready |
+| `opus 5 • medium • /effort` (bullet separator) | not ready | ready |
+
+**Observed after:**
+
+| input | before | after |
+|---|---|---|
+| the 2026-07-26 boot banner | ready | **not ready** |
+| any prose or interpunct mention of `/model`, `/fast`, `/effort` | ready | **not ready** |
+| a focused startup question (3 real shapes) | ready | **menu — never typed into** |
+| ordinary output listing `1.` / `2.` above the input box | ready | ready (not mistaken for a menu) |
+| a single numbered line beside the prompt | ready | ready |
+| drawn input box (`❯`) / codex prompt (`›`) | ready | ready |
+| `⏵⏵ bypass permissions on` | ready | ready |
+| `? for shortcuts` / `auto-accept edits` / `shift+tab to cycle` | **not ready** | **ready** (newly recognised) |
+| banner that has since grown an input box | ready | ready |
+| empty / whitespace pane | not ready | not ready |
+
+**Both guards refuse.** Restoring the old slash-command clause fails six assertions; removing the
+menu classification fails three. Both include the discrimination guard, whose only job is to prove
+the probe still tells its three verdicts apart:
+
+```
+# restoring the slash-command clause
+× REGRESSION: the 2026-07-26 startup banner does NOT read as ready
+× REGRESSION: a banner line in interpunct "status-bar shape" does NOT read as ready
+× REGRESSION: a soft-wrapped banner putting /model at line start does NOT read as ready
+× an agent echoing a slash command in its own output does NOT read as ready
+× the probe discriminates > produces all three verdicts and is not stuck on one
+Tests  6 failed | 12 passed (18)
+
+# removing the menu classification
+× REGRESSION: a startup question does NOT read as ready
+× a menu is not ready to be typed into
+× the probe discriminates > produces all three verdicts and is not stuck on one
+Tests  3 failed | 15 passed (18)
+```
+
+**Scope run:** `npx tsc --noEmit` clean; every tree-scanning test under `tests/unit` plus every
+test that mocks `capture-pane` (the fixtures that feed this probe) — counts in the PR body.

package/upgrades/1.3.987.md

@@ -0,0 +1,100 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+**When the agent-to-agent relay connection dropped, nothing recorded it — so the startup line
+saying it had connected stayed the last word forever, whatever happened afterwards.**
+
+`RelayClient` emits two connection-loss events: `disconnected` (socket close; the client retries
+with exponential backoff) and `displaced` (another connection claimed this identity — **terminal**,
+because `case 'displaced': shouldReconnect = false` disarms retry for the life of the process).
+`ThreadlineBootstrap` subscribed to `message`, `unknown-sender` and `auto-discovered` — and to
+**neither** loss event. Only `listener-daemon.ts` handled them.
+
+**Observed (2026-07-26).** The agent could not send to a peer; two send paths refused with
+`Relay not connected and local delivery unavailable`. The peer's own server reported
+`ready: true, relay.connected: true` and had been listening since the previous day — the peer was
+healthy. This agent reported `ready: false, relay.connected: false`, while its last written word on
+the subject was `Threadline: relay connected` at `18:21:27Z`, with no disconnect line anywhere.
+
+**The property that made this worth fixing rather than noting: the defect concealed its own cause.**
+A `displaced` frame would fully explain why backoff never recovered the connection, and
+`ThreadlineBootstrap` documents a known displacement race between the server's client and the
+standalone listener daemon. Whether that is what fired is **unknowable**, because nothing recorded
+it — the absence of evidence was produced by the defect itself.
+
+The server now subscribes to both and records each transition, appending to
+`logs/threadline-relay-events.jsonl` and exposing the latest event on the bootstrap result.
+
+**Ordering note.** This ships observability and *not* reconnection, reversing the author's first
+plan. A reconnect fix built first would have been unverifiable — there would have been no way to
+observe whether it held.
+
+## What to Tell Your User
+
+If I have ever been unable to reach another agent and could not tell you why, this is one reason.
+My link to the shared relay could go down and leave behind a note saying it was up — not merely
+silent, but actively misleading, because that startup note was the only note that could ever exist.
+
+Two things can end that connection. An ordinary drop, which retries by itself and usually recovers.
+And being displaced, where another process takes the same identity — in which case retrying is
+switched off deliberately and permanently, so the link is gone until a restart. Those demand
+opposite reactions from anyone reading, and both were equally invisible.
+
+Now a drop is reported calmly and says a retry is coming, and a displacement is reported as an error
+that says plainly the agent cannot send or receive until it restarts.
+
+Two honest limits. This does not reconnect anything — a restart still fixes it, as before, and
+recovery is separate work. And it cannot explain the outage that prompted it, because that evidence
+was never created; what changes is that the next one is diagnosable.
+
+## Summary of New Capabilities
+
+- A relay disconnection is recorded durably instead of passing silently.
+- A relay *displacement* is recorded, flagged terminal, and reported at error level with its
+  consequence stated — that retry is disarmed and the agent cannot send or receive until restart.
+- The two are distinguishable, so a reader can tell "wait for the retry" from "this is over".
+- Every occurrence is appended rather than overwriting the last, so a flapping connection is
+  visible — the shape a reconnection bug actually takes.
+- The most recent loss event is exposed on the bootstrap result, so a status surface can report
+  *why* the relay is down rather than only that it is.
+- A connection that has never dropped records nothing and reports no last event, keeping
+  "never dropped" distinct from "dropped, cause unknown".
+
+## Evidence
+
+**Before**, on the affected agent:
+
+| surface | reading |
+|---|---|
+| peer's own server | `ready: true`, `relay.connected: true`, listening since 2026-07-25 |
+| this agent | `ready: false`, `relay.connected: false` |
+| this agent's log, last relay line | `Threadline: relay connected` @ `18:21:27Z` |
+| disconnect / displacement lines | none — no handler existed |
+
+**After** — every row asserted by a test:
+
+| event | recorded | terminal | reported as | says |
+|---|---|---|---|---|
+| `disconnected` | yes | `false` | log | will retry with backoff |
+| `displaced` | yes | `true` | **error** | retry disarmed; cannot send/receive until restart |
+| never dropped | nothing written | — | — | last event is `null`, not a falsy "unknown" |
+| 5 consecutive drops | 5 rows appended | — | — | flapping stays visible |
+| unwritable log dir | handler does not throw | — | error | console + in-memory state still correct |
+| 5,000-char reason | clamped below 400 | — | — | untrusted text is not written whole |
+| null fingerprint | `"unknown"` | — | — | recorded honestly, not as empty string |
+
+**Three guards refuse.** Each regression was introduced deliberately and the suite re-run:
+
+```
+remove the 'displaced' subscription        → 4 failed | 6 passed (10)
+remove the 'disconnected' subscription     → 7 failed | 3 passed (10)
+collapse terminal into one verdict (false) → 4 failed | 6 passed (10)
+restored                                   → 10 passed (10)
+```
+
+**Scope run:** `npx tsc --noEmit` clean; tree-scanning tests plus every threadline test — counts in
+the PR body.

package/upgrades/side-effects/booting-pane-read-as-ready.md

@@ -0,0 +1,222 @@
+# Side-Effects Review — a startup banner, and a startup menu, were read as an input prompt
+
+**Version / slug:** `booting-pane-read-as-ready`
+**Date:** `2026-07-26`
+**Author:** `Echo (instar-dev agent)`
+**Second-pass reviewer:** `independent reviewer subagent — VERDICT: CONCERN. Design changed in response; see Phase 5.`
+
+## Summary of the change
+
+`SessionManager.detectClaudePrompt` decided a pane was accepting input if the last
+six non-blank lines contained `❯`, `›`, `bypass permissions`, `/(effort|model|fast)`,
+or `(low|medium|high) · /effort`. Two independent defects:
+
+**1 — the banner.** The slash-command clause matched a bare mention **anywhere, in
+any context, including prose**. Claude Code's startup banner advertises slash
+commands in prose; the incident pane carried:
+
+> `…Fable 5 draws down usage faster than Opus 4.8. Run /model and`
+> `select Fable to use it. Learn more: https://support.claude.com/…`
+
+**2 — the menu (found by the operator).** Claude Code paints the **same `❯`** on a
+menu's focused option that it uses for the input box. A session sitting on a
+startup question therefore read as READY. This is strictly worse: text typed at a
+banner is lost, but **Enter at a menu SELECTS AN OPTION**, so an arriving message
+can answer a permission question on the operator's behalf.
+
+**Observed (topic 29723, 2026-07-26).** Inbound `17:44:49Z` → respawn → pointer
+injected `17:45:00Z` → that session's start hook completed `17:45:15Z`. The paste
+landed 15s early, was swallowed by the redraw, and the injector logged
+`Injected initial message into "…" (915 chars, after stabilization delay)` — a
+success line for a delivery that did not happen. The message reached the agent only
+via the start hook's unanswered-message backstop, an unrelated path.
+
+**The slash-command clauses are DELETED, not tuned.** The first attempt kept them
+and required "status-bar shape" (line-start or post-interpunct). Second-pass review
+falsified that, and I verified each claim before accepting it:
+
+| falsifying input | verdict under the "shape" fix |
+|---|---|
+| `⚠ Fable 5 promotional access ends soon · /model to opt in` | `ready` (false positive) |
+| `  · /model to switch between Opus and Fable` | `ready` (false positive) |
+| soft-wrapped banner putting `/model` at column 0 | `ready` (false positive) |
+| `opus 5 • medium • /effort` (bullet separator) | not ready (false negative) |
+
+The artifact's own fixture contains `· /memory to free up context` and
+`+1 more · /status` — **banner** lines in the exact shape it claimed prose never
+uses. So discrimination was still vocabulary wearing structure's clothes, and the
+line-start branch reinstated the Anthropic-copy dependency it claimed to remove
+(at a fixed pane width, a copy edit shifting the wrap ~14 chars recreates the
+original defect). A signal that cannot separate an *advert for* a command from a
+*status bar showing* one carries no readiness information. Deleted, and the
+genuinely structural markers widened instead.
+
+**The answer is no longer a boolean.** See §1 — one of three consumers KILLS a live
+session on not-ready. `classifyPaneReadiness` returns `ready | menu | not-ready`;
+`isReadyPromptTail` is retained as the façade for callers that only want "can I
+type now".
+
+## Decision-point inventory
+
+| point | classification | note |
+|---|---|---|
+| `❯` / `›` present (and not on an option line) → ready | `invariant` | Deterministic substring test. |
+| permission-mode / shortcut footer present → ready | `invariant` | Widened from one marker to four, sourced from the probes already trusted for this (`SessionReaper`, interactive-pool config) rather than invented here. |
+| selector glyph ON a numbered option line + ≥2 options → menu | `invariant` | Deterministic shape test, mirroring `PermissionPromptAutoResolver`'s existing definition rather than a second divergent one. |
+| slash-command mention → ready | **REMOVED** | Could not distinguish advert from status bar in any formulation tried. |
+| consent-dialog auto-accept | `invariant` | Unchanged, and deliberately left in `SessionManager` — it has a side effect (`send-keys`), so it does not belong in a pure classifier. Verified still running BEFORE the classifier and over all 20 captured lines. |
+
+No judgment points. No model call.
+
+## 1. Over-block
+
+**The risk is not uniform across callers, and the first draft of this section was
+wrong about that.** There are three consumers:
+
+1. `waitForClaudeReadyWithRetry` → `handleReadyAndInject` (spawn/inject). Failure
+   direction: waits, then the pre-existing extended-wait and blind-inject-if-alive
+   fallbacks apply. Safe.
+2. `waitForClaudeReady` direct, in the Slack stuck-session path (`server.ts:8395`).
+   **Failure direction: it KILLS the live session and respawns.** A tightened probe
+   that false-negatives here destroys a live conversation. `docs/signal-vs-authority.md`
+   names session lifecycle as explicitly high-risk.
+3. `classifyPaneState` (new), used by (2) to tell `menu` from `not-ready`.
+
+**Mitigations, both required by the above:**
+- The positive marker set was **widened**, not just narrowed: `? for shortcuts`,
+  `shift+tab to cycle`, `auto-accept edits` join `bypass permissions`. Previously
+  only one of Claude Code's three permission-mode footers was recognised, so a
+  session in auto-accept mode depended entirely on `❯` being visible. That
+  assumption is no longer load-bearing. All four are asserted absent from the
+  banner fixture, so the widening costs no false positives.
+- The Slack path no longer kills on `menu`. It gives the always-on auto-resolver a
+  bounded second window and re-checks; a menu that never clears falls through to
+  the pre-existing stuck path, so no message is lost.
+
+**Residual, stated honestly:** a status bar using a separator other than U+00B7 (`•`,
+box-drawing) and showing none of the four footers and no `❯` would now wait. I have
+not enumerated every Claude Code rendering across widths and themes. On caller (1)
+that costs a delay; on caller (2) the menu carve-out plus the widened footers are
+what keep it from costing a session.
+
+## 2. Under-block
+
+**Injection still reports success on having TYPED, not on arrival.**
+`verifyInjection` recovers a swallowed *submit*, not a swallowed *paste*. A pane
+that becomes ready and then stalls mid-paste still produces a success log for a lost
+message. Deliberately **not bundled** — it changes the injector's success criterion
+at every inject callsite, and folding it in would make this PR's refusal evidence
+ambiguous. Recorded as a candidate, not silently deferred.
+
+Also untouched: the probe reads the last 6 of 20 captured non-blank lines. A banner
+longer than that window pushing a real prompt out of view still reads not-ready.
+Unchanged behaviour; fails toward waiting on callers (1) and (3).
+
+The menu detector requires ≥2 numbered options. A single-option prompt, or a
+free-text startup question with no numbered options, is not detected as a menu.
+
+## 3. Level-of-abstraction fit
+
+One pure function, no state, no I/O, below `SessionManager`. The consent-dialog
+branch stayed behind because it presses keys — a classifier that mutates the pane is
+not a classifier.
+
+**A smarter component already exists and was consulted rather than duplicated.**
+`PermissionPromptAutoResolver` owns approval-prompt handling (matching, auto-answer,
+audit). This probe deliberately reuses its notion of a menu (selector glyph on a
+numbered option line) instead of inventing a second one, and does not attempt to
+answer prompts — it only declines to call a menu an input surface.
+
+Callers of the removed clause: exactly one, verified independently by grep. No
+duplicate site left holding the old semantics.
+
+## 4. Signal vs authority compliance
+
+**The first draft's answer here was materially incomplete and is corrected.** It
+claimed the probe "cannot block a message, refuse an action, or reach a user". False
+via §1(2): a not-ready verdict at `server.ts` refuses an action and kills a session.
+
+The *principle* is not violated — `docs/signal-vs-authority.md` scopes it to
+brittle logic making judgments about **meaning**, and exempts deterministic
+invariants. This is mechanics (is a glyph on screen), not meaning. But the honest
+statement is: **this probe feeds a destructive authority**, which is exactly why the
+verdict was widened from a boolean to a named state, so that authority can
+distinguish "wedged" from "waiting on an answer" instead of treating both as kill.
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+No judgment points introduced. The change moves *away* from a vocabulary match whose
+behaviour drifts as Anthropic edits its banner copy, toward structural markers. Note
+the correction to the first draft: the intermediate "status-bar shape" design did
+**not** achieve that and claimed it anyway — the claim is retracted above rather
+than quietly restated.
+
+## 5. Interactions
+
+- **`waitForClaudeReadyWithRetry` / `handleReadyAndInject`** — unchanged; both now
+  consult the corrected probe. A pane that used to pass early on the banner now
+  passes on the input box instead: later, and correctly.
+- **`server.ts` Slack stuck-session path** — changed, see §1.
+- **`PermissionPromptAutoResolver`** — complementary, not shadowed. It clears
+  prompts; this declines to type at them. The Slack carve-out explicitly depends on
+  it running (it is an always-on floor with no enable flag).
+- **`StuckInputSentinel`, `SessionWatchdog`, `PromptGate`, `PresenceProxy`,
+  `SessionReaper`, `TriageOrchestrator`, `anthropic-interactive-pool`** — each keeps
+  its own independent markers for its own question ("is it stuck?", "is it idle?").
+  None imports `detectClaudePrompt`; none carried the removed clause. Their marker
+  vocabulary is now the *source* for this probe's footers rather than a fourth
+  divergent set.
+- **`ModelSwapService`** injects literal `/model <id>` into live panes — a real
+  in-pane source of the removed token. Another reason the clause had to go.
+- **Codex / Gemini / pi panes** — the `›` clause is unchanged; they do not print the
+  Claude banner.
+
+## 6. External surfaces
+
+None. No route, no config key, no CLI flag, no message text, no state file. Two new
+exported functions and one new public method on `SessionManager`, all internal.
+
+## 6b. Operator-surface quality
+
+One new log line when the Slack path declines to kill a session on a menu, naming
+the session and the reason. The pre-existing failure lines are unchanged.
+
+Worth recording for the follow-up: the *success* line still reports typing, not
+arrival — the asymmetry that hid this incident for seven hours is untouched here.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+Machine-local by construction — the probe reads a tmux pane on the machine that owns
+it. No replication, no lease interaction, no shared state, no generated URL. Two
+machines on different versions apply their own probe to their own panes; there is no
+cross-machine invariant to violate.
+
+## 8. Rollback cost
+
+Low. Delete the module, restore the inline clauses, revert one `server.ts` block. No
+migration, no persisted state, no config default, nothing written to an agent home.
+The test file would fail on revert, which is the desired property.
+
+## Phase 5 — Second-pass review (independent reviewer subagent)
+
+**VERDICT: CONCERN** — one blocking, four should-fix, one note. Every finding was
+independently verified before being accepted; all were real.
+
+| # | finding | disposition |
+|---|---|---|
+| 1 (blocking) | Unenumerated third consumer at `server.ts:8395` kills a live session on not-ready, so §1's "the failure direction is waiting, which is safe" and §4's "cannot refuse an action" are false for it. | **Design changed.** Verdict widened to `ready \| menu \| not-ready`; Slack path given a menu carve-out + bounded re-check; §1 and §4 rewritten. |
+| 2 (should-fix) | The `^` line-start branch reinstates the Anthropic-copy dependency via wrap geometry, and carries no test weight. | **Clause deleted entirely** (both branches). |
+| 3 (should-fix) | "Shape, not vocabulary" is falsified by the artifact's own fixture; `· /model to opt in` matches. | **Verified and accepted.** Clause deleted; the claim is retracted in §4b rather than restated. |
+| 4 (should-fix) | "A ready pane always shows `❯`" is contradicted by four sibling probes; only one of three permission-mode footers was covered. | **Marker set widened** to four footers, sourced from those siblings. This is also the mitigation for #1. |
+| 5 (should-fix) | §4 Q4 materially incomplete. | **Rewritten** above. |
+| 6 (note) | Interpunct is U+00B7 only; `•` and box-drawing are false negatives. `ModelSwapService` injects `/model` into live panes. | Moot for the separator (clause deleted); the `ModelSwapService` point is recorded in §5 as further justification. |
+
+**Independently found by the operator, in parallel:** the menu case (§ Summary 2).
+Verified against three realistic startup questions, all three of which read as ready
+before this change.
+
+**Reviewer concurrence on the revised design was not re-sought.** The revision was
+driven by the reviewer's own findings plus a verified operator report, and every
+change is pinned by a test asserting both sides of its boundary. That is a
+disclosed reduction in independence for the second iteration, not a claim of
+concurrence.

package/upgrades/side-effects/relay-drop-was-unrecorded.md

@@ -0,0 +1,160 @@
+# Side-Effects Review — a relay that dropped left "connected" as the last word
+
+**Version / slug:** `relay-drop-was-unrecorded`
+**Date:** `2026-07-26`
+**Author:** `Echo (instar-dev agent)`
+**Second-pass reviewer:** `see Phase 5`
+
+## Summary of the change
+
+`RelayClient` emits two connection-loss events: `disconnected` (socket close, client
+retries with backoff) and `displaced` (another connection claimed this identity —
+**terminal**, because `case 'displaced': shouldReconnect = false` disarms retry for
+the life of the process). `ThreadlineBootstrap` subscribed to `message`,
+`unknown-sender` and `auto-discovered` — and to **neither** loss event. Verified by
+grep: both return empty in that file. Only `listener-daemon.ts` handles them.
+
+So the server logged `Threadline: relay connected (fingerprint: …)` and could log
+nothing afterwards, whatever happened.
+
+**Observed (2026-07-26, topic 29723).** The agent could not send to peer
+`instar-codey`; two send paths refused with `Relay not connected and local delivery
+unavailable`. The peer's own server reported `ready:true, relay.connected:true`,
+listening since 2026-07-25 — the peer was fine. This agent reported
+`ready:false, relay.connected:false`, while its last written word on the subject was
+`relay connected` at 18:21:27Z, with no disconnect line anywhere.
+
+**The property that makes this worth fixing rather than noting: the defect conceals
+its own cause.** `displaced` would fully explain why exponential backoff never
+recovered the connection. Whether a `displaced` frame arrived is **unknowable**,
+because nothing recorded it. The absence of evidence is produced by the defect.
+`ThreadlineBootstrap` itself documents a known "displacement race" between the
+server's client and the standalone listener daemon — a candidate, **not asserted**.
+
+This change RECORDS transitions. It does not reconnect and does not alter client
+behaviour. That ordering is deliberate and is a correction to my own first plan
+("reconnect, then observe"): a reconnect fix built first would have been
+unverifiable, because there would be no way to see whether it held.
+
+## Decision-point inventory
+
+| point | classification | note |
+|---|---|---|
+| `disconnected` → record, non-terminal | `invariant` | Deterministic event subscription. |
+| `displaced` → record, terminal + error-level | `invariant` | Same. `terminal` is stored explicitly rather than inferred, because "will retry" vs "will never retry" is the distinction a reader needs and they are otherwise identical. |
+| reason string clamped to 300 chars | `invariant` | The reason originates off-machine; it is treated as untrusted text, never structured data. |
+| audit-write failure swallowed | `invariant` | An observer must not throw out of a handler on the path it observes. |
+
+No judgment points. No model call. Nothing gates or blocks.
+
+## 1. Over-block
+
+Nothing is blocked. The observer only appends and logs; it cannot refuse a
+connection, a send, or a message. The strongest available failure is noise in the
+log if the relay flaps — which is information, not a block, and is the signal a
+future reconnect fix will be judged against.
+
+## 2. Under-block
+
+**It does not fix the outage.** The relay is still down as of writing, and this
+change does not reconnect it. Restarting the server restores the connection; that is
+unchanged and untouched.
+
+**It does not identify tonight's cause.** That evidence was destroyed before it
+existed. The honest claim is narrower than it looks: the *next* occurrence becomes
+diagnosable, this one does not become explicable.
+
+**It observes only the server's client.** The MCP server and the listener daemon each
+construct their own client. The daemon already handles both events; the MCP path is
+untouched and remains unobserved. Recorded, not silently deferred.
+
+**A record that is never read is only half of observability.** This writes a durable
+JSONL and exposes the latest event through the bootstrap result. Surfacing it on
+`/threadline/status` is the obvious next step and is deliberately not bundled — this
+PR's refusal evidence is about recording, and mixing a route change in would blur it.
+
+## 3. Level-of-abstraction fit
+
+A pure-ish module (`fs` only), below the bootstrap, testable with a fake
+`EventEmitter` and no socket. The bootstrap owns wiring; the module owns recording.
+
+**A smarter component already exists and was consulted, not duplicated.**
+`listener-daemon.ts` handles both events and writes `listener-displaced-alert.json` —
+a single-slot file. This deliberately appends instead: a one-slot file cannot show a
+flapping connection, which is exactly the shape a reconnect bug takes.
+
+## 4. Signal vs authority compliance
+
+Pure signal. It records and logs; it holds no authority over anything. It cannot
+block a send, refuse a connection, or influence reconnection. `docs/signal-vs-authority.md`
+is satisfied trivially — there is no decision to misplace.
+
+The one risk an observer can carry is taking down what it watches. That is closed by
+swallowing audit-write failures, asserted by a test.
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+None introduced. Every branch is a deterministic event subscription.
+
+## 5. Interactions
+
+- **`listener-daemon.ts`** — already handles both events independently; unchanged.
+  Its single-slot alert file is left alone; this is a second, additive record.
+- **`ThreadlineClient` / `RelayClient`** — unchanged. No new emissions, no altered
+  reconnect behaviour, no change to `shouldReconnect`.
+- **The daemon-handles-relay branch** — when the daemon owns the relay, the server
+  never connects and the observer is never attached. Correct: nothing to observe.
+- **`/threadline/status`** — unchanged in this PR (see §2).
+
+## 6. External surfaces
+
+One new durable file, `logs/threadline-relay-events.jsonl`, and one optional field on
+the bootstrap result. No route, no config key, no CLI flag, no message to any user.
+
+**Content:** timestamps, event names, this agent's own fingerprint, and a clamped
+reason string from the relay. No message bodies, no peer content.
+
+## 6b. Operator-surface quality
+
+Two new log lines. The displacement line is error-level and states the consequence in
+plain terms — that retry is disarmed and the agent cannot send or receive until
+restart — rather than naming the event and leaving the reader to infer what it means.
+The disconnect line is calm and says a retry is coming. That difference is the entire
+point; a reader must be able to tell "wait" from "this is over".
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+Machine-local by design. Each machine observes its own relay client and writes its own
+record; a relay connection is per-process and cannot be reasoned about remotely. No
+replication, no lease interaction, no shared state, no generated URL.
+
+## 8. Rollback cost
+
+Low. Delete the module, remove one import, one declaration, one call, one optional
+result field. No migration, no persisted state anyone reads yet, no config default,
+nothing installed into an agent home. The test would fail on revert, announcing it.
+
+## Phase 5 — Second-pass review
+
+The change touches the session/dispatch family only in the sense that it observes it;
+it holds no authority, gates nothing, and cannot alter connection behaviour, so the
+high-risk trigger list (block/allow decisions, session lifecycle, trust) is not
+engaged. Author-applied lenses, disclosed:
+
+**Adversarial — "how would I make this useless?"** By recording to a single slot (a
+flap would overwrite itself) or by letting a write failure kill the handler. Both are
+closed and asserted by tests.
+
+**"Did I fix the symptom or the cause?"** Neither — deliberately. This fixes the
+*blindness*, which is a precondition for diagnosing the cause. Stated plainly in §2
+rather than implied.
+
+**"Would it have caught the incident?"** It would have recorded the transition and,
+if a displacement occurred, said so at error level with the consequence spelled out.
+It would not have prevented it.
+
+**Weakest point:** §2's last item. A durable record that no status surface reads is
+observability only for someone who knows the file exists. I judged the route change
+worth separating to keep this PR's refusal evidence unambiguous, but a reader could
+reasonably call that half a job — which is why it is written down here rather than
+left for them to notice.