agent-tempo 1.0.1

package/dist/activities/outbox.js

@@ -0,0 +1,849 @@
+"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.createOutboxActivities = createOutboxActivities;
+const client_1 = require("@temporalio/client");
+const activity_1 = require("@temporalio/activity");
+const os = __importStar(require("os"));
+const crypto = __importStar(require("crypto"));
+const config_1 = require("../config");
+const validation_1 = require("../utils/validation");
+const constants_1 = require("../constants");
+const git_info_1 = require("../git-info");
+const spawn_1 = require("../spawn");
+const config_2 = require("../config");
+const resolve_1 = require("./resolve");
+const agent_types_1 = require("../ensemble/agent-types");
+const default_part_1 = require("../utils/default-part");
+const adapters_1 = require("../adapters");
+const hard_terminate_1 = require("./hard-terminate");
+const signals_1 = require("../workflows/signals");
+const validation_2 = require("../utils/validation");
+const log = (...args) => console.error('[agent-tempo:outbox]', ...args);
+/**
+ * Classify a Temporal client error raised by `handle.query` / `handle.signal`
+ * / `handle.executeUpdate` as retryable (transient) vs permanent (#140).
+ *
+ * ## Contract
+ * - Returns `true` → caller should **re-throw the underlying Error** so the
+ *   activity's retry policy can back off and retry (per-worker config).
+ * - Returns `false` → caller should wrap in `ApplicationFailure.nonRetryable`
+ *   so the outbox surfaces a permanent failure and stops retrying.
+ *
+ * ## Safety posture
+ * **Conservative default: unknown → non-retryable.** Over-classifying as
+ * retryable causes infinite retry loops on genuinely permanent errors. The
+ * activity will fail fast on unknown cases; a follow-up PR can whitelist more
+ * transient signatures if we see false-permanent rates in the wild.
+ *
+ * ## Why name/message sniffing, not `instanceof`
+ * Matches the established pattern in `src/adapters/terminal-error.ts`
+ * `isTerminalWorkflowError`: the Temporal Node SDK surfaces slightly different
+ * error shapes between `@temporalio/client`, the gRPC layer, and
+ * `WorkflowUpdateFailedError` wrappers. Sniffing on name + message is resilient
+ * across those shapes. Activity-side classification is kept separate here so
+ * `src/activities/` has no adapter-module dependency.
+ */
+function isRetryableTemporalError(err) {
+    // ApplicationFailure instances have already been classified by the thrower
+    // (nonRetryable=true/false). The calling code paths in this module only ask
+    // about non-ApplicationFailure errors, but this guard makes the helper safe
+    // to call unconditionally.
+    if (err instanceof activity_1.ApplicationFailure)
+        return false;
+    const e = err;
+    const name = e?.name ?? '';
+    const msg = e?.message ?? '';
+    // ── Permanent: workflow is genuinely gone or validator rejected the op. ──
+    if (name.includes('WorkflowNotFound') ||
+        name.includes('WorkflowExecutionAlreadyCompleted') ||
+        // Update rejected by the workflow-side validator (e.g. `WorkflowGone`
+        // thrown from `claimAttachment`'s validator on a destroyed session).
+        // A retry won't make the validator change its mind.
+        name.includes('WorkflowUpdateFailed') ||
+        msg.includes('WorkflowGone') ||
+        msg.includes('workflow execution already completed'))
+        return false;
+    // ── Transient: RPC / network / temporary SDK unavailability. ──
+    if (name.includes('TransportError') ||
+        name.includes('TimeoutError') ||
+        msg.includes('DEADLINE_EXCEEDED') ||
+        msg.includes('UNAVAILABLE') ||
+        msg.includes('RESOURCE_EXHAUSTED') ||
+        msg.includes('CANCELLED') ||
+        /\bECONNRESET\b/.test(msg) ||
+        /\bECONNREFUSED\b/.test(msg) ||
+        /\bETIMEDOUT\b/.test(msg) ||
+        /\bENOTFOUND\b/.test(msg) ||
+        /\bEAI_AGAIN\b/.test(msg))
+        return true;
+    // Unknown shape — stay permanent (see "Safety posture" above).
+    return false;
+}
+/**
+ * Standard shape for the 3 §8.2 deliver activities' catch-all tail.
+ * Centralises the branch so each activity body stays concise.
+ *
+ * - If `err` is already an `ApplicationFailure` (typed permanent — e.g. the
+ *   explicit "not found" / "destroyed" throws), re-throw as-is.
+ * - If `err` is retryable per {@link isRetryableTemporalError}, re-throw the
+ *   original `Error` so the activity retry policy handles it.
+ * - Otherwise wrap in `ApplicationFailure.nonRetryable` with a caller-supplied
+ *   context prefix (e.g. `Detach failed for "alice"`).
+ */
+function classifyAndRethrow(err, contextPrefix) {
+    if (err instanceof activity_1.ApplicationFailure)
+        throw err;
+    if (isRetryableTemporalError(err)) {
+        // Re-throw the original so the activity retry policy backs off and retries.
+        // Normalise non-Error throwables (extremely rare) into Error form.
+        throw err instanceof Error ? err : new Error(String(err));
+    }
+    throw activity_1.ApplicationFailure.nonRetryable(`${contextPrefix}: ${err instanceof Error ? err.message : String(err)}`);
+}
+/**
+ * Create outbox delivery activities bound to a Temporal client and config.
+ * The returned object is registered with the worker as activities.
+ */
+function createOutboxActivities(client, config) {
+    return {
+        async deliverCue(input) {
+            const { ensemble, fromPlayerId, targetPlayerId, message, broadcastId, attachmentTicket } = input;
+            try {
+                const handle = await (0, resolve_1.resolveSession)(client, ensemble, targetPlayerId);
+                if (!handle) {
+                    throw activity_1.ApplicationFailure.nonRetryable(`No active session found for "${targetPlayerId}"`);
+                }
+                // #357 + #318: thread broadcastId / attachmentTicket onto the
+                // receiver's `receiveMessage` signal payload. Both fields are
+                // additive optionals — direct cues omit one or both.
+                await handle.signal('receiveMessage', {
+                    from: fromPlayerId,
+                    text: message,
+                    ...(broadcastId !== undefined ? { broadcastId } : {}),
+                    ...(attachmentTicket !== undefined ? { attachmentTicket } : {}),
+                });
+                return { success: true };
+            }
+            catch (err) {
+                // #236: transient RPC errors (e.g. DEADLINE_EXCEEDED on the signal call)
+                // retry per the activity policy; WorkflowNotFound / validator rejections
+                // stay permanent. Unknown errors default to non-retryable.
+                classifyAndRethrow(err, `Cue failed for "${targetPlayerId}"`);
+            }
+        },
+        async deliverReport(input) {
+            const { ensemble, fromPlayerId, text, reportType } = input;
+            try {
+                const conductorId = (0, config_1.conductorWorkflowId)(ensemble);
+                const handle = client.workflow.getHandle(conductorId);
+                await handle.describe(); // throws if conductor workflow is not running
+                await handle.signal('playerReport', { playerId: fromPlayerId, text, type: reportType });
+                return { success: true };
+            }
+            catch (err) {
+                // #236: describe() / signal() hitting a transient RPC error now retries;
+                // WorkflowNotFound (conductor gone) stays permanent as before.
+                classifyAndRethrow(err, 'Failed to deliver report to conductor');
+            }
+        },
+        async terminateSession(input) {
+            const { ensemble, targetPlayerId, terminatedBy } = input;
+            try {
+                const handle = await (0, resolve_1.resolveSession)(client, ensemble, targetPlayerId);
+                if (!handle) {
+                    throw activity_1.ApplicationFailure.nonRetryable(`No active session found for "${targetPlayerId}"`);
+                }
+                // PR-C commit 4: use the V2 `destroy` update — explicit operator termination
+                // per §2.5 (abandon in-flight, phase=gone, COMPLETE). The former
+                // `updateMetadata({ status: 'terminated' })` signal path was retired.
+                await handle.executeUpdate('destroy', {
+                    args: [{ reason: 'stop via tool', terminatedBy }],
+                });
+                // Notify conductor about the termination (best effort)
+                try {
+                    const conductorId = (0, config_1.conductorWorkflowId)(ensemble);
+                    const conductorHandle = client.workflow.getHandle(conductorId);
+                    await conductorHandle.signal('receiveMessage', {
+                        from: 'system',
+                        text: `Session "${targetPlayerId}" was terminated by ${terminatedBy}.`,
+                        responseRequested: false,
+                    });
+                }
+                catch {
+                    // Conductor may not exist — that's fine
+                }
+                return { success: true };
+            }
+            catch (err) {
+                // #236: transient RPC on the destroy update now retries; validator rejection
+                // (WorkflowGone, AttachmentMismatch) stays permanent.
+                classifyAndRethrow(err, `Terminate failed for "${targetPlayerId}"`);
+            }
+        },
+        async startRecruitedSession(input) {
+            const { ensemble, targetName, workDir, isConductor, initialMessage, fromPlayerId, agent, systemPrompt, taskQueue, agentDefinition, agentDefinitionDescription, held, model } = input;
+            try {
+                const workflowId = isConductor
+                    ? (0, config_1.conductorWorkflowId)(ensemble)
+                    : (0, config_1.sessionWorkflowId)(ensemble, targetName);
+                const { gitRoot, gitBranch } = (0, git_info_1.getGitInfo)(workDir);
+                // Generate a UUID for the session — used for deterministic --resume on encore
+                const sessionId = crypto.randomUUID();
+                // Warm hold: process will spawn and go active, but outbox is locked and
+                // the initial message is deferred. A standby message is sent instead.
+                const standbyMessage = held
+                    ? 'You are on standby. Your ensemble is loading — other players are still connecting. Wait for your task assignment. Do not start work or send messages yet.'
+                    : undefined;
+                const sessionInput = {
+                    metadata: {
+                        playerId: targetName,
+                        ensemble,
+                        hostname: os.hostname(),
+                        workDir,
+                        gitRoot,
+                        gitBranch,
+                        isConductor,
+                        agentType: agent,
+                        // PR-B (v0.25 step 2/7): populate adapterId on fresh recruits so the
+                        // session workflow and dispatch path can resolve the adapter descriptor
+                        // from the registry without falling back to the legacy agentType field.
+                        adapterId: adapters_1.registry.resolveFromAgentType(agent),
+                        sessionId,
+                        // #131 / #449 Phase C — persist the claude-api / opencode model
+                        // on durable metadata so restart can recover the original choice
+                        // across CAN. Both adapters use the same `model` metadata field
+                        // (different value shapes — bare vs `provider/model`) — the spawn
+                        // path inspects `metadata.agentType` to know which env var to set.
+                        ...((agent === 'claude-api' || agent === 'opencode') && model ? { model } : {}),
+                        ...(agentDefinition ? { playerType: agentDefinition } : {}),
+                        ...(agentDefinitionDescription ? { playerTypeDescription: agentDefinitionDescription } : {}),
+                        recruitedBy: fromPlayerId,
+                    },
+                    // Issue #450 — derive default `part` from the recruited
+                    // player type so a freshly recruited session reads as e.g.
+                    // `'Engineer session'` instead of the role-agnostic
+                    // `'Session in <basename>'` placeholder.
+                    autoSummary: (0, default_part_1.defaultPart)({
+                        playerType: agentDefinition,
+                        isConductor,
+                        workDir,
+                        adapterType: agent,
+                    }),
+                    disableStaleDetection: true,
+                    // When held: store the initial message for delivery on release, inject standby message instead
+                    ...(held ? { outboxLocked: true, heldMessage: initialMessage } : {}),
+                    messages: held
+                        ? [{
+                                id: crypto.randomUUID(),
+                                from: 'system',
+                                text: standbyMessage,
+                                timestamp: new Date().toISOString(),
+                                delivered: false,
+                            }]
+                        : (initialMessage ? [{
+                                id: crypto.randomUUID(),
+                                from: fromPlayerId,
+                                text: initialMessage,
+                                timestamp: new Date().toISOString(),
+                                delivered: false,
+                            }] : undefined),
+                };
+                await client.workflow.start('agentSessionWorkflow', {
+                    workflowId,
+                    taskQueue,
+                    args: [sessionInput],
+                    workflowIdConflictPolicy: client_1.WorkflowIdConflictPolicy.USE_EXISTING,
+                    searchAttributes: {
+                        ...(gitRoot ? { AgentTempoGitRoot: [gitRoot] } : {}),
+                        AgentTempoHostname: [os.hostname()],
+                        AgentTempoEnsemble: [ensemble],
+                        AgentTempoPlayerId: [targetName],
+                    },
+                });
+                log(`Pre-created workflow ${workflowId} for recruit "${targetName}" (sessionId=${sessionId}, held=${!!held})`);
+                return { success: true, sessionId };
+            }
+            catch (err) {
+                // #236: transient RPC during workflow.start (e.g. temporal server flap)
+                // now retries; WorkflowNotFound / validation / auth failures stay permanent.
+                // Note: this activity's pre-#236 catch was missing the ApplicationFailure
+                // passthrough guard — `classifyAndRethrow` restores it for free.
+                classifyAndRethrow(err, `Failed to start recruited session "${targetName}"`);
+            }
+        },
+        async spawnProcess(input) {
+            const { targetName, workDir, isConductor, agent, systemPrompt, ensemble, temporalAddress, temporalNamespace, agentDefinition, agentDefinitionPath, nativeResolvable, resume, sessionId, allowedTools, claudeBin, attachmentId, attachmentRunId, adapterId, mockMode, mockScenario, model, permissionMode, dangerouslySkipPermissions } = input;
+            // Read secrets from the worker's config closure — never from workflow state
+            const { temporalApiKey, temporalTlsCertPath, temporalTlsKeyPath } = config;
+            try {
+                if (agent === 'mock') {
+                    // ADR 0014 PR-2 — mock adapter spawns headless. No terminal,
+                    // no Claude binary, no MCP server child. Talks to Temporal
+                    // directly and posts every action through the standard outbox.
+                    const { spawnMockAdapter } = await Promise.resolve().then(() => __importStar(require('../spawn')));
+                    const { pid } = spawnMockAdapter({
+                        name: targetName,
+                        ensemble,
+                        temporalAddress,
+                        temporalNamespace,
+                        temporalApiKey,
+                        temporalTlsCertPath,
+                        temporalTlsKeyPath,
+                        isConductor,
+                        workDir,
+                        mockMode,
+                        mockScenario,
+                        attachmentId,
+                        attachmentRunId,
+                        adapterId,
+                    });
+                    log(`Spawned mock adapter (pid ${pid}) in ${workDir} as "${targetName}" (mode=${mockMode ?? 'echo'}${attachmentId ? `, attachmentId=${attachmentId}` : ''})`);
+                }
+                else if (agent === 'copilot') {
+                    if (allowedTools && allowedTools.length > 0) {
+                        log(`Warning: allowedTools [${allowedTools.join(', ')}] specified for copilot agent "${targetName}" — copilot bridge does not support --allowedTools, skipping`);
+                    }
+                    const { pid } = (0, spawn_1.spawnCopilotBridge)({
+                        name: targetName,
+                        ensemble,
+                        temporalAddress,
+                        temporalNamespace,
+                        temporalApiKey,
+                        temporalTlsCertPath,
+                        temporalTlsKeyPath,
+                        isConductor,
+                        workDir,
+                        sessionId,
+                        attachmentId,
+                        attachmentRunId,
+                        adapterId,
+                    });
+                    log(`Spawned copilot-bridge (pid ${pid}) in ${workDir} as "${targetName}"${attachmentId ? ` (attachmentId=${attachmentId})` : ''}`);
+                }
+                else if (agent === 'claude-api') {
+                    // #131 Phase C — headless Anthropic Messages API adapter. No
+                    // terminal, no Claude binary, no MCP-server child process. The
+                    // adapter boots an in-process MCP server + paired client and
+                    // talks to Anthropic via @anthropic-ai/sdk. Tool surface is
+                    // MCP-only in v1; file-edit/shell/web tools deferred to Phase 2.
+                    if (allowedTools && allowedTools.length > 0) {
+                        log(`Warning: allowedTools [${allowedTools.join(', ')}] specified for claude-api agent "${targetName}" — claude-api adapter does not gate tools per recruit, skipping`);
+                    }
+                    const { pid } = (0, spawn_1.spawnClaudeApiAdapter)({
+                        name: targetName,
+                        ensemble,
+                        temporalAddress,
+                        temporalNamespace,
+                        temporalApiKey,
+                        temporalTlsCertPath,
+                        temporalTlsKeyPath,
+                        isConductor,
+                        workDir,
+                        model,
+                        attachmentId,
+                        attachmentRunId,
+                        adapterId,
+                    });
+                    log(`Spawned claude-api adapter (pid ${pid}) in ${workDir} as "${targetName}"${model ? ` (model=${model})` : ''}${attachmentId ? ` (attachmentId=${attachmentId})` : ''}`);
+                }
+                else if (agent === 'opencode') {
+                    // #449 Phase C — headless multi-provider adapter via OpenCode.
+                    // No terminal, no Claude binary. The adapter manages its own
+                    // `opencode serve` subprocess (probed-free port, hardcoded
+                    // loopback bind); tools dispatch via OpenCode's MCP-native config
+                    // block (it spawns dist/server.js as its own MCP child). Per-tool
+                    // allowlists don't apply — opencode players have full file/shell/
+                    // web access via OpenCode's built-in tool registry.
+                    if (allowedTools && allowedTools.length > 0) {
+                        log(`Warning: allowedTools [${allowedTools.join(', ')}] specified for opencode agent "${targetName}" — opencode adapter does not gate tools per recruit, skipping`);
+                    }
+                    const { pid } = (0, spawn_1.spawnOpenCodeAdapter)({
+                        name: targetName,
+                        ensemble,
+                        temporalAddress,
+                        temporalNamespace,
+                        temporalApiKey,
+                        temporalTlsCertPath,
+                        temporalTlsKeyPath,
+                        isConductor,
+                        workDir,
+                        model,
+                        attachmentId,
+                        attachmentRunId,
+                        adapterId,
+                    });
+                    log(`Spawned opencode adapter (pid ${pid}) in ${workDir} as "${targetName}"${model ? ` (model=${model})` : ''}${attachmentId ? ` (attachmentId=${attachmentId})` : ''}`);
+                }
+                else if (agent === 'claude-code-headless') {
+                    // #520 — headless Claude Code adapter. Spawns the host's `claude` CLI
+                    // as a per-turn subprocess; uses the operator's existing OAuth login
+                    // so turns bill against subscription extra-usage credits. The adapter
+                    // process itself is a Node subprocess (this branch); the per-turn
+                    // `claude -p` invocations happen inside the adapter's invokeSdk loop
+                    // (PR-3). Per-tool allowlists don't apply — claude-code-headless
+                    // players inherit the full Claude Code tool surface.
+                    if (allowedTools && allowedTools.length > 0) {
+                        log(`Warning: allowedTools [${allowedTools.join(', ')}] specified for claude-code-headless agent "${targetName}" — claude-code-headless adapter does not gate tools per recruit, skipping`);
+                    }
+                    const { pid } = (0, spawn_1.spawnClaudeCodeHeadlessAdapter)({
+                        name: targetName,
+                        ensemble,
+                        temporalAddress,
+                        temporalNamespace,
+                        temporalApiKey,
+                        temporalTlsCertPath,
+                        temporalTlsKeyPath,
+                        isConductor,
+                        workDir,
+                        permissionMode,
+                        dangerouslySkipPermissions,
+                        attachmentId,
+                        attachmentRunId,
+                        adapterId,
+                    });
+                    log(`Spawned claude-code-headless adapter (pid ${pid}) in ${workDir} as "${targetName}"${permissionMode ? ` (permissionMode=${permissionMode})` : ''}${dangerouslySkipPermissions ? ' (dangerouslySkipPermissions=true)' : ''}${attachmentId ? ` (attachmentId=${attachmentId})` : ''}`);
+                }
+                else {
+                    // Resolve agent flags: --agent (native) > --system-prompt (shipped/legacy)
+                    let agentFlags = [];
+                    if (agentDefinition && nativeResolvable) {
+                        agentFlags = ['--agent', agentDefinition];
+                    }
+                    else if (agentDefinitionPath) {
+                        agentFlags = ['--system-prompt', agentDefinitionPath];
+                    }
+                    else if (systemPrompt) {
+                        agentFlags = ['--system-prompt', systemPrompt];
+                    }
+                    // Use --resume for encore (reconnect to existing session) or -n for new sessions.
+                    // For encore: use UUID for deterministic --resume (no interactive picker).
+                    // For new sessions: use --session-id to track the UUID for future encores.
+                    const nameArgs = resume
+                        ? ['--resume', sessionId || targetName]
+                        : ['-n', targetName, ...(sessionId ? ['--session-id', sessionId] : [])];
+                    // Build --allowedTools flag from agent definition frontmatter
+                    const allowedToolsFlags = allowedTools && allowedTools.length > 0
+                        ? ['--allowedTools', ...allowedTools]
+                        : [];
+                    // ENSEMBLE_SENTINEL_FLAG carries the ensemble name into the spawned
+                    // claude.exe's CommandLine so hard-terminate can scope `destroy --all`
+                    // kills by ensemble (issue #180). See src/constants.ts for details.
+                    const spawnArgs = [
+                        '--dangerously-skip-permissions',
+                        '--dangerously-load-development-channels', 'server:agent-tempo',
+                        constants_1.ENSEMBLE_SENTINEL_FLAG, ensemble,
+                        ...nameArgs,
+                        ...agentFlags,
+                        ...allowedToolsFlags,
+                    ];
+                    const envVars = {
+                        [config_2.ENV.ENSEMBLE]: ensemble,
+                        [config_2.ENV.CONDUCTOR]: isConductor ? 'true' : '',
+                        [config_2.ENV.PLAYER_NAME]: targetName,
+                        [config_2.ENV.TEMPORAL_ADDRESS]: temporalAddress,
+                        [config_2.ENV.TEMPORAL_NAMESPACE]: temporalNamespace,
+                    };
+                    if (agentDefinition)
+                        envVars[config_2.ENV.PLAYER_TYPE] = agentDefinition;
+                    if (temporalApiKey)
+                        envVars[config_2.ENV.TEMPORAL_API_KEY] = temporalApiKey;
+                    if (temporalTlsCertPath)
+                        envVars[config_2.ENV.TEMPORAL_TLS_CERT_PATH] = temporalTlsCertPath;
+                    if (temporalTlsKeyPath)
+                        envVars[config_2.ENV.TEMPORAL_TLS_KEY_PATH] = temporalTlsKeyPath;
+                    // PR-D: forward pre-claimed attachment so the adapter renews rather than fresh-claims.
+                    if (attachmentId)
+                        envVars[config_2.ENV.ATTACHMENT_ID] = attachmentId;
+                    if (attachmentRunId)
+                        envVars[config_2.ENV.ATTACHMENT_RUN_ID] = attachmentRunId;
+                    if (adapterId)
+                        envVars[config_2.ENV.ADAPTER_ID] = adapterId;
+                    const { pid } = (0, spawn_1.spawnInTerminal)(spawnArgs, workDir, envVars, { claudeBin });
+                    log(`Spawned claude process (pid ${pid}) in ${workDir} as "${targetName}" (resume=${!!resume}${attachmentId ? `, attachmentId=${attachmentId}` : ''})`);
+                }
+                return { success: true };
+            }
+            catch (err) {
+                // #236: spawnProcess throws predominantly OS-side errors (ENOENT/EACCES
+                // on the claude binary, EAGAIN on process-table overflow). The classifier
+                // is tuned for Temporal RPC; OS errors don't match its transient
+                // signatures, so they still flow through as non-retryable — byte-for-byte
+                // behavior preservation. The upside of going through the helper: if a
+                // future OS error surfaces a transient shape we add to the classifier,
+                // spawnProcess benefits automatically.
+                classifyAndRethrow(err, `Failed to spawn process for "${targetName}"`);
+            }
+        },
+        async releasePlayer(input) {
+            const { ensemble, targetPlayerId } = input;
+            try {
+                const handle = await (0, resolve_1.resolveSession)(client, ensemble, targetPlayerId);
+                if (!handle) {
+                    throw activity_1.ApplicationFailure.nonRetryable(`No session found for "${targetPlayerId}"`);
+                }
+                // Check if the session is actually held (outbox locked)
+                const isLocked = await handle.query('outboxLocked');
+                if (!isLocked) {
+                    throw activity_1.ApplicationFailure.nonRetryable(`Cannot release "${targetPlayerId}" — session is not held (outbox not locked).`);
+                }
+                // Signal the session to release — unlocks outbox and delivers held message
+                await handle.signal('releaseHeld');
+                log(`Released held session "${targetPlayerId}"`);
+                return { success: true };
+            }
+            catch (err) {
+                // #236: transient RPC on outboxLocked query / releaseHeld signal now
+                // retries; WorkflowNotFound / not-held validation stay permanent.
+                classifyAndRethrow(err, `Release failed for "${targetPlayerId}"`);
+            }
+        },
+        /**
+         * PR-D `deliverDetach` — resolve target session and signal `requestDetach`.
+         * Thin wrapper so the `detach` tool can enqueue through the outbox instead
+         * of firing a signal directly from tool code (QA B1).
+         */
+        async deliverDetach(input) {
+            const { ensemble, targetPlayerId, reason = 'user-stop', deadlineMs = 5_000 } = input;
+            try {
+                const handle = await (0, resolve_1.resolveSession)(client, ensemble, targetPlayerId);
+                if (!handle) {
+                    throw activity_1.ApplicationFailure.nonRetryable(`No session found for "${targetPlayerId}"`);
+                }
+                const info = await handle.query(signals_1.attachmentInfoQuery);
+                if (info.phase === 'detached') {
+                    log(`Detach skipped for "${targetPlayerId}" — already detached`);
+                    return { success: true };
+                }
+                if (info.phase === 'gone') {
+                    throw activity_1.ApplicationFailure.nonRetryable(`Cannot detach "${targetPlayerId}" — session is destroyed`);
+                }
+                await handle.signal(signals_1.requestDetachSignal, { reason, deadlineMs });
+                log(`Detach signaled for "${targetPlayerId}" (deadline=${deadlineMs}ms)`);
+                return { success: true };
+            }
+            catch (err) {
+                // #140: re-throw transient RPC/network errors so the activity retry
+                // policy handles them; permanent cases (validator rejection, workflow
+                // gone, unknown) become `ApplicationFailure.nonRetryable`.
+                classifyAndRethrow(err, `Detach failed for "${targetPlayerId}"`);
+            }
+        },
+        /**
+         * PR-D `deliverDestroy` — execute `destroyUpdate` on the target and
+         * optionally notify the ensemble conductor via `receiveMessageSignal`
+         * (typed constant, not a string literal per QA B2).
+         */
+        async deliverDestroy(input) {
+            const { ensemble, targetPlayerId, reason, terminatedBy, notifyConductor = true } = input;
+            try {
+                const handle = await (0, resolve_1.resolveSession)(client, ensemble, targetPlayerId);
+                if (!handle) {
+                    throw activity_1.ApplicationFailure.nonRetryable(`No session found for "${targetPlayerId}"`);
+                }
+                await handle.executeUpdate(signals_1.destroyUpdate, {
+                    args: [{
+                            reason: reason ?? 'destroyed via destroy tool',
+                            terminatedBy,
+                        }],
+                });
+                log(`Destroyed "${targetPlayerId}"${reason ? ` (reason: ${reason})` : ''}`);
+                if (notifyConductor) {
+                    try {
+                        const condId = (0, config_1.conductorWorkflowId)(ensemble);
+                        const condHandle = client.workflow.getHandle(condId);
+                        await condHandle.signal(signals_1.receiveMessageSignal, {
+                            from: 'system',
+                            text: `Session "${targetPlayerId}" was destroyed by ${terminatedBy}${reason ? ` (reason: ${reason})` : ''}.`,
+                            responseRequested: false,
+                        });
+                    }
+                    catch {
+                        // Conductor may not exist — non-fatal.
+                    }
+                }
+                return { success: true };
+            }
+            catch (err) {
+                // #140: transient errors (network, RPC timeout) become retryable;
+                // permanent cases (WorkflowNotFound, validator rejection) stay
+                // non-retryable. Unknown errors default to non-retryable.
+                classifyAndRethrow(err, `Destroy failed for "${targetPlayerId}"`);
+            }
+        },
+        /**
+         * PR-D `deliverRestart` — owns the §8.2 restart algorithm on the target.
+         * Graceful `requestDetach` → re-query phase → `forceDetach` (if --force
+         * OR already was the TOCTOU case) → `claimAttachment` → optional context
+         * replay via `receiveMessage` → `enqueueSpawn` on the target's outbox.
+         *
+         * Mid-algorithm failures surface as ApplicationFailures and retry per the
+         * activity's policy. QA B3 — replaces the pre-PR-D tool-side
+         * `performRestart` helper so no multi-step cross-workflow mutation happens
+         * outside the outbox pattern.
+         */
+        async deliverRestart(input) {
+            const { ensemble, targetPlayerId, invokerPlayerId, force = false, host, fresh = false, contextMessages = 10, loadFromState, transcript } = input;
+            try {
+                const handle = await (0, resolve_1.resolveSession)(client, ensemble, targetPlayerId);
+                if (!handle) {
+                    throw activity_1.ApplicationFailure.nonRetryable(`No workflow for "${targetPlayerId}". Use recruit to start a fresh session.`);
+                }
+                // Step 1 — inspect phase. `gone` means the workflow COMPLETEd.
+                const info = await handle.query(signals_1.attachmentInfoQuery);
+                if (info.phase === 'gone') {
+                    throw activity_1.ApplicationFailure.nonRetryable(`"${targetPlayerId}" was destroyed. Use recruit to start a fresh session.`);
+                }
+                // Step 2 — reap current attachment.
+                if (info.phase !== 'detached' && info.phase !== 'booting') {
+                    if (info.phase === 'attached' || info.phase === 'awaiting' || info.phase === 'processing') {
+                        try {
+                            await handle.signal(signals_1.requestDetachSignal, {
+                                reason: 'restart',
+                                deadlineMs: validation_1.DEFAULT_RESTART_DETACH_DEADLINE_MS,
+                            });
+                        }
+                        catch {
+                            // Best-effort; force path handles it below.
+                        }
+                    }
+                    const info2 = await handle.query(signals_1.attachmentInfoQuery);
+                    if (info2.phase !== 'detached' && info2.phase !== 'booting') {
+                        if (!force) {
+                            const holder = info2.currentAttachment?.hostname ?? 'unknown host';
+                            throw activity_1.ApplicationFailure.nonRetryable(`"${targetPlayerId}" has a live attachment on ${holder} (phase: ${info2.phase}). ` +
+                                `Use force=true to steal the lease.`);
+                        }
+                        // #159 Gap 2: OS-level kill is owned by the `forceDetachUpdate` handler itself
+                        // — it invokes `hardTerminateAttachment` on the reaped host's per-host queue
+                        // *before* flipping workflow state. That keeps the "kill first, then state"
+                        // ordering inside the durable workflow layer where it belongs; deliverRestart
+                        // just awaits the update and surfaces retryable errors to the caller.
+                        await handle.executeUpdate(signals_1.forceDetachUpdate, {
+                            args: [{
+                                    reason: 'restart',
+                                    ...(info2.currentAttachment ? { expectedAttachmentId: info2.currentAttachment.attachmentId } : {}),
+                                    gracePeriodMs: 0,
+                                }],
+                        });
+                    }
+                }
+                // Step 3 — metadata + adapter routing.
+                const metadata = await handle.query(signals_1.getMetadataQuery);
+                // ADR 0014 PR-2 — mock adapter restart path. `mock` is dev-mode only;
+                // a metadata.agentType='mock' here implies the dev daemon previously
+                // spawned this player and is now restarting it (encore / migrate).
+                // Prod restart never lands here for `mock` because gate 3 in
+                // src/tools/recruit.ts rejected the original recruit.
+                const rawAgent = metadata.agentType;
+                // #131 / #449 Phase C — claude-api / opencode join copilot / mock
+                // as recognized sdk-class agents here so restart/encore/migrate of
+                // a headless player resolves to the right adapterId + class. Without
+                // this branch, restart falls through to 'claude' → 'interactive'
+                // and the spawn path picks the terminal Claude Code path.
+                const agentType = rawAgent === 'copilot'
+                    ? 'copilot'
+                    : rawAgent === 'mock'
+                        ? 'mock'
+                        : rawAgent === 'claude-api'
+                            ? 'claude-api'
+                            : rawAgent === 'opencode'
+                                ? 'opencode'
+                                : rawAgent === 'claude-code-headless'
+                                    ? 'claude-code-headless'
+                                    : 'claude';
+                const adapterId = metadata.adapterId
+                    || (agentType === 'copilot'
+                        ? 'copilot'
+                        : agentType === 'mock'
+                            ? 'mock'
+                            : agentType === 'claude-api'
+                                ? 'claude-api'
+                                : agentType === 'opencode'
+                                    ? 'opencode'
+                                    : agentType === 'claude-code-headless'
+                                        ? 'claude-code-headless'
+                                        : 'claude-code');
+                const adapterClass = agentType === 'claude' ? 'interactive' : 'sdk';
+                const targetHost = host ?? info.preferredHost ?? metadata.hostname;
+                // Step 4 — claim fresh attachment.
+                const token = await handle.executeUpdate(signals_1.claimAttachmentUpdate, {
+                    args: [{
+                            host: targetHost,
+                            adapterId,
+                            adapterClass,
+                            leaseMs: validation_1.DEFAULT_RESTART_LEASE_MS,
+                        }],
+                });
+                // Step 5 — context seed (saved state and/or transcript replay).
+                //
+                // #334 PR-2: `loadFromState` lets the player choose to seed the new
+                // session from a curated state slot instead of (or alongside) the
+                // existing transcript replay. The semantics matrix (design §4.4):
+                //
+                //   loadFromState set      → seed from saved state, suppress replay by default
+                //   loadFromState + 'replay' → stack: saved state first, then transcript
+                //   loadFromState set, slot empty → graceful fallback to transcript replay
+                //   loadFromState absent   → existing behaviour (replay governed by `fresh`)
+                //
+                // Backward compat is structural (no `patched()` marker — see ADR 0011
+                // §Consequences and design §7.3): old outbox entries omit
+                // `loadFromState`, `wantsState` evaluates falsy, and execution falls
+                // through to the original transcript-replay block bit-for-bit.
+                const wantsState = loadFromState !== undefined;
+                const wantsTranscriptByFlag = transcript === 'replay';
+                let saved = null;
+                if (wantsState) {
+                    const stateKey = typeof loadFromState === 'string' ? loadFromState : validation_2.PLAYER_STATE_DEFAULT_KEY;
+                    saved = await handle.query(signals_1.playerStateQuery, { key: stateKey });
+                    if (saved) {
+                        await handle.signal(signals_1.receiveMessageSignal, {
+                            from: 'self-restart',
+                            text: `🎵 **Restored state — "${stateKey}"** (saved ${saved.savedAt} by ${saved.savedBy})\n\n${saved.content}`,
+                            responseRequested: false,
+                        });
+                    }
+                    else {
+                        log(`Restart loadFromState requested for slot "${stateKey}" but slot is empty — falling back to transcript replay`);
+                        // UX-friendly fallback per design §4.4: replay the transcript as
+                        // if the caller had not passed `loadFromState`. The fall-through
+                        // below picks this up via `wantsState && !saved`.
+                    }
+                }
+                // Replay the transcript when (a) loadFromState was not requested, OR
+                // (b) caller opted into stacking via `transcript: 'replay'`, OR
+                // (c) loadFromState was requested but the slot was empty (fallback).
+                // The pre-existing `fresh` flag still wins — `fresh: true` skips
+                // replay regardless of state-seeding outcome.
+                const wantsTranscript = !wantsState || wantsTranscriptByFlag || (wantsState && !saved);
+                if (!fresh && wantsTranscript) {
+                    const [part, allMessages] = await Promise.all([
+                        handle.query(signals_1.getPartQuery),
+                        handle.query(signals_1.allMessagesQuery),
+                    ]);
+                    const recent = allMessages.slice(-contextMessages);
+                    const summary = recent.length > 0
+                        ? recent.map((m) => `[${m.from}] ${m.text.slice(0, validation_1.PREVIEW_MAX_LENGTH)}`).join('\n')
+                        : '(no recent messages)';
+                    const contextMessage = [
+                        `🎵 **Restart** — you've been revived by ${invokerPlayerId}.`,
+                        part ? `Your last status: ${part}` : '',
+                        `Recent messages (last ${recent.length}):`,
+                        summary,
+                        '',
+                        'Resume where you left off. Use `ensemble` to see who is active.',
+                    ].filter(Boolean).join('\n');
+                    await handle.signal(signals_1.receiveMessageSignal, {
+                        from: invokerPlayerId,
+                        text: contextMessage,
+                        responseRequested: false,
+                    });
+                }
+                // Step 6 — enqueue the spawn.
+                //
+                // Issue #183: Claude Code rejects `--session-id <uuid>` when a transcript
+                // already exists at `~/.claude/projects/<encoded-path>/<uuid>.jsonl`
+                // ("Session ID already in use"). A prior failed spawn can leave that
+                // file behind, wedging every subsequent `fresh` restart that reuses the
+                // stored sessionId.
+                //
+                // #306: `/restart` ALWAYS spawns a fresh Claude Code process — never
+                // `--resume <id>`. The transcript `.jsonl` for the prior `spawnSessionId`
+                // is NOT guaranteed to have been flushed to disk before the prior
+                // adapter was hard-terminated (Windows `taskkill /T /F` is synchronous
+                // and unconditional). Claude Code then errors out with "No conversation
+                // found with session ID" and the new terminal drops to shell.
+                //
+                // Context preservation is already handled by the Step 5 replay above —
+                // we re-send recent messages to the fresh session. That's authoritative;
+                // the session-id `--resume` path was only ever a bonus on top. So we
+                // mint a new UUID on every restart, persist it to metadata, and never
+                // pass `resume: true` to the spawn.
+                const spawnSessionId = crypto.randomUUID();
+                await handle.signal(signals_1.updateMetadataSignal, { sessionId: spawnSessionId });
+                // Issue #184: re-resolve on the invoker host against the session's
+                // workDir (NOT the daemon's process.cwd — daemon runs elsewhere than
+                // the session's project, so the project-tier lookup needs the session's
+                // own cwd). `nativeResolvable` means the target can `--agent <name>`
+                // from its own tier lookup; the path fallback is shipped-relative so
+                // it exists on any host with agent-tempo installed — safe cross-host.
+                const resolved = metadata.playerType
+                    ? (0, agent_types_1.resolveAgentType)(metadata.playerType, metadata.workDir)
+                    : null;
+                const { spawnEntryId } = await handle.executeUpdate(signals_1.enqueueSpawnUpdate, {
+                    args: [{
+                            host: targetHost,
+                            attachmentId: token.attachmentId,
+                            runId: token.runId,
+                            // #306: `/restart` is always a fresh spawn (see comment above).
+                            resume: false,
+                            sessionId: spawnSessionId,
+                            adapterId,
+                            // #131 Phase C — claude-api adapter model carried across restart.
+                            // Read from durable session metadata so the restarted player runs
+                            // the same model the original recruit chose. Absent for non-claude-api
+                            // sessions and for legacy claude-api sessions recruited before the
+                            // metadata.model field landed (which fall back to the env / default
+                            // chain inside the adapter).
+                            ...(metadata.model !== undefined ? { model: metadata.model } : {}),
+                            ...(resolved ? {
+                                agentDefinition: resolved.name,
+                                agentDefinitionPath: resolved.path,
+                                nativeResolvable: resolved.nativeResolvable,
+                            } : {}),
+                        }],
+                });
+                log(`Restart prepared for "${targetPlayerId}" — attachmentId=${token.attachmentId}, spawnEntryId=${spawnEntryId}, host=${targetHost}, fresh sessionId=${spawnSessionId}${fresh ? ' (context replay skipped)' : ''}`);
+                return { success: true };
+            }
+            catch (err) {
+                // #140: the §8.2 restart algorithm fires many RPCs; any of them may
+                // hit a transient network/RPC error. Those get retried. Validator
+                // rejections (e.g. claim race), workflow-gone, and unknown errors
+                // stay permanent to avoid wedging the outbox on a dead target.
+                classifyAndRethrow(err, `Restart failed for "${targetPlayerId}"`);
+            }
+        },
+        /**
+         * #159 Gap 2 — OS-level process-tree kill. Registered on the per-host task queue so
+         * it runs on the machine that actually hosts the child process. Never throws: the
+         * returned `HardTerminateResult` tells the caller what happened (strategy, PIDs,
+         * notes), which the workflow can log without blocking the state flip.
+         */
+        async hardTerminateAttachment(input) {
+            return (0, hard_terminate_1.hardTerminateAttachment)(input);
+        },
+    };
+}