instar 1.3.101 → 1.3.102

package/dist/core/PeerPresencePuller.d.ts

@@ -0,0 +1,71 @@
+/**
+ * PeerPresencePuller (Multi-Machine Session Pool — HTTP presence transport).
+ *
+ * The pool registry's notion of which peer machines are ONLINE was originally
+ * fed only by the git-synced MachineHeartbeat: each machine writes its heartbeat
+ * into the shared agent repo, peers pull it, and recency ⇒ online. That breaks
+ * for a *credential-less standby* — a machine paired into the mesh over HTTP but
+ * WITHOUT push access to the shared repo (e.g. a second machine gh-authed to a
+ * different account). Its heartbeat never reaches the router, so the router
+ * marks it offline and the placement engine refuses to transfer to it, even
+ * though the two machines can reach each other perfectly over their tunnels.
+ *
+ * This puller closes that gap with a pull-based HTTP presence channel: on a
+ * cadence, ask each reachable peer for its self-capacity over the signed
+ * /mesh/rpc `session-status` command (a read-class command any registered peer
+ * may issue) and record the answer into the local pool registry. A peer that
+ * answers is, by definition, reachable + alive — so it goes online without ever
+ * touching git. Symmetric by design: every mesh machine runs one, so each keeps
+ * its own HTTP-sourced view of peer liveness, parallel to (and idempotent with)
+ * the git-synced path for credentialed peers.
+ *
+ * Fully injected (peers, fetch, record, clock) so the loop logic is unit-testable
+ * without a live mesh. `pullOnce()` NEVER throws — an unreachable peer simply is
+ * not recorded this pass and ages out of `online` naturally via the registry's
+ * failover threshold.
+ */
+/** A peer to consider polling: its machine id + resolved tunnel URL (null ⇒ unreachable). */
+export interface PeerPresenceMachine {
+    machineId: string;
+    url: string | null;
+}
+/** The slice of a peer's self-capacity the puller records (from `session-status`). */
+export interface PeerCapacity {
+    selfReportedLastSeen?: string;
+    loadAvg?: number;
+}
+export interface PeerPresencePullerDeps {
+    /** This machine's id — never pulled (a machine doesn't poll itself). */
+    selfMachineId: string;
+    /** The current mesh peers (id + resolved URL). Re-read each pass so newly paired peers are picked up. */
+    listPeers: () => PeerPresenceMachine[];
+    /**
+     * Send a signed `session-status` read to a peer and resolve its self-capacity,
+     * or `null` if the peer did not answer / rejected. May reject; `pullOnce`
+     * treats a rejection identically to a `null` (peer not recorded this pass).
+     */
+    fetchPeerCapacity: (machineId: string, url: string) => Promise<PeerCapacity | null>;
+    /** Record an observed peer heartbeat into the pool registry (marks it online for the failover window). */
+    recordHeartbeat: (obs: {
+        machineId: string;
+        selfReportedLastSeen: string;
+        loadAvg?: number;
+    }) => void;
+    /** Wall clock — injectable for tests. Defaults to `Date`. */
+    now?: () => Date;
+    /** Optional structured log line per pass (e.g. for the boot log). */
+    log?: (line: string) => void;
+}
+export declare class PeerPresencePuller {
+    private readonly d;
+    constructor(d: PeerPresencePullerDeps);
+    /**
+     * One presence pass: poll every reachable peer in parallel and record any that
+     * answer into the pool registry. Resolves with the ids recorded this pass.
+     * Never rejects.
+     */
+    pullOnce(): Promise<{
+        recorded: string[];
+    }>;
+}
+//# sourceMappingURL=PeerPresencePuller.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PeerPresencePuller.d.ts","sourceRoot":"","sources":["../../src/core/PeerPresencePuller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,6FAA6F;AAC7F,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,sFAAsF;AACtF,MAAM,WAAW,YAAY;IAC3B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAC;IACtB,yGAAyG;IACzG,SAAS,EAAE,MAAM,mBAAmB,EAAE,CAAC;IACvC;;;;OAIG;IACH,iBAAiB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IACpF,0GAA0G;IAC1G,eAAe,EAAE,CAAC,GAAG,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,oBAAoB,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACtG,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,qEAAqE;IACrE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,qBAAa,kBAAkB;IACjB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,sBAAsB;IAEtD;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAoBlD"}

package/dist/core/PeerPresencePuller.js

@@ -0,0 +1,59 @@
+/**
+ * PeerPresencePuller (Multi-Machine Session Pool — HTTP presence transport).
+ *
+ * The pool registry's notion of which peer machines are ONLINE was originally
+ * fed only by the git-synced MachineHeartbeat: each machine writes its heartbeat
+ * into the shared agent repo, peers pull it, and recency ⇒ online. That breaks
+ * for a *credential-less standby* — a machine paired into the mesh over HTTP but
+ * WITHOUT push access to the shared repo (e.g. a second machine gh-authed to a
+ * different account). Its heartbeat never reaches the router, so the router
+ * marks it offline and the placement engine refuses to transfer to it, even
+ * though the two machines can reach each other perfectly over their tunnels.
+ *
+ * This puller closes that gap with a pull-based HTTP presence channel: on a
+ * cadence, ask each reachable peer for its self-capacity over the signed
+ * /mesh/rpc `session-status` command (a read-class command any registered peer
+ * may issue) and record the answer into the local pool registry. A peer that
+ * answers is, by definition, reachable + alive — so it goes online without ever
+ * touching git. Symmetric by design: every mesh machine runs one, so each keeps
+ * its own HTTP-sourced view of peer liveness, parallel to (and idempotent with)
+ * the git-synced path for credentialed peers.
+ *
+ * Fully injected (peers, fetch, record, clock) so the loop logic is unit-testable
+ * without a live mesh. `pullOnce()` NEVER throws — an unreachable peer simply is
+ * not recorded this pass and ages out of `online` naturally via the registry's
+ * failover threshold.
+ */
+export class PeerPresencePuller {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    /**
+     * One presence pass: poll every reachable peer in parallel and record any that
+     * answer into the pool registry. Resolves with the ids recorded this pass.
+     * Never rejects.
+     */
+    async pullOnce() {
+        const peers = this.d.listPeers().filter((m) => m.machineId !== this.d.selfMachineId && !!m.url);
+        const results = await Promise.all(peers.map(async (m) => {
+            let cap = null;
+            try {
+                cap = await this.d.fetchPeerCapacity(m.machineId, m.url);
+            }
+            catch {
+                cap = null; // unreachable / rejected → not recorded; ages out of online
+            }
+            if (!cap)
+                return null;
+            const seen = cap.selfReportedLastSeen ?? (this.d.now?.() ?? new Date()).toISOString();
+            this.d.recordHeartbeat({ machineId: m.machineId, selfReportedLastSeen: seen, loadAvg: cap.loadAvg });
+            return m.machineId;
+        }));
+        const recorded = results.filter((r) => r !== null);
+        if (recorded.length && this.d.log)
+            this.d.log(`recorded ${recorded.length} peer(s) online over HTTP: ${recorded.join(', ')}`);
+        return { recorded };
+    }
+}
+//# sourceMappingURL=PeerPresencePuller.js.map

package/dist/core/PeerPresencePuller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PeerPresencePuller.js","sourceRoot":"","sources":["../../src/core/PeerPresencePuller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAiCH,MAAM,OAAO,kBAAkB;IACA;IAA7B,YAA6B,CAAyB;QAAzB,MAAC,GAAD,CAAC,CAAwB;IAAG,CAAC;IAE1D;;;;OAIG;IACH,KAAK,CAAC,QAAQ;QACZ,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,aAAa,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAChG,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAA0B,EAAE;YAC5C,IAAI,GAAG,GAAwB,IAAI,CAAC;YACpC,IAAI,CAAC;gBACH,GAAG,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,GAAa,CAAC,CAAC;YACrE,CAAC;YAAC,MAAM,CAAC;gBACP,GAAG,GAAG,IAAI,CAAC,CAAC,4DAA4D;YAC1E,CAAC;YACD,IAAI,CAAC,GAAG;gBAAE,OAAO,IAAI,CAAC;YACtB,MAAM,IAAI,GAAG,GAAG,CAAC,oBAAoB,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;YACtF,IAAI,CAAC,CAAC,CAAC,eAAe,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,oBAAoB,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACrG,OAAO,CAAC,CAAC,SAAS,CAAC;QACrB,CAAC,CAAC,CACH,CAAC;QACF,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;QAChE,IAAI,QAAQ,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG;YAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,QAAQ,CAAC,MAAM,8BAA8B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9H,OAAO,EAAE,QAAQ,EAAE,CAAC;IACtB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.101",
+  "version": "1.3.102",
   "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-29T23:00:30.910Z",
-  "instarVersion": "1.3.101",
+  "generatedAt": "2026-05-29T23:18:48.200Z",
+  "instarVersion": "1.3.102",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.102.md

@@ -0,0 +1,56 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Multi-machine: a second machine that can't push to your shared agent repo now
+still shows up as online — so work can move to it.** When you run one agent
+across two machines, the pool decides which machine is "online" (and therefore
+eligible to receive a conversation) from a heartbeat. Until now that heartbeat
+travelled through the shared agent git repo: each machine wrote its heartbeat
+into the repo and the others read it. A second machine paired over the network
+but signed into a *different* GitHub account has no way to push to that repo, so
+its heartbeat never arrived — the main machine saw it as permanently offline and
+refused to hand any session to it, even though the two machines could reach each
+other perfectly over their tunnels.
+
+There's now a direct presence channel that doesn't touch git: each machine
+periodically asks every reachable peer "are you there?" over the same signed,
+encrypted machine-to-machine channel it already uses for everything else, and
+marks a peer online the moment it answers. A credential-less standby therefore
+becomes a real, transfer-eligible member of the pool purely over its tunnel.
+
+## What to Tell Your User
+
+If you only run on one machine, nothing changes. If you run across two machines
+and the second one is signed into a different GitHub account (or otherwise can't
+push to the shared repo), it will now correctly show as online in your Machines
+list and become eligible to receive conversations — no extra setup, and no git
+credentials needed on the second machine.
+
+## Summary of New Capabilities
+
+- `PeerPresencePuller` (new core module): a pull-based HTTP presence channel.
+  Each mesh machine asks every reachable peer for its self-capacity over the
+  signed `session-status` MeshRpc command and records the answer into its local
+  `MachinePoolRegistry` — so a peer that can't push a git-synced heartbeat still
+  goes online over its tunnel. Symmetric, additive, and idempotent with the
+  existing git-synced heartbeat path; inert on a single-machine agent.
+
+## Evidence
+
+- `tests/unit/peer-presence-puller.test.ts` — loop semantics with injected fakes
+  (records an answering peer; never polls self; skips a peer with no URL; a
+  rejecting fetch neither throws nor records; null is not recorded; clock
+  fallback; `listPeers` re-read each pass).
+- `tests/unit/peer-presence-wiring.test.ts` — server-boot wiring: a real puller
+  is constructed, feeds the signed `session-status` call into
+  `machinePoolRegistry.recordHeartbeat`, and is actually started (immediate pass
+  + recurring unref-ed timer).
+- `tests/integration/peer-presence-roundtrip.test.ts` — full chain over a real
+  loopback `/mesh/rpc` with real Ed25519 keys: a peer starts OFFLINE +
+  placement-ineligible on the router (no git heartbeat) and, after ONE presence
+  pass over the signed channel, is ONLINE + placement-eligible — with an
+  unreachable peer never marked online.
+- Side-effects: `upgrades/side-effects/http-presence-transport.md`.

package/upgrades/side-effects/http-presence-transport.md

@@ -0,0 +1,75 @@
+# Side-effects review — HTTP presence transport (PeerPresencePuller)
+
+## What was happening (real-hardware, 2026-05-29)
+
+The Multi-Machine Session Pool's live-transfer proof (laptop ↔ Mac mini) got all
+the way to the edge and surfaced one architectural gap: the mesh **forms** fine
+over HTTP (non-interactive code-auth pairing, URLs exchanged, peers reachable at
+their tunnels, split-brain clear), but the router would not transfer a session
+to the mini because it saw the mini as `online: false`.
+
+Root cause: the pool registry's notion of which peers are ONLINE was fed ONLY by
+the **git-synced** `MachineHeartbeat` — each machine writes its heartbeat into
+the shared agent repo and peers pull it. The mini is paired into the mesh over
+HTTP but is `gh`-authed to a *different* account, so it has no push access to the
+shared repo. Its heartbeat never reaches the router → the router marks it offline
+→ the placement engine refuses to transfer to an offline machine — even though
+the two machines reach each other perfectly over their tunnels.
+
+## The fix
+
+A pull-based HTTP presence channel that does not touch git:
+
+- **`src/core/PeerPresencePuller.ts`** (new) — on a cadence, ask each reachable
+  peer for its self-capacity over the signed §L0 `session-status` MeshRpc command
+  and feed the answer into the local `MachinePoolRegistry.recordHeartbeat`. A peer
+  that answers is by definition reachable + alive, so it goes `online` purely over
+  HTTP. Fully injected (peers, fetch, record, clock) and `pullOnce()` NEVER throws
+  — an unreachable peer is simply not recorded this pass and ages out of `online`
+  via the registry's existing failover threshold.
+
+- **`src/commands/server.ts`** — in the mesh-rpc block (right after the
+  SessionRouter is wired, where `meshClient` / `peerUrl` / `machinePoolRegistry`
+  are in scope), construct one `PeerPresencePuller` and start it: an immediate
+  `pullOnce()` plus a 30 s `unref`-ed interval. `fetchPeerCapacity` issues
+  `meshClient.send(peer, { type: 'session-status' }, 0)`; `recordHeartbeat`
+  delegates to the real pool registry.
+
+`session-status` is a read-class command (RBAC: any *registered* peer — proven by
+`verifyEnvelope`), so the call authenticates off the mutual identity established
+at pairing. No router role, no epoch fence, no new route, no new config.
+
+## Blast radius
+
+- **Additive + symmetric.** Every mesh machine runs one puller; each maintains
+  its own HTTP-sourced view of peer liveness. It runs in PARALLEL with the
+  existing git-synced `refreshPool` path — a credentialed peer that both
+  git-syncs AND answers HTTP just refreshes twice. `recordHeartbeat` is the single
+  arbiter and the router's-clock liveness rule is unchanged, so a peer can never
+  be marked *fresher* than its real `routerReceivedAt`.
+- **Inert without a mesh.** A single-machine agent has no peers → `listPeers()` is
+  empty → `pullOnce()` is a no-op. Only constructed inside the existing
+  mesh-enabled block.
+- **No new config / route / schema / hook / skill → no migration.** Server +
+  one new core module; existing agents pick it up on the next release (same shape
+  as the native-rebuild / wake-socket fleet fix).
+- **Does NOT replace the git substrate** for ownership/placement *records* (§L0)
+  — only the high-frequency presence signal moves to HTTP.
+
+## Tests
+
+- `tests/unit/peer-presence-puller.test.ts` — loop semantics with injected fakes:
+  a peer that answers is recorded (id + loadAvg + selfReportedLastSeen); self is
+  never polled; a peer with no URL is skipped; a fetch that REJECTS does not throw
+  and does not record (peer ages out); a null result is not recorded; the clock
+  fallback fills `selfReportedLastSeen`; `listPeers` is re-read each pass.
+- `tests/unit/peer-presence-wiring.test.ts` — pins the server-boot wiring:
+  imports + constructs a real puller, feeds the signed `session-status` call into
+  `machinePoolRegistry?.recordHeartbeat`, and actually STARTS it (immediate
+  `pullOnce()` + recurring `unref`-ed timer) — guards against the
+  "constructed-but-inert" failure the Testing Integrity Standard calls out.
+- `tests/integration/peer-presence-roundtrip.test.ts` — the full chain over a real
+  loopback `/mesh/rpc` with real Ed25519 keys: MINI starts OFFLINE +
+  placement-ineligible on the router (no git heartbeat); after ONE presence pass
+  over the signed channel it is ONLINE + placement-eligible (loadAvg carried over
+  HTTP) — and an unreachable peer is never marked online.