agent-tempo 1.7.0-beta.11 → 1.7.0-beta.13

package/dashboard/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-tempo-dashboard",
   "private": true,
-  "version": "1.7.0-beta.11",
+  "version": "1.7.0-beta.13",
   "type": "module",
   "description": "Web dashboard for agent-tempo. Bundled into the npm package; served by the daemon at /dashboard/*.",
   "scripts": {

package/dist/activities/outbox.js

@@ -46,6 +46,7 @@ const git_info_1 = require("../git-info");
 const spawn_1 = require("../spawn");
 const config_2 = require("../config");
 const resolve_1 = require("./resolve");
+const visibility_deadline_1 = require("../utils/visibility-deadline");
 const action_counters_1 = require("../utils/action-counters");
 const search_attributes_1 = require("../utils/search-attributes");
 const agent_types_1 = require("../ensemble/agent-types");
@@ -86,6 +87,15 @@ function isRetryableTemporalError(err) {
     // to call unconditionally.
     if (err instanceof activity_1.ApplicationFailure)
         return false;
+    // #845 Mode A: a truncated visibility scan (resolveSession's deadline
+    // tripped mid-scan, #336/#529) is a LATENCY failure — the target may well
+    // exist; the scan just didn't finish. Treat it as transient so the
+    // activity retry policy re-runs resolveSession with a fresh 10s deadline
+    // (backoff-bounded) instead of collapsing it into a permanent
+    // "No active session found". This must NOT re-add an in-resolver retry
+    // loop — the bounding lives in Temporal's policy, not a hot-path scan.
+    if ((0, visibility_deadline_1.isVisibilityTimeout)(err))
+        return true;
     const e = err;
     const name = e?.name ?? '';
     const msg = e?.message ?? '';

package/dist/activities/resolve.d.ts

@@ -1,5 +1,13 @@
 import { Client, WorkflowHandle } from '@temporalio/client';
 import { AttachmentPhase } from '../types';
+/**
+ * Mode-B describe-by-id timeout (#845). The strongly-consistent
+ * `describe()` fallback on `resolveSession`'s not-found branch is a single
+ * O(1) RPC; 2s mirrors {@link DEFAULT_QUERY_TIMEOUT_MS} — two orders of
+ * magnitude over a healthy describe — so a wedged frontend can't re-hang
+ * the outbox loop the visibility deadline (#336/#529) was added to bound.
+ */
+export declare const RESOLVE_DESCRIBE_TIMEOUT_MS = 2000;
 /** Shared query for listing running session workflows. Exported for the
  *  ensemble-scoped variants in `client/core.ts` (#751). */
 export declare const SESSION_LIST_QUERY = "WorkflowType = \"agentSessionWorkflow\" AND ExecutionStatus = \"Running\"";
@@ -18,15 +26,36 @@ export declare const SESSION_LIST_QUERY = "WorkflowType = \"agentSessionWorkflow
  * in `scanEnsembleSessionsCloud`. Enforced by
  * tests/conformance/decision-path-fence.test.ts.
  *
- * **Deadline (#336/#529):** the visibility iterator is bounded by
- * `VISIBILITY_DEADLINES_MS.resolveSession` (default 10s). On timeout,
- * throws `VisibilityIteratorTimeoutError` rather than returning `null`
- * — silent `null` on a partially-scanned set would be indistinguishable
- * from "definitely not found," producing false "Player not found" errors
- * upstream. Every existing caller wraps this in a try/catch (outbox
- * activities, MCP tools' `defineTool` helper, CLI dev-verbs); the throw
- * propagates as a retryable / user-visible "lookup timed out" rather
- * than the misleading "player not found."
+ * **Mode A — deadline truncation (#336/#529):** the visibility iterator is
+ * bounded by `VISIBILITY_DEADLINES_MS.resolveSession` (default 10s). On
+ * timeout it throws `VisibilityIteratorTimeoutError` rather than returning
+ * `null` — silent `null` on a partially-scanned set would be
+ * indistinguishable from "definitely not found." The throw is classified
+ * **retryable** by the outbox activity (`isRetryableTemporalError`), so
+ * Temporal's activity retry policy re-runs the lookup with a fresh
+ * deadline rather than collapsing it to a permanent "player not found."
+ * Synchronous tool/CLI callers surface it as a distinct "resolution
+ * incomplete — retry," never "not found."
+ *
+ * **Mode B — visibility-index lag (#845):** `list()` can complete normally
+ * (no throw) yet miss a freshly-started workflow because the visibility
+ * index trails the workflow store (observed live as a 3/8→8/8 roster
+ * during post-restart worker warmup). An early-exhausting scan is NOT
+ * proof of absence. So on the not-found branch we do **exactly one**
+ * strongly-consistent `describe()` against the *derived* workflow id —
+ * an O(1) read by primary key that bypasses the lagging index. This is a
+ * point lookup, NOT a re-scan: it cannot re-introduce the unbounded-scan
+ * hang the deadline guard was added to prevent.
+ *
+ * **Documented Mode-B limitation:** the derived id
+ * `agent-session-{ensemble}-{playerName}` is minted from a player's
+ * INITIAL name at spawn; `set_name` does not change the workflow id. So
+ * describe-by-derived-id false-negatives for a player that was both
+ * RENAMED and is currently index-lagged — it falls back to `null` (looks
+ * absent) for that narrow intersection. Accepted by design: it closes the
+ * gap for the cold-boot/warmup incident class (nobody renames mid-boot),
+ * and a second full re-scan to cover renamed∩lagged would put scan cost on
+ * every genuine typo'd-name lookup. See issue #845.
  */
 export declare function resolveSession(client: Client, ensemble: string, playerName: string): Promise<WorkflowHandle | null>;
 /** Info returned for each session by scanEnsembleSessions. */
@@ -82,19 +111,55 @@ export interface EnsembleSessionInfo {
  */
 export declare function scanEnsembleSessionsCloud(client: Client, ensemble: string, log?: (...args: unknown[]) => void): Promise<EnsembleSessionInfo[]>;
 /**
- * Scan all running session workflows in an ensemble.
- * Returns metadata + part for each session. Shared by the ensemble MCP tool
- * and the Maestro refresh activity.
+ * Result of {@link scanEnsembleSessionsWithStatus} — the session rows plus
+ * whether the visibility scan completed or was cut short (#845).
+ *
+ * `truncated` is the Mode-A signal: a `VisibilityIteratorTimeoutError`
+ * fired (the wall-clock deadline tripped mid-scan), so `sessions` is a
+ * partial snapshot, NOT the full roster. Callers that render a roster (the
+ * `ensemble` tool) MUST surface this so a partial set is never mistaken
+ * for a complete one. NOTE: this does NOT cover Mode B (visibility-index
+ * lag) — there the scan completes normally and `truncated` is `false` even
+ * though a freshly-started workflow may be missing; that's best-effort by
+ * design and self-heals on the next tick.
+ *
+ * `scanned` is the number of running workflows the iterator visited before
+ * completing or timing out — useful for warn logs ("partial: 3 of ≥N").
+ */
+export interface EnsembleScanResult {
+    sessions: EnsembleSessionInfo[];
+    truncated: boolean;
+    scanned: number;
+}
+/**
+ * Scan all running session workflows in an ensemble, reporting whether the
+ * scan completed or was truncated by the visibility deadline (#845).
+ *
+ * This is the single source of truth for the local-profile ensemble scan;
+ * {@link scanEnsembleSessions} is a thin array-facade over it that drops
+ * the status fields for the many callers that don't need them.
  *
  * **Deadline (#336/#529):** the iterator is bounded by
- * `VISIBILITY_DEADLINES_MS.scanEnsembleSessions` (default 15s). On
- * timeout, returns the partial result accumulated so far and emits a
- * warn log. This site is **partial-tolerant by design** — the caller
- * (maestro refresh, ensemble MCP tool) treats the result as a
- * best-effort snapshot that the next tick / re-invocation will fill in.
+ * `VISIBILITY_DEADLINES_MS.scanEnsembleSessions` (default 15s). On timeout
+ * the accumulated rows are returned with `truncated: true` and a warn log
+ * — the scan is **partial-tolerant by design**, but the truncation is now
+ * SIGNALLED rather than silent so a roster renderer can flag it.
  *
  * T0.1 (#748): this legacy shape is the `costProfile: 'local'` path —
- * byte-identical to pre-#748 behavior. The cloud profile uses
+ * byte-identical row data to pre-#748 behavior. The cloud profile uses
  * {@link scanEnsembleSessionsCloud}.
  */
+export declare function scanEnsembleSessionsWithStatus(client: Client, ensemble: string, log?: (...args: unknown[]) => void): Promise<EnsembleScanResult>;
+/**
+ * Scan all running session workflows in an ensemble — array facade over
+ * {@link scanEnsembleSessionsWithStatus}.
+ *
+ * Returns just the session rows; the truncation/scan-status fields are
+ * dropped. This is the byte-identical shape the maestro refresh activity,
+ * the #785 upgrade-snapshot, and the other roster consumers already depend
+ * on — keeping it a thin delegate means the truncation-signalling work
+ * (#845) does NOT ripple through those call sites. Callers that need to
+ * know whether the scan was complete (the `ensemble` tool) call the rich
+ * sibling directly.
+ */
 export declare function scanEnsembleSessions(client: Client, ensemble: string, log?: (...args: unknown[]) => void): Promise<EnsembleSessionInfo[]>;

package/dist/activities/resolve.js

@@ -1,13 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SESSION_LIST_QUERY = void 0;
+exports.SESSION_LIST_QUERY = exports.RESOLVE_DESCRIBE_TIMEOUT_MS = void 0;
 exports.resolveSession = resolveSession;
 exports.scanEnsembleSessionsCloud = scanEnsembleSessionsCloud;
+exports.scanEnsembleSessionsWithStatus = scanEnsembleSessionsWithStatus;
 exports.scanEnsembleSessions = scanEnsembleSessions;
+const config_1 = require("../config");
 const search_attributes_1 = require("../utils/search-attributes");
 const signals_1 = require("../workflows/signals");
 const query_timeout_1 = require("../utils/query-timeout");
 const visibility_deadline_1 = require("../utils/visibility-deadline");
+/**
+ * Mode-B describe-by-id timeout (#845). The strongly-consistent
+ * `describe()` fallback on `resolveSession`'s not-found branch is a single
+ * O(1) RPC; 2s mirrors {@link DEFAULT_QUERY_TIMEOUT_MS} — two orders of
+ * magnitude over a healthy describe — so a wedged frontend can't re-hang
+ * the outbox loop the visibility deadline (#336/#529) was added to bound.
+ */
+exports.RESOLVE_DESCRIBE_TIMEOUT_MS = 2000;
 /** Shared query for listing running session workflows. Exported for the
  *  ensemble-scoped variants in `client/core.ts` (#751). */
 exports.SESSION_LIST_QUERY = `WorkflowType = "agentSessionWorkflow" AND ExecutionStatus = "Running"`;
@@ -26,15 +36,36 @@ exports.SESSION_LIST_QUERY = `WorkflowType = "agentSessionWorkflow" AND Executio
  * in `scanEnsembleSessionsCloud`. Enforced by
  * tests/conformance/decision-path-fence.test.ts.
  *
- * **Deadline (#336/#529):** the visibility iterator is bounded by
- * `VISIBILITY_DEADLINES_MS.resolveSession` (default 10s). On timeout,
- * throws `VisibilityIteratorTimeoutError` rather than returning `null`
- * — silent `null` on a partially-scanned set would be indistinguishable
- * from "definitely not found," producing false "Player not found" errors
- * upstream. Every existing caller wraps this in a try/catch (outbox
- * activities, MCP tools' `defineTool` helper, CLI dev-verbs); the throw
- * propagates as a retryable / user-visible "lookup timed out" rather
- * than the misleading "player not found."
+ * **Mode A — deadline truncation (#336/#529):** the visibility iterator is
+ * bounded by `VISIBILITY_DEADLINES_MS.resolveSession` (default 10s). On
+ * timeout it throws `VisibilityIteratorTimeoutError` rather than returning
+ * `null` — silent `null` on a partially-scanned set would be
+ * indistinguishable from "definitely not found." The throw is classified
+ * **retryable** by the outbox activity (`isRetryableTemporalError`), so
+ * Temporal's activity retry policy re-runs the lookup with a fresh
+ * deadline rather than collapsing it to a permanent "player not found."
+ * Synchronous tool/CLI callers surface it as a distinct "resolution
+ * incomplete — retry," never "not found."
+ *
+ * **Mode B — visibility-index lag (#845):** `list()` can complete normally
+ * (no throw) yet miss a freshly-started workflow because the visibility
+ * index trails the workflow store (observed live as a 3/8→8/8 roster
+ * during post-restart worker warmup). An early-exhausting scan is NOT
+ * proof of absence. So on the not-found branch we do **exactly one**
+ * strongly-consistent `describe()` against the *derived* workflow id —
+ * an O(1) read by primary key that bypasses the lagging index. This is a
+ * point lookup, NOT a re-scan: it cannot re-introduce the unbounded-scan
+ * hang the deadline guard was added to prevent.
+ *
+ * **Documented Mode-B limitation:** the derived id
+ * `agent-session-{ensemble}-{playerName}` is minted from a player's
+ * INITIAL name at spawn; `set_name` does not change the workflow id. So
+ * describe-by-derived-id false-negatives for a player that was both
+ * RENAMED and is currently index-lagged — it falls back to `null` (looks
+ * absent) for that narrow intersection. Accepted by design: it closes the
+ * gap for the cold-boot/warmup incident class (nobody renames mid-boot),
+ * and a second full re-scan to cover renamed∩lagged would put scan cost on
+ * every genuine typo'd-name lookup. See issue #845.
  */
 async function resolveSession(client, ensemble, playerName) {
     for await (const wf of (0, visibility_deadline_1.iterateWithDeadline)(client.workflow.list({ query: exports.SESSION_LIST_QUERY }), visibility_deadline_1.VISIBILITY_DEADLINES_MS.resolveSession, 'resolveSession')) {
@@ -49,16 +80,77 @@ async function resolveSession(client, ensemble, playerName) {
             }
         }
         catch (err) {
-            // Re-throw deadline timeouts — callers that wrap us in try/catch
-            // already treat unknown throws as a soft "lookup failed" path,
-            // and the typed error name makes the failure mode legible in
-            // outbox logs / user-facing tool errors.
+            // Re-throw deadline timeouts (Mode A) — callers that wrap us in
+            // try/catch treat the typed throw as a soft "lookup timed out" path,
+            // distinct from the not-found `null` below.
             if ((0, visibility_deadline_1.isVisibilityTimeout)(err))
                 throw err;
             // Workflow may have just completed, or worker is wedged (#433) — skip
         }
     }
-    return null;
+    // Mode B (#845): the scan completed without a match, but the visibility
+    // index may simply be lagging a just-started workflow. One strongly-
+    // consistent describe-by-derived-id disambiguates "index lag" from
+    // "genuinely absent" without a second scan.
+    return resolveByDerivedId(client, ensemble, playerName);
+}
+/**
+ * Mode-B (#845) strongly-consistent fallback for {@link resolveSession}.
+ *
+ * Reads the session workflow by its *derived* id
+ * (`agent-session-{ensemble}-{playerName}`) via a single bounded
+ * `describe()` — a primary-key lookup that bypasses the eventually-
+ * consistent visibility index. Returns the handle whenever the execution
+ * is `RUNNING`; otherwise `null` (genuinely absent, terminated/completed,
+ * renamed-false-negative, or describe timed out).
+ *
+ * Deliberately RUNNING-only — NO attachment-phase filter (#845 JC2): a
+ * `gone` player has a LIVE workflow with a terminal adapter, which the
+ * #822/#834 deliverability contract handles as warn-but-queue, not
+ * "not found". Filtering it here would regress #834 for the lagged-gone
+ * window and diverge from the main scan loop (which has no phase filter).
+ */
+async function resolveByDerivedId(client, ensemble, playerName) {
+    let timer;
+    try {
+        // `getHandle` is a lazy, no-RPC handle construction in the real client;
+        // kept inside the try purely so a defensive throw can never escape the
+        // fallback (it must only ever upgrade a null to a handle, never error).
+        const handle = client.workflow.getHandle((0, config_1.sessionWorkflowId)(ensemble, playerName));
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error('describe-by-id timed out')), exports.RESOLVE_DESCRIBE_TIMEOUT_MS);
+            timer.unref?.();
+        });
+        const desc = await Promise.race([handle.describe(), timeout]);
+        // Only a live (RUNNING) execution is a valid resolve target. A
+        // COMPLETED/TERMINATED latest run at this id means the player is gone,
+        // or the id was reused by a since-closed run → null. A RUNNING run
+        // under a reused id is legitimately the current player → return it.
+        //
+        // No attachment-phase filter (#845 JC2, architect ruling): the main
+        // scan loop returns the handle for ANY running session — phase=`gone`
+        // included — and #822/#834 treat `gone` as warn-but-QUEUE (the cue
+        // durably queues and auto-redelivers on re-attach), NOT "not found".
+        // Returning null for a lagged-`gone` player would bypass #822, re-
+        // introduce the false-not-found #834 fixed, and make resolution depend
+        // on visibility-index timing. The "don't deliver to a torn-down
+        // adapter" concern lives at the deliverability layer, not here.
+        if (desc.status.name !== 'RUNNING')
+            return null;
+        return handle;
+    }
+    catch {
+        // NotFound → genuinely absent (or the renamed∩lagged false-negative
+        // documented on resolveSession). Timeout/other → treat as absent; the
+        // caller's not-found path (or the activity retry policy for Mode A)
+        // handles it. We never throw from the fallback — it can only upgrade a
+        // null to a found handle, never turn a clean lookup into an error.
+        return null;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
 }
 /**
  * T0.1 (#748) — cloud-profile ensemble scan. Observation path ONLY (see the
@@ -162,25 +254,30 @@ async function scanEnsembleSessionsCloud(client, ensemble, log = () => { }) {
     return sessions;
 }
 /**
- * Scan all running session workflows in an ensemble.
- * Returns metadata + part for each session. Shared by the ensemble MCP tool
- * and the Maestro refresh activity.
+ * Scan all running session workflows in an ensemble, reporting whether the
+ * scan completed or was truncated by the visibility deadline (#845).
+ *
+ * This is the single source of truth for the local-profile ensemble scan;
+ * {@link scanEnsembleSessions} is a thin array-facade over it that drops
+ * the status fields for the many callers that don't need them.
  *
  * **Deadline (#336/#529):** the iterator is bounded by
- * `VISIBILITY_DEADLINES_MS.scanEnsembleSessions` (default 15s). On
- * timeout, returns the partial result accumulated so far and emits a
- * warn log. This site is **partial-tolerant by design** — the caller
- * (maestro refresh, ensemble MCP tool) treats the result as a
- * best-effort snapshot that the next tick / re-invocation will fill in.
+ * `VISIBILITY_DEADLINES_MS.scanEnsembleSessions` (default 15s). On timeout
+ * the accumulated rows are returned with `truncated: true` and a warn log
+ * — the scan is **partial-tolerant by design**, but the truncation is now
+ * SIGNALLED rather than silent so a roster renderer can flag it.
  *
  * T0.1 (#748): this legacy shape is the `costProfile: 'local'` path —
- * byte-identical to pre-#748 behavior. The cloud profile uses
+ * byte-identical row data to pre-#748 behavior. The cloud profile uses
  * {@link scanEnsembleSessionsCloud}.
  */
-async function scanEnsembleSessions(client, ensemble, log = () => { }) {
+async function scanEnsembleSessionsWithStatus(client, ensemble, log = () => { }) {
     const sessions = [];
+    let truncated = false;
+    let scanned = 0;
     try {
         for await (const workflow of (0, visibility_deadline_1.iterateWithDeadline)(client.workflow.list({ query: exports.SESSION_LIST_QUERY }), visibility_deadline_1.VISIBILITY_DEADLINES_MS.scanEnsembleSessions, 'scanEnsembleSessions')) {
+            scanned++;
             try {
                 const handle = client.workflow.getHandle(workflow.workflowId);
                 // Issue #433 — bound the metadata + part queries so a single wedged
@@ -234,11 +331,27 @@ async function scanEnsembleSessions(client, ensemble, log = () => { }) {
     }
     catch (err) {
         if ((0, visibility_deadline_1.isVisibilityTimeout)(err)) {
+            truncated = true;
             log(`scanEnsembleSessions: ${err.message} — returning partial (${sessions.length} sessions)`);
         }
         else {
             throw err;
         }
     }
-    return sessions;
+    return { sessions, truncated, scanned };
+}
+/**
+ * Scan all running session workflows in an ensemble — array facade over
+ * {@link scanEnsembleSessionsWithStatus}.
+ *
+ * Returns just the session rows; the truncation/scan-status fields are
+ * dropped. This is the byte-identical shape the maestro refresh activity,
+ * the #785 upgrade-snapshot, and the other roster consumers already depend
+ * on — keeping it a thin delegate means the truncation-signalling work
+ * (#845) does NOT ripple through those call sites. Callers that need to
+ * know whether the scan was complete (the `ensemble` tool) call the rich
+ * sibling directly.
+ */
+async function scanEnsembleSessions(client, ensemble, log = () => { }) {
+    return (await scanEnsembleSessionsWithStatus(client, ensemble, log)).sessions;
 }

package/dist/cli/commands.js

@@ -65,6 +65,7 @@ const croner_1 = require("croner");
 const client_1 = require("@temporalio/client");
 const spawn_1 = require("../spawn");
 const probe_1 = require("../pi/probe");
+const install_1 = require("../pi/install");
 const config_1 = require("../config");
 const git_info_1 = require("../git-info");
 const connection_1 = require("../connection");
@@ -1318,10 +1319,33 @@ async function up(opts) {
         if (!process.env.ANTHROPIC_API_KEY) {
             out.warn('ANTHROPIC_API_KEY is not set — the Pi conductor will fall back to Pi\'s own auth/default model. Set it if Pi needs an Anthropic key.');
         }
+        // #825 — extension-registration guard (mirrors command-center's #820 Bug-2
+        // guard). `up --agent pi` no longer passes an inline `-e` (that risked a
+        // divergent-copy double-load, #825); it now relies on the player extension
+        // being registered in Pi's settings.json. On a box that never ran `install-pi`,
+        // a plain `pi` would launch with NO extension — no claim/heartbeat, a silent
+        // non-conductor (the #820 Bug-2 failure, transplanted to the conductor). So
+        // auto-install idempotently before spawning; fail loud with the manual command
+        // if the write fails. (Checks the GLOBAL settings.json, like command-center; a
+        // user who ran `install-pi --project` still works — `pi` loads the project
+        // path and the same realpath dedupes, so the redundant global install is a
+        // harmless idempotent write, never a second load.)
+        if (!(0, install_1.arePiExtensionsRegistered)()) {
+            try {
+                const result = (0, install_1.installPiExtensions)();
+                out.log(out.dim(`  Registered the Pi extensions in ${result.settingsPath} (first-run install-pi).`));
+            }
+            catch (err) {
+                out.error('Cannot start Pi conductor — the Pi extensions are not registered and auto-install failed: ' +
+                    `${err instanceof Error ? err.message : String(err)}. Run \`agent-tempo install-pi\` manually, then retry.`);
+                process.exit(1);
+            }
+        }
         let piSpawn;
         try {
-            // resolvePiInteractiveBinary / resolvePiExtensionPath throw fail-clean
-            // (Pi CLI missing / extension unbuilt) — caught here, no terminal launched.
+            // resolvePiInteractiveBinary throws fail-clean (Pi CLI missing) — caught
+            // here, no terminal launched. #825: no more `-e`/extension resolution — the
+            // player extension loads from settings.json, registered + guarded just above.
             piSpawn = (0, spawn_1.buildPiConductorSpawn)({
                 ensemble: opts.ensemble,
                 sessionName,

package/dist/client/subscribe.d.ts

@@ -81,6 +81,16 @@ export interface SubscribeDeps {
      * present (Node 20), the wrapper falls back to fetch.
      */
     EventSourceImpl?: typeof EventSource;
+    /**
+     * #826 — force the fetch transport even when a native `EventSource` is
+     * available and no token is set. The fetch path is the only one that
+     * surfaces a permanent **401/404** as a thrown {@link SubscribeHttpError};
+     * native `EventSource` swallows those into its own silent reconnect cycle.
+     * The mission-control board needs that hard-error visibility (404 → `gone`,
+     * 401 → auth hint), so it sets this. TUI / dashboard leave it unset and keep
+     * the auto-selection (native `EventSource` on a tokenless loopback board).
+     */
+    forceFetch?: boolean;
     /**
      * Override sleep — used by tests to fast-forward backoff. Accepts an
      * `AbortSignal` so the wrapper can wake early on abort.

package/dist/client/subscribe.js

@@ -216,6 +216,8 @@ function makeIterator(args) {
  * for `Authorization: Bearer …` and is the only option in Node 20.
  */
 function canUseEventSource(deps) {
+    if (deps.forceFetch)
+        return false; // #826 — caller needs throw-on-permanent
     if (deps.token)
         return false;
     return resolveEventSource(deps) !== undefined;

package/dist/pi/mission-control/board.d.ts

@@ -41,14 +41,15 @@ export declare const DEFAULT_TAIL_LIMIT = 200;
  *
  * - `'connecting'` — initial / post-rebind, before the first coarse event lands.
  * - `'live'` — at least one coarse event has arrived on the current connection.
- * - `'reconnecting'` — the coarse stream ENDED (a non-404 error, a 401, or a
- *   defensive normal-end) and the loop has exited. Rows are KEPT (rendered stale,
- *   not cleared). NOTE (#827 review): this is terminal-until-rebind today — the
- *   stream does NOT auto-resubscribe (genuine transient blips are swallowed
- *   INSIDE `createSubscribe`, so the board stays `'live'` through them). The
- *   renderer therefore labels it "STREAM ENDED … reopens on re-bind", not
- *   "reconnecting". Auto-re-arm with backoff is tracked in #828; restore the
- *   reconnecting wording if/when the loop re-subscribes on this transition.
+ * - `'reconnecting'` — the coarse stream ended OR went silent past the watchdog
+ *   threshold (#826), and the board is RE-ARMING. Rows are KEPT (rendered stale,
+ *   not cleared). #828: the extension now auto-re-subscribes with bounded
+ *   equal-jitter backoff (genuine transient blips are still swallowed INSIDE
+ *   `createSubscribe`, so the board only reaches here on a real stream-death).
+ *   The variant is carried on `connectionDetail` (no new enum value): an arming
+ *   detail → `[RECONNECTING]`, a settled detail (re-arm capped at 30s) →
+ *   `[STREAM DOWN]`, and the 401-auth path (which does NOT auto-re-arm — a
+ *   re-sub would just 401 again) keeps the `[STREAM ENDED]` + set-token hint.
  * - `'gone'` — a hard 404 on the per-ensemble stream: the ensemble's maestro is
  *   gone. {@link setConnection} CLEARS the player list on this transition and the
  *   extension STOPS the stream; the renderer shows "ENSEMBLE DESTROYED".

package/dist/pi/mission-control/extension.d.ts

@@ -1,4 +1,5 @@
 import { type PiRole } from '../../config';
+import { createSubscribe } from '../../client/subscribe';
 import { type BoardModel, type CommandLevel } from './board';
 import { MissionControlActions, type ActionResult } from './actions';
 import { type InfraProgress } from '../../cli/ensure-infra';
@@ -32,6 +33,14 @@ export interface MissionControlDeps {
      * `'player'` and `'none'` both keep it dormant.
      */
     role?: PiRole;
+    /**
+     * #826/#828 — override the coarse-stream subscribe factory (test seam).
+     * Defaults to {@link createSubscribe}. Lets a fake-timer test inject a mock
+     * `subscribe` generator to drive the watchdog + re-arm loop deterministically
+     * and assert the single-loop invariant (subscribe called exactly N times, not
+     * N+1). Production never sets it.
+     */
+    createSubscribeImpl?: typeof createSubscribe;
 }
 /**
  * Infra-bootstrap seam (#700 P1). Defaults to the real {@link ensureInfra}; the
@@ -93,6 +102,61 @@ export declare function classifyCoarseStreamEnd(err: unknown, aborted: boolean):
     connection: 'gone' | 'reconnecting';
     detail?: string;
 } | null;
+/** #826 — watchdog poll cadence (how often we compare now − lastCoarseEventAt). */
+export declare const WATCHDOG_TICK_MS = 5000;
+/**
+ * #826 — board-level staleness threshold. The daemon emits a `heartbeat` SSE
+ * event every ≤10s on a live `/v1/events` stream, so >35s of TOTAL silence
+ * (3.5× heartbeat) means the stream is wedged/dead — a half-open socket from a
+ * hard `agent-tempo down` (ECONNREFUSED / dead TCP), which neither a 404 nor
+ * force-fetch's INTERNAL retry surfaces (that loop reconnects forever, never
+ * throws). Sits ABOVE the fetch loop's 30s internal backoff cap, so a healthy
+ * cycling loop still receiving heartbeats never trips it — this gap IS the
+ * no-double-retry boundary (watchdog = safety net ABOVE the transport).
+ */
+export declare const COARSE_STALE_MS = 35000;
+/**
+ * #828 — after this many consecutive failed re-arms the board stops claiming
+ * it's actively "reconnecting" and settles to the honest "[STREAM DOWN] —
+ * retrying every 30s" wording. Re-arm itself NEVER stops (a permanently silent
+ * wedge is the #752 silent-wedge class); only the label changes. ~5 steps takes
+ * the backoff ramp to its 30s cap.
+ */
+export declare const REARM_SETTLE_THRESHOLD = 5;
+/**
+ * #828 — equal-jitter backoff for the Nth re-arm attempt: `b/2 + rand(0, b/2)`
+ * where `b = min(1s·2^attempt, 30s)`. `Math.random()` is fine here — this is
+ * client code, not workflow code (the determinism rule does not apply). Jitter
+ * spreads re-arms so a fleet of boards doesn't thundering-herd a recovering
+ * daemon. `randomFn` is injectable for deterministic tests.
+ */
+export declare function rearmDelayMs(attempt: number, randomFn?: () => number): number;
+/**
+ * #828 — the reconnecting sub-variant wording for the Nth re-arm attempt: still
+ * ramping (< {@link REARM_SETTLE_THRESHOLD}) → "attempting to reconnect…";
+ * settled (≥) → "retrying every 30s". Carried on the model's `connectionDetail`
+ * (NO new BoardConnection enum value) and read by the renderer to pick the
+ * marker. Pure + exported for unit testing.
+ */
+export declare function reconnectDetailForAttempt(attempt: number): string;
+/**
+ * #828 — should a coarse stream-END auto-re-arm? Gate (architect ruling):
+ * - `null` (aborted teardown/rebind) → no
+ * - `gone` (404 — maestro torn down; a re-sub just 404s) → no (terminal by design)
+ * - `reconnecting` WITH a detail (the 401 auth path — tight-looping a
+ *   guaranteed-fail) → no; keep the set-token hint
+ * - `reconnecting` WITHOUT a detail (generic stream-drop / normal-end) → yes
+ * Pure + exported for unit testing.
+ */
+export declare function shouldRearmOnStreamEnd(end: {
+    connection: 'gone' | 'reconnecting';
+    detail?: string;
+} | null): boolean;
+/**
+ * #826 — is the coarse stream stale (silent past {@link COARSE_STALE_MS})?
+ * `lastEventAt === 0` means "not connected yet" → never stale. Pure.
+ */
+export declare function isCoarseStale(lastEventAt: number, now: number): boolean;
 /**
  * The operator-command + board controller. Holds the model + the action client;
  * command methods are independently unit-testable with a fake actions + ctx.