agent-tempo 1.2.0 → 1.4.0

package/dist/cli/global-wrapper.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refreshEntrypoint = refreshEntrypoint;
+exports.provisionWrapperScripts = provisionWrapperScripts;
+exports.getPathHint = getPathHint;
+/**
+ * Global wrapper provisioning — ensures `agent-tempo` is runnable from any
+ * shell without requiring `npx` or manual PATH surgery.
+ *
+ * **Strategy**: Write a thin wrapper script into `~/.agent-tempo/bin/` that
+ * reads an entrypoint pointer file (`.entrypoint`) to locate the real
+ * `dist/cli.js`. Every successful CLI boot refreshes the pointer so
+ * reinstalls (npm, pnpm, yarn — any package manager) auto-heal without
+ * user intervention.
+ *
+ * Cross-platform: emits a POSIX shell script + a `.cmd` for Windows.
+ *
+ * **Non-breaking**: If `agent-tempo` already resolves on PATH to a location
+ * outside `~/.agent-tempo/bin/` (e.g. npm global install), the wrapper is
+ * still written but the PATH hint is suppressed.
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+/** Resolved CLI entrypoint — the `dist/cli.js` of the running binary. */
+const THIS_CLI_JS = (0, path_1.resolve)(__dirname, '..', 'cli.js');
+/**
+ * Wrapper bin directory. Lives inside the agent-tempo home so it follows
+ * the same dev-mode / home-override semantics, but we hardcode `~/.agent-tempo`
+ * here because the wrapper must be stable across dev/prod modes — it's a
+ * user-facing PATH entry that shouldn't move.
+ */
+function getWrapperBinDir() {
+    return (0, path_1.join)((0, os_1.homedir)(), '.agent-tempo', 'bin');
+}
+const ENTRYPOINT_FILENAME = '.entrypoint';
+// ─── Unix wrapper ────────────────────────────────────────────────────────
+/* eslint-disable no-useless-escape */
+const UNIX_WRAPPER = [
+    '#!/bin/sh',
+    '# Auto-generated by agent-tempo. Do not edit manually.',
+    '# This wrapper resolves the agent-tempo CLI entrypoint dynamically so',
+    '# reinstalls (npm/pnpm/yarn) auto-heal without re-linking.',
+    'set -e',
+    'SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"',
+    `ENTRYPOINT_FILE="\${SCRIPT_DIR}/${ENTRYPOINT_FILENAME}"`,
+    'if [ ! -f "$ENTRYPOINT_FILE" ]; then',
+    '  echo "agent-tempo: entrypoint not configured. Run \'npx agent-tempo\' once to repair." >&2',
+    '  exit 1',
+    'fi',
+    'ENTRYPOINT="$(cat "$ENTRYPOINT_FILE")"',
+    'if [ ! -f "$ENTRYPOINT" ]; then',
+    '  echo "agent-tempo: entrypoint stale ($ENTRYPOINT). Run \'npx agent-tempo\' once to repair." >&2',
+    '  exit 1',
+    'fi',
+    'exec node "$ENTRYPOINT" "$@"',
+    '',
+].join('\n');
+// ─── Windows wrapper ─────────────────────────────────────────────────────
+const WIN_WRAPPER = [
+    '@echo off',
+    'rem Auto-generated by agent-tempo. Do not edit manually.',
+    'setlocal enabledelayedexpansion',
+    'set "SCRIPT_DIR=%~dp0"',
+    `set "ENTRYPOINT_FILE=%SCRIPT_DIR%${ENTRYPOINT_FILENAME}"`,
+    'if not exist "%ENTRYPOINT_FILE%" (',
+    '  echo agent-tempo: entrypoint not configured. Run "npx agent-tempo" once to repair. >&2',
+    '  exit /b 1',
+    ')',
+    'set /p ENTRYPOINT=<"%ENTRYPOINT_FILE%"',
+    'if not exist "%ENTRYPOINT%" (',
+    '  echo agent-tempo: entrypoint stale. Run "npx agent-tempo" once to repair. >&2',
+    '  exit /b 1',
+    ')',
+    'node "%ENTRYPOINT%" %*',
+    '',
+].join('\r\n');
+// ─── Public API ──────────────────────────────────────────────────────────
+/**
+ * Refresh the entrypoint pointer so the global wrapper resolves to the
+ * currently-running binary. Called on every successful CLI boot — cheap
+ * (one `writeFileSync`) and idempotent.
+ */
+function refreshEntrypoint() {
+    try {
+        const binDir = getWrapperBinDir();
+        (0, fs_1.mkdirSync)(binDir, { recursive: true });
+        const pointerPath = (0, path_1.join)(binDir, ENTRYPOINT_FILENAME);
+        const current = safeRead(pointerPath);
+        // Skip write if already correct — avoids unnecessary disk churn.
+        if (current === THIS_CLI_JS)
+            return;
+        // Atomic write-then-rename: a torn `.entrypoint` would break the wrapper
+        // until the next CLI boot, so stage into a tmp file and rename into place.
+        // `renameSync` is atomic on POSIX and at least better-than-torn on Windows.
+        const tmp = pointerPath + '.tmp';
+        (0, fs_1.writeFileSync)(tmp, THIS_CLI_JS, 'utf8');
+        (0, fs_1.renameSync)(tmp, pointerPath);
+    }
+    catch {
+        // Best-effort — never throw from a convenience provisioning step.
+    }
+}
+/**
+ * Ensure the wrapper scripts exist. Called once per binary version (guarded
+ * by the bootstrap cache). Returns `true` if a PATH hint should be shown
+ * to the user (i.e., the bin dir is not yet on PATH).
+ */
+function provisionWrapperScripts() {
+    try {
+        const binDir = getWrapperBinDir();
+        (0, fs_1.mkdirSync)(binDir, { recursive: true });
+        const unixPath = (0, path_1.join)(binDir, 'agent-tempo');
+        const cmdPath = (0, path_1.join)(binDir, 'agent-tempo.cmd');
+        let created = false;
+        // Write Unix wrapper if missing or outdated.
+        if (!(0, fs_1.existsSync)(unixPath) || safeRead(unixPath) !== UNIX_WRAPPER) {
+            (0, fs_1.writeFileSync)(unixPath, UNIX_WRAPPER, { mode: 0o755 });
+            created = true;
+        }
+        // Ensure executable even if content matches (chmod may have been lost).
+        try {
+            (0, fs_1.chmodSync)(unixPath, 0o755);
+        }
+        catch { /* Windows — no-op */ }
+        // Write Windows wrapper if missing or outdated.
+        if (!(0, fs_1.existsSync)(cmdPath) || safeRead(cmdPath) !== WIN_WRAPPER) {
+            (0, fs_1.writeFileSync)(cmdPath, WIN_WRAPPER);
+            created = true;
+        }
+        // Write the entrypoint pointer.
+        refreshEntrypoint();
+        // Determine if PATH hint is needed.
+        const needsPathHint = !isBinDirOnPath(binDir);
+        return { created, needsPathHint };
+    }
+    catch {
+        return { created: false, needsPathHint: false };
+    }
+}
+/**
+ * Returns a one-liner PATH hint appropriate for the current platform/shell.
+ */
+function getPathHint() {
+    const binDir = getWrapperBinDir();
+    if (process.platform === 'win32') {
+        return `Add to PATH: setx PATH "%PATH%;${binDir}"`;
+    }
+    // Unix — suggest the export for both bash and zsh.
+    return `Add to PATH: export PATH="${binDir}:$PATH"  (add to ~/.zshrc or ~/.bashrc)`;
+}
+// ─── Internals ───────────────────────────────────────────────────────────
+function safeRead(filePath) {
+    try {
+        return (0, fs_1.readFileSync)(filePath, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function isBinDirOnPath(binDir) {
+    const pathEnv = process.env.PATH || process.env.Path || '';
+    const sep = process.platform === 'win32' ? ';' : ':';
+    const dirs = pathEnv.split(sep);
+    // Windows filesystem paths are case-insensitive; normalize before comparing
+    // so `C:\Users\X\...` and `c:\users\x\...` don't produce a spurious PATH hint.
+    const norm = (p) => process.platform === 'win32' ? (0, path_1.resolve)(p).toLowerCase() : (0, path_1.resolve)(p);
+    return dirs.some((d) => norm(d) === norm(binDir));
+}

package/dist/cli/help-text.js

@@ -57,102 +57,102 @@ const types_1 = require("../types");
 // adding a new adapter automatically updates this surface.
 const AGENT_OPTIONS = types_1.AGENT_TYPES.join('|');
 function printHelp() {
-    console.log(`
-${out.bold('agent-tempo')} — Multi-session Claude Code coordination via Temporal
-
-${out.bold('Getting started:')}
-  ${out.cyan('agent-tempo up')}                  Start infrastructure, then launch the TUI with ${out.dim('agent-tempo')}
-
-${out.bold('Usage:')}
-  agent-tempo                         Launch the TUI (auto-provisions + opens home view)
-  agent-tempo <ensemble>              Launch the TUI directly into an ensemble view
-  agent-tempo <command> [options]
-
-${out.bold('Commands:')}
-  ${out.cyan('up')}                       Start infrastructure only — Temporal, daemon, MCP registration
-  ${out.cyan('down')}                     Stop infrastructure; workflows stay parked for the next ${out.dim('up')}
-  ${out.cyan('down --destroy [-y]')}      Terminate every workflow across every ensemble, then stop infrastructure
-  ${out.cyan('server')}                   Start the Temporal dev server and register search attributes
-  ${out.cyan('status')}  [ensemble]       Show active sessions and Temporal health
-  ${out.cyan('ensemble')} <sub>           Manage saved ensemble lineups (save/list/show)
-  ${out.cyan('broadcast')} <message>      Send a message to all active players
-  ${out.cyan('destroy')} <ensemble> [-y]  Terminate every workflow in one ensemble (typed confirmation)
-  ${out.cyan('attachment-info')} <name>   Inspect the V2 attachment phase + current holder
-  ${out.cyan('recall')} <name>            Read a player's message history (--limit/--offset/--preview/--from/--since/--include-sent/--json)
-  ${out.cyan('hosts')}                    List daemons polling this Temporal namespace with advertised capabilities (--all/--json)
-  ${out.cyan('refresh-host-profile')}     Re-advertise this daemon's capability profile to the global Maestro
-  ${out.cyan('restore')} <ensemble>       Restore orphaned sessions in one ensemble on this host (--all-hosts for cluster-view listing)
-  ${out.cyan('release')} [ensemble]       Release all held players (unlock outbox, deliver messages)
-  ${out.cyan('agent-types')} <sub>        Manage player type definitions (list/show/init)
-  ${out.cyan('daemon')}    <sub>          Manage the worker daemon (start/stop/status/logs)
-  ${out.cyan('dashboard')}                Open the web dashboard (--no-open / --pair / --json)
-  ${out.cyan('upgrade')}  [version]       Upgrade agent-tempo to latest (or specific version)
-  ${out.cyan('config')}                   Configure Temporal connection settings
-  ${out.cyan('init')}                     Register MCP server globally (or --project for .mcp.json)
-  ${out.cyan('preflight')}                Run preflight checks only
-  ${out.cyan('help')}                     Show this help message
-
-${out.bold('Removed — use the TUI:')}
-  ${out.dim('stop / restart / detach / migrate')}   → ${out.dim('/destroy · /restart · /shutdown')}
-  ${out.dim('conduct / start / recruit / disband')} → ${out.dim('launch `agent-tempo` · /recruit · /destroy')}
-  ${out.dim('resume')}                              → ${out.dim('/play')}
-  See https://github.com/vinceblank/agent-tempo/issues/285 for the full migration table.
-
-${out.bold('Connection options (all commands):')}
-  --temporal-address <addr>    Temporal server address (default: localhost:7233)
-  --temporal-namespace <ns>    Temporal namespace (default: default)
-  --temporal-api-key <key>     Temporal API key (for Temporal Cloud)
-  --temporal-tls-cert <path>   Path to TLS client certificate
-  --temporal-tls-key <path>    Path to TLS client key
-
-${out.bold('Other options:')}
-  --name <name>                Set session window name (up only)
-  --agent <name>               Agent type to spawn — ${AGENT_OPTIONS} (default: from config; up)
-  --dev                        Use the dev profile (~/.agent-tempo-dev, port 8474, namespace agent-tempo-dev)
-  --skip-preflight             Skip preflight checks
-  --background                 Run Temporal in background (server only)
-  --project                    Use per-project .mcp.json instead of global (init only)
-  --keep-mcp                   Don't remove MCP config (down only)
-  --keep-daemon                Don't stop the worker daemon (down only)
-  --destroy                    Also terminate every workflow (down only)
-  --kill-shared-temporal       Tear down the Temporal dev server even if the other profile is active (down only, #423)
-  -y, --yes                    Skip confirmation prompt (down --destroy, destroy)
-  --lineup <name|file>         Load ensemble lineup by name or file path (up)
-  --scenario <name|path>       Force every mock player in the lineup into mockMode:scripted with this scenario (dev-mode-only, up + --lineup)
-  --no-hold                    Skip startup hold (requires --lineup on up)
-  --ensemble <name>            Target a specific ensemble (broadcast, destroy, restore)
-  --all-hosts                  List cross-host orphans across the whole namespace (restore — read-only, #151)
-  -d, --dir <path>             Target directory (default: cwd)
-
-${out.bold('Config command:')}
-  ${out.dim('agent-tempo config')}              Interactive connection setup
-  ${out.dim('agent-tempo config show')}         Show resolved config
-  ${out.dim('agent-tempo config set <k> <v>')}  Set a config value
-
-  Settings are saved to ~/.agent-tempo/config.json.
-  Also reads ~/.config/temporalio/temporal.yaml as a fallback.
-
-  ${out.bold('Resolution order:')} CLI flag > env var > config file > temporal CLI config > default
-
-${out.bold('First time? Run this:')}
-  ${out.dim('cd your-project')}
-  ${out.dim('agent-tempo up')}
-  ${out.dim('agent-tempo')}            # Launch the TUI
-
-${out.bold('Typical workflow:')}
-  ${out.dim('agent-tempo up')}                 Start infrastructure (once per host)
-  ${out.dim('agent-tempo')}                    Launch the TUI
-  ${out.dim('agent-tempo status myband')}      Check who's active in an ensemble
-
-${out.bold('Environment:')}
-  AGENT_TEMPO_ENSEMBLE       Default ensemble name (fallback: "default")
-  TEMPORAL_ADDRESS            Default Temporal address (fallback: localhost:7233)
-  TEMPORAL_NAMESPACE          Default Temporal namespace (fallback: "default")
-  TEMPORAL_API_KEY            Temporal API key
-  TEMPORAL_TLS_CERT_PATH      Path to TLS client certificate
-  TEMPORAL_TLS_KEY_PATH       Path to TLS client key
-  AGENT_TEMPO_DEFAULT_AGENT  Default agent type: claude or copilot (fallback: claude)
-  AGENT_TEMPO_DEV_MODE       Set to "1" or "true" to enable the dev profile (alternative to --dev)
-  AGENT_TEMPO_HOME_OVERRIDE  Override the home dir entirely (escape hatch for triple-isolated envs)
+    console.log(`
+${out.bold('agent-tempo')} — Multi-session Claude Code coordination via Temporal
+
+${out.bold('Getting started:')}
+  ${out.cyan('agent-tempo up')}                  Start infrastructure, then launch the TUI with ${out.dim('agent-tempo')}
+
+${out.bold('Usage:')}
+  agent-tempo                         Launch the TUI (auto-provisions + opens home view)
+  agent-tempo <ensemble>              Launch the TUI directly into an ensemble view
+  agent-tempo <command> [options]
+
+${out.bold('Commands:')}
+  ${out.cyan('up')}                       Start infrastructure only — Temporal, daemon, MCP registration
+  ${out.cyan('down')}                     Stop infrastructure; workflows stay parked for the next ${out.dim('up')}
+  ${out.cyan('down --destroy [-y]')}      Terminate every workflow across every ensemble, then stop infrastructure
+  ${out.cyan('server')}                   Start the Temporal dev server and register search attributes
+  ${out.cyan('status')}  [ensemble]       Show active sessions and Temporal health
+  ${out.cyan('ensemble')} <sub>           Manage saved ensemble lineups (save/list/show)
+  ${out.cyan('broadcast')} <message>      Send a message to all active players
+  ${out.cyan('destroy')} <ensemble> [-y]  Terminate every workflow in one ensemble (typed confirmation)
+  ${out.cyan('attachment-info')} <name>   Inspect the V2 attachment phase + current holder
+  ${out.cyan('recall')} <name>            Read a player's message history (--limit/--offset/--preview/--from/--since/--include-sent/--json)
+  ${out.cyan('hosts')}                    List daemons polling this Temporal namespace with advertised capabilities (--all/--json)
+  ${out.cyan('refresh-host-profile')}     Re-advertise this daemon's capability profile to the global Maestro
+  ${out.cyan('restore')} <ensemble>       Restore orphaned sessions in one ensemble on this host (--all-hosts for cluster-view listing)
+  ${out.cyan('release')} [ensemble]       Release all held players (unlock outbox, deliver messages)
+  ${out.cyan('agent-types')} <sub>        Manage player type definitions (list/show/init)
+  ${out.cyan('daemon')}    <sub>          Manage the worker daemon (start/stop/status/logs)
+  ${out.cyan('dashboard')}                Open the web dashboard (--no-open / --pair / --json)
+  ${out.cyan('upgrade')}  [version]       Upgrade agent-tempo to latest (or specific version)
+  ${out.cyan('config')}                   Configure Temporal connection settings
+  ${out.cyan('init')}                     Register MCP server globally (or --project for .mcp.json)
+  ${out.cyan('preflight')}                Run preflight checks only
+  ${out.cyan('help')}                     Show this help message
+
+${out.bold('Removed — use the TUI:')}
+  ${out.dim('stop / restart / detach / migrate')}   → ${out.dim('/destroy · /restart · /shutdown')}
+  ${out.dim('conduct / start / recruit / disband')} → ${out.dim('launch `agent-tempo` · /recruit · /destroy')}
+  ${out.dim('resume')}                              → ${out.dim('/play')}
+  See https://github.com/vinceblank/agent-tempo/issues/285 for the full migration table.
+
+${out.bold('Connection options (all commands):')}
+  --temporal-address <addr>    Temporal server address (default: localhost:7233)
+  --temporal-namespace <ns>    Temporal namespace (default: default)
+  --temporal-api-key <key>     Temporal API key (for Temporal Cloud)
+  --temporal-tls-cert <path>   Path to TLS client certificate
+  --temporal-tls-key <path>    Path to TLS client key
+
+${out.bold('Other options:')}
+  --name <name>                Set session window name (up only)
+  --agent <name>               Agent type to spawn — ${AGENT_OPTIONS} (default: from config; up)
+  --dev                        Use the dev profile (~/.agent-tempo-dev, port 8474, namespace agent-tempo-dev)
+  --skip-preflight             Skip preflight checks
+  --background                 Run Temporal in background (server only)
+  --project                    Use per-project .mcp.json instead of global (init only)
+  --keep-mcp                   Don't remove MCP config (down only)
+  --keep-daemon                Don't stop the worker daemon (down only)
+  --destroy                    Also terminate every workflow (down only)
+  --kill-shared-temporal       Tear down the Temporal dev server even if the other profile is active (down only, #423)
+  -y, --yes                    Skip confirmation prompt (down --destroy, destroy)
+  --lineup <name|file>         Load ensemble lineup by name or file path (up)
+  --scenario <name|path>       Force every mock player in the lineup into mockMode:scripted with this scenario (dev-mode-only, up + --lineup)
+  --no-hold                    Skip startup hold (requires --lineup on up)
+  --ensemble <name>            Target a specific ensemble (broadcast, destroy, restore)
+  --all-hosts                  List cross-host orphans across the whole namespace (restore — read-only, #151)
+  -d, --dir <path>             Target directory (default: cwd)
+
+${out.bold('Config command:')}
+  ${out.dim('agent-tempo config')}              Interactive connection setup
+  ${out.dim('agent-tempo config show')}         Show resolved config
+  ${out.dim('agent-tempo config set <k> <v>')}  Set a config value
+
+  Settings are saved to ~/.agent-tempo/config.json.
+  Also reads ~/.config/temporalio/temporal.yaml as a fallback.
+
+  ${out.bold('Resolution order:')} CLI flag > env var > config file > temporal CLI config > default
+
+${out.bold('First time? Run this:')}
+  ${out.dim('cd your-project')}
+  ${out.dim('agent-tempo up')}
+  ${out.dim('agent-tempo')}            # Launch the TUI
+
+${out.bold('Typical workflow:')}
+  ${out.dim('agent-tempo up')}                 Start infrastructure (once per host)
+  ${out.dim('agent-tempo')}                    Launch the TUI
+  ${out.dim('agent-tempo status myband')}      Check who's active in an ensemble
+
+${out.bold('Environment:')}
+  AGENT_TEMPO_ENSEMBLE       Default ensemble name (fallback: "default")
+  TEMPORAL_ADDRESS            Default Temporal address (fallback: localhost:7233)
+  TEMPORAL_NAMESPACE          Default Temporal namespace (fallback: "default")
+  TEMPORAL_API_KEY            Temporal API key
+  TEMPORAL_TLS_CERT_PATH      Path to TLS client certificate
+  TEMPORAL_TLS_KEY_PATH       Path to TLS client key
+  AGENT_TEMPO_DEFAULT_AGENT  Default agent type: claude or copilot (fallback: claude)
+  AGENT_TEMPO_DEV_MODE       Set to "1" or "true" to enable the dev profile (alternative to --dev)
+  AGENT_TEMPO_HOME_OVERRIDE  Override the home dir entirely (escape hatch for triple-isolated envs)
 `);
 }

package/dist/cli/startup.js

@@ -134,6 +134,7 @@ const TTL_60S = 60 * 1000;
 // (#605 consolidated the two duplicated literals).
 // ─────────────────────────────────────────────────────────────────────────
 const sa_preflight_1 = require("./sa-preflight");
+const global_wrapper_1 = require("./global-wrapper");
 // ─────────────────────────────────────────────────────────────────────────
 // Semver-aware outdated-version badge rendering (#289 pin item 4)
 // ─────────────────────────────────────────────────────────────────────────
@@ -624,6 +625,16 @@ async function bootstrap(args) {
     // Steps 1–5: fail-fast on step 1 so we don't try to register MCP on an
     // incompatible Node. Each step mutates the cache in-place.
     const preflight = await stepPreflight(cache, now);
+    // Provision the global wrapper scripts (`~/.agent-tempo/bin/agent-tempo`)
+    // so the command is accessible without `npx`. Runs once per binary version
+    // (guarded by cache wipe on version change). Best-effort, non-blocking.
+    if (preflight.status !== 'failed') {
+        const { needsPathHint } = (0, global_wrapper_1.provisionWrapperScripts)();
+        if (needsPathHint) {
+            // Emit a one-time hint to stderr (won't pollute --json output).
+            process.stderr.write(`\n  hint: ${(0, global_wrapper_1.getPathHint)()}\n\n`);
+        }
+    }
     // Steps 2 + 3 are independent (MCP config is local fs/shell; Temporal
     // reachability is network), so run them in parallel — up to ~300ms
     // cold-path savings when the claude-mcp-list shell-out is slow.

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/client/core.js

@@ -432,16 +432,21 @@ function createTempoClientCore(client, opts = {}) {
             // queries reject as `QueryTimeoutError`, `Promise.allSettled` sees
             // three rejections and the existing all-rejected branch returns
             // `null` — caller treats this player's wireMeta as missing.
-            const [runIdR, messagingR, leaseR] = await Promise.allSettled([
+            const [runIdR, messagingR, leaseR, coarseR] = await Promise.allSettled([
                 (0, query_timeout_1.queryHandleWithTimeout)(h, signals_1.getRunIdQuery),
                 (0, query_timeout_1.queryHandleWithTimeout)(h, signals_1.getMessagingStateQuery),
                 (0, query_timeout_1.queryHandleWithTimeout)(h, signals_1.getLeaseStateQuery),
+                // 3c Tier-1 — coarse activity (currentTool + context usage). Bounded like
+                // the others; an older session workflow without the handler rejects and
+                // is simply absent (additive/non-breaking).
+                (0, query_timeout_1.queryHandleWithTimeout)(h, signals_1.getCoarseActivityQuery),
             ]);
             // If every query rejected, treat this as "session unreachable" —
             // the caller renders no wire-meta rather than partial sentinels.
             if (runIdR.status === 'rejected' &&
                 messagingR.status === 'rejected' &&
-                leaseR.status === 'rejected') {
+                leaseR.status === 'rejected' &&
+                coarseR.status === 'rejected') {
                 return null;
             }
             const out = {};
@@ -451,6 +456,8 @@ function createTempoClientCore(client, opts = {}) {
                 out.messaging = messagingR.value;
             if (leaseR.status === 'fulfilled')
                 out.lease = leaseR.value;
+            if (coarseR.status === 'fulfilled')
+                out.coarse = coarseR.value;
             return out;
         },
         async getMessages(ensemble, limit) {

package/dist/client/interface.d.ts

@@ -253,6 +253,12 @@ export interface TempoClientCore {
             expiresAt: number | null;
             leaseMs: number | null;
         };
+        /** 3c Tier-1 — coarse activity (currentTool + context usage) from `getCoarseActivityQuery`. */
+        coarse?: {
+            currentTool: string | null;
+            contextTokens?: number;
+            contextPercent?: number;
+        };
     } | null>;
     /** Get recent messages for an ensemble. */
     getMessages(ensemble: string, limit?: number): Promise<MaestroRelayMessage[]>;