instar 1.3.388 → 1.3.389

package/dist/server/PeerStreamProxy.d.ts

@@ -0,0 +1,104 @@
+/**
+ * PeerStreamProxy — phase 1 of Pool Dashboard Streaming
+ * (POOL-DASHBOARD-STREAM-SPEC §2.2, the scalability core).
+ *
+ * ONE multiplexed upstream connection per PEER machine, shared by every local
+ * dashboard client and every remote session on that peer. The local
+ * WebSocketManager (phase 2) owns local clients and the browser WS; this class
+ * owns ONLY the single upstream link and the bookkeeping that makes it correct:
+ *
+ *  - reference-counted subscriptions (per (session) → set of local clientIds);
+ *  - a 60s idle grace after the last unsubscribe, cancelled if a subscribe
+ *    arrives during it (no thrash opening/closing on a flapping client);
+ *  - ONE bounded reconnect on an upstream drop, resubscribing every current
+ *    subscription; a reconnect that does not open within reconnectTimeoutMs, or
+ *    a second drop, surfaces `machine-unreachable` (P19 — never a reconnect
+ *    storm);
+ *  - subscriptions that arrive mid-(re)connect are QUEUED and merged into the
+ *    resubscribe batch the moment the link opens — never lost;
+ *  - the peer URL is re-resolved on every subscribe; a changed URL tears the
+ *    old link down and opens a new one (no stale-URL duplicate links).
+ *
+ * Everything external is injected (transport, timers, clock) so the whole state
+ * machine is deterministically unit-testable without real sockets or wall time.
+ * This module performs NO tmux capture and NO local fan-out polling — capture
+ * happens only on the owning machine; fan-out to local clients is the injected
+ * `onFrameToClients`. (TAP POINT, ops#1: remote subs never enter the local
+ * polling loop.)
+ */
+export type ProxyState = 'idle' | 'connecting' | 'active' | 'idle-scheduled' | 'closing' | 'closed';
+/** A live upstream connection handle (one peer's /ws/pool-stream). */
+export interface UpstreamTransport {
+    /** Send a frame to the peer (subscribe/unsubscribe/input/key/history). */
+    send(frame: Record<string, unknown>): void;
+    /** Tear the connection down. Idempotent. */
+    close(): void;
+}
+/** Handlers the proxy gives the transport at connect time. */
+export interface UpstreamHandlers {
+    /** The link opened and is ready to carry frames. */
+    onOpen(): void;
+    /** A frame arrived from the peer (output/history/session_ended/error/…). */
+    onFrame(frame: Record<string, unknown>): void;
+    /** The link closed (clean or error). */
+    onClose(): void;
+}
+export type TimerHandle = {
+    __brand: 'PeerStreamProxyTimer';
+};
+export interface PeerStreamProxyDeps {
+    peerMachineId: string;
+    /** Resolve the peer's CURRENT url (re-read each subscribe for URL-change detection). */
+    resolveUrl: () => string | null;
+    /** Open an upstream link to `url`; the returned transport drives `handlers`. */
+    connect: (url: string, handlers: UpstreamHandlers) => UpstreamTransport;
+    /** Fan a peer frame out to every LOCAL client subscribed to (session). */
+    onFrameToClients: (session: string, frame: Record<string, unknown>) => void;
+    /** Surface an error to every local client subscribed to (session). */
+    onError: (session: string, code: 'peer-stream-lost' | 'machine-unreachable', detail?: string) => void;
+    now: () => number;
+    setTimer: (ms: number, fn: () => void) => TimerHandle;
+    clearTimer: (t: TimerHandle) => void;
+    /** Idle grace before closing an unsubscribed link (default 60_000). */
+    idleGraceMs?: number;
+    /** Reconnect open deadline (default 10_000). */
+    reconnectTimeoutMs?: number;
+    logger?: (line: string) => void;
+}
+export declare class PeerStreamProxy {
+    private readonly d;
+    private state;
+    private transport;
+    private connectedUrl;
+    /** session → set of local clientIds subscribed to it. THE source of truth:
+     *  on every (re)open we resubscribe from this map, so a subscribe that
+     *  arrives mid-connect is never lost and a mid-connect unsubscribe is never
+     *  replayed. */
+    private readonly subs;
+    private idleTimer;
+    private reconnectTimer;
+    private reconnectUsed;
+    constructor(d: PeerStreamProxyDeps);
+    get currentState(): ProxyState;
+    /** Total live subscriptions across all sessions (refcount). */
+    get refCount(): number;
+    /** Snapshot of session → clientIds (tests / introspection). */
+    sessionsView(): Record<string, string[]>;
+    private log;
+    /** A local client subscribes to a remote session on this peer. */
+    subscribe(session: string, clientId: string): void;
+    /** A local client unsubscribes (or disconnects). */
+    unsubscribe(session: string, clientId: string): void;
+    /** Forward an input/key frame for a session (caller already gated allowRemoteInput). */
+    relayInput(frame: Record<string, unknown>): void;
+    private openFresh;
+    private onUpstreamOpen;
+    private onUpstreamFrame;
+    private onUpstreamClose;
+    private scheduleIdleClose;
+    private failAll;
+    private teardownTransport;
+    /** Force-close (peer removed, server shutdown). Idempotent. */
+    close(): void;
+}
+//# sourceMappingURL=PeerStreamProxy.d.ts.map

package/dist/server/PeerStreamProxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PeerStreamProxy.d.ts","sourceRoot":"","sources":["../../src/server/PeerStreamProxy.ts"],"names":[],"mappings":"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"}

package/dist/server/PeerStreamProxy.js

@@ -0,0 +1,270 @@
+/**
+ * PeerStreamProxy — phase 1 of Pool Dashboard Streaming
+ * (POOL-DASHBOARD-STREAM-SPEC §2.2, the scalability core).
+ *
+ * ONE multiplexed upstream connection per PEER machine, shared by every local
+ * dashboard client and every remote session on that peer. The local
+ * WebSocketManager (phase 2) owns local clients and the browser WS; this class
+ * owns ONLY the single upstream link and the bookkeeping that makes it correct:
+ *
+ *  - reference-counted subscriptions (per (session) → set of local clientIds);
+ *  - a 60s idle grace after the last unsubscribe, cancelled if a subscribe
+ *    arrives during it (no thrash opening/closing on a flapping client);
+ *  - ONE bounded reconnect on an upstream drop, resubscribing every current
+ *    subscription; a reconnect that does not open within reconnectTimeoutMs, or
+ *    a second drop, surfaces `machine-unreachable` (P19 — never a reconnect
+ *    storm);
+ *  - subscriptions that arrive mid-(re)connect are QUEUED and merged into the
+ *    resubscribe batch the moment the link opens — never lost;
+ *  - the peer URL is re-resolved on every subscribe; a changed URL tears the
+ *    old link down and opens a new one (no stale-URL duplicate links).
+ *
+ * Everything external is injected (transport, timers, clock) so the whole state
+ * machine is deterministically unit-testable without real sockets or wall time.
+ * This module performs NO tmux capture and NO local fan-out polling — capture
+ * happens only on the owning machine; fan-out to local clients is the injected
+ * `onFrameToClients`. (TAP POINT, ops#1: remote subs never enter the local
+ * polling loop.)
+ */
+const DEFAULT_IDLE_GRACE_MS = 60_000;
+const DEFAULT_RECONNECT_TIMEOUT_MS = 10_000;
+export class PeerStreamProxy {
+    d;
+    state = 'idle';
+    transport = null;
+    connectedUrl = null;
+    /** session → set of local clientIds subscribed to it. THE source of truth:
+     *  on every (re)open we resubscribe from this map, so a subscribe that
+     *  arrives mid-connect is never lost and a mid-connect unsubscribe is never
+     *  replayed. */
+    subs = new Map();
+    idleTimer = null;
+    reconnectTimer = null;
+    reconnectUsed = false;
+    constructor(d) {
+        this.d = d;
+    }
+    get currentState() {
+        return this.state;
+    }
+    /** Total live subscriptions across all sessions (refcount). */
+    get refCount() {
+        let n = 0;
+        for (const set of this.subs.values())
+            n += set.size;
+        return n;
+    }
+    /** Snapshot of session → clientIds (tests / introspection). */
+    sessionsView() {
+        const out = {};
+        for (const [s, set] of this.subs)
+            out[s] = [...set];
+        return out;
+    }
+    log(line) {
+        this.d.logger?.(`[peer-stream-proxy ${this.d.peerMachineId}] ${line}`);
+    }
+    // ── subscribe / unsubscribe (refcounted) ───────────────────────────────
+    /** A local client subscribes to a remote session on this peer. */
+    subscribe(session, clientId) {
+        if (this.state === 'closed') {
+            this.log('subscribe after close — ignored');
+            return;
+        }
+        // Cancel a pending idle close — we have demand again.
+        if (this.idleTimer) {
+            this.d.clearTimer(this.idleTimer);
+            this.idleTimer = null;
+            if (this.state === 'idle-scheduled')
+                this.state = 'active';
+        }
+        let set = this.subs.get(session);
+        if (!set) {
+            set = new Set();
+            this.subs.set(session, set);
+        }
+        const firstForSession = set.size === 0;
+        set.add(clientId);
+        // URL re-resolution (stale-URL guard): if the peer moved, reconnect fresh.
+        const url = this.d.resolveUrl();
+        if (this.state === 'active' && this.connectedUrl && url && url !== this.connectedUrl) {
+            this.log(`peer url changed (${this.connectedUrl} → ${url}); reconnecting`);
+            this.teardownTransport();
+            this.openFresh(url);
+            return; // openFresh replays ALL current subs (incl. this one) on open
+        }
+        if (this.state === 'idle' || this.state === 'closing') {
+            // No link yet → open one; openFresh flushes all subs on open.
+            if (!url) {
+                // No reachable URL — honest failure, drop the just-added sub for it.
+                set.delete(clientId);
+                if (set.size === 0)
+                    this.subs.delete(session);
+                this.d.onError(session, 'machine-unreachable', 'no url for peer');
+                return;
+            }
+            this.openFresh(url);
+            return;
+        }
+        if (this.state === 'active') {
+            // Link is live → forward only when this is the first client for the
+            // session (the upstream is already streaming it for any later client).
+            if (firstForSession)
+                this.transport?.send({ type: 'subscribe', session });
+            return;
+        }
+        // connecting → the sub is now in `subs`; onUpstreamOpen resubscribes from
+        // `subs`, so it is automatically included in the batch (never lost).
+    }
+    /** A local client unsubscribes (or disconnects). */
+    unsubscribe(session, clientId) {
+        const set = this.subs.get(session);
+        if (!set)
+            return;
+        set.delete(clientId);
+        if (set.size === 0) {
+            this.subs.delete(session);
+            if (this.state === 'active')
+                this.transport?.send({ type: 'unsubscribe', session });
+        }
+        if (this.refCount === 0)
+            this.scheduleIdleClose();
+    }
+    /** Forward an input/key frame for a session (caller already gated allowRemoteInput). */
+    relayInput(frame) {
+        if (this.state === 'active')
+            this.transport?.send(frame);
+        // Not active → input is dropped (caller's terminal shows the live state);
+        // we never queue keystrokes across a reconnect (stale input is worse than none).
+    }
+    // ── connection lifecycle ───────────────────────────────────────────────
+    openFresh(url, reconnect = false) {
+        // A user-initiated open resets the one-shot reconnect budget; a reconnect
+        // leaves `reconnectUsed` true so a further drop → machine-unreachable.
+        if (!reconnect)
+            this.reconnectUsed = false;
+        this.state = 'connecting';
+        this.connectedUrl = url;
+        const handlers = {
+            onOpen: () => this.onUpstreamOpen(),
+            onFrame: (f) => this.onUpstreamFrame(f),
+            onClose: () => this.onUpstreamClose(),
+        };
+        try {
+            this.transport = this.d.connect(url, handlers);
+        }
+        catch (e) {
+            this.log(`connect threw: ${e?.message ?? e}`);
+            this.onUpstreamClose();
+        }
+    }
+    onUpstreamOpen() {
+        if (this.state === 'closed') {
+            this.transport?.close();
+            return;
+        }
+        this.state = 'active';
+        if (this.reconnectTimer) {
+            this.d.clearTimer(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        // Resubscribe from `subs` (the source of truth) — this naturally includes
+        // any subscribe that arrived mid-connect and excludes any mid-connect
+        // unsubscribe. No stale snapshot to lose.
+        for (const session of this.subs.keys())
+            this.transport?.send({ type: 'subscribe', session });
+        // If nothing is subscribed anymore (all unsubscribed during connect), idle-close.
+        if (this.refCount === 0)
+            this.scheduleIdleClose();
+    }
+    onUpstreamFrame(frame) {
+        const session = typeof frame.session === 'string' ? frame.session : null;
+        if (!session)
+            return; // peer frames without a session are not fan-out-able
+        // Only fan out to sessions we still have local subscribers for.
+        if (!this.subs.has(session))
+            return;
+        this.d.onFrameToClients(session, frame);
+    }
+    onUpstreamClose() {
+        if (this.state === 'closed' || this.state === 'closing') {
+            this.state = 'closed';
+            return;
+        }
+        this.transport = null;
+        // Nothing subscribed → just go idle, no reconnect.
+        if (this.refCount === 0) {
+            this.state = 'idle';
+            return;
+        }
+        if (this.reconnectUsed) {
+            // Second failure → declare the peer unreachable for every affected session.
+            this.log('second upstream drop → machine-unreachable');
+            this.failAll('machine-unreachable', 'peer unreachable after reconnect');
+            return;
+        }
+        // First drop → tell clients, attempt ONE bounded reconnect.
+        for (const session of this.subs.keys())
+            this.d.onError(session, 'peer-stream-lost', 'upstream dropped');
+        this.reconnectUsed = true;
+        const url = this.d.resolveUrl();
+        if (!url) {
+            this.failAll('machine-unreachable', 'no url on reconnect');
+            return;
+        }
+        this.openFresh(url, true);
+        // Bound the reconnect: if it doesn't open in time, declare unreachable.
+        this.reconnectTimer = this.d.setTimer(this.d.reconnectTimeoutMs ?? DEFAULT_RECONNECT_TIMEOUT_MS, () => {
+            this.reconnectTimer = null;
+            if (this.state !== 'active') {
+                this.log('reconnect timed out → machine-unreachable');
+                this.teardownTransport();
+                this.failAll('machine-unreachable', 'reconnect timed out');
+            }
+        });
+    }
+    scheduleIdleClose() {
+        if (this.idleTimer || this.state === 'closed')
+            return;
+        if (this.state === 'active')
+            this.state = 'idle-scheduled';
+        this.idleTimer = this.d.setTimer(this.d.idleGraceMs ?? DEFAULT_IDLE_GRACE_MS, () => {
+            this.idleTimer = null;
+            if (this.refCount === 0) {
+                this.log('idle grace elapsed → closing');
+                this.teardownTransport();
+                this.state = 'closed';
+            }
+        });
+    }
+    failAll(code, detail) {
+        for (const session of this.subs.keys())
+            this.d.onError(session, code, detail);
+        this.subs.clear();
+        this.teardownTransport();
+        this.state = 'closed';
+    }
+    teardownTransport() {
+        if (this.reconnectTimer) {
+            this.d.clearTimer(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        try {
+            this.transport?.close();
+        }
+        catch { /* @silent-fallback-ok: closing an already-dead upstream is best-effort */ }
+        this.transport = null;
+        this.connectedUrl = null;
+    }
+    /** Force-close (peer removed, server shutdown). Idempotent. */
+    close() {
+        if (this.idleTimer) {
+            this.d.clearTimer(this.idleTimer);
+            this.idleTimer = null;
+        }
+        this.subs.clear();
+        this.teardownTransport();
+        this.state = 'closed';
+    }
+}
+//# sourceMappingURL=PeerStreamProxy.js.map

package/dist/server/PeerStreamProxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PeerStreamProxy.js","sourceRoot":"","sources":["../../src/server/PeerStreamProxy.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.388",
+  "version": "1.3.389",
   "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-06-07T00:43:22.312Z",
-  "instarVersion": "1.3.388",
+  "generatedAt": "2026-06-07T00:51:44.855Z",
+  "instarVersion": "1.3.389",
   "entryCount": 199,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.389.md

@@ -0,0 +1,45 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+First building block of the single-dashboard cross-machine streaming feature
+(POOL-DASHBOARD-STREAM-SPEC): the `PeerStreamProxy` — one multiplexed upstream
+connection per peer machine that the dashboard's WebSocket layer will use
+(phase 2) to relay a remote session's terminal stream. This phase ships the
+state machine ONLY; it is not yet wired to the live WebSocketManager, so it
+changes no user-visible behavior on its own.
+
+The proxy is the scalability + correctness core the reviewers stressed:
+reference-counted subscriptions, a 60s idle grace (cancelled if demand
+returns), ONE bounded reconnect on a drop with full resubscribe (a second drop
+or a reconnect timeout → machine-unreachable, never a reconnect storm),
+mid-reconnect subscribes merged from the source-of-truth subscription map (never
+lost), and peer-URL-change detection (stale-URL links are torn down). Capture
+stays on the owning machine; this only relays — so fleet cost is
+O(subscriptions), not O(sessions × clients × peers).
+
+## What to Tell Your User
+
+Nothing yet — this is internal plumbing. The visible result (click any
+machine's session and it streams) lands when phases 2–3 wire it to the
+dashboard.
+
+- audience: agent-only
+- maturity: preview
+
+## Summary of New Capabilities
+
+- `src/server/PeerStreamProxy.ts` — the per-peer upstream relay state machine,
+  fully transport/timer/clock-injected (no live wiring yet).
+
+## Evidence
+
+- `tests/unit/PeerStreamProxy.test.ts` (13 tests, deterministic): open+multiplex
+  (one upstream, no double-subscribe for a second client), idle-close +
+  mid-grace reactivate, bounded reconnect + resubscribe, second-drop →
+  unreachable, reconnect-timeout → unreachable, mid-reconnect subscribe merged,
+  url-change reopen, no-url → machine-unreachable, input-relay-only-when-active,
+  idempotent close.

package/upgrades/side-effects/dashboard-stream-phase1-proxy.md

@@ -0,0 +1,61 @@
+# Side-Effects Review — Pool dashboard streaming phase 1 (PeerStreamProxy)
+
+**Version / slug:** `dashboard-stream-phase1-proxy`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+A NEW, self-contained module (`PeerStreamProxy`) — phase 1 of the converged
+POOL-DASHBOARD-STREAM-SPEC. The per-peer upstream relay state machine, with all
+external surfaces (transport, timers, clock) injected. NOT wired into the live
+WebSocketManager or server boot in this phase, so it has zero runtime effect
+until phase 2 consumes it.
+
+## Decision-point inventory
+
+The state machine's transitions: open / multiplex / idle-close / reactivate /
+bounded-reconnect / second-drop-unreachable / reconnect-timeout / url-change /
+no-url. Each is covered both-sides by a deterministic test.
+
+## 1. Over-block
+
+N/A — no gating; a relay. The conservative reconnect policy (one attempt per
+episode, then machine-unreachable) could declare a flaky-but-recoverable peer
+unreachable, but the user simply re-subscribes (re-click), which opens fresh
+and resets the budget. Storm-proof beats persistent.
+
+## 2. Under-block
+
+Keystrokes are never queued across a (re)connect — stale input is worse than
+none. Acceptable: the dashboard shows the live link state (phase 3) so the user
+knows when input is live.
+
+## 3. Level-of-abstraction fit
+
+Pure module under src/server/, no I/O of its own. The WebSocketManager (phase 2)
+owns local clients + the browser WS and injects the transport; this owns only
+the single upstream link + its bookkeeping. Matches the P2 precedent of
+shipping a tested building block before its consumer.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+No authority. A transport relay; all auth (ticket) + input gating
+(allowRemoteInput) live in phase 2 at the WSManager/upgrade boundary per spec
+§2.3.
+
+## 5. Interactions
+
+- WebSocketManager (phase 2): the future consumer; unaffected now (no import).
+- Local polling loop: untouched — remote subs never enter it (TAP POINT). This
+  module does no tmux capture.
+- P19 (No Unbounded Loops): the reconnect is a single bounded attempt; tests
+  assert the second-drop and timeout both terminate to machine-unreachable.
+
+## 6. External surfaces
+
+None in this phase. No routes, config, notifications, or wiring. A new source
+file + its test only.