agent-tempo 1.0.1

package/dist/tools/cue.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatDetachedDeliveryError = formatDetachedDeliveryError;
+exports.registerCueTool = registerCueTool;
+exports.formatUnknownPlayerError = formatUnknownPlayerError;
+exports.findClosestPlayers = findClosestPlayers;
+exports.levenshtein = levenshtein;
+const zod_1 = require("zod");
+const resolve_1 = require("./resolve");
+const resolve_2 = require("../activities/resolve");
+const signals_1 = require("../workflows/signals");
+const query_timeout_1 = require("../utils/query-timeout");
+const helpers_1 = require("./helpers");
+const validation_1 = require("../utils/validation");
+/**
+ * Max Levenshtein distance for a fuzzy-match candidate to surface in the
+ * unknown-player suggestion. Three insertions/deletions/substitutions covers
+ * common typos (transposed chars, dropped chars, off-by-one) without
+ * surfacing wildly unrelated names. #560 acceptance criterion 3.
+ */
+const FUZZY_MATCH_MAX_DISTANCE = 3;
+/** Cap on suggestions shown in the error to keep the message readable. */
+const FUZZY_MATCH_MAX_SUGGESTIONS = 3;
+/**
+ * Phases where the target session has no live adapter — the workflow inbox
+ * still queues the signal and auto-redelivers on re-attach, but the
+ * operator's "Message sent to X" success line is misleading because no
+ * human-readable surface processes the message *now*. #562 surfaces the
+ * gap.
+ *
+ * `draining` is NOT included — it's a brief mid-shutdown state and the
+ * adapter is still consuming pending messages; flagging it as undeliverable
+ * would false-positive during normal teardown.
+ */
+const UNDELIVERABLE_PHASES = new Set(['detached', 'gone']);
+/**
+ * Cue pre-flight timeout. Half of {@link DEFAULT_QUERY_TIMEOUT_MS} —
+ * `cue` is operator-interactive, so a slow target shouldn't make the
+ * user wait the full 2s default before falling through to the best-
+ * effort path. 1s strikes the balance between catching the common
+ * detached-player case and not wedging the operator.
+ */
+const CUE_PHASE_PREFLIGHT_TIMEOUT_MS = 1000;
+/**
+ * Build the operator-facing error message when the cue target is in an
+ * undeliverable phase. Lists three actionable next steps per the issue
+ * body's AC #3.
+ *
+ * Exported for unit testing.
+ */
+function formatDetachedDeliveryError(playerId, phase) {
+    return (`Player "${playerId}" is currently '${phase}' — no live adapter to receive. ` +
+        `Message NOT delivered. Options: ` +
+        `(1) use 'recall' to view their message history, ` +
+        `(2) 'restart' to re-attach the session and retry the cue, ` +
+        `(3) the workflow inbox queues the signal and auto-delivers on re-attach.`);
+}
+function registerCueTool(server, client, config, getPlayerId, handle) {
+    (0, helpers_1.defineTool)(server, 'cue', 'Send a message to another Claude Code session by player name. Delivered instantly via Temporal signal. For content larger than ~100 KB, use `coat_check_put` to stash the body and pass the returned ticket via `attachmentTicket` — the cue body itself should carry a short summary the recipient can act on without fetching.', {
+        playerId: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).describe('The player name of the target session'),
+        message: zod_1.z.string().max(validation_1.MESSAGE_MAX).describe('The message to send'),
+        attachmentTicket: zod_1.z.string().regex(validation_1.COAT_CHECK_TICKET_REGEX).max(validation_1.COAT_CHECK_TICKET_MAX).optional().describe('Optional coat-check ticket (#318). Reference content stashed via `coat_check_put`; the receiver sees the ticket on their `recall` message and can pull the body via `coat_check_get`. Backward-compatible — omit for normal cues.'),
+    }, async (args) => {
+        const { playerId, message, attachmentTicket } = args;
+        const nameError = (0, validation_1.validatePlayerName)(playerId);
+        if (nameError)
+            return (0, helpers_1.fail)(nameError);
+        try {
+            const resolved = await (0, resolve_1.resolveSession)(client, config.ensemble, playerId);
+            if (!resolved) {
+                // #560: replace the generic "no active session found" with an
+                // actionable error — active-player list + fuzzy-match suggestion
+                // + Agent-tool surface hint. We pay the extra `scanEnsembleSessions`
+                // round-trip ONLY on the error path, so the success path is
+                // unchanged.
+                const sessions = await (0, resolve_2.scanEnsembleSessions)(client, config.ensemble);
+                const activePlayers = sessions.map((s) => s.playerId).sort();
+                return (0, helpers_1.fail)(formatUnknownPlayerError(playerId, activePlayers));
+            }
+            // #562: phase pre-flight. Resolves the gap where `cue` to a
+            // detached/gone player returns "Message sent" — wire-truthful (the
+            // signal IS delivered to the workflow inbox), but operator-
+            // misleading because no live adapter surfaces the message.
+            let phase;
+            try {
+                const info = await (0, query_timeout_1.queryHandleWithTimeout)(resolved, signals_1.attachmentInfoQuery, { timeoutMs: CUE_PHASE_PREFLIGHT_TIMEOUT_MS });
+                phase = info.phase;
+            }
+            catch (err) {
+                // Query timed out or threw — workflow may be wedged. Don't
+                // penalize the operator: fall through to best-effort submit.
+                // Auto-redelivery on re-attach still applies. Stderr log keeps
+                // the observability trail without surfacing noise to the user.
+                console.error(`[agent-tempo:cue] phase pre-flight failed for "${playerId}" — proceeding best-effort:`, err instanceof Error ? err.message : err);
+            }
+            if (phase && UNDELIVERABLE_PHASES.has(phase)) {
+                return (0, helpers_1.fail)(formatDetachedDeliveryError(playerId, phase));
+            }
+            const entry = {
+                type: 'cue',
+                targetPlayerId: playerId,
+                message,
+                ...(attachmentTicket !== undefined ? { attachmentTicket } : {}),
+            };
+            const entryId = await handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
+            return (0, helpers_1.ok)(`Message sent to ${playerId}. (outbox: ${entryId})`);
+        }
+        catch (err) {
+            return (0, helpers_1.fail)(`Failed to send message to ${playerId}: ${(0, helpers_1.formatError)(err)}`);
+        }
+    });
+}
+/**
+ * Format the cue tool's "unknown player" error with actionable suggestions.
+ * Exported for direct unit testing — the production path passes the active
+ * player list from `scanEnsembleSessions`.
+ *
+ * The message disambiguates the two common causes per the issue body (#560):
+ *   1. Typo / destroyed player → fuzzy-match suggestion (Levenshtein ≤ 3),
+ *      active-player listing, hint about `recall` for destroyed targets.
+ *   2. Agent-tool sub-agent confusion → explicit note that Claude Code
+ *      `subagent_type:` agents run in the spawner's process and are NOT
+ *      addressable via `cue`; `recruit` is the cross-process surface.
+ *
+ * Returns a multi-line string. Caller wraps in {@link fail}.
+ */
+function formatUnknownPlayerError(target, activePlayers) {
+    const lines = [
+        `Player "${target}" is not registered with this tempo ensemble.`,
+    ];
+    const closest = findClosestPlayers(target, activePlayers);
+    if (closest.length > 0) {
+        lines.push('');
+        lines.push(`Did you mean: ${closest.map((p) => `"${p}"`).join(', ')}?`);
+    }
+    lines.push('');
+    if (activePlayers.length > 0) {
+        lines.push(`Active players: ${activePlayers.join(', ')}`);
+    }
+    else {
+        lines.push('No active players in this ensemble. Use `recruit` to start one.');
+    }
+    lines.push('');
+    lines.push("Note: Claude Code Agent-tool sub-agents (e.g. spawned via " +
+        "`subagent_type: tempo-*`) are NOT tempo players — they run in the " +
+        "spawner's process and aren't addressable via `cue`. Use `recruit` " +
+        "for a cross-process player, or `ensemble` to list current players.");
+    return lines.join('\n');
+}
+/**
+ * Find the closest matching player names by Levenshtein distance.
+ * Returns the top-N nearest within {@link FUZZY_MATCH_MAX_DISTANCE},
+ * sorted by ascending distance then alphabetically. Empty array if no
+ * candidate is close enough.
+ *
+ * Exported for unit testing.
+ */
+function findClosestPlayers(target, candidates) {
+    if (!target || candidates.length === 0)
+        return [];
+    const scored = candidates
+        .map((c) => ({ name: c, distance: levenshtein(target, c) }))
+        .filter((entry) => entry.distance <= FUZZY_MATCH_MAX_DISTANCE)
+        .sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name));
+    return scored.slice(0, FUZZY_MATCH_MAX_SUGGESTIONS).map((e) => e.name);
+}
+/**
+ * Plain Levenshtein edit distance — single-row DP, O(|a| · |b|) time,
+ * O(min) space. No library dependency.
+ *
+ * Exported for unit testing.
+ */
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    // Ensure b is the shorter string to keep the row small.
+    if (a.length < b.length) {
+        const tmp = a;
+        a = b;
+        b = tmp;
+    }
+    let prev = new Array(b.length + 1);
+    let curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, // insertion
+            prev[j] + 1, // deletion
+            prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[b.length];
+}

package/dist/tools/destroy.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client, WorkflowHandle } from '@temporalio/client';
+import { Config } from '../config';
+export declare function registerDestroyTool(server: McpServer, client: Client, config: Config, getPlayerId: () => string, handle: WorkflowHandle): void;

package/dist/tools/destroy.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDestroyTool = registerDestroyTool;
+/**
+ * `destroy` — terminal end of either a single session or the whole ensemble.
+ *
+ * **Single-player mode (`playerId` present)**: enqueues a `DestroyOutboxEntry`
+ * on the caller's workflow outbox. The session workflow's dispatch loop runs
+ * the `deliverDestroy` activity on the target, which calls `destroyUpdate` +
+ * (optionally) posts a system message on the ensemble conductor via
+ * `receiveMessageSignal`.
+ *
+ * **Ensemble mode (`playerId` omitted, #287)**: walks every peer session via
+ * `destroyUpdate` directly (in parallel), then terminates the scheduler +
+ * maestro, then destroys the conductor last. Direct `destroyUpdate` calls
+ * (not outbox entries) because ensemble teardown is a batch operation with
+ * a fixed ordering invariant (conductor sees peer teardown), not
+ * cross-workflow traffic that needs the caller's dispatch loop. The caller's
+ * own session is skipped — tools can't destroy themselves safely.
+ *
+ * For graceful shutdown without destroying workflows, use `shutdown` instead.
+ */
+const zod_1 = require("zod");
+const config_1 = require("../config");
+const signals_1 = require("../workflows/signals");
+const resolve_1 = require("../activities/resolve");
+const helpers_1 = require("./helpers");
+const validation_1 = require("../utils/validation");
+const log = (...args) => console.error('[agent-tempo:destroy]', ...args);
+function registerDestroyTool(server, client, config, getPlayerId, handle) {
+    (0, helpers_1.defineTool)(server, 'destroy', 'Terminally destroy a session workflow (when `playerId` is given) or the entire ensemble (when omitted): every peer session, the scheduler, the maestro, and the conductor. COMPLETEs workflows and cannot be undone. For graceful reap use `shutdown`; for a clean revive use `restart`.', {
+        // #306: `.min(1)` rejects `{playerId: ""}` at the SDK boundary so a
+        // buggy MCP caller can't silently fall through to ensemble-wide
+        // destroy mode. The handler also guards programmatic callers that
+        // bypass Zod (see explicit `playerId === ''` rejection below).
+        playerId: zod_1.z.string().min(1).max(validation_1.PLAYER_NAME_MAX).optional().describe('Target player name. Omit to destroy the entire ensemble.'),
+        reason: zod_1.z.string().max(500).optional().describe('Optional reason recorded in the workflow\'s audit event'),
+    }, async (args) => {
+        const { playerId, reason } = args;
+        const callerId = getPlayerId();
+        // #306: defense-in-depth for callers that bypass Zod (test harnesses,
+        // direct handler invocation). Zod's `.min(1)` already covers normal
+        // MCP traffic; this guard ensures empty-string never falls through to
+        // ensemble-wide destroy mode regardless of how the handler is reached.
+        if (playerId === '') {
+            return (0, helpers_1.fail)('`playerId` cannot be an empty string. Omit it to destroy the entire ensemble.');
+        }
+        // ── Single-player mode (existing behaviour) ─────────────────────────
+        if (playerId !== undefined) {
+            const nameError = (0, validation_1.validatePlayerName)(playerId);
+            if (nameError)
+                return (0, helpers_1.fail)(nameError);
+            if (playerId === callerId) {
+                return (0, helpers_1.fail)('Cannot destroy your own session.');
+            }
+            try {
+                const entry = {
+                    type: 'destroy',
+                    targetPlayerId: playerId,
+                    ...(reason !== undefined ? { reason } : {}),
+                    notifyConductor: true,
+                };
+                const entryId = await handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
+                return (0, helpers_1.ok)(`Destroy queued for **${playerId}**${reason ? ` (reason: ${reason})` : ''}. (outbox: ${entryId})`);
+            }
+            catch (err) {
+                return (0, helpers_1.fail)(`Failed to destroy: ${(0, helpers_1.formatError)(err)}`);
+            }
+        }
+        // ── Ensemble-scope mode (#287) ──────────────────────────────────────
+        // Order: peer sessions (parallel) → scheduler + maestro (parallel) →
+        // conductor last. The conductor-last step is the invariant the
+        // architect's spec relies on so the conductor sees every peer
+        // teardown before its own destroy.
+        try {
+            const destroyReason = reason ?? `ensemble destroy via ${callerId}`;
+            const sessions = await (0, resolve_1.scanEnsembleSessions)(client, config.ensemble);
+            const conductorWfId = (0, config_1.conductorWorkflowId)(config.ensemble);
+            const peers = [];
+            let conductorPresent = false;
+            for (const s of sessions) {
+                if (s.workflowId === conductorWfId) {
+                    conductorPresent = true;
+                }
+                else {
+                    peers.push(s);
+                }
+            }
+            const details = [];
+            let destroyed = 0;
+            let terminated = 0;
+            let failed = 0;
+            // Phase 1: destroy every peer in parallel (conductor excluded). Skip
+            // the caller's own session — self-destroy is a no-op guard.
+            const peerResults = await Promise.allSettled(peers.map(async (s) => {
+                if (s.playerId === callerId)
+                    return { session: s, outcome: 'skipped-self' };
+                try {
+                    await client.workflow.getHandle(s.workflowId).executeUpdate(signals_1.destroyUpdate, {
+                        args: [{ reason: destroyReason, terminatedBy: callerId }],
+                    });
+                    return { session: s, outcome: 'destroyed' };
+                }
+                catch (err) {
+                    return { session: s, outcome: 'failed', error: (0, helpers_1.formatError)(err) };
+                }
+            }));
+            for (const r of peerResults) {
+                if (r.status !== 'fulfilled')
+                    continue;
+                const v = r.value;
+                if (v.outcome === 'destroyed') {
+                    details.push({ target: v.session.playerId, outcome: 'destroyed' });
+                    destroyed++;
+                }
+                else if (v.outcome === 'failed') {
+                    details.push({ target: v.session.playerId, outcome: 'failed', error: v.error });
+                    failed++;
+                }
+                // #299: `'skipped-self'` is an internal control-flow tag for the
+                // caller's own session — intentionally NOT surfaced in `details`
+                // because `EnsembleDestroyDetail` is consumed publicly via
+                // `EnsembleDestroySummary` (TempoClient.destroy), which has no
+                // caller-self concept. The skip is a bookkeeping no-op here.
+            }
+            // Phase 2: scheduler + maestro terminate in parallel (non-session
+            // workflows — no destroy handler). `terminate` rejects when the
+            // workflow isn't running; treat as "not present" instead of failure.
+            const [schedRes, maestroRes] = await Promise.allSettled([
+                client.workflow.getHandle((0, config_1.schedulerWorkflowId)(config.ensemble)).terminate(destroyReason),
+                client.workflow.getHandle((0, config_1.maestroWorkflowId)(config.ensemble)).terminate(destroyReason),
+            ]);
+            if (schedRes.status === 'fulfilled') {
+                details.push({ target: 'scheduler', outcome: 'terminated' });
+                terminated++;
+            }
+            if (maestroRes.status === 'fulfilled') {
+                details.push({ target: 'maestro', outcome: 'terminated' });
+                terminated++;
+            }
+            // Phase 3: conductor last, so it observes peer teardown. Skipped if
+            // the caller IS the conductor (same self-destroy guard). #299: the
+            // skip is a control-flow no-op — no `details` entry, mirroring the
+            // peer-self skip. `EnsembleDestroyDetail.outcome` no longer carries
+            // a self-skip member.
+            if (callerId === 'conductor') {
+                // self-skip; no recording
+            }
+            else if (conductorPresent) {
+                try {
+                    await client.workflow.getHandle(conductorWfId).executeUpdate(signals_1.destroyUpdate, {
+                        args: [{ reason: destroyReason, terminatedBy: callerId }],
+                    });
+                    details.push({ target: 'conductor', outcome: 'destroyed' });
+                    destroyed++;
+                }
+                catch (err) {
+                    details.push({ target: 'conductor', outcome: 'failed', error: (0, helpers_1.formatError)(err) });
+                    failed++;
+                }
+            }
+            const summaryLine = `${destroyed} destroyed, ${terminated} terminated, ${failed} failed`;
+            const headline = failed > 0
+                ? `Ensemble **${config.ensemble}** partially destroyed.`
+                : `Ensemble **${config.ensemble}** destroyed.`;
+            const lines = [headline, summaryLine];
+            const failures = details.filter((d) => d.outcome === 'failed');
+            if (failures.length > 0) {
+                lines.push(`Errors:\n${failures.map((d) => `  - ${d.target}: ${d.error}`).join('\n')}`);
+                // #306 follow-up: surface the indeterminate-state hint from my own
+                // PR-#306 holistic review (regression risk #3). `Promise.allSettled`
+                // returned `failed` outcomes for these peers — the workflows may
+                // be in any state from "still running" to "destroyed but RPC
+                // timed out". Re-running `destroy` is safe (idempotent on the
+                // workflow side: `destroyUpdate` on a `gone` workflow is a no-op
+                // via the `isDestroyedQuery` guard) and the cleanest recovery.
+                const noun = failed === 1 ? 'peer' : 'peers';
+                lines.push(`⚠ ${failed} ${noun} in indeterminate state — ` +
+                    `run \`/destroy ${config.ensemble}\` again to clean up.`);
+            }
+            log(`Ensemble destroy by ${callerId}: ${summaryLine}`);
+            return (0, helpers_1.ok)(lines.join('\n'));
+        }
+        catch (err) {
+            return (0, helpers_1.fail)(`Failed to destroy ensemble: ${(0, helpers_1.formatError)(err)}`);
+        }
+    });
+}

package/dist/tools/detach.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client, WorkflowHandle } from '@temporalio/client';
+import { Config } from '../config';
+export declare function registerDetachTool(server: McpServer, _client: Client, _config: Config, getPlayerId: () => string, handle: WorkflowHandle): void;

package/dist/tools/detach.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDetachTool = registerDetachTool;
+/**
+ * `detach` — graceful reap of a session's adapter without destroying the workflow.
+ *
+ * QA B1: enqueues a `DetachOutboxEntry` on the caller's workflow outbox rather
+ * than firing `requestDetachSignal` directly from tool code. The session
+ * workflow's dispatch loop runs the `deliverDetach` activity on the target,
+ * which signals `requestDetachSignal` with the supplied `reason` + `deadlineMs`.
+ *
+ * Design reference: §8.1 (three verbs), §2.4 (phase transitions).
+ */
+const zod_1 = require("zod");
+const signals_1 = require("../workflows/signals");
+const helpers_1 = require("./helpers");
+const validation_1 = require("../utils/validation");
+const DEFAULT_DETACH_DEADLINE_MS = 5_000;
+function registerDetachTool(server, _client, _config, getPlayerId, handle) {
+    (0, helpers_1.defineTool)(server, 'detach', 'Gracefully detach a session\'s adapter. The session enters `draining` phase and reaps to `detached` after the deadline or when the adapter exits. The workflow survives — use `restart` to attach a new adapter, or `destroy` to terminate permanently.', {
+        playerId: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).describe('The player name to detach'),
+        deadlineMs: zod_1.z.number().min(0).max(validation_1.MAX_DETACH_DEADLINE_MS).optional().describe(`Max drain time in ms before force-detach (default ${DEFAULT_DETACH_DEADLINE_MS}, max ${validation_1.MAX_DETACH_DEADLINE_MS})`),
+    }, async (args) => {
+        const { playerId, deadlineMs = DEFAULT_DETACH_DEADLINE_MS } = args;
+        const nameError = (0, validation_1.validatePlayerName)(playerId);
+        if (nameError)
+            return (0, helpers_1.fail)(nameError);
+        if (playerId === getPlayerId()) {
+            return (0, helpers_1.fail)('Cannot detach your own session.');
+        }
+        try {
+            const entry = {
+                type: 'detach',
+                targetPlayerId: playerId,
+                reason: 'user-stop',
+                deadlineMs,
+            };
+            const entryId = await handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
+            return (0, helpers_1.ok)(`Detach queued for **${playerId}** (deadline: ${deadlineMs}ms; outbox: ${entryId}).`);
+        }
+        catch (err) {
+            return (0, helpers_1.fail)(`Failed to detach: ${(0, helpers_1.formatError)(err)}`);
+        }
+    });
+}

package/dist/tools/encore.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Client, WorkflowHandle } from '@temporalio/client';
+import type { Config } from '../config';
+export declare function registerEncoreTool(_server: McpServer, _client: Client, _config: Config, _getPlayerId: () => string, _handle: WorkflowHandle): void;

package/dist/tools/encore.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerEncoreTool = registerEncoreTool;
+/**
+ * `encore` — deprecation shim (PR-D).
+ *
+ * The `encore` verb is retired in v0.25 per design §8.1 "three verbs" —
+ * replaced by `restart`, which runs the same §8.2 algorithm (forceDetach +
+ * claimAttachment + context replay + enqueueSpawn) but is not limited to
+ * `stale`-only targets.
+ *
+ * The MCP tool remains registered so existing clients discover it via
+ * ListTools but returns an `isError` pointing to the replacement. The
+ * internal `case 'encore':` outbox dispatch and `performEncore` activity
+ * are still live; `restart` doesn't use them, but they stay so scheduler /
+ * test fixtures that enqueue encore entries keep working until v0.25.1.
+ */
+const zod_1 = require("zod");
+const helpers_1 = require("./helpers");
+function registerEncoreTool(_server, _client, _config, _getPlayerId, _handle) {
+    (0, helpers_1.defineTool)(_server, 'encore', '[deprecated in v0.25] The `encore` verb is retired — use `restart` instead, which runs the same forceDetach + claim + context-replay + enqueueSpawn algorithm but is not limited to stale targets.', {
+        playerId: zod_1.z.string().describe('The player name to revive'),
+        host: zod_1.z.string().optional().describe('Target hostname (legacy)'),
+        contextMessages: zod_1.z.number().optional().describe('Number of recent messages (legacy)'),
+    }, async () => {
+        return (0, helpers_1.fail)('The `encore` tool is deprecated. Use `restart` instead.\n' +
+            '  • `restart` runs the same algorithm (forceDetach → claim → context replay → spawn)\n' +
+            '  • Not limited to `stale`-only targets — works on any non-`gone` phase\n' +
+            '  • Pair with `host=<h>` or use `migrate` for cross-host revive');
+    });
+}

package/dist/tools/ensemble.d.ts

@@ -0,0 +1,32 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@temporalio/client';
+import { Config } from '../config';
+import { type EnsembleSessionInfo } from '../activities/resolve';
+/**
+ * Default dormancy threshold (1 hour). Per #563: a `detached` player whose
+ * last activity is older than this is considered dormant. `phase === 'gone'`
+ * is dormant regardless of timestamp.
+ */
+export declare const DORMANT_THRESHOLD_MS: number;
+/** Filter mode for the `dormant` arg on the `ensemble` MCP tool. */
+export type DormantFilter = 'show' | 'hide' | 'show-only';
+/**
+ * Classify a session as `'active'` or `'dormant'` per the #563 rules.
+ *
+ * - `phase === 'gone'` → always dormant.
+ * - `phase === 'detached'` AND `lastActivityAt` older than `thresholdMs`
+ *   → dormant.
+ * - `phase === 'detached'` AND `lastActivityAt` missing → dormant. (Pre-W2
+ *   sessions don't carry the timestamp; operator intent is to declutter
+ *   the active list, so we err toward grouping these with the cruft. The
+ *   default `--dormant=show` still shows them, just in their own section.)
+ * - Otherwise → active. Includes `awaiting` (live attachment), `processing`,
+ *   `attached`, `booting`, `draining`, and the undefined-phase case (older
+ *   workflows that predate the attachment lifecycle).
+ *
+ * Pure function — injectable `now` keeps it deterministic under test.
+ *
+ * Exported for unit testing.
+ */
+export declare function classifyDormancy(session: Pick<EnsembleSessionInfo, 'phase' | 'lastActivityAt'>, now: number, thresholdMs?: number): 'active' | 'dormant';
+export declare function registerEnsembleTool(server: McpServer, client: Client, config: Config, getPlayerId: () => string, ownWorkflowId: string): void;