instar 1.3.987 → 1.3.989

package/upgrades/1.3.989.md

@@ -0,0 +1,55 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+New `GET /channels`: every peer-to-peer channel this agent has, each with purpose, when-preferred,
+cost, a live verdict and the evidence for it. Adds `src/core/channelRegistry.ts` (pure resolver) and
+`src/core/instarChannels.ts` (the four channel definitions with injected probes).
+
+The design property is not the list — a hand-built list was wrong three times in one hour. It is that
+**the channel set is code-defined**, so a channel that failed to construct still gets a row saying so;
+and that the verdict vocabulary (`working | broken | half-built | reachable-no-credential |
+not-configured | unknown`) is wide enough to describe what was actually observed. `unknown` carries a
+reason and is counted separately from broken — "could not tell" is not "is down".
+
+Registry First awareness added to the CLAUDE.md template (new agents) and via `PostUpdateMigrator`
+(existing agents).
+
+## What to Tell Your User
+
+If you run more than one agent, you can now ask which ways of reaching the others actually work, and
+get an honest answer in one place. Each entry says what the channel is for, when to prefer it, what it
+costs, and whether it is usable right now — with the reason.
+
+The useful part is what it does when things are wrong. A channel that failed to start still appears,
+saying it failed, rather than quietly vanishing from the list. A channel that cannot work out its own
+state says so instead of reporting that it is fine. And states like "this can receive but cannot send"
+or "reachable, but I hold no key for it" are reported as themselves rather than squashed into working
+or broken.
+
+It does not repair anything. It makes the situation legible so a sensible choice is possible.
+
+## Summary of New Capabilities
+
+- Ask which peer channels exist and which are usable right now, with the evidence for each verdict.
+
+## Evidence
+
+Three refusals, restored to 25/25 green and `tsc` exit 0:
+
+- Drop channels whose probe failed → 5 unit tests fail (`expected […] to have a length of 2 but got 1`).
+- Treat an undetermined probe as healthy → 5 unit tests fail.
+- Empty the ROUTE's registry → 4 integration tests fail (`expected [] to deeply equal ['a2a-telegram', …]`).
+
+The third was run before the integration test existed: the route served zero channels and all 19 unit
+tests passed. The module was guarded; the wiring was not.
+
+## Known limits
+
+Machine-local (no pool-scope merge). One entry (`a2a-telegram` = half-built) is asserted rather than
+probed because it is a build-time fact, guarded by a source scan scoped to `src/`. `mutual-ssh`
+reports construction, explicitly NOT a completed round-trip. No dashboard rendering. Fixes no
+channel. <!-- tracked: CMT-1044 -->

package/upgrades/side-effects/channel-registry.md

@@ -0,0 +1,199 @@
+# Side-Effects Review — a channel registry whose defining property is that nothing can vanish from it
+
+**Version / slug:** `channel-registry`
+**Date:** `2026-07-26`
+**Author:** `Echo (instar-dev agent)`
+**Second-pass reviewer:** `see Phase 5`
+
+## Summary of the change
+
+Operator request (topic 29723): inter-agent channel choice "feels arbitrary"; there is no registry of
+what channels exist and when each is appropriate. Evidence: when the relay died I stopped and reported
+that I could not reach the peer. I did not evaluate alternatives — I had no way to ask what they were
+or which were alive.
+
+Adds `src/core/channelRegistry.ts` (pure resolver + state vocabulary), `src/core/instarChannels.ts`
+(this agent's four peer channels with injected probes), and `GET /channels`.
+
+**The design is NOT the list.** A hand-built list, tried first, was wrong three times in one hour —
+each time by classifying something by its label rather than its consumer. The load-bearing properties:
+
+1. **Absence is impossible.** The channel set is code-defined, never derived from what constructed
+   successfully. Row count == definition count, whatever probes do.
+2. **A channel that cannot determine liveness says so.** `unknown` carries a reason; it is never a
+   synonym for healthy and is counted separately from `unusable`.
+3. **The vocabulary matches reality:** `working | broken | half-built | reachable-no-credential |
+   not-configured | unknown`. Every value was observed on a real channel; none is speculative.
+
+## Refusal evidence (constraint 2)
+
+```
+REFUSAL 1 — drop channels whose probe failed (the incident's exact shape)
+  × REGRESSION: a channel whose probe THROWS still gets a row
+    → expected [ { id: 'healthy', …(7) } ] to have a length of 2 but got 1
+  Tests  5 failed | 7 passed (12)
+
+REFUSAL 2 — treat an undetermined probe as healthy (the mirror error)
+  × UNKNOWN is never counted as unusable — "could not tell" is not "broken"
+  × discriminates — it is not stuck on one verdict, and it reports the healthy case
+  Tests  5 failed | 7 passed (12)
+
+REFUSAL 3 — empty the ROUTE's registry
+  × REGRESSION: the route serves EVERY code-defined channel — an emptied registry fails here
+    → expected [] to deeply equal [ 'a2a-telegram', 'mutual-ssh', …(2) ]
+  Tests  4 failed | 2 passed (6)
+```
+
+Restored: **25 passed (25)**, `tsc --noEmit` exit 0.
+
+**Refusal 3 is the finding.** I ran it BEFORE writing the integration test: the route served zero
+channels and **all 19 unit tests passed.** The module was thoroughly guarded; the wiring was not. That
+is this feature's own defect one layer up — a surface reporting nothing wrong because nothing asked it
+anything — and without the mandatory refusal step I would have shipped it as covered.
+
+## Decision-point inventory
+
+| point | classification | note |
+|---|---|---|
+| per-channel probe → state | `invariant` per channel | Deterministic reads of runtime state. No model call. |
+| probe failure → `unknown` | `invariant` | Fails toward "undetermined", never toward healthy. |
+| malformed probe result → `unknown` | `invariant` | An unrecognised shape is a failed probe, not a healthy channel. |
+| 3s probe timeout | `invariant` | One wedged channel must not make the surface unanswerable. |
+| `unknown` excluded from `unusable` | `invariant` | Deliberate: "could not tell" ≠ "broken". |
+| a2a-telegram = `half-built` | **asserted, guarded** | Build-time fact; see §2. |
+
+No judgment points. No LLM. Nothing gates or blocks.
+
+## 1. Over-block
+
+Nothing is blocked — this is a read surface with no authority over any send. The available harm is
+**misinforming a reader**, and the direction that matters is a channel reported healthier than it is.
+Every failure path resolves to `unknown` or a specific unusable state; no path resolves to `working`
+without a probe explicitly saying so (asserted by the garbage/nullish/throw/hang tests).
+
+The opposite over-block — reporting a working channel as unusable — would cost me a usable path
+mid-outage. Guarded by the discrimination test asserting all four verdict classes occur and by the
+route test asserting a connected relay reports `working`.
+
+## 2. Under-block
+
+**One entry is asserted, not measured.** `a2a-telegram` is reported `half-built / receive-only`
+because its send function has no executing caller — a build-time property no runtime probe can see.
+Mitigated by a source-scan test that fails the moment a caller appears, forcing the entry to be
+corrected. Honest limit: it detects a caller in `src/`, not one added in scripts or templates.
+
+**Liveness is construction, not round-trip.** `mutual-ssh` reports `working` when its runtime
+constructed. That is NOT proof a peer was reached, and the detail string says so verbatim (asserted by
+test). Real round-trip probing is a bigger change and is deliberately not bundled. <!-- tracked: CMT-1044 -->
+
+**`peer-http` is honest but inert here.** No peer HTTP endpoint is configured, so it reports exactly
+that rather than probing. On an agent that configures one, this needs a real probe.
+
+**Not wired into the operator dashboard.** The data is available at `GET /channels`; nothing renders it.
+Deliberate — the same separation I applied in #1656, and stated here rather than left for a reader to
+notice. <!-- tracked: CMT-1044 -->
+
+**It does not fix a single channel.** Two of three peer channels remain unusable. This makes their state
+visible, which is a precondition for choosing between them, not a repair.
+
+## 3. Level-of-abstraction fit
+
+The resolver is pure (`fs`-free, network-free, clock injected) and testable without a server; the
+definitions own the runtime coupling; the route owns transport. Probes are injected, which is what
+made the incident state reproducible in tests.
+
+**A smarter thing already exists and is deliberately NOT duplicated.** `/capability-registry`
+(`scanState: "never-observed"`) and `/capabilities` (`autoDispatch: false` rather than an omitted key)
+and a discovery adapter's breaker-aware `isAvailable()` all already implement honest-absence. This is
+the same idiom applied to channels — universality, not invention. A future consolidation into
+`capability-registry` as host is reasonable; it is not attempted here because that surface has its own
+projection/scan lifecycle this data does not share.
+
+## 4. Signal vs authority compliance
+
+Pure signal, marked `advisory: true` in the response. It cannot refuse a send, select a channel, or
+influence routing; nothing consumes it programmatically. `docs/signal-vs-authority.md` is satisfied
+trivially. The one risk an observer carries — taking down what it watches — is closed by the probe
+timeout and by the route returning a self-describing error object rather than a 500.
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+None introduced. Every branch is a deterministic read.
+
+## 5. Interactions
+
+- **`/threadline/status`** — reads the same `ctx.threadlineRelayClient.connectionState`; unchanged, not
+  wrapped. Two surfaces over one source, deliberately: that one is threadline-specific, this one is
+  cross-channel.
+- **App-level auth** — `/channels` carries no per-handler auth check, matching `/capability-registry`.
+  I asserted 401 first and got 200; on checking, auth is app-level middleware absent from the test
+  harness by construction. Recorded in the test rather than deleted (§6b).
+- **`globalThis.__instarMutualSshRuntime`** — read only. Set by `server.ts` after successful construction.
+- **Excluded by design:** the upstream dispatcher and the reputation/discovery client. Both were on my
+  first list; both are asserted absent by test so the category error cannot be re-introduced quietly.
+
+## 6. External surfaces
+
+One new authenticated read route. No config key, no persisted state, no message to any user, nothing
+installed into an agent home. Response contains channel ids, purposes, verdicts and evidence strings —
+no credentials, no peer identifiers, no message content.
+
+## 6b. Operator-surface quality
+
+Each row carries purpose / when-preferred / cost / verdict / evidence — the operator's four questions
+plus the reason. Asserted non-empty for every row by test.
+
+Wording carries two deliberate hedges earned tonight: `mutual-ssh` says construction "is not a
+completed round-trip", and `not-configured` reads as a decision rather than a fault, so switched-off
+infrastructure does not manufacture alarms.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN, and this is a real limitation rather than a neutral choice.** Every probe
+reads this process's own state; a channel healthy here may be dead on a peer machine. No replication,
+no lease interaction, no generated URL. A pool-scope merge (`?scope=pool`, dark-peer tolerant) is the
+obvious extension and is not attempted here. <!-- tracked: CMT-1044 -->
+
+## 8. Rollback cost
+
+Low. Two new modules, one route, three test files. No migration, no persisted state, no config default.
+Reverting removes a read surface and nothing else; no caller depends on it.
+
+## Phase 5 — Second-pass review
+
+Not a gate, sentinel, guard or watchdog; holds no block/allow authority; touches no session lifecycle
+or trust level. The high-risk trigger list is not engaged. Author-applied lenses, disclosed:
+
+**Adversarial — "how would I make this useless?"** Two ways, both closed and asserted: let a failed
+probe delete its channel (refusal 1), or let it report healthy (refusal 2). A third — let the route
+stop asking — was open until refusal 3 found it.
+
+**"Would it have caught the incident?"** It would have shown, in one read: relay `broken`, a2a
+`half-built/receive-only`, mutual-ssh `broken`, peer-http `reachable-no-credential`. Summary: zero
+working. That is the answer I needed and could not get — and notably it would ALSO have stopped me
+telling the operator a fallback existed, because the row says it cannot send.
+
+**"Symptom or cause?"** Neither: it makes the state legible. The channels are still broken.
+
+**Weakest point:** the asserted `half-built` entry. It is guarded, but a guard scoped to `src/` is
+narrower than the claim it protects, and the entry is the single place where this registry could
+become the confident-but-stale label it exists to prevent.
+
+## Post-CI addendum — three awareness registries I did not know existed
+
+I updated `templates.ts` + `PostUpdateMigrator` by hand and believed the Agent Awareness Standard was
+satisfied. CI disagreed, three times:
+
+1. **`feature-delivery-completeness`** — the CLAUDE.md section must be listed in `featureSections`, or
+   the template↔migrator parity assertion cannot see it at all.
+2. **`capabilities-discoverability`** — a new route prefix must be classified in `CapabilityIndex`:
+   surfaced in `/capabilities` or explicitly `INTERNAL_PREFIXES`. Its message is exactly right —
+   *"The lint refuses to assume; the author makes the call."* Surfaced, since agents need it.
+3. **`migrateFrameworkShadowCapabilities`** — without a marker, a Codex/Gemini agent never learns the
+   capability and "will improvise a weaker workaround". That is this feature's own failure mode
+   reproduced one layer out, and I would have shipped it.
+
+**This is the Structure-over-Willpower case restated by accident.** I was deliberately doing the
+awareness work and still missed three of five required registries. No amount of care would have closed
+that gap; only the gates did. Recorded here rather than quietly fixed, because the ratio (2 found by
+intent, 3 by machinery) is the useful number.

package/upgrades/side-effects/ssh2-cjs-named-imports.md

@@ -0,0 +1,183 @@
+# Side-Effects Review — five modules that threw at load, and a guard that could not see it
+
+**Version / slug:** `ssh2-cjs-named-imports`
+**Date:** `2026-07-26`
+**Author:** `Echo (instar-dev agent)`
+**Second-pass reviewer:** `see Phase 5`
+
+## Summary of the change
+
+`ssh2` is CommonJS. Five files took named VALUE imports from it
+(`import { Server, utils } from 'ssh2'`). Node's ESM loader cannot statically detect
+CJS named exports, so each of those modules threw at load. Observed at every server
+boot, warning-level, surfaced nowhere:
+
+```
+[mutual-ssh] initialization blocked: The requested module 'ssh2' does not provide
+  an export named 'Server'                                    (server.ts:21596)
+[peer-execution] disabled-grant cleanup blocked: Named export 'utils' not found.
+                                                              (server.ts:21491)
+```
+
+Fix: default-import the namespace, destructure at runtime, keep the type import
+type-only (types are erased, so `import type { Connection }` is safe and unchanged).
+
+Verified against the built output under Node's real loader — all five previously
+threw, all five now load:
+
+```
+$ npm run build && node --input-type=module -e "…await import('./dist/core/'+m+'.js')…"
+  LOADS   PeerAuthorizedKeys / MachineSshEndpoint / MutualSshVerifier
+  LOADS   StandingSshVerifier / SshBootstrapAdvert
+```
+
+## The guard is a source scan, and that was not the first attempt
+
+The obvious regression guard — import each module, assert no throw — was written,
+passed, and was **wrong**. Reverting one file to the broken form left it fully green:
+
+```
+$ npx vitest run tests/unit/ssh2-modules-load-under-esm.test.ts   # BROKEN source
+  ✓ (8 tests) — Tests  8 passed (8)
+$ npx tsc --noEmit                                                # BROKEN source
+  tsc exit=0
+$ node --input-type=module -e "import { Server } from 'ssh2';"
+  SyntaxError: Named export 'Server' not found…
+```
+
+Vitest transforms through Vite, which rewrites CJS interop; production runs the
+compiled output under Node's loader, which does not. An in-process import assertion
+is **structurally incapable** of observing this class — it does not merely miss it.
+`tsc` is blind for a different reason: the types are genuinely correct.
+
+The replacement scans source text for named value imports from a CJS allowlist. It
+refuses correctly:
+
+```
+$ npx vitest run …   # after reverting src/core/MutualSshVerifier.ts
+  × REGRESSION: no source file takes a named value import from a CJS-only package
+    → core/MutualSshVerifier.ts: import { Client, utils } from 'ssh2'
+  Tests  1 failed | 5 passed (6)
+```
+
+## Decision-point inventory
+
+| point | classification | note |
+|---|---|---|
+| import form per file | `invariant` | Mechanical; no runtime branch introduced. |
+| scan allowlist (`CJS_ONLY_PACKAGES`) | `invariant` | Explicit list, currently `['ssh2']`. Deliberately not auto-derived — see §2. |
+| comment/string stripping before match | `invariant` | Asserted by a test using this file's own prose. |
+
+No judgment points. No model call. Nothing gates or blocks at runtime.
+
+## 1. Over-block
+
+The scan is the only thing that can refuse, and it refuses at test time, never at
+runtime. Its over-block risk is flagging an innocent file whose *prose* contains the
+forbidden shape — the known weakness of text checks, and one this codebase has been
+bitten by three times. Closed by stripping comments and string literals first, with a
+test that feeds it this very file's description of the bug and asserts zero matches.
+Both safe forms (`import ssh2 from 'ssh2'`, `import type { … }`) are asserted to pass.
+
+## 2. Under-block
+
+**The allowlist is manual.** A named value import from some *other* CJS package is
+not caught. Auto-deriving it (reading every dependency's `package.json` type field)
+was considered and rejected for this change: it turns a two-line list into a
+resolution problem with its own failure modes, and would have shipped untested. The
+list is the honest, visible limit. <!-- tracked: CMT-1044 -->
+
+**It scans `src/` only.** Scripts, hooks, and templates are not covered.
+
+**Loading is not working.** This proves five modules load. Whether `mutualSshRuntime.start()`
+then binds, finds keys, and reaches a peer is untested here and is NOT claimed. The
+precise claim: the channel could not have worked before, and one specific blocker is gone.
+
+**The guard cannot see the compiled reality.** A source scan infers the runtime
+failure from the source shape. The direct check — importing built output under Node —
+runs in this review but is not wired into CI, because it requires a build step the
+unit shard does not have.
+
+## 3. Level-of-abstraction fit
+
+The fix is at the only possible layer: the import statements themselves. The guard sits
+in the unit shard, which is where a cheap always-runs check belongs. A lint rule
+(`eslint-plugin-import`) would be the more conventional home; it is not adopted here
+because the repo has no such plugin configured and adding one is a larger change than
+the bug warrants.
+
+## 4. Signal vs authority compliance
+
+No runtime authority is introduced or moved. The change removes a load-time crash; it
+adds no gate, no branch, no decision. The test-time scan holds authority over CI only,
+which is the appropriate place for a brittle text check per `docs/signal-vs-authority.md`
+— brittleness is acceptable when the blast radius is a red build, not a blocked action.
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+None introduced.
+
+## 5. Interactions
+
+- **`MutualSshRuntime` / mesh transport** — unchanged. This only lets its dependencies load.
+- **`guardRegistry`** — see §6b. Not modified here.
+- **Type imports** — `import type { Connection, Server as SshServerType }` retained in
+  `MachineSshEndpoint.ts`; `Server` needed splitting into a value binding and a type
+  alias because it is used as both. Caught by `tsc`, not by me.
+
+## 6. External surfaces
+
+None. No route, no config key, no log line, no user-visible message, no persisted state.
+
+## 6b. Operator-surface quality — the finding this change does NOT fix
+
+`multiMachine.mutualSsh.enabled` registers itself with `guardRegistry` **inside** the
+try block that threw. So the failure removed itself from the inventory built to catch
+exactly this. Confirmed against the live pre-fix server:
+
+```
+total guard rows: 88
+mutualSsh/peerExecution rows: 1   →  multiMachine.peerExecution.enabled
+```
+
+`mutualSsh` has no row at all — not "off", not "errored", absent. This is the same
+shape as tonight's relay defect (a dropped connection left "connected" as the only
+record): **the defect deletes its own evidence.** Registering guards before the
+fallible construction, so a crashed subsystem still appears as `errored`, is a real
+change to a shared registry and is deliberately not bundled here. <!-- tracked: CMT-1044 -->
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+Machine-local by design — a module either loads in this process or does not. No
+replication, no lease interaction, no shared state, no generated URL. The *feature*
+being repaired is cross-machine, but this change to it is not.
+
+## 8. Rollback cost
+
+Low. Five import statements and one test file. No migration, no persisted state, no
+config default, nothing installed into an agent home. Reverting restores the previous
+behaviour exactly — a warning at boot and a dead channel — and the guard would fail
+loudly on the way, which is the intended announcement.
+
+## Phase 5 — Second-pass review
+
+Touches no block/allow decision, no session lifecycle, no trust level, no gate or
+sentinel, so the high-risk trigger list is not engaged. Author-applied lenses, disclosed:
+
+**Adversarial — "how would I make this useless?"** By writing a guard that cannot
+observe the failure. I did exactly that on the first attempt, and only caught it
+because the refusal step is mandatory rather than optional. Recorded in §2 as the
+central lesson rather than quietly replaced.
+
+**"Did I fix the symptom or the cause?"** The cause, for the load failure. Not for the
+invisibility — §6b is the cause of *why nobody noticed for so long*, and it is left
+open and tracked rather than half-done.
+
+**"Would it have caught the incident?"** The guard would have failed the build the day
+the named import was introduced. It would not have surfaced the boot warning; nothing
+here changes observability.
+
+**Weakest point:** §2's last item. The scan infers a runtime property from source
+text. The direct check exists and passes, but runs by hand in this review rather than
+in CI — so the thing CI actually enforces is one inference removed from the thing that
+broke.