agent-tempo 1.0.1 → 1.2.0

package/dist/client/core.js

@@ -941,6 +941,15 @@ function createTempoClientCore(client, opts = {}) {
                 taskQueue,
             });
         },
+        async listAllOrphans(opts = {}) {
+            // Lazy import — `reconcile/orphans` pulls validation/visibility
+            // helpers we don't need on every TempoClient consumer.
+            const { listAllOrphansCached } = await Promise.resolve().then(() => __importStar(require('../reconcile/orphans')));
+            return listAllOrphansCached(client, {
+                force: Boolean(opts.force),
+                ...(opts.ensemble ? { ensemble: opts.ensemble } : {}),
+            });
+        },
         async recall(ensemble, playerId) {
             // #128: direct session queries, no maestro round-trip. Throws rather
             // than returning empties so the CLI / TUI wrappers can surface a

package/dist/client/interface.d.ts

@@ -344,6 +344,27 @@ export interface TempoClientCore {
     listHosts(opts?: {
         force?: boolean;
     }): Promise<HostInfo[]>;
+    /**
+     * #579 — cluster-wide cross-host orphan listing (readonly). Used by the
+     * dashboard's `/orphans` screen via the daemon's `GET /v1/orphans`
+     * endpoint. Thin wrapper over `queryOrphanedSessions` with `allHosts: true`.
+     * Returns raw `OrphanCandidate` rows so callers can join with their own
+     * host-liveness / migrate-command rendering.
+     *
+     * `opts.ensemble` narrows the visibility query to a single ensemble.
+     * `opts.force` bypasses the 3-second in-process cache (mirrors
+     * `listHosts`). Result is cached keyed on the ensemble filter so
+     * `?ensemble=foo` and the unfiltered call don't clobber each other.
+     *
+     * Never throws on per-candidate failure — partial-tolerant by design
+     * (the underlying `queryOrphanedSessions` already skips unreachable
+     * candidates and returns what it could resolve). Visibility-query timeout
+     * also returns partial.
+     */
+    listAllOrphans(opts?: {
+        ensemble?: string;
+        force?: boolean;
+    }): Promise<import('../reconcile/orphans').OrphanCandidate[]>;
     /** Get active schedules for an ensemble. */
     getSchedules(ensemble: string): Promise<ScheduleEntry[]>;
     /** Cancel a named schedule in an ensemble. */

package/dist/daemon.js

@@ -770,6 +770,7 @@ async function main() {
         const result = await verifySearchAttributes({
             temporalAddress: config.temporalAddress,
             temporalNamespace: config.temporalNamespace,
+            temporalApiKey: config.temporalApiKey,
         });
         if (!result.ok && !result.probeError) {
             process.stderr.write('ERROR: ' + result.message + '\n');

package/dist/http/catalog.js

@@ -108,9 +108,23 @@ async function handleCreateEnsemble(req, res, client) {
     }
     const held = startMode === 'hold';
     const allowed = (0, body_1.allowedAgentsForCurrentMode)();
-    // 1. Recruit the conductor — bootstraps maestro + scheduler. Lineup's
-    // `conductor` block (if present) wins on name + agent + part; the
-    // top-level `host` is the conductor's spawn target either way.
+    // 0. Bootstrap the maestro session + hub workflow for this ensemble.
+    // `client.recruit()` submits an outbox entry on the maestro workflow —
+    // it must exist before we can signal it. The CLI's `agent-tempo up` path
+    // pre-creates the conductor workflow which bootstraps the maestro, but
+    // the dashboard create-ensemble flow goes directly through the client.
+    try {
+        await client.ensureMaestroSession(name);
+    }
+    catch (err) {
+        return (0, responses_1.errorResponse)(res, 500, {
+            error: 'maestro-bootstrap-failed',
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+    // 1. Recruit the conductor — lineup's `conductor` block (if present)
+    // wins on name + agent + part; the top-level `host` is the conductor's
+    // spawn target either way.
     const conductorBlock = resolved?.conductor;
     const conductorName = conductorBlock?.name ?? 'conductor';
     const conductorAgent = pickAgent(conductorBlock?.agent, allowed);

package/dist/http/event-types.d.ts

@@ -212,6 +212,47 @@ export interface PlayerSummaryV1 {
  * reason `overflow`.
  */
 export type EventIdToken = string;
+/**
+ * §4.x — single row in the `/v1/orphans` cluster-wide orphan listing.
+ *
+ * An orphan is a session workflow whose `attachmentInfo.phase ∈ {detached,
+ * draining, attached, processing, awaiting}` but whose home-host daemon
+ * isn't running an adapter for it — typically because the home host is
+ * down or the adapter crashed without orderly destroy. The dashboard
+ * `/orphans` screen surfaces these so an operator on a live host can
+ * migrate the player over.
+ *
+ * `hostLiveness` is joined server-side against `listHosts()` so the
+ * dashboard doesn't have to re-issue a hosts query per row:
+ *   - `'live'`  — `preferredHost` matches a host with `freshness === 'live'`
+ *   - `'stale'` — matches a host with `freshness === 'stale'`
+ *   - `'missing'` — `preferredHost` is null OR no matching host record
+ *
+ * `migrateCommand` is the TUI slash-command the operator pastes into their
+ * own session on the migrate target. `--yes-steal=` (NOT
+ * `--confirm-steal-from-host`) is the actual flag accepted by
+ * `src/tui/commands.ts:handleMigrate`. When `preferredHost` is null the
+ * command targets the local host and includes the steal guard pre-filled
+ * with the last-known host (or a literal `'(unknown)'` when even that is
+ * missing — the operator must edit it before submit).
+ */
+export interface OrphanV1 {
+    playerId: string;
+    ensemble: string;
+    workflowId: string;
+    preferredHost: string | null;
+    hostLiveness: 'live' | 'stale' | 'missing';
+    phase: AttachmentPhase;
+    detachedSince: string | null;
+    lastHeartbeatAt: string | null;
+    migrateCommand: string;
+}
+/** §4.x — response shape for `GET /v1/orphans[?ensemble=<name>]`. */
+export interface OrphansV1 {
+    v: 1;
+    capturedAt: string;
+    orphans: OrphanV1[];
+}
 /**
  * The PR-1 sentinel `lastEventId` value — emitted on `/v1/state/:ensemble`
  * before PR-2 lights up the aggregate poll loop. Subscribers passing this

package/dist/http/orphans.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `GET /v1/orphans[?ensemble=<name>]` handler — surfaces cluster-wide
+ * cross-host orphans to the dashboard (#579).
+ *
+ * Pipeline:
+ *   1. `TempoClient.listAllOrphans` → `OrphanCandidate[]` (visibility query
+ *      with `allHosts: true`, 3-second daemon-edge cache, partial-tolerant
+ *      on per-candidate failures).
+ *   2. `TempoClient.listHosts` → `HostInfo[]` for the freshness join
+ *      (also independently cached for 3s).
+ *   3. Map each candidate to the `OrphanV1` wire shape, joining
+ *      `hostLiveness` from the hosts snapshot and rendering the operator
+ *      `migrateCommand` via {@link renderMigrateCommand}.
+ *
+ * **NOT a wrapper around `restoreOrphansOnce`** — see ADR follow-up
+ * 2026-05-16 (architect option 3): the readonly branch of that helper
+ * collapses each candidate down to `{ playerId, ensemble, outcome }` and
+ * loses the wire fields we need (`workflowId`, `phase`, `detachedSince`,
+ * `lastHeartbeatAt`, `preferredHost`). The dashboard handler therefore
+ * calls `queryOrphanedSessions` directly (via `listAllOrphansCached`)
+ * and shares the cross-host detail formatter with the readonly branch
+ * via {@link buildCrossHostDetail} so the two surfaces never drift.
+ *
+ * Auth: same bearer + CORS gates as every other `/v1/*` read — applied
+ * at the dispatcher in `src/http/server.ts`, not here.
+ */
+import * as http from 'http';
+import type { OrphansV1, OrphanV1 } from './event-types';
+import type { TempoClient } from '../client/interface';
+import type { HostInfo } from '../types';
+import type { OrphanCandidate } from '../reconcile/orphans';
+/**
+ * Render the TUI `/migrate` slash command the operator pastes into their
+ * own session to recover an orphan. Wording mirrors
+ * `src/tui/commands.ts:handleMigrate` exactly:
+ *   - positional `<playerId> <host>`
+ *   - flag form `--yes-steal=<currentHost>` (NOT `--confirm-steal-from-host`)
+ *
+ * When `preferredHost` is non-null the bot can target it directly: the
+ * operator just runs `/migrate <player> <preferredHost>` from any
+ * session. When it's null we don't know where the player was last seen,
+ * so the rendered command targets `<dashboardHost>` and pre-fills the
+ * steal guard with the candidate's last-known adapter host (from
+ * `OrphanSummary.lastAdapter.hostname`) — falling through to the literal
+ * `(unknown)` when even that's missing. The operator MUST edit the
+ * placeholder before submit; rendering it literally guarantees the
+ * `/migrate` validator catches the slip rather than silently steaming
+ * ahead.
+ */
+export declare function renderMigrateCommand(args: {
+    playerId: string;
+    preferredHost: string | null;
+    dashboardHost: string;
+    lastAdapterHost: string | null;
+}): string;
+/**
+ * Map a single `OrphanCandidate` to its `OrphanV1` wire shape.
+ *
+ * Pure / side-effect-free — exposed for unit tests that want to exercise
+ * the join logic without spinning up a Temporal client.
+ */
+export declare function buildOrphanRow(args: {
+    candidate: OrphanCandidate;
+    hostsByName: Map<string, HostInfo>;
+    dashboardHost: string;
+}): OrphanV1;
+/** Build the full `OrphansV1` payload. Exposed for unit tests. */
+export declare function buildOrphansResponse(client: TempoClient, ensembleFilter: string | undefined, dashboardHost: string): Promise<OrphansV1>;
+/**
+ * Request handler. Bearer + CORS already enforced upstream — by the time
+ * we're called the caller is authorized.
+ */
+export declare function handleOrphans(res: http.ServerResponse, ctx: {
+    client: TempoClient;
+    dashboardHost: string;
+}, ensembleFilter: string | undefined): Promise<void>;

package/dist/http/orphans.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderMigrateCommand = renderMigrateCommand;
+exports.buildOrphanRow = buildOrphanRow;
+exports.buildOrphansResponse = buildOrphansResponse;
+exports.handleOrphans = handleOrphans;
+const responses_1 = require("./responses");
+/**
+ * Render the TUI `/migrate` slash command the operator pastes into their
+ * own session to recover an orphan. Wording mirrors
+ * `src/tui/commands.ts:handleMigrate` exactly:
+ *   - positional `<playerId> <host>`
+ *   - flag form `--yes-steal=<currentHost>` (NOT `--confirm-steal-from-host`)
+ *
+ * When `preferredHost` is non-null the bot can target it directly: the
+ * operator just runs `/migrate <player> <preferredHost>` from any
+ * session. When it's null we don't know where the player was last seen,
+ * so the rendered command targets `<dashboardHost>` and pre-fills the
+ * steal guard with the candidate's last-known adapter host (from
+ * `OrphanSummary.lastAdapter.hostname`) — falling through to the literal
+ * `(unknown)` when even that's missing. The operator MUST edit the
+ * placeholder before submit; rendering it literally guarantees the
+ * `/migrate` validator catches the slip rather than silently steaming
+ * ahead.
+ */
+function renderMigrateCommand(args) {
+    const { playerId, preferredHost, dashboardHost, lastAdapterHost } = args;
+    if (preferredHost) {
+        return `/migrate ${playerId} ${preferredHost}`;
+    }
+    const stealFrom = lastAdapterHost ?? '(unknown)';
+    return `/migrate ${playerId} ${dashboardHost} --force --yes-steal=${stealFrom}`;
+}
+/** Map host freshness → `OrphanV1.hostLiveness`. */
+function deriveLiveness(preferredHost, hostsByName) {
+    if (!preferredHost)
+        return 'missing';
+    const h = hostsByName.get(preferredHost);
+    if (!h)
+        return 'missing';
+    return h.freshness === 'live' ? 'live' : 'stale';
+}
+/**
+ * Map a single `OrphanCandidate` to its `OrphanV1` wire shape.
+ *
+ * Pure / side-effect-free — exposed for unit tests that want to exercise
+ * the join logic without spinning up a Temporal client.
+ */
+function buildOrphanRow(args) {
+    const { candidate, hostsByName, dashboardHost } = args;
+    const summary = candidate.summary;
+    const preferredHost = summary.preferredHost ?? null;
+    const lastAdapterHost = summary.lastAdapter?.hostname ?? null;
+    return {
+        playerId: summary.playerId,
+        ensemble: summary.ensemble,
+        workflowId: candidate.workflowId,
+        preferredHost,
+        hostLiveness: deriveLiveness(preferredHost, hostsByName),
+        phase: candidate.info.phase,
+        detachedSince: summary.detachedSince ?? null,
+        lastHeartbeatAt: candidate.info.currentAttachment?.lastHeartbeatAt ?? null,
+        migrateCommand: renderMigrateCommand({
+            playerId: summary.playerId,
+            preferredHost,
+            dashboardHost,
+            lastAdapterHost,
+        }),
+    };
+}
+/** Build the full `OrphansV1` payload. Exposed for unit tests. */
+async function buildOrphansResponse(client, ensembleFilter, dashboardHost) {
+    // Fire both reads in parallel — independent caches, cheap join.
+    const [candidates, hosts] = await Promise.all([
+        client.listAllOrphans(ensembleFilter ? { ensemble: ensembleFilter } : {}),
+        client.listHosts(),
+    ]);
+    const hostsByName = new Map(hosts.map((h) => [h.hostname, h]));
+    const orphans = candidates.map((candidate) => buildOrphanRow({ candidate, hostsByName, dashboardHost }));
+    return {
+        v: 1,
+        capturedAt: new Date().toISOString(),
+        orphans,
+    };
+}
+/**
+ * Request handler. Bearer + CORS already enforced upstream — by the time
+ * we're called the caller is authorized.
+ */
+async function handleOrphans(res, ctx, ensembleFilter) {
+    const payload = await buildOrphansResponse(ctx.client, ensembleFilter, ctx.dashboardHost);
+    (0, responses_1.jsonResponse)(res, 200, payload);
+}

package/dist/http/server.js

@@ -65,6 +65,7 @@ const catalog_1 = require("./catalog");
 const port_file_1 = require("./port-file");
 const responses_1 = require("./responses");
 const snapshot_1 = require("./snapshot");
+const orphans_1 = require("./orphans");
 const sse_handler_1 = require("./sse-handler");
 const log = (...args) => console.error(`[agent-tempo:http ${new Date().toISOString()}]`, ...args);
 /** Default bind addr per SSE-PROTOCOL.md §1. */
@@ -302,6 +303,18 @@ async function handle(req, res, ctx) {
     if (pathname === '/v1/hosts') {
         return handleHosts(res, ctx);
     }
+    // #579 — cluster-wide cross-host orphan listing for the dashboard.
+    // Same bearer + CORS gate as `/v1/hosts`; optional `?ensemble=<name>`
+    // narrows to one ensemble.
+    if (pathname === '/v1/orphans') {
+        const ensembleFilter = url.searchParams.get('ensemble') ?? undefined;
+        return (0, orphans_1.handleOrphans)(res, {
+            client: ctx.client,
+            // os.hostname() is OS-cached + sub-millisecond — no need to thread
+            // through HandleContext just for one rendering site.
+            dashboardHost: require('os').hostname(),
+        }, ensembleFilter);
+    }
     // Catalog reads (issue #400) — `listAgentTypes` / `listLineups`
     // touch local fs only, no Temporal calls; cheap to serve per-request.
     if (pathname === '/v1/agent-types') {

package/dist/reconcile/orphans.d.ts

@@ -1,30 +1,3 @@
-/**
- * Orphan-session query — shared by `reconcileOnBoot()` in `src/daemon.ts` and
- * the `agent-tempo restore` CLI command (`src/cli/commands.ts`).
- *
- * Design §10.1: a session is an **orphan** when the workflow is `Running` but
- * no adapter process is alive to own its attachment. Two candidate shapes
- * matter:
- *
- *  1. **Active-host sessions** — `AgentTempoAttachedHost = local` AND phase
- *     is `attached` / `processing` / `awaiting` / `draining`. The attachment
- *     exists but the adapter process may have died.
- *  2. **Detached-home sessions** — `AgentTempoAttachmentState = detached` AND
- *     `AgentTempoHostname = local`. No adapter at all; the home host is us.
- *
- * For each candidate we query `attachmentInfo` + `orphanSummary`. If the
- * adapter process is alive (`isAdapterProcessAlive` returns true) we skip —
- * that's the daemon-restarted-under-a-live-adapter case, not an orphan.
- *
- * `isAdapterProcessAlive` is stubbed as `() => false` for v0.25.0-beta.1 per
- * PR-E engineer brief §8 answer 1. No adapter PID file convention exists yet
- * (only the daemon process has `daemon.pid`; Copilot bridges write their own
- * per-session file but Claude Code CLI does not). A conservative always-dead
- * stub is safe: false negatives cost an extra `claimAttachment` attempt,
- * which the caller catches as `AttachmentConflict` and backs off silently
- * (design §10.6). False positives — skipping a session that needs restore —
- * are the worse failure mode.
- */
 import type { Client } from '@temporalio/client';
 import type { AttachmentInfo, AttachmentPhase, OrphanSummary } from '../types';
 /**
@@ -123,6 +96,43 @@ export declare function buildOrphanQuery(opts: BuildOrphanQueryOpts): string;
  * so the boot path can call `restoreOrphansOnce` again on a subsequent
  * cycle to pick up missed candidates.
  */
+/**
+ * 3-second cache TTL — mirrors `src/utils/hosts.ts:CACHE_TTL_MS`. Keeps
+ * rapid-fire dashboard refreshes cheap (the React query layer also has
+ * its own staleTime, this is defense in depth at the daemon edge).
+ */
+export declare const ORPHANS_CACHE_TTL_MS = 3000;
+/**
+ * Test hook — never call from production code. Convention per
+ * `docs/adr/0006-test-hooks-naming.md`.
+ */
+export declare function __resetOrphansCacheForTests(): void;
+/**
+ * Cluster-wide cross-host orphan listing for the dashboard (#579 / ADR
+ * follow-up). Thin wrapper over {@link queryOrphanedSessions} with
+ * `allHosts: true` and a 3-second in-process cache keyed by ensemble
+ * filter. Cache shape mirrors `src/utils/hosts.ts:listHosts`.
+ *
+ * Use the `cleanup` deadline (30s) rather than the `boot` deadline (60s)
+ * since this is called from a user-facing read endpoint where partial
+ * results are preferable to a 60s wait.
+ */
+export declare function listAllOrphansCached(client: Client, opts?: {
+    ensemble?: string;
+    force?: boolean;
+}, log?: (...args: unknown[]) => void): Promise<OrphanCandidate[]>;
+/**
+ * Cross-host detail resolver shared by `restoreOrphansOnce`'s readonly
+ * branch (#151 `agent-tempo restore --all-hosts`) and the dashboard's
+ * `/v1/orphans` handler (#579).
+ *
+ * Returns `null` when an `ensembleFilter` is provided and the candidate
+ * is outside that ensemble (caller should `continue`). Otherwise returns
+ * the preferred-host string used by both surfaces to group / annotate:
+ * `OrphanSummary.preferredHost` first, falling back to the candidate's
+ * last-known adapter host, finally `'(unknown)'`.
+ */
+export declare function buildCrossHostDetail(candidate: OrphanCandidate, ensembleFilter?: string): string | null;
 export declare function queryOrphanedSessions(client: Client, filter: OrphanQueryFilter, log?: (...args: unknown[]) => void, deadlineMs?: number): Promise<OrphanCandidate[]>;
 /**
  * Options for {@link restoreOrphansOnce}. `policy: 'never'` is NOT included

package/dist/reconcile/orphans.js

@@ -1,10 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORPHANS_CACHE_TTL_MS = void 0;
 exports.isAdapterProcessAliveStub = isAdapterProcessAliveStub;
 exports.buildOrphanQuery = buildOrphanQuery;
+exports.__resetOrphansCacheForTests = __resetOrphansCacheForTests;
+exports.listAllOrphansCached = listAllOrphansCached;
+exports.buildCrossHostDetail = buildCrossHostDetail;
 exports.queryOrphanedSessions = queryOrphanedSessions;
 exports.formatRestoreOutcome = formatRestoreOutcome;
 exports.restoreOrphansOnce = restoreOrphansOnce;
+/**
+ * Orphan-session query — shared by `reconcileOnBoot()` in `src/daemon.ts` and
+ * the `agent-tempo restore` CLI command (`src/cli/commands.ts`).
+ *
+ * Design §10.1: a session is an **orphan** when the workflow is `Running` but
+ * no adapter process is alive to own its attachment. Two candidate shapes
+ * matter:
+ *
+ *  1. **Active-host sessions** — `AgentTempoAttachedHost = local` AND phase
+ *     is `attached` / `processing` / `awaiting` / `draining`. The attachment
+ *     exists but the adapter process may have died.
+ *  2. **Detached-home sessions** — `AgentTempoAttachmentState = detached` AND
+ *     `AgentTempoHostname = local`. No adapter at all; the home host is us.
+ *
+ * For each candidate we query `attachmentInfo` + `orphanSummary`. If the
+ * adapter process is alive (`isAdapterProcessAlive` returns true) we skip —
+ * that's the daemon-restarted-under-a-live-adapter case, not an orphan.
+ *
+ * `isAdapterProcessAlive` is stubbed as `() => false` for v0.25.0-beta.1 per
+ * PR-E engineer brief §8 answer 1. No adapter PID file convention exists yet
+ * (only the daemon process has `daemon.pid`; Copilot bridges write their own
+ * per-session file but Claude Code CLI does not). A conservative always-dead
+ * stub is safe: false negatives cost an extra `claimAttachment` attempt,
+ * which the caller catches as `AttachmentConflict` and backs off silently
+ * (design §10.6). False positives — skipping a session that needs restore —
+ * are the worse failure mode.
+ */
+const os_1 = require("os");
 const signals_1 = require("../workflows/signals");
 const config_1 = require("../config");
 const client_1 = require("../client");
@@ -119,6 +151,64 @@ function buildOrphanQuery(opts) {
  * so the boot path can call `restoreOrphansOnce` again on a subsequent
  * cycle to pick up missed candidates.
  */
+// ─────────────────────────────────────────────────────────────────────────
+// #579 — cached cluster-wide orphan listing for the dashboard
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * 3-second cache TTL — mirrors `src/utils/hosts.ts:CACHE_TTL_MS`. Keeps
+ * rapid-fire dashboard refreshes cheap (the React query layer also has
+ * its own staleTime, this is defense in depth at the daemon edge).
+ */
+exports.ORPHANS_CACHE_TTL_MS = 3_000;
+const orphansCache = new Map();
+/**
+ * Test hook — never call from production code. Convention per
+ * `docs/adr/0006-test-hooks-naming.md`.
+ */
+function __resetOrphansCacheForTests() {
+    orphansCache.clear();
+}
+/**
+ * Cluster-wide cross-host orphan listing for the dashboard (#579 / ADR
+ * follow-up). Thin wrapper over {@link queryOrphanedSessions} with
+ * `allHosts: true` and a 3-second in-process cache keyed by ensemble
+ * filter. Cache shape mirrors `src/utils/hosts.ts:listHosts`.
+ *
+ * Use the `cleanup` deadline (30s) rather than the `boot` deadline (60s)
+ * since this is called from a user-facing read endpoint where partial
+ * results are preferable to a 60s wait.
+ */
+async function listAllOrphansCached(client, opts = {}, log = () => { }) {
+    const key = opts.ensemble ?? '__all__';
+    const now = Date.now();
+    const cached = orphansCache.get(key);
+    if (!opts.force && cached && now - cached.timestamp < exports.ORPHANS_CACHE_TTL_MS) {
+        return cached.candidates;
+    }
+    const candidates = await queryOrphanedSessions(client, {
+        hostname: (0, os_1.hostname)(),
+        allHosts: true,
+        ...(opts.ensemble !== undefined ? { ensemble: opts.ensemble } : {}),
+    }, log, visibility_deadline_1.VISIBILITY_DEADLINES_MS.orphanQueryCleanup);
+    orphansCache.set(key, { timestamp: now, candidates });
+    return candidates;
+}
+/**
+ * Cross-host detail resolver shared by `restoreOrphansOnce`'s readonly
+ * branch (#151 `agent-tempo restore --all-hosts`) and the dashboard's
+ * `/v1/orphans` handler (#579).
+ *
+ * Returns `null` when an `ensembleFilter` is provided and the candidate
+ * is outside that ensemble (caller should `continue`). Otherwise returns
+ * the preferred-host string used by both surfaces to group / annotate:
+ * `OrphanSummary.preferredHost` first, falling back to the candidate's
+ * last-known adapter host, finally `'(unknown)'`.
+ */
+function buildCrossHostDetail(candidate, ensembleFilter) {
+    if (ensembleFilter && candidate.summary.ensemble !== ensembleFilter)
+        return null;
+    return candidate.summary.preferredHost ?? candidate.summary.lastAdapter?.hostname ?? '(unknown)';
+}
 async function queryOrphanedSessions(client, filter, log = () => { }, deadlineMs = visibility_deadline_1.VISIBILITY_DEADLINES_MS.orphanQueryBoot) {
     const isAlive = filter.isAdapterProcessAlive ?? isAdapterProcessAliveStub;
     const query = buildOrphanQuery({
@@ -267,12 +357,9 @@ async function restoreOrphansOnce(client, opts, log = () => { }) {
     // as orphan candidate) and ensemble narrowing are both applied here too.
     if (allHostsReadonly) {
         for (const o of orphans) {
-            if (opts.ensemble && o.summary.ensemble !== opts.ensemble)
-                continue;
-            // `detail` carries the preferred host when set, falling back to the
-            // candidate's home hostname (from `OrphanSummary.lastAdapter.hostname`)
-            // and finally `(unknown)`. The CLI groups by this value.
-            const detail = o.summary.preferredHost ?? o.summary.lastAdapter?.hostname ?? '(unknown)';
+            const detail = buildCrossHostDetail(o, opts.ensemble);
+            if (detail === null)
+                continue; // ensemble narrowing excluded it
             record(o, { kind: 'skipped', reason: 'crossHost', detail });
         }
         return summary;

package/dist/tui/index.js

@@ -124,6 +124,7 @@ function createDummyClient() {
         attachmentInfo: fail,
         recall: fail,
         listHosts: async () => [],
+        listAllOrphans: async () => [],
         disbandEnsemble: fail,
         // #287 ensemble-scope verbs — same offline fail-fast shape.
         pause: fail,

package/dist/utils/bg-preflight.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Test hook — never call from production code. Convention per
+ * `docs/adr/0006-test-hooks-naming.md`.
+ */
+export declare function __resetBgPreflightCacheForTests(): void;
+export interface BgPreflightResult {
+    ok: boolean;
+    /** Populated when `ok === false`. Single line, ready to surface to the user. */
+    error?: string;
+    /** True when the result was served from the daemon-lifetime cache. */
+    cached: boolean;
+}
+/**
+ * Probe whether `claude --bg` can spawn in the given cwd without prompting
+ * the operator for permission acceptance. First call probes; subsequent
+ * calls for the same `(host, cwd)` hit the in-process cache.
+ *
+ * Returns `{ ok: true }` when the dry-run succeeded (exit 0). On any other
+ * exit code (or spawn-side ENOENT), returns `{ ok: false, error: ... }`
+ * with an actionable message. Never throws — callers handle the result.
+ */
+export declare function bgPreflight(cwd: string, options?: {
+    claudeBin?: string;
+    host?: string;
+}): BgPreflightResult;