instar 1.3.93 → 1.3.94

package/dist/core/MeshUrlAdvertiser.d.ts

@@ -0,0 +1,50 @@
+/**
+ * MeshUrlAdvertiser — populate a machine's `lastKnownUrl` so cross-machine
+ * routing can actually reach it.
+ *
+ * THE BUG THIS FIXES (found via real-hardware dogfooding, 2026-05-29):
+ * the Multi-Machine Session Pool routes every cross-machine RPC (deliver /
+ * transfer / lease) to a peer by reading `registry.machines[id].lastKnownUrl`.
+ * But the only writer of that field — `MachineIdentityManager.updateMachineUrl`
+ * — had ZERO callers. So in production every peer's URL was null, the peer
+ * filters (`!!e.lastKnownUrl`) dropped every peer, and no session could ever be
+ * delivered or transferred across machines. The 3-tier tests missed it because
+ * they inject peers with mock URLs and never exercise the runtime "where does
+ * lastKnownUrl come from" path.
+ *
+ * A machine's reachable URL is its tunnel URL: a named tunnel's hostname is
+ * known from config; a quick tunnel's URL is only known once `tunnel.start()`
+ * resolves it. This module turns either into the value to advertise, and writes
+ * it into the registry entry — from where the existing git-backed registry sync
+ * (RegistrySyncDebouncer) propagates it to peers.
+ */
+export interface MeshTunnelConfig {
+    enabled?: boolean;
+    type?: string;
+    hostname?: string;
+}
+/**
+ * Resolve the URL this machine should advertise to the mesh.
+ *
+ * Preference order:
+ *  1. A concretely-resolved tunnel URL (quick tunnels only know it at runtime;
+ *     `tunnel.start()` returns it). This is authoritative when present.
+ *  2. A named tunnel's deterministic `https://<hostname>`.
+ *  3. null — no reachable URL (tunnel disabled / not configured). A machine
+ *     with no tunnel is genuinely not reachable cross-machine; advertising
+ *     nothing is correct (peers will skip it rather than route to a dead URL).
+ */
+export declare function resolveAdvertisedMeshUrl(tunnel: MeshTunnelConfig | undefined, resolvedTunnelUrl?: string | null): string | null;
+/** Minimal slice of MachineIdentityManager this module needs (keeps it testable). */
+export interface MeshUrlRecorder {
+    getMachineUrl(machineId: string): string | null;
+    updateMachineUrl(machineId: string, url: string): void;
+}
+/**
+ * Advertise this machine's reachable URL into its own registry entry so peers
+ * can route to it. Idempotent (no write when unchanged), and tolerant when the
+ * self entry isn't present yet (best-effort — boot ordering can race the
+ * registration). Returns true iff it wrote a new value.
+ */
+export declare function advertiseSelfMeshUrl(recorder: MeshUrlRecorder, selfMachineId: string, url: string | null, log?: (msg: string) => void): boolean;
+//# sourceMappingURL=MeshUrlAdvertiser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MeshUrlAdvertiser.d.ts","sourceRoot":"","sources":["../../src/core/MeshUrlAdvertiser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,gBAAgB,GAAG,SAAS,EACpC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,GAChC,MAAM,GAAG,IAAI,CASf;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAChD,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACxD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,eAAe,EACzB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAC1B,OAAO,CAWT"}

package/dist/core/MeshUrlAdvertiser.js

@@ -0,0 +1,64 @@
+/**
+ * MeshUrlAdvertiser — populate a machine's `lastKnownUrl` so cross-machine
+ * routing can actually reach it.
+ *
+ * THE BUG THIS FIXES (found via real-hardware dogfooding, 2026-05-29):
+ * the Multi-Machine Session Pool routes every cross-machine RPC (deliver /
+ * transfer / lease) to a peer by reading `registry.machines[id].lastKnownUrl`.
+ * But the only writer of that field — `MachineIdentityManager.updateMachineUrl`
+ * — had ZERO callers. So in production every peer's URL was null, the peer
+ * filters (`!!e.lastKnownUrl`) dropped every peer, and no session could ever be
+ * delivered or transferred across machines. The 3-tier tests missed it because
+ * they inject peers with mock URLs and never exercise the runtime "where does
+ * lastKnownUrl come from" path.
+ *
+ * A machine's reachable URL is its tunnel URL: a named tunnel's hostname is
+ * known from config; a quick tunnel's URL is only known once `tunnel.start()`
+ * resolves it. This module turns either into the value to advertise, and writes
+ * it into the registry entry — from where the existing git-backed registry sync
+ * (RegistrySyncDebouncer) propagates it to peers.
+ */
+/**
+ * Resolve the URL this machine should advertise to the mesh.
+ *
+ * Preference order:
+ *  1. A concretely-resolved tunnel URL (quick tunnels only know it at runtime;
+ *     `tunnel.start()` returns it). This is authoritative when present.
+ *  2. A named tunnel's deterministic `https://<hostname>`.
+ *  3. null — no reachable URL (tunnel disabled / not configured). A machine
+ *     with no tunnel is genuinely not reachable cross-machine; advertising
+ *     nothing is correct (peers will skip it rather than route to a dead URL).
+ */
+export function resolveAdvertisedMeshUrl(tunnel, resolvedTunnelUrl) {
+    if (resolvedTunnelUrl && /^https?:\/\/\S+$/.test(resolvedTunnelUrl.trim())) {
+        return resolvedTunnelUrl.trim().replace(/\/+$/, '');
+    }
+    if (tunnel?.enabled !== false && tunnel?.hostname && tunnel.hostname.trim()) {
+        const host = tunnel.hostname.trim().replace(/^https?:\/\//, '').replace(/\/+$/, '');
+        if (host)
+            return `https://${host}`;
+    }
+    return null;
+}
+/**
+ * Advertise this machine's reachable URL into its own registry entry so peers
+ * can route to it. Idempotent (no write when unchanged), and tolerant when the
+ * self entry isn't present yet (best-effort — boot ordering can race the
+ * registration). Returns true iff it wrote a new value.
+ */
+export function advertiseSelfMeshUrl(recorder, selfMachineId, url, log) {
+    if (!url || !selfMachineId)
+        return false;
+    try {
+        if (recorder.getMachineUrl(selfMachineId) === url)
+            return false; // idempotent
+        recorder.updateMachineUrl(selfMachineId, url);
+        log?.(`  Mesh: advertised self URL → ${url}`);
+        return true;
+    }
+    catch {
+        // Self entry not present yet — caller may retry on a later lifecycle event.
+        return false;
+    }
+}
+//# sourceMappingURL=MeshUrlAdvertiser.js.map

package/dist/core/MeshUrlAdvertiser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MeshUrlAdvertiser.js","sourceRoot":"","sources":["../../src/core/MeshUrlAdvertiser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAQH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CACtC,MAAoC,EACpC,iBAAiC;IAEjC,IAAI,iBAAiB,IAAI,kBAAkB,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QAC3E,OAAO,iBAAiB,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,MAAM,EAAE,OAAO,KAAK,KAAK,IAAI,MAAM,EAAE,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;QAC5E,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACpF,IAAI,IAAI;YAAE,OAAO,WAAW,IAAI,EAAE,CAAC;IACrC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAQD;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAyB,EACzB,aAAqB,EACrB,GAAkB,EAClB,GAA2B;IAE3B,IAAI,CAAC,GAAG,IAAI,CAAC,aAAa;QAAE,OAAO,KAAK,CAAC;IACzC,IAAI,CAAC;QACH,IAAI,QAAQ,CAAC,aAAa,CAAC,aAAa,CAAC,KAAK,GAAG;YAAE,OAAO,KAAK,CAAC,CAAC,aAAa;QAC9E,QAAQ,CAAC,gBAAgB,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;QAC9C,GAAG,EAAE,CAAC,iCAAiC,GAAG,EAAE,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,4EAA4E;QAC5E,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/package.json

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

package/upgrades/1.3.94.md

@@ -0,0 +1,38 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Multi-Machine Session Pool — cross-machine routing fix (still dark).** Real
+hardware bring-up of a second machine surfaced a wiring gap: the session pool
+routes every cross-machine action (deliver / transfer / lease) to a peer by its
+`lastKnownUrl` (its tunnel URL), but nothing in the shipped code ever wrote that
+field — so every peer was filtered out and no session could be routed or
+transferred across machines. A machine now advertises its own tunnel URL into
+the mesh registry once the tunnel is up (and re-advertises after a sleep/wake
+restart, since a quick tunnel's URL changes), and a joining machine records the
+URL it paired through. The whole layer remains gated behind
+`multiMachine.sessionPool` (default off / `stage:'dark'`), so single-machine
+agents are unaffected.
+
+## What to Tell Your User
+
+Nothing changes yet — this is still off by default. It fixes a foundational gap
+so that, when the session pool is enabled, conversations can actually be placed
+on and moved between machines.
+
+## Summary of New Capabilities
+
+- `MeshUrlAdvertiser` (`resolveAdvertisedMeshUrl` + `advertiseSelfMeshUrl`):
+  populates a machine's `lastKnownUrl` from its tunnel URL on boot + sleep/wake.
+- `instar join` now records the awake machine's URL on the joining (standby) side.
+
+## Evidence
+
+- Unit: `tests/unit/mesh-url-advertiser.test.ts` (resolver + advertiser vs a real
+  MachineIdentityManager).
+- Wiring-integrity: `tests/unit/mesh-url-advertisement-wiring.test.ts` (asserts
+  the advertiser is actually invoked — the tier that would have caught the
+  original zero-callers gap).
+- Side-effects: `upgrades/side-effects/mesh-url-advertisement.md`.

package/upgrades/side-effects/mesh-url-advertisement.md

@@ -0,0 +1,66 @@
+# Side-effects review — Mesh URL advertisement (lastKnownUrl population)
+
+## What changed
+
+`updateMachineUrl()` (the only writer of `registry.machines[id].lastKnownUrl`)
+had **zero callers** on main. The Multi-Machine Session Pool routes every
+cross-machine RPC — `deliverMessage`, session transfer, lease ops — to a peer by
+reading that peer's `lastKnownUrl`, and filters peers with `!!e.lastKnownUrl`.
+With the field never written, every peer was filtered out and **no session
+could ever be delivered or transferred across machines**. The feature was inert
+across real machines despite green 3-tier tests (which inject mock peer URLs).
+
+Found 2026-05-29 bringing up a second real machine (the mini) for the
+session-pool real-hardware proof.
+
+This change adds:
+- `src/core/MeshUrlAdvertiser.ts` — `resolveAdvertisedMeshUrl(tunnel, resolvedUrl?)`
+  (named → `https://<hostname>`, quick → the runtime-resolved start URL, none →
+  null) + `advertiseSelfMeshUrl(recorder, selfId, url)` (idempotent, tolerant of
+  a missing self entry).
+- `src/commands/server.ts` — calls the advertiser after `tunnel.start()` on both
+  the boot path and the sleep/wake restart path (a quick tunnel gets a new URL
+  after a wake, so the previously-advertised URL goes stale).
+- `src/commands/machine.ts` (`joinMesh`) — the joiner records the URL it
+  connected through as the awake peer's `lastKnownUrl`, so a standby can route
+  back to the awake machine immediately without waiting for a registry sync.
+
+## Blast radius
+
+- **Dark-feature-only effect.** The populated `lastKnownUrl` is consumed solely
+  by the session-pool mesh code, which is gated behind `multiMachine.sessionPool`
+  (default `enabled:false`, `stage:'dark'`). On a single-machine agent there are
+  no peers, so nothing changes. Populating the field is otherwise inert.
+- **No new config, no new route, no schema change** → no migration needed.
+  Existing agents pick up the behavior at boot on the next release. No
+  `PostUpdateMigrator` entry required (the code runs at startup unconditionally
+  when multi-machine is enabled and a tunnel URL exists).
+- **Idempotent + fail-safe.** `advertiseSelfMeshUrl` writes only when the URL
+  changed and swallows the "self entry not present yet" race (returns false).
+  A tunnel-disabled machine advertises nothing (correct — it is genuinely
+  unreachable cross-machine; peers skip it rather than route to a dead URL).
+- **No secret exposure.** A tunnel URL is already public (the dashboard link).
+  Recording it in the registry adds no new exposure.
+
+## What this does NOT close (scoped, decision-gated follow-up)
+
+The **awake machine learning a git-uncredentialed standby's URL** still needs one
+of: (a) the standby having git push creds for the shared agent repo (so its
+advertised entry syncs via the existing git-backed RegistrySyncDebouncer), or
+(b) a signed mesh `announce-url` RPC so a standby can publish its URL to the
+awake machine over authenticated MeshRpc without git. (b) also requires the
+awake side to persist the joiner's identity, which today only happens via the
+**interactive SAS pairing** confirmation — so closing this fully touches the
+pairing security model. That is a genuine design fork (creds vs. new RPC +
+non-interactive registration), not a silent deferral, and is raised explicitly
+rather than hand-resolved on a production identity.
+
+## Tests
+
+- `tests/unit/mesh-url-advertiser.test.ts` — resolver (named/quick/disabled/none)
+  + advertiser against a real `MachineIdentityManager` (writes, idempotent,
+  updates on change, null no-op, missing-entry tolerance).
+- `tests/unit/mesh-url-advertisement-wiring.test.ts` — wiring-integrity: asserts
+  the advertiser is invoked on the boot + sleep/wake tunnel paths and the joiner
+  records the connect URL. This is the tier that was missing — it would have
+  caught the original "zero callers" gap.