[nissa-seru]

After quiesce() or resume() answers, the host and its durable host-mode record now agree, or the call fails, apart from calls that overlap, which Not covered names.

• quiesce() writes the record before it marks the host quiesced. When that write failed, quiesce() rejected with the host quiesced in memory while its record said it was serving. A restart then booted serving, and a second quiesce() resolved without writing the record.
• resume() keeps its order: it serves before it clears the record, so a failed clear leaves the record quiesced, the safe direction. A second resume() used to resolve without clearing the record, so the next restart booted quiesced. It now clears it, refused while a surgery holds the store, as resume() is on a quiesced host.
• Without a recovery file, the store is the record. A failed sync after its write was only logged, so quiesce() resolved before its record was durable. That now fails the call.

It applies #428's order for the framework's own state, the write first and memory after, to the host's quiesce.

What was wrong

We ran this on main with the host-mode write failing, for the recovery file and for a store-only config. Those runs aren't part of this PR.

• quiesce() rejected with the write's error, and getHostModeStatus() then said quiesced: true, with the reason given.
• A second quiesce() resolved and wrote nothing, since runQuiesce returns early for a host already quiesced.
• A restart booted serving.

By reading, and by this PR's tests on main's sources:

• A resume() whose clear failed left the host serving and the record quiesced, as its order chooses. A second resume() returned at runResume's check for a host already serving, so the record stayed quiesced.
• On a store-only config, persistHostMode logged a failed store.sync() and returned, so quiesce() and resume() resolved before their record was durable.

Changes

• runQuiesce writes the record first, with the time it records. It then sets quiesced, quiesceReason, quiescedAt and lastUnabandonable, and a write that throws leaves them as they were.
• hostModeRecordMayBeQuiesced says whether the record may say quiesced.
  • It's set at a quiesced boot, and by runQuiesce before its write, since a write that fails partway, such as a store write whose sync fails, may still reach the record.
  • It's cleared once resume() has cleared the record.
• runResume, on a host already serving, clears the record when it may say quiesced, such as after a resume() whose clear failed or a quiesce() whose write failed, and otherwise answers as before, writing nothing.
  • A surgery: that clear refuses first while a surgery holds the store, with the agent-busy error the clear on a quiesced host gives.
  • Another resume(): resumeInFlight is set while a resume() flushes its deferred writes and clears the record. A resume() arriving then leaves the record to it and answers as before.
• persistHostMode without a recovery path syncs the store and lets a failed sync throw, so the call rejects. The write is already in the store's log, unsynced, so it can still reach disk, which is why runQuiesce sets the flag before it writes. With a recovery path, the file is the record, and a failed sync of the store is logged, as before.
• Its doc comment says where the record is: the recovery file when there's a path for one, framework/state's hostMode otherwise. A boot with a path reads that hostMode only while no file exists.

What each part is for

• The order in runQuiesce: a failed write leaves the host serving, and a retry isn't taken for a quiesce already done.
• hostModeRecordMayBeQuiesced and runResume's clear: a retried resume() finishes the clear the first one couldn't, and so does a resume() after a quiesce whose write failed partway.
• The surgery refusal on that clear: a surgery can hold the store while the host serves, since it needs every agent idle, not the host quiesced. The clear writes the store, so it waits as the clear on a quiesced host does.
• resumeInFlight: without it, a resume() during another's flush took the serving-host path and cleared the record before that flush was done. On main it wrote nothing, and runResume's comment says the durable flag is cleared only after the flush.
• The store-only sync's throw: there the sync is what makes the record durable, so its failure is the write's.
• The recovery file's sync stays logged: there the record is the file, and failing the call would leave the file quiesced with the host serving.
• The tests:
  • The record write fails during quiesce(), for the recovery file and for a store-only config, whose restarts open the store again. The host is still serving, with no reason or time, and no record was written. A context write lands rather than being deferred, and a restart boots serving. The next quiesce writes the record, and a restart then boots quiesced, with its reason and time.
  • The record clear fails during resume(), for both. The call rejects with the host serving and the record quiesced. A retry whose clear fails too rejects with the record still quiesced, and the next retry clears it. A restart then boots serving.
  • A surgery holds the store while the host serves with a record that may say quiesced, for both. resume() is refused and writes nothing, and once the surgery is done it clears the record.
  • A resume() during another's flush, held for the test, for both. It answers serving and leaves the record quiesced, and the first clears it once its flush lands the deferred write.
  • The store-only sync fails. A quiesce() rejects, and the resume() after it clears the record the write may have left. A resume() whose sync fails rejects, and the next clears the record. With a recovery file, a failed sync is logged, and the quiesce holds across a restart.

Not taken: wrapping the write's error in a message of the framework's own. The error the write throws reaches the caller as before, and the host's status says whether it's quiesced.

What callers will notice

• A quiesce() whose record can't be written rejects as before, and the host now stays serving, so its context writes aren't deferred. Calling quiesce() again quiesces once the record can be written.
• A resume() retried after one whose clear failed clears the record, where it used to resolve with the record still quiesced. So does a resume() on a host still serving after a quiesce() whose write failed, and it rejects if that clear can't be written.
• Without a recovery file, a failed store sync after the record's write now fails quiesce() or resume(). After a quiesce() that failed this way, the record can still reach disk, so a restart can boot quiesced unless a resume() clears it first.
• A resume() on a serving host that clears the record is refused with agent-busy while a surgery holds the store, as resume() on a quiesced host is.

Evidence

On Linux with Node 24.22.0:

• The tests are the five new ones in test/host-quiesce.test.ts.
• Red-first: on main's sources, four of the five fail, and the file's other 34 pass.
  • The failed quiesce fails because the host reads as quiesced after the failed write.
  • The failed resume fails because a retried resume() writes nothing, so a retry whose clear fails resolves.
  • The surgery fails the same way: the retried resume() writes nothing, so it isn't refused.
  • The failed sync fails because a store-only quiesce() whose sync fails resolves.
  • A resume() during another's flush passes on main, which writes nothing there. It pins the in-flight guard against this change's own clear, as its removal below shows.
• Removals, at 1119711c, whose source and tests the head keeps: each of the 11 parts, taken out on its own and rebuilt, fails a test that pins it:
  • the record before the flag in runQuiesce;
  • setting hostModeRecordMayBeQuiesced before the write and at a quiesced boot;
  • runResume's clear on a serving host, its surgery refusal and its check for a resume() in flight;
  • resetting resumeInFlight once the flush and the clear are done;
  • clearing the flag after each of its two clears;
  • the store-only sync's throw;
  • the recovery file's logged sync, which an existing test, a resume whose chronicle sync fails, also pins.
• At 1119711c: host-quiesce passes 39 of 39, mcpl-coalescing 67 of 67, shutdown-errors 28 of 28, stop-with-host-operations 58 of 58, and maintenance-timer 47 of 47.
• The whole suite is this PR's CI: typecheck, build and tests on Node 20 and 24, on Ubuntu and macOS.

Not covered

• Operator calls that overlap. resume() clears the flag before it awaits its flush of deferred writes, and nothing serializes operator calls. So a quiesce() in that window writes its record, and resume()'s clear then overwrites it. A second resume() in that window answers before the first has cleared the record. By reading, the flush itself awaits nothing today, so the window yields only to microtasks: a call reaches it only from code in the same task, as Promise.all([framework.resume(), framework.quiesce()]) would, or from a microtask that runs in it.
• A recovery file's durability. It's renamed into place without an fsync, so after a power loss the record a call answered for may not be on disk.
• A recovery file's temporary file can stay behind when its write or its rename throws.

Written by Hilda-2681 (Claude Opus 5.5). Ezra-2423 (Claude Opus 5.5) reviewed its code at 1119711c.

[greptile-apps]

Required label not found on this PR.