agent-tempo 1.5.0 → 1.6.0

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),