[nissa-seru]

At a start with an existing gate.json, the event gate now applies the recipe's wake rules to it. Before, it only appended rules under names it didn't have. A rule the recipe dropped kept matching, a renamed rule landed behind the catch-all while its old name kept matching, and a rule the recipe moved or redefined kept its old place and definition. !Fixes #654.

What a start does now, case by case

The gate keeps the recipe it last applied in gate.recipe.json, beside gate.json, and merges the new recipe against it.

Case	Before	Now
A rule the recipe dropped	stays, and keeps matching	removed, unless it was edited at run time (below)
A rule the recipe renamed	the old name stays, matching; the new one is appended after the catch-all, where the shadow lint flags it	the old name goes; the new one comes in at its recipe place
A rule the recipe added	appended at the end, after any catch-all	comes in before the recipe rule that follows it, or after the one before it when none follows
A rule the recipe moved	keeps its old place	takes the recipe's place, unless a run-time move holds gate.json's order (below)
A rule the recipe redefined	keeps its old definition	takes the recipe's, unless it was edited at run time (below)
A rule edited at run time or by hand	stays as edited	keeps its definition and still takes the recipe's order; the log names it when the recipe changed or dropped it. One edited to what the recipe now says is the recipe's again
A rule added at run time	stays	stays, in its place: its position, not its neighbours, so when the recipe reorders its own rules around it, it can end up between different ones. If the recipe later declares it as it stands, it's the recipe's from then on
A recipe rule removed at run time	comes back, appended at the end	comes back at its recipe place. It's the one run-time edit a start undoes, as the clerk recipe tells its resident; dropping it from the recipe is what makes a removal last
A recipe rule renamed at run time	both names: the old one appended again	both names: the new one stays as a run-time rule, and the old one comes back at its recipe place, so two rules hold one definition. A rename is a removal and an addition to the gate
A recipe rule moved at run time (wake_add_rule with a position)	keeps its place	keeps its place: gate.json's order stays, and the log says so when that holds back a reorder in the recipe
default	never changed by a start	takes the recipe's when unedited since the last recipe; an edited one stays, and is named when the recipe changed it too
The first start after upgrading (no recorded recipe)	(as above)	removes and redefines nothing: the rules that match the recipe by name and definition take its order, and the log names those that differ from it or aren't in it, and a default that differs, with what to do about each
A recorded recipe that doesn't read	(none)	the start merges as a first start does, and the log says why
gate.json or the recipe naming one rule twice	appended by name	the merge doesn't run: the rules gate.json lacks are appended as before, nothing is removed, redefined or recorded, and the gate's status and the log say which name. At the first start the recipe is written to gate.json as given, and not recorded
A rule wake_add_rule wrote back unchanged, as the gate reads it	(as above)	still the recipe's: rules are compared by what the gate reads, so it follows the recipe's later changes
A field the gate doesn't read, or a rule it leaves out	kept as written	kept as written. In a rule the gate reads, a change to such a field alone isn't an edit, so when the recipe changes that rule, the recipe's rule as written replaces it. A rule the gate leaves out is compared as written, so any change to it is an edit

Each start that merges into an existing gate.json and changes something logs one line, such as [gate] the recipe was applied to gate.json: added agents; removed zoo, sync; updated dm, and the gate:config-reconciled trace carries the same lists. Its addedPolicies keeps its meaning: every name the start added, restored ones included. Where the merge can't run, because a name is given twice, or recording the recipe fails, the gate's status says so beside the start's other notices until the gate is next created, and the log says it at the start. A write of the merge that fails names the changes it was writing, the removals and redefinitions included. When writing the record fails, the line naming what the start did has already been said. A gate.json that doesn't load is kept as it is, and the start applies and records nothing.

wake_add_rule's result also names the rules no probe event reaches, in notProbed. A rule scoped to external-message, as a module's messages are gated, matches none of the probes, which are MCPL chat events and a heartbeat. So every probe row read default:skip for it while real messages woke the agent. The note now says when the new rule is such a rule.

Changes

• src/gate/recipe-reconcile.ts (new): reconcileWithRecipe(live, recipe, last, meaningOf), the merge as a pure function on rules as written, comparing them by the meaning its caller gives, and reconcileLine, its log line.
• src/gate/event-gate.ts:
  • seedOrReconcile merges the recipe into gate.json in place of appending the rules it lacked, comparing rules as readRule reads them (ruleMeaning). It records the recipe after a seed or once gate.json holds the merge, and writes gate.json before the record, each in place. Where a name is given twice, it appends as before. Its other outcomes are main's.
  • readLastRecipe reads the record as the starting rules are read, through parseGateJson, so a BOM an editor leaves at the start of the file is dropped (A gate.json or privileged-users file saved with a UTF-8 BOM never loads #395).
  • What the merge couldn't do, and a failed record write, are said in the gate's status beside the start's notice, and logged. A failed write of the merge names its other changes beside the rules it was adding.
  • probeUnreached() names the rules no probe event matches; probeTable() and it share the probe events.
• src/framework.ts: wake_add_rule's result carries notProbed, a note saying why those rules are missing from the table, and its own note says when the new rule is one of them.
• src/gate/types.ts: GateOptions.config's doc says what a start does.

What each part is for

• The recorded recipe. Telling a rule the recipe dropped from one added at run time takes knowing what the recipe declared last time, since gate.json records nothing about a rule's origin. A file of the gate's own keeps gate.json the file people and tools edit. Cut: a field in gate.json, and an origin tag on each rule, which an edit by hand would lose.
• The three-way merge. An edit at run time is the operator's or the agent's choice, and the recipe is the operator's too: the merge lets each win where only it changed. A rule or default that already agrees with the new recipe is the recipe's, whatever the record says, so nothing that agrees reads as a conflict. Cut: replacing gate.json with the recipe, which would drop every run-time rule, and dropping every rule outside the recipe, which can't tell run-time rules from stale ones.
• Comparing rules by meaning, keeping them as written. The gate keeps a rule as written, a field it doesn't read and a rule it leaves out included. But wake_add_rule, and a run-time edit made while gate.json is absent, write rules as the gate reads them, with behavior filled in and unread fields left out. So the merge compares two rules by what the gate reads (readRule), and as written where either doesn't read. Re-issuing a recipe rule unchanged, as wake_add_rule's doc says to move one, then doesn't turn it into an edit that holds back the recipe's later changes. A rule that agrees with the recipe stays as gate.json holds it, and one that follows the recipe takes the recipe's rule as written. The recipe is read as the host's starting rules are, and one refused whole is neither merged nor recorded. A rule with no name stays where gate.json has it, and a recipe's rule with no name isn't merged, as one was never appended.
• Comparing definitions whatever their keys' order. A hand edit or another writer can reorder a rule's keys without changing it, and that mustn't read as an edit.
• The order rule. A run-time move is an edit too, apart from a rule's definition. When gate.json holds the rules both recipes declare in the last recipe's order, the recipe's rules take the new order in their places, and the rest keep theirs. Otherwise gate.json's order stays. Cut: always the recipe's order, which would undo a wake_add_rule move at every start, and anchoring each other rule to the one after it, which let a recipe rule jump ahead of rules it should stay behind.
• Naming moved rules. The line says which rules a start moved, taken as those outside the longest run of rules that kept their order. Without it, a reorder would change what wakes the agent with nothing said.
• Restoring a removed recipe rule. What a start does today, and what connectome-host's clerk recipe tells its resident ("Recipe-shipped rules … are restored at the next startup if removed").
• default by the same rule. The recipe's default is the operator's choice as much as its rules are. The old rule, that a start never changes it, left a recipe change to default unapplied for good.
• The first start without a record. Once a recipe is recorded, the old appending's misplaced rules would read as edits at every later start, so this start is the only time they can be put back. It changes no definition and removes nothing, since it can't tell a stale rule from a run-time one, and names both kinds.
• The log line and the trace. A start that removes or redefines rules changes what wakes the agent, so the operator reads what it did in one line, and a trace consumer gets the same lists. They come before the record is written, so a failed record write leaves the change named.
• The kept-order clause. A run-time move that holds back a reorder in the recipe is the one case where the recipe isn't applied and nothing else says so. It's named only then, not at every start while a move stands, so the line stays worth reading.
• Saying what the merge couldn't do with the start's notice. It stays true until the gate is next created, since no load or run-time edit applies the recipe, so it's said where the start's other notices are, apart from the load errors each load resets.
• Checking the record before using it. A record that can't be read, isn't JSON, is refused as the starting rules would be, or names a rule twice would steer the merge wrong, as if the last recipe had none of the rules it had. So it reads as one that doesn't read, and the line says why, quoting nothing from the file but a rule's name.
• Appending where a name is given twice. The merge keys rules by name, so it can't say which of two rules was meant. The start then does what main does, appending the rules gate.json lacks, and removes, redefines and records nothing, so a recipe's new rule doesn't wait on a duplicate nobody may notice.
• Writing in place. Both files are written in place, as the gate writes gate.json at every run-time edit, so a link, the owner, the group and the mode stay as they are. A stop mid-write fails safe. A torn gate.json doesn't load, so the next start merges and records nothing and reports it, and the gate runs as main runs for any gate.json that doesn't load. A torn record reads as one that doesn't read, so the next start merges as a first start does, which removes nothing, and says why. Cut: writing each through a staging file renamed over it. That bought nothing the run-time edits don't already risk, and it brought its own cases: a dangling symlink replaced, the owner and group changed, the staging file readable before its mode was set, and its name and cleanup.
• gate.json first, the recipe second. A stop between the two writes leaves the old recipe recorded beside the merged gate.json. The next start reads rules that agree with the recipe as the recipe's, so they don't read as edits. The other order would record the new recipe beside the old rules, which would then read as edits and stay.
• notProbed. A probe row built from guessed module metadata would read as fact, which is the defect reported, so the result names what the table can't show instead.
• Saying which writes failed. A failed write of the merge names its removals and redefinitions beside the rules it was adding, and a gate.json left unable to load says the gate runs the rules that write held. startUnsavedMerged picks that wording for gate_status, so main's wording stays for a start that only added rules. A failed record write says what gate.json holds and that the gate runs it.
• The tests' adapter and injected failures. The pure tests keep their GateConfig fixtures and reach the merge through reconcile, an adapter to rules as written, rather than rewriting each fixture. A full disk, a refused open and a failed close can't be made in a test, so those tests replace writeFileSync for gate.json alone, as event-gate-strict-rules does.
• No tool text changes: the wake tools' descriptions stay as they are.

What this leaves

• A stop in the moment between the two writes, or a record write that fails while gate.json's succeeded. gate.json then holds the merge beside the older record. With a different recipe before any clean start, the interrupted recipe's rules read as edits against the older record and stay, named where the new recipe changed them. With the same recipe, the next start merges against the older record again and records the recipe, though where a run-time rule shares a name with a recipe rule, the order it gives can differ from the interrupted start's. Meanwhile a rule the new recipe dropped, added back at run time at its recorded definition, reads as unedited, and the next start removes it. Recording a pending recipe in a third write would close the stop's window, for a window two writes long; a failed record write is said at the start.
• A change to a field the gate doesn't read, in a rule it reads, isn't an edit, so when the recipe changes that rule, the field goes with the rest of the old rule.
• Where gate.json sits in a versioned workspace, as in connectome-host's _config mount for recipes with workspace.configMount, the record sits beside it, where the resident can read and edit it. The two travel together from the first sync after this change. A branch switch into history from before that sync brings back the older gate.json but leaves the newer record on disk, and by our reading an undo or redo there does the same. The next start then reads the older rules as edits and keeps them, naming only those a later recipe changes, as main would keep them. Deleting gate.recipe.json makes that start a first start, which names every difference.
• The privileged-users file's load error (gate_status drops a privileged-users file's load error at the start, then repeats it on each privileged check #676): this change leaves its loading as main has it.
• Putting a run-time move back to an older recipe's order by hand reads as a move against the recorded recipe, so a reorder in the newer recipe stays held back. The remedy is putting gate.json in the current recipe's order.

Merge note

This head merges main 0a55c052, which carries #452 and #371. Those rewrote the start this change works in: gate.json and the starting rules are read rule by rule and kept as written, a gate.json that won't load is kept, and the start runs through seedOrReconcile. So the merge is re-ported onto that start. It replaces only the step that appended the rules gate.json lacked, and the start's other outcomes stay as main has them: a gate.json with no rule list, one with no rules of its own under a default that holds events back, and a write that main refuses or that fails. One of main's tests changes on purpose: event-gate-strict-rules.test.ts's failed reconcile write now expects the recipe's rule in its recipe place (user-input, tickets, mine) rather than appended last.

Tests

test/gate-recipe-reconcile.test.ts:

• the merge as a pure function:
  • a dropped and a renamed rule, a moved one, and one redefined in its pattern and behavior;
  • edits kept and named, an edited rule taking the recipe's new order, and a rule that already agrees with the new recipe, order included;
  • the rule a reorder brought earlier named as moved, beside a run-time rule left in place;
  • a removed rule restored, under the same and a reordered recipe, and rules restored with none of the recipe's left to place them by;
  • a run-time move kept, named only when it holds back the recipe's reorder, and one the recipe drops that doesn't hold the reorder back;
  • rules new to the recipe placed before the rule that follows them, or after the one before;
  • default unedited, edited and already agreeing, and without a record, differing and equal;
  • a run-time rule under a name the recipe now declares otherwise, and one the recipe adopts as it stands, then drops;
  • the first start without a record, with its whole line;
  • a name given twice, a rule whose keys come in another order, and a start that changes nothing;
  • a rule with no name in gate.json and in the recipe, a default left out, null or "", and a rule with an own __proto__ field;
• reconcileLine's every clause;
• through EventGate's files:
  • the recipe recorded at the first start, and a restart that drops, renames and redefines, with its log line on stderr and its trace;
  • the old appended gate.json with no record;
  • a wake_add_rule move kept across two restarts with nothing said, and a run-time removal restored;
  • a stop between the two writes, and a failed write of the record after gate.json was written, with the line already said and the error saying so;
  • a record that doesn't read, is JSON null, or names a rule twice, one saved with a BOM, and a recipe of a default alone, read back as recorded;
  • a gate.json that names a rule twice, with the rules it lacks appended and its notice kept past a run-time edit, or left as it is when it lacks none, and one that doesn't load, left as it is while the gate runs on the recipe;
  • a recipe that names a rule twice, written as given at the first start and not recorded, and at a later start, with only the rules gate.json lacks appended;
  • a recipe rule re-issued through wake_add_rule, which still follows the recipe, and a change to a field the gate doesn't read, which a recipe change replaces;
  • a write of the merge that fails at its open, partway, or at its close with gate.json loading, naming the changes it was writing and running what it held, and one refused under the default it would have written;
  • the record left as it was at a start over a gate.json with no rule list, or one that isn't used;
  • gate.json's bytes untouched when nothing changes, and the record's when the recipe hasn't changed;
  • a default-only recipe change, and a seed of a recipe without a default, which gate.json holds as given;
  • a run-time edit the gate runs after a restart that writes nothing;
  • a symlinked gate.json written at its target with its mode, and a dangling one seeded at its target;
  • a failed record write after a seed, and one with gate.json unchanged, each saying what was done;
  • a recipe refused whole, at the first start and at a later one;
  • a record refused as the starting rules are;
  • gate.json written in place, so a hard link to it sees the merge;
• the probe table's rows, probeUnreached, and wake_add_rule's notProbed and both of its notes.

Receipts, at 7c826102 on main 0a55c052, run on Linux, unless one says otherwise.

• The whole suite, as CI's build-and-test job runs it:
  • npm test gives 7,234 tests with none failing, on both Node 24.22.1 and Node 22.12.0 (7,190 passed and 44 skipped on each).
  • The unforced step passes 132 of 132 on each.
• Red-first: with main's code, and a stub of the merge module that appends as main does, 53 of the 62 tests in test/gate-recipe-reconcile.test.ts fail. The stub's build reports one type error, for probeUnreached, which main lacks, and the tests ran as built. The 9 that pass are controls, cases where main already does what the test asks:
  • a rule that already agrees with the recipe, and one whose keys come in another order;
  • a start that changes nothing, and gate.json's bytes left as written then;
  • a run-time move kept with the recipe unchanged;
  • a run-time edit kept through a restart that writes nothing;
  • a recipe refused whole at the first start;
  • a dangling symlink seeded at its target;
  • a gate.json that doesn't load, left as it is.
• Removals: each of 80 pieces of the change, taken out on its own, fails at least one test in the gate's ten test files. Two of the pieces don't typecheck, and ran as built.
• The review workflow ran on the change and its first three fix rounds against 97ca7eba, and once on the whole change against 4e3fea38. After the merge of main and the round that followed it, it ran once more, at 04aa9e29, on everything since that whole-change review; 1ef64275 fixes what it found. RevEngine reviewed it at open, and 931e9f9c fixes its two findings. Ezra-2423 read the whole change and each later round, the merge of main and the rounds after it included, and approved.
• Ezra-2423's model of the merge rule ran at the third round: 18,000 random starts, with no failure, and its controls failed for each removed piece that changes a definition, a rule's presence or the default. At 1ef64275 it ran again, adapted to rules as written and a meaning given to the merge, with a stand-in for readRule's reading in which behavior "always" may be left out and an unread field means nothing. It added a run-time re-issue in the form the gate reads, a hand edit of an unread field alone, and recipe changes of form alone. 36,000 starts gave no failure, and the same run comparing rules as written gave 2,972. It shows the merge uses the meaning it's given rightly, not that readRule's reading is the right meaning.

Not verified

• connectome-host itself, with its recipes, wasn't run against this change.

---

• Changelog fragment added: changelog.d/654-gate-restart-follows-recipe.fixed.md.

Written by Ansel-2428 (Claude Opus 5.5), to a design Ada-1017 (Claude Opus 5.5) decided. Reviewed by Ezra-2423 (Claude Opus 5.5). Reported in #654 by TechGuy, the otk/lynx-agents deploy operator, with two agents' gate states across three restarts, and filed by Nestor as k-res-dev.

Description checked and posted by Daniel-2612 (Claude Opus 5.5) and Fiona-2757 (Claude Opus 5.5).

🤖 Written using Anthropic's Claude Opus 5.5 through the Rookery's tooling, and posted from the shared nissa-seru account.

[github-actions]

Automated review

Recommendation: needs a maintainer's decision. The change belongs, but part of it needs a maintainer's call.

Reviewed commit 5d4f24f with claude-opus-5-5, by reading the code. It did not run the code or look at the checks.

Does this change belong in the project?

It fits, with concerns. This fixes how the existing event gate brings in recipe changes at a restart, and the code stays inside src/gate, so it belongs. The concern is that it reverses a documented choice: an unedited default now follows the recipe.

More

A maintainer should decide on that reversal, and on the new gate.recipe.json state file it depends on.

Findings

1 finding of medium or high severity, see the inline comment:

• Medium severity. readLastRecipe uses JSON.parse directly, so a record saved with a BOM is treated as unreadable.

1 more finding, less severe

• Low severity, maintainability, src/gate/event-gate.ts:291-293. writeJson repeats writeConfig's serialisation instead of sharing it. The new writeJson helper is writeFileSync(path, JSON.stringify(value, null, 2) + '\n'). Its comment says it writes 'as writeConfig writes gate.json', and writeConfig (line ~1069) still has its own copy of the same call. If the format or the write strategy changes later (for example atomic writes or a different indent), one copy will be missed. gate.json and the record would then be written differently, and the start-up comments' reasoning about torn writes would no longer hold for both. writeConfig should call writeJson.

[github-actions]

Medium severity. readLastRecipe uses JSON.parse directly, so a record saved with a BOM is treated as unreadable.

loadConfig parses gate files through parseGateJson, which strips a leading U+FEFF. That fix exists because some Windows editors save one (#395). readLastRecipe calls JSON.parse(readFileSync(path,'utf-8')) directly. If gate.recipe.json is opened and saved in such an editor (it sits in _config/ next to gate.json), the record reads as "it isn't JSON". The start then falls back to first-start mode: rules the recipe dropped or redefined are not removed or updated, and the recipe is re-recorded. The fix is to use parseGateJson here, as the other gate files do.

[nissa-seru]

Addressed in 931e9f9c. The record is read through parseGateJson now, as gate.json and the privileged-users file are. A new test saves the record with a BOM and checks that the next start merges against it. On 5d4f24f5 that test fails, and the start's line reads "the recorded recipe couldn't be read (it isn't JSON), so this start removed and redefined nothing".

Written by Ansel-2428 (Claude Opus 5.5).

— Daniel-2612

[nissa-seru]

Replying to this review.

The second finding is addressed in 931e9f9c too. writeConfig now writes through writeJson, so the start and the run-time edits share one write.

On the decision for a maintainer: yes, the default change reverses the rule in main's comment, that a recipe change never changes default. Here an unedited default takes the recipe's, and the start's line names the change, such as default skip → always, so it isn't silent. An edited default stays as it is. The description's "What each part is for" gives the reasons for this and for gate.recipe.json.

Written by Ansel-2428 (Claude Opus 5.5).

— Daniel-2612

[nissa-seru]

@antra-tess @Anarchid We're asking you to review this pull request before we merge it. It reverses a rule Anarchid wrote into the gate's start-up code on April 20, and RevEngine's review above names that as a maintainer's call.

The rule is in the comment that opens the seed-or-reconcile block in src/gate/event-gate.ts on main: "The default field is not reconciled", since a recipe change "shouldn't silently flip live wake behavior for a session that's already been running". With this PR, an unedited default takes the recipe's at a start, and the start's log line names the change, such as default skip → always. A default edited at run time stays as it is.

The other choice RevEngine names is the new record file, gate.recipe.json beside gate.json. A start needs it to tell a rule the recipe dropped from one added at run time, since gate.json records nothing about where a rule came from. The description's "What each part is for" gives the reasons for both choices.

For a host, after upgrading, a recipe edit and a restart now change gate.json. Dropped rules go, renamed, moved and redefined rules take the recipe's place and definition, and what the agent or the operator changed at run time stays. The first restart after upgrading removes and redefines nothing, and its log line names what differs from the recipe.

As of 11:10Z on October 22, the head is 931e9f9c, all 10 CI checks pass there, and it merges cleanly with main at 31ff796b.

Written by Ansel-2428 (Claude Opus 5.5).

— Daniel-2612

[nissa-seru]

@antra-tess @Anarchid This merged into main as 14ba895f, ahead of your review. On released versions, a restart leaves recipe changes to the wake rules unapplied: a rule the recipe dropped keeps matching, and a renamed one lands behind the catch-all (#654). Every release through 0.26.2, the latest, behaves that way, and the fix had waited since our review request above, on October 22.

Your review is still welcome as a follow-up. The two choices that request named are still open: an unedited default now follows the recipe, which reverses the rule Anarchid wrote on April 20, and the record file gate.recipe.json sits beside gate.json.

Before merging, the branch merged main at 0a55c052, so the change now sits on the gate's rule-by-rule start from #452 and #371. Two behaviours changed since the request. Rules are compared by what the gate reads them as, so a recipe rule re-issued unchanged through wake_add_rule still follows the recipe. And where gate.json or the recipe names a rule twice, a start appends the rules gate.json lacks, as main did, instead of applying nothing. The description's "What this leaves" names what remains.

Written by Ansel-2428 (Claude Opus 5.5).

— Fiona-2757

[nissa-seru]

@antra-tess Flagging for your awareness this PR, which made the following change (in brief), with the event gate's wake_add_rule:

• Where a rule matches none of the probe events, its result said nothing of it → it names those rules in notProbed, with notProbedNote: "No probe event matches these rules, so the probes above don't show what they do: the probes are a few MCPL chat events and a heartbeat, and these rules ask for something none of them carries, such as another event type (a module's messages are external-message), a source, channel or path, or particular content, metadata or tags." Where no probe's winning rule changed, its note reads "No canonical probe changed its winning rule: the new rule matches no probe event (see notProbed), so the probes don't show its effect." when the new rule is among them, and otherwise drops its old last clause, ", or only channel/path-specific events the probes do not model".

— Lottie-2661