instar 1.3.90 → 1.3.92

package/upgrades/1.3.92.md

@@ -0,0 +1,63 @@
+# Instar Upgrade Guide — NEXT
+
+> In-flight shipment notes for the **Multi-Machine Session Pool** (active-active,
+> per-session placement + transfer). Built track-by-track behind a dark stage
+> gate; this guide grows as tracks land and becomes the versioned guide at the
+> release cut. Spec: docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md (approved).
+
+## What Changed
+
+**Multi-Machine Session Pool — foundation (Track A: Router-Leader Lease).** The
+groundwork for one agent identity running across several machines, all awake at
+once, with each conversation placed on the best-fit machine and transferable
+between machines. This shipment lands the foundation and ships **dark** (the
+entire layer is inert unless explicitly enabled and its rollout stage advanced):
+
+- **Clock-jump-proof router lease.** The machine that holds the "who's in charge"
+  lease now judges its own lease expiry on a **monotonic clock** instead of the
+  wall clock. A wall-clock jump — an NTP correction, a VM pause/resume, a
+  sleep/wake, or a CPU-starvation timer slip — can no longer fool a partitioned
+  machine into thinking it still holds the lease (or into giving it up early).
+  This is the lease-substrate-robustness hardening that the whole session pool
+  rests on, and it directly answers the SleepWakeDetector CPU-starvation lesson.
+- **Router role.** The existing leader lease is now also addressable as the
+  "router" role (the machine that dispatches conversations to machines). On a
+  single machine this is a no-op — it is its own router.
+- **Dark config block.** A new `multiMachine.sessionPool` config block ships
+  turned off (`enabled: false`, `stage: 'dark'`, `dryRun: true`). Existing
+  agents receive these dark defaults automatically on update.
+
+**Track B (part 1: machine nicknames).** Every machine the agent is installed on
+now gets a friendly, auto-assigned **nickname** (e.g. "Mac Mini", "Justins Macbook
+Pro") — the handle you'll use to say "run this on the mini" / "move this to <name>".
+Nicknames are unique within the pool, editable, and derived deterministically from
+the machine's hostname. Still dark (the Machines dashboard tab + the placement
+commands that consume nicknames land in the next part of Track B).
+
+## What to Tell Your User
+
+Nothing changes for you yet — this ships turned off. When the full feature is
+ready, your agent will be able to spread conversations across all the machines
+it's installed on (and you'll get a Machines tab in the dashboard to name them
+and move conversations between them by nickname). For now, this update just makes
+the under-the-hood "who's in charge" machinery immune to clock jumps, which makes
+everything steadier. A one-machine agent behaves exactly as before.
+
+## Summary of New Capabilities
+
+- Monotonic, clock-jump-proof self-fence for the router/leader lease
+  (`LeaseCoordinator`).
+- `MultiMachineCoordinator.isRouter()` — router-role accessor (alias of
+  `holdsLease()`).
+- `multiMachine.sessionPool` dark config block (`enabled`/`stage`/`dryRun`) with
+  migration parity for existing agents.
+
+## Evidence
+
+- Tier-1 unit tests: monotonic self-fence (incl. the backward-wall-clock-jump
+  immunity proof and the mid-tick `holdsLease` fence), real-monotonic default
+  wiring integrity, `isRouter()`, and the dark config defaults + migration parity
+  (adds-into-existing-multiMachine, no-clobber, inert, idempotent).
+- 155 tests green across the lease/config/coordinator/seamlessness cluster after
+  the change; tsc clean. Full suite runs in CI.
+- Side-effects review: upgrades/side-effects/session-pool-track-a-router-lease.md

package/upgrades/side-effects/session-error-nudge-rearm.md

@@ -0,0 +1,17 @@
+# Side effects — Session error-nudge re-arm (fleet-wide fix)
+
+## What this changes
+`src/core/SessionManager.ts` — the post-API-error idle nudge is now re-armable instead of once-per-session-forever.
+- `errorNudgedSessions` is now a per-idle-episode flag: set on nudge, CLEARED in the existing "Session is active" branch (recovery), so a long-running session that hits a SECOND transient API error is nudged again.
+- New `errorNudgeTotal: Map` + `MAX_ERROR_NUDGES_PER_SESSION` (50) bound runaway: a session flapping error→nudge→error without truly recovering stops being nudged and falls through to the normal zombie-kill path. Cleared on `sessionComplete`.
+- New pure exported `shouldErrorNudge(armedThisEpisode, totalNudges, max)` is the gate the production code routes through (unit-testable boundary).
+
+## Why
+A 2026-05-29 autonomous run was found idle after an `API Error: 500` — the SECOND such stop. Root cause: the nudge fired once per session, ever (the guard set was only cleared on sessionComplete). The in-session autonomous Stop hook cannot cover this (it fires only on a clean Stop, not an errored turn). Spec: docs/specs/SESSION-ERROR-NUDGE-REARM-SPEC.md.
+
+## Risk / blast radius
+Low + bounded. Behavior change is strictly MORE recovery (re-nudge on a fresh error episode) with a hard lifetime cap (50) so it can never nudge forever or burn quota. The rate-limit/throttle path is untouched (still hands off to RateLimitSentinel, consumes no nudge token). Server-side code → deploys fleet-wide via the normal release/auto-update; no agent-file or config change, no migrator entry needed.
+
+## Tests
+- `tests/unit/session-error-nudge.test.ts` — +behavioral coverage of shouldErrorNudge (both sides of every branch: armed/not-armed, under/over cap, re-arm-after-recovery) + structural pins (episode flag cleared in the active branch; gate routes through shouldErrorNudge).
+- SessionManager-adjacent suites (behavioral, terminate, zombie-kill-topic-binding, reap-detect, injection, multishot-recovery) all green — no regression to the idle/kill path.

package/upgrades/side-effects/session-pool-capability-classification.md

@@ -0,0 +1,16 @@
+# Side effects — classify the session-pool route prefixes (capability-discoverability lint)
+
+## What this fixes
+The CI `capabilities-discoverability` lint requires every route prefix in routes.ts to be classified in `src/server/CapabilityIndex.ts` — either discoverable (CAPABILITY_INDEX) or explicitly internal (INTERNAL_PREFIXES). The session-pool added three unclassified prefixes (`/pool`, `/mesh`, `/session-pool`), failing shard 1/4 on #506. Classified now:
+- **`/pool` → discoverable** (new CAPABILITY_INDEX entry `multiMachinePool`): it's the agent-facing "where is this running? / move this to <nickname>" + Machines-tab status surface. build reports `configured: !!machinePoolRegistry` + endpoints.
+- **`/mesh` → INTERNAL**: machine-to-machine MeshRpc transport (Ed25519-signed peer traffic), never an agent/user capability.
+- **`/session-pool` → INTERNAL**: rollout-gate E2E results — operator observability for a dark feature.
+
+## Risk / blast radius
+None — classification metadata only; no runtime behavior change. `/pool` now appears in /capabilities (correct — it's the documented multi-machine status surface).
+
+## Tests
+- `tests/unit/capabilities-discoverability.test.ts` — 98 pass (was 3 failing on /mesh, /pool, /session-pool). This is the lint that gates route-prefix classification fleet-wide.
+
+## Lesson
+Ran only the pool test files locally, not the cross-cutting lint — the capabilities-discoverability lint runs against ALL routes, so new routes need classification. CI caught it; running the full unit suite (or this lint) locally before push would have caught it sooner.

package/upgrades/side-effects/session-pool-review-fixes.md

@@ -0,0 +1,23 @@
+# Side effects — pre-merge review fixes (Multi-Machine Session Pool, PR #506)
+
+## Context
+A 23-agent adversarial review of the session-pool components (each finding verified against the code) confirmed 14 issues. This commit fixes the genuine CORRECTNESS bugs in the dark code before #506 merges; the integration-wiring findings (load-broker → router, isolation-at-join) are the L6 activation phase (D11), tracked separately.
+
+## Fixes (4 correctness bugs)
+- **`src/core/SessionOwnership.ts` (CRITICAL):** `release` now requires `status === 'active'`. Previously a source could release WHILE transferring, advancing the record to `released` before the target T claimed — T's claim was then rejected (claim-out-of-sequence), orphaning the session. New reason `release-requires-active`. Matches the §L3 handoff order (release is the last step, after T is active).
+- **`src/core/PlacementExecutor.ts` (high):** `validateTopicPlacement` now rejects `pinned:true` without a `preferredMachine` (`pinned-without-target`) → placement-blocked, instead of silently treating it as unpinned and letting placement drift off the intended machine.
+- **`src/core/StageAdvancer.ts` (high):** `reconcile()` only reverts on a `red` E2E for the CURRENT commit — a stale red from a prior commit is no longer a false regression signal.
+- **`src/core/SessionRouter.ts` (high #7):** on a stale-ownership ACK, the router now re-forwards to the current owner when the owner OR the epoch changed (previously only on a different owner) — so a SAME-owner epoch advance re-delivers at the corrected epoch instead of needlessly re-placing. A spurious same-owner/same-epoch stale ACK still falls through to re-place (bounded by maxReResolveDepth).
+
+## Risk / blast radius
+None at runtime — all four files are dark (the pool is enabled:false). These are pure-logic corrections with regression tests; no behavior change for a single-machine agent.
+
+## Tests (regression, both sides)
+- SessionOwnership: rejects release-while-transferring (+ T can still claim); allows release from active.
+- PlacementExecutor: pinned-without-target → blocked; pinned+target → placed.
+- StageAdvancer: reconcile does NOT revert on a stale-commit red.
+- SessionRouter: same-owner epoch-advance re-forwards at the new epoch; spurious same-epoch stale → re-place (no loop).
+- Plus closed two flagged test gaps: TransferOrchestrator transport-failed sendTransferRpc → sync-corrupted (no claim); RebalancePlanner spreads moves across free targets (pile-on guard).
+
+## Tracked (activation phase — D11)
+Load-broker → router integration (computeMachineLoad feeding placement weight), checkAgentIsolation at join, sessionCountTrustworthy consumption, and the persistent NonceStore for mesh (vs in-memory) land when the live router/registration is wired during activation.

package/upgrades/side-effects/session-pool-track-a-router-lease.md

@@ -0,0 +1,29 @@
+# Side-Effects Review — Session Pool Track A: Router-Leader Lease (monotonic self-fence)
+
+**Spec:** docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md (approved, review-convergence stamped)
+**Track:** A (L1 — Router-Leader Lease + durable renewal). Ships DARK.
+**Files:** src/core/LeaseCoordinator.ts, src/core/MultiMachineCoordinator.ts, src/core/types.ts, src/config/ConfigDefaults.ts
+
+## What changed
+1. **`LeaseCoordinator` monotonic self-fence (the core change).** The holder's self-expiry / self-suspend decision — "have I confirmed a renewal within `leaseTtlMs`?" — now measures elapsed on a **monotonic clock** (`monotonicNow()`, default `process.hrtime`) instead of the wall clock (`Date.now()`). A new injectable `monotonicNow` dep; a `markRenewOk()` mutator records the monotonic timestamp at every confirmed acquire/renew/broadcast; `holdsLease()` additionally fences a holder whose monotonic elapsed exceeds the TTL (even before the next `renew()` tick). The wall clock is retained ONLY for the human-readable `expiresAt`/`acquiredAt` display fields and as a conservative second gate in `holdsValidLease`.
+2. **`MultiMachineCoordinator.isRouter()`** — a semantic alias of `holdsLease()` so session-pool code can ask "am I the router?" (spec §L1: in v0.1 the router lease IS the fenced leader lease). No behavior change.
+3. **`SessionPoolConfig` type + dark config defaults** — `multiMachine.sessionPool: { enabled: false, stage: 'dark', dryRun: true }` added to `SHARED_DEFAULTS`. Migration parity via the centralized `applyDefaults` path (existence-checked).
+
+## Blast radius
+- **`LeaseCoordinator`** is on the hot path (`holdsLease()` gates ingress polls, scheduler ticks, outbound sends, registry writes). The added monotonic check is a cheap arithmetic compare on each call. Authority (epoch + push-rejection CAS) is UNCHANGED — only the holder's own self-expiry clock source changed.
+- **Wall-clock removal risk:** the wall-clock `lastRenewOkAt` field was removed (it was write-only after the self-suspend moved to monotonic). No other reader existed (verified by grep).
+- **Config:** adding `multiMachine.sessionPool` ONLY (never `multiMachine.enabled`) means it is inert — `applyDefaults` merges it under an existing multiMachine block without clobbering, and adds an inert block to agents without multiMachine. No agent's multi-machine state is switched on.
+
+## Risk + mitigation
+- **Risk:** a holder that previously relied on a wall-clock-forward jump to self-expire early would now wait the full monotonic TTL. **Mitigation:** the monotonic TTL is the CORRECT bound; the wall-clock `isExpired` second gate still fences early on a forward jump (conservative). Net behavior is strictly safer (immune to backward jumps that previously could SUPPRESS the self-fence — the bug this fixes).
+- **Risk:** `process.hrtime` availability. **Mitigation:** present in all supported Node versions; injectable for tests.
+- **Regression surface:** existing `LeaseCoordinator.test.ts` self-suspend tests drove the injected wall clock; updated to inject `monotonicNow` tied to the same fake clock. Verified: 155 tests green across the lease/config/coordinator/seamlessness cluster (LeaseCoordinator, FencedLease, ConfigDefaults, multi-machine-coordinator, multimachine-syncstatus, seamlessness-fault-injection, telegram-seamless-contract, seamlessnessConfig, HttpLeaseTransport, coordinator-independent-mode, poll-owner-lease-wiring, PrimaryAggregatorLease).
+
+## Migration parity
+- Config default added to `ConfigDefaults.SHARED_DEFAULTS` → auto-applied to existing agents on update via `PostUpdateMigrator.migrateConfig` → `applyDefaults`. Idempotent, existence-checked, never clobbers an operator-tuned value. Test coverage in ConfigDefaults.test.ts (adds-into-existing-multiMachine, no-clobber, inert, idempotent).
+
+## Rollback
+- The whole layer is dark (`sessionPool.enabled:false`, `stage:'dark'`). The monotonic self-fence is a pure robustness improvement to the existing lease and is safe to keep regardless; if a revert were ever needed, restore the wall-clock `lastRenewOkAt` self-suspend (single field + the `renew()` comparison). The `monotonicNow` seam is additive (optional dep).
+
+## Agent awareness
+- Track A introduces no user-facing surface (internal lease hardening + dark config). The CLAUDE.md Tier-0 blurb + Playbook deep entry land with Track B's `GET /pool` route (the first user-facing surface) and the Machines dashboard tab, per the spec's Migration Parity & Agent Awareness section.

package/upgrades/side-effects/session-pool-track-b-agent-awareness.md

@@ -0,0 +1,29 @@
+# Side-Effects Review — Session Pool Track B: agent awareness (CLAUDE.md Tier-0 blurb)
+
+**Spec:** docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md §"Migration Parity & Agent Awareness" (approved)
+**Track:** B (agent awareness). Completes Track B's user-facing + awareness surface.
+**Files:** src/scaffold/templates.ts (generateClaudeMd), src/core/PostUpdateMigrator.ts (migrateClaudeMd)
+
+## What changed
+1. **`generateClaudeMd()` (templates.ts):** added a Tier-0 "Multi-Machine Session Pool" blurb to the capabilities section (right after Cross-Machine Seamlessness) — explains the active-active pool, the **Machines tab**, `GET /pool`, `PATCH /pool/machines/:id` (with curl), and the proactive triggers ("run this on / move this to <nickname>", "where is this running?"). New agents get it via `init`.
+2. **`migrateClaudeMd()` (PostUpdateMigrator.ts):** content-sniff append (idempotent on the marker `Multi-Machine Session Pool (active-active` / `/pool/machines/`) so EXISTING agents get the same section on update — Migration Parity.
+
+## Blast radius
+- **Docs/awareness only** — no behavioral code path. `generateClaudeMd` produces the CLAUDE.md template for new agents; `migrateClaudeMd` appends to existing agents' CLAUDE.md (idempotent, content-sniffed — never duplicates). No runtime behavior changes.
+- The blurb describes a DARK feature (sessionPool ships off) + points to real endpoints (`/pool`, `/pool/machines/:id`) that exist (Track B(2b)) and the Machines tab that exists (Track B(2c)). No dangling references: "deep mechanics" points at the Machines tab + the spec (the code-enforced Playbook deep-entry is a tracked enhancement, not asserted here).
+
+## Risk + mitigation
+- **Risk:** migration appends to existing CLAUDE.md repeatedly. **Mitigation:** idempotent content-sniff on the unique marker (skips if present) — verified by the existing migration-parity test (13 green).
+- **Risk:** blurb claims a capability that isn't live. **Mitigation:** the blurb explicitly states "Ships DARK behind `multiMachine.sessionPool.stage`" + "a single-machine agent is a no-op" — honest about the dark state.
+
+## Migration parity
+- This IS the migration-parity work for the Agent Awareness Standard: `generateClaudeMd` (init) + `migrateClaudeMd` (existing agents) both add the section, sniff-guarded. migration-parity.test.ts green.
+
+## Rollback
+- Remove the blurb from `generateClaudeMd` + the `migrateClaudeMd` block. Docs-only; nothing depends on it.
+
+## Tests
+- tests/unit/migration-parity.test.ts (13) — enforces generateClaudeMd↔migrateClaudeMd consistency; green with the additions. tsc clean.
+
+## Agent awareness
+- This change IS the agent-awareness deliverable. The code-enforced Playbook deep-trigger (`multiMachine-placement-deep` + SelfKnowledgeTree probe — the spec's Structure>Willpower enhancement for on-demand deep mechanics) is tracked as a follow-up (decision D9). <!-- tracked: session-pool-track-b -->

package/upgrades/side-effects/session-pool-track-b-nicknames.md

@@ -0,0 +1,35 @@
+# Side-Effects Review — Session Pool Track B (part 1): Machine Nicknames
+
+**Spec:** docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md §L2 (approved, review-convergence stamped)
+**Track:** B part 1 (machine nicknames — the user-facing handle). Ships DARK (no route/UI yet).
+**Files:** src/core/NicknameAssigner.ts (new), src/core/MachineIdentity.ts, src/core/types.ts
+
+## What changed
+1. **`NicknameAssigner.ts` (new, pure):** `assignNickname()` / `deriveBaseNickname()` / `isValidNickname()`. Derives a friendly, deterministic, collision-free nickname from a machine's hostname (title-cased) → platform-arch fallback → numeric suffix on collision. No I/O.
+2. **`MachineRegistryEntry.nickname?` (types.ts):** new OPTIONAL field (backward-compatible — registries written before §L2 simply have no nickname).
+3. **`MachineIdentityManager` (MachineIdentity.ts):**
+   - `registerMachine()` now auto-assigns a nickname when absent — IDEMPOTENT (a re-register keeps the existing nickname and preserves `pairedAt`; it spreads the existing entry so no field is lost). Collision set = every other machine's nickname.
+   - `updateNickname(machineId, nickname)` — validates format + pool-uniqueness (case-insensitive, excluding self); a collision THROWS (not silently suffixed). Metadata-only — never moves a session or touches lease/ownership.
+   - `resolveNickname(name)` — case-insensitive, trimmed, active-only lookup → machineId | null (consumed by L4 placement/transfer commands; never silently mis-routes).
+
+## Blast radius
+- `registerMachine` is called at identity creation + pairing + role changes. The change is additive (adds a nickname field) and idempotent. The entry-spread (`...(existing ?? {})`) preserves all prior fields incl. seamlessness fields (syncSequence, authoredUnderEpoch, etc.) — verified the existing 64 machine-identity tests pass unchanged, plus `pairedAt` is now preserved on re-register (previously reset — a latent improvement).
+- The nickname field is optional + unused by any runtime path yet (no route/UI until Track B part 2) — purely additive data.
+
+## Risk + mitigation
+- **Risk:** `registerMachine` re-register previously reset `pairedAt`/role to fresh; now it preserves `pairedAt` and existing fields. **Mitigation:** this is strictly more correct (pairing time shouldn't reset on a role change); covered by the idempotency test. Role/lastSeen still update.
+- **Risk:** nickname collisions across machines. **Mitigation:** auto-assign disambiguates with a numeric suffix; manual updateNickname rejects collisions outright. Tested both paths.
+
+## Migration parity
+- No config/migration needed — the `nickname` field is optional and auto-populated on the next `registerMachine` (which runs at boot via `ensureSelfRegistered`). Existing registries without nicknames get one assigned on the next registration; absent until then (handled as optional everywhere).
+
+## Rollback
+- Additive + dark. Remove the field + the three manager methods + NicknameAssigner.ts to revert; no data migration to undo (the field is optional).
+
+## Tests
+- tests/unit/NicknameAssigner.test.ts (9) — derivation, collision, validation, determinism.
+- tests/unit/machine-nickname.test.ts (9) — auto-assign + idempotency + disambiguation + update validation/uniqueness + resolve (case-insensitive, active-only, revoked-excluded).
+- 18 new green; existing 64 machine-identity tests unchanged; tsc clean.
+
+## Agent awareness
+- Deferred to Track B part 2 (the `GET /pool` route + Machines dashboard tab) where the nickname becomes user-visible — that's where the CLAUDE.md Tier-0 blurb + Playbook trigger land, per the spec's Agent Awareness section. <!-- tracked: session-pool-track-b -->

package/upgrades/side-effects/session-pool-track-b-pool-api.md

@@ -0,0 +1,36 @@
+# Side-Effects Review — Session Pool Track B (part 2b): /pool API + hardware
+
+**Spec:** docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md §L2 (approved, review-convergence stamped)
+**Track:** B part 2b (the /pool HTTP surface + hardware self-attestation). Ships DARK (registry unwired in server until 2c).
+**Files:** src/core/types.ts, src/core/MachineIdentity.ts, src/server/routes.ts
+
+## What changed
+1. **`MachineRegistryEntry.hardware?` (types.ts):** new optional field — a machine's self-attested static hardware (`MachineHardware`), synced to peers via the registry. Additive, backward-compatible.
+2. **`MachineIdentityManager.recordSelfHardware(machineId, hardware)` (MachineIdentity.ts):** writes the machine's own hardware into its registry entry. Caller-supplies the hardware (manager stays free of `os`/assembly concerns). Idempotent — only writes when changed (avoids registry churn/sync on every boot); no-op for an unknown id.
+3. **Routes (routes.ts):**
+   - `RouteContext.machinePoolRegistry?` — optional dep (null/absent ships dark; existing ctx builders unaffected).
+   - **`GET /pool`** — router holder (from `coordinator.getSyncStatus()`) + `MachineCapacity[]` (from the registry). Always 200; `enabled:false` + empty view when unwired.
+   - **`PATCH /pool/machines/:id`** — `{ nickname }` → `identityManager.updateNickname` (via `ctx.coordinator.managers.identityManager`). 200 ok / 400 malformed-or-collision / 404 unknown / 503 single-machine. Metadata-only — never moves a session or touches lease/ownership.
+
+## Blast radius
+- **Routes are additive + Bearer-auth-protected** (the global server auth middleware; verified the router itself carries no auth, matching every other instar route — the integration test mounts the router bare and exercises it). `GET /pool` reads only `coordinator.getSyncStatus()` (already exists) + the registry; `PATCH` calls the already-tested `updateNickname`.
+- **`machinePoolRegistry` is OPTIONAL** in RouteContext → no existing ctx construction site breaks (tsc clean across the repo).
+- **`recordSelfHardware`** only writes when hardware changed — no extra registry-sync churn on steady-state boots.
+- Production wiring (server instantiates the registry + feeds heartbeats + calls recordSelfHardware at boot) lands in part 2c alongside the Machines dashboard tab; until then `GET /pool` reports `enabled:false`.
+
+## Risk + mitigation
+- **Risk:** `PATCH` reaching through `ctx.coordinator.managers.identityManager`. **Mitigation:** guarded (503 when coordinator/idMgr absent — single-machine install); the underlying `updateNickname` enforces format + uniqueness (rejects collisions). Error mapping verified (400/404/503) by the integration test.
+- **Risk:** hardware field on a synced registry record. **Mitigation:** optional + self-attested + advisory-only (never authority); `recordSelfHardware` idempotency prevents sync churn.
+
+## Migration parity
+- The `hardware` field is optional + auto-populated by `recordSelfHardware` at boot (wired in 2c) — existing registries get it on the next boot; absent until then (handled as optional everywhere).
+
+## Rollback
+- Additive + dark + (registry) unwired. Remove the routes + the optional ctx field + the hardware field/method to revert; no data migration to undo.
+
+## Tests
+- tests/integration/pool-routes.test.ts (6) — the "feature alive" surface: GET /pool 200 with router holder + machine capacities (nickname/hardware/liveness/clock-status); PATCH renames + GET reflects; 400 malformed; 400 collision; 404 unknown; 400 non-string. (This is the Tier-2/3 surface deferred from Track A per decision D5.)
+- tests/unit/machine-nickname.test.ts — recordSelfHardware (stores; idempotent-when-unchanged; unknown-id no-op). 74 manager tests green; tsc clean.
+
+## Agent awareness
+- The CLAUDE.md Tier-0 blurb + Playbook trigger land with part 2c (the dashboard tab + server wiring — the moment the surface is user-reachable), per the spec's Agent Awareness section. <!-- tracked: session-pool-track-b -->

package/upgrades/side-effects/session-pool-track-b-registry.md

@@ -0,0 +1,31 @@
+# Side-Effects Review — Session Pool Track B (part 2a): Machine-Pool Registry
+
+**Spec:** docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md §L2 (approved, review-convergence stamped)
+**Track:** B part 2a (the live machine-pool registry foundation). Ships DARK (no route/UI/wiring yet).
+**Files:** src/core/MachinePoolRegistry.ts (new), src/core/types.ts
+
+## What changed
+1. **Types (types.ts):** `MachineHardware` (platform/arch/cpuModel/cpuCores/totalMemBytes/hostname/instarVersion), `ClockSkewStatus` (`ok` | `divergence-detected-once` | `suspect-clock-removed`), `MachineCapacity` (the live per-machine record — nickname + liveness + load + sessions + hardware + clockSkewStatus). All additive.
+2. **`MachinePoolRegistry.ts` (new):**
+   - `captureHardware()` — pure-ish `os` reads → MachineHardware.
+   - `clockSkewTransition()` — PURE FSM implementing the §L2 transition table (2-divergent-beats-out / 2-clean-beats-in); `isPlacementEligibleByClock()`.
+   - `MachinePoolRegistry` class — records heartbeat observations (stamps `routerReceivedAt` on the ROUTER's clock, runs the clock-skew FSM, fires `onClockQuarantine` on removal), and assembles `MachineCapacity[]` (the data behind GET /pool). Liveness keys on `routerReceivedAt`, NEVER the machine's self-reported time (§L2 clock-skew safety).
+
+## Blast radius
+- **None at runtime yet.** Nothing instantiates `MachinePoolRegistry` — it ships dark, exercised only by its unit tests. Wiring (server instantiation + heartbeat feed) and the `GET /pool` / `PATCH /pool/machines/:id` routes land in part 2b; the Machines dashboard tab in part 2c. The types are additive (optional fields, new interfaces).
+
+## Risk + mitigation
+- **Risk:** clock-skew FSM correctness (a wrong transition could wrongly quarantine or fail to quarantine). **Mitigation:** the FSM is a pure function with a test covering BOTH sides of every transition (1-divergent-then-clean forgiven; 2-divergent removed; 2-clean re-admitted; removed+divergent stays removed). 13 tests green.
+- **Risk:** liveness fooled by a fast machine clock. **Mitigation:** liveness computed from `routerReceivedAt` (router's own clock at heartbeat arrival), tested explicitly (a far-future self-reported time still reads online by router clock, then offline once the router clock passes the threshold).
+
+## Migration parity
+- No config/migration in 2a (no new persisted config; the registry is in-memory, rebuilt from heartbeats). The clock-skew tolerance / NTP-drift config knobs land with the wiring (2b) under the `multiMachine.sessionPool` block via the ConfigDefaults path.
+
+## Rollback
+- Additive + dark + unwired. Delete `MachinePoolRegistry.ts` + the three §L2 types to revert; nothing depends on them yet.
+
+## Tests
+- tests/unit/MachinePoolRegistry.test.ts (13) — captureHardware, the full clock-skew FSM (both sides of each boundary), liveness-by-router-clock, assembly (nickname/capabilities from registry + load from heartbeat), quarantine→re-admit flow, unseen-machine handling. tsc clean.
+
+## Agent awareness
+- Deferred to part 2b/2c (the route + dashboard tab — the first user-facing surface), where the CLAUDE.md Tier-0 blurb + Playbook trigger land per the spec's Agent Awareness section. <!-- tracked: session-pool-track-b -->

package/upgrades/side-effects/session-pool-track-b-wiring.md

@@ -0,0 +1,39 @@
+# Side-Effects Review — Session Pool Track B (part 2c-wiring): server wiring + config knobs
+
+**Spec:** docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md §L2 (approved, review-convergence stamped)
+**Track:** B part 2c (wiring) — instantiate the pool registry at server boot. Ships DARK.
+**Files:** src/server/AgentServer.ts, src/commands/server.ts, src/core/types.ts, src/config/ConfigDefaults.ts
+
+## What changed
+1. **AgentServer:** new optional `machinePoolRegistry?` constructor option → passed straight into the RouteContext (`machinePoolRegistry: options.machinePoolRegistry ?? null`). Pure passthrough, mirrors `coordinator`.
+2. **server.ts boot:** instantiate `MachinePoolRegistry` (guarded, best-effort try/catch so it can never break boot):
+   - `listMachines` reads `coordinator.managers.identityManager.getActiveMachines()` → {machineId, nickname, hardware}.
+   - `clockSkewToleranceMs` / `failoverThresholdMs` from config.
+   - `recordSelfHardware(self, captureHardware())` once at boot (idempotent — only writes when changed).
+   - A 30s **unref'd** interval re-records a self-heartbeat (so this machine shows online with live load) and feeds peer heartbeats from `MachineHeartbeat.listAll()` (peer liveness + the clock-skew FSM). Passed to AgentServer.
+3. **Config knobs (types.ts + ConfigDefaults):** `SessionPoolConfig` gains `clockSkewToleranceMs` (300000), `maxExpectedNtpDriftMs` (250), `machineRecordEvictionMs` (86400000); added to the dark `multiMachine.sessionPool` ConfigDefaults block → migration parity (existing agents get them on update).
+
+## Blast radius
+- **Boot:** the registry block is fully wrapped in try/catch + every sub-step guarded; a failure logs `[pool] registry not wired` and continues — it cannot break server startup. The interval is `unref()`'d so it never holds the process open.
+- **RouteContext:** `machinePoolRegistry` is optional → no other ctx builder affected. tsc clean across the repo.
+- **Cost:** one registry instance + a 30s timer reading in-memory heartbeat records + `os.loadavg()` — negligible. `recordSelfHardware` writes the registry only when hardware changed (no steady-state sync churn).
+- **Dark:** the registry is always instantiated for observability (GET /pool), but the session-pool BEHAVIOR (placement/transfer) stays gated by `sessionPool.stage` (dark). This wiring only powers the read-only /pool view + Machines tab.
+
+## Risk + mitigation
+- **Risk:** `coordinator.managers.identityManager` access at boot. **Mitigation:** guarded (`coordinator?.managers?.identityManager`); if absent (single-machine without a coordinator) the registry simply isn't wired and GET /pool reports `enabled:false`.
+- **Risk:** the self-heartbeat interval drifting/erroring. **Mitigation:** wrapped in try/catch (best-effort); unref'd; 30s cadence.
+- **Risk:** clock-skew tolerance vs NTP drift misconfiguration. **Mitigation:** defaults honor `tolerance ≥ 2× drift`; asserted in the ConfigDefaults test (the §L2 startup invariant).
+
+## Migration parity
+- The three clock knobs are in the `multiMachine.sessionPool` ConfigDefaults block → auto-applied to existing agents via `applyDefaults` (existence-checked, idempotent). Asserted in ConfigDefaults.test.ts.
+
+## Rollback
+- Remove the boot block + the AgentServer option/ctx field to revert; the config knobs are inert defaults. All dark.
+
+## Tests
+- tests/integration/pool-routes.test.ts (6, prior) covers the route+registry behavior the wiring exposes.
+- ConfigDefaults.test.ts asserts the clock knobs + the `tolerance ≥ 2× drift` invariant. 27 green; tsc clean.
+- The full-boot "GET /pool returns enabled:true on a live server" assertion rides the Track-H real-hardware E2E (booting real servers); the wiring is otherwise simple guarded passthrough. <!-- tracked: session-pool-track-b -->
+
+## Agent awareness
+- The CLAUDE.md Tier-0 blurb + Playbook trigger land with the Machines dashboard tab (next, the user-reachable surface), per the spec's Agent Awareness section. <!-- tracked: session-pool-track-b -->

package/upgrades/side-effects/session-pool-track-c-dispatcher.md

@@ -0,0 +1,24 @@
+# Side-Effects Review — Session Pool Track C(2): MeshRpc dispatcher (L0)
+
+**Spec:** docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md §L0 (approved). **Track:** C part 2 (the receive side). Ships DARK (no HTTP route wired yet — that's the next step).
+**Files:** src/core/MeshRpc.ts (added MeshRpcDispatcher)
+
+## What changed
+- **`MeshRpcDispatcher`** (added to MeshRpc.ts): the transport-agnostic receive side. `dispatch(env)` runs the two gates (verify THEN rbac via `acceptEnvelope`), records the nonce ONLY on full accept (a rejected command never burns a nonce — anti-DoS), audits rejections via an injected `onReject` (SecurityLog), then routes to a registered per-command handler. Returns `{ok, result}` or `{ok:false, reason, status}` with an HTTP status mapping (auth → 401/403, freshness → 409, unimplemented handler → 501). Handlers, verify/rbac deps, nonce-record, and the audit sink are all injected.
+- **Layering (not a stub):** the dispatcher carries the command set; the MUTATION handlers (place/claim/release/transfer) are registered by their owning layers (L3/L4/L5 — Tracks D/E/F). A verified+authorized command with no handler yet returns `no-handler` (501) — the honest "this layer isn't wired yet" state, not a silent stub. Read-class handlers (capacity-report/session-status) can be backed by the L2 registry now.
+
+## Blast radius
+- **None at runtime yet** — nothing constructs a `MeshRpcDispatcher`. Additive to the (already-dark) MeshRpc.ts. The HTTP route (`POST /mesh/rpc`) + production wiring (Ed25519 verify, NonceStore, router-lease read, handler registry) land in the next step.
+
+## Risk + mitigation
+- **Risk:** a rejected command consuming a nonce (replay-DoS) or an accepted one not recording (replay hole). **Mitigation:** nonce recorded EXACTLY on accept (after both gates), before handler dispatch — tested both ways (accepted place burns the nonce; rejected place does NOT; no-handler still burns it because it WAS authorized).
+- **Risk:** wrong status codes leaking auth info. **Mitigation:** explicit reason→status map, tested (401 wrong-recipient, 403 not-router, 409 replayed-nonce, 501 no-handler).
+
+## Rollback
+- Additive + dark + unwired. Remove `MeshRpcDispatcher` to revert.
+
+## Tests
+- tests/unit/MeshRpc.test.ts now 21 (15 prior + 6 dispatcher): accept→record→dispatch; reject-unauthorized audits + no-nonce-burn (403); wrong-recipient (401); no-handler burns nonce (501); read-class routes; replayed-nonce (409). tsc clean.
+
+## Agent awareness
+- Internal m2m infra; agent awareness covered by Track B's CLAUDE.md blurb. <!-- tracked: session-pool-track-c -->

package/upgrades/side-effects/session-pool-track-c-meshrpc.md

@@ -0,0 +1,35 @@
+# Side-Effects Review — Session Pool Track C(1): MeshRpc envelope + RBAC (L0)
+
+**Spec:** docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md §L0 (approved, review-convergence stamped)
+**Track:** C part 1 (the signed m2m command layer — pure core). Ships DARK (no HTTP route wired yet).
+**Files:** src/core/MeshRpc.ts (new)
+
+## What changed
+1. **`MeshRpc.ts` (new, pure):** the §L0 command layer's correctness core — no I/O.
+   - `MeshCommand` (place/claim/release/transfer/capacity-report/session-status/secret-share) + `MeshEnvelope` ({sender, recipient, command, epoch, nonce, timestamp, signature}).
+   - `canonicalizeEnvelope` — recipient INCLUDED in the signed bytes (recipient-binding).
+   - `signEnvelope` — build + Ed25519-sign (crypto injected).
+   - `verifyEnvelope` — the 5-step receipt check IN ORDER: (1) recipient===self, (2) signature valid for sender's registered key, (3) sender is a registered peer, (4) nonce unseen, (5) timestamp within tolerance. Returns a typed reason; does NOT record the nonce (caller records only on full accept, so a rejected command never burns a nonce).
+   - `checkCommandRBAC` — the per-command role gate (place/transfer → router; claim → placement-target or failover-router; release → owner or failover-router; reports/secret-share → any peer).
+   - `acceptEnvelope` — verify THEN rbac (convenience).
+   - Crypto (sign/verify), nonce store, peer registry, and router/ownership reads are all INJECTED seams (like FencedLease's LeaseCrypto).
+
+## Blast radius
+- **None at runtime yet.** Nothing imports `MeshRpc` — it ships dark, exercised only by its unit tests. The HTTP transport (`POST /mesh/rpc` + a dispatcher adapting machineAuth's Ed25519 sign/verify + NonceStore + the router/ownership reads) and production wiring land in part 2. Pure additive module.
+
+## Risk + mitigation
+- **Risk:** an authorization hole (the whole point of §L0). **Mitigation:** two independent gates (verify = who; RBAC = may), both unit-tested on BOTH sides of every boundary — incl. the spec's headline cases: a command signed for A replayed verbatim to C → `wrong-recipient` (caught at step 1, before signature); a non-router issuing place/claim → `not-router`/`claim-unauthorized`; a stale-timestamp + a reused-nonce → rejected. 15 tests.
+- **Risk:** recipient-binding bypass. **Mitigation:** the recipient is part of the canonical signed bytes AND checked first; a verbatim replay to a different machine fails the recipient check before the signature is even evaluated (test: "checks recipient BEFORE signature").
+- **Risk:** a rejected command consuming a nonce (DoS). **Mitigation:** verifyEnvelope is pure (reads `seenNonce`, never records); the caller records the nonce only on full acceptance.
+
+## Migration parity
+- None in part 1 (pure module, unwired, no config). The `meshRpcClockToleranceMs` config knob + any route config land with the HTTP wiring (part 2) via the `multiMachine.sessionPool` ConfigDefaults path.
+
+## Rollback
+- Additive + dark + unwired. Delete `MeshRpc.ts` to revert; nothing depends on it.
+
+## Tests
+- tests/unit/MeshRpc.test.ts (15) — recipient-binding in the canonical bytes; verify (happy + wrong-recipient replay + bad-sig + unknown-sender + replayed-nonce + stale-timestamp + recipient-before-sig ordering); RBAC both sides for place/transfer/claim/release + read-class; acceptEnvelope verify-then-rbac ordering. tsc clean.
+
+## Agent awareness
+- No user-facing surface in part 1. The m2m backbone is internal infra; agent awareness for the session pool is covered by Track B's CLAUDE.md blurb. <!-- tracked: session-pool-track-c -->

package/upgrades/side-effects/session-pool-track-c-route-wiring.md

@@ -0,0 +1,31 @@
+# Side-Effects Review — Session Pool Track C(3): /mesh/rpc route + boot wiring (L0)
+
+**Spec:** docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md §L0 (approved). **Track:** C part 3 — completes Track C. Ships DARK (transport live; mutation handlers come from D/E/F).
+**Files:** src/server/routes.ts, src/server/AgentServer.ts, src/commands/server.ts, src/core/types.ts, src/config/ConfigDefaults.ts
+
+## What changed
+1. **`POST /mesh/rpc` route (routes.ts):** parses a signed MeshEnvelope → `ctx.meshRpcDispatcher.dispatch` → maps `{ok,result}` or `{ok:false,reason,status}` (401/403/409/501). 503 when unwired. Auth is the ENVELOPE's own Ed25519 sig (dispatcher), independent of the Bearer middleware. `RouteContext.meshRpcDispatcher?` (optional).
+2. **AgentServer:** optional `meshRpcDispatcher` option → RouteContext passthrough (mirrors machinePoolRegistry).
+3. **server.ts boot (guarded):** constructs a `MeshRpcDispatcher` when a machine identity exists — verify adapter (`getSigningPublicKeyPem(sender)` + Ed25519 `verify`), `isRegisteredPeer` = `isMachineActive`, an age-pruned in-memory seen-nonce map, `routerHolder` = `coordinator.getSyncStatus().leaseHolder`, `ownerOf`/`placementTargetOf` = null (wired by D/E), and LIVE read-class handlers (`capacity-report` → registry capacities, `session-status` → self capacity). Mutation handlers register from D/E/F → no-handler (501) until then.
+4. **Config:** `meshRpcClockToleranceMs` (30000) added to SessionPoolConfig + ConfigDefaults (migration parity).
+
+## Blast radius
+- `/mesh/rpc` is a NEW route guarded by the envelope's own Ed25519 signature + the dispatcher's verify/RBAC (independent of Bearer). Until a machine identity exists it's unwired → 503 (single-machine no-op).
+- Boot block fully try/catch-guarded (`[mesh-rpc] dispatcher not wired` on failure) — cannot break startup. The seen-nonce map is bounded (age-pruned at >5000 entries).
+- `ownerOf`/`placementTargetOf` are null until L3/L4 → `claim`/`release` correctly reject (`claim-unauthorized`) — honest (no ownership data yet), not a bug.
+
+## Risk + mitigation
+- **Risk:** the verify adapter mis-binding a key. **Mitigation:** reuses the exact `getSigningPublicKeyPem` + `verify` path machineAuthMiddleware uses for peer signatures; proven end-to-end with REAL Ed25519 keys over HTTP in the integration test.
+- **Risk:** in-memory nonce set lost on restart (replay window across restart). **Mitigation:** acceptable for the dark read-class transport + the 30s timestamp tolerance bounds any replay window; a durable NonceStore-backed variant is a noted refinement (NonceStore.validate is sequence-oriented, doesn't fit the nonce-only model cleanly).
+
+## Migration parity
+- `meshRpcClockToleranceMs` in the `multiMachine.sessionPool` ConfigDefaults block → existing agents get it on update.
+
+## Rollback
+- Remove the route + AgentServer option + boot block to revert. Dark + guarded.
+
+## Tests
+- tests/integration/mesh-rpc-route.test.ts (6, feature-alive): a REAL Ed25519-signed capacity-report → 200; wrong-recipient replay → 401; non-router place → 403; replayed nonce → 200 then 409; forged sig → 401; malformed body → 400. Plus MeshRpc unit (21) + ConfigDefaults (27). tsc clean.
+
+## Agent awareness
+- Internal m2m infra; covered by Track B's CLAUDE.md blurb. <!-- tracked: session-pool-track-c -->

package/upgrades/side-effects/session-pool-track-d-ownership-fsm.md

@@ -0,0 +1,31 @@
+# Side-Effects Review — Session Pool Track D(1): SessionOwnership FSM (L3)
+
+**Spec:** docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md §L3 (approved). **Track:** D part 1 (the per-session ownership state machine — pure core). Ships DARK (no CAS store/registry wired yet).
+**Files:** src/core/SessionOwnership.ts (new)
+
+## What changed
+- **`SessionOwnership.ts` (new, pure):** the §L3 ownership correctness core — no I/O.
+  - `SessionOwnershipRecord` ({sessionKey, ownerMachineId, ownershipEpoch, status: placing|active|transferring|released, transferTo?, nonce, timestamp, updatedAt, signature?}).
+  - `applyOwnershipAction(current, action, ctx)` — the pure transition: place (only null/released → no stealing a live session), claim (placing→active by the placed-owner, OR transferring→active by the named target — out-of-sequence/wrong-machine rejected), transfer (active→transferring), release (owner→released). Every transition advances the epoch by +1 (the CAS candidate).
+  - `mayRun(record, machineId, epoch)` — the run-fence: a worker runs ONLY while it observes itself `active` owner at the current epoch (no double-run; stale epoch grants nothing).
+  - `mayEmit(record, machineId, {now, transferringStartedAt, cutoffMs})` — the output-exclusion contract: the draining source emits tail-only within the cutoff window then nothing; the target holds until the cutoff elapses (disjoint windows); the steady-state active owner emits freely.
+  - `ownershipNonceKey(sessionKey, sender, epoch, nonce)` — per-session-scoped nonce key (the same nonce in two sessions does not collide; replay within a session is caught).
+
+## Blast radius
+- **None at runtime yet.** Nothing imports SessionOwnership — it ships dark, exercised only by its unit tests. The CAS store (per-session git single-ref fast-forward push, reusing the §L−1/GitLeaseStore discipline), the distributed registry, and the MeshRpc claim/release handlers (which wire `ownerOf`/`placementTargetOf` into the dispatcher) land in part 2. Pure additive module.
+
+## Risk + mitigation
+- **Risk:** a transition hole that allows two active owners or a no-owner gap (the core §L3 invariant). **Mitigation:** the FSM is pure + tested through the full transfer sequence (active(S)→transferring→active(T)): asserted no state has two active owners at the top epoch and `transferring` always still names S as the draining owner (no gap); out-of-sequence claim (T before transferring) → `claim-out-of-sequence`; wrong-machine claim → `claim-wrong-machine`; place won't steal a live session. 11 tests.
+- **Risk:** interleaved/double user output during the S→T overlap. **Mitigation:** the output-exclusion is a separate fence from the run-fence, tested (source tail-only-within-cutoff, target-holds-until-cutoff, disjoint windows).
+
+## Migration parity
+- None in part 1 (pure module, unwired, no config). The CAS retry/backoff + clock-tolerance config knobs land with the store (part 2) via the `multiMachine.sessionPool` ConfigDefaults path.
+
+## Rollback
+- Additive + dark + unwired. Delete SessionOwnership.ts to revert.
+
+## Tests
+- tests/unit/SessionOwnership.test.ts (11): place→claim→active; place-won't-steal-live; the transfer sequence (one-owner-throughout, claim-before-release); out-of-sequence + wrong-machine claim rejected; transfer-requires-active; release-requires-owner; run-fence (no two active owners, stale epoch fenced); output-exclusion (source tail-only, target holds, steady-state free); per-session nonce isolation. tsc clean.
+
+## Agent awareness
+- Internal ownership layer; session-pool agent awareness covered by Track B's CLAUDE.md blurb. <!-- tracked: session-pool-track-d -->

package/upgrades/side-effects/session-pool-track-d-registry.md

@@ -0,0 +1,27 @@
+# Side-Effects Review — Session Pool Track D(2): SessionOwnershipRegistry (L3)
+
+**Spec:** docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md §L3 (approved). **Track:** D part 2 (the per-session CAS registry). Ships DARK (no server wiring yet).
+**Files:** src/core/SessionOwnershipRegistry.ts (new)
+
+## What changed
+- **`SessionOwnershipRegistry.ts` (new):** the distributed per-session ownership registry. `cas(action, ctx)` runs the §L3 FSM transition (SessionOwnership.applyOwnershipAction), the per-session replay check (ownershipNonceKey), then the durable fast-forward CAS via an injected `store.casWrite` (the git single-ref push, mirroring GitLeaseStore). On a lost CAS (peer advanced first) → `cas-lost` + observed record; the nonce is recorded ONLY on a landed CAS. `ownerOf`/`placementTargetOf` (the §L4 RBAC reads), casConflicts/casRetryExhaustions metrics, and `ownershipRetryDelayMs` (lowest-machineId-first ordering HINT — never the arbiter; the remote ref-update decides). Store + nonce store are injected seams.
+
+## Blast radius
+- **None at runtime yet** — nothing constructs the registry. The server wiring (instantiate with a git-backed store + the per-session NonceStore + feed `ownerOf`/`placementTargetOf` into the MeshRpc dispatcher RBAC + register the `claim`/`release` handlers) lands in part 3. Pure additive module; reuses the proven GitLeaseStore CAS discipline per-session.
+
+## Risk + mitigation
+- **Risk:** split ownership under cross-machine contention. **Mitigation:** the CAS is the §L−1 single-ref fast-forward — exactly one candidate fast-forwards from epoch e; the loser is rejected non-fast-forward and observes the winner's e+1. Tested with a FakeStore that simulates a peer landing mid-flight: the loser gets `cas-lost` + observed the winner's record (NOT chosen by machineId).
+- **Risk:** replay re-opening a window. **Mitigation:** per-session nonce key {sessionKey,sender,epoch} (tested: same nonce across two sessions both land; replay within a session caught); nonce recorded only on a landed CAS.
+- **Risk:** retry storms. **Mitigation:** `ownershipRetryDelayMs` bounded exponential jitter; lowest-machineId-first is an ordering hint only.
+
+## Migration parity
+- None in part 2 (pure module, unwired). The CAS retry/backoff + clock-tolerance config knobs land with the server wiring (part 3) via the `multiMachine.sessionPool` ConfigDefaults path.
+
+## Rollback
+- Additive + dark + unwired. Delete SessionOwnershipRegistry.ts to revert.
+
+## Tests
+- tests/unit/SessionOwnershipRegistry.test.ts (6): place→claim lands + ownerOf; two-machine CAS at epoch+1 → one wins via ref-update + loser cas-lost + observed-the-winner; per-session nonce isolation (same nonce, two sessions, both land); FSM rejection propagated (out-of-sequence claim); retry-delay ordering hint bounded. tsc clean.
+
+## Agent awareness
+- Internal ownership layer; covered by Track B's CLAUDE.md blurb. <!-- tracked: session-pool-track-d -->

package/upgrades/side-effects/session-pool-track-d-wiring.md

@@ -0,0 +1,30 @@
+# Side-Effects Review — Session Pool Track D(3): ownership wiring + MeshRpc handlers (L3) — Track D complete
+
+**Spec:** docs/specs/MULTI-MACHINE-SESSION-POOL-SPEC.md §L3 (approved). **Track:** D part 3 — completes Track D. Ships DARK.
+**Files:** src/core/MeshRpc.ts, src/core/SessionOwnershipRegistry.ts, src/commands/server.ts, src/server/routes.ts, src/server/AgentServer.ts
+
+## What changed
+1. **MeshRpc:** `MeshCommandHandler` now receives the full envelope (so handlers can use `env.nonce` for the per-session ownership CAS); dispatcher passes it.
+2. **SessionOwnershipRegistry:** added `InMemorySessionOwnershipStore` (fast-forward CAS, single-machine-correct; the cross-machine git-backed store is the Track-H swap — the registry/FSM/CAS are store-agnostic).
+3. **server.ts boot:** constructs the `SessionOwnershipRegistry` (in-memory store + a per-session nonce set), feeds `ownerOf`/`placementTargetOf` into the MeshRpc dispatcher RBAC (replacing the prior null stubs), and registers the place/claim/transfer/release MeshRpc handlers → the registry CAS. Guarded; dark.
+4. **RouteContext + AgentServer:** `sessionOwnershipRegistry?` passthrough (for L4 placement + observability).
+
+## Blast radius
+- All within the existing guarded MeshRpc boot block (dark; built only when a machine identity exists). The mutation handlers route to the registry CAS; on a single machine the in-memory store is correct (no cross-machine contention). `/mesh/rpc` place/claim/transfer/release are now live (RBAC-gated); read-class unchanged.
+- `MeshCommandHandler` signature change is additive (handlers may ignore the new `env` arg); the dispatcher + its tests updated.
+
+## Risk + mitigation
+- **Risk:** an unauthorized claim/place mutating ownership. **Mitigation:** TWO gates — MeshRpc RBAC (place→router, claim→placement-target) refuses at the door (403), THEN the registry CAS (FSM + fast-forward) is the correctness fence. Proven end-to-end: integration test shows non-router place → 403 (no ownership written), non-target claim → 403 (ownership unchanged), router-place→target-claim → ownerOf reflects.
+- **Risk:** single-machine in-memory store ≠ cross-machine durability. **Mitigation:** correct for single-machine + dark v0.1; the git-backed cross-machine store is a tracked Track-H-proof swap (store is an injected seam) — see decision D10.
+
+## Migration parity
+- No new config (meshRpcClockToleranceMs already in ConfigDefaults from Track C). The ownership store is in-memory (no persisted config).
+
+## Rollback
+- Remove the registry construction + handler wiring from the boot block + the ctx field to revert. Dark + guarded.
+
+## Tests
+- tests/integration/session-ownership-mesh.test.ts (3, feature-alive): router place→target claim→ownerOf reflects; non-router place → 403 not-router (no write); non-target claim → 403 claim-unauthorized (ownership unchanged) — real Ed25519 over HTTP. Plus SessionOwnership (11) + SessionOwnershipRegistry (6) + MeshRpc (21). tsc clean.
+
+## Agent awareness
+- Internal ownership/mesh layer; covered by Track B's CLAUDE.md blurb. <!-- tracked: session-pool-track-d -->

package/upgrades/side-effects/session-pool-track-e-boot-wiring.md

@@ -0,0 +1,20 @@
+# Side effects — Track E part 3: deliverMessage boot wiring + factory + config tunables (§L4)
+
+## What this adds
+The owner-side receive wiring for the §L4 deliverMessage command, plus the §L4 router/placement config tunables. Ships DARK — the receive handler is registered on the boot mesh dispatcher (already gated by machine-identity presence; inert on a single-machine agent), and the config block stays `enabled:false, stage:dark`.
+
+- `src/core/DeliverMessageHandler.ts` (NEW) — `createDeliverMessageHandler(deps)`: the single shared factory for the owner-side receive contract (stale-ownership fence → idempotent durable-receipt-before-processing → queued/duplicate ACK). Imported by BOTH `server.ts` boot AND the tests, so the production handler and the tested handler cannot drift (Structure > Willpower).
+- `src/commands/server.ts` — the boot mesh dispatcher now registers `deliverMessage` via the factory, wired to the real `SessionOwnershipRegistry` (owner epoch) + the real `MessageProcessingLedger` (idempotency key = messageId; SQLite-backed durable receipt), with an in-memory fallback set when the ledger is unavailable.
+- `src/config/ConfigDefaults.ts` + `src/core/types.ts` — added the §L4 tunables to the dark `sessionPool` block: `deliverMessageTimeoutMs` (5000), `deliverMessageMaxRetries` (3), `placementHysteresisDelta` (0.15), `ownershipCasMaxRetries` (5). `applyDefaults` is add-missing-only + recursive, so existing agents backfill ONLY the new sub-fields on update without clobbering an operator's tuned values (migration parity).
+
+## Risk / blast radius
+None at runtime for a single-machine agent: the deliverMessage handler is only reachable through `/mesh/rpc`, which requires a registered peer machine + a router-holder RBAC check (router-only). The config additions are inert (enabled:false). No live-ingress path is touched — live-ingress interception + the outbound mesh client are Track-H's stage-gated activation (decision D11), not a deferral.
+
+## Tests
+- `tests/unit/DeliverMessageHandler.test.ts` — 5 tests: queued (first + onAccepted-once), duplicate (idempotent, no re-process), stale-ownership, not-stale-on-match/lead, null-epoch.
+- `tests/e2e/session-pool-delivermessage-e2e.test.ts` — 4 "feature alive" tests over the PRODUCTION factory + real MeshRpcDispatcher + real /mesh/rpc HTTP route + real SQLite MessageProcessingLedger + real SessionOwnershipRegistry: endpoint alive (200 + queued), redelivery → duplicate (ledger dedupe), stale-ownership after the owner epoch advances, non-router → 403.
+- `tests/unit/ConfigDefaults.test.ts` — +1: the Track-E tunables backfill into a partial sessionPool block (add-missing, operator stage preserved).
+
+## Agent awareness / migration parity
+- Agent awareness: already delivered in Track B's Tier-0 CLAUDE.md blurb (template + migrator) — it documents the "run this on / move this to <nickname>" triggers; Track E's recognizer makes them fire. No new CLAUDE.md change.
+- Migration parity: config sub-fields auto-backfill via `applyDefaults` (asserted by the new test). The deliverMessage receive handler is core boot code (no agent-installed-file change).

package/upgrades/side-effects/session-pool-track-e-placement-core.md

@@ -0,0 +1,17 @@
+# Side effects — Track E part 1: Placement core + nickname recognizer (§L4)
+
+## What this adds
+Two PURE, side-effect-free decision components for the Session Router (Multi-Machine Session Pool §L4). Both ship DARK (no wiring into the live router yet — that lands in Track E part 2 with the dispatch path + integration test). No runtime behavior changes for any deployed agent.
+
+- `src/core/PlacementExecutor.ts` — the single canonical placement component. `decide(PlacementRequest): PlacementDecision` is pure and deterministic; the caller performs the CAS + side effects. Placement policy is structured DATA (`PlacementPolicy`), schema-validated at construction via `validatePlacementPolicy()` (a malformed policy throws — the router refuses to act rather than silently defaulting). Ordering is `hard-constraint → pin → sticky → least-loaded`. Hard pin / unmet capability with no capable machine returns `outcome: 'queued'` + an `escalationReason` — it NEVER silently mis-places. `validateTopicPlacement()` validates per-topic metadata on read; corrupt metadata returns `outcome: 'placement-blocked'`.
+- `src/core/NicknameCommand.ts` — `recognizeNicknameCommand(text, knownNicknames)`: a conservative, deterministic recognizer for the user's "move/run this on <nickname>" requests (the headline test-as-self swap). It only matches when an explicit relocation verb AND a known nickname are both present, so a bare machine mention ("the mini is fast") never triggers a transfer. Resolves the longest matching nickname; classifies `pin` vs `transfer` intent.
+
+## Risk / blast radius
+None at runtime — neither module is imported by any boot path yet. Pure functions + new test files only. No config, no migration, no API surface in this commit.
+
+## Tests
+- `tests/unit/PlacementExecutor.test.ts` — 15 tests: least-loaded, offline/clock-quarantine exclusion, hard-pin placed/queued, soft-preference degrade, capability filter + escalation, sticky + hysteresis + rebalance-bypass, corrupt-metadata block, no-online-machine queue, decide() purity, and policy-validation rejection on every malformed field.
+- `tests/unit/NicknameCommand.test.ts` — 11 tests: verb coverage, run-on/pin intents, longest-nickname resolution, case-insensitivity, and the critical negatives (bare mention, no preposition, unknown target, empty input).
+
+## Follow-ups (tracked in this same Track E)
+Part 2 wires PlacementExecutor + NicknameCommand into the router dispatch path (owned→forward over MeshRpc, unowned→decide→CAS-claim→spawn) with the deliverMessage contract and a Tier-2 integration test.