[nissa-seru]

Why. When one agent's compression call parks at its provider gate, behind its own turn or a provider cooldown, no other agent's next maintenance pass can start until that turn ends, the cooldown passes, or a surgery or stop() withdraws the call. This keeps that parked call from holding up the other agents' maintenance.

Other agents' maintenance while one agent's compression call is parked

• base (main): one maintenance pass runs at a time, and it ends only once every agent it ticked has settled, so the parked call holds every other agent's next pass until its turn ends, its cooldown passes, or a surgery or stop() withdraws it.
• head: the parked agent's tick leaves its pass and goes on by itself, and the pass ends with the other agents' work. Later passes skip that agent until its tick settles, then tick it again. stop(), surgeries and resume() still wait for that tick.

A pass's run in the maintenance history

• base (main): a run ends after every agent's entry in it has its finishedAt.
• head: a run can end with the parked agent's entry unfinished, with no finishedAt, until its tick settles, so an entry's finishedAt can come after its run's. Such an entry's leftPassAt says when its tick left the pass.

An operator's maintain

• base (main): it returns when its pass ends, once every agent that pass ticked has settled.
• head: it returns when its pass ends, which can be before a parked agent's tick settles, so that agent's entry in the snapshot it returns can be unfinished, with leftPassAt saying when its tick left. A pass begun while that tick goes on, an operator's maintain included, skips that agent.

A compression call that is slow without parking still holds its pass, as on main. Every run of this used a mocked provider, not a live host, and no test reads the snapshot a maintain returns while a tick it started is parked.

• Changelog fragments added: changelog.d/maintenance-parked-call-leaves-pass.fixed.md and changelog.d/maintenance-left-pass-at.added.md.

Credits

Ada-1017 made its design calls, Cedric-2714 built it, and Alfred-2451 read it. Gladys-2592 checked that it was worth bringing onto main, and read the merge. Phoebe-2419 checked that its end state was the one to choose, which led to 7224aecc84ea, and read that round. Basil-1007 checked where each change sits, and Cordelia-2434 whether each part pays for itself. Duncan-2410 wrote its description, Cedric-2714 revised it for 6eef037ec3 and for the merge, and Myrtle-2415 put it in this shape.

Details for agents

At 6eef037ec3e8, whose merge base with main is a64cfc010f. 1ac2485e2572 merges main into it twice, aa134e75fc at 59f25061cd and then 6c7810995c34, and the head, 7224aecc84ea, adds two commits on that, as the last three bullets of Tests describe. Problem's probe ran at a64cfc010f, and the red runs in Tests use its src/framework.ts. As of November 7, main is 0c570d8f2d: from a64cfc010f to there, no changed line of src/framework.ts names maintenance, the provider gate or auxiliary admission. At 0c570d8f2d:

• One pass at a time: startQueuedMaintenance returns while a pass is running (src/framework.ts:7198–7199), and an operator's maintain joins that pass and returns once it ends (maintenanceTick, :10074, awaiting the pass at :10093).
• A pass waits for every agent it ticks: runQueuedMaintenance (:7251) leaves out an agent whose provider gate is blocked when the pass starts (:7304), ticks each other agent with work queued up to 8 times (MAINTENANCE_TICKS_PER_PASS, :2585), and waits for every agent's ticks to settle (Promise.allSettled, :7342–7343). Each agent's entry gets its finishedAt when its ticks settle (:7376), and the run gets its own after all of them (:7399).
• A call parks partway through: withAuxiliaryAdmission parks a compression call while its agent's provider gate is blocked (:6168), by its own turn or a provider cooldown (providerGateBlocked, :6119–6123). A surgery that takes the store or a stop() that closes admission wakes it and withdraws it (:6164–6179), with a MaintenanceWithdrawnError that settles its tick (:6208–6221).
• The history holds at most 50 runs (:7409).

At a64cfc010f a pass ended only once every agent's ticks had settled, and one pass runs at a time. So a tick whose call parked partway through a pass, behind a turn its own agent had started or behind a provider cooldown, held the pass until that turn ended or the cooldown passed, so no other agent's maintenance could start in a new pass meanwhile. This branch's new tests show it. Run over a64cfc010f's src/framework.ts, the two that check another agent's maintenance while one call is parked time out waiting for it, and with the source and tests of 954b922f18, this branch's first commit, all nine new tests pass.

Problem

At a64cfc010f:

• A pass waits for every agent it ticks. runQueuedMaintenance (src/framework.ts:7128) ticks each agent with context work queued whose provider gate is open when the pass starts (:7181), up to 8 ticks each (MAINTENANCE_TICKS_PER_PASS, :2488). The pass ends when every agent's ticks have settled (Promise.allSettled, :7220), and one pass runs at a time.
• A compression call can park partway through. An agent's compression calls go through withAuxiliaryAdmission (:6061), which parks a call while that agent's provider gate is blocked (:6071): its own turn holds the gate, or a provider cooldown does (providerGateBlocked, :6022).
• So one parked call holds the next pass. A tick whose call parked after the pass started held the pass until the turn ended or the cooldown passed, so no other agent's maintenance could start in a new pass meanwhile.

In a probe outside this branch at a64cfc010f, agent A's second compression call parked behind A's own turn, and agent B, queued then, made no call for 600 ms. Once A's turn was released, A's call went out 1 ms later and B's 5 ms later.

Changes

• A tick that parks leaves its pass. The pass races each tick against that agent's call parking, and a tick that parks goes on by itself. The pass ends with the other agents' work.
• Later passes skip that agent until its tick settles, then tick it again.
• Every wait still covers it. stop(), surgeries (rollbackToMessage, suppressMessages, switchBranch, undo and redo) and resume() wait for a tick that left its pass, including a wait begun before the tick left. stop() and surgeries still wake and withdraw a parked call.
• The agent's entry in that pass's run is completed when the tick settles: its ticks, readiness, end time and progress, and any failure, which is logged and alerted as a failure during the pass is, even if alerting it throws.
• stop()'s doc names a tick that left its pass among the maintenance in flight it waits for.
• resume() also waits for a pass that starts while it waits (6eef037ec3). A wait for maintenance can outlast its pass while a tick that left it goes on, and the timer can start a new pass meanwhile. The wait now waits for each pass, over-budget drain kick and tick that left a pass that it finds running, then looks again for any that started meanwhile. stop() and surgeries meet no such pass's work: once stop() has begun no pass starts, and a pass that starts under a surgery's hold ticks nothing.
• A pass that left only a repeated failure stays out of the history (6eef037ec3). A pass whose every entry is a failure already reported, with no tick taken, stays out of the history unless an operator's maintain asked for it. A tick that left its pass meets its failure only when it settles, so the decision is now made again then.
• maintenanceTick()'s doc says it returns when its pass ends, that a parked tick's entry in the snapshot it returns can be unfinished, and that resume() waits for that tick (6eef037ec3).
• An entry whose tick left its pass says when (7224aecc84ea). ContextMaintenanceAgentRun.leftPassAt is set when the tick leaves (src/framework.ts:8523): a provider call of that agent parked at its provider gate while the tick ran, the tick's own, behind the agent's turn or a provider cooldown, or another of the agent's calls, such as an over-budget drain's. It stays once the tick settles, and an entry whose work finished in its pass has none. maintenanceTick()'s doc names it.
• A budget hold's evidence look runs when such a tick settles (7224aecc84ea). main looks for evidence to release budget holds when a pass ends (releaseBudgetHoldsOnEvidence, :8324), and there a pass ended after a parked tick's work. With the tick out of its pass, that look runs while the tick is still parked, so the tick's own end now looks for its agent (releaseBudgetHoldOnEvidence, :8547). Without it, a strategy that records its progress a macrotask after its call's answer would have its hold wait for the next pass to end: the timer starts that pass within one maintenance interval, and it ends once its agents' ticks settle. context-manager's autobiographical strategy records in the answer's own microtask run, where the look queued when a call lands (managerCallLanded, :7054) already sees it.

For a host, the other agents' maintenance goes on while one agent's call is parked. A pass's run can end with that agent's entry unfinished, with no finishedAt, until its tick settles. So an entry's finishedAt can now come after its run's, and its leftPassAt says when its tick left.

Tests

On Linux with Node 24.22.2 and npm 11.19.1, on the source and tests of 954b922f18, after npm install installed @animalabs/membrane 0.8.0, @animalabs/chronicle 0.5.1 and @animalabs/context-manager 0.24.2:

• The new tests, in test/maintenance-timer.test.ts: nine, on one fixture of two agents on one framework, where A's second call parks behind A's own turn or behind a provider cooldown. For each gate, B's call goes out while A's is parked, A's goes once the gate opens, and A's entry in the pass's run is unfinished when the pass ends and finished after, ready, with 2 ticks. The others cover stop() withdrawing the parked call with no failure alert, stop() waiting for the tick once its call is in flight, a rollback and resume() each waiting for it, a resume() begun before the tick left its pass, the skip and the later tick, a failure after the tick left, and an alert that throws.
• With that source and those tests: the typecheck is clean, and the 90 test files that build a framework stand-in or name maintenance passes, the provider gate, quiesce or surgeries give 3,871 passing, 2 skipped and 0 failing. The two skipped need a disk that folds case.
• Red first: with a64cfc010f's src/framework.ts and this branch's tests, 6 of the 9 new tests fail. Four time out waiting for maintenance: both gate tests, the resume() begun before the tick left, and the skip and the later tick. The two that check a failure after the tick left find the pass that ticked A not ended, with A's call still parked. The two stop() tests and the rollback and resume() test pass there as well.
• Mutants: seven, each taking one piece of the change out of src/framework.ts, each caught by the tests predicted. They drop the skip, drop the waits' loop over ticks that left, drop a late failure's report, finish the entry at the pass's end, take the waits' list once, run the late tick without its finally, and never tick an agent again once its tick has left.
• For 6eef037ec3, with the same versions: three more tests in test/maintenance-timer.test.ts. resume(), waiting for a tick that left its pass behind a provider cooldown, still waits when the timer starts a pass that ticks B, and returns once B's tick has settled. A pass whose only tick left it, took no tick and failed with the failure already reported leaves the history once that tick settles. The same pass, run by an operator's maintain, stays. With 954b922f18's src/framework.ts, the first two fail and the file's other 64 tests pass. With 6eef037ec3 the typecheck is clean, and the 98 test files that build a framework stand-in or name maintenance passes, the provider gate, quiesce, resume() or a surgery, each run alone, give 4,163 passing, 2 skipped and 0 failing. The two skipped need a disk that folds case.
• Mutants for 6eef037ec3: six, each changing one piece of it in src/framework.ts, each caught. Putting back the wait's old form fails the resume() test. Removing the second decision fails the history test, and dropping its exemption for an operator's maintain fails the maintain test. Leaving drain kicks out of what the wait looks for fails three stop() tests with a drain kick. Removing the second decision's check of the run's entries fails nine tests in which a tick leaves its pass. A wait that loops while anything is registered doesn't end within 120 seconds in test/stop-with-host-operations.test.ts or test/diagnostics-signal.test.ts, whose stand-in passes stay registered once settled.
• For 59f25061cd, the merge of main aa134e75fc into 6eef037ec3: one conflict, in the maintenance pass's tick. main no longer withdraws a tick that an undo or redo moved the store under, a branch feat(presentation): one record, a presentation index per agent — the deferral queue replaced (#291 step 3) #844 took out, so the merge takes that branch out of tickFailed and the same clause out of the readiness check. tickFailed is now main's catch, and the readiness check is main's. Otherwise this branch's diff onto main is its diff onto a64cfc010f, with its tests and changelog fragment unchanged. With main's src/framework.ts and the merge's tests, on Linux with Node 24.22.2 and context-manager 0.25.0, 9 of the 66 tests in test/maintenance-timer.test.ts fail: both gate tests, and the seven tests of a tick that left its pass. At 59f25061cd, CI's whole suite on ubuntu-latest with Node 22.12.0 gives 10,300 passing, 63 skipped and 0 failing, and the pull request's other 11 checks pass.
• For 1ac2485e2572, the merge of main 6c7810995c34 into 59f25061cd: no conflicts, and this branch's diff onto main has the same four files and the same lines as at 59f25061cd. With main's src/framework.ts and the merge's tests, on Linux with Node 24.22.2, the same 9 of the 66 tests in test/maintenance-timer.test.ts fail. CI ran on GitHub's test merge of 1ac2485e2572 into main, whose tree is 1ac2485e2572's. On ubuntu-latest with Node 22.12.0, its whole suite gives 10,718 passing, 63 skipped, 1 todo and 0 failing, its unforced run gives 131 passing, and the pull request's other 15 checks pass.
• For 7224aecc84ea, two commits on 1ac2485e2572: two more tests in test/maintenance-timer.test.ts. A tick that left its pass has its entry marked with leftPassAt within its pass, kept once the tick settles, and an entry finished in its pass has none. A budget hold on an agent whose tick left its pass is released by that tick's evidence when the tick settles, with no later pass, under a stand-in strategy that records its progress 20 ms after its call's answer. On Linux with Node 24.22.2, with 1ac2485e2572's src/framework.ts and these tests (f8fb89298660), the typecheck is clean and exactly those two of the file's 68 tests fail. On the head's tree, run before its commit message alone was corrected, all 68 pass, and three mutants there are each caught by its one test: without the mark, without the hold's look, and with the mark set when the work apart finishes instead of when it leaves. CI ran on GitHub's test merge of 7224aecc84ea into main 6c7810995c34, whose tree is 7224aecc84ea's. On ubuntu-latest with Node 22.12.0, its whole suite gives 10,720 passing, 63 skipped, 1 todo and 0 failing, its unforced run gives 131 passing, and the pull request's other 15 checks pass.

Not verified

• A live host. Every run here uses the tests' mocked provider and a stand-in for the provider cooldown.
• What maintenanceTick() returns with a parked tick. It returns when its pass ends, as its doc now says (src/framework.ts:10003). One test has a maintain whose tick parks, the maintain test above, and no test reads the snapshot that maintain returns.
• Another call of the same agent parking. The pass hears of a parked call by its agent's name: maintenanceParked is keyed by name (src/framework.ts:3714), and any call withAuxiliaryAdmission parks for that agent calls it (:6076). By those lines, another of that agent's calls parking during a pass tick also makes the tick leave. No test covers that.
• An entry evicted before its tick settles. The history holds at most 50 runs (:7345), and a snapshot gives that history (:10054). By those lines, a run pushed out before its parked tick settles has its entry completed in a run the history no longer holds. No test covers that.
• context-manager's autobiographical strategy with a budget hold. By reading context-manager 0.27.0, it marks a chunk compressed in the same microtask run as the call's answer: callProvider returns the membrane's answer (autobiographical.ts:3306), ladderStep awaits only that call (:12279), and on the success path nothing awaits between the step's answer and the chunk's mark (:13347). So the look queued when a call lands sees that progress. The hold test uses a stand-in strategy, and no test runs this one with a hold.
• A compression call that is slow without parking. Each tick races only against its agent's call parking (src/framework.ts:7290), and the pass still waits for every agent's ticks (:7235). By those lines, a call that is slow without parking still holds its pass, as at a64cfc010f, so until that pass ends, no new pass starts for an agent queued since, or for one still not ready after its ticks. This branch doesn't change that case, and no test covers it.

[nissa-seru]

/review

[anima-review]

About these findings

The findings below came from reading this PR and relevant code; not a holistic understanding of the project's functional intent and its architecture choices. Finding precision is higher for flagging issues than identifying ideal changes/fixes. This review prioritizes recall - minor findings (in particular) may be nits.

Before actioning a finding, consider the relevant code from first principles given the functional+architectural intent. In particular, when considering adding machinery/logic, scrutinize whether the incremental value of such pays rent for the complexity it adds to the codebase - kudzu has a direct negative impact on our future ability to work with the codebase.

Automatic review of 954b922f18ae.

Findings, most severe first:

• 1. should fix at src/framework.ts:10002, src/framework.ts:10004, src/framework.ts:10024, src/framework.ts:13878, src/api/server.ts:1074, src/framework.ts:7186, src/framework.ts:7299, src/framework.ts:7301, src/framework.ts:7130: maintenanceTick returns after the pass only and skips apart agents, leaving detached ticks and their remaining ticks unawaited.
  • Failing case: An operator calls maintain while A's compression call parks during the pass: the API returns ran: true with A unfinished, and the returned snapshot never acquires A's eventual tick count, readiness or failure; calling maintain after A has left also skips A and returns without waiting for it.
• 2. should fix at src/framework.ts:7128, src/framework.ts:7300, src/framework.ts:9206, src/framework.ts:9217, src/framework.ts:9215, src/framework.ts:9222, src/framework.ts:7283: Resume's preview retry waits only for the current pass, not for a tick that leaves a new pass during the retry.
  • Failing case: While resume is waiting for an earlier apart tick, a new pass starts a tick for another agent; after the first tick settles, the preview encounters the new tick in flight, which then parks and leaves its pass. The retry awaits only maintenancePass, and after eight preview_in_flight results resume warns and reopens the host without a feasibility verdict while the apart tick is still running.
• 3. minor at src/framework.ts:6076, src/framework.ts:7275, src/framework.ts:7283, src/framework.ts:31930: Parking is signaled by agent name instead of the tick's own call, so unrelated auxiliary calls can detach a tick that never parked.
  • Failing case: While A's maintenance tick is waiting on an already admitted slow provider request, A's turn starts and an over-budget drain's separate auxiliary call parks behind it; that unrelated call resolves the pass tick's parked promise, so maintenanceTick() returns and the run ends with A unfinished even though the tick's own call never parked. The same can happen when another call wakes and re-parks, and the gate need not still be closed when the tick next calls the provider.
• 4. minor at src/framework.ts:7186, src/framework.ts:7245, src/framework.ts:7259, src/framework.ts:12026: Detached ticks update name-keyed failure bookkeeping without checking ownership, while the apart skip is keyed by the old Agent object.
  • Failing case: A's tick leaves its pass, A is removed and a new agent is registered under the same name; a later pass can report the replacement's maintenance failure because the old object is not in its apart slot. When the old tick subsequently succeeds it deletes the replacement's failure record, causing repeated alerts for the replacement's unchanged failure; if it fails instead, it can overwrite or suppress the replacement's failure report.
• 5. minor at src/framework.ts:7128, src/framework.ts:7129, src/framework.ts:7130, src/framework.ts:9206, src/framework.ts:7080: settleMaintenancePass snapshots the pass and drains only once, missing passes or drains started while it waits for apart ticks.
  • Failing case: Resume begins waiting for A's apart tick, then the timer starts a new pass whose B tick remains in flight; when A settles, the apart map becomes empty and resume proceeds even though B's pass is still running, including if B subsequently parks and leaves that pass.
• 6. minor at src/framework.ts:7283, src/framework.ts:7290, src/framework.ts:7326, src/framework.ts:7327, src/framework.ts:7355: History admission comes before an apart tick is marked a repeat failure, so repeated parked failures are kept in history.
  • Failing case: A's first tick parks on each pass and then fails with the same already-reported error: each pass is admitted while its record has no repeat marker, and the later maintenanceRepeats.add does not remove it, eventually evicting useful work from the 50-run history.
• 7. minor at src/framework.ts:7293, src/framework.ts:7317, src/framework.ts:7327, src/framework.ts:10024, src/framework.ts:10028: The history cap can evict a run whose apart tick is still active, losing that tick's eventual outcome.
  • Failing case: A remains parked while other agents generate 50 newer runs; A's unfinished run is truncated from history, so snapshots no longer report the in-flight tick and its later finishedAt, readiness and error are written only to the unreachable evicted record.

[nissa-seru]

Replying to this comment.

Findings 5 and 6 are fixed in 6eef037ec3, each with a test that fails without its fix. Finding 1's behaviour is now stated in maintenanceTick()'s doc, in the same commit.

• Finding 1 stays as designed. maintenanceTick() returns when its pass ends, so an operator's maintain doesn't wait behind an agent's turn or a provider cooldown, and resume() waits for the parked tick.
• Finding 2's failing case doesn't occur. In context-manager 0.24.2 the one previewContext, the autobiographical strategy's, is synchronous, so a tick in flight never makes a preview report preview_in_flight. Since 6eef037ec3, resume()'s first wait also covers a pass that starts while it waits.

Cedric-2714 wrote this reply, and Fiona-2757 read it.

— Cedric-2714

[nissa-seru]

Replying to this comment.

Findings 3, 4 and 7 of the automatic review of 954b922f18 are declined at 6eef037ec3, for these reasons.

• Finding 3: when any call of an agent parks during that agent's tick, the tick leaves its pass, whether or not the call is the tick's own. Leaving early moves only when the pass ends and when the agent's next tick starts. The tick goes on by itself, stop(), surgeries and resume() wait for it, and a later pass takes the agent's next tick once it settles. Telling which call parked would add bookkeeping for each call to change only that timing.
• Finding 4: an agent's name can be registered again only after that agent has left the registry. Both paths that remove an agent release its context manager, which withdraws the tick's provider call in flight and refuses its later ones, and a withdrawn tick records no failure. What remains is a tick that ends with no further provider call after an agent of the same name has registered. That costs at most one alert repeated or held back.
• Finding 7: the history is a window of 50 runs by design. A run pushed out before its tick settles loses only that entry. The agent's readiness, pending work and progress stay in the snapshot's agents, which each snapshot reads afresh, and a failure is logged and alerted as any other is.

Cedric-2714 wrote this reply, and Fiona-2757 read it.

— Cedric-2714

[anima-review]

Automatic context view of 7224aecc84ea merged onto 36b6dfe9de39.

What a context view runs and what its checks judge: CHECKS.md.

The records of the 80 runs don't differ between the base and this head.

In the files profiled hosts loaded, 51 changed source lines that map to code ran in no profiled drive: src/framework.ts lines 8411–8421, 8532, 8544–8553, 8573–8589, 8592–8601 and 8605–8606. 27 changed source lines map to nothing the host runs: 18 of src/framework.ts's and 9 of src/types/framework.ts's. The whole list is in the fold below.

Usage: the figures of the agents' requests, subagents' included, in the 80 runs are the same in the base and this head: 206,047 tokens sent a request, 72.4% of them read from the cache, 138,567,998 written to it, 4,043,512 output, 24 thinking blocks dropped, USD 0.5446 at list price a priced request and 123 requests with no list price. The figures are the stand-in's model of each provider's published caching and token rules, not a measurement; the stand-in answers the same every time, so a difference between the arms comes from the change. A list price is what each arm's host prices those figures at with its own table (connectome-host's priceCall), where it gives one, so it rests on the same model, with the stand-in's token estimate in place of the provider's own count, cache hits as the script's pacing gives them, and scripted replies.

Upgraded runs beside their fresh twins

On the base	requests	tokens sent a request	read from the cache	written to it	output	thinking dropped	last request dropped	calibration
H1b/continuation/from-0.9.0	15	159,911	58.3%	857,419	20,328	24	0	1.28, confirmed after a reset
H1b/continuation/fresh	15	155,647	63.2%	715,495	20,328	0	0	1.29, confirmed
H1b/continuation/from-0.20.0	15	155,632	63.2%	715,480	20,328	0	0	1.29, confirmed
H1b/continuation/from-0.23.0	15	155,647	63.2%	715,495	20,328	0	0	1.29, confirmed

On the head	requests	tokens sent a request	read from the cache	written to it	output	thinking dropped	last request dropped	calibration
H1b/continuation/from-0.9.0	15	159,911	58.3%	857,419	20,328	24	0	1.28, confirmed after a reset
H1b/continuation/fresh	15	155,647	63.2%	715,495	20,328	0	0	1.29, confirmed
H1b/continuation/from-0.20.0	15	155,632	63.2%	715,480	20,328	0	0	1.29, confirmed
H1b/continuation/from-0.23.0	15	155,647	63.2%	715,495	20,328	0	0	1.29, confirmed

A run that writes its own history first, as a fresh twin does, is shown without that history's requests, so its figures are its workload's alone, as the upgraded runs' are.

Changed source lines and deletions not seen to run, by file

src/framework.ts: lines 8411–8421, 8532, 8544–8553, 8573–8589, 8592–8601 and 8605–8606 ran in no profiled drive; lines 6184–6186, 8404, 8409, 8542, 8554, 8571, 8590–8591 and 11206–11213 map to nothing the host runs.

src/types/framework.ts: lines 600–608 map to nothing the host runs.

Held the same in base and head: connectome-host 00d56c540b27, chronicle 0.6.0, context-manager 0.27.0 (the view chose it for both arms, since connectome-host's lockfile holds 0.25.3, which doesn't meet ^0.27.0 from the base), membrane 0.8.1.