instar 1.3.1212 → 1.3.1213

package/dist/core/PeerEndpointRecorder.d.ts

@@ -14,6 +14,16 @@
  *   1. meshTransport gate — a no-op when `multiMachine.meshTransport` is off.
  *   2. Absence is a no-op, NEVER a wipe — undefined/null/`[]`/fully-invalid leaves the
  *      peer's prior ropes intact (a silent or un-upgraded sender must not erase them).
+ *   2b. Degradation does not discard a PROVEN rope — a non-empty advertisement that
+ *      OMITS a kind whose local health record says it is currently alive RETAINS that
+ *      kind instead of replacing it away. Invariant 2 guarded the empty case only, so a
+ *      peer that can no longer SEE its own best address (an agent inside a NAT'd VM —
+ *      the 2026-08-29 WSL machine, whose only visible NIC was an unreachable virtual
+ *      one) replaced a demonstrably-working tailscale rope with a dead-on-arrival lan
+ *      one, and the mesh lost its only route to that machine. Evidence beats assertion:
+ *      a rope carrying traffic is not dropped because an announcement forgot it. A rope
+ *      the health record calls dead (or has never dialed) is still dropped, so a
+ *      genuinely-retired endpoint does not linger forever.
  *   3. Synchronous per-kind validation BEFORE storage (defense-in-depth, not authority).
  *   4. Idempotent — skip the write (and its `lastSeen` bump + registry-dirty mark) when
  *      the normalized set is unchanged, preventing ~720 no-op rewrites/day on a stable
@@ -29,6 +39,13 @@ export interface PeerEndpointRecorderDeps {
     updateMachineEndpoints: (machineId: string, endpoints: MeshEndpoint[]) => void;
     /** Live read: false ⇒ recording is a strict no-op (the lease handling is unchanged). */
     meshTransportEnabled: () => boolean;
+    /**
+     * Invariant 2b evidence source: is (peer, kind) CURRENTLY alive in this machine's own
+     * rope-health record? Only a `true` retains an omitted kind — `false` (dead) and
+     * `undefined` (never dialed, no evidence) both fall through to replace semantics.
+     * Optional so a caller that wires no health source keeps the pre-2b behaviour exactly.
+     */
+    isEndpointAlive?: (machineId: string, kind: MeshEndpoint['kind']) => boolean | undefined;
     logger?: (msg: string) => void;
 }
 export declare class PeerEndpointRecorder {
@@ -45,5 +62,18 @@ export declare class PeerEndpointRecorder {
      * responder). Never pass a self-asserted body field — that is the load-bearing binding.
      */
     record(peerMachineId: string, raw: unknown): boolean;
+    /**
+     * Invariant 2b — merge an omitted-but-PROVEN kind back into the advertised set.
+     *
+     * `advertised` wins for every kind it names (a peer re-advertising a kind with a NEW
+     * url is still an upgrade, and must land). A kind present in `current` but absent from
+     * `advertised` is retained ONLY when `isEndpointAlive` positively says it is alive; a
+     * dead rope, an unknown rope, and a caller with no health source all fall through to
+     * plain replace semantics.
+     *
+     * Pure over its inputs (no I/O, no throw) so the retain decision is unit-testable
+     * without a registry or a resolver.
+     */
+    private retainProvenOmitted;
 }
 //# sourceMappingURL=PeerEndpointRecorder.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"PeerEndpointRecorder.d.ts","sourceRoot":"","sources":["../../src/core/PeerEndpointRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C,MAAM,WAAW,wBAAwB;IACvC,qFAAqF;IACrF,gBAAgB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,YAAY,EAAE,GAAG,SAAS,CAAC;IACpE,4FAA4F;IAC5F,sBAAsB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,IAAI,CAAC;IAC/E,wFAAwF;IACxF,oBAAoB,EAAE,MAAM,OAAO,CAAC;IACpC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,CAAC,CAA2B;gBAEjC,IAAI,EAAE,wBAAwB;IAI1C,OAAO,CAAC,GAAG;IAIX;;;;;;;;OAQG;IACH,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO;CAoBrD"}
+{"version":3,"file":"PeerEndpointRecorder.d.ts","sourceRoot":"","sources":["../../src/core/PeerEndpointRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C,MAAM,WAAW,wBAAwB;IACvC,qFAAqF;IACrF,gBAAgB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,YAAY,EAAE,GAAG,SAAS,CAAC;IACpE,4FAA4F;IAC5F,sBAAsB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,IAAI,CAAC;IAC/E,wFAAwF;IACxF,oBAAoB,EAAE,MAAM,OAAO,CAAC;IACpC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,OAAO,GAAG,SAAS,CAAC;IACzF,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,CAAC,CAA2B;gBAEjC,IAAI,EAAE,wBAAwB;IAI1C,OAAO,CAAC,GAAG;IAIX;;;;;;;;OAQG;IACH,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO;IAsBpD;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,mBAAmB;CA8B5B"}

package/dist/core/PeerEndpointRecorder.js

@@ -14,6 +14,16 @@
  *   1. meshTransport gate — a no-op when `multiMachine.meshTransport` is off.
  *   2. Absence is a no-op, NEVER a wipe — undefined/null/`[]`/fully-invalid leaves the
  *      peer's prior ropes intact (a silent or un-upgraded sender must not erase them).
+ *   2b. Degradation does not discard a PROVEN rope — a non-empty advertisement that
+ *      OMITS a kind whose local health record says it is currently alive RETAINS that
+ *      kind instead of replacing it away. Invariant 2 guarded the empty case only, so a
+ *      peer that can no longer SEE its own best address (an agent inside a NAT'd VM —
+ *      the 2026-08-29 WSL machine, whose only visible NIC was an unreachable virtual
+ *      one) replaced a demonstrably-working tailscale rope with a dead-on-arrival lan
+ *      one, and the mesh lost its only route to that machine. Evidence beats assertion:
+ *      a rope carrying traffic is not dropped because an announcement forgot it. A rope
+ *      the health record calls dead (or has never dialed) is still dropped, so a
+ *      genuinely-retired endpoint does not linger forever.
  *   3. Synchronous per-kind validation BEFORE storage (defense-in-depth, not authority).
  *   4. Idempotent — skip the write (and its `lastSeen` bump + registry-dirty mark) when
  *      the normalized set is unchanged, preventing ~720 no-op rewrites/day on a stable
@@ -51,10 +61,11 @@ export class PeerEndpointRecorder {
             return false; // empty/fully-invalid → no-op, never a wipe
         try {
             const current = this.d.getPeerEndpoints(peerMachineId);
-            if (meshEndpointsEqual(current, validated))
+            const next = this.retainProvenOmitted(peerMachineId, current, validated);
+            if (meshEndpointsEqual(current, next))
                 return false; // idempotent — skip the write
-            this.d.updateMachineEndpoints(peerMachineId, validated);
-            this.log(`recorded ${validated.length} endpoint(s) for ${peerMachineId} [${validated.map((e) => e.kind).join(',')}]`);
+            this.d.updateMachineEndpoints(peerMachineId, next);
+            this.log(`recorded ${next.length} endpoint(s) for ${peerMachineId} [${next.map((e) => e.kind).join(',')}]`);
             return true;
         }
         catch (err) {
@@ -65,5 +76,44 @@ export class PeerEndpointRecorder {
             return false;
         }
     }
+    /**
+     * Invariant 2b — merge an omitted-but-PROVEN kind back into the advertised set.
+     *
+     * `advertised` wins for every kind it names (a peer re-advertising a kind with a NEW
+     * url is still an upgrade, and must land). A kind present in `current` but absent from
+     * `advertised` is retained ONLY when `isEndpointAlive` positively says it is alive; a
+     * dead rope, an unknown rope, and a caller with no health source all fall through to
+     * plain replace semantics.
+     *
+     * Pure over its inputs (no I/O, no throw) so the retain decision is unit-testable
+     * without a registry or a resolver.
+     */
+    retainProvenOmitted(peerMachineId, current, advertised) {
+        const alive = this.d.isEndpointAlive;
+        if (!alive || !current || current.length === 0)
+            return advertised;
+        const advertisedKinds = new Set(advertised.map((e) => e.kind));
+        const retained = [];
+        for (const ep of current) {
+            if (advertisedKinds.has(ep.kind))
+                continue;
+            let verdict;
+            try {
+                verdict = alive(peerMachineId, ep.kind);
+            }
+            catch {
+                // @silent-fallback-ok: an unreadable health source is NO evidence, which is the
+                // same as "never dialed" — fall through to replace. Never retains on an error.
+                verdict = undefined;
+            }
+            if (verdict === true)
+                retained.push(ep);
+        }
+        if (retained.length > 0) {
+            this.log(`retained ${retained.length} proven endpoint(s) for ${peerMachineId} omitted by its advertisement `
+                + `[${retained.map((e) => e.kind).join(',')}] — health says alive`);
+        }
+        return [...advertised, ...retained];
+    }
 }
 //# sourceMappingURL=PeerEndpointRecorder.js.map

package/dist/core/PeerEndpointRecorder.js.map

@@ -1 +1 @@
-{"version":3,"file":"PeerEndpointRecorder.js","sourceRoot":"","sources":["../../src/core/PeerEndpointRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAYvF,MAAM,OAAO,oBAAoB;IACd,CAAC,CAA2B;IAE7C,YAAY,IAA8B;QACxC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;IAChB,CAAC;IAEO,GAAG,CAAC,CAAS;QACnB,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,oBAAoB,CAAC,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,aAAqB,EAAE,GAAY;QACxC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,oBAAoB,EAAE;YAAE,OAAO,KAAK,CAAC;QACjD,IAAI,CAAC,aAAa;YAAE,OAAO,KAAK,CAAC;QACjC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC,CAAC,kBAAkB;QACvE,MAAM,SAAS,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,CAAC,4CAA4C;QACtF,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC;YACvD,IAAI,kBAAkB,CAAC,OAAO,EAAE,SAAS,CAAC;gBAAE,OAAO,KAAK,CAAC,CAAC,8BAA8B;YACxF,IAAI,CAAC,CAAC,CAAC,sBAAsB,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;YACxD,IAAI,CAAC,GAAG,CAAC,YAAY,SAAS,CAAC,MAAM,oBAAoB,aAAa,KAAK,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACtH,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,qFAAqF;YACrF,yFAAyF;YACzF,wFAAwF;YACxF,IAAI,CAAC,GAAG,CAAC,mBAAmB,aAAa,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAClG,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"PeerEndpointRecorder.js","sourceRoot":"","sources":["../../src/core/PeerEndpointRecorder.ts"],"names":[],"mappings":"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"}

package/dist/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
-  "packageVersion": "1.3.1212",
+  "packageVersion": "1.3.1213",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/dist/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "e5674d7f14d889d929e239fecc78aa34e4fafebd8e07f9e7b598339109b7b084",
+  "sha256": "0511bc378e28f623a7f8670ca57f2563ae0c20396c88c436fd87507377ca87b9",
   "registrySha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
-  "packageVersion": "1.3.1212"
+  "packageVersion": "1.3.1213"
 }

package/dist/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
   "articleCount": 90,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1212"
+  "packageVersion": "1.3.1213"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1212",
+  "version": "1.3.1213",
   "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-08-29T19:31:15.184Z",
-  "instarVersion": "1.3.1212",
+  "generatedAt": "2026-08-29T20:28:30.776Z",
+  "instarVersion": "1.3.1213",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/src/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
-  "packageVersion": "1.3.1212",
+  "packageVersion": "1.3.1213",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/src/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "e5674d7f14d889d929e239fecc78aa34e4fafebd8e07f9e7b598339109b7b084",
+  "sha256": "0511bc378e28f623a7f8670ca57f2563ae0c20396c88c436fd87507377ca87b9",
   "registrySha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
-  "packageVersion": "1.3.1212"
+  "packageVersion": "1.3.1213"
 }

package/src/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
   "articleCount": 90,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1212"
+  "packageVersion": "1.3.1213"
 }

package/upgrades/1.3.1213.md

@@ -0,0 +1,45 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`PeerEndpointRecorder` gained invariant 2b: a non-empty peer advertisement that OMITS a
+rope kind no longer discards that kind when this machine's own rope-health record shows
+it currently alive. Retention requires positive evidence — a dead rope, a never-dialled
+rope, and an unreadable health source all keep the previous replace semantics, and an
+advertised kind always wins for its own kind. Wired from `meshResolver.snapshot()` in
+`server.ts`.
+
+Found live on 2026-08-29: a peer whose agent runs inside WSL can only see an unreachable
+virtual NIC, so it advertised `[lan]` alone, and the mesh discarded the working tailscale
+rope that was carrying its traffic at that moment.
+
+## What to Tell Your User
+
+If one of your machines runs its agent inside a nested environment (WSL, a container, a
+VM), it may not be able to see the address the other machines actually reach it on. When
+it announced the only address it *could* see, your other machines used to believe it and
+throw away the route that was working — leaving that machine unreachable with no way for
+it to correct the record.
+
+Now a route your machine can see carrying traffic is kept even when an announcement
+forgets to mention it. A route that has genuinely gone dead is still dropped, so nothing
+lingers forever.
+
+## Summary of New Capabilities
+
+- A peer's shorter address list can no longer delete a route this machine can see working.
+- Retention is evidence-based: only a rope the local health record reports alive is kept;
+  dead and never-dialled ropes are dropped exactly as before.
+- Fully reversible — with no health source wired the behaviour is byte-identical to the
+  previous replace semantics.
+
+## Evidence
+
+- Unit: `tests/unit/PeerEndpointRecorder.test.ts` (+8 cases), verified red-then-green
+  against pre-2b behaviour.
+- Integration: `tests/integration/mesh-endpoint-propagation.test.ts` (+2 cases) driving
+  the real `/api/lease` route with a real registry.
+- Side-effects review: `upgrades/side-effects/mesh-endpoint-degradation-retention.md`.

package/upgrades/side-effects/mesh-endpoint-degradation-retention.md

@@ -0,0 +1,106 @@
+# Side-effects review — mesh endpoint degradation retention (invariant 2b)
+
+**Change:** `PeerEndpointRecorder.record()` no longer lets a non-empty but DEGRADED peer
+advertisement discard a rope this machine's own health record currently shows alive.
+Wired in `server.ts` from `meshResolver.snapshot()`.
+
+**Origin (live incident, 2026-08-29, topic 62395):** a peer whose agent runs inside WSL
+can only see an unreachable virtual NIC (`eth0 172.22.96.135`); Tailscale lives on the
+Windows host, outside that VM. It advertised `[lan]` alone; the recorder replaced
+`[tailscale, lan]`, and the mesh lost its only working route to that machine — while the
+tailscale rope was verifiably carrying traffic at that moment (peer answered
+`/health` 200 and a signed mesh probe returned the typed `not-router` refusal).
+
+## 1. Over-block — what legitimate input does this now reject?
+
+None: the change never rejects an advertisement. Every advertised kind is still recorded
+verbatim and still wins for its own kind (covered by the "re-advertising a kind with a new
+url still wins" and "advertised kind actually changed" tests). The only behavioural delta
+is ADDITIVE retention of an omitted kind.
+
+The nearest thing to an over-block is over-RETENTION: keeping a rope the peer meant to
+retire. Bounded three ways — retention requires a positive `alive === true`; `false` and
+`undefined` (never dialled) both drop; and the resolver remains the dial-time authority,
+so a retained rope that stops working is marked dead and then dropped on the next
+degraded advertisement.
+
+## 2. Under-block — what does this still miss?
+
+It does NOT help when the proven rope is ALSO not currently alive in the health record at
+the moment the degraded advertisement lands (a machine that reboots into WSL-only
+visibility while its tailscale rope happens to be marked dead). That case needs the
+peer to be able to advertise an address it cannot locally see, which is the separate
+NAT'd-machine work — tracked, not deferred silently:
+<!-- tracked: CMT-211 -->
+
+It also does not fix the root cause for that machine: a WSL-hosted agent still cannot
+discover its own reachable address. This change stops the DATA LOSS, not the blindness.
+
+## 3. Level-of-abstraction fit
+
+Correct layer. `PeerEndpointRecorder` is the documented single chokepoint for "I just
+learned a peer's ropes" and already owns invariants 1–5, including the sibling
+absence-is-never-a-wipe rule. Invariant 2b is the same class of protection (an
+advertisement must not destroy knowledge) and belongs beside it, not in the two
+callsites. Nothing lower (the validator) knows current state; nothing higher (the routes)
+should own merge policy.
+
+## 4. Signal vs authority compliance
+
+Compliant. The recorder produces/persists a SIGNAL (the known endpoint set); it holds no
+blocking authority. `PeerEndpointResolver` remains the dial-time authority and already
+deprioritises-but-probes dead ropes, so a retained-but-stale endpoint cannot block or
+misroute anything — it can only be tried last. The new dep is a read-only evidence
+source; an exception from it is caught and degrades to the previous behaviour.
+
+## 5. Interactions
+
+- **Invariant 4 (idempotency):** preserved and explicitly tested — when the merged set
+  equals what is stored (the common steady-state case), the write is still skipped, so
+  this does not reintroduce the ~720 no-op rewrites/day the idempotency guard removed.
+- **Invariant 2 (absence):** untouched; the empty/invalid path returns before the merge.
+- **Invariant 5 (advisory):** untouched; only the peer's own entry is written.
+- **`MeshEndpointValidator` cap:** the merge appends retained entries AFTER validation of
+  the advertised set. A peer at the kind cap cannot exceed it, because retention only
+  adds kinds the advertisement did NOT name and there are three kinds total.
+- **No double-fire / no race added:** the merge is pure and synchronous inside the
+  existing single write path.
+
+## 6. External surfaces
+
+No route, config key, schema, or user-visible surface changes. `GET /health →
+multiMachine.syncStatus` and `GET /pool` may now show a peer retaining a rope kind they
+would previously have lost — which is the intended correction. Timing dependence is
+limited to reading a live snapshot, and the failure mode of that read is explicitly
+"no evidence ⇒ previous behaviour".
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN.** The retention decision is made from the RECEIVING machine's
+own rope-health record and written only into its own registry copy. This is deliberate
+and load-bearing: rope health is inherently per-observer (machine A's tailscale rope to C
+can be alive while B's is dead), so replicating the decision would let one machine's view
+overwrite another's ground truth. Each machine independently reaches the correct answer
+from its own evidence. No replication path is added and none is wanted. A single-machine
+agent has no peers and is a strict no-op.
+
+## 8. Rollback cost
+
+Trivial and total. Remove the `isEndpointAlive` dep from the `server.ts` construction and
+the recorder falls back — by an explicitly-tested path ("with NO health dep wired,
+behaviour is byte-identical to plain replace") — to the exact pre-change semantics. No
+data migration: the registry format is unchanged, and a retained endpoint is an ordinary
+entry the next advertisement can overwrite. No agent state repair.
+
+## Tests
+
+- Unit (`tests/unit/PeerEndpointRecorder.test.ts`, +8): retain-on-alive, drop-on-dead,
+  drop-on-no-evidence, drop-on-throw, advertised-kind-upgrade-wins, idempotent-merge,
+  no-dep-is-identical. Verified RED against pre-2b behaviour (3 failures for the right
+  reason: the retention cases) and GREEN after.
+- Integration (`tests/integration/mesh-endpoint-propagation.test.ts`, +2): the real
+  `/api/lease` route with a real registry — a degraded advertisement keeps a live rope,
+  and still drops a dead one.
+- E2E: not applicable — no new API route or feature-liveness surface; the change is a
+  merge rule inside an existing chokepoint already covered end-to-end by the integration
+  route test.