claude-tempo 0.19.0 → 0.20.1

package/CLAUDE.md

@@ -20,7 +20,7 @@ src/
 ├── cli.ts             # CLI entry point (claude-tempo command)
 ├── daemon.ts          # Daemon entry point — runs Temporal workers as a detached background process
 ├── cli/
-│   ├── commands.ts    # CLI command implementations (up, start, conduct, status, stop, …)
+│   ├── commands.ts    # CLI command implementations (up, start, conduct, status, stop, upgrade, …)
 │   ├── config-command.ts # config subcommand (interactive + set/show)
 │   ├── daemon.ts      # Daemon management utilities (start, stop, status, logs, isDaemonRunning)
 │   ├── mcp.ts         # MCP server registration helpers (init, global vs project)
@@ -137,7 +137,7 @@ npm test
 - **Part**: A player's description of what it's working on
 - **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.
+- **Session status**: Each session has a status (`pending` → `active` → `stale` | `blocked`) 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. Sessions become `blocked` when they are alive (delivering messages) but have produced no response to a `responseRequested: true` message for 5+ minutes — they may be stuck or spinning. Informational messages (broadcasts, schedule-fires, heartbeats, system notifications) set `responseRequested: false` and do not trigger blocked detection. Blocked status auto-recovers to `active` on next outbound.
 - **Outbox**: Outbound requests (cue, report, stop, recruit, encore) go through the session's own workflow outbox instead of directly signaling other workflows. The workflow's dispatch loop processes entries via activities, decoupling tools from cross-workflow signaling.
 - **Encore**: Revives a `stale` player session by restarting the Claude process and reconnecting to the existing Temporal workflow, with recent message context restored. Cannot encore `active`, `pending`, or `terminated` sessions — use `cue`, wait, or `recruit` respectively.
 - **Broadcast**: Fan-out variant of `cue` — sends a message to all active players in the ensemble in a single call. Optionally filtered by player type. Skips the sender, pending sessions, and (by default) stale sessions.
@@ -146,7 +146,7 @@ npm test
 - **Player types**: Reusable agent definitions in Claude Code's standard subagent format (`.md` files with YAML frontmatter). Ensemble lineups can reference types by name via a `type` field on players. Three-tier lookup: project `.claude/agents/` → user `~/.claude/agents/` → shipped `examples/agents/`. Players know their type via workflow metadata and the `who_am_i` tool. Agent type frontmatter may include an `allowedTools` array to restrict which MCP/CLI tools the spawned session can use (e.g., `allowedTools: [Read, Glob, Grep]`). When present, the type's `allowedTools` overrides any lineup-level setting and is passed to the Claude Code session via `--allowedTools`.
 - **Agent type discovery**: The `agent_types` MCP tool and `claude-tempo agent-types` CLI command let conductors discover available player types. Shipped examples (tempo-conductor, tempo-composer, tempo-soloist, tempo-tuner, tempo-critic, tempo-roadie, tempo-improv, tempo-liner) work out of the box. Ensemble lineups: tempo-big-band (full lifecycle), tempo-dev-team (feature work), tempo-review-squad (parallel review), tempo-jam-session (exploration).
 - **Schedule**: A one-shot or recurring message delivery configured via the `schedule` tool. Backed by a durable `claudeSchedulerWorkflow` — survives restarts. Supports delay (`delay`), fixed time (`at`), recurring interval (`every`), and cron expressions (`cron`) with optional IANA timezone (`timezone`). Cron schedules use `croner` for expression parsing and next-fire computation. Managed via `schedule`, `unschedule`, and `schedules` tools.
-- **Lineup**: A YAML file defining an ensemble configuration — which players to recruit, their types, working directories, and optional startup messages. Load via `load_lineup` to bootstrap a full ensemble in one step; save via `save_lineup` to snapshot a running ensemble's state for later reuse.
+- **Lineup**: A YAML file defining an ensemble configuration — which players to recruit, their types, working directories, and optional startup messages. Load via `load_lineup` to bootstrap a full ensemble in one step; `load_lineup` resolves the lineup by name using a three-tier lookup: saved lineups → shipped examples → file path. Save via `save_lineup` to snapshot a running ensemble's state for later reuse.
 - **Quality Gate**: A named checklist of criteria a conductor tracks to verify a task is complete. Created via `quality_gate` (conductor only), evaluated via `evaluate_gate`, and listed via `gates`. Each criterion has a `pending` → `passed` | `failed` status; the gate's aggregate status is derived automatically (all passed → `passed`, any failed → `failed`, else `open`). Gates are stored in the conductor workflow and survive `continueAsNew`.
 - **Worktree**: A git worktree provisioned by the conductor for a player, giving them an isolated checkout on a separate branch. Managed via the `worktree` tool (conductor only): `create` provisions the worktree and notifies the player, `remove` cleans up after the task, `list` shows all active worktrees. Worktree assignments are stored in the conductor workflow (`WorktreeEntry` records: player, path, branch, gitRoot, createdAt, createdBy).
 - **Stage**: A fan-out/fan-in tracking primitive for the conductor. Created via `stage` (conductor only), listing via `stages`, cancelled via `cancel_stage`. Each stage tracks a set of players; when a tracked player sends a `report`, their stage status updates automatically (`waiting` → `reported` or `blocked`). When all players have reported, the conductor is notified that the stage is complete. If `failurePolicy` is `'halt'` (default), a blocker from any player fails the entire stage. Stages are stored in the conductor workflow and survive `continueAsNew`.

package/README.md

@@ -145,7 +145,8 @@ Inside the TUI, type `/help` for slash commands. Inside Claude Code, use the `en
 | `claude-tempo start [ensemble]` | Open a player session |
 | `claude-tempo conduct [ensemble]` | Start a conductor session |
 | `claude-tempo status` | Show active sessions |
-| `claude-tempo down` | Stop everything |
+| `claude-tempo stop [ensemble]` | Stop sessions (recoverable via `encore`) |
+| `claude-tempo down` | Full teardown — sessions, daemon, and Temporal |
 
 **Lineups**
 | Command | Description |
@@ -165,6 +166,7 @@ Inside the TUI, type `/help` for slash commands. Inside Claude Code, use the `en
 | Command | Description |
 |---------|-------------|
 | `claude-tempo daemon start\|stop\|status\|logs` | Manage the worker daemon |
+| `claude-tempo upgrade [version]` | Graceful self-update (stops daemon, installs, restarts) |
 | `claude-tempo config` | Configure env vars interactively |
 | `claude-tempo preflight` | Verify environment |
 

package/dist/activities/outbox.js

@@ -92,6 +92,7 @@ function createOutboxActivities(client, config) {
                 await conductorHandle.signal('receiveMessage', {
                     from: 'system',
                     text: `Session "${targetPlayerId}" was terminated by ${terminatedBy}.`,
+                    responseRequested: false,
                 });
             }
             catch {
@@ -265,7 +266,7 @@ function createOutboxActivities(client, config) {
                     'Resume where you left off. Use `ensemble` to see who is active.',
                 ].filter(Boolean).join('\n');
                 // Inject context message (status already set to pending atomically above)
-                await handle.signal('receiveMessage', { from: fromPlayerId, text: contextMessage });
+                await handle.signal('receiveMessage', { from: fromPlayerId, text: contextMessage, responseRequested: false });
                 log(`Encore prepared for "${targetPlayerId}" — status reset to pending, context injected`);
                 // Return spawn parameters from the target's metadata
                 const agentType = metadata.agentType || 'claude';

package/dist/activities/schedule-fire.js

@@ -37,6 +37,7 @@ function createScheduleActivities(client) {
                                 text,
                                 isScheduled: true,
                                 scheduleName,
+                                responseRequested: false,
                             });
                             delivered++;
                         }
@@ -67,6 +68,7 @@ function createScheduleActivities(client) {
                     text,
                     isScheduled: true,
                     scheduleName,
+                    responseRequested: false,
                 });
                 return { success: true };
             }
@@ -92,6 +94,7 @@ async function notifyFailure(client, ensemble, createdBy, scheduleName, target,
                 text: failureText,
                 isScheduled: true,
                 scheduleName,
+                responseRequested: false,
             });
             return;
         }
@@ -107,6 +110,7 @@ async function notifyFailure(client, ensemble, createdBy, scheduleName, target,
             from: 'scheduler',
             text: failureText,
             isScheduled: true,
+            responseRequested: false,
             scheduleName,
         });
     }

package/dist/cli/commands.d.ts

@@ -36,6 +36,8 @@ interface DownOpts extends CliOverrides {
     ensemble?: string;
     all: boolean;
     removeMcp: boolean;
+    keepDaemon: boolean;
+    yes: boolean;
     dir: string;
 }
 export declare function down(opts: DownOpts): Promise<void>;
@@ -77,4 +79,8 @@ interface DaemonOpts extends CliOverrides {
 export declare function daemon(opts: DaemonOpts): Promise<void>;
 export declare function help(): void;
 export declare function version(): void;
+interface UpgradeOpts extends CliOverrides {
+    version?: string;
+}
+export declare function upgrade(opts: UpgradeOpts): Promise<void>;
 export {};

package/dist/cli/commands.js

@@ -47,6 +47,8 @@ exports.ensembleCommand = ensembleCommand;
 exports.daemon = daemon;
 exports.help = help;
 exports.version = version;
+exports.upgrade = upgrade;
+const readline = __importStar(require("readline"));
 const fs_1 = require("fs");
 const path_1 = require("path");
 const child_process_1 = require("child_process");
@@ -652,59 +654,107 @@ async function up(opts) {
     let lineup;
     const lineupArg = opts.lineup;
     if (lineupArg) {
-        // Resolve by name or file path
-        let lineupPath;
-        if ((0, fs_1.existsSync)((0, path_1.resolve)(lineupArg))) {
-            // Direct file path
-            lineupPath = (0, path_1.resolve)(lineupArg);
+        try {
+            const resolution = (0, loader_1.resolveLineupPath)(lineupArg);
+            lineup = (0, loader_1.loadLineup)(resolution.path);
         }
-        else {
-            // Try saved lineups (~/.claude-tempo/ensembles/)
-            const ensemblesDir = (0, path_1.join)(config_1.CLAUDE_TEMPO_HOME, 'ensembles');
-            const savedYaml = (0, path_1.join)(ensemblesDir, `${lineupArg}.yaml`);
-            const savedYml = (0, path_1.join)(ensemblesDir, `${lineupArg}.yml`);
-            if ((0, fs_1.existsSync)(savedYaml)) {
-                lineupPath = savedYaml;
-            }
-            else if ((0, fs_1.existsSync)(savedYml)) {
-                lineupPath = savedYml;
-            }
-            else {
-                // Try shipped examples
-                const shippedPath = (0, path_1.join)(PACKAGE_ROOT, 'examples', 'ensembles', `${lineupArg}.yaml`);
-                const shippedYml = (0, path_1.join)(PACKAGE_ROOT, 'examples', 'ensembles', `${lineupArg}.yml`);
-                if ((0, fs_1.existsSync)(shippedPath)) {
-                    lineupPath = shippedPath;
-                }
-                else if ((0, fs_1.existsSync)(shippedYml)) {
-                    lineupPath = shippedYml;
-                }
-                else {
-                    out.error(`Lineup "${lineupArg}" not found as file, saved lineup, or shipped example`);
-                    const saved = (0, saver_1.listLineups)();
-                    if (saved.length)
-                        out.log(`  Saved: ${saved.map(b => b.name).join(', ')}`);
-                    const shipped = (0, fs_1.readdirSync)((0, path_1.join)(PACKAGE_ROOT, 'examples', 'ensembles')).filter(f => f.endsWith('.yaml') || f.endsWith('.yml')).map(f => f.replace(/\.ya?ml$/, ''));
-                    if (shipped.length)
-                        out.log(`  Shipped: ${shipped.join(', ')}`);
-                    process.exit(1);
-                }
-            }
+        catch (err) {
+            out.error(err.message);
+            process.exit(1);
         }
-        lineup = (0, loader_1.loadLineup)(lineupPath);
     }
     if (lineup) {
         out.check('Lineup loaded', true, lineup.name);
     }
     // Resolve conductor agent from lineup or CLI flags
     const conductorAgent = lineup?.conductor?.agent === 'copilot' ? 'copilot' : opts.agent;
-    // Step 5: Connect to Temporal and pre-create conductor workflow before spawning
+    // Step 5: Connect to Temporal and check for existing conductor
     console.log();
-    out.log(`Launching conductor in ensemble ${out.cyan(opts.ensemble)}${conductorAgent === 'copilot' ? out.dim(' (copilot)') : ''}...`);
     const connection = await (0, connection_1.createTemporalConnection)(config);
     const client = new client_1.Client({ connection, namespace: config.temporalNamespace });
-    const sessionName = opts.name || lineup?.conductor?.name || (conductorAgent === 'copilot' ? `${opts.ensemble}-conductor` : 'conductor');
     const conductorWfId = (0, config_1.conductorWorkflowId)(opts.ensemble);
+    // Check if a conductor is already running
+    try {
+        const existingHandle = client.workflow.getHandle(conductorWfId);
+        const desc = await existingHandle.describe();
+        if (desc.status.name === 'RUNNING') {
+            if (!process.stdin.isTTY) {
+                out.error(`A conductor is already running for ensemble "${opts.ensemble}".`);
+                out.log(`  Use ${out.dim('--resume')} to reconnect, or ${out.dim('claude-tempo start')} to join as a player.`);
+                process.exit(1);
+            }
+            out.warn(`A conductor is already running for ensemble "${opts.ensemble}".`);
+            console.log();
+            out.log(`  1) Join as a new player session`);
+            out.log(`  2) Reconnect to the existing conductor (--resume)`);
+            out.log(`  3) Tear down and start fresh`);
+            out.log(`  4) Cancel`);
+            console.log();
+            const choice = await new Promise((res) => {
+                const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                rl.question(`  ${out.cyan('?')} Choose an option [1-4]: `, (answer) => {
+                    rl.close();
+                    res(answer.trim());
+                });
+            });
+            switch (choice) {
+                case '1':
+                    // Join as a player — delegate to start()
+                    console.log();
+                    out.log('Joining as a player session...');
+                    await start({
+                        ensemble: opts.ensemble,
+                        conductor: false,
+                        name: opts.name,
+                        skipPreflight: true, // infrastructure already verified above
+                        agent: opts.agent,
+                        dir: process.cwd(),
+                    });
+                    return;
+                case '2':
+                    // Reconnect to existing conductor
+                    console.log();
+                    out.log('Reconnecting to existing conductor...');
+                    await start({
+                        ensemble: opts.ensemble,
+                        conductor: true,
+                        resume: true,
+                        name: opts.name,
+                        skipPreflight: true,
+                        agent: opts.agent,
+                        dir: process.cwd(),
+                    });
+                    return;
+                case '3':
+                    // Terminate existing workflows, then fall through to normal up flow
+                    console.log();
+                    try {
+                        await client.workflow.getHandle(conductorWfId).terminate('up: fresh start');
+                    }
+                    catch { /* may not exist */ }
+                    try {
+                        await client.workflow.getHandle((0, config_1.schedulerWorkflowId)(opts.ensemble)).terminate('up: fresh start');
+                    }
+                    catch { /* may not exist */ }
+                    try {
+                        await client.workflow.getHandle((0, config_1.maestroWorkflowId)(opts.ensemble)).terminate('up: fresh start');
+                    }
+                    catch { /* may not exist */ }
+                    out.success('Existing ensemble torn down');
+                    // Fall through to normal up flow below
+                    break;
+                case '4':
+                default:
+                    out.log('Cancelled.');
+                    process.exit(0);
+            }
+        }
+    }
+    catch {
+        // No existing conductor — proceed normally
+    }
+    out.log(`Launching conductor in ensemble ${out.cyan(opts.ensemble)}${conductorAgent === 'copilot' ? out.dim(' (copilot)') : ''}...`);
+    const sessionName = opts.name || lineup?.conductor?.name || (conductorAgent === 'copilot' ? `${opts.ensemble}-conductor` : 'conductor');
     // Resolve conductor agent type from lineup
     const conductorType = lineup?.conductor?.agent && lineup.conductor.agent !== 'default' && lineup.conductor.agent !== 'copilot'
         ? lineup.conductor.agent
@@ -989,6 +1039,20 @@ function parseDuration(s) {
         default: throw new Error(`Unknown duration unit: "${match[2]}"`);
     }
 }
+/** Prompt the user for y/n confirmation. Exits with code 1 in non-TTY environments. */
+async function confirmPrompt(message) {
+    if (!process.stdin.isTTY) {
+        out.error('Non-interactive environment: use --yes / -y to confirm teardown.');
+        process.exit(1);
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(`${message} [y/N] `, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase() === 'y');
+        });
+    });
+}
 async function down(opts) {
     const config = (0, config_1.getConfig)(opts);
     let ensembleName = opts.ensemble;
@@ -1017,14 +1081,42 @@ async function down(opts) {
             }
             else if (runningEnsembles.size === 1) {
                 ensembleName = [...runningEnsembles][0];
+                // Auto-detected ensemble requires confirmation unless --yes
+                if (!opts.yes) {
+                    out.heading('claude-tempo teardown');
+                    out.log(`  This will destroy ensemble ${out.bold(ensembleName)}: all sessions, daemon, and Temporal server.`);
+                    const confirmed = await confirmPrompt('Proceed?');
+                    if (!confirmed) {
+                        out.log('Aborted.');
+                        process.exit(0);
+                    }
+                }
             }
             else {
-                out.error(`Multiple ensembles running. Please specify which one to tear down:`);
-                for (const name of [...runningEnsembles].sort()) {
-                    out.log(`  - claude-tempo down ${name}`);
+                // Multiple ensembles: require confirmation or --yes for each
+                if (!opts.yes) {
+                    out.heading('claude-tempo teardown');
+                    out.log(`  Multiple ensembles running:`);
+                    for (const name of [...runningEnsembles].sort()) {
+                        out.log(`    - ${name}`);
+                    }
+                    out.log('');
+                    out.log(`  This will destroy ${out.bold('all')} of them: sessions, daemon, and Temporal server.`);
+                    const confirmed = await confirmPrompt('Proceed?');
+                    if (!confirmed) {
+                        out.log('Aborted. To tear down a specific ensemble:');
+                        for (const name of [...runningEnsembles].sort()) {
+                            out.log(`  - claude-tempo down ${name}`);
+                        }
+                        process.exit(0);
+                    }
+                    // Treat as --all since user confirmed tearing down everything
+                    opts.all = true;
+                }
+                else {
+                    // --yes with multiple ensembles: treat as --all
+                    opts.all = true;
                 }
-                out.log(`  - claude-tempo down --all`);
-                process.exit(1);
             }
         }
         catch (err) {
@@ -1132,9 +1224,13 @@ async function down(opts) {
     }
     // Step 2: Kill bridge processes via PID files
     killBridgeProcesses();
-    // Step 2.5: Stop worker daemon — only if --all or no other workflows remain
-    // hasRemainingWorkflows is only meaningful when Temporal was reachable
-    if (opts.all || (temporalUp && !hasRemainingWorkflows)) {
+    // Step 2.5: Stop worker daemon — unless --keep-daemon or other ensembles still active
+    if (opts.keepDaemon) {
+        if ((0, daemon_1.isDaemonRunning)()) {
+            out.log(`  ${out.dim('Worker daemon left running (--keep-daemon)')}`);
+        }
+    }
+    else if (opts.all || !hasRemainingWorkflows) {
         if ((0, daemon_1.stopDaemon)()) {
             out.success('Worker daemon stopped');
         }
@@ -1549,6 +1645,7 @@ async function broadcast(opts) {
             await handle.signal('receiveMessage', {
                 from: 'cli',
                 text: opts.message,
+                responseRequested: false,
             });
             sent++;
             out.log(`  ${out.green('✓')} ${target.playerId}`);
@@ -1629,7 +1726,7 @@ async function encore(opts) {
     ].filter(Boolean).join('\n');
     // Reset status and inject context message
     await targetHandle.signal('updateMetadata', { status: 'pending' });
-    await targetHandle.signal('receiveMessage', { from: 'system', text: contextMessage });
+    await targetHandle.signal('receiveMessage', { from: 'system', text: contextMessage, responseRequested: false });
     out.log(`Reviving "${opts.name}" in ${targetMeta.workDir}...`);
     // Resolve agent flags
     let agentFlags = [];
@@ -1823,7 +1920,7 @@ ${out.bold('Usage:')}
 
 ${out.bold('Commands:')}
   ${out.cyan('up')}      [ensemble]    First-time setup: start Temporal, configure MCP, launch conductor
-  ${out.cyan('down')}                  Stop Temporal, terminate sessions, remove MCP config
+  ${out.cyan('down')}    [ensemble]    Tear down everything: sessions, daemon, Temporal server, MCP config
   ${out.cyan('server')}                Start the Temporal dev server and register search attributes
   ${out.cyan('conduct')} [ensemble]    Start a conductor session (resumes existing, --replace to restart)
   ${out.cyan('start')}   [ensemble]    Start a player session
@@ -1834,6 +1931,7 @@ ${out.bold('Commands:')}
   ${out.cyan('encore')}   <name>      Revive a stale player session (reconnect with context)
   ${out.cyan('agent-types')} <sub>    Manage player type definitions (list/show/init)
   ${out.cyan('daemon')}    <sub>       Manage the worker daemon (start/stop/status/logs)
+  ${out.cyan('upgrade')}  [version]    Upgrade claude-tempo to latest (or specific version)
   ${out.cyan('config')}                Configure Temporal connection settings
   ${out.cyan('init')}                  Register MCP server globally (or --project for .mcp.json)
   ${out.cyan('preflight')}             Run preflight checks only
@@ -1853,9 +1951,11 @@ ${out.bold('Other options:')}
   --background                Run Temporal in background (server only)
   --project                   Use per-project .mcp.json instead of global (init only)
   --keep-mcp                  Don't remove MCP config (down only)
+  --keep-daemon               Don't stop the worker daemon (down only)
+  -y, --yes                   Skip confirmation prompt (down only)
   --all                       Stop all sessions (stop only)
   --lineup <name|file>         Load ensemble lineup by name or file path (up only)
-  --ensemble <name>           Target a specific ensemble (stop only)
+  --ensemble <name>           Target a specific ensemble (stop/down)
   -d, --dir <path>            Target directory (default: cwd)
 
 ${out.bold('Config command:')}
@@ -1898,3 +1998,170 @@ function version() {
         out.log('claude-tempo (unknown version)');
     }
 }
+async function upgrade(opts) {
+    const config = (0, config_1.getConfig)(opts);
+    const targetVersion = opts.version || 'latest';
+    const installSpec = targetVersion === 'latest' ? 'claude-tempo' : `claude-tempo@${targetVersion}`;
+    // Read current version
+    let currentVersion = 'unknown';
+    try {
+        const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(PACKAGE_ROOT, 'package.json'), 'utf8'));
+        currentVersion = pkg.version || 'unknown';
+    }
+    catch { /* ignore */ }
+    out.heading('claude-tempo upgrade');
+    out.log(`  Current: v${currentVersion}`);
+    out.log(`  Target:  ${targetVersion}`);
+    console.log();
+    // Check for active sessions — warn the user
+    let activeSessions = 0;
+    try {
+        const connection = await Promise.race([
+            (0, connection_1.createTemporalConnection)(config),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 3000)),
+        ]);
+        const client = new client_1.Client({ connection, namespace: config.temporalNamespace });
+        const query = 'WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"';
+        for await (const _wf of client.workflow.list({ query })) {
+            activeSessions++;
+        }
+    }
+    catch {
+        // Can't connect to Temporal — that's fine, proceed with upgrade
+    }
+    if (activeSessions > 0) {
+        out.warn(`${activeSessions} active session(s) detected. They will lose daemon connectivity during upgrade.`);
+        out.log(`  ${out.dim('Consider running: claude-tempo stop --all')}`);
+        console.log();
+    }
+    // Stop the daemon gracefully (releases .node file locks)
+    const daemonWasRunning = (0, daemon_1.isDaemonRunning)();
+    if (daemonWasRunning) {
+        out.log('Stopping daemon...');
+        (0, daemon_1.stopDaemon)();
+        // Wait for process to exit — important on Windows for file lock release
+        const deadline = Date.now() + 5000;
+        while (Date.now() < deadline && (0, daemon_1.isDaemonRunning)()) {
+            await new Promise(r => setTimeout(r, 200));
+        }
+        if ((0, daemon_1.isDaemonRunning)()) {
+            out.error('Daemon did not stop in time. Try: claude-tempo daemon stop');
+            process.exit(1);
+        }
+        out.success('Daemon stopped');
+    }
+    // Build the detached updater script.
+    // This is a self-contained Node.js script (no native module deps) that:
+    //   1. Waits for the CLI process to exit (by PID)
+    //   2. Runs npm install -g
+    //   3. Verifies the install
+    //   4. Restarts the daemon
+    const cliPid = process.pid;
+    const isWin = process.platform === 'win32';
+    const updaterScript = `
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+
+const PID = ${cliPid};
+const INSTALL_SPEC = ${JSON.stringify(installSpec)};
+const TARGET = ${JSON.stringify(targetVersion)};
+const IS_WIN = ${isWin};
+const LOG_PATH = ${JSON.stringify((0, path_1.join)(config_1.CLAUDE_TEMPO_HOME, 'upgrade.log'))};
+
+function log(msg) {
+  const line = new Date().toISOString() + ' ' + msg;
+  try { fs.appendFileSync(LOG_PATH, line + '\\n'); } catch {}
+  console.log(msg);
+}
+
+function isPidAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch { return false; }
+}
+
+async function main() {
+  // Wait for CLI process to exit (up to 10s)
+  log('Waiting for CLI process (pid ' + PID + ') to exit...');
+  const deadline = Date.now() + 10000;
+  while (Date.now() < deadline && isPidAlive(PID)) {
+    await new Promise(r => setTimeout(r, 300));
+  }
+  if (isPidAlive(PID)) {
+    log('WARNING: CLI process still alive after 10s, proceeding anyway');
+  }
+
+  // Run npm install -g
+  log('Installing ' + INSTALL_SPEC + '...');
+  try {
+    const npmCmd = IS_WIN ? 'npm.cmd' : 'npm';
+    execFileSync(npmCmd, ['install', '-g', INSTALL_SPEC], {
+      stdio: 'inherit',
+      timeout: 120000,
+    });
+    log('Install completed');
+  } catch (err) {
+    log('Install FAILED: ' + err.message);
+    log('Recovery: npm install -g ' + INSTALL_SPEC);
+    process.exit(1);
+  }
+
+  // Verify installation
+  try {
+    const tempoCmd = IS_WIN ? 'claude-tempo.cmd' : 'claude-tempo';
+    const ver = execFileSync(tempoCmd, ['--version'], {
+      encoding: 'utf8',
+      timeout: 10000,
+    }).trim();
+    log('Verified: ' + ver);
+  } catch (err) {
+    log('WARNING: Could not verify installation: ' + err.message);
+    log('Recovery: npm install -g claude-tempo');
+  }
+
+  // Restart the daemon
+  log('Restarting daemon...');
+  try {
+    const tempoCmd = IS_WIN ? 'claude-tempo.cmd' : 'claude-tempo';
+    execFileSync(tempoCmd, ['daemon', 'start'], {
+      stdio: 'inherit',
+      timeout: 30000,
+    });
+    log('Daemon restarted');
+  } catch (err) {
+    log('WARNING: Daemon restart failed: ' + err.message);
+    log('Run manually: claude-tempo daemon start');
+  }
+
+  log('Upgrade complete!');
+}
+
+main().catch(err => {
+  log('Upgrade failed: ' + err.message);
+  process.exit(1);
+});
+`.trim();
+    // Clear previous upgrade log before spawning
+    const logPath = (0, path_1.join)(config_1.CLAUDE_TEMPO_HOME, 'upgrade.log');
+    try {
+        (0, fs_1.writeFileSync)(logPath, '');
+    }
+    catch { /* ignore */ }
+    // Spawn the updater as a detached child process
+    out.log(`Spawning upgrade process for ${out.cyan(installSpec)}...`);
+    const child = (0, child_process_1.spawn)(process.execPath, ['-e', updaterScript], {
+        detached: true,
+        stdio: 'ignore',
+        env: { ...process.env },
+    });
+    child.unref();
+    console.log();
+    out.success('Upgrade started in background');
+    out.log(`  ${out.dim('Monitor progress: ')}`);
+    if (isWin) {
+        out.log(`    ${out.dim('powershell Get-Content -Wait "' + logPath + '"')}`);
+    }
+    else {
+        out.log(`    ${out.dim('tail -f ' + logPath)}`);
+    }
+    out.log(`  ${out.dim('If it fails, run manually: npm install -g ' + installSpec)}`);
+}

package/dist/cli.js

@@ -47,6 +47,8 @@ function parseArgs(argv) {
         skipPreflight: false,
         background: false,
         keepMcp: false,
+        keepDaemon: false,
+        yes: false,
         all: false,
         project: false,
         replace: false,
@@ -89,6 +91,12 @@ function parseArgs(argv) {
         else if (arg === '--keep-mcp') {
             result.keepMcp = true;
         }
+        else if (arg === '--keep-daemon') {
+            result.keepDaemon = true;
+        }
+        else if (arg === '--yes' || arg === '-y') {
+            result.yes = true;
+        }
         else if (arg === '--all') {
             result.all = true;
         }
@@ -208,6 +216,8 @@ async function main() {
                 ensemble: args.ensemble || args.positional[1] || process.env[config_1.ENV.ENSEMBLE],
                 all: args.all,
                 removeMcp: !args.keepMcp,
+                keepDaemon: args.keepDaemon,
+                yes: args.yes,
                 dir: args.dir,
                 ...overrides,
             });
@@ -297,6 +307,12 @@ async function main() {
             await runTui({ config, ensemble });
             break;
         }
+        case 'upgrade':
+            await (0, commands_1.upgrade)({
+                version: args.positional[1], // e.g. "0.20.0" or "latest" or undefined
+                ...overrides,
+            });
+            break;
         case 'version':
             (0, commands_1.version)();
             break;

package/dist/ensemble/loader.d.ts

@@ -1,4 +1,13 @@
 import { EnsembleLineup } from './schema';
+export interface LineupResolution {
+    path: string;
+    source: 'saved' | 'shipped' | 'file';
+}
+/**
+ * Resolve a lineup name or file path to an absolute file path.
+ * Resolution order: saved lineups → shipped examples → direct file path → error.
+ */
+export declare function resolveLineupPath(nameOrPath: string): LineupResolution;
 /**
  * Load and validate an ensemble lineup from a YAML file.
  */