claude-tempo 0.26.0 → 0.28.0-beta.1

package/CLAUDE.md

@@ -28,6 +28,8 @@ src/
 │   ├── mcp.ts         # MCP server registration helpers (init, global vs project)
 │   ├── output.ts      # Shared CLI output formatting helpers
 │   ├── preflight.ts   # Environment preflight checks
+│   ├── removed-verbs.ts # lookup table for the 10 CLI verbs removed in #288 — dispatches migration hints before loading Temporal surface
+│   ├── startup.ts     # auto-provisioning bootstrap state machine (#289) — six-step idempotent sequence used by bare `claude-tempo` invocation
 │   └── upgrade-command.ts # upgrade subcommand — crash-proof; dynamic-imports Temporal only for active-session warning
 ├── adapters/
 │   ├── README.md      # Adapter contract documentation
@@ -69,12 +71,11 @@ src/
 │   ├── worktree.ts / stage.ts / stages.ts / cancel-stage.ts
 │   ├── load-lineup.ts / save-lineup.ts / agent-types.ts / resolve.ts
 │   ├── set-name.ts / set-part.ts / who-am-i.ts / release.ts
-│   ├── pause-ensemble.ts / resume-ensemble.ts
+│   ├── pause.ts / play.ts / shutdown.ts / restore.ts
 │   ├── hosts.ts
 │   └── helpers.ts     # Zod/MCP tool registration wrapper
 ├── tui/
 │   ├── App.tsx / store.ts / commands.ts   # TUI root, state, slash commands
-│   ├── client.ts                          # Backward-compat shim → src/client/
 │   ├── components/    # Ink components — see docs/tui.md for inventory
 │   └── utils/         # format, platform, theme, fullscreen, history
 ├── utils/
@@ -106,6 +107,13 @@ npm test
 > surveys or migrations, always grep **both** `test/` and `tests/` or you will miss
 > mocks and assertions that only live in one directory.
 
+> **Test-only hooks live with the module they reset and follow the
+> `__<verb><Noun>ForTests` naming convention** — see
+> [docs/adr/0006-test-hooks-naming.md](docs/adr/0006-test-hooks-naming.md). The
+> double-underscore prefix telegraphs "test escape hatch, do not call from
+> production code"; the hook's doc-comment should restate that explicitly. Hooks
+> are never surfaced through barrels or `TempoClient`.
+
 See [docs/development.md](docs/development.md) for full setup (Temporal dev server command,
 daemon worker notes, `npx ts-node` dev runner).
 

package/README.md

@@ -59,11 +59,10 @@ claude-tempo up
 This starts Temporal, registers the MCP server, launches the daemon, and opens a conductor session. Then add players:
 
 ```bash
-claude-tempo start          # open a player session
 claude-tempo status         # see who's active
 ```
 
-Or ask the conductor to `recruit` players from inside Claude Code.
+Or use the TUI to recruit players, or ask the conductor to `recruit` from inside Claude Code.
 
 ### Manual setup
 
@@ -71,8 +70,7 @@ Or ask the conductor to `recruit` players from inside Claude Code.
 claude-tempo server         # start Temporal dev server
 claude-tempo init           # register MCP server globally
 claude-tempo preflight      # verify environment
-claude-tempo conduct        # start a conductor
-claude-tempo start          # start a player
+claude-tempo up             # launch conductor via auto-provisioning
 ```
 
 ## Upgrading
@@ -90,12 +88,15 @@ claude-tempo upgrade 0.22.0
 ## Stopping & Tear Down
 
 ```bash
-# Stop a specific player session
-claude-tempo stop my-ensemble player-name
+# Terminate all sessions in an ensemble
+claude-tempo destroy my-ensemble
 
 # Tear down everything (all sessions, schedulers, and Maestro workflows)
 claude-tempo down --all
 
+# Tear down and terminate all workflows in one step
+claude-tempo down --destroy -y
+
 # Stop the background daemon
 claude-tempo daemon stop
 ```
@@ -107,17 +108,17 @@ claude-tempo daemon stop
 ## Core Concepts
 
 - **Player** — A Claude Code session registered as a Temporal workflow
-- **Conductor** — An optional orchestration hub (one per ensemble); receives `report` calls and connects to external interfaces
+- **Conductor** — Required orchestration hub (one per ensemble); receives `report` calls and connects to external interfaces. Lineup schema enforces its presence.
 - **Ensemble** — A named group of players isolated from other ensembles; defaults to `default`
 - **Cue** — A message sent to a player by name via Temporal signal
 - **Lineup** — A YAML file that defines a full team and recruits them in one step
 - **Player Type** — A reusable agent definition (`.md` with YAML frontmatter) that gives a player a named role
 
-Players in one ensemble cannot see or message players in another:
+Players in one ensemble cannot see or message players in another. Launch `claude-tempo` to open the TUI and switch between ensembles, or target a specific ensemble directly:
 
 ```bash
-claude-tempo conduct frontend   # conduct the "frontend" ensemble
-claude-tempo start backend      # join the "backend" ensemble
+claude-tempo up frontend        # provision and launch conductor in "frontend"
+claude-tempo up backend         # provision and launch conductor in "backend"
 ```
 
 ## MCP Tools
@@ -139,17 +140,16 @@ Tools available inside Claude Code sessions connected to claude-tempo:
 ## CLI
 
 ```bash
-claude-tempo up [ensemble]      # first-time setup
-claude-tempo conduct [ensemble] # start a conductor
-claude-tempo start [ensemble]   # start a player
+claude-tempo                    # launch TUI (auto-provisions on first run)
+claude-tempo up [ensemble]      # provision infrastructure and launch conductor
+claude-tempo down [--destroy]   # tear down infrastructure (--destroy also terminates workflows)
 claude-tempo status [ensemble]  # list active sessions
+claude-tempo destroy <ensemble> # terminate all sessions in an ensemble
+claude-tempo restore <ensemble> # restore orphaned sessions on this host
 claude-tempo hosts              # list daemons polling this Temporal namespace (--all/--json)
-claude-tempo recall <name>      # read a player's message history (--limit/--offset/--preview/--from/--since/--include-sent/--json)
+claude-tempo recall <name>      # read a player's message history (--limit/--offset/--preview/--json)
 claude-tempo attachment-info <name> # inspect a session's phase, holder, lease, and heartbeat age
 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 (--release also releases held players)
-claude-tempo tui                # open the terminal UI
 claude-tempo daemon <sub>       # manage the worker daemon
 claude-tempo upgrade            # update to latest
 ```
@@ -240,7 +240,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`, `/go` (release held), `/pause`, `/resume`, and more; type `/help` for the full list
+- **Slash commands** — `/recruit`, `/status`, `/schedule`, `/gates`, `/stages`, `/worktree`, `/go` (release held), `/pause`, `/play`, `/shutdown`, `/restore`, `/home`, 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/tui.md](docs/tui.md)
@@ -249,10 +249,10 @@ The TUI provides a chat-focused shell for managing your ensemble:
 
 > **Experimental** — subject to breaking changes.
 
-GitHub Copilot CLI sessions can join an ensemble using `--agent copilot`:
+GitHub Copilot CLI sessions can join an ensemble using `--agent copilot`. Recruit one from the TUI:
 
-```bash
-claude-tempo start myband --agent copilot -n copilot-1
+```
+/recruit copilot-1 --agent copilot
 ```
 
 📖 [Copilot bridge setup and limitations → docs/copilot.md](docs/copilot.md)

package/dist/activities/outbox.js

@@ -575,15 +575,22 @@ function createOutboxActivities(client, config) {
                 // already exists at `~/.claude/projects/<encoded-path>/<uuid>.jsonl`
                 // ("Session ID already in use"). A prior failed spawn can leave that
                 // file behind, wedging every subsequent `fresh` restart that reuses the
-                // stored sessionId. Since `fresh` already skips `--resume`, we mint a
-                // new UUID and persist it on the target's metadata so later non-fresh
-                // restarts resume against the new transcript. Non-fresh restarts keep
-                // the stored sessionId for deterministic `--resume`.
-                let spawnSessionId = metadata.sessionId;
-                if (fresh) {
-                    spawnSessionId = crypto.randomUUID();
-                    await handle.signal(signals_1.updateMetadataSignal, { sessionId: spawnSessionId });
-                }
+                // stored sessionId.
+                //
+                // #306: `/restart` ALWAYS spawns a fresh Claude Code process — never
+                // `--resume <id>`. The transcript `.jsonl` for the prior `spawnSessionId`
+                // is NOT guaranteed to have been flushed to disk before the prior
+                // adapter was hard-terminated (Windows `taskkill /T /F` is synchronous
+                // and unconditional). Claude Code then errors out with "No conversation
+                // found with session ID" and the new terminal drops to shell.
+                //
+                // Context preservation is already handled by the Step 5 replay above —
+                // we re-send recent messages to the fresh session. That's authoritative;
+                // the session-id `--resume` path was only ever a bonus on top. So we
+                // mint a new UUID on every restart, persist it to metadata, and never
+                // pass `resume: true` to the spawn.
+                const spawnSessionId = crypto.randomUUID();
+                await handle.signal(signals_1.updateMetadataSignal, { sessionId: spawnSessionId });
                 // Issue #184: re-resolve on the invoker host against the session's
                 // workDir (NOT the daemon's process.cwd — daemon runs elsewhere than
                 // the session's project, so the project-tier lookup needs the session's
@@ -598,8 +605,9 @@ function createOutboxActivities(client, config) {
                             host: targetHost,
                             attachmentId: token.attachmentId,
                             runId: token.runId,
-                            resume: !fresh,
-                            ...(spawnSessionId ? { sessionId: spawnSessionId } : {}),
+                            // #306: `/restart` is always a fresh spawn (see comment above).
+                            resume: false,
+                            sessionId: spawnSessionId,
                             adapterId,
                             ...(resolved ? {
                                 agentDefinition: resolved.name,
@@ -608,7 +616,7 @@ function createOutboxActivities(client, config) {
                             } : {}),
                         }],
                 });
-                log(`Restart prepared for "${targetPlayerId}" — attachmentId=${token.attachmentId}, spawnEntryId=${spawnEntryId}, host=${targetHost}${fresh ? ` (fresh sessionId=${spawnSessionId})` : ''}`);
+                log(`Restart prepared for "${targetPlayerId}" — attachmentId=${token.attachmentId}, spawnEntryId=${spawnEntryId}, host=${targetHost}, fresh sessionId=${spawnSessionId}${fresh ? ' (context replay skipped)' : ''}`);
                 return { success: true };
             }
             catch (err) {

package/dist/adapters/base.d.ts

@@ -14,6 +14,35 @@
  */
 import type { Client, WorkflowHandle } from '@temporalio/client';
 import type { AdapterClass, AdapterDescriptor, AttachmentToken, AttachmentPhase, DetachReason } from '../types';
+/** Snapshot of adapter state included in every telemetry frame. */
+interface AdapterTelemetrySnapshot {
+    attachmentId: string | null;
+    workflowId: string | null;
+    runId: string | null;
+    heartbeatsSent: number;
+    phaseTicksDone: number;
+}
+/**
+ * Build the structured frame emitted by every lifecycle handler. Pure
+ * function — exposed for unit tests that don't want to spawn a child
+ * process.
+ */
+export declare function buildProcessTerminatingFrame(signal: string, errorMessage?: string, snapshot?: AdapterTelemetrySnapshot[]): string;
+/**
+ * Install the process-lifecycle telemetry handlers. Idempotent. Skipped
+ * by default in test environments (see {@link shouldInstallLifecycleTelemetry}).
+ *
+ * Production callers (and the first `startV2Lifecycle()` call on any
+ * adapter) invoke without arguments. Unit tests pass `{ force: true }`
+ * to bypass the env gate.
+ */
+export declare function installProcessLifecycleTelemetry(opts?: {
+    force?: boolean;
+}): void;
+/** Test-only — uninstall handlers + reset state. */
+export declare function _resetProcessLifecycleTelemetryForTest(): void;
+/** Test-only — direct access to the live-adapter set. */
+export declare function _liveAdaptersForTest(): ReadonlySet<BaseAttachment>;
 /**
  * Override bundle for the reconnect loop timing (#201). Production defaults are
  * tuned for laptop-sleep cycles (15-min elapsed budget, 10s base, 60s cap). Tests
@@ -124,6 +153,13 @@ export declare abstract class BaseAttachment {
     onPhaseChange(listener: (phase: AttachmentPhase) => void): () => void;
     /** Subscribe to lease-revocation events (§9.3 split-brain resolution). */
     onLeaseRevoked(listener: (reason: DetachReason) => void): () => void;
+    /**
+     * Hypothesis A telemetry — capture the adapter state included in
+     * process-lifecycle log frames. Public so the module-level
+     * `snapshotLiveAdapters()` helper can read private fields without an
+     * `any` cast; consumers other than the telemetry path should not call it.
+     */
+    _captureTelemetrySnapshot(): AdapterTelemetrySnapshot;
     /**
      * Subscribe to terminal events — `WorkflowNotFound` (§9.4) and phase `gone`.
      * Terminal fires at most once per instance. Subclasses stop delivery + exit.
@@ -216,7 +252,55 @@ export declare abstract class BaseAttachment {
      * once per terminal — not on every tick.
      */
     private findCanSuccessorRunId;
+    /**
+     * Fire the terminal hook — the adapter is going dark and won't recover.
+     *
+     * #258: emits a structured log line on every fire so the next post-CAN
+     * silence incident is unambiguous in logs. Pre-#258, a `fireTerminal`
+     * from an unexpected source (the root cause was a silent destroy from
+     * the reconnect-loop pre-check on a transient terminal-class error) was
+     * indistinguishable from process death in workflow history — both produced
+     * "no further heartbeats." The structured log includes:
+     *
+     *   - `reason` — the existing DetachReason
+     *   - `callsite` — the calling function or rationale (passed by every
+     *     callsite so the source is grep-able without parsing stack traces)
+     *   - `attachmentId` / `workflowId` / `runId` — for cross-referencing
+     *     against workflow history when bisecting an incident
+     *   - `heartbeatsSent` / `phaseTicksDone` — the existing #249 counters
+     *     so an operator can correlate "loop alive at N heartbeats, then
+     *     terminal fired at this callsite" without external context
+     *
+     * Idempotent — repeat calls (e.g. reconnect-exhausted re-fires after
+     * destroy) early-return without re-logging. The first fire wins.
+     */
     private fireTerminal;
+    /**
+     * #258 tiebreaker: confirm whether a workflow is genuinely terminal after
+     * the reconnect-loop pre-check threw a terminal-class error. Used to
+     * distinguish a real workflow-gone state from a transient gRPC /
+     * visibility-API blip that classified as terminal.
+     *
+     * Returns:
+     *  - `{ kind: 'running', statusName }` — workflow is alive (any
+     *    non-terminal status). Caller should treat the original error as
+     *    transient and continue the reconnect loop.
+     *  - `{ kind: 'terminal', statusName }` — workflow is in a terminal
+     *    status (`COMPLETED` / `FAILED` / `CANCELLED` / `TERMINATED` /
+     *    `CONTINUED_AS_NEW` / `TIMED_OUT`). Caller should fire destroy.
+     *  - `{ kind: 'describe-threw' }` — `describe()` itself failed. Treat
+     *    as terminal (fire destroy) — consistent with pre-#258 semantics
+     *    when classification is ambiguous, and avoids spinning forever on
+     *    a workflow we can't reach.
+     *  - `{ kind: 'timed-out' }` — `describe()` exceeded
+     *    {@link DESCRIBE_TIMEOUT_MS}. Treat as terminal (fire destroy) —
+     *    same rationale: prefer clean shutdown to a hung loop.
+     *
+     * The unpinned handle follows any CAN chain to the latest run, so
+     * `desc.status.name === 'CONTINUED_AS_NEW'` here means the workflow
+     * id itself is closed (no successor) — genuinely terminal.
+     */
+    private confirmWorkflowTerminal;
     /**
      * Opt-in reconnect policy. Default: return `false` — the base class behaves
      * exactly as it did before #201 (fire terminal, tear down). Subclasses that