Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

fix(server): a pushed platform bundle lands in the store, and nowhere else (#422)

Myriad-Dreamin46fa21ed19ca
diff --git a/changelog/unreleased/2026-08-23-hot-update-bundles-land-only-in-the-store.md b/changelog/unreleased/2026-08-23-hot-update-bundles-land-only-in-the-store.md
new file mode 100644
index 00000000..4118e100
--- /dev/null
+++ b/changelog/unreleased/2026-08-23-hot-update-bundles-land-only-in-the-store.md
@@ -0,0 +1,28 @@
+# A pushed platform bundle lands in the store, and nowhere else
+
+- **Date:** 2026-08-23
+- **Type:** fix
+- **Scope:** `server`
+- **PR:** [#422](https://github.com/Prism-Shadow/penguin-harness/pull/422)
+
+[中文版](2026-08-23-hot-update-bundles-land-only-in-the-store.zh.md)
+
+Every push wrote its platform bundle to disk twice: once into `<data root>/hmr/uploads/`, so
+the boot had a file to import, and once more into the content-addressed store when the
+version was committed. Only the store copy was ever read again, and only the store was swept
+— `hmr/uploads/` grew by one multi-megabyte file per distinct bundle pushed, for the life of
+the installation. A watch-and-push development loop filled it fastest, but nothing ever
+emptied it.
+
+The bundle now goes straight to its content-addressed path in the store and is imported from
+there, so the bytes exist once and the sweep that already bounds the store bounds them.
+`hmr/uploads/` is removed by that same sweep on the next successful push.
+
+## Details
+
+- A push that fails to boot leaves its bundle unreferenced in the store rather than
+ committed; the next successful push's sweep collects it, and the committed version is kept
+ regardless of how many failed pushes sit between them.
+- The live swap and the disk commit share one more write than before: a data root whose
+ `hmr/store/` cannot be written at all now fails the push instead of applying it live and
+ reporting `persisted: false`. The running version is untouched either way.
diff --git a/changelog/unreleased/2026-08-23-hot-update-bundles-land-only-in-the-store.zh.md b/changelog/unreleased/2026-08-23-hot-update-bundles-land-only-in-the-store.zh.md
new file mode 100644
index 00000000..c46bef31
--- /dev/null
+++ b/changelog/unreleased/2026-08-23-hot-update-bundles-land-only-in-the-store.zh.md
@@ -0,0 +1,24 @@
+# 推送的 platform bundle 只落在 store 里
+
+- **Date:** 2026-08-23
+- **Type:** fix
+- **Scope:** `server`
+- **PR:** [#422](https://github.com/Prism-Shadow/penguin-harness/pull/422)
+
+[English](2026-08-23-hot-update-bundles-land-only-in-the-store.md)
+
+每次推送都会把 platform bundle 写两遍磁盘:一遍写进 `<数据根>/hmr/uploads/`,好让启动有个文件可以
+import;版本提交时再按内容寻址写进 store 一遍。之后只有 store 里那份还会被读到,被清理的也只有
+store——`hmr/uploads/` 每推送一个不同的 bundle 就多出一个数 MB 的文件,伴随安装终身。开发时的
+watch-and-push 循环填得最快,而没有任何东西会清空它。
+
+现在 bundle 直接写到 store 里它自己的内容寻址路径,也从那里被 import,于是这些字节只存在一份,
+原本就在给 store 定界的那次清理同时给它定了界。`hmr/uploads/` 会在下一次成功推送时被同一次清理
+删掉。
+
+## 细节
+
+- 启动失败的推送会在 store 里留下一个无人引用的 bundle,而不是被提交;下一次成功推送的清理会收走
+ 它,且无论中间夹着多少次失败推送,已提交的版本都会被保留。
+- 现在热交换与磁盘提交多共用一次写:`hmr/store/` 完全写不进去的数据根,会让推送直接失败,而不是
+ 先生效再报 `persisted: false`。两种情况下正在运行的版本都不受影响。
diff --git a/packages/server/src/hmr/host.ts b/packages/server/src/hmr/host.ts
index dc4674f6..a8de73d6 100644
--- a/packages/server/src/hmr/host.ts
+++ b/packages/server/src/hmr/host.ts
@@ -341,7 +341,9 @@ export class HmrHost {
webMem.set(rel, Buffer.from(b64, "base64"));
}
- const platformPath = await this.writeInlinePlatformBundle(target.platform);
+ const { file: platformPath, sha: platformSha } = await this.storePlatformBundle(
+ target.platform,
+ );
const bundle = await this.importBundleFile(platformPath);
const source = target.source ?? null;
@@ -402,7 +404,7 @@ export class HmrHost {
const digest = filesDigest(target.web);
const gz = zlib.gzipSync(Buffer.from(JSON.stringify({ files: target.web })));
const persisted = await this.persistVersion(
- target.platform,
+ platformSha,
target.cli,
gz,
digest.slice(0, 16),
@@ -469,20 +471,28 @@ export class HmrHost {
/**
* Materializes the inline platform bundle (the single-file ESM sent in the
- * request body) to disk and returns its path — how a push reaches a runtime
- * over HTTP alone: the bytes travel in the request, the server writes them,
- * then loads them via importBundleFile. Only the platform artifact needs
- * this treatment: it is the only one of the three this process ever
- * imports and boots. The cli artifact is never imported here (see
- * persistVersion) — it goes straight from request body to content-addressed
- * store.
+ * request body) to disk and returns its path and sha — how a push reaches a
+ * runtime over HTTP alone: the bytes travel in the request, the server writes
+ * them, then loads them via importBundleFile. Only the platform artifact needs
+ * this treatment: it is the only one of the three this process ever imports
+ * and boots. The cli artifact is never imported here (see persistVersion) — it
+ * goes straight from request body to content-addressed store.
+ *
+ * It lands at its FINAL content-addressed path, before the boot that decides
+ * whether it will be committed, so the bytes exist on disk exactly once: an
+ * upload area separate from the store would hold a second copy of every bundle
+ * ever pushed, under no sweep (pruneStore only knows the store). The cost is
+ * that a push which fails to boot leaves an unreferenced file behind; the next
+ * successful push's prune collects it, and the committed version is force-kept
+ * regardless of how many failures sit between them.
*/
- private async writeInlinePlatformBundle(content: string): Promise<string> {
- const dir = path.join(this.hmrDir, "uploads");
+ private async storePlatformBundle(content: string): Promise<{ file: string; sha: string }> {
+ const sha = sha1(content).slice(0, 16);
+ const dir = path.join(this.storeDir, "platform");
await fsp.mkdir(dir, { recursive: true });
- const file = path.join(dir, `platform-${sha1(content).slice(0, 16)}.mjs`);
+ const file = path.join(dir, `${sha}.mjs`);
await fsp.writeFile(file, content, "utf8");
- return file;
+ return { file, sha };
}
// -- Web platform (the frontend package's built dist) ---------------------
@@ -503,10 +513,10 @@ export class HmrHost {
// -- Persistence ----------------------------------------------------------
/**
- * Content-addresses the platform bundle (its CODE only — see the module doc: state
- * is never persisted), the cli bundle (never imported — just stored, for
- * packages/cli's own loader to pick up), and the web gzip artifact, then flips
- * harness.json ONCE — `platform`, `cli`, and `web` all land in the SAME atomic
+ * Content-addresses the cli bundle (never imported — just stored, for packages/cli's
+ * own loader to pick up) and the web gzip artifact next to the platform bundle the
+ * boot already stored (its CODE only — see the module doc: state is never
+ * persisted), then flips harness.json ONCE — `platform`, `cli`, and `web` all land in the SAME atomic
* rename, never three separate commits that could leave one pointer ahead of the
* others. `platform.bundle` and `cli.bundle` are genuinely independent files
* (distinct content, distinct sha) rather than the same physical bundle under two
@@ -568,18 +578,15 @@ export class HmrHost {
}
private async persistVersion(
- platformContent: string,
+ platformSha: string,
cliContent: string,
webGz: Buffer,
webSha: string,
assetsDir: string | null,
): Promise<boolean> {
try {
- const platformSha = sha1(platformContent).slice(0, 16);
- const platformDir = path.join(this.storeDir, "platform");
- await fsp.mkdir(platformDir, { recursive: true });
- await fsp.writeFile(path.join(platformDir, `${platformSha}.mjs`), platformContent, "utf8");
-
+ // The platform bundle is already in the store: storePlatformBundle put it at its
+ // content-addressed path so the boot could import it from there.
const cliSha = sha1(cliContent).slice(0, 16);
const cliDir = path.join(this.storeDir, "cli");
await fsp.mkdir(cliDir, { recursive: true });
@@ -682,6 +689,14 @@ export class HmrHost {
(sha) => fsp.rm(path.join(webDir, `${sha}.webz`), { force: true }),
);
+ // Pre-store pushes staged the platform bundle in `hmr/uploads/` before importing it
+ // and then wrote a second copy into the store; nothing ever read the staged copy
+ // again and no sweep covered that directory. Removing it here is one line in the
+ // sweep that already owns disk reclamation, rather than a migration step.
+ await fsp
+ .rm(path.join(this.hmrDir, "uploads"), { recursive: true, force: true })
+ .catch(() => undefined);
+
// Assets are directories, not single files; otherwise the same keep-newest rule.
const assetsRoot = path.join(this.storeDir, "assets");
const assetsRef = manifest.assets?.dir.match(/([0-9a-f]+)$/)?.[1] ?? null;
diff --git a/packages/server/test/hmr-host.test.ts b/packages/server/test/hmr-host.test.ts
index ad192d8d..ecf7eaf0 100644
--- a/packages/server/test/hmr-host.test.ts
+++ b/packages/server/test/hmr-host.test.ts
@@ -277,12 +277,12 @@ describe("upgrade outcome: persisted flag", () => {
const cookie = (await loginAdmin(t.app)).cookie;
const api = apiClient(t.app, cookie);
- // Force persistVersion's mkdir to fail without touching the live-swap path: `hmr/store`
- // exists as a plain FILE, so `fsp.mkdir(hmr/store/platform, { recursive: true })` throws
- // ENOTDIR. `hmr/uploads` (used earlier in doUpgradeAll, for the platform boot itself) is
- // unaffected since it's a sibling of `store`, not nested under it.
- await fs.mkdir(path.join(t.root, "hmr"), { recursive: true });
- await fs.writeFile(path.join(t.root, "hmr", "store"), "not a directory");
+ // Force persistVersion's mkdir to fail without touching the live-swap path:
+ // `hmr/store/web` exists as a plain FILE, so `fsp.mkdir(hmr/store/web,
+ // { recursive: true })` throws EEXIST. `hmr/store/platform`, which doUpgradeAll
+ // writes the bundle into before booting it, is a sibling and stays usable.
+ await fs.mkdir(path.join(t.root, "hmr", "store"), { recursive: true });
+ await fs.writeFile(path.join(t.root, "hmr", "store", "web"), "not a directory");
const res = await pushPlatform(
t.app,
@@ -519,3 +519,43 @@ describe("upgrade boot failure: recovery re-boots the PUSHED version, not the pa
expect((await t.app.request("/api/demo/v2", { headers: { cookie } })).status).toBe(200);
});
});
+
+describe("the store is the only place a pushed platform bundle lands", () => {
+ let t: TestApp;
+ afterEach(async () => {
+ await t.cleanup();
+ });
+
+ it("keeps the bundle count bounded across many pushes and stages nothing outside the store", async () => {
+ t = await createTestApp();
+ const cookie = (await loginAdmin(t.app)).cookie;
+
+ // A directory left by a pre-store push: it must not survive the next commit.
+ const legacyUploads = path.join(t.root, "hmr", "uploads");
+ await fs.mkdir(legacyUploads, { recursive: true });
+ await fs.writeFile(path.join(legacyUploads, "platform-deadbeefdeadbeef.mjs"), "// stale");
+
+ // Five distinct bundles: distinct content, so five distinct content addresses.
+ for (let i = 0; i < 5; i++) {
+ const res = await pushPlatform(t.app, cookie, platformServing([`/api/demo/v${i}`], `v${i}`));
+ expect(res.status).toBe(200);
+ expect(((await res.json()) as { persisted: boolean }).persisted).toBe(true);
+ }
+
+ expect(fsSync.existsSync(legacyUploads)).toBe(false);
+
+ // Bounded by the store's own keep rule (current + one rollback), not by the number
+ // of pushes.
+ const stored = await fs.readdir(path.join(t.root, "hmr", "store", "platform"));
+ expect(stored.length).toBeLessThanOrEqual(2);
+
+ // And what the manifest names is one of the survivors.
+ const manifest = JSON.parse(
+ await fs.readFile(path.join(t.root, "hmr", "harness.json"), "utf8"),
+ ) as { platform: { bundle: string } };
+ expect(stored).toContain(path.basename(manifest.platform.bundle));
+
+ // The last push is still the one serving.
+ expect((await t.app.request("/api/demo/v4", { headers: { cookie } })).status).toBe(200);
+ });
+});