@animalabs/agent-framework 0.27.0 → 0.28.0

package/dist/src/gate/event-gate.js

@@ -40,6 +40,15 @@ function parseGateJson(text) {
 const MIN_DEBOUNCE_MS = 100;
 /** Maximum debounce value (ms). */
 const MAX_DEBOUNCE_MS = 300_000;
+/** Maximum `judge.maxWaitMs` (ms): an hour. */
+const MAX_JUDGE_WAIT_MS = 3_600_000;
+/** Longest `judge.instructions` (characters) a rule may hold: they go to the
+ *  judge with every batch, so they're kept short. */
+const MAX_JUDGE_INSTRUCTIONS = 4_000;
+/** How long a judge request may take by default (ms) before onError decides. */
+const DEFAULT_JUDGE_TIMEOUT_MS = 20_000;
+/** Judge failures in a row after which gate_status names the judge as failing. */
+const JUDGE_FAILING_STREAK = 3;
 /** Whether a check made at `last` is still fresh at `now`, less than the
  *  reload throttle ago. A clock stepped backwards since makes it stale, so
  *  the next check runs rather than wait for the clock to catch up. */
@@ -176,8 +185,22 @@ function formatBehavior(b) {
         const k = b.passive_sample.keyBy ? `,keyBy:${b.passive_sample.keyBy}` : '';
         return `passive_sample:${b.passive_sample.every}${k}`;
     }
+    if ('judge' in b) {
+        const w = b.judge.maxWaitMs !== undefined ? `,maxWait:${b.judge.maxWaitMs}` : '';
+        return `judge:${b.judge.debounceMs}${w}`;
+    }
     return 'unknown';
 }
+/** The quiet period (ms) of a batching behavior: a debounce's, or a judge's. */
+function batchQuietMs(b) {
+    if (typeof b !== 'object')
+        return undefined;
+    if ('debounce' in b)
+        return b.debounce;
+    if ('judge' in b)
+        return b.judge.debounceMs;
+    return undefined;
+}
 /**
  * Stable fingerprint for a GateBehavior, used during reload to detect
  * config changes that invalidate per-policy state. JSON.stringify is
@@ -232,9 +255,10 @@ const MATCH_FIELDS = [
     'scope', 'source', 'channel', 'mount', 'pathGlob', 'tagsAny', 'tagsAll', 'tagsNone', 'metadataTrue', 'filter',
 ];
 const FILTER_FIELDS = ['type', 'pattern'];
-const BEHAVIOR_KINDS = ['debounce', 'rate_limit', 'passive_sample'];
+const BEHAVIOR_KINDS = ['debounce', 'rate_limit', 'passive_sample', 'judge'];
 const RATE_LIMIT_FIELDS = ['tokens', 'refillIntervalMs', 'keyBy'];
 const PASSIVE_SAMPLE_FIELDS = ['every', 'keyBy'];
+const JUDGE_FIELDS = ['debounceMs', 'maxWaitMs', 'instructions'];
 function isPlainObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -410,6 +434,7 @@ function fieldLevels(file) {
         { name: '"behavior"', fields: BEHAVIOR_KINDS },
         { name: '"behavior.rate_limit"', fields: RATE_LIMIT_FIELDS },
         { name: '"behavior.passive_sample"', fields: PASSIVE_SAMPLE_FIELDS },
+        { name: '"behavior.judge"', fields: JUDGE_FIELDS },
     ];
 }
 /** Where a name is a field the gate reads, at a level other than the one whose fields are `here`. */
@@ -589,7 +614,7 @@ function readRule(raw, unnamed, file = 'gate.json') {
         const of = (fields) => m.keys.some((key) => fields.includes(key));
         if (obj.match === undefined && (of(MATCH_FIELDS) || of(FILTER_FIELDS)))
             return 'so the rule matches every event';
-        if (obj.behavior === undefined && (of(BEHAVIOR_KINDS) || of(RATE_LIMIT_FIELDS) || of(PASSIVE_SAMPLE_FIELDS))) {
+        if (obj.behavior === undefined && (of(BEHAVIOR_KINDS) || of(RATE_LIMIT_FIELDS) || of(PASSIVE_SAMPLE_FIELDS) || of(JUDGE_FIELDS))) {
             return 'so the rule\'s behavior is "always"';
         }
         return undefined;
@@ -618,7 +643,7 @@ function readRule(raw, unnamed, file = 'gate.json') {
     }
     return reading;
 }
-const BEHAVIORS_NEEDED = '"always", "defer" or "skip", or an object holding one of "debounce", "rate_limit" and "passive_sample"';
+const BEHAVIORS_NEEDED = '"always", "defer" or "skip", or an object holding one of "debounce", "rate_limit", "passive_sample" and "judge"';
 /**
  * A rule's behavior: "always" when left out; one of the three names; or an
  * object holding one of the timing kinds. Anything else but a list or an
@@ -626,7 +651,8 @@ const BEHAVIORS_NEEDED = '"always", "defer" or "skip", or an object holding one
  * and is read so; a list, or an object holding none of the kinds, was
  * refused, and the rule is left out. Of
  * two kinds or more, "debounce", then "rate_limit", then "passive_sample" was
- * the one read, whatever their order, and is read so. Each other kind is read
+ * the one read, whatever their order, and is read so; "judge", newer than
+ * those, is read only where none of them is given. Each other kind is read
  * on its own as well, so that a refusal names its problems too, and a load
  * reads past them, since it isn't read either way. `kind` is the behavior's
  * kind even where it can't be read, for passthrough's check.
@@ -649,7 +675,7 @@ function readBehavior(r, value) {
     const kinds = BEHAVIOR_KINDS.filter((k) => b[k] !== undefined);
     const kind = kinds[0];
     if (kind === undefined) {
-        r.problems.push({ text: 'behavior holds none of "debounce", "rate_limit" and "passive_sample"' });
+        r.problems.push({ text: 'behavior holds none of "debounce", "rate_limit", "passive_sample" and "judge"' });
         return {};
     }
     if (kinds.length > 1) {
@@ -777,11 +803,109 @@ function readPassiveSample(r, value) {
         out.keyBy = keyBy;
     return { passive_sample: out };
 }
+/**
+ * A judge: a debounce's quiet period, read as `debounce` is, with at its
+ * nearest bound one out of range; an optional longest wait, from that
+ * quiet period to an hour, likewise; and the agent's optional instructions to
+ * the judge, text of at most MAX_JUDGE_INSTRUCTIONS characters. Earlier
+ * releases knew no judge, so nothing deployed has one: a rule whose judge
+ * can't be read is left out, and its instructions, which go to a model with
+ * every batch, are never cut to fit.
+ */
+function readJudge(r, value) {
+    if (!isPlainObject(value)) {
+        r.problems.push({
+            text: `behavior.judge is ${shownValue(value)}, where an object is needed, such as {"debounceMs": 30000, "instructions": "..."}`,
+        });
+        return undefined;
+    }
+    const conf = withoutEmpty(`${r.where}: behavior.judge`, value, r.notes, {
+        maxWaitMs: 'a batch is judged only after its quiet period',
+        instructions: 'the judge decides without the agent\'s word',
+    });
+    readFieldNames(r, 'behavior.judge', conf, JUDGE_FIELDS);
+    let ok = true;
+    const ms = conf.debounceMs;
+    let debounceMs;
+    if (typeof ms !== 'number' || !Number.isFinite(ms)) {
+        r.problems.push({ text: `behavior.judge.debounceMs is ${shownValue(ms)}, where a number of milliseconds is needed, such as 30000` });
+        ok = false;
+    }
+    else if (ms < MIN_DEBOUNCE_MS) {
+        r.problems.push({
+            text: `behavior.judge.debounceMs is ${ms} ms, under the ${MIN_DEBOUNCE_MS} ms minimum`, read: `so it's read as ${MIN_DEBOUNCE_MS} ms`,
+        });
+        debounceMs = MIN_DEBOUNCE_MS;
+    }
+    else if (ms > MAX_DEBOUNCE_MS) {
+        r.problems.push({
+            text: `behavior.judge.debounceMs is ${ms} ms, over the ${MAX_DEBOUNCE_MS} ms maximum`, read: `so it's read as ${MAX_DEBOUNCE_MS} ms`,
+        });
+        debounceMs = MAX_DEBOUNCE_MS;
+    }
+    else {
+        debounceMs = ms;
+    }
+    let maxWaitMs;
+    const wait = conf.maxWaitMs;
+    if (wait !== undefined) {
+        if (typeof wait !== 'number' || !Number.isFinite(wait)) {
+            r.problems.push({ text: `behavior.judge.maxWaitMs is ${shownValue(wait)}, where a number of milliseconds is needed, such as 120000` });
+            ok = false;
+        }
+        else {
+            const floor = debounceMs ?? MIN_DEBOUNCE_MS;
+            if (wait < floor) {
+                r.problems.push({
+                    text: `behavior.judge.maxWaitMs is ${wait} ms, under the rule's ${floor} ms quiet period`,
+                    read: `so it's read as ${floor} ms`,
+                });
+                maxWaitMs = floor;
+            }
+            else if (wait > MAX_JUDGE_WAIT_MS) {
+                r.problems.push({
+                    text: `behavior.judge.maxWaitMs is ${wait} ms, over the ${MAX_JUDGE_WAIT_MS} ms maximum`,
+                    read: `so it's read as ${MAX_JUDGE_WAIT_MS} ms`,
+                });
+                maxWaitMs = MAX_JUDGE_WAIT_MS;
+            }
+            else {
+                maxWaitMs = wait;
+            }
+        }
+    }
+    const said = conf.instructions;
+    let instructions;
+    if (said !== undefined) {
+        if (typeof said !== 'string') {
+            r.problems.push({ text: `behavior.judge.instructions is ${shownValue(said)}, where text is needed` });
+            ok = false;
+        }
+        else if (said.length > MAX_JUDGE_INSTRUCTIONS) {
+            r.problems.push({
+                text: `behavior.judge.instructions is ${said.length} characters long, over the ${MAX_JUDGE_INSTRUCTIONS}-character maximum`,
+            });
+            ok = false;
+        }
+        else {
+            instructions = said;
+        }
+    }
+    if (!ok || debounceMs === undefined)
+        return undefined;
+    const out = { debounceMs };
+    if (maxWaitMs !== undefined)
+        out.maxWaitMs = maxWaitMs;
+    if (instructions !== undefined)
+        out.instructions = instructions;
+    return { judge: out };
+}
 /** How each kind of behavior object is read. */
 const READ_KIND = {
     debounce: readDebounce,
     rate_limit: readRateLimit,
     passive_sample: readPassiveSample,
+    judge: readJudge,
 };
 /** A timing kind's keyBy: a field name. One of another type was read as none. */
 function readKeyBy(r, kind, value) {
@@ -1521,6 +1645,27 @@ export class EventGate {
     startUnsavedMerged = false;
     // Debounce state
     debounceTimers = new Map();
+    // Reply judge state (`judge` rules). The judge itself, when the host wires
+    // one; without it a judge rule's batch is delivered as a debounce's.
+    judgeFn;
+    judgeTimeoutMs;
+    judgeOnError;
+    /** Per rule, the batch the judge is deciding now. */
+    judging = new Map();
+    /** Per rule, a batch that fired while a turn changing the judged context ran or the host was
+     *  quiesced, held to be judged once both are clear: the judge reads the
+     *  context the turn leaves, which may already answer it. */
+    judgeHeld = new Map();
+    judgeRecords = new Map();
+    changesJudgedContextFn;
+    /** Lifetime count of events dropped from batches waiting on the judge, at
+     *  the inference buffer's cap (MAX_INFERENCE_BUFFER per rule). */
+    droppedJudgeEvents = 0;
+    /** Judge requests failed in a row, and the newest failure's reason: a host
+     *  whose provider can't serve the judge's model fails every time, which
+     *  gate_status says once it's a streak (judgeFailingNotice). */
+    judgeFailStreak = 0;
+    judgeLastFailure = '';
     // Rate-limit state — policy name → key → bucket.
     rateLimitBuckets = new Map();
     // Passive-sample state — policy name → key → counter (count since last fire).
@@ -1565,6 +1710,10 @@ export class EventGate {
     // self-wake (an external wake supersedes it; the timer would otherwise
     // land as a redundant empty wake right after the turn).
     selfWakeTimers = new Map();
+    /** When each agent's pending self-wake fires, and what armed it
+     *  (upcomingWakes). Read only while its timer is in selfWakeTimers, so an
+     *  entry a fire or a cancel left behind says nothing. */
+    selfWakeDue = new Map();
     // Privileged users who may wake the agent through sleep. Hot-reloaded from
     // privilegedUsersPath on change.
     privilegedUsersPath;
@@ -1595,6 +1744,12 @@ export class EventGate {
         this.channelShownFn = opts.channelShown;
         this.isNewestEntryFn = opts.isNewestEntry;
         this.now = opts.now ?? (() => Date.now());
+        this.judgeFn = opts.judge;
+        this.changesJudgedContextFn = opts.changesJudgedContext;
+        this.judgeTimeoutMs = opts.judgeTimeoutMs !== undefined && Number.isFinite(opts.judgeTimeoutMs) && opts.judgeTimeoutMs > 0
+            ? Math.min(opts.judgeTimeoutMs, MAX_TIMER_MS)
+            : DEFAULT_JUDGE_TIMEOUT_MS;
+        this.judgeOnError = opts.judgeOnError === 'skip' ? 'skip' : 'wake';
         this.loadPrivileged();
         // Seed or reconcile the on-disk config from the host's starting rules
         // (`initialConfig`), which are read as gate.json is, rule by rule: a rule
@@ -2110,6 +2265,7 @@ export class EventGate {
         for (const name of removed) {
             this.clearPolicyState(name);
             this.stats.delete(name);
+            this.judgeRecords.delete(name);
         }
         const cleared = [...after.keys()].filter((name) => before.has(name) && before.get(name) !== after.get(name));
         for (const name of cleared)
@@ -2568,7 +2724,7 @@ export class EventGate {
             return { trigger: true, policyName: policy.name, behavior: 'always' };
         }
         if (typeof policy.behavior === 'object') {
-            if ('debounce' in policy.behavior) {
+            if ('debounce' in policy.behavior || 'judge' in policy.behavior) {
                 this.handleDebounce(policy, info);
                 return { trigger: false, policyName: policy.name, behavior: policy.behavior };
             }
@@ -2709,7 +2865,7 @@ export class EventGate {
         if (b === 'defer' || b === 'skip')
             return false;
         if (typeof b === 'object') {
-            if ('debounce' in b)
+            if ('debounce' in b || 'judge' in b)
                 return false; // batches; never triggers inline
             if ('rate_limit' in b) {
                 const cfg = b.rate_limit;
@@ -2889,7 +3045,8 @@ export class EventGate {
         }
     }
     handleDebounce(policy, info) {
-        const debounceMs = policy.behavior.debounce;
+        const debounceMs = batchQuietMs(policy.behavior) ?? MIN_DEBOUNCE_MS;
+        const judge = typeof policy.behavior === 'object' && 'judge' in policy.behavior ? policy.behavior.judge : undefined;
         const event = {
             policyName: policy.name,
             content: info.content.length > MAX_CONTENT_SNIPPET
@@ -2910,14 +3067,24 @@ export class EventGate {
             ...(typeof info.metadata?.eventId === 'string' ? { eventId: info.metadata.eventId } : {}),
         };
         const existing = this.debounceTimers.get(policy.name);
+        // A judge's maxWaitMs caps how far new events push the batch back: it's
+        // judged by then, from its first event, quiet or not.
+        const delay = (firstAt, batchJudge) => {
+            const cap = batchJudge?.maxWaitMs;
+            return cap === undefined ? debounceMs : Math.max(0, Math.min(debounceMs, firstAt + cap - this.now()));
+        };
         if (existing) {
             clearTimeout(existing.timer);
             existing.events.push(event);
-            existing.timer = setTimeout(() => this.fireDebounce(policy.name), debounceMs);
+            const ms = delay(existing.firstAt, existing.judge);
+            existing.timer = setTimeout(() => this.fireDebounce(policy.name), ms);
+            existing.dueAt = this.now() + ms;
         }
         else {
-            const timer = setTimeout(() => this.fireDebounce(policy.name), debounceMs);
-            this.debounceTimers.set(policy.name, { timer, events: [event] });
+            const firstAt = this.now();
+            const ms = delay(firstAt, judge);
+            const timer = setTimeout(() => this.fireDebounce(policy.name), ms);
+            this.debounceTimers.set(policy.name, { timer, events: [event], firstAt, dueAt: firstAt + ms, ...(judge ? { judge } : {}) });
         }
     }
     fireDebounce(policyName) {
@@ -2928,6 +3095,13 @@ export class EventGate {
         }
         const events = state.events;
         this.debounceTimers.delete(policyName);
+        // A judge rule's batch goes to the reply judge, which delivers it, or
+        // doesn't, once it has decided (judgeBatch). Without a judge wired it's
+        // delivered below, as a debounce's batch is.
+        if (state.judge && this.judgeFn) {
+            this.judgeBatch(policyName, events, state.judge);
+            return;
+        }
         // If any agent is currently inferring — or the host is quiesced — buffer
         // for later (with cap). While quiesced, delivering would write a
         // "[Gate: N events]" message into the very context being operated on
@@ -3060,10 +3234,299 @@ export class EventGate {
         }
     }
     // =========================================================================
+    // Reply judge (`judge` rules)
+    // =========================================================================
+    /**
+     * Send one of a judge rule's batches to the reply judge. While a resident's
+     * turn runs or the host is quiesced the batch is held instead, merged with
+     * any the rule already holds, and judged once both are clear
+     * (flushJudgeHeldIfClear): the judge then reads the context the turn left,
+     * which may already have answered it. While the judge decides one of the
+     * rule's batches, a later one waits for that verdict (finishJudging), so the
+     * judge never decides two of a rule's batches at once.
+     */
+    judgeBatch(policyName, events, judge) {
+        if (this.disposed)
+            return;
+        const deciding = this.judging.get(policyName);
+        if (deciding) {
+            deciding.queued.push(...events);
+            this.capJudgeEvents(deciding.queued);
+            return;
+        }
+        if (this.judgedTurnRunning() || this.quiesced) {
+            this.holdForJudge(policyName, events, judge);
+            return;
+        }
+        const fn = this.judgeFn;
+        if (!fn) {
+            this.deliverOrBuffer(events);
+            return;
+        }
+        const abort = new AbortController();
+        const agentNames = this.getAgentNamesFn();
+        const state = { events, judge, started: Date.now(), abort, queued: [] };
+        this.judging.set(policyName, state);
+        const timedOut = new Promise((_, reject) => {
+            state.timer = setTimeout(() => {
+                abort.abort();
+                reject(new Error(`the judge took more than ${this.judgeTimeoutMs} ms`));
+            }, this.judgeTimeoutMs);
+            // Never keep the process alive on the judge's account.
+            state.timer.unref?.();
+        });
+        let asked;
+        try {
+            asked = fn({
+                policyName,
+                ...(judge.instructions !== undefined ? { instructions: judge.instructions } : {}),
+                events: events.map((e) => this.judgeEventSummary(e)),
+                agentNames,
+                upcomingWakes: this.upcomingWakes(agentNames, policyName),
+                signal: abort.signal,
+            });
+        }
+        catch (err) {
+            asked = Promise.reject(err);
+        }
+        Promise.race([asked, timedOut]).then((verdict) => this.finishJudging(policyName, state, verdict), (err) => this.finishJudging(policyName, state, undefined, err)).finally(() => {
+            if (state.timer)
+                clearTimeout(state.timer);
+        }).catch((err) => {
+            console.error(`[gate] Policy "${policyName}": the judge's verdict couldn't be applied (${errorText(err)})`);
+        });
+    }
+    /** Hold a batch for the judge until no turn changing the context it reads
+     *  runs and the host isn't quiesced, merged with what the rule already holds. */
+    holdForJudge(policyName, events, judge) {
+        const held = this.judgeHeld.get(policyName);
+        if (held) {
+            held.events.push(...events);
+            held.judge = judge;
+            this.capJudgeEvents(held.events);
+        }
+        else {
+            const fresh = [...events];
+            this.capJudgeEvents(fresh);
+            this.judgeHeld.set(policyName, { events: fresh, judge });
+        }
+    }
+    /**
+     * Keep a rule's events waiting on the judge to the inference buffer's cap,
+     * dropping the oldest, counted and logged as bufferForInference counts its
+     * drops: a turn that never ends (the wake-wedge) or a long quiesce on a busy
+     * channel would otherwise grow them without bound. A queue beside a batch
+     * the judge is deciding is capped on its own, so its newest events are never
+     * the ones dropped for the batch ahead of it.
+     */
+    capJudgeEvents(events) {
+        const drop = events.length - MAX_INFERENCE_BUFFER;
+        if (drop <= 0)
+            return;
+        events.splice(0, drop);
+        const before = this.droppedJudgeEvents;
+        this.droppedJudgeEvents += drop;
+        if (Math.floor(before / 50) !== Math.floor(this.droppedJudgeEvents / 50) || before === 0) {
+            console.error(`[gate] events waiting on the reply judge reached the cap (${MAX_INFERENCE_BUFFER} per rule): dropped `
+                + `${this.droppedJudgeEvents} oldest so far${this.quiesced ? ' during quiesce' : ''}`);
+        }
+    }
+    /** The rule's judge as it is now, when the rule is still a judge rule; else the one the batch was asked with. */
+    currentJudge(policyName, asked) {
+        const now = this.config.policies.find((p) => p.name === policyName)?.behavior;
+        return typeof now === 'object' && 'judge' in now ? now.judge : asked;
+    }
+    /**
+     * The gate's own timers that will wake `agentNames` with no new event, for
+     * the judge to weigh what waiting costs: each agent's pending self-wake
+     * (skip_reply's wake_in_seconds), the end of a sleep, and the pending
+     * batches of rules other than `exceptPolicy` (a debounce's wakes the agent
+     * when it fires; a judge rule's goes to the judge, so it only may).
+     */
+    upcomingWakes(agentNames, exceptPolicy) {
+        const wakes = [];
+        const now = this.now();
+        for (const name of agentNames) {
+            const due = this.selfWakeDue.get(name);
+            if (due && this.selfWakeTimers.has(name)) {
+                wakes.push({ at: due.at, certain: true, what: `${agentNames.length > 1 ? `${name}'s` : 'its'} own ${due.source} timer` });
+            }
+        }
+        if (this.sleepUntil > now && (this.sleepAgent === undefined || agentNames.includes(this.sleepAgent))) {
+            wakes.push({ at: this.sleepUntil, certain: true, what: 'the end of its sleep' });
+        }
+        for (const [name, state] of this.debounceTimers) {
+            if (name === exceptPolicy || state.events.length === 0)
+                continue;
+            const n = state.events.length;
+            const batch = `${n} ${n === 1 ? 'event' : 'events'}`;
+            wakes.push(state.judge
+                ? { at: state.dueAt, certain: false, what: `rule "${name}"'s batch of ${batch} goes to the judge` }
+                : { at: state.dueAt, certain: true, what: `rule "${name}"'s debounced batch of ${batch}` });
+        }
+        return wakes.sort((a, b) => (a.at ?? 0) - (b.at ?? 0));
+    }
+    /** A batch's event as the judge is shown it. */
+    judgeEventSummary(e) {
+        const id = e.routeChannelId ?? e.channelId;
+        let channel;
+        if (id !== undefined) {
+            let name = id;
+            if (e.routeChannelId !== undefined && e.serverId !== undefined && this.channelShownFn) {
+                try {
+                    name = this.channelShownFn({ serverId: e.serverId, channelId: e.routeChannelId });
+                }
+                catch {
+                    name = id;
+                }
+            }
+            channel = e.channelLabel ? `${e.channelLabel.startsWith('#') ? e.channelLabel : `#${e.channelLabel}`} (${name})` : name;
+        }
+        return {
+            eventType: e.eventType,
+            ...(channel !== undefined ? { channel } : {}),
+            ...(e.authorId !== undefined ? { authorId: e.authorId } : {}),
+            addressed: e.addressed,
+            content: e.content,
+            at: e.timestamp,
+        };
+    }
+    /**
+     * Apply the judge's verdict on a batch. Reply: the batch, with any of the
+     * rule's batches that fired meanwhile, is delivered as a debounce's is
+     * (held for a turn that started meanwhile, as fireDebounce holds one). Wait:
+     * nothing is delivered, and batches that fired meanwhile go to the judge
+     * afresh. A judge that failed, timed out or answered nothing usable decides
+     * by onError: "wake" delivers, "skip" doesn't. Each verdict is traced and
+     * counted for gate_status, and a failure is logged.
+     */
+    finishJudging(policyName, state, verdict, err) {
+        // A verdict for a batch the gate let go of (dispose() clears what the
+        // judge was deciding) applies to nothing, even after a start() since.
+        if (this.judging.get(policyName) !== state)
+            return;
+        this.judging.delete(policyName);
+        if (state.timer)
+            clearTimeout(state.timer);
+        const durationMs = Date.now() - state.started;
+        const failed = verdict == null || typeof verdict !== 'object' || typeof verdict.reply !== 'boolean';
+        if (failed && err?.providerAdmission === 'deferred') {
+            const wakes = this.judgeOnError === 'wake';
+            console.error(`[gate] Policy "${policyName}": the reply judge made no call (${errorText(err)}), so its batch of ${state.events.length} `
+                + `${state.events.length === 1 ? 'event' : 'events'} ${wakes ? 'wakes the agent' : "doesn't wake the agent"} (judge onError "${this.judgeOnError}")`);
+            if (this.disposed)
+                return;
+            if (wakes)
+                this.deliverOrBuffer([...state.events, ...state.queued]);
+            else if (state.queued.length > 0)
+                this.judgeBatch(policyName, state.queued, this.currentJudge(policyName, state.judge));
+            return;
+        }
+        const outcome = failed ? 'error' : verdict.reply ? 'reply' : 'wait';
+        const reason = failed
+            ? (err !== undefined ? errorText(err) : 'the judge gave no verdict')
+            : typeof verdict.reason === 'string' ? verdict.reason : '';
+        const record = this.judgeRecords.get(policyName) ?? { verdicts: { reply: 0, wait: 0, error: 0 } };
+        record.verdicts[outcome]++;
+        record.last = {
+            at: Date.now(),
+            verdict: outcome,
+            reason: safeSlice(reason, 0, 300),
+            eventCount: state.events.length,
+            durationMs,
+            ...(!failed && typeof verdict.inputTokens === 'number' ? { inputTokens: verdict.inputTokens } : {}),
+        };
+        if (this.config.policies.some((p) => p.name === policyName))
+            this.judgeRecords.set(policyName, record);
+        if (failed) {
+            this.judgeFailStreak++;
+            this.judgeLastFailure = safeSlice(reason, 0, 200);
+        }
+        else {
+            this.judgeFailStreak = 0;
+        }
+        const wake = outcome === 'reply' || (outcome === 'error' && this.judgeOnError === 'wake');
+        if (failed) {
+            console.error(`[gate] Policy "${policyName}": the reply judge failed (${reason}), so its batch of ${state.events.length} `
+                + `${state.events.length === 1 ? 'event' : 'events'} ${wake ? 'wakes the agent' : "doesn't wake the agent"} (judge onError "${this.judgeOnError}")`);
+        }
+        this.emitTrace({
+            type: 'gate:judge-verdict',
+            policyName,
+            verdict: outcome,
+            woke: wake,
+            eventCount: state.events.length,
+            durationMs,
+            ...(!failed && verdict.model ? { model: verdict.model } : {}),
+            ...(!failed && typeof verdict.inputTokens === 'number' ? { inputTokens: verdict.inputTokens } : {}),
+            ...(!failed && typeof verdict.cacheReadTokens === 'number' ? { cacheReadTokens: verdict.cacheReadTokens } : {}),
+            ...(!failed && typeof verdict.outputTokens === 'number' ? { outputTokens: verdict.outputTokens } : {}),
+            timestamp: Date.now(),
+        });
+        if (this.disposed)
+            return;
+        const judge = this.currentJudge(policyName, state.judge);
+        if (wake) {
+            this.deliverOrBuffer([...state.events, ...state.queued]);
+            return;
+        }
+        if (state.queued.length > 0)
+            this.judgeBatch(policyName, state.queued, judge);
+    }
+    /** Deliver a batch now, or hold it for the agents' turns and the host's
+     *  quiesce to end, as fireDebounce does; a delivery that throws drops it,
+     *  named in the log. */
+    deliverOrBuffer(events) {
+        if (events.length === 0)
+            return;
+        if (this.inferring.size > 0 || this.quiesced) {
+            this.bufferForInference(events);
+            return;
+        }
+        try {
+            this.deliverEvents(events);
+        }
+        catch (err) {
+            const one = events.length === 1;
+            console.error(`[gate] a judged batch of ${events.length} ${one ? 'event' : 'events'} couldn't be delivered `
+                + `(${errorText(err)}), so the batch is dropped`);
+        }
+    }
+    changesJudgedContext(agentName) {
+        return this.changesJudgedContextFn?.(agentName) ?? true;
+    }
+    judgedTurnRunning() {
+        return [...this.inferring].some((name) => this.changesJudgedContext(name));
+    }
+    stopJudging() {
+        for (const [policyName, state] of [...this.judging]) {
+            this.judging.delete(policyName);
+            if (state.timer)
+                clearTimeout(state.timer);
+            state.abort.abort();
+            this.holdForJudge(policyName, [...state.events, ...state.queued], state.judge);
+        }
+    }
+    /** Send the batches held for the judge once no turn changing the context it reads runs and the host isn't quiesced. */
+    flushJudgeHeldIfClear() {
+        if (this.quiesced || this.judgedTurnRunning() || this.judgeHeld.size === 0)
+            return;
+        const held = [...this.judgeHeld];
+        this.judgeHeld.clear();
+        // Deferred, as the inference buffer's flush is, to stay out of the
+        // turn-end callback that called this.
+        queueMicrotask(() => {
+            for (const [policyName, { events, judge }] of held)
+                this.judgeBatch(policyName, events, this.currentJudge(policyName, judge));
+        });
+    }
+    // =========================================================================
     // Inference lifecycle
     // =========================================================================
     onInferenceStarted(agentName) {
         this.inferring.add(agentName);
+        if (this.changesJudgedContext(agentName))
+            this.stopJudging();
         // A turn is starting — whatever caused it supersedes any pending
         // self-wake. (Arming happens MID-turn via skip_reply, i.e. after this
         // ran for the arming turn, so a fresh arm always survives its own turn.)
@@ -3082,10 +3545,13 @@ export class EventGate {
      *  still running. */
     onInferenceResumed(agentName) {
         this.inferring.add(agentName);
+        if (this.changesJudgedContext(agentName))
+            this.stopJudging();
     }
     onInferenceEnded(agentName) {
         this.inferring.delete(agentName);
         this.flushInferenceBufferIfClear();
+        this.flushJudgeHeldIfClear();
     }
     /**
      * Host quiesce suppression (issue #122). While set, debounce firings buffer
@@ -3100,8 +3566,16 @@ export class EventGate {
         if (this.quiesced === quiesced)
             return;
         this.quiesced = quiesced;
-        if (!quiesced)
+        if (quiesced) {
+            // A judge reading the context now would read it mid-surgery, and call
+            // its provider while the host holds still: it's stopped, and its batch
+            // held to be judged at resume.
+            this.stopJudging();
+        }
+        else {
             this.flushInferenceBufferIfClear();
+            this.flushJudgeHeldIfClear();
+        }
     }
     flushInferenceBufferIfClear() {
         if (this.quiesced)
@@ -3128,11 +3602,16 @@ export class EventGate {
      *  is the signature of the wake-wedge: an agent stuck mid-"inference" so all
      *  incoming events buffer and never trigger. */
     inferenceDiagnostics() {
+        let judgeHeldEvents = 0;
+        for (const held of this.judgeHeld.values())
+            judgeHeldEvents += held.events.length;
         return {
             inferring: [...this.inferring],
             bufferedEvents: this.inferenceBuffer.length,
             droppedBufferedEvents: this.droppedBufferedEvents,
             sleepUntil: this.sleepUntil,
+            judgeHeldEvents,
+            droppedJudgeEvents: this.droppedJudgeEvents,
         };
     }
     // =========================================================================
@@ -3278,6 +3757,7 @@ export class EventGate {
             this.requestInferenceFn(agentName, `self-scheduled wake (${source}, ${Math.round(ms / 1000)}s)`, 'self-wake', undefined, placement);
         }, ms);
         this.selfWakeTimers.set(agentName, timer);
+        this.selfWakeDue.set(agentName, { at: this.now() + ms, source });
         this.emitTrace({
             type: 'gate:decision',
             eventType: 'selfwake:set',
@@ -3489,6 +3969,16 @@ export class EventGate {
                     fireCount: this.passiveSampleFires.get(p.name) ?? 0,
                 };
             }
+            if (typeof p.behavior === 'object' && 'judge' in p.behavior) {
+                const record = this.judgeRecords.get(p.name);
+                result.judgeState = {
+                    pendingCount: debounce?.events.length ?? 0,
+                    judging: this.judging.has(p.name),
+                    heldCount: this.judgeHeld.get(p.name)?.events.length ?? 0,
+                    verdicts: { ...(record?.verdicts ?? { reply: 0, wait: 0, error: 0 }) },
+                    ...(record?.last ? { last: { ...record.last } } : {}),
+                };
+            }
             return result;
         });
         const byEventType = {};
@@ -3513,7 +4003,10 @@ export class EventGate {
             default: this.config.default ?? 'always',
             script: this.gateScript.status(),
             policies,
-            errors: [this.configErrorShown(), this.startNotice, this.startUnsaved, this.privilegedError]
+            errors: [
+                this.configErrorShown(), this.startNotice, this.startUnsaved, this.privilegedError,
+                this.judgeUnwiredNotice(), this.judgeFailingNotice(),
+            ]
                 .filter((e) => e !== null),
             shadowWarnings: this.shadowWarningsCache.map(formatShadowWarning),
             totalEvaluations: this.totalEvaluations,
@@ -3524,6 +4017,28 @@ export class EventGate {
             },
         };
     }
+    /** gate_status's word on judge rules in force with no judge wired. */
+    judgeUnwiredNotice() {
+        if (this.judgeFn)
+            return null;
+        const names = this.config.policies
+            .filter((p) => typeof p.behavior === 'object' && 'judge' in p.behavior)
+            .map((p) => p.name);
+        if (names.length === 0)
+            return null;
+        return `${quotedList(names)} ${names.length === 1 ? 'is a judge rule' : 'are judge rules'}, and this host wires no reply `
+            + `judge, so ${names.length === 1 ? 'its batches wake' : 'their batches wake'} the agent as a debounce of the same quiet period would`;
+    }
+    /** gate_status's word on a judge that keeps failing (JUDGE_FAILING_STREAK in a row). */
+    judgeFailingNotice() {
+        if (this.judgeFailStreak < JUDGE_FAILING_STREAK)
+            return null;
+        return `the reply judge has failed its last ${this.judgeFailStreak} requests (the newest: ${this.judgeLastFailure}), `
+            + (this.judgeOnError === 'wake'
+                ? 'so judge rules wake the agent as debounces of the same quiet period would'
+                : "so judge rules' batches don't wake the agent")
+            + "; the host's judge model or provider may not serve it (GateOptions.judge)";
+    }
     // =========================================================================
     // Cleanup
     // =========================================================================
@@ -3533,10 +4048,20 @@ export class EventGate {
             clearTimeout(state.timer);
         }
         this.debounceTimers.clear();
+        // A judge deciding now is told to stop, and its verdict, when it comes,
+        // delivers nothing (finishJudging); held batches go with the buffer.
+        for (const state of this.judging.values()) {
+            if (state.timer)
+                clearTimeout(state.timer);
+            state.abort.abort();
+        }
+        this.judging.clear();
+        this.judgeHeld.clear();
         for (const timer of this.selfWakeTimers.values()) {
             clearTimeout(timer);
         }
         this.selfWakeTimers.clear();
+        this.selfWakeDue.clear();
         // The sleep stays, with its note and agent, and its timer goes: fired
         // after a stop(), its wake reached a framework that had stopped, and the
         // timer held the process until the sleep's end. The next start() arms it