claude-tempo 0.15.0 → 0.16.1

package/README.md

@@ -478,6 +478,8 @@ claude-tempo <command> [options]
 | `stop [ensemble]` | Stop sessions (`-n <name>` for one, `--all` for everything) |
 | `init` | Register claude-tempo MCP server globally (`--project` for per-directory) |
 | `preflight` | Run environment checks |
+| `broadcast <msg>` | Send a message to all active players. Use `--type` to filter by player type, `--include-stale` to include stale sessions. |
+| `encore <name>` | Revive a stale player session by name. Use `--host` to target a remote machine. |
 | `ensemble <sub>` | Manage saved lineups (`save`, `list`, `show`) |
 | `agent-types <sub>` | Manage player types (`list`, `show <name>`, `init`) |
 | `version` | Print the installed version |

package/dist/activities/outbox.d.ts

@@ -46,6 +46,8 @@ export interface SpawnProcessInput {
     nativeResolvable?: boolean;
     /** When true, use --resume instead of -n (reconnect to existing session). */
     resume?: boolean;
+    /** Claude Code session UUID for --session-id (new sessions) or --resume (encore). */
+    claudeSessionId?: string;
     /** Tool restrictions from the agent definition frontmatter. */
     allowedTools?: string[];
 }
@@ -64,6 +66,8 @@ export interface EncoreResult {
     agentDefinitionPath?: string;
     nativeResolvable?: boolean;
     allowedTools?: string[];
+    /** Claude Code session UUID for deterministic --resume. */
+    claudeSessionId?: string;
     temporalAddress: string;
     temporalNamespace: string;
 }
@@ -71,11 +75,15 @@ export interface OutboxActivityResult {
     success: boolean;
     error?: string;
 }
+export interface RecruitResult extends OutboxActivityResult {
+    /** Claude Code session UUID assigned at recruit time. */
+    claudeSessionId?: string;
+}
 export interface OutboxActivities {
     deliverCue(input: DeliverCueInput): Promise<OutboxActivityResult>;
     deliverReport(input: DeliverReportInput): Promise<OutboxActivityResult>;
     terminateSession(input: TerminateSessionInput): Promise<OutboxActivityResult>;
-    startRecruitedSession(input: StartRecruitedSessionInput): Promise<OutboxActivityResult>;
+    startRecruitedSession(input: StartRecruitedSessionInput): Promise<RecruitResult>;
     spawnProcess(input: SpawnProcessInput): Promise<OutboxActivityResult>;
     performEncore(input: PerformEncoreInput): Promise<EncoreResult>;
 }

package/dist/activities/outbox.js

@@ -98,6 +98,8 @@ function createOutboxActivities(client, config) {
                     ? (0, config_1.conductorWorkflowId)(ensemble)
                     : (0, config_1.sessionWorkflowId)(ensemble, targetName);
                 const { gitRoot, gitBranch } = (0, git_info_1.getGitInfo)(workDir);
+                // Generate a UUID for the Claude Code session — used for deterministic --resume on encore
+                const claudeSessionId = crypto.randomUUID();
                 const sessionInput = {
                     metadata: {
                         playerId: targetName,
@@ -109,6 +111,7 @@ function createOutboxActivities(client, config) {
                         isConductor,
                         agentType: agent,
                         status: 'pending',
+                        claudeSessionId,
                         ...(agentDefinition ? { playerType: agentDefinition } : {}),
                         ...(agentDefinitionDescription ? { playerTypeDescription: agentDefinitionDescription } : {}),
                         recruitedBy: fromPlayerId,
@@ -137,15 +140,15 @@ function createOutboxActivities(client, config) {
                         ClaudeTempoPlayerId: [targetName],
                     },
                 });
-                log(`Pre-created workflow ${workflowId} for recruit "${targetName}"`);
-                return { success: true };
+                log(`Pre-created workflow ${workflowId} for recruit "${targetName}" (sessionId=${claudeSessionId})`);
+                return { success: true, claudeSessionId };
             }
             catch (err) {
                 throw activity_1.ApplicationFailure.nonRetryable(`Failed to start recruited session "${targetName}": ${err instanceof Error ? err.message : String(err)}`);
             }
         },
         async spawnProcess(input) {
-            const { targetName, workDir, isConductor, agent, systemPrompt, ensemble, temporalAddress, temporalNamespace, agentDefinition, agentDefinitionPath, nativeResolvable, resume, allowedTools } = input;
+            const { targetName, workDir, isConductor, agent, systemPrompt, ensemble, temporalAddress, temporalNamespace, agentDefinition, agentDefinitionPath, nativeResolvable, resume, claudeSessionId, allowedTools } = input;
             // Read secrets from the worker's config closure — never from workflow state
             const { temporalApiKey, temporalTlsCertPath, temporalTlsKeyPath } = config;
             try {
@@ -178,8 +181,12 @@ 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];
+                    // Use --resume for encore (reconnect to existing session) or -n for new sessions.
+                    // For encore: use UUID for deterministic --resume (no interactive picker).
+                    // For new sessions: use --session-id to track the UUID for future encores.
+                    const nameArgs = resume
+                        ? ['--resume', claudeSessionId || targetName]
+                        : ['-n', targetName, ...(claudeSessionId ? ['--session-id', claudeSessionId] : [])];
                     // Build --allowedTools flag from agent definition frontmatter
                     const allowedToolsFlags = allowedTools && allowedTools.length > 0
                         ? ['--allowedTools', ...allowedTools]
@@ -280,6 +287,7 @@ function createOutboxActivities(client, config) {
                     agentDefinitionPath,
                     nativeResolvable,
                     allowedTools,
+                    claudeSessionId: metadata.claudeSessionId || undefined,
                     temporalAddress: config.temporalAddress,
                     temporalNamespace: config.temporalNamespace,
                 };

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 export type AgentType = 'claude' | 'copilot';
-export type SessionStatus = 'active' | 'stale' | 'pending' | 'terminated';
+export type SessionStatus = 'active' | 'stale' | 'pending' | 'terminated' | 'blocked';
 export interface SessionMetadata {
     playerId: string;
     ensemble: string;
@@ -18,6 +18,8 @@ export interface SessionMetadata {
     recruitedBy?: string;
     /** Worktree path if this session was spawned in an isolated worktree. */
     worktreePath?: string;
+    /** Claude Code session UUID — used for deterministic --resume on encore. */
+    claudeSessionId?: string;
 }
 export interface AgentTypeInfo {
     name: string;

package/dist/utils/validation.d.ts

@@ -32,13 +32,15 @@ export declare const GATE_CRITERION_TEXT_MAX = 512;
 export declare const GATE_NOTES_MAX = 1024;
 /** Timeout for npm install in worktrees (60s). */
 export declare const WORKTREE_INSTALL_TIMEOUT = 60000;
+/** Window for blocked session detection (5 minutes). */
+export declare const BLOCKED_WINDOW_MS: number;
 /** 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. */
 export declare const PREVIEW_MAX_LENGTH = 200;
 /**
  * Whether a session should be included in a broadcast based on its status.
- * Always excludes pending and terminated. Excludes stale unless includeStale is true.
+ * Always excludes pending, terminated, and blocked. Excludes stale unless includeStale is true.
  */
 export declare function shouldIncludeInBroadcast(status: string | undefined, includeStale: boolean): boolean;
 /** Validate a player name string. Returns an error message or null if valid. */

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.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.PREVIEW_MAX_LENGTH = exports.ENCORE_DEFAULT_CONTEXT_MESSAGES = exports.BLOCKED_WINDOW_MS = 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;
@@ -38,17 +38,19 @@ exports.GATE_CRITERION_TEXT_MAX = 512;
 exports.GATE_NOTES_MAX = 1024;
 /** Timeout for npm install in worktrees (60s). */
 exports.WORKTREE_INSTALL_TIMEOUT = 60000;
+/** Window for blocked session detection (5 minutes). */
+exports.BLOCKED_WINDOW_MS = 5 * 60 * 1000;
 /** Default number of recent messages to include as context in an encore. */
 exports.ENCORE_DEFAULT_CONTEXT_MESSAGES = 10;
 /** Maximum length for message preview truncation. */
 exports.PREVIEW_MAX_LENGTH = 200;
 /**
  * Whether a session should be included in a broadcast based on its status.
- * Always excludes pending and terminated. Excludes stale unless includeStale is true.
+ * Always excludes pending, terminated, and blocked. Excludes stale unless includeStale is true.
  */
 function shouldIncludeInBroadcast(status, includeStale) {
     const s = status || 'active';
-    if (s === 'pending' || s === 'terminated')
+    if (s === 'pending' || s === 'terminated' || s === 'blocked')
         return false;
     if (s === 'stale' && !includeStale)
         return false;

package/dist/workflows/session.js

@@ -26,6 +26,7 @@ async function claudeSessionWorkflow(input) {
     (0, workflow_1.patched)('v0.11-check-and-set-status');
     (0, workflow_1.patched)('v0.13-quality-gates');
     (0, workflow_1.patched)('v0.14-worktrees');
+    (0, workflow_1.patched)('v0.15-blocked-detection');
     // Ensure search attributes are always current — critical when reconnecting
     // via WorkflowIdConflictPolicy.USE_EXISTING, which skips the attributes
     // passed to client.workflow.start().
@@ -43,6 +44,7 @@ async function claudeSessionWorkflow(input) {
     const sentMessages = input.sentMessages ?? [];
     const outbox = input.outbox ?? [];
     let lastActivityTime = Date.now();
+    let lastOutboundTime = Date.now();
     // ── Outbox Update + Query Handlers ──
     (0, workflow_1.setHandler)(signals_1.submitOutboxUpdate, (entryInput) => {
         const entry = {
@@ -66,6 +68,12 @@ async function claudeSessionWorkflow(input) {
             sentMessages.push({ id: entry.id, to: entry.targetPlayerId, text: '[encore requested]', timestamp: entry.createdAt });
         }
         lastActivityTime = Date.now();
+        lastOutboundTime = Date.now();
+        // Auto-recover from blocked when player sends outbound
+        if (input.metadata.status === 'blocked') {
+            input.metadata.status = 'active';
+            (0, workflow_1.upsertSearchAttributes)({ ClaudeTempoStatus: ['active'] });
+        }
         return entry.id;
     }, {
         validator: (entry) => {
@@ -89,6 +97,7 @@ async function claudeSessionWorkflow(input) {
     (0, workflow_1.setHandler)(signals_1.setPartSignal, (newPart) => {
         part = newPart;
         lastActivityTime = Date.now();
+        lastOutboundTime = Date.now();
     });
     (0, workflow_1.setHandler)(signals_1.setNameSignal, (newName) => {
         input.metadata.playerId = newName;
@@ -117,6 +126,8 @@ async function claudeSessionWorkflow(input) {
             input.metadata.playerTypeDescription = update.playerTypeDescription;
         if (update.worktreePath != null)
             input.metadata.worktreePath = update.worktreePath;
+        if (update.claudeSessionId != null)
+            input.metadata.claudeSessionId = update.claudeSessionId;
         if (update.status != null) {
             input.metadata.status = update.status;
             // Re-enable stale detection only when explicitly requested (server.ts sets this)
@@ -186,6 +197,9 @@ async function claudeSessionWorkflow(input) {
                 timestamp: new Date().toISOString(),
                 delivered: false,
             });
+            // Command processing counts as implicit outbound for blocked detection
+            lastActivityTime = Date.now();
+            lastOutboundTime = Date.now();
         });
         (0, workflow_1.setHandler)(signals_1.playerReportSignal, (report) => {
             reportHistory.push({
@@ -313,7 +327,7 @@ async function claudeSessionWorkflow(input) {
                         break;
                     case 'recruit': {
                         const tc = input.temporalConfig;
-                        await startRecruitedSession({
+                        const recruitResult = await startRecruitedSession({
                             ensemble: input.metadata.ensemble,
                             targetName: entry.targetName,
                             workDir: entry.workDir,
@@ -341,6 +355,7 @@ async function claudeSessionWorkflow(input) {
                             agentDefinition: entry.agentDefinition,
                             agentDefinitionPath: entry.agentDefinitionPath,
                             nativeResolvable: entry.nativeResolvable,
+                            claudeSessionId: recruitResult.claudeSessionId,
                             allowedTools: entry.allowedTools,
                         });
                         break;
@@ -367,6 +382,7 @@ async function claudeSessionWorkflow(input) {
                                 agentDefinitionPath: encoreResult.agentDefinitionPath,
                                 nativeResolvable: encoreResult.nativeResolvable,
                                 allowedTools: encoreResult.allowedTools,
+                                claudeSessionId: encoreResult.claudeSessionId,
                                 resume: true,
                             });
                         }
@@ -411,6 +427,16 @@ async function claudeSessionWorkflow(input) {
                 input.metadata.status = 'stale';
                 (0, workflow_1.upsertSearchAttributes)({ ClaudeTempoStatus: ['stale'] });
             }
+            // Detect blocked session: active session with messages delivered but no outbound
+            // activity for 5+ minutes. The session is alive but may be stuck or spinning.
+            const BLOCKED_WINDOW_MS = 5 * 60 * 1000;
+            const hasDeliveredMessages = messages.some((m) => m.delivered);
+            if (input.metadata.status === 'active' &&
+                hasDeliveredMessages &&
+                now - lastOutboundTime > BLOCKED_WINDOW_MS) {
+                input.metadata.status = 'blocked';
+                (0, workflow_1.upsertSearchAttributes)({ ClaudeTempoStatus: ['blocked'] });
+            }
             // Heartbeat: if no activity for 1 hour, inject a probe message.
             // If the session is alive, it will consume and deliver it.
             // If dead, stale detection will mark it on the next loop iteration.

package/dist/workflows/signals.d.ts

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

package/package.json

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