[rufalupa666-netizen]

Carries #179 (Ian de Marcellus) over the line, as offered there on Oct 26. Ian's commit is the base; the commits on top answer the Oct 20 review, then this PR's own review (R2: the hold moved out of the gate). Ian, it's yours to take back at any point.

Where the hold lives (R2). The gate decides whether a message wakes the agent; the scheduler decides when a turn starts, and a burst is a question of when. FrameworkConfig.messageQuietPeriod: { quietMs, maxWaitMs? } makes runInferencePass hold an idle agent's turn while every wake queued for it is a message wake — mcpl:channel-incoming or mcpl:push-event, other than the heartbeat's, and neither a continuation nor a retry of the turn — until quietMs after the newest or maxWaitMs (default 30 s) after the oldest (quietHoldRemaining). The requests go back to the queue as a busy agent's do; the loop's next pass reads them again; the scheduler's existing merge of queued wakes makes the one turn. A batch holding any other wake starts now. The gate is main's.

What that keeps as main has it. Each message's own decision: who wakes a sleeping agent (a privileged author's ping), where a reply goes (the direct path's channelId), what a skipped message does (queues no wake, so extends nothing), and what tune-out and conversation routing read. These were the four behaviours R1's gate-level hold changed (nissa-seru's runs, slimepriestess's re-read); the hold now never sees a message's decision.

Config. Read once at create(): both numbers finite and 0 or more, else the config is refused. Off when omitted.

Tests. quietHoldRemaining on fixed clocks: a burst, quiet, the cap, a cap below quietMs, a server event, the heartbeat, other wakes, continuations and retries. The scheduler against a real framework, with wide margins: one turn per burst, the option off, the cap under a stream, an operator's wake ending a hold, refused configs.

History. R1 (bbd1a80a) kept the hold in the gate and routed it through the debounce buffer, closing the Oct 20 review's two blocking points; its review found the cost of that layer, and R2 moves the hold. Both rounds are in the commits.

Suite at 72ee758c (Node 22.22.1): 8805 tests, 8698 pass, 1 fail, 106 skipped; the one failure is code-execution-env (npm install from the isolate on our host), unchanged from main. CI green.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SkepYxcPem6pmgRxKd2RBY

[github-actions]

Automated review

Recommendation: fix, then merge. 1 high severity finding should be fixed first.

Reviewed commit bbd1a80 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 the project. This fits. It adds an opt-in, off-by-default wake-holding option to the existing event gate, and the held wake is delivered through the gate's own debounce batch path.

5 reasons with sources

The PR follows the contributing guide's conventions.

• The change stays inside the event gate, which already owns wake timing: debounce, judge batches, sleep and quiesce. The hold is added next to the existing debounceTimers and judge state. It ends through fireBatch, a function factored out of the debounce path, so the gate does not get a second delivery path. The framework only passes the option through, in one line. (src/gate/event-gate.ts)
• It is opt-in and off by default, and the only new public surface is one GateOptions field and one optional GateDecision flag. messageQuietPeriod?: { quietMs, maxWaitMs? } sits next to the other GateOptions such as judge. quietHeld? is optional on GateDecision. When the option is unset, behaviour is unchanged. (src/gate/types.ts)
• The README says almost nothing about the gate's scope, so this verdict rests on how the code is organised. Searching the README turns up no description of the gate or of debouncing. Nothing in it rules out a per-channel quiet period, and nothing asks for one. (README.md)
• The PR follows the contributing guide: a changelog fragment, tests, numeric test counts, and the AI-authorship footer. It adds the fragment changelog.d/feat-gate-message-quiet-period.added.md, adds test/event-gate-quiet-period.test.ts, and reports 8533 tests with 8433 passing, 1 failing (also failing on main) and 99 skipped. It also credits the original contributor of #179 and says what it left unchanged. (CONTRIBUTING.md)
• A maintainer may want to look at the overlap with debounce policies, which also batch wakes and give the gate a second batching concept. The quiet period works per channel and applies to messages across all policies, while debounce works per policy, so the two differ. Both feed the same fireBatch. The PR leaves fork routing and tune-out as main handles them for debounce batches, and the code review has flagged how those see held messages. (src/gate/event-gate.ts)

Findings

8 findings of medium or high severity, see the inline comments:

• High severity. A privileged user's message to a sleeping agent is held, then dropped as asleep.
• Medium severity. Any skipped message, not just a rate-limited part of the burst, extends an open hold.
• Medium severity. quietMs/maxWaitMs are not checked for finite, in-range values.
• Medium severity. Held ambient messages lose the reply route to their own channel.
• Medium severity. A held message reaches the framework as untriggered: fork routing, targetAgents and tune-out all see a 'no'.
• Medium severity, test coverage. Tests depend on tight real-time margins and are likely to be flaky.
• Medium severity, test coverage. No test for a privileged message, or a held message, while asleep.
• Medium severity, test coverage. Missing tests for ambient routing, push-event holds and mixed debounce/quiet batches.

5 more findings, less severe

• Low severity, documentation, src/gate/types.ts:233-236. The doc says every held wake carries the burst's route, but only addressed messages get one. The option's doc and the changelog fragment say the held wake 'carries the burst's route'. wakeProvenance sets routeChannelId only when the chosen event is addressed. An ambient burst's wake carries no route and falls back to the most-recent-inbound locus. The doc should say so, or the code should route ambient bursts as well.
• Low severity, maintainability, src/gate/event-gate.ts:3146-3156. The decision trace does not show that a message was held. For a held message, the gate:decision trace reports trigger: false under the matched policy name and has no quietHeld field. Operators reading traces therefore cannot tell a held wake from a policy skip. The default-policy stats also count the event as triggered (line 3117) even though it did not trigger. Add quietHeld to the trace.
• Low severity, maintainability, src/gate/event-gate.ts:3585-3589. A no-op placeholder timer is created and then cleared at once. holdForQuietPeriod stores setTimeout(() => {}, 0) only so that armQuietHold can clear it straight away. This allocates a timer for nothing and makes the code harder to read. Make the timer field optional, or arm the hold directly.
• Low severity, maintainability, src/gate/event-gate.ts:3558-3580. The PendingEvent construction is copied from handleDebounce. holdForQuietPeriod repeats the ~20-line PendingEvent literal from handleDebounce (lines 3631-3650): snippet truncation, channelLabel, authorId, addressed, routeChannelId, messageId and eventId. Any future fix to how events are shaped, such as route resolution, must now be made in two places. Pull it out into a shared pendingEventFor(policyName, info, inContext) helper. As written, it also calls routeChannelFor twice per held message: once in quietKeyFor and once here.
• Low severity, documentation, src/gate/event-gate.ts:1998-2002. The comment names fireDebounce, but the hold goes through fireBatch. The field comment says the hold fires 'through the debounce path (fireDebounce)'. fireQuietHold actually calls fireBatch directly and skips fireDebounce's judge branch. The comment should name fireBatch.

For a deeper review by several readers and a judge, which takes longer, a maintainer can comment /review deep.

[github-actions]

High severity. A privileged user's message to a sleeping agent is held, then dropped as asleep.

evaluate deliberately lets a privileged author's message through while asleep (lines 3063-3083) so it can wake the agent. With messageQuietPeriod on, that message's trigger becomes a quiet hold (line 3138). When the hold ends, fireQuietHold checks only this.sleepUntil > this.now() and drops the whole batch as 'asleep', without looking at who wrote it. So with the option on, a privileged ping can never wake a sleeping agent, which breaks a feature the sleep design documents. Either skip holding when the agent is asleep and the author is privileged, or keep privileged events when the hold ends. No test covers this case.

[github-actions]

Medium severity. Any skipped message, not just a rate-limited part of the burst, extends an open hold.

The else if (this.quietHolds.has(key)) branch re-arms the hold for every untriggered channel-incoming or push-event in the channel, whatever made it untriggered. That includes messages a skip/never policy rejects on purpose, such as bot output, ambient chatter or other agents' messages. In a busy channel where the policies skip most traffic, an addressed human message's wake is therefore pushed back to the full maxWaitMs (30 s by default), well past quietMs. The comment and the option's doc justify this only for rate-limited parts of the same burst. Restrict re-arming to rate-limit denials, or to the same author.

[github-actions]

Medium severity. quietMs/maxWaitMs are not checked for finite, in-range values.

The constructor clamps only with Math.max(0, …), unlike judgeTimeoutMs (line 2185), which requires Number.isFinite(...) && > 0. A NaN maxWaitMs, for example from a malformed or string-typed host config, gives a NaN wait in armQuietHold. Values above about 2^31-1 ms overflow the timer. Node's setTimeout treats a NaN or out-of-range delay as 1 ms, so the hold would fire almost at once and silently stop batching, with no error or log. Validate the values and warn on bad ones.

[github-actions]

Medium severity. Held ambient messages lose the reply route to their own channel.

On the direct path (framework.ts ~14706-14727), every triggered channel-incoming wake carries channelId: event.channelId, so the turn's speech goes back to that channel, whether or not the message was addressed. With the hold, the wake's route comes from wakeProvenance, which sets routeChannelId only for addressed events (lines 329-331). An ambient burst's wake then falls back to the process-wide most-recent-inbound locus, which the framework comment at framework.ts 4316-4320 names as the bug that path fixed. Turning on the option therefore changes where replies to ordinary channel chatter are posted. The tests check only the addressed case.

[github-actions]

Medium severity. A held message reaches the framework as untriggered: fork routing, targetAgents and tune-out all see a 'no'.

Rewriting decision.trigger to false makes ChannelRegistry/PushHandler stamp triggerInference: false. Several things change as a result. The stored message gets triggered: false. routeConversationIncoming queues no wake for the channel's fork. deliverTo / targetAgents targeting is ignored, because the later wake goes to every name getAgentNames returns, the dormant trunk template and every fork included. The tune-out coordinator receives the resident verdict as false (framework.ts 14689), so subconscious wakes it depends on are never armed, and coalescingSubject does not ride the wake. The debounce path behaves the same way, but it only applies to operator-chosen policies; this option applies to every message, so it alters these subsystems across the board. A conversation-router or tune-out deployment that enables it will misroute wakes.

[github-actions]

Medium severity, test coverage. Tests depend on tight real-time margins and are likely to be flaky.

The tests use real setTimeout with margins of 10-40 ms. Examples: asserting Date.now() - start < 190 against a 120 ms cap, sleep(35) chosen to land between a 60 ms quiet period and 75 ms, and per-channel loops that expect exactly two wakes after sleep(120). On a loaded CI runner these fail at random. The gate takes an injectable now, and the tests could use node:test mock timers instead of wall-clock sleeps.

[github-actions]

Medium severity, test coverage. No test for a privileged message, or a held message, while asleep.

The sleep test covers only an ordinary message that was held before the sleep began. Nothing checks that a privileged author's message during sleep still wakes the agent with quiet period on, and today it does not. A test for that case is needed.

[github-actions]

Medium severity, test coverage. Missing tests for ambient routing, push-event holds and mixed debounce/quiet batches.

The route test covers only an addressed DM. No test holds an ambient message and checks where its wake routes. No test uses mcpl:push-event apart from the heartbeat. The PR says a batch that mixes a debounce policy's events with quiet-period events keeps the debounce's [Gate: …] line and the gate:debounce reason (deliverEvents lines 3739, 3826), but no test exercises that branch.

[nissa-seru]

@rufalupa666-netizen @ian-de-marcellus The burst problem is real, and this pull request now has a test for each of the Oct 20 review's two blocking points, both passing in its CI at bbd1a80a. With messageQuietPeriod on, though, four other behaviours change, each shown below by a run. Three of the four come from the hold turning a message's own decision into "no" and waking later through the batch path, so we suggest holding where the framework starts a turn instead.

The problem. #​179's measurement (891 of 1,428 follow-up parts within 2 s of the previous one, over about 4.7k messages) and @slimepriestess's Oct 20 review ("the burst problem is real. Main still has nothing that does this.") stand. We ran nothing for it.

What changes with the option on. At bbd1a80a, a message that would wake the agent gets the decision { trigger: false, quietHeld: true } (src/gate/event-gate.ts:3140). When the hold ends, fireQuietHold (:3605) wakes the agent through fireBatch (:3624). We ran the cases below on Linux with Bun 1.4.4 running the TypeScript sources. The framework runs used @animalabs/membrane 0.8.0 and @animalabs/context-manager 0.23.1. Cases (a) to (c) ran against the gate, built as test/event-gate-quiet-period.test.ts builds it: (a) with the option off and on, and (b) and (c) with it on. Cases (b) and (d) also ran through a real AgentFramework with the repository's MockMembrane and its MCPL test servers, at this head and at 59d60958.

• (a) A privileged author's message no longer wakes a sleeping agent. With the agent asleep and the author on the privileged-users list, the gate's decision with the option off is trigger: true, since the sleep check at :3063 lets a privileged author through. With it on, the decision is trigger: false, quietHeld: true, and 80 ms later, with quietMs 30, the gate had requested no wake. :3610 drops a hold that ends while the agent sleeps. So the description's "A hold that ends while the agent sleeps is dropped and counted as suppressed, as the messages' own wakes would have been" doesn't hold for a privileged author, whose own message, with the option off, got the decision trigger: true while the agent slept. RevEngine's high-severity finding says the same.
• (b) A reply can go to another channel. At the gate, a held ambient message's wake carried routeChannelId: null, and a held addressed message's carried its channel. Through the framework, an ambient message came in #room, and 150 ms later an ambient message came in #general, which a policy skips. With the option off, at this head and at 59d60958, the agent took one turn, in #room, and its reply went to #room. With it on (quietMs 1000), the turn was in #general, and the reply went to #general. We ran only this case, with a second channel's message during the hold. RevEngine's finding on the held route says the same.
• (c) Messages the policies skip keep an open hold going. With quietMs 60 and maxWaitMs 400, an addressed message came, then eight bot messages 40 ms apart in the same channel, each skipped by a policy. The addressed message's wake came at 398 ms, against quietMs 60 and maxWaitMs 400. The description gives the extension for "A part the policies didn't trigger (a rate-limited image after its caption)", and :3141 extends an open hold for any message in its channel the policies didn't trigger. RevEngine's medium-severity finding "Any skipped message, not just a rate-limited part of the burst, extends an open hold" says the same.
• (d) Tune-out and conversation routing see a held message as "no". The description leaves these "as main has them for a debounce batch", and the Oct 20 review raised them by reading. Through the framework:
  • Tune-out: the resident had tuned out a channel, and an addressed message came in it. With the option off, at this head and at 59d60958, the message got tune-out's acknowledgement (channels/acknowledge with the intent suppressed-tuned-out), and the Subconscious took one turn. With it on, there was no acknowledgement and no Subconscious turn, and the resident took one turn, in the tuned-out channel.
  • Conversation routing (FrameworkConfig.conversations, set to bind and trigger on every channel message): with the option off, a message in #room gave one turn, by the channel's fork. With it on, it gave two, the trunk's and the fork's.
  • Per-policy debounce, as the Oct 20 review puts it, "needs a policy match". :3132–3140 hold every channel message or push event whose decision is trigger: true, apart from the heartbeat's. So what the description leaves "as main has them for a debounce batch" reaches, with this option, every channel message or push event that would wake the agent, not only the ones a debounce policy matches.

A suggestion: the delay where a turn starts. The gate decides whether a message wakes the agent, and the framework's scheduler decides when a turn starts. A burst is a question of when. The scheduler already merges the wakes queued for an agent into one turn when the turn starts (runInferencePass, src/framework.ts:16538 at 59d60958), and test/batched-wake-line.test.ts's "four wakes merged into one turn" pins that with one provider call. Our suggestion is to hold an idle agent's turn start while message wakes for it keep arriving, up to quietMs after the last and maxWaitMs after the first, then start one turn with everything queued. We think that gives one turn per burst while each message's decision stays what the gate gives today, so sleep and privileged authors, each message's route, tune-out and conversation routing see what they see on main. A start that continues a turn already under way, or retries a failed one, would go ahead without waiting.

That's another layer than the Oct 20 review asked for: its first blocking point asked that a hold ending mid-turn go through the debounce buffer, and this pull request does. We suggest it because a hold kept in the gate has to rebuild, for each part of the framework, what a message's own wake would have carried, and (a), (b) and (d) are where that doesn't happen yet.

Duncan-2410 ran these cases, and Daniel-2612 wrote this comment.

— Daniel-2612

[slimepriestess]

@rufalupa666-netizen thank you for carrying this, and for answering each point of the Oct 20 review with a test. Here is the re-read at bbd1a80a. I'm the reviewer of record from #179. Both of my blocking points are closed, by run. I've also reproduced two of @nissa-seru's four findings, and I agree with their suggestion for where the hold belongs.

The Oct 20 review, closed

I ran my October probes against this head's build (macOS, Node 22.21.1):

• A hold that ends mid-turn now wakes the agent once after the turn ends; at #179 it never did.
• Nothing fires after dispose().
• A held DM's wake carries its route (routeChannelId: discord:dm:42).

Nine breakages, each applied alone, each fail their own new test by name:

• the old skip-the-inferring-agent firing;
• no route on the held event;
• one global hold;
• dispose() keeping holds;
• the heartbeat held;
• maxWaitMs raised to quietMs;
• an untriggered part not extending;
• firing while asleep;
• the framework's pass-through removed.

Full suite at this head: 8,535 tests, 8,490 pass, 0 fail, 45 skipped (macOS filesystem rules). Main has moved since 59d60958, and the one conflict is mechanical: main's eventTypesFrom option and this PR's messageQuietPeriod are added beside each other in the gate's constructor options, and keeping both resolves it.

nissa's findings: two reproduced

At the gate, with the same build:

• (a) With the agent asleep, a privileged author's message gets trigger: true with the option off. With it on, it gets trigger: false, quietHeld: true, and no wake follows (quietMs 30, read at 80 ms). That's a ping the sleep rule lets through, now lost.
• (c) With quietMs 60 and maxWaitMs 400, eight messages a policy skips, 40 ms apart, pushed an addressed message's wake to 391 ms.

I didn't run (b) or (d), which need the framework; those rest on their runs.

Where the hold belongs

My Oct 20 review is part of how the hold came to live in the gate. My first blocking point suggested routing the inferring agent through the gate's debounce buffer, and this PR did exactly that. But nissa's (a), (b) and (d) show the cost of that layer: once the gate says "no" and wakes later, every part of the framework that reads a message's own decision has to be rebuilt for the held one (sleep's privileged exception, the per-message route, tune-out, conversation routing).

Delaying where the framework starts a turn, as they suggest, keeps each message's decision what it is today. It also covers my first point without the gate's help: a start that continues a turn already under way goes ahead. I'd take their suggestion over fixing (a) to (d) one by one in the gate. It's your and Ian's call, and nissa's house's.

Happy to re-read whichever shape it takes.

[rufalupa666-netizen]

Thank you both — the runs are clear, and we'll take the suggestion: the hold moves out of the gate to where the scheduler starts an idle agent's turn (quietMs after the last message wake, maxWaitMs after the first, continuations and retries unheld), so each message's decision stays what the gate gives today. The gate changes come out; the tests move to the scheduler and onto mock timers. R2 at this PR, a day or so.

[rufalupa666-netizen]

R2 is up: 0f0292f8 merges main (e85c57db), 2195f772 moves the hold to where the scheduler starts an idle agent's turn, and 72ee758c is a one-line follow-up for prototype-built harnesses.

What moved. The gate is main's again: no quietHeld, no gate option. FrameworkConfig.messageQuietPeriod: { quietMs, maxWaitMs? } is read once (finite, 0 or more; maxWaitMs defaults to 30 s). In runInferencePass, after the busy requeue, an idle agent's batch waits while every wake in it is a message wake — mcpl:channel-incoming or mcpl:push-event, other than the heartbeat's, and neither a continuation nor a retry of the turn — until quietMs after the newest or maxWaitMs after the oldest (quietHoldRemaining, exported). The requests go back to the queue as a busy agent's do and the loop's next pass reads them again; the merge at the start makes the one turn. A batch holding any other wake starts now.

(a) to (d). Each message keeps what the gate and the ingress gave it, so a privileged author's ping wakes a sleeping agent as on main, a held wake's route is the direct path's channelId, a skipped message queues no wake and so extends nothing, and tune-out and conversation routing read the same verdicts they read today. The hold never sees a message's decision, only whether a queued wake is a message's.

Tests. quietHoldRemaining on fixed clocks (burst, quiet, the cap, a cap below quietMs, server events, the heartbeat, other wakes, continuations and retries), and the scheduler against a real framework with wide margins (one turn per burst, the option off, the cap under a stream, an operator's wake ending a hold, refused configs). The gate-level tests went with the gate's hold.

Suite at 72ee758c (Node 22.22.1): 8805 tests, 8698 pass, 1 fail, 106 skipped; the one failure is code-execution-env (npm install from the isolate on our host), unchanged from main. CI green.