@animalabs/agent-framework 0.29.0 → 0.31.0

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

@@ -11,7 +11,7 @@
  * inference tokens, not whether the agent should know about the event.
  */
 import { NOTICE_TAG } from '../notice-tags.js';
-import { cutToFit, suppliedValue } from '../supplied-text.js';
+import { cutToFit, quotedJson, quotedValue, suppliedValue } from '../supplied-text.js';
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { GateScript } from './gate-script.js';
@@ -284,10 +284,10 @@ function beforeWriting(err) {
  * "policies" that isn't a list and holds something. `runs` is what the gate
  * runs meanwhile (rulesRun).
  */
-function noListRefusal(noList, runs) {
+function noListRefusal(noList, runs, path) {
     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.';
+        + `was saved. Meanwhile the gate runs ${runs}. Until gate.json, at ${path}, 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
@@ -295,15 +295,15 @@ function noListRefusal(noList, runs) {
  * 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) {
+function unusableRefusal(unusable, runs, path) {
     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, at ${path}, 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 a file the gate can read; `
+            + '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.';
+    return `gate.json, at ${path}, 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
@@ -313,12 +313,17 @@ function unusableRefusal(unusable, runs) {
  * (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 "
+function notUsedRefusal(runs, path) {
+    return `gate.json, at ${path}, 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.';
 }
+function savedOnlyInForce(path, remedy) {
+    return remedy === undefined
+        ? ''
+        : ` gate.json, at ${path}, isn't in force, and a change is saved only if it brings it into force. ${remedy}`;
+}
 /**
  * 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.
@@ -331,7 +336,8 @@ export function shownValue(value) {
         return String(value);
     let json;
     try {
-        json = JSON.stringify(value) ?? String(value);
+        const stringified = JSON.stringify(value);
+        json = stringified === undefined ? String(value) : quotedJson(stringified);
     }
     catch {
         json = String(value);
@@ -346,9 +352,22 @@ function shownValues(values) {
 function joinedList(items, joiner = 'and') {
     return items.length < 2 ? items.join('') : `${items.slice(0, -1).join(', ')} ${joiner} ${items[items.length - 1]}`;
 }
+const asGateNames = (path) => path;
+function namedBy(names) {
+    if (!names)
+        return asGateNames;
+    return (path) => {
+        for (let end = path.length; end > 0; end = path.lastIndexOf('.', end - 1)) {
+            const head = path.slice(0, end);
+            if (Object.hasOwn(names, head))
+                return `${names[head]}${path.slice(end)}`;
+        }
+        return path;
+    };
+}
 /** `"a"`, `"a" and "b"`, `"a", "b" and "c"` (or "or"). */
 function quotedList(names, joiner = 'and') {
-    return joinedList(names.map((n) => `"${n}"`), joiner);
+    return joinedList(names.map((n) => quotedValue(n)), joiner);
 }
 /** 1st, 2nd, 3rd, 4th, 11th, 21st. */
 function ordinal(n) {
@@ -396,7 +415,7 @@ function fieldNames(obj, fields, held = true) {
 }
 /** `"tags" (did you mean "tagsAny", "tagsAll" or "tagsNone"?)` */
 function slipShown(slip) {
-    return `"${slip.key}" (did you mean ${quotedList(slip.meant, 'or')}?)`;
+    return `${quotedValue(slip.key)} (did you mean ${quotedList(slip.meant, 'or')}?)`;
 }
 /**
  * An object's names that do nothing in its place, split into those that are
@@ -427,21 +446,21 @@ function misplacedShown(m) {
  * 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) {
+function fieldLevels(file, named = asGateNames) {
     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 },
-        { name: '"behavior.judge"', fields: JUDGE_FIELDS },
+        { name: `"${named('behavior.rate_limit')}"`, fields: RATE_LIMIT_FIELDS },
+        { name: `"${named('behavior.passive_sample')}"`, fields: PASSIVE_SAMPLE_FIELDS },
+        { name: `"${named('behavior.judge')}"`, fields: JUDGE_FIELDS },
     ];
 }
 /** Where a name is a field the gate reads, at a level other than the one whose fields are `here`. */
-function homesOf(file, here) {
-    return (key) => fieldLevels(file)
+function homesOf(file, here, named) {
+    return (key) => fieldLevels(file, named)
         .filter((level) => level.fields !== here && level.fields.includes(key))
         .map((level) => level.name);
 }
@@ -573,14 +592,15 @@ const DROPPED = 'so the rule is read without it';
  */
 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);
+    const { misplaced, rest } = placedElsewhere(unread, homesOf(r.file, fields, r.named));
+    const shown = level === null ? null : r.named(level);
+    noteUnread(shown ? `${r.where}: ${shown}` : 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) });
+        r.problems.push({ text: `${shown ?? '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`,
+            text: `${shown ?? 'it'} has ${misplacedShown(m)}, which the gate doesn't read here`,
             read: misplacedReadOf(m) ?? (m.keys.length === 1 ? SLIP_READ : 'so they do nothing'),
         });
     }
@@ -593,7 +613,7 @@ function droppedEntries(count) {
  * 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') {
+function readRule(raw, unnamed, file = 'gate.json', named = asGateNames) {
     if (!isPlainObject(raw)) {
         return {
             where: unnamed,
@@ -603,7 +623,7 @@ function readRule(raw, unnamed, file = 'gate.json') {
         };
     }
     const name = nameOf(raw);
-    const r = { where: name ? `Policy "${name}"` : unnamed, file, problems: [], notes: [] };
+    const r = { where: name ? `Rule ${quotedValue(name)}` : unnamed, file, named, 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) => {
@@ -629,7 +649,7 @@ function readRule(raw, unnamed, file = 'gate.json') {
     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 passthrough = readPassthrough(r, obj.passthrough, kind);
     const reading = {
         where: r.where, problems: r.problems, notes: r.notes, quiet: kind === 'skip' || kind === 'defer' || r.noTokens === true,
     };
@@ -685,7 +705,7 @@ function readBehavior(r, value) {
     }
     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: [] };
+        const unread = { where: r.where, file: r.file, named: r.named, 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}"` });
@@ -701,18 +721,18 @@ function readBehavior(r, value) {
  */
 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` });
+        r.problems.push({ text: `${r.named('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`,
+            text: `${r.named('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`,
+            text: `${r.named('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 };
     }
@@ -734,11 +754,11 @@ function readDebounce(r, ms) {
 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}`,
+            text: `${r.named('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' });
+    const conf = withoutEmpty(`${r.where}: ${r.named('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;
@@ -746,17 +766,17 @@ function readRateLimit(r, value) {
     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` });
+        r.problems.push({ text: `${r.named('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`,
+            text: `${r.named('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`,
+            text: `${r.named('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",
@@ -777,15 +797,15 @@ function readRateLimit(r, value) {
  */
 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}` });
+        r.problems.push({ text: `${r.named('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' });
+    const conf = withoutEmpty(`${r.where}: ${r.named('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` });
+        r.problems.push({ text: `${r.named('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;
@@ -793,7 +813,7 @@ function readPassiveSample(r, value) {
     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'}`,
+            text: `${r.named('behavior.passive_sample.every')} is ${given}, ${given <= 0 ? 'under 1' : 'not a whole number'}`,
             read: `so it's read as ${every}`,
         });
     }
@@ -817,11 +837,11 @@ function readPassiveSample(r, value) {
 function readJudge(r, value) {
     if (!isPlainObject(value)) {
         r.problems.push({
-            text: `behavior.judge is ${shownValue(value)}, where an object is needed, such as {"debounceMs": 30000, "instructions": "..."}`,
+            text: `${r.named('behavior.judge')} is ${shownValue(value)}, where an object is needed, such as {"debounceMs": 30000, "instructions": "..."}`,
         });
         return undefined;
     }
-    const conf = withoutEmpty(`${r.where}: behavior.judge`, value, r.notes, {
+    const conf = withoutEmpty(`${r.where}: ${r.named('behavior.judge')}`, value, r.notes, {
         maxWaitMs: 'a batch is judged only after its quiet period',
         instructions: 'the judge decides without the agent\'s word',
     });
@@ -830,18 +850,18 @@ function readJudge(r, value) {
     const ms = conf.debounceMs;
     let debounceMs;
     if (typeof ms !== 'number' || !Number.isFinite(ms)) {
-        r.problems.push({ text: `behavior.judge.debounceMs is ${shownValue(ms)}, where a number of milliseconds is needed, such as 30000` });
+        r.problems.push({ text: `${r.named('behavior.judge.debounceMs')} is ${shownValue(ms)}, where a number of milliseconds is needed, such as 30000` });
         ok = false;
     }
     else if (ms < MIN_DEBOUNCE_MS) {
         r.problems.push({
-            text: `behavior.judge.debounceMs is ${ms} ms, under the ${MIN_DEBOUNCE_MS} ms minimum`, read: `so it's read as ${MIN_DEBOUNCE_MS} ms`,
+            text: `${r.named('behavior.judge.debounceMs')} is ${ms} ms, under the ${MIN_DEBOUNCE_MS} ms minimum`, read: `so it's read as ${MIN_DEBOUNCE_MS} ms`,
         });
         debounceMs = MIN_DEBOUNCE_MS;
     }
     else if (ms > MAX_DEBOUNCE_MS) {
         r.problems.push({
-            text: `behavior.judge.debounceMs is ${ms} ms, over the ${MAX_DEBOUNCE_MS} ms maximum`, read: `so it's read as ${MAX_DEBOUNCE_MS} ms`,
+            text: `${r.named('behavior.judge.debounceMs')} is ${ms} ms, over the ${MAX_DEBOUNCE_MS} ms maximum`, read: `so it's read as ${MAX_DEBOUNCE_MS} ms`,
         });
         debounceMs = MAX_DEBOUNCE_MS;
     }
@@ -852,21 +872,21 @@ function readJudge(r, value) {
     const wait = conf.maxWaitMs;
     if (wait !== undefined) {
         if (typeof wait !== 'number' || !Number.isFinite(wait)) {
-            r.problems.push({ text: `behavior.judge.maxWaitMs is ${shownValue(wait)}, where a number of milliseconds is needed, such as 120000` });
+            r.problems.push({ text: `${r.named('behavior.judge.maxWaitMs')} is ${shownValue(wait)}, where a number of milliseconds is needed, such as 120000` });
             ok = false;
         }
         else {
             const floor = debounceMs ?? MIN_DEBOUNCE_MS;
             if (wait < floor) {
                 r.problems.push({
-                    text: `behavior.judge.maxWaitMs is ${wait} ms, under the rule's ${floor} ms quiet period`,
+                    text: `${r.named('behavior.judge.maxWaitMs')} is ${wait} ms, under the rule's ${floor} ms quiet period`,
                     read: `so it's read as ${floor} ms`,
                 });
                 maxWaitMs = floor;
             }
             else if (wait > MAX_JUDGE_WAIT_MS) {
                 r.problems.push({
-                    text: `behavior.judge.maxWaitMs is ${wait} ms, over the ${MAX_JUDGE_WAIT_MS} ms maximum`,
+                    text: `${r.named('behavior.judge.maxWaitMs')} is ${wait} ms, over the ${MAX_JUDGE_WAIT_MS} ms maximum`,
                     read: `so it's read as ${MAX_JUDGE_WAIT_MS} ms`,
                 });
                 maxWaitMs = MAX_JUDGE_WAIT_MS;
@@ -880,12 +900,12 @@ function readJudge(r, value) {
     let instructions;
     if (said !== undefined) {
         if (typeof said !== 'string') {
-            r.problems.push({ text: `behavior.judge.instructions is ${shownValue(said)}, where text is needed` });
+            r.problems.push({ text: `${r.named('behavior.judge.instructions')} is ${shownValue(said)}, where text is needed` });
             ok = false;
         }
         else if (said.length > MAX_JUDGE_INSTRUCTIONS) {
             r.problems.push({
-                text: `behavior.judge.instructions is ${said.length} characters long, over the ${MAX_JUDGE_INSTRUCTIONS}-character maximum`,
+                text: `${r.named('behavior.judge.instructions')} is ${said.length} characters long, over the ${MAX_JUDGE_INSTRUCTIONS}-character maximum`,
             });
             ok = false;
         }
@@ -916,7 +936,7 @@ function readKeyBy(r, kind, value) {
     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"`,
+        text: `${r.named(`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;
@@ -1040,7 +1060,10 @@ function readMatch(r, value) {
                     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)})` });
+                    r.problems.push({
+                        text: `match.filter.pattern isn't a regular expression the gate can read (${quotedValue(errorText(e))}), so fix it, `
+                            + 'or give match.filter.type "text" to look for the pattern as plain text',
+                    });
                 }
             }
         }
@@ -1081,7 +1104,7 @@ function readResets(r, value) {
  * 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) {
+function readPassthrough(r, value, kind) {
     if (value === undefined || value === false)
         return false;
     if (value !== true) {
@@ -1090,9 +1113,10 @@ function readPassthrough(r, value, behavior, kind) {
     }
     if (kind === undefined || kind === 'rate_limit' || kind === 'passive_sample')
         return true;
+    const given = kind === 'always' || kind === 'defer' || kind === 'skip' ? `behavior "${kind}"` : r.named(`behavior.${kind}`);
     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',
+        text: `passthrough is true, and only a ${r.named('behavior.rate_limit')} or ${r.named('behavior.passive_sample')} rule passes on `
+            + `an event it matches without waking on it; with ${given}, leave passthrough out`,
     });
     return false;
 }
@@ -1223,7 +1247,7 @@ function readConfig(raw, file, start) {
             + `[{"name": "my-rule", "behavior": "always"}], and ${noRules}.`);
     }
     const rules = policies.map((rule, i) => {
-        const reading = readRule(rule, `The ${ordinal(i + 1)} policy`, file);
+        const reading = readRule(rule, `The ${ordinal(i + 1)} rule`, file);
         return { raw: rule, reading, outcome: ruleOutcome(reading) };
     });
     if (defaultBehavior !== 'always') {
@@ -1294,7 +1318,7 @@ function readLastRecipe(path) {
     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: null, problem: `it names the rule ${quotedValue(twice)} twice` };
     return { recipe: { rules, default: isPlainObject(raw) ? raw.default : undefined } };
 }
 /**
@@ -1303,7 +1327,7 @@ function readLastRecipe(path) {
  * wrote as read agrees with the same rule written more briefly.
  */
 function ruleMeaning(rule) {
-    const reading = readRule(rule, 'A policy');
+    const reading = readRule(rule, 'A rule');
     return reading.policy ? `read ${canonical(reading.policy)}` : `written ${canonical(rule)}`;
 }
 /**
@@ -1377,7 +1401,7 @@ function notUsedClause(write, starting) {
  */
 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 left = [...(write.leftOut ?? []).map((name) => quotedValue(name)), ...(nameless === 0 ? [] : [nameless === 1 ? 'one with no name' : `${nameless} with no name`])];
     const held = write.heldOut ?? [];
     const said = [];
     const fix = [];
@@ -1605,14 +1629,14 @@ export function findShadowedPolicies(policies, eventTypesFrom) {
  *  three it is (the rule never applies; it misses some of its events; it
  *  may not be meant for those events at all) and what to do. */
 export function formatShadowWarning(w) {
-    const later = `"${w.later}"`;
-    const earlier = `"${w.earlier}"`;
-    const move = `move ${later} above ${earlier} (wake_add_rule with the whole rule and insertBefore: "${w.earlier}")`;
+    const later = quotedValue(w.later);
+    const earlier = quotedValue(w.earlier);
+    const move = `move ${later} above ${earlier} (wake_add_rule with the whole rule and insertBefore: ${quotedValue(w.earlier)})`;
     if (w.whole) {
         return `${later} never applies: ${earlier} comes first and matches every event ${later} would. `
             + `If ${later} should apply, ${move}, or narrow ${earlier}.`;
     }
-    const types = w.eventTypes === 'all' ? 'all' : w.eventTypes.join(', ');
+    const types = w.eventTypes === 'all' ? 'all' : w.eventTypes.map((type) => quotedValue(type).slice(1, -1)).join(', ');
     if (w.known) {
         return `${earlier} comes first and takes ${later}'s ${types} events, so ${later} applies only to its others. `
             + `If it should apply to those too, ${move}.`;
@@ -1644,20 +1668,23 @@ function afterChange(name, callback) {
     }
 }
 /** The privileged-users file's error when some entries of its list aren't user ids. */
-function skippedPrivilegedIds(skipped, loaded) {
+function skippedPrivilegedIds(skipped, loaded, path) {
     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);
+        const json = quotedValue(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"}, `
+    const rest = loaded === 0
+        ? 'no id loaded, so no one is privileged'
+        : `the ${loaded === 1 ? 'one id that did load is' : `${loaded} ids that did load are`} privileged`;
+    return `${skipped.length} ${one ? 'entry' : 'entries'} in the privileged-users file, at ${path}, ${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}.`;
+        + `(a whole number within 2^53 - 1 of zero); ${rest}. Once ${one ? 'that entry is a user id' : 'those entries are user ids'}, the gate `
+        + 'reads the file again at its next check for changes.';
 }
 // ---------------------------------------------------------------------------
 // EventGate
@@ -1687,6 +1714,7 @@ export class EventGate {
     /** 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;
+    configFix = null;
     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
@@ -1759,8 +1787,8 @@ export class EventGate {
     sleepSuppressed = 0;
     sleepTimer = null;
     sleepAgent;
-    // From dispose() to the next resumeSleep(): no sleep or self-wake timer is
-    // armed, though a turn a failed stop() left running can still ask for one.
+    // From dispose() on, no sleep or self-wake timer is armed, though a turn a
+    // failed stop() left running can still ask for one.
     disposed = false;
     // Self-wake timers per agent (skip_reply's wake_in_seconds). Unlike sleep,
     // a self-wake suppresses NOTHING — it means "if nothing else wakes me by
@@ -1785,6 +1813,8 @@ export class EventGate {
     addMessageFn;
     requestInferenceFn;
     getAgentNamesFn;
+    /** Delivery-time re-check: is this channel held from the recipients now? */
+    isHeldFn;
     resolveRouteChannelFn;
     channelShownFn;
     isNewestEntryFn;
@@ -1798,6 +1828,7 @@ export class EventGate {
         this.addMessageFn = opts.addMessage;
         this.requestInferenceFn = opts.requestInference;
         this.getAgentNamesFn = opts.getAgentNames;
+        this.isHeldFn = opts.isHeld ?? (() => false);
         this.resolveRouteChannelFn = opts.resolveRouteChannel ?? defaultRouteChannel;
         this.channelShownFn = opts.channelShown;
         this.isNewestEntryFn = opts.isNewestEntry;
@@ -1923,7 +1954,7 @@ export class EventGate {
             }
             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 `
+                this.startMergeNote = `At start, the recipe names the rule ${quotedValue(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.';
             }
@@ -2119,8 +2150,10 @@ export class EventGate {
             raw = readFileSync(this.configPath, 'utf-8');
         }
         catch (err) {
-            if (!isMissing(err))
-                return this.configUnreadable(err);
+            if (!isMissing(err)) {
+                const why = quotedValue(errorText(err));
+                return this.configUnreadable(why, `gate.json, at ${this.configPath}, can't be read: ${why}`, 'Whoever runs this host can make it a file the gate can read, and the gate reads it again at its next check for changes.');
+            }
             // No file is no problem with it: the rules in force stay.
             this.configError = null;
             this.configUnused = false;
@@ -2140,12 +2173,22 @@ export class EventGate {
             parsed = parseGateJson(raw);
         }
         catch (err) {
-            return { ...this.configUnreadable(err), notJson: true };
+            const why = quotedValue(errorText(err));
+            return {
+                ...this.configUnreadable(why, `gate.json, at ${this.configPath}, isn't JSON: ${why}`, "Once it's JSON, the gate reads it again at its next check for changes."),
+                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 };
+            const problem = read.refused.startsWith('gate.json ')
+                ? `gate.json, at ${this.configPath},${read.refused.slice('gate.json'.length)}`
+                : read.refused;
+            return {
+                ...this.configUnreadable(read.refused, problem, 'Once gate.json is mended, the gate reads it again at its next check for changes.'),
+                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.
@@ -2158,20 +2201,20 @@ export class EventGate {
      * 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`);
+    configUnreadable(why, problem, fix = null) {
+        if (problem !== this.configError) {
+            console.error(`[gate] ${this.configPath} couldn't be used (${why}), so what it holds isn't in force${fix ? `. ${fix}` : ''}`);
             this.emitTrace({
                 type: 'gate:config-error',
-                error: msg,
+                error: why,
                 configPath: this.configPath,
                 timestamp: Date.now(),
             });
         }
-        this.configError = msg;
+        this.configError = problem;
+        this.configFix = fix;
         this.configUnused = true;
-        return { state: 'unreadable', error: msg };
+        return { state: 'unreadable', error: why };
     }
     /**
      * gate.json's error as gate_status shows it: one that keeps what the file
@@ -2180,7 +2223,8 @@ export class EventGate {
     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()}.`;
+        return `${sentence(this.configError)} So what gate.json holds isn't in force, and the gate runs ${this.rulesRun()}.`
+            + (this.configFix ? ` ${this.configFix}` : '');
     }
     /** What the gate runs, by where its rules came from, for a text that says so: "the host's starting rules". */
     rulesRun() {
@@ -2223,14 +2267,14 @@ export class EventGate {
     rulesForChange() {
         const read = this.readConfigFile();
         if (read.state === 'unreadable')
-            return { refused: unusableRefusal(read, this.rulesRun()) };
+            return { refused: unusableRefusal(read, this.rulesRun(), this.configPath) };
         if (read.state === 'loaded' || read.state === 'refused') {
             if ('noList' in read.listed)
-                return { refused: noListRefusal(read.listed.noList, this.rulesRun()) };
+                return { refused: noListRefusal(read.listed.noList, this.rulesRun(), this.configPath) };
             // 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()) };
+                return { refused: notUsedRefusal(this.rulesRun(), this.configPath) };
             }
             const edit = { top: read.listed.top, rules: [...read.listed.rules] };
             if (read.state === 'loaded')
@@ -2248,9 +2292,9 @@ export class EventGate {
             return {
                 ...edit,
                 remedy: sharing === 1
-                    ? `${removes ? 'Replacing or removing' : 'Replacing'} "${only}" by name would bring gate.json into force.`
+                    ? `${removes ? 'Replacing or removing' : 'Replacing'} ${quotedValue(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`
+                        ? `gate.json has ${sharing} rules named ${quotedValue(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.',
@@ -2424,7 +2468,8 @@ export class EventGate {
      * part-written.
      */
     addPolicy(rawPolicy, options) {
-        const reading = readRule(rawPolicy, 'A policy');
+        const named = namedBy(options?.fieldNames);
+        const reading = readRule(rawPolicy, 'A rule', 'gate.json', named);
         if (reading.problems.length > 0 || !reading.policy)
             throw new Error(refusalOf(reading));
         const policy = reading.policy;
@@ -2448,8 +2493,23 @@ export class EventGate {
                 const anchorName = 'before' in position ? position.before : position.after;
                 const anchorIdx = rules.findIndex((rule) => nameOf(rule) === anchorName);
                 if (anchorIdx < 0) {
-                    throw new Error(`addPolicy: no policy named "${anchorName}" to anchor on — `
-                        + `have: [${rules.map(nameOf).filter((name) => name !== undefined).join(', ')}]`);
+                    const field = named('before' in position ? 'position.before' : 'position.after');
+                    const others = [...new Set(rules.map(nameOf).filter((name) => name !== undefined))];
+                    if (idx >= 0 && anchorName === policy.name) {
+                        throw new Error(`${reading.where} wasn't saved: ${field} is ${quotedValue(anchorName)}, the rule being saved, and a rule can't be `
+                            + 'placed beside itself. '
+                            + (others.length > 0
+                                ? `The other rules are ${quotedList(others)}. Give ${field} one of those to place the rule beside it, or leave it out`
+                                : `There are no other rules, so leave ${field} out`)
+                            + ' to replace the rule where it is.'
+                            + savedOnlyInForce(this.configPath, remedy));
+                    }
+                    throw new Error(`${reading.where} wasn't saved: ${field} is ${quotedValue(anchorName)}, and no rule has that name. `
+                        + (others.length > 0
+                            ? `The other rules are ${quotedList(others)}. Give ${field} one of those to place the rule beside it, or leave it out`
+                            : `There are no other rules, so leave ${field} out`)
+                        + ' to add the rule at the end, or, where a rule already has its name, to replace that rule where it is.'
+                        + savedOnlyInForce(this.configPath, remedy));
                 }
                 rules.splice('before' in position ? anchorIdx : anchorIdx + 1, 0, policy);
             }
@@ -2525,6 +2585,16 @@ export class EventGate {
         const current = read.state === 'loaded' ? read.config : this.config;
         return current.policies.map((p) => p.name);
     }
+    /** @internal For `wake_add_rule`'s and `wake_remove_rule`'s refusals; not a host API. */
+    ruleNamesForChange() {
+        const edit = this.rulesForChange();
+        if ('refused' in edit)
+            return { refused: edit.refused };
+        return {
+            names: [...new Set(edit.rules.map(nameOf).filter((name) => name !== undefined))],
+            note: savedOnlyInForce(this.configPath, edit.remedy),
+        };
+    }
     /**
      * 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
@@ -2550,13 +2620,14 @@ export class EventGate {
         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}` : ''}`);
+            throw new Error(`Nothing was saved: with this change, gate.json, at ${this.configPath}, 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}`);
+            throw new Error(`Nothing was saved: with this change, gate.json, at ${this.configPath}, 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 });
@@ -3187,7 +3258,7 @@ export class EventGate {
         }
         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 `
+            console.error(`[gate] Rule ${quotedValue(policyName)}: its pending batch of ${events.length} ${one ? 'event' : 'events'} couldn't be delivered `
                 + `(${errorText(err)}), so the batch is dropped`);
             return;
         }
@@ -3201,7 +3272,23 @@ export class EventGate {
     // =========================================================================
     // Event delivery
     // =========================================================================
-    deliverEvents(events) {
+    deliverEvents(batched) {
+        // Delivery-time re-check: a channel tuned out after its events were
+        // batched is held now, and "already shown above at arrival" would be
+        // untrue of them. They are dropped; the hold's own reader has them.
+        const heldAt = (e) => e.routeChannelId ?? e.channelId;
+        const events = batched.filter((e) => {
+            const channel = heldAt(e);
+            return !(channel && this.isHeldFn(e.serverId, channel));
+        });
+        if (events.length < batched.length) {
+            this.emitTrace({
+                type: 'gate:held-dropped',
+                dropped: batched.length - events.length,
+                channels: [...new Set(batched.filter((e) => !events.includes(e)).map(heldAt))],
+                timestamp: this.now(),
+            });
+        }
         if (events.length === 0)
             return;
         const policyNames = [...new Set(events.map(e => e.policyName))];
@@ -3361,7 +3448,7 @@ export class EventGate {
             if (state.timer)
                 clearTimeout(state.timer);
         }).catch((err) => {
-            console.error(`[gate] Policy "${policyName}": the judge's verdict couldn't be applied (${errorText(err)})`);
+            console.error(`[gate] Rule ${quotedValue(policyName)}: the judge's verdict couldn't be applied (${errorText(err)})`);
         });
     }
     /** Hold a batch for the judge until no turn changing the context it reads
@@ -3429,8 +3516,8 @@ export class EventGate {
             const n = state.events.length;
             const batch = `${n} ${n === 1 ? 'event' : 'events'}`;
             wakes.push(state.judge
-                ? { at: state.dueAt, certain: false, what: `rule "${name}"'s batch of ${batch} goes to the judge` }
-                : { at: state.dueAt, certain: true, what: `rule "${name}"'s debounced batch of ${batch}` });
+                ? { at: state.dueAt, certain: false, what: `rule ${quotedValue(name)}'s batch of ${batch} goes to the judge` }
+                : { at: state.dueAt, certain: true, what: `rule ${quotedValue(name)}'s debounced batch of ${batch}` });
         }
         return wakes.sort((a, b) => (a.at ?? 0) - (b.at ?? 0));
     }
@@ -3480,7 +3567,7 @@ export class EventGate {
         const failed = verdict == null || typeof verdict !== 'object' || typeof verdict.reply !== 'boolean';
         if (failed && err?.providerAdmission === 'deferred') {
             const wakes = this.judgeOnError === 'wake';
-            console.error(`[gate] Policy "${policyName}": the reply judge made no call (${errorText(err)}), so its batch of ${state.events.length} `
+            console.error(`[gate] Rule ${quotedValue(policyName)}: the reply judge made no call (${errorText(err)}), so its batch of ${state.events.length} `
                 + `${state.events.length === 1 ? 'event' : 'events'} ${wakes ? 'wakes the agent' : "doesn't wake the agent"} (judge onError "${this.judgeOnError}")`);
             if (this.disposed)
                 return;
@@ -3515,7 +3602,7 @@ export class EventGate {
         }
         const wake = outcome === 'reply' || (outcome === 'error' && this.judgeOnError === 'wake');
         if (failed) {
-            console.error(`[gate] Policy "${policyName}": the reply judge failed (${reason}), so its batch of ${state.events.length} `
+            console.error(`[gate] Rule ${quotedValue(policyName)}: the reply judge failed (${reason}), so its batch of ${state.events.length} `
                 + `${state.events.length === 1 ? 'event' : 'events'} ${wake ? 'wakes the agent' : "doesn't wake the agent"} (judge onError "${this.judgeOnError}")`);
         }
         this.emitTrace({
@@ -3606,11 +3693,10 @@ export class EventGate {
     }
     /** A turn that continues another (a budget restart, a tool-result-guard
      *  retry) holds the entry its predecessor kept for it, and takes it again
-     *  where that entry ended in between: at a stop(), whose dispose() clears
-     *  every entry, or at a provider hold that kept the turn from starting,
-     *  whose end queues it again. Unlike onInferenceStarted it leaves a
-     *  pending self-wake alone: the logical turn that armed it is the one
-     *  still running. */
+     *  where that entry ended in between, as at a provider hold that kept the
+     *  turn from starting, whose end queues it again. Unlike
+     *  onInferenceStarted it leaves a pending self-wake alone: the logical
+     *  turn that armed it is the one still running. */
     onInferenceResumed(agentName) {
         this.inferring.add(agentName);
         if (this.changesJudgedContext(agentName))
@@ -3720,7 +3806,7 @@ export class EventGate {
         // Arm the self-wake: when the window elapses, clear sleep and request an
         // inference so the agent resumes on its own (not dependent on a heartbeat
         // tick or an incoming message). Cancelled by clearSleep()/`wake`, and by
-        // dispose(), after which start() arms it again (resumeSleep).
+        // dispose(), after which nothing arms it.
         this.armSleepWake();
         this.reloadPrivilegedIfChanged();
         this.emitTrace({
@@ -3733,25 +3819,11 @@ export class EventGate {
         });
         return { until: this.sleepUntil };
     }
-    /**
-     * Arm timers again for a lifecycle that starts after a stop(), and the
-     * sleep's wake first: dispose() clears its timer and keeps the sleep. A
-     * sleep still ahead wakes the agent at its end; one that ended while
-     * stopped wakes it now, since that wake is what the agent asked for. With
-     * no sleep, wakeFromSleep does nothing.
-     */
-    resumeSleep() {
-        this.disposed = false;
-        if (this.sleepUntil > this.now())
-            this.armSleepWake();
-        else
-            this.wakeFromSleep('sleep-expired');
-    }
     /**
      * Arm the sleep's wake for its end by the gate's own clock. One timer holds
      * at most MAX_TIMER_MS, about 24.8 days, so a longer sleep waits in steps,
      * and wakeFromSleep reads the clock as each one fires. Nothing is armed
-     * while the gate is disposed: resumeSleep() arms it at the next start().
+     * once the gate is disposed.
      */
     armSleepWake() {
         if (this.sleepTimer) {
@@ -3764,10 +3836,9 @@ export class EventGate {
         this.sleepTimer = setTimeout(() => this.wakeFromSleep('sleep-expired'), Math.min(remaining, MAX_TIMER_MS));
     }
     /**
-     * `agentName` is gone, as a conversation fork's end or an ephemeral run's
-     * 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`).
+     * `agentName` is gone, as an agent's end removes one: its pending
+     * self-wake is cancelled, and a sleep it set ends, rather than go on
+     * quieting every agent and then wake a name that no longer exists.
      */
     agentGone(agentName) {
         const selfWake = this.selfWakeTimers.get(agentName);
@@ -3775,6 +3846,8 @@ export class EventGate {
             clearTimeout(selfWake);
             this.selfWakeTimers.delete(agentName);
         }
+        if (this.sleepAgent === agentName)
+            this.clearSleep();
     }
     // =========================================================================
     // Self-wake (skip_reply wake_in_seconds)
@@ -3858,9 +3931,7 @@ export class EventGate {
      * fires early (Node's can, by a millisecond), or a clock set back.
      */
     wakeFromSleep(reason) {
-        // The timer that called it has fired; from resumeSleep(), for a sleep
-        // already over, one may still be armed, and it goes, so no stale step of
-        // it can fire later.
+        // The timer that called it has fired.
         if (this.sleepTimer) {
             clearTimeout(this.sleepTimer);
             this.sleepTimer = null;
@@ -3923,15 +3994,21 @@ export class EventGate {
      * 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
+     * (none, at startup), with its error in gate_status until a later read
+     * loads it, finds it gone, or fails another way. 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}`;
+        const file = `The privileged-users file, at ${this.privilegedUsersPath},`;
+        const held = this.privilegedUserIds.size;
+        const meanwhile = held === 0
+            ? 'no one is privileged'
+            : `${held === 1 ? 'the one id of the list that last loaded stays' : `the ${held} ids of the list that last loaded stay`} privileged`;
+        const revoke = 'Replacing it with a file holding [], or removing it, makes no one privileged at the gate\'s next check for changes.';
+        const failed = (problem, fix) => `${file} ${problem}, so ${meanwhile}. ${fix} ${revoke}`;
         let raw;
         try {
             raw = readFileSync(this.privilegedUsersPath, 'utf8');
@@ -3945,26 +4022,27 @@ export class EventGate {
                 this.privilegedError = null;
             }
             else {
-                this.privilegedError = failed(err instanceof Error ? err.message : String(err));
+                this.privilegedError = failed(`can't be read: ${quotedValue(errorText(err))}`, 'Whoever runs this host can make it a file the gate can read, and the gate reads it again at its next check for changes.');
             }
             return;
         }
         if (opts?.unlessUnchanged && raw === this.privilegedText)
             return;
         this.privilegedText = raw;
+        const fixed = 'Once it holds a list of user ids, the gate loads it at its next check for changes.';
         let ids;
         try {
             const parsed = parseGateJson(raw);
             ids = Array.isArray(parsed) ? parsed : parsed?.userIds;
         }
         catch (err) {
-            this.privilegedError = failed(err instanceof Error ? err.message : String(err));
+            this.privilegedError = failed(`isn't JSON: ${quotedValue(errorText(err))}`, fixed);
             return;
         }
         // 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": [...]}');
+            this.privilegedError = failed('holds no list of user ids, where one is needed, such as ["123"] or {"userIds": ["123"]}', fixed);
             return;
         }
         const loaded = new Set();
@@ -3980,7 +4058,7 @@ export class EventGate {
                 skipped.push(id);
         }
         this.privilegedUserIds = loaded;
-        this.privilegedError = skipped.length > 0 ? skippedPrivilegedIds(skipped, loaded.size) : null;
+        this.privilegedError = skipped.length > 0 ? skippedPrivilegedIds(skipped, loaded.size, this.privilegedUsersPath) : null;
     }
     /** At most once a second, the privileged-users file read again, and loaded when its text has changed. */
     reloadPrivilegedIfChanged() {
@@ -4134,9 +4212,9 @@ export class EventGate {
         this.selfWakeDue.clear();
         // The sleep stays, with its note and agent, and its timer goes: fired
         // after a stop(), its wake reached a framework that had stopped, and the
-        // timer held the process until the sleep's end. The next start() arms it
-        // again (resumeSleep). Until then nothing arms one, nor a self-wake: a
-        // turn a failed stop() left running can still call sleep or skip_reply.
+        // timer held the process until the sleep's end. Nothing arms one after
+        // this, nor a self-wake: a turn a failed stop() left running can still
+        // call sleep or skip_reply.
         if (this.sleepTimer) {
             clearTimeout(this.sleepTimer);
             this.sleepTimer = null;
@@ -4149,13 +4227,9 @@ export class EventGate {
         this.inferenceBuffer = [];
         // stop() disposes the gate once its streams and event loop have ended (a
         // turn still compiling then is dropped at its next check, before it sends
-        // anything), and a start() goes on with this gate. An agent left here by
-        // a turn whose exit didn't end it (a retry stop() cancelled, a successor
-        // stop() refused) would make every debounced batch buffer until that
-        // agent's next turn ended. A turn that continues after the start() takes
-        // its entry again (onInferenceResumed). A start() made during the stop()
-        // is refused, so no turn of a new lifecycle can have begun before this
-        // runs.
+        // anything). An agent left here by a turn whose exit didn't end it (a
+        // retry stop() cancelled, a successor stop() refused) would make every
+        // debounced batch buffer until that agent's next turn ended.
         this.inferring.clear();
     }
 }