agent-tempo 1.7.0-beta.9 → 1.7.0

package/dist/cli/commands.js

@@ -35,7 +35,9 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.status = status;
 exports.init = init;
+exports.initProject = initProject;
 exports.server = server;
+exports.formatEnsembleReadyLines = formatEnsembleReadyLines;
 exports.up = up;
 exports.formatScheduleRecurrence = formatScheduleRecurrence;
 exports.lineupScheduleToEntry = lineupScheduleToEntry;
@@ -63,6 +65,7 @@ const croner_1 = require("croner");
 const client_1 = require("@temporalio/client");
 const spawn_1 = require("../spawn");
 const probe_1 = require("../pi/probe");
+const install_1 = require("../pi/install");
 const config_1 = require("../config");
 const git_info_1 = require("../git-info");
 const connection_1 = require("../connection");
@@ -709,7 +712,10 @@ async function start(opts) {
     out.log(`\nCheck status: ${out.dim('agent-tempo status ' + opts.ensemble)}`);
     if (startLineup && startInitialStartup) {
         console.log();
-        out.log(`  ${(0, constants_1.ensembleReadyBanner)(startLineup.name, startLineup.players.length)}`);
+        // #832 — name the RESOLVED ensemble (opts.ensemble), not the lineup's `name:`.
+        const [readyLine, connectLine] = formatEnsembleReadyLines(opts.ensemble, startLineup.name, startLineup.players.length);
+        out.success(readyLine);
+        out.log(`  ${out.dim(connectLine)}`);
     }
 }
 async function status(opts) {
@@ -857,7 +863,7 @@ async function status(opts) {
 async function init(opts) {
     if (opts.project) {
         // Per-project .mcp.json mode
-        return initProject(opts.dir);
+        return initProject(opts.dir, opts.suppressNextSteps);
     }
     // Default: global install via `claude mcp add`
     if ((0, mcp_1.isGlobalMcpRegistered)() || (0, mcp_1.isMcpConfigured)(opts.dir)) {
@@ -868,22 +874,35 @@ async function init(opts) {
     const claudePath = (0, spawn_1.resolveClaudePath)();
     if (claudePath === 'claude') {
         out.warn('claude binary not found — falling back to project-level .mcp.json');
-        return initProject(opts.dir);
+        return initProject(opts.dir, opts.suppressNextSteps);
     }
-    if ((0, mcp_1.addGlobalMcp)()) {
+    const reg = (0, mcp_1.addGlobalMcp)();
+    if (reg.ok) {
         out.success('Registered agent-tempo globally (user scope)');
         out.log(`  ${out.dim('Available in all Claude Code sessions')}`);
     }
     else {
         out.warn('Failed to register globally — falling back to project-level .mcp.json');
-        return initProject(opts.dir);
+        // #818 — surface WHY (the captured `claude mcp add` stderr) so a fresh-install
+        // failure is diagnosable instead of silent. Show the first line; `DEBUG=1` logs full.
+        if (reg.error)
+            out.log(`  ${out.dim(reg.error.split('\n')[0])}`);
+        return initProject(opts.dir, opts.suppressNextSteps);
+    }
+    if (!opts.suppressNextSteps) {
+        out.log(`\nNext steps:`);
+        out.log(`  1. Start Temporal:  ${out.dim('temporal server start-dev')}`);
+        out.log(`  2. Start conductor: ${out.dim('agent-tempo conduct')}`);
     }
-    out.log(`\nNext steps:`);
-    out.log(`  1. Start Temporal:  ${out.dim('temporal server start-dev')}`);
-    out.log(`  2. Start conductor: ${out.dim('agent-tempo conduct')}`);
 }
-/** Per-project .mcp.json install (legacy, used with --project flag). */
-function initProject(dir) {
+/**
+ * Per-project .mcp.json install (legacy, used with --project flag).
+ *
+ * Exported for #818 regression coverage (the `suppressNextSteps` gate) — it only
+ * touches the filesystem + stdout, so it is unit-testable without shelling out to
+ * `claude`. Not part of the public CLI surface.
+ */
+function initProject(dir, suppressNextSteps) {
     const mcpPath = (0, path_1.join)(dir, '.mcp.json');
     const entry = {
         command: 'agent-tempo-server',
@@ -919,9 +938,13 @@ function initProject(dir) {
         out.success('Created .mcp.json with agent-tempo config');
     }
     out.log(`  ${out.dim(mcpPath)}`);
-    out.log(`\nNext steps:`);
-    out.log(`  1. Start Temporal:  ${out.dim('temporal server start-dev')}`);
-    out.log(`  2. Start conductor: ${out.dim('agent-tempo conduct')}`);
+    // #818 — `up` suppresses this stale manual-setup block (it already started
+    // Temporal + the conductor); the manual `agent-tempo init` verb still shows it.
+    if (!suppressNextSteps) {
+        out.log(`\nNext steps:`);
+        out.log(`  1. Start Temporal:  ${out.dim('temporal server start-dev')}`);
+        out.log(`  2. Start conductor: ${out.dim('agent-tempo conduct')}`);
+    }
 }
 // --- Temporal server management ---
 // #700 P1 — DEFAULT_DB_PATH, isTemporalReachable, and registerSearchAttributes
@@ -1018,6 +1041,25 @@ async function server(opts) {
         out.success('Temporal ready');
     }
 }
+/**
+ * #832 — the operator-facing "ensemble ready" lines for `up` / `conduct`.
+ *
+ * Keyed on the RESOLVED ensemble name (what `command-center` / `status` take —
+ * `--ensemble` flag > positional > env > `default`), NOT the lineup's `name:`
+ * field. The two diverge whenever any of those overrides the lineup name, so the
+ * old `Ensemble <lineup-name> is ready` line named a thing the operator can't
+ * actually `connect` to. Surfaces the connect command so the next step is one
+ * copy-paste away. Pure + exported for unit testing (the surrounding `up` does
+ * I/O and isn't unit-testable). The shared markdown {@link ensembleReadyBanner}
+ * stays lineup-keyed for the conductor's seeded directive (a different surface).
+ */
+function formatEnsembleReadyLines(ensemble, lineupName, playerCount) {
+    const plural = playerCount === 1 ? '' : 's';
+    return [
+        `Ensemble "${ensemble}" is ready (from lineup ${lineupName}). ${playerCount} player${plural} on standby.`,
+        `Connect: agent-tempo command-center ${ensemble}`,
+    ];
+}
 async function up(opts) {
     const config = (0, config_1.getConfig)(opts);
     // #689 — best-effort sweep of stale 0600 secret env files (residual from a shell
@@ -1074,7 +1116,10 @@ async function up(opts) {
         out.check('MCP configured', true);
     }
     else {
-        await init({ dir: process.cwd() });
+        // #818 — suppress init's manual "Next steps" block: `up` has already started
+        // Temporal + the conductor above, so printing "1. Start Temporal / 2. Start
+        // conductor" here is stale and misleading.
+        await init({ dir: process.cwd(), suppressNextSteps: true });
         out.check('MCP configured', true);
     }
     // Always forward all resolved Temporal settings to child processes.
@@ -1274,10 +1319,33 @@ async function up(opts) {
         if (!process.env.ANTHROPIC_API_KEY) {
             out.warn('ANTHROPIC_API_KEY is not set — the Pi conductor will fall back to Pi\'s own auth/default model. Set it if Pi needs an Anthropic key.');
         }
+        // #825 — extension-registration guard (mirrors command-center's #820 Bug-2
+        // guard). `up --agent pi` no longer passes an inline `-e` (that risked a
+        // divergent-copy double-load, #825); it now relies on the player extension
+        // being registered in Pi's settings.json. On a box that never ran `install-pi`,
+        // a plain `pi` would launch with NO extension — no claim/heartbeat, a silent
+        // non-conductor (the #820 Bug-2 failure, transplanted to the conductor). So
+        // auto-install idempotently before spawning; fail loud with the manual command
+        // if the write fails. (Checks the GLOBAL settings.json, like command-center; a
+        // user who ran `install-pi --project` still works — `pi` loads the project
+        // path and the same realpath dedupes, so the redundant global install is a
+        // harmless idempotent write, never a second load.)
+        if (!(0, install_1.arePiExtensionsRegistered)()) {
+            try {
+                const result = (0, install_1.installPiExtensions)();
+                out.log(out.dim(`  Registered the Pi extensions in ${result.settingsPath} (first-run install-pi).`));
+            }
+            catch (err) {
+                out.error('Cannot start Pi conductor — the Pi extensions are not registered and auto-install failed: ' +
+                    `${err instanceof Error ? err.message : String(err)}. Run \`agent-tempo install-pi\` manually, then retry.`);
+                process.exit(1);
+            }
+        }
         let piSpawn;
         try {
-            // resolvePiInteractiveBinary / resolvePiExtensionPath throw fail-clean
-            // (Pi CLI missing / extension unbuilt) — caught here, no terminal launched.
+            // resolvePiInteractiveBinary throws fail-clean (Pi CLI missing) — caught
+            // here, no terminal launched. #825: no more `-e`/extension resolution — the
+            // player extension loads from settings.json, registered + guarded just above.
             piSpawn = (0, spawn_1.buildPiConductorSpawn)({
                 ensemble: opts.ensemble,
                 sessionName,
@@ -1362,7 +1430,10 @@ async function up(opts) {
     // nothing is deferred — we only surface the banner on initial-startup paths.
     if (lineup && initialStartup) {
         console.log();
-        out.log(`  ${(0, constants_1.ensembleReadyBanner)(lineup.name, lineup.players.length)}`);
+        // #832 — name the RESOLVED ensemble (opts.ensemble), not the lineup's `name:`.
+        const [readyLine, connectLine] = formatEnsembleReadyLines(opts.ensemble, lineup.name, lineup.players.length);
+        out.success(readyLine);
+        out.log(`  ${out.dim(connectLine)}`);
     }
     console.log();
 }

package/dist/cli/mcp.d.ts

@@ -1,7 +1,31 @@
 /** Check if agent-tempo is registered in `claude mcp list` (global user scope). */
 export declare function isGlobalMcpRegistered(): boolean;
-/** Register agent-tempo globally via `claude mcp add`. */
-export declare function addGlobalMcp(): boolean;
+/** Result of {@link addGlobalMcp} — `ok` plus the captured failure reason. */
+export interface AddGlobalMcpResult {
+    ok: boolean;
+    /**
+     * #818 — when `ok` is false, the captured failure detail (the `claude mcp add`
+     * stderr, or the error message). Lets the caller surface WHY global registration
+     * failed instead of a bare "fell back to project .mcp.json" with no diagnosis.
+     */
+    error?: string;
+}
+/**
+ * Register agent-tempo globally via `claude mcp add -s user`.
+ *
+ * #818 — global registration was observed FAILING on a fresh published-package
+ * install (Windows), and the old `catch { return false }` swallowed the reason,
+ * leaving the silent project-`.mcp.json` fallback undiagnosable. We now capture the
+ * `claude mcp add` stderr and return it so the caller can surface it; a DEBUG-gated
+ * breadcrumb (`[agent-tempo:mcp]`) records the full detail for `DEBUG=1` runs.
+ *
+ * Windows hypothesis (worth confirming when reproducing): `claude mcp add -s user`
+ * may fail to resolve/write the user-scope config — e.g. the `claude` shim on PATH
+ * resolves to a `.cmd`/`.ps1` wrapper that execFileSync can't invoke directly, or
+ * the user-scope config path under `%APPDATA%`/`%USERPROFILE%` isn't writable in
+ * that shell. The captured stderr is the first concrete signal to disambiguate.
+ */
+export declare function addGlobalMcp(): AddGlobalMcpResult;
 /** Remove agent-tempo from global MCP config via `claude mcp remove`. */
 export declare function removeGlobalMcp(): boolean;
 /** Check if agent-tempo MCP is configured (global or project-level). */

package/dist/cli/mcp.js

@@ -22,17 +22,46 @@ function isGlobalMcpRegistered() {
         return false;
     }
 }
-/** Register agent-tempo globally via `claude mcp add`. */
+/** Pull the most useful failure detail off a thrown execFileSync error. */
+function execFailureDetail(err) {
+    const e = err;
+    const stderr = e?.stderr;
+    if (stderr) {
+        const s = (Buffer.isBuffer(stderr) ? stderr.toString('utf8') : String(stderr)).trim();
+        if (s)
+            return s;
+    }
+    return e?.message ? String(e.message).trim() : String(err);
+}
+/**
+ * Register agent-tempo globally via `claude mcp add -s user`.
+ *
+ * #818 — global registration was observed FAILING on a fresh published-package
+ * install (Windows), and the old `catch { return false }` swallowed the reason,
+ * leaving the silent project-`.mcp.json` fallback undiagnosable. We now capture the
+ * `claude mcp add` stderr and return it so the caller can surface it; a DEBUG-gated
+ * breadcrumb (`[agent-tempo:mcp]`) records the full detail for `DEBUG=1` runs.
+ *
+ * Windows hypothesis (worth confirming when reproducing): `claude mcp add -s user`
+ * may fail to resolve/write the user-scope config — e.g. the `claude` shim on PATH
+ * resolves to a `.cmd`/`.ps1` wrapper that execFileSync can't invoke directly, or
+ * the user-scope config path under `%APPDATA%`/`%USERPROFILE%` isn't writable in
+ * that shell. The captured stderr is the first concrete signal to disambiguate.
+ */
 function addGlobalMcp() {
     try {
         (0, child_process_1.execFileSync)('claude', [
             'mcp', 'add', 'agent-tempo', '-s', 'user',
             '--', 'agent-tempo-server',
         ], { stdio: ['ignore', 'ignore', 'pipe'] });
-        return true;
+        return { ok: true };
     }
-    catch {
-        return false;
+    catch (err) {
+        const error = execFailureDetail(err);
+        if (process.env.DEBUG) {
+            console.error('[agent-tempo:mcp] `claude mcp add -s user` failed:', error);
+        }
+        return { ok: false, error };
     }
 }
 /** Remove agent-tempo from global MCP config via `claude mcp remove`. */

package/dist/cli/startup.js

@@ -321,8 +321,14 @@ async function stepMcpConfig(cache, cwd, now) {
             return { status: 'ok', durationMs: 0 };
         }
         // Install into global user scope (matches current `init` behavior).
-        if (!(0, mcp_1.isGlobalMcpRegistered)() && (0, mcp_1.addGlobalMcp)()) {
-            return { status: 'action-taken', durationMs: 0, detail: 'registered agent-tempo in user MCP scope' };
+        if (!(0, mcp_1.isGlobalMcpRegistered)()) {
+            const reg = (0, mcp_1.addGlobalMcp)();
+            if (reg.ok) {
+                return { status: 'action-taken', durationMs: 0, detail: 'registered agent-tempo in user MCP scope' };
+            }
+            // #818 — include the captured failure reason so the bootstrap step is diagnosable.
+            const why = reg.error ? ` (${reg.error.split('\n')[0]})` : '';
+            return { status: 'failed', durationMs: 0, detail: `Could not register agent-tempo MCP${why}. Run \`agent-tempo init\` manually.` };
         }
         return { status: 'failed', durationMs: 0, detail: 'Could not register agent-tempo MCP. Run `agent-tempo init` manually.' };
     });

package/dist/cli.js

@@ -443,7 +443,11 @@ async function main() {
         // import — an operator can open the board even when the Temporal SDK is broken.
         const { commandCenterCommand } = await Promise.resolve().then(() => __importStar(require('./cli/command-center-command')));
         await commandCenterCommand({
-            ensemble: args.positional[1],
+            // #820 (Bug 3) — route through the canonical resolver (flag > positional >
+            // env > 'default'), mirroring `up` post-#685. Previously passed the bare
+            // `positional[1]`, which command-center-command then dropped in favor of
+            // `config.ensemble` (env/default) → `command-center <ensemble>` watched 'default'.
+            ensemble: (0, resolve_ensemble_1.resolveEnsemble)(args),
             ...overrides,
         });
         return;
@@ -540,10 +544,18 @@ async function main() {
             });
             break;
         case 'destroy': {
-            const target = args.positional[1] || args.ensemble || process.env[config_1.ENV.ENSEMBLE];
-            if (!target) {
-                out.error('Usage: agent-tempo destroy <ensemble> [-y]');
-                process.exit(1);
+            // #835 — use the SHARED resolver (flag > positional > env > default) so
+            // `destroy` matches every other verb. It previously hand-rolled INVERTED
+            // precedence (`positional || ensemble || env`), so `destroy foo --ensemble
+            // bar` destroyed `foo` — the lone outlier. `destroy` is gated by a typed
+            // confirmation (or `--yes`), so the resolver's `default` fallback is safe.
+            const target = (0, resolve_ensemble_1.resolveEnsemble)(args);
+            // #835 — surface a flag-over-positional override as a non-fatal note so the
+            // flag silently winning over a DIFFERENT positional isn't a silent mask
+            // (flag wins by design — this only warns, never errors).
+            const positional = args.positional[1];
+            if (args.ensemble && positional && args.ensemble !== positional) {
+                out.warn(`note: --ensemble "${args.ensemble}" overrides positional "${positional}"`);
             }
             await destroy({
                 ensemble: target,

package/dist/client/subscribe.d.ts

@@ -81,6 +81,16 @@ export interface SubscribeDeps {
      * present (Node 20), the wrapper falls back to fetch.
      */
     EventSourceImpl?: typeof EventSource;
+    /**
+     * #826 — force the fetch transport even when a native `EventSource` is
+     * available and no token is set. The fetch path is the only one that
+     * surfaces a permanent **401/404** as a thrown {@link SubscribeHttpError};
+     * native `EventSource` swallows those into its own silent reconnect cycle.
+     * The mission-control board needs that hard-error visibility (404 → `gone`,
+     * 401 → auth hint), so it sets this. TUI / dashboard leave it unset and keep
+     * the auto-selection (native `EventSource` on a tokenless loopback board).
+     */
+    forceFetch?: boolean;
     /**
      * Override sleep — used by tests to fast-forward backoff. Accepts an
      * `AbortSignal` so the wrapper can wake early on abort.

package/dist/client/subscribe.js

@@ -216,6 +216,8 @@ function makeIterator(args) {
  * for `Authorization: Bearer …` and is the only option in Node 20.
  */
 function canUseEventSource(deps) {
+    if (deps.forceFetch)
+        return false; // #826 — caller needs throw-on-permanent
     if (deps.token)
         return false;
     return resolveEventSource(deps) !== undefined;

package/dist/daemon.d.ts

@@ -74,14 +74,13 @@ export declare function ensureDevNamespace(connection: Pick<Connection, 'workflo
  * Test-only dependency-injection seam for {@link computeHostProfile}.
  *
  * Production callers omit `deps` entirely; the defaults resolve to the
- * real probes in `daemon-adapter-versions.ts`. Tests inject stubs to
- * exercise installed-vs-not-installed scenarios deterministically
- * without touching the host filesystem. Mirrors the
- * `ProbeAdapterVersionsDeps` shape from `daemon-adapter-versions.ts`,
- * but only includes synchronous probes — `computeHostProfile` is sync
- * by contract.
+ * real probes. Tests inject stubs to exercise installed-vs-not-installed
+ * scenarios deterministically without touching the host filesystem or
+ * spawning subprocesses. All probes are synchronous — `computeHostProfile`
+ * is sync by contract.
  *
- * Added in #532 PR-2 for the copilot host-profile probe.
+ * Added in #532 PR-2 for the copilot probe; extended in #819 for pi,
+ * opencode, and claude-api probes.
  */
 export interface ComputeHostProfileDeps {
     /**
@@ -91,6 +90,44 @@ export interface ComputeHostProfileDeps {
      * `undefined` when missing or unresolvable.
      */
     resolveCopilotSdkVersionSync?: () => string | undefined;
+    /**
+     * #819 — Synchronous Pi availability probe. Default: checks Node ≥ 22.19
+     * floor via {@link checkPiNodeFloor} AND `@earendil-works/pi-coding-agent`
+     * install via {@link probeSdkInstall}. Returns `{ available: true }` when
+     * both pass, `{ available: false }` otherwise. Tests inject a stub to
+     * avoid filesystem walks and Node-version coupling.
+     */
+    probePiSync?: () => {
+        available: boolean;
+    };
+    /**
+     * #819 — Synchronous opencode availability probe. Default: checks
+     * `@opencode-ai/sdk` install via {@link probeSdkInstall} AND
+     * `opencode` binary on PATH via {@link hasOpencodeCliOnPath}. Returns
+     * `true` when both pass. Tests inject a stub.
+     */
+    probeOpencodeSync?: () => boolean;
+    /**
+     * #819 — Synchronous claude-api availability probe. Default: checks
+     * `@anthropic-ai/sdk` install via {@link probeSdkInstall} AND
+     * `ANTHROPIC_API_KEY` in the daemon's process env. Returns `true` when
+     * both pass. Tests inject a stub.
+     *
+     * Why the key is required (not SDK-only like copilot):
+     * The claude-api adapter is spawned BY the daemon and inherits the
+     * DAEMON's env (`spawn.ts` passes no explicit env; the adapter process
+     * reads its own `process.env.ANTHROPIC_API_KEY` at execution time —
+     * `src/adapters/claude-api/adapter.ts:270`). Recruit does NOT plumb the
+     * key from the recruiting session. Therefore: the daemon having the key
+     * IS the deliverability predicate — advertising when the daemon env has
+     * the key makes this probe agree exactly with what recruit can deliver.
+     * This is not a conservative heuristic; it is the precise gate.
+     *
+     * The daemon inherits its env at spawn time (`...process.env` in
+     * `src/cli/daemon.ts`). A user adding the key after the daemon is
+     * already running must restart the daemon for it to be advertised.
+     */
+    probeClaudeApiSync?: () => boolean;
 }
 /**
  * Build the daemon's capability profile from its config + runtime env.

package/dist/daemon.js

@@ -82,6 +82,8 @@ const orphans_1 = require("./reconcile/orphans");
 const agent_types_1 = require("./ensemble/agent-types");
 const pre_flight_1 = require("./adapters/claude-code-headless/pre-flight");
 const daemon_adapter_versions_1 = require("./daemon-adapter-versions");
+const sdk_probe_1 = require("./utils/sdk-probe");
+const probe_1 = require("./pi/probe");
 const log = (...args) => console.error(`[agent-tempo:daemon ${new Date().toISOString()}]`, ...args);
 /**
  * Daemon process start time, captured at module load. Issue #399 Q5.3b
@@ -304,6 +306,16 @@ function daemonVersion() {
  */
 function computeHostProfile(config, deps = {}) {
     const resolveCopilotSync = deps.resolveCopilotSdkVersionSync ?? daemon_adapter_versions_1.resolveCopilotSdkVersionSync;
+    // #819 — production defaults for new optional-adapter probes. Each default
+    // is a one-liner wrapping the real probe; tests inject stubs.
+    const probePiSyncFn = deps.probePiSync ??
+        (() => (0, probe_1.checkPiNodeFloor)().ok && (0, sdk_probe_1.probeSdkInstall)(probe_1.PI_PACKAGE)
+            ? { available: true }
+            : { available: false });
+    const probeOpencodeSyncFn = deps.probeOpencodeSync ??
+        (() => (0, sdk_probe_1.probeSdkInstall)('@opencode-ai/sdk') && (0, sdk_probe_1.hasOpencodeCliOnPath)());
+    const probeClaudeApiSyncFn = deps.probeClaudeApiSync ??
+        (() => (0, sdk_probe_1.probeSdkInstall)('@anthropic-ai/sdk') && !!process.env.ANTHROPIC_API_KEY);
     const agentTypes = (() => {
         try {
             return (0, agent_types_1.listAgentTypes)().map((a) => a.name);
@@ -353,18 +365,52 @@ function computeHostProfile(config, deps = {}) {
         // require failures, but the boot path must not crash on any
         // surprise here.
     }
+    // #819 — pi probe. Delegates to `probePiSyncFn` (injected for tests;
+    // production default checks Node ≥ 22.19 floor + SDK install). Mirrors
+    // the recruit pre-flight: both conditions must pass before advertising.
+    try {
+        if (probePiSyncFn().available && !availableAgentTypes.includes('pi')) {
+            availableAgentTypes.push('pi');
+        }
+    }
+    catch {
+        // Boot path must not crash on any probe failure.
+    }
+    // #819 — opencode probe. Delegates to `probeOpencodeSyncFn` (injected for
+    // tests; production default checks SDK install + `opencode` binary on PATH).
+    try {
+        if (probeOpencodeSyncFn() && !availableAgentTypes.includes('opencode')) {
+            availableAgentTypes.push('opencode');
+        }
+    }
+    catch {
+        // Boot path must not crash on any probe failure.
+    }
+    // #819 — claude-api probe. Delegates to `probeClaudeApiSyncFn` (injected
+    // for tests; production default checks SDK install + ANTHROPIC_API_KEY in
+    // daemon env). The key check is not a conservative heuristic — the daemon
+    // env IS the deliverability predicate (adapter inherits daemon env; recruit
+    // does not plumb a key from the caller). See ComputeHostProfileDeps for the
+    // full rationale.
+    try {
+        if (probeClaudeApiSyncFn() && !availableAgentTypes.includes('claude-api')) {
+            availableAgentTypes.push('claude-api');
+        }
+    }
+    catch {
+        // Boot path must not crash on any probe failure.
+    }
     return {
         hostname: os.hostname(),
         version: daemonVersion(),
         defaultAgent: config.defaultAgent,
-        // #520 + #532 PR-2 — was: `[config.defaultAgent]`. Now grows when
-        // the optional probes pass: `claude-code-headless` (when `claude`
-        // is on PATH AND logged in), `copilot` (when `@github/copilot-sdk`
-        // is installed). Future PRs can extend the same pattern for
-        // `claude-api` (probe `@anthropic-ai/sdk` install +
-        // ANTHROPIC_API_KEY env) and `opencode` (probe `@opencode-ai/sdk`
-        // install + `opencode` binary on PATH). Recording as an array
-        // keeps the wire shape forward-compatible.
+        // #520 + #532 PR-2 + #819 — was: `[config.defaultAgent]`. Now grows when
+        // the optional probes pass: `claude-code-headless` (when `claude` is on
+        // PATH AND logged in), `copilot` (when `@github/copilot-sdk` is installed),
+        // `pi` (when `@earendil-works/pi-coding-agent` installed + Node ≥ 22.19),
+        // `opencode` (when `@opencode-ai/sdk` installed + `opencode` on PATH),
+        // `claude-api` (when `@anthropic-ai/sdk` installed + ANTHROPIC_API_KEY in
+        // daemon env). Recording as an array keeps the wire shape forward-compatible.
         availableAgentTypes,
         availablePlayerTypes: agentTypes,
         claudeBin: config.claudeBin,

package/dist/http/deliverability.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Daemon-side cue-deliverability preflight (#822).
+ *
+ * The maestro-outbox write endpoints (`POST .../cue`, `.../ask`, `.../reset`,
+ * and the board `/handoff` which routes through `.../cue`) historically enqueued
+ * to ANY target phase and returned a bare `202 { ok: true }` — so the
+ * command-center board rendered a confident `✓` even when the target had no live
+ * adapter (phase `detached`/`gone`) and the message merely queued on the
+ * workflow inbox, undelivered until re-attach. The MCP `cue` tool already guards
+ * this (`UNDELIVERABLE_PHASES` in `src/tools/cue.ts`) but it runs in-process
+ * before the Temporal write; the HTTP surface skipped the preflight entirely.
+ *
+ * This helper mirrors that phase check for the HTTP write surface, with one
+ * deliberate product divergence (design note Part 2, Ruling A): the operator
+ * board is **warn-but-queue**, NOT hard-fail like the MCP tool. The MCP tool
+ * serves an autonomous LLM that should re-route; the board serves a human
+ * operator who wants the message to durably land and just needs to KNOW it's
+ * queued, not delivered. So the endpoint keeps the enqueue and returns the
+ * target's deliverability so the board can render `⚠ queued (detached — delivers
+ * on re-attach)` instead of `✓`.
+ *
+ * Soft-failing: the preflight is bounded (1s) and never blocks the enqueue. On
+ * timeout / query error / unresolvable target it reports `'live'` (best-effort —
+ * the same posture as the MCP tool's preflight catch).
+ */
+import type { TempoClient } from '../client/interface';
+import type { AttachmentPhase } from '../types';
+/**
+ * Phases where the target has no live adapter, so a cue/ask/reset queues on the
+ * workflow inbox undelivered (auto-redelivers on re-attach). Mirrors
+ * `UNDELIVERABLE_PHASES` in `src/tools/cue.ts` — `draining` is deliberately
+ * EXCLUDED (a brief mid-shutdown state whose adapter is still consuming pending
+ * messages; flagging it would false-positive on normal teardown).
+ */
+export declare const UNDELIVERABLE_PHASES: ReadonlySet<AttachmentPhase>;
+/** Bounded preflight window — matches the MCP cue tool's 1s operator-interactive cap. */
+export declare const DELIVERABILITY_PREFLIGHT_TIMEOUT_MS = 1000;
+/** `'queued'` = enqueued but no live adapter to receive now; `'live'` = a live
+ *  adapter is (or is best-effort assumed) present. */
+export type Delivery = 'queued' | 'live';
+export interface DeliverabilityResult {
+    delivery: Delivery;
+    /** The observed phase, when the preflight query succeeded. */
+    phase?: AttachmentPhase;
+}
+/**
+ * Bounded, soft-failing phase preflight. Returns `{ delivery: 'queued', phase }`
+ * ONLY when an undeliverable phase is positively observed; on timeout / query
+ * error / unresolvable target it returns `{ delivery: 'live' }` (best-effort —
+ * never block the enqueue). Pure of HTTP concerns so `writes.ts` and `qa.ts`
+ * share one implementation.
+ */
+export declare function checkDeliverability(client: TempoClient, ensemble: string, playerId: string): Promise<DeliverabilityResult>;
+/**
+ * Build the additive deliverability fields folded into the `202` JSON body of an
+ * outbox-enqueue endpoint. Superset shape satisfying both the design note
+ * (`delivery`/`phase`) and the QA regression bar (`queued`/`warning`):
+ *
+ * - undeliverable → `{ delivery:'queued', phase, queued:true, warning:'queued-undeliverable (<phase>)' }`
+ * - live → `{ delivery:'live', queued:false }` (NO `warning` field — a healthy
+ *   target must read as a clean success)
+ */
+export declare function deliverabilityResponseFields(r: DeliverabilityResult): {
+    delivery: Delivery;
+    queued: boolean;
+    phase?: AttachmentPhase;
+    warning?: string;
+};

package/dist/http/deliverability.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DELIVERABILITY_PREFLIGHT_TIMEOUT_MS = exports.UNDELIVERABLE_PHASES = void 0;
+exports.checkDeliverability = checkDeliverability;
+exports.deliverabilityResponseFields = deliverabilityResponseFields;
+/**
+ * Phases where the target has no live adapter, so a cue/ask/reset queues on the
+ * workflow inbox undelivered (auto-redelivers on re-attach). Mirrors
+ * `UNDELIVERABLE_PHASES` in `src/tools/cue.ts` — `draining` is deliberately
+ * EXCLUDED (a brief mid-shutdown state whose adapter is still consuming pending
+ * messages; flagging it would false-positive on normal teardown).
+ */
+exports.UNDELIVERABLE_PHASES = new Set(['detached', 'gone']);
+/** Bounded preflight window — matches the MCP cue tool's 1s operator-interactive cap. */
+exports.DELIVERABILITY_PREFLIGHT_TIMEOUT_MS = 1000;
+/** Resolve `p`, or reject with a timeout after `ms`. */
+function withTimeout(p, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('deliverability preflight timed out')), ms);
+        if (typeof timer.unref === 'function') {
+            timer.unref();
+        }
+        p.then((v) => {
+            clearTimeout(timer);
+            resolve(v);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+/**
+ * Bounded, soft-failing phase preflight. Returns `{ delivery: 'queued', phase }`
+ * ONLY when an undeliverable phase is positively observed; on timeout / query
+ * error / unresolvable target it returns `{ delivery: 'live' }` (best-effort —
+ * never block the enqueue). Pure of HTTP concerns so `writes.ts` and `qa.ts`
+ * share one implementation.
+ */
+async function checkDeliverability(client, ensemble, playerId) {
+    try {
+        const info = await withTimeout(client.attachmentInfo(ensemble, playerId), exports.DELIVERABILITY_PREFLIGHT_TIMEOUT_MS);
+        const phase = info?.phase;
+        if (phase !== undefined && exports.UNDELIVERABLE_PHASES.has(phase)) {
+            return { delivery: 'queued', phase };
+        }
+        return { delivery: 'live', ...(phase !== undefined ? { phase } : {}) };
+    }
+    catch {
+        // Timed out / query threw / no session — proceed best-effort (the message
+        // still enqueues; auto-redelivery on re-attach applies). Matches the MCP
+        // cue tool's soft-fail-to-best-effort posture.
+        return { delivery: 'live' };
+    }
+}
+/**
+ * Build the additive deliverability fields folded into the `202` JSON body of an
+ * outbox-enqueue endpoint. Superset shape satisfying both the design note
+ * (`delivery`/`phase`) and the QA regression bar (`queued`/`warning`):
+ *
+ * - undeliverable → `{ delivery:'queued', phase, queued:true, warning:'queued-undeliverable (<phase>)' }`
+ * - live → `{ delivery:'live', queued:false }` (NO `warning` field — a healthy
+ *   target must read as a clean success)
+ */
+function deliverabilityResponseFields(r) {
+    if (r.delivery === 'queued') {
+        return {
+            delivery: 'queued',
+            queued: true,
+            ...(r.phase !== undefined ? { phase: r.phase } : {}),
+            warning: `queued-undeliverable${r.phase !== undefined ? ` (${r.phase})` : ''}`,
+        };
+    }
+    return {
+        delivery: 'live',
+        queued: false,
+        ...(r.phase !== undefined ? { phase: r.phase } : {}),
+    };
+}