Skip to content

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.ts
index 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.ts
index 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 half
expect((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);
+ });
+});