@animalabs/agent-framework 0.26.2 → 0.28.0

package/dist/src/gate/event-gate.d.ts

@@ -11,8 +11,8 @@
  * inference tokens, not whether the agent should know about the event.
  */
 import type { ToolDefinition } from '../types/events.js';
-import type { GateConfig, GatePolicy, GateDecision, GateEventInfo, GateStatus, ShadowWarning, GateProbeRow } from './types.js';
-export type { GateConfig, GateOptions, GateDecision, GateEventInfo } from './types.js';
+import type { GateConfig, GatePolicy, GateDecision, GateEntryRef, WakeLine, GateEventInfo, GateStatus, ShadowWarning, GateProbeRow, JudgeFn, UpcomingWake } from './types.js';
+export type { GateConfig, GateOptions, GateDecision, GateEntryRef, GateEventInfo, WakeLine, JudgeConfig, JudgeEventSummary, JudgeFn, JudgeRequest, JudgeVerdict, ReplyJudgeOptions, UpcomingWake, } from './types.js';
 interface PendingEvent {
     policyName: string;
     content: string;
@@ -44,11 +44,24 @@ interface PendingEvent {
      *  whose `channelId` is the adapter's raw id (a bare Discord snowflake for a
      *  DM) — unroutable. Absent when the host could not resolve one. */
     routeChannelId?: string;
+    /** The event's own identity among what the framework stored at arrival:
+     *  a channel message's id, a push event's event id (isNewestEntry). */
+    messageId?: string;
+    eventId?: string;
+}
+/** Where the host put a message the gate wrote: the agent whose window it
+ *  went to and, when it was held for that agent's live turn, the id it waits
+ *  under in the host's queue, or else the id it was stored under. */
+export interface WritePlacement {
+    agent?: string;
+    deferredId?: string;
+    messageId?: string;
 }
 /**
  * Where a gate-requested wake came from, handed to the framework alongside the
  * reason so the turn's InferenceRequest can carry it (host telemetry stamps
- * "who woke the agent" from it). Ids only, never content or display names.
+ * "who woke the agent" from it). Ids only, never content or display names,
+ * except `line`, which is the batch's own text for the agent's window.
  */
 export interface WakeProvenance {
     /** Composite channel id of the chosen event — telemetry only, never a
@@ -70,9 +83,20 @@ export interface WakeProvenance {
      *  (2026-09-30: a DM reply published into a guild channel). Ambient-only
      *  batches still set nothing and keep the legacy fallback. */
     routeChannelId?: string;
+    /** The server of `routeChannelId`'s channel, beside it whenever the chosen
+     *  event named its server: channel ids are unique only within one
+     *  server's connection (MCPL §14.2). */
+    routeServerId?: string;
     /** Timestamp (ms) of the chosen event, so a consumer coalescing several
      *  requests can order by event recency, not by flush order. */
     at?: number;
+    /** The batch's `[Gate: …]` line, when the gate handed it to the wake rather
+     *  than wrote it: a WakeLine, the parts its text is rendered from when it's
+     *  written (wakeLineText), decided by a fresh start of the wake's turn as
+     *  WakeLine says. Unlike the fields above, this is content for the agent's
+     *  window, not telemetry: it carries the channel's name as the agent is
+     *  shown it. */
+    line?: WakeLine;
 }
 interface TraceEventLike {
     type: string;
@@ -85,6 +109,24 @@ interface TraceEventLike {
  * addressed all come from that one event, so they can never disagree.
  */
 export declare function wakeProvenance(events: PendingEvent[]): WakeProvenance | undefined;
+/** A handed batched-wake line's text (WakeLine), as it reads when written at
+ *  `now`: the gate's words, its message's age counted to then. */
+export declare function wakeLineText(line: WakeLine, now: number): string;
+/**
+ * A value as a message quotes it: its JSON, cut short when long, never inside a
+ * surrogate pair, since the message reaches the agent's context.
+ */
+export declare function shownValue(value: unknown): string;
+/**
+ * A tool's input, its parameters given by its schema's `properties`, read as a
+ * rule's fields are: a null or "" parameter is left out (a note names each "",
+ * with what leaving it out does where `means` says), a slip of a parameter
+ * (fieldNames) is refused, naming the one meant, and so is a field of one of
+ * its object parameters given on its own, naming that parameter; any other
+ * name is noted, or named in that refusal. Returns the input without what was
+ * left out.
+ */
+export declare function checkToolInput(tool: string, input: Record<string, unknown>, properties: Readonly<Record<string, unknown>>, notes: string[], means?: Readonly<Record<string, string>>): Record<string, unknown>;
 /**
  * Find rules made unreachable by earlier, broader rules (first match wins).
  * The 2026-08-08 Mythos incident is the canonical catch: a prepended
@@ -103,12 +145,57 @@ export declare class EventGate {
     /** Optional agent-authored programmable gate (gate.js). */
     private gateScript;
     private compiledPolicies;
-    private configMtime;
+    /** The text of gate.json whose rules are in force, from a load or a write
+     *  (or the start's reconcile, whose write failed); or, while what's in force
+     *  is what a start ran beside gate.json or in its place (configSource not
+     *  "file"), gate.json's text as that start found it.
+     *  A reload parses the file again only when its text differs; a file that
+     *  holds it again after failing to load (a chmod that makes it readable,
+     *  an edit undone) needs nothing applied, only its error cleared. */
+    private configText;
+    /** The notes on fields the text in force has that the gate doesn't read, if any. */
+    private configNote;
     private lastReloadCheck;
     private configSource;
     private lastReloadTimestamp;
-    private configErrors;
+    /** The current problem with each file the gate reads, one each, replaced
+     *  whenever that file is read again (gate_status `errors`). */
+    private configError;
+    /** Whether gate.json's error is one that keeps what it holds out of force
+     *  (configUnreadable), so gate_status says what's in force instead. */
+    private configUnused;
+    private privilegedError;
+    /** What the start did with the host's starting rules that it couldn't use
+     *  or add (describeStart), kept apart from gate.json's own error, until the
+     *  next start. */
+    private startNotice;
+    /** The rules in force that the start couldn't save (describeUnsaved),
+     *  until gate.json is written or a reload applies its text. */
+    private startUnsaved;
+    /** What the start's merge of the recipe couldn't do (seedOrReconcile), said with startNotice until the next start. */
+    private startMergeNote;
+    /** Whether the start's unsaved rules (startUnsaved) are a merge's that did more than add rules. */
+    private startUnsavedMerged;
     private debounceTimers;
+    private judgeFn;
+    private judgeTimeoutMs;
+    private judgeOnError;
+    /** Per rule, the batch the judge is deciding now. */
+    private judging;
+    /** 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. */
+    private judgeHeld;
+    private judgeRecords;
+    private changesJudgedContextFn;
+    /** Lifetime count of events dropped from batches waiting on the judge, at
+     *  the inference buffer's cap (MAX_INFERENCE_BUFFER per rule). */
+    private droppedJudgeEvents;
+    /** 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). */
+    private judgeFailStreak;
+    private judgeLastFailure;
     private rateLimitBuckets;
     private passiveSampleCounters;
     private rateLimitDenied;
@@ -133,15 +220,23 @@ export declare class EventGate {
     private sleepAgent;
     private disposed;
     private selfWakeTimers;
+    /** 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. */
+    private selfWakeDue;
     private privilegedUsersPath;
     private privilegedUserIds;
-    private privilegedMtime;
+    /** The privileged-users file's text as last read, whether or not it loaded;
+     *  undefined when it was missing or its last read failed. */
+    private privilegedText;
     private lastPrivilegedCheck;
     private emitTrace;
     private addMessageFn;
     private requestInferenceFn;
     private getAgentNamesFn;
     private resolveRouteChannelFn;
+    private channelShownFn?;
+    private isNewestEntryFn?;
     /** Clock injection — keeps the new rate_limit / passive_sample paths
      *  testable without monkey-patching Date.now globally. */
     private now;
@@ -153,40 +248,191 @@ export declare class EventGate {
         addMessage: (participant: string, content: Array<{
             type: 'text';
             text: string;
-        }>, metadata?: Record<string, unknown>, forAgent?: string) => unknown;
-        requestInference: (agentName: string, reason: string, source: string, provenance?: WakeProvenance) => void;
+        }>, metadata?: Record<string, unknown>, forAgent?: string, placement?: WritePlacement) => unknown;
+        /** `after`: the placement of the message the wake is for, when it has
+         *  one, so the host can drop the wake once a request that carried the
+         *  message is answered. */
+        requestInference: (agentName: string, reason: string, source: string, provenance?: WakeProvenance, after?: WritePlacement) => void;
         getAgentNames: () => string[];
         /** Optional clock — defaults to Date.now. Tests inject for deterministic time. */
         now?: () => number;
         /** Per-event timeout (ms) for the optional gate.js script. Default 50. */
         scriptTimeoutMs?: number;
+        /** The reply judge `judge` rules ask (JudgeConfig). Absent: a judge
+         *  rule's batch is delivered as a debounce's, and gate_status says so. */
+        judge?: JudgeFn;
+        /** Whether a turn of this agent changes the context the judge reads. Such
+         *  turns, and only they, hold a judge rule's batch until they end, and one
+         *  that starts while the judge decides stops the judge, whose batch is
+         *  then judged after the turn. Absent: every agent's turns do. */
+        changesJudgedContext?: (agentName: string) => boolean;
+        /** How long a judge request may take (ms). Default 20,000. */
+        judgeTimeoutMs?: number;
+        /** What a judge failure does: wake (default) or skip. */
+        judgeOnError?: 'wake' | 'skip';
         /** Map an event to the registered channel it arrived on (the host knows
-         *  how push-event origins compose into channel ids). Default: a
-         *  channel-incoming event's own channel id; nothing for push events. */
+         *  how push-event origins compose into channel ids). The gate routes a
+         *  batched wake by it, tests a policy's `match.channel` against it when
+         *  the event's own id misses, and keys `keyBy: "channelId"` counts on it.
+         *  A resolver that throws counts as returning nothing. Default: a
+         *  channel-incoming event's own channel id; nothing for push events, so
+         *  a push then matches and counts by its own id alone. */
         resolveRouteChannel?: (info: GateEventInfo) => string | undefined;
+        /** How the agent is shown a channel, its server's and its id (the
+         *  framework's ChannelRegistry.nameShown): a batched wake's summary names
+         *  each channel so, since two servers' channels can share an id. Default:
+         *  the id. */
+        channelShown?: (channel: {
+            serverId: string;
+            channelId: string;
+        }) => string;
+        /** Whether an MCPL event's own context entry is still the newest entry in
+         *  the window a batched wake's line would be written to, with nothing
+         *  waiting to be written there. A batched wake for that one message
+         *  doesn't write its line when it fires: it hands the line to the wake
+         *  (WakeProvenance.line), for a fresh start of the wake's turn to decide
+         *  (WakeLine). Absent: every batched wake writes its line, as before. */
+        isNewestEntry?: (entry: GateEntryRef) => boolean;
     });
-    private loadConfig;
+    /**
+     * Write the starting rules to gate.json, as given, when it's absent, and
+     * record them as the recipe last applied (lastRecipePath); or, when it
+     * loads, merge them into its own rule list against that record, three ways
+     * and as written (reconcileWithRecipe), and record them. A rule as the last
+     * recipe left it follows the new one, a rule edited since keeps its edit, a
+     * rule no recipe declared stays, and `default` follows the same rule. A
+     * rule gate.json holds holds its name, whether the gate reads it or leaves
+     * it out. gate.json is written before the record, so a stop between the two
+     * leaves a state the next start reads rightly: the other order would make
+     * the old recipe's rules read as edits. Nothing is recorded where gate.json
+     * isn't written as the merge asks, or a name is given twice. Where
+     * gate.json has no rules of its own and, under its default, one of them that
+     * could wake the agent can't be put in force (left out, with no name, or kept
+     * out by a rule of gate.json's of its name that the gate leaves out), or
+     * they're refused whole and that default holds events back, gate.json isn't
+     * used at this start, which runs as one without it does. Otherwise, where
+     * gate.json has no rule list to add them to, it writes nothing, and the gate
+     * runs beside it those of them it reads. Says what it did when that wasn't
+     * simply done or not needed.
+     */
+    private seedOrReconcile;
+    /**
+     * Record the starting config, as given, as the recipe last applied, after
+     * gate.json holds what the start merged (`holds` says what that is). A
+     * write that fails is said with the start: the next start merges against
+     * the record as the write left it.
+     */
+    private recordRecipe;
+    /**
+     * gate.json as it is on disk: absent; loaded; refused, when it's JSON that
+     * readConfig doesn't use; or unreadable, when it can't be read or isn't
+     * JSON (`notJson`, where it could be read). A loaded file comes with its note,
+     * which names what it holds that does nothing or is read past a problem, and
+     * a loaded or refused one with its own fields and rule list as written, for a
+     * write to edit (Listed).
+     * Reading applies nothing: whoever applies a loaded config records its text
+     * as `configText`. With `unlessUnchanged`, a file whose text is
+     * `configText` comes back `unchanged`, unparsed, since the rules in force
+     * came from it, or are what a start ran beside it or in its place.
+     */
+    private readConfigFile;
+    /**
+     * gate.json's current error, replacing the last one, and traced and logged
+     * when it's new, so an edit that doesn't load is in the log once.
+     */
+    private configUnreadable;
+    /**
+     * gate.json's error as gate_status shows it: one that keeps what the file
+     * holds out of force says what's in force instead, so it reads on its own.
+     */
+    private configErrorShown;
+    /** What the gate runs, by where its rules came from, for a text that says so: "the host's starting rules". */
+    private rulesRun;
+    /**
+     * What a policy change edits: gate.json's own fields and rule list as
+     * written, each rule as written, so a write keeps every rule it doesn't
+     * change, problems and unknown fields included, whether gate.json loads or
+     * is JSON the gate doesn't use. Over one it doesn't use, writeConfig writes
+     * only what loads, so a change is refused, naming what keeps the file out
+     * and what would bring it into force (`remedy`), unless it mends that, and
+     * the file stays as its operator wrote it. When
+     * gate.json is absent, the same of the text whose rules are in force, so a
+     * rule it leaves out keeps its name; or the rules in force, where no text
+     * is, it has no rule list, or what's in force is what a start ran beside or
+     * in place of it. A change is refused (`refused`) for a gate.json that can't
+     * be read or isn't JSON (unusableRefusal), whose rules can't be edited
+     * without writing over what it holds, and for one with no rule list a write
+     * could edit without that (a list, a "policies" that isn't one and holds
+     * something, or JSON that isn't an object): so a removal or an anchor is
+     * refused too, rather than looked for in rules that may not be what the
+     * file holds. It's refused as well for a gate.json that holds the text a
+     * start didn't use (start-without), since what the change wrote would put
+     * its rules in force in place of what the start runs.
+     */
+    private rulesForChange;
     private compilePolicies;
+    /**
+     * Clear the state of each rule `was` held in force that `next` leaves out or
+     * gives another behavior: a reload calls it before it puts `next` in force,
+     * a write after. Without this, a rule that came back, or whose tokens 100
+     * became 5 (or keyBy switched, or every 10 became 3), would run on the
+     * buckets and counters of the rule it was. A rule left out loses its stats
+     * (matchCount, lastMatchTimestamp) too; a rule kept keeps them, which are
+     * history, not live state, and one kept with the same behavior keeps all its
+     * state, its denial and fire counts included. Rules that share a name share
+     * its state, so a name keeps it only where its rules, in order, keep their
+     * behaviors. Each pending debounce batch is sent last, as its timer would
+     * have sent it, once every rule's state is cleared; one whose delivery throws
+     * is named in the log and dropped (fireDebounce), and the rest are still
+     * sent, so the write or reload that cleared it has done what it was for, its
+     * caller hears that it did, and no state is left behind.
+     */
+    private clearStateFor;
     private reloadIfChanged;
     /**
      * Add or replace (upsert) a single policy in gate.json and apply it live.
      *
-     * The raw policy is validated with the SAME `validatePolicy` used when loading
-     * gate.json — an invalid shape throws (nothing is written) and the caller
-     * surfaces it as a tool error. On success the policy is persisted to gate.json
-     * (so it survives restart and is visible to `workspace--edit _config/gate.json`)
+     * The raw policy is read with the SAME `readRule` used when loading gate.json,
+     * and since its caller is there to fix it, any problem it has throws, naming
+     * every one (nothing is written), and the caller surfaces it as a tool error,
+     * where a load reads past it (readConfig). On success the policy is persisted
+     * to gate.json (so it survives restart and is visible to `workspace--edit _config/gate.json`)
      * and the in-memory config is swapped in immediately, so the rule takes effect
-     * without waiting for the throttled mtime reload.
+     * without waiting for the throttled reload.
      *
      * The freshest on-disk config is re-read first, so a concurrent operator edit
-     * isn't clobbered. A policy with the same `name` is replaced IN PLACE when no
-     * `position` is given (order preserved); WITH a `position` it is moved there
-     * — so re-issuing a rule is also how you reposition it. New policies append
-     * by default; `'prepend'` puts one at the very front (ahead of EVERYTHING,
-     * including addressed-message wake rules — see the shadow lint), and the
-     * anchored forms `{before: name}` / `{after: name}` insert relative to an
-     * existing rule, which is almost always the safer way to order a sampler
-     * or debounce against a specific catch-all.
+     * isn't clobbered, and the change edits gate.json's own rule list by name:
+     * every rule it doesn't change is written back as it was written, problems and
+     * fields the gate doesn't read included, and so is everything else gate.json
+     * holds, such as a list of rules parked under another name, beside which a
+     * change adds a "policies" list where there's none (rulesForChange). Over a
+     * gate.json the gate doesn't use, only a change after which it loads is
+     * written, such as one replacing or removing the rule that keeps it out, and
+     * that leaves it rules in force, since it holds events back by default; any
+     * other is refused, naming what does, and the file stays as written. When
+     * gate.json is absent, the change edits the text whose rules are in force the
+     * same way, or the rules in force where there's none. A gate.json that can't
+     * be read or isn't JSON is refused (unusableRefusal), and stays as it is. A policy with the
+     * same `name` is replaced IN PLACE when no `position` is given (order
+     * preserved); WITH a `position` it is moved there — so re-issuing a rule is
+     * also how you reposition it. New policies append by default; `'prepend'` puts
+     * one at the very front (ahead of EVERYTHING, including addressed-message wake
+     * rules — see the shadow lint), and the anchored forms `{before: name}` /
+     * `{after: name}` insert relative to an existing rule, which is almost always
+     * the safer way to order a sampler or debounce against a specific catch-all.
+     * Fields of the policy the gate reads nowhere, and that aren't a slip of one
+     * it does, are left out of what's written, and named to `onIgnoredFields` once
+     * the change is written and traced. A throw from the callback is logged,
+     * and the change stands (afterChange). A field it reads at another level is a
+     * problem, like a slip.
+     *
+     * Throws, writing nothing, for an invalid policy, a placement it can't make,
+     * a gate.json that can't be read or isn't JSON, one with no rule list it
+     * could edit without writing over what it holds, one a start didn't use,
+     * which runs as one without it does, while it's unchanged, or one the gate
+     * doesn't use that the change doesn't mend or would leave with no rules in
+     * force; and throws when the write fails, which may leave gate.json
+     * part-written.
      */
     addPolicy(rawPolicy: unknown, options?: {
         position?: 'append' | 'prepend' | {
@@ -194,31 +440,63 @@ export declare class EventGate {
         } | {
             after: string;
         };
+        onIgnoredFields?: (notes: string[]) => void;
     }): GatePolicy;
     /**
      * Remove a policy by name from gate.json and clear its live state. Any pending
-     * debounce batch is delivered first (matching reloadIfChanged's removal path,
-     * so buffered events aren't silently dropped). Returns false if no policy of
-     * that name exists (nothing written). Freshest on-disk config is re-read first
-     * (see addPolicy).
+     * debounce batch is sent once the removal is written and in force, as its
+     * timer would have sent it, so buffered events aren't silently dropped
+     * (clearStateFor). Freshest on-disk config is re-read first, and every other
+     * rule is written back as it was written (see addPolicy). A name that isn't
+     * a non-empty string names no rule, so it returns false, writing nothing,
+     * whatever gate.json holds. Otherwise it throws, writing nothing, for a
+     * gate.json that can't be read or isn't JSON, one with no rule list it could
+     * edit, or one a start didn't use, as addPolicy does, and returns false,
+     * writing nothing, if no policy of that name exists, gate.json's own rules
+     * included, so one the gate leaves out can be removed by name too. For a name
+     * it holds, it throws, writing nothing, for a gate.json the gate doesn't use
+     * that the removal doesn't mend or would leave with no rules in force, and
+     * throws when the write fails, which may
+     * leave gate.json part-written; the rules in force then stay as they were,
+     * with their state.
      */
     removePolicy(name: string): boolean;
     /**
-     * List the current policy names (freshest on-disk view). Cheap helper for
+     * List the current policy names: those of a newer gate.json that loads (the
+     * freshest on-disk view), and otherwise the rules in force, which beside a
+     * gate.json with no rule list are the host's starting rules. Cheap helper for
      * tools/UX that want to show what's active without the full status payload.
      */
     listPolicyNames(): string[];
     /**
-     * Persist a config to gate.json and apply it in memory together: write the
-     * file, swap in the compiled policies, and sync `configMtime` to the new file
-     * so `reloadIfChanged` doesn't redundantly re-parse identical content. Throws
-     * if the write fails (disk/permission) — callers surface it as a tool error.
+     * Persist gate.json and apply it in memory together: `top`, its own fields,
+     * with `rules` as its rule list. Only what loads is written: a change to a
+     * gate.json the gate doesn't use, for which `remedy` is given, what would
+     * bring it into force, throws, naming that and `remedy`, and writes nothing,
+     * where the change doesn't mend what keeps it out, or where it would leave
+     * gate.json with no rules in force: such a gate.json holds events back by
+     * default, so putting it in force would hold back every event, those the
+     * rules in force wake on included. The rules in force are then what the text
+     * written reads as, as at a load, so what it still holds that the gate reads
+     * past or leaves out stays named; the text is kept as `configText`, so
+     * `reloadIfChanged` doesn't parse it again. Once the text is written and its
+     * rules are in force, a rule that was in force that it leaves out or gives
+     * another behavior loses its state (clearStateFor), last, since a pending
+     * batch it sends can't be taken back, and a write that fails leaves the
+     * rules in force with their state; a batch that can't be delivered is
+     * logged, not thrown. A write that fails throws, saying whether gate.json was
+     * changed: one that fails before writing leaves it as it was, and one that
+     * fails after its open may leave it part-written (beforeWriting). Callers
+     * surface it as a tool error.
      */
     private writeConfig;
     private compiledMatches;
     evaluate(info: GateEventInfo): GateDecision;
     private computeDecision;
-    /** Resolve the partition key for keyBy-style behaviors. */
+    /** Resolve the partition key for keyBy-style behaviors. `keyBy:
+     *  "channelId"` takes the registered id the gate resolves for the event when
+     *  it has one, as channel matching does, so a channel's push events count
+     *  with its channels/incoming messages rather than under their raw id. */
     private resolveKey;
     private applyRateLimit;
     private applyPassiveSample;
@@ -229,11 +507,12 @@ export declare class EventGate {
      */
     private applyResets;
     /**
-     * Clear ALL per-policy state (debounce timer, rate-limit buckets,
-     * passive-sample counters, denial / fire counters) for one policy.
-     * Used by reloadIfChanged when a policy is removed or its behavior
-     * params change. Stats (matchCount, lastMatchTimestamp) are preserved
-     * — those are historical and shouldn't reset on a config edit.
+     * Clear one policy's live state (rate-limit buckets, passive-sample
+     * counters, denial / fire counters) and stop its debounce timer, leaving
+     * its pending batch for fireDebounce to send, as clearStateFor does once
+     * every policy's state is cleared. It leaves stats (matchCount,
+     * lastMatchTimestamp), which are history; clearStateFor deletes a removed
+     * policy's.
      */
     private clearPolicyState;
     /**
@@ -250,6 +529,15 @@ export declare class EventGate {
      * may be stateful, and a probe must never perturb state.
      */
     probe(info: GateEventInfo): GateDecision;
+    /** The canonical synthetic events the probe table runs: chat shapes as MCPL delivers them, and a heartbeat. */
+    private probeEvents;
+    /**
+     * The rules no probe event matches, such as one scoped to an event type
+     * the probes don't model (`external-message`, how a module's messages are
+     * gated): the probe table can't show what they do, so a result that shows
+     * the table names them rather than let its rows read as their effect.
+     */
+    probeUnreached(): string[];
     /**
      * Probe a canonical set of synthetic chat/heartbeat events and report which
      * rule wins each and whether it would wake. Backs the before/after table in
@@ -257,7 +545,8 @@ export declare class EventGate {
      * must become legible (af#105; the Mythos stand-back-density incident would
      * have been visible as `dm: discord-direct-address → stand-back-density`).
      * Probes are representative shapes, not an exhaustive event space — rules
-     * keyed on specific channels/mounts may not match any probe.
+     * keyed on specific channels/mounts, or on other event types, may not match
+     * any probe; `probeUnreached` names those.
      */
     probeTable(): GateProbeRow[];
     /** Current shadow-lint findings for the live policy order. Fresh compute —
@@ -280,6 +569,61 @@ export declare class EventGate {
     private handleDebounce;
     private fireDebounce;
     private deliverEvents;
+    /** isNewestEntry for one event; a callback fault keeps the line. */
+    private newestEntry;
+    /**
+     * 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.
+     */
+    private judgeBatch;
+    /** 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. */
+    private holdForJudge;
+    /**
+     * 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.
+     */
+    private capJudgeEvents;
+    /** The rule's judge as it is now, when the rule is still a judge rule; else the one the batch was asked with. */
+    private currentJudge;
+    /**
+     * 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: string[], exceptPolicy?: string): UpcomingWake[];
+    /** A batch's event as the judge is shown it. */
+    private judgeEventSummary;
+    /**
+     * 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.
+     */
+    private finishJudging;
+    /** 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. */
+    private deliverOrBuffer;
+    private changesJudgedContext;
+    private judgedTurnRunning;
+    private stopJudging;
+    /** Send the batches held for the judge once no turn changing the context it reads runs and the host isn't quiesced. */
+    private flushJudgeHeldIfClear;
     onInferenceStarted(agentName: string): void;
     /** A turn that continues another (a budget restart, a tool-result-guard
      *  retry) holds the entry its predecessor kept for it, and takes it again
@@ -310,6 +654,9 @@ export declare class EventGate {
         bufferedEvents: number;
         droppedBufferedEvents: number;
         sleepUntil: number;
+        /** Events held for the reply judge until the turn or quiesce ends, and the judge's own drops at the cap. */
+        judgeHeldEvents: number;
+        droppedJudgeEvents: number;
     };
     /** Called internally when debounce fires during inference. */
     private bufferForInference;
@@ -334,10 +681,9 @@ export declare class EventGate {
     private armSleepWake;
     /**
      * `agentName` is gone, as a conversation fork's end or an ephemeral run's
-     * removes one: its pending self-wake is cancelled, and a sleep it set ends.
-     * The gate's sleep holds back every agent's wakes, so nobody is asleep once
-     * its agent is gone, and neither wake would reach a name that no longer
-     * exists. A sleep another agent set, or one set with no agent, stays.
+     * removes one: its pending self-wake is cancelled, rather than wake a name
+     * that no longer exists. It holds no sleep: neither can set one (the
+     * framework refuses their `sleep`).
      */
     agentGone(agentName: string): void;
     /**
@@ -372,15 +718,24 @@ export declare class EventGate {
     } | null;
     /** Author id from an event's metadata, across the discord ingest shapes. */
     private extractAuthorId;
-    /** Load the privileged-users file (bare array or { userIds: [...] }). */
     /**
      * Whether an author id is on the privileged-users list (hot-reloaded).
      * Shared by sleep bypass and tune-out wake classification (#77: wakes are
      * "mentions, gate-privileged authors, etc.").
      */
     isPrivilegedUser(authorId: string | null | undefined): boolean;
+    /**
+     * Read the privileged-users file: a list of user ids, or `{"userIds": [...]}`,
+     * each a non-empty string or a safe integer (a whole number within 2^53 - 1 of zero). An absent file
+     * means no one is privileged. A file that can't be read, isn't JSON, or
+     * holds no list leaves the list that last loaded in this process in effect
+     * (none, at startup), with its error in gate_status until the file is read
+     * again. In a list, an entry that isn't a user id is skipped, and named in
+     * the file's error, and the rest load. With `unlessUnchanged`, a file whose
+     * text is the text last read isn't parsed again.
+     */
     private loadPrivileged;
-    /** Throttled mtime-based reload of the privileged-users file. */
+    /** At most once a second, the privileged-users file read again, and loaded when its text has changed. */
     private reloadPrivilegedIfChanged;
     getToolDefinition(): ToolDefinition;
     handleToolCall(): Promise<{
@@ -389,6 +744,10 @@ export declare class EventGate {
         error?: string;
     }>;
     getStatus(): GateStatus;
+    /** gate_status's word on judge rules in force with no judge wired. */
+    private judgeUnwiredNotice;
+    /** gate_status's word on a judge that keeps failing (JUDGE_FAILING_STREAK in a row). */
+    private judgeFailingNotice;
     dispose(): void;
 }
 //# sourceMappingURL=event-gate.d.ts.map