agent-tempo 1.5.0 → 1.6.0

package/dashboard/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-tempo-dashboard",
   "private": true,
-  "version": "1.5.0",
+  "version": "1.6.0",
   "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

@@ -345,6 +345,10 @@ async function applyLineupPlayersAndSchedules(args) {
                     temporalTlsKeyPath: config.temporalTlsKeyPath,
                     isConductor: false,
                     workDir: playerWorkDir,
+                    // #672 — a `up --lineup` copilot PLAYER is also spawned directly (no
+                    // terminal) by the transient CLI → same self-kill bug as the conductor.
+                    // Skip the ppid-poll; daemon-recruit copilot (outbox.ts) keeps it.
+                    transientSpawner: true,
                 });
             }
             else {
@@ -589,6 +593,9 @@ async function start(opts) {
             temporalTlsKeyPath: config.temporalTlsKeyPath,
             isConductor: opts.conductor,
             workDir,
+            // #672 — CLI-direct copilot spawn (start path): transient `up`/`conduct`
+            // spawner → skip the ppid-poll. Daemon-recruit copilot (outbox.ts) omits it.
+            transientSpawner: true,
         });
         out.success(`Launched copilot bridge "${sessionName}" (pid ${pid ?? 'unknown'})`);
     }
@@ -1304,6 +1311,10 @@ async function up(opts) {
             temporalTlsKeyPath: config.temporalTlsKeyPath,
             isConductor: true,
             workDir: process.cwd(),
+            // #672 — the `up` CLI is a TRANSIENT spawner; the detached bridge must NOT
+            // ppid-poll it (would self-kill seconds after launch → lease never renews →
+            // all players detach). The daemon-recruit path (outbox.ts) omits this.
+            transientSpawner: true,
         }));
     }
     else if (conductorAgent === 'pi') {

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

@@ -1,3 +1,18 @@
+import type { AgentType } from '../types';
+/**
+ * Agents valid as a persistent `defaultAgent` — the conductor-capable PRODUCTION
+ * agents. `defaultAgent` drives the conductor that `up` / `start` / `conduct`
+ * spawn when no `--agent` is given (`cli.ts` `resolvedAgent`), and the
+ * conductor-spawn branch only realises `copilot` / `pi` / else→`claude`. So:
+ *   - `mock` is DEV-ONLY (recruit pre-flight rejects it outside dev mode) — never
+ *     a persistent default.
+ *   - the headless adapters (`claude-api` / `opencode` / `claude-code-headless`)
+ *     can't be a conductor — they'd silently fall through to `claude` — so they
+ *     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).
+ */
+export declare const VALID_DEFAULT_AGENTS: readonly AgentType[];
 /** 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

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALID_DEFAULT_AGENTS = void 0;
 exports.configInteractive = configInteractive;
 exports.configSet = configSet;
 exports.configShow = configShow;
@@ -41,6 +42,20 @@ const readline = __importStar(require("readline"));
 const config_1 = require("../config");
 const config_2 = require("../config");
 const out = __importStar(require("./output"));
+/**
+ * Agents valid as a persistent `defaultAgent` — the conductor-capable PRODUCTION
+ * agents. `defaultAgent` drives the conductor that `up` / `start` / `conduct`
+ * spawn when no `--agent` is given (`cli.ts` `resolvedAgent`), and the
+ * conductor-spawn branch only realises `copilot` / `pi` / else→`claude`. So:
+ *   - `mock` is DEV-ONLY (recruit pre-flight rejects it outside dev mode) — never
+ *     a persistent default.
+ *   - the headless adapters (`claude-api` / `opencode` / `claude-code-headless`)
+ *     can't be a conductor — they'd silently fall through to `claude` — so they
+ *     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).
+ */
+exports.VALID_DEFAULT_AGENTS = ['claude', 'copilot', 'pi'];
 // NOTE: `createTemporalConnection` is dynamic-imported inside `configInteractive`'s
 // connection-test step (issue #157 PR C). Top-level static import would pull in
 // `@temporalio/client`, defeating the crash-proof property of `config show` /
@@ -131,11 +146,11 @@ async function configInteractive() {
         config.temporalTlsKeyPath = await ask('TLS key path', existing.temporalTlsKeyPath);
     }
     // Default agent type
-    const agentChoice = await choose('Default agent', ['claude', 'copilot']);
-    if (agentChoice === 'copilot') {
-        config.defaultAgent = 'copilot';
+    const agentChoice = await choose('Default agent', [...exports.VALID_DEFAULT_AGENTS]);
+    if (agentChoice !== 'claude') {
+        config.defaultAgent = agentChoice;
     }
-    // Don't set defaultAgent if claude — it's the default, keeps config clean
+    // Don't set defaultAgent if claude — it's the implicit default, keeps config clean
     (0, config_1.saveConfigFile)(config);
     out.success(`Saved to ${config_1.CONFIG_FILE_PATH}`);
     // Test connection
@@ -190,9 +205,9 @@ function configSet(key, value) {
         out.log(`  Valid keys: ${Object.keys(keyMap).join(', ')}`);
         process.exit(1);
     }
-    // Validate agent type
-    if (configKey === 'defaultAgent' && value !== 'claude' && value !== 'copilot') {
-        out.error(`Invalid agent type: "${value}". Must be "claude" or "copilot".`);
+    // Validate agent type — restrict to the conductor-capable production agents.
+    if (configKey === 'defaultAgent' && !exports.VALID_DEFAULT_AGENTS.includes(value)) {
+        out.error(`Invalid agent type: "${value}". Must be one of: ${exports.VALID_DEFAULT_AGENTS.join(', ')}.`);
         process.exit(1);
     }
     config[configKey] = value;

package/dist/client/core.js

@@ -1167,6 +1167,21 @@ function createTempoClientCore(client, opts = {}) {
                 return false;
             }
         },
+        async ensembleExists(ensemble) {
+            // #673 — STRONGLY-CONSISTENT existence check. `describe()` the per-ensemble
+            // maestro HUB (started at `up`/creation via `ensureMaestroWorkflow`) — it
+            // reflects a just-started workflow IMMEDIATELY, unlike `listEnsembles`
+            // (Temporal visibility, eventually consistent on Cloud). Only RUNNING
+            // counts as "exists": a TERMINATED/COMPLETED hub (destroyed ensemble) → false,
+            // and a never-created hub throws WorkflowNotFoundError → false.
+            try {
+                const desc = await handle((0, config_1.maestroWorkflowId)(ensemble)).describe();
+                return desc.status.name === 'RUNNING';
+            }
+            catch {
+                return false;
+            }
+        },
         // ── Maestro session (TUI-owned workflow for two-way messaging) ──
         async ensureMaestroSession(ensemble) {
             const workflowId = (0, config_1.sessionWorkflowId)(ensemble, 'maestro');

package/dist/client/interface.d.ts

@@ -428,6 +428,15 @@ export interface TempoClientCore {
     isConnected(): Promise<boolean>;
     /** Check if the Global Maestro workflow is running. */
     hasGlobalMaestro(): Promise<boolean>;
+    /**
+     * #673 — STRONGLY-CONSISTENT existence check for an ensemble: `describe()` the
+     * per-ensemble maestro hub workflow (started at `up`/creation) and report
+     * whether it's RUNNING. Unlike {@link listEnsembles} (Temporal VISIBILITY,
+     * eventually consistent on Cloud), `describe` reflects a just-started workflow
+     * immediately — the SSE existence gate uses it as a fallback so a fresh
+     * ensemble isn't 404'd before visibility catches up.
+     */
+    ensembleExists(ensemble: string): Promise<boolean>;
     /**
      * Subscribe to the per-ensemble SSE event stream exposed by the daemon
      * at `/v1/events/:ensemble`. Returns an `AsyncIterable<TempoEvent>` —

package/dist/config.d.ts

@@ -121,6 +121,15 @@ export declare const ENV: {
      * module loads (see `src/cli/dev-mode-bootstrap.ts`).
      */
     readonly DEV_MODE: "AGENT_TEMPO_DEV_MODE";
+    /**
+     * #672 — set to `'1'` by a TRANSIENT-CLI spawner (e.g. the short-lived `up`
+     * conductor) on a process it intentionally DETACHES to outlive that spawner.
+     * Tells the parent-death watchdog to skip ONLY the ppid-poll signal (which
+     * would otherwise self-kill the detached process when the transient spawner
+     * exits); the universally-correct stdin-EOF signal stays. Daemon-recruit
+     * spawns do NOT set it, so recruited adapters keep the #604 anti-leak ppid-poll.
+     */
+    readonly NO_PPID_WATCHDOG: "AGENT_TEMPO_NO_PPID_WATCHDOG";
     /**
      * Escape hatch for triple-isolated environments (ADR 0014 §5.3). When
      * set, `resolveTempoHome()` returns this path verbatim — bypassing both

package/dist/config.js

@@ -152,6 +152,15 @@ exports.ENV = {
      * module loads (see `src/cli/dev-mode-bootstrap.ts`).
      */
     DEV_MODE: 'AGENT_TEMPO_DEV_MODE',
+    /**
+     * #672 — set to `'1'` by a TRANSIENT-CLI spawner (e.g. the short-lived `up`
+     * conductor) on a process it intentionally DETACHES to outlive that spawner.
+     * Tells the parent-death watchdog to skip ONLY the ppid-poll signal (which
+     * would otherwise self-kill the detached process when the transient spawner
+     * exits); the universally-correct stdin-EOF signal stays. Daemon-recruit
+     * spawns do NOT set it, so recruited adapters keep the #604 anti-leak ppid-poll.
+     */
+    NO_PPID_WATCHDOG: 'AGENT_TEMPO_NO_PPID_WATCHDOG',
     /**
      * Escape hatch for triple-isolated environments (ADR 0014 §5.3). When
      * set, `resolveTempoHome()` returns this path verbatim — bypassing both

package/dist/http/server.js

@@ -546,9 +546,20 @@ async function handle(req, res, ctx) {
         }
         // Validate existence before opening the SSE stream — clean 404 when
         // the ensemble was never live, instead of an empty stream.
+        //
+        // #673 — `listEnsembles` is a Temporal VISIBILITY query (eventually
+        // consistent; ~seconds behind on Temporal Cloud), so immediately after
+        // `up`/creation the just-started maestro hub isn't indexed yet and this
+        // gate would 404 — which the subscribe client classes as PERMANENT, leaving
+        // the TUI stuck on "Loading messages…". Before 404'ing, fall back to a
+        // STRONGLY-CONSISTENT describe of the maestro hub (`ensembleExists`): a
+        // RUNNING hub means the ensemble is live even if visibility hasn't caught up.
         const list = await ctx.client.listEnsembles().catch(() => []);
         if (!list.find((e) => e.name === ensemble)) {
-            return (0, responses_1.errorResponse)(res, 404, { error: 'ensemble-not-found', ensemble });
+            const existsStrong = await ctx.client.ensembleExists(ensemble).catch(() => false);
+            if (!existsStrong) {
+                return (0, responses_1.errorResponse)(res, 404, { error: 'ensemble-not-found', ensemble });
+            }
         }
         const bus = ctx.aggregate.getOrCreateEnsembleBus(ensemble);
         return (0, sse_handler_1.handleSseRequest)(req, res, {

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.
      */

package/dist/pi/cue-pump.js

@@ -1,6 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CuePump = void 0;
+exports.buildPiInjector = buildPiInjector;
+/**
+ * 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.
+ */
+function buildPiInjector(rt) {
+    if (!rt)
+        return null;
+    const pi = rt.pi;
+    const send = typeof pi?.sendMessage === 'function' ? pi.sendMessage.bind(pi) : null;
+    if (send) {
+        const sendUser = typeof pi?.sendUserMessage === 'function' ? pi.sendUserMessage.bind(pi) : null;
+        return {
+            inject: (msg, opts) => send(msg, opts),
+            ...(sendUser ? { escalate: (text) => sendUser(text) } : {}),
+            lastTurnStartAt: () => rt.lastTurnStartAt,
+        };
+    }
+    const session = rt.session;
+    if (session) {
+        return {
+            inject: (msg, opts) => session.sendCustomMessage(msg, opts),
+            lastTurnStartAt: () => rt.lastTurnStartAt,
+        };
+    }
+    return null;
+}
 const DEFAULT_POLL_MS = 1_000;
 const log = (...args) => {
     // eslint-disable-next-line no-console
@@ -8,14 +38,22 @@ const log = (...args) => {
 };
 class CuePump {
     source;
-    resolveSession;
+    resolveInjector;
     intervalMs;
+    now;
     timer = null;
     draining = false;
+    /**
+     * 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).
+     */
+    lastInject = null;
     constructor(opts) {
         this.source = opts.source;
-        this.resolveSession = opts.resolveSession;
+        this.resolveInjector = opts.resolveInjector;
         this.intervalMs = opts.intervalMs ?? DEFAULT_POLL_MS;
+        this.now = opts.now ?? Date.now;
     }
     start() {
         if (this.timer)
@@ -33,28 +71,40 @@ class CuePump {
         }
     }
     /**
-     * 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.
      */
     async tick() {
         if (this.draining)
             return;
         this.draining = true;
         try {
+            const injector = this.resolveInjector();
+            // (1) Escalation check — runs even with no new pending. If the previous
+            // tick injected a cue via pi.sendMessage and NO turn has started since, the
+            // cue may be sitting in a cold-idle agent's queue unprocessed → re-inject as
+            // a user message (which always wakes a turn). Once per cue.
+            await this.maybeEscalate(injector);
             const pending = await this.source.fetchPending();
             if (pending.length === 0)
                 return;
-            const session = this.resolveSession();
-            if (!session) {
-                // No live session yet — leave cues queued; next tick retries.
+            if (!injector) {
+                // No live injection target yet (no `pi` handle / session) — leave cues
+                // queued; next tick retries once an instance attaches/rebinds. Logged so a
+                // live bring-up can see cues are HELD (not lost) while waiting to attach.
+                log(`no live injector — holding ${pending.length} cue(s) for next tick`);
                 return;
             }
             const delivered = [];
+            let lastDeliveredText = null;
             for (const msg of pending) {
+                const content = msg.from ? `[cue from ${msg.from}] ${msg.text}` : msg.text;
                 try {
-                    await this.injectCue(session, msg);
+                    await this.injectCue(injector, msg, content);
                     delivered.push(msg.id);
+                    lastDeliveredText = content;
                 }
                 catch (err) {
                     log(`failed to inject cue ${msg.id}:`, err);
@@ -63,18 +113,54 @@ class CuePump {
                 }
             }
             await this.source.ackDelivered(delivered);
+            // Track ONLY the LAST cue injected via the escalation-eligible route so the
+            // NEXT tick can re-inject it as a user message if no turn started. Tracking
+            // just the last is intentional and does NOT drop earlier cues' delivery:
+            // every cue in this batch was already injected via pi.sendMessage (queued in
+            // Pi), so they ALL drain once any turn starts — escalation only needs to WAKE
+            // a turn, and re-injecting one cue as a user message does exactly that. The
+            // session-fallback route omits `escalate` → no tracking.
+            if (injector.escalate && lastDeliveredText !== null) {
+                this.lastInject = { text: lastDeliveredText, injectedAt: this.now(), escalated: false };
+            }
         }
         finally {
             this.draining = false;
         }
     }
     /**
-     * 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.
+     */
+    async maybeEscalate(injector) {
+        const pending = this.lastInject;
+        if (!pending || pending.escalated)
+            return;
+        if (!injector?.escalate)
+            return;
+        const turnAt = injector.lastTurnStartAt();
+        if (turnAt !== null && turnAt >= pending.injectedAt) {
+            // A turn started after the inject → the cue was picked up; stop tracking.
+            this.lastInject = null;
+            return;
+        }
+        try {
+            await injector.escalate(pending.text);
+            pending.escalated = true;
+            log('escalated un-woken cue via sendUserMessage');
+        }
+        catch (err) {
+            log('cue escalation failed:', err);
+        }
+    }
+    /**
+     * 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.
      */
-    async injectCue(session, msg) {
-        const content = msg.from ? `[cue from ${msg.from}] ${msg.text}` : msg.text;
+    async injectCue(injector, msg, content) {
         // LOAD-BEARING Pi-runtime invariant (D10) — confirmed sound through Pi 0.78.x
         // (researcher-cited; a D6 "behaviors-to-revalidate-on-bump" item):
         //   peer cue     = { deliverAs: 'followUp', triggerTurn: true } → QUEUES; drains
@@ -87,9 +173,10 @@ class CuePump {
         // The guarantee this comment protects: a future Pi version MUST keep followUp
         // non-interrupting AND triggerTurn a no-op-while-busy. If that regresses, peer
         // cues silently become preemptions, defeating operator-vs-peer. Not unit-testable
-        // here (the session is mocked) — locked by researcher confirmation + the D6 Pi
-        // version floor (≥ #2860 + #5115) + a real-Pi mid-turn integration smoke.
-        await session.sendCustomMessage({ customType: 'cue', content, display: true }, { deliverAs: msg.isMaestro ? 'steer' : 'followUp', triggerTurn: true });
+        // here (the injector is mocked) — locked by researcher confirmation + the D6 Pi
+        // version floor (≥ #2860 + #5115) + a real-Pi mid-turn integration smoke. The
+        // #677 sendUserMessage escalation is the belt-and-suspenders for a missed wake.
+        await injector.inject({ customType: 'cue', content, display: true }, { deliverAs: msg.isMaestro ? 'steer' : 'followUp', triggerTurn: true });
     }
 }
 exports.CuePump = CuePump;