instar 1.3.996 → 1.3.998

package/dist/core/instarChannels.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instarChannels.d.ts","sourceRoot":"","sources":["../../src/core/instarChannels.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAsB,MAAM,sBAAsB,CAAC;AAElF,kGAAkG;AAClG,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,WAAW,EAAE,MAAM;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjE,8FAA8F;IAC9F,oBAAoB,EAAE,MAAM,OAAO,CAAC;IACpC,+DAA+D;IAC/D,gBAAgB,EAAE,MAAM,OAAO,CAAC;IAChC,+FAA+F;IAC/F,QAAQ,EAAE,MAAM,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1F;AAeD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,mBAAmB,GAAG,iBAAiB,EAAE,CAuErF;AAED,uCAAuC;AACvC,eAAO,MAAM,kBAAkB,QAA0B,CAAC"}
+{"version":3,"file":"instarChannels.d.ts","sourceRoot":"","sources":["../../src/core/instarChannels.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAsB,MAAM,sBAAsB,CAAC;AAElF,kGAAkG;AAClG,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,WAAW,EAAE,MAAM;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjE,8FAA8F;IAC9F,oBAAoB,EAAE,MAAM,OAAO,CAAC;IACpC,+DAA+D;IAC/D,gBAAgB,EAAE,MAAM,OAAO,CAAC;IAChC,+FAA+F;IAC/F,QAAQ,EAAE,MAAM,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1F;AAeD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,mBAAmB,GAAG,iBAAiB,EAAE,CA0ErF;AAED,uCAAuC;AACvC,eAAO,MAAM,kBAAkB,QAA0B,CAAC"}

package/dist/core/instarChannels.js

@@ -25,18 +25,21 @@ export function buildChannelDefinitions(ctx) {
             audience: 'peer',
             purpose: 'Direct agent-to-agent messaging over the shared relay.',
             whenPreferred: 'The default for peer work: fastest, and invisible to the operator, so it does not spend their attention.',
-            cost: 'Requires the relay to be connected. Invisible when it fails, which is its main hazard.',
+            cost: 'Requires the server process relay client to be connected, and another process can hold a different relay state. Invisible when it fails, which is its main hazard.',
             probe: async () => {
                 const s = ctx.relayStatus();
                 if (s === null) {
                     return { state: 'not-configured', direction: 'none', detail: 'threadline layer was never constructed on this agent' };
                 }
                 if (s.ready && s.connected) {
-                    return { state: 'working', direction: 'bidirectional', detail: 'relay reports ready and connected' };
+                    return {
+                        state: 'working', direction: 'bidirectional',
+                        detail: 'server process relay client reports ready and connected; NOTE this confirms the server client, not another process client such as the MCP tool path, and not that any given send will land',
+                    };
                 }
                 return {
                     state: 'broken', direction: 'none',
-                    detail: `relay reports ready=${s.ready}, connected=${s.connected}; a send would be refused`,
+                    detail: `server process relay client reports ready=${s.ready}, connected=${s.connected}; a server-process send would be refused, while another process client such as the MCP tool path has its own state`,
                 };
             },
         },

package/dist/core/instarChannels.js.map

@@ -1 +1 @@
-{"version":3,"file":"instarChannels.js","sourceRoot":"","sources":["../../src/core/instarChannels.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"instarChannels.js","sourceRoot":"","sources":["../../src/core/instarChannels.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgBH;;;;;;;;GAQG;AACH,MAAM,uBAAuB,GAC3B,8FAA8F;IAC9F,qCAAqC,CAAC;AAExC,MAAM,UAAU,uBAAuB,CAAC,GAAwB;IAC9D,OAAO;QACL;YACE,EAAE,EAAE,kBAAkB;YACtB,QAAQ,EAAE,MAAM;YAChB,OAAO,EAAE,wDAAwD;YACjE,aAAa,EAAE,0GAA0G;YACzH,IAAI,EAAE,oKAAoK;YAC1K,KAAK,EAAE,KAAK,IAAiC,EAAE;gBAC7C,MAAM,CAAC,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;gBAC5B,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;oBACf,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,sDAAsD,EAAE,CAAC;gBACxH,CAAC;gBACD,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;oBAC3B,OAAO;wBACL,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe;wBAC5C,MAAM,EAAE,4LAA4L;qBACrM,CAAC;gBACJ,CAAC;gBACD,OAAO;oBACL,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM;oBAClC,MAAM,EAAE,6CAA6C,CAAC,CAAC,KAAK,eAAe,CAAC,CAAC,SAAS,oHAAoH;iBAC3M,CAAC;YACJ,CAAC;SACF;QACD;YACE,EAAE,EAAE,cAAc;YAClB,QAAQ,EAAE,MAAM;YAChB,OAAO,EAAE,oHAAoH;YAC7H,aAAa,EAAE,+HAA+H;YAC9I,IAAI,EAAE,mEAAmE;YACzE,4FAA4F;YAC5F,KAAK,EAAE,KAAK,IAAiC,EAAE,CAC7C,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;SACxF;QACD;YACE,EAAE,EAAE,YAAY;YAChB,QAAQ,EAAE,MAAM;YAChB,OAAO,EAAE,mFAAmF;YAC5F,aAAa,EAAE,4EAA4E;YAC3F,IAAI,EAAE,iFAAiF;YACvF,KAAK,EAAE,KAAK,IAAiC,EAAE;gBAC7C,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,EAAE,CAAC;oBAC5B,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,2BAA2B,EAAE,CAAC;gBAC7F,CAAC;gBACD,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,EAAE,CAAC;oBAChC,OAAO;wBACL,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM;wBAClC,MAAM,EAAE,8GAA8G;qBACvH,CAAC;gBACJ,CAAC;gBACD,0FAA0F;gBAC1F,OAAO;oBACL,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe;oBAC5C,MAAM,EAAE,4GAA4G;iBACrH,CAAC;YACJ,CAAC;SACF;QACD;YACE,EAAE,EAAE,WAAW;YACf,QAAQ,EAAE,MAAM;YAChB,OAAO,EAAE,2DAA2D;YACpE,aAAa,EAAE,gEAAgE;YAC/E,IAAI,EAAE,uEAAuE;YAC7E,KAAK,EAAE,KAAK,IAAiC,EAAE;gBAC7C,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,QAAQ,EAAE,CAAC;gBAC/B,IAAI,CAAC,CAAC,CAAC,SAAS;oBAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;gBAClF,IAAI,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC;oBACtB,OAAO,EAAE,KAAK,EAAE,yBAAyB,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;gBACnF,CAAC;gBACD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;YAC5E,CAAC;SACF;KACF,CAAC;AACJ,CAAC;AAED,uCAAuC;AACvC,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.996",
+  "version": "1.3.998",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-27T07:22:09.595Z",
-  "instarVersion": "1.3.996",
+  "generatedAt": "2026-07-27T07:59:39.801Z",
+  "instarVersion": "1.3.998",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.997.md

@@ -0,0 +1,61 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The `threadline-relay` row in the channel registry reported `relay reports ready and connected`
+without naming the subject of that verdict. It reads `ctx.threadlineRelayClient` — the **server
+process's** relay client. The MCP tool path runs in a different process holding its own client, so
+`GET /channels` could report `working` while a send from the MCP path failed, and both readings were
+true at the same time.
+
+The verdicts are unchanged. Only the claims are scoped, following the `mutual-ssh` precedent already
+in the same file. The working branch now reports the server-process client explicitly and states that
+this is neither another process's client nor a guarantee that a given send will land; the broken
+branch is scoped the same way. `cost` is updated because it is user-visible registry prose, while
+`whenPreferred` is left alone because it describes channel preference rather than the runtime client
+whose state was measured.
+
+## What to Tell Your User
+
+When your agent tells you a channel is working, it now tells you which part of itself it checked.
+
+Your agent runs in more than one process, and they can hold different connection states at the same
+time. Previously it could report that the agent-to-agent relay was connected while a message sent by
+a different part of the agent quietly failed — and both statements were true, which is what made it
+confusing. The report now names what it actually measured, so a green reading cannot be misread as a
+promise about a path it never checked.
+
+## Summary of New Capabilities
+
+No new endpoint, command, or configuration. The threadline relay row in the channel registry now
+names the process whose relay state it reports, in both its working and its broken form.
+
+## Evidence
+
+Restoring the original unscoped claim fails the new test for the right reason:
+
+```
+× threadline-relay working detail scopes the verdict to the server-process relay client
+  → expected 'relay reports ready and connected' to contain 'server process relay client'
+  Tests  1 failed | 7 passed (8)
+```
+
+Removing the `mutual-ssh` caveat likewise fails, confirming the precedent test still bites:
+
+```
+× mutual-ssh reports construction WITHOUT claiming a completed round-trip
+  → expected 'runtime constructed and listening' to contain 'not a completed round-trip'
+  Tests  1 failed | 7 passed (8)
+```
+
+Both restored byte-identical. Green: `Test Files 3 passed (3) · Tests 36 passed (36)` across
+`channel-registry-claims`, `channel-registry` and `user-channel-liveness`; `tsc --noEmit` exit 0.
+
+## Known limits
+
+The row still reports a single measurement — the server process's relay client — and now says so.
+It does not probe the MCP tool's client, so it cannot tell you that path's state; it only stops
+implying it. Nor does a connected reading promise that any particular send will land.

package/upgrades/1.3.998.md

@@ -0,0 +1,63 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`tests/unit/agent-registry.test.ts` and `tests/unit/builtin-manifest.test.ts` were removed from
+`FLAKY_TESTS` in `vitest.push.config.ts`, so both run in the push/CI unit gate again. The surrounding
+comment now records the measurements and the falsified hypothesis rather than a bare heading.
+
+Neither test is flaky. Both arrived in `f193df789` ("exclude pre-existing flaky tests from push
+gate") — a bulk exclusion, not an individual diagnosis — and sat under a
+"Environment-dependent / non-deterministic" heading that was thereafter read as a finding about each
+one.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+Measured on current `main`, three consecutive runs each:
+
+```
+agent-registry.test.ts    → 42 passed | 42 passed | 42 passed
+builtin-manifest.test.ts  →  9 passed |  9 passed |  9 passed
+```
+
+The one concrete environmental hypothesis was tested and falsified. `builtin-manifest.test.ts` reads
+`src/data/builtin-manifest.json`, a generated and gitignored artifact that a job which never builds
+would not have. Deleting the file and re-running:
+
+```
+Tests  9 passed (9)
+```
+
+It still passes because the test's own `beforeAll` regenerates it via
+`scripts/generate-builtin-manifest.cjs` — it was already self-sufficient by design.
+
+After the change, verified by parsing the resolved `FLAKY_TESTS` array rather than assuming the edit
+took: both paths report `NO LONGER EXCLUDED`, 92 entries remain. Both tests run green together
+(`Test Files 2 passed (2) · Tests 51 passed (51)`); `tsc --noEmit` exit 0.
+
+## Known limits
+
+The remaining 92 entries are untouched and unexamined. Several — the supertest/port-collision group
+especially — are plausibly genuinely environment-bound, and emptying the list wholesale would repeat
+the bulk move that caused this. Local determinism is also not proof of CI determinism: if either test
+fails in CI, that is a real finding to diagnose, not a reason to re-park it.
+
+## Why the comment is verbose
+
+The note two entries below already described this same mistake: two other tests were re-armed on
+2026-06-05 from the same heading, with the observation that the label had been wrong and that both
+had rotted while parked. The diagnosis, the precedent and the warning were already in the file,
+three lines above two more mislabelled tests. The replacement comment therefore carries the
+measurements and the falsified theory, so the next person reaching for that label has to argue with
+evidence instead of reapplying a heading.

package/upgrades/side-effects/rearm-parked-tests.md

@@ -0,0 +1,73 @@
+# Side-effects review — re-arm two parked tests
+
+**Change:** remove `tests/unit/agent-registry.test.ts` and `tests/unit/builtin-manifest.test.ts` from
+`FLAKY_TESTS` in `vitest.push.config.ts`, and replace the surrounding comment with the measurements
+and the falsified hypothesis.
+
+**Decision point touched?** No new decision point. This *restores* an existing one: two guards that
+were excluded from the CI gate now participate in it again. No runtime code changes; the diff is
+config + comment only.
+
+---
+
+## 1. Over-block
+
+Re-arming can only make the gate stricter, and that is the intent. The over-block risk is that a test
+fails in CI for an environmental reason that does not exist locally — in which case CI turns red on
+work unrelated to the failure, and the author is blocked by something they did not cause.
+
+Mitigated by measurement rather than hope: both were run three consecutive times on current `main`
+(42/42/42 and 9/9/9), and the one specific environmental hypothesis available —
+`builtin-manifest.test.ts` depending on the generated, gitignored `src/data/builtin-manifest.json` —
+was tested by deleting the file. The test still passed 9/9 because its `beforeAll` regenerates it.
+
+Residual risk is real but bounded: local determinism is not proof of CI determinism. If either fails
+in CI, the correct response is to diagnose it, not to re-park it. Re-parking without a diagnosis is
+the exact move that created this situation.
+
+## 2. Under-block
+
+This change does not attempt to audit the rest of `FLAKY_TESTS` (92 entries remain). Several — the
+supertest/port-collision group in particular — are plausibly genuinely environment-bound, and
+emptying the list wholesale would be the same bulk move that caused the problem, run in reverse. So
+the class is knowingly only partly addressed here: two members verified and fixed, the remainder
+untouched and unexamined. Stated rather than implied.
+
+## 3. Level-of-abstraction fit
+
+Correct layer. The mislabel lives in the exclusion list, so the fix belongs in the exclusion list.
+A deeper fix — something that would *prevent* a bulk exclusion from being read later as a per-test
+finding — would need a mechanism requiring evidence at the point of exclusion (e.g. a required
+measurement note per entry). That is a larger design change and is deliberately not attempted here.
+
+## 4. Signal vs authority compliance
+
+Unchanged. The tests are signals that CI (the authority) consumes. Nothing here gives any check new
+blocking power it did not already have by design; it restores participation that was removed.
+
+## 5. Interactions
+
+The two files now execute inside the push/CI unit run, adding their runtime to that job and their
+failures to its verdict. Both are fast unit tests. `builtin-manifest.test.ts` shells out to
+`scripts/generate-builtin-manifest.cjs` in `beforeAll` if the generated file is missing, which writes
+`src/data/builtin-manifest.json` — a gitignored artifact that `npm run build` writes anyway. It is
+the only test that reads that file, so no cross-test read/write race is introduced. Worth naming
+explicitly because a test that writes into the repo during a sharded run is the shape that *would*
+cause genuine flakiness if another test ever read the same file.
+
+## 6. External surfaces
+
+None. No endpoint, no config key, no agent-visible behaviour, no user-visible behaviour. The only
+observer of this change is CI.
+
+## 7. Multi-machine posture
+
+Not applicable — this is repo-level CI configuration, identical on every checkout, with no runtime
+state, no per-machine data, and nothing to replicate or proxy.
+
+## 8. Rollback cost
+
+Trivial and immediate: re-add the two strings to `FLAKY_TESTS`. No data migration, no release
+coupling, no agent state to repair. If a rollback happens, the comment block should record *why* the
+test actually failed — otherwise the rollback recreates the original defect, which was an exclusion
+carrying no evidence.

package/upgrades/side-effects/relay-scope-detail.md

@@ -0,0 +1,119 @@
+# Side-Effects Review - Relay Scope Detail
+
+**Version / slug:** `relay-scope-detail`
+**Date:** `2026-07-26`
+**Author:** `Codex`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+This change narrows the human-readable claim made by `src/core/instarChannels.ts` for the `threadline-relay` channel. The runtime state is unchanged: a connected server-process relay client still reports `working`, and a disconnected server-process relay client still reports `broken`. The detail text now names the measured subject as the server-process relay client and states that another process, notably the MCP tool path, owns its own relay client state. `tests/unit/channel-registry-claims.test.ts` adds real-builder coverage for that scope and pins the existing `mutual-ssh` caveat as the precedent.
+
+## Decision-point inventory
+
+- `src/core/instarChannels.ts` `threadline-relay` probe detail - modify - the registry detail now names the server-process relay client as the subject of both working and broken readings.
+- `src/core/instarChannels.ts` `threadline-relay` cost text - modify - the static cost text now notes that another process can hold a different relay state.
+- `tests/unit/channel-registry-claims.test.ts` relay-scope assertion - add - the test verifies the real resolved channel output names the server process, MCP tool path distinction, and no send-delivery promise.
+- `tests/unit/channel-registry-claims.test.ts` mutual-SSH exact assertion - modify - the test now pins the existing caveat exactly so the precedent cannot be weakened silently.
+
+---
+
+## 1. Over-block
+
+No block/allow surface - over-block not applicable. The change does not reject inputs, deny operations, alter admission, or change any runtime state transition.
+
+---
+
+## 2. Under-block
+
+No block/allow surface - under-block not applicable. The remaining failure mode is informational: a caller could still ignore the scoped detail and treat `working` alone as a send guarantee. That is outside this small wording fix; the row now provides the precise caveat needed for callers that read details.
+
+---
+
+## 3. Level-of-abstraction fit
+
+This is at the registry-claim layer. The registry already owns the prose that explains what each probe measured, and the defect was in that prose rather than in the relay client, server route, or MCP implementation. The change does not add a detector or authority; it makes the existing low-level signal name its scope honestly.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [ ] No - this change produces a signal consumed by an existing smart gate.
+- [x] No - this change has no block/allow surface.
+- [ ] Yes - but the logic is a smart gate with full conversational context (LLM-backed with recent history or equivalent).
+- [ ] Yes, with brittle logic - STOP. Reshape the design.
+
+This change has no blocking authority. It changes explanatory text attached to an already-existing channel probe result.
+
+---
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+No new static heuristic at a competing-signals decision point. The change does not decide between conflicting live signals; it labels one signal's subject more precisely.
+
+---
+
+## 5. Interactions
+
+**Shadowing:** No new check runs before or after another check. Existing callers still receive the same channel ids, states, and directions.
+
+**Double-fire:** No new event, retry, notification, send, or recovery path is introduced.
+
+**Races:** No shared mutable state is added. The probe still reads the injected `relayStatus()` function exactly once per resolution.
+
+**Feedback loops:** No feedback loop is changed. The registry output may influence human or agent choice of channel, but this patch only clarifies what the output means.
+
+---
+
+## 6. External surfaces
+
+`GET /channels` and any internal consumer of the channel registry will show clearer prose for `threadline-relay`. Other agents and users may see the updated detail text after upgrade. No external systems are called. No persistent state, database row, ledger, or memory file is changed. No operator-facing action is added; the dashboard/API display remains a read-only informational surface for this row.
+
+---
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+No operator surface - not applicable. This change touches no dashboard renderer, approval page, grant/revoke form, or secret-drop form.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+Machine-local by design: relay client connection state is a per-process and per-machine runtime truth. The registry should report exactly the process it measured rather than pretending the value replicates across machines or sibling processes. The change emits no user-facing notices, holds no durable state, and generates no URLs.
+
+---
+
+## 8. Rollback cost
+
+Hot-fix release: revert the text and test changes, then ship the next patch. There is no data migration, no agent state repair, and no persistent cleanup. During rollback propagation, users would only lose the more precise registry wording.
+
+---
+
+## Conclusion
+
+The review found no side-effecting runtime behavior. The implementation keeps the existing `working` and `broken` verdicts while making their subject explicit. The only visible change is clearer registry prose, backed by unit tests that fail if the scoped relay claim or the existing mutual-SSH scope caveat is weakened.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** not required
+**Independent read of the artifact:** not required
+
+Second-pass review is not required for this Tier 1 wording-and-test change.
+
+---
+
+## Evidence pointers
+
+- `./node_modules/.bin/vitest run tests/unit/channel-registry-claims.test.ts tests/unit/user-channel-liveness.test.ts`
+- Falsification restored the old relay detail and confirmed the relay-scope test failed on the missing server-process subject.
+- Falsification shortened the mutual-SSH detail and confirmed the exact-precedent assertion failed.
+
+---
+
+## Class-Closure Declaration (display-only mirror)
+
+No agent-authored-artifact defect - not applicable.