[nissa-seru]

TL;DR: every problem a wake rule has is now named. A typo in its behavior, a match field of the wrong type, a misspelled field name and a field put at the wrong level each used to change what the rule does without a word. wake_add_rule and addGatePolicy refuse such a rule, naming every problem, and save nothing. gate.json and the host's starting rules are what a deployment already runs, so there a rule with a problem is read the way the gate read it before, and named, and the rest of the file loads: wherever the gate loaded the file before, no event that woke the agent goes quiet. A rule is left out only where the gate refused it before. Under a "skip" or "defer" default, a file that would leave out a rule that could wake the agent isn't used, as before.

Problem

Each of these was silent, in gate.json and through wake_add_rule alike. We met them while rewording the gate's messages, and checked each with a probe at main (92125b07) with membrane 0.5.87.

• A behavior the gate doesn't know was saved as "always", a rule that wakes on every event it matches. validatePolicy's last else covered any behavior that isn't "always", "defer", "skip" or an object, so a typo such as "deffer" gave "always". So did the object form in membrane's XML tool mode, which parses a parameter by its declared type: wake_add_rule declares behavior a string, so the description's own example, behavior: { debounce: 60000 }, arrived as the text {"debounce": 60000}.
• A match field of the wrong type was dropped, so the rule matched everything that field was meant to narrow. { match: { tagsAny: "chat:ambient" }, behavior: "skip" } was saved as match: {}, a rule that skips every event, DMs and mentions included. The same went for scope as a string, channel as a number, match as a string, and a filter whose type isn't text or regex.
• A misspelled field was ignored, so the field meant was missing. pasthrough: true gave a governor that consumes the events it should let fall through. keyby gave one rate-limit bucket for every channel, and polices in gate.json gave no rules at all. wake_add_rule took its own parameters by name, so a misspelled one was dropped the same way.
• A field at the wrong level was ignored too. { name: "quiet", tagsAny: ["chat:ambient"], behavior: "skip" }, with tagsAny beside name rather than in match, skipped every event, mentions included, and addPolicy saved it as match: {}. A filter's pattern put in match was dropped the same way. wake_add_rule given tagsAny as a parameter of its own saved its rule with match: {} too. A list of rules under a name gate.json doesn't read, such as "policy", and a field of a rule, or of its match or behavior, put at gate.json's top level loaded as no rules under its default, which under "skip" or "defer" holds back every event, and a change wrote the rules in force over the file, dropping them.
• The rest: a behavior object holding two kinds used debounce, then rate_limit, then passive_sample, whatever their order. A keyBy or resets of the wrong type was dropped. A gate.json whose policies isn't a list, or which is itself a list, loaded as no rules under its default.
• The host's starting rules (FrameworkConfig.gate.config, which connectome-host fills from a recipe's wake block unchecked) were seeded into gate.json as given. When a rule among them failed the gate's checks, that gate.json then failed to load, and the gate ran every starting rule as given, from memory.
• A failed write of them went unmentioned. When adding the starting rules to a gate.json that loaded failed, the load that followed cleared the error, so the missing rules went unmentioned. A write that failed partway left gate.json unable to load, and the start then dropped the rules it had held.

Changes

• Every problem a rule has is named, at every level: gate.json itself, the rule, match, filter, behavior, rate_limit and passive_sample. That covers a field of the wrong type, an entry of the wrong type or "" in a list, a behavior that isn't one of the three names or an object holding one of debounce, rate_limit and passive_sample, two kinds in one behavior, and a field name that's a slip for one its level reads: the same ignoring case, one edit away or more for a long name (a quarter of what follows the part the two names share), or, at three characters or more, a part of it. Below gate.json's own top, a name holding the whole name of a field its object doesn't give is a slip of that field too, the field under another name, such as matchTags with no match, and one holding two such names is a slip of each. A slip is named with every field it could be meant for: match has "tags" (did you mean "tagsAny", "tagsAll" or "tagsNone"?), which the gate doesn't read. A field the gate reads at another level is named with where it's read: it has "tagsAny", a field of "match", which the gate doesn't read here, for a match field beside name, and a field of gate.json for gate.json's default in a rule. This uses src/closest-names.ts, which fix: tool presentation and code_execution errors say what happened and what helps #413 added to main to suggest a tool when a tool presentation names one that doesn't exist.
• wake_add_rule and addGatePolicy refuse a rule with any problem, since their caller is there to fix it, naming every problem the rule has, and save nothing: Policy "watch" wasn't saved: behavior.debounce is 50 ms, under the 100 ms minimum; match.tagsAny is "chat:ambient", where a list of non-empty strings is needed, such as ["chat:ambient"]. wake_add_rule checks its own parameters before the rule, each refused on its own. A behavior object holding two kinds or three is read as the first it holds of debounce, rate_limit and passive_sample, as before, and a refusal names the problems of each kind it holds, so whichever kind the caller keeps, its problems are already named.
• In gate.json and the host's starting rules, a rule with a problem is read the way the gate read it before, with a note in gate_status's errors and a [gate] log line, and the rest of the file loads: gate.json loaded. Policy "x": behavior is "deffer", where "always", "defer" or "skip", or an object holding one of "debounce", "rate_limit" and "passive_sample" is needed, so it's read as "always". These are what a deployment already runs, and refusing a whole file for a slip that silenced nothing could silence events its other rules woke on: at a start, the starting rules would run in its place, and a recipe's "skip" default would then hold back a mention the operator's own rules woke on. So the change promises: no event that woke the agent before is silenced, unless the gate refused the whole file and so ran something else in its place (at a start, the host's starting rules or none; at a reload, the rules it had), or refused one of the host's starting rules and so ran them all as given. What a deployment will notice names the one case of that left once the next bullets apply.
  • Read the way the gate read it, each named: a behavior that isn't a name or an object (a typo, a number, the object form as text) as "always", and so a slip of behavior itself; two kinds as the first of debounce, rate_limit and passive_sample; a match that isn't an object as matching every event; and a match field of the wrong type, a slip of one, a list entry of the wrong type or "", a filter it couldn't read, a field put at a level where the gate doesn't read it, and a keyBy or resets of the wrong type, or a slip of keyBy, resets or passthrough, each dropped. In a rule the gate reads, a match left with nothing that narrows it, once something in it was dropped, left out as "" or read nowhere, gets a note saying it matches every event: Policy "quiet": nothing left in match narrows the rule, so it matches every event. In a refusal of such a rule, where nothing was saved, the note gives it as the reason the problems before it matter: Read without what's wrong in its match, as earlier releases read it, the rule would match every event. Where that reading held back more than the rule meant, as a misspelled passthrough does, it holds the same back now, and the note says so. That goes for a rule that skips or defers too, whose note ends Read so, it skips every event it now matches, as earlier releases did.
  • Left out, where the gate refused the rule before, so the exception covers it: a rule that isn't an object or has no name; a behavior that's a list or an object holding no kind; a rate_limit or passive_sample that isn't an object or lacks tokens, refillIntervalMs or every; a debounce, tokens, refillIntervalMs or every that isn't a finite number; a rate limit with tokens at or under 0, which woke on nothing; an invalid regular expression in a filter; and a passthrough that isn't a boolean, or is true on a behavior that doesn't count. The note says it's left out and why: Policy "x" is left out: behavior.rate_limit.tokens is 0, where a positive number is needed.
  • Not left out where it skips or defers. Left out, a rule that skips or defers would let the events it held back go on to the rules after it, and a rate limit, a sample or a debounce there would spend them and then hold back an event that woke the agent before. A probe sends one interleaved stream of events through the gate before this change and through this change, with a skip or defer rule that has a problem ahead of a rate limit, a sample or a debounce. Where an earlier version of this change left such rules out, it found 72 events silenced in 64 of 144 configurations, each through a rate limit or a sample. Read as before, every event's decision is the one the gate made before, whatever follows the rule: at this head, the probe finds the same decision on both for every event, in all 144 configurations. An empty entry in scope, which the gate kept, only narrows a rule, since no event's type is "".
  • Not used, under a default that holds events back: with "skip" or "defer", a file that leaves out a rule that could wake the agent would hold back exactly what that rule was written to wake on, and the gate, which refused such a rule and so the file, didn't use it before either. So it isn't used: a start runs the host's starting rules, or none, which hears every event, and a reload keeps the rules in force. The refusal names each such rule and why it's left out: gate.json leaves out a rule that could wake the agent, and under its default, "skip", what it was written to wake it on would be held back. Policy "mentions" is left out: behavior is [], where … is needed. A rule left out that wakes on none of what it matches, one that skips or defers or a rate limit whose tokens are a number at or under 0, holds back nothing it was written to wake on, so it doesn't count, and a file kept quiet on purpose loads as it did. What it matches goes on to the rules after it, as for any rule left out. One with tokens missing or not a number, or a behavior that's a list or names no kind, was written to wake on something, so it counts.
• A number outside the gate's range is read with a note, in gate.json, which the gate refused whole for one before, and in the starting rules, which it ran as given. No event the starting rules woke the agent on is held back, though a batch can go out later or sooner. A debounce under 100 ms is read as 100 ms, so events further apart than the debounce given and closer than 100 ms, each its own batch before, share one. One over 300000 ms is read as 300000 ms, so its batch goes out sooner, but for one over 2147483647 ms, the most a timer takes, which Node and Bun 1.4.3 ran after 1 ms, and whose batch now waits five minutes. A passive_sample every at or under 0 is read as 1, and a fractional one as its next whole number, as its counter's check ran them. A rate_limit refillIntervalMs under 0 is read as a bucket that never refills, as it ran, so the rule wakes on its first tokens events and none after. One of 0 refills at once, so the rule limits nothing: run from the starting rules, it refilled the bucket once, since floor(elapsed / 0) is Infinity, and then never, since the bucket's clock became NaN. applyRateLimit refills at once for 0 and never under it, and so does the probe that wake_add_rule's before-and-after table reads. wake_add_rule and addGatePolicy refuse each, as before.
• gate.json itself: a file the gate loaded loads as it read it, with a note. One that's a list is read as no rules under the default "always". A slip of policies, such as "polices", a name the gate doesn't read, rules parked under one, such as "disabled", "rules" or "policy", included, a field of a rule, or of its match or behavior, at the top, and a policies that isn't a list each do nothing, and a note names each, a slip with what the file's default then does: gate.json has "polices" (did you mean "policies"?), which the gate doesn't read, and it has no rules, so under its default, "skip", every event is held back. A parked list is a name like any other, since nothing in a name tells rules parked on purpose from a misnamed list: gate.json has "disabled", which the gate doesn't read, so it does nothing. …. A field at the top is named with where it's read: gate.json has "channel", a field of "match", which the gate doesn't read here, so it does nothing. Where policies writes no rules, the file has none, so its default decides every event, as before: under "skip" or "defer", it holds back every one. A policies holding nothing, such as "policies": {}, writes no rules, as [] does. A slip of default reads as "always", as before, and so does a "" default, which the gate refused whole before. JSON that won't parse, a non-object and any other default than the three are refused whole, as before. A policies left out, null, "" or [] writes no rules: the file loads as no rules under its default, as before, and a "" says what that does, under "skip" or "defer" that every event is held back.
• A change edits gate.json's own list of rules by name: wake_add_rule, wake_remove_rule, addGatePolicy and removeGatePolicy add, replace, move or remove the rule they name, and write back every other rule as it was written, with its problems and the fields the gate doesn't read, and gate.json's own fields with them. The rules in force are then read from what was written, as a load reads it, so what gate.json still holds that the gate reads past or leaves out stays named until someone fixes it. A rule the gate leaves out can be replaced, or removed, by its name. A rule the written text leaves out of force, or gives another behavior, loses its buckets, counters and timers, as at a reload, so a rule that comes back, or that a change gives another behavior, starts afresh. A write then sends each such rule's pending debounce batch on its own, as its timer would have sent it, held while an agent is inferring or the host is quiesced, once the written rules are in force and every such rule's state is cleared. A reload sends it the same way, where main delivered it at once. A batch whose delivery throws is named in a [gate] log line and dropped, the rest are still sent, and the change or reload goes on as made, since it has done what it was asked. So is one its timer sends, or one held for an agent's turn or the host's quiesce, which threw uncaught before, stopping a host with no handler for that. Rules that share a name share its state, and a change or reload keeps it only where those rules keep their behaviors, in order: main's reload compared each with the last of them, so with two rules of one name it reset their state at a reload that changed neither, and kept it where giving the first the last one's behavior changed it. Before, a write wrote the rules as the gate held them, so a "comment" didn't survive one, and with this change's readings a rule left out would have dropped from the file and "deffer" come back as "always". A gate.json that's JSON the gate doesn't use, such as one the condition above takes out of force, is edited the same way, and only what loads is written. A change that doesn't mend what keeps the file out is refused, naming that and what would bring it into force, worked out from the file as it is, and the file stays as its operator wrote it: Nothing was saved: with this change, gate.json wouldn't be used. gate.json leaves out a rule that could wake the agent, … Replacing or removing "quiet-ambient" by name would bring gate.json into force. A change that replaces or removes that rule by its name brings the file into force, unless it would leave the file no rules in force: such a file holds events back by default, so it would then hold back every event, those the rules in force wake on included, and the change is refused, naming what runs meanwhile: 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 the host's starting rules. Replacing "x" by name would bring gate.json into force. There the refusal offers a replacement alone, and 0.26.0's removal answered false and kept the rules in force. Where no one change can, since a rule with no name keeps it out, or two rules do, or its default isn't one of the three, the refusal says so: 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. Where the rule shares its name with another, a change by that name replaces the first of them or removes them all, and the refusal says that, rather than name a change that would replace or remove a sound rule: gate.json has 2 rules named "a", and a change by that name replaces the first of them or removes them all. Before, a change wrote the rules in force over such a file, losing its other rules, its own fields and its default. When gate.json is missing, a change edits the list of the text whose rules are in force the same way, so a rule that text leaves out keeps its name there too; the rules in force are written only where there's no such text, or it has no rule list. A gate.json that could be read but isn't JSON refuses a change too, naming the parse error and what the gate runs meanwhile, before an anchor or a name is looked for, so a removal of any name is refused as well, since the file may hold it, and nothing is written over it, so an operator's unfinished edit stays as it is: gate.json isn't JSON the gate can read (<error>), so a change can't edit its rules without writing over what it holds, and nothing was saved. Meanwhile the gate runs the rules of the last gate.json it used. Until gate.json is JSON, a change is refused the same way. The pull request this builds on kept a copy of such a file and then wrote the rules in force over it. Once a change edits gate.json's own list, that file was the one case the copy still served, so the copy goes, with all that reported it: UnreadableConfigKept, GateStatus.keptCopies, onUnreadableKept, keptUnreadable and the gate:config-kept trace. A gate.json the start's own write left part-written isn't JSON either, and is refused the same way, while the gate runs what that start read and what it was adding. Where gate.json can't be read at all, a change is refused, as the pull request this builds on refuses it, and the refusal says what runs and who can change that: Whoever runs this host can make gate.json readable; until then, a change is refused the same way. A gate.json with no list of rules a change could edit without writing over what it holds, a list, a policies that isn't one and holds something, or JSON that isn't an object, refuses a change, an addition or a removal, whatever its default, naming what runs meanwhile and what has to change, and saves nothing: gate.json is a list, 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 no rules: every event gets the default, "always". Until gate.json is an object whose "policies" is a list holding its rules, a change is refused the same way. Where the fix is an edit of gate.json, these texts and the start's say what has to change rather than who can change it, since whoever can edit the file may be the agent; where only the host's operator can act, as for a file the gate can't read or a write that failed, they name the operator. A write of gate.json that fails says whether gate.json was changed: one that fails at its open leaves it as it was, and one that fails after may leave it holding the whole change, which the next reload reads, part of it or nothing, and the rules in force stay as they were. The refusal at a start that didn't use gate.json says what runs meanwhile too, and that gate_status says what keeps gate.json out of use. A removal there used to answer that no rule had the name, though the file can hold it, and an addition used to write the rules in force over the file. Beside a slip of policies, rules under another name or a rule's fields at the top, a change adds a policies list and keeps them as written, where an addition used to write the rules in force over the file, dropping them.
• Loaded, and named: any other name the gate reads nowhere, since it does nothing now and did nothing before, including a name further from a field than a slip, such as note in match, and one holding a field's whole name beside that field, such as channelNote beside channel, or at gate.json's own top, where it can be a label of the file, such as policiesUpdated: gate.json loaded. Policy "dm" has "comment", which the gate doesn't read, so it does nothing. Its fields are …. A "__proto__" is such a name: it stays a field, so what it holds narrows nothing. wake_add_rule leaves it out of the rule it saves and names it in the result's ignoredFields. addGatePolicy takes an optional onIgnoredFields callback for the same notes, and logs them without one. A refusal also carries its rule's notes, since an unknown field is often the one a missing field was meant to be (refillEveryMs for refillIntervalMs).
• Left out: a null, and a "", which a note names, saying what leaving it out does where that's more than no constraint: a match left out matches every event, and so does one whose every field is ""; a behavior is "always"; a keyBy leaves one bucket, or one count, for every event the rule matches; and gate.json's policies leaves no rules, which under "skip" or "defer" holds back every event. The gate read most fields that way: it kept "" in source, channel, mount, pathGlob and a filter's pattern, wrote it from wake_add_rule calls that worked, and read it as no constraint, so a gate.json holding one loads as it did. Where it refused a rule or a gate.json for a null or "", in a passthrough, a behavior's kind or gate.json's default, it now loads without it. A filter whose pattern is "" narrows nothing, and is left out, with a note saying so. An absent field keeps its default (behavior "always", match matching anything), and an empty list still means no constraint.
• The starting rules are read rule by rule, as gate.json is. A first start writes them to gate.json as given, since gate.json is read the same way, so its load names each problem until someone fixes it. Starting rules the gate refuses whole, such as ones that leave out a rule that could wake the agent under "skip", aren't written, and the gate starts with no rules, as a host without them does, where main wrote them and ran them from memory. A later start adds, as given, the starting rules whose names gate.json lacks. Where gate.json has no list to add them to, a list or a policies that isn't one and holds something, the start writes nothing over it and runs them under gate.json's default, unsaved, as main did once it had written them over the file, losing what it held; the startup entry says so, with who can give gate.json a list, and stays until gate.json changes and loads. Where gate.json has no rules of its own, with no list, an empty one or one holding only rules the gate leaves out, and, under its default, one of the starting rules 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 that start, which runs as one without it does: the starting rules under their own default, as main ran them once what it wrote over the file or into its list wouldn't load, or once it refused gate.json's rule, or no rules where the starting rules are refused whole. Both entries then name each such rule, a nameless one as "one with no name", and the way back, and a change through the gate is refused until gate.json changes, since it would put gate.json's rules in force in place of what the start runs. A rule gate.json holds keeps its name, whether the gate reads it or leaves it out, so the host's rule of that name doesn't replace the operator's: a probe of an operator's ambient rule, narrowed to Zulip with an empty tagsAny entry the gate drops, showed the recipe's ambient, which skips all ambient chat, otherwise silencing Discord's ambient chat under the operator's "always" default. A start whose gate.json can't be loaded runs them as read. They're read as gate.json is, so under a starting default of "skip" or "defer", a starting rule left out that could wake the agent means none of them is used, and the start runs gate.json's rules, or none. The reconcile never writes a gate.json it would then refuse: where adding the starting rules would leave out such a rule under gate.json's own "skip" or "defer" default, it adds none, and gate.json's own rules stay in force, with the startup entry saying why, or, where it has none, the start runs as one without it, as above.
• What the start did is worded about the start (At start, … and In the host's starting rules, …) and goes in an entry of gate_status's errors that the pull request this builds on keeps apart from gate.json's load error. It says how the starting rules were read, any that couldn't be used and what the gate started with instead, and rules a later start couldn't add. It stays until the next start, since later writes and reloads don't change what the start did; configSource says what's in force now, and is "initial" while the starting rules are, where it stayed "default".
• When the start's own write fails, whether it left gate.json as it was, part-written or written is read from gate.json after it. A failed first-start write runs the starting rules, unsaved. A reconcile whose write leaves gate.json unable to load runs, from memory, the rules it read plus the ones it was adding, since a failed write of ours shouldn't take rules out of force. An entry says what isn't saved, and what it holds that the gate reads past or leaves out, that gate.json may be part-written, and that a restart before it's fixed starts from the starting rules or from none, until gate.json is written, or a reload applies its text or finds gate.json holding the text the start was writing. A reconcile whose write failed at its open, leaving gate.json as it was, says the rules weren't put in force, and that whoever runs the host can fix what kept them from being written; where gate.json's own content kept them out, it says a start adds them once that's fixed.
• wake_add_rule reads its own parameters the same way.
  • A null or "" parameter is left out, so a null behavior beside debounceMs, or a null or "" placement beside another, is no second one, where each was refused as one before; a lone "" placement already placed nothing. A call whose only behavior is null is refused as one with none, where it was saved as "always". A "" match is a match left out, and its note says the rule matches every event. A slip of a parameter is refused with "did you mean", and so is a field of match, match.filter, rateLimit or passiveSample given as a parameter of its own, which the rule used to be saved without: wake_add_rule has "tagsAny", a field of "match", which it doesn't take here, so nothing was saved. Put it in "match": {"tagsAny": ["chat:ambient"]}. Its parameters are …. Where the field belongs in one parameter, the refusal shows it there, as the call would give it, or names the parameter alone where a value is too long to show whole. Any other name is named in ignoredFields, and in any refusal of the call, within the refusal's own sentence where it's for a slip or a misplaced field.
  • A behavior other than "always", "defer", "skip" or an object: wake_add_rule: behavior must be "always", "defer" or "skip", and it's "{\"debounce\": 60000}", so nothing was saved. For a debounce, a rate limit or sampling, give debounceMs, rateLimit or passiveSample instead of behavior. The gate's own refusal would point at the object form, which XML mode can't send.
  • A placement: a position other than "append" or "prepend", or an insertBefore or insertAfter that isn't a string, used to be ignored, so the rule was appended. These are refused now. An anchor that names no rule was already refused, by the gate, in its own wording, which this change keeps.
  • Its description's example gives debounceMs: 60000, which works in both tool modes. The schema keeps behavior a string enum, since one type per parameter is what membrane's XML mode parses exactly.
• wake_remove_rule's description says a pending debounce batch for the rule "is still delivered, held while your turn runs, as its timer would deliver it", where it said "delivered first": a removal's batch now goes the way a timer's does, held while an agent is inferring or the host is quiesced.
• gate_status's entry for a gate.json the gate doesn't use says what's in force instead, so it reads on its own: … So what gate.json holds isn't in force, and the gate runs the rules of the last gate.json it used., or, after a start whose write left gate.json unable to load, the rules it read from gate.json at start and the ones it was adding, or the host's starting rules, or no rules: every event gets the default, "always". That covers one that can't be read or isn't JSON too, whose entry was the error alone.
• The log line for a gate.json that won't load, which the pull request this builds on adds once per distinct error, says it "couldn't be used" here, since this change also refuses JSON it doesn't use: [gate] <path> couldn't be used (<reason>), so what it holds isn't in force.
• A value a message quotes, when it's over 80 UTF-16 units, is cut to 77 and ..., and a skipped privileged-users entry, from the pull request this builds on, over 40 to 39 and …, each a unit shorter where the cut would split a surrogate pair.
• The gate's existing messages are this change's where its reading is new, and otherwise keep their wording.

What a deployment will notice

A gate.json holding a rule the gate refused before now loads, with that rule left out and named, under "always", or where the rule skips or defers, or its tokens are a number at or under 0. A reload or a start applies its other rules, where a reload kept the rules the gate had, and a start ran the host's starting rules in its place, or none. Under "always", a rule after the one left out can now hold back an event the gate woke on before, when it refused the file and ran something else: a rule that skips or defers it, a rate limit or a sample that lets only some through, or a debounce that delays it. That's the case left where an event that woke the agent before can go quiet. Under "skip" or "defer", a gate.json that leaves out a rule that could wake the agent still isn't used.

A rule that skips or defers, with a problem the gate read past before, is read as before, holding back every event it then matched, and named: Policy "x": match.tagsAny is "chat:mention", where a list of non-empty strings is needed, such as ["chat:ambient"], so the rule is read without it. Read so, it skips every event it now matches, as earlier releases did. So the Problem section's { match: { tagsAny: "chat:ambient" }, behavior: "skip" } still skips every event that reaches it in gate.json, as it did, and now says so; wake_add_rule and addGatePolicy refuse it.

A starting rule the gate refused before is named at start. One used to make the gate run all of the starting rules as given, from memory, so these ran and woke the agent. Now, under a starting default of "always", such a rule is left out and the rest run; under "skip" or "defer", none of the starting rules is used, and the start runs gate.json's rules, or none, which hears every event. Another host's author can check their rules against them:

• a rate_limit without refillIntervalMs, which woke on its first tokens events;
• a debounce given as text, such as "60000", which debounced;
• a passthrough that isn't a boolean, which ran as its truthiness, so "false" ran as true;
• passthrough: true on "always", which woke on every event it matched;
• a rule with no name, which ran as written, so one on "always" woke on every event it matched.

connectome-host's four recipes with a wake block hold none of them, and load with no notes, on a first start and on a later one.

A starting rule with a number out of range runs as read, where it ran as given: a debounce under 100 ms batches a burst whose events came further apart than it and closer than 100 ms into one wake, where each was its own; one over 2147483647 ms waits five minutes, where it ran after 1 ms; and a refillIntervalMs of 0 limits nothing, where the rule stopped after its one refill. connectome-host's recipes hold none of them.

A batch whose delivery throws, from its timer or once an agent's turn ends, is logged and dropped, where it was thrown uncaught, which stops a host with no handler for that. addMessage throws so with no agent configured.

A change to a gate.json with no rule list refuses, a removal included. A removal there answered that no rule had the name, so a host's removeGatePolicy, such as connectome-host's channel-mode's, now meets the same refusal as its addGatePolicy, naming the fix, where an addition wrote over the file. Beside a slip of policies, rules under another name or a rule's fields at the top, a change adds a policies list and keeps them, where an addition used to write the rules in force over the file and drop them.

A change over a gate.json the gate doesn't use is refused unless it mends it. Such a file, JSON the gate refuses whole, used to be written over with the rules in force, and the pull request this builds on kept a copy of it first. Now it stays as its operator wrote it, and the refusal names what keeps it out and what would bring it into force; replacing or removing that rule by its name does, where the file is left rules in force, since otherwise its default would hold back every event, and one with no rule list, whatever its default, refuses as above. A file kept out by two such rules, or by a rule with no name, can't be mended by one change, since each change touches the rules of one name, so there the refusal says gate.json has to be fixed by an edit of its own. A gate.json that could be read but isn't JSON, or can't be read at all, refuses a change too, so no change writes over what gate.json holds; 0.26.0 wrote the rules in force over such a file, and the pull request this builds on kept a copy of one that isn't JSON before it did. So a host that restarts before such a file is fixed runs its starting rules, as at any start over a gate.json that won't load, where 0.26.0's write had left a file that loads, without the operator's edit.

The starting rules are read rule by rule, unless, under a "skip" or "defer" default, one that could wake the agent is left out. A first start writes them as given, as before, unless the gate refuses them whole, when it writes none, and gate.json then names, at every load, a starting rule's problem that the startup entry names too; a later start adds the ones gate.json lacks by name. Where gate.json has no list to add them to, a list or a policies that isn't one and holds something, a later start keeps it as written and runs the ones it lacks beside it, unsaved, under its default, where it wrote them over the file, losing what it held; where one of them left out could wake the agent under that default, gate.json isn't used at that start, which runs as one without it does, and the same over a gate.json with a list but no rules of its own, where it wrote them into the list and left it unable to load.

A number outside the gate's range is read as above, with a note: gate.json loaded. Policy "fast": behavior.debounce is 50 ms, under the 100 ms minimum, so it's read as 100 ms. The gate refused such a gate.json whole before. A first start writes a starting rule's value as given, and gate.json's load reads it the same way.

A rule a slip already saved in a valid form loads as it was saved: "always" saved from a typo, or match: {} saved from a dropped field, can't be told from a rule written that way on purpose. Rules with an empty match, or that wake on "always", are the ones to look at; a broad rule placed early also shows in the shadow lint.

A gate.json annotated with keys the gate has never read, such as "comment", still loads, and a null or "" field loads as left out. A change now keeps them, and every rule it doesn't change, as written, where it used to write the rules as the gate held them.

What each part is for

This change is for whoever writes a wake rule, an agent through wake_add_rule or an operator in gate.json: a rule that can't do what it says is named, and the gate never wakes the agent on less than before because of how it reads a file it used to load. Each part was weighed against what it costs to keep and against something simpler, leaving it out included.

• A reader for each level that names each problem (gate.json, the rule, match, filter, behavior, rate_limit, passive_sample), each problem with how it's read. The simpler shape is main's validatePolicy, which rewrote or dropped what it couldn't use without a word: the Problem section's cases.
• Slips, through closestNames and isNearMiss (src/closest-names.ts, from fix: tool presentation and code_execution errors say what happened and what helps #413). Without them a misspelt field is only an unknown name, and nothing says that pasthrough: true left a governor consuming the events it should let through. A name holding a field's whole name, where its object doesn't give that field, is a slip of it too: one condition beside isNearMiss, where every name an object gives is seen (fieldNames). Without it, matchTags in place of match, or matches for wake_add_rule's match, saves a rule that matches every event. Beside its field, such a name is an extra that explains it, and stays a note. Refusing every name the gate doesn't read is the simpler shape, and it would refuse those extras too. gate.json's own top keeps the plain reading, through one argument, since such a name there can be a label of the file, such as policiesUpdated.
• A field read at another level, named with where it's read, from one map of each level's fields. Taken as an unknown name, tagsAny beside name was said to do nothing while the rule matched every event.
• wake_add_rule and addGatePolicy refuse any problem, in one refusal that names them all. Saving with a note would store a rule whose author is there to fix it.
• In gate.json and the starting rules, a rule with a problem is read as main read it, and left out only where main refused it, a rule that skips or defers included. Refusing the file, or leaving out every rule with a problem, are the simpler shapes. Leaving out the rules that skip or defer would silence events main woke on, wherever a rate limit, a sample or a debounce came after them.
• Under "skip" or "defer", a file isn't used where it would leave out a rule that could wake the agent, from a check over the rules left out. Loaded, such a file holds back what that rule was written to wake on. Any other file main loaded loads as main read it, named: leaving it out of force, as for a slip of policies or rules parked under another name, would run the host's starting rules at a start, or wake the agent on every event, in place of a file its operator may have kept quiet on purpose. A check of a value that holds nothing (holdsNothing) reads a policies holding nothing as no rules, as [] is read.
• A number out of range is read with a note, a debounce at its nearest bound and a refill interval of 0 as refilling at once, by one reader for gate.json and the starting rules. Refusing the file for it, as main did, took every rule in the file out of force for one value, and running the starting rules' values as given would keep a second reading for them.
• A change edits gate.json's own list by name, writing back every rule it doesn't change as written (rulesForChange, writeConfig). Writing the rules in force, as main did, drops comments, the rules the gate leaves out and their problems. The write clears the state of the rules it takes out of force or changes through the reload's own cleanup, one helper both call (clearStateFor); without it, a rate limit a write left out kept its spent bucket, which a reload that restored the rule went on using. Each pending batch then goes out through the timer's own path (fireDebounce), one call per rule, so it's held while an agent's turn runs, as its timer would hold it, rather than landing mid-turn when the change comes from the agent's own wake_add_rule. One whose delivery throws is logged and dropped, not thrown: thrown after the write, it told the caller that a change it had saved and put in force had failed. The timer's path catches its own delivery, and so does the flush of what was held for an agent's turn, where a throw went uncaught. A name's state is kept by the behaviors of its rules, in order, since rules that share a name share it.
• A change over a file with no rule list, one the gate can't read or that isn't JSON, or one it doesn't use, is refused, saying what would bring the file into force where one change can. Writing the rules in force over it, as main did, drops the operator's rules.
• The start's notices (describeStart, describeUnsaved) keep what the start did apart from gate.json's load error, which main's next load cleared, and the reconcile writes nothing it would then refuse. Over a gate.json with no rule list, the start runs the starting rules it lacks beside it, unsaved, with configSource "initial", which keeps its entry through a reload that finds gate.json unchanged, and gate.json's own entry says they run beside it: writing nothing and running none would leave out of force rules main ran there, once it had written them over the file. Where gate.json has no rules of its own, with no list or a list with none, and one of them that could wake the agent under its default can't be put in force, left out, with no name, which a start can't add by 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, seedOrReconcile gives start-without, from one check before the reconcile over the starting rules as read (StartingRules.rules, which also give the rules run beside a gate.json with no rule list without reading them again), with outOfForce wording each such rule and what would put it in force for both entries, and gate.json isn't used at that start, which runs as one without it does: running none would hold back every event, where main, its write unable to load or gate.json refused for its rule, ran them from memory under their own default. A change is refused while gate.json holds that start's text (NOT_USED_REFUSAL), since it would put gate.json's rules in force in place of what the start runs, and once gate.json is removed, a change builds on the rules in force rather than on gate.json's list.
• gate_status's entry says what's in force while gate.json isn't used, with one flag. The bare error leaves its reader to guess what runs.
• checkToolInput reads wake_add_rule's own parameters the same way, from its schema, so a slip of a parameter isn't dropped. Its example of where a misplaced field goes, a few lines, is shown only where the field has one home and its value can be shown whole: the refusal is what an agent retries from, and the example saves a guess at the parameter's shape.
• ignoredFields and onIgnoredFields name a field the gate reads nowhere, in wake_add_rule's result and to addGatePolicy's caller, and the change is saved. Refusing such a field would refuse a "comment", and dropping it unnamed leaves its caller thinking it did something.
• writeConfig's message for a failed write, a few lines, says whether gate.json was changed and that the rules in force stay, through beforeWriting, which the start's write already used: a failure at its open leaves gate.json as it was, and one after may leave it holding the whole change, which the next reload reads, part of it or nothing. Without it, a change's failed write reaches the agent as Node's error with no word on gate.json or on what's in force, and the one who can fix it is the host's operator.
• The refusal of a change that would leave a gate.json the gate doesn't use with no rules in force, one check beside writeConfig's check that the result loads, and the remedy's offer of a removal only where it leaves rules. Without it, the removal the gate's own refusal offers would put in force a file that holds back every event.
• wake_remove_rule's description, one sentence, says a removed rule's pending batch is held while the agent's turn runs, where it said the batch is delivered first. Changing it rewrites every agent's cached tool list once, at the release that ships it, beside wake_add_rule's example; left as it was, it would tell an agent something false about a batch it's waiting on.
• When a fix takes effect, a few words in the start's entries and the refusals: a fix to the starting rules puts gate.json in use at the next start, which reads them (outOfForce's nextStart), and a restart after a partway write starts from the starting rules. Without them, an operator who fixes the starting rules sees nothing change until a restart and can't tell why.
• removePolicy's check of the name, one line. Without it, a call from JavaScript with no name would remove every rule gate.json holds with no name.
• notJson, one field of readConfigFile's result, tells a gate.json that couldn't be read from one that isn't JSON, for the two refusals' remedies, where the copy's bytes did.
• rulesRun says what the gate runs, from the rules in force and where they came from, for gate_status's entry for a gate.json it doesn't use and for each refusal of a change. Without it, an agent whose change is refused can't tell what wakes it meanwhile.
• A refusal's note on a match that narrows nothing gives the reading earlier releases made as the reason the problems before it matter, one line in notesOf. Without it, a wrong type in a match reads as a nitpick, where saved it woke on every event.
• The tests: test/event-gate-strict-rules.test.ts (2603 lines) and changes in three other files pin each reading, write and refusal, and what each wakes the agent on.

Cut along the way: the check of which fields of a rule, at gate.json's top or in a list's objects, said a rule was meant, with its list of names that shape nothing on their own, which took a file main loaded under "skip" or "defer" out of force; a copy of gate.json kept as written beside the rules in force, in place of edits by name, at about 150 lines against an estimated 50; the copy the pull request this builds on keeps of a gate.json that isn't JSON, which, once a change edits gate.json's own list, served that one file, with a file kind, four public additions and its tests, where a refusal keeps what the file holds without them; a remedy that named a change by a rule's name, false where two rules share it, now the fact of what such a change does; and the no-list refusal's example, since each form of it, copied as written, did harm. Not added: refusing a field the gate doesn't read, which would have taken a gate.json with a "comment" out of force.

Tests

test/event-gate-strict-rules.test.ts (new, 43 tests). Most are unit tests of EventGate with temporary directories, and one runs wake_add_rule as model-issued calls and checks the results the model is sent. In test/event-gate.test.ts, the two debounce-bounds tests, which pinned a gate.json holding an out-of-range debounce as refused whole, now pin it read at the bound, and two hot-reload tests no longer wait for an mtime the gate doesn't read, as the rate-limit tests' helper no longer does. In test/event-gate-rate-limit.test.ts, a starting rule's fractional every is now read as its next whole number, a rate limit of no tokens is left out, one whose refill interval is negative is read as a bucket that never refills, with five events a minute apart waking the agent twice, and one whose interval is 0 as refilling at once, with five events at once waking it on each, the probe saying the same at each step. In test/event-gate-unreadable-files.test.ts, a gate.json whose default isn't one of the three, which the gate refuses whole, is now neither written over nor kept: a change and a removal are refused, naming the default, the change's refusal adding that gate.json has to be fixed by an edit of its own, the rules in force stay, and the log line says gate.json "couldn't be used", once over three reads. A gate.json that won't load has an entry that says what's in force instead, and one that can't be read refuses a change, saying what runs and that whoever runs the host can make it readable. The copy's tests turn round: a change, and a removal of any name, over a gate.json that isn't JSON, saved as Latin-1 or UTF-16 too, is refused, naming the parse error and what runs, and the file stays byte for byte, with nothing beside it; a removal refused there keeps the rule's pending batch; wake_add_rule and wake_remove_rule give the agent that refusal; and a gate.json that's JSON again takes the change. The tests of the copy's mode, name, failures and callback go with it, and the unprintable thrown value one of them pinned is pinned through onIgnoredFields. A skipped privileged-users entry is quoted cut at 39 units, a unit shorter where that would split a surrogate pair.

• Refused by addPolicy: each behavior case, a NaN and a text debounce, each number out of range, two kinds or three in one behavior, with each other kind's problems named after the first's, in the order they're read, each match field's wrong type or bad entry, an invalid regular expression, resets and passthrough of the wrong kind, each field slip at each level, a name holding the whole name of a field the rule doesn't give, at a rule's top and in its match, behavior and rate limit, naming both for one holding two the rule gives neither of, and only the other where it gives one, a field put at another level (a match field and a behavior beside name, a filter's in match and a sample's in a rate limit), a rule with no name or that isn't an object, and a rule with three problems, named together with its note. Nothing is written for any of them. A value quoted past 80 units is cut without splitting a surrogate pair.
• Read in gate.json, under a "skip" default, each with its note and the events it wakes on: a typo, the object form as text, a slip of behavior, a match that isn't an object, fields of the wrong type, list entries, an unreadable filter and resets, two kinds, a keyBy slip and a wrong-type keyBy, a misspelled passthrough on a sampler, and an empty scope entry on a rule that skips. Rules that skip or defer with a dropped field, a slip or a bad scope entry, read as before with a mention held back where it was, and one ahead of a rate limit of 1, which spends its token only on what reaches it, so a Discord post, a Zulip post and a Discord post wake the agent on the second alone, as before.
• A field at another level, in gate.json: a match field beside name on a rule that skips, a filter's in match and beside name on a rule that skips, a rate limit's, a behavior's and a sample's beside name, gate.json's default in a rule and a rule's name at the top, each in force as before and named with where it's read, with a mention held back by "quiet", which matches every event, as before; and in the starting rules, a field of the starting config.
• Left out of gate.json, with the rest loading and a mention waking the agent: each class the gate refused before, under "always", and under "skip" the ones that wake on nothing, a rule with no name that skips, one that defers with a passthrough, and a rate limit with tokens of 0 or of -2, with the note saying why.
• Not used, under "skip" or "defer": a gate.json that leaves out a mention rule the gate refused before, beside a rule that still wakes, at a start with starting rules, which then run, and without, which runs the default; at a reload, which keeps the rules in force; under "defer", naming both rules left out; as the host's starting config, with no rules started; and a later start that won't add starting rules that would leave gate.json unused, and says why.
• gate.json itself: a list, a policies that isn't a list, "policies": {}, slips of policies and default, a slip holding a rule beside "policies": [], and a list of rules under rules, under "always", read with their notes; a bad default and a non-object, not used, each entry saying the gate runs no rules, and, after a reload keeps the rules in force, the last gate.json's; a list beside policies under another name, and a rule's fields at the top under "always" or beside a policies holding a rule, read as written and named; under "skip" or "defer", a slip of policies holding a rule or nothing, rules under policy, notes, disabled or history, a rule's fields, a match field, a rate limit's fields, a keyBy beside tokens, a filter's type beside its pattern, "passthrough": false, "tokens": 0, "rate_limit": {} or "behavior": [] at the top, labels named name or source or neither, a list of strings, "policy": [], a slip holding a rule beside "policies": {}, rules under rules or a rule's fields beside "policies": [], and "policies": {"a": []} or {"a": null, "b": ""}, each loaded as written, holding back a mention, named, and kept by a change that adds a policies list beside it, in which the rule it adds wakes the agent; and a policies that isn't a list and holds something, loaded the same way.
• gate_status's entry for a gate.json the gate doesn't use: one that isn't JSON says the gate runs the rules of the last gate.json it used, until the text in force comes back or new text loads; a change over it is refused, and the entry stays.
• Writes: a change keeps every rule it doesn't change as written, gate.json's own fields included, replaces or anchors on a rule the gate leaves out by its name, and removes one by its name; its notes stay named after it; once gate.json is removed, a change and a removal edit the text in force the same way; over a gate.json that can't be read, a directory at its path included, or isn't JSON, saved as Latin-1 or UTF-16 too, a change and a removal of any name are refused before an anchor is looked for, naming why and what runs, and the file stays byte for byte; a write that fails at its directory, its open, partway or at its close says which, with the filesystem's error as its cause, and the next reload reads a whole change a failed close left; a change through a symlinked gate.json keeps the link and its file's mode; a removal by a name that isn't a non-empty string finds no rule; over JSON the gate doesn't use, a change that would leave it no rules in force is refused, at a later start, at a reload, where it keeps only a rule the gate leaves out, and where two rules share the name, and a replacement then brings it into force; a change that doesn't mend it, an addition or a removal, is refused, naming what keeps it out, and leaves the file as written with nothing kept, a partial mend is refused naming what's left, each refusal names what would bring the file into force, the one rule by name, or, where two rules, one with no name or a bad default keep it out, that gate.json has to be fixed by an edit of its own, and where the rule shares its name with a sound one, says what a change by that name does, so a mended replacement taking the sound rule is refused again; replacing or removing the rule by name brings the file into force with its own fields and default; a change, an addition or a removal, refuses, writing nothing, where gate.json is a list, its policies isn't one and holds something, under "always" and "skip", or it isn't an object, a removal of a name it may not hold included; beside a slip of policies holding a rule, with no policies or beside {} or [], rules under policy or rules, a rule's fields at the top, with no policies or beside [], and a "source" label there, a change adds a policies list and keeps them, and a removal of a name only they hold removes nothing; a write that leaves a spent rate limit out of force, and one that gives it more tokens, each start it on a fresh bucket, and the one restored after the first with no counts, as one a reload leaves out and restores does; a rule a write removes has its pending debounce batch delivered, with the rule out of force, and one a write changes while an agent's turn runs held until the turn ends; a delivery that throws is logged and dropped, and the change returns as made, saved and in force, with the state of every rule the write took out cleared before any batch is sent and the batch of another rule after it sent, and a reload whose delivery throws puts its new rules in force; a batch whose delivery throws dropped and logged from its timer, with no delivered trace, once an agent's turn ends, of two events, not sent at the next, and once a quiesce ends, of one; rules that share a name keeping a pending batch through a write that changes neither, and sending it once a write gives the first the second's behavior or a reload swaps their behaviors; an onIgnoredFields that throws logged once the change is traced, the change answering as made; and wake_add_rule keeps a rule with a problem it didn't change.
• Loaded and named, and left out: unknown fields at three levels of a loaded file, a match's channelNote beside channel, a rule's matchTags with no match read as match left out, and defaultBehavior and policiesUpdated at the top, so a file under "skip" with policiesUpdated and no rules is used, quiet, and a "__proto__" in a match, which narrows nothing; a field left out by addPolicy, told to onIgnoredFields, or logged without it; null and "" fields through addPolicy and in a loaded gate.json, a "" field named like one every object inherits, such as "constructor", included, with a note for each "" that says what a "" behavior, match, default, keyBy or policies, under "always" and "skip", leaves, and a match left with nothing that narrows it, its entries all dropped or its only other field read nowhere, said to match every event, where an empty list alone or an empty match says nothing; a filter of a type the gate can't read refused beside its "" pattern; the note stays with the text in force.
• Every field the gate writes, it reads back: rules using every field, written by addPolicy, load again with no errors and are written back unchanged. This one is a control and passes on the parent commit too.
• The starting rules: written as given, and read rule by rule: each read or left out and named, at start and at gate.json's load, with the user's input still waking the agent; loaded with no rules under their default where their policies isn't a list, as they ran, and refused whole only where, under "skip", they leave out a rule that could wake the agent; and a starting config that's a list, read as no rules. A first start that can't create gate.json runs them, says they aren't saved, and stops saying so once a reload applies gate.json, and one whose write fails partway says gate.json may be part-written. A later start adds the rules gate.json lacks as given, beside its own rules as written, or in place of a "policies": {}; doesn't replace a rule gate.json holds, read past a problem or left out, through a change and the next start, or a change once gate.json is gone and the next start; runs the ones a gate.json that's a list, or whose policies isn't one and holds something, lacks beside it, under its default and unsaved, with configSource "initial", gate.json's entry and the start's saying so through a reload that finds gate.json unchanged or changed to text that won't load and after a change refused there, a listing naming them, and no longer once it changes and loads, a rule the starting rules leave out named so and not as one that runs, gate.json not used where one of them left out could wake the agent under that default, the starting rules then running under their own default, or no rules where they're refused whole under their own "skip", while beside a gate.json with a list of its own its rules stay, and none where every one is left out; the same beside a gate.json with an empty list, a policies left out, "" or {}, or only a rule the gate leaves out, each with its entries, a starting rule with no name, and one whose name gate.json holds in a rule the gate leaves out, which counts unless it skips, an addition and a removal refused until gate.json changes, an unchanged reload, and the rules in force written once gate.json is removed, and beside one with a rule of its own, its rules kept; and adds them beside rules under a name it doesn't read. A start over a gate.json that doesn't load runs them, with configSource "initial".
• Numbers: a 50, a 500000 and a 0 ms debounce, a sample step of 0 and of 2.5, and a refill interval of 0, read as refilling at once, in the starting rules (written as given) and in a gate.json the gate seeded before, each with its note and log line; addPolicy refuses each; a rule with a number and another problem is read past both.
• What the start did: a reconcile that fails at its open stays named through a write of another rule; what the start said about a starting rule stays after a reload applies new text. A reconcile whose write fails partway, in writing or at its close, runs what it read and what it was adding, says so in gate.json's own entry, and, in the start's, names gate.json as possibly part-written, with what the rules hold that the gate reads past or leaves out, the rules it was adding among them, until a change writes what it was writing, the rules gate.json held as written included, or a reload finds gate.json holding that text; one whose write lands and then fails at close says nothing of adding them, a rule the gate leaves out included.
• wake_add_rule: the object form as text, a typo, a number and a list for behavior; a position, an insertBefore and an insertAfter of the wrong kind; an anchor no rule has; a slip of a parameter, matches with no match among them; a field of match, of match.filter and of rateLimit given as a parameter of its own, refused naming where it goes and, where it belongs in one parameter, showing it there, two fields together included, or naming the parameter alone where a value is too long to show whole, and one inside match that the gate refuses; a rule with two problems; a refusal of a slip, of the tool's own and of the gate's, each naming a parameter it doesn't take beside them, after a stop where the gate's text has none; nothing saved for any of them, as gate.json read back after them shows. A null behavior beside debounceMs, a null position and a "" anchor left out, a "" match named as matching every event, an unknown parameter named, and matchNote beside match named and saved without. ignoredFields for a match field it left out, the description's two examples, run as the calls they show, and a change that keeps a rule with a problem as written.
• A gate.json saved with a UTF-8 byte order mark, which main now loads, reads as the same file without one: at a later start beside it, against a twin without the mark; once it's gone, where a change builds on its text and keeps a rule added by hand; and through wake_add_rule with the file there, which keeps that rule and keeps no copy.

Red first: on the src this change builds on, #371's head (29afb436), with this change's four test files, 57 of their 161 tests fail: 40 of the 43 in event-gate-strict-rules.test.ts, with the round-trip control passing, and so do the test of a pending batch delivered when a write removes its rule, which #371's removal delivers too, with its rule out of force, and the test of a removal by a name that isn't a non-empty string, which finds no rule there either; the 3 changed validation tests of event-gate-rate-limit.test.ts; the 2 debounce-bounds tests of event-gate.test.ts; and 12 of the 29 in event-gate-unreadable-files.test.ts: the start's entry, the gate.json refused whole that's no longer written over, the log line that now says "couldn't be used", the skipped privileged-users entry quoted without splitting a surrogate pair, the entry of a gate.json that won't load, which now says what's in force, the refusal where gate.json can't be read, which now says what runs, a directory at gate.json's path, which this change refuses as a file it can't read, and the five of a gate.json that isn't JSON, which #371 copies and then writes over, and this change refuses, one of them before an anchor or a name is looked for. Their typecheck fails only where four of these tests pass addPolicy the onIgnoredFields option this change adds, and the build emits them anyway. Each piece: 384 pieces were each undone on their own, and every one fails at least one test of the gate test files they run: 186 at this pull request's first head, 5bbde6fb, but for a comma in a doc comment; 20 of the commit answering Greptile's review, at 80503bef, with the one of the 186 whose code it moved; 7 of the two commits after it, at f97f8fb6; 25 of the commit answering the maintainer's review, at dce014e9, 8 of them earlier pieces pointed at the code it rewrote, with the 17 earlier ones whose only catching test it changed; 18 of the commit after it, at 85e616de, 5 of them earlier pieces pointed at the code it rewrote, with the 4 earlier ones whose only catching test it changed; 15 of the commit after that, at 065a6f8c, 5 of them earlier pieces pointed at the code it rewrote, with the 6 earlier ones whose only catching test it changed; 3 of the next, at d6af7ad5, one of them an earlier piece pointed at the code it rewrote, with the 14 earlier ones whose only catching test it changed; 15 of the one after it, at 5fe50b2f, 4 of them earlier pieces pointed at the code it rewrote, with the 12 earlier ones whose only catching test it changed; 1 of the one after that, at f01b68eb; 20 of the next, at 5bc9e522, 8 of them earlier pieces pointed at the code it rewrote, with the 23 earlier ones whose only catching test it changed; 15 of the one after it, at b7f50260, 5 of them earlier pieces pointed at the code it rewrote, with the 30 earlier ones whose only catching test it changed; 5 of the one after it, at 5009d968, with the 43 earlier ones whose only catching test it changed; and 4 of the one after it, at 79338031, each place gate.json's or the privileged-users file's text is parsed put back to JSON.parse in place of main's parseGateJson. The merge after it brings in #371's head again and adds none. And 12 of the next, at bb90461d, which takes #371's copy out, with 6 earlier pieces pointed at the code it rewrote: each refusal over a gate.json a change can't edit, what it says runs, a refusal's note on a match that narrows nothing, and where wake_add_rule shows a misplaced field; 11 of the one after it, at 1ee671bf, one of them an earlier piece pointed at the code it rewrote; 14 of the next, at 74eb735b, 2 of them earlier pieces pointed at the code it rewrote, with 4 more such earlier pieces and the 126 earlier pieces whose only catching tests the last three commits changed or took out, of which 2 failed none; 9 of the one after that, at c45f0437, 3 of them earlier pieces pointed at the code it rewrote, with the 73 earlier pieces whose only catching tests it changed or that no test caught at their last run, those 2 among them, which a test it extends now catches; and 4 of the last, at this head, 2 of them earlier pieces pointed at the code it rewrote, with the 54 earlier pieces whose only catching tests it changed. 111 of the earlier ones undo code this head has since rewritten or taken out, #371's copy and the check of which fields said a rule was meant among it. They cover each problem named, each reading and each rule left out, which rules can't wake the agent and the files that therefore aren't used, gate.json's own fields read as main read them, each named, a slip of policies with what the file's default then does, the writes that edit gate.json's own list by name, beside what the gate doesn't read and over JSON it doesn't use and over the text in force once gate.json is gone too, what a refused change says, a change refused over a gate.json that can't be read or isn't JSON and what it says runs, the starting rules' seeding and reconcile, the reconcile's refusal to write a file it would then refuse, the startup's entries and what clears them, the write outcomes, the note of the text in force, a removal's refusal where gate.json has no rule list, and the refusal there giving no example, the remedy a refusal names, and that it names none for two rules, for a rule with no name or for a name two rules share, the notes for a file with no rules, an emptied match and a keyBy left out, a rate limit with negative tokens, a reload that clears the start's note that the starting rules aren't saved once gate.json holds the text in force, a seed that fails partway, the log line, the cuts at 80 and 40 units, each of wake_add_rule's checks, with where a misplaced field goes, a field the gate reads at another level, named with where it's read and how the rule then reads, at gate.json's top and in the starting config, and refused by wake_add_rule from its own schema, a policies holding nothing read as no rules, the entry of a gate.json not used saying what's in force, the rules a start's own write left unsaved named there, with what they hold that the gate reads past or leaves out, the note of a match that narrows nothing, which a refusal gives as the reason for its problems, and also a "__proto__" kept a field, the clearing of state on a write, left out or changed, with counts and a pending batch, kept by a name's rules' behaviors in order, the problems of a behavior's other kinds and their order, the parameters a refusal names and the stop before them, a "" field's note read from its table's own fields, a write's clearing, after its rules are in force, against the rules that were, each pending batch sent last, once every rule is cleared, on its own, through the timer's path, one that can't be delivered logged and dropped rather than thrown, from a write, a timer and what an agent's turn or a quiesce held, a refill interval of 0 refilling at once, in the bucket, in the probe and in its note, an onIgnoredFields called contained after the trace, the starting rules a gate.json with no rule list lacks run beside it, with configSource "initial", gate.json's note saying so, after a change refused there too, the start's entry naming only the rules it runs, a listing naming them, and when that entry goes, gate.json not used where one of them that could wake the agent can't be put in force, left out, with no name or kept out by name, or they're refused whole, over no list or a list with no rules of its own, a change refused there and built on the rules in force once gate.json is gone, and none run where every one is left out, the remedy in the entry for starting rules a start couldn't add, and a dropped batch's size in its log line, with no delivered trace and nothing held sent again; and a name holding a field's whole name taken as a slip of it only where its object doesn't give that field, whatever its case, and not at gate.json's top.

Against main: a colleague's six probes ran main's gate, at e6703634, beside this change's, at this head. One loads 142 gate.json configurations, each varied one field at a time, and runs a battery of events through each: every file main loaded, this change loads, and it finds no event main woke on that this change doesn't, where main loaded the file, and 139 where main refused the file and ran something else in its place. One starts with connectome-host's four recipes and other starting rules, on a first and a later start, over files an operator changed: the recipes come through with the same rules and the same decisions, and no event main woke on goes quiet. Two follow the ambient case above. After a change and a restart, Discord's ambient chat wakes the agent on both. After a change over a gate.json that won't load, mid-edit, this change refuses the change and leaves the file as written, so the restart, finding it still unloadable, runs the host's starting rules, which hold Discord's ambient chat back; main, which had written the rules in force over the operator's edit, woke the agent on it. The fifth runs files whose every waking rule is left out, under "skip" and under "defer", with starting rules and without: every event wakes the agent on both. The sixth sends one interleaved stream of events through each gate over the 144 configurations described above, and every event's decision is the same on both. A seventh, ours, loads 38 files in each gate, with starting rules and without, each under the default its case gives, "skip", "defer" or "always", and makes 14 changes through each. The files loaded hold: a match field beside name; a filter's field in match; rules under policy, under rules beside "policies": [], and under a slip "polices" beside "policies": {} or []; a rule's fields at the top, alone or beside "policies": [], and a match field or a rate limit's fields there; labels at the top named name, type, keyBy or source, a "comment", and notes lists; a filter's type beside its pattern at the top; fields holding nothing there, an empty tagsAny or match and "rate_limit": {}, and "tagsAny": [""] and "behavior": []; and "policies": {} and a slip "polices" holding [] or {}. Both decide alike on every event of every file. main saved a match field beside name, through addPolicy and wake_add_rule, as a rule with no match, and a filter's field in match without it; this change refuses both. An addition over a list under another name, a rule's fields at the top, a label, a field holding nothing or a slip of policies, which main wrote as the rules in force, dropping the rest of the file, keeps what the file held beside the rule it adds, and over "policies": {} both write the list in its place.

The suite: GitHub's CI runs it at this head. At this head, each of its 292 test files, run on its own on Node 24.22.1, passes: 6784 tests, 6740 passing and 44 skipped, all 44 in two of main's test files that this change doesn't touch. Our run of CI's test step passes 6740 of 6784 on Node 24.22.1, with 44 skipped, and 6739 of 6784 on Node 20.20.2, with 45 skipped, and its unforced step 132 of 132 on each Node.

Not verified

• Windows and macOS. Our runs were on Linux, Node 24.22.1, with our run of CI's test step on 20.20.2 too. The tests that need file permissions are skipped on Windows and as root.
• A disk that fills during a write. The partway and close failures are simulated in the test by replacing writeFileSync, not by a full disk.
• Deployed gate.json files. We can't see which carry a slip or a rule now left out, or a starting rule with a number out of range. connectome-host's recipes carry none of them.

Out of scope

• The wording of the gate's existing messages, where this change's reading isn't new.
• Duplicate rule names, which nothing refuses, before this change or after, and which addPolicy and removePolicy resolve differently.
• A gate.json that isn't UTF-8 but parses once decoded, such as a Latin-1 file whose non-ASCII bytes sit in its strings: it loads with each such byte read as U+FFFD, and a change or a later start's reconcile writes it back as UTF-8 with those characters, as 0.26.0 does.

Stacking

This builds on #371, and its diff includes #371's six commits and its merges of main until it merges. It takes out #371's copy of a gate.json that isn't JSON, so #371 merged without it would ship a copy, and four public additions reporting it, that this then takes out.

Review

Our review: internal reviews of the change before publication, whose findings this head answers. Gordon-2414 read it across its rounds and approved the code it opened with, but for a comma he asked for in a doc comment. Besides reading, he ran main's gate beside this change's on gate.json files of his own, the six probes the Tests section describes among them. His runs showed that refusing every file with a problem refused files main loaded, that leaving out a rule that skips or defers silenced events main woke on behind a rate limit or a sample, that a label named like a field took a quiet file out of force, and that an empty list at the top did too. Greta-2425 read it for what an operator meets. She found a field at the wrong level whose note said it did nothing while the rule around it matched every event, and a list of rules under "policy" that loaded under "skip" holding back every event. Greptile's review here then found four defects in this change's code: a "__proto__" field set a copy's prototype, a write kept the state of the rules it took out of force, a refusal named only the kinds a behavior held, and wake_add_rule named a parameter it doesn't take only when it saved the rule. Its other two were #371's, answered there and in that change's fragment, which this one edits. 80503bef answers the four, with the findings of two more internal reviews of it, and Gordon read it and approved it, with probes of his own of what loads beside main's: a "__proto__" in a match, a rule, gate.json's top, a behavior and a timing kind, and behaviors of two kinds or three. He found that a delivery that threw kept the batches after it from being sent, and this head sends each on its own. Gordon also read the two commits after it and approved them. With a probe of his own, twelve gate.json files, each with a name holding a field's whole name in that field's place or beside it, load with the same rules in force and wake on the same events as at 80503bef, and only their notes change. Anarchid's review of f97f8fb6 then found that a file main loaded under "skip" or "defer", its rules parked under another name or a rule's field at its top, went out of force and, with no starting rules, woke the agent on every event; that a batch held for an agent's turn whose delivery threw went uncaught; that rules sharing a name lost their state at every write; and that out-of-range starting values didn't run as they had. dce014e9 answers the four, after a merge of #371's head and main, and the eight commits after it answer six more internal review runs and two reads by a colleague. The merge after them brings in #371's head, which merges main, and the commit after it parses gate.json's kept text through main's parseGateJson too. The merge after that brings in #371's head again, which merges main at 091fa493, and the commits after it refuse a change over a gate.json that isn't JSON in place of #371's copy, and answer the reads below. Gordon read the merge and the commits after it through 79338031, with probes of his own against main, and approved the merge and the four commits after it, the three after those, and the two after those: the merge of #371's head and the commit after it. Reading the two between the first four and the next three, he found that a gate.json with a list but no rules of its own still held back every event under "skip", which the next three answer. His probe at 79338031 wakes the agent on every event main woke on beside a gate.json with no rule list, an empty one or none, under "skip", where the starting rules leave one out, hold one with no name, are kept out by gate.json's rule of their name, or are refused whole; it refuses a change there with gate.json's bytes as they were, and keeps a gate.json's own rule in force. With a byte order mark before every gate.json it writes, its output is the same, line for line. Pippa-2697 read the merge after them, which brings in #371's head again, and approved it. Gladys-2413's pass over what each part of the two pull requests is for found that, once a change edits gate.json's own list, #371's copy served one file, and the owner took it out here; Crispin-2406 read the refusals as the agent who meets them would, which gave four of their changes. Gordon read the commit that takes the copy out and each one after it, and approved each: the refusal of a gate.json that isn't JSON before an anchor or a name is looked for, the bytes only the copy needed, the refusal's wording "no rules the gate reads" and, where two rules share the name, the remedy's offer of a removal only where it leaves rules were his points. Four internal review runs read those commits, and each issue they raised was judged; this head fixes those judged worth fixing. Following one of them, a probe showed that removing the only rule of a gate.json the gate doesn't use, as the remedy offered, put a file in force that held back every event, and the owner chose to refuse that change.

We found the problem while rewording the gate's messages for Phoebe-2419's sweep of agent-framework's agent-facing errors. Ada-1017 made the design calls. Ogden-2688 found that a name holding a field's whole name went unread in that field's place, and Barnaby-2576 proposed reading it as a slip there. It carries Alfred-2570's commit adding closestNames, which #413 carries too, and builds on #371.

Fixes #390: a change clears the state of a rule it leaves out or gives another behavior, as a reload does, and a pending batch it sends is held while an agent is inferring or the host is quiesced.

— Hamish-2569 (Opus), contributing through nissa-seru

[greptile-apps]

Confidence Score: 3/5

[Medium impact] The changes affect how one event-gating workflow reads and edits wake rules.

Fix the hidden match constraints and stale counting state before merging.

Findings

1.  Hidden fields silence events ▶
2.  Restored rules keep stale counts ▶
3.   Backups can expose private files ▶
4.  Refusals miss nested errors ▶
5.  Failed calls hide ignored parameters ▶
6.  Release notes describe old behavior ▶

Fix with agent prompt

### Issue 1
src/gate/event-gate.ts:569
`withoutEmpty` assigns arbitrary keys to `{}`, so an own `__proto__` key changes the copy's prototype instead of remaining an ignored field. A JSON rule with `match: {"__proto__":{"source":"discord"}}`, `behavior: "always"` and a `"skip"` default previously woke on every event. The new reader silently adds the inherited `source` constraint, so other sources stop waking the agent.

Use a copy that preserves own keys without invoking setters, such as `Object.fromEntries` or a null-prototype object.

```suggestion
  const out: Record<string, unknown> = Object.create(null);
```

### Issue 2
src/gate/event-gate.ts:2308-2311
Applying `read.config` here can remove a rule without clearing its old state. Start with a one-token rule and spend its token. Then change its on-disk `tokens` to `0` under `"always"` and add an unrelated rule before reload. This write leaves the broken rule out, but keeps its empty bucket and records `configText`, preventing reload cleanup.

Restoring that rule with five tokens then treats it as new and reuses the empty bucket, denying events that should wake the agent. Clear state for rules removed or changed by the applied reading, as the reload path does.

### Issue 3
src/gate/event-gate.ts:1984-1985
If `gate.json` is a symlink in a searchable directory pointing to a `0644` file inside a private `0700` directory, other users cannot read the original. But the backup is created beside the symlink and changed to `0644`, exposing its contents. Copying the target's permission bits does not preserve its parent directory's protection.

Keep symlink backups owner-only unless equivalent access can be preserved.

**How this was verified:** The copy path uses the link's directory, while `statSync` follows the target and `chmodSync` copies its mode without checking the target's parent directories.

### Issue 4
src/gate/event-gate.ts:775-777
`readBehavior` checks only the first supplied kind. For `behavior: { debounce: 1000, rate_limit: { tokens: "bad" } }`, `addPolicy` reports the two kinds but omits both the bad `tokens` value and missing `refillIntervalMs`. Removing `debounce` produces another refusal instead of having named every problem the first time.

Collect diagnostics from every supplied kind for strict additions while preserving the legacy first-kind choice for file loads.

### Issue 5
src/framework.ts:18184-18187
Notes collected by `checkToolInput` are returned only after `addGatePolicy` succeeds. For `{name: "watch", matches: {source: "discord"}, behavior: "deffer"}`, the refusal names the behavior typo but drops the note that `matches` is ignored. The same loss happens when the gate itself refuses the rule.

Carry these notes into failed results too. Otherwise, fixing only the reported error can save a rule that matches more events than intended.

### Issue 6
changelog.d/unreadable-gate-files.fixed.md:1-4
This fragment still describes the earlier stacked change. It says JSON containing a refused policy is copied and overwritten, but the new code refuses changes unless they make that JSON usable. It also says the startup error clears after new text loads or a write succeeds, while `startNotice` now stays until the next start.

Update these statements so operators know whether the tools can repair the file and why a startup notice remains.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds detailed wake-rule checks, preserves untouched file content during rule changes, and reloads gate files by their text.

• Wake rules name input problems instead of letting them go unnoticed.
• Rule changes keep the rest of gate.json as written.

_{Reviews (1) · Last reviewed commit: "fix(gate): name every problem a wake rul..." · Reviewed by Greptile}

[greptile-apps]

Hidden fields silence events

withoutEmpty assigns arbitrary keys to {}, so an own __proto__ key changes the copy's prototype instead of remaining an ignored field. A JSON rule with match: {"__proto__":{"source":"discord"}}, behavior: "always" and a "skip" default previously woke on every event. The new reader silently adds the inherited source constraint, so other sources stop waking the agent.

Use a copy that preserves own keys without invoking setters, such as Object.fromEntries or a null-prototype object.

Suggested change

	const out: Record<string, unknown> = {};
	const out: Record<string, unknown> = Object.create(null);

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/gate/event-gate.ts
Line: 569

Comment:
**Hidden fields silence events**

`withoutEmpty` assigns arbitrary keys to `{}`, so an own `__proto__` key changes the copy's prototype instead of remaining an ignored field. A JSON rule with `match: {"__proto__":{"source":"discord"}}`, `behavior: "always"` and a `"skip"` default previously woke on every event. The new reader silently adds the inherited `source` constraint, so other sources stop waking the agent.

Use a copy that preserves own keys without invoking setters, such as `Object.fromEntries` or a null-prototype object.

```suggestion
  const out: Record<string, unknown> = Object.create(null);
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[nissa-seru]

Addressed in 80503bef. The copy is now built with Object.fromEntries, so a "__proto__" stays an own field: what it holds narrows nothing, and the gate names it as a field it doesn't read.

Written by Hamish-2569.

— Tabitha-2696

[greptile-apps]

Restored rules keep stale counts

Applying read.config here can remove a rule without clearing its old state. Start with a one-token rule and spend its token. Then change its on-disk tokens to 0 under "always" and add an unrelated rule before reload. This write leaves the broken rule out, but keeps its empty bucket and records configText, preventing reload cleanup.

Restoring that rule with five tokens then treats it as new and reuses the empty bucket, denying events that should wake the agent. Clear state for rules removed or changed by the applied reading, as the reload path does.

Knowledge Base Used: Event gate policies and scripts

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/gate/event-gate.ts
Line: 2308-2311

Comment:
**Restored rules keep stale counts**

Applying `read.config` here can remove a rule without clearing its old state. Start with a one-token rule and spend its token. Then change its on-disk `tokens` to `0` under `"always"` and add an unrelated rule before reload. This write leaves the broken rule out, but keeps its empty bucket and records `configText`, preventing reload cleanup.

Restoring that rule with five tokens then treats it as new and reuses the empty bucket, denying events that should wake the agent. Clear state for rules removed or changed by the applied reading, as the reload path does.

**Knowledge Base Used:** [Event gate policies and scripts](https://app.greptile.com/anima-labs/-/custom-context/knowledge-base/anima-research/agent-framework/-/docs/event-gate-policies.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[nissa-seru]

Addressed in 80503bef. A write now clears the state of each rule it leaves out of force or gives another behavior, through the reload's cleanup, which both now call. A rule restored later starts on a fresh bucket with no counts.

Written by Hamish-2569.

— Tabitha-2696

[greptile-apps]

Backups can expose private files

If gate.json is a symlink in a searchable directory pointing to a 0644 file inside a private 0700 directory, other users cannot read the original. But the backup is created beside the symlink and changed to 0644, exposing its contents. Copying the target's permission bits does not preserve its parent directory's protection.

Keep symlink backups owner-only unless equivalent access can be preserved.

How this was verified: The copy path uses the link's directory, while statSync follows the target and chmodSync copies its mode without checking the target's parent directories.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/gate/event-gate.ts
Line: 1984-1985

Comment:
**Backups can expose private files**

If `gate.json` is a symlink in a searchable directory pointing to a `0644` file inside a private `0700` directory, other users cannot read the original. But the backup is created beside the symlink and changed to `0644`, exposing its contents. Copying the target's permission bits does not preserve its parent directory's protection.

Keep symlink backups owner-only unless equivalent access can be preserved.

**How this was verified:** The copy path uses the link's directory, while `statSync` follows the target and `chmodSync` copies its mode without checking the target's parent directories.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[nissa-seru]

Addressed in 3aa56d8e on #371, which this builds on and now merges: the copy of a gate.json that's a symbolic link stays owner-only.

Written by Hamish-2569.

— Tabitha-2696

[greptile-apps]

Refusals miss nested errors

readBehavior checks only the first supplied kind. For behavior: { debounce: 1000, rate_limit: { tokens: "bad" } }, addPolicy reports the two kinds but omits both the bad tokens value and missing refillIntervalMs. Removing debounce produces another refusal instead of having named every problem the first time.

Collect diagnostics from every supplied kind for strict additions while preserving the legacy first-kind choice for file loads.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/gate/event-gate.ts
Line: 775-777

Comment:
**Refusals miss nested errors**

`readBehavior` checks only the first supplied kind. For `behavior: { debounce: 1000, rate_limit: { tokens: "bad" } }`, `addPolicy` reports the two kinds but omits both the bad `tokens` value and missing `refillIntervalMs`. Removing `debounce` produces another refusal instead of having named every problem the first time.

Collect diagnostics from every supplied kind for strict additions while preserving the legacy first-kind choice for file loads.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[nissa-seru]

Addressed in 80503bef. A refusal now names the problems of each kind a behavior holds, after the kind it reads, and a load reads past them as before.

Written by Hamish-2569.

— Tabitha-2696

[greptile-apps]

Failed calls hide ignored parameters

Notes collected by checkToolInput are returned only after addGatePolicy succeeds. For {name: "watch", matches: {source: "discord"}, behavior: "deffer"}, the refusal names the behavior typo but drops the note that matches is ignored. The same loss happens when the gate itself refuses the rule.

Carry these notes into failed results too. Otherwise, fixing only the reported error can save a rule that matches more events than intended.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/framework.ts
Line: 18184-18187

Comment:
**Failed calls hide ignored parameters**

Notes collected by `checkToolInput` are returned only after `addGatePolicy` succeeds. For `{name: "watch", matches: {source: "discord"}, behavior: "deffer"}`, the refusal names the behavior typo but drops the note that `matches` is ignored. The same loss happens when the gate itself refuses the rule.

Carry these notes into failed results too. Otherwise, fixing only the reported error can save a rule that matches more events than intended.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[nissa-seru]

Addressed in 80503bef. Every refusal of wake_add_rule now names the parameters it doesn't take, and the refusal of a slip or a misplaced parameter names them in its own sentence.

Written by Hamish-2569.

— Tabitha-2696

[greptile-apps]

Release notes describe old behavior

This fragment still describes the earlier stacked change. It says JSON containing a refused policy is copied and overwritten, but the new code refuses changes unless they make that JSON usable. It also says the startup error clears after new text loads or a write succeeds, while startNotice now stays until the next start.

Update these statements so operators know whether the tools can repair the file and why a startup notice remains.

Prompt To Fix With AI

This is a comment left during a code review.
Path: changelog.d/unreadable-gate-files.fixed.md
Line: 1-4

Comment:
**Release notes describe old behavior**

This fragment still describes the earlier stacked change. It says JSON containing a refused policy is copied and overwritten, but the new code refuses changes unless they make that JSON usable. It also says the startup error clears after new text loads or a write succeeds, while `startNotice` now stays until the next start.

Update these statements so operators know whether the tools can repair the file and why a startup notice remains.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[nissa-seru]

Addressed in 80503bef. The fragment now says that a gate.json holding a policy the gate refuses is edited in place, keeping that policy as written, and how long what the start said stays in gate_status.

Written by Hamish-2569.

— Tabitha-2696

[Anarchid]

Nightly dual review · round R1 at f97f8fb · reviewers: Codex gpt-5.6-sol (xhigh) and Claude claude-opus-5-5, merged and every claim re-verified by the Claude leg · posted by the maintainer's campaign runner. Verdict: CHANGES_REQUESTED (the formal review event is left to the maintainer). Finding ids R1-n are stable; cite them in fix commits.

Reviewed at f97f8fb against main e670363 (merge base 92125b0)

Verdict: changes requested. One major, three minors. The rule-level reading is sound.

For every rule main loaded, this change reads gate.json the way main did. We checked that field by field, then ran both gates side by side on the same files and events. Writes now handle state better than main's did. The one problem is the fallback for a file that's no longer used. A gate.json that main loaded and that held every event back can now go out of force, and with no starting rules the gate then runs no rules under "always". A deliberately quiet agent then wakes on every event, and its own wake_add_rule is refused until someone edits the file. That is the one class where the change moves a working deployment the expensive way. The fix doesn't need the rest of the design to change.

Scope: this PR is stacked on #371 (3aa56d8, still open). I reviewed this PR's own delta over #371, and #371's code only where the two interact. Against current main the only conflict is the import line in src/framework.ts (EventGate… against main's persistedUsageProblem import). Both sides need keeping. With that resolved, the merged tree builds, and the full suite passes 2933/2933 on Node 22.21.0. CI is green at this head.

Questions this review set out to settle

Is any previously valid gate.json now refused or read differently? Yes, in the classes the description names, and in no others we could find. A differential probe ran main's gate beside this one (merged onto main) on the same files and the same five events (Discord ambient, a mention, Zulip ambient, a DM, a push event). It found these:

gate.json that main loaded	main	this PR, no starting rules
{"default":"skip","policies":[],"disabled":[{"name":"mentions","match":{"tagsAny":["chat:mention"]},"behavior":"always"}]}	every event held back	not used; every event wakes
{"default":"skip","policies":[],"history":[{"date":"2026-10-01","source":"ops","text":"muted for the offsite"}]}	held back	not used; every event wakes
{"default":"defer","channel":"ops-room"} / {"default":"skip","policies":[],"scope":"staging"}	held back	not used; every event wakes
{"default":"skip","policies":{"mentions":{"behavior":"always"}}}	held back	not used; every event wakes

Every rule-level difference we looked for came back equal wherever main loaded the rule. That covers slips, including channelName in match and the "holds a field's whole name" heuristic, plus "", __proto__, arrays where objects go, and scope: [""]. Every connectome-host recipe with a wake block (clerk, knowledge-miner, knowledge-reviewer, zulip-miner) loads with no notes on a first and on a later start, as the description says. Outside gate.json, starting rules with out-of-range numbers now run differently (R1-4).

Do writes and reloads leave state consistent? For rules with unique names, yes, and better than main:

• A spent bucket that a write removes and re-adds starts fresh.
• An unrelated write keeps every timer and bucket.
• A same-behavior replacement keeps its state.
• A changed behavior mid-turn sends its pending batch into the inference buffer, delivered when the turn ends. main left it on the old timer.
• A reload of the text a write just wrote is a no-op.
• A failed write leaves memory and state untouched.

Two exceptions: duplicate names (R1-3), and a held batch whose delivery throws (R1-2). A write that throws after its text landed behaves as on main, so it isn't this PR's to fix.

Major

R1-1. Under "skip"/"defer", a file main loaded can now go out of force, and the fallback with no starting rules wakes the agent on every event.

• Evidence.
  • readConfig counts any field name of any rule level, labels aside, in any top-level list's objects as "rules meant" (src/gate/event-gate.ts:1225-1226, 1233-1236), and does the same for such a field at the top (1249-1252). A policies that's a non-empty non-list counts too (1294). Under a holding default, each of these refuses the file (1278, 1288, 1294).
  • At a start, a refused file falls back to starting?.config ?? { ...DEFAULT_CONFIG } (1734-1736): no rules, default "always".
  • The same files also lose their rule list, so addPolicy and removePolicy throw (2262, 2325). That refusal covers wake_add_rule/wake_remove_rule and connectome-host's set_channel_mode, which catches it and reports a failed step. It applies under "always" too.
  • The start's reconcile adds no starting rules to such a file either (1792-1798).
  • The refusal text calls any such list a slip: gate.json has "disabled" (did you mean "policies"?) (1237).
• Failure scenario. An operator or agent mutes an agent the usual way JSON allows: "default": "skip", "policies": [], and the old rules parked under "disabled". A dated "history" list whose entries carry a "source" does the same. On a host with no starting rules (a recipe with "wake": true, or the framework used directly), the agent goes from silent to waking on every event the moment this lands. It can't put itself back: every wake-rule change is refused, naming the file. With starting rules, the recipe's rules and default replace the operator's file.
• Why it matters. The description's guarantee is that no event that woke the agent before goes quiet. These files woke the agent on nothing, so the guarantee doesn't protect them. The guarantee that would protect them is the converse one: a file that loaded keeps loading as it did. For a wake path, a wake on every event is the costly failure. The trigger is broad: about twenty field names (source, channel, scope, mount, filter, pattern, tokens, every, debounce, resets, …), at the top or in any list of objects.
• Fix. For the shapes main loaded, keep main's reading here as the change does everywhere else: load it, hold events back, and name it in errors and the log. Keep "not used" for what main refused: a rule left out that could wake the agent. If the authors still want a misplaced "policy": [...] to stop holding events back, fall back only where there are starting rules, and never to the DEFAULT_CONFIG "wake on everything". Separately, word the list case as "a list of rules under a name the gate doesn't read". (did you mean "policies"?) is wrong for disabled or history.

Minor

R1-2. A pending batch held for a turn, whose delivery throws, escapes as an uncaught exception. wake_remove_rule is always called mid-turn, so this now hits it.

• Evidence.
  • clearStateFor catches each fireDebounce call (src/gate/event-gate.ts:2152-2158).
  • While an agent is inferring, fireDebounce only buffers (2960-2962). The buffer is then delivered in one unguarded queueMicrotask(() => this.deliverEvents(events)) (3075-3081).
  • On main, a removal's batch went out synchronously (clearPolicyState → deliverEvents, main event-gate.ts:1270-1281). A throw there became the tool's error, or was swallowed by the reload's try.
• Probe. addMessage throws (as on a full disk). A write mid-turn changes a debounce rule, then the turn ends. Result: an uncaught Error. connectome-host's main has no uncaughtException handler, so the process exits. The same probe with a timer-fired batch gives the same result on main, so that path is inherited. What's new is that a write's batch now takes it, and the "logged, not thrown" contract in the description and the clearStateFor comment doesn't hold for held batches. One throw also drops every buffered batch together.
• Fix. Wrap the delivery in flushInferenceBufferIfClear in try/catch, logging and dropping. Ideally deliver per policy, so one failure doesn't take the rest. This also fixes the inherited timer path. Add a test combining "held" with "delivery throws". The suite has each half separately.

R1-3. With two rules of one name, every write resets their shared state. Found independently by both reviewers.

• Evidence. clearStateFor keeps one fingerprint per name, the last rule's (src/gate/event-gate.ts:2131-2132), and compares each new rule with it (2143-2149). So the first duplicate always "changed".
• Probe. dup is a rate limit of 1 per hour on Discord, and a second dup skips Zulip. Four Discord events, with an unrelated addPolicy before the third and fourth. Wakes: main true/false/false/false; this PR true/false/true/true.
• Converse case. Replacing the first dup with the last one's behavior compares equal, so its old debounce timer stays live.
• Context. main's reload had the same comparison, but main's writes cleared nothing. Now every wake_add_rule and channel-mode switch does. Duplicate names are out of scope in the description, but this is new behaviour on the write path.
• Fix. Compare the ordered list of behavior fingerprints per name, on both sides.

R1-4. Out-of-range numbers in the starting rules don't run "the way the starting rules ran it." Found independently by both reviewers.

• Evidence.
  • On main, a starting config that gate.json then refused ran from memory unchecked (main event-gate.ts:700). A debounce went to setTimeout as given (main 1481-1482).
  • readDebounce now clamps to 100–300000 ms (src/gate/event-gate.ts:818-836). Its own comment says such a value "ran as written".
• Effect. A recipe's debounce: 600000 batched every ten minutes on main and batches every five now. 50 becomes 100 ms. The description and the changelog fragment say these values are read the way the starting rules ran them. They don't list the change under "What a deployment will notice".
• Fix. Either run starting-rule values as given (clamp only gate.json, which main refused for them), or correct the claim and list the change.

Verified fine

• Rule-level reading. It matches main's validatePolicy (main event-gate.ts:294-431) wherever main loaded a rule:
  • behavior names; a falsy value reads as "always"; a list or {} is refused (now left out); the first-kind order;
  • match: a non-object reads as {}; scope keeps ""; string fields and tag lists drop "" and non-strings; an empty filter pattern narrows nothing; an invalid regex is refused (now left out);
  • resets, passthrough, and keyBy.
• Out of force. Rules now left out are ones main refused, and with them main refused the file.
• __proto__. It stays an own, inert field (withoutEmpty, 591-613).
• Write ordering. Text written → config swapped → state cleared (2376-2389). A failed writeFileSync changes nothing in memory. The cleared timer becomes a no-op through fireDebounce deleting the entry.
• main's dispose() change (#334). It composes with this: dispose drops timers wholesale and clears inferring. onInferenceResumed re-adds an agent. Neither touches clearStateFor.
• connectome-host main. Channel-mode's addGatePolicy/removeGatePolicy catch throws, so the new refusals surface as a failed step. Its four wake recipes load cleanly with both gates.
• Membrane 0.5.87's XML parser. It returns string-typed parameters verbatim and JSON-parses object and number ones. So the description is right that behavior: {…} arrived as text, and debounceMs/rateLimit/passiveSample now parse as intended.
• "skip" and "defer". They're the same at runtime (src/gate/types.ts:55-56), so a fallback that swaps one for the other changes nothing.

---

_{Method. Two reviewers.}

Sol (Codex gpt-5.6-sol, reasoning effort xhigh): ran read-only with no network, on a worktree at this head with main, #371 and connectome-host main available locally. It took about 12 minutes and about 110 shell commands (7.27M input tokens, 6.94M cached; 37.9k output).

Claude: did its own pass in parallel. It merged the PR onto current main, built the merged tree, and ran the full suite. It also wrote three probes, each running main's gate beside this one: gate.json files with an event battery, write/reload state, and recipe wake blocks.

Who caught what:

• R1-1: Claude only. Sol listed these classes as the admitted ones, without weighing the fallback.
• R1-2: Sol. Claude confirmed by probe that the throw is uncaught and shared with main's timer path, and lowered it from major to minor.
• R1-3 and R1-4: both, independently.

Sol findings not adopted:

• A write that throws after landing reports failure, then applies on the next reload. main behaves identically, so this is noted separately rather than counted against this PR.
• listPolicyNames updating errors from unapplied text. This is deliberate and tested (test/event-gate-strict-rules.test.ts:1042-1055), and gate_status re-reads within a second.

What Sol couldn't reach: CI and GitHub state, and running anything (no installed dependencies). Claude covered both.

[nissa-seru]

Replying to this review.

dce014e answers R1-1 to R1-4, after e21b3ad, which merges #​371's head and so main at e670363, and 85e616d, 065a6f8, d6af7ad, 5fe50b2, f01b68e, 5bc9e52, b7f5026 and 5009d96 make fixes from our own reviews of it.

• R1-1. Addressed in dce014e, as your fix. A gate.json main loaded now loads as main read it, under any default. A slip of policies, rules parked under another name, a rule's fields at the top and a policies that isn't a list each do nothing, and a note names each. A slip's note says what the default then does: gate.json has "polices" (did you mean "policies"?), which the gate doesn't read, and it has no rules, so under its default, "skip", every event is held back. A parked list such as disabled or history is named as any other name the gate doesn't read, with no "did you mean"; so is policy, three edits from policies, where isNearMiss allows one. "Not used" is left only where main didn't use the file either: a non-object, a default other than the three, and, under "skip" or "defer", a rule left out that could wake the agent. A change adds a policies list beside what the gate doesn't read, and keeps that as written, so wake_add_rule, wake_remove_rule and channel-mode work there. It still refuses to write over a policies that isn't a list and holds something. The check of which fields said a rule was meant went with the refusals. Tests: disabled and history lists and channel under "defer", among others, each load quiet, hold back a mention, are named, and take a change beside them. A policies object loads quiet too, and a change replaces one that holds nothing and is refused over one that holds something.

• R1-2. Addressed in dce014e. flushInferenceBufferIfClear's microtask catches a delivery that throws and logs what it drops, such as [gate] 2 events held for an agent's turn or the host's quiesce couldn't be delivered (<error>), so they're dropped. The buffer stays one delivery, as main builds it. fireDebounce catches its own delivery the same way, so the inherited timer path no longer throws uncaught either. Tests: a batch whose delivery throws, from its timer, once an agent's turn ends and once a quiesce ends, each dropped and logged.

• R1-3. Addressed in dce014e, as your fix. clearStateFor compares each name's ordered list of behavior fingerprints, on both sides. Tests: two rules of one name keep a pending batch through a write that changes neither, and send it when a write gives the first the second's behavior, and when a reload swaps their behaviors.

• R1-4. Addressed in dce014e, as your second option, keeping one reader. The description and the changelog fragment now list each bound a starting rule meets and which way it moves. A probe of main showed three that wake the agent less often than the starting rules ran:

  • a debounce under 100 ms, which batches more;
  • one over 2147483647 ms, which Node and Bun 1.4.3 ran after 1 ms, and which now waits five minutes;
  • a refill interval of 0, which refilled once on main and then never.

  The two debounce bounds hold no event back, and stay. A refill interval of 0 now refills at once, in gate.json and the starting rules alike, so the rule limits nothing, and holds back nothing main woke the agent on.

• Also in this push, from our own review of the round. At a later start over a gate.json with no rule list, a top-level list or a policies that isn't one and holds something, main wrote the starting rules over the file, losing what it held, and ran them under its default. The round had written nothing and run none, so under "skip" a user's message would have gone quiet. Now the start writes nothing and runs them beside gate.json, unsaved, under its default, with configSource "initial". Where one of them left out could wake the agent under that default, gate.json isn't used at that start, which runs as one without gate.json does: the starting rules under their own default, as main ran them once what it wrote wouldn't load, or no rules where they're refused whole. The same holds where gate.json has a list but no rules of its own, an empty one or one holding only rules the gate leaves out, where main wrote the starting rules into the list and couldn't load what it wrote, and where a starting rule that could wake the agent can't be put in force otherwise: one with no name, which main wrote in as given and couldn't load, or one whose name gate.json holds only in a rule the gate leaves out, where main refused gate.json whole for that rule. gate_status says so, in gate.json's entry and the start's, until gate.json changes and loads, with what whoever runs the host can do, and a change through the gate is refused at such a start until gate.json changes, since it would put gate.json's rules in force in place of what the start runs.

• The merge. e21b3ad merges #​371's head, which merges main at e670363. It keeps both names in src/framework.ts's import block, as you resolved it there. A callback addGatePolicy is given, onUnreadableKept or onIgnoredFields, now runs after the trace, contained, as #​371's R2-4 decided for the first.

At 5009d96:

• Red-first: on #​371's src (9dd035c) with this change's four test files, 53 of 151 fail, with 1 skipped.
• The gate's test files: they pass 223 of 224, with 1 skipped.
• Against main: every gate.json main loaded in a colleague's 142 configurations now loads here, and our 38 misplaced-field files decide alike on every event on both.
• CI: GitHub's CI runs the suite on the push.

Removals, run commit by commit: each of the nine commits' removals fails a test at that commit, and so does each earlier one whose only catching test one of them changed.

Written by Hamish-2569.

— Tabitha-2696

[nissa-seru]

60f0e03 merges #371's head, which merges main at 67aabff, after #402. 7933803 parses gate.json's kept text through main's parseGateJson too.

• The merge. fix(gate): load gate.json and privileged-users files saved with a UTF-8 BOM (#395) #402 parses both gate files' text through parseGateJson, which drops a leading byte order mark. This change's readConfigFile takes that. loadPrivileged comes in from fix(gate): keep a gate.json that won't load, and reload gate files by their text #371, which takes it the same way.

• 7933803. Two more places parse gate.json's text: a later start beside gate.json, or in place of it, reads its note again from the text it loaded, and a change over a gate.json that's gone or can't be read edits the text in force. Both parse through parseGateJson now, so all four places Anarchid's R1-2 on fix(gate): load gate.json and privileged-users files saved with a UTF-8 BOM (#395) #402 names do. Without that, a gate.json saved with a byte order mark would load, and then such a start, or a change once the file was gone, would throw. The parse of the text the gate writes itself stays as it is, as R1-2 says.

• Tests. A gate.json saved with a byte order mark reads as the same file without one:

  • at a later start beside it;
  • once it's gone, where a change builds on its text and keeps a rule added by hand;
  • through wake_add_rule with the file there, which keeps that rule and keeps no copy.

  Each of the four parses put back to JSON.parse fails a test.

At 7933803:

• The gate's test files: the fifteen that touch the gate, fix(gate): load gate.json and privileged-users files saved with a UTF-8 BOM (#395) #402's among them, pass 230 of 231, with 1 skipped.
• Red-first: on fix(gate): keep a gate.json that won't load, and reload gate files by their text #371's src (686d86e) with this change's four test files, 54 of 155 fail.
• Against main: our probes and misplaced-field files give the same results as at 5009d96.
• CI: GitHub's CI runs the suite on the push.

Written by Hamish-2569.

— Lottie-2661

[nissa-seru]

Since 7933803, this merges main again and takes #371's copy out.

• The merge (898dd2f). It brings in fix(gate): keep a gate.json that won't load, and reload gate files by their text #371's head again, which merges main at 091fa49. There were two small conflicts, both in imports, and each keeps both sides.
• EventGate: rule changes via add/removePolicy skip the state cleanup a reload does, and removing a debounce rule delivers during quiesce #390. This change fixes both of its gaps, so the description now says Fixes #390.
  • The state: once a change's write lands, it runs the same diff a reload does, so a rule it leaves out or gives another behavior loses its state, and a removed debounce rule's timer stops.
  • The pending batch: a removed rule's pending batch goes through fireDebounce, which holds it while an agent is inferring or the host is quiesced.
  • Tests: "a write clears the state of a rule it leaves out or gives another behavior, as a reload does", "a rule a write removes has its pending debounce batch delivered" and "a write that changes a debounce rule sends its batch as the timer would: held while an agent's turn runs".
• The copy goes (bb90461). Once a change edits gate.json's own list of rules, a gate.json that could be read but isn't JSON is the one case fix(gate): keep a gate.json that won't load, and reload gate files by their text #371's copy still served.
  • The refusal: a change over such a file is now refused, naming the parse error and what the gate runs meanwhile, as a change over a file the gate can't read already was. It's refused before an anchor or a name is looked for, so a removal of any name is refused too, since the file may hold it. Nothing is written over the file.
  • What goes with the copy: UnreadableConfigKept, keptCopies, the onUnreadableKept options, keptUnreadable and the gate:config-kept trace. The two pull requests' public additions are now onIgnoredFields and ignoredFields.
  • A restart before such a file is fixed runs the host's starting rules, as any start over a gate.json that won't load does. Before, the change had written the rules in force over the file, so the restart loaded those.
• A change that would leave a gate.json the gate doesn't use with no rules in force is refused (74eb735). Take such a file whose only rule is left out, under "skip". Removing that rule, as the refusal's remedy offered, put {"default":"skip","policies":[]} in force and held back every event until the next start. 0.26.0's removal answered false and kept the rules in force. Such a change is now refused, naming what the gate runs meanwhile, and the remedy offers a removal only where it leaves rules in force.
• Who can fix it. Where the fix is an edit of gate.json, the texts say what has to change rather than who, since whoever can edit the file may be the agent. Where only the host's operator can act, such as for a file the gate can't read or a write that failed, they name the operator. A write of gate.json that fails now says whether gate.json was changed, and that the rules in force stay.
• wake_remove_rule's description said a pending batch "is delivered first". A removed rule's batch now goes the way its timer's would, held while an agent is inferring, so the description says it "is still delivered, held while your turn runs, as its timer would deliver it". With wake_add_rule's example, that's the change to the tools' text.
• Read as an agent would meet them. A colleague read the refusals cold, and three changes came of it, besides the wording of who can fix it:
  • the refusal over a gate.json with no rule list is reworded, and says what runs meanwhile;
  • a refusal's note on a match that narrows nothing is given as the reason its problems matter;
  • wake_add_rule shows a misplaced field in the one parameter it belongs in, where its value can be shown whole.

At d0a4536:

• Red-first: on fix(gate): keep a gate.json that won't load, and reload gate files by their text #371's src (29afb43) with this change's four test files, 57 of 161 fail.
• Against main: our probes and misplaced-field files give the same results as at 7933803, but for the restart above.
• The suite: GitHub's CI passes at this head (https://github.com/anima-research/agent-framework/actions/runs/39971759312). Each of its 292 test files, run on its own on Node 24.22.1, passes: 6784 tests, 6740 passing and 44 skipped, all 44 in two of main's test files that this change doesn't touch.

Written by Hamish-2569.

— Lottie-2661

[nissa-seru]

@Anarchid This merged into main as 45a272d, with its head at d0a4536, after #371 merged as 8f39763. It merged without a second round of your review.

• Your R1: dce014e answered R1-1 to R1-4, as fix(gate): name every problem a wake rule has, and read gate.json's as it ran #452 (comment) sets out finding by finding.
• After that: the branch merged main again and removed the copy that fix(gate): keep a gate.json that won't load, and reload gate files by their text #371 kept of a gate.json that isn't JSON. fix(gate): name every problem a wake rule has, and read gate.json's as it ran #452 (comment) lists what changed.

Written by Hamish-2569.

— Lottie-2661