claude-tempo 0.11.0 → 0.12.0

package/CLAUDE.md

@@ -9,7 +9,8 @@ claude-tempo is an MCP server that enables multiple Claude Code sessions to coor
 - **Runtime**: Node.js 18+ with TypeScript
 - **MCP**: `@modelcontextprotocol/sdk` (stdio transport)
 - **Temporal**: `@temporalio/client`, `@temporalio/worker`, `@temporalio/workflow`, `@temporalio/activity`
-- **No other dependencies** — no database, no custom broker
+- **croner** — cron expression parsing and next-fire computation (used by `schedule` tool)
+- **yaml**, **zod** — lineup parsing and schema validation
 
 ## Project Structure
 
@@ -34,7 +35,7 @@ src/
 │   ├── scheduler-signals.ts # Scheduler signal/query type definitions
 │   └── signals.ts     # Session signal/query type definitions
 ├── activities/
-│   ├── outbox.ts      # Outbox delivery activities (cue, report, stop, recruit)
+│   ├── outbox.ts      # Outbox delivery activities (cue, report, stop, recruit, encore)
 │   └── schedule-fire.ts # Schedule fire activity
 ├── ensemble/
 │   ├── schema.ts      # Lineup type definitions
@@ -53,12 +54,17 @@ src/
 │   ├── recruit.ts     # Spawn new session (via outbox), supports `type` param
 │   ├── report.ts      # Report to conductor (via outbox)
 │   ├── stop.ts        # Stop a session (via outbox)
+│   ├── broadcast.ts   # Send message to all active players (via outbox fan-out)
+│   ├── encore.ts      # Revive a stale session (via outbox)
+│   ├── recall.ts      # Read own message history (received + sent)
 │   ├── load-lineup.ts # Load an ensemble lineup, recruit players
 │   ├── save-lineup.ts # Save current ensemble state as a lineup
 │   ├── schedule.ts    # Create one-shot or recurring schedules
 │   ├── unschedule.ts  # Cancel a named schedule
 │   ├── schedules.ts   # List active schedules
 │   └── helpers.ts     # Zod/MCP tool registration wrapper
+├── utils/
+│   └── validation.ts  # Shared validation constants (name/message/path limits, encore defaults) and helpers
 ├── types.ts           # Shared type definitions
 ├── channel.ts         # Claude channel notification helper
 ├── git-info.ts        # Git repository detection helper
@@ -101,11 +107,14 @@ npm test
 - **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.
-- **Outbox**: Outbound requests (cue, report, stop, recruit) 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.
+- **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.
+- **Recall**: Queries a session's own message history from the Temporal workflow. Shows received messages by default; pass `includeSent: true` to also see sent messages. Supports `limit`, `since`, and `from` filters.
 - **Per-host task queues**: Each host runs a `claude-tempo-{hostname}` activity worker for local-only operations (e.g., `spawnProcess`). This enables cross-machine recruiting — the `recruit` tool accepts an optional `host` parameter to route the spawn to a remote machine's task queue.
-- **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.
+- **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, cron-style intervals, and time-bounded delivery. Managed via `schedule`, `unschedule`, and `schedules` tools.
+- **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.
 - **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.
 
@@ -123,3 +132,14 @@ Examples:
 - `feat(tools): add ensemble discovery tool`
 - `fix(workflow): handle signal delivery edge case`
 - `docs: update getting started guide`
+
+## Release Process
+
+**Correct order — never deviate:**
+
+1. Merge the feature PR into `main` (squash merge)
+2. Bump `version` in `package.json` and add a `## [x.y.z]` entry in `CHANGELOG.md` on `main`
+3. Commit: `chore: bump version to vX.Y.Z`
+4. Tag the bump commit: `git tag vX.Y.Z && git push origin vX.Y.Z`
+
+The release workflow triggers on `v*` tag pushes and publishes to npm. **Never tag before the version bump commit exists on main, and never tag a commit that doesn't match the version in `package.json`.** Tagging prematurely (e.g., before a feature PR merges) publishes the old version to npm and forces a patch bump to recover.

package/README.md

@@ -130,6 +130,9 @@ These tools are available inside Claude Code sessions connected to claude-tempo:
 | `agent_types` | List available player types with name, description, and source. |
 | `save_lineup` | Save the current ensemble as a YAML lineup (conductor only). |
 | `load_lineup` | Load a lineup to recruit players and create schedules. |
+| `broadcast` | Send a message to all active players. Optional `type` filter limits to a specific player type. |
+| `encore` | Revive a stale player session — restarts the process and reconnects to the existing workflow with context restored. |
+| `recall` | Read your own message history. Shows received messages by default; pass `includeSent: true` for the full timeline. |
 
 ## Scheduling
 
@@ -147,11 +150,20 @@ Tell your session things like:
 - *"Schedule a check every hour called 'deploy-watch' — cue ops to check deployment status"*
 - *"Remind me in 30 minutes to review PR #42"*
 - *"Every 5 minutes for the next hour, ping frontend to check their progress"*
-- *"Set up a daily standup reminder at 9am UTC for the conductor"*
+- *"Set up a daily standup at 9am New York time, weekdays only"*
 - *"Cancel the deploy-watch schedule"*
 - *"Show me all active schedules"*
 
-Schedules support one-shot delays, fixed times, and recurring intervals with optional bounds (max count or end time).
+Schedules support four timing modes — all accept optional bounds (`count` max fires, `until` end time):
+
+| Mode | Parameter | Example |
+|------|-----------|---------|
+| One-shot delay | `delay` | `"10m"`, `"2h"`, `"1d"` |
+| Fixed time | `at` | `"2026-04-03T20:00:00Z"` |
+| Recurring interval | `every` | `"5m"`, `"1h"` |
+| Cron expression | `cron` + optional `timezone` | `"0 9 * * 1-5"` (weekdays 9am) |
+
+The `timezone` parameter accepts any IANA timezone (e.g. `"America/New_York"`, `"Europe/London"`). Defaults to UTC when omitted.
 
 ### How it works
 
@@ -238,7 +250,7 @@ players:
 
 ## Player Types
 
-Player types are reusable agent definitions in Claude Code's standard subagent format — `.md` files with YAML frontmatter specifying name, description, and optional model. They let you define specialized roles once and reuse them across lineups.
+Player types are reusable agent definitions in Claude Code's standard subagent format — `.md` files with YAML frontmatter specifying name, description, optional model, and optional tool restrictions. They let you define specialized roles once and reuse them across lineups.
 
 ### How player types work
 
@@ -254,6 +266,23 @@ players:
 
 When a player is recruited with a type, the agent definition is resolved and passed to the session. Players know their type via the `who_am_i` tool.
 
+### Tool restrictions (`allowedTools`)
+
+Agent type frontmatter may include an `allowedTools` array to restrict which tools the spawned session can use. When present, it is passed to the Claude Code session via `--allowedTools` and overrides any lineup-level setting.
+
+```yaml
+---
+name: tempo-reviewer
+description: Read-only code reviewer
+allowedTools:
+  - Read
+  - Glob
+  - Grep
+---
+```
+
+This is useful for security-sensitive roles (read-only reviewers, auditors) or to prevent specific players from making changes outside their scope. Sessions launched without a type, or with a type that omits `allowedTools`, receive no tool restrictions.
+
 ### Three-tier lookup
 
 Player types are resolved in order (first match wins):

package/dist/activities/outbox.d.ts

@@ -30,6 +30,7 @@ export interface StartRecruitedSessionInput {
     taskQueue: string;
     agentDefinition?: string;
     agentDefinitionDescription?: string;
+    allowedTools?: string[];
 }
 export interface SpawnProcessInput {
     targetName: string;
@@ -43,6 +44,28 @@ export interface SpawnProcessInput {
     agentDefinition?: string;
     agentDefinitionPath?: string;
     nativeResolvable?: boolean;
+    /** When true, use --resume instead of -n (reconnect to existing session). */
+    resume?: boolean;
+    /** Tool restrictions from the agent definition frontmatter. */
+    allowedTools?: string[];
+}
+export interface PerformEncoreInput {
+    ensemble: string;
+    targetPlayerId: string;
+    fromPlayerId: string;
+    contextMessageCount?: number;
+}
+export interface EncoreResult {
+    workDir: string;
+    hostname: string;
+    isConductor: boolean;
+    agent: AgentType;
+    agentDefinition?: string;
+    agentDefinitionPath?: string;
+    nativeResolvable?: boolean;
+    allowedTools?: string[];
+    temporalAddress: string;
+    temporalNamespace: string;
 }
 export interface OutboxActivityResult {
     success: boolean;
@@ -54,6 +77,7 @@ export interface OutboxActivities {
     terminateSession(input: TerminateSessionInput): Promise<OutboxActivityResult>;
     startRecruitedSession(input: StartRecruitedSessionInput): Promise<OutboxActivityResult>;
     spawnProcess(input: SpawnProcessInput): Promise<OutboxActivityResult>;
+    performEncore(input: PerformEncoreInput): Promise<EncoreResult>;
 }
 /**
  * Create outbox delivery activities bound to a Temporal client and config.

package/dist/activities/outbox.js

@@ -40,10 +40,12 @@ const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const crypto = __importStar(require("crypto"));
 const config_1 = require("../config");
+const validation_1 = require("../utils/validation");
 const git_info_1 = require("../git-info");
 const spawn_1 = require("../spawn");
 const config_2 = require("../config");
 const resolve_1 = require("./resolve");
+const agent_types_1 = require("../ensemble/agent-types");
 const log = (...args) => console.error('[claude-tempo:outbox]', ...args);
 /**
  * Create outbox delivery activities bound to a Temporal client and config.
@@ -143,11 +145,14 @@ function createOutboxActivities(client, config) {
             }
         },
         async spawnProcess(input) {
-            const { targetName, workDir, isConductor, agent, systemPrompt, ensemble, temporalAddress, temporalNamespace, agentDefinition, agentDefinitionPath, nativeResolvable } = input;
+            const { targetName, workDir, isConductor, agent, systemPrompt, ensemble, temporalAddress, temporalNamespace, agentDefinition, agentDefinitionPath, nativeResolvable, resume, allowedTools } = input;
             // Read secrets from the worker's config closure — never from workflow state
             const { temporalApiKey, temporalTlsCertPath, temporalTlsKeyPath } = config;
             try {
                 if (agent === 'copilot') {
+                    if (allowedTools && allowedTools.length > 0) {
+                        log(`Warning: allowedTools [${allowedTools.join(', ')}] specified for copilot agent "${targetName}" — copilot bridge does not support --allowedTools, skipping`);
+                    }
                     const { pid } = (0, spawn_1.spawnCopilotBridge)({
                         name: targetName,
                         ensemble,
@@ -173,11 +178,18 @@ function createOutboxActivities(client, config) {
                     else if (systemPrompt) {
                         agentFlags = ['--system-prompt', systemPrompt];
                     }
+                    // Use --resume for encore (reconnect to existing session) or -n for new sessions
+                    const nameArgs = resume ? ['--resume', targetName] : ['-n', targetName];
+                    // Build --allowedTools flag from agent definition frontmatter
+                    const allowedToolsFlags = allowedTools && allowedTools.length > 0
+                        ? ['--allowedTools', ...allowedTools]
+                        : [];
                     const spawnArgs = [
                         '--dangerously-skip-permissions',
                         '--dangerously-load-development-channels', 'server:claude-tempo',
-                        '-n', targetName,
+                        ...nameArgs,
                         ...agentFlags,
+                        ...allowedToolsFlags,
                     ];
                     const envVars = {
                         [config_2.ENV.ENSEMBLE]: ensemble,
@@ -195,7 +207,7 @@ function createOutboxActivities(client, config) {
                     if (temporalTlsKeyPath)
                         envVars[config_2.ENV.TEMPORAL_TLS_KEY_PATH] = temporalTlsKeyPath;
                     const { pid } = (0, spawn_1.spawnInTerminal)(spawnArgs, workDir, envVars);
-                    log(`Spawned claude process (pid ${pid}) in ${workDir} as "${targetName}"`);
+                    log(`Spawned claude process (pid ${pid}) in ${workDir} as "${targetName}" (resume=${!!resume})`);
                 }
                 return { success: true };
             }
@@ -203,5 +215,80 @@ function createOutboxActivities(client, config) {
                 throw activity_1.ApplicationFailure.nonRetryable(`Failed to spawn process for "${targetName}": ${err instanceof Error ? err.message : String(err)}`);
             }
         },
+        async performEncore(input) {
+            const { ensemble, targetPlayerId, fromPlayerId, contextMessageCount = validation_1.ENCORE_DEFAULT_CONTEXT_MESSAGES } = input;
+            try {
+                const handle = await (0, resolve_1.resolveSession)(client, ensemble, targetPlayerId);
+                if (!handle) {
+                    throw activity_1.ApplicationFailure.nonRetryable(`No session found for "${targetPlayerId}"`);
+                }
+                // Atomically transition status from 'stale' to 'pending' — prevents double-spawn races
+                const transitioned = await handle.executeUpdate('checkAndSetStatus', {
+                    args: [{ expectedStatus: 'stale', newStatus: 'pending' }],
+                });
+                if (!transitioned) {
+                    // Read current status for a useful error message
+                    const metadata = await handle.query('getMetadata');
+                    const status = metadata.status;
+                    throw activity_1.ApplicationFailure.nonRetryable(`Cannot encore "${targetPlayerId}" — status is "${status}" (must be "stale"). Another encore may already be in progress.`);
+                }
+                // Query context (status is now locked to 'pending', safe from races)
+                const metadata = await handle.query('getMetadata');
+                const part = await handle.query('getPart');
+                const allMessages = await handle.query('allMessages');
+                // Build context message from recent messages
+                const recentMessages = allMessages.slice(-contextMessageCount);
+                const msgSummary = recentMessages.length > 0
+                    ? recentMessages.map(m => `[${m.from}] ${m.text.slice(0, validation_1.PREVIEW_MAX_LENGTH)}`).join('\n')
+                    : '(no recent messages)';
+                const contextMessage = [
+                    `🎵 **Encore** — you've been revived by ${fromPlayerId}.`,
+                    part ? `Your last status: ${part}` : '',
+                    `Recent messages (last ${recentMessages.length}):`,
+                    msgSummary,
+                    '',
+                    '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 });
+                log(`Encore prepared for "${targetPlayerId}" — status reset to pending, context injected`);
+                // Return spawn parameters from the target's metadata
+                const agentType = metadata.agentType || 'claude';
+                const playerType = metadata.playerType;
+                let agentDefinitionPath;
+                let nativeResolvable;
+                let allowedTools;
+                if (playerType) {
+                    try {
+                        const info = (0, agent_types_1.resolveAgentType)(playerType);
+                        if (info) {
+                            agentDefinitionPath = info.path;
+                            nativeResolvable = info.nativeResolvable;
+                            allowedTools = info.allowedTools;
+                        }
+                    }
+                    catch {
+                        // Agent type resolution failure is non-fatal
+                    }
+                }
+                return {
+                    workDir: metadata.workDir,
+                    hostname: metadata.hostname,
+                    isConductor: metadata.isConductor,
+                    agent: agentType === 'copilot' ? 'copilot' : 'claude',
+                    agentDefinition: playerType,
+                    agentDefinitionPath,
+                    nativeResolvable,
+                    allowedTools,
+                    temporalAddress: config.temporalAddress,
+                    temporalNamespace: config.temporalNamespace,
+                };
+            }
+            catch (err) {
+                if (err instanceof activity_1.ApplicationFailure)
+                    throw err;
+                throw activity_1.ApplicationFailure.nonRetryable(`Encore failed for "${targetPlayerId}": ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
     };
 }

package/dist/activities/schedule-fire.d.ts

@@ -10,9 +10,14 @@ export interface FireScheduleResult {
     success: boolean;
     error?: string;
 }
+export interface ComputeNextCronInput {
+    cronExpression: string;
+    timezone?: string;
+}
 /** Activity interface — used by proxyActivities in the scheduler workflow. */
 export interface ScheduleActivities {
     fireSchedule(input: FireScheduleInput): Promise<FireScheduleResult>;
+    computeNextCronFire(input: ComputeNextCronInput): Promise<string | null>;
 }
 /**
  * Create the schedule-fire activity bound to a Temporal client.

package/dist/activities/schedule-fire.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createScheduleActivities = createScheduleActivities;
+const croner_1 = require("croner");
 const config_1 = require("../config");
 const resolve_1 = require("./resolve");
 /**
@@ -9,6 +10,11 @@ const resolve_1 = require("./resolve");
  */
 function createScheduleActivities(client) {
     return {
+        async computeNextCronFire(input) {
+            const job = new croner_1.Cron(input.cronExpression, { timezone: input.timezone || 'UTC' });
+            const next = job.nextRun();
+            return next ? next.toISOString() : null;
+        },
         async fireSchedule(input) {
             const { ensemble, scheduleName, message, target, createdBy } = input;
             try {

package/dist/cli/commands.d.ts

@@ -50,6 +50,19 @@ interface AgentTypesCommandOpts {
     name?: string;
 }
 export declare function agentTypesCommand(opts: AgentTypesCommandOpts): Promise<void>;
+interface BroadcastOpts extends CliOverrides {
+    ensemble?: string;
+    message: string;
+    type?: string;
+    includeStale?: boolean;
+}
+export declare function broadcast(opts: BroadcastOpts): Promise<void>;
+interface EncoreOpts extends CliOverrides {
+    name: string;
+    ensemble?: string;
+    host?: string;
+}
+export declare function encore(opts: EncoreOpts): Promise<void>;
 interface EnsembleCommandOpts extends CliOverrides {
     subcommand?: string;
     name?: string;

package/dist/cli/commands.js

@@ -41,6 +41,8 @@ exports.up = up;
 exports.down = down;
 exports.stop = stop;
 exports.agentTypesCommand = agentTypesCommand;
+exports.broadcast = broadcast;
+exports.encore = encore;
 exports.ensembleCommand = ensembleCommand;
 exports.help = help;
 exports.version = version;
@@ -59,6 +61,7 @@ const mcp_1 = require("./mcp");
 const loader_1 = require("../ensemble/loader");
 const saver_1 = require("../ensemble/saver");
 const agent_types_1 = require("../ensemble/agent-types");
+const validation_1 = require("../utils/validation");
 const out = __importStar(require("./output"));
 /** Package root is two levels up from dist/cli/ */
 const PACKAGE_ROOT = (0, path_1.resolve)(__dirname, '..', '..');
@@ -1227,6 +1230,178 @@ async function agentTypesCommand(opts) {
             process.exit(1);
     }
 }
+async function broadcast(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 ensemble = opts.ensemble || config.ensemble;
+    const query = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"`;
+    const targets = [];
+    for await (const wf of client.workflow.list({ query })) {
+        try {
+            const handle = client.workflow.getHandle(wf.workflowId);
+            const metadata = await handle.query('getMetadata');
+            if (metadata.ensemble !== ensemble)
+                continue;
+            // Filter by status
+            if (!(0, validation_1.shouldIncludeInBroadcast)(metadata.status, !!opts.includeStale))
+                continue;
+            // Filter by player type if specified
+            if (opts.type && metadata.playerType !== opts.type)
+                continue;
+            targets.push({ playerId: metadata.playerId, workflowId: wf.workflowId });
+        }
+        catch {
+            // Workflow may have just completed — skip it
+        }
+    }
+    if (targets.length === 0) {
+        out.warn('No active players matched the broadcast filter.');
+        await connection.close();
+        return;
+    }
+    // Signal each target directly (CLI bypasses outbox)
+    let sent = 0;
+    for (const target of targets) {
+        try {
+            const handle = client.workflow.getHandle(target.workflowId);
+            await handle.signal('receiveMessage', {
+                from: 'cli',
+                text: opts.message,
+            });
+            sent++;
+            out.log(`  ${out.green('✓')} ${target.playerId}`);
+        }
+        catch (err) {
+            out.warn(`  ${target.playerId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    out.success(`Broadcast sent to ${sent}/${targets.length} player${targets.length === 1 ? '' : 's'}`);
+    await connection.close();
+}
+async function encore(opts) {
+    if (opts.host) {
+        out.error('Cross-machine encore is not supported via the CLI. Use the MCP `encore` tool with --host instead (it routes through the outbox and per-host task queues).');
+        process.exit(1);
+        return;
+    }
+    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 ensemble = opts.ensemble || config.ensemble;
+    // Resolve the target session
+    const query = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"`;
+    let targetHandle = null;
+    let targetMeta = null;
+    for await (const wf of client.workflow.list({ query })) {
+        try {
+            const handle = client.workflow.getHandle(wf.workflowId);
+            const metadata = await handle.query('getMetadata');
+            if (metadata.ensemble === ensemble && metadata.playerId === opts.name) {
+                targetHandle = handle;
+                targetMeta = metadata;
+                break;
+            }
+        }
+        catch {
+            // skip
+        }
+    }
+    if (!targetHandle || !targetMeta) {
+        out.error(`No session found with name "${opts.name}" in ensemble "${ensemble}".`);
+        await connection.close();
+        process.exit(1);
+        return;
+    }
+    const status = targetMeta.status || 'active';
+    if (status !== 'stale') {
+        out.error(`Session "${opts.name}" is ${status}, not stale. Encore only works on stale sessions.`);
+        await connection.close();
+        process.exit(1);
+        return;
+    }
+    // Query context
+    const part = await targetHandle.query('getPart');
+    const allMessages = await targetHandle.query('allMessages');
+    const recentMessages = allMessages.slice(-validation_1.ENCORE_DEFAULT_CONTEXT_MESSAGES);
+    const msgSummary = recentMessages.length > 0
+        ? recentMessages.map(m => `[${m.from}] ${m.text.slice(0, validation_1.PREVIEW_MAX_LENGTH)}`).join('\n')
+        : '(no recent messages)';
+    const contextMessage = [
+        `🎵 **Encore** — you've been revived via CLI.`,
+        part ? `Your last status: ${part}` : '',
+        `Recent messages (last ${recentMessages.length}):`,
+        msgSummary,
+        '',
+        'Resume where you left off. Use `ensemble` to see who is active.',
+    ].filter(Boolean).join('\n');
+    // Reset status and inject context message
+    await targetHandle.signal('updateMetadata', { status: 'pending' });
+    await targetHandle.signal('receiveMessage', { from: 'system', text: contextMessage });
+    out.log(`Reviving "${opts.name}" in ${targetMeta.workDir}...`);
+    // Resolve agent flags
+    let agentFlags = [];
+    if (targetMeta.playerType) {
+        try {
+            const info = (0, agent_types_1.resolveAgentType)(targetMeta.playerType);
+            if (info?.nativeResolvable) {
+                agentFlags = ['--agent', targetMeta.playerType];
+            }
+            else if (info?.path) {
+                agentFlags = ['--system-prompt', info.path];
+            }
+        }
+        catch {
+            // non-fatal
+        }
+    }
+    const spawnArgs = [
+        '--dangerously-skip-permissions',
+        '--dangerously-load-development-channels', 'server:claude-tempo',
+        '--resume', opts.name,
+        ...agentFlags,
+    ];
+    const envVars = {
+        [config_1.ENV.ENSEMBLE]: ensemble,
+        [config_1.ENV.CONDUCTOR]: targetMeta.isConductor ? 'true' : '',
+        [config_1.ENV.PLAYER_NAME]: opts.name,
+        [config_1.ENV.TEMPORAL_ADDRESS]: config.temporalAddress,
+        [config_1.ENV.TEMPORAL_NAMESPACE]: config.temporalNamespace,
+    };
+    if (targetMeta.playerType)
+        envVars[config_1.ENV.PLAYER_TYPE] = targetMeta.playerType;
+    if (config.temporalApiKey)
+        envVars[config_1.ENV.TEMPORAL_API_KEY] = config.temporalApiKey;
+    if (config.temporalTlsCertPath)
+        envVars[config_1.ENV.TEMPORAL_TLS_CERT_PATH] = config.temporalTlsCertPath;
+    if (config.temporalTlsKeyPath)
+        envVars[config_1.ENV.TEMPORAL_TLS_KEY_PATH] = config.temporalTlsKeyPath;
+    const { pid } = (0, spawn_1.spawnInTerminal)(spawnArgs, targetMeta.workDir, envVars);
+    out.success(`Encore! "${opts.name}" revived (pid ${pid})`);
+    await connection.close();
+}
 async function ensembleCommand(opts) {
     switch (opts.subcommand) {
         case 'save': {
@@ -1297,6 +1472,8 @@ ${out.bold('Commands:')}
   ${out.cyan('stop')}    [ensemble]    Stop sessions (-n <name> for one, or --all)
   ${out.cyan('status')}  [ensemble]    Show active sessions and Temporal health
   ${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('agent-types')} <sub>    Manage player type definitions (list/show/init)
   ${out.cyan('config')}                Configure Temporal connection settings
   ${out.cyan('init')}                  Register MCP server globally (or --project for .mcp.json)

package/dist/cli.js

@@ -51,6 +51,7 @@ function parseArgs(argv) {
         project: false,
         replace: false,
         resume: false,
+        includeStale: false,
     };
     let i = 0;
     while (i < argv.length) {
@@ -103,6 +104,15 @@ function parseArgs(argv) {
         else if (arg === '--ensemble' && i + 1 < argv.length) {
             result.ensemble = argv[++i];
         }
+        else if (arg === '--type' && i + 1 < argv.length) {
+            result.type = argv[++i];
+        }
+        else if (arg === '--include-stale') {
+            result.includeStale = true;
+        }
+        else if (arg === '--host' && i + 1 < argv.length) {
+            result.host = argv[++i];
+        }
         else if (arg === '--agent' && i + 1 < argv.length) {
             const val = argv[++i];
             if (val !== 'claude' && val !== 'copilot') {
@@ -209,6 +219,35 @@ async function main() {
                 ...overrides,
             });
             break;
+        case 'broadcast': {
+            const msg = args.positional.slice(1).join(' ');
+            if (!msg) {
+                out.error('Usage: claude-tempo broadcast <message> [--ensemble <name>] [--type <player-type>] [--include-stale]');
+                process.exit(1);
+            }
+            await (0, commands_1.broadcast)({
+                message: msg,
+                ensemble: args.ensemble || ensemble,
+                type: args.type,
+                includeStale: args.includeStale,
+                ...overrides,
+            });
+            break;
+        }
+        case 'encore': {
+            const encoreName = args.positional[1] || args.name;
+            if (!encoreName) {
+                out.error('Usage: claude-tempo encore <name> [--ensemble <name>] [--host <hostname>]');
+                process.exit(1);
+            }
+            await (0, commands_1.encore)({
+                name: encoreName,
+                ensemble: args.ensemble || ensemble,
+                host: args.host,
+                ...overrides,
+            });
+            break;
+        }
         case 'ensemble':
             await (0, commands_1.ensembleCommand)({
                 subcommand: args.positional[1],