agent-tempo 1.2.0 → 1.3.1

package/dist/cli/upgrade-command.js

@@ -131,87 +131,87 @@ async function upgrade(opts) {
     //   4. Restarts the daemon
     const cliPid = process.pid;
     const isWin = process.platform === 'win32';
-    const updaterScript = `
-const { execFileSync } = require('child_process');
-const fs = require('fs');
-
-const PID = ${cliPid};
-const INSTALL_SPEC = ${JSON.stringify(installSpec)};
-const TARGET = ${JSON.stringify(targetVersion)};
-const IS_WIN = ${isWin};
-const LOG_PATH = ${JSON.stringify((0, path_1.join)(config_1.AGENT_TEMPO_HOME, 'upgrade.log'))};
-
-function log(msg) {
-  const line = new Date().toISOString() + ' ' + msg;
-  try { fs.appendFileSync(LOG_PATH, line + '\\n'); } catch {}
-  console.log(msg);
-}
-
-function isPidAlive(pid) {
-  try { process.kill(pid, 0); return true; }
-  catch { return false; }
-}
-
-async function main() {
-  // Wait for CLI process to exit (up to 10s)
-  log('Waiting for CLI process (pid ' + PID + ') to exit...');
-  const deadline = Date.now() + 10000;
-  while (Date.now() < deadline && isPidAlive(PID)) {
-    await new Promise(r => setTimeout(r, 300));
-  }
-  if (isPidAlive(PID)) {
-    log('WARNING: CLI process still alive after 10s, proceeding anyway');
-  }
-
-  // Run npm install -g
-  log('Installing ' + INSTALL_SPEC + '...');
-  try {
-    const npmCmd = IS_WIN ? 'npm.cmd' : 'npm';
-    execFileSync(npmCmd, ['install', '-g', INSTALL_SPEC], {
-      stdio: 'inherit',
-      timeout: 120000,
-    });
-    log('Install completed');
-  } catch (err) {
-    log('Install FAILED: ' + err.message);
-    log('Recovery: npm install -g ' + INSTALL_SPEC);
-    process.exit(1);
-  }
-
-  // Verify installation
-  try {
-    const tempoCmd = IS_WIN ? 'agent-tempo.cmd' : 'agent-tempo';
-    const ver = execFileSync(tempoCmd, ['--version'], {
-      encoding: 'utf8',
-      timeout: 10000,
-    }).trim();
-    log('Verified: ' + ver);
-  } catch (err) {
-    log('WARNING: Could not verify installation: ' + err.message);
-    log('Recovery: npm install -g agent-tempo');
-  }
-
-  // Restart the daemon
-  log('Restarting daemon...');
-  try {
-    const tempoCmd = IS_WIN ? 'agent-tempo.cmd' : 'agent-tempo';
-    execFileSync(tempoCmd, ['daemon', 'start'], {
-      stdio: 'inherit',
-      timeout: 30000,
-    });
-    log('Daemon restarted');
-  } catch (err) {
-    log('WARNING: Daemon restart failed: ' + err.message);
-    log('Run manually: agent-tempo daemon start');
-  }
-
-  log('Upgrade complete!');
-}
-
-main().catch(err => {
-  log('Upgrade failed: ' + err.message);
-  process.exit(1);
-});
+    const updaterScript = `
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+
+const PID = ${cliPid};
+const INSTALL_SPEC = ${JSON.stringify(installSpec)};
+const TARGET = ${JSON.stringify(targetVersion)};
+const IS_WIN = ${isWin};
+const LOG_PATH = ${JSON.stringify((0, path_1.join)(config_1.AGENT_TEMPO_HOME, 'upgrade.log'))};
+
+function log(msg) {
+  const line = new Date().toISOString() + ' ' + msg;
+  try { fs.appendFileSync(LOG_PATH, line + '\\n'); } catch {}
+  console.log(msg);
+}
+
+function isPidAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch { return false; }
+}
+
+async function main() {
+  // Wait for CLI process to exit (up to 10s)
+  log('Waiting for CLI process (pid ' + PID + ') to exit...');
+  const deadline = Date.now() + 10000;
+  while (Date.now() < deadline && isPidAlive(PID)) {
+    await new Promise(r => setTimeout(r, 300));
+  }
+  if (isPidAlive(PID)) {
+    log('WARNING: CLI process still alive after 10s, proceeding anyway');
+  }
+
+  // Run npm install -g
+  log('Installing ' + INSTALL_SPEC + '...');
+  try {
+    const npmCmd = IS_WIN ? 'npm.cmd' : 'npm';
+    execFileSync(npmCmd, ['install', '-g', INSTALL_SPEC], {
+      stdio: 'inherit',
+      timeout: 120000,
+    });
+    log('Install completed');
+  } catch (err) {
+    log('Install FAILED: ' + err.message);
+    log('Recovery: npm install -g ' + INSTALL_SPEC);
+    process.exit(1);
+  }
+
+  // Verify installation
+  try {
+    const tempoCmd = IS_WIN ? 'agent-tempo.cmd' : 'agent-tempo';
+    const ver = execFileSync(tempoCmd, ['--version'], {
+      encoding: 'utf8',
+      timeout: 10000,
+    }).trim();
+    log('Verified: ' + ver);
+  } catch (err) {
+    log('WARNING: Could not verify installation: ' + err.message);
+    log('Recovery: npm install -g agent-tempo');
+  }
+
+  // Restart the daemon
+  log('Restarting daemon...');
+  try {
+    const tempoCmd = IS_WIN ? 'agent-tempo.cmd' : 'agent-tempo';
+    execFileSync(tempoCmd, ['daemon', 'start'], {
+      stdio: 'inherit',
+      timeout: 30000,
+    });
+    log('Daemon restarted');
+  } catch (err) {
+    log('WARNING: Daemon restart failed: ' + err.message);
+    log('Run manually: agent-tempo daemon start');
+  }
+
+  log('Upgrade complete!');
+}
+
+main().catch(err => {
+  log('Upgrade failed: ' + err.message);
+  process.exit(1);
+});
 `.trim();
     // Clear previous upgrade log before spawning
     const logPath = (0, path_1.join)(config_1.AGENT_TEMPO_HOME, 'upgrade.log');

package/dist/cli.js

@@ -61,6 +61,8 @@ const dev_banner_1 = require("./cli/dev-banner");
 const types_1 = require("./types");
 const config_1 = require("./config");
 const legacy_migration_1 = require("./cli/legacy-migration");
+const global_wrapper_1 = require("./cli/global-wrapper");
+const grpc_shutdown_guard_1 = require("./utils/grpc-shutdown-guard");
 /** Package root — cli.js compiles to dist/cli.js, so one level up. Used by the inline `version` handler. */
 const PACKAGE_ROOT = (0, path_1.resolve)(__dirname, '..');
 function parseArgs(argv) {
@@ -328,6 +330,12 @@ function reportMigrationResult(result) {
     process.exitCode = 1;
 }
 async function main() {
+    // Neutralize the Temporal/grpc-js "Channel has been shut down" retry-after-
+    // close race before any Temporal-touching command runs. See
+    // src/utils/grpc-shutdown-guard.ts. Cheap, import-clean, and idempotent — it
+    // attaches a single `uncaughtException` listener and pulls in no Temporal/grpc
+    // modules, so it is safe above the crash-proof fast paths below.
+    (0, grpc_shutdown_guard_1.installGrpcShutdownGuard)();
     const args = parseArgs(process.argv.slice(2));
     const overrides = cliOverrides(args);
     // ADR 0014 §5.4 / gate 4: every dev-mode CLI invocation prints the
@@ -335,6 +343,10 @@ async function main() {
     // self-identify as the dev profile. Banner emits to stderr — keeps
     // `--json` stdout consumers clean.
     (0, dev_banner_1.emitDevBannerIfActive)();
+    // Refresh the global wrapper entrypoint pointer so `~/.agent-tempo/bin/agent-tempo`
+    // always resolves to the currently-running binary. Cheap (single writeFileSync),
+    // idempotent, and best-effort — never blocks or throws.
+    (0, global_wrapper_1.refreshEntrypoint)();
     // ── Crash-proof fast paths (#157 PR C) ────────────────────────────────
     // These handlers MUST NOT reach `./cli/commands`, `./cli/preflight`, or
     // any other module that transitively imports `@temporalio/*` / `rxjs` /

package/dist/daemon.js

@@ -66,6 +66,7 @@ const config_1 = require("./config");
 const dev_banner_1 = require("./cli/dev-banner");
 const worker_1 = require("./worker");
 const connection_1 = require("./connection");
+const grpc_shutdown_guard_1 = require("./utils/grpc-shutdown-guard");
 const daemon_1 = require("./cli/daemon");
 const client_3 = require("./client");
 const orphans_1 = require("./reconcile/orphans");
@@ -684,6 +685,10 @@ function startCleanupLoop(client, daemonConfig, hostname = os.hostname()) {
     };
 }
 async function main() {
+    // Neutralize the Temporal/grpc-js "Channel has been shut down" retry-after-
+    // close race so a stray retry timer can't kill the long-lived daemon. See
+    // src/utils/grpc-shutdown-guard.ts.
+    (0, grpc_shutdown_guard_1.installGrpcShutdownGuard)();
     // ADR 0014 §5.4 / gate 4 — dev daemon log self-identifies. Banner fires
     // first so it lands at the top of `~/.agent-tempo-dev/daemon.log` for
     // grep-friendly identification regardless of subsequent log volume.

package/dist/scripts/verify-daemon-isolation-guard.js

@@ -81,30 +81,30 @@ catch (err) {
     console.error(err && err.message);
     process.exit(1);
 }
-const detector = `
-  // Step 1: load daemon-command (should leave require.cache clean of Temporal).
-  require(${JSON.stringify(DAEMON_COMMAND_DIST)});
-  // Step 2: simulate a regression — load @temporalio/client directly.
-  // This is what would happen if a future edit to daemon-command (or one of
-  // its deps) accidentally imported something Temporal-adjacent.
-  require(${JSON.stringify(temporalClientPath)});
-  // Step 3: run the same detector as test/daemon-command-isolation.test.ts.
-  const forbidden = [
-    /[\\\\/]@temporalio[\\\\/]/,
-    /[\\\\/]rxjs[\\\\/]/,
-    /[\\\\/]@grpc[\\\\/]/,
-    /[\\\\/]nice-grpc(?:-[^\\\\/]+)?[\\\\/]/,
-    /[\\\\/]long[\\\\/]umd[\\\\/]/,
-  ];
-  const hits = Object.keys(require.cache).filter((k) => forbidden.some((re) => re.test(k)));
-  if (hits.length > 0) {
-    console.log('Detector found ' + hits.length + ' forbidden module(s) in require.cache:');
-    for (const h of hits.slice(0, 3)) console.log('  ' + h);
-    if (hits.length > 3) console.log('  ... (' + (hits.length - 3) + ' more)');
-    process.exit(0);
-  }
-  console.error('BUG: detector did not flag any of the injected forbidden modules.');
-  process.exit(1);
+const detector = `
+  // Step 1: load daemon-command (should leave require.cache clean of Temporal).
+  require(${JSON.stringify(DAEMON_COMMAND_DIST)});
+  // Step 2: simulate a regression — load @temporalio/client directly.
+  // This is what would happen if a future edit to daemon-command (or one of
+  // its deps) accidentally imported something Temporal-adjacent.
+  require(${JSON.stringify(temporalClientPath)});
+  // Step 3: run the same detector as test/daemon-command-isolation.test.ts.
+  const forbidden = [
+    /[\\\\/]@temporalio[\\\\/]/,
+    /[\\\\/]rxjs[\\\\/]/,
+    /[\\\\/]@grpc[\\\\/]/,
+    /[\\\\/]nice-grpc(?:-[^\\\\/]+)?[\\\\/]/,
+    /[\\\\/]long[\\\\/]umd[\\\\/]/,
+  ];
+  const hits = Object.keys(require.cache).filter((k) => forbidden.some((re) => re.test(k)));
+  if (hits.length > 0) {
+    console.log('Detector found ' + hits.length + ' forbidden module(s) in require.cache:');
+    for (const h of hits.slice(0, 3)) console.log('  ' + h);
+    if (hits.length > 3) console.log('  ... (' + (hits.length - 3) + ' more)');
+    process.exit(0);
+  }
+  console.error('BUG: detector did not flag any of the injected forbidden modules.');
+  process.exit(1);
 `;
 const result = (0, child_process_1.spawnSync)(process.execPath, ['-e', detector], {
     stdio: ['ignore', 'inherit', 'inherit'],

package/dist/server.js

@@ -56,9 +56,13 @@ const server_tools_1 = require("./server-tools");
 const adapters_1 = require("./adapters");
 const agent_types_1 = require("./ensemble/agent-types");
 const parent_death_watchdog_1 = require("./utils/parent-death-watchdog");
+const grpc_shutdown_guard_1 = require("./utils/grpc-shutdown-guard");
 const log = (...args) => console.error('[agent-tempo]', ...args);
 async function main() {
     (0, parent_death_watchdog_1.installParentDeathWatchdog)();
+    // Neutralize the Temporal/grpc-js "Channel has been shut down" retry-after-
+    // close race. See src/utils/grpc-shutdown-guard.ts.
+    (0, grpc_shutdown_guard_1.installGrpcShutdownGuard)();
     // Only activate when explicitly opted in via AGENT_TEMPO_ENSEMBLE
     if (!process.env[config_1.ENV.ENSEMBLE]) {
         log(`${config_1.ENV.ENSEMBLE} not set — MCP server idle (no workflow started)`);

package/dist/spawn.js

@@ -262,12 +262,12 @@ function spawnInTerminal(claudeArgs, workDir, envVars, options) {
             // Append `; exit` so the wrapping shell exits when claude does (clean or killed).
             // Without it, claude exit returns control to the shell prompt and the tab lingers —
             // parity with the Windows WT `closeOnExit: 'always'` + parent-walk fix from #166.
-            const osaScript = `
-        tell application "Ghostty"
-          set cfg to new surface configuration
-          set initial working directory of cfg to ${JSON.stringify(workDir)}
-          set initial input of cfg to ${JSON.stringify(claudeInvocation + '; exit\n')}
-          set win to new window with configuration cfg
+            const osaScript = `
+        tell application "Ghostty"
+          set cfg to new surface configuration
+          set initial working directory of cfg to ${JSON.stringify(workDir)}
+          set initial input of cfg to ${JSON.stringify(claudeInvocation + '; exit\n')}
+          set win to new window with configuration cfg
         end tell`;
             log('Using Ghostty initial-input path');
             const child = (0, child_process_1.spawn)('osascript', ['-e', osaScript], {
@@ -285,12 +285,12 @@ function spawnInTerminal(claudeArgs, workDir, envVars, options) {
             // so any `"` or `\` in paths/args doesn't break the AppleScript parser. Parity with
             // the Ghostty path above.
             const shellCmd = `cd ${shellQuote(workDir)} && ${claudeInvocation} ; exit`;
-            const osaScript = `
-        tell application "iTerm2"
-          set newWindow to (create window with default profile)
-          tell current session of newWindow
-            write text ${JSON.stringify(shellCmd)}
-          end tell
+            const osaScript = `
+        tell application "iTerm2"
+          set newWindow to (create window with default profile)
+          tell current session of newWindow
+            write text ${JSON.stringify(shellCmd)}
+          end tell
         end tell`;
             log('Using iTerm2 write-text path');
             const child = (0, child_process_1.spawn)('osascript', ['-e', osaScript], {

package/dist/tools/coat-check-evict.js

@@ -17,8 +17,8 @@ const maestro_signals_1 = require("../workflows/maestro-signals");
 const helpers_1 = require("./helpers");
 const validation_1 = require("../utils/validation");
 function registerCoatCheckEvictTool(server, client, config, getPlayerId) {
-    (0, helpers_1.defineTool)(server, 'coat_check_evict', `Evict a coat-check entry (#318) before its TTL expires. Owner-or-conductor only — non-owners (and non-conductors) get a permission error.
-
+    (0, helpers_1.defineTool)(server, 'coat_check_evict', `Evict a coat-check entry (#318) before its TTL expires. Owner-or-conductor only — non-owners (and non-conductors) get a permission error.
+
 Use to free a slot when this ensemble is at the 20-entry cap and you want to make room. \`evicted: false\` means the ticket was already gone (TTL-expired or evicted by someone else).`, {
         ticket: zod_1.z.string().regex(validation_1.COAT_CHECK_TICKET_REGEX).max(validation_1.COAT_CHECK_TICKET_MAX).describe(`The ticket id returned by an earlier \`coat_check_put\` (≤${validation_1.COAT_CHECK_TICKET_MAX} chars).`),
     }, async (args) => {

package/dist/tools/coat-check-get.js

@@ -21,8 +21,8 @@ const maestro_signals_1 = require("../workflows/maestro-signals");
 const helpers_1 = require("./helpers");
 const validation_1 = require("../utils/validation");
 function registerCoatCheckGetTool(server, client, config, getPlayerId) {
-    (0, helpers_1.defineTool)(server, 'coat_check_get', `Redeem a coat-check ticket (#318) and pull the stashed content. Returns the entry's summary, content body, and audit info — or "not found" when the ticket is missing / expired / evicted (no error, just empty).
-
+    (0, helpers_1.defineTool)(server, 'coat_check_get', `Redeem a coat-check ticket (#318) and pull the stashed content. Returns the entry's summary, content body, and audit info — or "not found" when the ticket is missing / expired / evicted (no error, just empty).
+
 Successful redemptions bump the entry's fetch-audit counters (\`lastFetchedAt\` / \`lastFetchedBy\` / \`fetchCount\`) so the putter can later see whether anyone has redeemed. \`coat_check_list\` won't bump these — only an actual redemption counts.`, {
         ticket: zod_1.z.string().regex(validation_1.COAT_CHECK_TICKET_REGEX).max(validation_1.COAT_CHECK_TICKET_MAX).describe(`The ticket id returned by an earlier \`coat_check_put\` (≤${validation_1.COAT_CHECK_TICKET_MAX} chars).`),
     }, async (args) => {

package/dist/tools/coat-check-put.js

@@ -17,10 +17,10 @@ const maestro_signals_1 = require("../workflows/maestro-signals");
 const helpers_1 = require("./helpers");
 const validation_1 = require("../utils/validation");
 function registerCoatCheckPutTool(server, client, config, getPlayerId) {
-    (0, helpers_1.defineTool)(server, 'coat_check_put', `Stash a large content body on this ensemble's coat-check (#318). Returns a ticket id any player can redeem later via \`coat_check_get\`. Pass the ticket on a \`cue\`'s \`attachmentTicket\` field so the recipient knows what to fetch.
-
-Use this when your message body would otherwise exceed the cue's 100 KB cap — researcher reports, review-item dumps, etc. The cue body should carry a short summary; the coat-check entry holds the full artifact.
-
+    (0, helpers_1.defineTool)(server, 'coat_check_put', `Stash a large content body on this ensemble's coat-check (#318). Returns a ticket id any player can redeem later via \`coat_check_get\`. Pass the ticket on a \`cue\`'s \`attachmentTicket\` field so the recipient knows what to fetch.
+
+Use this when your message body would otherwise exceed the cue's 100 KB cap — researcher reports, review-item dumps, etc. The cue body should carry a short summary; the coat-check entry holds the full artifact.
+
 Limits: ${validation_1.COAT_CHECK_CONTENT_MAX} bytes (UTF-8) per entry, max ${validation_1.COAT_CHECK_SLOTS_MAX} live entries per ensemble. Saturation rejects with \`CoatCheckSlotsFull\` — wait for TTL or \`coat_check_evict\` an entry you own. TTL defaults to 7 days (configurable per put within [1h, 30d]).`, {
         summary: zod_1.z.string().min(1).max(validation_1.COAT_CHECK_SUMMARY_MAX).describe(`Short preamble surfaced in \`coat_check_list\` and on dashboards (≤${validation_1.COAT_CHECK_SUMMARY_MAX} chars). 1-2 sentences describing what the recipient gets if they redeem.`),
         content: zod_1.z.string().min(1).max(validation_1.COAT_CHECK_CONTENT_MAX).describe(`The full content body — markdown encouraged, opaque to the system. Max ${validation_1.COAT_CHECK_CONTENT_MAX} bytes (UTF-8).`),

package/dist/tools/fetch-state.js

@@ -38,8 +38,8 @@ const validation_1 = require("../utils/validation");
  * telemetry shows real demand.
  */
 function registerFetchStateTool(server, client, config, handle, getPlayerId) {
-    (0, helpers_1.defineTool)(server, 'fetch_state', `Read a saved-state slot for yourself or a peer. Defaults to your own "${validation_1.PLAYER_STATE_DEFAULT_KEY}" slot.
-
+    (0, helpers_1.defineTool)(server, 'fetch_state', `Read a saved-state slot for yourself or a peer. Defaults to your own "${validation_1.PLAYER_STATE_DEFAULT_KEY}" slot.
+
 Pass \`playerId\` to read a peer's slot (any player in the ensemble can read any other player's state — audit identity is recorded on each slot via \`savedBy\`). Returns a "(no state saved …)" message when the slot is empty.`, {
         key: zod_1.z.string().regex(validation_1.PLAYER_STATE_KEY_REGEX).max(validation_1.PLAYER_STATE_KEY_MAX).optional().describe(`Slot name (default "${validation_1.PLAYER_STATE_DEFAULT_KEY}").`),
         playerId: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).optional().describe('Target player name (default: self).'),

package/dist/tools/save-state.js

@@ -19,19 +19,19 @@ const signals_1 = require("../workflows/signals");
 const helpers_1 = require("./helpers");
 const validation_1 = require("../utils/validation");
 function registerSaveStateTool(server, handle, getPlayerId) {
-    (0, helpers_1.defineTool)(server, 'save_state', `Save curated state for yourself into a named slot — a peer can later read it via \`fetch_state\`, and a future restart can seed itself from this artifact instead of replaying the transcript.
-
-Recommended structure (markdown, not enforced):
-
-  ## Current task
-  ...
-  ## Findings
-  ...
-  ## Next steps
-  ...
-  ## Open questions
-  ...
-
+    (0, helpers_1.defineTool)(server, 'save_state', `Save curated state for yourself into a named slot — a peer can later read it via \`fetch_state\`, and a future restart can seed itself from this artifact instead of replaying the transcript.
+
+Recommended structure (markdown, not enforced):
+
+  ## Current task
+  ...
+  ## Findings
+  ...
+  ## Next steps
+  ...
+  ## Open questions
+  ...
+
 Limits: ${validation_1.PLAYER_STATE_CONTENT_MAX} bytes per slot, max ${validation_1.PLAYER_STATE_SLOTS_MAX} slots per player. Slot key defaults to "${validation_1.PLAYER_STATE_DEFAULT_KEY}". When all ${validation_1.PLAYER_STATE_SLOTS_MAX} slots are full, saving a new key fails with \`PlayerStateSlotsFull\` — call \`clear_state\` to free a slot.`, {
         content: zod_1.z.string().min(1).max(validation_1.PLAYER_STATE_CONTENT_MAX).describe(`The state content — markdown encouraged, opaque to the system. Max ${validation_1.PLAYER_STATE_CONTENT_MAX} bytes (UTF-8).`),
         key: zod_1.z.string().regex(validation_1.PLAYER_STATE_KEY_REGEX).max(validation_1.PLAYER_STATE_KEY_MAX).optional().describe(`Slot name (default "${validation_1.PLAYER_STATE_DEFAULT_KEY}"). Alphanumeric + underscore + hyphen, max ${validation_1.PLAYER_STATE_KEY_MAX} chars.`),

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;
+}