instar 1.3.92 → 1.3.93

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.92",
+  "version": "1.3.93",
   "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-05-29T16:08:56.086Z",
-  "instarVersion": "1.3.92",
+  "generatedAt": "2026-05-29T16:44:14.621Z",
+  "instarVersion": "1.3.93",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.92.md

@@ -1,63 +1,27 @@
-# Instar Upgrade Guide — NEXT
+# Upgrade Guide — vNEXT
 
-> 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).
+<!-- bump: patch -->
 
 ## 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).
+The Multi-Machine Session Pool gains its activation wiring (still DARK): the SessionRouter
+is now constructed at boot and consulted on the inbound message path — but ONLY when the
+rollout stage is advanced past 'dark'. A single-machine, un-activated agent behaves exactly
+as before (the interception is gated off on three independent conditions and fails safe to
+local dispatch).
 
 ## 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.
+Nothing changes yet — this is the plumbing that lets the session pool actually move
+conversations between machines once it's staged on. It stays off until explicitly activated.
 
 ## 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.
+| Area | Capability |
+| --- | --- |
+| Multi-machine | The inbound dispatch can route a topic's message to the machine that owns the session (gated; dark by default). |
 
 ## 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
+- `tests/unit/session-pool-activation-wiring.test.ts` pins the safety invariants: gated on a
+  non-dark stage, fail-safe to local dispatch, real-deps construction, module-ref sharing.

package/upgrades/1.3.93.md

@@ -0,0 +1,28 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+The Multi-Machine Session Pool gains its activation wiring (still DARK): the SessionRouter
+is constructed at boot and consulted on the inbound message path, and a forwarded message
+now resumes the session on the owner machine — but ALL of this is gated on the rollout stage
+being advanced past 'dark'. A single-machine, un-activated agent behaves exactly as before:
+the interception is gated off on three independent conditions (no router without machine
+identity, stage defaults dark, fail-safe to local dispatch).
+
+## What to Tell Your User
+
+Nothing changes yet — this is the plumbing that lets the session pool actually move
+conversations between machines once it's staged on. It stays off until explicitly activated.
+
+## Summary of New Capabilities
+
+| Area | Capability |
+| --- | --- |
+| Multi-machine | Inbound dispatch can route a topic's message to the machine that owns the session, and the owner resumes it (gated; dark by default). |
+
+## Evidence
+
+- `tests/unit/session-pool-activation-wiring.test.ts` pins the safety invariants: gated on a
+  non-dark stage, fail-safe to local dispatch, real-deps construction, owner-side resume bridge.

package/upgrades/side-effects/session-pool-activation-wiring.md

@@ -0,0 +1,22 @@
+# Side effects — Session Pool activation wiring (§L4 live-ingress, dark)
+
+## What this adds (task A of the activation)
+Wires the SessionRouter into the live boot + the inbound message-dispatch path, GATED so it is inert until the rollout stage advances past 'dark'.
+
+- `src/commands/server.ts`:
+  - Module-level refs `_sessionRouter` + `_sessionPoolStage()` (the idiomatic instar pattern — the inbound handler in `wireTelegramRouting` is defined above `startServer`, so the router constructed in startServer's mesh block is shared via a module ref, like `_orphanReaper`/`_topicResumeMap`).
+  - **Construction** (mesh block, when a machine identity exists): `new SessionRouter({...})` wired to the real `MachinePoolRegistry` (machineRegistry), `SessionOwnershipRegistry` (resolveOwnership + casClaimOwnership), `PlacementExecutor`, and an outbound `MeshRpcClient` (deliverMessage/spawnOnMachine to peers via `lastKnownUrl`). `_sessionPoolStage()` reads the live `multiMachine.sessionPool.{enabled,stage}` (defaults 'dark').
+  - **Interception** (inbound `onTopicMessage`, after target-session resolution): when `_sessionRouter && _sessionPoolStage() !== 'dark'`, consult `route()`; a `forwarded`/`duplicate` outcome short-circuits (the owner machine handles it); everything else falls through to the existing local dispatch. Wrapped in try/catch → falls back to local on any error.
+
+## Risk / blast radius
+**None in production.** The gate defaults to dark on three independent conditions: `_sessionRouter` is null without machine identity; `_sessionPoolStage()` returns 'dark' unless `enabled && stage` set (ConfigDefaults ships enabled:false/stage:dark); and the interception fails safe to local dispatch. So a single-machine, un-activated agent is byte-identical to today. The live-transfer behavior is gated by the staged rollout (StageAdvancer + E2E records).
+
+## Tests
+- `tests/unit/session-pool-activation-wiring.test.ts` — 4 wiring-integrity tests pinning the safety invariants: gated on non-dark stage (default-dark → inert), fail-safe try/catch → local, real-deps construction (registry/ownership/placement + MeshRpcClient), module-ref sharing. Guards against a regression that removes the gate (which would activate cross-machine routing unconditionally).
+- SessionRouter behavior itself is covered by its 17 unit + 3 integration tests (#506).
+
+## Remaining (the hardware operation — B/C/D)
+Deploy to laptop + bring up the mini as machine #2; advance dark→shadow→live-transfer (each E2E-gated); test-as-self nickname-swap proof. The owner-side deliverMessage→local-spawn bridge (so a forwarded message actually spawns on the owner) is the final piece, validated on the 2-machine setup.
+
+## Addendum — owner-side bridge (task A.2)
+`createDeliverMessageHandler` now takes an `onAccepted` hook wired (in the mesh block) to `spawnSessionForTopic`: a FIRST-seen forwarded `deliverMessage` spawns/resumes the local session for the topic so the conversation continues on the OWNER machine — the receive-side of the §L4 handoff. Gated on `_sessionPoolStage() !== 'dark'` + `telegram` present; fire-and-forget (the durable receipt is ACKed before this runs); fails safe (logs, never throws into the dispatcher). Inert until live-transfer (a deliverMessage only arrives from a router peer). This makes the activation code-complete: outbound forward (router) + receive+ACK (handler) + owner-side resume (bridge). Remaining is purely the 2-machine hardware proof.