agent-tempo 1.0.1

package/dist/tools/recall.d.ts

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

package/dist/tools/recall.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerRecallTool = registerRecallTool;
+const zod_1 = require("zod");
+const helpers_1 = require("./helpers");
+const recall_format_1 = require("../utils/recall-format");
+function registerRecallTool(server, handle, getPlayerId) {
+    (0, helpers_1.defineTool)(server, 'recall', 'Read your own message history. Shows received messages by default; use includeSent to also see outgoing messages. `offset` pages the timeline; `previewLength` truncates bodies (unset = full text).', {
+        limit: zod_1.z.number().min(1).max(100).optional().describe('Max messages to return (default 20, max 100)'),
+        offset: zod_1.z.number().int().min(0).optional().describe('Skip N messages for paging (default 0)'),
+        previewLength: zod_1.z.number().int().min(1).optional().describe('Truncate each body to N chars + "…"; omit for full text'),
+        since: zod_1.z.string().optional().describe('Only show messages at or after this ISO timestamp'),
+        from: zod_1.z.string().optional().describe('Filter received messages by sender name'),
+        includeSent: zod_1.z.boolean().optional().describe('Include sent messages in the timeline (default: false)'),
+    }, async (args) => {
+        const { limit, offset, previewLength, since, from: fromFilter, includeSent } = args;
+        // Validate `since` up-front so the formatter never sees a garbage date.
+        if (since && Number.isNaN(Date.parse(since))) {
+            return (0, helpers_1.fail)(`Invalid ISO timestamp for "since": ${since}`);
+        }
+        try {
+            const received = await handle.query('allMessages');
+            const sent = includeSent ? await handle.query('allSentMessages') : [];
+            const timeline = (0, recall_format_1.buildTimeline)(received, sent, Boolean(includeSent));
+            const rendered = (0, recall_format_1.formatRecall)(timeline, { limit, offset, previewLength, since, from: fromFilter });
+            return (0, helpers_1.ok)(rendered.text);
+        }
+        catch (err) {
+            return (0, helpers_1.fail)(`Failed to recall messages: ${(0, helpers_1.formatError)(err)}`);
+        }
+    });
+}

package/dist/tools/recruit.d.ts

@@ -0,0 +1,38 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client, WorkflowHandle } from '@temporalio/client';
+import { Config } from '../config';
+import { AgentType } from '../types';
+import type { HostInfo } from '../types';
+/**
+ * #274 M15 — dep-injection surface on the recruit tool registrar.
+ *
+ * `listHostsFn` lets tests stub host discovery without touching
+ * `TestWorkflowEnvironment` internals. Production callers (`src/server.ts`)
+ * omit this; the default pulls in `src/utils/hosts.ts` lazily.
+ */
+export interface RegisterRecruitToolDeps {
+    listHostsFn?: (client: Client) => Promise<HostInfo[]>;
+}
+export declare function registerRecruitTool(server: McpServer, client: Client, config: Config, getPlayerId: () => string, handle: WorkflowHandle, ownAgentType?: AgentType, deps?: RegisterRecruitToolDeps): void;
+/**
+ * Given a host liveness+profile snapshot, validate that `targetHost` is
+ * (a) known, (b) recruit-ready, and (c) advertises support for
+ * `requestedAgent`. Returns a user-facing error string when validation
+ * fails, or `null` when all checks pass.
+ *
+ * Profile-missing is treated as a soft pass (the daemon is alive but
+ * didn't signal a profile, e.g. rolling-upgrade scenario or global
+ * maestro was unreachable at its boot). We fall through rather than
+ * fail — M10 / AC11c says operational UX beats strict enforcement when
+ * information is genuinely absent.
+ *
+ * Exported for unit testing per the M15 dep-injection pattern.
+ */
+export declare function checkHostPreflight(hosts: HostInfo[], targetHost: string, requestedAgent: AgentType): string | null;
+/**
+ * Pick the closest hostname to `target` by Levenshtein distance. Returns
+ * `null` when `candidates` is empty OR the nearest match is so distant
+ * (edit distance ≥ half the longer string's length) that suggesting it
+ * would be misleading. Exported for tests.
+ */
+export declare function nearestHostname(target: string, candidates: string[]): string | null;

package/dist/tools/recruit.js

@@ -0,0 +1,447 @@
+"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.registerRecruitTool = registerRecruitTool;
+exports.checkHostPreflight = checkHostPreflight;
+exports.nearestHostname = nearestHostname;
+const zod_1 = require("zod");
+const child_process_1 = require("child_process");
+const config_1 = require("../config");
+const types_1 = require("../types");
+const resolve_1 = require("./resolve");
+const signals_1 = require("../workflows/signals");
+const helpers_1 = require("./helpers");
+const agent_types_1 = require("../ensemble/agent-types");
+const validation_1 = require("../utils/validation");
+const sdk_probe_1 = require("../utils/sdk-probe");
+const pre_flight_1 = require("../adapters/claude-code-headless/pre-flight");
+const types_2 = require("../adapters/claude-code-headless/types");
+const toolLog = (...args) => console.error('[agent-tempo:recruit]', ...args);
+/**
+ * #449 Phase C — check whether the `opencode` binary is on PATH. Used by
+ * the recruit pre-flight to fail fast with an actionable error before the
+ * adapter spawn activity runs and hits ENOENT mid-flight.
+ *
+ * Cross-platform: `where` on Windows, `command -v` on POSIX. Both exit 0
+ * when found, non-zero otherwise; stdout/stderr captured silently.
+ */
+function hasOpencodeOnPath() {
+    try {
+        const cmd = process.platform === 'win32' ? 'where' : 'command';
+        const args = process.platform === 'win32' ? ['opencode'] : ['-v', 'opencode'];
+        const result = (0, child_process_1.spawnSync)(cmd, args, {
+            stdio: ['ignore', 'ignore', 'ignore'],
+            shell: process.platform !== 'win32', // POSIX needs the shell built-in
+        });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function registerRecruitTool(server, client, config, getPlayerId, handle, ownAgentType = 'claude', deps = {}) {
+    // Lazy default — only imports utils/hosts when actually called, so the
+    // MCP server's module load graph doesn't drag the whole join layer
+    // into every consumer at import time.
+    const listHostsFn = deps.listHostsFn ?? (async (c) => {
+        const { listHosts } = await Promise.resolve().then(() => __importStar(require('../utils/hosts')));
+        return listHosts(c, {
+            force: true, // pre-flight wants "right now" — no cached snapshot
+            namespace: config.temporalNamespace,
+            taskQueue: config.taskQueue,
+        });
+    });
+    (0, helpers_1.defineTool)(server, 'recruit', `Start a new named session in a directory. Rejects if the name is already active. Supports Claude Code or Copilot CLI agents. Defaults to "${ownAgentType}" (same as this session).`, {
+        workDir: zod_1.z.string().max(validation_1.PATH_MAX).describe('The working directory for the new session'),
+        name: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).describe('Name for the new session'),
+        conductor: zod_1.z.boolean().optional()
+            .describe('Whether this session is a conductor (default: false)'),
+        initialMessage: zod_1.z.string().max(validation_1.MESSAGE_MAX).optional()
+            .describe('Optional task or message for the new session (sent after it sets its name)'),
+        agent: zod_1.z.enum(types_1.AGENT_TYPES).optional()
+            .describe(`Which agent to use (default: "${ownAgentType}", same as this session). "mock" requires dev mode (--dev). "claude-api" runs headless via the Anthropic Messages API — requires ANTHROPIC_API_KEY env var and the @anthropic-ai/sdk optional dependency installed; has access to agent-tempo MCP tools (cue, report, recall, ensemble, …) but NOT file-edit or shell tools (use "claude" for those). "opencode" runs headless via a local opencode serve subprocess; multi-provider (Anthropic, OpenAI, Bedrock, Ollama, …) — requires the @opencode-ai/sdk optional dep and an opencode binary on PATH. opencode players ARE file-op-capable (file edits / shell / web search via OpenCode's built-in tools). "claude-code-headless" runs the official Claude Code CLI as a headless per-turn \`claude -p\` subprocess — requires the \`claude\` binary on PATH AND a logged-in Claude Code session (\`claude auth login\`); turns bill against the host's existing subscription extra-usage credits, NOT a Console API key. claude-code-headless players have full Claude Code tool access (Bash, Read, Write, Edit, Glob, Grep, WebSearch, WebFetch).`),
+        model: zod_1.z.string().regex(/^[a-z0-9][a-z0-9-/.:_]*$/).optional()
+            .describe('Model id. For "claude-api": bare Anthropic id (e.g. "claude-opus-4-7"). For "opencode": combined "provider/model" (e.g. "anthropic/claude-opus-4-7", "openai/gpt-4o", "ollama/llama3"). Falls back to AGENT_TEMPO_API_MODEL (claude-api) or AGENT_TEMPO_OPENCODE_MODEL (opencode), then a constants-pinned default. Ignored for claude / copilot / mock adapters.'),
+        type: zod_1.z.string().optional()
+            .describe('Agent type name — references a Claude Code agent definition (e.g., "tempo-soloist")'),
+        systemPrompt: zod_1.z.string().optional()
+            .describe('Path to a .md file to use as custom agent system prompt (--system-prompt)'),
+        host: zod_1.z.string().optional()
+            .describe('Target hostname for cross-machine recruiting. Omit for local spawn.'),
+        force: zod_1.z.boolean().optional()
+            .describe('Force-terminate any existing session with this name before recruiting. Use when a previous session is orphaned or stuck.'),
+        mockMode: zod_1.z.enum(types_1.MOCK_MODES).optional()
+            .describe('Dev-mode only (agent: "mock"). Mock adapter mode. Default: "echo". "silent" never replies (heartbeat-stale validation); "chaos" probabilistic fail/crash injection (env-tuned).'),
+        mockScenario: zod_1.z.string().optional()
+            .describe('Dev-mode only (agent: "mock", mockMode: "scripted"). Bare scenario name (resolved against shipped scenarios/) or absolute path to a scenario YAML.'),
+        // #520 — claude-code-headless adapter knobs. Both ignored for other adapters.
+        permissionMode: zod_1.z.enum(types_2.CLAUDE_CODE_PERMISSION_MODES).optional()
+            .describe('claude-code-headless only. Permission mode forwarded to `claude -p --permission-mode`. Default "acceptEdits" auto-approves writes + common fs commands. "bypassPermissions" / "dangerouslySkipPermissions" trades safety for speed in trusted contexts. "plan" plans without executing — not useful for headless players. Mutually exclusive with `dangerouslySkipPermissions`.'),
+        dangerouslySkipPermissions: zod_1.z.boolean().optional()
+            .describe('claude-code-headless only. When true, passes `--dangerously-skip-permissions` to `claude -p` instead of `--permission-mode`. Use only in sandboxed/trusted contexts. Mutually exclusive with `permissionMode`.'),
+    }, async (args) => {
+        const { workDir, name, initialMessage } = args;
+        const isConductor = args.conductor === true;
+        const agent = args.agent || ownAgentType;
+        const model = args.model;
+        const agentTypeName = args.type;
+        const systemPrompt = args.systemPrompt;
+        const host = args.host;
+        const force = args.force === true;
+        const mockMode = args.mockMode;
+        const mockScenario = args.mockScenario;
+        const permissionMode = args.permissionMode;
+        const dangerouslySkipPermissions = args.dangerouslySkipPermissions === true;
+        // ADR 0014 §7 gate 3 — recruit-time rejection of `agent: 'mock'`
+        // outside dev mode. Defense-in-depth: even if a hand-edited install
+        // had `dist/adapters/mock/` present (gate 1 bypassed) AND somehow
+        // got the registry to register the descriptor (gate 2 bypassed),
+        // this rejects the request with a clear, actionable error.
+        if (agent === 'mock' && !(0, config_1.isDevMode)()) {
+            return (0, helpers_1.fail)(`agent: "mock" is only available in dev mode. Restart agent-tempo with --dev (or set AGENT_TEMPO_DEV_MODE=1) to enable.`);
+        }
+        // mockMode / mockScenario are only meaningful with the mock adapter —
+        // reject silently-ignored params so users learn the right flag shape.
+        if (mockMode != null && agent !== 'mock') {
+            return (0, helpers_1.fail)(`mockMode is only valid when agent: "mock" (got agent: "${agent}").`);
+        }
+        if (mockScenario != null && agent !== 'mock') {
+            return (0, helpers_1.fail)(`mockScenario is only valid when agent: "mock" (got agent: "${agent}").`);
+        }
+        if (agent === 'mock' && mockMode === 'scripted' && !mockScenario) {
+            return (0, helpers_1.fail)(`mockMode: "scripted" requires mockScenario (a bare scenario name or path to a YAML file).`);
+        }
+        // PR-3: silent + chaos modes don't consult the scenario file. Reject
+        // explicitly rather than silently ignore so users learn the right
+        // shape and don't sit wondering why their scenario wasn't applied.
+        if (mockScenario && (mockMode === 'silent' || mockMode === 'chaos')) {
+            return (0, helpers_1.fail)(`mockMode: "${mockMode}" does not use a scenario. Drop mockScenario or switch to mockMode: "scripted".`);
+        }
+        // #131 / #449 Phase C — model knob is meaningful for claude-api AND
+        // opencode (different shapes — bare vs `provider/model` — both flow
+        // through the same recruit field). Reject silently-ignored params for
+        // the other adapters so users learn the right shape.
+        // Local-spawn pre-flight checks (env vars + SDK install + binaries)
+        // run only when `host` is unset; cross-host recruits delegate to the
+        // target daemon's `availableAgentTypes` advertisement (the existing
+        // `checkHostPreflight` path), which already gates on whether the
+        // remote daemon resolved the SDK at boot.
+        if (model != null && agent !== 'claude-api' && agent !== 'opencode') {
+            return (0, helpers_1.fail)(`model is only valid when agent: "claude-api" or agent: "opencode" (got agent: "${agent}").`);
+        }
+        // #520 — claude-code-headless permission knobs are mutually exclusive
+        // and only meaningful for that adapter. Reject silently-ignored
+        // params so users learn the right shape.
+        if (permissionMode != null && agent !== 'claude-code-headless') {
+            return (0, helpers_1.fail)(`permissionMode is only valid when agent: "claude-code-headless" (got agent: "${agent}").`);
+        }
+        if (dangerouslySkipPermissions && agent !== 'claude-code-headless') {
+            return (0, helpers_1.fail)(`dangerouslySkipPermissions is only valid when agent: "claude-code-headless" (got agent: "${agent}").`);
+        }
+        if (permissionMode != null && dangerouslySkipPermissions) {
+            return (0, helpers_1.fail)(`permissionMode and dangerouslySkipPermissions are mutually exclusive — pass at most one.`);
+        }
+        if (agent === 'claude-api' && !host && !force) {
+            if (!process.env.ANTHROPIC_API_KEY) {
+                return (0, helpers_1.fail)(`agent: "claude-api" requires the ANTHROPIC_API_KEY environment variable on the spawn host. Set it before recruiting (export ANTHROPIC_API_KEY=sk-...) or use \`force: true\` to bypass this check.`);
+            }
+            try {
+                require.resolve('@anthropic-ai/sdk');
+            }
+            catch {
+                return (0, helpers_1.fail)(`agent: "claude-api" requires the @anthropic-ai/sdk optional dependency. Install with \`npm install @anthropic-ai/sdk\` and retry, or use \`force: true\` to bypass this check.`);
+            }
+        }
+        // #449 Phase C — opencode pre-flight. Two checks: the optional SDK
+        // (signal that opencode integration is intended on this host) AND
+        // the `opencode` binary on PATH (the adapter spawns `opencode serve`
+        // as a subprocess). Cross-host recruits skip both — the target
+        // daemon's `availableAgentTypes` is the gate there.
+        if (agent === 'opencode' && !host && !force) {
+            if (!(0, sdk_probe_1.probeSdkInstall)('@opencode-ai/sdk')) {
+                return (0, helpers_1.fail)(`agent: "opencode" requires the @opencode-ai/sdk optional dependency. Install with \`npm install @opencode-ai/sdk\` and retry, or use \`force: true\` to bypass this check.`);
+            }
+            if (!hasOpencodeOnPath()) {
+                return (0, helpers_1.fail)(`agent: "opencode" requires the \`opencode\` binary on PATH. Install with \`npm install -g opencode-ai\` and retry, or use \`force: true\` to bypass this check.`);
+            }
+        }
+        // #520 — claude-code-headless pre-flight. Two checks, both bounded by
+        // short timeouts (3s + 5s). The auth probe uses the official `claude
+        // auth status` subcommand — no billed API call. Cross-host recruits
+        // skip both — the target daemon's `availableAgentTypes` is the gate
+        // there (PR-2 wires the daemon-side probe).
+        if (agent === 'claude-code-headless' && !host && !force) {
+            const claudeBin = config.claudeBin ?? 'claude';
+            const binProbe = (0, pre_flight_1.probeClaudeBinary)(claudeBin);
+            if (!binProbe.ok) {
+                return (0, helpers_1.fail)(`agent: "claude-code-headless" pre-flight failed: ${binProbe.error} Use \`force: true\` to bypass.`);
+            }
+            const authProbe = (0, pre_flight_1.probeClaudeAuth)(claudeBin);
+            if (!authProbe.loggedIn) {
+                return (0, helpers_1.fail)(`agent: "claude-code-headless" pre-flight failed: ${authProbe.error} Use \`force: true\` to bypass.`);
+            }
+        }
+        // #532 — copilot pre-flight. SDK-only probe (mirrors claude-api's
+        // pattern; copilot has no subprocess CLI on PATH). The bridge
+        // subprocess hard-requires `@github/copilot-sdk` at module load
+        // (`src/adapters/copilot/adapter.ts:71`), so without this gate the
+        // user only learns of the missing dep AFTER bridge spawn —
+        // adapter crashes with `process.exit(1)` and the player sits in
+        // `booting` until lease timeout. We use `probeSdkInstall` (FS walk)
+        // rather than `require.resolve` because pnpm layouts without a
+        // top-level hoisted link otherwise false-negative; see issue #532
+        // investigation footnote. GITHUB_TOKEN / Copilot CLI login are
+        // intentionally NOT checked: the SDK falls through to the
+        // logged-in user (`adapter.ts:31, :263`), so token presence is not
+        // a hard requirement. Cross-host recruits skip — the target
+        // daemon's `availableAgentTypes` is the gate there.
+        if (agent === 'copilot' && !host && !force) {
+            if (!(0, sdk_probe_1.probeSdkInstall)('@github/copilot-sdk')) {
+                return (0, helpers_1.fail)(`agent: "copilot" requires the @github/copilot-sdk optional dependency. Install with \`npm install @github/copilot-sdk\` and retry, or use \`force: true\` to bypass this check.`);
+            }
+        }
+        // Resolve agent type if provided
+        let agentDefinition;
+        let agentDefinitionPath;
+        let agentDefinitionDescription;
+        let nativeResolvable;
+        let allowedTools;
+        if (agentTypeName) {
+            const info = (0, agent_types_1.resolveAgentType)(agentTypeName);
+            if (!info) {
+                const available = (0, agent_types_1.listAgentTypes)().map(t => t.name);
+                return (0, helpers_1.fail)(`Unknown agent type "${agentTypeName}". Available types: ${available.length ? available.join(', ') : '(none)'}`);
+            }
+            agentDefinition = info.name;
+            agentDefinitionPath = info.path;
+            agentDefinitionDescription = info.description;
+            nativeResolvable = info.nativeResolvable;
+            allowedTools = info.allowedTools;
+        }
+        // Validate name
+        const nameError = (0, validation_1.validatePlayerName)(name);
+        if (nameError) {
+            return (0, helpers_1.fail)(nameError);
+        }
+        if (name === 'conductor' && !isConductor) {
+            return (0, helpers_1.fail)(`The name "conductor" is reserved for conductor sessions. Use a different name, or set conductor: true.`);
+        }
+        // ── #274 AC12 — cross-host recruit pre-flight ──
+        //
+        // When `host` is specified, verify that the target is live + has
+        // the requested agent runtime available BEFORE submitting to the
+        // outbox. Otherwise `recruit --host foo` could queue forever on a
+        // per-host task queue nobody's listening on (the exact failure
+        // mode #274 set out to close).
+        //
+        // `force: true` bypasses pre-flight entirely (AC12d) — covers the
+        // scripted-recruit-on-about-to-boot-daemon case plus any other
+        // "I know what I'm doing" override. RPC failure during pre-flight
+        // falls through with a warning (AC12e) so today's recruit
+        // availability characteristics are preserved.
+        if (host && !force) {
+            try {
+                const hosts = await listHostsFn(client);
+                const preflightError = checkHostPreflight(hosts, host, agent);
+                if (preflightError)
+                    return (0, helpers_1.fail)(preflightError);
+            }
+            catch (err) {
+                toolLog(`Host pre-flight RPC failed for "${host}"; proceeding without validation (use --force to silence this warning): ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        try {
+            // Check if a conductor already exists when recruiting a conductor
+            if (isConductor) {
+                try {
+                    const conductorWfId = (0, config_1.conductorWorkflowId)(config.ensemble);
+                    const conductorHandle = client.workflow.getHandle(conductorWfId);
+                    const desc = await conductorHandle.describe();
+                    if (desc.status.name === 'RUNNING') {
+                        if (force) {
+                            await conductorHandle.terminate(`Force-terminated for re-recruit by ${getPlayerId()}`);
+                        }
+                        else {
+                            return (0, helpers_1.fail)(`A conductor is already running in ensemble "${config.ensemble}". Use \`agent-tempo conduct --replace\` from the CLI to replace it, \`stop\` it first, or use \`force: true\` to replace it.`);
+                        }
+                    }
+                }
+                catch {
+                    // No existing conductor — proceed
+                }
+            }
+            // Check if a session with this name is already active
+            const existing = await (0, resolve_1.resolveSession)(client, config.ensemble, name);
+            if (existing) {
+                if (force) {
+                    // Force-terminate the existing session before recruiting
+                    await existing.terminate(`Force-terminated for re-recruit by ${getPlayerId()}`);
+                    // Best-effort notify conductor
+                    try {
+                        const condId = (0, config_1.conductorWorkflowId)(config.ensemble);
+                        const condHandle = client.workflow.getHandle(condId);
+                        await condHandle.signal('receiveMessage', {
+                            from: 'system',
+                            text: `Session "${name}" was force-terminated for re-recruit by ${getPlayerId()}.`,
+                            responseRequested: false,
+                        });
+                    }
+                    catch {
+                        // Conductor may not exist — that's fine
+                    }
+                }
+                else {
+                    return (0, helpers_1.fail)(`Session **${name}** is already active. Use \`cue\` to send it a message, \`stop\` it first, or use \`force: true\` to replace it.`);
+                }
+            }
+            const entry = {
+                type: 'recruit',
+                targetName: name,
+                workDir,
+                isConductor,
+                initialMessage,
+                agent,
+                systemPrompt: agentDefinition ? undefined : systemPrompt,
+                targetHostname: host,
+                agentDefinition,
+                agentDefinitionPath,
+                agentDefinitionDescription,
+                nativeResolvable,
+                allowedTools,
+                claudeBin: config.claudeBin,
+                ...(agent === 'mock' ? { mockMode: mockMode ?? 'echo' } : {}),
+                ...(agent === 'mock' && mockScenario ? { mockScenario } : {}),
+                ...(agent === 'claude-api' && model ? { model } : {}),
+                // #520 — claude-code-headless permission knobs flow through the
+                // outbox so PR-2's spawn helper picks them up via env. Fields
+                // are only present on the entry when actually set; the
+                // OutboxEntryInput shape will gain typed `permissionMode` /
+                // `dangerouslySkipPermissions` fields in PR-2.
+                ...(agent === 'claude-code-headless' && permissionMode ? { permissionMode } : {}),
+                ...(agent === 'claude-code-headless' && dangerouslySkipPermissions ? { dangerouslySkipPermissions: true } : {}),
+            };
+            const entryId = await handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
+            return (0, helpers_1.ok)(`Recruit request submitted for **${name}** in ${workDir}. The session will be spawned shortly. (outbox: ${entryId})`);
+        }
+        catch (err) {
+            return (0, helpers_1.fail)(`Failed to recruit: ${(0, helpers_1.formatError)(err)}`);
+        }
+    });
+}
+// ────────────────────────────────────────────────────────────────────────
+// #274 AC12 — host pre-flight validation (exported for unit tests)
+// ────────────────────────────────────────────────────────────────────────
+/**
+ * Given a host liveness+profile snapshot, validate that `targetHost` is
+ * (a) known, (b) recruit-ready, and (c) advertises support for
+ * `requestedAgent`. Returns a user-facing error string when validation
+ * fails, or `null` when all checks pass.
+ *
+ * Profile-missing is treated as a soft pass (the daemon is alive but
+ * didn't signal a profile, e.g. rolling-upgrade scenario or global
+ * maestro was unreachable at its boot). We fall through rather than
+ * fail — M10 / AC11c says operational UX beats strict enforcement when
+ * information is genuinely absent.
+ *
+ * Exported for unit testing per the M15 dep-injection pattern.
+ */
+function checkHostPreflight(hosts, targetHost, requestedAgent) {
+    const match = hosts.find((h) => h.hostname === targetHost);
+    if (!match) {
+        const knownNames = hosts.map((h) => h.hostname);
+        const suggestion = nearestHostname(targetHost, knownNames);
+        const available = knownNames.length > 0 ? knownNames.join(', ') : '(none — no daemons currently polling)';
+        const hint = suggestion && suggestion !== targetHost ? ` Did you mean "${suggestion}"?` : '';
+        return `Unknown host "${targetHost}".${hint} Available: ${available}. Use \`force: true\` to bypass this check.`;
+    }
+    if (match.freshness !== 'live' || !match.recruitReady) {
+        return `Host "${targetHost}" is not recruit-ready right now (freshness=${match.freshness}, recruitReady=${match.recruitReady}). Wait for the daemon to signal again, or use \`force: true\` to bypass.`;
+    }
+    // Profile-missing → soft pass. Daemon is alive + recruit-ready; we
+    // just don't have capability info. Log-level guidance could be added
+    // later; for now we accept to avoid false-negative rejection.
+    if (match.profile && match.profile.availableAgentTypes) {
+        if (!match.profile.availableAgentTypes.includes(requestedAgent)) {
+            const supports = match.profile.availableAgentTypes.length > 0
+                ? match.profile.availableAgentTypes.join(', ')
+                : '(none advertised)';
+            return `Host "${targetHost}" cannot run \`${requestedAgent}\` (supports: ${supports}). Use \`force: true\` to bypass this check.`;
+        }
+    }
+    return null;
+}
+/**
+ * Pick the closest hostname to `target` by Levenshtein distance. Returns
+ * `null` when `candidates` is empty OR the nearest match is so distant
+ * (edit distance ≥ half the longer string's length) that suggesting it
+ * would be misleading. Exported for tests.
+ */
+function nearestHostname(target, candidates) {
+    if (candidates.length === 0)
+        return null;
+    let best = null;
+    for (const cand of candidates) {
+        const dist = levenshtein(target, cand);
+        if (best === null || dist < best.dist)
+            best = { name: cand, dist };
+    }
+    if (!best)
+        return null;
+    const ratioThreshold = Math.max(target.length, best.name.length) / 2;
+    return best.dist < ratioThreshold ? best.name : null;
+}
+/** Iterative O(n·m) Levenshtein distance. 15 lines, no dep. */
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    // previous row of distances
+    let prev = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        const curr = new Array(b.length + 1);
+        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(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+        }
+        prev = curr;
+    }
+    return prev[b.length];
+}

package/dist/tools/release.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 registerReleaseTool(server: McpServer, client: Client, config: Config, getPlayerId: () => string, handle: WorkflowHandle): void;

package/dist/tools/release.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerReleaseTool = registerReleaseTool;
+const zod_1 = require("zod");
+const resolve_1 = require("../activities/resolve");
+const signals_1 = require("../workflows/signals");
+const helpers_1 = require("./helpers");
+const validation_1 = require("../utils/validation");
+function registerReleaseTool(server, client, config, getPlayerId, handle) {
+    (0, helpers_1.defineTool)(server, 'release', 'Release held player sessions — unlocks their outboxes and delivers deferred task messages. Without a player name, releases all held sessions.', {
+        player: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).optional()
+            .describe('Name of a specific held player to release. Omit to release all held players.'),
+    }, async (args) => {
+        const { player } = args;
+        if (player) {
+            const nameError = (0, validation_1.validatePlayerName)(player);
+            if (nameError)
+                return (0, helpers_1.fail)(nameError);
+        }
+        try {
+            if (player) {
+                // Release a specific player
+                const sessions = await (0, resolve_1.scanEnsembleSessions)(client, config.ensemble);
+                const target = sessions.find((s) => s.playerId === player);
+                if (!target) {
+                    return (0, helpers_1.fail)(`No session found with name "${player}".`);
+                }
+                // Check if the session's outbox is actually locked
+                const targetHandle = client.workflow.getHandle(target.workflowId);
+                let isLocked = false;
+                try {
+                    isLocked = await targetHandle.query(signals_1.outboxLockedQuery);
+                }
+                catch {
+                    // Query may fail for old workflows without the handler — not held
+                }
+                if (!isLocked) {
+                    return (0, helpers_1.fail)(`Session "${player}" is not held (outbox not locked). Only held sessions can be released.`);
+                }
+                const entry = {
+                    type: 'release',
+                    targetPlayerId: player,
+                };
+                const entryId = await handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
+                return (0, helpers_1.ok)(`Release request submitted for **${player}**. Task assignment will be delivered shortly. (outbox: ${entryId})`);
+            }
+            else {
+                // Release all held players — scan ensemble and check outboxLocked on each
+                const sessions = await (0, resolve_1.scanEnsembleSessions)(client, config.ensemble);
+                const heldSessions = [];
+                for (const session of sessions) {
+                    // Skip self and conductors (conductor outbox is never locked)
+                    if (session.playerId === getPlayerId())
+                        continue;
+                    try {
+                        const sessionHandle = client.workflow.getHandle(session.workflowId);
+                        const isLocked = await sessionHandle.query(signals_1.outboxLockedQuery);
+                        if (isLocked) {
+                            heldSessions.push(session);
+                        }
+                    }
+                    catch {
+                        // Skip sessions where query fails (old workflows, terminated, etc.)
+                    }
+                }
+                if (heldSessions.length === 0) {
+                    return (0, helpers_1.ok)('No held sessions found. Nothing to release.');
+                }
+                const released = [];
+                const errors = [];
+                for (const session of heldSessions) {
+                    try {
+                        const entry = {
+                            type: 'release',
+                            targetPlayerId: session.playerId,
+                        };
+                        await handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
+                        released.push(session.playerId);
+                    }
+                    catch (err) {
+                        errors.push(`${session.playerId}: ${(0, helpers_1.formatError)(err)}`);
+                    }
+                }
+                const lines = [];
+                if (released.length > 0) {
+                    lines.push(`Released ${released.length} player(s): ${released.join(', ')}`);
+                }
+                if (errors.length > 0) {
+                    lines.push(`Errors:\n${errors.map((e) => `  - ${e}`).join('\n')}`);
+                }
+                return (0, helpers_1.ok)(lines.join('\n'));
+            }
+        }
+        catch (err) {
+            return (0, helpers_1.fail)(`Failed to release: ${(0, helpers_1.formatError)(err)}`);
+        }
+    });
+}

package/dist/tools/report.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WorkflowHandle } from '@temporalio/client';
+export declare function registerReportTool(server: McpServer, handle: WorkflowHandle): void;