agent-tempo 1.2.0 → 1.4.0

package/dist/pi/cue-pump.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CuePump = void 0;
+const DEFAULT_POLL_MS = 1_000;
+const log = (...args) => {
+    // eslint-disable-next-line no-console
+    console.error('[agent-tempo:pi]', ...args);
+};
+class CuePump {
+    source;
+    resolveSession;
+    intervalMs;
+    timer = null;
+    draining = false;
+    constructor(opts) {
+        this.source = opts.source;
+        this.resolveSession = opts.resolveSession;
+        this.intervalMs = opts.intervalMs ?? DEFAULT_POLL_MS;
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            this.tick().catch((err) => log('cue-pump tick failed:', err));
+        }, this.intervalMs);
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * 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.
+     */
+    async tick() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        try {
+            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.
+                return;
+            }
+            const delivered = [];
+            for (const msg of pending) {
+                try {
+                    await this.injectCue(session, msg);
+                    delivered.push(msg.id);
+                }
+                catch (err) {
+                    log(`failed to inject cue ${msg.id}:`, err);
+                    // Stop on first failure — preserve ordering; retry next tick.
+                    break;
+                }
+            }
+            await this.source.ackDelivered(delivered);
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+    /**
+     * Inject one cue into the live session (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;
+        // 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
+        //     when the agent goes idle, NEVER preempts a running turn. triggerTurn only
+        //     wakes a cold-idle session (followUp alone won't start one); it is a no-op
+        //     while a turn is in flight.
+        //   operator cue = { deliverAs: 'steer', triggerTurn: true } → same-turn PRIORITY:
+        //     injected after the current tool batch, before the next LLM call. NOT a hard
+        //     mid-tool abort (only RPC abort / AbortSignal hard-interrupts a running tool).
+        // 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 });
+    }
+}
+exports.CuePump = CuePump;

package/dist/pi/extension.d.ts

@@ -0,0 +1,45 @@
+import type { Client } from '@temporalio/client';
+import { type Config } from '../config';
+import type { ExtensionAPI, PiAgentSession } from './pi-types';
+/** Runtime mode. Headless = recruited unsupervised player (MD-C gate active). */
+export type PiExtensionMode = 'interactive' | 'headless';
+export type PiToolAccess = 'restricted' | 'standard' | 'full';
+export interface PiExtensionOptions {
+    /** Default `'interactive'`. Headless installs the MD-C tool_call gate. */
+    mode?: PiExtensionMode;
+    /** MD-C tool-class policy (headless only). Default `'restricted'`. */
+    toolAccess?: PiToolAccess;
+}
+/**
+ * Build the Pi extension factory. `mode='headless'` installs the MD-C tool_call
+ * gate; `mode='interactive'` (default) does not (the human owns their machine).
+ */
+export declare function createPiExtension(options?: PiExtensionOptions): (pi: ExtensionAPI) => void;
+/**
+ * RELIABLE detach for the headless exit sequence (Phase 3a). Headless owns its
+ * exit loop, so — unlike interactive's best-effort `quit` path — it can AWAIT a
+ * clean detach before disposing the SDK session. Ordering (architect ruling):
+ * stopHeartbeat → requestDetach → adapterExited (all inside `wf.detach`) → unmap.
+ * The caller then calls `session.dispose()`; the dispose-fired `session_shutdown`
+ * finds no mapped runtime → no-op (avoids double-detach). Detaches every runtime
+ * in the process (headless = one player per process).
+ */
+export declare function detachAllPiRuntimesForExit(): Promise<void>;
+/**
+ * Headless-only: wire the live Pi SDK session onto a runtime so the cue pump can
+ * inject into it. The interactive CLI's `session_start` payload carries
+ * `session`, but the headless SDK's DEFAULT session_start payload does NOT (it's
+ * `{ type, reason }`) — so `attachOrRebind` sets `rt.session = null` and the cue
+ * pump's `resolveSession` returns null (every cue is dropped). The headless entry
+ * HOLDS the session from `createAgentSession`, so it calls this after
+ * `bindExtensions` (by which point the runtime exists + has claimed) to set it.
+ * (3a live smoke — devops.)
+ */
+export declare function setRuntimeSession(workflowId: string, session: PiAgentSession): void;
+/** Override the Temporal connection factory (inject a fake Client). */
+export declare function __setPiClientFactoryForTests(factory: (config: Config) => Promise<Client>): void;
+/** Stop timers, clear the per-player runtime map + shared-client singletons + factory. */
+export declare function __resetPiRuntimesForTests(): 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

@@ -0,0 +1,407 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPiExtension = createPiExtension;
+exports.detachAllPiRuntimesForExit = detachAllPiRuntimesForExit;
+exports.setRuntimeSession = setRuntimeSession;
+exports.__setPiClientFactoryForTests = __setPiClientFactoryForTests;
+exports.__resetPiRuntimesForTests = __resetPiRuntimesForTests;
+/**
+ * agent-tempo Pi extension — interactive (Phase 2) + headless (Phase 3a) runtime.
+ *
+ *   createPiExtension({ mode, toolAccess })  →  (pi: ExtensionAPI) => void
+ *   export default = createPiExtension()      (interactive)
+ *
+ * Registers the FULL agent-tempo tool surface natively on Pi (shared
+ * transport-neutral descriptors + `renderToPi`), drives the attachment phase
+ * from Pi lifecycle events, holds an attachment lease + heartbeat, and pumps
+ * cues into the live session. The SAME extension runs interactive (behind a
+ * human `pi` CLI) and headless (injected into `createAgentSession` by the daemon
+ * — Phase 3a); `mode` is the only behavioural discriminator (it gates the MD-C
+ * tool_call enforcement, which applies to unsupervised headless players only).
+ *
+ * ── Module-scope singleton (CRITICAL — researcher finding) ──
+ * Pi REBUILDS the extension instance on every SessionManager switch, so
+ * per-INSTANCE state does NOT survive. Everything that must survive — the
+ * Temporal `Client`, the fixed `workflowId`, the pinned handle, the heartbeat
+ * timer, the cue pump, the current-session pointer — lives in a MODULE-SCOPE
+ * singleton (`runtimes`, keyed by workflowId; one entry interactive, N for the
+ * headless daemon — D12a). The rebuilt instance RE-BINDS; it never recreates.
+ *
+ * ── Teardown (Option C — reason-discriminated) ──
+ * `session_shutdown` carries `reason` {quit|reload|new|resume|fork}. We detach
+ * ONLY on a clean `quit`; switch/unknown reasons → rebind (no detach). The
+ * `quit` detach is best-effort; the MD-A lease reaper is the permanent floor.
+ * Headless owns its exit sequence, so it uses {@link detachAllPiRuntimesForExit}
+ * for RELIABLE detach (await adapterExited) before disposing the SDK session.
+ *
+ * Determinism boundary: this module (and all of src/pi/) is CLIENT-SIDE only.
+ */
+const os = __importStar(require("os"));
+const crypto = __importStar(require("crypto"));
+const config_1 = require("../config");
+const server_tools_1 = require("../server-tools");
+const phase_driver_1 = require("./phase-driver");
+const workflow_client_1 = require("./workflow-client");
+const cue_pump_1 = require("./cue-pump");
+const reset_pump_1 = require("./reset-pump");
+const render_tools_1 = require("./render-tools");
+const lazy_proxy_1 = require("./lazy-proxy");
+const probe_1 = require("./probe");
+const inner_loop_publisher_1 = require("./inner-loop-publisher");
+const inner_loop_client_1 = require("./inner-loop-client");
+const gate_client_1 = require("./gate-client");
+const tool_capability_1 = require("./tool-capability");
+const gate_registry_1 = require("../http/gate-registry");
+const log = (...args) => {
+    // eslint-disable-next-line no-console
+    console.error('[agent-tempo:pi]', ...args);
+};
+const nowIso = () => new Date().toISOString();
+const PI_AGENT_TYPE = 'claude'; // Pi is not yet a first-class AgentType.
+// MD-C shell/exec tool-class membership is owned by `tool-capability.ts`
+// (`classify(name) === 'exec'`, content signed off by tempo-security). F1
+// import-refactor (3d): this REPLACES the former local `SHELL_TOOL_NAMES` set —
+// the canonical EXEC_TOOLS set is a SUPERSET that also blocks
+// powershell/pwsh/cmd/run, closing the gap the local list left open. Single
+// source of truth: never re-declare a shell denylist here.
+// ── Module-scope Temporal Client singleton (D12a: one Client per OS process) ──
+let sharedClientPromise = null;
+let connectedClient = null;
+function getSharedClient(config) {
+    if (!sharedClientPromise) {
+        sharedClientPromise = workflow_client_1.PiWorkflowClient.connect(config)
+            .then((c) => { connectedClient = c; return c; })
+            .catch((err) => { sharedClientPromise = null; log('Temporal connect failed:', err); throw err; });
+    }
+    return sharedClientPromise;
+}
+/** Connection factory; overridable via `__setPiClientFactoryForTests`. */
+let clientFactory = getSharedClient;
+/** One runtime per player, keyed by fixed workflowId. Survives instance rebuilds. */
+const runtimes = new Map();
+/**
+ * Build the Pi extension factory. `mode='headless'` installs the MD-C tool_call
+ * gate; `mode='interactive'` (default) does not (the human owns their machine).
+ */
+function createPiExtension(options = {}) {
+    const mode = options.mode ?? 'interactive';
+    const toolAccess = options.toolAccess ?? 'restricted';
+    return function piExtension(pi) {
+        const probe = (0, probe_1.probePi)();
+        if (!probe.available)
+            log('WARNING:', probe.reason);
+        const config = (0, config_1.getConfig)();
+        const isConductor = process.env[config_1.ENV.CONDUCTOR] === '1' || process.env[config_1.ENV.CONDUCTOR] === 'true';
+        // Identity — FIXED workflowId for the process lifetime. `currentPlayerId` is
+        // the mutable DISPLAY id (set_name updates it); the workflowId never repoints.
+        let currentPlayerId = process.env[config_1.ENV.PLAYER_NAME] || `pi-${process.pid}`;
+        const workflowId = (0, config_1.sessionWorkflowId)(config.ensemble, currentPlayerId);
+        // 3c — the inner-loop URL + ingest token are keyed to the player's FIXED
+        // identity (the daemon minted the token for sessionWorkflowId(ensemble,
+        // <recruit name>)). `currentPlayerId` is mutable (set_name), so capture the
+        // original here — the publisher's HTTP client URL must match the workflowId.
+        const fixedPlayerId = currentPlayerId;
+        // Kick off (or reuse) the module-scope shared connection.
+        void clientFactory(config);
+        // ── D11 lazy proxies: resolve MODULE-SCOPE state per call (instance-independent) ──
+        const clientProxy = (0, lazy_proxy_1.createLazyProxy)(() => connectedClient, 'Temporal client');
+        const handleProxy = (0, lazy_proxy_1.createLazyProxy)(() => runtimes.get(workflowId)?.wf.handle ?? null, 'workflow handle');
+        // ── Register the FULL tool surface on THIS instance's `pi` ──
+        const toolOpts = {
+            client: clientProxy,
+            config,
+            getPlayerId: () => currentPlayerId,
+            setPlayerId: (id) => { currentPlayerId = id; },
+            handle: handleProxy,
+            workflowId,
+            ownAgentType: PI_AGENT_TYPE,
+            isConductor,
+        };
+        (0, render_tools_1.renderToPi)(pi, (0, server_tools_1.buildAllTempoTools)(toolOpts));
+        log(`registered tools (player=${currentPlayerId}, conductor=${isConductor}, mode=${mode})`);
+        // ── 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
+        // tools are HARD-BLOCKED at toolAccess='restricted' (the safe unsupervised
+        // default) regardless of any later gate logic. The supervised gate (3d) slots
+        // in AFTER this MD-C floor — for now, anything MD-C permits is allowed.
+        if (mode === 'headless') {
+            // 3d MD-G — the operator gate's two loopback clients, keyed to the FIXED
+            // player identity (matches the ingest token + workflowId). `gateInner`
+            // emits the gate_pending frame (the daemon's ingest side-effect registers
+            // the pending) and reports presence {subscribers, gateArmed}; `gateClient`
+            // polls the daemon for the operator's decision. Both no-op without the
+            // ingest token (so this is inert for a manually-launched headless Pi).
+            const gateInner = new inner_loop_client_1.InnerLoopHttpClient({ ensemble: config.ensemble, playerId: fixedPlayerId });
+            const gateClient = new gate_client_1.GateClient({ ensemble: config.ensemble, playerId: fixedPlayerId });
+            pi.on('tool_call', async (event, ctx) => {
+                const cls = (0, tool_capability_1.classify)(event.toolName);
+                // 1) MD-C tool-class FLOOR (fires FIRST). classify()==='exec' is the
+                //    canonical EXEC set (F1) — a SUPERSET that hard-blocks
+                //    powershell/pwsh/cmd/run at restricted. HARD-block, never gated.
+                if (cls === 'exec' && toolAccess === 'restricted') {
+                    log(`MD-C: blocked '${event.toolName}' (toolAccess=restricted)`);
+                    return {
+                        block: true,
+                        reason: `toolAccess=restricted: shell/exec tools are disabled for this headless Pi player`,
+                    };
+                }
+                // 2) MD-G OPERATOR GATE — engage for any non-low-risk tool WHEN an
+                //    operator is armed AND present (both read from the short-poll
+                //    cached presence). low-risk bypasses; unknown→high-blast is gated-
+                //    when-armed (R2). The await resolves on the operator's decision,
+                //    the daemon's 45s auto-allow, ctx.signal cancel, or the bounded
+                //    poll deadline — all FAIL-OPEN except an explicit deny.
+                if (cls !== 'low-risk' && gateInner.gateArmed(workflowId) && gateInner.subscriberCount(workflowId) > 0) {
+                    const requestId = crypto.randomUUID();
+                    gateInner.publish(workflowId, {
+                        type: 'inner.gate_pending',
+                        requestId,
+                        tool: event.toolName,
+                        argsSummary: (0, inner_loop_publisher_1.truncateSummary)(event.input, 2048),
+                        classification: cls, // low-risk already returned above
+                        timeoutMs: gate_registry_1.GATE_AUTO_ALLOW_MS,
+                        ts: Date.now(),
+                    });
+                    const effect = await gateClient.awaitDecision(requestId, { signal: ctx?.signal });
+                    if (effect === 'deny') {
+                        log(`MD-G: operator DENIED '${event.toolName}' (req ${requestId})`);
+                        return { block: true, reason: `operator denied ${event.toolName}` };
+                    }
+                    log(`MD-G: '${event.toolName}' permitted (req ${requestId})`);
+                    return {};
+                }
+                // 3) not gated → permit.
+                return {};
+            });
+            log(`MD-C+MD-G tool gate active (mode=headless, toolAccess=${toolAccess})`);
+        }
+        /** Build session metadata from the (current) identity + host. */
+        function buildMetadata() {
+            return {
+                playerId: currentPlayerId,
+                ensemble: config.ensemble,
+                hostname: os.hostname(),
+                workDir: process.cwd(),
+                isConductor,
+                agentType: PI_AGENT_TYPE,
+                adapterId: 'pi',
+            };
+        }
+        /** Persist the active Pi conversation id to metadata.sessionId IF it changed (P2-5). */
+        async function refreshSessionId(rt, sessionId) {
+            if (!sessionId || sessionId === rt.lastSessionId)
+                return;
+            await rt.wf.updateSessionId(sessionId);
+            rt.lastSessionId = sessionId;
+        }
+        /**
+         * Get-or-create the runtime for this player. FIRST attach claims the lease +
+         * starts the heartbeat + cue pump. A subsequent `session_start` (instance
+         * rebuild) RE-BINDS the surviving runtime — session pointer only, no re-claim.
+         */
+        async function attachOrRebind(payload) {
+            const existing = runtimes.get(workflowId);
+            if (existing) {
+                existing.session = payload.session ?? existing.session;
+                log(`re-bound ${currentPlayerId} (Pi instance rebuilt; lease intact)`);
+                return existing;
+            }
+            const client = await clientFactory(config);
+            const wf = new workflow_client_1.PiWorkflowClient({
+                client,
+                config,
+                metadata: buildMetadata(),
+                expectedAttachmentId: process.env[config_1.ENV.ATTACHMENT_ID] || undefined,
+            });
+            const driver = new phase_driver_1.PhaseDriver();
+            const pump = new cue_pump_1.CuePump({
+                source: wf,
+                resolveSession: () => runtimes.get(workflowId)?.session ?? null,
+            });
+            // 3c — inner-loop publisher + its loopback-HTTP sink. The client no-ops
+            // unless AGENT_TEMPO_INGEST_TOKEN is present (daemon-spawned headless
+            // players only), so interactive Pi gets Tier-1 coarse for free and zero
+            // Tier-2 forwarding. URL keyed to the FIXED playerId (matches workflowId).
+            const registry = new inner_loop_client_1.InnerLoopHttpClient({ ensemble: config.ensemble, playerId: fixedPlayerId });
+            const pub = new inner_loop_publisher_1.InnerLoopPublisher({ workflowId, registry });
+            // 3d D14 — reset poll-tick (sibling to the cue pump): polls pendingReset →
+            // session.newSession() clean-wipe + ack. resolveSession re-acquired each
+            // tick so a session switch never wipes a stale session.
+            const reset = new reset_pump_1.ResetPump({
+                source: wf,
+                resolveSession: () => runtimes.get(workflowId)?.session ?? null,
+            });
+            const rt = { workflowId, wf, driver, pump, pub, reset, session: payload.session ?? null };
+            runtimes.set(workflowId, rt);
+            await wf.ensureSessionWorkflow();
+            const result = driver.handle('session_start', payload, nowIso());
+            await wf.performAction(result.action); // claim → attached, starts heartbeat
+            pump.start();
+            // Start the publisher AFTER the claim (heartbeat is live → coarse samples
+            // have a delivery path) and wire its coarse state into the heartbeat. The
+            // bound method is wrapped so `this` survives the provider call.
+            pub.start(pi);
+            wf.setCoarseProvider(() => pub.getCoarseState());
+            reset.start(); // 3d D14 — begin polling for pending resets
+            log(`attached ${currentPlayerId} (wf ${workflowId})`);
+            return rt;
+        }
+        // ── Lifecycle: session_start → first attach OR re-bind ──
+        pi.on('session_start', async (payload) => {
+            try {
+                const rt = await attachOrRebind(payload);
+                await refreshSessionId(rt, rt.session?.id);
+            }
+            catch (err) {
+                log('session_start wiring failed:', err);
+            }
+        });
+        // ── Lifecycle: phase-affecting events ──
+        for (const event of ['agent_start', 'agent_end']) {
+            pi.on(event, async (payload) => {
+                const rt = runtimes.get(workflowId);
+                if (!rt)
+                    return;
+                if (payload.session)
+                    rt.session = payload.session;
+                const result = rt.driver.handle(event, payload, nowIso());
+                try {
+                    await rt.wf.performAction(result.action);
+                    if (event === 'agent_start')
+                        await refreshSessionId(rt, rt.session?.id);
+                }
+                catch (err) {
+                    log(`${event} → ${result.action.kind} failed:`, err);
+                }
+            });
+        }
+        // ── Lifecycle: activity-only events (NEVER drive phase) ──
+        for (const event of [
+            'turn_start', 'turn_end', 'tool_execution_start', 'tool_execution_end',
+        ]) {
+            pi.on(event, (payload) => {
+                const rt = runtimes.get(workflowId);
+                if (!rt)
+                    return;
+                if (payload.session)
+                    rt.session = payload.session;
+                rt.driver.handle(event, payload, nowIso());
+            });
+        }
+        // ── Lifecycle: session_shutdown → Option C (reason-discriminated teardown) ──
+        pi.on('session_shutdown', async (payload) => {
+            const rt = runtimes.get(workflowId);
+            if (!rt)
+                return;
+            rt.session = null; // switch gap: cue pump stops injecting (dodges Pi #2860)
+            if (payload.reason === 'quit') {
+                rt.pub.stop(); // 3c — stop observing + flush the trailing coalesce buffer
+                rt.reset.stop(); // 3d — stop the reset poll
+                try {
+                    await rt.wf.detach('agent-exited'); // requestDetach + adapterExited + stopHeartbeat
+                    runtimes.delete(workflowId);
+                }
+                catch (err) {
+                    log('quit detach (best-effort) failed — reaper will backstop:', err);
+                }
+            }
+        });
+    };
+}
+/**
+ * RELIABLE detach for the headless exit sequence (Phase 3a). Headless owns its
+ * exit loop, so — unlike interactive's best-effort `quit` path — it can AWAIT a
+ * clean detach before disposing the SDK session. Ordering (architect ruling):
+ * stopHeartbeat → requestDetach → adapterExited (all inside `wf.detach`) → unmap.
+ * The caller then calls `session.dispose()`; the dispose-fired `session_shutdown`
+ * finds no mapped runtime → no-op (avoids double-detach). Detaches every runtime
+ * in the process (headless = one player per process).
+ */
+async function detachAllPiRuntimesForExit() {
+    for (const rt of runtimes.values()) {
+        rt.pub.stop(); // 3c — stop the inner-loop publisher before detaching
+        rt.reset.stop(); // 3d — stop the reset poll before detaching
+        try {
+            await rt.wf.detach('agent-exited');
+        }
+        catch (err) {
+            log('headless detach failed (reaper will backstop):', err);
+        }
+    }
+    runtimes.clear();
+}
+/**
+ * Headless-only: wire the live Pi SDK session onto a runtime so the cue pump can
+ * inject into it. The interactive CLI's `session_start` payload carries
+ * `session`, but the headless SDK's DEFAULT session_start payload does NOT (it's
+ * `{ type, reason }`) — so `attachOrRebind` sets `rt.session = null` and the cue
+ * pump's `resolveSession` returns null (every cue is dropped). The headless entry
+ * HOLDS the session from `createAgentSession`, so it calls this after
+ * `bindExtensions` (by which point the runtime exists + has claimed) to set it.
+ * (3a live smoke — devops.)
+ */
+function setRuntimeSession(workflowId, session) {
+    const rt = runtimes.get(workflowId);
+    if (rt) {
+        rt.session = session;
+        log(`headless session wired to runtime (wf ${workflowId})`);
+    }
+    else {
+        log(`setRuntimeSession: no runtime for ${workflowId} yet (session_start may not have fired)`);
+    }
+}
+// ── Test-only hooks (ADR 0006 `__<verb><Noun>ForTests` convention) ──
+/** Override the Temporal connection factory (inject a fake Client). */
+function __setPiClientFactoryForTests(factory) {
+    clientFactory = factory;
+}
+/** Stop timers, clear the per-player runtime map + shared-client singletons + factory. */
+function __resetPiRuntimesForTests() {
+    for (const rt of runtimes.values()) {
+        rt.pub.stop();
+        rt.reset.stop();
+        rt.pump.stop();
+        rt.wf.stopHeartbeat();
+    }
+    runtimes.clear();
+    sharedClientPromise = null;
+    connectedClient = null;
+    clientFactory = getSharedClient;
+}
+/** Default export — interactive-mode extension (the human `pi` CLI entry). */
+const piExtension = createPiExtension();
+exports.default = piExtension;

package/dist/pi/gate-client.d.ts

@@ -0,0 +1,54 @@
+/** Env var carrying the per-player ingest token (threaded in at spawn, shared w/ inner-loop). */
+export declare const INGEST_TOKEN_ENV = "AGENT_TEMPO_INGEST_TOKEN";
+/** What the handler does with the result. */
+export type GateEffect = 'allow' | 'deny';
+/** Minimal `fetch` shape (injectable for tests) — same contract as the inner-loop client. */
+export type GateFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+}) => Promise<{
+    status: number;
+    json(): Promise<unknown>;
+}>;
+export interface GateClientOptions {
+    ensemble: string;
+    playerId: string;
+    ingestToken?: string;
+    readPort?: () => number | null;
+    fetchFn?: GateFetch;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    now?: () => number;
+    /** Cancellable wait (tests inject a synchronous/controllable one). */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * Loopback poll-bridge to the daemon gate. Construct one per headless player.
+ * The `awaitDecision` poll is the only public surface used by the engagement path.
+ */
+export declare class GateClient {
+    private readonly ensemble;
+    private readonly playerId;
+    private readonly ingestToken;
+    private readonly readPort;
+    private readonly fetchFn;
+    private readonly pollIntervalMs;
+    private readonly timeoutMs;
+    private readonly now;
+    private readonly sleep;
+    constructor(opts: GateClientOptions);
+    private get enabled();
+    private resolutionUrl;
+    /** One poll. Returns the effect on a resolved answer, or null to keep polling. */
+    private pollOnce;
+    /**
+     * Poll the daemon for the operator's decision on `requestId`, blocking until
+     * resolved / timeout / abort. FAIL-OPEN: `allow` unless the operator explicitly
+     * denied. Without a token/transport (e.g. interactive Pi, daemon HTTP off) →
+     * immediate `allow` (the gate is a daemon-mediated feature).
+     */
+    awaitDecision(requestId: string, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<GateEffect>;
+}