agent-tempo 1.0.1

package/dist/tui/commands.js

@@ -0,0 +1,1375 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMANDS = exports.SUBCOMMAND_MAP = exports.PLAYER_PARAM_COMMANDS = exports.filterPlayerNames = exports.filterPaletteCommands = exports.classifyPaletteInput = exports.parseCommand = exports.tokenize = void 0;
+exports.commitNotification = commitNotification;
+exports.parseRecallFlags = parseRecallFlags;
+exports.formatTimestamp = formatTimestamp;
+exports.getCommandNames = getCommandNames;
+exports.isValidCommand = isValidCommand;
+exports.formatHelpSummary = formatHelpSummary;
+/**
+ * Slash command parser and registry for the TUI shell.
+ * Parses user input into structured commands and provides handler
+ * implementations for each command.
+ *
+ * **#471/#472**: The pure helpers (`parseCommand`, `tokenize`,
+ * `classifyPaletteInput`, `filterPaletteCommands`, `filterPlayerNames`,
+ * `PLAYER_PARAM_COMMANDS`, `SUBCOMMAND_MAP`) live in `src/palette/` and
+ * are re-exported below so the TUI's surface stays unchanged. The
+ * dashboard imports the same helpers via `agent-tempo/palette`.
+ */
+const os_1 = require("os");
+const store_1 = require("./store");
+const platform_1 = require("./utils/platform");
+const format_1 = require("./utils/format");
+const saver_1 = require("../ensemble/saver");
+const attachment_format_1 = require("../utils/attachment-format");
+const format_hosts_1 = require("../utils/format-hosts");
+const recall_format_1 = require("../utils/recall-format");
+// ── Re-exports (#471/#472 — palette helpers moved to src/palette) ──
+//
+// These re-exports keep the TUI's pre-extraction surface intact. Existing
+// callers (`PromptArea.tsx`, `tests/tui/palette.test.ts`,
+// `tests/tui/commands.test.ts`) keep importing from `../commands` /
+// `../../src/tui/commands` without change.
+var palette_1 = require("../palette");
+Object.defineProperty(exports, "tokenize", { enumerable: true, get: function () { return palette_1.tokenize; } });
+Object.defineProperty(exports, "parseCommand", { enumerable: true, get: function () { return palette_1.parseCommand; } });
+Object.defineProperty(exports, "classifyPaletteInput", { enumerable: true, get: function () { return palette_1.classifyPaletteInput; } });
+Object.defineProperty(exports, "filterPaletteCommands", { enumerable: true, get: function () { return palette_1.filterPaletteCommands; } });
+Object.defineProperty(exports, "filterPlayerNames", { enumerable: true, get: function () { return palette_1.filterPlayerNames; } });
+Object.defineProperty(exports, "PLAYER_PARAM_COMMANDS", { enumerable: true, get: function () { return palette_1.PLAYER_PARAM_COMMANDS; } });
+Object.defineProperty(exports, "SUBCOMMAND_MAP", { enumerable: true, get: function () { return palette_1.SUBCOMMAND_MAP; } });
+// ── Parser ──
+//
+// `tokenize` and `parseCommand` moved to `src/palette` in #471/#472 and
+// are re-exported above. They're imported into the TUI handler closures
+// below via the same import surface (`from '../commands'`) so callers
+// see no change.
+// ── Static item helper ──
+let _staticIdCounter = 0;
+function nextId() {
+    return `cmd-${++_staticIdCounter}`;
+}
+function commitStatic(dispatch, type, content) {
+    dispatch({
+        type: 'COMMIT_STATIC',
+        item: { id: nextId(), type, content, timestamp: Date.now() },
+    });
+}
+// ── Bottom-pinned notifications (#306) ──
+let _notificationIdCounter = 0;
+function nextNotificationId() {
+    return ++_notificationIdCounter;
+}
+/**
+ * #306: Dispatch a bottom-pinned notification — auto-expires after TTL
+ * (8s for errors, 5s for warn/info). Use for errors and warnings that
+ * must stay visible while other output streams by; regular activity
+ * logs still go through {@link commitStatic}.
+ */
+function commitNotification(dispatch, kind, content) {
+    const now = Date.now();
+    dispatch({
+        type: 'ADD_NOTIFICATION',
+        notification: {
+            id: nextNotificationId(),
+            kind,
+            content,
+            timestamp: now,
+            expiresAt: now + store_1.NOTIFICATION_TTL_MS[kind],
+        },
+    });
+}
+// ── Handlers ──
+/** /players — show interactive player picker. */
+async function handlePlayers(_args, dispatch, _api) {
+    // Show picker overlay — data comes from store (already polled)
+    dispatch({ type: 'SHOW_PICKER', pickerType: 'players' });
+}
+/** /player <name> — show detailed player info. */
+async function handlePlayer(args, dispatch, api, ctx) {
+    if (args.length === 0) {
+        // No args — show picker with navigate intent (App.tsx dispatches NAVIGATE_PLAYER on selection)
+        dispatch({ type: 'SHOW_PICKER', pickerType: 'players', intent: 'navigate' });
+        return;
+    }
+    const target = args[0];
+    try {
+        // Verify the player exists
+        const ensembles = ctx.activeEnsemble
+            ? [{ name: ctx.activeEnsemble }]
+            : await api.discoverEnsembles();
+        for (const ens of ensembles) {
+            const players = await api.getPlayers(ens.name);
+            const player = players.find(p => p.playerId === target);
+            if (!player)
+                continue;
+            // Navigate to the player detail view
+            dispatch({ type: 'NAVIGATE_PLAYER', playerId: target });
+            return;
+        }
+        commitNotification(dispatch, 'error', `Player "${target}" not found in any ensemble.`);
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `Failed to get player info: ${err}`);
+    }
+}
+/**
+ * /destroy <player> [reason] — request terminal-destroy confirmation.
+ *
+ * PR-H (#132): consolidates the legacy `/stop` slash command (which routed
+ * through `terminatePlayer` — raw Temporal terminate) and the no-confirm
+ * `/destroy` shipped in PR-D into one flow. The slash command always
+ * prompts y/N first; the yes-confirm handler in App.tsx routes through
+ * `TempoClient.destroy()` (V2 `destroyUpdate` via the outbox path) so the
+ * adapter's `isDestroyed` query sees the terminal state cleanly.
+ *
+ * The optional `reason` is concatenated from args[1..] and stashed on the
+ * action for the confirmation handler to forward to `destroy(reason)`.
+ */
+async function handleDestroy(args, dispatch, _api, ctx) {
+    if (args.length === 0) {
+        commitNotification(dispatch, 'error', 'Usage: /destroy <player|ensemble> [reason]');
+        return;
+    }
+    const target = args[0];
+    // #306: Conductor is an ensemble invariant (#294) — it can't be destroyed
+    // standalone without leaving the ensemble in an invalid state (no conductor
+    // to accept cues, no coordination). Redirect the user to the correct verb
+    // instead of silently dispatching a confirmation the UI never renders.
+    if (target === 'conductor') {
+        commitNotification(dispatch, 'error', `✗ Cannot destroy the conductor — ensembles require one (see #294). ` +
+            `Use /shutdown to park this ensemble, /restart conductor to revive it, or ` +
+            `/destroy ${ctx.activeEnsemble ?? '<ensemble>'} to terminate the whole ensemble.`);
+        return;
+    }
+    // Ensemble scope: target matches the active ensemble → typed-name
+    // confirmation. Player scope: any other target → y/N. The active-ensemble
+    // match is unambiguous inside a single-ensemble TUI session.
+    if (target === ctx.activeEnsemble) {
+        dispatch({ type: 'CONFIRM_ENSEMBLE_DESTROY', ensemble: target });
+        return;
+    }
+    // #306: CONFIRM_STOP locks the input line awaiting y/N. The discoverability
+    // prompt was previously emitted to scrollback via commitStatic, but that
+    // line scrolled off-screen as new messages arrived — leaving the user
+    // staring at a frozen input. Replaced with a pinned render in App.tsx
+    // (`renderPinnedConfirmations`) that persists exactly as long as
+    // `state.confirmingStop` does (no TTL). The reason carried here surfaces
+    // in the pinned line too.
+    const reason = args.slice(1).join(' ') || undefined;
+    dispatch({ type: 'CONFIRM_STOP', player: target, ...(reason !== undefined ? { reason } : {}) });
+}
+/** /broadcast <message> — send a message to all active players in the current ensemble. */
+async function handleBroadcast(args, dispatch, api, ctx) {
+    if (args.length === 0) {
+        commitNotification(dispatch, 'error', 'Usage: /broadcast <message>');
+        return;
+    }
+    if (!ctx.activeEnsemble) {
+        commitNotification(dispatch, 'error', 'No active ensemble. Select one with /ensemble first.');
+        return;
+    }
+    const message = args.join(' ');
+    try {
+        const players = await api.getPlayers(ctx.activeEnsemble);
+        let sent = 0;
+        for (const p of players) {
+            // Broadcast to talkable phases only — `active` (attached/processing) and
+            // `idle` (awaiting). Mirrors `shouldIncludeInBroadcast` in utils/validation.
+            const label = (0, format_1.phaseToLabel)(p.phase);
+            if (label === 'active' || label === 'idle') {
+                try {
+                    await api.sendMessage(ctx.activeEnsemble, p.playerId, message, 'maestro');
+                    sent++;
+                }
+                catch {
+                    // Skip individual failures
+                }
+            }
+        }
+        commitStatic(dispatch, 'message', `\u2714 Broadcast delivered to ${sent} player${sent !== 1 ? 's' : ''}: ${message}`);
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `\u2717 Broadcast failed: ${err}`);
+    }
+}
+/**
+ * /hosts [--all] — list daemons polling this Temporal namespace.
+ *
+ * #274. Surfaces the same data as `agent-tempo hosts` CLI and the
+ * `hosts` MCP tool via the shared `formatHostList` helper.
+ * `--all` opts into stale hosts; default hides them.
+ */
+async function handleHosts(args, dispatch, api) {
+    const includeStale = args.includes('--all');
+    try {
+        const list = await api.listHosts({ force: true });
+        dispatch({
+            type: 'SHOW_COMMAND_OVERLAY',
+            title: 'Hosts',
+            content: (0, format_hosts_1.formatHostList)(list, { includeStale }),
+        });
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `/hosts failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * /recall [player] [--limit N] [--offset N] [--preview N] [--from X]
+ *         [--since ISO] [--include-sent | --received-only]
+ *
+ * #128: unified per-session recall. Without a player positional, targets
+ * the ensemble's maestro session (the TUI's natural context); with a
+ * player positional, queries that player's session — same data shape the
+ * MCP `recall` tool and `agent-tempo recall <name>` CLI surface.
+ *
+ * The legacy pre-#128 behavior (aggregated maestro relay-log filtered
+ * by player) is retired; that path was inconsistent with the other two
+ * surfaces and the design doc on #128 explicitly chose parity.
+ *
+ * #361: The TUI default flipped to `includeSent: true` because the
+ * single-message view that `/recall` originally targeted was confusing
+ * when the user had just typed a message and wanted to see the dialog
+ * context. The MCP tool's default is unchanged (still received-only) so
+ * external callers see no contract drift. `--include-sent` is still
+ * accepted for backward compatibility (no-op when default is true);
+ * pass `--received-only` to opt out.
+ */
+async function handleRecall(args, dispatch, api, ctx) {
+    const ensemble = requireEnsemble(dispatch, ctx);
+    if (!ensemble)
+        return;
+    const parsed = parseRecallFlags(args);
+    if (parsed.error) {
+        commitNotification(dispatch, 'error', parsed.error);
+        return;
+    }
+    // Player defaults to the ensemble's maestro — see docstring.
+    const targetPlayer = parsed.player ?? 'maestro';
+    try {
+        const { received, sent } = await api.recall(ensemble, targetPlayer);
+        // #361: TUI default → include sent. `--received-only` opts out;
+        // `--include-sent` remains accepted (no-op now) for backward compat.
+        const includeSent = parsed.receivedOnly === true ? false : (parsed.includeSent ?? true);
+        const timeline = (0, recall_format_1.buildTimeline)(received, sent, includeSent);
+        const rendered = (0, recall_format_1.formatRecall)(timeline, {
+            limit: parsed.limit,
+            offset: parsed.offset,
+            previewLength: parsed.previewLength,
+            since: parsed.since,
+            from: parsed.from,
+        });
+        const title = `Recall \u00B7 ${targetPlayer}`;
+        dispatch({ type: 'SHOW_COMMAND_OVERLAY', title, content: rendered.text });
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `Failed to recall messages: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Parse the `/recall` arg vector into structured flags. Exported for unit
+ * tests; the TUI handler consumes the structured result directly.
+ *
+ * Accepted shapes:
+ *   `/recall`                                    — maestro session
+ *   `/recall alice`                              — alice's session
+ *   `/recall --limit 5 --preview 80`             — flags only
+ *   `/recall alice --limit 5 --include-sent`     — player + flags
+ *
+ * Unknown flags or non-numeric values for numeric flags produce a usage
+ * error rather than silent drop, so the user isn't surprised by a default.
+ */
+function parseRecallFlags(args) {
+    const out = {};
+    let i = 0;
+    // Leading non-flag positional is the player override.
+    if (args.length > 0 && !args[0].startsWith('--')) {
+        out.player = args[0];
+        i = 1;
+    }
+    while (i < args.length) {
+        const flag = args[i];
+        const consumeNumber = (name, key) => {
+            const raw = args[i + 1];
+            if (raw === undefined)
+                return `Missing value for ${name}`;
+            const n = Number(raw);
+            if (!Number.isFinite(n) || !Number.isInteger(n) || n < (key === 'offset' ? 0 : 1)) {
+                return `Invalid ${name}: ${raw}`;
+            }
+            // #270: cap --limit at 100 to match the MCP Zod schema. Recall queries
+            // load the full inbox/sent history from the workflow; the cap bounds
+            // the worst-case payload across every surface. Error message matches
+            // the CLI parser at `src/cli.ts` verbatim so operators see the same
+            // suggestion regardless of entry point.
+            if (key === 'limit' && n > 100) {
+                return `--limit exceeds max (100). Use --offset N to page through more results.`;
+            }
+            out[key] = n;
+            i += 2;
+            return null;
+        };
+        const consumeString = (name, key) => {
+            const raw = args[i + 1];
+            if (raw === undefined)
+                return `Missing value for ${name}`;
+            out[key] = raw;
+            i += 2;
+            return null;
+        };
+        let err = null;
+        switch (flag) {
+            case '--limit':
+                err = consumeNumber('--limit', 'limit');
+                break;
+            case '--offset':
+                err = consumeNumber('--offset', 'offset');
+                break;
+            case '--preview':
+                err = consumeNumber('--preview', 'previewLength');
+                break;
+            case '--since':
+                err = consumeString('--since', 'since');
+                break;
+            case '--from':
+                err = consumeString('--from', 'from');
+                break;
+            case '--include-sent':
+                out.includeSent = true;
+                i += 1;
+                break;
+            // #361: opt out of the post-flip default (received + sent).
+            case '--received-only':
+                out.receivedOnly = true;
+                i += 1;
+                break;
+            default: err = `Unknown flag: ${flag}`;
+        }
+        if (err)
+            return { error: err };
+    }
+    return out;
+}
+// ── PR-D verbs — thin handlers calling TempoClient methods ──
+function requireEnsemble(dispatch, ctx) {
+    if (!ctx.activeEnsemble) {
+        commitNotification(dispatch, 'error', 'No active ensemble. Use /ensemble <name> first.');
+        return null;
+    }
+    return ctx.activeEnsemble;
+}
+/** /restart <player> [--fresh] [--no-force] [--load-from-state[=key]] [--stack-transcript] — revive a player session per §8.2. */
+async function handleRestart(args, dispatch, api, ctx) {
+    if (args.length === 0) {
+        commitNotification(dispatch, 'error', 'Usage: /restart <player> [--fresh] [--no-force] [--load-from-state[=key]] [--stack-transcript]');
+        return;
+    }
+    const ensemble = requireEnsemble(dispatch, ctx);
+    if (!ensemble)
+        return;
+    const target = args[0];
+    const fresh = args.includes('--fresh');
+    // Default: steal the lease. /restart is nearly always invoked against a
+    // live-but-unresponsive session, so forcing is the common case. Pass
+    // --no-force to refuse if a live attachment is present.
+    const force = !args.includes('--no-force');
+    // #334 PR-2 — saved-state seed. `--load-from-state` (no value) → default
+    // key 'main'; `--load-from-state=<key>` → named slot; `--load-from-state=`
+    // (empty after `=`) collapses to default rather than failing the Zod
+    // regex with a confusing slot-key validation error. `--stack-transcript`
+    // opts into stacking the transcript replay on top of the saved state.
+    const loadStateArg = args.find((a) => a === '--load-from-state' || a.startsWith('--load-from-state='));
+    let loadFromState;
+    if (loadStateArg !== undefined) {
+        const eqIdx = loadStateArg.indexOf('=');
+        const keyPart = eqIdx >= 0 ? loadStateArg.slice(eqIdx + 1) : '';
+        loadFromState = keyPart.length > 0 ? keyPart : true;
+    }
+    const transcript = args.includes('--stack-transcript') ? 'replay' : undefined;
+    try {
+        const result = await api.restart(ensemble, target, {
+            fresh,
+            force,
+            invokerPlayerId: 'tui',
+            ...(loadFromState !== undefined ? { loadFromState } : {}),
+            ...(transcript !== undefined ? { transcript } : {}),
+        });
+        // #306: Command-result summary as a bottom-pinned notification so it
+        // stays visible while subsequent activity (heartbeats, joins, etc.)
+        // streams into scrollback. Pre-#306 this rode commitStatic('info') and
+        // the user often missed the entryId / host on a busy ensemble.
+        commitNotification(dispatch, 'info', `\u21BB Restart queued for ${result.playerId}${result.host ? ` on ${result.host}` : ''} (outbox ${result.entryId}).`);
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `Restart failed for ${target}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * /migrate <player> <host> [--fresh] [--force] [--yes-steal=<hostname>] — restart on a different host.
+ *
+ * #580 — when `--force` is set AND the target's current attachment is on a
+ * host other than the operator's, the deliberate-action gate from design
+ * §16.5 Option B requires `--yes-steal=<currentHost>` to match the holder's
+ * hostname exactly. This mirrors the MCP-tool guard (`enforceYesStealGuard`
+ * in `src/tools/restart.ts`) — making the operator type the host being stolen
+ * from prevents accidental cross-host takeover by the same finger habit that
+ * mashes `y` at any prompt. The MCP path was always covered; the TUI was the
+ * only operator surface that bypassed it.
+ */
+async function handleMigrate(args, dispatch, api, ctx) {
+    if (args.length < 2) {
+        commitNotification(dispatch, 'error', 'Usage: /migrate <player> <host> [--fresh] [--force] [--yes-steal=<hostname>]');
+        return;
+    }
+    const ensemble = requireEnsemble(dispatch, ctx);
+    if (!ensemble)
+        return;
+    const target = args[0];
+    const host = args[1];
+    const fresh = args.includes('--fresh');
+    const force = args.includes('--force');
+    // #580 — `--yes-steal=<hostname>` parsing. Same shape as
+    // `--load-from-state=<key>` in handleRestart: accept `--yes-steal=value`
+    // (canonical), reject the bare flag with a friendly hint because the
+    // gate's whole UX value is naming the host explicitly.
+    const yesStealArg = args.find((a) => a === '--yes-steal' || a.startsWith('--yes-steal='));
+    let confirmStealFromHost;
+    if (yesStealArg !== undefined) {
+        const eqIdx = yesStealArg.indexOf('=');
+        const valuePart = eqIdx >= 0 ? yesStealArg.slice(eqIdx + 1).trim() : '';
+        if (valuePart.length === 0) {
+            commitNotification(dispatch, 'error', "--yes-steal requires a hostname: --yes-steal=<currentHost>. The flag's safety property is that you type the host name being stolen from.");
+            return;
+        }
+        confirmStealFromHost = valuePart;
+    }
+    // #580 — cross-host force-migrate gate. Only fires when --force is set
+    // AND the target's current attachment is on a different host. Mirrors
+    // the lookup `enforceYesStealGuard` does on the MCP side.
+    if (force) {
+        const localHostname = ctx.localHostname ?? (0, os_1.hostname)();
+        let currentHost;
+        try {
+            const info = await api.attachmentInfo(ensemble, target);
+            currentHost = info.currentAttachment?.hostname;
+        }
+        catch {
+            // If we can't read the phase, fall through and let downstream
+            // handle the state. Not our job to synthesize a phantom guard
+            // failure from a transient query error.
+        }
+        if (currentHost && currentHost !== localHostname) {
+            if (!confirmStealFromHost) {
+                commitNotification(dispatch, 'error', `session "${target}" is attached to host "${currentHost}".\n` +
+                    `To confirm moving it, re-run with --yes-steal:\n\n` +
+                    `  /migrate ${target} ${host} --force --yes-steal=${currentHost}\n\n` +
+                    `This safety flag prevents accidental cross-host session takeover.`);
+                return;
+            }
+            if (confirmStealFromHost !== currentHost) {
+                commitNotification(dispatch, 'error', `--yes-steal mismatch: session "${target}" is on "${currentHost}", ` +
+                    `not "${confirmStealFromHost}". Re-run with --yes-steal=${currentHost}.`);
+                return;
+            }
+        }
+    }
+    try {
+        const result = await api.migrate(ensemble, target, host, {
+            fresh,
+            force,
+            invokerPlayerId: 'tui',
+            ...(confirmStealFromHost !== undefined ? { confirmStealFromHost } : {}),
+        });
+        commitStatic(dispatch, 'info', `\u27A4 Migrate queued for ${result.playerId} \u2192 ${result.host ?? host} (outbox ${result.entryId}).`);
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `Migrate failed for ${target}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** /attachment-info <player> — inspect the V2 attachment phase + current holder. */
+async function handleAttachmentInfo(args, dispatch, api, ctx) {
+    if (args.length === 0) {
+        commitNotification(dispatch, 'error', 'Usage: /attachment-info <player>');
+        return;
+    }
+    const ensemble = requireEnsemble(dispatch, ctx);
+    if (!ensemble)
+        return;
+    const target = args[0];
+    try {
+        const info = await api.attachmentInfo(ensemble, target);
+        // #264: share the display formatter with the CLI (`src/utils/attachment-format.ts`)
+        // so both surfaces render heartbeat age + match each other's field order /
+        // edge-case handling. Pre-#264 this block inlined a near-identical render
+        // but omitted heartbeat age, creating a latent parity gap.
+        const lines = (0, attachment_format_1.formatAttachmentInfoForDisplay)(target, info);
+        dispatch({ type: 'SHOW_COMMAND_OVERLAY', title: `Attachment \u00B7 ${target}`, content: lines.join('\n') });
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `attachment_info failed for ${target}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** /recruit [name] — launch the recruit wizard. Pre-fills name if given. */
+async function handleRecruit(args, dispatch, _api, ctx) {
+    // Parse optional inline args: /recruit name --type foo --dir /path
+    const answers = {};
+    if (args.length > 0 && !args[0].startsWith('--')) {
+        answers.name = args[0];
+    }
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--type' && args[i + 1])
+            answers.playerType = args[++i];
+        if (args[i] === '--dir' && args[i + 1])
+            answers.workDir = args[++i];
+        if (args[i] === '--agent' && args[i + 1])
+            answers.agent = args[++i];
+        if (args[i] === '--host' && args[i + 1])
+            answers.host = args[++i];
+    }
+    dispatch({ type: 'ENTER_RECRUIT', answers, defaultAgent: ctx.defaultAgent });
+}
+/** Delete a schedule by name — shared logic for /schedule delete and /unschedule. */
+async function deleteSchedule(name, dispatch, api, ctx) {
+    if (!ctx.activeEnsemble) {
+        commitNotification(dispatch, 'error', 'No active ensemble. Select one with /ensemble first.');
+        return;
+    }
+    try {
+        await api.cancelSchedule(ctx.activeEnsemble, name);
+        commitStatic(dispatch, 'message', `\u2714 Schedule "${name}" deleted.`);
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `\u2717 Failed to delete schedule "${name}": ${err}`);
+    }
+}
+/** /schedule [create|delete <name>] — manage schedules. */
+async function handleSchedule(args, dispatch, api, ctx) {
+    if (args.length > 0) {
+        const sub = args[0].toLowerCase();
+        // /schedule create → enter wizard
+        if (sub === 'create') {
+            dispatch({ type: 'ENTER_SCHEDULE_WIZARD' });
+            return;
+        }
+        // /schedule delete <name>
+        if (sub === 'delete') {
+            if (args.length < 2) {
+                commitNotification(dispatch, 'error', 'Usage: /schedule delete <name>');
+                return;
+            }
+            await deleteSchedule(args[1], dispatch, api, ctx);
+            return;
+        }
+        commitNotification(dispatch, 'error', `Unknown subcommand: ${sub}. Usage: /schedule [create | delete <name>]`);
+        return;
+    }
+    // /schedule (no args) → show interactive overlay
+    if (!ctx.activeEnsemble) {
+        commitNotification(dispatch, 'error', 'No active ensemble. Select one with /ensemble first.');
+        return;
+    }
+    try {
+        const schedules = await api.getSchedules(ctx.activeEnsemble);
+        if (schedules.length === 0) {
+            dispatch({
+                type: 'SHOW_OVERLAY',
+                overlay: {
+                    type: 'schedules',
+                    title: 'Schedules',
+                    items: [{ id: '_empty', label: 'No active schedules' }],
+                    hint: 'n=new  esc=close',
+                },
+            });
+            return;
+        }
+        const items = schedules.map(s => {
+            const timingParts = [];
+            if (s.type === 'interval' && s.interval) {
+                timingParts.push(`every ${formatMs(s.interval)}`);
+            }
+            if (s.cronExpression) {
+                timingParts.push(`cron: ${s.cronExpression}`);
+            }
+            if (s.nextFireAt) {
+                timingParts.push(`next: ${formatTimestamp(s.nextFireAt)}`);
+            }
+            if (s.firedCount > 0) {
+                timingParts.push(`fired ${s.firedCount}x`);
+            }
+            return {
+                id: s.name,
+                label: `${s.name} \u2192 ${s.target}`,
+                sublabel: timingParts.join('  \u00B7  ') || s.type,
+            };
+        });
+        dispatch({
+            type: 'SHOW_OVERLAY',
+            overlay: {
+                type: 'schedules',
+                title: 'Schedules',
+                items,
+                hint: 'n=new  d=delete  esc=close',
+            },
+        });
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `Failed to fetch schedules: ${err}`);
+    }
+}
+/** /unschedule <name> — alias for /schedule delete. */
+async function handleUnschedule(args, dispatch, api, ctx) {
+    if (args.length === 0) {
+        commitNotification(dispatch, 'error', 'Usage: /unschedule <name> (hint: use /schedule delete <name>)');
+        return;
+    }
+    await deleteSchedule(args[0], dispatch, api, ctx);
+}
+/** /status — show ensemble status overlay. */
+async function handleStatus(_args, dispatch) {
+    dispatch({ type: 'SHOW_STATUS' });
+}
+/** /gates — list quality gates. */
+async function handleGates(_args, dispatch, api, ctx) {
+    try {
+        let ensembleNames;
+        if (ctx.activeEnsemble) {
+            ensembleNames = [ctx.activeEnsemble];
+        }
+        else {
+            const ensembles = await api.discoverEnsembles();
+            if (ensembles.length === 0) {
+                commitNotification(dispatch, 'info', 'No ensembles running.');
+                return;
+            }
+            ensembleNames = ensembles.map(e => e.name);
+        }
+        const icons = (0, platform_1.statusIcons)((0, platform_1.supportsUnicode)());
+        const allItems = [];
+        for (const ensName of ensembleNames) {
+            const gates = await api.getGates(ensName);
+            for (const g of gates) {
+                const icon = g.status === 'passed' ? icons.check
+                    : g.status === 'failed' ? icons.cross
+                        : '\u25CB';
+                const criteriaSum = g.criteria.map(c => {
+                    const cIcon = c.status === 'passed' ? icons.check : c.status === 'failed' ? icons.cross : icons.pending;
+                    return `${cIcon} ${c.text}`;
+                }).join('  ');
+                allItems.push({
+                    id: `${ensName}:${g.task}`,
+                    label: `${icon} ${g.task}  [${g.status}]`,
+                    sublabel: criteriaSum || '(no criteria)',
+                });
+            }
+        }
+        if (allItems.length === 0) {
+            commitNotification(dispatch, 'info', 'No quality gates defined.');
+        }
+        else {
+            dispatch({
+                type: 'SHOW_OVERLAY',
+                overlay: {
+                    type: 'gates',
+                    title: 'Quality Gates',
+                    items: allItems,
+                    hint: '\u21B5=detail  esc=close',
+                },
+            });
+        }
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `Failed to fetch gates: ${err}`);
+    }
+}
+/** /stages — list stages. */
+async function handleStages(_args, dispatch, api, ctx) {
+    try {
+        let ensembleNames;
+        if (ctx.activeEnsemble) {
+            ensembleNames = [ctx.activeEnsemble];
+        }
+        else {
+            const ensembles = await api.discoverEnsembles();
+            if (ensembles.length === 0) {
+                commitNotification(dispatch, 'info', 'No ensembles running.');
+                return;
+            }
+            ensembleNames = ensembles.map(e => e.name);
+        }
+        const icons = (0, platform_1.statusIcons)((0, platform_1.supportsUnicode)());
+        const allItems = [];
+        for (const ensName of ensembleNames) {
+            const stages = await api.getStages(ensName);
+            for (const s of stages) {
+                const icon = s.status === 'complete' ? icons.check
+                    : s.status === 'failed' ? icons.cross
+                        : s.status === 'cancelled' ? icons.terminated
+                            : icons.active;
+                const playerSum = s.players.map(p => {
+                    const pIcon = p.status === 'reported' ? icons.check
+                        : p.status === 'blocked' ? icons.cross
+                            : icons.pending;
+                    return `${pIcon} ${p.playerId}`;
+                }).join('  ');
+                allItems.push({
+                    id: `${ensName}:${s.name}`,
+                    label: `${icon} ${s.name}  [${s.status}]  (${s.failurePolicy})`,
+                    sublabel: playerSum || '(no players)',
+                });
+            }
+        }
+        if (allItems.length === 0) {
+            commitNotification(dispatch, 'info', 'No stages defined.');
+        }
+        else {
+            dispatch({
+                type: 'SHOW_OVERLAY',
+                overlay: {
+                    type: 'stages',
+                    title: 'Stages',
+                    items: allItems,
+                    hint: '\u21B5=detail  esc=close',
+                },
+            });
+        }
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `Failed to fetch stages: ${err}`);
+    }
+}
+/** /worktree [list] — list active worktrees. */
+async function handleWorktree(args, dispatch, api, ctx) {
+    const subcommand = args[0] || 'list';
+    // /worktree create <player> [--branch <name>] — delegate to conductor
+    if (subcommand === 'create') {
+        if (args.length < 2) {
+            commitNotification(dispatch, 'error', 'Usage: /worktree create <player> [--branch <name>]');
+            return;
+        }
+        const ensemble = ctx.activeEnsemble;
+        if (!ensemble) {
+            commitNotification(dispatch, 'error', 'No active ensemble. Use /ensemble to select one.');
+            return;
+        }
+        const ensembles = await api.discoverEnsembles();
+        const ens = ensembles.find(e => e.name === ensemble);
+        if (!ens?.hasConductor) {
+            commitNotification(dispatch, 'error', 'No conductor in this ensemble. Worktree create requires a conductor.');
+            return;
+        }
+        const cmdParts = args.slice(0); // ['create', '<player>', ...flags]
+        await api.sendCommand(ensemble, `/worktree ${cmdParts.join(' ')}`, 'maestro');
+        commitStatic(dispatch, 'info', `\u2192 Worktree create request sent to conductor for ${args[1]}.`);
+        return;
+    }
+    // /worktree remove <player> — delegate to conductor
+    if (subcommand === 'remove') {
+        if (args.length < 2) {
+            commitNotification(dispatch, 'error', 'Usage: /worktree remove <player>');
+            return;
+        }
+        const ensemble = ctx.activeEnsemble;
+        if (!ensemble) {
+            commitNotification(dispatch, 'error', 'No active ensemble. Use /ensemble to select one.');
+            return;
+        }
+        const ensembles = await api.discoverEnsembles();
+        const ens = ensembles.find(e => e.name === ensemble);
+        if (!ens?.hasConductor) {
+            commitNotification(dispatch, 'error', 'No conductor in this ensemble. Worktree remove requires a conductor.');
+            return;
+        }
+        await api.sendCommand(ensemble, `/worktree remove ${args[1]}`, 'maestro');
+        commitStatic(dispatch, 'info', `\u2192 Worktree remove request sent to conductor for ${args[1]}.`);
+        return;
+    }
+    if (subcommand !== 'list') {
+        commitNotification(dispatch, 'error', `Unknown subcommand: ${subcommand}. Usage: /worktree [list | create <player> | remove <player>]`);
+        return;
+    }
+    try {
+        const ensembles = await api.discoverEnsembles();
+        if (ensembles.length === 0) {
+            commitNotification(dispatch, 'info', 'No ensembles running.');
+            return;
+        }
+        const allItems = [];
+        for (const ens of ensembles) {
+            const worktrees = await api.getWorktrees(ens.name);
+            for (const w of worktrees) {
+                allItems.push({
+                    id: `${ens.name}:${w.player}`,
+                    label: `${w.player} \u2192 ${w.branch}`,
+                    sublabel: `${w.path}  (${w.createdBy})`,
+                });
+            }
+        }
+        if (allItems.length === 0) {
+            commitNotification(dispatch, 'info', 'No active worktrees.');
+        }
+        else {
+            dispatch({
+                type: 'SHOW_OVERLAY',
+                overlay: {
+                    type: 'worktrees',
+                    title: 'Worktrees',
+                    items: allItems,
+                    hint: 'esc=close',
+                },
+            });
+        }
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `Failed to fetch worktrees: ${err}`);
+    }
+}
+/** /search <term> — search message history. */
+async function handleSearch(args, dispatch, api, ctx) {
+    if (args.length === 0) {
+        commitNotification(dispatch, 'error', 'Usage: /search <term>');
+        return;
+    }
+    const term = args.join(' ');
+    const termLower = term.toLowerCase();
+    try {
+        // Fetch messages from ensemble(s)
+        const ensembles = ctx.activeEnsemble
+            ? [{ name: ctx.activeEnsemble }]
+            : await api.discoverEnsembles();
+        const allResults = [];
+        const seen = new Set();
+        for (const ens of ensembles) {
+            // Fetch from both Maestro event log (100) and ensemble chat cache (500)
+            const [messages, chatResult] = await Promise.all([
+                api.getMessages(ens.name, 100),
+                api.getEnsembleChat(ens.name, 0, 500).catch(() => ({ messages: [] })),
+            ]);
+            // Merge both sources, dedup by from+to+timestamp prefix
+            const combined = [
+                ...messages.map(m => ({ from: m.from, to: m.to, text: m.text, timestamp: m.timestamp })),
+                ...chatResult.messages.map((m) => ({ from: m.from, to: m.to, text: m.text, timestamp: m.timestamp })),
+            ];
+            for (const m of combined) {
+                const dedupKey = `${m.from}:${m.to}:${m.text.slice(0, 60)}:${m.timestamp.slice(0, 19)}`;
+                if (seen.has(dedupKey))
+                    continue;
+                seen.add(dedupKey);
+                const haystack = `${m.from} ${m.to} ${m.text}`.toLowerCase();
+                if (haystack.includes(termLower)) {
+                    allResults.push({ ensemble: ens.name, ...m });
+                }
+            }
+        }
+        if (allResults.length === 0) {
+            commitNotification(dispatch, 'info', `No messages matching "${term}".`);
+            return;
+        }
+        const lines = [`\n  ${allResults.length} result${allResults.length !== 1 ? 's' : ''} for "${term}":\n`];
+        for (const r of allResults.slice(-50)) {
+            const time = formatTimestamp(r.timestamp);
+            const text = r.text.replace(/\n/g, ' ');
+            const truncated = text.length > 70 ? text.slice(0, 67) + '...' : text;
+            lines.push(`  ${time}  ${r.from} \u2192 ${r.to}: ${truncated}`);
+        }
+        if (allResults.length > 50) {
+            lines.push(`\n  ... and ${allResults.length - 50} more. Narrow your search for fewer results.`);
+        }
+        dispatch({ type: 'SHOW_COMMAND_OVERLAY', title: `Search \u00B7 "${term}"`, content: lines.join('\n') });
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `Search failed: ${err}`);
+    }
+}
+/** /recruit-conductor — one-shot recruit a conductor for the current ensemble. */
+async function handleRecruitConductor(_args, dispatch, api, ctx) {
+    const ensemble = ctx.activeEnsemble;
+    if (!ensemble) {
+        commitNotification(dispatch, 'error', 'No active ensemble. Use /ensemble to select or create one.');
+        return;
+    }
+    commitStatic(dispatch, 'info', '\u2026 Recruiting conductor (tempo-conductor)\u2026');
+    // `agent-tempo conduct` was removed in #288. Delegate to the shared helper
+    // which query-first checks for a live conductor phase, then shells out via
+    // `client.spawnConductor` (which runs `agent-tempo up <ensemble>`). This is
+    // the same two-op `/restore` uses, so the recruit-vs-restore code paths stay
+    // aligned.
+    const { ensureConductorSpawned } = await Promise.resolve().then(() => __importStar(require('../client/ensure-conductor-spawned')));
+    const outcome = await ensureConductorSpawned(ensemble, api);
+    if (outcome.spawned) {
+        commitStatic(dispatch, 'info', '\u2714 Conductor terminal launched.');
+    }
+    else if (outcome.reason === 'alreadyLive') {
+        commitStatic(dispatch, 'info', '\u2714 Conductor is already attached to this ensemble.');
+    }
+    else {
+        commitNotification(dispatch, 'error', `\u2717 Conductor spawn failed: ${outcome.error}`);
+    }
+}
+/** /lineup load|save — manage ensemble lineups. */
+async function handleLineup(args, dispatch, api, ctx) {
+    if (args.length === 0) {
+        commitNotification(dispatch, 'error', 'Usage: /lineup load <file> | /lineup save [file]');
+        return;
+    }
+    const subcommand = args[0].toLowerCase();
+    if (subcommand === 'load') {
+        if (args.length < 2) {
+            // No file arg — show available lineups
+            try {
+                const lineups = (0, saver_1.listAllLineups)();
+                if (lineups.length === 0) {
+                    commitNotification(dispatch, 'info', 'No lineups available. Create one with /lineup save.');
+                    return;
+                }
+                const items = lineups.map(l => ({
+                    id: l.name,
+                    label: l.name,
+                    sublabel: l.source === 'saved' ? 'saved' : 'shipped example',
+                }));
+                dispatch({
+                    type: 'SHOW_OVERLAY',
+                    overlay: {
+                        type: 'lineups',
+                        title: 'Available Lineups',
+                        items,
+                        hint: 'Usage: /lineup load <name>  \u00B7  esc=close',
+                    },
+                });
+            }
+            catch {
+                commitNotification(dispatch, 'error', 'Usage: /lineup load <name>');
+            }
+            return;
+        }
+        const filePath = args[1];
+        // Enter lineup confirmation mode — App.tsx handles y/n
+        dispatch({
+            type: 'CONFIRM_LINEUP',
+            action: 'load',
+            path: filePath,
+            summary: `Load lineup from: ${filePath}`,
+        });
+        return;
+    }
+    if (subcommand === 'save') {
+        const ensemble = ctx.activeEnsemble;
+        if (!ensemble) {
+            commitNotification(dispatch, 'error', 'No active ensemble. Use /ensemble <name> first.');
+            return;
+        }
+        const filePath = args[1] || `ensemble-${ensemble}.yml`;
+        try {
+            await api.sendCommand(ensemble, `/save_lineup ${filePath}`, 'maestro');
+            commitStatic(dispatch, 'info', `\u2714 Lineup save requested: ${filePath}`);
+        }
+        catch (err) {
+            commitNotification(dispatch, 'error', `\u2717 Failed to save lineup: ${err}`);
+        }
+        return;
+    }
+    commitNotification(dispatch, 'error', `Unknown lineup subcommand: ${subcommand}. Use: load, save`);
+}
+/** /ensembles — show interactive ensemble picker. */
+/** /ensemble <name> — switch active ensemble context, or navigate home if no args. */
+async function handleEnsemble(args, dispatch, api) {
+    if (args.length === 0) {
+        // #306: No args — navigate to the full home view (Online/Paused/Offline
+        // picker, badges, cwd-pinning, loading state) instead of the bare picker
+        // overlay. The home view is the canonical ensemble switcher; /ensemble
+        // exists for direct-by-name shortcut.
+        dispatch({ type: 'NAVIGATE_HOME' });
+        return;
+    }
+    const name = args[0];
+    try {
+        const ensembles = await api.discoverEnsembles();
+        const match = ensembles.find(e => e.name === name);
+        if (!match) {
+            const available = ensembles.map(e => e.name).join(', ') || 'none';
+            commitNotification(dispatch, 'error', `Ensemble "${name}" not found. Available: ${available}`);
+            return;
+        }
+        // Switch ensemble — clears old data, polling will refresh
+        dispatch({ type: 'NAVIGATE_ENSEMBLE', ensemble: name });
+        commitStatic(dispatch, 'info', `\u2714 Switched to ensemble: ${name} (${match.playerCount} player${match.playerCount !== 1 ? 's' : ''})`);
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `Failed to switch ensemble: ${err}`);
+    }
+}
+/**
+ * /go — release all held players in the current ensemble.
+ *
+ * #306: Direct TempoClient path — the legacy `sendCommand('/release',
+ * 'maestro')` routed through the maestro hub → conductor's Claude Code
+ * session → `release` MCP tool, which required a live conductor + added
+ * 2-5s of LLM-interpretation latency. `api.release(ensemble)` submits
+ * release outbox entries from the TUI's own maestro session; no conductor
+ * needed, no LLM hop, clean partial-success diagnostics.
+ */
+async function handleGo(_args, dispatch, api, ctx) {
+    const ensemble = ctx.activeEnsemble;
+    if (!ensemble) {
+        commitNotification(dispatch, 'error', 'No active ensemble. Use /ensemble to select one.');
+        return;
+    }
+    try {
+        const summary = await api.release(ensemble);
+        if (summary.released.length === 0 && summary.errors.length === 0) {
+            // #306 follow-up: even with nothing to release, defensively clear
+            // the held indicator. The poll will reconcile in 2s; this just
+            // prevents a stale indicator from flashing yellow until then.
+            dispatch({ type: 'SET_ENSEMBLE_HELD', held: false });
+            commitNotification(dispatch, 'info', 'No held players to release.');
+            return;
+        }
+        if (summary.released.length > 0) {
+            commitStatic(dispatch, 'info', `\u2714 Released ${summary.released.length} player${summary.released.length !== 1 ? 's' : ''}: ${summary.released.join(', ')}`);
+        }
+        // #306 follow-up: optimistically clear the held indicator so the
+        // StatusBar `held` segment + the pinned `Tip: /go` line disappear
+        // immediately. Mirrors the pause/play optimistic toggle.
+        dispatch({ type: 'SET_ENSEMBLE_HELD', held: false });
+        for (const e of summary.errors) {
+            commitNotification(dispatch, 'error', `\u2717 Release failed for ${e.playerId}: ${e.error}`);
+        }
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `\u2717 Release failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Resolve the ensemble target from args/context, emitting a friendly error
+ * when neither is available. Shared by every ensemble-scoped verb below.
+ */
+function resolveEnsembleArg(args, ctx, dispatch, verb) {
+    const target = args[0] ?? ctx.activeEnsemble;
+    if (!target) {
+        commitNotification(dispatch, 'error', `No active ensemble. Use /ensemble to select one, or /${verb} <ensemble>.`);
+        return null;
+    }
+    return target;
+}
+/** /pause [ensemble] — pause every session + scheduler + maestro. */
+async function handlePause(args, dispatch, api, ctx) {
+    const ensemble = resolveEnsembleArg(args, ctx, dispatch, 'pause');
+    if (!ensemble)
+        return;
+    try {
+        await api.pause(ensemble);
+        // Bug B: optimistically flip the StatusBar indicator so users don't
+        // wait for the next 2s poll tick to see "paused". The poll loop will
+        // sync the truth back if the call somehow lied.
+        dispatch({ type: 'SET_ENSEMBLE_PAUSED', paused: true });
+        commitStatic(dispatch, 'info', `\u23F8 Paused ensemble "${ensemble}".`);
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `\u2717 Pause failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** /play [ensemble] — resume a paused ensemble (renamed from /resume). */
+async function handlePlay(args, dispatch, api, ctx) {
+    const ensemble = resolveEnsembleArg(args, ctx, dispatch, 'play');
+    if (!ensemble)
+        return;
+    try {
+        await api.play(ensemble);
+        // Bug B: optimistically clear the StatusBar `paused` segment so users
+        // get instant feedback that the resume took effect.
+        dispatch({ type: 'SET_ENSEMBLE_PAUSED', paused: false });
+        // #306 follow-up: defensive clear of the held flag. `/play` does NOT
+        // release held players (held + paused are orthogonal — `/load_lineup`
+        // flips both, `/play` clears only paused), but if the held indicator
+        // was stale this prevents it from lingering until the next poll. The
+        // 2s poll will resync if any player is still actually held.
+        dispatch({ type: 'SET_ENSEMBLE_HELD', held: false });
+        commitStatic(dispatch, 'info', `▶ Resumed ensemble "${ensemble}".`);
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `✗ Play failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** /shutdown [ensemble] — graceful teardown (detach adapters + pause maestro/scheduler). */
+async function handleShutdown(args, dispatch, api, ctx) {
+    const ensemble = resolveEnsembleArg(args, ctx, dispatch, 'shutdown');
+    if (!ensemble)
+        return;
+    commitStatic(dispatch, 'info', `\u2026 Shutting down "${ensemble}" \u2026`);
+    try {
+        const summary = await api.shutdown(ensemble);
+        // #306: per-player detail lines stay in scrollback as a record; the
+        // aggregate summary below is pinned so it can't scroll above the fold
+        // on a busy chat. After success we also land the user on home, since
+        // a parked ensemble has no live players to talk to.
+        for (const d of summary.details) {
+            const line = `  ${d.playerId} \u2014 ${d.outcome}${d.error ? `: ${d.error}` : ''}`;
+            commitStatic(dispatch, d.outcome === 'failed' ? 'error' : 'info', line);
+        }
+        commitNotification(dispatch, summary.failed === 0 ? 'info' : 'error', `\u2714 Shutdown "${ensemble}" \u2014 ${summary.detached} detached, ${summary.skipped} skipped, ${summary.failed} failed` +
+            `${summary.maestroPaused ? ', maestro paused' : ''}${summary.schedulerPaused ? ', scheduler paused' : ''}.`);
+        dispatch({ type: 'NAVIGATE_HOME' });
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `\u2717 Shutdown failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** /restore [ensemble] — bring a parked ensemble back (reattach orphans + spawn conductor if absent). */
+async function handleRestore(args, dispatch, api, ctx) {
+    const ensemble = resolveEnsembleArg(args, ctx, dispatch, 'restore');
+    if (!ensemble)
+        return;
+    commitStatic(dispatch, 'info', `\u2026 Restoring "${ensemble}" \u2026`);
+    try {
+        const summary = await api.restore(ensemble);
+        // Bug B: optimistically clear the `paused` indicator. /restore both
+        // unpauses maestro+scheduler AND fans setPaused=false to every session,
+        // so by the time the call resolves the ensemble is no longer paused.
+        dispatch({ type: 'SET_ENSEMBLE_PAUSED', paused: false });
+        const { formatRestoreOutcome } = await Promise.resolve().then(() => __importStar(require('../reconcile/orphans')));
+        // #306: per-player detail lines stay in scrollback as a record; the
+        // aggregate summary below is pinned so it can't scroll above the fold.
+        for (const d of summary.details) {
+            const text = `  ${d.playerId} \u2014 ${formatRestoreOutcome(d.outcome)}`;
+            commitStatic(dispatch, d.outcome.kind === 'failed' ? 'error' : 'info', text);
+        }
+        commitNotification(dispatch, summary.failed === 0 ? 'info' : 'error', `\u2714 Restore "${ensemble}" \u2014 ${summary.reattached} reattached, ${summary.skipped} skipped, ${summary.failed} failed.`);
+        // Step 2: ensure a conductor terminal is present (spawn if absent).
+        const { ensureConductorSpawned } = await Promise.resolve().then(() => __importStar(require('../client/ensure-conductor-spawned')));
+        const conductorOutcome = await ensureConductorSpawned(ensemble, api);
+        if (conductorOutcome.spawned) {
+            commitStatic(dispatch, 'info', '  Conductor terminal launched.');
+        }
+        else if (conductorOutcome.reason === 'spawnFailed') {
+            commitNotification(dispatch, 'error', `  Conductor spawn failed: ${conductorOutcome.error}`);
+        }
+        // `alreadyLive` is silent — no action needed.
+    }
+    catch (err) {
+        commitNotification(dispatch, 'error', `\u2717 Restore failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** /home — navigate back to the home view without touching workflow state. */
+async function handleHome(_args, dispatch) {
+    dispatch({ type: 'NAVIGATE_HOME' });
+}
+// ── Utility ──
+function formatTimestamp(ts) {
+    try {
+        const d = new Date(ts);
+        return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
+    }
+    catch {
+        return '??:??';
+    }
+}
+/** Format milliseconds as a human-readable duration (e.g. "30s", "5m", "1.5h"). */
+function formatMs(ms) {
+    if (ms < 60000)
+        return `${Math.round(ms / 1000)}s`;
+    if (ms < 3600000)
+        return `${Math.round(ms / 60000)}m`;
+    return `${(ms / 3600000).toFixed(1)}h`;
+}
+// ── Registry ──
+/** All supported slash commands. */
+exports.COMMANDS = {
+    recruit: {
+        description: 'Spawn a new player session',
+        usage: '/recruit <name> [--type <type>] [--dir <path>]',
+        handler: handleRecruit,
+    },
+    broadcast: {
+        description: 'Send a message to all active players',
+        usage: '/broadcast <message>',
+        handler: handleBroadcast,
+    },
+    restart: {
+        description: 'Restart a session (reap + claim + context replay + spawn). Steals a live lease by default — pass --no-force to refuse if held. --load-from-state seeds from a saved-state slot (#334).',
+        usage: '/restart <player> [--fresh] [--no-force] [--load-from-state[=key]] [--stack-transcript]',
+        handler: handleRestart,
+    },
+    destroy: {
+        description: 'Terminally destroy a player (y/N) or an ensemble (typed-name)',
+        usage: '/destroy <player|ensemble> [reason]',
+        handler: handleDestroy,
+    },
+    migrate: {
+        description: "Restart a session on a different host. --force on a cross-host target requires --yes-steal=<currentHost> (§16.5 Option B).",
+        usage: '/migrate <player> <host> [--fresh] [--force] [--yes-steal=<hostname>]',
+        handler: handleMigrate,
+    },
+    'attachment-info': {
+        description: 'Inspect the V2 attachment state of a session',
+        usage: '/attachment-info <player>',
+        handler: handleAttachmentInfo,
+    },
+    hosts: {
+        description: 'List daemons polling this Temporal namespace with advertised capabilities (#274)',
+        usage: '/hosts [--all]',
+        handler: handleHosts,
+    },
+    recall: {
+        description: "Read a player's message history (received + sent by default; --received-only to opt out)",
+        usage: '/recall [player] [--limit N] [--offset N] [--preview N] [--from X] [--since ISO] [--received-only]',
+        handler: handleRecall,
+    },
+    schedule: {
+        description: 'Manage schedules — list, create, or delete',
+        usage: '/schedule [create | delete <name>]',
+        handler: handleSchedule,
+    },
+    players: {
+        description: 'List active players or show player detail',
+        usage: '/players [name]',
+        handler: handlePlayer,
+    },
+    gates: {
+        description: 'List quality gates and their status',
+        usage: '/gates',
+        handler: handleGates,
+    },
+    stages: {
+        description: 'List stages and their status',
+        usage: '/stages',
+        handler: handleStages,
+    },
+    worktree: {
+        description: 'Manage git worktrees for player isolation',
+        usage: '/worktree [list | create <player> | remove <player>]',
+        handler: handleWorktree,
+    },
+    lineup: {
+        description: 'Load or save an ensemble lineup',
+        usage: '/lineup load <file> | save [file]',
+        handler: handleLineup,
+    },
+    ensemble: {
+        description: 'Switch active ensemble by name (or open home view with no arg)',
+        usage: '/ensemble [name]',
+        handler: handleEnsemble,
+    },
+    search: {
+        description: 'Search message history',
+        usage: '/search <term>',
+        handler: handleSearch,
+    },
+    help: {
+        description: 'Show available commands',
+        usage: '/help [command]',
+        handler: null, // Handled directly in App.tsx
+    },
+    'recruit-conductor': {
+        description: 'Recruit a conductor for the current ensemble',
+        usage: '/recruit-conductor',
+        handler: handleRecruitConductor,
+    },
+    status: {
+        description: 'Show ensemble players and status',
+        usage: '/status',
+        handler: handleStatus,
+    },
+    go: {
+        description: 'Release all held players (unlock outbox)',
+        usage: '/go',
+        handler: handleGo,
+    },
+    pause: {
+        description: 'Pause every session + scheduler + maestro in the ensemble',
+        usage: '/pause [ensemble]',
+        handler: handlePause,
+    },
+    play: {
+        description: 'Resume a paused ensemble (renamed from /resume — avoids collision with `claude --resume`)',
+        usage: '/play [ensemble]',
+        handler: handlePlay,
+    },
+    shutdown: {
+        description: 'Graceful ensemble teardown — detach adapters, pause maestro + scheduler',
+        usage: '/shutdown [ensemble]',
+        handler: handleShutdown,
+    },
+    restore: {
+        description: 'Restore a parked ensemble — reattach orphans, unpause maestro + scheduler',
+        usage: '/restore [ensemble]',
+        handler: handleRestore,
+    },
+    home: {
+        description: 'Return to the home view (does not touch workflows)',
+        usage: '/home',
+        handler: handleHome,
+    },
+    back: {
+        description: 'Return to maestro view',
+        usage: '/back',
+        handler: null, // Handled directly in App.tsx
+    },
+    quit: {
+        description: 'Exit the TUI',
+        usage: '/quit (or /exit)',
+        handler: null, // Handled directly in App.tsx
+    },
+    // #306: /exit is an alias for /quit. Claude Code uses /exit, so users
+    // arriving from there expect it to work. Both go to the same App.tsx
+    // handler that calls Ink's exit().
+    exit: {
+        description: 'Exit the TUI (alias for /quit)',
+        usage: '/exit',
+        handler: null, // Handled directly in App.tsx
+    },
+};
+/** Get sorted list of command names for display. */
+function getCommandNames() {
+    return Object.keys(exports.COMMANDS).sort();
+}
+/** Check if a command name is registered. */
+function isValidCommand(name) {
+    return name in exports.COMMANDS;
+}
+/** Format a help summary of all commands. */
+function formatHelpSummary() {
+    const lines = getCommandNames().map(name => {
+        const cmd = exports.COMMANDS[name];
+        return `  ${cmd.usage.padEnd(48)} ${cmd.description}`;
+    });
+    return ['Available commands:', '', ...lines, '', 'Type /help <command> for details.'].join('\n');
+}
+// `filterPaletteCommands`, `PLAYER_PARAM_COMMANDS`, `SUBCOMMAND_MAP`,
+// `PaletteMode`, `PaletteContext`, `classifyPaletteInput`, and
+// `filterPlayerNames` moved to `src/palette/index.ts` in #471/#472. The
+// re-exports at the top of this file preserve the pre-extraction surface
+// so PromptArea / App.tsx / tests/tui/* keep working unchanged.