instar 1.3.483 → 1.3.485

package/skills/spec-converge/scripts/cross-model-review.mjs

@@ -15,20 +15,37 @@
  * access, so context must be inlined before the spawn.
  *
  * Modes:
- *   --detect-only            Print detection JSON and exit (no codex spawn).
- *                            { available, framework?, model?, reason? }
+ *   --detect-only            Print detection JSON and exit (no spawn).
+ *                            { available, frameworks: [...all available...],
+ *                              framework?, model?, reason? } — the `frameworks`
+ *                            array is the Piece-3 family-diverse collection;
+ *                            the single-framework fields stay for back-compat.
+ *                            With --state-dir <dir>, also records the
+ *                            activation observation to the durable
+ *                            framework-activation history (the standing-
+ *                            framework baseline for the mandatory check).
+ *   --hash-only              Print { hash } — sha256 of the spec's reviewable
+ *                            body (frontmatter-stripped, CRLF-normalized) for
+ *                            the skill's delta-gating. Requires --spec.
  *   (default)                Detect; if available, assemble the prompt + run
- *                            the codex review; print the ReviewerResult JSON.
+ *                            the review; print the ReviewerResult JSON. With
+ *                            --family <id>, run through THAT framework
+ *                            specifically (must be on the trusted first-party
+ *                            allowlist — spec text is never sent to a custom/
+ *                            base-URL endpoint; pi-cli is excluded by design).
  *
  * Usage:
  *   node skills/spec-converge/scripts/cross-model-review.mjs \
  *     --spec docs/specs/<slug>.md \
  *     [--context docs/foo.md --context docs/bar.md ...] \
- *     [--detect-only] \
+ *     [--detect-only] [--state-dir .instar] \
+ *     [--hash-only] \
+ *     [--family codex-cli|gemini-cli] \
  *     [--timeout-ms 120000]
  *
  * Output: a single JSON object on stdout (machine-readable for the skill).
- *   On detect-only: the CrossModelDetectionResult.
+ *   On detect-only: the detection JSON above.
+ *   On hash-only:   { hash }.
  *   On full run:    the ReviewerResult ({ status, framework?, model?, verdict?,
  *                   findings?, reason?, flag }).
  *
@@ -60,19 +77,30 @@ function fail(msg) {
 
 function parseArgs() {
   const args = process.argv.slice(2);
-  const out = { spec: null, context: [], detectOnly: false, timeoutMs: null };
+  const out = {
+    spec: null,
+    context: [],
+    detectOnly: false,
+    hashOnly: false,
+    family: null,
+    stateDir: null,
+    timeoutMs: null,
+  };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === '--spec') out.spec = args[++i];
     else if (a === '--context') out.context.push(args[++i]);
     else if (a === '--detect-only') out.detectOnly = true;
+    else if (a === '--hash-only') out.hashOnly = true;
+    else if (a === '--family') out.family = args[++i];
+    else if (a === '--state-dir') out.stateDir = args[++i];
     else if (a === '--timeout-ms') out.timeoutMs = parseInt(args[++i], 10);
     else fail(`Unknown arg: ${a}`);
   }
   if (!out.detectOnly && !out.spec) {
     fail(
       'Usage: cross-model-review.mjs --spec PATH [--context PATH ...] ' +
-        '[--detect-only] [--timeout-ms N]',
+        '[--detect-only] [--hash-only] [--family ID] [--state-dir DIR] [--timeout-ms N]',
     );
   }
   return out;
@@ -98,17 +126,81 @@ function readRepoFile(rel) {
 }
 
 async function main() {
-  const { spec, context, detectOnly, timeoutMs } = parseArgs();
+  const { spec, context, detectOnly, hashOnly, family, stateDir, timeoutMs } = parseArgs();
   const mod = await loadModule();
 
-  // Detection is the same in both modes.
-  const detection = mod.detectCrossModelReviewer();
+  // ── --hash-only: the delta-gating hash of the spec's reviewable body ──
+  if (hashOnly) {
+    if (!spec) fail('--hash-only requires --spec PATH');
+    const specMarkdown = readRepoFile(spec);
+    process.stdout.write(JSON.stringify({ hash: mod.hashSpecReviewableBody(specMarkdown) }) + '\n');
+    process.exit(0);
+  }
 
+  // ── --detect-only: report ALL available families (Piece 3) ──
   if (detectOnly) {
-    process.stdout.write(JSON.stringify(detection) + '\n');
+    const all = mod.detectAllCrossModelReviewers();
+    // Back-compat: keep the old single-framework fields (first-match shape).
+    const first = mod.detectCrossModelReviewer();
+    const report = {
+      available: all.length > 0,
+      frameworks: all,
+      ...(first.framework ? { framework: first.framework } : {}),
+      ...(first.model ? { model: first.model } : {}),
+      ...(first.reason ? { reason: first.reason } : {}),
+    };
+    // Record the activation observation into the durable standing-framework
+    // baseline when a state dir was provided. A record failure is surfaced in
+    // the JSON (fail-loud), never silently swallowed — a missing baseline
+    // would quietly weaken the externals-mandatory check.
+    if (stateDir) {
+      const frameworks = {};
+      for (const entry of mod.SUPPORTED_REVIEWER_FRAMEWORKS) {
+        frameworks[entry.id] = all.some((d) => d.framework === entry.id);
+      }
+      try {
+        mod.recordFrameworkActivationObservation(stateDir, { frameworks });
+        report.activationRecorded = true;
+      } catch (err) {
+        report.activationRecorded = false;
+        report.activationRecordError =
+          err instanceof Error ? err.message.slice(0, 200) : String(err);
+      }
+    }
+    process.stdout.write(JSON.stringify(report) + '\n');
     process.exit(0);
   }
 
+  // ── full run ──
+  // --family: run through ONE specific framework. Allowlist-gated — the full
+  // spec text is never sent to a custom/base-URL endpoint (pi-cli excluded).
+  let familyEntry = null;
+  if (family) {
+    if (!mod.isTrustedReviewerFramework(family)) {
+      process.stdout.write(
+        JSON.stringify({
+          status: 'unavailable',
+          reason: 'untrusted-framework',
+          flag: 'cross-model-review: unavailable',
+        }) + '\n',
+      );
+      process.exit(0);
+    }
+    familyEntry = mod.SUPPORTED_REVIEWER_FRAMEWORKS.find((f) => f.id === family) ?? null;
+    if (!familyEntry) {
+      process.stdout.write(
+        JSON.stringify({
+          status: 'unavailable',
+          reason: 'no-supported-framework',
+          flag: 'cross-model-review: unavailable',
+        }) + '\n',
+      );
+      process.exit(0);
+    }
+  }
+
+  const detection = familyEntry ? familyEntry.detect() : mod.detectCrossModelReviewer();
+
   // Unavailable → print the unavailable flag, exit 0. Never block.
   if (!detection.available) {
     const flag = mod.buildCrossModelFlag('unavailable', detection.reason);
@@ -130,10 +222,16 @@ async function main() {
     context: contextDocs,
   });
 
-  const result = await mod.runCrossModelReview({
-    assembled,
-    ...(Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
-  });
+  const result = familyEntry
+    ? await familyEntry.review({
+        promptText: assembled.promptText,
+        timeoutMs: Number.isFinite(timeoutMs) ? timeoutMs : mod.REVIEW_TIMEOUT_MS,
+        detectionOverride: detection,
+      })
+    : await mod.runCrossModelReview({
+        assembled,
+        ...(Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
+      });
 
   // Surface truncation in the emitted result so the skill/report can note it.
   process.stdout.write(JSON.stringify({ ...result, promptTruncated: assembled.truncated }) + '\n');

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-10T23:23:57.878Z",
-  "instarVersion": "1.3.483",
+  "generatedAt": "2026-06-11T21:37:39.431Z",
+  "instarVersion": "1.3.485",
   "entryCount": 201,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.484.md

@@ -0,0 +1,37 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Implements Piece 3 (final piece) of `docs/specs/AUTONOMY-PRINCIPLES-ENFORCEMENT-SPEC.md`. The spec-converge skill's external (non-Claude) review pass becomes mandatory with teeth, dynamic, and safe:
+
+- **gemini-cli joins the reviewer registry** (`src/core/crossModelReviewer.ts`) — the registry seam's first extension beyond codex: never-throws detection (binary + cached OAuth at the path the CLI actually reads), provider via the existing factory with its own circuit breaker, identical degraded semantics.
+- **Family-diverse**: one external pass per AVAILABLE family (detect-all), not first-match-only.
+- **Delta-gated**: a content hash of the spec's reviewable body (frontmatter-stripped) decides when externals must re-run — round 1 and any changed round; unchanged rounds record a skip-with-logged-note instead of burning external quota.
+- **Durable activation baseline**: framework availability observations are recorded to `state/framework-activation-history.jsonl`; externals are non-skippable whenever a non-Claude framework was active within a 7-day lookback — deactivating a framework just before converging no longer exempts a spec.
+- **Trusted-provider allowlist**: only first-party OAuth CLIs (codex-cli, gemini-cli) can receive spec text; pi-cli/custom endpoints are structurally excluded (`untrusted-framework` refusal).
+- **Fail-loud model canary**: a review pass degrades loudly (`model-resolution-canary`) rather than silently running with an unresolved tier-word model.
+
+Honest scope notes: the spec's "broken `resolveModelForFramework` foundation" was already fixed on main before this build (recorded at PR #1055); the Claude-only-agent different-family floor + tracked-gap signal are disclosed residuals (see the side-effects artifact).
+
+## What to Tell Your User
+
+- "When I review a spec before building, I now get a second opinion from EVERY non-Claude AI family I have access to (GPT via codex, Gemini via the gemini CLI) — automatically, on every round where the spec actually changed. I can't quietly skip it anymore: a record of which frameworks I've had active in the last week keeps the outside-opinion requirement honest."
+- "Your spec text only ever goes to first-party AI providers you've logged into — never to custom or unknown endpoints."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Gemini external reviewer | Automatic in spec-converge when the gemini CLI is installed + authed |
+| Family-diverse external pass | Automatic — one pass per available family per changed round |
+| Delta-gated externals | Automatic — unchanged rounds log a skip note instead of re-reviewing |
+| 7-day activation baseline | Automatic — recorded on every detection; read at convergence |
+
+## Evidence
+
+- 32 new unit tests (`crossModelReviewer-piece3.test.ts`) + 45 existing (`crossModelReviewer.test.ts`) + 3 integration (`cross-model-review-flow.test.ts`) — all green; `tsc` exit 0; full lint clean.
+- Live smoke on the dev machine: detect-all reported codex-cli:gpt-5.5 AND gemini-cli:gemini-2.5-pro; `--family pi-cli` refused with `untrusted-framework`; the activation observation landed in the JSONL.
+- Independent second-pass review verified the egress allowlist end-to-end and caught a real bug (a `GEMINI_HOME` env var the CLI doesn't actually honor) — fixed before ship.

package/upgrades/1.3.485.md

@@ -0,0 +1,31 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixes the two live bugs from 2026-06-08 testing that left cross-machine dashboard streaming connecting-but-blank with no recovery (POOL-DASHBOARD-STREAM-SPEC, shipped #950–#970):
+
+- **Closed-proxy eviction** (`WebSocketManager.peerProxyFor`): a peer's stream proxy that reached `closed` — after the bounded reconnect failed, or after the 60s idle grace once the last viewer left — stayed cached forever, and a closed proxy silently ignores every later subscribe while the server still answered `subscribed`. One hiccup (or one minute of nobody watching) made that machine permanently unstreamable until a server restart. The get-or-create chokepoint now evicts a closed proxy and opens a fresh episode with its own bounded reconnect budget (P19 no-storm guarantee preserved: reconnects remain one-per-episode, new episodes only on explicit user subscribes).
+- **Cross-machine scrollback** (`history` relay): the terminal-history fetch only ever captured locally — structurally empty for a session owned by another machine. It now relays upstream for remote-subscribed sessions exactly like input/key (spec §2.2: capture happens ONLY on the owning machine), via a new read-only `PeerStreamProxy.relayFrame`; the dashboard client sends `machineId` on history requests for remote tiles.
+- **Honest history miss**: the "no output for session" reply was a sessionless error frame, which the peer fan-out structurally drops; it now carries `session` + `code:'session-not-found'` and renders in the terminal (§2.4 failure honesty).
+
+The serving side of the protocol is unchanged — an updated machine streaming from a not-yet-updated peer degrades to exactly today's behavior at worst. The remote-input default-off security gate is untouched.
+
+## What to Tell Your User
+
+- "Watching one machine's terminal from another machine's dashboard now actually shows the terminal — including scrolling back through its history — and if the link between machines hiccups, clicking the session again recovers it instead of staying dead until a restart."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Remote session scrollback | Automatic — scroll up in any remote session's terminal in the dashboard |
+| Stream recovery after a dropped peer link | Automatic — re-clicking the session tile opens a fresh, bounded connection episode |
+
+## Evidence
+
+- 7 new unit tests (5 behavior + 2 regression guards) across `tests/unit/WebSocketManager.test.ts` and `tests/unit/PeerStreamProxy.test.ts`; each behavior test was run against the UNFIXED code first and failed for the stated reason (missing relayFrame, ignored re-subscribe after closed, sessionless error), then green with the fix.
+- Full unit suite green in the worktree; `pnpm build` clean.
+- Live verification on the real laptop + Mac Mini (a Mini session terminal rendering on the laptop dashboard, then recovery after an induced link drop) — performed post-deploy, results recorded in topic 13481.

package/upgrades/side-effects/cross-model-hardening.md

@@ -0,0 +1,93 @@
+# Side-Effects Review — Cross-Model Convergence Hardening (Autonomy Principles Enforcement, Piece 3)
+
+**Version / slug:** `cross-model-hardening`
+**Date:** `2026-06-10`
+**Author:** `echo`
+**Second-pass reviewer:** `independent reviewer subagent (see appended verdict)`
+
+## Summary of the change
+
+Implements Piece 3 of `docs/specs/AUTONOMY-PRINCIPLES-ENFORCEMENT-SPEC.md`: cross-model convergence becomes **mandatory (with a durable activation baseline), dynamic (no pinning), family-diverse, delta-gated, allowlist-constrained, and fail-loud**. Honest scope note: the spec's headline "broken foundation" claim (`resolveModelForFramework` returning a dead tier string for gemini/pi) was **already fixed on main** before this build — recorded at PR #1055; this PR implements everything else.
+
+- **gemini-cli reviewer registry entry** (`src/core/crossModelReviewer.ts`) — the registry seam's first extension beyond codex: injectable never-throws detection (binary + cached OAuth creds), provider via the existing factory (own circuit breaker), identical degraded semantics.
+- **Family-diverse collection** — `detectAllCrossModelReviewers()` returns ALL available frameworks; the skill now runs one external pass per available family instead of first-match-only.
+- **Delta-gating** — `hashSpecReviewableBody()` (sha256, frontmatter-stripped, CRLF-normalized); externals are mandatory on round 1 + any round where the reviewable body changed; an unchanged round records a skip-with-logged-note (≠ skipped-abbreviated).
+- **Durable activation baseline** — `recordFrameworkActivationObservation()` / `wasNonClaudeFrameworkActiveWithin()` (JSONL at `state/framework-activation-history.jsonl`, 2000-line cap): externals are non-skippable whenever a non-Claude framework was active at any point in a 7-day lookback — a just-before-converge deactivation no longer exempts a spec (round-2 adversarial F-R2-3).
+- **Trusted-provider allowlist** — `TRUSTED_REVIEWER_FRAMEWORKS = ['codex-cli','gemini-cli']`; the registry constructively carries only first-party OAuth CLIs; `--family pi-cli` (or any unlisted id) is refused (`untrusted-framework`) so the full spec text is never sent to a custom/base-URL endpoint.
+- **Fail-loud canary** — `isConcreteReviewerModel()`: both entries degrade LOUDLY (`model-resolution-canary`) rather than silently reviewing with a bare tier word.
+
+Files: `src/core/crossModelReviewer.ts`, `skills/spec-converge/scripts/cross-model-review.mjs`, `skills/spec-converge/SKILL.md`, `tests/unit/crossModelReviewer-piece3.test.ts` (new, 32 tests), hermeticity fixes in 2 existing test files.
+
+## Decision-point inventory
+
+- Cross-model framework detection/selection — **modify** — first-match → all-available (collection only; no blocking authority).
+- `--family` allowlist guard — **add** — hard-invariant refusal of an untrusted framework id at the script edge (egress protection, enumerable set).
+- Externals-mandatory check (SKILL.md + `wasNonClaudeFrameworkActiveWithin`) — **add** — a deterministic read over the durable history that decides whether the SKILL FLOW may skip an external pass. Process-gating inside spec review; blocks no agent action or message.
+- Model canary — **add** — degrades a review pass; blocks nothing.
+
+---
+
+## 1. Over-block
+
+The allowlist refusing `pi-cli` could be seen as over-blocking a legitimate reviewer — deliberate: pi is multi-provider by design (its model flag may resolve to a custom endpoint), and the cost of a wrongly-allowed egress (full spec text to an attacker-controlled model) dwarfs the cost of one fewer reviewer family. The activation lookback could keep externals mandatory for an agent that genuinely uninstalled a framework yesterday — accepted: the 7-day tail is the entire point (anti-gaming), and the pass degrades to advisory-unavailable rather than hard-failing when the framework is truly gone.
+
+## 2. Under-block
+
+The activation history only records when `--detect-only`/review runs execute — an agent that NEVER ran spec-converge in the lookback has an empty history and presents as single-framework. Acceptable: the first detect of the current convergence records the observation, so the gaming window is "deactivate before the FIRST round" — and a genuinely deactivated-everywhere agent degrades to the advisory floor exactly as specced. The history is also local-file mutable by the agent itself (not tamper-proof) — consistent with every other instar state file; the report banner + frontmatter flag remain the human-visible disclosure.
+
+## 3. Level-of-abstraction fit
+
+Correct: detection/selection/hash/history are cheap structural helpers in the existing crossModelReviewer module (the registry's documented extension point); the SKILL owns the flow policy; nothing re-implements the provider factory, circuit breaker, or aggregation (`aggregateRoundOutcomes` unchanged and still computes the spec-level flag).
+
+## 4. Signal vs authority compliance
+
+**Required reference:** docs/signal-vs-authority.md
+
+- [x] No — no block/allow surface over agent behavior or messages. The two refusal points (allowlist, canary) are **hard-invariant validation** over enumerable sets (the principle's explicitly-allowed class — egress protection is the "safety guards on irreversible actions" case). Review outcomes only ever DEGRADE with logged reasons; judgment stays with the reviewers and the convergence process.
+
+## 5. Interactions
+
+- **Back-compat:** `detectCrossModelReviewer` (first-match) and the script's default single-pass mode are unchanged; existing callers/tests pass (hermeticity fixes only — the suite previously assumed gemini absent, false on hosts with gemini installed).
+- **Aggregation:** per-family results feed the existing per-round → spec-level aggregation unchanged; a delta-skip is recorded as a logged note, not a round outcome, so `degraded-all-rounds` semantics are preserved.
+- **Double-fire/races:** the activation JSONL is append-with-cap from a single skill flow; worst case under concurrent convergences is a lost observation line (history is a union-over-time read, so this cannot flip mandatory→optional within the lookback).
+- **Circuit breakers:** each framework keeps its own breaker via the factory — a rate-limited codex degrades that pass; gemini still runs (the family-diversity goal).
+
+## 6. External surfaces
+
+- **LLM egress:** spec text now also flows to gemini (first-party Google OAuth CLI) when available — the same egress class as the existing codex pass, now explicitly allowlist-bounded. No new third-party endpoints; pi/custom endpoints structurally excluded.
+- **Persistent state:** `state/framework-activation-history.jsonl` (capped). No fleet surface: spec-converge remains agent-private (decision recorded in the Piece-2 artifact); no `src/` runtime route/config change — `crossModelReviewer.ts` is library code consumed by the skill script.
+
+## 7. Rollback cost
+
+Revert the commit. The history file is inert if orphaned. No migration, no API, no fleet propagation.
+
+## Conclusion
+
+Piece 3 closes the spec: externals can no longer be quietly skipped (durable 7-day baseline + delta-gating with logged notes), selection is dynamic and family-diverse with zero pinned model names, and the two real security findings from convergence (spec egress to untrusted endpoints; silent dead-model reviews) are structurally closed (allowlist + canary). Verified: tsc clean, full lint clean, 77 unit (45 existing + 32 new) + 3 integration green, live smoke on this host detected both codex + gemini and refused pi-cli. Clear to ship as the final PR of the spec.
+
+---
+
+## Scope disclosure (honest residual)
+
+Two spec clauses are NOT implemented in this PR and are tracked, not orphaned <!-- tracked: CMT-1317 -->: (a) the Claude-only-agent floor reaching a *different-family* model via the subscription-path/provider-registry fallback — a single-framework agent currently gets the honest advisory `unavailable` flag (the pre-existing behavior, loudly disclosed in the report banner), and (b) surfacing "no external family reachable at all" as a HumanAsDetector-style tracked-gap signal rather than the advisory note. Both need provider-registry plumbing that doesn't belong in this hardening pass.
+
+## Second-pass review
+
+**Reviewer:** independent reviewer subagent (verified findings against the actually-installed gemini CLI v0.25.2).
+**Independent read of the artifact: concern raised → all resolved this pass.**
+
+- MUST-FIX (resolved): `GEMINI_HOME` is not a real gemini CLI env var (zero occurrences in the CLI dist; creds are unconditionally `~/.gemini/oauth_creds.json`). Honoring it made detection probe a path the CLI never reads — a false-unavailable would silently skip the gemini pass AND poison the activation baseline with `gemini-cli:false`, the exact suppression Piece 3 prevents. Fixed: env lookup dropped; injectable test seam kept.
+- NICE-TO-HAVE (applied): frontmatter-strip close anchor tightened to a whole-line fence (`\n---(\n|$)`) so `--- text`/`----` inside the block can't terminate the strip mid-line.
+- INFORMATIONAL (applied anyway): `wasNonClaudeFrameworkActiveWithin` now counts only TRUSTED reviewer framework ids, so a stray `{"claude-code":true}` line can't flip the externals-mandatory decision.
+- HONESTY (applied): the scope disclosure above was added at the reviewer's prompting — the artifact previously implied full Piece-3 coverage.
+- Confirmed clean: `--family` allowlist guard sits before any detect/provider call; no path (default, detect-all, or detectionOverride) can route spec text to a non-registry framework — the registry⊆allowlist invariant is itself unit-tested; `buildIntelligenceProvider({framework:'gemini-cli'})` cannot reach a custom base-URL (allowlisted child env); refresh-token-only IS authed for this CLI; the canary precedes provider construction in both entries; the 2000-line cap keeps the most recent lines; the reader never throws on corruption; the existing-test edits weaken no assertion.
+
+After fixes: tsc exit 0, 77/77 unit + 3/3 integration green.
+
+---
+
+## Evidence pointers
+
+- `tests/unit/crossModelReviewer-piece3.test.ts` (32): gemini detect triad, detect-all cardinality, canary accept/reject, hash frontmatter/CRLF stability, activation write/read/lookback/corrupt-line/cap, allowlist, gemini degraded paths.
+- Live smoke: `--detect-only --state-dir` → codex-cli:gpt-5.5 + gemini-cli:gemini-2.5-pro both detected + observation written; `--family pi-cli` → `untrusted-framework`; `--hash-only` → stable hash.
+- `npx tsc --noEmit` exit 0; `npm run lint` exit 0.

package/upgrades/side-effects/pool-stream-cross-machine-fix.md

@@ -0,0 +1,94 @@
+# Side-Effects Review — Pool Dashboard Streaming: cross-machine history relay + closed-proxy recovery
+
+**Version / slug:** `pool-stream-cross-machine-fix`
+**Date:** `2026-06-11`
+**Author:** `echo (instar-dev agent)`
+**Second-pass reviewer:** `not required` (no block/allow surface on messaging/dispatch, no session lifecycle, no sentinel/gate/watchdog logic — see Phase-5 assessment in Conclusion)
+
+## Summary of the change
+
+Fixes the two live bugs found during 2026-06-08 live testing of Pool Dashboard Streaming (POOL-DASHBOARD-STREAM-SPEC, converged-approved 2026-06-06), which left a remote (Mac Mini) session tile connecting but rendering a blank terminal, with no recovery until server restart:
+
+1. **Closed-proxy eviction** (`src/server/WebSocketManager.ts` → `peerProxyFor`): a `PeerStreamProxy` that reached `closed` (idle-grace close after the last viewer left, or `machine-unreachable` after the bounded reconnect failed) stayed cached in `peerProxies` forever. A closed proxy ignores every further subscribe by design, while the subscribe handler still answered `subscribed` — so one upstream hiccup (or 60s of nobody watching) made that peer permanently unstreamable, silently. `peerProxyFor` now evicts a closed proxy and creates a fresh one; a fresh user-initiated subscribe is a fresh episode with its own bounded reconnect budget (P19 preserved).
+2. **Cross-machine history relay** (`src/server/WebSocketManager.ts` `history` case, `src/server/PeerStreamProxy.ts` `relayFrame`, `dashboard/index.html` `loadMoreHistory`): the scrollback fetch (`{type:'history'}`) had no remote branch — it always called local `captureOutput`, which can only return empty for a session owned by another machine (spec §2.2: capture happens ONLY on the owning machine). The handler now relays history upstream for a remote-subscribed session exactly like input/key, the proxy gained a read-only `relayFrame` (relayInput delegates to it), and the dashboard client sends `machineId` on history requests for remote sessions.
+3. **Relayable history miss** (same `history` case): the local "no output" reply was `{type:'error', message}` with NO session field — the peer fan-out drops sessionless frames, so the error could never travel. It now carries `session` + `code:'session-not-found'`, which the dashboard already renders honestly (§2.4).
+
+Files: `src/server/WebSocketManager.ts`, `src/server/PeerStreamProxy.ts`, `dashboard/index.html`, `tests/unit/WebSocketManager.test.ts`, `tests/unit/PeerStreamProxy.test.ts`.
+
+## Decision-point inventory
+
+- `WebSocketManager.peerProxyFor` — modify — get-or-create now evicts a `closed` proxy; routing decision (which proxy serves a peer), not a block/allow decision.
+- `WebSocketManager.handleMessage 'history'` — modify — adds the remote-routing branch (same shape as the existing `input`/`key` remote branches); read-only data fetch, no authority.
+- `PeerStreamProxy.relayFrame` — add — forwards a read-only frame while the link is active; drops otherwise (same drop semantics relayInput always had).
+- `gateWrite` (remote input authority, `poolStreamAllowRemoteInput`) — **pass-through, untouched** — history is read-only and never reaches `gateWrite`; the input default-off security gate is not modified by this change.
+- Stream ticket auth (`StreamTicketStore`, `/pool-stream` upgrade) — **pass-through, untouched**.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No issue identified. The change adds no new rejection. The history remote branch only triggers when the client explicitly sent a `machineId` AND that client already holds a live remote subscription for exactly that `(machine, session)` pair (`client.remoteSubs.has(...)`) — a history request for a never-subscribed remote session falls through to the local path and answers `session-not-found`, which is the honest answer (you cannot scroll back a session you are not watching). Local history requests (no machineId) are byte-for-byte unchanged.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- A history request relayed while the upstream is `connecting` (mid-reconnect) is dropped, not queued — the user's infinite-scroll simply doesn't load that batch and re-fires on the next scroll (the client re-requests on scroll position). Stale queued requests racing a reconnect would be worse. Accepted, documented in `relayFrame`'s contract.
+- The history reply fans to EVERY local client subscribed to that (machine, session), not just the requester — same multiplexing behavior the spec defines for all frames (§2.2 "frames relay 1:1"); clients gate rendering on `activeSession`, so a non-requesting viewer at most refreshes its scrollback.
+- The 2026-06-07 mint-timeout failure class (wedged ticket mint) is already handled by the explicit 10s timeout shipped in #970, upstream of this change.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The history relay is placed at exactly the layer the spec assigned it: the SUBSCRIBE-side routing chokepoint in `WebSocketManager.handleMessage`, parallel to the existing `input`/`key` remote branches — not a new parallel path. `relayFrame` lives in `PeerStreamProxy` because that class owns "is the upstream link usable" state; the manager owns "is this session remote for this client" state. The eviction lives in `peerProxyFor` (the single get-or-create chokepoint) rather than inside the proxy (e.g. a self-reopening proxy), keeping the proxy's one-shot bounded-reconnect state machine — and its P19 guarantee — untouched.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no block/allow surface.
+
+The change is pure data-plane plumbing (routing read-only frames to the machine that owns the data, and replacing a dead connection object). The ONLY authority in this subsystem — the serving machine's `poolStreamAllowRemoteInput` gate on remote keystrokes — is not touched, weakened, or bypassed: history never reaches `gateWrite` because it is a read, and reads were already permitted to any authenticated peer link (the initial subscribe capture has always shipped full screen content to the peer). No new information becomes visible to any principal that could not already see it.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** the remote history branch runs BEFORE the local capture path, gated on `client.remoteSubs` — the local path is unreachable only for sessions the client explicitly subscribed remotely, which is exactly the set local capture could never serve (it returned null for them). Nothing that previously worked is shadowed.
+- **Double-fire:** none — a history request takes exactly one branch (remote XOR local). Eviction cannot double-open: `peerProxyFor` is synchronous, and only a `closed` proxy (no live transport, no pending timers except a fired/cleared one) is evicted, so no second live upstream to the same peer can exist.
+- **Races:** a client disconnect between failAll and re-subscribe calls `dropRemoteSubsForClient`, which looks up the CURRENT map entry — if eviction already replaced the proxy, the unsubscribe lands on the fresh proxy where `unsubscribe()` of an unknown clientId is a documented no-op. An old evicted proxy holds no timers and no transport (failAll/idle-close tear both down), so it is plain garbage, not a leak.
+- **Feedback loops:** none — the eviction does not auto-reconnect; it only acts on the next explicit user subscribe, so a permanently-down peer costs one bounded reconnect cycle per user click, never a storm.
+
+---
+
+## 6. External surfaces
+
+- **Other machines:** the serving side of the protocol is UNCHANGED — an updated laptop streaming from a not-yet-updated Mini works (the Mini's serving side always answered history requests arriving on a peer link; the bug was the laptop never sending them). Mixed-version fleets degrade to exactly today's behavior at worst.
+- **Protocol:** no new frame types; `history` was already in the documented protocol and in `UpstreamTransport.send`'s doc comment ("subscribe/unsubscribe/input/key/history"). The local history-miss error gains `code` + `session` fields (additive; the dashboard's existing `error` handler renders `code`-carrying frames and still `console.error`s unknown shapes).
+- **Persistent state:** none touched. No config, no migrations, no ledgers.
+- **Timing:** `relayFrame` depends on the upstream being `active` — bounded, observable via the existing `[pool-stream-connector]` log lines.
+
+---
+
+## 7. Rollback cost
+
+Pure code change in three files with no persistent state: revert the commit, ship as the next patch. During a rollback window the symptom is exactly the pre-fix behavior (blank remote scrollback, no post-hiccup recovery) — degraded, not destructive. No data migration, no agent state repair, no template/hook migration (dashboard/index.html ships in the npm package and replaces wholesale on update).
+
+---
+
+## Conclusion
+
+Review produced one design adjustment: the local history-miss error was originally left sessionless; the relay analysis (§5 fan-out drops sessionless frames) surfaced that it could never travel cross-machine, so it now carries `session` + `code` — that is also what makes the dashboard render it honestly instead of burying it in the console. Phase-5 second-pass assessment: the change touches none of the listed high-risk surfaces (no outbound/inbound messaging block decisions, no session spawn/restart/kill/recovery, no compaction, no coherence gates/idempotency/trust, no sentinel/guard/gate/watchdog logic — the one gate in this subsystem, remote-input default-off, is untouched pass-through), so a dedicated reviewer subagent is not required; the artifact stands on the three-tier test evidence. Clear to ship.
+
+**Phase 1 principle check (recorded):** the change involves no new decision point that gates information flow or constrains behavior — it repairs the data plane of an approved feature to match its converged spec (§2.2 capture-on-owner, §2.4 failure honesty, P19 bounded reconnect). Signal-vs-authority applies as a constraint check only: confirmed no brittle logic gained blocking authority.
+
+**Phase 2 plan (recorded):** built in a FRESH worktree `.worktrees/fix-pool-stream-cross-machine` off `JKHeadley/main` @ `60c4e3a3c` (v1.3.484), canonical remote verified (`JKHeadley → github.com/JKHeadley/instar.git`), per-worktree identity `Instar Agent (echo) <echo@instar.local>`. Acceptance criteria: (a) new unit tests fail on unfixed code for the stated reasons — verified (5 failures: missing relayFrame ×2, ignored re-subscribe ×2 → silent blank, sessionless error ×1); (b) all green with fix; (c) full suite green; (d) live verify on the real laptop+Mini after deploy. Rollback: revert commit (see §7).