agent-tempo 1.5.1 → 1.6.1

package/dashboard/package.json

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

package/dist/activities/outbox.d.ts

@@ -1,6 +1,6 @@
 import { Client } from '@temporalio/client';
 import { Config } from '../config';
-import { AgentType, MockMode, DetachReason } from '../types';
+import { AgentType, AttachmentPhase, MockMode, DetachReason } from '../types';
 import type { ClaudeCodeHeadlessPermissionMode } from '../adapters/claude-code-headless/types';
 import type { IngestTokenRegistry } from '../http/ingest-registry';
 import type { GateRegistry } from '../http/gate-registry';
@@ -180,6 +180,12 @@ export interface SpawnProcessInput {
 export interface OutboxActivityResult {
     success: boolean;
     error?: string;
+    /**
+     * Human-readable note for a non-failure outcome the caller may surface — e.g.
+     * #676 FIX-3's "skipped duplicate spawn" no-op. Floor today is the daemon log;
+     * structured here so a future workflow-side relay can surface it to the operator.
+     */
+    note?: string;
 }
 export interface RecruitResult extends OutboxActivityResult {
     /** Session UUID assigned at recruit time. */
@@ -214,4 +220,11 @@ export interface OutboxActivities {
  *   destroy path REVOKES it. Optional: undefined disables ingest-token minting
  *   (e.g. the dev test harness that constructs activities without the daemon).
  */
+/**
+ * #676 FIX-3 — should spawnProcess SKIP as a duplicate dispatch? TRUE iff this is
+ * a FRESH recruit (no `attachmentId` handoff) AND a live adapter is already
+ * attached. A restart/migrate carries `attachmentId` (the handoff to its fresh
+ * claim — phase is legitimately live) → never skipped. Pure + exported for tests.
+ */
+export declare function shouldSkipDuplicateSpawn(attachmentId: string | undefined, phase: AttachmentPhase): boolean;
 export declare function createOutboxActivities(client: Client, config: Config, ingestTokens?: IngestTokenRegistry, gate?: GateRegistry): OutboxActivities;

package/dist/activities/outbox.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldSkipDuplicateSpawn = shouldSkipDuplicateSpawn;
 exports.createOutboxActivities = createOutboxActivities;
 const client_1 = require("@temporalio/client");
 const activity_1 = require("@temporalio/activity");
@@ -144,6 +145,17 @@ function classifyAndRethrow(err, contextPrefix) {
  *   destroy path REVOKES it. Optional: undefined disables ingest-token minting
  *   (e.g. the dev test harness that constructs activities without the daemon).
  */
+/**
+ * #676 FIX-3 — should spawnProcess SKIP as a duplicate dispatch? TRUE iff this is
+ * a FRESH recruit (no `attachmentId` handoff) AND a live adapter is already
+ * attached. A restart/migrate carries `attachmentId` (the handoff to its fresh
+ * claim — phase is legitimately live) → never skipped. Pure + exported for tests.
+ */
+function shouldSkipDuplicateSpawn(attachmentId, phase) {
+    if (attachmentId)
+        return false; // restart/migrate handoff — must spawn
+    return phase === 'attached' || phase === 'processing' || phase === 'awaiting';
+}
 function createOutboxActivities(client, config, ingestTokens, gate) {
     return {
         async deliverCue(input) {
@@ -315,6 +327,35 @@ function createOutboxActivities(client, config, ingestTokens, gate) {
             const { targetName, workDir, isConductor, agent, systemPrompt, ensemble, temporalAddress, temporalNamespace, agentDefinition, agentDefinitionPath, nativeResolvable, resume, sessionId, allowedTools, claudeBin, attachmentId, attachmentRunId, adapterId, mockMode, mockScenario, model, permissionMode, dangerouslySkipPermissions, toolAccess } = input;
             // Read secrets from the worker's config closure — never from workflow state
             const { temporalApiKey, temporalTlsCertPath, temporalTlsKeyPath } = config;
+            // #676 FIX-3 — double-dispatch backstop (ACTIVITY-level; no workflow/bundle
+            // touch). A FRESH recruit (NO attachmentId) of a name that ALREADY has a live
+            // adapter is a duplicate dispatch → skip the spawn so we don't race a second
+            // adapter for the lease. attachmentId PRESENT = a restart/migrate HANDOFF to a
+            // fresh claim (phase is legitimately {attached|processing|awaiting} from that
+            // claim) → MUST NOT skip, or restart attaches to a non-existent adapter.
+            // Guard ABOVE the agent switch so it covers every agent. TOCTOU best-effort —
+            // claimAttachment's expectedAttachmentId arbitrates the rare race.
+            if (!attachmentId) {
+                const checkWorkflowId = isConductor ? (0, config_1.conductorWorkflowId)(ensemble) : (0, config_1.sessionWorkflowId)(ensemble, targetName);
+                try {
+                    const info = await client.workflow.getHandle(checkWorkflowId).query(signals_1.attachmentInfoQuery);
+                    if (shouldSkipDuplicateSpawn(attachmentId, info.phase)) {
+                        // Corrected message (architect): force does NOT bypass this skip under
+                        // FIX-3(a), so do NOT tell the operator to pass force. Replace-a-live-
+                        // adapter is restart/migrate's lane; a stale session self-heals in ~90s.
+                        const note = `recruit skipped: player "${targetName}" is already attached (phase=${info.phase}) — ` +
+                            `spawning now would create a duplicate adapter racing the live session. To replace it, ` +
+                            `use \`restart\` (same host) or \`migrate\` (other host). If the session is actually stale, ` +
+                            `its lease expires and it's reaped within ~90s, after which recruit spawns normally.`;
+                        log(`[#676 FIX-3] ${note}`);
+                        return { success: true, note };
+                    }
+                }
+                catch (err) {
+                    // Not-queryable-yet / transient → fall through to spawn (best-effort guard).
+                    log(`FIX-3 attachment pre-check inconclusive for "${targetName}" — proceeding to spawn: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
             try {
                 if (agent === 'mock') {
                     // ADR 0014 PR-2 — mock adapter spawns headless. No terminal,

package/dist/cli/commands.js

@@ -938,6 +938,7 @@ function temporalCliExists() {
 }
 function registerSearchAttributes(temporalAddress, namespace = 'default') {
     let failed = 0;
+    let permissionBlocked = 0;
     for (const attr of sa_preflight_1.REQUIRED_SEARCH_ATTRIBUTES) {
         const r = (0, sa_preflight_1.registerSearchAttribute)(attr, temporalAddress, namespace);
         switch (r.status) {
@@ -948,17 +949,33 @@ function registerSearchAttributes(temporalAddress, namespace = 'default') {
                 out.dim(`  ${attr.name} (already registered)`);
                 break;
             case 'failed':
-                // Surface the real error — pre-#605 this branch was silently
-                // labeled "already exists" and the operator only discovered the
-                // problem hours later when workflow start failed with
-                // INVALID_ARGUMENT. Most common cause on the SQLite dev server is
-                // the 10-Keyword-per-namespace cap (often hit when a namespace
-                // accumulates both old + new wire-rename attribute families).
-                failed++;
-                out.warn(`Failed to register ${attr.name}: ${r.detail}`);
+                // A PERMISSION error (Temporal Cloud namespace API keys can't reach the
+                // operator service) means we can't tell whether the SA exists — NOT that
+                // it's missing. Don't print a scary per-attr "Failed to register" or count
+                // it as a failure; collapse to ONE soft line below and PROCEED. Reserve
+                // the per-attr warning + hard "will fail" conclusion for DEFINITIVE
+                // failures (e.g. the SQLite dev server's 10-Keyword-per-namespace cap).
+                if ((0, sa_preflight_1.isPermissionError)(r.detail)) {
+                    permissionBlocked++;
+                }
+                else {
+                    failed++;
+                    out.warn(`Failed to register ${attr.name}: ${r.detail}`);
+                }
                 break;
         }
     }
+    // Permission-blocked (normal on Temporal Cloud): one accurate, non-alarming
+    // line — we couldn't manage the SAs, but that doesn't mean they're missing.
+    if (permissionBlocked > 0) {
+        const saList = sa_preflight_1.REQUIRED_SEARCH_ATTRIBUTES.map((a) => `${a.name}:${a.type}`).join(', ');
+        out.warn(`Couldn't verify search attributes — this credential lacks permission to manage them ` +
+            `(normal on Temporal Cloud, where search attributes are managed via the Cloud UI or tcld). ` +
+            `If workflow starts fail with "search attribute ... is not defined", create these ` +
+            `${sa_preflight_1.REQUIRED_SEARCH_ATTRIBUTES.length} via the Cloud UI / tcld: ${saList}. ` +
+            `Otherwise this is safe to ignore.`);
+    }
+    // DEFINITIVE failures genuinely block — keep the hard, actionable conclusion.
     if (failed > 0) {
         out.warn(`${failed} search attribute${failed === 1 ? '' : 's'} not registered — ` +
             `workflow starts will fail. Resolve the errors above before continuing.`);

package/dist/cli/config-command.d.ts

@@ -11,8 +11,24 @@ import type { AgentType } from '../types';
  *     are not offered here.
  * Single source of truth for the interactive selector + `config set` validation
  * (#666 — adds `pi` so the new interactive Pi conductor can be the default).
+ *
+ * DELIBERATE SUBSET of `AGENT_TYPES` (NOT derived from it): this is a CAPABILITY
+ * allowlist (conductor-capable production agents), distinct from `parseAgent`'s
+ * type-VALIDITY check, which accepts all of `AGENT_TYPES`. Keep the two separate —
+ * #683 was caused by a validity check (`config.ts`) that had been hardcoded to a
+ * stale subset; this one is intentionally narrow and must stay that way.
  */
 export declare const VALID_DEFAULT_AGENTS: readonly AgentType[];
+/** True when a config key holds a credential value that must be masked on display. */
+export declare function isSecretKey(key: string): boolean;
+/**
+ * Render a secret for display: a short non-sensitive prefix (when the value is
+ * long enough that the prefix reveals only a small fraction) + a masked tail +
+ * the char count. NEVER returns the full value. Empty/unset → "(not set)".
+ *
+ * Examples: `sk-ant-…•••• (set, 47 chars)` · short secret → `•••• (set, 6 chars)`.
+ */
+export declare function maskSecret(value: string | undefined | null): string;
 /** Interactive config setup: `agent-tempo config` */
 export declare function configInteractive(): Promise<void>;
 /** Non-interactive: `agent-tempo config set <key> <value>` */

package/dist/cli/config-command.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VALID_DEFAULT_AGENTS = void 0;
+exports.isSecretKey = isSecretKey;
+exports.maskSecret = maskSecret;
 exports.configInteractive = configInteractive;
 exports.configSet = configSet;
 exports.configShow = configShow;
@@ -54,6 +56,12 @@ const out = __importStar(require("./output"));
  *     are not offered here.
  * Single source of truth for the interactive selector + `config set` validation
  * (#666 — adds `pi` so the new interactive Pi conductor can be the default).
+ *
+ * DELIBERATE SUBSET of `AGENT_TYPES` (NOT derived from it): this is a CAPABILITY
+ * allowlist (conductor-capable production agents), distinct from `parseAgent`'s
+ * type-VALIDITY check, which accepts all of `AGENT_TYPES`. Keep the two separate —
+ * #683 was caused by a validity check (`config.ts`) that had been hardcoded to a
+ * stale subset; this one is intentionally narrow and must stay that way.
  */
 exports.VALID_DEFAULT_AGENTS = ['claude', 'copilot', 'pi'];
 // NOTE: `createTemporalConnection` is dynamic-imported inside `configInteractive`'s
@@ -61,7 +69,38 @@ exports.VALID_DEFAULT_AGENTS = ['claude', 'copilot', 'pi'];
 // `@temporalio/client`, defeating the crash-proof property of `config show` /
 // `config set` — both of which are pure fs operations and must remain operable
 // under a broken Temporal SDK install.
-const SECRET_KEYS = new Set(['temporalApiKey']);
+// #684 — secret-masking. Any config field whose name looks like a credential is
+// masked in EVERY display path (show / interactive default / set echo) so a key is
+// never printed raw (terminal scrollback, screen-share, logs). Generalized on
+// purpose: a future secret added to the config is masked BY DEFAULT, not leaked.
+const SECRET_KEYS = new Set(['temporalApiKey', 'httpToken', 'readToken', 'adminToken']);
+// Matches *_API_KEY / *ApiKey / *Token / *Secret / *Password but NOT path fields
+// (e.g. temporalTlsKeyPath is a file path, not the key — it must stay visible).
+const SECRET_KEY_PATTERN = /(api[_-]?key|token|secret|password)/i;
+/** True when a config key holds a credential value that must be masked on display. */
+function isSecretKey(key) {
+    if (/path$/i.test(key))
+        return false; // *Path fields are file locations, not secrets
+    return SECRET_KEYS.has(key) || SECRET_KEY_PATTERN.test(key);
+}
+/**
+ * Render a secret for display: a short non-sensitive prefix (when the value is
+ * long enough that the prefix reveals only a small fraction) + a masked tail +
+ * the char count. NEVER returns the full value. Empty/unset → "(not set)".
+ *
+ * Examples: `sk-ant-…•••• (set, 47 chars)` · short secret → `•••• (set, 6 chars)`.
+ */
+function maskSecret(value) {
+    if (value == null || value === '')
+        return '(not set)';
+    const len = value.length;
+    // Reveal a prefix only when it's a small fraction of the whole; never for short
+    // secrets (so the output can never contain the full input — see the unit test).
+    const prefixLen = len >= 12 ? 6 : len >= 8 ? 3 : 0;
+    const prefix = value.slice(0, prefixLen);
+    const masked = prefixLen > 0 ? `${prefix}…••••` : '••••';
+    return `${masked} (set, ${len} chars)`;
+}
 /** Read a line from stdin with a prompt and optional default value. */
 function ask(prompt, defaultVal, mask = false) {
     return new Promise((resolve) => {
@@ -69,7 +108,11 @@ function ask(prompt, defaultVal, mask = false) {
             input: process.stdin,
             output: process.stdout,
         });
-        const display = defaultVal ? `${prompt} (${defaultVal}): ` : `${prompt}: `;
+        // #684 — for masked (secret) prompts NEVER echo the raw existing value as the
+        // shown default; render a masked hint instead. The real `defaultVal` is still
+        // returned on empty input, so an existing key is preserved without exposing it.
+        const shownDefault = mask ? maskSecret(defaultVal) : defaultVal;
+        const display = defaultVal ? `${prompt} (${shownDefault}): ` : `${prompt}: `;
         if (mask) {
             // For secret input: write prompt manually, mute output
             process.stdout.write(`? ${display}`);
@@ -212,7 +255,9 @@ function configSet(key, value) {
     }
     config[configKey] = value;
     (0, config_1.saveConfigFile)(config);
-    out.success(`Set ${configKey} = ${configKey.includes('Key') ? '****' : value}`);
+    // #684 — echo through the same secret-masking path so `config set temporalApiKey …`
+    // never prints the value back raw (and a *Path field still shows its location).
+    out.success(`Set ${configKey} = ${isSecretKey(configKey) ? maskSecret(value) : value}`);
 }
 /** Show current config: `agent-tempo config show` */
 function configShow() {
@@ -234,8 +279,9 @@ function configShow() {
     for (const { key, configKey } of keys) {
         const value = config[configKey];
         const source = sources[configKey];
-        const isSecret = SECRET_KEYS.has(key);
-        const display = !value ? '(not set)' : isSecret ? '****' : value;
+        // #684 — secret-like fields go through maskSecret (prefix + masked tail + char
+        // count); everything else shows its value or "(not set)".
+        const display = isSecretKey(key) ? maskSecret(value) : (!value ? '(not set)' : value);
         out.log(`  ${key.padEnd(22)} ${display.padEnd(30)} ${out.dim(source)}`);
     }
     console.log();

package/dist/cli/resolve-ensemble.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Resolve the target ensemble with the precedence every CLI command uses (#685):
+ *
+ *   `--ensemble` flag  >  positional arg  >  `AGENT_TEMPO_ENSEMBLE` env  >  `'default'`
+ *
+ * `up` previously passed a bare positional-derived value and IGNORED the
+ * `--ensemble` flag (so `agent-tempo up --ensemble pitest` silently launched in
+ * `default`). Centralizing the rule here makes it a single, unit-testable source
+ * of truth so it can't drift per-command again.
+ *
+ * Pure: `env` is injectable (defaults to the live `AGENT_TEMPO_ENSEMBLE`) so the
+ * precedence is testable without mutating `process.env`.
+ */
+export declare function resolveEnsemble(args: {
+    ensemble?: string;
+    positional: string[];
+}, env?: string | undefined): string;

package/dist/cli/resolve-ensemble.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveEnsemble = resolveEnsemble;
+const config_1 = require("../config");
+/**
+ * Resolve the target ensemble with the precedence every CLI command uses (#685):
+ *
+ *   `--ensemble` flag  >  positional arg  >  `AGENT_TEMPO_ENSEMBLE` env  >  `'default'`
+ *
+ * `up` previously passed a bare positional-derived value and IGNORED the
+ * `--ensemble` flag (so `agent-tempo up --ensemble pitest` silently launched in
+ * `default`). Centralizing the rule here makes it a single, unit-testable source
+ * of truth so it can't drift per-command again.
+ *
+ * Pure: `env` is injectable (defaults to the live `AGENT_TEMPO_ENSEMBLE`) so the
+ * precedence is testable without mutating `process.env`.
+ */
+function resolveEnsemble(args, env = process.env[config_1.ENV.ENSEMBLE]) {
+    return args.ensemble || args.positional[1] || env || 'default';
+}

package/dist/cli/sa-preflight.d.ts

@@ -88,6 +88,14 @@ export interface RegistrationResult {
     /** stderr from the temporal CLI, populated when `status === 'failed'`. */
     detail?: string;
 }
+/**
+ * True when a registration error means "this credential can't manage search
+ * attributes" (a permission/authorization failure) rather than a definitive
+ * registration failure (e.g. the SQLite dev server's 10-Keyword cap). Used to
+ * avoid the false "not registered → starts will fail" conclusion on Temporal
+ * Cloud, where SA management lives behind the Cloud UI / `tcld`.
+ */
+export declare function isPermissionError(detail: string | undefined): boolean;
 /**
  * Pure classifier — turn a temporal CLI exit into a {@link RegistrationStatus}.
  * Extracted from {@link registerSearchAttribute} so the matching rules can

package/dist/cli/sa-preflight.js

@@ -39,6 +39,7 @@ exports.isTemporalCloud = isTemporalCloud;
 exports.sdkProbeRegisteredAttributes = sdkProbeRegisteredAttributes;
 exports.formatPreflightError = formatPreflightError;
 exports.verifySearchAttributes = verifySearchAttributes;
+exports.isPermissionError = isPermissionError;
 exports.classifyRegistrationOutput = classifyRegistrationOutput;
 exports.registerSearchAttribute = registerSearchAttribute;
 exports.assertSearchAttributesOrExit = assertSearchAttributesOrExit;
@@ -284,6 +285,36 @@ async function verifySearchAttributes(opts) {
         message: formatPreflightError(missing, opts.temporalNamespace, probeError, cloud),
     };
 }
+/**
+ * Substrings signalling the credential lacks PERMISSION to manage search
+ * attributes — distinct from a definitive registration failure. Temporal Cloud
+ * namespace API keys can't reach the operator service (Cloud manages SAs via its
+ * UI / `tcld`), so `temporal operator search-attribute create/list` returns
+ * "Request unauthorized" / PermissionDenied. That means we CANNOT determine
+ * whether the SAs are registered — NOT that they're missing. Concluding
+ * "not registered → workflow starts will fail" from a permission error is a
+ * false alarm: on Cloud the SAs are typically already present and starts succeed.
+ */
+const PERMISSION_ERROR_MARKERS = [
+    'request unauthorized',
+    'permission denied',
+    'permissiondenied',
+    'unauthorized',
+    'not authorized',
+];
+/**
+ * True when a registration error means "this credential can't manage search
+ * attributes" (a permission/authorization failure) rather than a definitive
+ * registration failure (e.g. the SQLite dev server's 10-Keyword cap). Used to
+ * avoid the false "not registered → starts will fail" conclusion on Temporal
+ * Cloud, where SA management lives behind the Cloud UI / `tcld`.
+ */
+function isPermissionError(detail) {
+    if (!detail)
+        return false;
+    const d = detail.toLowerCase();
+    return PERMISSION_ERROR_MARKERS.some((m) => d.includes(m));
+}
 /**
  * Pure classifier — turn a temporal CLI exit into a {@link RegistrationStatus}.
  * Extracted from {@link registerSearchAttribute} so the matching rules can

package/dist/cli.js

@@ -62,6 +62,7 @@ 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 resolve_ensemble_1 = require("./cli/resolve-ensemble");
 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, '..');
@@ -473,7 +474,10 @@ async function main() {
             break;
         case 'up':
             await up({
-                ensemble,
+                // #685 — honor `--ensemble` (flag > positional > env > 'default'), via the
+                // shared resolver. Previously `up` passed the bare positional-derived
+                // `ensemble`, so `--ensemble <name>` was silently ignored → launched in `default`.
+                ensemble: (0, resolve_ensemble_1.resolveEnsemble)(args),
                 name: args.name,
                 lineup: args.lineup,
                 noHold: args.noHold,

package/dist/config.d.ts

@@ -334,9 +334,18 @@ export declare function loadTemporalCliConfig(): PersistedConfig;
  */
 export declare function parseTemporalYaml(content: string): PersistedConfig;
 /**
- * Parse an agent value against the {@link AgentType} union.
- * Throws when `value` is present but not a valid agent; returns `'claude'`
- * for empty/unset values so callers can use it as a source-aware default.
+ * Parse an agent value against the canonical {@link AGENT_TYPES} union — the
+ * SINGLE SOURCE OF TRUTH for agent validity (shared with `cli.ts`'s `--agent`
+ * parser). Throws when `value` is present but not a known agent; returns
+ * `'claude'` for empty/unset values so callers can use it as a source-aware default.
+ *
+ * This is a pure type-VALIDITY check — it accepts EVERY `AgentType` (including
+ * `mock` and the headless adapters). Narrower CAPABILITY constraints are gated
+ * separately downstream: the recruit pre-flight rejects `mock` outside dev mode,
+ * and `config`'s `VALID_DEFAULT_AGENTS` restricts the persistent default to the
+ * conductor-capable subset. (#683: the former hardcoded `['claude','copilot']`
+ * list was stale — it rejected `defaultAgent=pi` at config LOAD, poisoning every
+ * command before the `--agent` flag was even read.)
  */
 export declare function parseAgent(value: string | undefined, source: ConfigSource): AgentType;
 /**

package/dist/config.js

@@ -23,14 +23,8 @@ const fs_1 = require("fs");
 const path_1 = require("path");
 const os_1 = require("os");
 const zod_1 = require("zod");
+const types_1 = require("./types");
 const validation_1 = require("./utils/validation");
-// `'mock'` is a valid `AgentType` value but intentionally NOT in the resolved
-// `defaultAgent` set — recruit pre-flight rejects it outside dev mode anyway,
-// and it's never a sensible *default* (each mock spawn is configured per call
-// via the `agent: 'mock'` flag, not via the resolved chain). Listing it here
-// would only enable users to set `defaultAgent=mock` in `~/.agent-tempo/config.json`,
-// which the recruit gate would then turn around and reject in production.
-const VALID_AGENTS = ['claude', 'copilot'];
 /** Environment variable name constants — use these instead of string literals. */
 exports.ENV = {
     ENSEMBLE: 'AGENT_TEMPO_ENSEMBLE',
@@ -458,16 +452,25 @@ const AGENT_SOURCE_LABELS = {
     none: 'none',
 };
 /**
- * Parse an agent value against the {@link AgentType} union.
- * Throws when `value` is present but not a valid agent; returns `'claude'`
- * for empty/unset values so callers can use it as a source-aware default.
+ * Parse an agent value against the canonical {@link AGENT_TYPES} union — the
+ * SINGLE SOURCE OF TRUTH for agent validity (shared with `cli.ts`'s `--agent`
+ * parser). Throws when `value` is present but not a known agent; returns
+ * `'claude'` for empty/unset values so callers can use it as a source-aware default.
+ *
+ * This is a pure type-VALIDITY check — it accepts EVERY `AgentType` (including
+ * `mock` and the headless adapters). Narrower CAPABILITY constraints are gated
+ * separately downstream: the recruit pre-flight rejects `mock` outside dev mode,
+ * and `config`'s `VALID_DEFAULT_AGENTS` restricts the persistent default to the
+ * conductor-capable subset. (#683: the former hardcoded `['claude','copilot']`
+ * list was stale — it rejected `defaultAgent=pi` at config LOAD, poisoning every
+ * command before the `--agent` flag was even read.)
  */
 function parseAgent(value, source) {
     if (value == null || value === '')
         return 'claude';
-    if (!VALID_AGENTS.includes(value)) {
+    if (!types_1.AGENT_TYPES.includes(value)) {
         throw new Error(`Invalid agent "${value}" from ${AGENT_SOURCE_LABELS[source]}. ` +
-            `Valid values: ${VALID_AGENTS.join(', ')}.`);
+            `Valid values: ${types_1.AGENT_TYPES.join(', ')}.`);
     }
     return value;
 }

package/dist/pi/cue-pump.d.ts

@@ -1,10 +1,21 @@
 /**
- * Cue pump — pulls cues queued on the session workflow and injects them into
- * the LIVE Pi session via `sendCustomMessage`, then acks them.
+ * Cue pump — pulls cues queued on the session workflow and injects them into the
+ * LIVE Pi agent, then acks them.
  *
  * Pi has no reverse-RPC into a running session from Temporal, so (like the
  * existing adapters) we poll `pendingMessages` and ack via `markDelivered`.
  *
+ * ── Injection target: the STABLE `pi` handle, re-resolved per tick (#677) ──
+ * Pi 0.78.1's `SessionStartEvent` carries NO `session` field, so in INTERACTIVE
+ * mode `PiEventPayload.session` is null → the old `resolveSession` returned null
+ * every tick → the interactive Pi conductor NEVER received cues. The fix routes
+ * injection through the `pi` ExtensionAPI handle (`pi.sendMessage`), which is
+ * always live. Crucially the injector is RE-RESOLVED PER TICK from the surviving
+ * module-scope runtime — capturing it once silently dies after an interactive
+ * session switch (the runtime's `pi` is repointed on rebind). Headless still works
+ * (its `pi` is the real ExtensionAPI too); the legacy `session.sendCustomMessage`
+ * path is kept as a feature-detected fallback.
+ *
  * Injection follows D10 cue-delivery semantics:
  *   - **deliverAs** — operator cue (`msg.isMaestro`, a human steering from the
  *     Maestro dashboard) → `'steer'` (interrupt the in-flight turn so the
@@ -16,44 +27,106 @@
  *     is a no-op when a turn is already running (the message just queues), so we
  *     don't need to race-check the idle state — set it unconditionally.
  *
+ * ── Escalation (#677): turn-started → sendUserMessage ──
+ * `triggerTurn: true` on `sendMessage` SHOULD wake a cold-idle agent, but if it
+ * doesn't (e.g. a Pi regression, or a queued followUp that never drains), the
+ * cue sits unprocessed and silently. The pump therefore tracks the last cue it
+ * injected via the escalation-eligible `pi.sendMessage` route; on the NEXT tick,
+ * if NO turn started since (the runtime's `lastTurnStartAt` is still older than
+ * the inject), it re-injects the SAME cue via `pi.sendUserMessage` — a user-role
+ * message ALWAYS starts a turn. Escalation fires at most once per cue (it can't
+ * loop). The primary route stays `pi.sendMessage` so the `cue` customType +
+ * operator-vs-peer steer/followUp semantics are preserved; `sendUserMessage`
+ * loses both, so it is fallback-only.
+ *
  * Adapted from Pi's `examples/extensions/file-trigger.ts`.
  */
 import type { Message } from '../types';
-import type { PiAgentSession } from './pi-types';
+import type { ExtensionAPI, PiAgentSession, PiOutboundMessage, PiCustomMessageOptions } from './pi-types';
 /** Source of pending cues + ack — satisfied by `PiWorkflowClient`. */
 export interface CueSource {
     fetchPending(): Promise<Message[]>;
     ackDelivered(messageIds: string[]): Promise<void>;
 }
 /**
- * Resolves the CURRENT live Pi session at injection time. Re-acquired on every
- * tick rather than captured once, so a session switch (D11) never injects into
- * a stale session. Returns `null` when no session is attached.
+ * The live cue-injection capability, RE-RESOLVED each tick from the surviving
+ * runtime so a session switch never injects through a stale handle. Two routes:
+ *   - PRIMARY (`pi.sendMessage`): preserves the `cue` customType + steer/followUp
+ *     operator-vs-peer semantics. Escalation-eligible.
+ *   - FALLBACK (`session.sendCustomMessage`): legacy path; NOT escalation-eligible.
+ */
+export interface MessageInjector {
+    /** Inject one cue (D10 — `cue` customType, steer/followUp + triggerTurn). */
+    inject(msg: PiOutboundMessage, opts: PiCustomMessageOptions): void | Promise<void>;
+    /**
+     * Re-inject the SAME cue as a user-role message (always wakes a turn). Present
+     * ONLY on the escalation-eligible `pi.sendMessage` route — its presence IS the
+     * "this route can escalate" signal (the legacy session fallback omits it).
+     */
+    escalate?(text: string): void | Promise<void>;
+    /** Epoch-ms of the last observed `turn_start` (null = none yet) — drives escalation. */
+    lastTurnStartAt(): number | null;
+}
+/**
+ * Resolves the CURRENT injection capability at tick time. Re-acquired every tick
+ * rather than captured once, so a Pi instance rebuild (D11) never injects through
+ * a stale `pi`/session. Returns `null` when nothing is attached yet.
  */
-export type SessionResolver = () => PiAgentSession | null;
+export type InjectorResolver = () => MessageInjector | null;
+/** The runtime slice {@link buildPiInjector} reads — satisfied by `PiPlayerRuntime`. */
+export interface InjectorRuntime {
+    pi: ExtensionAPI | null;
+    session: PiAgentSession | null;
+    lastTurnStartAt: number | null;
+}
+/**
+ * Build the per-tick {@link MessageInjector} from the live runtime, PREFERRING the
+ * stable `pi.sendMessage` handle (interactive root-cause fix, #677) and falling
+ * back to `session.sendCustomMessage` only when `pi.sendMessage` is unavailable.
+ * Pure + feature-detected (`typeof`) so it's safe whatever Pi build is loaded and
+ * unit-testable without a real Pi.
+ */
+export declare function buildPiInjector(rt: InjectorRuntime | null | undefined): MessageInjector | null;
 export interface CuePumpOptions {
     source: CueSource;
-    resolveSession: SessionResolver;
+    resolveInjector: InjectorResolver;
     /** Poll interval (ms). */
     intervalMs?: number;
+    /** Injected clock (tests). Defaults to `Date.now`. */
+    now?: () => number;
 }
 export declare class CuePump {
     private readonly source;
-    private readonly resolveSession;
+    private readonly resolveInjector;
     private readonly intervalMs;
+    private readonly now;
     private timer;
     private draining;
+    /**
+     * The last cue injected via the escalation-eligible `pi.sendMessage` route,
+     * pending a turn-start check on the next tick. Cleared once a turn starts or
+     * once escalated (escalate-once invariant).
+     */
+    private lastInject;
     constructor(opts: CuePumpOptions);
     start(): void;
     stop(): void;
     /**
-     * One poll cycle: fetch pending cues, inject each into the live session, ack
-     * the ones successfully injected. Re-entrancy guarded so a slow tick never
-     * overlaps the next interval.
+     * One poll cycle: (1) escalate a previously-injected cue that never woke a turn,
+     * then (2) fetch pending cues, inject each into the live agent, ack the ones
+     * successfully injected. Re-entrancy guarded so a slow tick never overlaps the
+     * next interval.
      */
     tick(): Promise<void>;
     /**
-     * Inject one cue into the live session (D10 — see file header). Operator cues
+     * If a previously sendMessage-injected cue has not been followed by a turn, the
+     * `triggerTurn` wake didn't take — re-inject the SAME cue as a user-role message
+     * (always starts a turn). Escalates at most once per cue; clears the tracker
+     * once a turn is observed.
+     */
+    private maybeEscalate;
+    /**
+     * Inject one cue into the live agent (D10 — see file header). Operator cues
      * `steer` (same-turn priority); peer cues `followUp` (queue). `triggerTurn` is
      * always set: a no-op mid-turn, the required cold-idle wake otherwise.
      */