agent-tempo 1.2.0 → 1.4.0

package/dist/http/inner-loop.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InnerLoopRegistry = exports.InnerSubscription = exports.INNER_SUB_QUEUE_MAX = void 0;
+/** Per-subscriber bounded queue depth before drop-oldest engages. */
+exports.INNER_SUB_QUEUE_MAX = 256;
+/**
+ * One connected `/inner` SSE subscriber. Async-iterable: the SSE handler does
+ * `for await (const frame of sub) { write(frame) }`. Bounded queue with
+ * drop-oldest; a `compacted{dropped,sinceTs}` marker is injected before the next
+ * real frame whenever drops have occurred since the last delivery.
+ *
+ * No ring / replay / seq — this is an ephemeral best-effort tail (MD-F): a
+ * disconnect loses in-flight deltas, by design.
+ */
+class InnerSubscription {
+    now;
+    queue = [];
+    dropped = 0;
+    droppedSinceTs = 0;
+    waiter = null;
+    closed = false;
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /** Enqueue a frame, dropping the oldest if the queue is full. Source → sub. */
+    push(frame) {
+        if (this.closed)
+            return;
+        if (this.queue.length >= exports.INNER_SUB_QUEUE_MAX) {
+            this.queue.shift(); // drop oldest
+            if (this.dropped === 0)
+                this.droppedSinceTs = this.now();
+            this.dropped++;
+        }
+        this.queue.push(frame);
+        // A full queue means no waiter is parked (a waiter only parks on an empty
+        // queue), so a drop never races a pending take — drain just wakes a waiter
+        // when one exists (queue was empty, now has one item).
+        if (this.waiter) {
+            const next = this.take();
+            if (next) {
+                const w = this.waiter;
+                this.waiter = null;
+                w({ value: next, done: false });
+            }
+        }
+    }
+    /** Pull the next deliverable, injecting a `compacted` marker first if drops are pending. */
+    take() {
+        if (this.dropped > 0) {
+            const marker = { type: 'compacted', dropped: this.dropped, sinceTs: this.droppedSinceTs };
+            this.dropped = 0;
+            return marker;
+        }
+        return this.queue.shift() ?? null;
+    }
+    next() {
+        if (this.closed)
+            return Promise.resolve({ value: undefined, done: true });
+        const item = this.take();
+        if (item)
+            return Promise.resolve({ value: item, done: false });
+        return new Promise((resolve) => { this.waiter = resolve; });
+    }
+    /** Terminate the stream — wakes a parked consumer with `done: true`. Idempotent. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.waiter) {
+            const w = this.waiter;
+            this.waiter = null;
+            w({ value: undefined, done: true });
+        }
+    }
+    return() {
+        this.close();
+        return Promise.resolve({ value: undefined, done: true });
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}
+exports.InnerSubscription = InnerSubscription;
+/**
+ * Per-daemon registry of inner-loop subscribers, keyed by the player's fixed
+ * session `workflowId`. Implements eng's {@link InnerLoopSink} interface
+ * (`publish` + `subscriberCount`) so the publisher's thin client and this sink
+ * share one contract.
+ */
+class InnerLoopRegistry {
+    now;
+    subs = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /** Open a new SSE subscription for a player. Caller drains it, then `unsubscribe`. */
+    subscribe(workflowId) {
+        const sub = new InnerSubscription(this.now);
+        let set = this.subs.get(workflowId);
+        if (!set) {
+            set = new Set();
+            this.subs.set(workflowId, set);
+        }
+        set.add(sub);
+        return sub;
+    }
+    /** Remove + close one subscription (on SSE disconnect). Prunes the empty player set. */
+    unsubscribe(workflowId, sub) {
+        const set = this.subs.get(workflowId);
+        if (!set)
+            return;
+        set.delete(sub);
+        sub.close();
+        if (set.size === 0)
+            this.subs.delete(workflowId);
+    }
+    /** Fan a frame out to every live subscriber for the player. Source → subs. */
+    publish(workflowId, frame) {
+        const set = this.subs.get(workflowId);
+        if (!set)
+            return;
+        for (const sub of set)
+            sub.push(frame);
+    }
+    /** Live subscriber count — the publisher's presence gate reads this (via `/inner/presence`). */
+    subscriberCount(workflowId) {
+        return this.subs.get(workflowId)?.size ?? 0;
+    }
+    /** Close every subscriber for a player (player gone → streams end with `:closed`). */
+    closePlayer(workflowId) {
+        const set = this.subs.get(workflowId);
+        if (!set)
+            return;
+        for (const sub of set)
+            sub.close();
+        this.subs.delete(workflowId);
+    }
+    /** Total live inner-tail subscribers across all players (diagnostics). */
+    totalSubscriberCount() {
+        let n = 0;
+        for (const set of this.subs.values())
+            n += set.size;
+        return n;
+    }
+    /** Close everything (daemon shutdown). */
+    close() {
+        for (const set of this.subs.values()) {
+            for (const sub of set)
+                sub.close();
+        }
+        this.subs.clear();
+    }
+}
+exports.InnerLoopRegistry = InnerLoopRegistry;

package/dist/http/server.d.ts

@@ -18,6 +18,9 @@
 import * as http from 'http';
 import type { TempoClient } from '../client/interface';
 import type { AggregateRunner } from './aggregate';
+import type { InnerLoopRegistry } from './inner-loop';
+import type { IngestTokenRegistry } from './ingest-registry';
+import type { GateRegistry } from './gate-registry';
 import { type CorsConfig } from './cors';
 import { ConnectionCap } from './sse-handler';
 /** Default bind addr per SSE-PROTOCOL.md §1. */
@@ -59,10 +62,14 @@ export interface HttpServerOptions {
      */
     portFilePath?: string;
     /**
-     * Inject the bearer token directly. Production callers pass `undefined`
-     * so the server reads/auto-generates from `~/.agent-tempo/config.json`.
+     * @deprecated 3e — back-compat alias for {@link readToken}. A single injected
+     * bearer is treated as the READ token (T1). Prefer `readToken`/`adminToken`.
      */
     httpToken?: string;
+    /** 3e — inject the read-tier (T1) token directly (tests). Overrides config/env. */
+    readToken?: string;
+    /** 3e — inject the admin (T1+T2+T3) token directly (tests). Overrides env. */
+    adminToken?: string;
     /**
      * Test seam — lets unit tests stub `process.uptime`-style readings.
      */
@@ -80,6 +87,25 @@ export interface HttpServerOptions {
      * low value in tests to exercise the 503 path.
      */
     maxSseConnections?: number;
+    /**
+     * 3c Tier-2 — the inner-loop fine-tail registry (off-wire SSE sink) and the
+     * ingest-token registry (source-plane auth). When both are provided the
+     * `/v1/players/:e/:p/inner` egress + `/inner/ingest` + `/inner/presence`
+     * ingress routes light up; absent → those routes 404/503. The daemon
+     * constructs + shares these (the outbox mints ingest tokens into the same
+     * `ingestTokens` instance the server validates against).
+     */
+    innerLoop?: InnerLoopRegistry;
+    ingestTokens?: IngestTokenRegistry;
+    /**
+     * 3d MD-G — the operator-gate registry. When provided (with `ingestTokens`)
+     * the `/v1/players/:e/:p/gate-arm` + `/gate-disarm` + `/gate/:requestId`
+     * operator routes (requireTier(3)) and the `/gate/:requestId/resolution`
+     * subprocess-poll route (ingest-token) light up; absent → those routes 404.
+     * The daemon constructs + shares this with the worker (auto-disarm on
+     * detach/destroy) — same singleton pattern as the inner-loop registries.
+     */
+    gate?: GateRegistry;
 }
 export interface HttpServerHandle {
     /** The actual port the server is listening on (after `.listen()` resolves). */
@@ -106,13 +132,22 @@ interface HandleContext {
     version: string;
     bindAddr: string;
     corsConfig: CorsConfig;
-    httpToken: string | null;
+    /** 3e RBAC read-tier token (T1), or null. */
+    readToken: string | null;
+    /** 3e RBAC admin token (T1+T2+T3) — env-var-only, or null when unset. */
+    adminToken: string | null;
     startedAt: number;
     subscriberCount: () => number;
     /** Present when PR-2 streaming is wired; null on PR-1-only deployments. */
     aggregate: AggregateRunner | null;
     /** Process-wide SSE subscriber cap (§7.3). */
     sseConnectionCap: ConnectionCap;
+    /** 3c Tier-2 inner-loop fine-tail sink (off-wire) — null when unwired. */
+    innerLoop: InnerLoopRegistry | null;
+    /** 3c Tier-2 ingest-token registry (source-plane auth) — null when unwired. */
+    ingestTokens: IngestTokenRegistry | null;
+    /** 3d MD-G operator-gate registry — null when unwired. */
+    gate: GateRegistry | null;
 }
 /**
  * Top-level request dispatcher — exported for unit tests that want to

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;
+}