agent-tempo 1.0.1

package/dist/types.js

@@ -0,0 +1,39 @@
+"use strict";
+// Shared types used by both workflow code (V8 sandbox) and Node.js server code.
+// This file must NOT import from @temporalio/* — it's pure TypeScript types.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZERO_CHAT_HIGH_WATER = exports.MOCK_MODES = exports.AGENT_TYPES = void 0;
+/**
+ * Agent runtime selector.
+ *
+ * - `'claude'` / `'copilot'` — production adapters; ship in the npm tarball.
+ * - `'mock'` — dev-mode-only adapter (ADR 0014 PR-2). Defense-in-depth gates
+ *   (build-time exclusion, registry gate behind `isDevMode()`, recruit-time
+ *   rejection, runtime banner) keep this off production paths. The string
+ *   value lives in the type union so workflow / outbox / recruit code can
+ *   discriminate without `any` casts even in production builds; the runtime
+ *   gates are what actually prevent execution.
+ *
+ * Single source of truth: {@link AGENT_TYPES}. The CLI argv parser
+ * (`src/cli.ts`'s `--agent` validation) and the recruit MCP tool's
+ * `z.enum` import this tuple so adding a new adapter only requires
+ * editing one line — see #476 (the `claude-api` allowlist drift bug
+ * that motivated centralising this).
+ */
+exports.AGENT_TYPES = ['claude', 'copilot', 'mock', 'claude-api', 'opencode', 'claude-code-headless'];
+/**
+ * Mock-adapter mode (ADR 0014 §4.2). Single source of truth shared by the
+ * adapter, the recruit tool's zod enum (`z.enum(MOCK_MODES)`), the spawn
+ * options, the recruit outbox entry, the lineup schema, and the lineup
+ * dispatcher. `'echo' | 'scripted'` shipped in PR-2; `'silent' | 'chaos'`
+ * landed in PR-3.
+ *
+ * Declared here rather than in `src/adapters/mock/` so non-dev-mode modules
+ * (recruit, spawn, schema) can reference the type without pulling the
+ * adapter source unit into their dep graph.
+ */
+exports.MOCK_MODES = ['echo', 'scripted', 'silent', 'chaos'];
+/** Zero-value for ChatHighWater — use as default when no prior fetch. */
+exports.ZERO_CHAT_HIGH_WATER = {
+    maestroRecv: 0, maestroSent: 0, conductorRecv: 0, conductorSent: 0,
+};

package/dist/utils/attachment-format.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared attachment-info display formatter.
+ *
+ * Renders an {@link AttachmentInfo} snapshot into an array of plain strings
+ * suitable for either stdout (`agent-tempo attachment-info`) or the TUI
+ * overlay (`/attachment-info`). Pure — no Temporal, no stdout, no ANSI
+ * colors — so unit tests can assert exact lines without booting a client.
+ *
+ * Lives in `src/utils/` (not `src/cli/`) because both the CLI and TUI
+ * consume it; #264 carved it out of `src/cli/commands.ts` to eliminate the
+ * cross-surface drift where only the CLI rendered heartbeat age.
+ *
+ * `now` is injectable so tests can freeze the clock and assert the
+ * heartbeat-age string deterministically. Heartbeat age uses
+ * {@link formatDurationMs} (same helper the scheduler output uses) suffixed
+ * with "ago" — e.g. `5s ago`, `2m ago`. Clock-skew (heartbeat timestamp in
+ * the future) renders as `just now`; a malformed timestamp renders as
+ * `unknown`.
+ */
+import type { AttachmentInfo } from '../types';
+export declare function formatAttachmentInfoForDisplay(name: string, info: AttachmentInfo, now?: number): string[];
+export declare function formatHeartbeatAge(lastHeartbeatAt: string, now: number): string;

package/dist/utils/attachment-format.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatAttachmentInfoForDisplay = formatAttachmentInfoForDisplay;
+exports.formatHeartbeatAge = formatHeartbeatAge;
+const duration_1 = require("./duration");
+function formatAttachmentInfoForDisplay(name, info, now = Date.now()) {
+    const lines = [
+        `${name} — phase: ${info.phase}`,
+        `  in-flight: ${info.inFlightCount}`,
+    ];
+    if (info.currentAttachment) {
+        const a = info.currentAttachment;
+        lines.push(`  attached on: ${a.hostname} (adapter: ${a.adapterId}/${a.adapterClass})`);
+        lines.push(`  attachmentId: ${a.attachmentId}`);
+        lines.push(`  lease expires: ${a.expiresAt}`);
+        lines.push(`  heartbeat: ${formatHeartbeatAge(a.lastHeartbeatAt, now)}`);
+    }
+    if (info.preferredHost)
+        lines.push(`  preferred host: ${info.preferredHost}`);
+    if (info.processingSince)
+        lines.push(`  processing since: ${info.processingSince}`);
+    return lines;
+}
+function formatHeartbeatAge(lastHeartbeatAt, now) {
+    const then = Date.parse(lastHeartbeatAt);
+    if (!Number.isFinite(then))
+        return 'unknown';
+    const ageMs = now - then;
+    if (ageMs < 0)
+        return 'just now'; // adapter clock ran ahead of ours — degrade gracefully
+    return `${(0, duration_1.formatDurationMs)(ageMs)} ago`;
+}

package/dist/utils/default-part.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Adapter types that are considered "headless" — i.e. they run without
+ * an interactive terminal. When a session has no explicit `part` and no
+ * player type, a headless adapter gets `'Headless <adapter> session'`
+ * instead of the generic `'Session in <basename>'`.
+ *
+ * Issue #537.
+ */
+export declare const HEADLESS_ADAPTERS: Set<string>;
+/**
+ * Compute the default `part` text seeded into a fresh session workflow.
+ *
+ * Issue #450 — replaces the hardcoded `'Conductor session'` literal
+ * (which leaked through to non-conductor players via the rev3-cert
+ * deferred audit item R3.P2.5) and the role-agnostic
+ * `'Session in <basename>'` fallback with a single helper that picks a
+ * default reflecting the player's role whenever a player type is
+ * resolvable.
+ *
+ * Resolution order:
+ *   1. If `playerType` is set, derive from the suffix after stripping
+ *      `tempo-` / `my-tempo-` / `la-tempo-`. Abbreviations live in
+ *      `ROLE_ABBREVIATIONS`; everything else is title-cased:
+ *        `tempo-conductor`     → `'Conductor session'`
+ *        `my-tempo-engineer`   → `'Engineer session'`
+ *        `my-tempo-qa`         → `'QA session'`
+ *        `my-tempo-devops`     → `'DevOps session'`
+ *        `la-tempo-advisor`    → `'Advisor session'`
+ *        `acme-reviewer`       → `'Acme-reviewer session'` (no prefix match)
+ *   2. Else if `isConductor`, return `'Conductor session'` (the
+ *      pre-#450 conductor literal — kept so untyped conductor sessions
+ *      still read correctly).
+ *   3. Else if the adapter is headless (#537), return
+ *      `'Headless <adapterType> session'`.
+ *   4. Else fall back to `'Session in <basename(workDir)>'`, or
+ *      `'New session'` when no `workDir` is provided.
+ */
+export declare function defaultPart(opts: {
+    playerType?: string;
+    isConductor?: boolean;
+    workDir?: string;
+    adapterType?: string;
+}): string;

package/dist/utils/default-part.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HEADLESS_ADAPTERS = void 0;
+exports.defaultPart = defaultPart;
+const path_1 = __importDefault(require("path"));
+/**
+ * Match the common agent-tempo agent-type prefixes so the suffix can be
+ * surfaced as a human-readable role:
+ *   - `tempo-*`     (shipped types: tempo-conductor, tempo-soloist, …)
+ *   - `my-tempo-*`  (per-user overrides under `~/.claude/agents/`)
+ *   - `la-tempo-*`  (workspace/project agents under `.claude/agents/`)
+ *
+ * Anything that doesn't match falls through and the full type name is
+ * title-cased instead, so a custom `acme-reviewer` type still reads as
+ * `'Acme-reviewer session'` rather than something nonsensical.
+ */
+const PLAYER_TYPE_PREFIX = /^(my-|la-)?tempo-/i;
+/**
+ * Roles whose canonical capitalisation is not what naive title-casing
+ * produces (e.g. `qa` would become `'Qa'`). Keys are the lowercased
+ * suffix after `PLAYER_TYPE_PREFIX` is stripped; values are the
+ * display string spliced into `'<value> session'`.
+ *
+ * Add entries sparingly — most types follow the title-case rule and
+ * shouldn't need a special case.
+ */
+const ROLE_ABBREVIATIONS = {
+    qa: 'QA',
+    po: 'PO',
+    devops: 'DevOps',
+};
+/**
+ * Adapter types that are considered "headless" — i.e. they run without
+ * an interactive terminal. When a session has no explicit `part` and no
+ * player type, a headless adapter gets `'Headless <adapter> session'`
+ * instead of the generic `'Session in <basename>'`.
+ *
+ * Issue #537.
+ */
+exports.HEADLESS_ADAPTERS = new Set([
+    'claude-code-headless',
+    'copilot',
+    'opencode',
+    'claude-api',
+    'mock',
+]);
+/**
+ * Compute the default `part` text seeded into a fresh session workflow.
+ *
+ * Issue #450 — replaces the hardcoded `'Conductor session'` literal
+ * (which leaked through to non-conductor players via the rev3-cert
+ * deferred audit item R3.P2.5) and the role-agnostic
+ * `'Session in <basename>'` fallback with a single helper that picks a
+ * default reflecting the player's role whenever a player type is
+ * resolvable.
+ *
+ * Resolution order:
+ *   1. If `playerType` is set, derive from the suffix after stripping
+ *      `tempo-` / `my-tempo-` / `la-tempo-`. Abbreviations live in
+ *      `ROLE_ABBREVIATIONS`; everything else is title-cased:
+ *        `tempo-conductor`     → `'Conductor session'`
+ *        `my-tempo-engineer`   → `'Engineer session'`
+ *        `my-tempo-qa`         → `'QA session'`
+ *        `my-tempo-devops`     → `'DevOps session'`
+ *        `la-tempo-advisor`    → `'Advisor session'`
+ *        `acme-reviewer`       → `'Acme-reviewer session'` (no prefix match)
+ *   2. Else if `isConductor`, return `'Conductor session'` (the
+ *      pre-#450 conductor literal — kept so untyped conductor sessions
+ *      still read correctly).
+ *   3. Else if the adapter is headless (#537), return
+ *      `'Headless <adapterType> session'`.
+ *   4. Else fall back to `'Session in <basename(workDir)>'`, or
+ *      `'New session'` when no `workDir` is provided.
+ */
+function defaultPart(opts) {
+    const playerType = opts.playerType?.trim();
+    if (playerType) {
+        const suffix = playerType.replace(PLAYER_TYPE_PREFIX, '');
+        if (suffix) {
+            const abbrev = ROLE_ABBREVIATIONS[suffix.toLowerCase()];
+            if (abbrev) {
+                return `${abbrev} session`;
+            }
+            const titled = suffix.charAt(0).toUpperCase() + suffix.slice(1);
+            return `${titled} session`;
+        }
+    }
+    if (opts.isConductor) {
+        return 'Conductor session';
+    }
+    // Issue #537 — headless adapters get a descriptive default when
+    // neither playerType nor isConductor identify the session.
+    const adapterType = opts.adapterType?.trim();
+    if (adapterType && exports.HEADLESS_ADAPTERS.has(adapterType)) {
+        return `Headless ${adapterType} session`;
+    }
+    if (opts.workDir && opts.workDir.trim()) {
+        return `Session in ${path_1.default.basename(opts.workDir)}`;
+    }
+    return 'New session';
+}

package/dist/utils/duration.d.ts

@@ -0,0 +1,30 @@
+/** Parse a duration string like "30s", "10m", "2h", "1d" into milliseconds. */
+export declare function parseDuration(dur: string): number | null;
+/**
+ * Humanise a millisecond count as a short duration string: `30s` / `5m` /
+ * `2h` / `1d`. Picks the largest unit whose integer-or-fractional value is
+ * ≥ 1. Inverse (roughly) of {@link parseDuration}; matches the output shape
+ * several other surfaces emit (scheduler listings, attachment-info CLI).
+ *
+ * Consolidated here as part of #264 so the shared attachment-info formatter
+ * in `src/utils/attachment-format.ts` doesn't drag the CLI-local duplicate.
+ * Other local duplicates exist at `src/ensemble/saver.ts` and
+ * `src/tools/schedules.ts` — those can be migrated incrementally; leaving
+ * them alone keeps this PR's scope tight.
+ */
+export declare function formatDurationMs(ms: number): string;
+/**
+ * Render an ISO timestamp as a coarse "N{s,m,h,d} ago" string for human-
+ * readable listings. Returns `"just now"` for ≤1s, `"unknown"` if the
+ * timestamp can't be parsed.
+ *
+ * `now` is injectable for deterministic tests; defaults to `Date.now()`.
+ *
+ * **Why a second time helper exists** (the TUI has `formatRelativeTime`
+ * in `src/tui/utils/format.ts` doing roughly the same thing):
+ * `src/tui/` carries Ink/React transitive imports the headless tools layer
+ * mustn't take on. This helper has zero dependencies and is freely
+ * importable by any layer. Consolidation across the two homes is tracked
+ * as future deduplication work, not in scope here.
+ */
+export declare function formatTimeAgo(iso: string, now?: number): string;

package/dist/utils/duration.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDuration = parseDuration;
+exports.formatDurationMs = formatDurationMs;
+exports.formatTimeAgo = formatTimeAgo;
+/** Parse a duration string like "30s", "10m", "2h", "1d" into milliseconds. */
+function parseDuration(dur) {
+    const match = dur.match(/^(\d+(?:\.\d+)?)\s*(s|m|h|d)$/i);
+    if (!match)
+        return null;
+    const value = parseFloat(match[1]);
+    switch (match[2].toLowerCase()) {
+        case 's': return value * 1000;
+        case 'm': return value * 60_000;
+        case 'h': return value * 3_600_000;
+        case 'd': return value * 86_400_000;
+        default: return null;
+    }
+}
+/**
+ * Humanise a millisecond count as a short duration string: `30s` / `5m` /
+ * `2h` / `1d`. Picks the largest unit whose integer-or-fractional value is
+ * ≥ 1. Inverse (roughly) of {@link parseDuration}; matches the output shape
+ * several other surfaces emit (scheduler listings, attachment-info CLI).
+ *
+ * Consolidated here as part of #264 so the shared attachment-info formatter
+ * in `src/utils/attachment-format.ts` doesn't drag the CLI-local duplicate.
+ * Other local duplicates exist at `src/ensemble/saver.ts` and
+ * `src/tools/schedules.ts` — those can be migrated incrementally; leaving
+ * them alone keeps this PR's scope tight.
+ */
+function formatDurationMs(ms) {
+    if (ms >= 86_400_000)
+        return `${ms / 86_400_000}d`;
+    if (ms >= 3_600_000)
+        return `${ms / 3_600_000}h`;
+    if (ms >= 60_000)
+        return `${ms / 60_000}m`;
+    return `${ms / 1000}s`;
+}
+/**
+ * Render an ISO timestamp as a coarse "N{s,m,h,d} ago" string for human-
+ * readable listings. Returns `"just now"` for ≤1s, `"unknown"` if the
+ * timestamp can't be parsed.
+ *
+ * `now` is injectable for deterministic tests; defaults to `Date.now()`.
+ *
+ * **Why a second time helper exists** (the TUI has `formatRelativeTime`
+ * in `src/tui/utils/format.ts` doing roughly the same thing):
+ * `src/tui/` carries Ink/React transitive imports the headless tools layer
+ * mustn't take on. This helper has zero dependencies and is freely
+ * importable by any layer. Consolidation across the two homes is tracked
+ * as future deduplication work, not in scope here.
+ */
+function formatTimeAgo(iso, now = Date.now()) {
+    const t = Date.parse(iso);
+    if (!Number.isFinite(t))
+        return 'unknown';
+    const ms = now - t;
+    if (ms < 1000)
+        return 'just now';
+    if (ms < 60_000)
+        return `${Math.floor(ms / 1000)}s ago`;
+    if (ms < 3_600_000)
+        return `${Math.floor(ms / 60_000)}m ago`;
+    if (ms < 86_400_000)
+        return `${Math.floor(ms / 3_600_000)}h ago`;
+    return `${Math.floor(ms / 86_400_000)}d ago`;
+}

package/dist/utils/ensemble-ops.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared ensemble-scope plumbing for the MCP tool handlers (`pause`, `play`,
+ * `shutdown`, `restore`, ensemble-scope `destroy`) and their `TempoClient`
+ * counterparts.
+ *
+ * All of these verbs need the same bits:
+ *   1. Toggle the maestro + scheduler pause signals, tolerating "workflow
+ *      not running" on each because a bare-bones ensemble may lack either.
+ *   2. Fan out a signal (or update) across every session in the ensemble.
+ *
+ * Inlining these at each call site was pushing the diff past the architect's
+ * 500-line budget on PR #287 and bloating every new verb with near-identical
+ * try/catch scaffolding. This module is the single source of truth for both
+ * layers (tools + TempoClient) so a future signal-name rename or fan-out
+ * concurrency tweak only has to change here.
+ */
+import type { Client } from '@temporalio/client';
+/**
+ * Result of a pause/unpause toggle. Each flag reflects whether the signal
+ * was actually delivered — `false` means the workflow wasn't running and
+ * the error was swallowed (the common bare-ensemble case).
+ */
+export interface MaestroSchedulerToggleResult {
+    maestro: boolean;
+    scheduler: boolean;
+}
+/** Pause the ensemble's maestro + scheduler. Best-effort on both. */
+export declare function pauseMaestroAndScheduler(client: Client, ensemble: string): Promise<MaestroSchedulerToggleResult>;
+/** Unpause the ensemble's maestro + scheduler. Best-effort on both. */
+export declare function unpauseMaestroAndScheduler(client: Client, ensemble: string): Promise<MaestroSchedulerToggleResult>;
+/**
+ * Fan-out a signal across every session in the ensemble. Per-session calls
+ * run in parallel via `Promise.allSettled` so a slow / failing session
+ * doesn't block the others — all Temporal ensembles are inherently
+ * unordered at this boundary (each session has its own workflow).
+ *
+ * `skip(playerId)` lets the caller exclude specific sessions (e.g. the
+ * caller's own session) without an extra pass.
+ */
+export interface FanoutSignalResult {
+    sent: number;
+    skipped: number;
+    failed: number;
+    perSession: Array<{
+        playerId: string;
+        workflowId: string;
+        outcome: 'sent';
+    } | {
+        playerId: string;
+        workflowId: string;
+        outcome: 'skipped';
+    } | {
+        playerId: string;
+        workflowId: string;
+        outcome: 'failed';
+        error: string;
+    }>;
+}
+export declare function signalAllSessions(client: Client, ensemble: string, signalName: string, payload: unknown, opts?: {
+    skip?: (playerId: string) => boolean;
+}): Promise<FanoutSignalResult>;

package/dist/utils/ensemble-ops.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pauseMaestroAndScheduler = pauseMaestroAndScheduler;
+exports.unpauseMaestroAndScheduler = unpauseMaestroAndScheduler;
+exports.signalAllSessions = signalAllSessions;
+const config_1 = require("../config");
+const resolve_1 = require("../activities/resolve");
+const maestro_signals_1 = require("../workflows/maestro-signals");
+const scheduler_signals_1 = require("../workflows/scheduler-signals");
+/** Pause the ensemble's maestro + scheduler. Best-effort on both. */
+async function pauseMaestroAndScheduler(client, ensemble) {
+    return toggleMaestroAndScheduler(client, ensemble, true);
+}
+/** Unpause the ensemble's maestro + scheduler. Best-effort on both. */
+async function unpauseMaestroAndScheduler(client, ensemble) {
+    return toggleMaestroAndScheduler(client, ensemble, false);
+}
+async function toggleMaestroAndScheduler(client, ensemble, paused) {
+    // Two independent RPCs — run them in parallel. Each catches its own
+    // error so one missing workflow doesn't block the other's state change.
+    const [maestro, scheduler] = await Promise.all([
+        safeSignal(client, (0, config_1.maestroWorkflowId)(ensemble), maestro_signals_1.maestroSetPausedSignal.name, paused),
+        safeSignal(client, (0, config_1.schedulerWorkflowId)(ensemble), scheduler_signals_1.setSchedulerPausedSignal.name, paused),
+    ]);
+    return { maestro, scheduler };
+}
+async function safeSignal(client, workflowId, signalName, payload) {
+    try {
+        await client.workflow.getHandle(workflowId).signal(signalName, payload);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function signalAllSessions(client, ensemble, signalName, payload, opts = {}) {
+    const sessions = await (0, resolve_1.scanEnsembleSessions)(client, ensemble);
+    const shouldSkip = opts.skip ?? (() => false);
+    const result = { sent: 0, skipped: 0, failed: 0, perSession: [] };
+    const settled = await Promise.allSettled(sessions.map(async (s) => {
+        if (shouldSkip(s.playerId)) {
+            return { session: s, outcome: 'skipped' };
+        }
+        try {
+            await client.workflow.getHandle(s.workflowId).signal(signalName, payload);
+            return { session: s, outcome: 'sent' };
+        }
+        catch (err) {
+            return {
+                session: s,
+                outcome: 'failed',
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }));
+    for (const r of settled) {
+        // `Promise.allSettled` only rejects if the mapper itself throws, and
+        // the mapper catches all signal errors internally — so every entry
+        // here will be `fulfilled`.
+        if (r.status !== 'fulfilled')
+            continue;
+        const v = r.value;
+        if (v.outcome === 'sent') {
+            result.sent++;
+            result.perSession.push({ playerId: v.session.playerId, workflowId: v.session.workflowId, outcome: 'sent' });
+        }
+        else if (v.outcome === 'skipped') {
+            result.skipped++;
+            result.perSession.push({ playerId: v.session.playerId, workflowId: v.session.workflowId, outcome: 'skipped' });
+        }
+        else {
+            result.failed++;
+            result.perSession.push({ playerId: v.session.playerId, workflowId: v.session.workflowId, outcome: 'failed', error: v.error });
+        }
+    }
+    return result;
+}

package/dist/utils/format-hosts.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared formatter for the #274 `hosts` surface.
+ *
+ * Single source of truth consumed by:
+ *   - `src/tools/hosts.ts` (MCP tool) — formatted text in `ok(...)` payload
+ *   - `src/cli/commands.ts` (CLI `hosts` command) — stdout table
+ *   - `src/tui/commands.ts` (TUI `/hosts` slash) — overlay content
+ *
+ * Pure: no Temporal, no I/O, no ANSI colors (the CLI can wrap lines in
+ * color downstream if desired; the formatter emits plain strings so
+ * tests can assert exact output without stripping escape codes).
+ */
+import type { HostInfo } from '../types';
+export interface FormatHostsOpts {
+    /**
+     * Include hosts whose freshness is `'stale'`. Default `false`:
+     * CLI/TUI hide them by default; `--all` opts in.
+     */
+    includeStale?: boolean;
+}
+export declare function formatHostList(hosts: HostInfo[], opts?: FormatHostsOpts): string;

package/dist/utils/format-hosts.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatHostList = formatHostList;
+function formatHostList(hosts, opts = {}) {
+    const includeStale = opts.includeStale ?? false;
+    const visible = includeStale ? hosts : hosts.filter((h) => h.freshness === 'live');
+    if (visible.length === 0) {
+        if (!includeStale && hosts.length > 0) {
+            return 'No live hosts connected. Pass `--all` to include stale hosts.';
+        }
+        return 'No hosts connected.';
+    }
+    const lines = [];
+    lines.push(`${visible.length} host${visible.length === 1 ? '' : 's'} connected:`);
+    lines.push('');
+    for (const host of visible) {
+        lines.push(...formatSingleHost(host));
+        lines.push('');
+    }
+    // Drop the final empty line so consumers don't have to `.trim()`.
+    if (lines[lines.length - 1] === '')
+        lines.pop();
+    return lines.join('\n');
+}
+function formatSingleHost(host) {
+    const lines = [];
+    const tag = host.freshness === 'live' ? '' : ' (stale)';
+    const recruit = host.recruitReady ? 'recruit-ready' : 'not recruit-ready';
+    lines.push(`**${host.hostname}**${tag} — ${recruit}`);
+    // Instance(s). One-liner per pid.
+    for (const inst of host.instances) {
+        const bits = [`pid ${inst.pid}`, `version ${inst.version}`];
+        const workerBits = [];
+        if (inst.hasWorkflowWorker)
+            workerBits.push('wf');
+        if (inst.hasActivityWorker)
+            workerBits.push('act');
+        if (inst.hasHostQueueWorker)
+            workerBits.push('host');
+        bits.push(`workers: ${workerBits.length > 0 ? workerBits.join('+') : 'none'}`);
+        if (inst.lastAccessTime)
+            bits.push(`last seen ${inst.lastAccessTime}`);
+        if (inst.legacy)
+            bits.push('legacy-identity');
+        lines.push(`  - ${bits.join(' · ')}`);
+    }
+    // Profile (capability).
+    if (host.profile) {
+        const p = host.profile;
+        const profileBits = [];
+        if (p.platform)
+            profileBits.push(`platform: ${p.platform}`);
+        if (p.defaultAgent)
+            profileBits.push(`default agent: ${p.defaultAgent}`);
+        if (p.claudeBin)
+            profileBits.push(`claude bin: ${p.claudeBin}`);
+        if (profileBits.length > 0)
+            lines.push(`  profile · ${profileBits.join(' · ')}`);
+        if (p.availableAgentTypes && p.availableAgentTypes.length > 0) {
+            lines.push(`    available agents: ${p.availableAgentTypes.join(', ')}`);
+        }
+        if (p.availablePlayerTypes && p.availablePlayerTypes.length > 0) {
+            lines.push(`    available player types: ${p.availablePlayerTypes.join(', ')}`);
+        }
+        if (host.profileStaleness === 'stale') {
+            lines.push(`    ⚠ profile version disagrees with live identity — awaiting re-signal`);
+        }
+    }
+    else if (host.profileStaleness === 'missing') {
+        lines.push(`  (profile unavailable)`);
+    }
+    return lines;
+}