claude-tempo 0.22.1 → 0.24.0

package/CLAUDE.md

@@ -27,6 +27,9 @@ src/
 │   ├── output.ts      # Shared CLI output formatting helpers
 │   └── preflight.ts   # Environment preflight checks
 ├── copilot-bridge.ts  # Copilot SDK bridge for Copilot CLI players
+├── client/
+│   ├── interface.ts   # TempoClient TypeScript interface and related types
+│   └── index.ts       # TempoClient factory implementation and barrel re-exports
 ├── worker.ts          # Temporal worker setup (used by daemon only)
 ├── connection.ts      # Temporal connection factory (shared by server + CLI)
 ├── spawn.ts           # Cross-platform process spawning helpers
@@ -75,12 +78,15 @@ src/
 │   ├── stage.ts       # Define a stage — fan-out/fan-in tracking for parallel tasks (conductor only)
 │   ├── stages.ts      # List stages and their status (conductor only)
 │   ├── cancel-stage.ts # Cancel an active stage (conductor only)
+│   ├── release.ts     # Release held players (unlock outbox + deliver deferred messages)
+│   ├── pause-ensemble.ts # Pause all sessions and the scheduler ensemble-wide
+│   ├── resume-ensemble.ts # Resume a paused ensemble
 │   └── helpers.ts     # Zod/MCP tool registration wrapper
 ├── tui/
 │   ├── index.ts       # TUI entry point — connects to Temporal and renders the Ink app
 │   ├── App.tsx        # Root TUI component — chat-focused shell with slash commands
 │   ├── store.ts       # TUI state reducer (phase, players, messages, schedules, static history)
-│   ├── client.ts      # TempoClient interface and implementation — wraps Temporal queries via Maestro
+│   ├── client.ts      # Thin re-export shim — re-exports createTempoClient from src/client/ for backward compatibility
 │   ├── commands.ts    # Slash command parser and registry (/player, /broadcast, /status, etc.)
 │   ├── ink-loader.ts  # Dynamic ESM loader for Ink (avoids CJS/ESM conflicts)
 │   ├── ink-context.tsx # React context for injected Ink primitives
@@ -170,9 +176,12 @@ npm test
 - **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`.
+- **Hold / Release**: Controlled ensemble startup mechanism. `load_lineup(hold: true)` spawns all players with locked outboxes and a standby message ("waiting for release") instead of their real task. When ready, the conductor calls `release` (MCP tool or `claude-tempo release` CLI) to unlock outboxes and deliver the actual task messages. Use case: pre-warm a full team before kicking off a long job.
+- **Pause / Resume**: Ensemble-wide mid-session flow control. `pause_ensemble` locks all session outboxes and signals the scheduler to skip fires; `resume_ensemble` reverses both. `stop` outbox entries bypass the pause lock and are always dispatched. Pause state is owned by the per-ensemble Maestro (`maestroSetPaused` signal) and synced to sessions and the scheduler.
+- **Outbox lock**: A workflow-level flag on each session that gates outbox dispatch independently of pause. Used by the hold mechanism (`outboxLocked` query, `releaseHeld` signal) and the pause mechanism (`setPaused` signal, `paused` query). The two flags are independent — a session can be held (locked) but not paused, or paused but not locked.
 - **Maestro**: Two Maestro workflow variants exist. The **per-ensemble** `claudeMaestroWorkflow` (ID: `claude-maestro-{ensemble}`) monitors a single ensemble — maintains a player snapshot, ring-buffer event log (max 200 entries), an aggregated ensemble chat cache (max 500 entries, refreshed every ~10s via `fetchEnsembleChat` activity), and queues commands for relay to the conductor via `maestroSendCommand`. The ensemble chat cache merges maestro + conductor traffic and is served via the `maestroEnsembleChat` query. The **global** `claudeGlobalMaestroWorkflow` (ID: `claude-maestro-global`) spans all ensembles — aggregates players by ensemble, maintains a cross-ensemble message ring buffer (max 500 entries), and exposes on-demand player/conductor history via `maestroFetchPlayerMessages` and `maestroFetchConductorHistory` updates. Both are implemented in `src/workflows/maestro.ts` with activities in `src/activities/maestro.ts`.
-- **TempoClient**: The TUI's API layer (`src/tui/client.ts`) — a TypeScript interface and implementation that wraps Temporal queries to the Maestro and conductor workflows. Provides `discoverEnsembles`, `getPlayers`, `getMessages`, `getConductorHistory`, `sendMessage`, `sendCommand`, `getEnsembleChat`, `getGates`, `getStages`, `getWorktrees`, and `terminatePlayer`. Uses Global Maestro as the primary source with graceful fallback to per-ensemble Maestro and direct workflow list queries.
-- **Wire protocol**: All Temporal signal, query, update, and workflow names are documented in [`docs/WIRE-PROTOCOL.md`](docs/WIRE-PROTOCOL.md). These names are stable as of v0.10 — renaming or removing any is a breaking change requiring a major version bump.
+- **TempoClient**: The API layer for querying ensemble state (`src/client/`). The interface and types live in `interface.ts`; the factory implementation lives in `index.ts`. Provides `discoverEnsembles`, `getPlayers`, `getMessages`, `getConductorHistory`, `sendMessage`, `sendCommand`, `getEnsembleChat`, `getGates`, `getStages`, `getWorktrees`, and `terminatePlayer`. Uses Global Maestro as the primary source with graceful fallback to per-ensemble Maestro and direct workflow list queries. `src/tui/client.ts` is a thin re-export shim for backward compatibility — new consumers should import from `src/client/` directly.
+- **Wire protocol**: All Temporal signal, query, update, and workflow names are documented in [`docs/WIRE-PROTOCOL.md`](docs/WIRE-PROTOCOL.md). These names are stable as of v0.10 — renaming or removing any is a breaking change requiring a major version bump. **Process**: when adding signals, queries, or updates to any workflow file (`signals.ts`, `scheduler-signals.ts`, `maestro-signals.ts`), update `docs/WIRE-PROTOCOL.md` in the same commit.
 - **Daemon**: A standalone background process (`src/daemon.ts`) that runs all Temporal workers. Auto-started by any claude-tempo command if not already running. PID stored at `~/.claude-tempo/daemon.pid`; logs at `~/.claude-tempo/daemon.log`. Sessions are now pure MCP clients — they no longer run in-process workers. Managed via `claude-tempo daemon start|stop|status|logs`.
 
 ## TUI Key Behaviors

package/README.md

@@ -36,6 +36,7 @@ Each session registers as a **player** in Temporal. Players discover each other
 | 🎭 **Player Types** | Reusable agent definitions with 8 shipped types and three-tier lookup |
 | 🖥️ **Terminal UI** | Chat-focused TUI with slash commands, overlays, and interactive wizards |
 | 🌐 **Cross-machine** | Any session that can reach your Temporal server can join the ensemble |
+| ⏸️ **Hold / Pause / Resume** | Pre-warm a full team before delivering tasks; pause and resume mid-session |
 | 🤖 **Copilot bridge** | Mix Claude Code and GitHub Copilot CLI sessions in the same ensemble |
 
 ## Installation
@@ -86,6 +87,21 @@ Stops the daemon, installs the latest version, and restarts automatically. To up
 claude-tempo upgrade 0.22.0
 ```
 
+## Stopping & Tear Down
+
+```bash
+# Stop a specific player session
+claude-tempo stop my-ensemble player-name
+
+# Tear down everything (all sessions, schedulers, and Maestro workflows)
+claude-tempo down --all
+
+# Stop the background daemon
+claude-tempo daemon stop
+```
+
+📖 [Full CLI reference → docs/cli.md](docs/cli.md)
+
 ---
 
 ## Core Concepts
@@ -127,6 +143,9 @@ claude-tempo up [ensemble]      # first-time setup
 claude-tempo conduct [ensemble] # start a conductor
 claude-tempo start [ensemble]   # start a player
 claude-tempo status [ensemble]  # list active sessions
+claude-tempo release [ensemble] # release held players (unlock + deliver tasks)
+claude-tempo pause [ensemble]   # pause all sessions and the scheduler
+claude-tempo resume [ensemble]  # resume a paused ensemble
 claude-tempo tui                # open the terminal UI
 claude-tempo daemon <sub>       # manage the worker daemon
 claude-tempo upgrade            # update to latest
@@ -218,7 +237,7 @@ claude-tempo tui --ensemble my-ensemble   # direct ensemble mode
 The TUI provides a chat-focused shell for managing your ensemble:
 
 - **Ensemble chat feed** — live aggregated view of conductor + player traffic; type bare text to message the conductor, `@player message` to message directly
-- **Slash commands** — `/recruit`, `/status`, `/schedule`, `/gates`, `/stages`, `/worktree`, and more; type `/help` for the full list
+- **Slash commands** — `/recruit`, `/status`, `/schedule`, `/gates`, `/stages`, `/worktree`, `/go` (release held), `/pause`, `/resume`, and more; type `/help` for the full list
 - **Interactive overlays and wizards** — step-by-step flows for recruiting players, creating schedules, and managing ensembles
 
 📖 [TUI reference → docs/dashboard.md](docs/dashboard.md)

package/dist/activities/outbox.d.ts

@@ -33,6 +33,12 @@ export interface StartRecruitedSessionInput {
     allowedTools?: string[];
     /** Custom claude binary path (from config.claudeBin). */
     claudeBin?: string;
+    /** When true, spawn process but lock outbox and defer initial message until release (warm hold). */
+    held?: boolean;
+}
+export interface ReleasePlayerInput {
+    ensemble: string;
+    targetPlayerId: string;
 }
 export interface SpawnProcessInput {
     targetName: string;
@@ -92,6 +98,7 @@ export interface OutboxActivities {
     startRecruitedSession(input: StartRecruitedSessionInput): Promise<RecruitResult>;
     spawnProcess(input: SpawnProcessInput): Promise<OutboxActivityResult>;
     performEncore(input: PerformEncoreInput): Promise<EncoreResult>;
+    releasePlayer(input: ReleasePlayerInput): Promise<OutboxActivityResult>;
 }
 /**
  * Create outbox delivery activities bound to a Temporal client and config.

package/dist/activities/outbox.js

@@ -101,7 +101,7 @@ function createOutboxActivities(client, config) {
             return { success: true };
         },
         async startRecruitedSession(input) {
-            const { ensemble, targetName, workDir, isConductor, initialMessage, fromPlayerId, agent, systemPrompt, taskQueue, agentDefinition, agentDefinitionDescription } = input;
+            const { ensemble, targetName, workDir, isConductor, initialMessage, fromPlayerId, agent, systemPrompt, taskQueue, agentDefinition, agentDefinitionDescription, held } = input;
             try {
                 const workflowId = isConductor
                     ? (0, config_1.conductorWorkflowId)(ensemble)
@@ -109,6 +109,11 @@ function createOutboxActivities(client, config) {
                 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,
@@ -127,15 +132,23 @@ function createOutboxActivities(client, config) {
                     },
                     autoSummary: `Session in ${path.basename(workDir)}`,
                     disableStaleDetection: true,
-                    ...(initialMessage ? {
-                        messages: [{
+                    // 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('claudeSessionWorkflow', {
                     workflowId,
@@ -149,7 +162,7 @@ function createOutboxActivities(client, config) {
                         ClaudeTempoPlayerId: [targetName],
                     },
                 });
-                log(`Pre-created workflow ${workflowId} for recruit "${targetName}" (sessionId=${sessionId})`);
+                log(`Pre-created workflow ${workflowId} for recruit "${targetName}" (sessionId=${sessionId}, held=${!!held})`);
                 return { success: true, sessionId };
             }
             catch (err) {
@@ -309,5 +322,28 @@ function createOutboxActivities(client, config) {
                 throw activity_1.ApplicationFailure.nonRetryable(`Encore failed for "${targetPlayerId}": ${err instanceof Error ? err.message : String(err)}`);
             }
         },
+        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) {
+                if (err instanceof activity_1.ApplicationFailure)
+                    throw err;
+                throw activity_1.ApplicationFailure.nonRetryable(`Release failed for "${targetPlayerId}": ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
     };
 }

package/dist/cli/commands.d.ts

@@ -77,6 +77,18 @@ interface DaemonOpts extends CliOverrides {
     subcommand?: string;
 }
 export declare function daemon(opts: DaemonOpts): Promise<void>;
+interface ReleaseOpts extends CliOverrides {
+    ensemble: string;
+}
+/** Release all held sessions in an ensemble (unlock outbox, deliver initial messages). */
+export declare function release(opts: ReleaseOpts): Promise<void>;
+interface PauseResumeOpts extends CliOverrides {
+    ensemble: string;
+}
+/** Pause an entire ensemble — sessions, scheduler, and maestro. */
+export declare function pause(opts: PauseResumeOpts): Promise<void>;
+/** Resume an entire ensemble — sessions, scheduler, and maestro. */
+export declare function resume(opts: PauseResumeOpts): Promise<void>;
 export declare function help(): void;
 export declare function version(): void;
 interface UpgradeOpts extends CliOverrides {

package/dist/cli/commands.js

@@ -45,6 +45,9 @@ exports.broadcast = broadcast;
 exports.encore = encore;
 exports.ensembleCommand = ensembleCommand;
 exports.daemon = daemon;
+exports.release = release;
+exports.pause = pause;
+exports.resume = resume;
 exports.help = help;
 exports.version = version;
 exports.upgrade = upgrade;
@@ -61,6 +64,7 @@ const git_info_1 = require("../git-info");
 const connection_1 = require("../connection");
 const signals_1 = require("../workflows/signals");
 const scheduler_signals_1 = require("../workflows/scheduler-signals");
+const maestro_signals_1 = require("../workflows/maestro-signals");
 const preflight_1 = require("./preflight");
 const mcp_1 = require("./mcp");
 const loader_1 = require("../ensemble/loader");
@@ -437,6 +441,7 @@ const SEARCH_ATTRIBUTES = [
     { name: 'ClaudeTempoPlayerId', type: 'Keyword' },
     { name: 'ClaudeTempoStatus', type: 'Keyword' },
     { name: 'ClaudeTempoPlayerType', type: 'Keyword' },
+    { name: 'ClaudeTempoIsConductor', type: 'Bool' },
 ];
 async function isTemporalReachable(config) {
     try {
@@ -1942,6 +1947,123 @@ async function daemon(opts) {
             process.exit(1);
     }
 }
+/** Release all held sessions in an ensemble (unlock outbox, deliver initial messages). */
+async function release(opts) {
+    const config = (0, config_1.getConfig)(opts);
+    let connection;
+    try {
+        connection = await Promise.race([
+            (0, connection_1.createTemporalConnection)(config),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 3000)),
+        ]);
+    }
+    catch {
+        out.error(`Cannot connect to Temporal at ${config.temporalAddress}`);
+        process.exit(1);
+        return;
+    }
+    const client = new client_1.Client({ connection, namespace: config.temporalNamespace });
+    const query = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running" AND ClaudeTempoEnsemble = "${opts.ensemble.replace(/["\\\n\r]/g, '')}"`;
+    let released = 0;
+    for await (const wf of client.workflow.list({ query })) {
+        try {
+            const handle = client.workflow.getHandle(wf.workflowId);
+            const locked = await handle.query(signals_1.outboxLockedQuery);
+            if (locked) {
+                await handle.signal(signals_1.releaseHeldSignal);
+                released++;
+                const sa = wf.searchAttributes || {};
+                const playerId = Array.isArray(sa.ClaudeTempoPlayerId) ? String(sa.ClaudeTempoPlayerId[0]) : wf.workflowId;
+                out.log(`  ${out.dim('released')} ${playerId}`);
+            }
+        }
+        catch {
+            // Skip failed queries (terminated workflows, etc.)
+        }
+    }
+    if (released > 0) {
+        out.success(`Released ${released} player${released !== 1 ? 's' : ''}`);
+    }
+    else {
+        out.log('No held players found.');
+    }
+    await connection.close();
+}
+/** Pause an entire ensemble — sessions, scheduler, and maestro. */
+async function pause(opts) {
+    const config = (0, config_1.getConfig)(opts);
+    let connection;
+    try {
+        connection = await Promise.race([
+            (0, connection_1.createTemporalConnection)(config),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 3000)),
+        ]);
+    }
+    catch {
+        out.error(`Cannot connect to Temporal at ${config.temporalAddress}`);
+        process.exit(1);
+        return;
+    }
+    const client = new client_1.Client({ connection, namespace: config.temporalNamespace });
+    await setPausedState(client, opts.ensemble, true);
+    out.success(`Ensemble "${opts.ensemble}" paused`);
+    await connection.close();
+}
+/** Resume an entire ensemble — sessions, scheduler, and maestro. */
+async function resume(opts) {
+    const config = (0, config_1.getConfig)(opts);
+    let connection;
+    try {
+        connection = await Promise.race([
+            (0, connection_1.createTemporalConnection)(config),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 3000)),
+        ]);
+    }
+    catch {
+        out.error(`Cannot connect to Temporal at ${config.temporalAddress}`);
+        process.exit(1);
+        return;
+    }
+    const client = new client_1.Client({ connection, namespace: config.temporalNamespace });
+    await setPausedState(client, opts.ensemble, false);
+    out.success(`Ensemble "${opts.ensemble}" resumed`);
+    await connection.close();
+}
+/** Shared logic: set paused state across all ensemble components. */
+async function setPausedState(client, ensemble, paused) {
+    // 1. Signal maestro hub
+    try {
+        const mh = client.workflow.getHandle((0, config_1.maestroWorkflowId)(ensemble));
+        await mh.signal(maestro_signals_1.maestroSetPausedSignal, paused);
+    }
+    catch {
+        // Maestro may not be running — non-critical
+    }
+    // 2. Signal all active sessions
+    const sanitized = ensemble.replace(/["\\\n\r]/g, '');
+    const query = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running" AND ClaudeTempoEnsemble = "${sanitized}"`;
+    let count = 0;
+    for await (const wf of client.workflow.list({ query })) {
+        try {
+            const handle = client.workflow.getHandle(wf.workflowId);
+            await handle.signal(signals_1.setPausedSignal, paused);
+            count++;
+        }
+        catch {
+            // Skip failed signals
+        }
+    }
+    out.log(`  ${out.dim(paused ? 'paused' : 'resumed')} ${count} session${count !== 1 ? 's' : ''}`);
+    // 3. Signal scheduler
+    try {
+        const sh = client.workflow.getHandle((0, config_1.schedulerWorkflowId)(ensemble));
+        await sh.signal(scheduler_signals_1.setSchedulerPausedSignal, paused);
+        out.log(`  ${out.dim(paused ? 'paused' : 'resumed')} scheduler`);
+    }
+    catch {
+        // Scheduler may not be running — non-critical
+    }
+}
 function help() {
     console.log(`
 ${out.bold('claude-tempo')} — Multi-session Claude Code coordination via Temporal
@@ -1963,6 +2085,9 @@ ${out.bold('Commands:')}
   ${out.cyan('ensemble')} <sub>       Manage saved ensemble lineups (save/list/show)
   ${out.cyan('broadcast')} <message>   Send a message to all active players
   ${out.cyan('encore')}   <name>      Revive a stale player session (reconnect with context)
+  ${out.cyan('release')} [ensemble]   Release all held players (unlock outbox, deliver messages)
+  ${out.cyan('pause')}   [ensemble]   Pause an ensemble (sessions, scheduler, maestro)
+  ${out.cyan('resume')}  [ensemble]   Resume a paused ensemble
   ${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)

package/dist/cli.js

@@ -260,6 +260,24 @@ async function main() {
             });
             break;
         }
+        case 'release':
+            await (0, commands_1.release)({
+                ensemble: args.ensemble || ensemble,
+                ...overrides,
+            });
+            break;
+        case 'pause':
+            await (0, commands_1.pause)({
+                ensemble: args.ensemble || ensemble,
+                ...overrides,
+            });
+            break;
+        case 'resume':
+            await (0, commands_1.resume)({
+                ensemble: args.ensemble || ensemble,
+                ...overrides,
+            });
+            break;
         case 'ensemble':
             await (0, commands_1.ensembleCommand)({
                 subcommand: args.positional[1],

package/dist/client/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * TempoClient — factory implementation and barrel re-exports.
+ *
+ * Extracted from `src/tui/client.ts` so that non-TUI consumers (CLI, tests,
+ * external integrations) can create a TempoClient without depending on Ink/React.
+ */
+import { Client } from '@temporalio/client';
+import type { TempoClient } from './interface';
+export type { TempoClient, EnsembleSummary } from './interface';
+export declare function createTempoClient(client: Client): TempoClient;