fix(ocap-kernel): record a vat's death in one synchronous step

[sirtimid]

A vat's death is four store writes: reject the promises it was deciding, unpin its root, drop its config and vat store, set the terminated mark. They were spread across VatManager.stopVat and VatHandle.terminate, with awaits between them, so a crank could land in the middle and see a half-dead vat.

A new private #retireVat does all four in one synchronous step, before the worker is touched. The worker is torn down even if a write fails, and the caller hears about the store failure rather than a channel that would not close.

Having the death in one place leads to these changes:

• stopVat no longer needs a live handle to terminate. A failed relaunch leaves a vat persisted but not running. terminateVat threw VatNotFoundError for one, so it could not be retired at all, and terminateSubcluster stopped part-way on reaching one. A vat that is neither running nor persisted still throws.
• A worker whose launch fails is stopped. platformServices.launch spawns the worker before the handshake, and a failed handshake leaves no handle to stop it through. runVat now stops it, so initializeAllVats and restartVat no longer strand workers (only launchVat cleaned up before). A launch that failed before a worker existed no longer asks the runtime to stop one, which logged a misleading second error.
• VatHandle.terminate only does the handle's own work: reject pending commands, then close the channel.
• removeVatFromSubcluster tolerates a vat in no subcluster, so deleteVat can be retried.

A channel that fails on its own

The drain's catch in VatHandle used to call terminate(true, …) and get the store teardown for free. With that moved out, the handle takes a required onStreamFailure. It rejects its own pending commands, and VatManager.#retireLostVat retires the vat the same way a requested termination would. Two details matter:

• It waits for the current crank. Run inside a delivery savepoint, an aborting crank would roll the retirement back while the handle stays dropped from #vats.
• It matches the report to the handle that made it, not the vat id. A restart puts a new handle under the same id, and a vat the kernel is stopping also breaks its own drain. Before this PR that second teardown ran in full, rejecting the decider promises and calling deleteVat twice.

There is nobody to retry this path, so a store failure ends in a log line saying to terminateVat by hand.

"Channel fails" is narrower than it sounds. Nothing listens for a worker that dies outright (NodeWorkerReader registers only 'message', and PlatformServices.launch drops 'error'/'exit' once the worker is online), so the kernel only sees a worker that is still sending bad frames. Wiring up 'exit'/'error' is left for later.

Write order

The mark goes after the rejections and before deleteVat:

• After the rejections, because the mark schedules nextTerminatedVatCleanup, which deletes the decider promises' c-list entries assuming they were already rejected. stopVat records a vat's death before killing its worker, so a failed record strands a live worker #1067 asked for the mark in a finally; all three review agents showed that marking after failed rejections hangs those promises' subscribers for good.
• Before deleteVat, because deleteVat drops the vatConfig row that a retry uses to find the vat. With the mark last, a failure on that write left a vat that could never be marked.

As a result, every failure leaves either the mark set or the row that allows a retry. The idempotence guard covers only the writes that must happen once, and deleteVat reruns. deleteVat itself now drops vatConfig last, so a failure on the vat store or subcluster write leaves the row a retry needs. If deleteVat itself throws, the vat is marked and its vatConfig row survives. cleanupTerminatedVat now discards that row, so the sweep cannot bring the vat back to life.

Synchronous is not atomic. terminateVat runs between cranks with no open transaction, so the four writes are four commits. This PR removes the interleaving and the dead ends, not the partial-failure window. Closing that window is the Tier 3 question of routing control-plane termination through the run loop.

Superseding #1030

Supersedes #1030 by @grypez, which fixed the same "persisted but not running" defect with a dedicated #retirePersistedVat branch. This PR routes it through the one path instead. Carried over: his defect narrative, his removeVatFromSubcluster change and test, and his persisted-but-not-running test cases.

Changes

• VatManager.#retireVat records a vat's death in one synchronous step
• stopVat tolerates a missing handle when terminating, and reports the store failure over the channel failure
• VatHandle.terminate keeps only the handle's own work; a new required onStreamFailure reports a failed channel
• VatManager.#retireLostVat retires such a vat between cranks, ignoring reports from a handle it no longer keeps
• runVat stops the worker a failed handshake leaves behind; launchVat drops its own teardown and its now-redundant trailing mark
• cleanupTerminatedVat discards the vat's vatConfig row
• deleteVat drops the vatConfig row last
• Kernel's in-crank termination lambda drops its now-redundant trailing mark
• removeVatFromSubcluster tolerates a vat in no subcluster

Testing

VatManager.test.ts:

• All four writes land in stopVat's synchronous prefix. They are read out of the mocks before the returned promise is awaited, so the test checks that no yield point comes between them, not just their order.
• A failure before the mark leaves the vat unmarked. A failure on deleteVat leaves it marked, and a retry finishes the job without repeating the one-time writes.
• The store failure wins over a channel failure.
• A failed handshake stops the worker; a launch that never had a worker does not try to.
• A reported channel failure retires the vat with the channel's error and waits for the open crank first. It is ignored after the kernel has stopped the vat or a restart has replaced its handle, and a failed retirement logs rather than rejects.
• @grypez's five persisted-but-not-running cases.

VatHandle.test.ts checks that pending commands are rejected before the channel closes, using a stream whose end never settles. It also checks that a failed channel is reported with its commands already rejected, and that a restart leaves them alone.

store/index.test.ts checks that a deleteVat failing on the vat store keeps the vatConfig row, and that a second call finishes.

kernel-test's vat-lifecycle.test.ts adds two cases against a real kernel and SQLite store:

• No vatConfig record survives termination and cleanup.
• A vat whose worker emits a frame the reader rejects is fully retired, using the real NodejsPlatformServices trigger.

Each fix was mutation-checked on its own, and each mutation failed only its own cases.

Full @metamask/ocap-kernel suite green. @ocap/kernel-test's vat-lifecycle, subclusters, persistence, garbage-collection, resume and orphaned-ephemeral-exo were green against a fresh dist before the rebase.

Closes #1063
Closes #1067

🤖 Generated with Claude Code

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c9cc6fb. Configure here.}

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	73.34% ⬆️ +0.07%	9973 / 13598
🔵	Statements	73.13% ⬆️ +0.06%	10102 / 13813
🔵	Functions	73.75% ⬆️ +0.03%	2332 / 3162
🔵	Branches	67.72% ⬆️ +0.11%	4115 / 6076

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/ocap-kernel/src/Kernel.ts	89.84% ⬇️ -0.08%	79.54% 🟰 ±0%	85.41% 🟰 ±0%	89.84% ⬇️ -0.08%	322-324, 395, 419, 494-504, 592, 660, 736-739, 752, 762-763, 816, 839
packages/ocap-kernel/src/store/index.ts	98.87% 🟰 ±0%	95.23% 🟰 ±0%	100% 🟰 ±0%	98.86% 🟰 ±0%	416
packages/ocap-kernel/src/store/methods/subclusters.ts	98.82% ⬆️ +0.02%	90.62% ⬆️ +0.62%	96.15% 🟰 ±0%	98.78% ⬆️ +0.02%	263
packages/ocap-kernel/src/store/methods/vat.ts	98.51% ⬆️ +0.01%	90% 🟰 ±0%	100% 🟰 ±0%	98.5% ⬆️ +0.01%	308-309
packages/ocap-kernel/src/vats/VatHandle.ts	90% ⬇️ -0.14%	86.66% 🟰 ±0%	100% 🟰 ±0%	90% ⬇️ -0.14%	176-179, 375-380, 389-395
packages/ocap-kernel/src/vats/VatManager.ts	98.33% ⬇️ -1.67%	97.61% ⬇️ -2.39%	96.42% ⬇️ -3.58%	98.33% ⬇️ -1.67%	208-211, 238

Generated in workflow #5054 for commit 4dd8e8a by the Vitest Coverage Report Action

[rekmarks-consensys-1]

This looks good except for two essay-length docstrings, resulting from—I suspect—a common Claudish failure mode where it dumps its train of thought into documentation instead of trying to protect the reader's attention.

[rekmarks-consensys-1]

LGTM!