claude-tempo 0.7.0 → 0.8.0

package/CLAUDE.md

@@ -30,10 +30,11 @@ src/
 │   ├── listen.ts      # Manual message check
 │   ├── recruit.ts     # Spawn new session
 │   ├── report.ts      # Report to conductor
-│   ├── terminate.ts   # Terminate a session
+│   ├── stop.ts        # Stop a session
 │   └── helpers.ts     # Zod/MCP tool registration wrapper
 ├── types.ts           # Shared type definitions
 ├── channel.ts         # Claude channel notification helper
+├── git-info.ts        # Git repository detection helper
 └── config.ts          # Env var handling
 ```
 
@@ -66,8 +67,9 @@ npm test
 - **Ensemble**: The set of all active players, namespaced by `CLAUDE_TEMPO_ENSEMBLE`
 - **Cue**: A message sent to a player by name via Temporal signal
 - **Part**: A player's description of what it's working on
-- **Recruit**: Spawning a new Claude Code session as a player
+- **Recruit**: Spawning a new Claude Code session as a player. The workflow is pre-created with the initial message before the process spawns, ensuring reliable delivery.
 - **set_name**: Players start with a random hex ID; `set_name` updates the `ClaudeTempoPlayerId` search attribute to a human-readable name
+- **Session status**: Each session has a status (`pending` → `active` → `stale`) tracked via `ClaudeTempoStatus` search attribute. Pre-created workflows start as `pending`, transition to `active` when the process connects, and become `stale` if messages go undelivered for 3+ minutes.
 
 ## Dashboard
 

package/README.md

@@ -1,6 +1,13 @@
-# claude-tempo
-
-Multi-session [Claude Code](https://claude.ai/code) coordination via [Temporal](https://temporal.io).
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="assets/logo-light.svg">
+    <img alt="claude-tempo" src="assets/logo-light.svg" height="140">
+  </picture>
+</p>
+<p align="center">
+  Multi-session <a href="https://claude.ai/code">Claude Code</a> coordination via <a href="https://temporal.io">Temporal</a>.
+</p>
 
 Multiple Claude Code sessions discover each other, exchange messages in real time, and coordinate work — across machines, not just localhost.
 
@@ -174,7 +181,7 @@ Ensemble: myband
     Building the REST endpoints
     /Users/me/projects/app  feat/api  my-machine.local
 
-  bob
+  bob (pending)
     Working on the dashboard
     /Users/me/projects/app  feat/ui  my-machine.local
 
@@ -210,7 +217,7 @@ These tools are available inside Claude Code sessions connected to claude-tempo:
 | `listen` | Manually check for pending messages. |
 | `recruit` | Spawn a new Claude Code session in a directory. Can recruit a conductor with `conductor: true`. |
 | `report` | Send updates to the conductor. No-op if no conductor exists. |
-| `terminate` | Terminate a player session by name. |
+| `stop` | Stop a player session by name. |
 | `schedule` | Create a one-shot or recurring schedule to cue a player. |
 | `unschedule` | Cancel a named schedule. |
 | `schedules` | List all active schedules. |
@@ -398,6 +405,23 @@ Sessions start with a random 8-character hex ID. Set a name at launch with `-n`
 - Names must contain only letters, numbers, hyphens, and underscores
 - The name "conductor" is reserved for conductor sessions
 
+### Session status lifecycle
+
+Each session has a status that tracks its connection state:
+
+| Status | Meaning |
+|--------|---------|
+| `pending` | Workflow created by `recruit`, but the Claude Code process hasn't connected yet |
+| `active` | Session is running and responsive |
+| `stale` | Messages have gone undelivered for 3+ minutes — the session is likely disconnected |
+
+Status transitions:
+- **`pending` → `active`** — when the spawned session connects and sends its `updateMetadata` signal
+- **`active` → `stale`** — when undelivered messages exceed the stale threshold (3 minutes)
+- Any status → **terminated** — on graceful shutdown or `stop`
+
+`claude-tempo status` shows `(pending)` and `(stale)` indicators next to player names. The `ClaudeTempoStatus` search attribute is also set, so you can filter sessions by status in the Temporal UI (e.g., `ClaudeTempoStatus = "stale"`).
+
 ### Terminal support
 
 `recruit` and the CLI detect your terminal automatically:
@@ -409,10 +433,13 @@ Sessions start with a random 8-character hex ID. Set a name at launch with `-n`
 | Terminal.app | ✓ | — | — |
 | gnome-terminal | — | ✓ | — |
 | konsole / xterm | — | ✓ | — |
+| Windows Terminal | — | — | ✓ (tabs) |
 | cmd.exe / PowerShell | — | — | ✓ |
 
 macOS terminals preserve the full shell environment (fish, zsh, bash) including node version managers (fnm, nvm).
 
+Windows Terminal is detected automatically via the `WT_SESSION` environment variable. When running inside Windows Terminal, recruited sessions open as new tabs (with the player name as the tab title) instead of separate cmd.exe windows.
+
 ## Configuration
 
 Run `claude-tempo config` to save Temporal connection settings so you don't need flags or env vars every time:

package/dist/cli/commands.js

@@ -97,7 +97,7 @@ async function start(opts) {
                 if (opts.replace) {
                     out.log(`Stopping existing conductor for ensemble "${opts.ensemble}"...`);
                     try {
-                        await handle.signal(signals_1.shutdownSignal);
+                        await handle.signal(signals_1.updateMetadataSignal, { status: 'terminated' });
                         // Wait briefly for graceful shutdown
                         for (let i = 0; i < 10; i++) {
                             await new Promise(r => setTimeout(r, 500));
@@ -228,6 +228,7 @@ async function status(opts) {
                 host: meta.hostname || '',
                 conductor: meta.isConductor || false,
                 agentType: meta.agentType || 'claude',
+                status: meta.status || 'active',
             });
         }
         catch {
@@ -280,8 +281,11 @@ async function status(opts) {
         for (const s of members) {
             const role = s.conductor ? out.yellow(' (conductor)') : '';
             const agent = s.agentType === 'copilot' ? out.dim(' [copilot]') : '';
+            const statusLabel = s.status === 'stale' ? out.yellow(' (stale)')
+                : s.status === 'pending' ? out.dim(' (pending)')
+                    : '';
             const name = out.bold(s.name);
-            out.log(`  ${name}${role}${agent}`);
+            out.log(`  ${name}${role}${statusLabel}${agent}`);
             if (s.part)
                 out.log(`    ${out.dim(s.part)}`);
             const details = [s.workDir, s.branch, s.host].filter(Boolean).join('  ');
@@ -382,6 +386,7 @@ const SEARCH_ATTRIBUTES = [
     { name: 'ClaudeTempoGitRoot', type: 'Keyword' },
     { name: 'ClaudeTempoEnsemble', type: 'Keyword' },
     { name: 'ClaudeTempoPlayerId', type: 'Keyword' },
+    { name: 'ClaudeTempoStatus', type: 'Keyword' },
 ];
 function isTemporalReachable(config) {
     return (0, connection_1.createTemporalConnection)(config)
@@ -926,7 +931,7 @@ async function stop(opts) {
                         continue;
                     }
                 }
-                await handle.signal(signals_1.shutdownSignal);
+                await handle.signal(signals_1.updateMetadataSignal, { status: 'terminated' });
                 stopped++;
                 out.log(`  ${out.dim('stopped')} ${wf.workflowId}`);
             }
@@ -986,9 +991,9 @@ async function stopByName(client, name, config, ensemble) {
                 // No conductor or conductor not running — fine
             }
         }
-        // Send shutdown signal (graceful)
+        // Send termination status update (graceful)
         try {
-            await handle.signal(signals_1.shutdownSignal);
+            await handle.signal(signals_1.updateMetadataSignal, { status: 'terminated' });
             out.success(`Stopped "${name}"`);
         }
         catch {

package/dist/copilot-bridge.js

@@ -179,7 +179,7 @@ async function main() {
                 `- listen: Check for pending messages\n` +
                 `- recruit: Spawn a new player session\n` +
                 `- report: Report to the conductor\n` +
-                `- terminate: Terminate a session\n\n` +
+                `- stop: Stop a session\n\n` +
                 `When you receive a message from another session, treat it like a coworker asking for help — respond promptly using your MCP tools.`,
         },
         excludedTools: ['write_powershell', 'read_powershell', 'list_powershell'],
@@ -391,7 +391,7 @@ async function main() {
         polling = false;
         clearInterval(interval);
         try {
-            await handle.signal('shutdown');
+            await handle.signal('updateMetadata', { status: 'terminated', terminatedBy: 'system' });
         }
         catch {
             // workflow may already be gone

package/dist/git-info.d.ts

@@ -0,0 +1,4 @@
+export declare function getGitInfo(workDir: string): {
+    gitRoot?: string;
+    gitBranch?: string;
+};

package/dist/git-info.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGitInfo = getGitInfo;
+const child_process_1 = require("child_process");
+function getGitInfo(workDir) {
+    try {
+        const gitRoot = (0, child_process_1.execSync)('git rev-parse --show-toplevel', {
+            cwd: workDir,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        let gitBranch;
+        try {
+            gitBranch = (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD', {
+                cwd: workDir,
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+        }
+        catch {
+            // not on a branch
+        }
+        return { gitRoot, gitBranch };
+    }
+    catch {
+        return {};
+    }
+}

package/dist/server.js

@@ -37,20 +37,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const crypto = __importStar(require("crypto"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
-const child_process_1 = require("child_process");
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const client_1 = require("@temporalio/client");
 const config_1 = require("./config");
 const connection_1 = require("./connection");
 const worker_1 = require("./worker");
+const git_info_1 = require("./git-info");
 const ensemble_1 = require("./tools/ensemble");
 const cue_1 = require("./tools/cue");
 const set_part_1 = require("./tools/set-part");
 const listen_1 = require("./tools/listen");
 const recruit_1 = require("./tools/recruit");
 const report_1 = require("./tools/report");
-const terminate_1 = require("./tools/terminate");
+const stop_1 = require("./tools/stop");
 const set_name_1 = require("./tools/set-name");
 const schedule_1 = require("./tools/schedule");
 const unschedule_1 = require("./tools/unschedule");
@@ -59,30 +59,6 @@ const save_ensemble_1 = require("./tools/save-ensemble");
 const load_ensemble_1 = require("./tools/load-ensemble");
 const channel_1 = require("./channel");
 const log = (...args) => console.error('[claude-tempo]', ...args);
-function getGitInfo(workDir) {
-    try {
-        const gitRoot = (0, child_process_1.execSync)('git rev-parse --show-toplevel', {
-            cwd: workDir,
-            encoding: 'utf-8',
-            stdio: ['pipe', 'pipe', 'pipe'],
-        }).trim();
-        let gitBranch;
-        try {
-            gitBranch = (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD', {
-                cwd: workDir,
-                encoding: 'utf-8',
-                stdio: ['pipe', 'pipe', 'pipe'],
-            }).trim();
-        }
-        catch {
-            // not on a branch
-        }
-        return { gitRoot, gitBranch };
-    }
-    catch {
-        return {};
-    }
-}
 async function main() {
     // Only activate when explicitly opted in via CLAUDE_TEMPO_ENSEMBLE
     if (!process.env[config_1.ENV.ENSEMBLE]) {
@@ -104,7 +80,7 @@ async function main() {
     const getPlayerId = () => playerId;
     const setPlayerId = (id) => { playerId = id; };
     const workDir = process.cwd();
-    const { gitRoot, gitBranch } = getGitInfo(workDir);
+    const { gitRoot, gitBranch } = (0, git_info_1.getGitInfo)(workDir);
     log(`Starting ${isConductor ? 'conductor' : `peer ${playerId}`} in ${workDir}`);
     // Connect Temporal client
     const connection = await (0, connection_1.createTemporalConnection)(config);
@@ -142,7 +118,7 @@ async function main() {
         taskQueue: config.taskQueue,
         args: [sessionInput],
         workflowIdConflictPolicy: client_1.WorkflowIdConflictPolicy.USE_EXISTING,
-        // No execution timeout — workflows live until shutdown signal or stale detection.
+        // No execution timeout — workflows live until terminated status or stale detection.
         searchAttributes: {
             ...(gitRoot ? { ClaudeTempoGitRoot: [gitRoot] } : {}),
             ClaudeTempoHostname: [os.hostname()],
@@ -151,6 +127,35 @@ async function main() {
         },
     });
     log(`Workflow ${workflowId} started (or reconnected)`);
+    // Watch for workflow completion — exit the process when the workflow ends
+    // (e.g., via stop tool setting status to 'terminated')
+    handle.result().then(() => {
+        log('Workflow completed — shutting down');
+        stopPoller();
+        worker.shutdown();
+        workerRunPromise.catch(() => { }).then(() => process.exit(0));
+    }).catch((err) => {
+        // Only exit on workflow-level errors (cancelled, failed), not transient connection errors
+        const name = err?.name || '';
+        if (name.includes('WorkflowFailed') || name.includes('WorkflowCancelled') || name.includes('WorkflowNotFound')) {
+            log('Workflow ended unexpectedly — shutting down');
+            stopPoller();
+            worker.shutdown();
+            workerRunPromise.catch(() => { }).then(() => process.exit(1));
+        }
+        else {
+            log('Transient error watching workflow result:', err?.message || err);
+        }
+    });
+    // If the workflow was pre-created by a recruiter, update it with real metadata
+    // and mark the session as active now that it's connected.
+    await handle.signal('updateMetadata', {
+        hostname: os.hostname(),
+        gitRoot,
+        gitBranch,
+        status: 'active',
+        enableStaleDetection: true,
+    });
     // If there's a conductor running, announce ourselves
     if (!isConductor) {
         try {
@@ -193,7 +198,7 @@ async function main() {
     (0, listen_1.registerListenTool)(mcpServer, handle);
     (0, recruit_1.registerRecruitTool)(mcpServer, client, config, getPlayerId, isBridgeMode ? 'copilot' : 'claude');
     (0, report_1.registerReportTool)(mcpServer, client, config, getPlayerId);
-    (0, terminate_1.registerTerminateTool)(mcpServer, client, config, getPlayerId);
+    (0, stop_1.registerStopTool)(mcpServer, client, config, getPlayerId);
     (0, schedule_1.registerScheduleTool)(mcpServer, client, config, getPlayerId);
     (0, unschedule_1.registerUnscheduleTool)(mcpServer, client, config);
     (0, schedules_1.registerSchedulesTool)(mcpServer, client, config);
@@ -236,15 +241,10 @@ async function main() {
         log('Shutting down...');
         stopPoller();
         try {
-            await handle.signal('shutdown');
+            await handle.signal('updateMetadata', { status: 'terminated', terminatedBy: 'system' });
         }
         catch {
-            try {
-                await handle.cancel();
-            }
-            catch {
-                // workflow may already be gone
-            }
+            // workflow may already be gone
         }
         worker.shutdown();
         await workerRunPromise.catch(() => { });

package/dist/spawn.js

@@ -176,8 +176,43 @@ function spawnInTerminal(claudeArgs, workDir, envVars) {
         return { pid: child.pid };
     }
     if (process.platform === 'win32') {
-        // Use 'start' to open a visible terminal window, and pass the full
-        // command as a single string to avoid DEP0190 deprecation warning
+        // Detect Windows Terminal: WT_SESSION env var is set when running inside it.
+        // wt.exe is a UWP app execution alias that Node.js can't resolve directly,
+        // but `cmd.exe /c start "" wt.exe ...` works through the Windows shell.
+        const hasWt = Boolean(process.env.WT_SESSION);
+        if (hasWt) {
+            // Extract player name from claudeArgs (-n <name>) for tab title
+            const nameIdx = claudeArgs.indexOf('-n');
+            const tabTitle = nameIdx !== -1 && nameIdx + 1 < claudeArgs.length
+                ? claudeArgs[nameIdx + 1]
+                : 'claude-tempo';
+            // Build inline env var assignments for cmd /c since wt.exe spawns
+            // a new process that won't inherit our env.
+            // Escape values for cmd.exe: wrap in quotes and escape inner special chars.
+            const cmdEscape = (s) => s.replace(/([&|<>^"%])/g, '^$1');
+            const setCmds = Object.entries(envVars)
+                .map(([k, v]) => `set "${k}=${cmdEscape(v)}"`)
+                .join(' && ');
+            const claudeCmd = `${cmdEscape(claudeBin)} ${claudeArgs.map(a => `"${cmdEscape(a)}"`).join(' ')}`;
+            const innerCmd = setCmds
+                ? `${setCmds} && ${claudeCmd}`
+                : claudeCmd;
+            // Use `cmd.exe /c start "" wt.exe ...` to resolve the UWP app alias
+            const child = (0, child_process_1.spawn)('cmd.exe', [
+                '/c', 'start', '',
+                'wt.exe', '-w', '0',
+                'new-tab',
+                '--title', tabTitle,
+                '-d', workDir,
+                'cmd', '/k', innerCmd,
+            ], {
+                detached: true,
+                stdio: 'ignore',
+            });
+            child.unref();
+            return { pid: child.pid };
+        }
+        // Fallback: open a new cmd.exe window
         const child = (0, child_process_1.spawn)('cmd.exe', ['/c', 'start', '""', claudeBin, ...claudeArgs], {
             cwd: workDir,
             detached: true,

package/dist/tools/ensemble.js

@@ -74,6 +74,7 @@ function registerEnsembleTool(server, client, config, getPlayerId, ownWorkflowId
                         gitBranch: metadata.gitBranch,
                         isConductor: metadata.isConductor,
                         agentType: metadata.agentType || 'claude',
+                        status: metadata.status,
                         isYou: metadata.playerId === getPlayerId(),
                     });
                 }
@@ -98,6 +99,8 @@ function registerEnsembleTool(server, client, config, getPlayerId, ownWorkflowId
                 p.isYou ? '(you)' : '',
                 p.isConductor ? '(conductor)' : '',
                 p.agentType === 'copilot' ? '[copilot]' : '',
+                p.status === 'stale' ? '(stale)' : '',
+                p.status === 'pending' ? '(pending)' : '',
             ].filter(Boolean).join(' ');
             return [
                 `**${p.playerId}** ${tags}`.trim(),

package/dist/tools/recruit.js

@@ -1,8 +1,44 @@
 "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;
+const os = __importStar(require("os"));
 const zod_1 = require("zod");
+const client_1 = require("@temporalio/client");
 const config_1 = require("../config");
+const git_info_1 = require("../git-info");
 const spawn_1 = require("../spawn");
 const resolve_1 = require("./resolve");
 const helpers_1 = require("./helpers");
@@ -57,7 +93,7 @@ function registerRecruitTool(server, client, config, getPlayerId, ownAgentType =
                         return {
                             content: [{
                                     type: 'text',
-                                    text: `A conductor is already running in ensemble "${config.ensemble}". Use \`claude-tempo conduct --replace\` from the CLI to replace it, or \`terminate\` it first.`,
+                                    text: `A conductor is already running in ensemble "${config.ensemble}". Use \`claude-tempo conduct --replace\` from the CLI to replace it, or \`stop\` it first.`,
                                 }],
                             isError: true,
                         };
@@ -73,17 +109,53 @@ function registerRecruitTool(server, client, config, getPlayerId, ownAgentType =
                 return {
                     content: [{
                             type: 'text',
-                            text: `Session **${name}** is already active. Use \`cue\` to send it a message, or \`terminate\` it first.`,
+                            text: `Session **${name}** is already active. Use \`cue\` to send it a message, or \`stop\` it first.`,
                         }],
                     isError: true,
                 };
             }
-            // Record existing workflows so we can find the new one
-            const existingIds = new Set();
-            const listQuery = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"`;
-            for await (const wf of client.workflow.list({ query: listQuery })) {
-                existingIds.add(wf.workflowId);
-            }
+            // Pre-create the Temporal workflow so the initial message is already loaded
+            const workflowId = isConductor
+                ? (0, config_1.conductorWorkflowId)(config.ensemble)
+                : (0, config_1.sessionWorkflowId)(config.ensemble, name);
+            const { gitRoot, gitBranch } = (0, git_info_1.getGitInfo)(workDir);
+            const sessionInput = {
+                metadata: {
+                    playerId: name,
+                    ensemble: config.ensemble,
+                    hostname: os.hostname(),
+                    workDir,
+                    gitRoot,
+                    gitBranch,
+                    isConductor,
+                    agentType: agent,
+                    status: 'pending',
+                },
+                autoSummary: `Session in ${require('path').basename(workDir)}`,
+                disableStaleDetection: true,
+                ...(initialMessage ? {
+                    messages: [{
+                            id: require('crypto').randomUUID(),
+                            from: getPlayerId(),
+                            text: initialMessage,
+                            timestamp: new Date().toISOString(),
+                            delivered: false,
+                        }],
+                } : {}),
+            };
+            await client.workflow.start('claudeSessionWorkflow', {
+                workflowId,
+                taskQueue: config.taskQueue,
+                args: [sessionInput],
+                workflowIdConflictPolicy: client_1.WorkflowIdConflictPolicy.USE_EXISTING,
+                searchAttributes: {
+                    ...(gitRoot ? { ClaudeTempoGitRoot: [gitRoot] } : {}),
+                    ClaudeTempoHostname: [os.hostname()],
+                    ClaudeTempoEnsemble: [config.ensemble],
+                    ClaudeTempoPlayerId: [name],
+                },
+            });
+            log(`Pre-created workflow ${workflowId} for recruit "${name}"`);
             // Spawn the session using the selected backend
             if (agent === 'copilot') {
                 const { pid } = (0, spawn_1.spawnCopilotBridge)({
@@ -122,42 +194,26 @@ function registerRecruitTool(server, client, config, getPlayerId, ownAgentType =
                 const { pid } = (0, spawn_1.spawnInTerminal)(spawnArgs, workDir, envVars);
                 log(`Spawned claude process (pid ${pid}) in ${workDir} as "${name}"`);
             }
-            // Poll for the new workflow to appear (up to ~15s)
-            let newWorkflowId = null;
-            for (let attempt = 0; attempt < 30; attempt++) {
+            // Brief poll (5s) to confirm the session connected, but don't fail if it hasn't
+            const handle = client.workflow.getHandle(workflowId);
+            let confirmed = false;
+            for (let attempt = 0; attempt < 10; attempt++) {
                 await sleep(500);
-                for await (const wf of client.workflow.list({ query: listQuery })) {
-                    if (!existingIds.has(wf.workflowId)) {
-                        newWorkflowId = wf.workflowId;
+                try {
+                    const desc = await handle.describe();
+                    if (desc.status.name === 'RUNNING') {
+                        confirmed = true;
                         break;
                     }
                 }
-                if (newWorkflowId)
-                    break;
-            }
-            if (!newWorkflowId) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `Session "${name}" spawned but did not register within 15 seconds. It may still be starting up. Check \`ensemble\` shortly.`,
-                        }],
-                };
-            }
-            const newHandle = client.workflow.getHandle(newWorkflowId);
-            // Name is already set via CLAUDE_TEMPO_PLAYER_NAME env var at startup,
-            // so we only need to send the initial task message if provided.
-            // (Previously we sent a set_name instruction here, but that was redundant
-            // and could cause confusion if the LLM renamed itself incorrectly.)
-            if (initialMessage) {
-                await newHandle.signal('receiveMessage', {
-                    from: getPlayerId(),
-                    text: initialMessage,
-                });
+                catch { /* not ready yet */ }
             }
             return {
                 content: [{
                         type: 'text',
-                        text: `Recruited session **${name}** in ${workDir}. It will set its name shortly.${initialMessage ? ' Initial task sent.' : ''}`,
+                        text: confirmed
+                            ? `Recruited session **${name}** in ${workDir}. Workflow running.${initialMessage ? ' Initial task pre-loaded.' : ''}`
+                            : `Recruited session **${name}** in ${workDir}. Workflow pre-created, session still starting up.${initialMessage ? ' Initial task pre-loaded.' : ''}`,
                     }],
             };
         }

package/dist/tools/{terminate.d.ts → stop.d.ts}

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

package/dist/tools/stop.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerStopTool = registerStopTool;
+const zod_1 = require("zod");
+const config_1 = require("../config");
+const resolve_1 = require("./resolve");
+const helpers_1 = require("./helpers");
+function registerStopTool(server, client, config, getPlayerId) {
+    (0, helpers_1.defineTool)(server, 'stop', 'Stop a player session by name. Signals termination and the session exits gracefully.', {
+        playerId: zod_1.z.string().describe('The player name of the session to stop'),
+    }, async (args) => {
+        const { playerId } = args;
+        if (playerId === getPlayerId()) {
+            return {
+                content: [{ type: 'text', text: 'Cannot stop your own session.' }],
+                isError: true,
+            };
+        }
+        try {
+            const handle = await (0, resolve_1.resolveSession)(client, config.ensemble, playerId);
+            if (!handle) {
+                return {
+                    content: [{ type: 'text', text: `No active session found with name "${playerId}".` }],
+                    isError: true,
+                };
+            }
+            // Notify the conductor before stopping (matches CLI stop behavior)
+            try {
+                const conductorHandle = client.workflow.getHandle((0, config_1.conductorWorkflowId)(config.ensemble));
+                await conductorHandle.signal('receiveMessage', {
+                    from: getPlayerId(),
+                    text: `Stopping session **${playerId}**.`,
+                });
+            }
+            catch {
+                // No conductor running — that's fine
+            }
+            await handle.signal('updateMetadata', { status: 'terminated', terminatedBy: getPlayerId() });
+            return {
+                content: [{ type: 'text', text: `Stop signal sent to **${playerId}**. The session will exit gracefully.` }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: `Failed to stop: ${err}` }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 export type AgentType = 'claude' | 'copilot';
+export type SessionStatus = 'active' | 'stale' | 'pending' | 'terminated';
 export interface SessionMetadata {
     playerId: string;
     ensemble: string;
@@ -8,6 +9,7 @@ export interface SessionMetadata {
     gitBranch?: string;
     isConductor: boolean;
     agentType?: AgentType;
+    status?: SessionStatus;
 }
 export interface SessionInput {
     metadata: SessionMetadata;