A local-first multi-agent app development platform, built on PenguinHarness
fix(server): hot-update recovery re-boots the version that was running (#421)
Myriad-Dreamin5f8028cdebe7
diff --git a/changelog/unreleased/2026-08-23-hot-update-recovery-reboots-the-running-version.md b/changelog/unreleased/2026-08-23-hot-update-recovery-reboots-the-running-version.mdnew file mode 100644index 00000000..98d09230--- /dev/null+++ b/changelog/unreleased/2026-08-23-hot-update-recovery-reboots-the-running-version.md@@ -0,0 +1,34 @@+# Boot-failure recovery re-boots the version that was actually running++- **Date:** 2026-08-23+- **Type:** fix+- **Scope:** `server`+- **PR:** [#421](https://github.com/Prism-Shadow/penguin-harness/pull/421)++[中文版](2026-08-23-hot-update-recovery-reboots-the-running-version.zh.md)++When a pushed platform failed to boot, the host+[re-booted the previous version](2026-08-20-hot-update-failure-modes.md) from the parked+document — but chose *which* bundle to re-boot by comparing the running bundle's `id`+against the packaged default's, and falling back to `harness.json` when they differed.+Neither signal identified the running version. A push delivers the packaged export itself,+so every bundle `scripts/deploy.mjs` built carried the packaged id and the comparison never+fired; and the manifest names the last version written to disk, which is a different+version whenever a push landed live but could not be persisted.++On a machine that had been deployed to, a failed push therefore dropped the live process+back to the platform the installation shipped with: the endpoints that deployment had added+stopped answering, the only error reported was the push's own, and the next restart brought+them back — so the running code and the committed code disagreed with nothing to say so.++Recovery re-boots the bundle that was running, held as the loaded object rather than+re-derived, so it is the same version by construction in both cases.++## Details++- The host records the platform bundle behind every successful boot — the packaged+ default, a version restored from `harness.json`, and a pushed version alike — and+ boot-failure recovery re-boots that object against the parked document the kernel hands+ back.+- Recovery no longer reads `harness.json` or re-imports from the store, so it also works+ for a version whose push reported `persisted: false`.diff --git a/changelog/unreleased/2026-08-23-hot-update-recovery-reboots-the-running-version.zh.md b/changelog/unreleased/2026-08-23-hot-update-recovery-reboots-the-running-version.zh.mdnew file mode 100644index 00000000..9084fc43--- /dev/null+++ b/changelog/unreleased/2026-08-23-hot-update-recovery-reboots-the-running-version.zh.md@@ -0,0 +1,29 @@+# 启动失败的恢复现在重启真正在运行的那个版本++- **Date:** 2026-08-23+- **Type:** fix+- **Scope:** `server`+- **PR:** [#421](https://github.com/Prism-Shadow/penguin-harness/pull/421)++[English](2026-08-23-hot-update-recovery-reboots-the-running-version.md)++推送的 platform 启动失败时,host 会从 park 文档+[重启上一个版本](2026-08-20-hot-update-failure-modes.zh.md)——但它判断该重启*哪一个* bundle 的+依据,是拿正在运行的 bundle 的 `id` 与打包默认版比较,不同时才回退去读 `harness.json`。这两个信号+都标识不了正在运行的版本。推送送过去的就是打包导出的那个 bundle,于是 `scripts/deploy.mjs` 构建出+的每一个 bundle 都带着打包版的 id,这个比较从未成立过;而 manifest 记的是最后写进磁盘的版本,只要+某次推送生效了却没能持久化,它就是另一个版本。++于是在一台部署过的机器上,一次失败的推送会把活着的进程退回到这台安装自带的 platform:那次部署新增+的端点不再应答,报出来的错误只有推送自己那一个,而下一次重启又会把它们带回来——运行中的代码和已提交+的代码不一致,却没有任何东西把这件事说出来。++现在恢复重启的是当时正在运行的那个 bundle,以已加载的对象持有、而不是重新推导出来,因此两种情况下+它按构造就是同一个版本。++## 细节++- host 会记录每一次成功启动背后的 platform bundle——打包默认版、从 `harness.json` 恢复的版本、推送+ 的版本,一视同仁——启动失败的恢复就拿这个对象、配上内核交回的 park 文档重新启动。+- 恢复不再读 `harness.json`,也不再从 store 重新 import,所以对一个推送时报告 `persisted: false`+ 的版本同样有效。diff --git a/packages/server/src/hmr/host.ts b/packages/server/src/hmr/host.tsindex d0fd4056..dc4674f6 100644--- a/packages/server/src/hmr/host.ts+++ b/packages/server/src/hmr/host.ts@@ -159,7 +159,16 @@ export class HmrHost {readonly resources = new HotResources();private instance: Instance<PlatformApi> | null = null;- private implId = packagedPlatform.id;+ /**+ * The bundle behind the RUNNING instance, held as the loaded object rather than a+ * pointer to re-read: it is what boot-failure recovery re-boots (see recoverPrevious).+ * A bundle's `id` cannot stand in for this — the packaged export IS what a push+ * delivers (hmr/entry.ts re-exports `packagedPlatform` as `hotPlatform`), so every+ * pushed bundle carries the packaged id and comparing ids cannot tell a pushed version+ * from the compiled-in default. Nor can the manifest: a push whose disk commit failed+ * (`persisted: false`) is running a version harness.json does not name.+ */+ private current: PlatformBundle = packagedPlatform;/** Current version's materialized native assets dir (see assetsDir()). */private assets: string | null = null;private readonly hmrDir: string;@@ -185,8 +194,9 @@ export class HmrHost {process.stderr.write(`[hmr] ${msg}\n`);}+ /** The running version's id — derived from the running bundle, never tracked alongside it. */currentImplId(): string {- return this.implId;+ return this.current.id;}/**@@ -225,6 +235,7 @@ export class HmrHost {initialDoc(bundle.iface, bundle.context),this.resources,)) as Instance<PlatformApi>;+ this.current = bundle;}return this.instance;} catch (err) {@@ -297,7 +308,7 @@ export class HmrHost {this.resources,)) as Instance<PlatformApi>;this.instance = instance;- this.implId = bundle.id;+ this.current = bundle;this.webMem = webMem;} catch (err) {this.warn(@@ -385,7 +396,7 @@ export class HmrHost {// web or cli it's paired with. `result.doc` (the swap's parked+migrated state)// is never written to disk — see the module doc: code persists, state does not.this.instance = result.instance as Instance<PlatformApi>;- this.implId = bundle.id;+ this.current = bundle;this.webMem = webMem;const digest = filesDigest(target.web);@@ -410,28 +421,25 @@ export class HmrHost {/*** Boot-failure recovery: re-boot the version that was running before the failed- * upgrade, from its own parked document. The committed manifest still names that- * version (a failed push persists nothing), so the bundle comes from there — or it is- * the packaged default when nothing was ever pushed. Best-effort by design: a double- * fault only warns and leaves the disposed instance in place, because /api/hmr is+ * upgrade, from its own parked document. The bundle is `this.current` — the object+ * that was running, still loaded — rather than anything re-read from disk: the+ * manifest names the last DURABLE version, which is a different version whenever the+ * running one could not be persisted, and a bundle's `id` cannot distinguish pushed+ * from packaged at all (see the field's doc). Best-effort by design: a double fault+ * only warns and leaves the disposed instance in place, because /api/hmr is* runtime-owned and therefore still reachable for a follow-up push, and a process* restart restores the committed version regardless.*/private async recoverPrevious(doc: Json): Promise<void> {try {- let bundle: PlatformBundle = packagedPlatform;- if (this.implId !== packagedPlatform.id) {- const manifest = JSON.parse(await fsp.readFile(this.manifestPath, "utf8")) as Manifest;- if (manifest.platform === undefined) throw new Error("harness.json has no `platform`");- bundle = await this.importBundleFile(path.join(this.hmrDir, manifest.platform.bundle));- }+ const bundle = this.current;this.instance = (await boot(bundle.impl,bundle.iface,doc,this.resources,)) as Instance<PlatformApi>;- // implId unchanged: the previous version is the running version again.+ // `current` unchanged: the previous version is the running version again.} catch (err) {this.warn(`boot-failure recovery failed too — the process serves a half-stopped App until ` +diff --git a/packages/server/test/hmr-host.test.ts b/packages/server/test/hmr-host.test.tsindex 3ca0b1af..ad192d8d 100644--- a/packages/server/test/hmr-host.test.ts+++ b/packages/server/test/hmr-host.test.ts@@ -414,6 +414,13 @@ const impl = {export const hotPlatform = { id: "boom", iface, impl, context: {} };`;+/**+ * The same failing bundle under the id every REAL push carries: hmr/entry.ts re-exports+ * `packagedPlatform` as `hotPlatform`, so a bundle built by scripts/deploy.mjs is+ * indistinguishable from the compiled-in default by id alone.+ */+const BOOM_PLATFORM_PACKAGED_ID = BOOM_PLATFORM.replace('id: "boom"', 'id: "packaged"');+describe("upgrade boot failure: the previous version is re-booted, not left half-dead", () => {let t: TestApp | undefined;@@ -457,3 +464,58 @@ describe("upgrade boot failure: the previous version is re-booted, not left halfexpect((await served.json()) as object).toMatchObject({ servedBy: "recovered-push" });});});++describe("upgrade boot failure: recovery re-boots the PUSHED version, not the packaged default", () => {+ let t: TestApp | undefined;++ afterEach(async () => {+ if (t) await t.cleanup();+ t = undefined;+ });++ it("a failed push over an already-pushed version keeps that version's routes serving", async () => {+ t = await createTestApp();+ const cookie = (await loginAdmin(t.app)).cookie;++ // A real deploy: the pushed bundle carries the packaged id, because that is the+ // export hmr/entry.ts ships.+ const first = await pushPlatform(t.app, cookie, platformServing(["/api/demo/v1"], "packaged"));+ expect(first.status).toBe(200);+ expect((await t.app.request("/api/demo/v1", { headers: { cookie } })).status).toBe(200);++ const bad = await pushPlatform(t.app, cookie, BOOM_PLATFORM_PACKAGED_ID);+ expect(bad.status).toBe(400);++ // The version that was running before the failed push is running again — recovery+ // must not fall back to the runtime's compiled-in platform, which does not serve+ // this route at all.+ expect((await t.app.request("/api/demo/v1", { headers: { cookie } })).status).toBe(200);+ });++ it("recovers the RUNNING version even when its own push could not be persisted", async () => {+ t = await createTestApp();+ const cookie = (await loginAdmin(t.app)).cookie;++ // v1 lands durably; harness.json names it.+ expect(+ (await pushPlatform(t.app, cookie, platformServing(["/api/demo/v1"], "v1"))).status,+ ).toBe(200);++ // v2 boots but cannot be written: `store/web` as a plain FILE makes persistVersion's+ // `mkdir store/web` throw EEXIST after the platform bundle is already stored, so the+ // commit never happens and the manifest still names v1 while v2 serves. v1's own+ // bundle file is deliberately left readable — the point is which version recovery+ // CHOOSES, not whether it can load one at all.+ const webStore = path.join(t.root, "hmr", "store", "web");+ await fs.rm(webStore, { recursive: true, force: true });+ await fs.writeFile(webStore, "not a directory");+ const second = await pushPlatform(t.app, cookie, platformServing(["/api/demo/v2"], "v2"));+ expect(second.status).toBe(200);+ expect(((await second.json()) as { persisted: boolean }).persisted).toBe(false);+ expect((await t.app.request("/api/demo/v2", { headers: { cookie } })).status).toBe(200);++ // A failed push now recovers v2 — what was RUNNING — not v1, what was committed.+ expect((await pushPlatform(t.app, cookie, BOOM_PLATFORM_PACKAGED_ID)).status).toBe(400);+ expect((await t.app.request("/api/demo/v2", { headers: { cookie } })).status).toBe(200);+ });+});