@animalabs/agent-framework 0.26.2 → 0.27.0

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

@@ -10,9 +10,11 @@
  * and are always dispatched to modules — the gate decides whether to spend
  * inference tokens, not whether the agent should know about the event.
  */
-import { existsSync, readFileSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 import { GateScript } from './gate-script.js';
+import { canonical, duplicateName, lastRecipePath, noChanges, reconcileLine, reconcileWithRecipe } from './recipe-reconcile.js';
+import { closestNames, isNearMiss } from '../closest-names.js';
 import { MAX_TIMER_MS } from '../deadline-timer.js';
 import { safeSlice } from '../safe-slice.js';
 // ---------------------------------------------------------------------------
@@ -38,6 +40,19 @@ function parseGateJson(text) {
 const MIN_DEBOUNCE_MS = 100;
 /** Maximum debounce value (ms). */
 const MAX_DEBOUNCE_MS = 300_000;
+/** 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. */
+function checkedRecently(now, last) {
+    const elapsed = now - last;
+    return elapsed >= 0 && elapsed < RELOAD_THROTTLE_MS;
+}
+/** A read that failed because nothing is at the path. Any other failure
+ *  (EACCES on a directory, ELOOP, ENOTDIR) is a file that's there but can't
+ *  be read. */
+function isMissing(err) {
+    return err?.code === 'ENOENT';
+}
 // ---------------------------------------------------------------------------
 // Default config
 // ---------------------------------------------------------------------------
@@ -110,10 +125,35 @@ export function wakeProvenance(events) {
         ...(channelId ? { channelId } : {}),
         ...(pick.authorId ? { counterparty: `${ns}:user:${pick.authorId}` } : {}),
         ...(pick.addressed ? { addressed: true } : {}),
-        ...(pick.addressed && pick.routeChannelId ? { routeChannelId: pick.routeChannelId } : {}),
+        ...(pick.addressed && pick.routeChannelId
+            ? { routeChannelId: pick.routeChannelId, ...(pick.serverId ? { routeServerId: pick.serverId } : {}) }
+            : {}),
         at: pick.timestamp,
     };
 }
+/** A `[Gate: …]` line's reference to messages already in the window: how
+ *  many, in which channel, and how long ago the oldest arrived, as of `now`. */
+function referenceLine(count, channel, oldest, now) {
+    const age = Math.round((now - oldest) / 1000);
+    return `- ${count} message${count > 1 ? 's' : ''} in ${channel} ` +
+        `(oldest ~${age}s ago) — already shown above at arrival; this is a ` +
+        `batched wake, not new content`;
+}
+/** 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 function wakeLineText(line, now) {
+    return `[Gate: 1 event matched]\n\n${referenceLine(1, line.shown, line.at, now)}`;
+}
+/** The event's own stored entry, as the framework is asked about it. */
+function entryRef(event) {
+    return {
+        eventType: event.eventType,
+        ...(event.serverId !== undefined ? { serverId: event.serverId } : {}),
+        ...(event.channelId !== undefined ? { channelId: event.channelId } : {}),
+        ...(event.messageId !== undefined ? { messageId: event.messageId } : {}),
+        ...(event.eventId !== undefined ? { eventId: event.eventId } : {}),
+    };
+}
 /**
  * Default route-channel resolution when the host supplies none: a
  * channel-incoming event's channel id is already the registered composite id;
@@ -149,178 +189,1153 @@ function behaviorFingerprint(b) {
     return typeof b === 'string' ? b : JSON.stringify(b);
 }
 // ---------------------------------------------------------------------------
-// Config validation
+// Reading rules
 // ---------------------------------------------------------------------------
-function validateConfig(raw) {
-    if (!raw || typeof raw !== 'object') {
-        throw new Error('gate.json must be a JSON object');
+// A rule is read as written when it can be, and every problem it has is named.
+// gate.json and the host's starting rules are what a deployment already runs,
+// so a rule with a problem is read the way earlier releases read it, and no
+// event that woke the agent there goes quiet: a behavior the gate doesn't know
+// is read as "always"; a field of the wrong type, one slip from one the gate
+// reads there, or one the gate reads at another level of the rule (a match's
+// "tagsAny" beside "name"), as left out, its problem naming where it's read;
+// and a number out of range the way the starting rules ran it, but for a
+// debounce, read at its nearest bound, which can send a batch later or sooner
+// but drops no event in it, and a refill interval of 0, read as refilling at
+// once. A rule is left out only where earlier releases refused it. One that
+// skips or defers is read past a problem too, holding back what they held back:
+// left out, the events it held back would go on to the rules after it, where a
+// rate limit, a sample or a debounce could spend them and then hold back an
+// event that woke the agent before. Under a default that holds events back, a
+// file that leaves out a rule that could wake the agent isn't used, since that
+// would hold back what the rule was written to wake on; earlier releases didn't
+// use it either. A change through addPolicy, whose caller is there to fix it,
+// refuses any problem, and nothing is saved. A field name that is no slip of
+// one the gate reads there, and that it reads at no other level, changes
+// nothing, a slip of another level's field included: it loads, and a note names
+// it with the fields its place holds. In a rule, a name holding a field's whole
+// name is such a name beside that field, an extra that explains it, and a slip
+// of the field where it's given in the field's place (fieldNames); at
+// gate.json's top, where it can be a label of the file, it's such a name either
+// way. A file earlier releases loaded loads as they read it: a slip of
+// "policies", a list of rules parked under a name the gate doesn't read, a
+// rule's fields at gate.json's top and a "policies" that isn't a list each do
+// nothing, and a note names each, so where "policies" writes no rules the file
+// has none, and under "skip" or "defer" it holds back every event, as it did. A
+// "policies" holding nothing writes no rules, as one left out does. A null is a
+// field left out, and so is "", with a note: earlier releases read most fields
+// that way, and none narrows anything by them. Where they refused a rule or a
+// file for a null or a "" (a passthrough, a behavior's kind, gate.json's
+// default), it now loads without it.
+const CONFIG_FIELDS = ['default', 'policies'];
+const POLICY_FIELDS = ['name', 'match', 'behavior', 'resets', 'passthrough'];
+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 RATE_LIMIT_FIELDS = ['tokens', 'refillIntervalMs', 'keyBy'];
+const PASSIVE_SAMPLE_FIELDS = ['every', 'keyBy'];
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** A value that sets nothing: null, "", an empty list, or an object holding only such values. */
+function holdsNothing(value) {
+    return value === null || value === '' || (Array.isArray(value) && value.length === 0)
+        || (isPlainObject(value) && Object.values(value).every(holdsNothing));
+}
+/**
+ * Whether a failed write left its file as it was: writeFileSync reports a
+ * failure once it has the file open, so it may have changed it, as its write
+ * or its close.
+ */
+function beforeWriting(err) {
+    const syscall = err.syscall;
+    return syscall !== 'write' && syscall !== 'close';
+}
+/**
+ * A change's refusal where gate.json has no rule list it could edit without
+ * writing over what it holds: a list, JSON that isn't an object, or a
+ * "policies" that isn't a list and holds something. `runs` is what the gate
+ * runs meanwhile (rulesRun).
+ */
+function noListRefusal(noList, runs) {
+    return `${noList}, so it has no list of rules a change could edit without writing over what it holds, and nothing `
+        + `was saved. Meanwhile the gate runs ${runs}. Until gate.json is an object whose "policies" is a list holding its `
+        + 'rules, a change is refused the same way.';
+}
+/**
+ * A change's refusal where gate.json is there but couldn't be used as a file
+ * a change edits: it couldn't be read, or it isn't JSON (`notJson`). Nothing is
+ * written over it, so what it holds, often an operator's unfinished edit, stays
+ * as it is. `runs` is what the gate runs meanwhile (rulesRun).
+ */
+function unusableRefusal(unusable, runs) {
+    if (!unusable.notJson) {
+        return `gate.json couldn't be read (${unusable.error}), so a change can't edit it, and nothing was written over it. `
+            + `Meanwhile the gate runs ${runs}. Whoever runs this host can make gate.json readable; until then, a change is `
+            + 'refused the same way.';
+    }
+    return `gate.json isn't JSON the gate can read (${unusable.error}), so a change can't edit its rules without writing `
+        + `over what it holds, and nothing was saved. Meanwhile the gate runs ${runs}. Until gate.json is JSON, a change is `
+        + 'refused the same way.';
+}
+/**
+ * A change's refusal at a start that didn't use gate.json, which has no rules
+ * of its own (start-without): a change puts the rules gate.json then holds in
+ * force, so it would take out of force what the start runs in its place.
+ * `runs` is what the gate runs meanwhile (rulesRun); gate_status's entries
+ * (notUsedClause, describeStart) say which rules keep gate.json out of use
+ * and each fix.
+ */
+function notUsedRefusal(runs) {
+    return "gate.json isn't used at this start, which runs as one without it does, and a change would put gate.json's rules in "
+        + `force in place of what that runs, so nothing was saved. Meanwhile the gate runs ${runs}. gate_status says what keeps `
+        + 'gate.json out of use and what would put it in use, such as giving it rules under "policies", or fixing the starting '
+        + 'rules, which whoever runs this host can do, for the next start; until then, a change is refused the same way.';
+}
+/**
+ * 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 function shownValue(value) {
+    if (value === undefined)
+        return 'missing';
+    // JSON writes NaN and the infinities as null.
+    if (typeof value === 'number' && !Number.isFinite(value))
+        return String(value);
+    let json;
+    try {
+        json = JSON.stringify(value) ?? String(value);
     }
-    const obj = raw;
-    const defaultBehavior = obj.default ?? 'always';
-    if (defaultBehavior !== 'always' && defaultBehavior !== 'defer' && defaultBehavior !== 'skip') {
-        throw new Error(`gate.json "default" must be "always", "defer", or "skip", got: ${defaultBehavior}`);
+    catch {
+        json = String(value);
     }
-    const policies = [];
-    if (Array.isArray(obj.policies)) {
-        for (const p of obj.policies) {
-            policies.push(validatePolicy(p));
+    return json.length > 80 ? `${safeSlice(json, 0, 77)}...` : json;
+}
+/** Entries of a list as a message quotes them. */
+function shownValues(values) {
+    return values.map(shownValue).join(', ');
+}
+/** `a`, `a and b`, `a, b and c` (or "or"). */
+function joinedList(items, joiner = 'and') {
+    return items.length < 2 ? items.join('') : `${items.slice(0, -1).join(', ')} ${joiner} ${items[items.length - 1]}`;
+}
+/** `"a"`, `"a" and "b"`, `"a", "b" and "c"` (or "or"). */
+function quotedList(names, joiner = 'and') {
+    return joinedList(names.map((n) => `"${n}"`), joiner);
+}
+/** 1st, 2nd, 3rd, 4th, 11th, 21st. */
+function ordinal(n) {
+    const tens = n % 100;
+    const suffix = tens >= 11 && tens <= 13 ? 'th' : (['th', 'st', 'nd', 'rd'][n % 10] ?? 'th');
+    return `${n}${suffix}`;
+}
+/** A message part as one sentence, for joining several. */
+function sentence(text) {
+    return /[.?!]$/.test(text) ? text : `${text}.`;
+}
+/** How a note speaks of what it checks: a rule's fields, or a tool's parameters. */
+const RULE_FIELDS_TERMS = { unread: "which the gate doesn't read", listed: 'Its fields are' };
+const TOOL_PARAMETERS_TERMS = { unread: "which it doesn't take", listed: 'Its parameters are' };
+/**
+ * An object's field names that the gate doesn't read in its place: slips of
+ * one it does, and the rest. A name is a slip of each field isNearMiss finds
+ * it close to and, where `held`, of each whose whole name it holds, ignoring
+ * case, that the object doesn't give: sent in that field's place, it's the
+ * field under another name (`matchTags` with no `match`), where beside it,
+ * it's an extra. The object is one withoutEmpty read, so a field given as
+ * null or "" isn't given.
+ */
+function fieldNames(obj, fields, held = true) {
+    const slips = [];
+    const unread = [];
+    for (const key of Object.keys(obj)) {
+        if (obj[key] === undefined || fields.includes(key))
+            continue;
+        // Every field the gate reads has four characters or more, so holding one
+        // needs no length of its own here. A field of two characters or fewer
+        // would be held by names that have nothing to do with it ("valid" holds
+        // "id"), and holding it would need the three characters isNearMiss asks
+        // of a part.
+        const holds = (field) => key.toLowerCase().includes(field.toLowerCase());
+        const near = fields.filter((field) => isNearMiss(key, field) || (held && !Object.hasOwn(obj, field) && holds(field)));
+        if (near.length === 0) {
+            unread.push(key);
+            continue;
         }
+        // closestNames keeps every name decided on above, in its order.
+        slips.push({ key, meant: closestNames(key, near, near.length) });
     }
-    return { policies, default: defaultBehavior };
+    return { slips, unread };
+}
+/** `"tags" (did you mean "tagsAny", "tagsAll" or "tagsNone"?)` */
+function slipShown(slip) {
+    return `"${slip.key}" (did you mean ${quotedList(slip.meant, 'or')}?)`;
 }
-function validatePolicy(raw) {
-    if (!raw || typeof raw !== 'object') {
-        throw new Error('Each gate policy must be an object');
+/**
+ * An object's names that do nothing in its place, split into those that are
+ * fields read elsewhere, grouped by where (`homesOf`), and the rest.
+ */
+function placedElsewhere(unread, homesOf) {
+    const misplaced = [];
+    const rest = [];
+    for (const key of unread) {
+        const homes = homesOf(key);
+        if (homes.length === 0) {
+            rest.push(key);
+            continue;
+        }
+        const same = misplaced.find((m) => m.homes.join() === homes.join());
+        if (same)
+            same.keys.push(key);
+        else
+            misplaced.push({ keys: [key], homes });
     }
-    const obj = raw;
-    if (typeof obj.name !== 'string' || !obj.name) {
-        throw new Error('Gate policy must have a "name" string');
+    return { misplaced, rest };
+}
+/** `"tagsAny", a field of "match"`; `"tagsAny" and "source", fields of "match"` */
+function misplacedShown(m) {
+    return `${quotedList(m.keys)}, ${m.keys.length === 1 ? 'a field' : 'fields'} of ${joinedList(m.homes)}`;
+}
+/**
+ * The levels of a gate.json the gate reads fields at, each as a message names
+ * it, `file` naming the file itself.
+ */
+function fieldLevels(file) {
+    return [
+        { name: file, fields: CONFIG_FIELDS },
+        { name: 'a rule', fields: POLICY_FIELDS },
+        { name: '"match"', fields: MATCH_FIELDS },
+        { name: '"match.filter"', fields: FILTER_FIELDS },
+        { name: '"behavior"', fields: BEHAVIOR_KINDS },
+        { name: '"behavior.rate_limit"', fields: RATE_LIMIT_FIELDS },
+        { name: '"behavior.passive_sample"', fields: PASSIVE_SAMPLE_FIELDS },
+    ];
+}
+/** Where a name is a field the gate reads, at a level other than the one whose fields are `here`. */
+function homesOf(file, here) {
+    return (key) => fieldLevels(file)
+        .filter((level) => level.fields !== here && level.fields.includes(key))
+        .map((level) => level.name);
+}
+/** Where each field of an object schema's nested objects is taken: `tagsAny` in "match". */
+function nestedFields(properties, path = '') {
+    const homes = new Map();
+    const add = (field, where) => homes.set(field, [...(homes.get(field) ?? []), where]);
+    for (const [name, schema] of Object.entries(properties)) {
+        if (!isPlainObject(schema) || !isPlainObject(schema.properties))
+            continue;
+        const where = path ? `${path}.${name}` : name;
+        for (const field of Object.keys(schema.properties))
+            add(field, `"${where}"`);
+        for (const [field, inner] of nestedFields(schema.properties, where))
+            for (const at of inner)
+                add(field, at);
+    }
+    return homes;
+}
+/** A note naming the fields an object has that do nothing in its place, with the fields that do. */
+function noteUnread(where, unread, fields, notes, terms = RULE_FIELDS_TERMS) {
+    if (unread.length === 0)
+        return;
+    notes.push(`${where} has ${quotedList(unread)}, ${terms.unread}, so ${unread.length === 1 ? 'it does' : 'they do'} `
+        + `nothing. ${terms.listed} ${quotedList(fields)}.`);
+}
+/**
+ * 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 function checkToolInput(tool, input, properties, notes, means = {}) {
+    const params = Object.keys(properties);
+    const given = withoutEmpty(tool, input, notes, means);
+    const { slips, unread } = fieldNames(given, params);
+    const homes = nestedFields(properties);
+    const { misplaced, rest } = placedElsewhere(unread, (key) => homes.get(key) ?? []);
+    if (slips.length > 0 || misplaced.length > 0) {
+        // Every name it doesn't take is named, so the call that follows the refusal doesn't count on one.
+        const has = [
+            ...(slips.length > 0 ? [`${slips.map(slipShown).join(' and ')}, ${TOOL_PARAMETERS_TERMS.unread}`] : []),
+            ...misplaced.map((m) => `${misplacedShown(m)}, ${TOOL_PARAMETERS_TERMS.unread} here`),
+            ...(rest.length > 0 ? [`${quotedList(rest)}, ${TOOL_PARAMETERS_TERMS.unread}`] : []),
+        ];
+        // Where a field has one home, show it there, as the call would give it. A
+        // value shownValue cuts short isn't one the call could give, so then the
+        // parameter is named alone.
+        const moves = misplaced.filter((m) => m.homes.length === 1).map((m) => {
+            const it = m.keys.length === 1 ? 'it' : 'them';
+            const shown = m.keys.map((key) => [key, shownValue(given[key])]);
+            return shown.every(([key, value]) => value === JSON.stringify(given[key]))
+                ? `Put ${it} in ${m.homes[0]}: {${shown.map(([key, value]) => `${JSON.stringify(key)}: ${value}`).join(', ')}}.`
+                : `Put ${it} in ${m.homes[0]}.`;
+        });
+        throw new Error(`${tool} has ${has.join(', and ')}, so nothing was saved. ${moves.map((move) => `${move} `).join('')}`
+            + `${TOOL_PARAMETERS_TERMS.listed} ${quotedList(params)}.`);
     }
-    // Validate behavior
-    let behavior;
-    if (obj.behavior === 'always' || obj.behavior === 'defer' || obj.behavior === 'skip') {
-        behavior = obj.behavior;
+    noteUnread(tool, rest, params, notes, TOOL_PARAMETERS_TERMS);
+    return given;
+}
+/**
+ * An object's fields as the gate reads them: a null or "" is a field left out,
+ * and a note names each "", with what leaving it out does where that's more
+ * than setting no constraint (`means`, by field). Every other field stays an
+ * own field of the copy, "__proto__" included, which JSON gives as one: set by
+ * assignment, it would make its value the copy's prototype, whose fields the
+ * gate would then read as the object's own.
+ */
+function withoutEmpty(where, obj, notes, means = {}) {
+    const kept = [];
+    const empty = [];
+    for (const [key, value] of Object.entries(obj)) {
+        if (value === null || value === undefined)
+            continue;
+        if (value === '')
+            empty.push(key);
+        else
+            kept.push([key, value]);
+    }
+    const out = Object.fromEntries(kept);
+    if (empty.length > 0) {
+        const meant = empty.flatMap((key) => {
+            // An own field only: a name such as "constructor" would find Object.prototype's.
+            const what = Object.hasOwn(means, key) ? means[key] : undefined;
+            return what ? [what] : [];
+        });
+        notes.push(`${where} has ${quotedList(empty)} as "", so ${empty.length === 1 ? "it's" : "they're"} left out`
+            + `${meant.length > 0 ? `: ${meant.join(', and ')}` : ''}.`);
     }
-    else if (obj.behavior && typeof obj.behavior === 'object') {
-        const b = obj.behavior;
-        if ('debounce' in b) {
-            if (typeof b.debounce !== 'number' || b.debounce <= 0) {
-                throw new Error(`Policy "${obj.name}": debounce must be a positive number`);
-            }
-            if (b.debounce < MIN_DEBOUNCE_MS) {
-                throw new Error(`Policy "${obj.name}": debounce must be >= ${MIN_DEBOUNCE_MS}ms, got ${b.debounce}`);
-            }
-            if (b.debounce > MAX_DEBOUNCE_MS) {
-                throw new Error(`Policy "${obj.name}": debounce must be <= ${MAX_DEBOUNCE_MS}ms, got ${b.debounce}`);
-            }
-            behavior = { debounce: b.debounce };
+    return out;
+}
+/** What leaving out a rule's field does, where that's more than setting no constraint. */
+const RULE_LEFT_OUT = { behavior: 'a rule without one has the behavior "always"', match: 'a rule without one matches every event' };
+/** The same for gate.json's own fields, under the default it then has. */
+function configLeftOut(defaultBehavior) {
+    return {
+        default: 'its default is "always"',
+        policies: defaultBehavior === 'skip' || defaultBehavior === 'defer'
+            ? `it has no rules, so under its default, "${defaultBehavior}", every event is held back`
+            : 'it has no rules, so every event gets the default, "always"',
+    };
+}
+/**
+ * A rule's notes, ending with what a match that narrows nothing does. A
+ * refusal says it of the rule read without what's wrong in its match, as
+ * earlier releases read it, since that's why what's wrong there matters.
+ */
+function notesOf(reading, refused = false) {
+    if (!reading.matchesAll)
+        return reading.notes;
+    return [...reading.notes, refused
+            ? "Read without what's wrong in its match, as earlier releases read it, the rule would match every event."
+            : `${reading.where}: nothing left in match narrows the rule, so it matches every event.`];
+}
+/** How a slip is read: as a field left out, which does nothing. */
+const SLIP_READ = 'so it does nothing';
+/** How a field of the wrong type is read: as one left out. */
+const DROPPED = 'so the rule is read without it';
+/**
+ * An object's field names, at `level` of the rule (such as "match"): a slip of
+ * a field is a problem, read as the field left out, and so is a field the gate
+ * reads at another level, named with where that is (`misplacedReadOf` says
+ * how the rule then reads, where that's more than the field doing nothing);
+ * any other name the gate doesn't read is noted.
+ */
+function readFieldNames(r, level, obj, fields, readOf = () => SLIP_READ, misplacedReadOf = () => undefined) {
+    const { slips, unread } = fieldNames(obj, fields);
+    const { misplaced, rest } = placedElsewhere(unread, homesOf(r.file, fields));
+    noteUnread(level ? `${r.where}: ${level}` : r.where, rest, fields, r.notes);
+    for (const slip of slips) {
+        r.problems.push({ text: `${level ?? 'it'} has ${slipShown(slip)}, which the gate doesn't read`, read: readOf(slip) });
+    }
+    for (const m of misplaced) {
+        r.problems.push({
+            text: `${level ?? 'it'} has ${misplacedShown(m)}, which the gate doesn't read here`,
+            read: misplacedReadOf(m) ?? (m.keys.length === 1 ? SLIP_READ : 'so they do nothing'),
+        });
+    }
+}
+/** "so that entry is dropped", "so those entries are dropped". */
+function droppedEntries(count) {
+    return count === 1 ? 'so that entry is dropped' : 'so those entries are dropped';
+}
+/**
+ * A rule, read as written, or past each problem it has. `unnamed` names a rule
+ * without a name in messages, and `file` the file it's in.
+ */
+function readRule(raw, unnamed, file = 'gate.json') {
+    if (!isPlainObject(raw)) {
+        return {
+            where: unnamed,
+            problems: [{ text: `it's ${shownValue(raw)}, where a rule is an object, such as {"name": "my-rule", "behavior": "always"}` }],
+            notes: [],
+            quiet: false,
+        };
+    }
+    const name = nameOf(raw);
+    const r = { where: name ? `Policy "${name}"` : unnamed, file, problems: [], notes: [] };
+    const obj = withoutEmpty(r.where, raw, r.notes, RULE_LEFT_OUT);
+    // Field names first, so a slip of one is named before what its absence does.
+    readFieldNames(r, null, obj, POLICY_FIELDS, (slip) => {
+        if (slip.meant.includes('behavior') && obj.behavior === undefined)
+            return 'so the rule\'s behavior is "always"';
+        if (slip.meant.includes('match') && obj.match === undefined)
+            return 'so the rule matches every event';
+        return SLIP_READ;
+    }, (m) => {
+        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))) {
+            return 'so the rule\'s behavior is "always"';
+        }
+        return undefined;
+    });
+    if (!name) {
+        r.problems.push({
+            text: obj.name === undefined ? 'it has no "name"' : `name is ${shownValue(obj.name)}, where a non-empty string is needed`,
+        });
+    }
+    const { behavior, kind } = readBehavior(r, obj.behavior);
+    const match = readMatch(r, obj.match);
+    const resets = readResets(r, obj.resets);
+    const passthrough = readPassthrough(r, obj.passthrough, behavior, kind);
+    const reading = {
+        where: r.where, problems: r.problems, notes: r.notes, quiet: kind === 'skip' || kind === 'defer' || r.noTokens === true,
+    };
+    if (name && behavior && r.problems.every((p) => p.read !== undefined)) {
+        const policy = { name, match, behavior };
+        if (resets)
+            policy.resets = resets;
+        if (passthrough)
+            policy.passthrough = true;
+        reading.policy = policy;
+        if (r.matchesAll)
+            reading.matchesAll = true;
+    }
+    return reading;
+}
+const BEHAVIORS_NEEDED = '"always", "defer" or "skip", or an object holding one of "debounce", "rate_limit" and "passive_sample"';
+/**
+ * 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
+ * object was read as "always", a rule that wakes on every event it matches,
+ * 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
+ * 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.
+ */
+function readBehavior(r, value) {
+    if (value === undefined)
+        return { behavior: 'always', kind: 'always' };
+    if (value === 'always' || value === 'defer' || value === 'skip')
+        return { behavior: value, kind: value };
+    if (!isPlainObject(value)) {
+        if (Array.isArray(value)) {
+            r.problems.push({ text: `behavior is ${shownValue(value)}, where ${BEHAVIORS_NEEDED} is needed` });
+            return {};
+        }
+        r.problems.push({ text: `behavior is ${shownValue(value)}, where ${BEHAVIORS_NEEDED} is needed`, read: 'so it\'s read as "always"' });
+        return { behavior: 'always', kind: 'always' };
+    }
+    const b = withoutEmpty(`${r.where}: behavior`, value, r.notes);
+    readFieldNames(r, 'behavior', b, BEHAVIOR_KINDS);
+    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"' });
+        return {};
+    }
+    if (kinds.length > 1) {
+        r.problems.push({ text: `behavior holds ${quotedList(kinds)}, and a rule has one behavior`, read: `so only its "${kind}" is read` });
+    }
+    const behavior = READ_KIND[kind](r, b[kind]);
+    for (const other of kinds.slice(1)) {
+        const unread = { where: r.where, file: r.file, problems: [], notes: [] };
+        READ_KIND[other](unread, b[other]);
+        for (const p of unread.problems)
+            r.problems.push({ text: p.text, read: `which goes unread with the rest of "${other}"` });
+    }
+    return { behavior, kind };
+}
+/**
+ * A debounce: a number of milliseconds. One out of the gate's range is read
+ * at its nearest bound. Earlier releases refused it in gate.json and ran it
+ * as written in the starting rules, where one over 2,147,483,647 ms ran after
+ * 1 ms, the most a timer takes; read at the bound, a batch goes out later or
+ * sooner than it did there, and every event in it is still delivered.
+ */
+function readDebounce(r, ms) {
+    if (typeof ms !== 'number' || !Number.isFinite(ms)) {
+        r.problems.push({ text: `behavior.debounce is ${shownValue(ms)}, where a number of milliseconds is needed, such as 60000` });
+        return undefined;
+    }
+    if (ms < MIN_DEBOUNCE_MS) {
+        r.problems.push({
+            text: `behavior.debounce is ${ms} ms, under the ${MIN_DEBOUNCE_MS} ms minimum`, read: `so it's read as ${MIN_DEBOUNCE_MS} ms`,
+        });
+        return { debounce: MIN_DEBOUNCE_MS };
+    }
+    if (ms > MAX_DEBOUNCE_MS) {
+        r.problems.push({
+            text: `behavior.debounce is ${ms} ms, over the ${MAX_DEBOUNCE_MS} ms maximum`, read: `so it's read as ${MAX_DEBOUNCE_MS} ms`,
+        });
+        return { debounce: MAX_DEBOUNCE_MS };
+    }
+    return { debounce: ms };
+}
+/**
+ * A rate limit. A refill interval under 0 ran as a bucket that never refills,
+ * waking on its first tokens and then on none of what the rule matched, and
+ * is read so. One of 0 refilled the bucket once and then never, its clock left
+ * at NaN; it's read as refilling at once, every time, so the rule limits
+ * nothing, which holds back nothing it woke the agent on (applyRateLimit). A
+ * rule whose tokens aren't a positive number is left out, as earlier releases'
+ * check refused it. Tokens that are a number not over 0, which ran unchecked
+ * from the starting rules, woke the agent on nothing the rule matched, so that
+ * rule is quiet (noTokens): leaving it out holds back nothing it was written
+ * to wake on, though what it matches goes on to the rules after it, as for any
+ * rule left out.
+ */
+function readRateLimit(r, value) {
+    if (!isPlainObject(value)) {
+        r.problems.push({
+            text: `behavior.rate_limit is ${shownValue(value)}, where an object is needed, such as {"tokens": 3, "refillIntervalMs": 60000}`,
+        });
+        return undefined;
+    }
+    const conf = withoutEmpty(`${r.where}: behavior.rate_limit`, value, r.notes, { keyBy: 'every event the rule matches shares one bucket' });
+    readFieldNames(r, 'behavior.rate_limit', conf, RATE_LIMIT_FIELDS);
+    const tokens = conf.tokens;
+    const refill = conf.refillIntervalMs;
+    const tokensUsable = typeof tokens === 'number' && Number.isFinite(tokens) && tokens > 0;
+    if (typeof tokens === 'number' && !(tokens > 0))
+        r.noTokens = true;
+    if (!tokensUsable) {
+        r.problems.push({ text: `behavior.rate_limit.tokens is ${shownValue(tokens)}, where a positive number is needed` });
+    }
+    const refillUsable = typeof refill === 'number' && Number.isFinite(refill);
+    if (!refillUsable) {
+        r.problems.push({
+            text: `behavior.rate_limit.refillIntervalMs is ${shownValue(refill)}, where a positive number of milliseconds is needed`,
+        });
+    }
+    else if (refill <= 0) {
+        r.problems.push({
+            text: `behavior.rate_limit.refillIntervalMs is ${refill}, where a positive number of milliseconds is needed`,
+            read: refill === 0
+                ? 'so its tokens refill at once, and it limits nothing it matches'
+                : "so its tokens never refill, and once they're spent it wakes the agent on nothing it matches",
+        });
+    }
+    const keyBy = readKeyBy(r, 'rate_limit', conf.keyBy);
+    if (!tokensUsable || !refillUsable)
+        return undefined;
+    const out = { tokens, refillIntervalMs: refill };
+    if (keyBy !== undefined)
+        out.keyBy = keyBy;
+    return { rate_limit: out };
+}
+/**
+ * A sample. A step at or under 0 sampled every event, as 1 does, and a
+ * fraction its next whole number, since the count was compared with it, so
+ * each is read that way.
+ */
+function readPassiveSample(r, value) {
+    if (!isPlainObject(value)) {
+        r.problems.push({ text: `behavior.passive_sample is ${shownValue(value)}, where an object is needed, such as {"every": 10}` });
+        return undefined;
+    }
+    const conf = withoutEmpty(`${r.where}: behavior.passive_sample`, value, r.notes, { keyBy: 'every event the rule matches shares one count' });
+    readFieldNames(r, 'behavior.passive_sample', conf, PASSIVE_SAMPLE_FIELDS);
+    const given = conf.every;
+    let every;
+    if (typeof given !== 'number' || !Number.isFinite(given)) {
+        r.problems.push({ text: `behavior.passive_sample.every is ${shownValue(given)}, where a whole number of 1 or more is needed` });
+    }
+    else if (Number.isInteger(given) && given > 0) {
+        every = given;
+    }
+    else {
+        every = given <= 0 ? 1 : Math.ceil(given);
+        r.problems.push({
+            text: `behavior.passive_sample.every is ${given}, ${given <= 0 ? 'under 1' : 'not a whole number'}`,
+            read: `so it's read as ${every}`,
+        });
+    }
+    const keyBy = readKeyBy(r, 'passive_sample', conf.keyBy);
+    if (every === undefined)
+        return undefined;
+    const out = { every };
+    if (keyBy !== undefined)
+        out.keyBy = keyBy;
+    return { passive_sample: out };
+}
+/** How each kind of behavior object is read. */
+const READ_KIND = {
+    debounce: readDebounce,
+    rate_limit: readRateLimit,
+    passive_sample: readPassiveSample,
+};
+/** A timing kind's keyBy: a field name. One of another type was read as none. */
+function readKeyBy(r, kind, value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string')
+        return value;
+    r.problems.push({
+        text: `behavior.${kind}.keyBy is ${shownValue(value)}, where a field name is needed, such as "channelId"`,
+        read: `so it does nothing, and every event the rule matches shares one ${kind === 'rate_limit' ? 'bucket' : 'count'}`,
+    });
+    return undefined;
+}
+/**
+ * A rule's match: every field optional, and one left out matches anything. A
+ * field of the wrong type, or an entry of one in a list, was dropped, which
+ * widened the rule, and is read so; an empty entry in a list, dropped, but for
+ * one in `scope`, which was kept and narrows the rule, since no event's type is
+ * "". A match that isn't an object matched every event, and so does one left
+ * with nothing that narrows it, which readRule notes, for a rule it can read,
+ * where something in the match was named: dropped, left out or unread.
+ */
+function readMatch(r, value) {
+    const match = {};
+    if (value === undefined)
+        return match;
+    if (!isPlainObject(value)) {
+        r.problems.push({
+            text: `match is ${shownValue(value)}, where an object is needed, such as {"source": "discord"}`,
+            read: 'so the rule matches every event',
+        });
+        return match;
+    }
+    const named = r.problems.length + r.notes.length;
+    const m = withoutEmpty(`${r.where}: match`, value, r.notes);
+    readFieldNames(r, 'match', m, MATCH_FIELDS);
+    if (m.scope !== undefined) {
+        if (!Array.isArray(m.scope)) {
+            r.problems.push({
+                text: `match.scope is ${shownValue(m.scope)}, where a list of event types is needed, such as ["mcpl:channel-incoming"]`,
+                read: 'so the rule matches every type of event',
+            });
         }
-        else if ('rate_limit' in b) {
-            const rl = b.rate_limit;
-            if (!rl || typeof rl !== 'object') {
-                throw new Error(`Policy "${obj.name}": rate_limit must be an object`);
+        else {
+            const types = m.scope.filter((s) => typeof s === 'string');
+            const dropped = m.scope.filter((s) => typeof s !== 'string');
+            if (dropped.length > 0) {
+                r.problems.push({
+                    text: `match.scope holds ${shownValues(dropped)}, which ${dropped.length === 1 ? "isn't an event type" : "aren't event types"}`,
+                    read: types.length > 0 ? droppedEntries(dropped.length) : `${droppedEntries(dropped.length)}, and the rule matches every type of event`,
+                });
             }
-            const conf = rl;
-            if (typeof conf.tokens !== 'number' || !Number.isFinite(conf.tokens) || conf.tokens <= 0) {
-                throw new Error(`Policy "${obj.name}": rate_limit.tokens must be a positive number`);
+            if (types.includes('')) {
+                r.problems.push({
+                    text: 'match.scope holds "", and no event\'s type is ""',
+                    read: types.every((t) => t === '') ? 'so the rule matches no event' : 'so that entry matches no event',
+                    narrows: true,
+                });
             }
-            if (typeof conf.refillIntervalMs !== 'number' || !Number.isFinite(conf.refillIntervalMs) || conf.refillIntervalMs <= 0) {
-                throw new Error(`Policy "${obj.name}": rate_limit.refillIntervalMs must be a positive number`);
+            match.scope = types;
+        }
+    }
+    for (const [field, example] of [
+        ['source', '"discord"'], ['channel', '"discord:*:12345"'], ['mount', '"project"'], ['pathGlob', '"notes/*.md"'],
+    ]) {
+        const given = m[field];
+        if (given === undefined)
+            continue;
+        if (typeof given === 'string')
+            match[field] = given;
+        else
+            r.problems.push({ text: `match.${field} is ${shownValue(given)}, where a string is needed, such as ${example}`, read: DROPPED });
+    }
+    for (const [field, example] of [
+        ['metadataTrue', '["mentioned"]'], ['tagsAny', '["chat:ambient"]'], ['tagsAll', '["chat:ambient"]'], ['tagsNone', '["chat:ambient"]'],
+    ]) {
+        const given = m[field];
+        if (given === undefined)
+            continue;
+        if (!Array.isArray(given)) {
+            r.problems.push({
+                text: `match.${field} is ${shownValue(given)}, where a list of non-empty strings is needed, such as ${example}`, read: DROPPED,
+            });
+            continue;
+        }
+        const kept = given.filter((s) => typeof s === 'string' && s.length > 0);
+        const dropped = given.filter((s) => typeof s !== 'string' || s.length === 0);
+        if (dropped.length > 0) {
+            r.problems.push({
+                text: `match.${field} holds ${shownValues(dropped)}, where each entry is a non-empty string`,
+                read: kept.length > 0 ? droppedEntries(dropped.length) : `${droppedEntries(dropped.length)}, and with none left the list narrows nothing`,
+            });
+        }
+        if (kept.length > 0)
+            match[field] = kept;
+    }
+    if (m.filter !== undefined) {
+        if (!isPlainObject(m.filter)) {
+            r.problems.push({
+                text: `match.filter is ${shownValue(m.filter)}, where an object is needed, such as {"type": "text", "pattern": "release"}`,
+                read: DROPPED,
+            });
+        }
+        else {
+            // An empty pattern matches every event's content, so a filter with one
+            // narrows nothing, as before, and it's left out, its other problems named.
+            const emptyPattern = m.filter.pattern === '';
+            const f = withoutEmpty(`${r.where}: match.filter`, emptyPattern ? { ...m.filter, pattern: undefined } : m.filter, r.notes);
+            readFieldNames(r, 'match.filter', f, FILTER_FIELDS);
+            const without = 'so the rule is read without its filter';
+            const type = f.type === 'text' || f.type === 'regex' ? f.type : undefined;
+            if (type === undefined) {
+                r.problems.push({ text: `match.filter.type is ${shownValue(f.type)}, where "text" or "regex" is needed`, read: without });
             }
-            const out = {
-                tokens: conf.tokens,
-                refillIntervalMs: conf.refillIntervalMs,
-            };
-            if (typeof conf.keyBy === 'string' && conf.keyBy.length > 0) {
-                out.keyBy = conf.keyBy;
+            if (emptyPattern) {
+                r.notes.push(`${r.where}: match.filter's pattern is "", so the filter narrows nothing, and it's left out.`);
             }
-            behavior = { rate_limit: out };
-        }
-        else if ('passive_sample' in b) {
-            const ps = b.passive_sample;
-            if (!ps || typeof ps !== 'object') {
-                throw new Error(`Policy "${obj.name}": passive_sample must be an object`);
+            else if (typeof f.pattern !== 'string') {
+                r.problems.push({
+                    text: `match.filter.pattern is ${shownValue(f.pattern)}, where the text or regular expression to look for is needed`,
+                    read: without,
+                });
             }
-            const conf = ps;
-            if (typeof conf.every !== 'number' || !Number.isInteger(conf.every) || conf.every <= 0) {
-                throw new Error(`Policy "${obj.name}": passive_sample.every must be a positive integer`);
+            else if (type === 'text') {
+                match.filter = { type, pattern: f.pattern };
             }
-            const out = { every: conf.every };
-            if (typeof conf.keyBy === 'string' && conf.keyBy.length > 0) {
-                out.keyBy = conf.keyBy;
+            else if (type === 'regex') {
+                try {
+                    new RegExp(f.pattern);
+                    match.filter = { type, pattern: f.pattern };
+                }
+                catch (e) {
+                    r.problems.push({ text: `match.filter.pattern isn't a regular expression the gate can read (${errorText(e)})` });
+                }
             }
-            behavior = { passive_sample: out };
-        }
-        else {
-            throw new Error(`Policy "${obj.name}": unknown behavior — expected always | defer | skip | { debounce } | { rate_limit } | { passive_sample }`);
         }
     }
-    else {
-        behavior = 'always';
+    // Left with nothing that narrows it once something in it was named, it
+    // matches every event. Empty lists and nulls alone always meant no
+    // constraint, and name nothing.
+    const narrows = Object.entries(match).some(([field, v]) => !(field === 'scope' && Array.isArray(v) && v.length === 0));
+    if (!narrows && r.problems.length + r.notes.length > named)
+        r.matchesAll = true;
+    return match;
+}
+/** A rule's resets: names of rules whose state it clears when it fires. An entry that isn't a name was dropped. */
+function readResets(r, value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        r.problems.push({
+            text: `resets is ${shownValue(value)}, where a list of rule names is needed, such as ["other-rule"]`,
+            read: 'so the rule resets no other',
+        });
+        return undefined;
     }
-    // Validate match (lenient — missing fields mean "match all")
-    const match = {};
-    if (obj.match && typeof obj.match === 'object') {
-        const m = obj.match;
-        if (Array.isArray(m.scope))
-            match.scope = m.scope.filter(s => typeof s === 'string');
-        if (typeof m.source === 'string')
-            match.source = m.source;
-        if (typeof m.channel === 'string')
-            match.channel = m.channel;
-        if (typeof m.mount === 'string')
-            match.mount = m.mount;
-        if (typeof m.pathGlob === 'string')
-            match.pathGlob = m.pathGlob;
-        if (Array.isArray(m.metadataTrue)) {
-            const fields = m.metadataTrue.filter((s) => typeof s === 'string' && s.length > 0);
-            if (fields.length > 0)
-                match.metadataTrue = fields;
-        }
-        const tagList = (v) => {
-            if (!Array.isArray(v))
-                return undefined;
-            const out = v.filter((s) => typeof s === 'string' && s.length > 0);
-            return out.length > 0 ? out : undefined;
+    // Unknown names are ignored at runtime, so reload races don't blow up.
+    const names = value.filter((s) => typeof s === 'string' && s.length > 0);
+    const dropped = value.filter((s) => typeof s !== 'string' || s.length === 0);
+    if (dropped.length > 0) {
+        r.problems.push({
+            text: `resets holds ${shownValues(dropped)}, where each entry is a rule's name`,
+            read: names.length > 0 ? droppedEntries(dropped.length) : `${droppedEntries(dropped.length)}, and the rule resets no other`,
+        });
+    }
+    return names.length > 0 ? names : undefined;
+}
+/**
+ * A rule's passthrough. It's meaningful only on the counting behaviors, where
+ * "matched but didn't fire" is a distinct outcome that can fall through. On
+ * always, defer, skip or a debounce it would be a no-op at best and a
+ * misleading promise at worst, so it's refused rather than ignored.
+ */
+function readPassthrough(r, value, behavior, kind) {
+    if (value === undefined || value === false)
+        return false;
+    if (value !== true) {
+        r.problems.push({ text: `passthrough is ${shownValue(value)}, where true or false is needed` });
+        return false;
+    }
+    if (kind === undefined || kind === 'rate_limit' || kind === 'passive_sample')
+        return true;
+    r.problems.push({
+        text: `passthrough is only valid with rate_limit or passive_sample behaviors — for "${behavior ? formatBehavior(behavior) : kind}" `
+            + 'there is no non-firing match to fall through on',
+    });
+    return false;
+}
+/**
+ * A rule with no problem is in force as written. One with a problem is read
+ * past it, the way earlier releases read it, so it wakes the agent wherever
+ * they did and holds back what they held back, a rule that skips or defers
+ * included. It's left out only where they refused it.
+ */
+function ruleOutcome(reading) {
+    if (reading.problems.length === 0)
+        return 'as-written';
+    return reading.policy === undefined ? 'left-out' : 'read';
+}
+/** What a load or a start says of a rule: how it's read past its problems, or that it's left out, and its notes. */
+function readingSentences(reading, outcome) {
+    const said = [];
+    if (outcome === 'read') {
+        // Read past a problem that can widen it, a rule that holds events back holds back what it now matches.
+        const behavior = reading.policy?.behavior;
+        const holds = (behavior === 'skip' || behavior === 'defer') && reading.problems.some((p) => !p.narrows)
+            ? ` Read so, it ${behavior === 'skip' ? 'skips' : 'defers'} every event it now matches, as earlier releases did.`
+            : '';
+        said.push(`${reading.where}: ${reading.problems.map((p) => `${p.text}, ${p.read}`).join('; ')}.${holds}`);
+    }
+    else if (outcome === 'left-out') {
+        said.push(`${reading.where} is left out: ${reading.problems.map((p) => p.text).join('; ')}.`);
+    }
+    return [...said, ...notesOf(reading)];
+}
+/** addPolicy's refusal of a rule with problems: every one of them, and its notes. */
+function refusalOf(reading) {
+    return [`${reading.where} wasn't saved: ${reading.problems.map((p) => p.text).join('; ')}.`, ...notesOf(reading, true)].join(' ');
+}
+/** A rule's name as written, when it has a usable one. */
+function nameOf(rule) {
+    return isPlainObject(rule) && typeof rule.name === 'string' && rule.name ? rule.name : undefined;
+}
+/** What a load of gate.json says, from what its reading says of it: nothing, when that's nothing. */
+function loadNote(sentences) {
+    return sentences.length > 0 ? `gate.json loaded. ${sentences.join(' ')}` : null;
+}
+/** The names of the rules a gate.json holds as written: none, for one with no rule list. */
+function heldNames(listed) {
+    return new Set('noList' in listed ? [] : listed.rules.map(nameOf).filter((name) => name !== undefined));
+}
+/**
+ * gate.json, or the host's starting rules, read (`file` names which in
+ * messages). A file earlier releases loaded loads as they read it, with a
+ * note naming what they didn't read: a list is read as no rules under the
+ * default "always", and a slip of "policies", a name the gate doesn't read
+ * (a list of rules parked under one included), a field of a rule at the
+ * file's top and a "policies" that isn't a list each as nothing, so where
+ * "policies" writes no rules the file has none, and its default decides every
+ * event. A "policies" holding nothing, an empty list or one that isn't a
+ * list, writes no rules, as one left out does. Earlier releases refused it
+ * whole where it isn't an object, or its default isn't one of the three, and
+ * it isn't used. Each rule is read on its own. Under a default that holds
+ * events back, a rule left out that could wake the agent would hold back what
+ * it was written to wake on, so the file isn't used, as earlier releases,
+ * which refused such a rule and so the file, didn't use it. `start` is what a
+ * later start ran over a gate.json with no rules of its own, for its note: the
+ * host's starting rules beside one with no rule list, or, where gate.json
+ * isn't used at that start, the clause saying why and what runs instead
+ * (notUsedClause), which the sentence saying it has no rules carries.
+ */
+function readConfig(raw, file, start) {
+    const File = file === 'gate.json' ? file : 'The starting config';
+    if (Array.isArray(raw)) {
+        return {
+            config: { policies: [], default: 'always' },
+            rules: [],
+            sentences: [
+                `${File} is a list, where an object is needed, such as {"policies": [{"name": "my-rule", "behavior": "always"}]}, `
+                    + (start === 'beside'
+                        ? 'so none of it is read, and the gate runs the host\'s starting rules beside it, under the default, "always".'
+                        : 'so none of it is read, and every event gets the default, "always".'),
+            ],
+            listed: { noList: `${File} is a list` },
         };
-        const tagsAny = tagList(m.tagsAny);
-        if (tagsAny)
-            match.tagsAny = tagsAny;
-        const tagsAll = tagList(m.tagsAll);
-        if (tagsAll)
-            match.tagsAll = tagsAll;
-        const tagsNone = tagList(m.tagsNone);
-        if (tagsNone)
-            match.tagsNone = tagsNone;
-        if (m.filter && typeof m.filter === 'object') {
-            const f = m.filter;
-            if ((f.type === 'text' || f.type === 'regex') && typeof f.pattern === 'string') {
-                match.filter = { type: f.type, pattern: f.pattern };
-                if (f.type === 'regex') {
-                    try {
-                        new RegExp(f.pattern);
-                    }
-                    catch (e) {
-                        throw new Error(`Policy "${obj.name}": invalid regex pattern: ${e}`);
-                    }
-                }
-            }
-        }
     }
-    // Validate resets (optional list of policy names; unknown names are ignored
-    // at runtime so reload races don't blow up).
-    let resets;
-    if (Array.isArray(obj.resets)) {
-        const names = obj.resets.filter((s) => typeof s === 'string' && s.length > 0);
-        if (names.length > 0)
-            resets = names;
-    }
-    // Validate passthrough — only meaningful on the counting behaviors, where
-    // "matched but didn't fire" is a distinct outcome that can fall through.
-    // On always/defer/skip/debounce the flag would be a no-op at best and a
-    // misleading promise at worst, so reject it loudly instead of ignoring it.
-    let passthrough;
-    if (obj.passthrough !== undefined) {
-        if (typeof obj.passthrough !== 'boolean') {
-            throw new Error(`Policy "${obj.name}": passthrough must be a boolean`);
-        }
-        if (obj.passthrough) {
-            const counting = typeof behavior === 'object'
-                && ('rate_limit' in behavior || 'passive_sample' in behavior);
-            if (!counting) {
-                throw new Error(`Policy "${obj.name}": passthrough is only valid with rate_limit or `
-                    + `passive_sample behaviors — for "${formatBehavior(behavior)}" there is `
-                    + 'no non-firing match to fall through on');
-            }
-            passthrough = true;
+    if (!isPlainObject(raw))
+        return { refused: `${file} must be a JSON object`, listed: { noList: `${File} is ${shownValue(raw)}` } };
+    const sentences = [];
+    // At a start that doesn't use it, what having no rules does is that.
+    const notUsedWhy = typeof start === 'object' ? start.notUsed : undefined;
+    const notUsed = notUsedWhy === undefined ? undefined : `it has no rules, so ${notUsedWhy}`;
+    const obj = withoutEmpty(file, raw, sentences, { ...configLeftOut(raw.default), ...(notUsed ? { policies: notUsed } : {}) });
+    // Here a name holding "default" or "policies" isn't a slip of it: at the
+    // top, such a name can be a label of the file ("policiesUpdated").
+    const names = fieldNames(obj, CONFIG_FIELDS, false);
+    const { misplaced, rest } = placedElsewhere(names.unread, homesOf(file, CONFIG_FIELDS));
+    noteUnread(file, rest, CONFIG_FIELDS, sentences);
+    for (const m of misplaced) {
+        sentences.push(`${file} has ${misplacedShown(m)}, which the gate doesn't read here, so ${m.keys.length === 1 ? 'it does' : 'they do'} nothing.`);
+    }
+    // A "policies" holding nothing writes no rules, as one left out does.
+    const noPolicies = obj.policies === undefined || holdsNothing(obj.policies);
+    // What a change edits, used or not: its own fields and rule list as written
+    // (a list left out, null or "", or one holding nothing, is an empty one),
+    // beside whatever else it holds; or, where "policies" isn't a list and holds
+    // something, what it is instead, since a list there would write over it.
+    const listed = noPolicies || Array.isArray(obj.policies)
+        ? { top: raw, rules: Array.isArray(obj.policies) ? obj.policies : [] }
+        : { noList: `${File}'s "policies" is ${shownValue(obj.policies)}` };
+    const given = obj.default;
+    if (given !== undefined && given !== 'always' && given !== 'defer' && given !== 'skip') {
+        return { refused: `${file} "default" must be "always", "defer", or "skip", got: ${shownValue(given)}`, listed };
+    }
+    const defaultBehavior = given ?? 'always';
+    // Beside a start that runs the host's starting rules, since it has no list to add them to, they're what its default
+    // meets; at one that doesn't use it, what runs in its place is.
+    const noRules = start === 'beside'
+        ? `it has no rules, so the gate runs the host's starting rules beside it, under its default, "${defaultBehavior}"`
+        : notUsed ?? configLeftOut(defaultBehavior).policies;
+    for (const slip of names.slips) {
+        let read = SLIP_READ;
+        // Where "policies" writes no rules, what a slip of it holds leaves the file with none.
+        if (slip.meant.includes('policies') && noPolicies)
+            read = `and ${noRules}`;
+        else if (slip.meant.includes('default') && obj.default === undefined)
+            read = 'so its default is "always"';
+        sentences.push(`${File} has ${slipShown(slip)}, which the gate doesn't read, ${read}.`);
+    }
+    const policies = Array.isArray(obj.policies) ? obj.policies : [];
+    if (!Array.isArray(obj.policies) && obj.policies !== undefined) {
+        sentences.push(`${File}'s "policies" is ${shownValue(obj.policies)}, where a list of rules is needed, such as `
+            + `[{"name": "my-rule", "behavior": "always"}], and ${noRules}.`);
+    }
+    const rules = policies.map((rule, i) => {
+        const reading = readRule(rule, `The ${ordinal(i + 1)} policy`, file);
+        return { raw: rule, reading, outcome: ruleOutcome(reading) };
+    });
+    if (defaultBehavior !== 'always') {
+        const silenced = rules.filter((rule) => rule.outcome === 'left-out' && !rule.reading.quiet);
+        if (silenced.length > 0) {
+            const one = silenced.length === 1;
+            return {
+                refused: [
+                    `${file} leaves out ${one ? 'a rule' : 'rules'} that could wake the agent, and under its default, "${defaultBehavior}", `
+                        + `what ${one ? 'it was' : 'they were'} written to wake it on would be held back.`,
+                    ...silenced.flatMap((rule) => readingSentences(rule.reading, rule.outcome)),
+                ].join(' '),
+                listed,
+                silenced: silenced.map((rule) => nameOf(rule.raw)),
+            };
         }
     }
-    const policy = { name: obj.name, match, behavior };
-    if (resets)
-        policy.resets = resets;
-    if (passthrough)
-        policy.passthrough = passthrough;
-    return policy;
+    for (const rule of rules)
+        sentences.push(...readingSentences(rule.reading, rule.outcome));
+    // A list with no rules, or none the gate reads, where no sentence above said it has none.
+    if (notUsed !== undefined && !sentences.some((said) => said.includes(notUsed))) {
+        sentences.push(`${File} has no rules${rules.length > 0 ? ' but ones the gate leaves out' : ''}, so ${notUsedWhy}.`);
+    }
+    return {
+        config: {
+            policies: rules.filter((rule) => rule.outcome !== 'left-out').map((rule) => rule.reading.policy),
+            default: defaultBehavior,
+        },
+        rules,
+        sentences,
+        listed,
+    };
+}
+function readStartingRules(raw) {
+    const read = readConfig(raw, 'the starting config');
+    if ('refused' in read)
+        return { refusedWhole: read.refused, rules: [], sentences: [] };
+    return {
+        config: read.config,
+        given: raw,
+        rules: read.rules.map((rule) => ({ name: nameOf(rule.raw), raw: rule.raw, policy: rule.reading.policy, quiet: rule.reading.quiet })),
+        sentences: read.sentences,
+    };
+}
+/**
+ * The recipe the gate last applied (lastRecipePath), as written, or null when
+ * it has none on record. It's read as the host's starting rules are, so a
+ * recipe recorded as given reads back as the start read it. A record that
+ * exists and isn't one the gate wrote (it can't be read, isn't JSON, is
+ * refused as the starting rules are, or names a rule twice) gives null with
+ * the reason, which quotes nothing from the file but a rule's name: a start
+ * then removes and redefines nothing, as the first does, and says why.
+ */
+function readLastRecipe(path) {
+    if (!existsSync(path))
+        return { recipe: null };
+    let raw;
+    try {
+        raw = parseGateJson(readFileSync(path, 'utf-8'));
+    }
+    catch (err) {
+        const code = err.code;
+        return { recipe: null, problem: code ? `reading it failed with ${code}` : "it isn't JSON" };
+    }
+    const read = readStartingRules(raw);
+    if (read.refusedWhole !== undefined)
+        return { recipe: null, problem: "it isn't read as the starting rules are" };
+    const rules = read.rules.map((rule) => rule.raw);
+    const twice = duplicateName(rules);
+    if (twice !== undefined)
+        return { recipe: null, problem: `it names the rule "${twice}" twice` };
+    return { recipe: { rules, default: isPlainObject(raw) ? raw.default : undefined } };
+}
+/**
+ * A rule's meaning, for the start's merge: the rule as the gate reads it,
+ * where it reads, and as written where it doesn't. So a rule `wake_add_rule`
+ * wrote as read agrees with the same rule written more briefly.
+ */
+function ruleMeaning(rule) {
+    const reading = readRule(rule, 'A policy');
+    return reading.policy ? `read ${canonical(reading.policy)}` : `written ${canonical(rule)}`;
+}
+/**
+ * What gate_status says about the start, which stays until the next one: the
+ * host's starting rules that couldn't be used and what the start did instead,
+ * how it read them past problems, and rules a reconcile couldn't add. Worded
+ * about the start, so later writes and reloads
+ * leave it true; configSource says what's in force now. `held` is the names
+ * of the rules gate.json holds as written, when it loaded.
+ */
+function describeStart(starting, write, held) {
+    const parts = [];
+    if (starting.refusedWhole !== undefined) {
+        // gate.json's rules: as loaded, or as read before a write of the start's
+        // own left it unable to load; or none, where gate.json wasn't used either.
+        const instead = write.kind === 'start-without'
+            ? `gate.json, which has no rules the gate reads, wasn't used either: under its default, "${write.default}", it would hold back every `
+                + 'event, so the gate started with no rules, as a start without gate.json does. Giving gate.json rules under '
+                + '"policies", or fixing the starting rules, puts rules in force (a fix to the starting rules, at the next start).'
+            : held !== null || write.kind === 'reconcile-failed'
+                ? "The gate started with gate.json's rules."
+                : 'The gate started with no rules, as on a host without starting rules.';
+        parts.push(`At start, the host's starting rules weren't used: ${sentence(starting.refusedWhole)} ${instead}`);
+    }
+    if (starting.sentences.length > 0)
+        parts.push(`In the host's starting rules, ${starting.sentences.join(' ')}`);
+    // A reconcile whose write failed and left gate.json loading: the rules it
+    // was adding didn't reach it, unless the write landed before failing.
+    if (write.kind === 'reconcile-failed' && held) {
+        if (!write.names.every((name) => held.has(name))) {
+            parts.push(`At start, the host's starting rules ${quotedList(write.names)} couldn't be added to gate.json (${write.error}), `
+                + "so they weren't put in force. "
+                + (write.text !== undefined
+                    ? 'Whoever runs this host can fix what kept them from being written.'
+                    : 'A start adds them once what kept them out is fixed.'));
+        }
+        // The merge's other changes: removals, redefinitions, moves and the default.
+        if (write.changing?.length) {
+            parts.push(`At start, the recipe's changes to gate.json (${quotedList(write.changing)}) `
+                + (write.atOpen
+                    ? `weren't saved (${write.error}), so the gate started with gate.json's rules as they were. `
+                    : `may not all have been saved (${write.error}): the gate started with gate.json as the write left it. `)
+                + (write.text !== undefined
+                    ? 'Whoever runs this host can fix what kept them from being written.'
+                    : 'A start applies them once what kept them out is fixed.'));
+        }
+    }
+    return parts.length > 0 ? parts.join(' ') : null;
+}
+/**
+ * Why gate.json, which has no rules of its own, isn't used at a start that runs
+ * as one without it (start-without), and what runs in its place: the clause
+ * after "it has no rules, so" in its note.
+ */
+function notUsedClause(write, starting) {
+    const back = 'Giving gate.json rules under "policies"';
+    const out = outOfForce(write);
+    if (out) {
+        return `it isn't used at this start: under its default, "${write.default}", ${out.said}, so the gate runs the starting `
+            + `rules under their own default, "${starting.config?.default ?? 'always'}", as a start without gate.json does. ${back}, or ${out.fix}, puts it in use`
+            + (out.nextStart ? ' (a fix to the starting rules, at the next start)' : '');
+    }
+    return `under its default, "${write.default}", it would hold back every event: it isn't used at this start, and the gate runs `
+        + `no rules, as a start without gate.json does, so every event gets the default, "always". ${back}, or fixing the starting rules, puts rules in force`
+        + ' (a fix to the starting rules, at the next start)';
+}
+/**
+ * The starting rules a start that doesn't use gate.json couldn't put in force
+ * beside it or in it, which could wake the agent, and what would put them in
+ * force: null where the starting rules were refused whole.
+ */
+function outOfForce(write) {
+    const nameless = write.nameless ?? 0;
+    const left = [...(write.leftOut ?? []).map((name) => `"${name}"`), ...(nameless === 0 ? [] : [nameless === 1 ? 'one with no name' : `${nameless} with no name`])];
+    const held = write.heldOut ?? [];
+    const said = [];
+    const fix = [];
+    if (left.length > 0) {
+        said.push(`the host's starting rules would leave out ${joinedList(left)}, which could wake the agent`);
+        fix.push(`fixing ${joinedList(left)} in the starting rules`);
+    }
+    if (held.length > 0) {
+        said.push(`the host's ${quotedList(held)}, which could wake the agent, would be kept out by gate.json's `
+            + `${held.length === 1 ? 'rule of that name' : 'rules of those names'}, which the gate leaves out`);
+        fix.push(`fixing gate.json's ${quotedList(held)}`);
+    }
+    // While gate.json has no rules of its own, every one of them has to be put
+    // in force for it to be used, so where both kinds keep it out, both fixes
+    // are needed; giving gate.json rules of its own is the other way, which the
+    // entry gives first.
+    // The starting rules are read at a start, so a fix to them puts gate.json in
+    // use from the next one.
+    return said.length > 0
+        ? { said: said.join(', and '), fix: fix.length > 1 ? `both ${fix.join(', and ')}` : fix[0], nextStart: left.length > 0 }
+        : null;
+}
+/**
+ * What gate_status says when the start left rules in force unsaved: a first
+ * start's seed that failed, a reconcile whose write left gate.json unable to
+ * load (`loaded` false), or, over a gate.json with no rule list (`loaded`
+ * true), the starting rules it lacks, run beside it, or, over one with no rules
+ * of its own, the starting rules run under their own default where gate.json
+ * isn't used. It goes once gate.json is written, or a reload applies its text
+ * or, but where the start ran rules beside or in place of such a gate.json,
+ * finds it holding the text in force.
+ */
+function describeUnsaved(starting, write, loaded) {
+    if (write.kind === 'reconcile-unsaved') {
+        if (!loaded)
+            return null;
+        return `At start, the host's starting rules ${quotedList(write.names)} couldn't be added to gate.json (${write.error}). `
+            + `The gate runs them under gate.json's default, "${write.config.default ?? 'always'}", as if gate.json held them, but `
+            + "they aren't saved in it: once gate.json changes and loads, what it holds is in force instead. Once gate.json has a "
+            + 'list of rules under "policies", a start adds them to it, as to any gate.json with a list.';
+    }
+    if (write.kind === 'start-without') {
+        // Starting rules refused whole put none in force, and describeStart says so.
+        const out = outOfForce(write);
+        if (!out)
+            return null;
+        return `At start, gate.json, which has no rules the gate reads, wasn't used: under its default, "${write.default}", ${out.said}. The gate `
+            + `runs the starting rules under their own default, "${starting.config?.default ?? 'always'}", as a start without gate.json `
+            + 'does, but they aren\'t saved in it: once gate.json changes and loads, what it holds is in force instead. Giving '
+            + `gate.json rules under "policies", or ${out.fix}, puts it in use`
+            + `${out.nextStart ? ' (a fix to the starting rules, at the next start)' : ''}.`;
+    }
+    if (loaded)
+        return null;
+    if (write.kind === 'seed-failed') {
+        return write.atOpen
+            ? `At start, gate.json couldn't be created (${write.error}), so the host's starting rules are in force but aren't saved in it. `
+                + 'Whoever runs this host can fix what keeps it from being written.'
+            : `At start, writing the host's starting rules to gate.json failed partway (${write.error}), so gate.json may be left `
+                + "part-written. The starting rules are in force but aren't saved in it, and a restart before gate.json is fixed starts "
+                + 'from them too. Whoever runs this host can fix what kept it from being written, and gate.json.';
+    }
+    if (write.kind === 'reconcile-failed') {
+        // A write of the recipe's merge that did more than add rules, or one that only added them.
+        const merging = (write.changing?.length ?? 0) > 0;
+        const changes = quotedList([...write.names, ...(write.changing ?? [])]);
+        const what = merging
+            ? write.atOpen
+                ? `the recipe's changes to gate.json (${changes}) couldn't be written (${write.error}), and gate.json couldn't be loaded after that`
+                : `writing the recipe's changes to gate.json (${changes}) failed partway (${write.error}), so gate.json may be left part-written`
+            : write.atOpen
+                ? `the host's starting rules ${quotedList(write.names)} couldn't be added to gate.json (${write.error}), and gate.json `
+                    + "couldn't be loaded after that"
+                : `adding the host's starting rules ${quotedList(write.names)} to gate.json failed partway (${write.error}), so gate.json `
+                    + 'may be left part-written';
+        // What those rules hold that the gate reads past or leaves out, since
+        // gate.json's own entry is now its load error.
+        const read = write.sentences?.length ? `, read as a load reads them: ${write.sentences.join(' ')}` : '.';
+        const runs = merging ? 'the rules that write held' : "the rules it read from gate.json and the ones it was adding";
+        return `At start, ${what}. The gate runs ${runs}, which aren't saved${read} `
+            + `A restart before gate.json is fixed starts from ${starting.config ? "the host's starting rules" : 'no rules'}. `
+            + 'Whoever runs this host can fix what kept it from being written, and gate.json.';
+    }
+    return null;
 }
 // ---------------------------------------------------------------------------
 // Shadow lint — prove (conservatively) when rule ordering makes a rule dead
@@ -426,6 +1441,44 @@ export function formatShadowWarning(w) {
     return `rule "${w.earlier}" makes "${w.later}" unreachable for ${types} `
         + `(first match wins — every event "${w.later}" would match is consumed by "${w.earlier}" first)`;
 }
+/** The text of a thrown value, for a log line. It never throws itself, whatever was thrown. */
+function errorText(err) {
+    try {
+        return err instanceof Error ? err.message : String(err);
+    }
+    catch {
+        return 'a value that could not be printed';
+    }
+}
+/**
+ * Run a caller's callback once the change it's told of is made and traced. A
+ * throw from it is logged, not thrown, so the call answers as the change it
+ * made: told the change had failed, an agent could make it a second time.
+ */
+function afterChange(name, callback) {
+    try {
+        callback();
+    }
+    catch (err) {
+        console.error(`[gate] ${name} threw once the change was made, and the change stands: ${errorText(err)}`);
+    }
+}
+/** The privileged-users file's error when some entries of its list aren't user ids. */
+function skippedPrivilegedIds(skipped, loaded) {
+    const one = skipped.length === 1;
+    const shown = skipped.slice(0, 5).map((x) => {
+        if (typeof x === 'number' && Number.isInteger(x)) {
+            return `${x} (a number this large can't be read exactly: write the id as a string, in quotes)`;
+        }
+        const json = JSON.stringify(x) ?? String(x);
+        return json.length > 40 ? `${safeSlice(json, 0, 39)}…` : json;
+    });
+    const more = skipped.length > shown.length ? `, and ${skipped.length - shown.length} more` : '';
+    const rest = loaded === 0 ? 'no id loaded, so no one is privileged' : `${loaded} ${loaded === 1 ? 'id' : 'ids'} did load`;
+    return `${skipped.length} ${one ? 'entry' : 'entries'} in the privileged-users file ${one ? "isn't a user id" : "aren't user ids"}, `
+        + `so ${one ? 'it was' : 'they were'} skipped: ${shown.join(', ')}${more}. A user id is a non-empty string, or a safe integer `
+        + `(a whole number within 2^53 - 1 of zero); ${rest}.`;
+}
 // ---------------------------------------------------------------------------
 // EventGate
 // ---------------------------------------------------------------------------
@@ -435,11 +1488,37 @@ export class EventGate {
     /** Optional agent-authored programmable gate (gate.js). */
     gateScript;
     compiledPolicies = [];
-    configMtime = 0;
+    /** 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. */
+    configText;
+    /** The notes on fields the text in force has that the gate doesn't read, if any. */
+    configNote = null;
     lastReloadCheck = 0;
     configSource = 'default';
     lastReloadTimestamp = null;
-    configErrors = [];
+    /** The current problem with each file the gate reads, one each, replaced
+     *  whenever that file is read again (gate_status `errors`). */
+    configError = null;
+    /** 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. */
+    configUnused = false;
+    privilegedError = null;
+    /** 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. */
+    startNotice = null;
+    /** The rules in force that the start couldn't save (describeUnsaved),
+     *  until gate.json is written or a reload applies its text. */
+    startUnsaved = null;
+    /** What the start's merge of the recipe couldn't do (seedOrReconcile), said with startNotice until the next start. */
+    startMergeNote = null;
+    /** Whether the start's unsaved rules (startUnsaved) are a merge's that did more than add rules. */
+    startUnsavedMerged = false;
     // Debounce state
     debounceTimers = new Map();
     // Rate-limit state — policy name → key → bucket.
@@ -490,7 +1569,9 @@ export class EventGate {
     // privilegedUsersPath on change.
     privilegedUsersPath;
     privilegedUserIds = new Set();
-    privilegedMtime = 0;
+    /** The privileged-users file's text as last read, whether or not it loaded;
+     *  undefined when it was missing or its last read failed. */
+    privilegedText;
     lastPrivilegedCheck = 0;
     // Dependency-injected callbacks
     emitTrace;
@@ -498,6 +1579,8 @@ export class EventGate {
     requestInferenceFn;
     getAgentNamesFn;
     resolveRouteChannelFn;
+    channelShownFn;
+    isNewestEntryFn;
     /** Clock injection — keeps the new rate_limit / passive_sample paths
      *  testable without monkey-patching Date.now globally. */
     now;
@@ -509,52 +1592,79 @@ export class EventGate {
         this.requestInferenceFn = opts.requestInference;
         this.getAgentNamesFn = opts.getAgentNames;
         this.resolveRouteChannelFn = opts.resolveRouteChannel ?? defaultRouteChannel;
+        this.channelShownFn = opts.channelShown;
+        this.isNewestEntryFn = opts.isNewestEntry;
         this.now = opts.now ?? (() => Date.now());
         this.loadPrivileged();
-        // Seed or reconcile the on-disk config.
+        // 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
+        // with a problem is read past it, or left out (readConfig).
         //
-        // First start: write `initialConfig` verbatim.
-        // Subsequent starts: if the recipe/config source declares policies that
-        // aren't yet in gate.json (e.g. the user edited the recipe between
-        // sessions), append them by name. Existing policies are left alone so
-        // user edits via `workspace--edit _config/gate.json` survive.
-        // The `default` field is not reconciled — it's an explicit operator
-        // choice and a recipe change shouldn't silently flip live wake
-        // behavior for a session that's already been running.
-        if (opts.initialConfig) {
-            try {
-                mkdirSync(dirname(this.configPath), { recursive: true });
-                if (!existsSync(this.configPath)) {
-                    writeFileSync(this.configPath, JSON.stringify(opts.initialConfig, null, 2) + '\n');
-                }
-                else {
-                    const existing = this.loadConfig();
-                    if (existing) {
-                        const existingNames = new Set(existing.policies.map(p => p.name));
-                        const missing = opts.initialConfig.policies.filter(p => !existingNames.has(p.name));
-                        if (missing.length > 0) {
-                            const reconciled = {
-                                ...existing,
-                                policies: [...existing.policies, ...missing],
-                            };
-                            writeFileSync(this.configPath, JSON.stringify(reconciled, null, 2) + '\n');
-                            opts.emitTrace({
-                                type: 'gate:config-reconciled',
-                                configPath: this.configPath,
-                                addedPolicies: missing.map(p => p.name),
-                                timestamp: Date.now(),
-                            });
-                        }
-                    }
-                }
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                this.configErrors.push(`Failed to seed/reconcile gate.json: ${msg}`);
-            }
+        // First start: write `initialConfig` as given, since gate.json is read the
+        // same way, and record it as the recipe last applied, beside gate.json.
+        // Later starts: merge the recipe into gate.json against that record,
+        // three ways and as written (seedOrReconcile), so a rule the recipe
+        // dropped, renamed, moved or redefined follows it, while a rule edited at
+        // run time or by `workspace--edit _config/gate.json`, and one no recipe
+        // declared, stays. `default` follows the same rule: an unedited one takes
+        // the recipe's.
+        const initial = opts.initialConfig;
+        const starting = initial !== undefined ? readStartingRules(initial) : undefined;
+        const write = starting ? this.seedOrReconcile(starting) : { kind: 'none' };
+        // Load config: gate.json; without it, the starting rules as read, unless
+        // none of them is used; and otherwise no rules, as a host without any has. When a
+        // reconcile's own write left gate.json unable to load, the gate runs what
+        // that write held, the rules it read as the recipe's merge changed them,
+        // since a failed write of ours shouldn't take rules out of force. Over a gate.json
+        // with no rule list to add them to, it runs gate.json's default with the
+        // starting rules it lacks, as earlier releases did once they had written
+        // them over it, where seedOrReconcile gives them (reconcile-unsaved). Where
+        // gate.json has no rules of its own and they can't run beside it or be
+        // added to it (start-without), earlier releases couldn't load what they
+        // wrote and ran the starting rules from memory, so gate.json isn't used,
+        // and the start runs as one without it does.
+        const read = this.readConfigFile();
+        if (read.state === 'loaded') {
+            // Beside a gate.json with no rule list, the host's starting rules it
+            // lacks, and its note says they run beside it, or, in place of one with
+            // no rules of its own, those a start without it runs, and its note says
+            // why.
+            const beside = write.kind === 'reconcile-unsaved';
+            const without = write.kind === 'start-without' ? write : null;
+            this.config = beside ? write.config : without ? (starting?.config ?? { ...DEFAULT_CONFIG }) : read.config;
+            this.configText = read.text;
+            const start = beside ? 'beside' : without && starting ? { notUsed: notUsedClause(without, starting) } : undefined;
+            const asStarted = start ? readConfig(parseGateJson(read.text), 'gate.json', start) : null;
+            this.configNote = asStarted && 'sentences' in asStarted ? loadNote(asStarted.sentences) : read.note;
+            this.configError = this.configNote;
+            this.configSource = beside || starting?.config && without ? 'initial' : without ? 'default' : 'file';
+            if (this.configNote)
+                console.error(`[gate] ${this.configNote}`);
+        }
+        else if (write.kind === 'reconcile-failed') {
+            this.config = write.config;
+            // A change over the part-written gate.json is refused; once gate.json is
+            // gone, this text is what a change edits, so every rule it holds keeps its name.
+            this.configText = write.text;
+            this.configNote = write.note ?? null;
+            this.configSource = 'file';
+        }
+        else {
+            this.config = starting?.config ?? { ...DEFAULT_CONFIG };
+            this.configSource = starting?.config ? 'initial' : 'default';
+        }
+        // What the start did is kept apart from gate.json's load error, so the
+        // load above can't clear it when it succeeds.
+        if (starting) {
+            const described = describeStart(starting, write, read.state === 'loaded' ? heldNames(read.listed) : null);
+            this.startNotice = [described, this.startMergeNote].filter((part) => part !== null).join(' ') || null;
+            this.startUnsaved = describeUnsaved(starting, write, read.state === 'loaded');
+            this.startUnsavedMerged = write.kind === 'reconcile-failed' && (write.changing?.length ?? 0) > 0;
+        }
+        for (const said of [this.startNotice, this.startUnsaved]) {
+            if (said)
+                console.error(`[gate] ${said}`);
         }
-        // Load config
-        this.config = this.loadConfig() ?? opts.initialConfig ?? { ...DEFAULT_CONFIG };
         this.compiledPolicies = this.compilePolicies(this.config);
         this.refreshShadowWarnings('startup');
         // Programmable gate: an optional agent-authored `gate.js` next to gate.json.
@@ -564,30 +1674,382 @@ export class EventGate {
     // =========================================================================
     // Config loading
     // =========================================================================
-    loadConfig() {
-        if (!existsSync(this.configPath)) {
-            return null;
+    /**
+     * 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.
+     */
+    seedOrReconcile(starting) {
+        const read = this.readConfigFile();
+        if (read.state === 'absent') {
+            if (!starting.config)
+                return { kind: 'none' };
+            try {
+                mkdirSync(dirname(this.configPath), { recursive: true });
+                writeFileSync(this.configPath, JSON.stringify(starting.given, null, 2) + '\n');
+            }
+            catch (err) {
+                return { kind: 'seed-failed', error: errorText(err), atOpen: beforeWriting(err) };
+            }
+            const twice = duplicateName(starting.rules.map((rule) => rule.raw));
+            if (twice !== undefined) {
+                this.startMergeNote = `At start, the recipe names the rule "${twice}" twice, so gate.json was seeded with it as given and it `
+                    + "wasn't recorded as the recipe last applied: a later start merges the recipe by name, once gate.json and the recipe "
+                    + 'name each rule once.';
+            }
+            else {
+                this.recordRecipe(lastRecipePath(this.configPath), starting.given, 'gate.json was seeded with the recipe');
+            }
+            return { kind: 'none' };
+        }
+        if (read.state !== 'loaded')
+            return { kind: 'none' };
+        const held = heldNames(read.listed);
+        const fileDefault = read.config.default ?? 'always';
+        // No rule list, an empty one, or one holding only rules the gate leaves out.
+        const noRules = read.config.policies.length === 0;
+        // Starting rules refused whole put none beside or in a gate.json with no
+        // rules of its own, which holds events back. Earlier releases wrote them
+        // over it or into it, couldn't load what they wrote, and ran them from
+        // memory, so gate.json isn't used at this start either.
+        if (noRules && starting.refusedWhole !== undefined && fileDefault !== 'always') {
+            return { kind: 'start-without', default: fileDefault };
+        }
+        // Nor can a start put in force, beside or in a gate.json with no rules of
+        // its own, a starting rule a load leaves out, one with no name, which it
+        // can't add by name, or one whose name gate.json holds in a rule the gate
+        // leaves out, which keeps the host's rule of that name out. Where, under
+        // gate.json's default, one of them could wake the agent, earlier releases
+        // ran the starting rules from memory: they couldn't load what they wrote
+        // over gate.json or into it, or, refusing its rule, didn't load it at all.
+        // So gate.json isn't used at this start, which runs as one without it does.
+        if (noRules && fileDefault !== 'always') {
+            const out = starting.rules.filter((rule) => !rule.quiet && (rule.policy === undefined || (rule.name !== undefined && held.has(rule.name))));
+            if (out.length > 0) {
+                const named = out.flatMap((rule) => (rule.name === undefined ? [] : [rule.name]));
+                return {
+                    kind: 'start-without',
+                    default: fileDefault,
+                    leftOut: named.filter((name) => !held.has(name)),
+                    nameless: out.length - named.length,
+                    heldOut: named.filter((name) => held.has(name)),
+                };
+            }
         }
+        if ('noList' in read.listed) {
+            const missing = starting.rules.filter((rule) => rule.name !== undefined && !held.has(rule.name));
+            if (missing.length === 0)
+                return { kind: 'none' };
+            const names = missing.map((rule) => rule.name);
+            // Adding them would write over what gate.json holds. Earlier releases
+            // wrote them over it and ran them under its default, so the gate runs
+            // them so, unsaved, beside it.
+            const error = `${read.listed.noList}, so there's no list of rules to add them to without writing over what it holds`;
+            // The ones it runs: a starting rule left out is named as the starting rules are read.
+            const running = missing.flatMap((rule) => (rule.policy === undefined ? [] : [rule.policy]));
+            if (running.length === 0)
+                return { kind: 'reconcile-failed', names, atOpen: true, config: read.config, error };
+            return { kind: 'reconcile-unsaved', names: running.map((policy) => policy.name), error, config: { policies: running, default: fileDefault } };
+        }
+        // Starting rules refused whole have nothing to merge or record.
+        if (starting.refusedWhole !== undefined)
+            return { kind: 'none' };
+        // The merge, as written: gate.json's rule list and default against the
+        // recipe's, three ways, with the recipe last applied.
+        const recordPath = lastRecipePath(this.configPath);
+        const last = readLastRecipe(recordPath);
+        const given = isPlainObject(starting.given) ? starting.given : {};
+        let merged;
+        let appended = false;
+        let appendedNote = '';
         try {
-            const raw = readFileSync(this.configPath, 'utf-8');
-            const stat = statSync(this.configPath);
-            this.configMtime = stat.mtimeMs;
-            const config = validateConfig(parseGateJson(raw));
-            this.configSource = 'file';
-            this.configErrors = [];
-            return config;
+            merged = reconcileWithRecipe({ rules: read.listed.rules, default: read.listed.top.default }, { rules: starting.rules.map((rule) => rule.raw), default: given.default }, last.recipe, ruleMeaning);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            this.configErrors = [msg];
+            // A name given twice: a merge by name can't say which rule was meant.
+            // So the start adds the rules gate.json lacks, after its own, as
+            // earlier releases did, and removes, redefines and records nothing.
+            const missing = starting.rules.filter((rule) => rule.name !== undefined && !held.has(rule.name));
+            const lacked = [...new Set(missing.map((rule) => rule.name))];
+            appended = true;
+            // What it did is said once its write is made (appendedNote), and a
+            // write that fails is said as any start's is.
+            const why = `At start, ${errorText(err)}, and the merge with the recipe needs one rule per name, so it didn't run`;
+            const remedy = 'Once gate.json and the recipe name each rule once, a start merges the recipe.';
+            this.startMergeNote = `${why}. ${remedy}`;
+            appendedNote = `${why}: `
+                + (lacked.length > 0
+                    ? `the start added the rules gate.json lacked (${quotedList(lacked)}), after its own, and removed, redefined and recorded nothing. `
+                    : 'gate.json is as it was, and nothing was recorded. ')
+                + remedy;
+            merged = {
+                rules: [...read.listed.rules, ...missing.map((rule) => rule.raw)],
+                default: read.listed.top.default,
+                defaultChanged: false,
+                changes: { ...noChanges(), added: missing.map((rule) => rule.name) },
+            };
+        }
+        const { changes } = merged;
+        if (last.problem !== undefined)
+            changes.recordUnreadable = last.problem;
+        const top = { ...read.listed.top };
+        if (merged.defaultChanged) {
+            if (merged.default === undefined)
+                delete top.default;
+            else
+                top.default = merged.default;
+        }
+        const reconciled = { ...top, policies: merged.rules };
+        const names = [...changes.added, ...changes.restored];
+        const changing = [...changes.removed, ...changes.updated, ...changes.moved, ...(changes.defaultChange ? ['default'] : [])];
+        const written = canonical(reconciled) !== canonical({ ...read.listed.top, policies: read.listed.rules });
+        if (written) {
+            // What the write holds, as a load reads it, for a write that fails partway.
+            const holds = readConfig(reconciled, 'gate.json');
+            if ('refused' in holds) {
+                // A write of ours doesn't take gate.json's own rules out of force:
+                // nothing is written or recorded, so it loads as it did. (With no
+                // rules of its own, gate.json isn't used at this start, above.)
+                const error = 'with them, gate.json would leave out a rule that could wake the agent, and under its default, '
+                    + `"${changes.defaultChange?.to ?? read.config.default ?? 'always'}", it wouldn't be used`;
+                return { kind: 'reconcile-failed', names, changing, atOpen: true, config: read.config, error };
+            }
+            const text = JSON.stringify(reconciled, null, 2) + '\n';
+            try {
+                writeFileSync(this.configPath, text);
+            }
+            catch (err) {
+                return {
+                    kind: 'reconcile-failed',
+                    names,
+                    changing,
+                    error: errorText(err),
+                    atOpen: beforeWriting(err),
+                    config: holds.config,
+                    text,
+                    note: loadNote(holds.sentences),
+                    sentences: holds.sentences,
+                };
+            }
+        }
+        if (appended)
+            this.startMergeNote = appendedNote;
+        // Said before the record is written, so a failed record write still
+        // leaves what the start did to gate.json named. A start that only added
+        // rules, since the merge couldn't run, is said in startNotice instead.
+        const line = appended ? null : reconcileLine(changes);
+        if (line)
+            console.error(line);
+        if (line || names.length > 0) {
+            this.emitTrace({
+                type: 'gate:config-reconciled',
+                configPath: this.configPath,
+                ...changes,
+                // Every name the start added to gate.json, as an append's trace gave.
+                addedPolicies: names,
+                timestamp: Date.now(),
+            });
+        }
+        if (!appended && (!last.recipe || canonical({ rules: last.recipe.rules, default: last.recipe.default }) !== canonical({ rules: starting.rules.map((rule) => rule.raw), default: given.default }))) {
+            this.recordRecipe(recordPath, starting.given, written ? 'gate.json holds the recipe merged into it' : 'the merge left gate.json as it was');
+        }
+        return { kind: 'none' };
+    }
+    /**
+     * 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.
+     */
+    recordRecipe(recordPath, given, holds) {
+        try {
+            writeFileSync(recordPath, JSON.stringify(given, null, 2) + '\n');
+        }
+        catch (err) {
+            this.startMergeNote = `At start, ${holds}, and the gate runs it, but recording the recipe in ${basename(recordPath)} failed `
+                + `(${errorText(err)}), so the next start merges against the record as this write left it. Whoever runs this host can `
+                + 'fix what kept it from being written.';
+        }
+    }
+    /**
+     * 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.
+     */
+    readConfigFile(opts) {
+        let raw;
+        try {
+            raw = readFileSync(this.configPath, 'utf-8');
+        }
+        catch (err) {
+            if (!isMissing(err))
+                return this.configUnreadable(err);
+            // No file is no problem with it: the rules in force stay.
+            this.configError = null;
+            this.configUnused = false;
+            return { state: 'absent' };
+        }
+        // A file holding the text in force has that text's notes as its error,
+        // whatever a failed read or a look at other text since left there: beside
+        // the host's starting rules, they say those run beside it.
+        const inForce = raw === this.configText;
+        if (opts?.unlessUnchanged && inForce) {
+            this.configError = this.configNote;
+            this.configUnused = false;
+            return { state: 'unchanged' };
+        }
+        let parsed;
+        try {
+            parsed = parseGateJson(raw);
+        }
+        catch (err) {
+            return { ...this.configUnreadable(err), notJson: true };
+        }
+        const read = readConfig(parsed, 'gate.json');
+        // JSON the gate doesn't use is still the operator's file, edited as written.
+        if ('refused' in read) {
+            return { ...this.configUnreadable(new Error(read.refused)), state: 'refused', listed: read.listed, silenced: read.silenced };
+        }
+        // A field the gate doesn't read does nothing, and a rule is read past a
+        // problem or left out, so the file loads, and each is named.
+        const note = loadNote(read.sentences);
+        this.configError = inForce ? this.configNote : note;
+        this.configUnused = false;
+        return { state: 'loaded', config: read.config, text: raw, note, listed: read.listed };
+    }
+    /**
+     * 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.
+     */
+    configUnreadable(err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg !== this.configError) {
+            console.error(`[gate] ${this.configPath} couldn't be used (${msg}), so what it holds isn't in force`);
             this.emitTrace({
                 type: 'gate:config-error',
                 error: msg,
                 configPath: this.configPath,
                 timestamp: Date.now(),
             });
-            return null; // Caller keeps previous config
         }
+        this.configError = msg;
+        this.configUnused = true;
+        return { state: 'unreadable', error: msg };
+    }
+    /**
+     * 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.
+     */
+    configErrorShown() {
+        if (this.configError === null || !this.configUnused)
+            return this.configError;
+        return `${sentence(this.configError)} So what gate.json holds isn't in force, and the gate runs ${this.rulesRun()}.`;
+    }
+    /** What the gate runs, by where its rules came from, for a text that says so: "the host's starting rules". */
+    rulesRun() {
+        if (this.config.policies.length === 0)
+            return `no rules: every event gets the default, "${this.config.default ?? 'always'}"`;
+        // Rules from a gate.json text, with the start's unsaved: only a start
+        // whose reconcile write left gate.json unable to load runs those, since a
+        // write of gate.json that lands, a reload that finds it holding a text
+        // that loads, or, while gate.json's rules are in force, one that finds it
+        // holding the text in force, clears startUnsaved.
+        return this.configSource === 'file'
+            ? this.startUnsaved !== null
+                ? this.startUnsavedMerged
+                    ? 'the rules its start was writing to gate.json'
+                    : 'the rules it read from gate.json at start and the ones it was adding'
+                : 'the rules of the last gate.json it used'
+            : "the host's starting rules";
+    }
+    /**
+     * 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.
+     */
+    rulesForChange() {
+        const read = this.readConfigFile();
+        if (read.state === 'unreadable')
+            return { refused: unusableRefusal(read, this.rulesRun()) };
+        if (read.state === 'loaded' || read.state === 'refused') {
+            if ('noList' in read.listed)
+                return { refused: noListRefusal(read.listed.noList, this.rulesRun()) };
+            // Rules not gate.json's in force while it holds the text in force: what a
+            // start ran in place of one with no rules of its own, until it changes.
+            if (read.state === 'loaded' && read.text === this.configText && this.configSource !== 'file') {
+                return { refused: notUsedRefusal(this.rulesRun()) };
+            }
+            const edit = { top: read.listed.top, rules: [...read.listed.rules] };
+            if (read.state === 'loaded')
+                return edit;
+            // What would bring it into force, for a change that doesn't. A change
+            // finds its rule by name: a replacement takes the first rule with it,
+            // and a removal every one.
+            const names = [...new Set(read.silenced ?? [])];
+            const only = names.length === 1 ? names[0] : undefined;
+            const sharing = only === undefined ? 0 : edit.rules.filter((rule) => nameOf(rule) === only).length;
+            // A removal that would leave no rules in force is refused (writeConfig),
+            // so it isn't offered.
+            const rest = readConfig({ ...edit.top, policies: edit.rules.filter((rule) => nameOf(rule) !== only) }, 'gate.json');
+            const removes = !('refused' in rest) && rest.config.policies.length > 0;
+            return {
+                ...edit,
+                remedy: sharing === 1
+                    ? `${removes ? 'Replacing or removing' : 'Replacing'} "${only}" by name would bring gate.json into force.`
+                    : sharing > 1
+                        ? `gate.json has ${sharing} rules named "${only}", and a change by that name replaces the first of them`
+                            + `${removes ? ' or removes them all' : ''}.`
+                        : 'No change through the gate can bring it into force, so gate.json has to be fixed by an edit of its own; '
+                            + 'until then, a change is refused the same way.',
+            };
+        }
+        // While the rules in force aren't gate.json's, configText is the text a
+        // start ran them beside or in place of, so its rules aren't the ones in force.
+        const text = this.configText !== undefined && this.configSource === 'file'
+            ? readConfig(parseGateJson(this.configText), 'gate.json')
+            : undefined;
+        return text && !('refused' in text) && !('noList' in text.listed)
+            ? { top: text.listed.top, rules: [...text.listed.rules] }
+            : { top: { policies: [], default: this.config.default ?? 'always' }, rules: [...this.config.policies] };
     }
     compilePolicies(config) {
         return config.policies.map(policy => {
@@ -619,53 +2081,70 @@ export class EventGate {
             return compiled;
         });
     }
+    /**
+     * 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.
+     */
+    clearStateFor(was, next) {
+        const behaviorsByName = (config) => {
+            const byName = new Map();
+            for (const p of config.policies)
+                byName.set(p.name, [...(byName.get(p.name) ?? []), behaviorFingerprint(p.behavior)]);
+            return new Map([...byName].map(([name, behaviors]) => [name, JSON.stringify(behaviors)]));
+        };
+        const before = behaviorsByName(was);
+        const after = behaviorsByName(next);
+        const removed = [...before.keys()].filter((name) => !after.has(name));
+        for (const name of removed) {
+            this.clearPolicyState(name);
+            this.stats.delete(name);
+        }
+        const cleared = [...after.keys()].filter((name) => before.has(name) && before.get(name) !== after.get(name));
+        for (const name of cleared)
+            this.clearPolicyState(name);
+        for (const name of [...removed, ...cleared])
+            this.fireDebounce(name);
+        return { removed, cleared };
+    }
     reloadIfChanged() {
         const now = Date.now();
-        if (now - this.lastReloadCheck < RELOAD_THROTTLE_MS)
+        if (checkedRecently(now, this.lastReloadCheck))
             return;
         this.lastReloadCheck = now;
         try {
-            if (!existsSync(this.configPath))
-                return;
-            const stat = statSync(this.configPath);
-            if (stat.mtimeMs === this.configMtime)
+            // Missing, unchanged or unreadable: the rules in force stay.
+            const read = this.readConfigFile({ unlessUnchanged: true });
+            // gate.json holds the text in force, so none the start ran is unsaved,
+            // unless what's in force is what the start ran beside it or in its place.
+            if (read.state === 'unchanged' && this.configSource === 'file')
+                this.startUnsaved = null;
+            if (read.state !== 'loaded')
                 return;
-            const newConfig = this.loadConfig();
-            if (!newConfig)
-                return; // Parse error — keep previous config
-            // Capture old policies' behavior fingerprints before any state
-            // mutation — needed to detect kept policies whose parameters changed.
-            const oldBehaviorByName = new Map();
-            for (const p of this.config.policies) {
-                oldBehaviorByName.set(p.name, behaviorFingerprint(p.behavior));
-            }
-            // Clean up state for REMOVED policies (gone from new config entirely).
-            const newPolicyNames = new Set(newConfig.policies.map(p => p.name));
-            const removedPolicies = [];
-            for (const oldName of oldBehaviorByName.keys()) {
-                if (!newPolicyNames.has(oldName)) {
-                    this.clearPolicyState(oldName, { deliverPendingDebounce: true });
-                    this.stats.delete(oldName);
-                    removedPolicies.push(oldName);
-                }
-            }
-            // Clean up state for KEPT policies whose behavior parameters changed.
-            // Without this, a tokens 100→5 edit (or keyBy switch, or every 10→3,
-            // etc.) wouldn't take effect until existing buckets/counters drained.
-            // Stats are preserved — matchCount is historical, not live state.
-            const stateClearedPolicies = [];
-            for (const newPolicy of newConfig.policies) {
-                const oldHash = oldBehaviorByName.get(newPolicy.name);
-                if (oldHash === undefined)
-                    continue; // new policy, no state to clear
-                const newHash = behaviorFingerprint(newPolicy.behavior);
-                if (oldHash !== newHash) {
-                    this.clearPolicyState(newPolicy.name, { deliverPendingDebounce: true });
-                    stateClearedPolicies.push(newPolicy.name);
-                }
-            }
+            const newConfig = read.config;
+            const { removed: removedPolicies, cleared: stateClearedPolicies } = this.clearStateFor(this.config, newConfig);
             this.config = newConfig;
             this.compiledPolicies = this.compilePolicies(newConfig);
+            // Recorded only now that its rules are in force, so a reload that
+            // throws before here is tried again at the next check.
+            this.configText = read.text;
+            this.configNote = read.note;
+            this.configSource = 'file';
+            if (read.note)
+                console.error(`[gate] ${read.note}`);
+            // The rules in force are now gate.json's, so none the start ran is unsaved.
+            this.startUnsaved = null;
             this.lastReloadTimestamp = now;
             this.refreshShadowWarnings('reload');
             this.emitTrace({
@@ -678,7 +2157,7 @@ export class EventGate {
             });
         }
         catch {
-            // Ignore stat errors
+            // The rules in force stay, and the next check tries again.
         }
     }
     // =========================================================================
@@ -687,52 +2166,83 @@ export class EventGate {
     /**
      * 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, options) {
-        const policy = validatePolicy(rawPolicy);
-        const current = this.loadConfig() ?? this.config;
-        const policies = [...current.policies];
-        const idx = policies.findIndex((p) => p.name === policy.name);
+        const reading = readRule(rawPolicy, 'A policy');
+        if (reading.problems.length > 0 || !reading.policy)
+            throw new Error(refusalOf(reading));
+        const policy = reading.policy;
+        const ignored = notesOf(reading);
+        const edit = this.rulesForChange();
+        if ('refused' in edit)
+            throw new Error(edit.refused);
+        const { top, rules, remedy } = edit;
+        const idx = rules.findIndex((rule) => nameOf(rule) === policy.name);
         const position = options?.position;
         if (idx >= 0 && position === undefined) {
-            policies[idx] = policy; // replace in place, order preserved
+            rules[idx] = policy; // replace in place, order preserved
         }
         else {
             if (idx >= 0)
-                policies.splice(idx, 1); // repositioning a known rule
+                rules.splice(idx, 1); // repositioning a known rule
             if (position === 'prepend') {
-                policies.unshift(policy);
+                rules.unshift(policy);
             }
             else if (position !== undefined && typeof position === 'object') {
                 const anchorName = 'before' in position ? position.before : position.after;
-                const anchorIdx = policies.findIndex((p) => p.name === anchorName);
+                const anchorIdx = rules.findIndex((rule) => nameOf(rule) === anchorName);
                 if (anchorIdx < 0) {
                     throw new Error(`addPolicy: no policy named "${anchorName}" to anchor on — `
-                        + `have: [${policies.map((p) => p.name).join(', ')}]`);
+                        + `have: [${rules.map(nameOf).filter((name) => name !== undefined).join(', ')}]`);
                 }
-                policies.splice('before' in position ? anchorIdx : anchorIdx + 1, 0, policy);
+                rules.splice('before' in position ? anchorIdx : anchorIdx + 1, 0, policy);
             }
             else {
-                policies.push(policy);
+                rules.push(policy);
             }
         }
-        this.writeConfig({ ...current, policies });
+        this.writeConfig(top, rules, remedy);
         this.emitTrace({
             type: 'gate:policy-added',
             configPath: this.configPath,
@@ -740,25 +2250,47 @@ export class EventGate {
             replaced: idx >= 0,
             timestamp: Date.now(),
         });
+        if (ignored.length > 0) {
+            // A caller that doesn't take the notes still gets them said, in the log.
+            const onIgnoredFields = options?.onIgnoredFields;
+            if (onIgnoredFields)
+                afterChange('onIgnoredFields', () => onIgnoredFields(ignored));
+            else
+                console.error(`[gate] ${ignored.join(' ')}`);
+        }
         return policy;
     }
     /**
      * 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) {
-        const current = this.loadConfig() ?? this.config;
-        if (!current.policies.some((p) => p.name === name)) {
+        // nameOf gives undefined for a rule with no name, so a call from JavaScript
+        // with no name would otherwise remove every such rule.
+        if (typeof name !== 'string' || name === '')
             return false;
-        }
-        // Deliver any pending debounce batch, then drop timers/buckets/counters.
-        this.clearPolicyState(name, { deliverPendingDebounce: true });
-        this.stats.delete(name);
-        const policies = current.policies.filter((p) => p.name !== name);
-        this.writeConfig({ ...current, policies });
+        const edit = this.rulesForChange();
+        if ('refused' in edit)
+            throw new Error(edit.refused);
+        if (!edit.rules.some((rule) => nameOf(rule) === name))
+            return false;
+        // The write clears the rule's state once it has succeeded (writeConfig),
+        // so a refusal or a failed write leaves the rule in force with its state.
+        this.writeConfig(edit.top, edit.rules.filter((rule) => nameOf(rule) !== name), edit.remedy);
         this.emitTrace({
             type: 'gate:policy-removed',
             configPath: this.configPath,
@@ -768,34 +2300,74 @@ export class EventGate {
         return true;
     }
     /**
-     * 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() {
-        const current = this.loadConfig() ?? this.config;
+        const read = this.readConfigFile({ unlessUnchanged: true });
+        const current = read.state === 'loaded' ? read.config : this.config;
         return current.policies.map((p) => p.name);
     }
     /**
-     * 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.
      */
-    writeConfig(config) {
-        mkdirSync(dirname(this.configPath), { recursive: true });
-        writeFileSync(this.configPath, JSON.stringify(config, null, 2) + '\n');
-        this.config = config;
-        this.compiledPolicies = this.compilePolicies(config);
+    writeConfig(top, rules, remedy) {
+        const text = JSON.stringify({ ...top, policies: rules }, null, 2) + '\n';
+        const read = readConfig(JSON.parse(text), 'gate.json');
+        if ('refused' in read) {
+            throw new Error(`Nothing was saved: with this change, gate.json wouldn't be used. ${sentence(read.refused)}${remedy ? ` ${remedy}` : ''}`);
+        }
+        // One the gate doesn't use, and that a change can mend, holds back what a
+        // rule it leaves out would wake on, so its default holds events back.
+        if (remedy !== undefined && read.config.policies.length === 0) {
+            throw new Error('Nothing was saved: with this change, gate.json would have no rules the gate reads, and its default would hold back every '
+                + `event. Meanwhile the gate runs ${this.rulesRun()}. ${remedy}`);
+        }
+        try {
+            mkdirSync(dirname(this.configPath), { recursive: true });
+            writeFileSync(this.configPath, text);
+        }
+        catch (err) {
+            throw new Error(beforeWriting(err)
+                ? `gate.json couldn't be written (${errorText(err)}), so nothing was saved: the rules in force and gate.json stay `
+                    + 'as they were. Whoever runs this host can fix what keeps it from being written.'
+                : `Writing gate.json failed partway (${errorText(err)}), so the change isn't in force: the rules in force stay as `
+                    + 'they were. gate.json may hold the whole change, which the gate reads at its next reload; or it may hold part of it '
+                    + 'or nothing, which the gate can\'t read, and then they stay until gate.json is fixed. '
+                    + 'Whoever runs this host can fix what kept it from being written, and check what gate.json holds.', { cause: err });
+        }
+        const was = this.config;
+        this.configText = text;
+        this.configNote = loadNote(read.sentences);
+        this.config = read.config;
+        this.compiledPolicies = this.compilePolicies(read.config);
         this.refreshShadowWarnings('policy-mutation');
         this.configSource = 'file';
-        this.configErrors = [];
+        this.configError = this.configNote;
+        this.configUnused = false;
+        this.startUnsaved = null;
         this.lastReloadTimestamp = Date.now();
-        try {
-            this.configMtime = statSync(this.configPath).mtimeMs;
-        }
-        catch {
-            // A failed stat only risks one redundant reload; keep the old mtime.
-        }
+        this.clearStateFor(was, read.config);
     }
     // =========================================================================
     // Policy matching — first match wins (passthrough observers excepted; the
@@ -811,9 +2383,17 @@ export class EventGate {
         if (compiled.sourceRegex && !compiled.sourceRegex.test(info.serverId)) {
             return false;
         }
-        // Channel check
+        // Channel check: the event's own channel id, or the registered id the
+        // gate resolves for its route. A push event carries the adapter's raw id
+        // (`origin.channelId`, or none), and a channels/incoming message the
+        // registered one, so a pattern in the registered form matches every
+        // event in its channel whose push names the channel (by `mcplChannelId`,
+        // or a Discord origin's guild and channel): its messages on both paths,
+        // and its reactions, edits, voice reports and other pushes.
         if (compiled.channelRegex && !compiled.channelRegex.test(info.channelId)) {
-            return false;
+            const registered = this.routeChannelFor(info);
+            if (registered === undefined || !compiled.channelRegex.test(registered))
+                return false;
         }
         // Mount check (workspace fs events)
         if (compiled.mountRegex) {
@@ -883,10 +2463,9 @@ export class EventGate {
         // marker requires too: a `source` in an event's metadata is the server's
         // own word, which any server can give.
         if (this.sleepUntil > this.now()) {
-            this.reloadPrivilegedIfChanged();
             const isHeartbeat = info.serverId === 'heartbeat';
             const authorId = this.extractAuthorId(info.metadata);
-            const privileged = authorId !== null && this.privilegedUserIds.has(authorId);
+            const privileged = this.isPrivilegedUser(authorId);
             if (!isHeartbeat && !privileged) {
                 this.sleepSuppressed++;
                 this.totalEvaluations++;
@@ -1007,17 +2586,25 @@ export class EventGate {
     // =========================================================================
     // rate_limit + passive_sample + resets
     // =========================================================================
-    /** Resolve the partition key for keyBy-style behaviors. */
-    resolveKey(metadata, keyBy) {
+    /** 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. */
+    resolveKey(info, keyBy) {
         if (!keyBy)
             return SHARED_BUCKET_KEY;
-        const value = metadata?.[keyBy];
+        if (keyBy === 'channelId') {
+            const registered = this.routeChannelFor(info);
+            if (registered !== undefined)
+                return registered;
+        }
+        const value = info.metadata?.[keyBy];
         if (value === undefined || value === null || value === '')
             return SHARED_BUCKET_KEY;
         return String(value);
     }
     applyRateLimit(policy, info, config) {
-        const key = this.resolveKey(info.metadata, config.keyBy);
+        const key = this.resolveKey(info, config.keyBy);
         let buckets = this.rateLimitBuckets.get(policy.name);
         if (!buckets) {
             buckets = new Map();
@@ -1031,7 +2618,15 @@ export class EventGate {
         }
         else if (bucket.tokens < config.tokens) {
             const elapsed = now - bucket.lastRefill;
-            if (elapsed > 0) {
+            // A refill interval of 0, read from gate.json or the starting rules
+            // (readRateLimit), refills at once; divided by, it refilled the bucket
+            // once and left its clock at NaN. Under 0, no number of whole intervals
+            // has passed, so it never refills.
+            if (config.refillIntervalMs === 0) {
+                bucket.tokens = config.tokens;
+                bucket.lastRefill = now;
+            }
+            else if (elapsed > 0) {
                 const tokensToAdd = Math.floor(elapsed / config.refillIntervalMs);
                 if (tokensToAdd > 0) {
                     bucket.tokens = Math.min(config.tokens, bucket.tokens + tokensToAdd);
@@ -1053,7 +2648,7 @@ export class EventGate {
         return { trigger: false, policyName: policy.name, behavior: policy.behavior };
     }
     applyPassiveSample(policy, info, config) {
-        const key = this.resolveKey(info.metadata, config.keyBy);
+        const key = this.resolveKey(info, config.keyBy);
         let counters = this.passiveSampleCounters.get(policy.name);
         if (!counters) {
             counters = new Map();
@@ -1083,21 +2678,17 @@ export class EventGate {
         }
     }
     /**
-     * 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.
      */
-    clearPolicyState(name, options) {
+    clearPolicyState(name) {
         const debounce = this.debounceTimers.get(name);
-        if (debounce) {
+        if (debounce)
             clearTimeout(debounce.timer);
-            if (options.deliverPendingDebounce && debounce.events.length > 0) {
-                this.deliverEvents(debounce.events);
-            }
-            this.debounceTimers.delete(name);
-        }
         this.rateLimitBuckets.delete(name);
         this.passiveSampleCounters.delete(name);
         this.rateLimitDenied.delete(name);
@@ -1122,12 +2713,16 @@ export class EventGate {
                 return false; // batches; never triggers inline
             if ('rate_limit' in b) {
                 const cfg = b.rate_limit;
-                const key = this.resolveKey(info.metadata, cfg.keyBy);
+                const key = this.resolveKey(info, cfg.keyBy);
                 const bucket = this.rateLimitBuckets.get(policy.name)?.get(key);
                 if (!bucket)
                     return true; // fresh bucket starts full
+                // As applyRateLimit refills: at once, for an interval of 0, and never
+                // for one under 0.
+                if (cfg.refillIntervalMs === 0)
+                    return true;
                 let tokens = bucket.tokens;
-                if (tokens < cfg.tokens) {
+                if (tokens < cfg.tokens && cfg.refillIntervalMs > 0) {
                     const elapsed = Math.max(0, this.now() - bucket.lastRefill);
                     tokens = Math.min(cfg.tokens, tokens + Math.floor(elapsed / cfg.refillIntervalMs));
                 }
@@ -1135,7 +2730,7 @@ export class EventGate {
             }
             if ('passive_sample' in b) {
                 const cfg = b.passive_sample;
-                const key = this.resolveKey(info.metadata, cfg.keyBy);
+                const key = this.resolveKey(info, cfg.keyBy);
                 const count = this.passiveSampleCounters.get(policy.name)?.get(key) ?? 0;
                 return count + 1 >= cfg.every;
             }
@@ -1161,16 +2756,8 @@ export class EventGate {
         const trigger = (this.config.default ?? 'always') === 'always';
         return { trigger, policyName: null, behavior: this.config.default ?? 'always' };
     }
-    /**
-     * 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
-     * the wake_add_rule result — the point where a rule change's real semantics
-     * 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.
-     */
-    probeTable() {
+    /** The canonical synthetic events the probe table runs: chat shapes as MCPL delivers them, and a heartbeat. */
+    probeEvents() {
         const chat = (label, eventType, metadata, tags) => ({
             label,
             info: {
@@ -1201,7 +2788,32 @@ export class EventGate {
                 },
             },
         ];
-        return probes.map(({ label, info }) => {
+        return probes;
+    }
+    /**
+     * 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() {
+        const events = this.probeEvents().map(({ info }) => info);
+        return this.compiledPolicies
+            .filter((compiled) => !events.some((info) => this.compiledMatches(compiled, info)))
+            .map((compiled) => compiled.policy.name);
+    }
+    /**
+     * 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
+     * the wake_add_rule result — the point where a rule change's real semantics
+     * 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, or on other event types, may not match
+     * any probe; `probeUnreached` names those.
+     */
+    probeTable() {
+        return this.probeEvents().map(({ label, info }) => {
             const d = this.probe(info);
             return {
                 probe: label,
@@ -1294,6 +2906,8 @@ export class EventGate {
             serverId: info.serverId || undefined,
             addressed: Array.isArray(info.tags) && info.tags.includes('chat:addressed'),
             routeChannelId: this.routeChannelFor(info),
+            ...(typeof info.metadata?.messageId === 'string' ? { messageId: info.metadata.messageId } : {}),
+            ...(typeof info.metadata?.eventId === 'string' ? { eventId: info.metadata.eventId } : {}),
         };
         const existing = this.debounceTimers.get(policy.name);
         if (existing) {
@@ -1322,7 +2936,19 @@ export class EventGate {
             this.bufferForInference(events);
             return;
         }
-        this.deliverEvents(events);
+        // A delivery that throws drops the batch, named in the log: thrown from
+        // its timer, it would be uncaught, and stop the process, and thrown to a
+        // write or reload that sends it (clearStateFor), it would report a change
+        // that was made as failed.
+        try {
+            this.deliverEvents(events);
+        }
+        catch (err) {
+            const one = events.length === 1;
+            console.error(`[gate] Policy "${policyName}": its pending batch of ${events.length} ${one ? 'event' : 'events'} couldn't be delivered `
+                + `(${errorText(err)}), so the batch is dropped`);
+            return;
+        }
         this.emitTrace({
             type: 'gate:debounce-delivered',
             policyName,
@@ -1345,48 +2971,94 @@ export class EventGate {
         const quoted = events.filter(e => !e.inContext);
         const referenced = events.filter(e => e.inContext);
         const lines = quoted.map(e => `- [${e.policyName}] (${e.eventType}): ${e.content}`);
+        // How each referenced channel is named in the line, in order.
+        const shown = [];
         if (referenced.length > 0) {
+            // By channel, its server and its id: two servers' channels can share
+            // an id.
             const byChannel = new Map();
             for (const e of referenced) {
                 // The registered id when known, so this line names the channel the
                 // same way routing notices and send tools do (a push event's own
-                // channelId is the adapter's raw id).
-                const key = e.routeChannelId ?? e.channelId ?? '(unknown channel)';
-                const entry = byChannel.get(key) ?? { count: 0, oldest: e.timestamp, label: e.channelLabel };
+                // channelId is the adapter's raw id), shown as the agent names it
+                // back where the event names its server.
+                // Only a registered id is a channel name; an adapter's raw id is
+                // shown as it is.
+                const id = e.routeChannelId ?? e.channelId;
+                const name = id === undefined
+                    ? '(unknown channel)'
+                    : e.routeChannelId !== undefined && e.serverId !== undefined && this.channelShownFn
+                        ? this.channelShownFn({ serverId: e.serverId, channelId: e.routeChannelId })
+                        : id;
+                const key = JSON.stringify([e.serverId ?? null, id ?? null]);
+                const entry = byChannel.get(key) ?? { name, count: 0, oldest: e.timestamp, label: e.channelLabel };
                 entry.count += 1;
                 entry.oldest = Math.min(entry.oldest, e.timestamp);
                 entry.label = entry.label ?? e.channelLabel;
                 byChannel.set(key, entry);
             }
-            for (const [channelId, { count, oldest, label }] of byChannel) {
+            for (const { name, count, oldest, label } of byChannel.values()) {
                 // Prefer the human-readable name; keep the id parenthesized so the
                 // agent can still address tools that want the composite id. A name
                 // may carry its own `#`, so one is added only where the name lacks
                 // it, as at the other places that add a `#`.
-                const channel = label ? `${label.startsWith('#') ? label : `#${label}`} (${channelId})` : channelId;
-                const age = Math.round((Date.now() - oldest) / 1000);
-                lines.push(`- ${count} message${count > 1 ? 's' : ''} in ${channel} ` +
-                    `(oldest ~${age}s ago) — already shown above at arrival; this is a ` +
-                    `batched wake, not new content`);
+                const channel = label ? `${label.startsWith('#') ? label : `#${label}`} (${name})` : name;
+                shown.push(channel);
+                lines.push(referenceLine(count, channel, oldest, Date.now()));
             }
         }
+        // The line says which messages a wake is for. For one message that is
+        // still the newest thing in the window it would be written to, it says
+        // nothing the message right above doesn't. But the turn compiles later,
+        // and what lands in between puts the message above other entries, so the
+        // gate hands the line to the wake (WakeProvenance.line) and a fresh start
+        // of the wake's turn decides it (WakeLine). Several messages, one with
+        // anything after it, or content the line quotes, keep the line now.
         const text = `[Gate: ${events.length} event${events.length > 1 ? 's' : ''} matched]\n\n${lines.join('\n')}`;
-        this.addMessageFn('user', [{ type: 'text', text }], {
-            source: 'gate:debounce',
-            policies: policyNames,
-        });
+        const only = events.length === 1 && events[0].inContext ? events[0] : undefined;
+        let line;
+        if (only && this.newestEntry(only)) {
+            const shownChannel = only.routeChannelId ?? only.channelId;
+            line = {
+                entry: entryRef(only),
+                policyNames,
+                shown: shown[0],
+                at: only.timestamp,
+                ...(shownChannel !== undefined ? { channelId: shownChannel } : {}),
+            };
+        }
+        else {
+            this.addMessageFn('user', [{ type: 'text', text }], {
+                source: 'gate:debounce',
+                policies: policyNames,
+            });
+        }
         // Provenance of the batched wake (who/where woke the agent): the newest
         // ADDRESSED event first, else the newest event naming a channel or an
         // author; channel + author + addressed from that ONE event. When that
         // event addressed the agent and its registered channel is known,
         // `routeChannelId` names the turn's speech locus too — the reply goes
         // back to whoever addressed the agent, not to whichever channel last saw
-        // any traffic. Ambient-only batches carry telemetry only.
-        const provenance = wakeProvenance(events);
+        // any traffic. Ambient-only batches set no locus. A batch whose line the
+        // gate left to the turn's start carries it too (`line`), one object
+        // shared by every agent the batch wakes, so it is written once.
+        const chosen = wakeProvenance(events);
+        const provenance = line ? { ...chosen, line } : chosen;
         for (const agentName of this.getAgentNamesFn()) {
             this.requestInferenceFn(agentName, 'gate:debounce', 'gate', provenance);
         }
     }
+    /** isNewestEntry for one event; a callback fault keeps the line. */
+    newestEntry(event) {
+        if (!this.isNewestEntryFn)
+            return false;
+        try {
+            return this.isNewestEntryFn(entryRef(event)) === true;
+        }
+        catch {
+            return false;
+        }
+    }
     // =========================================================================
     // Inference lifecycle
     // =========================================================================
@@ -1436,8 +3108,19 @@ export class EventGate {
             return;
         if (this.inferring.size === 0 && this.inferenceBuffer.length > 0) {
             const events = this.inferenceBuffer.splice(0);
-            // Defer to avoid re-entrancy inside trace callbacks
-            queueMicrotask(() => this.deliverEvents(events));
+            // Defer to avoid re-entrancy inside trace callbacks. A delivery that
+            // throws drops what was held, named in the log, as fireDebounce drops a
+            // batch: thrown in the microtask, it would be uncaught.
+            queueMicrotask(() => {
+                try {
+                    this.deliverEvents(events);
+                }
+                catch (err) {
+                    const one = events.length === 1;
+                    console.error(`[gate] ${events.length} ${one ? 'event' : 'events'} held for an agent's turn or the host's quiesce couldn't be `
+                        + `delivered (${errorText(err)}), so ${one ? "it's" : "they're"} dropped`);
+                }
+            });
         }
     }
     /** Live inference-gating snapshot for diagnostics (e.g. a SIGUSR2 dump).
@@ -1535,10 +3218,9 @@ export class EventGate {
     }
     /**
      * `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) {
         const selfWake = this.selfWakeTimers.get(agentName);
@@ -1546,8 +3228,6 @@ export class EventGate {
             clearTimeout(selfWake);
             this.selfWakeTimers.delete(agentName);
         }
-        if (this.sleepUntil !== 0 && this.sleepAgent === agentName)
-            this.clearSleep();
     }
     // =========================================================================
     // Self-wake (skip_reply wake_in_seconds)
@@ -1586,12 +3266,16 @@ export class EventGate {
             const nowIso = new Date(this.now()).toISOString().slice(0, 19) + 'Z';
             // Deliver the notice into the WAKING agent's window — a self-wake
             // armed by a non-primary agent (e.g. a subconscious cadence) must not
-            // narrate itself into the primary's context.
+            // narrate itself into the primary's context. Its wake goes with it: an
+            // agent that heard the notice during a turn was awake when its timer
+            // fired, and the host drops the wake once a request that carried the
+            // notice is answered.
+            const placement = {};
             this.addMessageFn('user', [{
                     type: 'text',
                     text: `[self-wake] your ${source} timer (${Math.round(ms / 1000)}s) elapsed — now ${nowIso}`,
-                }], { source: 'gate:self-wake' }, agentName);
-            this.requestInferenceFn(agentName, `self-scheduled wake (${source}, ${Math.round(ms / 1000)}s)`, 'self-wake');
+                }], { source: 'gate:self-wake' }, agentName, placement);
+            this.requestInferenceFn(agentName, `self-scheduled wake (${source}, ${Math.round(ms / 1000)}s)`, 'self-wake', undefined, placement);
         }, ms);
         this.selfWakeTimers.set(agentName, timer);
         this.emitTrace({
@@ -1675,7 +3359,6 @@ export class EventGate {
             return String(metadata.authorId);
         return null;
     }
-    /** 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
@@ -1684,48 +3367,82 @@ export class EventGate {
     isPrivilegedUser(authorId) {
         if (!authorId)
             return false;
-        this.loadPrivileged();
+        this.reloadPrivilegedIfChanged();
         return this.privilegedUserIds.has(authorId);
     }
-    loadPrivileged() {
+    /**
+     * 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.
+     */
+    loadPrivileged(opts) {
         if (!this.privilegedUsersPath)
             return;
+        const failed = (why) => `Failed to load privileged-users file: ${why}`;
+        let raw;
         try {
-            if (!existsSync(this.privilegedUsersPath)) {
+            raw = readFileSync(this.privilegedUsersPath, 'utf8');
+        }
+        catch (err) {
+            // Read again next time: a file can become readable with its text
+            // unchanged, as a chmod makes it.
+            this.privilegedText = undefined;
+            if (isMissing(err)) {
                 this.privilegedUserIds = new Set();
-                this.privilegedMtime = 0;
-                return;
+                this.privilegedError = null;
             }
-            this.privilegedMtime = statSync(this.privilegedUsersPath).mtimeMs;
-            const raw = parseGateJson(readFileSync(this.privilegedUsersPath, 'utf8'));
-            const ids = Array.isArray(raw) ? raw : Array.isArray(raw?.userIds) ? raw.userIds : [];
-            this.privilegedUserIds = new Set(ids.map((x) => String(x)));
+            else {
+                this.privilegedError = failed(err instanceof Error ? err.message : String(err));
+            }
+            return;
+        }
+        if (opts?.unlessUnchanged && raw === this.privilegedText)
+            return;
+        this.privilegedText = raw;
+        let ids;
+        try {
+            const parsed = parseGateJson(raw);
+            ids = Array.isArray(parsed) ? parsed : parsed?.userIds;
         }
         catch (err) {
-            this.configErrors.push(`Failed to load privileged-users file: ${err instanceof Error ? err.message : String(err)}`);
+            this.privilegedError = failed(err instanceof Error ? err.message : String(err));
+            return;
         }
-    }
-    /** Throttled mtime-based reload of the privileged-users file. */
+        // A file that parses but holds no list hasn't loaded either: it used to
+        // mean no one is privileged, without a word.
+        if (!Array.isArray(ids)) {
+            this.privilegedError = failed('expected a list of user ids, or {"userIds": [...]}');
+            return;
+        }
+        const loaded = new Set();
+        const skipped = [];
+        for (const id of ids) {
+            if (typeof id === 'string' && id !== '')
+                loaded.add(id);
+            // JSON.parse has already rounded an integer past 2^53, and the rounded
+            // value can be another user's id, so it's skipped rather than loaded.
+            else if (typeof id === 'number' && Number.isSafeInteger(id))
+                loaded.add(String(id));
+            else
+                skipped.push(id);
+        }
+        this.privilegedUserIds = loaded;
+        this.privilegedError = skipped.length > 0 ? skippedPrivilegedIds(skipped, loaded.size) : null;
+    }
+    /** At most once a second, the privileged-users file read again, and loaded when its text has changed. */
     reloadPrivilegedIfChanged() {
         if (!this.privilegedUsersPath)
             return;
         const now = this.now();
-        if (now - this.lastPrivilegedCheck < RELOAD_THROTTLE_MS)
+        if (checkedRecently(now, this.lastPrivilegedCheck))
             return;
         this.lastPrivilegedCheck = now;
-        try {
-            if (!existsSync(this.privilegedUsersPath)) {
-                if (this.privilegedUserIds.size > 0)
-                    this.privilegedUserIds = new Set();
-                return;
-            }
-            const mtime = statSync(this.privilegedUsersPath).mtimeMs;
-            if (mtime !== this.privilegedMtime)
-                this.loadPrivileged();
-        }
-        catch {
-            /* leave the last-known set in place on a transient stat/read error */
-        }
+        this.loadPrivileged({ unlessUnchanged: true });
     }
     getToolDefinition() {
         return {
@@ -1737,6 +3454,10 @@ export class EventGate {
         };
     }
     async handleToolCall() {
+        // What's in force now: each file read again if a check is due, as the
+        // next event would.
+        this.reloadIfChanged();
+        this.reloadPrivilegedIfChanged();
         const status = this.getStatus();
         return { success: true, data: status };
     }
@@ -1792,7 +3513,8 @@ export class EventGate {
             default: this.config.default ?? 'always',
             script: this.gateScript.status(),
             policies,
-            errors: [...this.configErrors],
+            errors: [this.configErrorShown(), this.startNotice, this.startUnsaved, this.privilegedError]
+                .filter((e) => e !== null),
             shadowWarnings: this.shadowWarningsCache.map(formatShadowWarning),
             totalEvaluations: this.totalEvaluations,
             defaultDecisions: {