claude-tempo 0.16.2 → 0.17.0

package/CLAUDE.md

@@ -32,10 +32,14 @@ src/
 │   ├── index.ts       # Workflow exports (re-exports for worker bundle)
 │   ├── session.ts     # claude-session workflow
 │   ├── scheduler.ts   # durable scheduler workflow (one per ensemble)
+│   ├── maestro.ts     # Maestro ensemble hub workflow (one per ensemble)
+│   ├── maestro-signals.ts # Maestro signal/query/update type definitions
 │   ├── 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, encore)
+│   ├── maestro.ts     # Maestro activities (refreshEnsembleState, relayCommandToConductor, fetchConductorHistory)
+│   ├── resolve.ts     # Session resolver shared by outbox + schedule-fire activities
 │   └── schedule-fire.ts # Schedule fire activity
 ├── ensemble/
 │   ├── schema.ts      # Lineup type definitions
@@ -125,6 +129,7 @@ npm test
 - **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.
 - **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).
+- **Maestro**: A durable `claudeMaestroWorkflow` (one per ensemble, ID: `claude-maestro-{ensemble}`) that acts as an ensemble state aggregator for external integrations. It periodically polls all session metadata to maintain a player snapshot and ring-buffer event log, and accepts commands via the `maestroSendCommand` update for relay to the conductor. The Maestro dashboard ([vinceblank/maestro](https://github.com/vinceblank/maestro)) connects to this workflow to display live ensemble state. Implemented in `src/workflows/maestro.ts` with activities in `src/activities/maestro.ts`.
 - **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.
 
 ## Dashboard

package/dist/activities/maestro.d.ts

@@ -0,0 +1,31 @@
+import { Client } from '@temporalio/client';
+import { HistoryEntry, MaestroPlayerInfo } from '../types';
+export interface RelayCommandInput {
+    ensemble: string;
+    text: string;
+    source: string;
+    replyTo?: string;
+}
+export interface RelayCommandResult {
+    success: boolean;
+    error?: string;
+}
+export interface FetchConductorHistoryInput {
+    ensemble: string;
+}
+export interface FetchConductorHistoryResult {
+    success: boolean;
+    history: HistoryEntry[];
+    error?: string;
+}
+/** Activity interface — used by proxyActivities in the Maestro workflow. */
+export interface MaestroActivities {
+    refreshEnsembleState(ensemble: string): Promise<MaestroPlayerInfo[]>;
+    fetchConductorHistory(input: FetchConductorHistoryInput): Promise<FetchConductorHistoryResult>;
+    relayCommandToConductor(input: RelayCommandInput): Promise<RelayCommandResult>;
+}
+/**
+ * Create the Maestro activity implementations bound to a Temporal client.
+ * Registered with the shared worker.
+ */
+export declare function createMaestroActivities(client: Client): MaestroActivities;

package/dist/activities/maestro.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMaestroActivities = createMaestroActivities;
+const activity_1 = require("@temporalio/activity");
+const config_1 = require("../config");
+const resolve_1 = require("./resolve");
+const log = (...args) => console.error('[claude-tempo:maestro]', ...args);
+/**
+ * Create the Maestro activity implementations bound to a Temporal client.
+ * Registered with the shared worker.
+ */
+function createMaestroActivities(client) {
+    return {
+        async refreshEnsembleState(ensemble) {
+            try {
+                const sessions = await (0, resolve_1.scanEnsembleSessions)(client, ensemble);
+                return sessions.map((s) => ({
+                    playerId: s.playerId,
+                    part: s.part,
+                    hostname: s.hostname,
+                    workDir: s.workDir,
+                    gitRoot: s.gitRoot,
+                    gitBranch: s.gitBranch,
+                    isConductor: s.isConductor,
+                    agentType: s.agentType,
+                    playerType: s.playerType,
+                    status: s.status,
+                }));
+            }
+            catch (err) {
+                log('refreshEnsembleState failed:', err);
+                throw activity_1.ApplicationFailure.nonRetryable(`Failed to scan ensemble: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+        async fetchConductorHistory(input) {
+            try {
+                const wfId = (0, config_1.conductorWorkflowId)(input.ensemble);
+                const handle = client.workflow.getHandle(wfId);
+                const history = await handle.query('history');
+                return { success: true, history };
+            }
+            catch (err) {
+                // ContinueAsNew transient errors and missing conductor are soft failures
+                const msg = err instanceof Error ? err.message : String(err);
+                log('fetchConductorHistory failed (soft):', msg);
+                return { success: false, history: [], error: msg };
+            }
+        },
+        async relayCommandToConductor(input) {
+            try {
+                const wfId = (0, config_1.conductorWorkflowId)(input.ensemble);
+                const handle = client.workflow.getHandle(wfId);
+                await handle.signal('command', {
+                    text: input.text,
+                    source: input.source,
+                    ...(input.replyTo ? { replyTo: input.replyTo } : {}),
+                });
+                return { success: true };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                log('relayCommandToConductor failed:', msg);
+                return { success: false, error: msg };
+            }
+        },
+    };
+}

package/dist/activities/resolve.d.ts

@@ -8,3 +8,23 @@ import { Client, WorkflowHandle } from '@temporalio/client';
  * Shared by activity files (outbox, schedule-fire) and the tools layer.
  */
 export declare function resolveSession(client: Client, ensemble: string, playerName: string): Promise<WorkflowHandle | null>;
+/** Info returned for each session by scanEnsembleSessions. */
+export interface EnsembleSessionInfo {
+    workflowId: string;
+    playerId: string;
+    part: string;
+    hostname: string;
+    workDir: string;
+    gitRoot?: string;
+    gitBranch?: string;
+    isConductor: boolean;
+    agentType: string;
+    playerType?: string;
+    status?: string;
+}
+/**
+ * Scan all running session workflows in an ensemble.
+ * Returns metadata + part for each session. Shared by the ensemble MCP tool
+ * and the Maestro refresh activity.
+ */
+export declare function scanEnsembleSessions(client: Client, ensemble: string): Promise<EnsembleSessionInfo[]>;

package/dist/activities/resolve.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveSession = resolveSession;
+exports.scanEnsembleSessions = scanEnsembleSessions;
+/** Shared query for listing running session workflows. */
+const SESSION_LIST_QUERY = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"`;
 /**
  * Resolve a session by player name.
  * Lists all running session workflows and queries each for metadata.
@@ -10,8 +13,7 @@ exports.resolveSession = resolveSession;
  * Shared by activity files (outbox, schedule-fire) and the tools layer.
  */
 async function resolveSession(client, ensemble, playerName) {
-    const query = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"`;
-    for await (const wf of client.workflow.list({ query })) {
+    for await (const wf of client.workflow.list({ query: SESSION_LIST_QUERY })) {
         try {
             const handle = client.workflow.getHandle(wf.workflowId);
             const metadata = await handle.query('getMetadata');
@@ -25,3 +27,37 @@ async function resolveSession(client, ensemble, playerName) {
     }
     return null;
 }
+/**
+ * Scan all running session workflows in an ensemble.
+ * Returns metadata + part for each session. Shared by the ensemble MCP tool
+ * and the Maestro refresh activity.
+ */
+async function scanEnsembleSessions(client, ensemble) {
+    const sessions = [];
+    for await (const workflow of client.workflow.list({ query: SESSION_LIST_QUERY })) {
+        try {
+            const handle = client.workflow.getHandle(workflow.workflowId);
+            const metadata = await handle.query('getMetadata');
+            if (metadata.ensemble !== ensemble)
+                continue;
+            const part = await handle.query('getPart');
+            sessions.push({
+                workflowId: workflow.workflowId,
+                playerId: metadata.playerId,
+                part,
+                hostname: metadata.hostname,
+                workDir: metadata.workDir,
+                gitRoot: metadata.gitRoot,
+                gitBranch: metadata.gitBranch,
+                isConductor: metadata.isConductor,
+                agentType: metadata.agentType || 'claude',
+                playerType: metadata.playerType,
+                status: metadata.status,
+            });
+        }
+        catch {
+            // Workflow may have just completed — skip it
+        }
+    }
+    return sessions;
+}

package/dist/cli/commands.js

@@ -74,6 +74,27 @@ function formatDurationMs(ms) {
         return `${ms / 60_000}m`;
     return `${ms / 1000}s`;
 }
+/**
+ * Ensure the Maestro workflow is running for the given ensemble.
+ * Idempotent — uses USE_EXISTING conflict policy.
+ */
+async function ensureMaestroWorkflow(client, config, ensemble) {
+    const wfId = (0, config_1.maestroWorkflowId)(ensemble);
+    try {
+        await client.workflow.start('claudeMaestroWorkflow', {
+            workflowId: wfId,
+            taskQueue: config.taskQueue,
+            args: [{ ensemble }],
+            workflowIdConflictPolicy: client_1.WorkflowIdConflictPolicy.USE_EXISTING,
+            searchAttributes: {
+                ClaudeTempoEnsemble: [ensemble],
+            },
+        });
+    }
+    catch {
+        // Maestro is non-critical — log but don't fail
+    }
+}
 async function start(opts) {
     const config = (0, config_1.getConfig)(opts);
     const workDir = opts.dir || process.cwd();
@@ -190,6 +211,18 @@ async function start(opts) {
     }
     out.log(`  Ensemble: ${opts.ensemble}`);
     out.log(`  Directory: ${workDir}`);
+    // Start Maestro workflow when launching a conductor
+    if (opts.conductor) {
+        try {
+            const connection = await (0, connection_1.createTemporalConnection)(config);
+            const client = new client_1.Client({ connection, namespace: config.temporalNamespace });
+            await ensureMaestroWorkflow(client, config, opts.ensemble);
+            await connection.close();
+        }
+        catch {
+            // Maestro is non-critical
+        }
+    }
     out.log(`\nCheck status: ${out.dim('claude-tempo status ' + opts.ensemble)}`);
 }
 async function status(opts) {
@@ -289,9 +322,12 @@ async function status(opts) {
             const agent = s.agentType === 'copilot' ? out.dim(' [copilot]') : '';
             const statusLabel = s.status === 'stale' ? out.yellow(' (stale)')
                 : s.status === 'pending' ? out.dim(' (pending)')
-                    : '';
+                    : s.status === 'blocked' ? out.yellow(' (blocked)')
+                        : '';
+            // Show PID info for copilot bridge sessions
+            const pidInfo = s.agentType === 'copilot' ? getBridgePidInfo(s.name) : '';
             const name = out.bold(s.name);
-            out.log(`  ${name}${role}${statusLabel}${agent}`);
+            out.log(`  ${name}${role}${statusLabel}${agent}${pidInfo}`);
             if (s.part)
                 out.log(`    ${out.dim(s.part)}`);
             const details = [s.workDir, s.branch, s.host].filter(Boolean).join('  ');
@@ -716,6 +752,8 @@ async function up(opts) {
         }
         else {
             out.check('Conductor registered', true);
+            // Ensure Maestro workflow is running
+            await ensureMaestroWorkflow(client, config, opts.ensemble);
             // Send conductor instructions if provided
             if (lineup.conductor?.instructions) {
                 try {
@@ -1129,6 +1167,31 @@ async function stopByName(client, name, config, ensemble) {
         process.exit(1);
     }
 }
+/**
+ * Read PID info for a copilot bridge session from its PID file.
+ * Returns a formatted string like " (pid 12345)" or "" if no PID file found.
+ */
+function getBridgePidInfo(name) {
+    const pidPath = (0, path_1.join)(process.cwd(), 'logs', `${name}.pid`);
+    if (!(0, fs_1.existsSync)(pidPath))
+        return '';
+    try {
+        const pid = parseInt((0, fs_1.readFileSync)(pidPath, 'utf8').trim(), 10);
+        if (isNaN(pid))
+            return '';
+        // Check if process is still alive
+        try {
+            process.kill(pid, 0); // signal 0 = existence check, doesn't kill
+            return out.dim(` (pid ${pid})`);
+        }
+        catch {
+            return out.dim(` (pid ${pid}, dead)`);
+        }
+    }
+    catch {
+        return '';
+    }
+}
 /**
  * Kill a bridge process by reading its PID file from logs/.
  * Cleans up the PID file after.

package/dist/config.d.ts

@@ -94,3 +94,5 @@ export declare function sessionWorkflowId(ensemble: string, playerId: string): s
 export declare function conductorWorkflowId(ensemble: string): string;
 /** Build a workflow ID for the scheduler: claude-scheduler-{ensemble} */
 export declare function schedulerWorkflowId(ensemble: string): string;
+/** Build a workflow ID for the Maestro: claude-maestro-{ensemble} */
+export declare function maestroWorkflowId(ensemble: string): string;

package/dist/config.js

@@ -11,6 +11,7 @@ exports.hostTaskQueue = hostTaskQueue;
 exports.sessionWorkflowId = sessionWorkflowId;
 exports.conductorWorkflowId = conductorWorkflowId;
 exports.schedulerWorkflowId = schedulerWorkflowId;
+exports.maestroWorkflowId = maestroWorkflowId;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const os_1 = require("os");
@@ -263,3 +264,7 @@ function conductorWorkflowId(ensemble) {
 function schedulerWorkflowId(ensemble) {
     return `claude-scheduler-${ensemble}`;
 }
+/** Build a workflow ID for the Maestro: claude-maestro-{ensemble} */
+function maestroWorkflowId(ensemble) {
+    return `claude-maestro-${ensemble}`;
+}

package/dist/copilot-bridge.js

@@ -84,6 +84,8 @@ const POLL_INTERVAL_MS = 2000;
 const CREATE_SESSION_TIMEOUT_MS = 45_000;
 const MAX_CONSECUTIVE_FAILURES = 3;
 const MAX_SESSION_RECREATIONS = 2;
+/** Check workflow status every N polls (~30s at 2s interval). */
+const WORKFLOW_STATUS_CHECK_INTERVAL = 15;
 /** Wrap createSession with a timeout so auth/network hangs don't block forever. */
 async function createSessionWithTimeout(copilotClient, sessionConfig, timeoutMs = CREATE_SESSION_TIMEOUT_MS) {
     let timer;
@@ -252,6 +254,9 @@ async function main() {
     catch (err) {
         log(`Initial prompt error after ${Date.now()}ms:`, err?.message, err?.stack?.substring(0, 300));
     }
+    // PID file paths — computed early so early-exit paths can clean up
+    const pidDir = path.join(workDir, 'logs');
+    const pidFile = path.join(pidDir, `${playerName || playerIdForWorkflow}.pid`);
     // Wait for the MCP server's workflow to register in Temporal.
     // We know the exact workflow ID because we pass CLAUDE_TEMPO_PLAYER_NAME to the
     // MCP server — no need for a time-window heuristic that could misidentify workflows.
@@ -277,6 +282,11 @@ async function main() {
         log(`ERROR: Workflow ${expectedWorkflowId} did not register within 30 seconds`);
         await session.disconnect();
         await copilotClient.stop();
+        // Clean up PID file to avoid stale entries in `claude-tempo status`
+        try {
+            fs.unlinkSync(pidFile);
+        }
+        catch { /* may not exist yet */ }
         process.exit(1);
     }
     log(`Workflow ready: ${expectedWorkflowId}`);
@@ -288,6 +298,15 @@ async function main() {
         log(`set_name completed in ${Date.now() - t0}ms`);
     }
     const MAESTRO_ACK = '\n\n[IMPORTANT: This message is from a human (Maestro). Immediately cue the sender back with a brief acknowledgment and your planned next step before doing the work.]';
+    // Write PID file so callers can find/kill orphaned bridge processes
+    try {
+        fs.mkdirSync(pidDir, { recursive: true });
+        fs.writeFileSync(pidFile, String(process.pid));
+        log(`PID file written: ${pidFile}`);
+    }
+    catch (err) {
+        log(`Warning: could not write PID file: ${err?.message}`);
+    }
     // Start message poller — inject messages into the Copilot session.
     // Tracks consecutive failures and attempts session recreation before giving up.
     let polling = true;
@@ -295,6 +314,36 @@ async function main() {
     let pollCount = 0;
     let consecutiveFailures = 0;
     let sessionRecreations = 0;
+    // interval declared here, assigned after poll is defined
+    let interval;
+    // Shared cleanup — disconnects session, removes PID file, stops client.
+    // `signalTermination` controls whether we also signal the workflow to terminate
+    // (skip if the workflow is already gone).
+    let shuttingDown = false;
+    const cleanup = async (signalTermination) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        polling = false;
+        clearInterval(interval);
+        if (signalTermination) {
+            try {
+                await handle.signal('updateMetadata', { status: 'terminated', terminatedBy: 'system' });
+            }
+            catch {
+                // workflow may already be gone
+            }
+        }
+        try {
+            await session.disconnect();
+        }
+        catch { /* already disconnected */ }
+        try {
+            fs.unlinkSync(pidFile);
+        }
+        catch { /* already gone */ }
+        await copilotClient.stop();
+    };
     /** Attempt to recreate the Copilot session after repeated failures. */
     async function recreateSession() {
         sessionRecreations++;
@@ -326,6 +375,24 @@ async function main() {
             const silenceSec = ((Date.now() - lastEventTime) / 1000).toFixed(0);
             log(`[health] poll #${pollCount}, sessionAlive=${sessionAlive}, lastEvent=${lastEventType} ${silenceSec}s ago`);
         }
+        // Periodic workflow status check — detect external termination/completion
+        if (pollCount % WORKFLOW_STATUS_CHECK_INTERVAL === 0) {
+            try {
+                const desc = await handle.describe();
+                const wfStatus = desc.status.name;
+                if (wfStatus !== 'RUNNING') {
+                    log(`Workflow status is ${wfStatus} — exiting cleanly`);
+                    await cleanup(false); // workflow already gone, don't signal
+                    process.exit(0);
+                }
+            }
+            catch (err) {
+                // If we can't describe (e.g., workflow not found), it was likely terminated
+                log(`Workflow describe failed: ${err?.message} — treating as terminated`);
+                await cleanup(false);
+                process.exit(0);
+            }
+        }
         try {
             const messages = await handle.query('pendingMessages');
             if (messages.length === 0)
@@ -365,49 +432,18 @@ async function main() {
                 const recovered = await recreateSession();
                 if (!recovered) {
                     log('ERROR: Session recovery failed. Shutting down bridge.');
-                    polling = false;
-                    clearInterval(interval);
+                    await cleanup(true);
                     process.exit(2);
                 }
             }
         }
     };
-    const interval = setInterval(poll, POLL_INTERVAL_MS);
+    interval = setInterval(poll, POLL_INTERVAL_MS);
     log('Message poller started. Bridge is running.');
-    // Write PID file so callers can find/kill orphaned bridge processes
-    const pidDir = path.join(workDir, 'logs');
-    const pidFile = path.join(pidDir, `${playerName || playerIdForWorkflow}.pid`);
-    try {
-        fs.mkdirSync(pidDir, { recursive: true });
-        fs.writeFileSync(pidFile, String(process.pid));
-        log(`PID file written: ${pidFile}`);
-    }
-    catch (err) {
-        log(`Warning: could not write PID file: ${err?.message}`);
-    }
-    // Graceful shutdown
+    // Graceful shutdown on SIGINT/SIGTERM — signal the workflow before exiting
     const shutdown = async () => {
-        log('Shutting down...');
-        polling = false;
-        clearInterval(interval);
-        try {
-            await handle.signal('updateMetadata', { status: 'terminated', terminatedBy: 'system' });
-        }
-        catch {
-            // workflow may already be gone
-        }
-        try {
-            await session.disconnect();
-        }
-        catch {
-            // session may already be disconnected
-        }
-        // Clean up PID file
-        try {
-            fs.unlinkSync(pidFile);
-        }
-        catch { /* may already be gone */ }
-        await copilotClient.stop();
+        log('Shutting down (signal received)...');
+        await cleanup(true);
         process.exit(0);
     };
     process.on('SIGINT', shutdown);

package/dist/server.js

@@ -255,7 +255,13 @@ async function main() {
         `Use \`ensemble\` to see who else is active. ` +
         `Use \`cue\` to reply directly to the player who messaged you, or to ask others for help. ` +
         `Use \`recruit\` if you need a session in a directory where none exists. ` +
-        `Use \`report\` to notify the conductor of task completion, blockers, or questions — always report when you finish a recruited task.`;
+        `Use \`report\` to notify the conductor of task completion, blockers, or questions — always report when you finish a recruited task.` +
+        (isConductor
+            ? `\n\nOperational rules:\n` +
+                `- Before assigning parallel work on different branches, provision git worktrees via the \`worktree\` tool so each player has an isolated checkout.\n` +
+                `- No player should switch branches without your approval — if a player needs a different branch, provision a worktree for them.\n` +
+                `- Before shipping, verify the branch diff scope matches the assigned task (no unrelated changes).`
+            : `\n\nDo not switch git branches without the conductor's approval. If no conductor exists, broadcast your intent to the ensemble first. Prefer using the \`worktree\` tool for branch isolation.`);
     const mcpServer = new mcp_js_1.McpServer({
         name: 'claude-tempo',
         version: PKG_VERSION,

package/dist/tools/ensemble.js

@@ -36,53 +36,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerEnsembleTool = registerEnsembleTool;
 const zod_1 = require("zod");
 const os = __importStar(require("os"));
+const resolve_1 = require("../activities/resolve");
 const helpers_1 = require("./helpers");
 function registerEnsembleTool(server, client, config, getPlayerId, ownWorkflowId) {
     (0, helpers_1.defineTool)(server, 'ensemble', `Discover active Claude Code sessions in the "${config.ensemble}" ensemble. Returns player IDs, descriptions, and metadata.`, {
         scope: zod_1.z.string().optional().describe('Filter scope: "machine" (same hostname), "repo" (same git root), "all" (default). All scopes are within the current ensemble.'),
     }, async (args) => {
         const scope = (args.scope ?? 'all');
-        // List all running session workflows, then filter by ensemble using
-        // in-memory metadata queries. This avoids depending on custom search
-        // attributes which are eventually consistent and may be missing/stale.
-        const query = `WorkflowType = "claudeSessionWorkflow" AND ExecutionStatus = "Running"`;
-        const players = [];
+        let sessions;
         try {
-            for await (const workflow of client.workflow.list({ query })) {
-                try {
-                    const handle = client.workflow.getHandle(workflow.workflowId);
-                    const metadata = await handle.query('getMetadata');
-                    // Filter by ensemble
-                    if (metadata.ensemble !== config.ensemble)
-                        continue;
-                    // Filter by scope
-                    if (scope === 'machine' && metadata.hostname !== os.hostname())
-                        continue;
-                    if (scope === 'repo') {
-                        const ownHandle = client.workflow.getHandle(ownWorkflowId);
-                        const ownMeta = await ownHandle.query('getMetadata');
-                        if (metadata.gitRoot !== ownMeta.gitRoot)
-                            continue;
-                    }
-                    const part = await handle.query('getPart');
-                    players.push({
-                        playerId: metadata.playerId,
-                        part,
-                        hostname: metadata.hostname,
-                        workDir: metadata.workDir,
-                        gitRoot: metadata.gitRoot,
-                        gitBranch: metadata.gitBranch,
-                        isConductor: metadata.isConductor,
-                        agentType: metadata.agentType || 'claude',
-                        playerType: metadata.playerType,
-                        status: metadata.status,
-                        isYou: metadata.playerId === getPlayerId(),
-                    });
-                }
-                catch {
-                    // Workflow may have just completed — skip it
-                }
-            }
+            sessions = await (0, resolve_1.scanEnsembleSessions)(client, config.ensemble);
         }
         catch (err) {
             return {
@@ -90,6 +53,30 @@ function registerEnsembleTool(server, client, config, getPlayerId, ownWorkflowId
                 isError: true,
             };
         }
+        // Apply scope filters
+        let ownGitRoot;
+        if (scope === 'repo') {
+            try {
+                const ownHandle = client.workflow.getHandle(ownWorkflowId);
+                const ownMeta = await ownHandle.query('getMetadata');
+                ownGitRoot = ownMeta.gitRoot;
+            }
+            catch {
+                // Can't determine own git root — skip repo filtering
+            }
+        }
+        const players = sessions
+            .filter((s) => {
+            if (scope === 'machine' && s.hostname !== os.hostname())
+                return false;
+            if (scope === 'repo' && ownGitRoot && s.gitRoot !== ownGitRoot)
+                return false;
+            return true;
+        })
+            .map((s) => ({
+            ...s,
+            isYou: s.playerId === getPlayerId(),
+        }));
         if (players.length === 0) {
             return {
                 content: [{ type: 'text', text: 'No active sessions found.' }],

package/dist/types.d.ts

@@ -198,4 +198,47 @@ export interface ScheduleEntry {
     /** IANA timezone for cron evaluation (e.g., "America/New_York"). Defaults to UTC. */
     timezone?: string;
 }
+/** Snapshot of a player as seen by the Maestro workflow. */
+export interface MaestroPlayerInfo {
+    playerId: string;
+    part: string;
+    hostname: string;
+    workDir: string;
+    gitRoot?: string;
+    gitBranch?: string;
+    isConductor: boolean;
+    agentType: string;
+    playerType?: string;
+    status?: string;
+}
+/** An event generated by diffing consecutive Maestro snapshots. */
+export interface MaestroEvent {
+    type: 'player_joined' | 'player_left' | 'status_changed' | 'part_changed';
+    playerId: string;
+    timestamp: string;
+    oldValue?: string;
+    newValue?: string;
+}
+/** A command queued via the maestroSendCommand update, awaiting relay. */
+export interface MaestroPendingCommand {
+    id: string;
+    text: string;
+    source: string;
+    replyTo?: string;
+    createdAt: string;
+    status: 'pending' | 'delivered' | 'failed';
+    error?: string;
+}
+/** Input for the Maestro workflow. */
+export interface MaestroInput {
+    ensemble: string;
+    /** Restored from continue-as-new. */
+    players?: MaestroPlayerInfo[];
+    /** Restored from continue-as-new (ring buffer, max 200). */
+    events?: MaestroEvent[];
+    /** Restored from continue-as-new. */
+    pendingCommands?: MaestroPendingCommand[];
+    /** Refresh interval in milliseconds (default 10000). Lowered in tests. */
+    pollIntervalMs?: number;
+}
 export {};

package/dist/worker.js

@@ -45,6 +45,7 @@ const connection_1 = require("./connection");
 const connection_2 = require("./connection");
 const schedule_fire_1 = require("./activities/schedule-fire");
 const outbox_1 = require("./activities/outbox");
+const maestro_1 = require("./activities/maestro");
 const log = (...args) => console.error('[claude-tempo:worker]', ...args);
 const BUNDLE_PATH = path.resolve(__dirname, '..', 'workflow-bundle.js');
 async function getWorkflowBundle() {
@@ -73,6 +74,7 @@ async function createWorkers(config) {
     const client = new client_1.Client({ connection: clientConnection, namespace: config.temporalNamespace });
     const scheduleActivities = (0, schedule_fire_1.createScheduleActivities)(client);
     const outboxActivities = (0, outbox_1.createOutboxActivities)(client, config);
+    const maestroActivities = (0, maestro_1.createMaestroActivities)(client);
     const workflowBundle = await getWorkflowBundle();
     const SHUTDOWN_GRACE_TIME = '10s';
     const SHUTDOWN_FORCE_TIME = '15s';
@@ -85,6 +87,7 @@ async function createWorkers(config) {
         shutdownForceTime: SHUTDOWN_FORCE_TIME,
         activities: {
             ...scheduleActivities,
+            ...maestroActivities,
             // Shared-queue delivery activities (everything except spawnProcess)
             deliverCue: outboxActivities.deliverCue,
             deliverReport: outboxActivities.deliverReport,