instar 1.3.194 → 1.3.196

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-02T01:01:44.852Z",
-  "instarVersion": "1.3.194",
+  "generatedAt": "2026-06-02T02:41:08.992Z",
+  "instarVersion": "1.3.196",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "f322fd8145036bf5369d7d8b083c782e0a612ee456cdf8853bf6483655664bf1",
+      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "f322fd8145036bf5369d7d8b083c782e0a612ee456cdf8853bf6483655664bf1",
+      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "f322fd8145036bf5369d7d8b083c782e0a612ee456cdf8853bf6483655664bf1",
+      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "f322fd8145036bf5369d7d8b083c782e0a612ee456cdf8853bf6483655664bf1",
+      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "f322fd8145036bf5369d7d8b083c782e0a612ee456cdf8853bf6483655664bf1",
+      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "f322fd8145036bf5369d7d8b083c782e0a612ee456cdf8853bf6483655664bf1",
+      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "f322fd8145036bf5369d7d8b083c782e0a612ee456cdf8853bf6483655664bf1",
+      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "f322fd8145036bf5369d7d8b083c782e0a612ee456cdf8853bf6483655664bf1",
+      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "f322fd8145036bf5369d7d8b083c782e0a612ee456cdf8853bf6483655664bf1",
+      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "f322fd8145036bf5369d7d8b083c782e0a612ee456cdf8853bf6483655664bf1",
+      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "f322fd8145036bf5369d7d8b083c782e0a612ee456cdf8853bf6483655664bf1",
+      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "f322fd8145036bf5369d7d8b083c782e0a612ee456cdf8853bf6483655664bf1",
+      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "f322fd8145036bf5369d7d8b083c782e0a612ee456cdf8853bf6483655664bf1",
+      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "f322fd8145036bf5369d7d8b083c782e0a612ee456cdf8853bf6483655664bf1",
+      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "f322fd8145036bf5369d7d8b083c782e0a612ee456cdf8853bf6483655664bf1",
+      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -753,7 +753,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/machineRoutes.ts",
-      "contentHash": "1d64bdcd5106044c1d9d976dfbd610876f09755ac38a57a76e2994eaa39b238d",
+      "contentHash": "a8b151ac8857cb3c161ed123cb175b400db9ad6d0bb18fe8def72a33fa1444ac",
       "since": "2025-01-01"
     },
     "route-group:secret-drop": {
@@ -1089,7 +1089,7 @@
       "type": "template",
       "domain": "operations",
       "sourcePath": "src/templates/scripts/convergence-check.sh",
-      "contentHash": "41ef69307819140731f293b175093238f88988365c3973b8e44b9c18669e32bd",
+      "contentHash": "b0475554bde6729d2d9a1f8005dcada6a8e4c767203d8293c09a212f9bf0a196",
       "since": "2025-01-01"
     },
     "template:git-sync-gate.sh": {
@@ -1457,7 +1457,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "7eb989c2729fd9444153c88828d66a63b17490f5ddad146930fe6d21f0026a11",
+      "contentHash": "fde1c526b156577e0ad447d179760c9a0b095b051b6af0fd56b879278f504c38",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {
@@ -1489,7 +1489,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "f322fd8145036bf5369d7d8b083c782e0a612ee456cdf8853bf6483655664bf1",
+      "contentHash": "1cd3546e774a6045c3b8c1481a1aa2acfbbb330232f7d3f1353d0f92aca6b1bc",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {
@@ -1545,7 +1545,7 @@
       "type": "subsystem",
       "domain": "coordination",
       "sourcePath": "src/core/MultiMachineCoordinator.ts",
-      "contentHash": "1dc3fb11c8ddea5cfe5f02561636cd54c1661d0e9da04f54607ad7679f027ea6",
+      "contentHash": "63ce6fcd9564b1e547e2b0ad6153e43293566dac6a6db6f17ffb8cbf28b28894",
       "since": "2025-01-01"
     },
     "subsystem:backup-manager": {

package/src/scaffold/templates.ts

@@ -435,7 +435,7 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 - **A handoff feels like a compaction pause, not amnesia** — the new machine resumes via CONTINUATION (picks up the thread, no re-greeting). Planned handoff = current context; hard failover = as-of-last-sync, and if my context is partial I say so honestly ("picking this back up from the other machine").
 - Read mesh/sync state, never guess it: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/health\` → \`multiMachine.syncStatus\` (\`leaseHolder, leaseEpoch, holdsLease, splitBrainState, awakeMachineCount\`); \`instar doctor\` shows the same.
 - A genuinely **unresolvable split-brain** surfaces as ONE Attention-queue item with a Y/N decision ("demote machine X?"), deduped per partition episode — I present it to the user, I don't silently pick.
-- Dials under \`.instar/config.json\` → \`multiMachine\` (ingressHeartbeatMs, leaseTtlMs, liveTailMaxStalenessMs, handoffAckTimeoutMs, …); a nonsensical combo is rejected at startup, not run silently.
+- Dials under \`.instar/config.json\` → \`multiMachine\` (ingressHeartbeatMs, leaseTtlMs, leasePullIntervalMs, liveTailMaxStalenessMs, handoffAckTimeoutMs, …); a nonsensical combo is rejected at startup, not run silently.
 
 **Multi-Machine Session Pool (active-active — spread conversations across machines)** — The longer arc beyond one-awake-machine: with the pool enabled I run conversations across ALL my machines at once and can MOVE a conversation between them. Ships DARK behind \`multiMachine.sessionPool.stage\` (default 'dark'); a single-machine agent is a no-op.
 - **See the pool:** the **Machines tab** in the dashboard, or \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/pool\` → which machine is the router ("dispatcher") + every machine's nickname, hardware, online status, load, and clock-skew status.

package/src/templates/scripts/convergence-check.sh

@@ -149,6 +149,26 @@ if echo "$CONTENT" | grep -qiE "(i used to (think|believe|feel|assume)|back when
   ISSUE_COUNT=$((ISSUE_COUNT + 1))
 fi
 
+# 8. SPEC-REVIEW LINK — a spec handed over for review must carry a rendered
+# ELI16 tunnel link the operator can open. Structure > Willpower: the link is
+# guaranteed by skills/spec-converge/scripts/publish-spec-review.mjs. Narrow by
+# design (this blocks the send): fires only on an unambiguous spec handoff —
+# a docs/specs/*.md reference, OR a GitHub PR mentioned with the word "spec" —
+# in an explicit review/approval handoff, with no /view/ link present. An
+# ordinary code-PR mention does not fire.
+SPEC_HANDOFF=""
+if echo "$CONTENT" | grep -qiE "docs/specs/[^ )]+\.md"; then
+  SPEC_HANDOFF="yes"
+elif echo "$CONTENT" | grep -qiE "github\.com/[^ )]+/pull/[0-9]+" && echo "$CONTENT" | grep -qiE "\bspec(s|ification)?\b"; then
+  SPEC_HANDOFF="yes"
+fi
+if [ -n "$SPEC_HANDOFF" ] \
+  && echo "$CONTENT" | grep -qiE "\b(review|approv|sign[- ]?off|take a look|for your|ready for)\b" \
+  && ! echo "$CONTENT" | grep -qiE "/view/[0-9a-f-]{8,}"; then
+  ISSUES+=("SPEC_REVIEW_LINK: You're handing a spec over for review with no rendered ELI16 tunnel link the operator can open. Deliver spec reviews via skills/spec-converge/scripts/publish-spec-review.mjs — it renders the ELI16, verifies the link (HTTP 200), and includes it. Don't send a spec for review without the rendered link.")
+  ISSUE_COUNT=$((ISSUE_COUNT + 1))
+fi
+
 # Output results
 if [ "$ISSUE_COUNT" -gt "0" ]; then
   echo "=== CONVERGENCE CHECK: ${ISSUE_COUNT} ISSUE(S) FOUND ==="

package/upgrades/1.3.195.md

@@ -0,0 +1,33 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Multi-machine agents now actively **pull** the lease that decides which machine is "awake," instead of only waiting to be told.
+
+Previously a standby machine learned about a takeover only when the awake machine could push a message to it. On a quiet network, or one where traffic only flows one direction (a common home-network situation), that push might never arrive — so a standby could be left blind, and two machines could each believe they were in charge without noticing each other.
+
+Now every machine, on a steady cadence and regardless of whether the other looks alive, asks its peers for their current lease. If it learns a newer one, it steps down automatically. If it discovers a genuine tie — both machines holding the same generation of the lease — it records that as a contested state visible on the dashboard rather than silently carrying on. This is the robustness-under-poor-conditions half of the cross-machine work, and it ships build-and-test only: nothing in a live deployment is switched on by this change.
+
+The session-pool rollout control was also tightened so it can only roll a stage back (on a failed end-to-end check for the running build), never advance on its own — advancing stays a deliberate operator action.
+
+## What to Tell Your User
+
+- **No more blind standby**: "If I'm running on more than one of your machines, the backup now actively checks in with the others on its own schedule — so even on a quiet or one-way home network it won't get stuck thinking it's in charge when it isn't."
+- **Honest about confusion**: "If two of my machines ever end up both believing they're the active one, I now surface that as a flagged, contested state you can see — instead of quietly double-acting."
+- **Nothing to set up**: "This is on by default with sensible timing and changes nothing about how you talk to me; it only makes the multi-machine setup steadier when conditions are bad."
+
+## Summary of New Capabilities
+
+- An active lease-pull path on the machine-to-machine channel (a new authenticated pull endpoint plus a pull method on the lease transport) so a standby can ask for a peer's current lease instead of only being pushed to.
+- A constant-cadence, jittered standby pull loop that runs independent of holder liveness, auto-demotes a fenced holder on a newer lease, and surfaces a same-epoch split-brain near-silently to the sync status / dashboard.
+- A configurable pull cadence with a startup-validated bound (pull at least once per lease lifetime), resolved alongside the other cross-machine timing knobs and noted in the agent's own capability docs.
+- A revert-only rollout reconcile tick for the session pool, with the running commit identifier resolved from git at boot.
+
+## Evidence
+
+- 108 tests green across the touched area and all three tiers: unit (lease transport pull cases, lease-coordinator pull accessors and same-epoch masking, the pull-cadence config invariant, the coordinator pull-loop contested surface), integration (the new pull endpoint: serve, empty, and unauthenticated), and end-to-end (a two-machine partition produces two awake machines, and on heal the active pull converges back to one — over the real lease components and a mock HTTP wire). Type-check clean.
+- Test-writing caught a real setup bug (a lease builder's third argument is the nonce, not the epoch) before it reached an assertion.
+- Spec: docs/specs/MULTI-MACHINE-ROBUST-LEASE-PROPAGATION-SPEC.md (approved). Side-effects review: upgrades/side-effects/multi-machine-robust-lease-propagation.md.

package/upgrades/1.3.196.md

@@ -0,0 +1,27 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixes a crash-loop regression introduced with the multi-machine active-pull feature.
+
+On a machine running by itself (no other live machine in its mesh), the active-pull loop was re-checking the "who's awake" role every few seconds and, whenever the short-lived internal lease briefly lapsed between renewals, wrongly flipped the machine to a standby (read-only) state. A follow-up write then crashed the server, and it restarted into the same loop. Because the server is also the messaging relay, the operator saw silence during the loop.
+
+The fix: the active-pull loop now only re-evaluates the awake/standby role when it has actually heard a lease from a peer. A machine on its own is never demoted by the pull loop on a transient lease lapse — its normal heartbeat keeps renewing the lease as before. The genuine multi-machine behavior (a backup that pulls a newer lease from a live peer still steps down) is unchanged.
+
+This pairs with the earlier hardening that made a read-only/standby write non-fatal, so both the wrong state and the crash it could cause are now closed.
+
+## What to Tell Your User
+
+Nothing to do. If you run an agent on a single machine, this removes a rare crash-restart loop that could make it go quiet for a while; multi-machine setups behave the same as before, just without the spurious solo demotion.
+
+## Summary of New Capabilities
+
+- The active lease-pull loop only reconciles the awake/standby role when a peer lease was actually observed, so a solo machine is never demoted (and never driven read-only) by the pull loop on a transient self-lease lapse. Regression test added; the real peer-driven demotion path is retained and tested.
+
+## Evidence
+
+- `tsc --noEmit` clean; 45 multi-machine unit tests green, including a new regression (a solo holder whose self-lease lapses with no peer observed stays awake and never goes read-only) and the retained same-epoch contested-split-brain test (feature intact).
+- Root cause of the 2026-06-02 echo crash-loop incident. Spec: docs/specs/MULTI-MACHINE-ROBUST-LEASE-PROPAGATION-SPEC.md (approved). Side-effects review: upgrades/side-effects/fix-activepull-solo-demotion.md.

package/upgrades/side-effects/fix-activepull-solo-demotion.md

@@ -0,0 +1,75 @@
+# Side-Effects Review — Fix: active-pull must not demote a solo machine on a transient lease lapse
+
+**Version / slug:** `fix-activepull-solo-demotion`
+**Date:** `2026-06-02`
+**Author:** `echo`
+**Spec:** `docs/specs/MULTI-MACHINE-ROBUST-LEASE-PROPAGATION-SPEC.md` (approved: true) — corrects a regression in the active-pull it introduced (#668).
+**Parent principle:** `Cross-Machine Coherence — One Agent, Robust Under Degraded Conditions`
+
+## Summary of the change
+
+A one-condition fix to `MultiMachineCoordinator.tickLeasePull`: it now only calls
+`reconcileRoleToLease('lease-pull')` + `surfacePullDiscoveredSplitBrain()` when a peer
+lease was **actually observed** (`leaseCoordinator.observedPeerLease()` non-null).
+
+### Why (live incident, 2026-06-02)
+
+The active-pull loop (shipped in #668) reconciled the machine's lease role
+**unconditionally** every `leasePullIntervalMs` (~5s). On a solo machine — one with no
+reachable peers (the only registry peer was dead 3 days, no `lastKnownUrl`, so `peers()`
+was empty) — every brief lapse of the 60s self-lease between renewals made
+`holdsLease()` return false, so the pull loop flipped the machine to **standby** →
+`StateManager` read-only → a standby write threw and (pre-#673) crashed the server in a
+launchd restart loop (lease epoch climbed into the thousands). The crashing server is the
+Telegram relay, so the operator saw silence. #673 already stopped the *crash* (read-only
+write is now an isolated/recoverable uncaught-exception class); this PR removes the *root
+cause* (the spurious demotion itself).
+
+## Decision-point inventory
+
+- `tickLeasePull` reconcile vs skip: reconcile only when `observedPeerLease()` is non-null.
+  Pull is for LEARNING from peers; with no peer signal there is nothing to reconcile.
+  Role/renewal for a solo holder stays with the heartbeat `tickLease` (which RE-ACQUIRES,
+  not merely demotes).
+
+## 1. Over-correction risk
+Does gating on an observed peer break the real feature (a standby pulling a higher-epoch
+holder must still demote)? No — that path records the holder's lease via `recordObserved`,
+so `observedPeerLease()` is non-null and the reconcile runs exactly as before. Covered by
+the retained "same-epoch contested" test.
+
+## 2. Under-correction risk
+A solo holder whose lease lapses is no longer demoted by the *pull* loop, but the 2-min
+heartbeat `tickLease` still renews/re-acquires it — so role management is preserved, just
+moved off the aggressive 5s pull cadence that caused the DoS.
+
+## 3. Level-of-abstraction fit
+The fix sits in the pull tick (the loop that caused the regression), gating on the
+coordinator's existing `observedPeerLease()` accessor — no new surface.
+
+## 4. Signal vs Authority
+The pull remains a SIGNAL (observe peer leases); the FencedLease epoch/validity checks
+remain the authority for who holds. The fix stops the signal loop from ACTING (demoting)
+in the absence of any signal.
+
+## 5. External surfaces
+None. No route/config/schema change. `leasePullIntervalMs` unchanged.
+
+## 6. Interactions with existing primitives
+Composes with #673 (read-only-write no longer fatal) as defense-in-depth: #673 prevents
+the crash; this prevents the wrong state that led to it. The heartbeat `tickLease` and the
+acquire path are untouched.
+
+## 7. Rollback cost
+Trivial + safe: a single `if (observedPeerLease())` guard. Reverting restores the prior
+(buggy) unconditional reconcile.
+
+## Migration parity
+None — pure code logic change, reaches existing agents on the normal dist update.
+
+## Tests
+`tsc --noEmit` clean. 45 multi-machine tests green, including a NEW regression
+(`MultiMachineCoordinator-leasePull` — a solo holder whose self-lease lapses with no peer
+observed stays awake + never goes read-only) and the retained same-epoch-contested test
+(feature intact). Operational note: echo was reverted to solo mode during the incident
+(machine identity moved aside); re-pairing its mesh is a separate, operator-gated step.

package/upgrades/side-effects/multi-machine-robust-lease-propagation.md

@@ -0,0 +1,120 @@
+# Side-Effects Review — Multi-Machine Robust Lease Propagation (active PULL)
+
+**Version / slug:** `multi-machine-robust-lease-propagation`
+**Date:** `2026-06-01`
+**Author:** `echo`
+**Second-pass reviewer:** `independent lessons-aware convergence review (2 passes → converged)`
+**Spec:** `docs/specs/MULTI-MACHINE-ROBUST-LEASE-PROPAGATION-SPEC.md` (approved: true, approved-with-change)
+**Parent principle:** `Cross-Machine Coherence — One Agent, Robust Under Degraded Conditions`
+
+## Summary of the change
+
+Adds an **active lease PULL** path to the cross-machine fenced-lease layer, so a
+standby is no longer blind on a quiet or one-way (NAT) network where the holder's
+broadcast never arrives. The transport gains a `pullPeer`/`pullAllPeers` over the
+authenticated channel (`POST /api/lease/pull`, machine-auth is body-hash based so a
+signed empty body authenticates cleanly); the coordinator runs a constant-cadence,
+jittered pull loop independent of holder liveness, folds a pulled higher-epoch lease
+(auto-demoting a fenced holder) and surfaces a same-epoch contested split-brain
+Near-Silently (logs + `getSyncStatus().splitBrainState='contested'`), which the
+registry `awakeMachineCount` misses in a git-less mesh.
+
+This is **build + test only**: the loop arms only when a pull-capable transport is
+attached and multi-machine is configured; no production lease, stage, or config is
+flipped by this change. The session-pool rollout `StageAdvancer` is now wired to a
+**revert-only** reconcile tick (it can demote a live stage on a red E2E for the current
+commit; promotion stays operator-triggered) and its commit SHA is boot-cached from git.
+
+## Decision-point inventory
+
+- `HttpLeaseTransport.pullPeer` returns the peer lease / `null` (network error, non-ok,
+  or no lease are all advisory `null` — never thrown); a successful pull (even one
+  carrying no lease) marks the medium reachable (bidirectional `isReachable`).
+- `LeaseCoordinator.effectiveView` fold: a pulled lease overrides only when STRICTLY
+  higher-epoch (same-epoch self-issued wins the tie) — the existing rule, unchanged.
+- `surfacePullDiscoveredSplitBrain` contested vs clear: we still hold AND a raw observed
+  peer lease names a different holder at our epoch → latch `contested` (rising-edge log).
+- `StageAdvancer.reconcile` revert vs hold: red E2E for the CURRENT commit → revert one
+  stage; otherwise hold (promotion is never automatic).
+
+## 1. Over-block / over-act risk
+The pull loop never ACTS on roles — it only folds observed leases and reconciles role to
+`holdsLease()`. A pulled higher epoch demotes us (correct fencing); a same-epoch tie does
+NOT demote (it surfaces as contested, the genuinely-unresolvable case the operator owns).
+The reconcile tick can only demote a stage on a verified red, never advance.
+
+## 2. Under-act risk
+A quiet/one-way network previously left a standby blind (the bug this closes). The
+constant cadence — independent of whether the holder looks alive — is the anti-blinding
+guarantee; the startup invariant `leasePullIntervalMs < leaseTtlMs` ensures at least one
+pull per lease lifetime.
+
+## 3. Level-of-abstraction fit
+The pull lives at the transport (wire) + coordinator (lease authority) layers — the same
+layers that own broadcast/observe — not bolted onto a sentinel or prompt. The route is a
+sibling of the existing `POST /api/lease` receive route.
+
+## 4. Signal vs Authority
+The pull is a LEARNING signal (folds observed state); the FencedLease epoch/signature
+checks remain the sole authority for who holds. A pull cannot grant authority — only the
+CAS/fence can. Split-brain surfacing is observability only (no auto-demote on a tie).
+
+## 5. External surfaces
+Adds `POST /api/lease/pull` (machine-auth gated; returns the responder's effective-view
+lease, which may re-serve a third machine — there is intentionally NO holder==responder
+guard since the puller re-verifies via `acceptTunnelLease`). No new outbound external
+calls beyond peer pulls over the already-authenticated machine channel.
+
+## 6. Interactions with existing primitives
+`pullPeer`/`pullAllPeers` are OPTIONAL on the `LeaseTransport` interface, so existing
+mock/git-only transports remain valid and `canPullPeers()` is false there (loop no-ops).
+`leasePullIntervalMs` joins the resolved seamlessness config with a startup invariant,
+de-conflicted from the existing `standbyPullIntervalMs` (git pull) by name and purpose.
+The pull-tick reconcile reuses `reconcileRoleToLease`; the contested flag ORs into the
+existing `getSyncStatus` split-brain computation.
+
+## 7. Rollback cost
+All additive + default-safe. The pull loop only arms with a pull-capable transport +
+multi-machine config; `stop()` clears the timer (stopped-guard prevents resurrection from
+an in-flight tick's re-arm). Disabling = set `leasePullIntervalMs` ≥ `leaseTtlMs` (caught
+at startup) or run a git-only transport. No production lease/stage state is changed by
+this commit.
+
+## Migration parity
+- `leasePullIntervalMs` is a code-defaulted (5s) optional knob resolved + validated in
+  `seamlessnessConfig` (matches its siblings — not seeded into config.json), so existing
+  agents get the default with no migration; a nonsensical value is rejected at startup.
+- The CLAUDE.md dials note gains `leasePullIntervalMs` in BOTH the generator
+  (`templates.ts`) and the migrator (`PostUpdateMigrator.ts` `migrateClaudeMd`) so new
+  and existing agents both learn the dial.
+
+## Tests
+108 green across the touched area + 3 tiers: unit (`HttpLeaseTransport` pull cases,
+`LeaseCoordinator` pull accessors + same-epoch masking, `seamlessnessConfig`
+leasePullIntervalMs invariant, `MultiMachineCoordinator-leasePull` loop→contested),
+integration (`machine-routes` `POST /api/lease/pull` serve/null/401), e2e
+(`multi-machine-lease-split-brain` partition→two-awake→pull-converge-to-one over real
+lease components + mock HTTP). `tsc --noEmit` clean. Test-writing caught a real bug: the
+`buildAcquisition` 3rd arg is the NONCE not the epoch (the first draft built epoch-1
+leases when it meant epoch-5), and the same-epoch split-brain only forms when the peer
+lease appears AFTER local acquisition.
+
+## Follow-up (CI shard 4/4, post-merge-with-main)
+
+`initializeLease()` → `startLeasePullLoop()` called `leaseCoordinator.canPullPeers()`
+unconditionally, which threw for an injected coordinator that does not implement the
+pull API — the existing `multi-machine-coordinator.test.ts` partial double (`fakeLease`)
+lacks it, and so would any build predating active-pull. Hardened the loop start with a
+`typeof this.leaseCoordinator.canPullPeers === 'function'` guard so such a coordinator
+simply skips the loop (the intended git-only-mesh / partial-double behavior) instead of
+crashing. Caught by the full CI unit matrix (shard 4/4, both Node 20 and 22) after the
+merge with main brought the existing coordinator test into scope; 28 multi-machine tests
+green, `tsc --noEmit` clean.
+
+Also regenerated the generated `src/data/builtin-manifest.json` (via
+`npm run generate:manifest`): an earlier revert to drop version churn from the PR diff
+left it stale at v1.3.154, but `builtin-manifest.test.ts` ("is up-to-date with current
+source") compares against the regenerated manifest for current source (now v1.3.192
+post-merge). No behavior change — it is a generated data file. (`esm-compliance.test.ts`'s
+local `require()` findings are byte-identical to main and present on main, so they are
+pre-existing and pass in CI — not introduced here.)