agent-tempo 1.3.1 → 1.4.1

package/dist/http/server.js

@@ -56,6 +56,8 @@ exports.handle = handle;
 const http = __importStar(require("http"));
 const config_1 = require("../config");
 const auth_1 = require("./auth");
+const inner_loop_routes_1 = require("./inner-loop-routes");
+const gate_routes_1 = require("./gate-routes");
 const cors_1 = require("./cors");
 const dashboard_1 = require("./dashboard");
 const dashboard_pair_1 = require("./dashboard-pair");
@@ -98,10 +100,46 @@ async function startHttpServer(opts) {
     // generation now so the daemon doesn't crash mid-request when the first
     // bearer-required call shows up.
     const bindIsLoopback = (0, auth_1.isLoopbackBindAddr)(bindAddr);
-    const httpToken = opts.httpToken ?? (0, auth_1.loadOrGenerateHttpToken)({ bearerRequired: !bindIsLoopback });
-    if (!bindIsLoopback && !httpToken) {
+    // 3e RBAC token resolution. Back-compat: a single `httpToken` option (or a
+    // legacy config.json `httpToken`) is adopted as the READ token (T1); the ADMIN
+    // token is env-var-only. Explicit `readToken`/`adminToken` options override
+    // (used by tests). loopback bind ⇒ no bearer required ⇒ tokens may be null.
+    let readToken;
+    let legacyMigrated = false;
+    if (opts.readToken !== undefined) {
+        readToken = opts.readToken;
+    }
+    else if (opts.httpToken !== undefined) {
+        // Back-compat: a single injected bearer is treated as the READ token (T1).
+        readToken = opts.httpToken;
+    }
+    else {
+        const loaded = (0, auth_1.loadReadToken)({ bearerRequired: !bindIsLoopback });
+        readToken = loaded.token;
+        legacyMigrated = loaded.legacy;
+    }
+    const adminToken = opts.adminToken ?? (0, auth_1.loadAdminToken)();
+    if (!bindIsLoopback && !readToken) {
         throw new Error('Bearer token required for non-loopback bind but none configured. ' +
-            'Set httpToken in ~/.agent-tempo/config.json or unset AGENT_TEMPO_HTTP_BIND.');
+            'Set AGENT_TEMPO_HTTP_READ_TOKEN (or readToken in ~/.agent-tempo/config.json), ' +
+            'or unset AGENT_TEMPO_HTTP_BIND.');
+    }
+    // 3e MD-E — one-time startup warnings (non-blocking).
+    //
+    // (1) Legacy migration: a pre-3e single `httpToken` was adopted as the READ
+    //     token (T1) and no admin token is configured, so writes / operator gate /
+    //     inner-tail (all Tier ≥ 2) will 503 until an admin token is set.
+    if (legacyMigrated && adminToken === null) {
+        log('NOTICE: adopted legacy config.json `httpToken` as the read-tier token. ' +
+            'Writes, the operator gate, and the inner-tail are admin-only and will return ' +
+            '503 until you set AGENT_TEMPO_HTTP_ADMIN_TOKEN (env-var only).');
+    }
+    // (2) Plaintext-bearer exposure: binding to a non-loopback address serves the
+    //     bearer token over cleartext HTTP. Suppressible, never blocking.
+    if (!bindIsLoopback && process.env[config_1.ENV.TLS_ACKNOWLEDGED] !== '1') {
+        log(`WARNING: binding to non-loopback ${bindAddr} serves the bearer token over ` +
+            'plaintext HTTP. Terminate TLS at a reverse proxy, or tunnel via SSH/Tailscale. ' +
+            `Set ${config_1.ENV.TLS_ACKNOWLEDGED}=1 to acknowledge and suppress this warning.`);
     }
     const startedAt = opts.startedAtMs ?? Date.now();
     // §7.3 process-wide cap. Defaults to 100 per spec; env var override.
@@ -122,11 +160,15 @@ async function startHttpServer(opts) {
         version: opts.version,
         bindAddr,
         corsConfig,
-        httpToken,
+        readToken,
+        adminToken,
         startedAt,
         subscriberCount,
         aggregate: opts.aggregate ?? null,
         sseConnectionCap,
+        innerLoop: opts.innerLoop ?? null,
+        ingestTokens: opts.ingestTokens ?? null,
+        gate: opts.gate ?? null,
     }).catch((err) => {
         log('unhandled handler error:', err instanceof Error ? err.message : err);
         if (!res.headersSent) {
@@ -233,12 +275,53 @@ async function handle(req, res, ctx) {
     if (method === 'GET' && pairConsumeMatch) {
         return (0, dashboard_pair_1.handlePairConsume)(req, res, pairConsumeMatch[1]);
     }
-    // Authentication gate.
+    // 3c Tier-2 INGRESS (publisher → daemon). Matched BEFORE the outer bearer
+    // gate: these use their OWN source-plane auth (loopback `socket.remoteAddress`
+    // + `X-Ingest-Token` vs the URL workflowId), so a localhost Pi subprocess
+    // reaches them regardless of the daemon's bind address. Only live when the
+    // daemon wired the registries; else they fall through to the 404/405 path.
+    if (ctx.innerLoop && ctx.ingestTokens) {
+        const innerDeps = { innerLoop: ctx.innerLoop, ingestTokens: ctx.ingestTokens, ...(ctx.gate ? { gate: ctx.gate } : {}) };
+        const ingestMatch = pathname.match(/^\/v1\/players\/([^/]+)\/([^/]+)\/inner\/ingest$/);
+        if (ingestMatch) {
+            if (method !== 'POST') {
+                return (0, responses_1.errorResponse)(res, 405, { error: 'method-not-allowed' }, { Allow: 'POST' });
+            }
+            return (0, inner_loop_routes_1.handleInnerIngest)(req, res, innerDeps, decodeURIComponent(ingestMatch[1]), decodeURIComponent(ingestMatch[2]));
+        }
+        const presenceMatch = pathname.match(/^\/v1\/players\/([^/]+)\/([^/]+)\/inner\/presence$/);
+        if (presenceMatch) {
+            if (method !== 'GET') {
+                return (0, responses_1.errorResponse)(res, 405, { error: 'method-not-allowed' }, { Allow: 'GET' });
+            }
+            return (0, inner_loop_routes_1.handleInnerPresence)(req, res, innerDeps, decodeURIComponent(presenceMatch[1]), decodeURIComponent(presenceMatch[2]));
+        }
+    }
+    // 3d MD-G INGRESS (Pi subprocess → daemon poll). Same source-plane auth as the
+    // inner-loop ingest (loopback `socket.remoteAddress` + `X-Ingest-Token` vs the
+    // URL workflowId), matched BEFORE the bearer gate. Live only when the daemon
+    // wired the gate + ingest registries.
+    if (ctx.gate && ctx.ingestTokens) {
+        const gateDeps = { gate: ctx.gate, ingestTokens: ctx.ingestTokens };
+        const resolutionMatch = pathname.match(/^\/v1\/players\/([^/]+)\/([^/]+)\/gate\/([^/]+)\/resolution$/);
+        if (resolutionMatch) {
+            if (method !== 'GET') {
+                return (0, responses_1.errorResponse)(res, 405, { error: 'method-not-allowed' }, { Allow: 'GET' });
+            }
+            return (0, gate_routes_1.handleGateResolution)(req, res, gateDeps, decodeURIComponent(resolutionMatch[1]), decodeURIComponent(resolutionMatch[2]), decodeURIComponent(resolutionMatch[3]));
+        }
+    }
+    // Layer 2 — shared AUTHENTICATION + Origin/DNS-rebind defense (architect's
+    // decomposition). bearerRequired() carries the Origin-rebind logic; a request
+    // in bearer mode must present a token granting at LEAST a tier (read or admin).
+    // This is the single shared upstream pass — the per-route TIER authorization
+    // (Layer 3, `gateTier(N)` / inline `requireTier(3)`) refines it below: reads → T1,
+    // writes/pair-mint → T2 (admin), gate/inner → T3 (admin).
     const originHeader = headerString(req.headers.origin);
     const reqBearer = (0, auth_1.bearerRequired)(ctx.bindAddr, originHeader);
     if (reqBearer) {
         const provided = (0, auth_1.extractBearerToken)(headerString(req.headers.authorization));
-        if (!provided || !ctx.httpToken || !(0, auth_1.tokensMatch)(provided, ctx.httpToken)) {
+        if (!provided || (0, auth_1.tierForToken)(provided, ctx) === 0) {
             writeCorsHeaders(res, originHeader, ctx, reqBearer);
             return (0, responses_1.errorResponse)(res, 401, { error: 'unauthorized' });
         }
@@ -252,6 +335,46 @@ async function handle(req, res, ctx) {
         res.setHeader('Access-Control-Allow-Origin', cors.echo);
         res.setHeader('Vary', 'Origin');
     }
+    // Layer 3 — per-route AUTHORIZATION (3e MD-E). The tier-guard input is
+    // resolved ONCE here off the shared L2 pass (bindAddr + Origin + the two
+    // RBAC tokens) and reused by every `gateTier(N)` call below — reads require
+    // T1, the write/pair-mint surface requires T2 (admin). The grandfathered T3
+    // gate/inner sites (3c/3d) keep their own inline `requireTier(3)` by design.
+    //
+    // This is defense-in-depth ON TOP of the L2 token-validity floor above (which
+    // already rejects an unrecognized bearer with 401): the explicit per-route
+    // guard keeps each surface protected at its declared tier even if the L2 floor
+    // is later relaxed, and makes the required tier self-documenting + greppable.
+    const tierInput = {
+        bindAddr: ctx.bindAddr,
+        originHeader,
+        authHeader: headerString(req.headers.authorization),
+        readToken: ctx.readToken,
+        adminToken: ctx.adminToken,
+    };
+    /**
+     * Write a tier-denial response, surfacing requireTier's actionable `detail`
+     * hint on 403 (insufficient-tier) / 503 (admin-unset) when present (3e ruling
+     * #3). The hint is operator guidance — e.g. "set AGENT_TEMPO_HTTP_ADMIN_TOKEN"
+     * — NOT a sensitive leak (security-confirmed). Shared by `gateTier` and the
+     * inline T3 gate/inner sites so every tier denial carries the same body shape.
+     */
+    const denyTier = (r) => {
+        (0, responses_1.errorResponse)(res, r.status, 'detail' in r ? { error: r.error, detail: r.detail } : { error: r.error });
+    };
+    /**
+     * Apply a per-route tier guard against the L2-resolved input. On failure it
+     * writes the 401/403/503 response and returns `false` (caller returns); on
+     * success returns `true`. Loopback requests short-circuit to PASS inside
+     * {@link requireTier} (local-trust → full tier).
+     */
+    const gateTier = (n) => {
+        const g = (0, auth_1.requireTier)(n, tierInput);
+        if (g.ok)
+            return true;
+        denyTier(g);
+        return false;
+    };
     // Write surface (PR-7a of #340) — POST `/v1/ensembles/:ensemble/<action>`
     // Match BEFORE the GET-only method gate; everything else (POST to a
     // read endpoint, GET to a write endpoint) flows into the 405 fallback
@@ -261,6 +384,10 @@ async function handle(req, res, ctx) {
         const ensemble = decodeURIComponent(writeMatch[1]);
         const action = writeMatch[2];
         if ((0, writes_1.isWriteAction)(action)) {
+            // L3 — the mutate surface is admin-only (Tier 2). Gate before the method
+            // check so an under-privileged caller can't probe the write verbs via 405.
+            if (!gateTier(2))
+                return;
             if (method !== 'POST') {
                 return (0, responses_1.errorResponse)(res, 405, { error: 'method-not-allowed' }, { Allow: 'POST, OPTIONS' });
             }
@@ -274,6 +401,8 @@ async function handle(req, res, ctx) {
     // alongside the writeMatch above so it's reached before the GET-only
     // gate; the GET on the same path (list ensembles) is handled below.
     if (pathname === '/v1/ensembles' && method === 'POST') {
+        if (!gateTier(2))
+            return; // L3 — create-ensemble is a write (Tier 2).
         return (0, catalog_1.handleCreateEnsemble)(req, res, ctx.client);
     }
     // POST `/dashboard/api/pair` — mint a pairing for cross-device QR (PR-8
@@ -281,9 +410,43 @@ async function handle(req, res, ctx) {
     // proves authority before issuing a token; the token's GET-side consume
     // is the carve-out above the auth gate.
     if (method === 'POST' && pathname === '/dashboard/api/pair') {
+        // L3 — minting a cross-device pairing token is an admin operation (Tier 2):
+        // it grants a bearer-equivalent capability, so it must require the admin token.
+        if (!gateTier(2))
+            return;
         const provided = (0, auth_1.extractBearerToken)(headerString(req.headers.authorization));
         return (0, dashboard_pair_1.handlePairCreate)(req, res, provided);
     }
+    // 3d MD-G OPERATOR plane (operator/dashboard → daemon) — POST routes, so they
+    // sit BEFORE the GET-only method gate below (alongside the other POST routes).
+    // `requireTier(3)` — only an admin-token holder may arm/disarm or decide
+    // (MD-E highest tier). Live only when the daemon wired the gate registries.
+    if (ctx.gate && ctx.ingestTokens && method === 'POST') {
+        const gateDeps = { gate: ctx.gate, ingestTokens: ctx.ingestTokens };
+        const armMatch = pathname.match(/^\/v1\/players\/([^/]+)\/([^/]+)\/gate-(arm|disarm)$/);
+        const decideMatch = pathname.match(/^\/v1\/players\/([^/]+)\/([^/]+)\/gate\/([^/]+)$/);
+        if (armMatch || decideMatch) {
+            const tier = (0, auth_1.requireTier)(3, {
+                bindAddr: ctx.bindAddr,
+                originHeader,
+                authHeader: headerString(req.headers.authorization),
+                readToken: ctx.readToken,
+                adminToken: ctx.adminToken,
+            });
+            if (!tier.ok) {
+                denyTier(tier);
+                return;
+            }
+            if (armMatch) {
+                const [, e, p, verb] = armMatch;
+                return verb === 'arm'
+                    ? (0, gate_routes_1.handleGateArm)(req, res, gateDeps, decodeURIComponent(e), decodeURIComponent(p))
+                    : (0, gate_routes_1.handleGateDisarm)(req, res, gateDeps, decodeURIComponent(e), decodeURIComponent(p));
+            }
+            // decideMatch — POST /gate/:requestId { decision }
+            return (0, gate_routes_1.handleGateDecide)(req, res, gateDeps, decodeURIComponent(decideMatch[1]), decodeURIComponent(decideMatch[2]), decodeURIComponent(decideMatch[3]));
+        }
+    }
     // Method gate — read endpoints are GET-only. Both POST paths above
     // (PR-7a writes, PR-8 pair-mint) handle their own method matching;
     // everything else falls through here.
@@ -295,18 +458,26 @@ async function handle(req, res, ctx) {
     // `/v1/*` API uses. The pre-auth pair-token carve-out above is the
     // single exception that bootstraps cross-device pairing.
     if (pathname === '/dashboard' || pathname.startsWith('/dashboard/')) {
+        if (!gateTier(1))
+            return; // L3 — the dashboard SPA is read-tier (Tier 1).
         return (0, dashboard_1.handleDashboardStatic)(req, res, pathname);
     }
     if (pathname === '/v1/ensembles') {
+        if (!gateTier(1))
+            return; // L3 — read (Tier 1).
         return handleListEnsembles(res, ctx);
     }
     if (pathname === '/v1/hosts') {
+        if (!gateTier(1))
+            return; // L3 — read (Tier 1).
         return handleHosts(res, ctx);
     }
     // #579 — cluster-wide cross-host orphan listing for the dashboard.
     // Same bearer + CORS gate as `/v1/hosts`; optional `?ensemble=<name>`
     // narrows to one ensemble.
     if (pathname === '/v1/orphans') {
+        if (!gateTier(1))
+            return; // L3 — read (Tier 1).
         const ensembleFilter = url.searchParams.get('ensemble') ?? undefined;
         return (0, orphans_1.handleOrphans)(res, {
             client: ctx.client,
@@ -318,14 +489,20 @@ async function handle(req, res, ctx) {
     // Catalog reads (issue #400) — `listAgentTypes` / `listLineups`
     // touch local fs only, no Temporal calls; cheap to serve per-request.
     if (pathname === '/v1/agent-types') {
+        if (!gateTier(1))
+            return; // L3 — read (Tier 1).
         return (0, catalog_1.handleListAgentTypes)(res);
     }
     if (pathname === '/v1/lineups') {
+        if (!gateTier(1))
+            return; // L3 — read (Tier 1).
         return (0, catalog_1.handleListLineups)(res);
     }
     // /v1/state/:ensemble — single capture group.
     const stateMatch = pathname.match(/^\/v1\/state\/([^/]+)$/);
     if (stateMatch) {
+        if (!gateTier(1))
+            return; // L3 — read (Tier 1); covers the fixture path too.
         const ensemble = decodeURIComponent(stateMatch[1]);
         // Fixture mode (PR-3 of #340) — `?fixture=<name>` short-circuits the
         // live snapshot with canned data. Sits behind the bearer-auth gate.
@@ -340,6 +517,8 @@ async function handle(req, res, ctx) {
     // signals "feature exists, not yet wired" rather than "ensemble
     // doesn't exist".
     if (pathname === '/v1/events') {
+        if (!gateTier(1))
+            return; // L3 — read/observe stream (Tier 1).
         if (!ctx.aggregate) {
             return (0, responses_1.errorResponse)(res, 503, { error: 'streaming-not-implemented' }, { 'Retry-After': '60' });
         }
@@ -352,6 +531,8 @@ async function handle(req, res, ctx) {
     }
     const evtMatch = pathname.match(/^\/v1\/events\/([^/]+)$/);
     if (evtMatch) {
+        if (!gateTier(1))
+            return; // L3 — read/observe stream (Tier 1); covers fixture too.
         const ensemble = decodeURIComponent(evtMatch[1]);
         // Fixture mode (PR-3 of #340) — `?fixture=<name>` short-circuits both
         // the existence check and the aggregate poll loop with a canned event
@@ -378,6 +559,30 @@ async function handle(req, res, ctx) {
             cap: ctx.sseConnectionCap,
         });
     }
+    // 3c Tier-2 EGRESS — operator/widget inner-loop SSE fine tail. After the outer
+    // bearer gate (so it's already authenticated); the explicit `requireTier(3)`
+    // marks the tier for 3e (today the outer bearer already satisfied it — 3e
+    // relaxes the outer gate to a read token and this guard demands the admin
+    // token, no call-site change). View-agnostic: bearer-keyed, NO Origin
+    // requirement, plain `event:`/`data:` framing (fetch + Node-client consumable).
+    const innerSseMatch = pathname.match(/^\/v1\/players\/([^/]+)\/([^/]+)\/inner$/);
+    if (innerSseMatch) {
+        if (!ctx.innerLoop || !ctx.ingestTokens) {
+            return (0, responses_1.errorResponse)(res, 503, { error: 'streaming-not-implemented' }, { 'Retry-After': '60' });
+        }
+        const tier = (0, auth_1.requireTier)(3, {
+            bindAddr: ctx.bindAddr,
+            originHeader,
+            authHeader: headerString(req.headers.authorization),
+            readToken: ctx.readToken,
+            adminToken: ctx.adminToken,
+        });
+        if (!tier.ok) {
+            denyTier(tier);
+            return;
+        }
+        return (0, inner_loop_routes_1.handleInnerSse)(req, res, { innerLoop: ctx.innerLoop, ingestTokens: ctx.ingestTokens }, decodeURIComponent(innerSseMatch[1]), decodeURIComponent(innerSseMatch[2]));
+    }
     return (0, responses_1.errorResponse)(res, 404, { error: 'not-found' });
 }
 /** Pull a single string from a possibly-array header. */

package/dist/http/snapshot.d.ts

@@ -51,6 +51,12 @@ export interface PlayerWireMeta {
         expiresAt: number | null;
         leaseMs: number | null;
     };
+    /** 3c Tier-1 — coarse activity (currentTool + context usage), merged onto the summary. */
+    coarse?: {
+        currentTool: string | null;
+        contextTokens?: number;
+        contextPercent?: number;
+    };
 }
 /**
  * Project a `MaestroPlayerInfo` into the wire-stable `PlayerSummaryV1`.

package/dist/http/snapshot.js

@@ -99,6 +99,12 @@ function toPlayerSummaryV1(p, wireMeta = null) {
         ...(wireMeta?.runId !== undefined ? { runId: wireMeta.runId } : {}),
         ...(wireMeta?.messaging !== undefined ? { messaging: wireMeta.messaging } : {}),
         ...(wireMeta?.lease !== undefined ? { lease: wireMeta.lease } : {}),
+        // 3c Tier-1 — coarse activity merged onto the summary so the aggregate
+        // poll/diff can emit player.activity. currentTool is always present on the
+        // coarse object (null = idle); context fields are conditionally included.
+        ...(wireMeta?.coarse?.currentTool !== undefined ? { currentTool: wireMeta.coarse.currentTool } : {}),
+        ...(wireMeta?.coarse?.contextTokens !== undefined ? { contextTokens: wireMeta.coarse.contextTokens } : {}),
+        ...(wireMeta?.coarse?.contextPercent !== undefined ? { contextPercent: wireMeta.coarse.contextPercent } : {}),
     };
 }
 /**

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

@@ -0,0 +1,61 @@
+/**
+ * Cue pump — pulls cues queued on the session workflow and injects them into
+ * the LIVE Pi session via `sendCustomMessage`, 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 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
+ *     override lands immediately); peer cue → `'followUp'` (queue behind the
+ *     current turn rather than interrupting a peer's work).
+ *   - **triggerTurn — always `true`.** Researcher-confirmed: Pi's `followUp`
+ *     does NOT self-wake an idle agent, so an unconditional `triggerTurn` is
+ *     REQUIRED to avoid #18-style silent cue loss when no human is driving. It
+ *     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.
+ *
+ * Adapted from Pi's `examples/extensions/file-trigger.ts`.
+ */
+import type { Message } from '../types';
+import type { PiAgentSession } 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.
+ */
+export type SessionResolver = () => PiAgentSession | null;
+export interface CuePumpOptions {
+    source: CueSource;
+    resolveSession: SessionResolver;
+    /** Poll interval (ms). */
+    intervalMs?: number;
+}
+export declare class CuePump {
+    private readonly source;
+    private readonly resolveSession;
+    private readonly intervalMs;
+    private timer;
+    private draining;
+    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.
+     */
+    tick(): Promise<void>;
+    /**
+     * 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.
+     */
+    private injectCue;
+}

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;