agent-tempo 1.5.1 → 1.6.0

package/dashboard/package.json

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

package/dist/pi/extension.d.ts

@@ -9,21 +9,9 @@ import { InnerLoopPublisher } from './inner-loop-publisher';
 /** Runtime mode. Headless = recruited unsupervised player (MD-C gate active). */
 export type PiExtensionMode = 'interactive' | 'headless';
 export type PiToolAccess = 'restricted' | 'standard' | 'full';
-/**
- * B1 runtime guard (#645 H4) — the type gate's blind spot.
- *
- * `PiEventPayload.session` is UNDECLARED in Pi 0.78's `.d.ts` — it's an
- * interactive-only RUNTIME field, so the pi-drift type gate can't assert it. In
- * INTERACTIVE mode the `session_start` payload MUST carry `session` (the cue +
- * reset pumps inject into it); a null session there means injection is silently
- * inert — a likely Pi API drift. (Headless legitimately omits it — it wires
- * `rt.session` via `setRuntimeSession` — so the guard is interactive-only.)
- *
- * Pure + injected `warn` so it unit-tests without the workflow harness.
- */
-export declare function warnIfInteractiveSessionMissing(mode: PiExtensionMode, payload: {
+export declare function noteInteractiveSessionAbsent(mode: PiExtensionMode, payload: {
     session?: unknown;
-}, warn: (msg: string) => void): void;
+}, note: (msg: string) => void): void;
 export interface PiExtensionOptions {
     /** Default `'interactive'`. Headless installs the MD-C tool_call gate. */
     mode?: PiExtensionMode;
@@ -35,7 +23,7 @@ export interface PiExtensionOptions {
  * extension-instance rebuilds. Holds the durable attachment (handle + lease +
  * heartbeat, inside `wf`), the phase driver, the cue pump, and the session ptr.
  */
-interface PiPlayerRuntime {
+export interface PiPlayerRuntime {
     readonly workflowId: string;
     readonly wf: PiWorkflowClient;
     readonly driver: PhaseDriver;
@@ -50,6 +38,19 @@ interface PiPlayerRuntime {
     /** 3d D14 — polls the workflow's pending reset → clean-wipe (newSession) + ack. */
     readonly reset: ResetPump;
     session: PiAgentSession | null;
+    /**
+     * #677 — THIS player's CURRENT Pi `ExtensionAPI` handle. Repointed on every
+     * instance rebuild (`session_start` re-bind) so the cue pump injects through the
+     * live `pi.sendMessage` (the stable interactive-injection path; Pi 0.78.1's
+     * SessionStartEvent has no `session` field). Re-resolved per tick — never captured.
+     */
+    pi: ExtensionAPI | null;
+    /**
+     * #677 — epoch-ms of the last observed `turn_start`/`agent_start`. The cue pump
+     * reads it to decide whether a sendMessage-injected cue actually woke a turn; if
+     * not, it escalates to `sendUserMessage`. `null` until the first turn starts.
+     */
+    lastTurnStartAt: number | null;
     lastSessionId?: string;
 }
 /**
@@ -94,6 +95,19 @@ export declare function __seedRuntimeForTests(workflowId: string, rt: PiPlayerRu
  * for the full singleton reset). TEST ESCAPE HATCH — do NOT call from production code.
  */
 export declare function __clearRuntimesForTests(): void;
+/**
+ * Read the live runtime for a workflowId out of the module-scope map. TEST ESCAPE
+ * HATCH — do NOT call from production code. Used by the #677 rebind test to assert
+ * the post-switch tick injects through the NEW pi (cue pump) AND that the
+ * InnerLoopPublisher rebound to it.
+ */
+export declare function __getPiRuntimeForTests(workflowId: string): PiPlayerRuntime | undefined;
+/**
+ * Reset the one-time interactive-session breadcrumb flag (#677). TEST ESCAPE HATCH
+ * — do NOT call from production code. The flag is module-scope and fires at most
+ * once per process, so tests asserting the note must reset it between cases.
+ */
+export declare function __resetInteractiveSessionNoteForTests(): void;
 /** Default export — interactive-mode extension (the human `pi` CLI entry). */
 declare const piExtension: (pi: ExtensionAPI) => void;
 export default piExtension;

package/dist/pi/extension.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.warnIfInteractiveSessionMissing = warnIfInteractiveSessionMissing;
+exports.noteInteractiveSessionAbsent = noteInteractiveSessionAbsent;
 exports.createPiExtension = createPiExtension;
 exports.detachAllPiRuntimesForExit = detachAllPiRuntimesForExit;
 exports.setRuntimeSession = setRuntimeSession;
@@ -41,6 +41,8 @@ exports.__setPiClientFactoryForTests = __setPiClientFactoryForTests;
 exports.__resetPiRuntimesForTests = __resetPiRuntimesForTests;
 exports.__seedRuntimeForTests = __seedRuntimeForTests;
 exports.__clearRuntimesForTests = __clearRuntimesForTests;
+exports.__getPiRuntimeForTests = __getPiRuntimeForTests;
+exports.__resetInteractiveSessionNoteForTests = __resetInteractiveSessionNoteForTests;
 /**
  * agent-tempo Pi extension — interactive (Phase 2) + headless (Phase 3a) runtime.
  *
@@ -93,24 +95,37 @@ const log = (...args) => {
     console.error('[agent-tempo:pi]', ...args);
 };
 const nowIso = () => new Date().toISOString();
-const PI_AGENT_TYPE = 'claude'; // Pi is not yet a first-class AgentType.
+// Pi IS a first-class AgentType (#666). #676 FIX-2: was a stale 'claude'
+// placeholder — that made a Pi session misreport its agentType metadata AND
+// recruit's mirror-fallback resolve to 'claude'.
+const PI_AGENT_TYPE = 'pi';
 /**
- * B1 runtime guard (#645 H4) — the type gate's blind spot.
+ * Interactive-session breadcrumb (#645 H4 → reworded for #677).
  *
- * `PiEventPayload.session` is UNDECLARED in Pi 0.78's `.d.ts` — it's an
- * interactive-only RUNTIME field, so the pi-drift type gate can't assert it. In
- * INTERACTIVE mode the `session_start` payload MUST carry `session` (the cue +
- * reset pumps inject into it); a null session there means injection is silently
- * inert — a likely Pi API drift. (Headless legitimately omits it — it wires
- * `rt.session` via `setRuntimeSession` — so the guard is interactive-only.)
+ * Pi 0.78.1's `SessionStartEvent` carries NO `session` field, so in INTERACTIVE
+ * mode `payload.session` is null. Pre-#677 that meant cue/reset injection was inert
+ * (it read `payload.session`), so this was a WARNING. Post-#677 injection routes
+ * through the stable `pi.sendMessage` handle (re-resolved per tick) and a missing
+ * session is the EXPECTED path — NOT an error. The "is `pi.sendMessage` still
+ * wired?" correctness signal now lives at BUILD time in the H4 drift gate
+ * (`test/pi-drift/assert.ts` `_passSendMsg` / `_sendSurfaceCallShape`), so this
+ * runtime check's correctness role is redundant.
  *
- * Pure + injected `warn` so it unit-tests without the workflow harness.
+ * What remains is value as a ONE-TIME, non-alarming boot breadcrumb: during Pi
+ * bring-up it confirms at a glance "you're on the expected 0.78.1 no-session path;
+ * cues route via pi.sendMessage." Fires AT MOST ONCE per process (the
+ * module-scope `notedInteractiveSessionAbsent` flag) — not per switch, not per
+ * tick. Pure + injected `note` so it unit-tests without the workflow harness.
  */
-function warnIfInteractiveSessionMissing(mode, payload, warn) {
-    if (mode === 'interactive' && payload.session == null) {
-        warn('WARNING: interactive session_start carried no session — cue/reset injection inert; ' +
-            'possible Pi API drift (#645)');
-    }
+let notedInteractiveSessionAbsent = false;
+function noteInteractiveSessionAbsent(mode, payload, note) {
+    if (mode !== 'interactive' || payload.session != null)
+        return;
+    if (notedInteractiveSessionAbsent)
+        return;
+    notedInteractiveSessionAbsent = true;
+    note('interactive session_start has no `session` field — expected on Pi ≥0.78.1; ' +
+        'cues/reset route via pi.sendMessage (re-resolved per tick).');
 }
 // MD-C shell/exec tool-class membership is owned by `tool-capability.ts`
 // (`classify(name) === 'exec'`, content signed off by tempo-security). F1
@@ -173,6 +188,21 @@ function createPiExtension(options = {}) {
         };
         (0, render_tools_1.renderToPi)(pi, (0, server_tools_1.buildAllTempoTools)(toolOpts));
         log(`registered tools (player=${currentPlayerId}, conductor=${isConductor}, mode=${mode})`);
+        // ── #677 PART B — interactive-only `/tempo-reset` command ──
+        // Pi's `newSession` (clean-wipe) is ExtensionCommandContext-ONLY (not on the
+        // SDK session), so an interactive Pi conductor can ONLY be reset by the operator
+        // running this command. The reset pump's interactive branch notifies the
+        // operator to run it when a peer/conductor requests a reset (operator-mediated
+        // is the ceiling). Headless players have no command surface → not registered.
+        if (mode === 'interactive' && typeof pi.registerCommand === 'function') {
+            pi.registerCommand('tempo-reset', {
+                description: "Clean-wipe this Pi session's context (agent-tempo reset).",
+                handler: async (_args, ctx) => {
+                    log('/tempo-reset — clean-wiping session context (newSession)');
+                    await ctx.newSession();
+                },
+            });
+        }
         // ── MD-C tool-access gate (HEADLESS ONLY) ──
         // Interactive Pi = a human owns their machine → no gate. Headless = recruited
         // unsupervised → MD-C governs tool access. TOOL-CLASS CHECK FIRST: shell/exec
@@ -258,6 +288,16 @@ function createPiExtension(options = {}) {
             const existing = runtimes.get(workflowId);
             if (existing) {
                 existing.session = payload.session ?? existing.session;
+                // #677 — repoint to THIS instance's `pi`. Pi rebuilds the extension
+                // instance on every session switch; the surviving runtime + its cue pump
+                // (created on first attach) re-resolve the injector from `rt.pi` each tick,
+                // so the cue pump injects through the LIVE handle, not the stale one.
+                existing.pi = pi;
+                // #677 FREEBIE — the InnerLoopPublisher was captured-once on the FIRST pi
+                // and goes stale after a switch (README:251 carry-item — same root cause).
+                // Re-start it on the new pi so its `pi.on(...)` observers track the live
+                // instance. `start()` re-registers handlers; its flush timer is idempotent.
+                existing.pub.start(pi);
                 log(`re-bound ${currentPlayerId} (Pi instance rebuilt; lease intact)`);
                 return existing;
             }
@@ -271,7 +311,11 @@ function createPiExtension(options = {}) {
             const driver = new phase_driver_1.PhaseDriver();
             const pump = new cue_pump_1.CuePump({
                 source: wf,
-                resolveSession: () => runtimes.get(workflowId)?.session ?? null,
+                // #677 — re-resolve the injector from the SURVIVING runtime each tick:
+                // prefer `rt.pi.sendMessage` (stable interactive path), fall back to
+                // `rt.session.sendCustomMessage`. Reading `runtimes.get(workflowId)` (not a
+                // captured `rt`) is what makes a post-rebind tick use the NEW pi.
+                resolveInjector: () => (0, cue_pump_1.buildPiInjector)(runtimes.get(workflowId) ?? null),
             });
             // 3c — inner-loop publisher + its loopback-HTTP sink. The client no-ops
             // unless AGENT_TEMPO_INGEST_TOKEN is present (daemon-spawned headless
@@ -285,8 +329,16 @@ function createPiExtension(options = {}) {
             const reset = new reset_pump_1.ResetPump({
                 source: wf,
                 resolveSession: () => runtimes.get(workflowId)?.session ?? null,
+                // #677 PART B — interactive can't auto-wipe (no session field / newSession is
+                // command-context-only); the reset pump notifies the operator via this handle.
+                resolvePi: () => runtimes.get(workflowId)?.pi ?? null,
             });
-            const rt = { workflowId, wf, driver, pump, pub, reset, session: payload.session ?? null };
+            const rt = {
+                workflowId, wf, driver, pump, pub, reset,
+                session: payload.session ?? null,
+                pi, // #677 — first-attach instance's pi (repointed on each rebind)
+                lastTurnStartAt: null,
+            };
             runtimes.set(workflowId, rt);
             await wf.ensureSessionWorkflow();
             const result = driver.handle('session_start', payload, nowIso());
@@ -303,8 +355,9 @@ function createPiExtension(options = {}) {
         }
         // ── Lifecycle: session_start → first attach OR re-bind ──
         pi.on('session_start', async (payload) => {
-            // B1 (#645 H4): warn loudly if interactive session_start lost its session.
-            warnIfInteractiveSessionMissing(mode, payload, log);
+            // #677: one-time INFO breadcrumb when interactive session_start has no
+            // `session` field (the expected 0.78.1 path — injection routes via pi.sendMessage).
+            noteInteractiveSessionAbsent(mode, payload, log);
             try {
                 const rt = await attachOrRebind(payload);
                 await refreshSessionId(rt, rt.session?.id);
@@ -321,6 +374,10 @@ function createPiExtension(options = {}) {
                     return;
                 if (payload.session)
                     rt.session = payload.session;
+                // #677 — a turn has begun → stamp for the cue pump's escalation check (so
+                // a sendMessage-injected cue that DID wake a turn is not re-escalated).
+                if (event === 'agent_start')
+                    rt.lastTurnStartAt = Date.now();
                 const result = rt.driver.handle(event, payload, nowIso());
                 try {
                     await rt.wf.performAction(result.action);
@@ -342,6 +399,9 @@ function createPiExtension(options = {}) {
                     return;
                 if (payload.session)
                     rt.session = payload.session;
+                // #677 — turn_start marks a live turn for the cue pump's escalation check.
+                if (event === 'turn_start')
+                    rt.lastTurnStartAt = Date.now();
                 rt.driver.handle(event, payload, nowIso());
             });
         }
@@ -441,6 +501,23 @@ function __seedRuntimeForTests(workflowId, rt) {
 function __clearRuntimesForTests() {
     runtimes.clear();
 }
+/**
+ * Read the live runtime for a workflowId out of the module-scope map. TEST ESCAPE
+ * HATCH — do NOT call from production code. Used by the #677 rebind test to assert
+ * the post-switch tick injects through the NEW pi (cue pump) AND that the
+ * InnerLoopPublisher rebound to it.
+ */
+function __getPiRuntimeForTests(workflowId) {
+    return runtimes.get(workflowId);
+}
+/**
+ * Reset the one-time interactive-session breadcrumb flag (#677). TEST ESCAPE HATCH
+ * — do NOT call from production code. The flag is module-scope and fires at most
+ * once per process, so tests asserting the note must reset it between cases.
+ */
+function __resetInteractiveSessionNoteForTests() {
+    notedInteractiveSessionAbsent = false;
+}
 /** Default export — interactive-mode extension (the human `pi` CLI entry). */
 const piExtension = createPiExtension();
 exports.default = piExtension;

package/dist/pi/index.d.ts

@@ -18,8 +18,8 @@ export { PhaseDriver } from './phase-driver';
 export type { PiPhase, WorkflowAction, PhaseDriverResult } from './phase-driver';
 export { PiWorkflowClient } from './workflow-client';
 export type { PiWorkflowClientOptions } from './workflow-client';
-export { CuePump } from './cue-pump';
-export type { CueSource, SessionResolver, CuePumpOptions } from './cue-pump';
+export { CuePump, buildPiInjector } from './cue-pump';
+export type { CueSource, MessageInjector, InjectorResolver, InjectorRuntime, CuePumpOptions, } from './cue-pump';
 export { renderToPi, toPiResult } from './render-tools';
 export { createLazyProxy } from './lazy-proxy';
 export { zodShapeToTypeBox, UnsupportedZodFeatureError } from './zod-to-typebox';

package/dist/pi/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PI_NODE_FLOOR = exports.TESTED_PI_VERSION = exports.PI_AI_PACKAGE = exports.PI_PACKAGE = exports.probePi = exports.UnsupportedZodFeatureError = exports.zodShapeToTypeBox = exports.createLazyProxy = exports.toPiResult = exports.renderToPi = exports.CuePump = exports.PiWorkflowClient = exports.PhaseDriver = exports.default = void 0;
+exports.PI_NODE_FLOOR = exports.TESTED_PI_VERSION = exports.PI_AI_PACKAGE = exports.PI_PACKAGE = exports.probePi = exports.UnsupportedZodFeatureError = exports.zodShapeToTypeBox = exports.createLazyProxy = exports.toPiResult = exports.renderToPi = exports.buildPiInjector = exports.CuePump = exports.PiWorkflowClient = exports.PhaseDriver = exports.default = void 0;
 /**
  * agent-tempo Pi integration — barrel.
  *
@@ -27,6 +27,7 @@ var workflow_client_1 = require("./workflow-client");
 Object.defineProperty(exports, "PiWorkflowClient", { enumerable: true, get: function () { return workflow_client_1.PiWorkflowClient; } });
 var cue_pump_1 = require("./cue-pump");
 Object.defineProperty(exports, "CuePump", { enumerable: true, get: function () { return cue_pump_1.CuePump; } });
+Object.defineProperty(exports, "buildPiInjector", { enumerable: true, get: function () { return cue_pump_1.buildPiInjector; } });
 var render_tools_1 = require("./render-tools");
 Object.defineProperty(exports, "renderToPi", { enumerable: true, get: function () { return render_tools_1.renderToPi; } });
 Object.defineProperty(exports, "toPiResult", { enumerable: true, get: function () { return render_tools_1.toPiResult; } });

package/dist/pi/pi-types.d.ts

@@ -243,10 +243,60 @@ export interface PiToolDefinition {
      */
     execute: (toolCallId: string, params: Record<string, unknown>, signal?: unknown, onUpdate?: unknown, ctx?: unknown) => Promise<PiToolResult> | PiToolResult;
 }
+/**
+ * The context Pi passes to a registered command handler (#677 PART B). NARROW
+ * structural slice — `/tempo-reset` only calls `newSession()` (clean-wipe).
+ * Pi's real `ExtensionCommandContext` (much larger) is assignable to this.
+ *
+ * `newSession` is command-context-ONLY in Pi — it is NOT on the SDK session
+ * object — which is exactly why an interactive Pi conductor CANNOT be auto-reset:
+ * the reset pump can only NOTIFY the operator to run `/tempo-reset` themselves
+ * (operator-mediated is the ceiling; see reset-pump.ts).
+ */
+export interface PiCommandContext {
+    /** Start a FRESH session (clean-wipe, no replay). */
+    newSession(): Promise<{
+        cancelled: boolean;
+    }>;
+}
+/** Options for {@link ExtensionAPI.registerCommand} (#677 PART B) — the slice we set. */
+export interface PiCommandOptions {
+    description?: string;
+    handler: (args: string, ctx: PiCommandContext) => Promise<void>;
+}
 /** The `pi` object passed to `export default function(pi: ExtensionAPI) {}`. */
 export interface ExtensionAPI {
     on(event: PiLifecycleEvent | string, handler: PiEventHandler): void;
     registerTool(def: PiToolDefinition): void;
+    /**
+     * Register an interactive slash command (#677 PART B — `/tempo-reset`). Optional
+     * in the slice: only the interactive Pi CLI surfaces commands (headless has no
+     * command surface). Kept loose by the architect's registerCommand ruling — see
+     * test/pi-drift/assert.ts `_registerSurfaceExists`.
+     */
+    registerCommand?(name: string, options: PiCommandOptions): void;
+    /**
+     * Inject a custom message into the live session through the STABLE `pi` handle
+     * (#677). Same message shape as `PiAgentSession.sendCustomMessage`'s param0
+     * (`Pick<CustomMessage, "customType"|"content"|"display"|"details">`). This is
+     * the interactive cue-injection path: Pi 0.78.1's `SessionStartEvent` carries
+     * NO `session` field, so `PiEventPayload.session` is null in interactive mode —
+     * routing cues through `pi.sendMessage` (re-resolved per tick from the surviving
+     * runtime) injects reliably regardless. Optional in the slice (Pi provides it; a
+     * fake/older Pi may not — the cue pump feature-detects with `typeof`).
+     */
+    sendMessage?(message: PiOutboundMessage, options?: PiCustomMessageOptions): void;
+    /**
+     * Inject a USER-role message — ALWAYS triggers a turn (#677 escalation path).
+     * When `sendMessage`'s `triggerTurn` fails to wake a cold-idle agent, the cue
+     * pump re-injects the SAME cue via this user-role call (a user message always
+     * starts a turn). It LOSES the `cue` customType + operator-vs-peer steer/followUp
+     * semantics, so it is FALLBACK-ONLY (never the primary route). Optional in the
+     * slice for the same reason as `sendMessage`.
+     */
+    sendUserMessage?(content: string, options?: {
+        deliverAs?: 'steer' | 'followUp';
+    }): void;
 }
 /** An extension is a default-exported function receiving the `ExtensionAPI`. */
 export type PiExtension = (pi: ExtensionAPI) => void | Promise<void>;

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

@@ -1,19 +1,29 @@
 /**
- * Reset pump (3d D14) — polls the session workflow's single-slot pending reset
- * and performs a CLEAN-WIPE on the live Pi session, then acks it. Sibling to
- * {@link CuePump}: Pi has no reverse-RPC from Temporal, so reset (an operator/
- * conductor CONTROL op — it bypasses the MD-G tool gate) is delivered by polling
- * `pendingReset` and acking via the race-safe `ackReset(resetId)` (the workflow
- * clears the slot only if the id still matches, so a newer reset landing during
- * the wipe is preserved for the next tick).
+ * Reset pump (3d D14 + #677 PART B) — polls the session workflow's single-slot
+ * pending reset and DELIVERS it, then acks. Sibling to {@link CuePump}: Pi has no
+ * reverse-RPC from Temporal, so reset (an operator/conductor CONTROL op — it
+ * bypasses the MD-G tool gate) is delivered by polling `pendingReset` and acking
+ * via the race-safe `ackReset(resetId)` (the workflow clears the slot only if the
+ * id still matches, so a newer reset landing during delivery is preserved).
  *
- * D14 (maintainer-ruled): reset = clean-wipe via Pi `session.newSession()` (fresh
- * context, NO replay). Seeded reset is a separate concern (`restart` +
- * `loadFromState`), so a `fresh:false` here is defensively logged + acked (never
- * silently wiped) — the reset tool only ever sends `fresh:true` today.
+ * D14 (maintainer-ruled): reset = clean-wipe (fresh context, NO replay). Seeded
+ * reset is a separate concern (`restart` + `loadFromState`), so a `fresh:false`
+ * here is defensively logged + acked — the reset tool only ever sends `fresh:true`.
+ *
+ * ── CAPABILITY BRANCH (#677 PART B) ──
+ * Delivery depends on what's attached, NOT a mode flag:
+ *   1. HEADLESS / session-capable — `session.newSession()` exists → AUTO clean-wipe
+ *      in place, then ack.
+ *   2. INTERACTIVE — Pi 0.78.1's SessionStartEvent has no `session` field, so
+ *      `rt.session` is null AND `newSession` is command-context-ONLY (not on the
+ *      SDK session): the pump CANNOT auto-wipe an interactive conductor. Instead it
+ *      NOTIFIES the operator (via the stable `pi.sendMessage` handle) to run
+ *      `/tempo-reset` themselves — ACK-ON-NOTIFY, id-matched so the notice fires
+ *      ONCE per resetId (no per-tick spam). Operator-mediated is the ceiling.
+ *   3. Nothing attached yet — leave pending; retry next tick.
  */
 import type { PendingReset } from '../types';
-import type { PiAgentSession } from './pi-types';
+import type { ExtensionAPI, PiAgentSession } from './pi-types';
 /** Source of the pending reset + ack — satisfied by `PiWorkflowClient`. */
 export interface ResetSource {
     fetchPendingReset(): Promise<PendingReset | null>;
@@ -21,27 +31,55 @@ export interface ResetSource {
 }
 /** Resolves the CURRENT live Pi session at wipe time (re-acquired each tick — D11). */
 export type SessionResolver = () => PiAgentSession | null;
+/** Resolves the CURRENT Pi `ExtensionAPI` handle (interactive operator-notice route — D11). */
+export type PiResolver = () => ExtensionAPI | null;
 export interface ResetPumpOptions {
     source: ResetSource;
     resolveSession: SessionResolver;
+    /**
+     * #677 PART B — the live `pi` handle for the interactive operator-notice route.
+     * Re-resolved each tick (repointed on instance rebuild). Absent → no notify path
+     * (legacy/headless-only callers); the pump still auto-wipes when a session with
+     * `newSession()` is present.
+     */
+    resolvePi?: PiResolver;
     /** Poll interval (ms). */
     intervalMs?: number;
 }
 export declare class ResetPump {
     private readonly source;
     private readonly resolveSession;
+    private readonly resolvePi;
     private readonly intervalMs;
     private timer;
     private draining;
+    /**
+     * #677 PART B — the resetId we've already surfaced as an operator notice, so the
+     * "run /tempo-reset" notice fires ONCE per request (id-matched). Cleared when the
+     * slot empties or a wipe happens.
+     */
+    private lastNotifiedResetId;
     constructor(opts: ResetPumpOptions);
     start(): void;
     stop(): void;
     /**
-     * One poll cycle: fetch the pending reset; if present + a live session is
-     * attached, perform the wipe and ack. Re-entrancy guarded so a slow tick never
-     * overlaps the next interval. Public for unit tests to drive directly.
+     * One poll cycle (#677 PART B capability branch). Re-entrancy guarded so a slow
+     * tick never overlaps the next interval. Public for unit tests to drive directly.
+     *
+     *   1. no pending                → clear dedup, done.
+     *   2. fresh=false               → log + ack (clear slot; seeded reset is restart's job).
+     *   3. session.newSession() avail → AUTO clean-wipe + ack (headless / session-capable).
+     *   4. else pi.sendMessage avail  → operator notice (once per id) + ack (interactive).
+     *   5. else                       → nothing attached yet; leave pending, retry.
      */
     tick(): Promise<void>;
-    /** Wipe (D14 clean-wipe) + deliver the "context wiped" notice. */
-    private performReset;
+    /** D14 clean-wipe (caller guarantees `fresh` + `newSession`) + the "context wiped" notice. */
+    private performWipe;
+    /**
+     * Interactive operator notice (#677 PART B). The pump can't reach `newSession`
+     * (command-context-only), so it asks the human to run `/tempo-reset`. Sent via
+     * the stable `pi.sendMessage` handle, non-triggering (it's an instruction, not a
+     * turn). Best-effort: a failed notice never throws the tick.
+     */
+    private notifyOperator;
 }

package/dist/pi/reset-pump.js

@@ -9,12 +9,20 @@ const log = (...args) => {
 class ResetPump {
     source;
     resolveSession;
+    resolvePi;
     intervalMs;
     timer = null;
     draining = false;
+    /**
+     * #677 PART B — the resetId we've already surfaced as an operator notice, so the
+     * "run /tempo-reset" notice fires ONCE per request (id-matched). Cleared when the
+     * slot empties or a wipe happens.
+     */
+    lastNotifiedResetId = null;
     constructor(opts) {
         this.source = opts.source;
         this.resolveSession = opts.resolveSession;
+        this.resolvePi = opts.resolvePi ?? (() => null);
         this.intervalMs = opts.intervalMs ?? DEFAULT_POLL_MS;
     }
     start() {
@@ -33,9 +41,14 @@ class ResetPump {
         }
     }
     /**
-     * One poll cycle: fetch the pending reset; if present + a live session is
-     * attached, perform the wipe and ack. Re-entrancy guarded so a slow tick never
-     * overlaps the next interval. Public for unit tests to drive directly.
+     * One poll cycle (#677 PART B capability branch). Re-entrancy guarded so a slow
+     * tick never overlaps the next interval. Public for unit tests to drive directly.
+     *
+     *   1. no pending                → clear dedup, done.
+     *   2. fresh=false               → log + ack (clear slot; seeded reset is restart's job).
+     *   3. session.newSession() avail → AUTO clean-wipe + ack (headless / session-capable).
+     *   4. else pi.sendMessage avail  → operator notice (once per id) + ack (interactive).
+     *   5. else                       → nothing attached yet; leave pending, retry.
      */
     async tick() {
         if (this.draining)
@@ -43,30 +56,48 @@ class ResetPump {
         this.draining = true;
         try {
             const pr = await this.source.fetchPendingReset();
-            if (!pr)
+            if (!pr) {
+                this.lastNotifiedResetId = null; // slot empty → forget the last notice
                 return;
+            }
+            if (!pr.fresh) {
+                // D14: reset is clean-wipe ONLY. A seeded reset is restart+loadFromState
+                // (not this path). Don't guess — log + ack (clear the slot).
+                log(`reset ${pr.resetId}: fresh=false — no wipe (seeded reset is restart's job)`);
+                await this.source.ackReset(pr.resetId);
+                this.lastNotifiedResetId = null;
+                return;
+            }
+            // (3) Session-capable (headless) → auto clean-wipe in place.
             const session = this.resolveSession();
-            if (!session)
-                return; // no live session yet — leave it pending; next tick retries
-            await this.performReset(session, pr);
-            await this.source.ackReset(pr.resetId);
+            if (session && typeof session.newSession === 'function') {
+                await this.performWipe(session, pr);
+                await this.source.ackReset(pr.resetId);
+                this.lastNotifiedResetId = null;
+                return;
+            }
+            // (4) Interactive → can't auto-wipe; notify the operator to run /tempo-reset.
+            const pi = this.resolvePi();
+            if (pi && typeof pi.sendMessage === 'function') {
+                if (this.lastNotifiedResetId !== pr.resetId) {
+                    this.notifyOperator(pi, pr); // ONCE per resetId (no per-tick spam)
+                    this.lastNotifiedResetId = pr.resetId;
+                }
+                // ACK-ON-NOTIFY: the request has been DELIVERED to the operator (the most
+                // an interactive conductor can do); clear the slot so it doesn't re-poll.
+                await this.source.ackReset(pr.resetId);
+                return;
+            }
+            // (5) Nothing attached yet — leave it pending; next tick retries.
         }
         finally {
             this.draining = false;
         }
     }
-    /** Wipe (D14 clean-wipe) + deliver the "context wiped" notice. */
-    async performReset(session, pr) {
-        if (!pr.fresh) {
-            // D14: reset is clean-wipe ONLY. A seeded reset would be restart+loadFromState
-            // (not this path). Don't guess — log + fall through to ack (clear the slot).
-            log(`reset ${pr.resetId}: fresh=false — no wipe (seeded reset is restart's job)`);
-            return;
-        }
-        if (typeof session.newSession !== 'function') {
-            log(`reset ${pr.resetId}: session.newSession() unavailable — skipping wipe (will still ack)`);
-            return;
-        }
+    /** D14 clean-wipe (caller guarantees `fresh` + `newSession`) + the "context wiped" notice. */
+    async performWipe(session, pr) {
+        // `newSession` is optional on the slice; tick() gated `typeof === 'function'`
+        // before calling, so the assertion is sound (the doc-comment states the contract).
         await session.newSession(); // clean-wipe: fresh context, no replay
         const by = pr.requestedBy ? ` (requested by ${pr.requestedBy})` : '';
         const notice = `[reset] context wiped — fresh start${by}.${pr.reason ? ` reason: ${pr.reason}` : ''}`;
@@ -81,5 +112,24 @@ class ResetPump {
             log(`reset ${pr.resetId}: notice injection failed (non-fatal):`, err);
         }
     }
+    /**
+     * Interactive operator notice (#677 PART B). The pump can't reach `newSession`
+     * (command-context-only), so it asks the human to run `/tempo-reset`. Sent via
+     * the stable `pi.sendMessage` handle, non-triggering (it's an instruction, not a
+     * turn). Best-effort: a failed notice never throws the tick.
+     */
+    notifyOperator(pi, pr) {
+        const by = pr.requestedBy ? ` by ${pr.requestedBy}` : '';
+        const reason = pr.reason ? ` (reason: ${pr.reason})` : '';
+        const notice = `⟳ context reset requested${by}${reason} — run /tempo-reset to clean-wipe this ` +
+            `session's context. agent-tempo can't auto-reset an interactive Pi conductor.`;
+        try {
+            pi.sendMessage?.({ customType: 'system', content: notice, display: true }, { deliverAs: 'followUp', triggerTurn: false });
+            log(`reset ${pr.resetId}: interactive — notified operator to run /tempo-reset`);
+        }
+        catch (err) {
+            log(`reset ${pr.resetId}: operator notice failed (non-fatal):`, err);
+        }
+    }
 }
 exports.ResetPump = ResetPump;

package/dist/server-tools.d.ts

@@ -18,7 +18,7 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Client, WorkflowHandle } from '@temporalio/client';
-import { Config } from './config';
+import { Config, ConfigSource } from './config';
 import { AgentType } from './types';
 import { type TempoToolDescriptor } from './tools/descriptor';
 /**
@@ -45,6 +45,12 @@ export interface RegisterAllTempoToolsOpts {
     workflowId: string;
     /** Default agent for `recruit` when the caller doesn't override. */
     ownAgentType: AgentType;
+    /**
+     * #676 FIX-1 — the SOURCE of `config.defaultAgent` (getConfigWithSources().sources),
+     * so recruit can prefer an operator-SET default over the `ownAgentType` mirror.
+     * Optional → undefined preserves the pre-FIX-1 mirror fallback.
+     */
+    defaultAgentSource?: ConfigSource;
     /** Whether this player is the ensemble's conductor (gates conductor-only tools). */
     isConductor: boolean;
 }

package/dist/server-tools.js

@@ -59,14 +59,14 @@ const coat_check_evict_1 = require("./tools/coat-check-evict");
  * surface.
  */
 function buildAllTempoTools(opts) {
-    const { client, config, getPlayerId, setPlayerId, handle, workflowId, ownAgentType, isConductor } = opts;
+    const { client, config, getPlayerId, setPlayerId, handle, workflowId, ownAgentType, defaultAgentSource, isConductor } = opts;
     const tools = [
         (0, ensemble_1.buildEnsembleTool)(client, config, getPlayerId, workflowId),
         (0, cue_1.buildCueTool)(client, config, getPlayerId, handle),
         (0, set_part_1.buildSetPartTool)(handle),
         (0, set_name_1.buildSetNameTool)(client, config, handle, getPlayerId, setPlayerId),
         (0, listen_1.buildListenTool)(handle),
-        (0, recruit_1.buildRecruitTool)(client, config, getPlayerId, handle, ownAgentType),
+        (0, recruit_1.buildRecruitTool)(client, config, getPlayerId, handle, ownAgentType, defaultAgentSource),
         (0, report_1.buildReportTool)(handle),
         (0, schedule_1.buildScheduleTool)(client, config, getPlayerId),
         (0, unschedule_1.buildUnscheduleTool)(client, config),

package/dist/server.js

@@ -72,7 +72,10 @@ async function main() {
         await idleServer.connect(transport);
         return;
     }
-    const config = (0, config_1.getConfig)();
+    // #676 FIX-1 — resolve config WITH sources so recruit can tell an operator-SET
+    // defaultAgent from the built-in 'claude' default. `.config` is the same Config
+    // getConfig() returns (behavior-preserving); `.sources.defaultAgent` is the origin.
+    const { config, sources } = (0, config_1.getConfigWithSources)();
     const isConductor = process.env[config_1.ENV.CONDUCTOR] === 'true';
     const requestedName = process.env[config_1.ENV.PLAYER_NAME] || '';
     // Conductors use their requested name or fall back to 'conductor'.
@@ -289,7 +292,7 @@ async function main() {
     // the same call. Adding a new tool? Add it once in `server-tools.ts`.
     (0, server_tools_1.registerAllTempoTools)(mcpServer, {
         client, config, getPlayerId, setPlayerId, handle, workflowId,
-        ownAgentType, isConductor,
+        ownAgentType, defaultAgentSource: sources.defaultAgent, isConductor,
     });
     const MAESTRO_ACK = '\n\n[IMPORTANT: This message is from a human (Maestro). Immediately cue the sender back with a brief acknowledgment and your planned next step before doing the work.]';
     // Start message poller — push messages into Claude Code via channel notifications.

package/dist/tools/recruit.d.ts

@@ -1,5 +1,5 @@
 import { Client, WorkflowHandle } from '@temporalio/client';
-import { Config } from '../config';
+import { Config, ConfigSource } from '../config';
 import { AgentType } from '../types';
 import type { HostInfo } from '../types';
 import { type TempoToolDescriptor } from './descriptor';
@@ -13,7 +13,24 @@ import { type TempoToolDescriptor } from './descriptor';
 export interface RegisterRecruitToolDeps {
     listHostsFn?: (client: Client) => Promise<HostInfo[]>;
 }
-export declare function buildRecruitTool(client: Client, config: Config, getPlayerId: () => string, handle: WorkflowHandle, ownAgentType?: AgentType, deps?: RegisterRecruitToolDeps): TempoToolDescriptor;
+/**
+ * #676 FIX-1 — recruit agent precedence: explicit `argAgent` > operator-SET
+ * `configDefault` > `ownAgentType` (this player's mirror-fallback). The
+ * `defaultAgentSource` distinguishes an operator-set default (origin
+ * flag/env/config/temporal-cli) from the built-in 'claude' default (source
+ * 'default') / truly-unset ('none') — only an operator-set default wins over the
+ * mirror, so a copilot/pi conductor recruits its own kind by default. Pure +
+ * exported for unit testing.
+ */
+export declare function resolveRecruitAgent(argAgent: AgentType | undefined, configDefault: AgentType, defaultAgentSource: ConfigSource | undefined, ownAgentType: AgentType): AgentType;
+export declare function buildRecruitTool(client: Client, config: Config, getPlayerId: () => string, handle: WorkflowHandle, ownAgentType?: AgentType, 
+/**
+ * #676 FIX-1 — the SOURCE of `config.defaultAgent` (from getConfigWithSources),
+ * used to distinguish an operator-SET default from the built-in 'claude'
+ * default (source 'default'). Undefined → treated as not-operator-set →
+ * recruit falls back to `ownAgentType` (preserves the pre-FIX-1 mirror).
+ */
+defaultAgentSource?: ConfigSource, deps?: RegisterRecruitToolDeps): TempoToolDescriptor;
 /**
  * Given a host liveness+profile snapshot, validate that `targetHost` is
  * (a) known, (b) recruit-ready, and (c) advertises support for

package/dist/tools/recruit.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRecruitAgent = resolveRecruitAgent;
 exports.buildRecruitTool = buildRecruitTool;
 exports.checkHostPreflight = checkHostPreflight;
 exports.nearestHostname = nearestHostname;
@@ -78,7 +79,30 @@ function hasOpencodeOnPath() {
         return false;
     }
 }
-function buildRecruitTool(client, config, getPlayerId, handle, ownAgentType = 'claude', deps = {}) {
+/**
+ * #676 FIX-1 — recruit agent precedence: explicit `argAgent` > operator-SET
+ * `configDefault` > `ownAgentType` (this player's mirror-fallback). The
+ * `defaultAgentSource` distinguishes an operator-set default (origin
+ * flag/env/config/temporal-cli) from the built-in 'claude' default (source
+ * 'default') / truly-unset ('none') — only an operator-set default wins over the
+ * mirror, so a copilot/pi conductor recruits its own kind by default. Pure +
+ * exported for unit testing.
+ */
+function resolveRecruitAgent(argAgent, configDefault, defaultAgentSource, ownAgentType) {
+    if (argAgent)
+        return argAgent;
+    const operatorSet = !!defaultAgentSource
+        && ['flag', 'env', 'config', 'temporal-cli'].includes(defaultAgentSource);
+    return operatorSet ? configDefault : ownAgentType;
+}
+function buildRecruitTool(client, config, getPlayerId, handle, ownAgentType = 'claude', 
+/**
+ * #676 FIX-1 — the SOURCE of `config.defaultAgent` (from getConfigWithSources),
+ * used to distinguish an operator-SET default from the built-in 'claude'
+ * default (source 'default'). Undefined → treated as not-operator-set →
+ * recruit falls back to `ownAgentType` (preserves the pre-FIX-1 mirror).
+ */
+defaultAgentSource, deps = {}) {
     // Lazy default — only imports utils/hosts when actually called, so the
     // MCP server's module load graph doesn't drag the whole join layer
     // into every consumer at import time.
@@ -133,7 +157,7 @@ function buildRecruitTool(client, config, getPlayerId, handle, ownAgentType = 'c
         handler: async (args) => {
             const { workDir, name, initialMessage } = args;
             const isConductor = args.conductor === true;
-            const agent = args.agent || ownAgentType;
+            const agent = resolveRecruitAgent(args.agent, config.defaultAgent, defaultAgentSource, ownAgentType);
             const model = args.model;
             const agentTypeName = args.type;
             const systemPrompt = args.systemPrompt;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-tempo",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Many agents, one tempo. Durable coordination for multi-agent work via Temporal.",
   "keywords": [
     "mcp",