instar 1.3.1004 → 1.3.1006

package/upgrades/1.3.1005.md

@@ -0,0 +1,235 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`GET /channels` covers WhatsApp and iMessage. Both adapters existed but had no registry row — a gap
+recorded explicitly when the direct user channels shipped, and a hole in the registry's own
+"absence is impossible" property, since a channel with no row cannot report that it is missing.
+
+WhatsApp is read from `getStatus().state`, a real state machine rather than a boolean, so
+`qr-pending` maps to `reachable-no-credential` — the link is alive and waiting for a human to scan a
+pairing code, and a restart will not help. `connecting`/`reconnecting` report `unknown` with the phase
+named rather than being guessed; `disconnected`/`closed` are `broken`; an unrecognised state is
+`unknown`, never `working`.
+
+iMessage is read from `getConnectionInfo().state`, deliberately NOT the sibling `connectedAt` — that
+field is computed as `started ? new Date().toISOString() : undefined`, so it reports the moment you
+asked rather than the moment it connected. A source ratchet fails if anyone wires it in.
+
+`IMessageAdapter.getConnectionInfo().connectedAt` was computed inline as
+`started ? new Date().toISOString() : undefined`, so it reported the moment of the READ rather than
+the moment of connection. Three reads produced three different "connection times", all wrong.
+
+The instant is now captured once, immediately after `started` flips true in `start()`, and cleared in
+`stop()`. An adapter that never connected reports no time.
+
+Adds `scripts/recheck-parked-tests.mjs` — the missing EXIT PATH for `vitest.push.config.ts`'s
+`FLAKY_TESTS`. Entry to that list costs nothing (the file is classified as ordinary config, so
+removing a guard from CI needs no artifact), and nothing ever re-checked whether a parked test could
+return. Entry free, exit impossible, ungated surface monotonically growing.
+
+The script reports which parked entries now pass deterministically and which point at files that no
+longer exist. It never re-arms and never edits config.
+
+Skipping the host-wide test-runner bound via `INSTAR_HOST_TEST_SEMAPHORE=off` printed a deterministic
+warning — identical on every run. The shared detector that counts sustained self-disables was consumed
+only by `dev:preflight`, hours downstream.
+
+Measured on 2026-07-27: an agent self-disabled the bound 37 times in about three hours and read the
+same warning 37 times as routine output. The detector's threshold is 3.
+
+The skip warning now also reports the current count, that this is no longer an exception, and that
+`dev:preflight` fails on the signature. It reuses the shared detector, so the number in the warning
+and the number that fails preflight cannot drift.
+
+`scripts/lib/classify-tier.mjs` no longer treats a `.config` FILENAME reference as evidence of a
+config surface. The `\.config\b` alternative in `CONFIG_SURFACE_HINT` matched any text containing
+`.config`, including filenames — so a script that merely READ `vitest.push.config.ts`, combined with
+an ordinary object literal, fired "new capability: new config key added" and raised that change's risk
+floor to 2.
+
+## What to Tell Your User
+
+Your agent can now tell you whether WhatsApp and iMessage are actually working, alongside Telegram and
+Slack.
+
+The useful part is what it says when WhatsApp is waiting for you to scan a pairing code. That is not
+broken — the connection is fine, it just needs you for a moment — and restarting things would not fix
+it. It now says exactly that, instead of lumping it in with a dropped connection.
+
+It is also careful about what it does not know. If a link is mid-connection it says so rather than
+guessing, and a working link means the connection was up when it checked, not a promise that a message
+to one particular person will arrive.
+
+If your agent uses iMessage, the "connected since" time it reported was never real — it was recomputed
+as the current time every time anything asked, so it always said "just now".
+
+That is a small thing that could have caused a confident wrong answer, because a precise-looking
+timestamp invites questions like how long has this been up or did it drop recently. Those would all
+have been answered with a number that meant nothing.
+
+It now records the moment it actually connects, and reports nothing at all when it is not connected —
+which is the honest answer rather than a placeholder.
+
+None — internal change (no user-facing surface).
+
+None — internal change (no user-facing surface).
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+No new endpoint, command, or config key. `GET /channels` gains `user-whatsapp` and `user-imessage`
+rows with live-state verdicts.
+
+No new endpoint, command, or config key. The iMessage connection-info object now reports a real
+connect instant instead of the current time.
+
+None — internal change (no user-facing surface).
+
+None — internal change (no user-facing surface).
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+Falsified by flattening `qr-pending` to `broken` in production:
+
+```
+× THE STATE A BOOLEAN LOSES: qr-pending is reachable-no-credential, not broken
+  → expected 'broken' to be 'reachable-no-credential'
+  Tests  1 failed | 15 passed (16)
+```
+
+Restored byte-identical. Green across every suite touching the change:
+`Test Files 5 passed (5) · Tests 59 passed (59)` (`user-channel-wa-imessage`,
+`user-channel-liveness`, `channel-registry`, `channel-registry-claims`, `channels-route`);
+`tsc --noEmit` exit 0. The integration test pinning the exact channel set and the audience partition
+was updated in this change rather than left for CI to catch.
+
+Falsified by restoring the inline expression:
+
+```
+× THE FIX: getConnectionInfo no longer manufactures a timestamp on read
+  → expected 'getConnectionInfo(): ConnectionInfo {…' not to match /new Date\(\)/
+  Tests  1 failed | 3 passed (4)
+```
+
+Restored byte-identical. Green across every iMessage suite:
+`Test Files 4 passed (4) · Tests 64 passed (64)`; `tsc --noEmit` exit 0. No production consumer reads
+the field — verified by grep; the only references are comments explaining why the channel-registry row
+deliberately does not use it.
+
+Measured on current main, three consecutive runs each: `notification-spam-prevention.test.ts`
+15/15/15, `message-formatter.test.ts` 17/17/17, `ReflectionConsolidator.test.ts` 16/16/16 — all parked
+as broken or non-deterministic, all repaired at some point and never re-armed. Note the inverse of the
+2026-06-05 note in that same file: those tests rotted while parked; these were fixed while parked.
+Nobody noticed either way. Plus one dangling entry: `tests/unit/slack-stall-active-gate.test.ts` is
+excluded and does not exist.
+
+Falsified by restoring the naive parser:
+
+```
+× THE PARSER: prose in the array does not become an entry        → s own
+× finds the dangling entry ...                                   → expected 42 to be less than 5
+× REGRESSION: an apostrophe in a comment cannot corrupt the parse
+  Tests  3 failed | 2 passed (5)
+```
+
+Restored byte-identical; 5 passed.
+
+Live, against the real ledger:
+
+```
+WARN: SKIPPING the host-wide test-runner bound (reason: off) — posture: off. …
+WARN: this is self-disable #39 on this host within the detector's window (threshold 3).
+WARN: that is no longer an exception — it is the pattern the detector exists to find.
+WARN: `instar dev:preflight` FAILS on this signature …
+```
+
+Falsified by reverting the mapping to the originally-guessed field name:
+
+```
+× THE FIX: fires on the detector's real output shape → expected null not to be null
+× fires exactly AT the threshold
+  Tests  2 failed | 3 passed (5)
+```
+
+Restored byte-identical. Green: `Test Files 3 passed (3) · Tests 121 passed (121)`; `tsc --noEmit`
+exit 0.
+
+Falsified by restoring the alternative:
+
+```
+× does NOT fire on a mere .config FILENAME reference — the reproduction of the real case
+  → reading a .config filename is not adding a config key: expected 2 to be 1
+  Tests  1 failed | 48 passed (49)
+```
+
+Restored byte-identical; 49 passed, including all 47 pre-existing classifier tests unchanged. A second
+new test iterates every remaining anchor (`ConfigDefaults`, `defaultConfig`, `InstarConfig`,
+`configSchema`) and asserts the floor still rises — narrowing a check must not blind it.
+
+## Also in this change: the Telegram row now names its subject
+
+Found by checking the shipped feature on a running agent rather than only in tests. `/capabilities`
+reported `telegram: { configured: true, adapter: true, bidirectional: true }` while `/channels`
+reported `user-telegram: unknown — the Telegram poll loop is not running` — the config surface and the
+live surface disagreeing, which is exactly what this registry exists to expose.
+
+But the row was measuring the SERVER process's adapter and presenting it as the channel's state. On a
+lifeline deployment inbound never goes through that adapter: a separate lifeline process polls and
+forwards, and the server logs "Telegram relay wired (via lifeline callback forwarding)". Inbound was
+healthy; a stopped server poller is normal there.
+
+That is the same scope error the `threadline-relay` row was fixed for in #1667 — a true statement
+whose subject is unstated, so the reader concludes something about a path that was never measured.
+The verdict stays `unknown` (what it can see is genuinely undetermined); it now names the server
+adapter and says plainly that this alone does not mean messages are not arriving.
+
+## Known limits
+
+`working` means the link was up when probed — not that a message to a particular chat or contact
+would land. Neither row probes a round-trip, because a status read must not send. iMessage is bound to
+the host running its backend, recorded as a real cost of choosing it.
+
+`lastError` and `reconnectAttempts` in the same object are still hardcoded `undefined` / `0`. They are
+the same class of defect and are deliberately not fixed here — inventing values for them would repeat
+the error this corrects. The field also says nothing about connection quality.
+
+It never re-arms — a local deterministic-pass does not establish a CI pass, and a third of the list is
+parked for a native-binding reason whose stated scope is "on this machine". Glob entries are reported
+rather than resolved. Only a rotating slice runs per invocation, so a single run does not survey the
+whole list; the output says how many it checked.
+
+Louder text only — it cannot refuse a run, and making the kill switch refuse was considered and
+rejected (a kill switch that stops working after three uses is not a kill switch). It fires only for
+`reason: 'off'`; the spoofed-CI skip is not escalated, since that path has a different population and
+no measurement behind it.
+
+If a genuine config-key addition mentions only a `*.config.ts` filename and none of the remaining
+anchors, its floor will no longer rise. The remaining anchors cover this repo's actual config
+surfaces, and the both-sides test guards against a future narrowing that blinds the check — but this
+is a heuristic over diff text and always was.
+
+## Correction
+
+The first (naive) parser reported 92 parked entries; the true count is 91. That wrong number was
+published in the release note of the earlier re-arm change. Recorded rather than silently fixed.
+
+## Built-in caution
+
+Two implementations of this produced no output and no error — one un-awaited promise, one guessed data
+shape swallowed by the best-effort catch. Both were found by running it and reading the output. The
+fallible mapping is now a pure exported function pinned against the detector's real shape, so a future
+shape change fails a test rather than vanishing into the catch.
+
+## Why it mattered
+
+The floor is what makes a tier declaration meaningful: declaring under it is permitted but audited as
+a deliberate override. A floor that fires on a filename teaches authors that below-floor declarations
+are routine, which is how a real floor gets argued past later. A noisy guard degrades the guard it
+belongs to.

package/upgrades/1.3.1006.md

@@ -0,0 +1,69 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed an addressing bug that could prevent two healthy agents from ever exchanging a
+Threadline message.
+
+`threadline_discover` returns each agent's fingerprint truncated to 8 hex characters, and
+`threadline_send`'s own parameter documentation advertises that short form
+(`"fd9268c2..."`). But `ThreadlineClient.resolveAgent` had no branch for a bare prefix: it
+fell through to name matching, found no agent *named* `7970149e`, and returned null. The
+send then failed with `Agent not found: "7970149e"`. The documented discover-then-send
+workflow could not complete.
+
+`resolveAgent` now accepts a bare fingerprint prefix, and **requires a unique match**. This
+matters: `resolveAgent` decides which peer receives a message, and discovery can legitimately
+return two rows for the same agent (a live registration and a stale one). Resolving a prefix
+to "whichever matched first" would have silently delivered to the wrong agent while reporting
+success — worse than not delivering at all. When several agents share a prefix and exactly
+one is online, the live one wins (the same allowance name resolution already makes for
+live-vs-stale twins). Otherwise the send is refused with every candidate and its full
+fingerprint listed, so the caller can say precisely which they meant.
+
+Non-hex input, and any prefix matching no known fingerprint, fall through untouched — name
+resolution, including for agents with hex-like names, behaves exactly as before.
+
+## What to Tell Your User
+
+If you have ever tried to connect two of your agents over Threadline and been told the other
+agent could not be found — while both were plainly running and correctly configured — this is
+very likely why, and it is fixed.
+
+The short agent ID your agent sees when it looks up its peers is now an address it can
+actually send to. Nothing changes about how you ask for it; "message my other agent" simply
+works where it may previously have failed with a confusing not-found error.
+
+One deliberate behaviour worth knowing: if a short ID is ambiguous because two agents share
+those opening characters, your agent will now stop and list them rather than pick one. That
+is intentional. A message delivered to the wrong agent looks like success and is much harder
+to notice than a message that refuses to send.
+
+## Summary of New Capabilities
+
+- Agent-to-agent messaging accepts the short (8-character) agent fingerprint that agent
+  discovery returns, closing a gap where the discover-then-send workflow could not complete.
+- Ambiguous short IDs are reported with the full candidate list instead of resolving to an
+  arbitrary agent, so a message can never be silently delivered to the wrong peer.
+- A stale duplicate registration no longer makes a working address ambiguous when exactly one
+  matching agent is online.
+
+## Evidence
+
+The tests were run against unmodified source *before* the fix was applied, to prove they
+exercise the bug rather than merely accompany it:
+
+- Fix reverted: **5 failed / 21 passed** — the 5 failures are precisely the new behaviours
+  (8-char prefix resolves, case-insensitivity, ambiguity throws, candidates named in the
+  error, live-row preference). The 21 that pass are the deliberate regression guards.
+- Fix applied: **26 passed**.
+- Regression surface: `tests/unit/threadline/` — **65 files, 1581 tests, all passing**.
+- `tsc --noEmit` clean.
+
+Observed live on 2026-07-27 between two running, relay-connected agents on the same machine.
+Both ends failed symmetrically — each reported the other as "not found" while holding the
+other's address — which is what identified the seam between the two tools, rather than either
+agent, as the defect.

package/upgrades/side-effects/imessage-connected-at.md

@@ -0,0 +1,62 @@
+# Side-effects review — iMessage connectedAt is recorded, not synthesised
+
+**Change:** `IMessageAdapter.getConnectionInfo().connectedAt` returned
+`started ? new Date().toISOString() : undefined` — the time of the READ, never the time of the
+connection. It now returns a value captured once at connect and cleared on stop.
+
+**Decision point touched?** No. Status reporting only; nothing gates on this field.
+
+---
+
+## 1. Over-block
+
+None — nothing is rejected or blocked. The only behavioural change is that a value which was always
+populated-while-running can now be `undefined` in one new case: an adapter whose `started` flag is
+true but which has not passed through `start()` in this process (not reachable through the public
+API, since `start()` is what sets `started`).
+
+## 2. Under-block
+
+The field is now accurate about connect time but still says nothing about connection QUALITY — a
+long-lived connection that has been failing to deliver reports the same timestamp as a healthy one.
+Unchanged by this and not claimed.
+
+Also unchanged: `lastError` and `reconnectAttempts` in the same object are still hardcoded
+`undefined` / `0`. They are the same class of defect — fields that look informative and carry no
+information — and are deliberately NOT fixed here, because inventing values for them would repeat
+the error this change corrects. Named rather than silently left.
+
+## 3. Level-of-abstraction fit
+
+Correct: the adapter is the only thing that knows when it connected, so it is the only place the
+instant can be recorded honestly. Nothing downstream can reconstruct it.
+
+## 4. Signal vs authority compliance
+
+Pure signal, unchanged in authority. It makes an existing signal truthful rather than adding one.
+
+## 5. Interactions
+
+No production consumer reads `connectedAt` — verified by grep across `src/`; the only references are
+comments in `userChannels.ts` and `routes.ts` explaining why the channel-registry row deliberately
+does NOT use it. Those comments remain accurate: the row is built on `state`, which is the right
+liveness signal regardless of this fix.
+
+`ConnectionInfo.connectedAt` is already optional in the type, so returning `undefined` when not
+connected requires no type change.
+
+## 6. External surfaces
+
+None directly. The value appears in whatever surfaces render `getConnectionInfo()`. Anything that was
+displaying it was displaying fiction; it will now show a real instant or nothing.
+
+## 7. Multi-machine posture
+
+Machine-local by design and inherently so: the adapter and its backend run on one host, and a
+connection instant is a fact about THIS process. There is no state to replicate and a cross-machine
+view would be meaningless — another machine's connect time says nothing about this one's.
+
+## 8. Rollback cost
+
+Trivial: restore the inline expression and drop the field. No persisted state, no schema, no
+migration. Rolling back restores a fabricated timestamp, so it should carry a reason.

package/upgrades/side-effects/parked-test-recheck.md

@@ -0,0 +1,71 @@
+# Side-effects review — parked-test re-check (the exit path for FLAKY_TESTS)
+
+**Change:** adds `scripts/recheck-parked-tests.mjs`, which reports which `FLAKY_TESTS` entries now
+pass deterministically and which point at files that no longer exist. Read-only; never edits config.
+
+**Decision point touched?** No gate is added or changed. It informs a human judgement (should this
+test be re-armed?) that currently has no prompt at all.
+
+---
+
+## 1. Over-block
+
+None possible: the script always exits 0 and modifies nothing. Making it a gate was considered and
+rejected — a red build for a test somebody parked deliberately would recreate the original problem
+from the other side.
+
+## 2. Under-block
+
+Deliberate and central: it does NOT re-arm. A local deterministic-pass does not establish a CI pass,
+and roughly a third of the list is parked for a native-binding failure whose stated scope is literally
+"on this machine" while CI is a different environment. Auto-re-arming on local green would be the
+confident-wrong-answer this area keeps producing.
+
+It also cannot evaluate glob entries (`tests/unit/threadline/**`) — those are reported separately
+rather than resolved, because a glob is not a file and pretending otherwise would put fake entries in
+the missing list.
+
+Bounded by default: only a rotating slice is executed per run. So a single run does NOT survey the
+whole list, and the output says how many were checked. Under-coverage that announces itself.
+
+## 3. Level-of-abstraction fit
+
+Correct. The gap is that the exclusion list has an entry path and no exit path; this is the exit
+path's reporting half. The complementary half — requiring evidence on ADDITIONS — is tracked
+separately (ACT-1341) and is a gate change, not a report.
+
+## 4. Signal vs authority compliance
+
+Pure signal, and deliberately so. Per `docs/signal-vs-authority.md` it produces information for an
+authority (a human) that already exists; it holds none itself.
+
+## 5. Interactions
+
+Reads `vitest.push.config.ts` by literal parse rather than importing it — importing would execute the
+config, and this must remain safe to run against a config that does not load. It executes vitest as a
+subprocess for the sampled files; those runs go through the normal host test-runner bound like any
+other.
+
+No production code touched. Nothing imports the script.
+
+## 6. External surfaces
+
+None. A developer-facing script; no endpoint, no config key, no agent-visible behaviour.
+
+## 7. Multi-machine posture
+
+Not applicable in the replication sense, and that is itself the point: the answer it produces is
+about THIS machine's environment, and the script says so in its own output note. A cross-machine
+merged view would be actively misleading, since the whole question is whether a local environment
+reason still holds.
+
+## 8. Rollback cost
+
+Trivial — delete the script and its test. No state, no schema, no consumers.
+
+## A correction this change surfaced
+
+The first implementation's naive parser produced a count of 92 parked entries. The true count is 91.
+That wrong number was published in the release note of the earlier re-arm change (`#1668`). It is
+recorded here rather than silently corrected, because a plausible-but-wrong number that reached an
+artifact is exactly the failure class this repository keeps finding.

package/upgrades/side-effects/selfdisable-escalation.md

@@ -0,0 +1,78 @@
+# Side-effects review — escalate the self-disable warning at the point of use
+
+**Change:** when the test-runner bound is skipped via `INSTAR_HOST_TEST_SEMAPHORE=off`, the existing
+deterministic warning is followed by an escalation naming how many self-disables the shared detector
+already sees in its window, and that `dev:preflight` fails on the signature.
+
+**Decision point touched?** No gate, no blocking, no new authority. It adds output to an existing
+logging path. The bound's behaviour is unchanged in every posture.
+
+---
+
+## 1. Over-block
+
+None possible — it prints lines. It cannot refuse, delay, or fail a run. Explicitly considered and
+rejected: making the chokepoint REFUSE on a sustained pattern. The kill switch exists for genuine
+emergencies, and a kill switch that stops working after three uses is not a kill switch. Escalating
+the signal is the correct lever; removing the escape hatch is not.
+
+## 2. Under-block
+
+It is only louder text. A reader determined to ignore it still can, and someone scripting `off`
+permanently will see it scroll past forever. This narrows the gap between the moment of the decision
+and the moment of the consequence; it does not close it.
+
+It also fires only for `reason === 'off'`. The other loud skip (spoofed CI on a dev host) is graded
+"like off" by the spec and is NOT escalated here — deliberate scope, since that path has a different
+population and I have no measurement for it.
+
+## 3. Level-of-abstraction fit
+
+Correct: the chokepoint is where the decision is observable at the moment it is made. The detector
+already existed but was consumed only by `dev:preflight`, hours downstream. This wires the same
+detector to the earliest surface, and reuses it rather than re-counting so threshold and window
+cannot drift between the two consumers.
+
+## 4. Signal vs authority compliance
+
+Pure signal, and deliberately kept so. The escalation informs; the human or agent decides; the
+existing preflight check retains whatever authority it had.
+
+## 5. Interactions
+
+`skipLine` becomes async and is awaited at all seven call sites in `globalSetup`. That is load-bearing
+rather than cosmetic: the first implementation used fire-and-forget and the escalation never printed,
+because globalSetup returns before the promise settles.
+
+The lookup dynamically imports `scripts/lib/test-runner-selfdisable-patterns.mjs` from a test setup
+file. Wrapped so a resolution failure degrades to the plain line.
+
+Adds one ledger read (bounded to the detector's own `DEFAULT_MAX_EVENTS`) per SKIPPED run only — never
+on the acquire path.
+
+## 6. External surfaces
+
+None. Test-run stderr only; no endpoint, no config key, no user-facing behaviour.
+
+## 7. Multi-machine posture
+
+Machine-local by design and inherently so: the ledger records what THIS host did, and the bound is a
+per-host concurrency limit. A cross-machine count would be meaningless — another machine's
+self-disables say nothing about this one's.
+
+## 8. Rollback cost
+
+Trivial: drop the escalation block and revert `skipLine` to sync. No state, no schema, no consumers.
+
+## What this change's own construction demonstrated
+
+Two implementations produced NO output and NO error. The first attached the lookup to an un-awaited
+promise; the second guessed the detector's shape and had the mistake swallowed by the best-effort
+catch that exists so a louder warning cannot break a run. Both were found by running it and reading
+the output, not by anything failing.
+
+That is the same failure class as the change's subject, twice, inside the change. The response was
+structural rather than resolving to be careful: the fallible mapping is now a pure exported function
+pinned against the detector's real output shape, so a future shape change fails a test instead of
+disappearing into the catch. The catch stays — it is correct that this cannot break a run — but it no
+longer has anything unverified to hide.

package/upgrades/side-effects/threadline-prefix-resolve.md

@@ -0,0 +1,136 @@
+# Side-effects review — bare fingerprint-prefix addressing in `resolveAgent`
+
+**Change:** `ThreadlineClient.resolveAgent` gains a bare fingerprint-prefix branch
+(`findAgentByFingerprintPrefix`), so the 8-char fingerprint `threadline_discover`
+emits is an address `threadline_send` will actually accept.
+
+**Discovered:** live, 2026-07-27. Echo → instar-codey. Both agents healthy, both
+relay-connected, correct chat, correct topic. Every send answered
+`Agent not found: "7970149e"`. Codey's own reply to Echo failed with the mirror-image
+error `Agent not found: "63b1dbb2"`. Neither agent was misconfigured — the address one
+tool handed out was an address the other tool refused.
+
+## 1. Over-block — what legitimate input does this reject that it shouldn't?
+
+None. The new branch only ever *adds* resolutions; it returns `undefined` for any input
+that is not a bare hex string of 4–64 chars, and for any hex string that matches no
+known fingerprint. In both cases control falls through to the pre-existing name path
+unchanged.
+
+The one input class that now behaves differently in a *rejecting* direction is an
+**ambiguous** prefix — two known agents sharing it. That previously resolved to `null`
+("not found"); it now throws a named-candidates error. This is strictly more informative
+than the old outcome, and the alternative (silently picking) is the failure this review
+most wants to prevent. See §4.
+
+## 2. Under-block — what does this still miss?
+
+- **Discover still emits 8 chars while its neighbouring comment says 32.**
+  `ThreadlineMCPServer.ts` sets `entry.fingerprint = a.publicKey.substring(0, 8)` at two
+  sites (lines 510, 870 on main) beside a comment reading "fingerprint = first 32 hex
+  chars". This change makes the 8-char form *work* rather than making the two halves
+  agree. Deliberate: changing discover's output is a contract change to every existing
+  consumer, whereas widening the resolver is backward-compatible and fixes all current
+  callers at once. The inconsistency is recorded here rather than silently fixed.
+  <!-- tracked: ACT-1380 -->
+- **A 4-char prefix is permitted.** With a large enough agent population, 4 hex chars
+  will collide. Collisions surface as the ambiguity error rather than a wrong delivery,
+  so the failure mode is safe, but it is a usability cliff at scale rather than a
+  correctness one.
+- This does not address unreachability caused by anything other than addressing — a dark
+  relay, an unpaired peer, or a trust refusal are all untouched.
+
+## 3. Level-of-abstraction fit
+
+Correct layer. `resolveAgent` is the single funnel every send path already goes through
+(`routes.ts:12841` calls `relayClient.resolveAgent(targetAgent)` and 404s on null). Fixing
+it here fixes the MCP tool, the HTTP route, and any future caller at once. Fixing it in
+the MCP tool would have left the HTTP route broken; fixing it in discover would have
+changed a published output shape without helping callers who already hold a short
+fingerprint from an older message or a log line.
+
+## 4. Signal vs authority compliance
+
+`resolveAgent` is an *authority* — its return value directly determines which peer
+receives a message. That is precisely why the new branch **requires a unique match**.
+
+The tempting implementation is "match the prefix, take the first hit." That would have
+made my own send succeed today, because discover returned **two** `instar-codey` rows
+(`092c1cac…` and `7970149e…`) and only one is live. Taking the first would have delivered
+to whichever the map happened to yield first — a silent wrong-recipient delivery, which is
+categorically worse than a failed send, because the sender believes it succeeded.
+
+So the branch reuses the existing convention exactly:
+- exactly one match → resolve
+- several matches, exactly one online → resolve to the live one (`pickSingleOnline`, the
+  same live-vs-dead twin allowance `findAgentByName` already makes)
+- otherwise → throw, naming every candidate and its full fingerprint
+
+Ambiguity is surfaced to the caller as a decision, never absorbed as a guess.
+
+## 5. Interactions
+
+- **Ordering.** The prefix branch runs after exact-match (1) and before name parsing (2).
+  It cannot shadow name resolution, because a zero-match prefix returns `undefined` and
+  falls through. An agent whose *name* is hex-like resolves as before — covered by an
+  explicit regression test.
+- **`name:prefix` syntax.** Untouched. `parseAgentAddress` only engages on a colon, and a
+  bare prefix has none. The 4-char floor is deliberately the same one `parseAgentAddress`
+  already uses for its suffix, so the two addressing forms agree on what counts as a
+  prefix.
+- **Cold cache.** The retry after `autoDiscover()` in step 4 now re-tries the prefix as
+  well as the name. Without this the fix would work only when the cache was already warm —
+  which is the very condition that is false on a first send after boot.
+- **Rediscovery cooldown.** Unchanged; the prefix branch performs no discovery of its own.
+
+## 6. External surfaces
+
+No wire-format, protocol, or persisted-state change. No new config, route, or dependency.
+The observable difference is that an address which previously 404'd now resolves, plus one
+new error message string on the ambiguous path. Nothing depends on timing or conversation
+state.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local by design, and correctly so — no justification marker needed because no
+durable state is introduced.** `knownAgents` is a process-local in-memory cache rebuilt
+from relay discovery on every connect. Two machines running this agent each resolve
+against their own live view of the relay, which is the correct behaviour: reachability is
+a property of *this* process's relay connection, not a fact to replicate. Replicating a
+resolution cache would actively harm — a peer that machine A can reach may be unreachable
+from machine B, and a shared cache would assert otherwise.
+
+No user-facing notice, no generated URL, no state that could strand on topic transfer.
+
+## 8. Rollback cost
+
+Near zero. Revert the commit; the added method becomes unreferenced and the resolver
+returns to exact-match-plus-name. No migration, no persisted state, no agent-state repair.
+Any address that worked before still works after a revert — the change is purely additive
+to the set of inputs that resolve.
+
+## Evidence
+
+Tests were verified to fail against unmodified source before the fix was applied, so they
+demonstrably exercise the bug rather than merely accompanying it:
+
+```
+# fix reverted, tests only
+Tests  5 failed | 21 passed (26)
+  ✗ resolves the 8-char prefix that discover emits (the reported bug) → null
+  ✗ is case-insensitive on the prefix                                 → null
+  ✗ THROWS on an ambiguous prefix rather than delivering to the wrong agent → resolved null
+  ✗ names every candidate in the ambiguity error                      → resolved null
+  ✗ prefers the single LIVE row when a stale twin shares the prefix    → null
+
+# fix applied
+Tests  26 passed (26)
+
+# regression surface
+tests/unit/threadline/ — 65 files, 1581 passed
+tsc --noEmit — clean
+```
+
+The 21 that pass in both runs are the deliberate regression guards (full fingerprint,
+ordinary name, hex-like name, unknown prefix → null); they *should* pass either way, and
+their passing on unfixed source is what makes them meaningful as guards.