claude-tempo 0.13.1 → 0.14.0

package/dist/cli/commands.d.ts

@@ -32,6 +32,8 @@ interface UpOpts extends CliOverrides {
 }
 export declare function up(opts: UpOpts): Promise<void>;
 interface DownOpts extends CliOverrides {
+    ensemble: string;
+    all: boolean;
     removeMcp: boolean;
     dir: string;
 }

package/dist/cli/commands.js

@@ -893,16 +893,26 @@ function parseDuration(s) {
 }
 async function down(opts) {
     const config = (0, config_1.getConfig)(opts);
+    const ensembleName = opts.ensemble;
+    // Validate ensemble name before interpolating into query strings
+    const nameErr = (0, validation_1.validateEnsembleName)(ensembleName);
+    if (nameErr) {
+        out.error(nameErr);
+        process.exit(1);
+    }
     out.heading('claude-tempo teardown');
-    // Step 1: Terminate all active workflows
+    out.log(`  Ensemble: ${out.bold(ensembleName)}${opts.all ? ' (--all: will also stop Temporal server)' : ''}`);
+    // Step 1: Terminate workflows for the target ensemble
     const temporalUp = await isTemporalReachable(config);
+    let hasRemainingWorkflows = false;
     if (temporalUp) {
         try {
             const connection = await (0, connection_1.createTemporalConnection)(config);
             const client = new client_1.Client({ connection, namespace: config.temporalNamespace });
-            const query = 'WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"';
+            // Terminate session workflows scoped to this ensemble
+            const sessionQuery = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running" AND ClaudeTempoEnsemble = "${ensembleName}"`;
             let terminated = 0;
-            for await (const wf of client.workflow.list({ query })) {
+            for await (const wf of client.workflow.list({ query: sessionQuery })) {
                 try {
                     const handle = client.workflow.getHandle(wf.workflowId);
                     await handle.terminate('claude-tempo down');
@@ -910,12 +920,25 @@ async function down(opts) {
                 }
                 catch { /* already closed */ }
             }
+            // Also terminate the ensemble's scheduler workflow
+            try {
+                const schedulerHandle = client.workflow.getHandle((0, config_1.schedulerWorkflowId)(ensembleName));
+                await schedulerHandle.terminate('claude-tempo down');
+                terminated++;
+            }
+            catch { /* no scheduler or already closed */ }
+            // Check if other workflows still running (to decide whether to kill Temporal)
+            const allRunningQuery = 'ExecutionStatus = "Running"';
+            for await (const _ of client.workflow.list({ query: allRunningQuery })) {
+                hasRemainingWorkflows = true;
+                break;
+            }
             await connection.close();
             if (terminated > 0) {
-                out.success(`Terminated ${terminated} active session${terminated !== 1 ? 's' : ''}`);
+                out.success(`Terminated ${terminated} workflow${terminated !== 1 ? 's' : ''} in ensemble "${ensembleName}"`);
             }
             else {
-                out.log(`  ${out.dim('No active sessions to terminate')}`);
+                out.warn(`No active workflows found for ensemble "${ensembleName}"`);
             }
         }
         catch {
@@ -924,8 +947,8 @@ async function down(opts) {
     }
     // Step 2: Kill bridge processes via PID files
     killBridgeProcesses();
-    // Step 3: Stop Temporal server
-    if (temporalUp) {
+    // Step 3: Stop Temporal server — only if --all flag or no other workflows remain
+    if (temporalUp && (opts.all || !hasRemainingWorkflows)) {
         // Find and kill the temporal dev server process
         try {
             if (process.platform === 'win32') {
@@ -941,6 +964,9 @@ async function down(opts) {
             out.warn('Could not stop Temporal server (may need to stop it manually)');
         }
     }
+    else if (temporalUp) {
+        out.log(`  ${out.dim('Temporal server left running (other ensembles still active)')}`);
+    }
     else {
         out.log(`  ${out.dim('Temporal not running')}`);
     }

package/dist/cli.js

@@ -205,6 +205,8 @@ async function main() {
             break;
         case 'down':
             await (0, commands_1.down)({
+                ensemble,
+                all: args.all,
                 removeMcp: !args.keepMcp,
                 dir: args.dir,
                 ...overrides,

package/dist/ensemble/loader.js

@@ -28,6 +28,12 @@ function loadLineup(filePath) {
         if (!/^[a-zA-Z0-9_-]+$/.test(p.name)) {
             throw new Error(`Invalid lineup: players[${i}].name "${p.name}" contains invalid characters`);
         }
+        if (p.isolation != null && p.isolation !== 'worktree') {
+            throw new Error(`Invalid lineup: players[${i}].isolation must be "worktree" if specified`);
+        }
+        if (p.branch != null && (typeof p.branch !== 'string' || !p.branch)) {
+            throw new Error(`Invalid lineup: players[${i}].branch must be a non-empty string`);
+        }
     }
     // Validate schedules if present
     if (doc.schedules != null) {
@@ -70,6 +76,8 @@ function loadLineup(filePath) {
             ...(p.agent != null && { agent: p.agent }),
             ...(p.instructions != null && { instructions: p.instructions }),
             ...(Array.isArray(p.allowedTools) && { allowedTools: p.allowedTools.map(String) }),
+            ...(p.isolation != null && { isolation: p.isolation }),
+            ...(p.branch != null && { branch: p.branch }),
         })),
         schedules: doc.schedules,
     };

package/dist/ensemble/schema.d.ts

@@ -14,6 +14,8 @@ export interface EnsembleLineup {
         agent?: string;
         instructions?: string;
         allowedTools?: string[];
+        isolation?: 'worktree';
+        branch?: string;
         /** Transient: resolved agent definition name (set by loadAndResolveLineup). */
         _agentDefinition?: string;
         /** Transient: resolved absolute path to .md file (set by loadAndResolveLineup). */

package/dist/tools/load-lineup.js

@@ -15,6 +15,7 @@ const duration_1 = require("../utils/duration");
 const safe_path_1 = require("../utils/safe-path");
 const helpers_1 = require("./helpers");
 const validation_1 = require("../utils/validation");
+const worktree_1 = require("../utils/worktree");
 const log = (...args) => console.error('[claude-tempo:load-lineup]', ...args);
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -79,7 +80,8 @@ function registerLoadLineupTool(server, client, config, getPlayerId, ownAgentTyp
             // Recruit players sequentially
             for (const player of lineup.players) {
                 const playerName = player.name;
-                const workDir = player.workDir || process.cwd();
+                let workDir = player.workDir || process.cwd();
+                let worktreePath;
                 const agentType = player.agent === 'copilot' ? 'copilot' : 'claude';
                 const isCustomAgent = player.agent && player.agent !== 'default' && player.agent !== 'copilot';
                 const systemPrompt = player._agentDefinition ? undefined : (isCustomAgent ? player.agent : undefined);
@@ -104,6 +106,31 @@ function registerLoadLineupTool(server, client, config, getPlayerId, ownAgentTyp
                     }
                     continue;
                 }
+                // Create worktree if isolation is requested
+                if (player.isolation === 'worktree') {
+                    try {
+                        // Determine git root: use the player's workDir as the git root,
+                        // or fall back to cwd (which should be a git repo).
+                        const gitRoot = workDir;
+                        const result = (0, worktree_1.createWorktree)({
+                            gitRoot,
+                            ensemble: config.ensemble,
+                            playerName,
+                            branch: player.branch,
+                        });
+                        worktreePath = result.path;
+                        workDir = result.path;
+                        log(`Worktree for "${playerName}": ${result.path} (branch: ${result.branch}, created: ${result.created})`);
+                        // Install dependencies — blocking but failure is non-fatal
+                        if (result.created) {
+                            (0, worktree_1.installDependencies)(result.path);
+                        }
+                    }
+                    catch (err) {
+                        failed.push(`${playerName}: worktree creation failed — ${err}`);
+                        continue;
+                    }
+                }
                 // Record existing workflows to detect the new one
                 const existingIds = new Set();
                 const listQuery = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"`;
@@ -194,6 +221,16 @@ function registerLoadLineupTool(server, client, config, getPlayerId, ownAgentTyp
                     failed.push(`${playerName}: spawned but did not register within 15s`);
                     continue;
                 }
+                // Record worktree path in session metadata
+                if (worktreePath && newWorkflowId) {
+                    try {
+                        const newHandle = client.workflow.getHandle(newWorkflowId);
+                        await newHandle.signal('updateMetadata', { worktreePath });
+                    }
+                    catch (err) {
+                        log(`Failed to set worktreePath metadata for "${playerName}":`, err);
+                    }
+                }
                 // Send initial instructions if provided
                 if (player.instructions) {
                     try {

package/dist/types.d.ts

@@ -16,6 +16,8 @@ export interface SessionMetadata {
     playerTypeDescription?: string;
     /** Player ID of who recruited this player. */
     recruitedBy?: string;
+    /** Worktree path if this session was spawned in an isolated worktree. */
+    worktreePath?: string;
 }
 export interface AgentTypeInfo {
     name: string;

package/dist/utils/validation.d.ts

@@ -30,6 +30,8 @@ export declare const GATE_CRITERIA_MAX = 20;
 export declare const GATE_CRITERION_TEXT_MAX = 512;
 /** Maximum length for gate criterion notes. */
 export declare const GATE_NOTES_MAX = 1024;
+/** Timeout for npm install in worktrees (60s). */
+export declare const WORKTREE_INSTALL_TIMEOUT = 60000;
 /** Default number of recent messages to include as context in an encore. */
 export declare const ENCORE_DEFAULT_CONTEXT_MESSAGES = 10;
 /** Maximum length for message preview truncation. */

package/dist/utils/validation.js

@@ -4,7 +4,7 @@
  * Used by MCP tool Zod schemas and config validation.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PREVIEW_MAX_LENGTH = exports.ENCORE_DEFAULT_CONTEXT_MESSAGES = exports.GATE_NOTES_MAX = exports.GATE_CRITERION_TEXT_MAX = exports.GATE_CRITERIA_MAX = exports.GATE_TASK_MAX = exports.CRON_EXPRESSION_MAX = exports.SCHEDULE_MESSAGE_MAX = exports.SCHEDULE_NAME_MAX = exports.PATH_MAX = exports.PART_MAX = exports.MESSAGE_MAX = exports.ENSEMBLE_NAME_REGEX = exports.PLAYER_NAME_MAX = exports.PLAYER_NAME_REGEX = void 0;
+exports.PREVIEW_MAX_LENGTH = exports.ENCORE_DEFAULT_CONTEXT_MESSAGES = exports.WORKTREE_INSTALL_TIMEOUT = exports.GATE_NOTES_MAX = exports.GATE_CRITERION_TEXT_MAX = exports.GATE_CRITERIA_MAX = exports.GATE_TASK_MAX = exports.CRON_EXPRESSION_MAX = exports.SCHEDULE_MESSAGE_MAX = exports.SCHEDULE_NAME_MAX = exports.PATH_MAX = exports.PART_MAX = exports.MESSAGE_MAX = exports.ENSEMBLE_NAME_REGEX = exports.PLAYER_NAME_MAX = exports.PLAYER_NAME_REGEX = void 0;
 exports.shouldIncludeInBroadcast = shouldIncludeInBroadcast;
 exports.validatePlayerName = validatePlayerName;
 exports.validateEnsembleName = validateEnsembleName;
@@ -36,6 +36,8 @@ exports.GATE_CRITERIA_MAX = 20;
 exports.GATE_CRITERION_TEXT_MAX = 512;
 /** Maximum length for gate criterion notes. */
 exports.GATE_NOTES_MAX = 1024;
+/** Timeout for npm install in worktrees (60s). */
+exports.WORKTREE_INSTALL_TIMEOUT = 60000;
 /** Default number of recent messages to include as context in an encore. */
 exports.ENCORE_DEFAULT_CONTEXT_MESSAGES = 10;
 /** Maximum length for message preview truncation. */

package/dist/utils/worktree.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Compute the base directory for all worktrees in an ensemble.
+ * Convention: `{gitRoot}/../.ct-worktrees/{ensemble}/`
+ */
+export declare function worktreeBasePath(gitRoot: string, ensemble: string): string;
+export interface CreateWorktreeOpts {
+    gitRoot: string;
+    ensemble: string;
+    playerName: string;
+    branch?: string;
+}
+export interface CreateWorktreeResult {
+    /** Absolute path to the worktree directory. */
+    path: string;
+    /** Branch name used for the worktree. */
+    branch: string;
+    /** Whether the worktree was newly created (false if it already existed). */
+    created: boolean;
+}
+/**
+ * Create a git worktree for a player. If the worktree already exists
+ * at the expected path, returns it without re-creating.
+ *
+ * Branch defaults to `{ensemble}/{playerName}` if not specified.
+ */
+export declare function createWorktree(opts: CreateWorktreeOpts): CreateWorktreeResult;
+/**
+ * Install dependencies in a worktree directory.
+ *
+ * Detects the package manager (npm, yarn, pnpm) by lockfile presence.
+ * Failure or timeout is logged but does not throw — the recruit proceeds
+ * with whatever state the worktree is in.
+ */
+export declare function installDependencies(worktreePath: string, timeoutMs?: number): void;
+/**
+ * Remove a git worktree.
+ */
+export declare function removeWorktree(worktreePath: string): void;

package/dist/utils/worktree.js

@@ -0,0 +1,168 @@
+"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.worktreeBasePath = worktreeBasePath;
+exports.createWorktree = createWorktree;
+exports.installDependencies = installDependencies;
+exports.removeWorktree = removeWorktree;
+/**
+ * Git worktree helpers for player isolation.
+ *
+ * Creates and manages git worktrees so each player can work on an
+ * isolated copy of the repository without conflicting with others.
+ */
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const validation_1 = require("./validation");
+const log = (...args) => console.error('[claude-tempo:worktree]', ...args);
+/**
+ * Compute the base directory for all worktrees in an ensemble.
+ * Convention: `{gitRoot}/../.ct-worktrees/{ensemble}/`
+ */
+function worktreeBasePath(gitRoot, ensemble) {
+    return path.join(path.dirname(gitRoot), '.ct-worktrees', ensemble);
+}
+/**
+ * Create a git worktree for a player. If the worktree already exists
+ * at the expected path, returns it without re-creating.
+ *
+ * Branch defaults to `{ensemble}/{playerName}` if not specified.
+ */
+function createWorktree(opts) {
+    const { gitRoot, ensemble, playerName } = opts;
+    const branch = opts.branch || `${ensemble}/${playerName}`;
+    const basePath = worktreeBasePath(gitRoot, ensemble);
+    const wtPath = path.join(basePath, playerName);
+    // If worktree already exists, reuse it
+    if ((0, fs_1.existsSync)(path.join(wtPath, '.git'))) {
+        log(`Worktree already exists at "${wtPath}" — reusing`);
+        return { path: wtPath, branch, created: false };
+    }
+    // Ensure base directory exists
+    (0, fs_1.mkdirSync)(basePath, { recursive: true });
+    // Check if the branch already has a worktree (would cause git error)
+    try {
+        const existing = (0, child_process_1.execFileSync)('git', ['worktree', 'list', '--porcelain'], {
+            cwd: gitRoot,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // Parse porcelain output: "branch refs/heads/{branch}" lines
+        const branchRef = `refs/heads/${branch}`;
+        if (existing.includes(`branch ${branchRef}`)) {
+            throw new Error(`Branch "${branch}" already has an active worktree. ` +
+                `Remove it first with \`git worktree remove\` or choose a different branch.`);
+        }
+    }
+    catch (err) {
+        // Re-throw our own error, swallow git failures (e.g., no worktrees yet)
+        if (err.message?.includes('already has an active worktree'))
+            throw err;
+    }
+    // Create the worktree. Use -B to create/reset the branch.
+    try {
+        log(`Creating worktree: git worktree add -B ${branch} ${wtPath}`);
+        (0, child_process_1.execFileSync)('git', ['worktree', 'add', '-B', branch, wtPath], {
+            cwd: gitRoot,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        const msg = err.stderr || err.stdout || err.message || String(err);
+        throw new Error(`Failed to create worktree at "${wtPath}": ${msg.trim()}`);
+    }
+    return { path: wtPath, branch, created: true };
+}
+/**
+ * Install dependencies in a worktree directory.
+ *
+ * Detects the package manager (npm, yarn, pnpm) by lockfile presence.
+ * Failure or timeout is logged but does not throw — the recruit proceeds
+ * with whatever state the worktree is in.
+ */
+function installDependencies(worktreePath, timeoutMs = validation_1.WORKTREE_INSTALL_TIMEOUT) {
+    // Detect package manager by lockfile
+    let cmd;
+    let args;
+    if ((0, fs_1.existsSync)(path.join(worktreePath, 'pnpm-lock.yaml'))) {
+        cmd = 'pnpm';
+        args = ['install', '--frozen-lockfile'];
+    }
+    else if ((0, fs_1.existsSync)(path.join(worktreePath, 'yarn.lock'))) {
+        cmd = 'yarn';
+        args = ['install', '--frozen-lockfile'];
+    }
+    else if ((0, fs_1.existsSync)(path.join(worktreePath, 'package-lock.json')) || (0, fs_1.existsSync)(path.join(worktreePath, 'package.json'))) {
+        cmd = 'npm';
+        args = ['install'];
+    }
+    else {
+        log(`No package.json found in "${worktreePath}" — skipping install`);
+        return;
+    }
+    try {
+        log(`Installing dependencies in "${worktreePath}": ${cmd} ${args.join(' ')}`);
+        (0, child_process_1.execFileSync)(cmd, args, {
+            cwd: worktreePath,
+            encoding: 'utf8',
+            timeout: timeoutMs,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        log(`Dependencies installed successfully in "${worktreePath}"`);
+    }
+    catch (err) {
+        // Log warning but don't throw — recruit should still proceed
+        const msg = err.killed ? `Timed out after ${timeoutMs}ms` : (err.stderr || err.message || String(err));
+        log(`Warning: dependency install failed in "${worktreePath}": ${msg}`);
+    }
+}
+/**
+ * Remove a git worktree.
+ */
+function removeWorktree(worktreePath) {
+    try {
+        (0, child_process_1.execFileSync)('git', ['worktree', 'remove', '--force', worktreePath], {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        log(`Removed worktree at "${worktreePath}"`);
+    }
+    catch (err) {
+        const msg = err.stderr || err.message || String(err);
+        log(`Warning: failed to remove worktree at "${worktreePath}": ${msg.trim()}`);
+    }
+}

package/dist/workflows/session.js

@@ -114,6 +114,8 @@ async function claudeSessionWorkflow(input) {
             input.metadata.playerType = update.playerType;
         if (update.playerTypeDescription != null)
             input.metadata.playerTypeDescription = update.playerTypeDescription;
+        if (update.worktreePath != null)
+            input.metadata.worktreePath = update.worktreePath;
         if (update.status != null) {
             input.metadata.status = update.status;
             // Re-enable stale detection only when explicitly requested (server.ts sets this)

package/dist/workflows/signals.d.ts

@@ -21,6 +21,7 @@ export declare const updateMetadataSignal: import("@temporalio/workflow").Signal
     enableStaleDetection?: boolean;
     playerType?: string;
     playerTypeDescription?: string;
+    worktreePath?: string;
 }], string>;
 export declare const getPartQuery: import("@temporalio/workflow").QueryDefinition<string, [], string>;
 export declare const getMetadataQuery: import("@temporalio/workflow").QueryDefinition<SessionMetadata, [], string>;

package/examples/agents/tempo-conductor.md

@@ -51,6 +51,41 @@ You are a combination of Product Manager, Task Decomposition Expert, and Context
 - **Escalation**: If a player reports a blocker you can't resolve, report it upward or recruit a specialist.
 - **Wrap-up**: Collect final reports, synthesize results, stop idle players, report completion.
 
+## Worktree Coordination
+
+Use git worktrees when two or more engineers need to work in the same repo on different branches simultaneously. Each worktree is an independent checkout — players can build, test, and commit without interfering with each other.
+
+### When to use
+
+- Two players working on different feature branches in the same repo
+- Running a long build/test in one branch while another player continues development
+- Isolating risky changes from the main working tree
+
+### How to coordinate
+
+1. **Create the worktree** (you or a player with shell access):
+   ```
+   git worktree add ../ct-{task} {branch}
+   ```
+2. **Install dependencies** in the new worktree:
+   ```
+   cd ../ct-{task} && npm install
+   ```
+3. **Recruit with `workDir`** pointing to the worktree:
+   ```
+   recruit({ name: "eng-33", workDir: "../ct-{task}", ... })
+   ```
+4. **Clean up** after the task: stop the player first, then remove the worktree:
+   ```
+   git worktree remove ../ct-{task}
+   ```
+
+`recruit` already accepts `workDir` — no new tools are needed for manual worktree coordination.
+
+### Platform notes
+
+- **Windows**: Use short sibling paths (e.g. `../ct-feat33`) to avoid MAX_PATH limits. Always stop players before removing worktrees — NTFS file locks will block cleanup while a session is active.
+
 ## Handling Context Pressure
 
 When a player reports context pressure (growing context, lost instructions, repeated work), act immediately:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-tempo",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "MCP server for multi-session Claude Code coordination via Temporal",
   "keywords": [
     "mcp",