agent-tempo 1.2.0 → 1.4.0

package/dist/tools/worktree.js

@@ -33,149 +33,154 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerWorktreeTool = registerWorktreeTool;
+exports.buildWorktreeTool = buildWorktreeTool;
 const zod_1 = require("zod");
 const resolve_1 = require("./resolve");
 const signals_1 = require("../workflows/signals");
-const helpers_1 = require("./helpers");
+const descriptor_1 = require("./descriptor");
 const worktree_1 = require("../utils/worktree");
 const validation_1 = require("../utils/validation");
-function registerWorktreeTool(server, client, config, handle, getPlayerId) {
-    (0, helpers_1.defineTool)(server, 'worktree', 'Manage git worktrees for player isolation. Conductor only. Actions: create (provision worktree for a player), remove (clean up), list (show active worktrees). Use when multiple players commit to different branches of the same repo simultaneously; skip for read-only work, sequential work, or tasks under ~5 min. IMPORTANT: before `remove`, have the player stop any long-running processes inside the worktree (dev servers, file watchers) — on Windows a memory-mapped native module will block directory removal and `remove` will fail. See docs/orchestration.md#when-to-use-worktrees.', {
-        action: zod_1.z.enum(['create', 'remove', 'list']).describe('Action to perform'),
-        player: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).optional().describe('Player name (required for create/remove)'),
-        branch: zod_1.z.string().optional().describe('Git branch for the worktree (defaults to {ensemble}/{player-name})'),
-    }, async (args) => {
-        const { action, player, branch } = args;
-        try {
-            switch (action) {
-                case 'create': {
-                    if (!player) {
-                        return (0, helpers_1.fail)('`player` is required for create action.');
-                    }
-                    // Verify player exists
-                    const targetHandle = await (0, resolve_1.resolveSession)(client, config.ensemble, player);
-                    if (!targetHandle) {
-                        return (0, helpers_1.fail)(`No active session found for "${player}".`);
-                    }
-                    // Check target is on same host (cross-machine worktrees not supported)
-                    const targetMeta = await targetHandle.query('getMetadata');
-                    const { hostname } = await Promise.resolve().then(() => __importStar(require('os'))).then((os) => ({ hostname: os.hostname() }));
-                    if (targetMeta.hostname && targetMeta.hostname !== hostname) {
-                        return (0, helpers_1.fail)(`Cannot create worktree for "${player}" — they are on host "${targetMeta.hostname}" but worktrees must be created locally.`);
-                    }
-                    const gitRoot = process.cwd();
-                    const result = (0, worktree_1.createWorktree)({
-                        gitRoot,
-                        ensemble: config.ensemble,
-                        playerName: player,
-                        branch,
-                    });
-                    if (result.created) {
-                        (0, worktree_1.installDependencies)(result.path);
-                    }
-                    // Record in conductor's worktree state
-                    const entry = {
-                        player,
-                        path: result.path,
-                        branch: result.branch,
-                        gitRoot,
-                        createdAt: new Date().toISOString(),
-                        createdBy: getPlayerId(),
-                    };
-                    await handle.signal('setWorktree', entry);
-                    // Auto-cue the player with worktree info
-                    const cueMessage = [
-                        `\u{1f33f} **Worktree ready** for your task:`,
-                        `- **Path**: \`${result.path}\``,
-                        `- **Branch**: \`${result.branch}\``,
-                        '',
-                        `Run \`cd ${result.path}\` to switch to your isolated workspace.`,
-                        `All your changes will be on branch \`${result.branch}\`.`,
-                        `When done, commit and push \u2014 the conductor will handle cleanup.`,
-                    ].join('\n');
-                    await handle.executeUpdate(signals_1.submitOutboxUpdate, {
-                        args: [{
-                                type: 'cue',
-                                targetPlayerId: player,
-                                message: cueMessage,
-                            }],
-                    });
-                    // #261: when we reused an existing worktree directory, surface the
-                    // actual state transition (same branch / switched / created-from-main)
-                    // so the conductor sees ground truth instead of the prior silent
-                    // "reused existing" that implied the worktree was already on the
-                    // requested branch.
-                    const createdLabel = result.created
-                        ? 'new'
-                        : (() => {
-                            switch (result.switched) {
-                                case 'same':
-                                    return `reused existing (already on \`${result.branch}\`)`;
-                                case 'switched':
-                                    return `reused existing (switched to \`${result.branch}\`)`;
-                                case 'created-from-main':
-                                    return `reused existing (created \`${result.branch}\` from origin/main)`;
-                                default:
-                                    return 'reused existing';
-                            }
-                        })();
-                    return (0, helpers_1.ok)(`Worktree created for **${player}**:\n- Path: \`${result.path}\`\n- Branch: \`${result.branch}\`\n- Created: ${createdLabel}\n\nPlayer has been notified.`);
-                }
-                case 'remove': {
-                    if (!player) {
-                        return (0, helpers_1.fail)('`player` is required for remove action.');
-                    }
-                    // Look up worktree entry from conductor state
-                    const entries = await handle.query('worktrees');
-                    const entry = entries.find((w) => w.player === player);
-                    if (!entry) {
-                        return (0, helpers_1.fail)(`No worktree found for player "${player}".`);
-                    }
-                    // Remove from disk. #594: removeWorktree throws if the directory
-                    // survives the removal (Windows file-lock half-removal). We must
-                    // NOT signal `removeWorktree` state or cue the player until disk
-                    // removal is confirmed — otherwise Temporal state records "no
-                    // worktree" while a locked orphan directory remains on disk, and
-                    // the next `create` fails with a confusing git fatal.
-                    try {
-                        (0, worktree_1.removeWorktree)(entry.path, entry.gitRoot);
-                    }
-                    catch (err) {
-                        return (0, helpers_1.fail)(`Worktree for **${player}** could not be removed: ${(0, helpers_1.formatError)(err)}\n\n` +
-                            `Conductor state is unchanged — the worktree is still tracked. ` +
-                            `Have the player stop any long-running processes inside the worktree ` +
-                            `(dev servers, file watchers), then retry \`worktree remove\`.`);
-                    }
-                    // Remove from conductor state (only reached on confirmed disk removal)
-                    await handle.signal('removeWorktree', player);
-                    // Auto-cue the player
-                    try {
+function buildWorktreeTool(client, config, handle, getPlayerId) {
+    return {
+        name: 'worktree',
+        description: 'Manage git worktrees for player isolation. Conductor only. Actions: create (provision worktree for a player), remove (clean up), list (show active worktrees). Use when multiple players commit to different branches of the same repo simultaneously; skip for read-only work, sequential work, or tasks under ~5 min. IMPORTANT: before `remove`, have the player stop any long-running processes inside the worktree (dev servers, file watchers) — on Windows a memory-mapped native module will block directory removal and `remove` will fail. See docs/orchestration.md#when-to-use-worktrees.',
+        params: {
+            action: zod_1.z.enum(['create', 'remove', 'list']).describe('Action to perform'),
+            player: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).optional().describe('Player name (required for create/remove)'),
+            branch: zod_1.z.string().optional().describe('Git branch for the worktree (defaults to {ensemble}/{player-name})'),
+        },
+        handler: async (args) => {
+            const { action, player, branch } = args;
+            try {
+                switch (action) {
+                    case 'create': {
+                        if (!player) {
+                            return (0, descriptor_1.fail)('`player` is required for create action.');
+                        }
+                        // Verify player exists
+                        const targetHandle = await (0, resolve_1.resolveSession)(client, config.ensemble, player);
+                        if (!targetHandle) {
+                            return (0, descriptor_1.fail)(`No active session found for "${player}".`);
+                        }
+                        // Check target is on same host (cross-machine worktrees not supported)
+                        const targetMeta = await targetHandle.query('getMetadata');
+                        const { hostname } = await Promise.resolve().then(() => __importStar(require('os'))).then((os) => ({ hostname: os.hostname() }));
+                        if (targetMeta.hostname && targetMeta.hostname !== hostname) {
+                            return (0, descriptor_1.fail)(`Cannot create worktree for "${player}" — they are on host "${targetMeta.hostname}" but worktrees must be created locally.`);
+                        }
+                        const gitRoot = process.cwd();
+                        const result = (0, worktree_1.createWorktree)({
+                            gitRoot,
+                            ensemble: config.ensemble,
+                            playerName: player,
+                            branch,
+                        });
+                        if (result.created) {
+                            (0, worktree_1.installDependencies)(result.path);
+                        }
+                        // Record in conductor's worktree state
+                        const entry = {
+                            player,
+                            path: result.path,
+                            branch: result.branch,
+                            gitRoot,
+                            createdAt: new Date().toISOString(),
+                            createdBy: getPlayerId(),
+                        };
+                        await handle.signal('setWorktree', entry);
+                        // Auto-cue the player with worktree info
+                        const cueMessage = [
+                            `\u{1f33f} **Worktree ready** for your task:`,
+                            `- **Path**: \`${result.path}\``,
+                            `- **Branch**: \`${result.branch}\``,
+                            '',
+                            `Run \`cd ${result.path}\` to switch to your isolated workspace.`,
+                            `All your changes will be on branch \`${result.branch}\`.`,
+                            `When done, commit and push \u2014 the conductor will handle cleanup.`,
+                        ].join('\n');
                         await handle.executeUpdate(signals_1.submitOutboxUpdate, {
                             args: [{
                                     type: 'cue',
                                     targetPlayerId: player,
-                                    message: `Worktree removed. You're back in the shared repository.`,
+                                    message: cueMessage,
                                 }],
                         });
+                        // #261: when we reused an existing worktree directory, surface the
+                        // actual state transition (same branch / switched / created-from-main)
+                        // so the conductor sees ground truth instead of the prior silent
+                        // "reused existing" that implied the worktree was already on the
+                        // requested branch.
+                        const createdLabel = result.created
+                            ? 'new'
+                            : (() => {
+                                switch (result.switched) {
+                                    case 'same':
+                                        return `reused existing (already on \`${result.branch}\`)`;
+                                    case 'switched':
+                                        return `reused existing (switched to \`${result.branch}\`)`;
+                                    case 'created-from-main':
+                                        return `reused existing (created \`${result.branch}\` from origin/main)`;
+                                    default:
+                                        return 'reused existing';
+                                }
+                            })();
+                        return (0, descriptor_1.ok)(`Worktree created for **${player}**:\n- Path: \`${result.path}\`\n- Branch: \`${result.branch}\`\n- Created: ${createdLabel}\n\nPlayer has been notified.`);
                     }
-                    catch {
-                        // Player may no longer be active — non-fatal
+                    case 'remove': {
+                        if (!player) {
+                            return (0, descriptor_1.fail)('`player` is required for remove action.');
+                        }
+                        // Look up worktree entry from conductor state
+                        const entries = await handle.query('worktrees');
+                        const entry = entries.find((w) => w.player === player);
+                        if (!entry) {
+                            return (0, descriptor_1.fail)(`No worktree found for player "${player}".`);
+                        }
+                        // Remove from disk. #594: removeWorktree throws if the directory
+                        // survives the removal (Windows file-lock half-removal). We must
+                        // NOT signal `removeWorktree` state or cue the player until disk
+                        // removal is confirmed — otherwise Temporal state records "no
+                        // worktree" while a locked orphan directory remains on disk, and
+                        // the next `create` fails with a confusing git fatal.
+                        try {
+                            (0, worktree_1.removeWorktree)(entry.path, entry.gitRoot);
+                        }
+                        catch (err) {
+                            return (0, descriptor_1.fail)(`Worktree for **${player}** could not be removed: ${(0, descriptor_1.formatError)(err)}\n\n` +
+                                `Conductor state is unchanged — the worktree is still tracked. ` +
+                                `Have the player stop any long-running processes inside the worktree ` +
+                                `(dev servers, file watchers), then retry \`worktree remove\`.`);
+                        }
+                        // Remove from conductor state (only reached on confirmed disk removal)
+                        await handle.signal('removeWorktree', player);
+                        // Auto-cue the player
+                        try {
+                            await handle.executeUpdate(signals_1.submitOutboxUpdate, {
+                                args: [{
+                                        type: 'cue',
+                                        targetPlayerId: player,
+                                        message: `Worktree removed. You're back in the shared repository.`,
+                                    }],
+                            });
+                        }
+                        catch {
+                            // Player may no longer be active — non-fatal
+                        }
+                        return (0, descriptor_1.ok)(`Worktree for **${player}** removed (branch: \`${entry.branch}\`).`);
                     }
-                    return (0, helpers_1.ok)(`Worktree for **${player}** removed (branch: \`${entry.branch}\`).`);
-                }
-                case 'list': {
-                    const entries = await handle.query('worktrees');
-                    if (entries.length === 0) {
-                        return (0, helpers_1.ok)('No active worktrees.');
+                    case 'list': {
+                        const entries = await handle.query('worktrees');
+                        if (entries.length === 0) {
+                            return (0, descriptor_1.ok)('No active worktrees.');
+                        }
+                        const lines = entries.map((w) => `- **${w.player}**: \`${w.path}\` (branch: \`${w.branch}\`, created: ${w.createdAt} by ${w.createdBy})`);
+                        return (0, descriptor_1.ok)(`${entries.length} active worktree${entries.length === 1 ? '' : 's'}:\n${lines.join('\n')}`);
                     }
-                    const lines = entries.map((w) => `- **${w.player}**: \`${w.path}\` (branch: \`${w.branch}\`, created: ${w.createdAt} by ${w.createdBy})`);
-                    return (0, helpers_1.ok)(`${entries.length} active worktree${entries.length === 1 ? '' : 's'}:\n${lines.join('\n')}`);
                 }
             }
-        }
-        catch (err) {
-            return (0, helpers_1.fail)(`Worktree operation failed: ${(0, helpers_1.formatError)(err)}`);
-        }
-    });
+            catch (err) {
+                return (0, descriptor_1.fail)(`Worktree operation failed: ${(0, descriptor_1.formatError)(err)}`);
+            }
+        },
+    };
 }

package/dist/tui/index.js

@@ -75,12 +75,12 @@ async function run(opts) {
         const app = ink.render(
         // The TUI recruit wizard only offers `claude` / `copilot` — `mock` is
         // a dev-mode CLI-only path (ADR 0014 §7 gate 3); `claude-api` (#131),
-        // `opencode` (#449), and `claude-code-headless` (#520) are CLI/MCP-only
-        // paths. If the user's resolved default is one of those, fall back to
-        // `claude` for the TUI default; they can still recruit those agents
-        // via the CLI (e.g. `agent-tempo recruit ... --agent opencode`) or
-        // the MCP `recruit` tool.
-        react_1.default.createElement(ink_context_1.InkProvider, { ink, children: react_1.default.createElement(App_1.App, { api, ensemble: opts.ensemble, defaultAgent: (opts.config.defaultAgent === 'mock' || opts.config.defaultAgent === 'claude-api' || opts.config.defaultAgent === 'opencode' || opts.config.defaultAgent === 'claude-code-headless') ? 'claude' : opts.config.defaultAgent }) }));
+        // `opencode` (#449), `claude-code-headless` (#520), and `pi` (Phase 3a
+        // headless) are CLI/MCP-only paths. If the user's resolved default is one
+        // of those, fall back to `claude` for the TUI default; they can still
+        // recruit those agents via the CLI (e.g. `agent-tempo recruit ... --agent
+        // pi`) or the MCP `recruit` tool.
+        react_1.default.createElement(ink_context_1.InkProvider, { ink, children: react_1.default.createElement(App_1.App, { api, ensemble: opts.ensemble, defaultAgent: (opts.config.defaultAgent === 'mock' || opts.config.defaultAgent === 'claude-api' || opts.config.defaultAgent === 'opencode' || opts.config.defaultAgent === 'claude-code-headless' || opts.config.defaultAgent === 'pi') ? 'claude' : opts.config.defaultAgent }) }));
         await app.waitUntilExit();
     }
     finally {

package/dist/types.d.ts

@@ -15,7 +15,7 @@
  * editing one line — see #476 (the `claude-api` allowlist drift bug
  * that motivated centralising this).
  */
-export declare const AGENT_TYPES: readonly ["claude", "copilot", "mock", "claude-api", "opencode", "claude-code-headless"];
+export declare const AGENT_TYPES: readonly ["claude", "copilot", "mock", "claude-api", "opencode", "claude-code-headless", "pi"];
 export type AgentType = typeof AGENT_TYPES[number];
 /**
  * Mock-adapter mode (ADR 0014 §4.2). Single source of truth shared by the
@@ -349,6 +349,8 @@ export interface SessionInput {
     reportHistory?: PlayerReport[];
     /** Restored from continue-as-new (pending/processing entries only) */
     outbox?: OutboxEntry[];
+    /** Restored from continue-as-new (D14) — an un-acked pending reset survives a CAN. */
+    pendingReset?: PendingReset | null;
     autoSummary?: string;
     /** Disable stale session detection (for passive mailbox workflows like maestro) */
     disableStaleDetection?: boolean;
@@ -564,6 +566,14 @@ export interface RecruitOutboxEntry extends OutboxEntryBase {
      * when `agent !== 'claude-code-headless'`.
      */
     dangerouslySkipPermissions?: boolean;
+    /**
+     * Phase 3a / MD-C — headless Pi tool-class policy. `'restricted'` (default;
+     * Bash/shell/exec hard-blocked) | `'standard'` (scoped Bash) | `'full'`
+     * (unsandboxed; admin/force-gated at recruit). Ignored when `agent !== 'pi'`.
+     * Inline literal — types.ts is the V8-sandbox-safe shared module; do NOT import
+     * the type from src/pi or src/adapters.
+     */
+    toolAccess?: 'restricted' | 'standard' | 'full';
 }
 export interface ReleaseOutboxEntry extends OutboxEntryBase {
     type: 'release';
@@ -692,7 +702,42 @@ export interface SpawnOutboxEntry extends OutboxEntryBase {
      */
     model?: string;
 }
-export type OutboxEntry = CueOutboxEntry | RecruitOutboxEntry | ReportOutboxEntry | StopOutboxEntry | ReleaseOutboxEntry | SpawnOutboxEntry | DetachOutboxEntry | DestroyOutboxEntry | RestartOutboxEntry;
+/**
+ * Reset outbox entry (D14) — enqueued by the `reset` tool so the dispatch loop
+ * runs `deliverReset` on the target, which sets a `pendingReset` flag the Pi
+ * extension polls + acts on (CLEAN-WIPE → Pi `newSession()`). POLL-delivery
+ * (mirrors cue/pendingMessages), NOT a direct signal into the subprocess.
+ * Operator-initiated → does NOT route through the MD-G tool gate.
+ */
+export interface ResetOutboxEntry extends OutboxEntryBase {
+    type: 'reset';
+    /** Player whose context is wiped. */
+    targetPlayerId: string;
+    /** Who requested the reset (owner or conductor). Recorded for audit. */
+    invokerPlayerId?: string;
+    /** Clean-wipe (D14 default `true` → `newSession`). `false` reserved for a softer reset. */
+    fresh?: boolean;
+    /** Optional human-readable reason, surfaced to the wiped session + audit. */
+    reason?: string;
+}
+export type OutboxEntry = CueOutboxEntry | RecruitOutboxEntry | ReportOutboxEntry | StopOutboxEntry | ReleaseOutboxEntry | SpawnOutboxEntry | DetachOutboxEntry | DestroyOutboxEntry | RestartOutboxEntry | ResetOutboxEntry;
+/**
+ * Pending reset flag set on a session workflow by `deliverReset`, polled by the
+ * Pi extension via `pendingResetQuery` and cleared via `ackResetSignal(resetId)`
+ * after the extension performs the wipe. Single-slot, latest-wins.
+ */
+export interface PendingReset {
+    /** Correlation id (the originating outbox entry id). Ack clears only on match. */
+    resetId: string;
+    /** Clean-wipe (`newSession`) when true (D14 default). */
+    fresh: boolean;
+    /** Optional reason. */
+    reason?: string;
+    /** Who requested it (audit). */
+    requestedBy?: string;
+    /** ISO timestamp, stamped by the workflow (`workflow.now()`) — deterministic. */
+    requestedAt: string;
+}
 /** Distributive Omit that works correctly on union types. */
 type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K> : never;
 /** Input type for submitting outbox entries — auto-fields (id, createdAt, status, error, deliveredAt) are added by the workflow. */

package/dist/types.js

@@ -20,7 +20,7 @@ exports.ZERO_CHAT_HIGH_WATER = exports.MOCK_MODES = exports.AGENT_TYPES = void 0
  * editing one line — see #476 (the `claude-api` allowlist drift bug
  * that motivated centralising this).
  */
-exports.AGENT_TYPES = ['claude', 'copilot', 'mock', 'claude-api', 'opencode', 'claude-code-headless'];
+exports.AGENT_TYPES = ['claude', 'copilot', 'mock', 'claude-api', 'opencode', 'claude-code-headless', 'pi'];
 /**
  * Mock-adapter mode (ADR 0014 §4.2). Single source of truth shared by the
  * adapter, the recruit tool's zod enum (`z.enum(MOCK_MODES)`), the spawn

package/dist/utils/default-part.js

@@ -46,6 +46,7 @@ exports.HEADLESS_ADAPTERS = new Set([
     'opencode',
     'claude-api',
     'mock',
+    'pi',
 ]);
 /**
  * Compute the default `part` text seeded into a fresh session workflow.

package/dist/utils/grpc-shutdown-guard.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Process-level guard for the Temporal/grpc-js "Channel has been shut down"
+ * shutdown race.
+ *
+ * `@temporalio/client`'s gRPC retry interceptor (`grpc-retry.js`) schedules
+ * call retries with `setTimeout`. `Connection.close()` shuts down the
+ * underlying grpc-js channel but does NOT clear those pending timers. When a
+ * retry timer fires *after* the channel is closed, `InternalChannel.createCall`
+ * throws `Error: Channel has been shut down` **synchronously inside the timer
+ * callback** — off any awaited path, so no surrounding `try/catch` (including
+ * the one around `connection.close()`) can catch it. It escapes to
+ * `uncaughtException` and kills the process.
+ *
+ * Observed stack (the crash this guards against):
+ *   InternalChannel.createCall (@grpc/grpc-js/.../internal-channel.js)
+ *   ...
+ *   Timeout.retry [as _onTimeout] (@temporalio/client/lib/grpc-retry.js)
+ *
+ * This artifact is always benign: it only occurs for a connection we have
+ * already finished with (its query result was captured, or we degraded), as
+ * the channel tears down. Swallowing exactly this error — and nothing else —
+ * removes the crash without masking real failures. Any other uncaught
+ * exception is re-thrown, which Node treats as fatal (print + non-zero exit),
+ * preserving normal crash semantics.
+ *
+ * Install once at CLI entry. Idempotent.
+ *
+ * Coupling notes:
+ * - The match string is grpc-js's exact `close()` error
+ *   (`@grpc/grpc-js/build/src/internal-channel.js`, the `SHUTDOWN`-state throw).
+ *   That state is reachable ONLY via an explicit `close()` — a live connection
+ *   hitting a transient error reports `TRANSIENT_FAILURE`, never this message —
+ *   so swallowing it cannot mask a failure we'd want to surface. If grpc-js ever
+ *   renames the message this guard silently becomes a no-op (crash resurfaces);
+ *   update `CHANNEL_SHUTDOWN_MESSAGE` to match.
+ * - This handler is registered first (it's installed at process entry). When it
+ *   re-throws a non-benign error, Node exits immediately and any LATER
+ *   `uncaughtException` listener is bypassed. The codebase currently registers
+ *   no other `uncaughtException` listeners, so this is benign today — revisit if
+ *   a crash reporter is ever added.
+ */
+/**
+ * Register the guard on `process`. Safe to call multiple times — only the
+ * first call attaches a listener.
+ */
+export declare function installGrpcShutdownGuard(): void;
+/**
+ * Test-only escape hatch — removes the listener and resets the install latch so
+ * a fresh `installGrpcShutdownGuard()` can be exercised. Never call from
+ * production code. See docs/adr/0006-test-hooks-naming.md.
+ */
+export declare function __resetGrpcShutdownGuardForTests(): void;

package/dist/utils/grpc-shutdown-guard.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Process-level guard for the Temporal/grpc-js "Channel has been shut down"
+ * shutdown race.
+ *
+ * `@temporalio/client`'s gRPC retry interceptor (`grpc-retry.js`) schedules
+ * call retries with `setTimeout`. `Connection.close()` shuts down the
+ * underlying grpc-js channel but does NOT clear those pending timers. When a
+ * retry timer fires *after* the channel is closed, `InternalChannel.createCall`
+ * throws `Error: Channel has been shut down` **synchronously inside the timer
+ * callback** — off any awaited path, so no surrounding `try/catch` (including
+ * the one around `connection.close()`) can catch it. It escapes to
+ * `uncaughtException` and kills the process.
+ *
+ * Observed stack (the crash this guards against):
+ *   InternalChannel.createCall (@grpc/grpc-js/.../internal-channel.js)
+ *   ...
+ *   Timeout.retry [as _onTimeout] (@temporalio/client/lib/grpc-retry.js)
+ *
+ * This artifact is always benign: it only occurs for a connection we have
+ * already finished with (its query result was captured, or we degraded), as
+ * the channel tears down. Swallowing exactly this error — and nothing else —
+ * removes the crash without masking real failures. Any other uncaught
+ * exception is re-thrown, which Node treats as fatal (print + non-zero exit),
+ * preserving normal crash semantics.
+ *
+ * Install once at CLI entry. Idempotent.
+ *
+ * Coupling notes:
+ * - The match string is grpc-js's exact `close()` error
+ *   (`@grpc/grpc-js/build/src/internal-channel.js`, the `SHUTDOWN`-state throw).
+ *   That state is reachable ONLY via an explicit `close()` — a live connection
+ *   hitting a transient error reports `TRANSIENT_FAILURE`, never this message —
+ *   so swallowing it cannot mask a failure we'd want to surface. If grpc-js ever
+ *   renames the message this guard silently becomes a no-op (crash resurfaces);
+ *   update `CHANNEL_SHUTDOWN_MESSAGE` to match.
+ * - This handler is registered first (it's installed at process entry). When it
+ *   re-throws a non-benign error, Node exits immediately and any LATER
+ *   `uncaughtException` listener is bypassed. The codebase currently registers
+ *   no other `uncaughtException` listeners, so this is benign today — revisit if
+ *   a crash reporter is ever added.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installGrpcShutdownGuard = installGrpcShutdownGuard;
+exports.__resetGrpcShutdownGuardForTests = __resetGrpcShutdownGuardForTests;
+const CHANNEL_SHUTDOWN_MESSAGE = 'Channel has been shut down';
+let installed = false;
+function isBenignChannelShutdown(err) {
+    return (err instanceof Error &&
+        typeof err.message === 'string' &&
+        err.message.includes(CHANNEL_SHUTDOWN_MESSAGE));
+}
+const handler = (err) => {
+    if (isBenignChannelShutdown(err)) {
+        // A Temporal gRPC retry timer fired after we closed the connection. The
+        // result we cared about was already captured (or degraded). Drop it.
+        if (process.env.CLAUDE_TEMPO_DEBUG) {
+            // eslint-disable-next-line no-console
+            console.error('[agent-tempo] ignored post-shutdown gRPC channel error (benign Temporal retry-after-close race)');
+        }
+        return;
+    }
+    // Not ours — restore default crash behavior. Throwing from inside an
+    // 'uncaughtException' handler causes Node to print the error and exit with a
+    // non-zero code (exit code 7, "Uncaught Exception Handler Error", on current
+    // Node — not 1) without re-entering this handler, preserving the original
+    // failure's visibility and crash semantics.
+    throw err;
+};
+/**
+ * Register the guard on `process`. Safe to call multiple times — only the
+ * first call attaches a listener.
+ */
+function installGrpcShutdownGuard() {
+    if (installed)
+        return;
+    installed = true;
+    process.on('uncaughtException', handler);
+}
+/**
+ * Test-only escape hatch — removes the listener and resets the install latch so
+ * a fresh `installGrpcShutdownGuard()` can be exercised. Never call from
+ * production code. See docs/adr/0006-test-hooks-naming.md.
+ */
+function __resetGrpcShutdownGuardForTests() {
+    process.off('uncaughtException', handler);
+    installed = false;
+}

package/dist/utils/sdk-probe.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Locate an installed package's `package.json` by walking `node_modules`
+ * directories upward from `fromDir`. The single source of truth for the
+ * filesystem walk — {@link probeSdkInstall} (presence) and
+ * {@link readSdkPackageVersion} (version) both build on it.
+ *
+ * @param pkgName Bare specifier (e.g. `'@opencode-ai/sdk'`).
+ * @param fromDir Where to start the walk. Defaults to the caller's
+ *   `__dirname`-equivalent — pass an explicit value to anchor elsewhere.
+ * @returns The absolute path to `<dir>/node_modules/<pkgName>/package.json`
+ *   for the first match up the filesystem, or `null` if none is found.
+ */
+export declare function findSdkPackageJson(pkgName: string, fromDir?: string): string | null;
 /**
  * @param pkgName Bare specifier (e.g. `'@opencode-ai/sdk'`).
  * @param fromDir Where to start the walk. Defaults to the caller's
@@ -7,3 +20,13 @@
  *   anywhere on the walk up the filesystem.
  */
 export declare function probeSdkInstall(pkgName: string, fromDir?: string): boolean;
+/**
+ * Read an installed package's `package.json#version` via the same filesystem
+ * walk as {@link probeSdkInstall}. Returns `null` when the package isn't
+ * installed, its `package.json` is unreadable, or its `version` field is
+ * absent/non-string — callers treat `null` as "version unknown".
+ *
+ * @param pkgName Bare specifier (e.g. `'@earendil-works/pi-coding-agent'`).
+ * @param fromDir Walk start (defaults to this module's `__dirname`).
+ */
+export declare function readSdkPackageVersion(pkgName: string, fromDir?: string): string | null;