@agenthippo-ai/agenthippo 0.1.1 → 1.110.9

package/out/pack/caps.js

@@ -0,0 +1,271 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) AgentHippo.ai. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CapMeter = exports.CAP_ENV_ALIASES = exports.parseCapPolicy = exports.STRICTEST_ON_BREACH = exports.ON_BREACH_ALIASES = exports.ON_BREACH_ACTIONS = exports.LEASE_CAP_FIELDS = exports.LEASE_CAP_ALIASES = exports.DEPRECATED_CAP_SPELLINGS = void 0;
+exports.resolveOnBreach = resolveOnBreach;
+exports.mergeCaps = mergeCaps;
+exports.capsAreUnbounded = capsAreUnbounded;
+exports.capsFromEnv = capsFromEnv;
+/**
+ * Caps and the live kill switch — the enforcement half of the control plane (serve-v4-clean §5).
+ *
+ * `assertAdmitted` already answers "may this artifact run here, now?" at sandbox CREATION. That is
+ * necessary and not sufficient for an enterprise control plane, which also needs:
+ *
+ *   caps  — a bound on what one session may consume, enforced by serve rather than requested of
+ *           the agent. A cap the agent could talk its way past is not a cap.
+ *   kill  — "stop now", not "stop admitting". Lease revocation alone leaves running sandboxes alive
+ *           until their TTL (up to 30 minutes); an operator hitting the emergency stop means the
+ *           work ends, so the lease watcher below destroys live sandboxes too.
+ *
+ * Precedence is deliberate: an operator's local limit may only ever be *tighter* than the
+ * control plane's. A self-hosted deployment can impose more restraint on itself, never less —
+ * so a compromised or misconfigured instance cannot raise its own ceiling by editing a flag.
+ */
+const lease_schema_1 = require("./lease-schema");
+/**
+ * Re-exported so callers outside pack/ have ONE import site for the cap vocabulary.
+ *
+ * The tables themselves live in `lease-schema.ts`, next to the lease validator that consumes them,
+ * because the whole point is that a lease field, an env var and a CLI flag are held to the same
+ * vocabulary. Adding an alias in one place changes all three.
+ */
+var lease_schema_2 = require("./lease-schema");
+Object.defineProperty(exports, "DEPRECATED_CAP_SPELLINGS", { enumerable: true, get: function () { return lease_schema_2.DEPRECATED_CAP_SPELLINGS; } });
+Object.defineProperty(exports, "LEASE_CAP_ALIASES", { enumerable: true, get: function () { return lease_schema_2.LEASE_CAP_ALIASES; } });
+Object.defineProperty(exports, "LEASE_CAP_FIELDS", { enumerable: true, get: function () { return lease_schema_2.LEASE_CAP_FIELDS; } });
+Object.defineProperty(exports, "ON_BREACH_ACTIONS", { enumerable: true, get: function () { return lease_schema_2.ON_BREACH_ACTIONS; } });
+Object.defineProperty(exports, "ON_BREACH_ALIASES", { enumerable: true, get: function () { return lease_schema_2.ON_BREACH_ALIASES; } });
+Object.defineProperty(exports, "STRICTEST_ON_BREACH", { enumerable: true, get: function () { return lease_schema_2.STRICTEST_ON_BREACH; } });
+Object.defineProperty(exports, "parseCapPolicy", { enumerable: true, get: function () { return lease_schema_2.parseCapPolicy; } });
+/** Env var aliases, old spelling → current spelling. */
+exports.CAP_ENV_ALIASES = {
+    AGENTHIPPO_MAX_CONCURRENT_CELLS: 'AGENTHIPPO_MAX_CONCURRENT_SANDBOXES',
+};
+/**
+ * Resolve a breach action from ANY untrusted source (env, CLI flag, lease field).
+ *
+ * The governing rule, and the reason this is one function rather than three:
+ * **an unrecognised action fails closed to the STRICTER action, loudly. It never softens.**
+ *
+ * It used to soften, in two places at once. `capsFromEnv` mapped an unknown value to `undefined`,
+ * and `cli/index.ts` did the same for `--cap-on-breach`; `mergeCaps` then found no
+ * `'destroy-sandbox'` on either side and `governor.enforce` defaulted to `revoke-inference`. So a
+ * typo — or the perfectly reasonable pre-rename value `destroy-cell` — quietly downgraded
+ * enforcement from "end the session" to "take away its model route", while the console showed the
+ * stricter setting the operator had typed.
+ *
+ * @param source what to name in the warning, e.g. `AGENTHIPPO_CAP_ON_BREACH` or `--cap-on-breach`.
+ */
+function resolveOnBreach(raw, source) {
+    const value = raw?.trim();
+    if (!value) {
+        return { action: undefined, warnings: [] };
+    }
+    if (value in lease_schema_1.ON_BREACH_ACTIONS) {
+        return { action: value, warnings: [] };
+    }
+    const aliased = lease_schema_1.ON_BREACH_ALIASES[value];
+    if (aliased) {
+        return {
+            action: aliased,
+            warnings: [
+                `${source}="${value}" is DEPRECATED; use "${lease_schema_1.DEPRECATED_CAP_SPELLINGS[value] ?? aliased}". ` +
+                    `Treating it as "${aliased}". The old spelling will stop being accepted.`,
+            ],
+        };
+    }
+    return {
+        action: lease_schema_1.STRICTEST_ON_BREACH,
+        warnings: [
+            `${source}="${value}" is not a breach action this build understands. ` +
+                `FAILING CLOSED to "${lease_schema_1.STRICTEST_ON_BREACH}" — an unreadable enforcement setting must never ` +
+                `weaken enforcement. Known actions: ${Object.keys(lease_schema_1.ON_BREACH_ACTIONS).join(', ')}.`,
+        ],
+    };
+}
+/** Ceiling on metered sessions, so an unbounded instance cannot grow meters without limit. */
+const MAX_METERED_SESSIONS = 10_000;
+/**
+ * Tighten-only merge. `local` may lower any bound the control plane set, never raise it, and may
+ * only escalate the breach action (revoke → destroy), never soften it.
+ */
+function mergeCaps(controlPlane, local) {
+    const cp = controlPlane ?? {};
+    const lo = local ?? {};
+    const tighter = (a, b) => {
+        if (a === undefined) {
+            return b;
+        }
+        if (b === undefined) {
+            return a;
+        }
+        return Math.min(a, b);
+    };
+    return {
+        maxTurnsPerSession: tighter(cp.maxTurnsPerSession, lo.maxTurnsPerSession),
+        maxSessionSeconds: tighter(cp.maxSessionSeconds, lo.maxSessionSeconds),
+        maxConcurrentSandboxes: tighter(cp.maxConcurrentSandboxes, lo.maxConcurrentSandboxes),
+        // destroy is stricter than revoke; either side may escalate, neither may soften.
+        onBreach: cp.onBreach === 'destroy-sandbox' || lo.onBreach === 'destroy-sandbox'
+            ? 'destroy-sandbox'
+            : (cp.onBreach ?? lo.onBreach),
+    };
+}
+/** True when no bound is set at all — lets callers skip the machinery entirely. */
+function capsAreUnbounded(caps) {
+    return caps.maxTurnsPerSession === undefined
+        && caps.maxSessionSeconds === undefined
+        && caps.maxConcurrentSandboxes === undefined;
+}
+/**
+ * Per-session meter. Checked BEFORE a turn runs: a cap discovered afterwards has already let the
+ * spend happen, so `check` is the gate and `record` only advances the counters.
+ */
+class CapMeter {
+    caps;
+    sessions = new Map();
+    constructor(caps) {
+        this.caps = caps;
+    }
+    /**
+     * Adopt caps the control plane pushed since boot.
+     *
+     * Caps used to be read from the lease exactly ONCE, at construction, so tightening a cap in
+     * the control plane did nothing until every instance was restarted — the fleet reported the
+     * new policy while enforcing the old one. Live-caught by the control-plane acceptance test.
+     * Existing per-session counters are deliberately kept: a lowered cap must bite immediately on
+     * sessions already over it, not hand them a fresh allowance.
+     */
+    setCaps(caps) {
+        this.caps = caps;
+    }
+    /** Current policy in force — surfaced on the admin/health endpoint. */
+    policy() {
+        return this.caps;
+    }
+    /**
+     * @param liveSandboxes Current live sandbox count — concurrency is an instance-wide bound, so it is
+     *                  supplied by the caller rather than tracked here.
+     */
+    check(sessionKey, liveSandboxes, nowMs = Date.now()) {
+        const usage = this.sessions.get(sessionKey);
+        if (this.caps.maxTurnsPerSession !== undefined && usage && usage.turns >= this.caps.maxTurnsPerSession) {
+            return {
+                allowed: false,
+                cap: 'turns',
+                reason: `session turn cap reached (${usage.turns}/${this.caps.maxTurnsPerSession})`,
+            };
+        }
+        if (this.caps.maxSessionSeconds !== undefined && usage) {
+            const elapsed = Math.floor((nowMs - usage.startedAtMs) / 1000);
+            if (elapsed >= this.caps.maxSessionSeconds) {
+                return {
+                    allowed: false,
+                    cap: 'duration',
+                    reason: `session duration cap reached (${elapsed}s/${this.caps.maxSessionSeconds}s)`,
+                };
+            }
+        }
+        // Concurrency applies only to sessions that would need a NEW sandbox; an established session
+        // reuses its own, so counting it against the cap would strand it once the fleet filled up.
+        if (this.caps.maxConcurrentSandboxes !== undefined && !usage && liveSandboxes >= this.caps.maxConcurrentSandboxes) {
+            return {
+                allowed: false,
+                cap: 'concurrency',
+                reason: `instance is at its concurrent sandbox cap (${liveSandboxes}/${this.caps.maxConcurrentSandboxes})`,
+            };
+        }
+        return { allowed: true };
+    }
+    /**
+     * Advance the counters for a turn that actually ran.
+     *
+     * Metering happens even when caps are currently unbounded, and that is the point: caps can be
+     * tightened from the control plane mid-flight, and a session that ran fifty turns under an
+     * unbounded policy must not then receive a fresh allowance the moment a cap appears. Counting
+     * only while a cap happens to be set is precisely the kind of gap an agent can be steered into.
+     */
+    record(sessionKey, nowMs = Date.now()) {
+        const existing = this.sessions.get(sessionKey);
+        if (existing) {
+            existing.turns += 1;
+            return;
+        }
+        // Bounded so an unbounded, long-lived instance cannot accumulate meters forever; the
+        // oldest session is the one least likely to still be running.
+        if (this.sessions.size >= MAX_METERED_SESSIONS) {
+            let oldestKey;
+            let oldestAt = Infinity;
+            for (const [key, usage] of this.sessions) {
+                if (usage.startedAtMs < oldestAt) {
+                    oldestAt = usage.startedAtMs;
+                    oldestKey = key;
+                }
+            }
+            if (oldestKey) {
+                this.sessions.delete(oldestKey);
+            }
+        }
+        this.sessions.set(sessionKey, { turns: 1, startedAtMs: nowMs });
+    }
+    /** Drop a session's meter — called when its sandbox is destroyed so a fresh session starts clean. */
+    forget(sessionKey) {
+        this.sessions.delete(sessionKey);
+    }
+    usage(sessionKey) {
+        const u = this.sessions.get(sessionKey);
+        if (!u) {
+            return undefined;
+        }
+        return { turns: u.turns, ageSeconds: Math.floor((Date.now() - u.startedAtMs) / 1000) };
+    }
+}
+exports.CapMeter = CapMeter;
+/**
+ * Parse `AGENTHIPPO_MAX_*` style env, ignoring blanks and non-numbers rather than guessing.
+ *
+ * LOCAL config, so the rules differ from a lease deliberately: a typo in an operator's own env is
+ * dropped (they can see and fix it, and dropping it only affects their own instance), whereas the
+ * same typo arriving from a control plane means the fleet believes a cap is in force that is not.
+ * The `onBreach` vocabulary, however, comes from the same table `parseCapPolicy` uses, so a value
+ * that is valid in a lease is valid here and vice versa — including any back-compat aliases layered
+ * into `ON_BREACH_ALIASES`.
+ */
+function capsFromEnv(env = process.env, warn = (m) => console.warn(`Warning: ${m}`)) {
+    const num = (raw) => {
+        const v = parseInt((raw ?? '').trim(), 10);
+        return Number.isFinite(v) && v > 0 ? v : undefined;
+    };
+    /** Current spelling wins; a deprecated one is honoured once, loudly. */
+    const numWithAlias = (current) => {
+        const direct = num(env[current]);
+        if (direct !== undefined) {
+            return direct;
+        }
+        for (const [old, replacement] of Object.entries(exports.CAP_ENV_ALIASES)) {
+            if (replacement !== current) {
+                continue;
+            }
+            const legacy = num(env[old]);
+            if (legacy === undefined) {
+                continue;
+            }
+            warn(`${old} is DEPRECATED; use ${current}. Honouring it for now.`);
+            return legacy;
+        }
+        return undefined;
+    };
+    const breach = resolveOnBreach(env.AGENTHIPPO_CAP_ON_BREACH, 'AGENTHIPPO_CAP_ON_BREACH');
+    for (const w of breach.warnings) {
+        warn(w);
+    }
+    return {
+        maxTurnsPerSession: numWithAlias('AGENTHIPPO_MAX_TURNS_PER_SESSION'),
+        maxSessionSeconds: numWithAlias('AGENTHIPPO_MAX_SESSION_SECONDS'),
+        maxConcurrentSandboxes: numWithAlias('AGENTHIPPO_MAX_CONCURRENT_SANDBOXES'),
+        onBreach: breach.action,
+    };
+}

package/out/pack/governor.js

@@ -0,0 +1,309 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) AgentHippo.ai. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.effectiveDenyMode = effectiveDenyMode;
+exports.createGovernor = createGovernor;
+exports.withGovernor = withGovernor;
+const caps_1 = require("./caps");
+const lease_1 = require("./lease");
+/**
+ * What a deny mode MEANS on this deployment, as opposed to what it was written as.
+ *
+ * Without a sandbox driver there is no non-cooperative way to stop a turn already executing in
+ * this process, so `kill` degrades to `drain`. The degradation is real and unavoidable at this
+ * layer; what is not acceptable is reporting `kill` while doing `drain`.
+ */
+function effectiveDenyMode(mode, supportsInFlightTermination) {
+    if (mode === 'kill' && !supportsInFlightTermination) {
+        return 'drain';
+    }
+    return mode;
+}
+function createGovernor(opts) {
+    const meter = new caps_1.CapMeter(opts.caps);
+    // Not const: every lease poll re-merges the control plane's caps over the local ones.
+    let unbounded = (0, caps_1.capsAreUnbounded)(opts.caps);
+    let timer;
+    /** Latches once the lease kills us: no further turn may sneak through between polls. */
+    let killed;
+    /** Last lease seen, so per-session deny checks need no fetch on the turn path. */
+    let currentLease;
+    /**
+     * sessionKey → the verified user it belongs to, learned from `admitTurn`.
+     *
+     * Only the turn path knows the resolved identity, but the lease WATCHER is what ends running
+     * work — so without remembering it, a `user`-scoped kill could refuse the next turn and still
+     * leave the user's live sandbox running.
+     */
+    const sessionUsers = new Map();
+    /** True unless the deployment has no way to end a running turn — see GovernableSandboxes. */
+    const canTerminateInFlight = opts.sandboxes.supportsInFlightTermination !== false;
+    /** Session rules extended to the users behind them, so id rotation does not escape. */
+    let followedUsers = new Map();
+    /** Kill rules already reported as degraded, so the warning is loud once, not every poll. */
+    const degradedKillsReported = new Set();
+    const audit = (event, fields) => {
+        try {
+            opts.audit?.(event, fields);
+        }
+        catch { /* evidence must never break enforcement */ }
+    };
+    /**
+     * Bounded on purpose: a long-lived serve sees unbounded distinct session keys (every anonymous
+     * gateway sender gets a fresh uuid), and an unbounded map here would be a slow leak in the one
+     * component that must never be the reason an instance falls over. Oldest-first eviction costs
+     * only the ability to kill an already-idle session by user scope.
+     */
+    const MAX_TRACKED_SESSION_USERS = 10_000;
+    const rememberSessionUser = (sessionKey, userId) => {
+        if (sessionUsers.size >= MAX_TRACKED_SESSION_USERS && !sessionUsers.has(sessionKey)) {
+            const oldest = sessionUsers.keys().next();
+            if (!oldest.done) {
+                sessionUsers.delete(oldest.value);
+            }
+        }
+        sessionUsers.set(sessionKey, userId);
+    };
+    const enforce = async (sessionKey, decision) => {
+        // The MERGED policy, not the local one: a control plane that escalates revoke → destroy
+        // must be obeyed on the next breach, not on the next restart.
+        const action = meter.policy().onBreach ?? 'revoke-inference';
+        try {
+            if (action === 'destroy-sandbox') {
+                // The SANDBOX is destroyed; the session's meter deliberately survives it.
+                // `meter.forget` here reset turns and the duration clock, so a breached session got
+                // a brand-new budget and `maxTurnsPerSession: 10` degraded into "one refused turn
+                // every ten, forever" — a cap that renews on breach is not a cap.
+                await opts.sandboxes.destroySession(sessionKey);
+            }
+            else {
+                // Narrower: the session keeps its sandbox (and its state, for inspection) but loses
+                // the model route, so it cannot spend another token.
+                await opts.sandboxes.revokeRoute(sessionKey, 'inference');
+            }
+        }
+        catch (err) {
+            // A tier-0 sandbox cannot revoke a single route; falling back to destroy keeps the cap
+            // honest instead of silently letting the session continue.
+            opts.logger?.warn(`[Governor] ${action} failed for ${sessionKey}, destroying instead: ${err instanceof Error ? err.message : String(err)}`);
+            await opts.sandboxes.destroySession(sessionKey).catch(() => undefined);
+            // Same rule as the deliberate destroy above: the meter outlives the sandbox, or the
+            // fallback path quietly hands back the budget the primary path refused.
+        }
+        opts.logger?.warn(`[Governor] cap breach on ${sessionKey}: ${decision.reason} — ${action}`);
+        audit('cap_breach', { sessionKey, cap: decision.cap, reason: decision.reason, action });
+    };
+    const killAll = async (reason) => {
+        const live = opts.sandboxes.sandboxes();
+        for (const c of live) {
+            await opts.sandboxes.destroySession(c.sessionKey).catch(() => undefined);
+            // The meter deliberately SURVIVES the kill, for exactly the reason `enforce` gives when
+            // it destroys a sandbox on a cap breach: a cap that renews when the sandbox goes away is
+            // not a cap. `meter.forget` here meant a kill-then-restore (a billing hold lifted, a
+            // drill, an operator toggling the switch) handed every session a brand-new turn and
+            // duration budget — so the cheapest way past a cap was to trip the kill switch. The two
+            // paths now agree: destroying a sandbox never returns budget.
+        }
+        if (live.length > 0) {
+            opts.logger?.warn(`[Governor] kill switch: destroyed ${live.length} live sandbox(s) — ${reason}`);
+        }
+        else if (!canTerminateInFlight) {
+            // Without a driver there is nothing to destroy, and the kill switch reduces to refusing
+            // the next turn. Say so rather than logging a successful stop of zero sandboxes.
+            opts.logger?.warn(`[Governor] kill switch: no sandbox driver, so nothing running can be stopped — ` +
+                `in-flight turns will finish and only NEW turns are refused (${reason}). Run with --sandbox for true in-flight kill.`);
+        }
+        audit('kill_switch', { reason, destroyed: live.length, inFlightTerminated: canTerminateInFlight });
+        return live.length;
+    };
+    const checkLease = async () => {
+        if (!opts.getLease) {
+            return;
+        }
+        try {
+            const lease = await opts.getLease();
+            // Adopt caps the control plane has pushed since boot. Same tighten-only merge as at
+            // construction, re-applied every poll: an operator who lowers a cap in the console
+            // must not have to restart the fleet for it to bite. Without this the instance
+            // reported the new policy while enforcing the boot-time one.
+            const merged = (0, caps_1.mergeCaps)(lease?.caps, opts.caps);
+            meter.setCaps(merged);
+            unbounded = (0, caps_1.capsAreUnbounded)(merged);
+            // Cache the deny rules so `admitTurn` stays synchronous and cheap: enforcement latency
+            // is the poll interval, exactly like the kill switch, rather than a fetch per turn.
+            currentLease = lease;
+            // Recomputed each poll from what the turn path has learned, so a session stop reaches the
+            // user's other sessions even after they rotate `session_id`.
+            followedUsers = (0, lease_1.resolveFollowedUsers)(lease, sessionUsers);
+            // A `kill` rule this deployment cannot honour must not be reported as honoured. Warn
+            // once per rule, before sweeping, so an operator learns immediately that the rule they
+            // just published means `drain` here.
+            if (!canTerminateInFlight) {
+                for (const rule of lease?.deny ?? []) {
+                    if (rule.mode !== 'kill') {
+                        continue;
+                    }
+                    const id = `${rule.scope}:${rule.match}`;
+                    if (degradedKillsReported.has(id)) {
+                        continue;
+                    }
+                    degradedKillsReported.add(id);
+                    opts.logger?.warn(`[Governor] deny(kill) on ${id} DEGRADED TO DRAIN: this deployment has no sandbox driver, so a turn ` +
+                        'already executing cannot be stopped. It will run to completion; only the next turn is refused. ' +
+                        'Run serve with --sandbox for a kill that ends work mid-flight.');
+                    audit('deny_kill_degraded', { scope: rule.scope, match: rule.match, effectiveMode: 'drain' });
+                }
+            }
+            // `kill` rules end work already running. `drain` deliberately does not — it lets the
+            // in-flight turn finish and only refuses the next one.
+            for (const sandbox of opts.sandboxes.sandboxes()) {
+                const v = (0, lease_1.denyVerdict)(lease, {
+                    sessionKey: sandbox.sessionKey,
+                    pack: opts.pack ?? '',
+                    userHash: opts.userHash,
+                    // Remembered from this session's turns, so a `user`-scoped kill reaches a
+                    // gateway session whose key carries no `u<hash>--` prefix to read it off.
+                    userId: sessionUsers.get(sandbox.sessionKey),
+                    followedUsers,
+                });
+                if (v.denied && effectiveDenyMode(v.mode, canTerminateInFlight) === 'kill') {
+                    await opts.sandboxes.destroySession(sandbox.sessionKey).catch(() => undefined);
+                    sessionUsers.delete(sandbox.sessionKey);
+                    // The meter survives, same rule as `killAll` and `enforce`: a stop order must not
+                    // hand the session a fresh budget when it is lifted.
+                    opts.logger?.warn(`[Governor] deny(kill) destroyed ${sandbox.sandboxId} — ${v.reason}`);
+                    audit('session_killed', { sessionKey: sandbox.sessionKey, sandboxId: sandbox.sandboxId, reason: v.reason });
+                }
+            }
+            const verdict = (0, lease_1.leaseIsDead)(lease);
+            if (verdict.dead) {
+                killed = verdict.reason ?? 'lease revoked';
+                await killAll(killed);
+            }
+            else if (killed) {
+                // A restored lease lifts the latch — an operator can turn the fleet back on
+                // without restarting every instance.
+                opts.logger?.info('[Governor] lease restored — accepting turns again');
+                audit('kill_switch_lifted', {});
+                killed = undefined;
+            }
+        }
+        catch (err) {
+            // Fail-open on transport, exactly like the lease source: a control-plane outage must
+            // not take a customer's fleet down.
+            opts.logger?.warn(`[Governor] lease check failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    return {
+        async admitTurn(sessionKey, userId) {
+            if (killed) {
+                return { allowed: false, reason: `stopped by the control plane: ${killed}` };
+            }
+            if (userId) {
+                rememberSessionUser(sessionKey, userId);
+            }
+            // Scoped stop orders refuse NEW work in both modes; the difference between drain and
+            // kill is only what happened to the turn already running, decided at the last poll.
+            const denied = (0, lease_1.denyVerdict)(currentLease, {
+                sessionKey,
+                pack: opts.pack ?? '',
+                userHash: opts.userHash,
+                userId: userId ?? sessionUsers.get(sessionKey),
+                // A session stop follows the user, so sending a fresh `session_id` does not escape it.
+                // Recomputed here as well as on the poll because the identity behind THIS session may
+                // only just have become known — waiting a poll would admit exactly the turn we are
+                // trying to refuse.
+                followedUsers: (0, lease_1.resolveFollowedUsers)(currentLease, sessionUsers),
+            });
+            if (denied.denied) {
+                return { allowed: false, reason: denied.reason };
+            }
+            // What is running, not just whether it may run: signature + pin, for the no-sandbox
+            // path where nothing else asks. Before the caps check, because an unsigned or
+            // unpinned pack must be refused whether or not the session has budget left.
+            if (opts.admitPack) {
+                // The lease the poll last saw — the SAME view the kill and deny checks just used,
+                // and no fetch on the turn path.
+                const packVerdict = opts.admitPack(sessionKey, currentLease);
+                if (!packVerdict.allowed) {
+                    return { allowed: false, reason: packVerdict.reason ?? 'refused by pack admission' };
+                }
+            }
+            if (unbounded) {
+                return { allowed: true };
+            }
+            const decision = meter.check(sessionKey, opts.sandboxes.sandboxes().length);
+            if (!decision.allowed) {
+                // Concurrency is a "come back later" refusal about the INSTANCE — there is no
+                // offending session to punish, and revoking someone else's route would be wrong.
+                if (decision.cap !== 'concurrency') {
+                    await enforce(sessionKey, decision);
+                }
+            }
+            return decision;
+        },
+        recordTurn(sessionKey) {
+            // Always meter, even while unbounded: caps can be tightened mid-flight from the
+            // control plane, and a session must not get a clean slate the moment one appears.
+            meter.record(sessionKey);
+        },
+        killAll,
+        refresh: checkLease,
+        start() {
+            if (!opts.getLease || timer) {
+                return;
+            }
+            // One constant for the poll interval, shared with the lease source's cache — see
+            // DEFAULT_LEASE_POLL_SECONDS. These two used to disagree (30 vs 60) and the banner
+            // printed the smaller one.
+            const everyMs = (0, lease_1.resolveLeasePollSeconds)(opts.pollSeconds) * 1000;
+            timer = setInterval(() => { void checkLease(); }, everyMs);
+            timer.unref?.();
+            void checkLease();
+        },
+        stop() {
+            if (timer) {
+                clearInterval(timer);
+                timer = undefined;
+            }
+        },
+        // The caps ACTUALLY in force, which after a poll may be tighter than the boot-time ones.
+        policy: () => meter.policy(),
+    };
+}
+/**
+ * Put the governor in front of a runner, so every turn passes the gate no matter which endpoint
+ * it arrived on. serve has three call sites into `runner.run`; decorating the runner covers all
+ * of them and cannot be forgotten when a fourth is added — the same relocation trick
+ * `createSandboxRunner` uses one layer down.
+ */
+function withGovernor(runner, governor) {
+    return {
+        async run(options) {
+            const sessionKey = options.sessionId ?? 'default';
+            // The identity serve resolved for this turn — what makes "stop this user" exact.
+            const decision = await governor.admitTurn(sessionKey, options.analyticsUserId);
+            if (!decision.allowed) {
+                // A refusal is a normal, reportable outcome — not an exception. The caller turns
+                // this into a 429/403 with the operator's reason intact.
+                return {
+                    success: false,
+                    text: '',
+                    thinking: '',
+                    toolCalls: [],
+                    error: decision.reason ?? 'refused by policy',
+                };
+            }
+            // Counted BEFORE the turn runs: a turn that crashes or is aborted still consumed the
+            // budget, and not counting it would let a session retry past its cap forever.
+            governor.recordTurn(sessionKey);
+            return runner.run(options);
+        },
+        dispose() {
+            governor.stop();
+            runner.dispose();
+        },
+    };
+}