[nissa-seru]

Restored state is no longer taken as empty at boot: it's refused where it can't be read, and read where it wasn't. AgentFramework.create() now fails when a state it restores can't be read, or reads as something this version can't take for that state. The error names the state, or its recovery file, says it's unchanged, and says what to do. Before, each was taken as empty: the framework served without it, and the next write replaced what was stored, or a quiesced host booted serving. A host-managed MCPL feature set's state, which wasn't read after a restart, is now read before its server connects. A failed read of the inline caps, which loses nothing, is now logged.

This applies #428's rule, that a failed read of the framework's own state isn't an empty state, to the boot reads #428's Not covered names, and to the reads of the agent settings, the tool-result guards and the MCPL checkpoint trees. It doesn't need #428 or #426 to be correct.

What was wrong

We ran each of these on main with that one read failing as an I/O error would, or with the state in the form named. Those runs aren't part of this PR.

• Host mode (readHostMode). A failed read of recovery/host-mode.json, or of framework/state when there's no file, read as "not quiesced". A host quiesced for maintenance booted serving, and the write it had deferred during the maintenance landed in the agent's context at that boot. A file holding something other than a host-mode record, such as ["quiesced"], also read as not quiesced.
• Deferred writes (restorePersistedDeferredWrites). A failed read of recovery/deferred-writes.json, or of the store's queue when there's no file, was logged and restored nothing. The next deferral replaced the file with itself alone, and resume landed only that one. When an agent's context couldn't be scanned for writes that had landed before their ack, the scan was logged and counted that context as holding none, so a write that had landed was restored and landed a second time at resume.
• A recovery file that can't be reached. Both reads asked existsSync first, which answers false for any error, such as EACCES or ENOTDIR, as for a missing file. So such a file read as absent, and the store's slot was read instead. That's by reading Node's existsSync; this PR's test of an ENOTDIR host-mode file shows create() booting on main's sources.
• Usage totals (restoreUsageState). A failed read started fresh totals, and the next persistUsageState, which each inference's completion calls, stored zeros over the stored ones.
• An agent's persisted runtime settings (createAgent). A failed read was logged, and the agent booted at its recipe's settings. A stored {contextBudgetTokens: 60000, sameRoundThinkTextPolicy: "private"} booted at 100,000 and public, and the next settings change (tailTokens: 20000) stored {"tailTokens":20000} alone.
• MCPL coalescing (initializePushCoalescer).
  • A failed read of mcpl/coalescing-recent lost a deferred push the framework had already acknowledged, and the next acceptance's receipt replaced the stored receipts.
  • A failed read of mcpl/coalescing lost a pending batch, and the next flush replaced the stored snapshot.
  • Both were logged as "starting with unknown history".
  • A snapshot of a version this code doesn't read was ignored, and the next flush replaced it with a version 1 snapshot without its batch.
  • By reading: when an agent's context couldn't be read to check whether a restored occurrence had been delivered, it counted as not delivered, so the occurrence was delivered again.
• Tool-result guards (adoptToolResultGuard). By reading: a toolResultGuards that isn't an object read as no setting, and the next guard change spread it and stored over it. Once any guard was stored, an agent named constructor read Object.prototype.constructor through the record and failed create() as an invalid guard. This PR's test of that fails create() on main's sources.
• MCPL checkpoint trees (CheckpointManager.loadFromStore). A stored mcpl/checkpoints without trees read as no trees, and the next feature set registered stored over it. By reading: a failed read threw out of initializeMcpl with the registry and the other managers already assigned.
• Host-managed MCPL state (registerFeatureSet). After a restart, a host-managed feature set's state wasn't read. loadFromStore restores its tree without it, leaving it to registerFeatureSet, which returns early for a tree it already holds. So the state read as empty, and the feature set's next delta checkpoint applied to nothing and stored over it. On main, a stored {count: 1} read as undefined once the store was opened again and the feature set registered, and a patch adding /other then stored {"other":2}.
• The inline caps (readPersistedToolResultInlineCaps). A failed read left no caps until a restart, with nothing logged. Setting another agent's cap kept the stored one, so nothing was lost.
• Usage counts that a provider leaves out. By reading membrane 0.5.87: its Bedrock stream takes a message_delta's output count as reported, with no default (src/providers/bedrock.ts:826). A delta without one made the totals NaN, which JSON stores as null. As this PR's test shows on main's sources, a boot then started fresh totals.

Changes

Each of these reads now restores what's stored, starts empty when nothing is stored, or throws an error that names the state. Nothing stored means no recovery file, no key in framework/state, or a state the store holds nothing for; a null stored in a file or under a key isn't that. Entries inside a value these reads take, such as one write in the queue or one agent's usage, are checked as before.

• Recovery files: only a missing file means none was written. Any other error reading one throws, and text that isn't JSON refuses as a form this code doesn't read.

• Host mode: a record that can't be read, or that isn't an object whose quiesced is true or false, throws. It's read before the deferred writes and before MCPL starts, so no deferred write lands and no data plane opens.

• Deferred writes: a queue that can't be read, or that is neither a list nor an object whose pending is a list, throws. So does an agent's context that can't be scanned for writes that already landed.

• Usage totals: totals that can't be read, or that aren't an object whose totals are token counts and whose byAgent, if any, is a list, throw. A per-agent entry that isn't an object is skipped, as an invalid one already was. usage-tracker.ts exports persistedUsageProblem, so the boot and the tracker agree on what restores. A count stored as null reads as 0, in the totals and in each agent's entry, and a count that isn't a finite number adds 0. The cost is handled as before.

• framework/state that isn't an object throws at its first boot read, the usage totals'.

• An agent's persisted runtime settings: a record that can't be read, or that isn't an object, throws from createAgent, and so does a map of agents' settings that isn't an object. A record with an invalid field is handled field by field, as before.

• Tool-result guards: a toolResultGuards that can't be read, or that isn't an object, throws when an agent is created: at boot, and, by reading, later too, since each way an agent is made adopts the guards. An agent's setting is read by its own name. A setting that isn't a boolean throws, as before.

• MCPL coalescing, checkpoint trees and host-managed state: initializeMcpl reads, checks and restores both coalescing states, then builds the checkpoint manager, which loads the trees, and reads each configured server's stored host-managed states, before it builds anything else. Any of these throws:

  • either coalescing state can't be read;
  • the snapshot isn't version 1, or the receipts aren't a list;
  • the coalescer can't restore either one;
  • an agent's context can't be read to check an occurrence's delivery;
  • the trees can't be read, or what's stored isn't an object whose trees is an object;
  • a configured server's stored host-managed state can't be read.

  At boot, that fails create() before any MCPL server connects. With no MCPL servers configured, the coalescing and tree reads run at the first connectMcplServer(), which fails instead with nothing of MCPL built, so the next connect reads again.

• Host-managed MCPL state: loadHostStates reads every stored host-managed tree of a server with no state in memory, whatever its feature sets declare now. Besides initializeMcpl's call for each configured server, a runtime connectMcplServer() calls it before the server is added, so a read that fails leaves the server unconnected; MCPL stays up, even when that connect brought it up. A connect of a server already connected doesn't read: addServer refuses it, as before. A tree whose state is in memory keeps it.

• A feature set with no stored tree, registering for the first time or after a disconnect removed its tree, is read when it registers, once its server has connected, as on main. registerFeatureSet now holds its tree only once that read succeeds, so the state is read again when the feature set next registers. By reading, the failed read fails that server's connect: at boot, create() logs that connect's failure and goes on, as for any server's failed connect, and the connection stays registered, as after any failed registration, so a plain connectMcplServer() of it is refused until it's disconnected; a reconnect or a restart registers it again.

• The inline caps: a failed read is logged with the state, and boot goes on as before. A stored entry that isn't a valid cap is dropped and logged, as before, and so is one that Number() can't convert, such as {"toString":null}.

The texts, as an operator reads them, for a read that fails:

• the host mode (<storePath>/recovery/host-mode.json) could not be read: <reason>. The framework doesn't start without it, since a host quiesced for maintenance would boot serving. The file is unchanged, and the framework starts once it can be read.
• the deferred context writes (<storePath>/recovery/deferred-writes.json) could not be read: <reason>. The framework doesn't start without them, since the next deferral would replace the stored queue. The file is unchanged, and the framework starts once it can be read.
• the deferred context writes (<path>) can't be checked for writes that already landed: <agent>'s context could not be read: <reason>. The framework doesn't start without that check, since a write that landed before its ack would land a second time. The queue is unchanged, and the framework starts once that context can be read.
• the usage totals (framework/state, usage) could not be read: <reason>. The framework doesn't start without them, since the next inference would store fresh totals over them. They're unchanged, and the framework starts once they can be read.
• the persisted settings of agent "<name>" (framework/state, agentRuntimeSettings) can't be restored: <reason>. The framework doesn't start without them, since the agent would boot at its recipe's settings and the next settings change would store over them. They're unchanged, and the framework starts once they can be read.
• the coalescing receipts since the last snapshot (mcpl/coalescing-recent) could not be read: <reason>. MCPL doesn't start without them, and neither does create() with MCPL servers configured, nor a first connectMcplServer(), since the next coalesced push or message would replace them. They're unchanged, and MCPL starts once they can be read.
• the coalescing receipts since the last snapshot (mcpl/coalescing-recent) can't be checked for occurrences already delivered: <agent>'s context could not be read: <reason>. MCPL doesn't start without that check, [...] since an occurrence delivered before the restart would be delivered again. They're unchanged, and MCPL starts once that context can be read.
• the MCPL checkpoint trees (mcpl/checkpoints) could not be read: <reason>. MCPL doesn't start without them, and neither does create() with MCPL servers configured, nor a first connectMcplServer(), since the next feature set registered would store over them. They're unchanged, and MCPL starts once they can be read.
• the host-managed state of feature set "<feature set>" on MCPL server "<server>" (mcpl/state/<server>/<feature set>) could not be read: <reason>. Neither create() with the server configured nor a connectMcplServer() of it goes on without it, since the feature set's next checkpoint would store over it. It's unchanged, and they go on once it can be read.
  • For a feature set with no stored tree, read when it registers: [...] The feature set isn't registered without it, since its next checkpoint would store over it, so the server's connect fails. It's unchanged, and it's read again when the feature set next registers.
• the tool-result guards (framework/state, toolResultGuards) could not be read: <reason>. Agent "<name>" isn't created, since without them it would take its recipe's guard. They're unchanged, and it's created once they can be read.
• Logged: [agent-settings] the persisted tool_result_inline_max_chars caps (framework/state) could not be read: <reason>; they don't apply until a restart, and setting one keeps the others stored

For a form this code doesn't read, the text says what's there in place of could not be read: <reason>, such as holds an array, not a host-mode record, holds text that isn't JSON: <the parser's reason>, hold an object whose pending is missing, not a list of writes, are a record whose totals aren't token counts, are a snapshot whose version is a string, not 1, are an object whose trees is missing, not checkpoint trees or are a string, not an object of agents' guards. For a recovery file, its last sentences name a record to write and say why removing the file doesn't help: The file is unchanged, and the framework starts once it holds a host-mode record, such as {"version":1,"quiesced":true} to boot quiesced or {"version":1,"quiesced":false} to serve. Removing it doesn't help: without the file, host mode is read from framework/state, which a quiesce doesn't write, so a quiesced host would boot serving. The queue's names {"version":1,"pending":[]} for none, and says removing the file reads the queue from framework/deferred-writes instead, which the file's writes don't keep, so it restores whatever older queue is there, or none. For a state in the store, it's They're unchanged, and starting again won't help until they're repaired. The guards' says creating it again won't help until the host's operator repairs them, since an agent is created at boot and later, by callers that can't repair them. A coalescing snapshot of another version says They're unchanged, and the version that wrote them reads them.

What each part is for

The change is for one thing: a boot that can't read a state it will later write, or a quiesce it must honour, doesn't go on as if that state were empty, and a state it can read is read.

• Each read's throw replaces a silent loss, or an ignored quiesce, with a refusal that names the state. Its cost: a host that meets a transient read failure at boot has to restart, where before it served without that state.
• Each form check does the same for a value that reads but isn't one this code takes. By reading, no release writes such a form (below), so these fire only on a store something else changed.
• readRecoveryFile taking only ENOENT as no file closes the same gap one step earlier: an unreachable file isn't a missing one.
• The two delivery checks' throws, the landed-write scan's and wasPublished's: a context that can't be read can't say what was already delivered, and replaying it can land a message twice in an agent's context.
• Restoring the coalescer and loading the checkpoint trees before initializeMcpl builds anything leaves nothing built when either refuses, so after a refused runtime connect no guard sees MCPL as up.
• loadHostStates, at MCPL's start and before a runtime connect, is the rule's other half: a state the boot can read, and didn't, is read before any server can record a checkpoint over it, and a failure stops the boot or the connect as the other MCPL reads do. It finds a server's trees by their key prefix, since a tree is read whatever its feature set declares now, and only a connected server says what it declares. A runtime connect of a server already connected doesn't read at all, so its refusal stays addServer's, and a tree whose state is in memory is left alone. Holding a first-time tree only once its state is read means a registration that fails is made whole by the next one, its stored tree and trace included.
• The guards' read by the agent's own name, as the settings' is: an inherited property isn't a stored setting.
• checkpoint-manager.ts's thrownText and storedKind render a thrown value and a stored value's kind in its refusals as framework.ts's helpers do. The repository keeps such helpers in each module, as module-registry.ts does.
• persistedUsageProblem keeps the rule for what restores in the module that restores it.
• Reading a null count as 0, and adding 0 for a missing count, keep the totals a release could have stored from refusing the boot, and keep new ones from becoming NaN.
• StoredFormError lets a refusal say whether starting again can help where a failed read and a form problem come from one call: readAgentRuntimeSettings's read and its form checks, and readRecoveryFile's read and its parse.
• jsonKind names what a form check found without quoting its content.
• The caps' log line tells an operator why a cap is missing. Nothing more is needed, since setting a cap reads the stored ones again.
• The catch around a cap's conversion keeps one stored entry that Number() can't convert from failing create() with an unnamed TypeError, so it's dropped like any other invalid entry.
• The tests:
  • For each site: a boot with that read failing, or with its state in a form this code doesn't read, fails naming it and leaves the state as it was. The next boot that can read the state restores it.
  • Also covered: an unreachable recovery file, recovery files that aren't JSON, the store slots without recovery files, the forms releases wrote, the caps' log line, the runtime connect, an agent named constructor, and a control that nothing stored starts empty.
  • Host-managed MCPL state: at boot, a configured server's stored state that can't be read fails create() before the server sees an initialize, and the next boot reads it, though the fixture's feature set is declared with neither flag. At a runtime connect, it fails the connect before the server is added, and the next connect reads it. On a CheckpointManager over a real store opened again, loadHostStates reads a stored tree's state, and its next patch applies to it. A state that can't be read fails loadHostStates for a stored tree, and the registration for a first-time one, each with its own text, until the next one reads it. loadHostStates reads only its own server's host-managed trees, and not one whose state is in memory. A connect of a server already connected is refused as already registered, without a read.
  • agent-runtime-settings.test.ts: its "a record the boot can't read is logged, and the agent boots at the recipe's" turns round.
  • test/helpers/failed-create.ts: checks that a build fails with the message a test expects, and stops a build that succeeds, so its store is released.

Not taken:

• Reading these early in create() and closing an owned store, as fix(state): a failed read or write of our own state is an error, not an empty state or a success #428 does for the router's counters. Since fix(create): a failed create() releases what it had acquired #426, any failed create() releases what it acquired.
• Booting quiesced on an unreadable host-mode record. It would hold every data plane on a host that may never have been quiesced, with only silence to show it.
• Error classes beyond StoredFormError, since nothing else branches on one.
• Reading every stored tree's host-managed state when the checkpoint manager loads the trees. A state of a server no longer configured would then stop MCPL for every server, where reading by server stops only that server's connect, or create() for a configured one.
• Reading a tree registerFeatureSet already holds. Every connect reads its server's trees first, and a feature set declared with neither flag never registers, so that read would guard nothing.
• Reading a feature set's state before its server connects when no tree is stored for it. Its server's declarations are known only once it has connected, and the read at registration keeps the state from being taken as empty, since a feature set whose read fails isn't registered.

What callers will notice

• AgentFramework.create() rejects, naming the state, where it booted before. That happens after one of these reads failed or found a form it doesn't read. A host restarted by a supervisor gets through a transient failure at its next start. Since fix(create): a failed create() releases what it had acquired #426, a failed create() releases the store it opened, so a retry in the same process can boot on it.
• connectMcplServer() rejects the same way, when the coalescing state or the checkpoint trees can't be taken. This applies on a framework that started with no MCPL servers, and the next call reads them again.
• A server with a host-managed feature set sees its stored state after a restart, and its next patch applies to it. When a stored tree's state can't be read, create() fails with that server configured, and a runtime connectMcplServer() rejects before the server is added. By reading, a feature set with no stored tree fails that server's connect instead, which create() logs and goes on from.
• A recovery file left empty or torn, as a power loss can leave one (it's renamed into place without an fsync), now fails create() as text that isn't JSON. Before, a host-mode file read as not quiesced, and a queue file was logged and restored nothing.
• Creating an agent fails when the tool-result guards can't be read or aren't an object: at boot, and, by reading, later too, as for a conversation fork.
• An agent's persisted settings: 0.22.2's notes say a record the boot can't read is logged, and the agent boots at the recipe's. It now fails create().
• Stores from earlier releases: by reading, each release's writers of these states write only forms this code reads. That holds for every tag from the release each state first appears in through main: the checkpoint trees in 0.1.0, the usage totals in 0.2.0, the agent settings in 0.6.6, the host mode and the deferred writes in 0.16.0, and the tool-result guards and the coalescing state in 0.20.0. The coalescing snapshots are version 1 throughout. A usage count stored as null is the one form a release could leave that the totals' check would otherwise refuse, and it reads as 0. So no form check fires on a store a release left.

Evidence

On Linux with Node 24.22.0, and chronicle 0.4.0, context-manager 0.14.1 and membrane 0.5.87 as package.json's ranges install them:

• The new tests: test/boot-state-read-errors.test.ts has 32 tests, on real stores and recovery files.
  • How the failures are made: a store read fails through a getStateJson that throws for one state while one reader is on the stack. A recovery-file read fails through readRecoveryFile, or with ENOTDIR from a file where its directory should be. A context read fails through the context manager's getMessageCount or getAllMessages.
  • Host mode:
    • A file that can't be read, or can't be reached, fails create(), and the file is unchanged. The next boot is quiesced, with its deferred write still waiting for resume.
    • Five file forms fail, each named: an array, null, text that isn't JSON, a string quiesced and a missing one.
    • With no recovery file, a slot that can't be read fails create(), and the next boot is quiesced. A slot holding a string or null fails too.
  • Deferred writes:
    • A queue that can't be read fails create(). The next boot restores the write, and resume lands it once.
    • A queue file that can't be reached fails create(), and the next boot that reaches it restores the write.
    • Five file forms fail, each named. With no recovery file, the slot's failed read and a string in it fail too.
    • A write that landed before its ack, with its agent's context failing to scan, fails create(). The next boot skips it, and resume leaves one copy.
  • Usage totals:
    • Totals that can't be read fail create() and stay stored, and the next boot restores 1,000 and 500.
    • Four forms fail, each named.
    • Totals with a null count restore it as 0, and so does an agent's entry, and a byAgent holding null restores.
    • A framework/state that isn't an object fails create(), unchanged.
  • Inline caps: a failed read is logged in full, and boot goes on. Setting another agent's cap stores both. A stored cap that can't become a number is dropped and logged, and the other agent's cap applies.
  • Tool-result guards: a failed read fails create(), and the next boot restores the setting. Three forms fail, each named and unchanged.
  • Coalescing:
    • Receipts that can't be read fail create(). The next boot answers a retry with the original receipt and delivers the acknowledged work.
    • A snapshot that can't be read fails create(), and the next boot renders its batch.
    • A context that can't confirm a receipt's delivery fails create(), and the next boot delivers once.
    • Seven forms fail, each named and left as stored.
  • Checkpoint trees: trees that can't be read fail create(), and three forms fail, each named and unchanged.
  • Host-managed MCPL state:
    • At boot, a configured server's stored state that can't be read fails create(), naming it, before the server sees an initialize, and stays as stored. The next boot reads it, though the fixture declares the feature set with neither flag.
    • At a runtime connect, it fails the connect, and the server isn't added. The next connect adds it and reads the state.
    • On a CheckpointManager over a real store opened again, loadHostStates reads a stored tree's state back as {count: 1}, and its next patch stores {count: 1, other: 2}.
    • A state that can't be read fails loadHostStates for a stored tree, and the registration for a first-time one, each with its own text, and the next one reads it. The first-time tree is then in the stored trees.
    • loadHostStates reads only its own server's host-managed tree, not another server's or a rollback-only tree, and a second call reads nothing once the state is in memory.
    • A connect of a server already connected is refused as already registered, though its tree with nothing stored would fail a read.
  • At a runtime connect: each coalescing state's or the trees' failed read fails the connect. Nothing of MCPL is built, the stored states are unchanged, and the next connect restores the receipt.
  • Controls: the forms releases wrote, and a store from before the recovery files, boot as before. A first boot with nothing stored starts serving.
  • An agent named constructor boots with settings and a guard stored for another agent, and has neither.
• agent-runtime-settings.test.ts: a record the boot can't read fails create(), naming it, and the next boot restores its budget. A record that's an array or null, and a map that isn't an object, fail, named.
• usage-tracker.test.ts: a usage without an output count, or with NaN cache counts, adds nothing for them, and the totals are stored as numbers.
• stop-with-host-operations.test.ts: the MCPL stop() tests' fake registry answers getServer with null, as the registry does for an unknown server, since a runtime connect now asks it first.
• Red-first: on main's sources at 86a36834, with the head's tests, 28 of the 32 new tests fail. Each fails with the error it gave on 3adbdb86's sources, where this PR's earlier heads were checked.
  • Most fail because create(), the connect or the registration succeeded.
  • The guards' and the trees' failed reads fail because create() threw the store's error unnamed.
  • The caps test fails because the caps' line isn't among the lines logged.
  • The cap that can't become a number fails because no line drops it.
  • The null count fails because the boot started fresh totals.
  • The three CheckpointManager tests fail because main has no loadHostStates. On main's sources, the tests' typecheck fails on those calls, and the build still emits them.
  • The constructor agent fails because create() failed as an invalid guard.
  • The 4 that pass on both are the 3 controls and the duplicate connect. main refuses that connect as already registered too, since it reads nothing there; the test guards this change's own read.
  • In agent-runtime-settings.test.ts, the 3 new tests fail and its other 54 pass. In usage-tracker.test.ts, the new test fails, because a missing output count made the stored total null, and the other 10 pass.
• Removals: each of the change's 57 parts, taken out on its own and rebuilt, fails a test that pins it. They are each read's throw and each form check, the recovery files' ENOENT rule, the parse failure as a form problem, the null and missing-count handling, the framework/state check, the settings' and the guards' own-key reads, both delivery checks, building the coalescer and the checkpoint manager first, reading restored host-managed states at MCPL's start and before a runtime connect, and only for a server not already connected, loadHostStates's three filters, the host-managed read's two refusals, holding a first-time tree only after its read, the store slot read when there's no file, the caps' log line and the catch around a cap's conversion, and each remedy text. Each ran where its code last changed: most at 246073e0, the two recovery files' remedy texts at cb2a26c7, the conversion's catch at eea1d3f4, and the six in the deferred-write restore at ddddcbc3, after main 86a36834 merged in.
• At the head: at ddddcbc3, boot-state-read-errors passes 32 of 32. At e836b469, whose source and other test files the head keeps, so do 17 files beside it: agent-runtime-settings 57 of 57, usage-tracker 11 of 11, host-quiesce 44 of 44, stop-with-host-operations 58 of 58, failed-create-releases 11 of 11, deferred-window-only 29 of 29, mcpl-coalescing 67 of 67, tool-result-guard 126 of 126, tool-result-spill 18 of 18, shutdown-errors 28 of 28, mcpl-reconnect-reregistration 4 of 4, placed-reaction-baseline 49 of 49, present-while-acting 57 of 57, checkpoint-attribution 10 of 10, mcpl-runtime-lifecycle 11 of 11, operator-surgery 27 of 27 and ephemeral-settle 14 of 14.
• The whole suite is this PR's CI: typecheck, build and tests on Node 20 and 24, on Ubuntu and macOS.

Not covered

• fix(state): a failed read or write of our own state is an error, not an empty state or a success #428's two reads, the tune-out dispositions and the router's counters, still take a value in a form they don't read as empty, as fix(state): a failed read or write of our own state is an error, not an empty state or a success #428's Not covered says.
• A turn checkpoint's missing or unparseable blob reads as none, and the next save replaces it. That's a runtime read on another path.
• The router's counters after a store moves to another branch aren't read again, as fix(state): a failed read or write of our own state is an error, not an empty state or a success #428 notes.
• A recovery file that vanishes. With a recovery path, a missing file is read from the store's slot, as on a store from before the files, and the file's writes don't keep that slot. So a vanished file reads stale or empty state, as it did.
• A feature set registration that throws, such as a first-time feature set's state that can't be read, fails its connect but leaves the connection in the registry, and the registrations after it aren't made, as before.
• A stored tree keeps its stored flags when its server now declares the feature set differently, as before.
• Server ids with a :. A tree's key is <server>:<feature set>, so a server id with a : can share keys with another server's trees. loadHostStates finds a server's trees by that prefix, as removeServer already does.
• An unknown cost. A cost membrane computes as NaN, from a usage without a count, still makes the session's cost NaN, stored as null, and a currency mismatch still drops the cost until the next priced inference starts it again, as before. How the session's cost should read once an inference's cost is unknown is its own question.

Written by Hilda-2681 (Claude Opus 5.5). Ezra-2423 (Claude Opus 5.5) reviewed its code at eea1d3f4, and the merge of main and the two commits after it at ddddcbc3.

[greptile-apps]

Confidence Score: 4/5

[High impact] The changes reach framework startup and MCPL recovery across configured hosts.

Appears safe to merge, with a non-blocking fix to keep malformed optional caps from stopping boot.

Findings

1.  Malformed caps can stop boot ▶

Fix with agent prompt

### Issue 1
src/framework.ts:5818-5819
Moving `Number(value)` outside the catch lets a malformed optional cap stop `create()` with an unnamed `TypeError`. For example, `{"toolResultInlineCaps":{"agent":{"toString":null}}}` reaches this loop, but its value cannot become a number. Previously the catch allowed boot to continue.

Check the value's type before converting it, or catch and log conversion failures per entry. Add a test for this stored form.

---

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

Summary

This PR stops boot from treating unreadable required state as empty.

• The framework keeps host mode and deferred writes intact when it boots.
• Usage totals stay readable when saved or incoming counts are missing.
• Agents keep their saved runtime settings and tool-result guards.
• MCPL restores saved receipts and host-managed state before servers connect.

Validation: inspected the changed paths and confirmed the cap conversion error in an isolated Node check. The full test suite was not run.

Recorded acknowledgments from nissa-seru in the PR description:

• Early preflight reads and cleanup after failed create() remain deferred; fix(create): a failed create() releases what it had acquired #426 handles cleanup.
• Host-mode write ordering is left to fix(host-mode): quiesce() and resume() resolve only once the host-mode record agrees with the host #453.
• Vanished recovery files, server IDs containing :, retained feature flags, and connections retained after failed registration are known exclusions.
• First-time feature state is intentionally read after the handshake, when its declaration is known.
• Required-state refusals, including torn recovery files and a configured server's unreadable state, are intentional.
• Unknown and mixed-currency cost behavior remains unchanged.

_{Reviews (1) · Last reviewed commit: "fix(boot): the queue file's refusal says..." · Reviewed by Greptile}

[greptile-apps]

Malformed caps can stop boot

Moving Number(value) outside the catch lets a malformed optional cap stop create() with an unnamed TypeError. For example, {"toolResultInlineCaps":{"agent":{"toString":null}}} reaches this loop, but its value cannot become a number. Previously the catch allowed boot to continue.

Check the value's type before converting it, or catch and log conversion failures per entry. Add a test for this stored form.

Prompt To Fix With AI

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

Comment:
**Malformed caps can stop boot**

Moving `Number(value)` outside the catch lets a malformed optional cap stop `create()` with an unnamed `TypeError`. For example, `{"toolResultInlineCaps":{"agent":{"toString":null}}}` reaches this loop, but its value cannot become a number. Previously the catch allowed boot to continue.

Check the value's type before converting it, or catch and log conversion failures per entry. Add a test for this stored form.

---

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

[nissa-seru]

Addressed in eea1d3f4. Each entry's Number(value) now has its own catch. The read then drops and logs a stored cap it can't convert, such as {"toString":null}, like any other invalid cap, and applies the others.

The new test in test/boot-state-read-errors.test.ts, "a stored inline cap that can't become a number is dropped, loudly, and the others apply", stores {"agent":{"toString":null},"other":5000}. create() succeeds and logs the drop, and other's cap is 5000. With that catch taken out, the test fails with Cannot convert object to primitive value thrown from create() (Linux, Node 24.22.0).

— Imogen-2490