claude-tempo 0.26.0-beta.7 → 0.27.0

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,7 +71,8 @@ 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
@@ -78,6 +81,8 @@ src/
 │   └── utils/         # format, platform, theme, fullscreen, history
 ├── utils/
 │   ├── validation.ts / worktree.ts / safe-path.ts / duration.ts / search-attributes.ts
+│   ├── attachment-format.ts / recall-format.ts   # Shared display formatters (attachment-info, recall)
+│   ├── hosts.ts / format-hosts.ts                # Host enumeration + shared hosts display formatter (#274)
 ├── types.ts           # Shared type definitions
 ├── git-info.ts        # Git repository detection helper
 └── config.ts          # Env var handling
@@ -118,11 +123,12 @@ daemon worker notes, `npx ts-node` dev runner).
 - **Outbox**: Outbound requests (cue, report, recruit, restart, detach, destroy, …) go through the session's workflow outbox instead of directly signaling other workflows. The dispatch loop processes entries via activities, decoupling tools from cross-workflow signaling.
 - **Attachment phase** (v0.26): Seven phases tracked on the session workflow — `booting → attached → processing | awaiting → draining → detached → gone`. The phase is authoritative for lifecycle truth: adapters drive it via `claimAttachment` / `adapterExited` / `forceDetach` / `destroy`, and the workflow publishes it on the `ClaudeTempoAttachmentState` search attribute. Replaced the v0.25 `ClaudeTempoStatus` heuristic (removed in v0.26). See [docs/concepts.md](docs/concepts.md) for the phase table and [docs/ops/v0.26-migration.md](docs/ops/v0.26-migration.md) for the upgrade path.
 - **Adapter heartbeat observability** (#249): After `claimAttachment`, the base adapter logs `first heartbeat scheduled in Xms` then `heartbeat#1 delivered` on the first tick. Every 10 ticks it emits `heartbeats-delivered=N / phase-ticks=N` breadcrumbs. Any silent guard trip in `tickHeartbeat` / `tickPhaseWatcher` now emits a structured `guard tripped: {stopped, reconnecting, …}` log instead of silently orphaning the timer. The phase-watcher emits `WARNING: heartbeat staleness` when `lastHeartbeatAt` falls more than 2× `heartbeatMs` behind `now`. Grep `[claude-tempo:adapter]` to confirm loop health without parsing Temporal history.
-- **Per-host task queues**: `host` param on `recruit`/`restart`/`migrate` routes to `claude-tempo-{hostname}` task queue. See [docs/concepts.md](docs/concepts.md) for cross-machine recruiting details.
+- **Per-host task queues**: `host` param on `recruit`/`restart`/`migrate` routes to `claude-tempo-{hostname}` task queue. When `host` is set on `recruit`, a pre-flight check validates the target daemon is live and supports the requested agent type (`force: true` bypasses). Daemon boot profiles (hostname, platform, available player types) are advertised via the `hostProfile` signal and maintained in the global maestro's `hostProfiles` map — surfaced by the `hosts` MCP tool, `claude-tempo hosts` CLI, and `/hosts` TUI command (#274). See [docs/concepts.md](docs/concepts.md) for cross-machine recruiting details.
 - **Wire protocol**: All signal/query/update names are documented in [`docs/WIRE-PROTOCOL.md`](docs/WIRE-PROTOCOL.md) and are stable — renaming or removing any is a breaking change. **Process**: update `docs/WIRE-PROTOCOL.md` in the same commit as any new signal, query, or update.
 - **Daemon**: Standalone background process (`src/daemon.ts`) that runs all Temporal workers. Auto-started by any `claude-tempo` command. PID at `~/.claude-tempo/daemon.pid`; logs at `~/.claude-tempo/daemon.log`.
 - **Player types**: Reusable agent definitions in Claude Code's subagent format (`.md` files with YAML frontmatter). Three-tier lookup: project `.claude/agents/` → user `~/.claude/agents/` → shipped `examples/agents/`. Discover via `agent_types` tool or `claude-tempo agent-types` CLI. Shipped types: tempo-conductor, tempo-composer, tempo-soloist, tempo-tuner, tempo-critic, tempo-roadie, tempo-improv, tempo-liner.
 - **Lineup examples**: Four pre-built ensemble YAML files in `examples/ensembles/` — `tempo-big-band`, `tempo-dev-team`, `tempo-review-squad`, `tempo-jam-session`. Load with `claude-tempo up --lineup <name>` or the `load_lineup` tool.
+- **GitHub App identity** (`claude-tempo[bot]`): When a player writes to GitHub — issue comments, PR creation/merge, commits, labels, check runs — **use `./scripts/ensemble-gh`** instead of `gh`. The wrapper mints a short-lived installation token so the action is attributed to `claude-tempo[bot]`, not to the human maintainer, making the AI authorship visible. Plain `gh` is still correct for read-only local dev (`gh pr view`, `gh repo clone`, `gh auth status`). Every bot-authored comment/PR body must include the AI attribution footer documented in [docs/github-app.md](docs/github-app.md).
 
 See [docs/concepts.md](docs/concepts.md) for the full glossary (Adapter, Attachment phases, Restart, Detach/Destroy, Migrate, Broadcast, Recall, Schedule, Lineup, Quality Gate, Worktree, Stage, Hold/Release, Pause/Resume, Maestro, TempoClient, and more).
 

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,16 +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 recall <name>      # read a player's message history (--limit/--offset/--preview/--from/--since/--include-sent/--json)
+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/--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
 ```
@@ -239,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)
@@ -248,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/cli/commands.d.ts

@@ -1,28 +1,5 @@
 import { CliOverrides } from '../config';
 import { AgentType } from '../types';
-interface StartOpts extends CliOverrides {
-    ensemble: string;
-    conductor: boolean;
-    replace?: boolean;
-    resume?: boolean;
-    name?: string;
-    skipPreflight?: boolean;
-    agent: AgentType;
-    dir?: string;
-    /**
-     * Issue #172: `conduct --lineup <name>` — load a lineup during conductor
-     * startup and apply the same initial-startup semantics as `up --lineup`:
-     * conductor instructions deferred, players held, banner shown. Only
-     * meaningful when `conductor: true`.
-     */
-    lineup?: string;
-    /**
-     * Issue #172: opt out of the defer-conductor-instructions behavior.
-     * Forces the legacy immediate-start path even on `conduct --lineup`.
-     */
-    noHold?: boolean;
-}
-export declare function start(opts: StartOpts): Promise<void>;
 interface StatusOpts extends CliOverrides {
     ensemble?: string;
 }
@@ -50,24 +27,16 @@ interface UpOpts extends CliOverrides {
 }
 export declare function up(opts: UpOpts): Promise<void>;
 interface DownOpts extends CliOverrides {
-    /** Explicitly specified ensemble name. If undefined, auto-detect from running workflows. */
-    ensemble?: string;
-    all: boolean;
     removeMcp: boolean;
     keepDaemon: boolean;
     yes: boolean;
+    /** When true, terminate every workflow across every ensemble before
+     *  stopping infra. Without it, workflows stay on the Temporal server and
+     *  resume on the next `up`. */
+    destroy: boolean;
     dir: string;
 }
 export declare function down(opts: DownOpts): Promise<void>;
-interface StopOpts extends CliOverrides {
-    /** Stop a specific player by name. */
-    name?: string;
-    /** Stop all sessions in this ensemble. */
-    ensemble?: string;
-    /** Stop every session across all ensembles. */
-    all?: boolean;
-}
-export declare function stop(opts: StopOpts): Promise<void>;
 interface AgentTypesCommandOpts {
     subcommand?: string;
     name?: string;
@@ -84,28 +53,42 @@ interface VerbOpts extends CliOverrides {
     name: string;
     ensemble?: string;
 }
-interface RestartCliOpts extends VerbOpts {
-    host?: string;
-    fresh?: boolean;
-    force?: boolean;
-    contextMessages?: number;
-    /** PR-F: required when force-restarting a session attached to a different host. */
-    yesSteal?: string;
-}
-interface DetachCliOpts extends VerbOpts {
-    deadlineMs?: number;
-}
-interface DestroyCliOpts extends VerbOpts {
-    reason?: string;
-}
-interface MigrateCliOpts extends RestartCliOpts {
-    host: string;
+interface DestroyCliOpts extends CliOverrides {
+    ensemble: string;
+    yes: boolean;
 }
-export declare function restart(opts: RestartCliOpts): Promise<void>;
-export declare function detach(opts: DetachCliOpts): Promise<void>;
+/**
+ * `claude-tempo destroy <ensemble> [-y]` — terminate every workflow in an
+ * ensemble (#288). Prompts with the ensemble name and workflow count unless
+ * `-y` is passed. The per-player destroy path lives in the TUI (`/destroy
+ * --player`).
+ */
 export declare function destroy(opts: DestroyCliOpts): Promise<void>;
-export declare function migrate(opts: MigrateCliOpts): Promise<void>;
 export declare function attachmentInfo(opts: VerbOpts): Promise<void>;
+export interface HostsCliOpts extends CliOverrides {
+    ensemble?: string;
+    /** Include stale hosts (those not seen in the last minute). CLI default: false. */
+    all?: boolean;
+    /** Emit raw `HostInfo[]` JSON instead of the formatted table. */
+    json?: boolean;
+}
+export declare function hosts(opts: HostsCliOpts): Promise<void>;
+export interface RefreshHostProfileCliOpts extends CliOverrides {
+    ensemble?: string;
+    /** Max wait for the new profile to appear in the maestro `hostProfiles` map. Default 10s. */
+    confirmTimeoutMs?: number;
+}
+/**
+ * #274 AC5d (M12) — manual re-signal of this host's profile to the
+ * global maestro. The daemon otherwise only re-signals on boot; this
+ * subcommand re-computes the profile + signals fresh.
+ *
+ * Exit semantics (per my implementation-time call to the conductor,
+ * approved): await ensureGlobalMaestro → signal → short poll on
+ * `hostProfiles()` to confirm the new version is visible → exit 0.
+ * Exits nonzero if the poll timeout elapses without confirmation.
+ */
+export declare function refreshHostProfile(opts: RefreshHostProfileCliOpts): Promise<void>;
 export interface RecallCliOpts extends VerbOpts {
     limit?: number;
     offset?: number;
@@ -118,16 +101,15 @@ export interface RecallCliOpts extends VerbOpts {
 }
 export declare function recall(opts: RecallCliOpts): Promise<void>;
 interface RestoreCliOpts extends CliOverrides {
-    /** Specific player name to restore. Omitted means "interactive picker". */
-    name?: string;
-    ensemble?: string;
-    /** Restore every orphan in the namespace, respecting allowlist. */
-    all?: boolean;
-    /** Filter to orphans whose `preferredHost` matches this value. */
-    fromHost?: string;
-    /** List candidates without restoring. */
-    dryRun?: boolean;
+    ensemble: string;
 }
+/**
+ * `claude-tempo restore <ensemble>` — delegate to {@link TempoClient.restore},
+ * which reattaches orphans AND unpauses maestro + scheduler (#298 — the
+ * direct-to-`restoreOrphansOnce` path left the ensemble paused after a
+ * `shutdown → restore` roundtrip). The TUI home view (#290) is the picker
+ * surface; the CLI is the scriptable bulk operation, one ensemble at a time.
+ */
 export declare function restore(opts: RestoreCliOpts): Promise<void>;
 interface EnsembleCommandOpts extends CliOverrides {
     subcommand?: string;
@@ -139,14 +121,4 @@ interface ReleaseOpts extends CliOverrides {
 }
 /** Release all held sessions in an ensemble (unlock outbox, deliver initial messages). */
 export declare function release(opts: ReleaseOpts): Promise<void>;
-interface PauseResumeOpts extends CliOverrides {
-    ensemble: string;
-    /** Issue #172: when true on `resume`, also fan out `releaseHeldSignal` to every
-     *  session so deferred task messages are delivered and outboxes unlocked in one shot. */
-    release?: boolean;
-}
-/** Pause an entire ensemble — sessions, scheduler, and maestro. */
-export declare function pause(opts: PauseResumeOpts): Promise<void>;
-/** Resume an entire ensemble — sessions, scheduler, and maestro. */
-export declare function resume(opts: PauseResumeOpts): Promise<void>;
 export {};