agent-tempo 1.7.0-beta.9 → 1.7.0

package/CLAUDE.md

@@ -174,6 +174,22 @@ npm run check:all   # runs every CI gate locally (build, tests, drift checks, li
 > surveys or migrations, always grep **both** `test/` and `tests/` or you will miss
 > mocks and assertions that only live in one directory.
 
+> **Windows `**`-glob false-negative (#707) — a zero-match can read as "clean".**
+> On Windows, a ripgrep glob with a **leading directory segment before `**`**
+> silently matches **zero** files: `Grep ... glob="src/**/*.ts"` returns *"No
+> files found"* even when matches exist — a false negative that looks identical
+> to "searched and found nothing." This bites call-site surveys, drift checks,
+> and any "prove a symbol is absent" decision. **Reliable forms** (use these):
+> path-scope instead — `Grep path="src" type="ts"` — or drop the leading dir —
+> `glob="**/*.ts"`; or just `Read` the file when you know the path. A bare
+> recursive `**/*.ext` works; `dir/**/*.ext` is the broken shape.
+> The bug is in the search-tool layer, not this repo — **no repo check shells a
+> `**` glob.** Repo lint/drift/conformance checks enumerate via `fs` recursion
+> or `git ls-files` (never a shelled `**` glob) and now **assert a non-zero file
+> count** (#707) so a future enumeration breakage fails loud instead of passing
+> as "clean." Hold that bar for any new source-scanning check: *a check that
+> scans nothing must never report success.*
+
 > **Test-only hooks live with the module they reset and follow the
 > `__<verb><Noun>ForTests` naming convention** — see
 > [docs/adr/0006-test-hooks-naming.md](docs/adr/0006-test-hooks-naming.md). The
@@ -222,7 +238,7 @@ daemon worker notes, `npx ts-node` dev runner).
 - **`upgrade-to-2` cutover** (#785, ratified migration protocol A2 — `docs/design/v2-scoping.md` §A.3): The 1.x → 2.0 migration verb. A 2.0 worker can never replay a 1.x-recorded run, so 2.0 ships behind a clean cutover: `agent-tempo upgrade-to-2` runs a six-phase protocol — **preflight** (enumerate ensembles; refuse if any connected daemon is below the 1.7.x version floor — `hostProfile.version` on the global maestro; covers same-host-stale-daemon, #801) → **pause** (brake the work *sources* — maestro + scheduler — leaving sessions live to drain) → **drain** (poll outboxes ≤60s; `--force-drain` records stragglers instead of stopping) → **snapshot** (freeze session dispatch, then capture continuity to `~/.agent-tempo/upgrade-snapshot-v1.json`) → **destroy** (idempotent teardown: peers → scheduler+maestro → conductor) → **done**. **Load-bearing invariant: SNAPSHOT strictly precedes DESTROY** (`destroyAndFinish` takes a persisted snapshot as a required arg); a crash leaves either everything intact or a durable snapshot + partial teardown, never destruction without capture. Resumable via the snapshot's phase stamp. The snapshot captures schedules (durable intent), #334 state slots (continuity), `sessionId` (resume pointer), the non-default recruit `model` (ad-hoc claude-api/opencode/pi continuity), and undelivered cues (operator review, NOT redelivered); coat-check is dropped (TTL-transient); gates/stages/worktrees are intentionally not captured (transient coordination state; worktree continuity rides `workDir`). **`src/upgrade/snapshot-v1.ts` is the cross-release interface the 2.0-side `up --from-upgrade` (#786) imports** — it is VERSIONED and deliberately Temporal-free; additive optional fields do NOT bump the version, only removed/renamed/retyped required fields do (with a 2.0 reader migration). CLI flags: `--yes` (skip confirm), `--dry-run` (print snapshot + destroy list, exit before pausing), `--force-drain`. The verb is crash-proof (`src/cli/upgrade-to-2-command.ts` dynamic-imports the Temporal-touching engine). See `src/upgrade/` and issue #785.
 - **Coat-check** (#318, ADR 0008): Per-ensemble transient content store on Maestro state. Solves the 100 KB cue body cap — stash a large artifact with `coat_check_put` (returns a ticket id) and attach the ticket to a `cue` via `attachmentTicket`; the recipient calls `coat_check_get` to pull the full body. Four MCP tools: `coat_check_put` (any player; max 32 KiB per entry, 20 slots per ensemble, TTL 7d default), `coat_check_get` (any player; bumps fetch-audit counters), `coat_check_list` (read-only survey; headers only, content omitted), `coat_check_evict` (owner or conductor). Saturation rejects with `CoatCheckSlotsFull` (no LRU eviction). See `src/tools/coat-check-*.ts` and [docs/adr/0008-coat-check-pattern.md](docs/adr/0008-coat-check-pattern.md).
 - **Lineup examples**: Six pre-built ensemble YAML files in `examples/ensembles/` — `tempo-big-band`, `tempo-dev-team`, `tempo-review-squad`, `tempo-jam-session`, `tempo-mock-jam` (dev-mode all-mock ensemble), `tempo-headless-jam` (#520 — all-`claude-code-headless` subscription-billed ensemble). Load with `agent-tempo up --lineup <name>` or the `load_lineup` tool.
-- **GitHub App identity** (`agent-tempo[bot]`): When a player writes to GitHub — issue comments, PR creation/merge, commits, labels, check runs — **use `./scripts/ensemble-gh`** instead of `gh`. The wrapper mints a short-lived installation token so the action is attributed to `agent-tempo[bot]`, not to the human maintainer, making the AI authorship visible. Plain `gh` is still correct for read-only local dev (`gh pr view`, `gh repo clone`, `gh auth status`). On Windows, invoke via `bash ./scripts/ensemble-gh` — bare PowerShell silently no-ops with no error (see #741). Every bot-authored comment/PR body must include the AI attribution footer documented in [docs/github-app.md](docs/github-app.md).
+- **GitHub App identity** (`agent-tempo[bot]`): When a player writes to GitHub — issue comments, PR creation/merge, commits, labels, check runs — **use `./scripts/ensemble-gh`** instead of `gh`. The wrapper mints a short-lived installation token so the action is attributed to `agent-tempo[bot]`, not to the human maintainer, making the AI authorship visible. Plain `gh` is still correct for read-only local dev (`gh pr view`, `gh repo clone`, `gh auth status`). On Windows, `./scripts/ensemble-gh` works directly from PowerShell via the `scripts/ensemble-gh.cmd` shim (#741); the `bash ./scripts/ensemble-gh` form also still works as an explicit fallback. Every bot-authored comment/PR body must include the AI attribution footer documented in [docs/github-app.md](docs/github-app.md).
 
 See [docs/concepts.md](docs/concepts.md) for the full glossary (Adapter, Attachment phases, Restart, Detach/Destroy, Migrate, Broadcast, Recall, Schedule, Lineup, Quality Gate, Worktree, Stage, Hold/Release, Pause/Resume, Maestro, TempoClient, Command-center planner, and more).
 

package/README.md

@@ -148,12 +148,13 @@ agent-tempo                    # launch TUI (auto-provisions on first run)
 agent-tempo up [ensemble]      # provision infrastructure and launch conductor
 agent-tempo down [--destroy]   # tear down infrastructure (--destroy also terminates workflows)
 agent-tempo status [ensemble]  # list active sessions
-agent-tempo destroy <ensemble> # terminate all sessions in an ensemble
+agent-tempo destroy [ensemble] # terminate all sessions in an ensemble (defaults to "default")
 agent-tempo restore <ensemble> # restore orphaned sessions on this host
 agent-tempo hosts              # list daemons polling this Temporal namespace (--all/--json)
 agent-tempo recall <name>      # read a player's message history (--limit/--offset/--preview/--json)
 agent-tempo attachment-info <name> # inspect a session's phase, holder, lease, and heartbeat age
 agent-tempo release [ensemble] # release held players (unlock + deliver tasks)
+agent-tempo dashboard          # open the web dashboard (--pair for QR-code cross-device access)
 agent-tempo daemon <sub>       # manage the worker daemon
 agent-tempo upgrade            # update to latest
 ```

package/dashboard/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-tempo-dashboard",
   "private": true,
-  "version": "1.7.0-beta.9",
+  "version": "1.7.0",
   "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/command-center-command.js

@@ -54,6 +54,7 @@ exports.commandCenterCommand = commandCenterCommand;
 const config_1 = require("../config");
 const spawn_1 = require("../spawn");
 const probe_1 = require("../pi/probe");
+const install_1 = require("../pi/install");
 const out = __importStar(require("./output"));
 /**
  * Public entry point — invoked by the CLI dispatcher. Launches the board in a
@@ -62,7 +63,12 @@ const out = __importStar(require("./output"));
  */
 async function commandCenterCommand(args) {
     const config = (0, config_1.getConfig)(args);
-    const ensemble = config.ensemble;
+    // #820 (Bug 3) — honor the positional / `--ensemble` flag. `args.ensemble` is
+    // resolved by the CLI dispatch via the canonical `resolveEnsemble` (flag >
+    // positional > env > 'default'), mirroring `up` post-#685. `config.ensemble`
+    // IGNORES `overrides.ensemble` (config.ts hard-codes it from env/default), so
+    // reading it dropped the positional and the board silently watched 'default'.
+    const ensemble = args.ensemble ?? config.ensemble;
     // Preflight — fail BEFORE launching a terminal that would die. checkPiNodeFloor
     // is a best-effort Node-version proxy; buildPiCommandCenterSpawn's default
     // resolver throws fail-clean when the Pi CLI is missing.
@@ -71,6 +77,24 @@ async function commandCenterCommand(args) {
         out.error(`Cannot start command-center — ${nodeFloor.reason}`);
         process.exit(1);
     }
+    // #820 (Bug 2) — extension-registration guard. command-center relies on the
+    // GLOBAL Pi extension registration (it deliberately passes NO inline `-e`, unlike
+    // `up --agent pi`). On a fresh box that never ran `install-pi`, the extensions are
+    // absent from `~/.pi/agent/settings.json`, so a plain `pi` launches with NO board
+    // and NO error. Auto-install (idempotent — matches `up --agent pi`'s out-of-box
+    // behavior) before spawning; fail loudly with the exact command if the write fails.
+    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 command-center — 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);
+        }
+    }
     // Admin (T3) token — mission-control's operator write/gate surface reads it.
     // #54: a LOCAL (loopback) daemon grants full trust tokenless, so a tokenless
     // board is fully functional locally; only a REMOTE / 0.0.0.0 daemon requires the
@@ -112,5 +136,4 @@ async function commandCenterCommand(args) {
     const { pid } = (0, spawn_1.launchInTerminal)(spawn.cmd, spawn.args, process.cwd(), spawn.env);
     out.success(`Command-center launched for ensemble ${out.cyan(ensemble)} (pid ${pid ?? 'unknown'})`);
     out.log(`  ${out.dim('Observer-only Pi board — the player extension stays dormant in this session.')}`);
-    out.log(`  ${out.dim('Requires `agent-tempo install-pi` to have registered the extensions.')}`);
 }

package/dist/cli/commands.d.ts

@@ -8,8 +8,23 @@ export declare function status(opts: StatusOpts): Promise<void>;
 interface InitOpts {
     dir: string;
     project?: boolean;
+    /**
+     * #818 — suppress the manual-setup "Next steps" block (start Temporal / start
+     * conductor). Set by the automated `up` flow, which has ALREADY started Temporal
+     * and launched the conductor — printing those steps there is stale and misleading.
+     * The manual `agent-tempo init` verb leaves it unset so the guidance still shows.
+     */
+    suppressNextSteps?: boolean;
 }
 export declare function init(opts: InitOpts): Promise<void>;
+/**
+ * Per-project .mcp.json install (legacy, used with --project flag).
+ *
+ * Exported for #818 regression coverage (the `suppressNextSteps` gate) — it only
+ * touches the filesystem + stdout, so it is unit-testable without shelling out to
+ * `claude`. Not part of the public CLI surface.
+ */
+export declare function initProject(dir: string, suppressNextSteps?: boolean): void;
 interface ServerOpts extends CliOverrides {
     background: boolean;
 }
@@ -36,6 +51,19 @@ interface UpOpts extends CliOverrides {
      */
     scenario?: string;
 }
+/**
+ * #832 — the operator-facing "ensemble ready" lines for `up` / `conduct`.
+ *
+ * Keyed on the RESOLVED ensemble name (what `command-center` / `status` take —
+ * `--ensemble` flag > positional > env > `default`), NOT the lineup's `name:`
+ * field. The two diverge whenever any of those overrides the lineup name, so the
+ * old `Ensemble <lineup-name> is ready` line named a thing the operator can't
+ * actually `connect` to. Surfaces the connect command so the next step is one
+ * copy-paste away. Pure + exported for unit testing (the surrounding `up` does
+ * I/O and isn't unit-testable). The shared markdown {@link ensembleReadyBanner}
+ * stays lineup-keyed for the conductor's seeded directive (a different surface).
+ */
+export declare function formatEnsembleReadyLines(ensemble: string, lineupName: string, playerCount: number): [readyLine: string, connectLine: string];
 export declare function up(opts: UpOpts): Promise<void>;
 /**
  * Format a `ScheduleEntry` recurrence for the `status` display.