agent-tempo 1.4.2 → 1.5.0

package/CLAUDE.md

@@ -210,7 +210,7 @@ daemon worker notes, `npx ts-node` dev runner).
 - **Claude API adapter** (`agent: 'claude-api'`, #131): Headless adapter that drives sessions via the Anthropic Messages API (`@anthropic-ai/sdk`) — no terminal, no Claude Code CLI. Requires `ANTHROPIC_API_KEY` env var and the `@anthropic-ai/sdk` optional dependency. Default model `claude-opus-4-7` (overridable via `model` recruit arg or `CLAUDE_TEMPO_API_MODEL` env). Claude-API players have access to agent-tempo MCP tools (cue, report, recall, ensemble, …) but not file-edit/shell/web tools. See `src/adapters/claude-api/`.
 - **OpenCode adapter** (`agent: 'opencode'`, #449): Headless multi-provider adapter that drives sessions via [SST OpenCode](https://opencode.ai) as a managed subprocess — supports Anthropic, OpenAI, Bedrock, Vertex, Ollama, and ~70 other providers via OpenCode's `provider/model` selector. Requires OpenCode CLI (`npm install -g opencode-ai`) and the `@opencode-ai/sdk` optional dependency. Recruit with `model: 'provider/name'` (e.g. `'anthropic/claude-opus-4-7'`). Tool bridging is MCP-native — OpenCode spawns `dist/server.js` as its own stdio MCP child. Session state is persisted server-side by OpenCode; the adapter stashes the session id on workflow metadata for reconnect across `opencode serve` restarts. See `src/adapters/opencode/`.
 - **Claude Code headless adapter** (`agent: 'claude-code-headless'`, #520): Headless adapter that drives sessions via the official `claude` CLI as a per-turn `claude -p --output-format stream-json` subprocess. The whole point: turns bill against the host's existing Claude Code subscription extra-usage credits (Pro / Max plans) rather than a Console workspace API key — the only ToS-clean way for a third-party tool to tap that pool. Requires the `claude` binary on PATH AND a logged-in Claude Code session (`claude auth login`); recruit pre-flight rejects with an actionable error otherwise. Tool surface is the union of full Claude Code built-ins (Bash / Read / Write / Edit / Glob / Grep / WebSearch / WebFetch) and the agent-tempo MCP surface — registered via inline `--mcp-config` so `claude` spawns `dist/server.js` as its own MCP child (no in-process bridge). Recruit knobs: `permissionMode` (default `'acceptEdits'`) or `dangerouslySkipPermissions: true` (mutually exclusive). Sessions resume across restart via the existing `sessionId` metadata field — the same UUID is shared with the interactive `claude-code` adapter (per-cwd JSONL is per-cwd, not per-adapter). See `src/adapters/claude-code-headless/` and `examples/ensembles/tempo-headless-jam.yaml`.
-- **Pi adapter** (`agent: 'pi'`, #632 Phase 3a): Headless adapter that runs a Pi AI session as a first-class agent-tempo player — no terminal, no BaseAttachment. Recruit injects the Phase 2 `src/pi` extension into Pi's `createAgentSession`; the module-scope singleton owns claim/heartbeat/tools/cue pump (MD-D). Requires the `pi-ai` optional dependency (`npm install -g pi-ai`) on Node 22.19+. Optional `model: 'provider/model'` selector (e.g. `'anthropic/claude-opus-4-7'`, `'github-copilot/gpt-4o'`); absent → Pi's own default. MD-C tool-access policy: `toolAccess: 'restricted'` (default — Bash/shell/exec HARD-BLOCKED) | `'standard'` (scoped Bash) | `'full'` (unsandboxed; requires `force: true`). `noExtensions: true` closes the S2 exec-tool-bypass gap (no disk/package extensions load alongside the agent-tempo extension). See `src/adapters/pi/` and `src/pi/headless.ts`.
+- **Pi adapter** (`agent: 'pi'`, #632 / #666): Two modes. **(1) Interactive conductor** (#666): `agent-tempo up --agent pi --ensemble <name>` launches `pi` in a real terminal with the agent-tempo extension auto-loaded (`pi -e dist/pi/extension.js`); the Pi session self-bootstraps its Temporal workflow and attaches as a conductor/player — no separate recruiter step. From the TUI, `/recruit-conductor` relaunches the active ensemble's conductor — set `conductor.agent: pi` in that ensemble's lineup to make it a Pi conductor. Requires `@earendil-works/pi-coding-agent` on Node ≥ 22.19. Recommended: `ANTHROPIC_API_KEY` (without it the session falls back to Pi's own auth/default model). The `AGENT_TEMPO_*` env is auto-wired by `up`; power users can invoke the extension directly with `pi -e dist/pi/extension.js`. `--model provider/model` selector (e.g. `'github-copilot/gpt-4o'`) is a fast-follow. **(2) Headless player** (Phase 3a): `recruit` with `agent: 'pi'` — no terminal, no BaseAttachment; runs `createAgentSession` with an in-memory `SessionManager`; the module-scope singleton owns claim/heartbeat/tools/cue pump (MD-D). MD-C tool-access policy: `toolAccess: 'restricted'` (default — Bash/shell/exec HARD-BLOCKED) | `'standard'` (scoped Bash) | `'full'` (unsandboxed; requires `force: true`). `noExtensions: true` closes the S2 exec-tool-bypass gap. See `src/adapters/pi/` and `src/pi/headless.ts`.
 - **Mission-control Pi extension** (3f): An observer-only Pi extension that turns one interactive Pi TUI into a live ensemble board + operator controller. HTTP-drives the daemon — coarse ensemble view via `/v1/events/:ensemble` SSE + fine per-player tail via `/inner` (T3); operator controls (cue/pause/play/restart/destroy + gate arm/disarm/decide) POST to the daemon write surface using `AGENT_TEMPO_HTTP_ADMIN_TOKEN`. **Never claims attachment or registers as a player** — invisible to the ensemble. ~200ms render throttle from an in-memory `BoardModel`. Requires an interactive Pi session with `ctx.hasUI`. See `src/pi/mission-control/`.
 - **Mock adapter** (`agent: 'mock'`, dev mode only): Four modes: `echo` (echoes input), `scripted` (replays YAML scenario rules), `silent` (drains messages without replying — heartbeat-stale validation), `chaos` (probabilistic fail/crash injection via seeded PRNG). Only registered when `isDevMode()` is true; stripped from the npm tarball by `prepack`. See `src/adapters/mock/`.
 - **Saveable state** (#334, ADR 0011): Per-player curated state slots — the player itself decides what context survives a restart. Three MCP tools: `save_state` (owner-only write, max 4 slots × 32 KiB), `fetch_state` (read self or peer; audit identity recorded on each entry's `savedBy`), `clear_state` (owner-only). `restart` accepts `loadFromState: true | 'someKey'` to seed the new session from a saved-state slot instead of (or, with `transcript: 'replay'`, alongside) transcript replay. Saved-state delivery uses `from: 'self-restart'` as a stable system identity. Empty-slot fallback: graceful — falls through to transcript replay with a log line. See [docs/design/334-player-saveable-state.md](docs/design/334-player-saveable-state.md).

package/README.md

@@ -37,7 +37,7 @@ Each session registers as a **player** in Temporal. Players discover each other
 | 🖥️ **Terminal UI** | Chat-focused TUI with slash commands, overlays, and interactive wizards |
 | 🌐 **Cross-machine** | Any session that can reach your Temporal server can join the ensemble |
 | ⏸️ **Hold / Pause / Resume** | Pre-warm a full team before delivering tasks; pause and resume mid-session |
-| 🤖 **Headless adapters** | Copilot bridge, Claude API, OpenCode, Claude Code headless (`claude -p` — bills against your Claude Code subscription), and Pi AI — mix providers and headless agents in the same ensemble |
+| 🤖 **Headless adapters** | Copilot bridge, Claude API, OpenCode, Claude Code headless (`claude -p` — bills against your Claude Code subscription), and Pi AI (headless player or interactive conductor) — mix providers and headless agents in the same ensemble |
 
 ## Installation
 
@@ -261,6 +261,26 @@ GitHub Copilot CLI sessions can join an ensemble using `--agent copilot`. Recrui
 
 📖 [Copilot bridge setup and limitations → docs/copilot.md](docs/copilot.md)
 
+## Pi AI Integration
+
+Pi AI sessions can join an ensemble in two modes:
+
+**Interactive conductor** — launch Pi in a real terminal with the agent-tempo extension auto-loaded:
+
+```
+agent-tempo up --agent pi --ensemble <name>
+```
+
+The Pi session self-bootstraps its Temporal workflow and attaches as a conductor or player. The `AGENT_TEMPO_*` environment is wired automatically. For power users, the underlying extension path is `dist/pi/extension.js` — invoke directly with `pi -e dist/pi/extension.js`.
+
+From the TUI, `/recruit-conductor` relaunches the active ensemble's conductor — set `conductor.agent: pi` in that ensemble's lineup to make it a Pi conductor.
+
+**Prerequisites:** `@earendil-works/pi-coding-agent` on Node ≥ 22.19. Recommended: `ANTHROPIC_API_KEY` (without it the session falls back to Pi's own auth/default model).
+
+**Headless Pi players** — recruit as a background agent slot using `agent: 'pi'` (see [docs/design/pi-hardening-h1-h2-h3.md](docs/design/pi-hardening-h1-h2-h3.md)).
+
+📖 [Pi integration reference → docs/design/pi-hardening-h1-h2-h3.md](docs/design/pi-hardening-h1-h2-h3.md)
+
 ## Worker Daemon
 
 The daemon runs Temporal workers as a background process — it starts automatically on first use. Manage it explicitly with `agent-tempo daemon start|stop|status|logs`.

package/dashboard/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-tempo-dashboard",
   "private": true,
-  "version": "1.4.2",
+  "version": "1.5.0",
   "type": "module",
   "description": "Web dashboard for agent-tempo. Bundled into the npm package; served by the daemon at /dashboard/*.",
   "scripts": {

package/dist/cli/commands.js

@@ -62,6 +62,7 @@ const crypto_1 = require("crypto");
 const croner_1 = require("croner");
 const client_1 = require("@temporalio/client");
 const spawn_1 = require("../spawn");
+const probe_1 = require("../pi/probe");
 const config_1 = require("../config");
 const git_info_1 = require("../git-info");
 const connection_1 = require("../connection");
@@ -1163,8 +1164,9 @@ async function up(opts) {
     // outside dev mode so a mis-configured lineup doesn't spawn a real session
     // unexpectedly (mirrors the player-level guard at ~line 209).
     const conductorAgent = lineup?.conductor?.agent === 'copilot' ? 'copilot' :
-        lineup?.conductor?.agent === 'mock' && (0, config_1.isDevMode)() ? 'mock' :
-            opts.agent;
+        lineup?.conductor?.agent === 'pi' ? 'pi' :
+            lineup?.conductor?.agent === 'mock' && (0, config_1.isDevMode)() ? 'mock' :
+                opts.agent;
     // Step 5: Connect to Temporal and check for existing conductor
     console.log();
     const connection = await (0, connection_1.createTemporalConnection)(config);
@@ -1304,6 +1306,41 @@ async function up(opts) {
             workDir: process.cwd(),
         }));
     }
+    else if (conductorAgent === 'pi') {
+        // Interactive Pi conductor (#666). MUST launch `pi` in a REAL TERMINAL —
+        // Pi only fires session_start / attaches in a TTY (headless/print-mode does
+        // NOT). So this uses launchInTerminal, NOT spawnPiHeadless (that's recruited
+        // players). One branch serves `up --agent pi` AND TUI /recruit-conductor.
+        //
+        // PREFLIGHT — fail clean BEFORE launching a terminal that would die:
+        const nodeFloor = (0, probe_1.checkPiNodeFloor)(); // best-effort proxy on the daemon's Node
+        if (!nodeFloor.ok) {
+            out.error(`Cannot start Pi conductor — ${nodeFloor.reason}`);
+            process.exit(1);
+        }
+        if (!process.env.ANTHROPIC_API_KEY) {
+            out.warn('ANTHROPIC_API_KEY is not set — the Pi conductor will fall back to Pi\'s own auth/default model. Set it if Pi needs an Anthropic key.');
+        }
+        let piSpawn;
+        try {
+            // resolvePiInteractiveBinary / resolvePiExtensionPath throw fail-clean
+            // (Pi CLI missing / extension unbuilt) — caught here, no terminal launched.
+            piSpawn = (0, spawn_1.buildPiConductorSpawn)({
+                ensemble: opts.ensemble,
+                sessionName,
+                temporalEnvVars,
+                taskQueue: config.taskQueue,
+                devMode: (0, config_1.isDevMode)(),
+                conductorTypeName: resolvedConductorType?.name || conductorTypeName,
+                anthropicApiKey: process.env.ANTHROPIC_API_KEY,
+            });
+        }
+        catch (err) {
+            out.error(`Cannot start Pi conductor — ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        ({ pid } = (0, spawn_1.launchInTerminal)(piSpawn.cmd, piSpawn.args, process.cwd(), piSpawn.env));
+    }
     else {
         const claudeArgs = [
             '--dangerously-skip-permissions',

package/dist/pi/extension.d.ts

@@ -1,15 +1,57 @@
 import type { Client } from '@temporalio/client';
 import { type Config } from '../config';
 import type { ExtensionAPI, PiAgentSession } from './pi-types';
+import { PhaseDriver } from './phase-driver';
+import { PiWorkflowClient } from './workflow-client';
+import { CuePump } from './cue-pump';
+import { ResetPump } from './reset-pump';
+import { InnerLoopPublisher } from './inner-loop-publisher';
 /** Runtime mode. Headless = recruited unsupervised player (MD-C gate active). */
 export type PiExtensionMode = 'interactive' | 'headless';
 export type PiToolAccess = 'restricted' | 'standard' | 'full';
+/**
+ * B1 runtime guard (#645 H4) — the type gate's blind spot.
+ *
+ * `PiEventPayload.session` is UNDECLARED in Pi 0.78's `.d.ts` — it's an
+ * interactive-only RUNTIME field, so the pi-drift type gate can't assert it. In
+ * INTERACTIVE mode the `session_start` payload MUST carry `session` (the cue +
+ * reset pumps inject into it); a null session there means injection is silently
+ * inert — a likely Pi API drift. (Headless legitimately omits it — it wires
+ * `rt.session` via `setRuntimeSession` — so the guard is interactive-only.)
+ *
+ * Pure + injected `warn` so it unit-tests without the workflow harness.
+ */
+export declare function warnIfInteractiveSessionMissing(mode: PiExtensionMode, payload: {
+    session?: unknown;
+}, warn: (msg: string) => void): void;
 export interface PiExtensionOptions {
     /** Default `'interactive'`. Headless installs the MD-C tool_call gate. */
     mode?: PiExtensionMode;
     /** MD-C tool-class policy (headless only). Default `'restricted'`. */
     toolAccess?: PiToolAccess;
 }
+/**
+ * Per-PLAYER runtime — lives in the module-scope `runtimes` map and SURVIVES Pi
+ * extension-instance rebuilds. Holds the durable attachment (handle + lease +
+ * heartbeat, inside `wf`), the phase driver, the cue pump, and the session ptr.
+ */
+interface PiPlayerRuntime {
+    readonly workflowId: string;
+    readonly wf: PiWorkflowClient;
+    readonly driver: PhaseDriver;
+    readonly pump: CuePump;
+    /**
+     * 3c — inner-loop publisher: observes Pi events to maintain Tier-1 coarse state
+     * (sampled by the heartbeat via `wf.setCoarseProvider`) and forward Tier-2 fine
+     * frames to the daemon (presence-gated, off-wire). Started on first attach,
+     * stopped on teardown.
+     */
+    readonly pub: InnerLoopPublisher;
+    /** 3d D14 — polls the workflow's pending reset → clean-wipe (newSession) + ack. */
+    readonly reset: ResetPump;
+    session: PiAgentSession | null;
+    lastSessionId?: string;
+}
 /**
  * Build the Pi extension factory. `mode='headless'` installs the MD-C tool_call
  * gate; `mode='interactive'` (default) does not (the human owns their machine).
@@ -40,6 +82,18 @@ export declare function setRuntimeSession(workflowId: string, session: PiAgentSe
 export declare function __setPiClientFactoryForTests(factory: (config: Config) => Promise<Client>): void;
 /** Stop timers, clear the per-player runtime map + shared-client singletons + factory. */
 export declare function __resetPiRuntimesForTests(): void;
+/**
+ * Seed a fake runtime into the module-scope `runtimes` map. TEST ESCAPE HATCH —
+ * do NOT call from production code. The map is otherwise unreachable from a test;
+ * this is the seam for covering lifecycle paths like {@link detachAllPiRuntimesForExit}.
+ */
+export declare function __seedRuntimeForTests(workflowId: string, rt: PiPlayerRuntime): void;
+/**
+ * Clear the module-scope `runtimes` map WITHOUT timer/heartbeat teardown (for
+ * afterEach isolation in runtime-seeding tests; use {@link __resetPiRuntimesForTests}
+ * for the full singleton reset). TEST ESCAPE HATCH — do NOT call from production code.
+ */
+export declare function __clearRuntimesForTests(): void;
 /** Default export — interactive-mode extension (the human `pi` CLI entry). */
 declare const piExtension: (pi: ExtensionAPI) => void;
 export default piExtension;

package/dist/pi/extension.js

@@ -33,11 +33,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.warnIfInteractiveSessionMissing = warnIfInteractiveSessionMissing;
 exports.createPiExtension = createPiExtension;
 exports.detachAllPiRuntimesForExit = detachAllPiRuntimesForExit;
 exports.setRuntimeSession = setRuntimeSession;
 exports.__setPiClientFactoryForTests = __setPiClientFactoryForTests;
 exports.__resetPiRuntimesForTests = __resetPiRuntimesForTests;
+exports.__seedRuntimeForTests = __seedRuntimeForTests;
+exports.__clearRuntimesForTests = __clearRuntimesForTests;
 /**
  * agent-tempo Pi extension — interactive (Phase 2) + headless (Phase 3a) runtime.
  *
@@ -91,6 +94,24 @@ const log = (...args) => {
 };
 const nowIso = () => new Date().toISOString();
 const PI_AGENT_TYPE = 'claude'; // Pi is not yet a first-class AgentType.
+/**
+ * B1 runtime guard (#645 H4) — the type gate's blind spot.
+ *
+ * `PiEventPayload.session` is UNDECLARED in Pi 0.78's `.d.ts` — it's an
+ * interactive-only RUNTIME field, so the pi-drift type gate can't assert it. In
+ * INTERACTIVE mode the `session_start` payload MUST carry `session` (the cue +
+ * reset pumps inject into it); a null session there means injection is silently
+ * inert — a likely Pi API drift. (Headless legitimately omits it — it wires
+ * `rt.session` via `setRuntimeSession` — so the guard is interactive-only.)
+ *
+ * Pure + injected `warn` so it unit-tests without the workflow harness.
+ */
+function warnIfInteractiveSessionMissing(mode, payload, warn) {
+    if (mode === 'interactive' && payload.session == null) {
+        warn('WARNING: interactive session_start carried no session — cue/reset injection inert; ' +
+            'possible Pi API drift (#645)');
+    }
+}
 // MD-C shell/exec tool-class membership is owned by `tool-capability.ts`
 // (`classify(name) === 'exec'`, content signed off by tempo-security). F1
 // import-refactor (3d): this REPLACES the former local `SHELL_TOOL_NAMES` set —
@@ -282,6 +303,8 @@ function createPiExtension(options = {}) {
         }
         // ── Lifecycle: session_start → first attach OR re-bind ──
         pi.on('session_start', async (payload) => {
+            // B1 (#645 H4): warn loudly if interactive session_start lost its session.
+            warnIfInteractiveSessionMissing(mode, payload, log);
             try {
                 const rt = await attachOrRebind(payload);
                 await refreshSessionId(rt, rt.session?.id);
@@ -402,6 +425,22 @@ function __resetPiRuntimesForTests() {
     connectedClient = null;
     clientFactory = getSharedClient;
 }
+/**
+ * Seed a fake runtime into the module-scope `runtimes` map. TEST ESCAPE HATCH —
+ * do NOT call from production code. The map is otherwise unreachable from a test;
+ * this is the seam for covering lifecycle paths like {@link detachAllPiRuntimesForExit}.
+ */
+function __seedRuntimeForTests(workflowId, rt) {
+    runtimes.set(workflowId, rt);
+}
+/**
+ * Clear the module-scope `runtimes` map WITHOUT timer/heartbeat teardown (for
+ * afterEach isolation in runtime-seeding tests; use {@link __resetPiRuntimesForTests}
+ * for the full singleton reset). TEST ESCAPE HATCH — do NOT call from production code.
+ */
+function __clearRuntimesForTests() {
+    runtimes.clear();
+}
 /** Default export — interactive-mode extension (the human `pi` CLI entry). */
 const piExtension = createPiExtension();
 exports.default = piExtension;

package/dist/pi/pi-types.d.ts

@@ -37,13 +37,19 @@ export interface PiCustomMessageOptions {
      */
     deliverAs?: 'steer' | 'followUp';
 }
-/** A message injected into a live Pi session. */
+/**
+ * A message injected into a live Pi session. Real `sendCustomMessage` msg param =
+ * `Pick<CustomMessage, "customType" | "content" | "display" | "details">` — so
+ * `customType` + `display` are REQUIRED (C1, #645 H4). `content` is kept
+ * `string` (narrower than the real `string | (TextContent | ImageContent)[]`,
+ * still assignable — we only ever inject text).
+ */
 export interface PiOutboundMessage {
     /** Free-form tag Pi surfaces to the agent (we use `'cue'`). */
-    customType?: string;
+    customType: string;
     content: string;
     /** Render the injected content in the human-visible transcript. */
-    display?: boolean;
+    display: boolean;
 }
 /**
  * The live, human-attached agent session. `sendCustomMessage` is bound in the
@@ -73,7 +79,13 @@ export interface PiAgentSession {
  * RE-ACQUIRE the session from each payload (never cache across switches — D11).
  */
 export interface PiEventPayload {
-    /** The live session, present on most lifecycle events. */
+    /**
+     * UNDECLARED in Pi 0.78 `.d.ts` — an interactive-only RUNTIME field; headless
+     * populates `rt.session` via `setRuntimeSession` instead. NOT type-assertable,
+     * so the pi-drift gate EXCLUDES it (see test/pi-drift/assert.ts) and the
+     * runtime guard B1 (extension.ts) covers it: a null session on interactive
+     * `session_start` warns of possible Pi API drift.
+     */
     session?: PiAgentSession;
     /** A per-message/per-turn identifier when the event carries one. */
     messageId?: string;
@@ -90,7 +102,8 @@ export interface PiEventPayload {
 /**
  * Pi context-window usage — the PULL-only token signal (3c). There is NO token
  * event in Pi 0.78; usage is queried on demand via `ExtensionContext.getContextUsage()`.
- * Mirrors pi-ai's `ContextUsage` (verified against the installed 0.78 `.d.ts`).
+ * Mirrors `ContextUsage`, exported from `@earendil-works/pi-coding-agent`
+ * (extensions surface), NOT pi-ai (verified against the installed 0.78 `.d.ts`).
  */
 export interface PiContextUsage {
     /** Estimated context tokens in use, or `null` when unknown. */
@@ -205,6 +218,12 @@ export interface PiToolResult {
  */
 export interface PiToolDefinition {
     name: string;
+    /**
+     * Human-facing label. The real `ToolDefinition` REQUIRES `label` (C4, #645 H4);
+     * render-tools sets it to the tool name. Omitting it would RED the gate's
+     * ToolDefinition row.
+     */
+    label: string;
     description?: string;
     /** TypeBox schema object. Typed `unknown` to avoid coupling pi-types to typebox. */
     parameters: unknown;

package/dist/pi/render-tools.js

@@ -43,6 +43,8 @@ function renderToPi(pi, descriptors) {
     for (const d of descriptors) {
         pi.registerTool({
             name: d.name,
+            // Real ToolDefinition REQUIRES `label` (C4, #645 H4) — use the tool name.
+            label: d.name,
             description: d.description,
             parameters: (0, zod_to_typebox_1.zodShapeToTypeBox)(d.params, d.name),
             // Pi calls execute POSITIONALLY: (toolCallId, params, signal, onUpdate, ctx).

package/dist/spawn.d.ts

@@ -38,9 +38,12 @@ export declare function findLinuxTerminal(): string | null;
  * Build a shell command string that sets env vars and runs claude.
  * Uses inline `KEY=val` syntax which works in bash, zsh, AND fish.
  */
-export declare function buildClaudeCommand(claudeBin: string, claudeArgs: string[], envVars: Record<string, string>): string;
+export declare function buildTerminalCommand(bin: string, binArgs: string[], envVars: Record<string, string>): string;
 /**
- * Spawn a Claude Code session in a visible terminal window.
+ * Launch ANY binary in a visible terminal window (the cross-platform core
+ * extracted from `spawnInTerminal`, #666 C1). Generic over `bin`/`args` so it
+ * drives both Claude (via the {@link spawnInTerminal} wrapper) and the
+ * interactive Pi conductor (`pi -e <ext>`).
  *
  * Strategy per terminal:
  *  - Ghostty: `initial input` into a normal window (preserves full shell env)
@@ -49,11 +52,82 @@ export declare function buildClaudeCommand(claudeBin: string, claudeArgs: string
  *  - Windows: shell:true with env vars
  *  - Linux: terminal emulator with -e flag
  */
+export declare function launchInTerminal(bin: string, args: string[], workDir: string, envVars: Record<string, string>): {
+    pid: number | undefined;
+};
+/**
+ * Spawn a Claude Code session in a visible terminal window — a thin, unchanged
+ * wrapper over {@link launchInTerminal} (resolves the claude binary, forwards
+ * the rest). Signature preserved for the existing callers (commands.ts conductor
+ * + outbox.ts recruit-spawn) + the spawn-route regression tests (#666 C1).
+ */
 export declare function spawnInTerminal(claudeArgs: string[], workDir: string, envVars: Record<string, string>, options?: {
     claudeBin?: string;
 }): {
     pid: number | undefined;
 };
+/**
+ * Resolve the INTERACTIVE Pi CLI binary (#666) — the human-TTY `pi`, DISTINCT
+ * from {@link resolvePiPath} (the headless adapter entry). Interactive TTY mode
+ * is REQUIRED for a conductor: Pi only fires `session_start` / attaches in a real
+ * terminal (non-TTY / `--print` → print-mode → tools register but NO attach).
+ *
+ * `pi` on PATH wins; else fall back to the installed package CLI via `node`.
+ * THROWS fail-clean if neither resolves, so the caller never launches a terminal
+ * that would immediately die. Collaborators injectable for unit tests.
+ */
+export declare function resolvePiInteractiveBinary(deps?: {
+    onPath?: (bin: string) => boolean;
+    exists?: (p: string) => boolean;
+}): {
+    cmd: string;
+    args: string[];
+};
+/**
+ * Resolve the absolute path to the BUNDLED `dist/pi/extension.js` for `pi -e <abs>`
+ * (#666). Pi loads the BUILT CommonJS extension even in dev. Mirrors
+ * {@link resolvePiPath}'s dev/prod `__dirname` split: prod `__dirname` = `dist/`
+ * (→ `dist/pi/extension.js`); dev `__dirname` = `src/` (→ sibling `dist/pi/…`).
+ * Existence-checked + fail-clean ("run npm run build"). Injectable for tests.
+ */
+export declare function resolvePiExtensionPath(deps?: {
+    exists?: (p: string) => boolean;
+    isDev?: boolean;
+    baseDir?: string;
+}): string;
+/** Inputs for {@link buildPiConductorSpawn} (pure — unit-tested without spawning). */
+export interface PiConductorSpawnOpts {
+    ensemble: string;
+    sessionName: string;
+    /** Temporal env (address/namespace/api-key/tls) built by the caller. */
+    temporalEnvVars: Record<string, string>;
+    /** Temporal task queue — the Pi extension's PiWorkflowClient needs it (confirm #1). */
+    taskQueue: string;
+    devMode: boolean;
+    /** Conductor agent-type name → AGENT_TEMPO_PLAYER_TYPE, when typed. */
+    conductorTypeName?: string;
+    /** Forwarded if set (warn-not-fail upstream when unset). */
+    anthropicApiKey?: string;
+    /** Injectable resolvers (default to the real ones, which fail-clean on miss). */
+    resolveBinary?: () => {
+        cmd: string;
+        args: string[];
+    };
+    resolveExtension?: () => string;
+}
+/**
+ * Build the interactive Pi conductor spawn spec — `{ cmd, args, env }` for
+ * {@link launchInTerminal} (#666 C3). PURE + injectable so the env/args mapping is
+ * unit-tested. The default resolvers THROW fail-clean (binary missing / extension
+ * unbuilt) BEFORE a terminal is launched. `args` = `[...binArgs, '-e', <ext>]`;
+ * conductor INSTRUCTIONS arrive via the lineup-baked workflow messages → cue pump
+ * (no `--system-prompt` for the MVP).
+ */
+export declare function buildPiConductorSpawn(opts: PiConductorSpawnOpts): {
+    cmd: string;
+    args: string[];
+    env: Record<string, string>;
+};
 export interface CopilotBridgeOpts {
     name: string;
     ensemble: string;

package/dist/spawn.js

@@ -6,8 +6,12 @@ exports.shellQuote = shellQuote;
 exports.resolveClaudePath = resolveClaudePath;
 exports.detectMacTerminal = detectMacTerminal;
 exports.findLinuxTerminal = findLinuxTerminal;
-exports.buildClaudeCommand = buildClaudeCommand;
+exports.buildTerminalCommand = buildTerminalCommand;
+exports.launchInTerminal = launchInTerminal;
 exports.spawnInTerminal = spawnInTerminal;
+exports.resolvePiInteractiveBinary = resolvePiInteractiveBinary;
+exports.resolvePiExtensionPath = resolvePiExtensionPath;
+exports.buildPiConductorSpawn = buildPiConductorSpawn;
 exports.spawnCopilotBridge = spawnCopilotBridge;
 exports.spawnMockAdapter = spawnMockAdapter;
 exports.spawnClaudeApiAdapter = spawnClaudeApiAdapter;
@@ -234,17 +238,20 @@ function findLinuxTerminal() {
  * Build a shell command string that sets env vars and runs claude.
  * Uses inline `KEY=val` syntax which works in bash, zsh, AND fish.
  */
-function buildClaudeCommand(claudeBin, claudeArgs, envVars) {
+function buildTerminalCommand(bin, binArgs, envVars) {
     const envInline = Object.entries(envVars)
         .map(([k, v]) => `${k}=${shellQuote(v)}`)
         .join(' ');
     // Quote the binary path if it contains spaces (e.g., "C:\Program Files\...")
-    const quotedBin = claudeBin.includes(' ') ? shellQuote(claudeBin) : claudeBin;
-    const args = claudeArgs.map(a => shellQuote(a)).join(' ');
+    const quotedBin = bin.includes(' ') ? shellQuote(bin) : bin;
+    const args = binArgs.map(a => shellQuote(a)).join(' ');
     return envInline ? `${envInline} ${quotedBin} ${args}` : `${quotedBin} ${args}`;
 }
 /**
- * Spawn a Claude Code session in a visible terminal window.
+ * Launch ANY binary in a visible terminal window (the cross-platform core
+ * extracted from `spawnInTerminal`, #666 C1). Generic over `bin`/`args` so it
+ * drives both Claude (via the {@link spawnInTerminal} wrapper) and the
+ * interactive Pi conductor (`pi -e <ext>`).
  *
  * Strategy per terminal:
  *  - Ghostty: `initial input` into a normal window (preserves full shell env)
@@ -253,9 +260,14 @@ function buildClaudeCommand(claudeBin, claudeArgs, envVars) {
  *  - Windows: shell:true with env vars
  *  - Linux: terminal emulator with -e flag
  */
-function spawnInTerminal(claudeArgs, workDir, envVars, options) {
-    const claudeBin = resolveClaudePath(options?.claudeBin);
-    const claudeInvocation = buildClaudeCommand(claudeBin, claudeArgs, envVars);
+function launchInTerminal(bin, args, workDir, envVars) {
+    // Internal aliases keep the platform body below byte-identical to the original
+    // spawnInTerminal (behavior-preserving extraction, #666 C1 — minimal blast
+    // radius; the existing terminal-spawn tests are the proof). The terminal logic
+    // is bin/args-agnostic; the `claude*` names are historical.
+    const claudeBin = bin;
+    const claudeArgs = args;
+    const claudeInvocation = buildTerminalCommand(claudeBin, claudeArgs, envVars);
     if (process.platform === 'darwin') {
         const detected = detectMacTerminal();
         log(`Terminal detection: TERM_PROGRAM=${JSON.stringify(process.env.TERM_PROGRAM)}, detected=${detected}`);
@@ -414,6 +426,105 @@ function spawnInTerminal(claudeArgs, workDir, envVars, options) {
     child.unref();
     return { pid: child.pid };
 }
+/**
+ * Spawn a Claude Code session in a visible terminal window — a thin, unchanged
+ * wrapper over {@link launchInTerminal} (resolves the claude binary, forwards
+ * the rest). Signature preserved for the existing callers (commands.ts conductor
+ * + outbox.ts recruit-spawn) + the spawn-route regression tests (#666 C1).
+ */
+function spawnInTerminal(claudeArgs, workDir, envVars, options) {
+    return launchInTerminal(resolveClaudePath(options?.claudeBin), claudeArgs, workDir, envVars);
+}
+// --- Interactive Pi conductor (#666) ---
+/** Is `bin` resolvable on PATH? (where/which, mirrors resolveClaudePath.) */
+function binaryOnPath(bin) {
+    const cmd = process.platform === 'win32' ? 'where' : 'which';
+    try {
+        (0, child_process_1.execFileSync)(cmd, [bin], { stdio: ['ignore', 'ignore', 'ignore'] });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Walk up from `__dirname` for the installed Pi package's CLI entry. */
+function findPiPackageCli(exists) {
+    let dir = __dirname;
+    for (let i = 0; i < 8; i += 1) {
+        const candidate = (0, path_1.join)(dir, 'node_modules', '@earendil-works', 'pi-coding-agent', 'dist', 'cli.js');
+        if (exists(candidate))
+            return candidate;
+        const parent = (0, path_1.dirname)(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Resolve the INTERACTIVE Pi CLI binary (#666) — the human-TTY `pi`, DISTINCT
+ * from {@link resolvePiPath} (the headless adapter entry). Interactive TTY mode
+ * is REQUIRED for a conductor: Pi only fires `session_start` / attaches in a real
+ * terminal (non-TTY / `--print` → print-mode → tools register but NO attach).
+ *
+ * `pi` on PATH wins; else fall back to the installed package CLI via `node`.
+ * THROWS fail-clean if neither resolves, so the caller never launches a terminal
+ * that would immediately die. Collaborators injectable for unit tests.
+ */
+function resolvePiInteractiveBinary(deps = {}) {
+    const onPath = deps.onPath ?? binaryOnPath;
+    const exists = deps.exists ?? fs_1.existsSync;
+    if (onPath('pi'))
+        return { cmd: 'pi', args: [] };
+    const cli = findPiPackageCli(exists);
+    if (cli)
+        return { cmd: 'node', args: [cli] };
+    throw new Error('Pi CLI not found. Install it with `npm install -g pi-ai` and ensure `pi` is on PATH ' +
+        '(or add the @earendil-works/pi-coding-agent package). The conductor needs the interactive Pi CLI.');
+}
+/**
+ * Resolve the absolute path to the BUNDLED `dist/pi/extension.js` for `pi -e <abs>`
+ * (#666). Pi loads the BUILT CommonJS extension even in dev. Mirrors
+ * {@link resolvePiPath}'s dev/prod `__dirname` split: prod `__dirname` = `dist/`
+ * (→ `dist/pi/extension.js`); dev `__dirname` = `src/` (→ sibling `dist/pi/…`).
+ * Existence-checked + fail-clean ("run npm run build"). Injectable for tests.
+ */
+function resolvePiExtensionPath(deps = {}) {
+    const exists = deps.exists ?? fs_1.existsSync;
+    const isDev = deps.isDev ?? __filename.endsWith('.ts');
+    const base = deps.baseDir ?? __dirname;
+    const extPath = isDev
+        ? (0, path_1.resolve)(base, '..', 'dist', 'pi', 'extension.js') // dev: src/ → repo/dist/pi/extension.js
+        : (0, path_1.resolve)(base, 'pi', 'extension.js'); // prod: dist/ → dist/pi/extension.js
+    if (!exists(extPath)) {
+        throw new Error(`Pi conductor extension not found at ${extPath}. Run \`npm run build\` first.`);
+    }
+    return extPath;
+}
+/**
+ * Build the interactive Pi conductor spawn spec — `{ cmd, args, env }` for
+ * {@link launchInTerminal} (#666 C3). PURE + injectable so the env/args mapping is
+ * unit-tested. The default resolvers THROW fail-clean (binary missing / extension
+ * unbuilt) BEFORE a terminal is launched. `args` = `[...binArgs, '-e', <ext>]`;
+ * conductor INSTRUCTIONS arrive via the lineup-baked workflow messages → cue pump
+ * (no `--system-prompt` for the MVP).
+ */
+function buildPiConductorSpawn(opts) {
+    const { cmd, args: binArgs } = (opts.resolveBinary ?? resolvePiInteractiveBinary)();
+    const extPath = (opts.resolveExtension ?? resolvePiExtensionPath)();
+    const args = [...binArgs, '-e', extPath];
+    const env = {
+        ...opts.temporalEnvVars,
+        [config_1.ENV.TASK_QUEUE]: opts.taskQueue,
+        [config_1.ENV.ENSEMBLE]: opts.ensemble,
+        [config_1.ENV.CONDUCTOR]: 'true', // codebase-consistent; the Pi extension accepts '1'|'true'
+        [config_1.ENV.PLAYER_NAME]: opts.sessionName,
+        ...(opts.devMode ? { [config_1.ENV.DEV_MODE]: '1' } : {}),
+        ...(opts.anthropicApiKey ? { ANTHROPIC_API_KEY: opts.anthropicApiKey } : {}),
+        ...(opts.conductorTypeName ? { [config_1.ENV.PLAYER_TYPE]: opts.conductorTypeName } : {}),
+    };
+    return { cmd, args, env };
+}
 /**
  * Resolve the path to the compiled copilot bridge adapter entry point.
  * In dev (ts-node), returns a ts-node command; in production, returns the dist path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-tempo",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "Many agents, one tempo. Durable coordination for multi-agent work via Temporal.",
   "keywords": [
     "mcp",
@@ -81,7 +81,8 @@
     "lint:lockstep-version": "node -e \"const r=require('./package.json').version,d=require('./dashboard/package.json').version;if(r!==d){console.error('Version drift: root='+r+' dashboard='+d+'. Bump dashboard/package.json#version to match root.');process.exit(1);}console.log('Lockstep OK: '+r);\"",
     "lint:lockfile-canonical": "bash scripts/check-lockfile-canonical.sh",
     "lint:dashboard-css-sync": "npm run build:scripts && node dist/scripts/check-components-css-sync.js",
-    "check:all": "npm run lint:test-ensemble-literals && npm run lint:skip-reasons && npm run lint:lockstep-version && npm run lint:lockfile-canonical && npm run lint:surface-drift && npm run lint:no-stale-scaffold && npm run build && npm run lint:dashboard-css-sync && npm test && npm --prefix dashboard run lint && npm --prefix dashboard run test && npm run size-limit && npm run verify-tarball"
+    "lint:pi-drift": "node scripts/check-pi-drift.js",
+    "check:all": "npm run lint:test-ensemble-literals && npm run lint:skip-reasons && npm run lint:lockstep-version && npm run lint:lockfile-canonical && npm run lint:surface-drift && npm run lint:no-stale-scaffold && npm run build && npm run lint:pi-drift && npm run lint:dashboard-css-sync && npm test && npm --prefix dashboard run lint && npm --prefix dashboard run test && npm run size-limit && npm run verify-tarball"
   },
   "optionalDependencies": {
     "@anthropic-ai/sdk": "~0.91.1",