Skip to content

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

feat: support hot update of harness (#298)

Myriad-Dreamin3ca7ce55ac3a
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2dc06129..f13b4d2f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -115,3 +115,65 @@ jobs:
- name: Windows installer tests
shell: pwsh
run: ./scripts/test-installer.ps1
+
+ # Runtime desktop app, in parallel with the test jobs: an unpacked Electron
+ # shell that boots the server and WAITS for hot-reload requests (the
+ # "runtime" form of the four-layer model). The platform units are the
+ # existing packages (server = backend platform, web = frontend platform);
+ # the artifact bakes a copy of both in so it works out of the box, and its
+ # running platform is replaceable over /api/hmr. Built with electron-builder
+ # `--dir` (an unpacked app directory including the Electron runtime, not an
+ # installer): a runtime is meant to be dropped in and hot-updated, not
+ # distributed through an installer channel — signed installers stay in
+ # desktop-build.yml. Unsigned by design.
+ runtime:
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - os: ubuntu-latest
+ platform: "--linux"
+ - os: macos-latest
+ platform: "--mac"
+ - os: windows-latest
+ platform: "--win"
+ runs-on: ${{ matrix.os }}
+ permissions:
+ contents: read
+ steps:
+ - uses: actions/checkout@v5
+
+ # pnpm version comes from package.json's packageManager field.
+ - uses: pnpm/action-setup@v6
+
+ - uses: actions/setup-node@v5
+ with:
+ node-version: 24
+ cache: pnpm
+
+ - run: pnpm install --frozen-lockfile
+
+ - run: pnpm build
+
+ # Stage the self-contained app tree (packages/desktop/stage/app) that
+ # electron-builder packages — the same explicit step desktop-build.yml runs.
+ - name: Stage the app tree
+ run: node packages/desktop/scripts/stage.mjs
+
+ - name: Build unpacked runtime
+ env:
+ CSC_IDENTITY_AUTO_DISCOVERY: "false"
+ run: pnpm --dir packages/desktop exec electron-builder ${{ matrix.platform }} --dir --publish never
+
+ - name: Upload runtime artifact
+ uses: actions/upload-artifact@v4
+ with:
+ name: penguin-runtime-${{ runner.os }}
+ if-no-files-found: error
+ # Each OS produces exactly one of these unpacked trees.
+ path: |
+ packages/desktop/stage/out/linux-unpacked
+ packages/desktop/stage/out/win-unpacked
+ packages/desktop/stage/out/mac
+ packages/desktop/stage/out/mac-arm64
+ packages/desktop/stage/out/mac-x64
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 61186b5d..5ca150bd 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -204,9 +204,9 @@ jobs:
DIR="$(cd "$(dirname "$SELF")/.." && pwd)"
export PENGUIN_WEB_DIST="${PENGUIN_WEB_DIST:-$DIR/web}"
if [ -x "$DIR/node/bin/node" ]; then
- exec "$DIR/node/bin/node" "$DIR/lib/dist/index.js" "$@"
+ exec "$DIR/node/bin/node" "$DIR/lib/dist/penguin.js" "$@"
fi
- exec node "$DIR/lib/dist/index.js" "$@"
+ exec node "$DIR/lib/dist/penguin.js" "$@"
EOF
chmod +x out/penguin/bin/penguin
@@ -282,9 +282,9 @@ jobs:
if not defined PENGUIN_WEB_DIST set "PENGUIN_WEB_DIST=%DIR%\web"
if exist "%DIR%\git\usr\bin\sh.exe" set "PENGUIN_BUNDLED_SHELL=%DIR%\git\usr\bin\sh.exe"
if exist "%DIR%\node\node.exe" (
- "%DIR%\node\node.exe" "%DIR%\lib\dist\index.js" %*
+ "%DIR%\node\node.exe" "%DIR%\lib\dist\penguin.js" %*
) else (
- node "%DIR%\lib\dist\index.js" %*
+ node "%DIR%\lib\dist\penguin.js" %*
)
exit /b %ERRORLEVEL%
EOF
diff --git a/changelog/unreleased/2026-08-18-hot-update.md b/changelog/unreleased/2026-08-18-hot-update.md
new file mode 100644
index 00000000..f9b7d117
--- /dev/null
+++ b/changelog/unreleased/2026-08-18-hot-update.md
@@ -0,0 +1,42 @@
+# Hot update: replace the running harness's code over HTTP, no restart
+
+A running PenguinHarness — the desktop app included — can now be updated in place: one
+HTTP push replaces the backend platform, the CLI's command implementations, and the Web
+App together, in seconds, without restarting the server or reinstalling anything. Live
+state survives the swap — a terminal process started before an update is still running,
+with its output intact, after it.
+
+## One push, one version
+
+`POST /api/hmr/upgrade` takes a single gzip payload carrying three artifacts — the
+platform bundle, the CLI bundle, and the built web dist — and applies them as one atomic
+version. The new platform must boot and the web dist must validate before anything is
+committed; a failure of either leaves the previous version running untouched. A restart
+resumes the last committed version as a unit, and a damaged store falls back to the
+packaged defaults rather than a broken half-update. The store keeps the current version
+plus one rollback candidate.
+
+Deploying is one command: `PENGUIN_ADMIN_PASSWORD=… node scripts/deploy.mjs <port|url>`
+builds and pushes everything, working equally through an ssh tunnel to a remote machine.
+
+## Pushed code owns its API
+
+The runtime no longer owns the route table. Every request is offered to the running
+platform first, so a push can add an endpoint, replace one, or change what an existing
+one does — with no rebuild and no new server release. Only the `/api/hmr/*` upgrade
+channel is reserved: it is what a broken platform gets replaced through, so no push can
+take it away.
+
+## The CLI updates with the push
+
+`penguin` always runs the commands built into it; `penguin-hmr` runs the CLI
+implementation most recently pushed to the machine, straight from the update store — so
+command fixes ship with the same push as the server code they talk to, without
+reinstalling the binary.
+
+## Access
+
+The hot APIs require an admin session (the same login as the browser) and are
+loopback-only unless served over HTTPS — there is deliberately no token on disk and no
+insecure-network override: a file credential would be readable by everything running as
+the same user, including an agent's own shell.
diff --git a/changelog/unreleased/README.md b/changelog/unreleased/README.md
index 89a9b386..8213add1 100644
--- a/changelog/unreleased/README.md
+++ b/changelog/unreleased/README.md
@@ -1,6 +1,7 @@
# Unreleased
- [2026-08-18] Core & Web App: an official `MiniMax-M3` preset (1M context, vision) pins AgentHub's `minimax-m3` Responses client and direct endpoint, uses `MINIMAX_*` credential fallback, prices at the standard pay-as-you-go tier (≤512K input), and adds the MiniMax provider glyph plus bilingual docs (requires AgentHub >= 0.4.2). ([details](2026-08-18-minimax-m3-preset.md))
+- [2026-08-18] The running harness — desktop app included — can be updated over HTTP without a restart: one atomic push replaces the backend platform, the CLI's commands (`penguin-hmr`), and the Web App together; pushed code can add or replace API endpoints; live terminals survive the swap. Admin session required, loopback-only without HTTPS. ([details](2026-08-18-hot-update.md))
- [2026-08-14] Match the macOS app icon's visual size to neighbouring apps. ([details](2026-08-14-macos-app-icon-size.md))
- [2026-08-14] Unknown model IDs can be moved to Custom with the OpenAI-compatible client. ([details](2026-08-14-model-group-protocol.md))
- [2026-08-11] CLI: `penguin config model remove --model-id <id> --provider <group>` deletes a model entry and the credential inlined on it, matched on the exact pair so a same-id entry under another group is left alone; the `default_model` / `vision_model` settings are cleared when they named the removed entry, matching what the Web App's models page already does on delete. ([details](2026-08-11-cli-model-remove.md))
diff --git a/package.json b/package.json
index 263d3604..b1f58d58 100644
--- a/package.json
+++ b/package.json
@@ -29,6 +29,7 @@
"@prismshadow/penguin-core": "workspace:*",
"@types/node": "^24.0.0",
"concurrently": "^10.0.4",
+ "esbuild": "^0.28.1",
"prettier": "^3.9.4",
"tsx": "^4.20.0",
"typescript": "^5.6.0",
diff --git a/packages/cli/package.json b/packages/cli/package.json
index f8064fdc..c6836165 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -10,7 +10,8 @@
"directory": "packages/cli"
},
"bin": {
- "penguin": "./dist/index.js"
+ "penguin": "./dist/penguin.js",
+ "penguin-hmr": "./dist/penguin-hmr.js"
},
"engines": {
"node": ">=24"
@@ -19,7 +20,7 @@
"typecheck": "tsc --noEmit -p tsconfig.json",
"test": "vitest run --passWithNoTests",
"build": "tsup",
- "penguin": "node ../../scripts/run-with-env.mjs PENGUIN_HOME=~/.penguin/dev-data PORT=7369 -- tsx src/index.ts"
+ "penguin": "node ../../scripts/run-with-env.mjs PENGUIN_HOME=~/.penguin/dev-data PORT=7369 -- tsx src/penguin.ts"
},
"dependencies": {
"@modelcontextprotocol/client": "^2.0.0",
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 9f47bd2f..af21b798 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -1,19 +1,12 @@
/**
- * PenguinHarness CLI entry point.
+ * The whole CLI as a plain function: commander commands over
+ * @prismshadow/penguin-core, returning an exit code.
*
- * Only responsible for parsing CLI input into SDK arguments and rendering the streaming
- * OmniMessage returned by the SDK.
- * Loads .env on startup (e.g. locally configured ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL).
- *
- * penguin config model add|default ...
- * penguin chat ...
- * penguin run --message ...
- * penguin server|web ...
- * penguin update ...
- * Docs: packages/docs/content/cli.{zh,en}.md (site path /docs/cli).
+ * Built twice: into this package's `penguin` binary (penguin.ts), and — as the CLI
+ * artifact pushed to POST /api/hmr/upgrade — into the bundle `penguin-hmr` loads from
+ * the HMR store instead (see scripts/deploy.mjs).
*/
-import "dotenv/config";
-import { Command } from "commander";
+import { Command, CommanderError } from "commander";
import { VERSION } from "@prismshadow/penguin-core";
import { registerConfigCommand } from "./commands/config.js";
import { registerRunCommand } from "./commands/run.js";
@@ -22,28 +15,41 @@ import { registerServeCommands } from "./commands/serve.js";
import { registerUpdateCommand } from "./commands/update.js";
import { defaultMessages } from "./i18n.js";
-// Language comes from the PENGUIN_LANG env var (default en); used consistently for
-// command/option descriptions and runtime output.
-const t = defaultMessages();
-
-const program = new Command();
-program
- .name("penguin")
- .description(t.cliDescription)
- .version(VERSION, "-v, --version", t.versionDesc);
+/**
+ * Runs one invocation (`argv` = process.argv.slice(2)) and returns its exit code.
+ * `exitOverride()` keeps commander from calling process.exit, and process.exitCode is
+ * read back then restored, so calling this more than once in a process is safe.
+ */
+export async function cli(argv: string[]): Promise<number> {
+ const t = defaultMessages();
+ const program = new Command();
+ program
+ .name("penguin")
+ .description(t.cliDescription)
+ .version(VERSION, "-v, --version", t.versionDesc)
+ .exitOverride();
-registerConfigCommand(program, t);
-registerRunCommand(program, t);
-registerChatCommand(program, t);
-registerServeCommands(program, t);
-registerUpdateCommand(program, t);
+ registerConfigCommand(program, t);
+ registerRunCommand(program, t);
+ registerChatCommand(program, t);
+ registerServeCommands(program, t);
+ registerUpdateCommand(program, t);
-// Show help only when no subcommand is given (empty input); do not error.
-program.action(() => {
- program.outputHelp();
-});
+ // Show help only when no subcommand is given (empty input); do not error.
+ program.action(() => {
+ program.outputHelp();
+ });
-program.parseAsync(process.argv).catch((err: unknown) => {
- process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
- process.exitCode = 1;
-});
+ const priorExitCode = process.exitCode;
+ process.exitCode = undefined;
+ try {
+ await program.parseAsync(argv, { from: "user" });
+ return typeof process.exitCode === "number" ? process.exitCode : 0;
+ } catch (err) {
+ if (err instanceof CommanderError) return err.exitCode;
+ process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+ return 1;
+ } finally {
+ process.exitCode = priorExitCode;
+ }
+}
diff --git a/packages/cli/src/penguin-hmr.ts b/packages/cli/src/penguin-hmr.ts
new file mode 100644
index 00000000..96eb4426
--- /dev/null
+++ b/packages/cli/src/penguin-hmr.ts
@@ -0,0 +1,32 @@
+/**
+ * `penguin-hmr`: the CLI currently pushed to this machine's HMR store, instead of the
+ * one built into this binary. Use `penguin` when nothing is pushed.
+ */
+import "dotenv/config";
+import { pathToFileURL } from "node:url";
+import { resolveRoot } from "@prismshadow/penguin-core";
+import { resolveCliBundlePath } from "@prismshadow/penguin-server/hmr/manifest";
+
+export async function loadPushedCli(root: string): Promise<(argv: string[]) => Promise<number>> {
+ const bundlePath = await resolveCliBundlePath(root);
+ if (bundlePath === null) throw new Error(`no CLI pushed to ${root}; use \`penguin\` instead`);
+ // Cache-busted: a re-push writes a new file, but the same path may be reused.
+ const mod = (await import(`${pathToFileURL(bundlePath).href}?v=${Date.now()}`)) as {
+ cli?: (argv: string[]) => Promise<number>;
+ };
+ if (typeof mod.cli !== "function") throw new Error(`${bundlePath} does not export 'cli'`);
+ return mod.cli;
+}
+
+/** Only when run as the entry point, so tests can import loadPushedCli. */
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ loadPushedCli(resolveRoot())
+ .then((cli) => cli(process.argv.slice(2)))
+ .then((code) => {
+ process.exitCode = code;
+ })
+ .catch((err: unknown) => {
+ process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+ process.exitCode = 1;
+ });
+}
diff --git a/packages/cli/src/penguin.ts b/packages/cli/src/penguin.ts
new file mode 100644
index 00000000..e31b4ac6
--- /dev/null
+++ b/packages/cli/src/penguin.ts
@@ -0,0 +1,12 @@
+/** `penguin`: the CLI built into this binary. */
+import "dotenv/config";
+import { cli } from "./index.js";
+
+cli(process.argv.slice(2))
+ .then((code) => {
+ process.exitCode = code;
+ })
+ .catch((err: unknown) => {
+ process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+ process.exitCode = 1;
+ });
diff --git a/packages/cli/tsup.config.ts b/packages/cli/tsup.config.ts
index acc70b42..83c21d87 100644
--- a/packages/cli/tsup.config.ts
+++ b/packages/cli/tsup.config.ts
@@ -1,7 +1,7 @@
import { defineConfig } from "tsup";
export default defineConfig({
- entry: ["src/index.ts"],
+ entry: ["src/penguin.ts", "src/penguin-hmr.ts"],
format: ["esm"],
target: "node20",
platform: "node",
diff --git a/packages/core/package.json b/packages/core/package.json
index b3e22cc5..9e1c11f3 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -29,6 +29,11 @@
"./model-catalog": {
"types": "./dist/state/model-catalog.d.ts",
"import": "./dist/state/model-catalog.js"
+ },
+ "./kernel": {
+ "types": "./dist/kernel/index.d.ts",
+ "import": "./dist/kernel/index.js",
+ "default": "./dist/kernel/index.js"
}
},
"main": "./dist/index.js",
@@ -43,6 +48,7 @@
"@modelcontextprotocol/client": "^2.0.0",
"@prismshadow/agenthub": "^0.4.2",
"@prismshadow/penguin-skills": "workspace:*",
+ "arktype": "^2.2.3",
"smol-toml": "^1.3.0",
"yaml": "^2.5.0"
},
diff --git a/packages/core/src/kernel/boot.ts b/packages/core/src/kernel/boot.ts
new file mode 100644
index 00000000..fd44bba2
--- /dev/null
+++ b/packages/core/src/kernel/boot.ts
@@ -0,0 +1,274 @@
+/**
+ * boot(): the only place instances are created. Walks the static tree declared
+ * by the iface, boots children first (keyed collections get a handle with
+ * add/remove — runtime cardinality changes still go through boot), then calls
+ * the impl factory and verifies the returned api against the iface method set.
+ *
+ * State discipline (linear state):
+ * - serializable state lives in the parked context document,
+ * - live resources stay in the runtime-side `Resources` registry and the
+ * context only carries handle ids (claim on boot; a failed claim is an
+ * explicit discard, surfaced to the upgrade ladder),
+ * - reseedable state is rebuilt after boot and never parked.
+ */
+import type { Json, JsonObject } from "./json.js";
+import { isJsonObject } from "./json.js";
+import type { AnyIface, ChildDecl, Iface, Park } from "./iface.js";
+import { isKeyed } from "./iface.js";
+
+/** Runtime-owned live resources (pty, child processes, connections). */
+export interface Resources {
+ /**
+ * `dispose` is how a resource says what "shut down" means for it — the registry
+ * itself knows nothing about kinds, so a platform can introduce a resource type the
+ * runtime has never heard of and still have it cleaned up at process exit.
+ */
+ register(id: string, resource: unknown, dispose?: () => void): void;
+ claim<T = unknown>(id: string): T | undefined;
+ release(id: string): void;
+}
+
+export interface NodeCtx {
+ resources: Resources;
+ /** Self-cleaning registration: collected disposers are drained at dispose. */
+ effect(dispose: () => void): void;
+}
+
+/** Handle a parent receives for a `keyed()` child collection. */
+export interface KeyedHandle<A extends Park = Park> {
+ get(key: string): A | undefined;
+ keys(): string[];
+ add(key: string, context: Json): Promise<A>;
+ remove(key: string): void;
+}
+
+/**
+ * An impl provides the factory for its node plus impls for declared children.
+ * `children` values handed to create(): singleton child → its api, keyed
+ * child → a KeyedHandle. (Loosely typed until the arktype-era inference —
+ * see TODO(schema) in json.ts.)
+ */
+export interface Impl<A extends Park = Park, C extends Json = Json> {
+ create(ctx: NodeCtx, context: C, children: Record<string, unknown>): A | Promise<A>;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ children?: Record<string, Impl<any, any>>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyImpl = Impl<any, any>;
+
+export class BootError extends Error {
+ constructor(message: string) {
+ super(message);
+ this.name = "BootError";
+ }
+}
+
+/** Parked tree node: `v` is the iface version the document was parked under. */
+export interface ParkedNode extends JsonObject {
+ v: number;
+ self: Json;
+ children: { [name: string]: Json };
+}
+
+interface NodeInst {
+ iface: AnyIface;
+ api: Park & Record<string, unknown>;
+ disposers: Array<() => void>;
+ children: Map<string, NodeInst | KeyedInst>;
+}
+
+interface KeyedInst {
+ kind: "keyed";
+ iface: AnyIface;
+ impl: AnyImpl;
+ items: Map<string, NodeInst>;
+}
+
+function isKeyedInst(child: NodeInst | KeyedInst): child is KeyedInst {
+ return "kind" in child && child.kind === "keyed";
+}
+
+export interface Instance<A extends Park = Park> {
+ api: A;
+ iface: Iface<A, Json>;
+ /** Pure snapshot of the whole tree; does not touch the running instance. */
+ park(): ParkedNode;
+ /** Children-first teardown: drains every effect registered via ctx.effect. */
+ dispose(): void;
+}
+
+/** Shapes a fresh (no prior state) parked document for an iface tree. */
+export function initialDoc(
+ iface: AnyIface,
+ self: Json,
+ children: { [name: string]: Json } = {},
+): ParkedNode {
+ const shaped: { [name: string]: Json } = {};
+ for (const [name, decl] of Object.entries(iface.children)) {
+ shaped[name] = children[name] ?? (isKeyed(decl) ? { items: {} } : null);
+ }
+ return { v: iface.version, self, children: shaped };
+}
+
+function parseParkedNode(doc: Json, path: string): ParkedNode {
+ if (!isJsonObject(doc) || typeof doc.v !== "number" || doc.self === undefined) {
+ throw new BootError(`${path}: not a parked node document`);
+ }
+ const children = doc.children;
+ return {
+ v: doc.v,
+ self: doc.self,
+ children: isJsonObject(children) ? children : {},
+ };
+}
+
+async function bootNode(
+ impl: AnyImpl,
+ iface: AnyIface,
+ doc: Json,
+ resources: Resources,
+ path: string,
+): Promise<NodeInst> {
+ const parked = parseParkedNode(doc, path);
+ const parsed = iface.context.strictParse(parked.self, `${path}.self`);
+ if (!parsed.ok) {
+ throw new BootError(
+ `${path}: context does not satisfy iface '${iface.name}' v${iface.version} ` +
+ `(dropped=[${parsed.dropped}] missing=[${parsed.missing}] invalid=[${parsed.invalid}])`,
+ );
+ }
+
+ const childInsts = new Map<string, NodeInst | KeyedInst>();
+ const childHandles: Record<string, unknown> = {};
+ for (const [name, decl] of Object.entries(iface.children)) {
+ const childImpl = impl.children?.[name];
+ if (childImpl === undefined) {
+ throw new BootError(`${path}: impl provides no child impl for '${name}'`);
+ }
+ if (isKeyed(decl)) {
+ const collection: KeyedInst = {
+ kind: "keyed",
+ iface: decl.iface,
+ impl: childImpl,
+ items: new Map(),
+ };
+ const itemsDoc = isJsonObject(parked.children[name])
+ ? (parked.children[name] as JsonObject).items
+ : undefined;
+ if (isJsonObject(itemsDoc)) {
+ for (const [key, itemDoc] of Object.entries(itemsDoc)) {
+ collection.items.set(
+ key,
+ await bootNode(
+ childImpl,
+ decl.iface,
+ itemDoc,
+ resources,
+ `${path}.children.${name}.items.${key}`,
+ ),
+ );
+ }
+ }
+ childInsts.set(name, collection);
+ childHandles[name] = makeKeyedHandle(collection, resources, `${path}.children.${name}`);
+ } else {
+ const childDoc = parked.children[name] ?? initialDoc(decl, null);
+ const inst = await bootNode(childImpl, decl, childDoc, resources, `${path}.children.${name}`);
+ childInsts.set(name, inst);
+ childHandles[name] = inst.api;
+ }
+ }
+
+ const disposers: Array<() => void> = [];
+ const ctx: NodeCtx = {
+ resources,
+ effect: (dispose) => disposers.push(dispose),
+ };
+ const api = (await impl.create(ctx, parsed.value, childHandles)) as Park &
+ Record<string, unknown>;
+
+ // Go-style method-set check, moved to boot time: the impl satisfies the iface
+ // implicitly or not at all.
+ const missingMethods = iface.methods.filter((m) => typeof api[m] !== "function");
+ if (missingMethods.length > 0) {
+ throw new BootError(
+ `${path}: impl does not satisfy iface '${iface.name}': missing method(s) [${missingMethods.join(", ")}]`,
+ );
+ }
+
+ return { iface, api, disposers, children: childInsts };
+}
+
+function makeKeyedHandle(collection: KeyedInst, resources: Resources, path: string): KeyedHandle {
+ return {
+ get: (key) => collection.items.get(key)?.api,
+ keys: () => [...collection.items.keys()],
+ async add(key, context) {
+ if (collection.items.has(key))
+ throw new BootError(`${path}.items.${key}: key already exists`);
+ const doc =
+ isJsonObject(context) && typeof context.v === "number"
+ ? context
+ : initialDoc(collection.iface, context);
+ const inst = await bootNode(
+ collection.impl,
+ collection.iface,
+ doc,
+ resources,
+ `${path}.items.${key}`,
+ );
+ collection.items.set(key, inst);
+ return inst.api;
+ },
+ remove(key) {
+ const inst = collection.items.get(key);
+ if (inst === undefined) return;
+ collection.items.delete(key);
+ disposeNode(inst);
+ },
+ };
+}
+
+function parkNode(node: NodeInst): ParkedNode {
+ const children: { [name: string]: Json } = {};
+ for (const [name, child] of node.children) {
+ if (isKeyedInst(child)) {
+ const items: { [key: string]: Json } = {};
+ for (const [key, item] of child.items) items[key] = parkNode(item);
+ children[name] = { items };
+ } else {
+ children[name] = parkNode(child);
+ }
+ }
+ return { v: node.iface.version, self: node.api.park(), children };
+}
+
+function disposeNode(node: NodeInst): void {
+ for (const child of node.children.values()) {
+ if (isKeyedInst(child)) {
+ for (const item of child.items.values()) disposeNode(item);
+ child.items.clear();
+ } else {
+ disposeNode(child);
+ }
+ }
+ // Reverse order: later effects may depend on earlier ones.
+ for (const dispose of node.disposers.reverse()) dispose();
+ node.disposers.length = 0;
+}
+
+export async function boot<A extends Park, C extends Json>(
+ impl: Impl<A, C>,
+ iface: Iface<A, C>,
+ context: Json,
+ resources: Resources,
+): Promise<Instance<A>> {
+ const root = await bootNode(impl, iface, context, resources, "$");
+ return {
+ api: root.api as unknown as A,
+ iface: iface as Iface<A, Json>,
+ park: () => parkNode(root),
+ dispose: () => disposeNode(root),
+ };
+}
diff --git a/packages/core/src/kernel/iface.ts b/packages/core/src/kernel/iface.ts
new file mode 100644
index 00000000..54f9ef4b
--- /dev/null
+++ b/packages/core/src/kernel/iface.ts
@@ -0,0 +1,91 @@
+/**
+ * ImplInterface in the Go-interface spirit: a descriptor is pure data
+ * (method set + context schema + children shape + migration table). Impls
+ * satisfy an iface implicitly — no registration, no inheritance — checked at
+ * compile time via `satisfies ImplOf<...>` and at boot time by comparing the
+ * method set against the returned api object. Small interfaces compose by
+ * embedding; `Park` is the minimal one embedded in every node.
+ */
+import type { Json } from "./json.js";
+import type { Schema } from "./schema.js";
+
+/** The minimal interface every node implements: a pure snapshot. Dispose is separate. */
+export interface Park {
+ park(): Json;
+}
+
+export interface KeyedDecl {
+ kind: "keyed";
+ iface: AnyIface;
+}
+
+export type ChildDecl = AnyIface | KeyedDecl;
+
+export interface Iface<A extends Park = Park, C extends Json = Json> {
+ kind: "iface";
+ name: string;
+ version: number;
+ context: Schema<C>;
+ /** Runtime-checkable method set (Go's method-set check moved to boot time). */
+ methods: readonly string[];
+ /** Static tree shape: boot is the only place children are created. */
+ children: Record<string, ChildDecl>;
+ /** Ships with the code, keyed by fromVersion; chained automatically (1→2→3). */
+ migrations: Record<number, (old: Json) => Json>;
+ /** Phantom marker carrying the api type (covariant so Instance<Derived> is an Instance<Park>); never a runtime value. */
+ api?: A;
+}
+
+// Child iface maps are heterogeneous (each entry has its own api/context types);
+// the erased form keeps the tree walkable. TODO(schema): arktype-era typing can
+// recover per-child types via inference.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyIface = Iface<any, any>;
+
+export function defineIface<A extends Park, C extends Json>(def: {
+ name: string;
+ version: number;
+ context: Schema<C>;
+ methods: readonly string[];
+ children?: Record<string, ChildDecl>;
+ migrations?: Record<number, (old: Json) => Json>;
+}): Iface<A, C> {
+ return {
+ kind: "iface",
+ name: def.name,
+ version: def.version,
+ context: def.context,
+ methods: def.methods,
+ children: def.children ?? {},
+ migrations: def.migrations ?? {},
+ };
+}
+
+/** Keyed collection: static shape, dynamic cardinality. */
+export function keyed(iface: AnyIface): KeyedDecl {
+ return { kind: "keyed", iface };
+}
+
+export function isKeyed(decl: ChildDecl): decl is KeyedDecl {
+ return "kind" in decl && decl.kind === "keyed";
+}
+
+/**
+ * The serializable interface descriptor — the "platform interface" term of the
+ * snapshot equation (snapshot = platform interface + code + state). Pure data:
+ * dependency checks compare this without executing any checked code.
+ */
+export function ifaceData(iface: AnyIface): Json {
+ return {
+ name: iface.name,
+ version: iface.version,
+ methods: [...iface.methods],
+ context: iface.context.describe(),
+ children: Object.fromEntries(
+ Object.entries(iface.children).map(([name, decl]) => [
+ name,
+ isKeyed(decl) ? { keyed: ifaceData(decl.iface) } : ifaceData(decl),
+ ]),
+ ),
+ };
+}
diff --git a/packages/core/src/kernel/index.ts b/packages/core/src/kernel/index.ts
new file mode 100644
index 00000000..5c3a9957
--- /dev/null
+++ b/packages/core/src/kernel/index.ts
@@ -0,0 +1,25 @@
+/**
+ * Hot-update kernel: Park + boot + a static instance tree, ~300 lines.
+ *
+ * No Node/React/SDK dependencies (arktype is the one library, for context
+ * schemas) so both the server platform and the web platform run the same
+ * code. See the architecture proposal ("可热更新、可分发的 Agent Harness").
+ */
+export type { Json, JsonObject } from "./json.js";
+export { isJsonObject } from "./json.js";
+export type { ParseFail, ParseResult, Schema } from "./schema.js";
+export { schema, type } from "./schema.js";
+export type { AnyIface, ChildDecl, Iface, KeyedDecl, Park } from "./iface.js";
+export { defineIface, ifaceData, isKeyed, keyed } from "./iface.js";
+export type {
+ AnyImpl,
+ Impl,
+ Instance,
+ KeyedHandle,
+ NodeCtx,
+ ParkedNode,
+ Resources,
+} from "./boot.js";
+export { boot, BootError, initialDoc } from "./boot.js";
+export type { UpgradeBlocked, UpgradeResult } from "./upgrade.js";
+export { upgrade } from "./upgrade.js";
diff --git a/packages/core/src/kernel/json.ts b/packages/core/src/kernel/json.ts
new file mode 100644
index 00000000..85ad5596
--- /dev/null
+++ b/packages/core/src/kernel/json.ts
@@ -0,0 +1,14 @@
+/**
+ * Kernel currency: everything that crosses a park/boot boundary is plain JSON.
+ *
+ * Context typing rides on arktype (see ./schema.ts): contexts are defined as
+ * arktype types and wrapped with schema(); Json stays the wire-level currency
+ * every parked document is made of.
+ */
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+
+export type JsonObject = { [key: string]: Json };
+
+export function isJsonObject(value: Json | undefined): value is JsonObject {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
diff --git a/packages/core/src/kernel/schema.ts b/packages/core/src/kernel/schema.ts
new file mode 100644
index 00000000..58c0675e
--- /dev/null
+++ b/packages/core/src/kernel/schema.ts
@@ -0,0 +1,71 @@
+/**
+ * Schema: the kernel's validation CONTRACT, implemented over arktype.
+ *
+ * The contract stays structural (strictParse + describe) so independently
+ * built platform bundles can hand-roll a conforming object with zero
+ * dependencies; in-repo code defines contexts with arktype and wraps them
+ * with schema().
+ *
+ * strictParse is the machine-checkable definition of "data would be
+ * discarded": unknown object keys are reported as `dropped`, absent required
+ * fields as `missing`, type mismatches as `invalid`. Any non-empty list
+ * blocks a silent upgrade and enters the upgrade ladder.
+ */
+import { type } from "arktype";
+import type { Type } from "arktype";
+import type { Json } from "./json.js";
+
+export interface ParseFail {
+ ok: false;
+ /** Paths present in the document but unknown to the schema (would be discarded). */
+ dropped: string[];
+ /** Paths the schema requires but the document lacks. */
+ missing: string[];
+ /** Paths whose value does not match the schema's type. */
+ invalid: string[];
+}
+
+export type ParseResult<C extends Json = Json> = { ok: true; value: C } | ParseFail;
+
+export interface Schema<C extends Json = Json> {
+ strictParse(doc: Json | undefined, path?: string): ParseResult<C>;
+ /** Serializable self-description (the snapshot equation's "interface is data"). */
+ describe(): Json;
+}
+
+// One import site for context definitions: `import { schema, type } from ".../kernel"`.
+export { type } from "arktype";
+
+/** Wraps an arktype type as a kernel Schema (undeclared object keys rejected). */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function schema<C extends Json>(t: Type<C, any>): Schema<C> {
+ // Object types get strict key checking; non-object types (opaque "unknown"
+ // state) have no keys to reject.
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ let strict: Type<C, any> = t;
+ try {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ strict = (t as any).onUndeclaredKey("reject") as Type<C, any>;
+ } catch {
+ strict = t;
+ }
+ return {
+ strictParse(doc, path = "$") {
+ if (doc === undefined) return { ok: false, dropped: [], missing: [path], invalid: [] };
+ const out = strict(doc);
+ if (!(out instanceof type.errors)) return { ok: true, value: out as C };
+ const fail: ParseFail = { ok: false, dropped: [], missing: [], invalid: [] };
+ for (const e of out) {
+ const p = e.path.length > 0 ? `${path}.${e.path.join(".")}` : path;
+ // arktype error → ladder judgment: a required key absent is `missing`;
+ // an undeclared key (onUndeclaredKey("reject") expects it "removed")
+ // is `dropped`; everything else is a type mismatch.
+ if (e.code === "required") fail.missing.push(p);
+ else if (e.expected === "removed") fail.dropped.push(p);
+ else fail.invalid.push(`${p}: expected ${e.expected}`);
+ }
+ return fail;
+ },
+ describe: () => t.expression,
+ };
+}
diff --git a/packages/core/src/kernel/upgrade.ts b/packages/core/src/kernel/upgrade.ts
new file mode 100644
index 00000000..9bd5c144
--- /dev/null
+++ b/packages/core/src/kernel/upgrade.ts
@@ -0,0 +1,139 @@
+/**
+ * The upgrade ladder, MVP slice: silent → migrator chain → blocked.
+ *
+ * "Data is not discarded" is machine-decided by strictParse over the parked
+ * document (after running per-node migration chains). Any dropped/missing/
+ * invalid path blocks the swap: the old instance keeps running untouched and
+ * the caller receives the parked doc plus the exact paths — the input for the
+ * next rungs of the ladder (auto-upgrader / agent / human), which live outside
+ * the kernel.
+ *
+ * Validate-then-swap: the running tree is only disposed after the whole
+ * document reconciles. MVP accepts the residual risk that boot itself may still
+ * throw after dispose — the doc is returned to the caller for persistence, so
+ * the worst case is "old impl + parked doc, re-boot by hand", never data loss.
+ */
+import type { Json } from "./json.js";
+import { isJsonObject } from "./json.js";
+import type { AnyIface, Iface, Park } from "./iface.js";
+import { isKeyed } from "./iface.js";
+import type { Impl, Instance, ParkedNode, Resources } from "./boot.js";
+import { boot } from "./boot.js";
+
+export interface UpgradeBlocked {
+ status: "blocked";
+ dropped: string[];
+ missing: string[];
+ invalid: string[];
+ /** The parked (and partially migrated) document — persist it; nothing is lost. */
+ doc: Json;
+}
+
+export type UpgradeResult<A extends Park> =
+ { status: "ok"; mode: "silent" | "migrated"; instance: Instance<A>; doc: Json } | UpgradeBlocked;
+
+/** An undeclared child that is an empty container (no data to lose). */
+function isEmptyChildDoc(doc: Json): boolean {
+ if (doc === null) return true;
+ if (isJsonObject(doc) && Object.keys(doc).length === 1 && isJsonObject(doc.items)) {
+ return Object.keys(doc.items).length === 0;
+ }
+ return false;
+}
+
+interface ReconcileState {
+ dropped: string[];
+ missing: string[];
+ invalid: string[];
+ migrated: boolean;
+}
+
+/** Runs migration chains and strict-parses the whole tree; pure, touches no instance. */
+function reconcileNode(iface: AnyIface, doc: Json, path: string, state: ReconcileState): Json {
+ if (!isJsonObject(doc) || typeof doc.v !== "number" || doc.self === undefined) {
+ state.invalid.push(`${path}: not a parked node document`);
+ return doc;
+ }
+ let version = doc.v;
+ let self = doc.self;
+ if (version > iface.version) {
+ state.invalid.push(`${path}.v: parked under v${version}, newer than iface v${iface.version}`);
+ return doc;
+ }
+ // Migrator chain ships with the code (iface.migrations), auto-chained 1→2→3.
+ // MVP scope: migrations transform the node's own `self` document; reshaping
+ // children is out of scope for the chain and lands in `blocked` instead.
+ while (version < iface.version) {
+ const migrate = iface.migrations[version];
+ if (migrate === undefined) break;
+ self = migrate(self);
+ version += 1;
+ state.migrated = true;
+ }
+ if (version < iface.version) {
+ state.missing.push(`${path}.v: no migration path from v${version} to v${iface.version}`);
+ }
+
+ const parsed = iface.context.strictParse(self, `${path}.self`);
+ if (!parsed.ok) {
+ state.dropped.push(...parsed.dropped);
+ state.missing.push(...parsed.missing);
+ state.invalid.push(...parsed.invalid);
+ }
+
+ const docChildren = isJsonObject(doc.children) ? doc.children : {};
+ const children: { [name: string]: Json } = {};
+ for (const [name, decl] of Object.entries(iface.children)) {
+ const childPath = `${path}.children.${name}`;
+ const childDoc = docChildren[name];
+ if (isKeyed(decl)) {
+ const items: { [key: string]: Json } = {};
+ const itemsDoc = isJsonObject(childDoc) ? childDoc.items : undefined;
+ if (isJsonObject(itemsDoc)) {
+ for (const [key, itemDoc] of Object.entries(itemsDoc)) {
+ items[key] = reconcileNode(decl.iface, itemDoc, `${childPath}.items.${key}`, state);
+ }
+ }
+ children[name] = { items };
+ } else if (childDoc === undefined) {
+ state.missing.push(childPath);
+ } else {
+ children[name] = reconcileNode(decl, childDoc, childPath, state);
+ }
+ }
+ // Children the new iface no longer declares are discarded data — report
+ // them, UNLESS they are empty containers: an empty keyed collection (or a
+ // null slot) carries no data, so dropping it discards nothing (linear
+ // state tracks values, not shapes).
+ for (const [name, childDoc] of Object.entries(docChildren)) {
+ if (name in iface.children) continue;
+ if (isEmptyChildDoc(childDoc)) continue;
+ state.dropped.push(`${path}.children.${name}`);
+ }
+
+ const out: ParkedNode = { v: iface.version, self, children };
+ return out;
+}
+
+export async function upgrade<A extends Park, C extends Json>(opts: {
+ current: Instance<Park>;
+ impl: Impl<A, C>;
+ iface: Iface<A, C>;
+ resources: Resources;
+}): Promise<UpgradeResult<A>> {
+ const parked = opts.current.park();
+ const state: ReconcileState = { dropped: [], missing: [], invalid: [], migrated: false };
+ const doc = reconcileNode(opts.iface, parked, "$", state);
+ if (state.dropped.length > 0 || state.missing.length > 0 || state.invalid.length > 0) {
+ return {
+ status: "blocked",
+ dropped: state.dropped,
+ missing: state.missing,
+ invalid: state.invalid,
+ doc: parked,
+ };
+ }
+ opts.current.dispose();
+ const instance = await boot(opts.impl, opts.iface, doc, opts.resources);
+ return { status: "ok", mode: state.migrated ? "migrated" : "silent", instance, doc };
+}
diff --git a/packages/core/test/engine.test.ts b/packages/core/test/engine.test.ts
index 3d8f3f79..a9290636 100644
--- a/packages/core/test/engine.test.ts
+++ b/packages/core/test/engine.test.ts
@@ -2291,8 +2291,16 @@ describe("ContextEngine LLM timeout / network interruption (PRN-012)", () => {
expect(nextRunTexts.join("\n")).not.toContain("[turn_aborted]");
// t1 already executed once during the failed attempts (side effect occurred); the
// transcript is plain text and is not dispatched again by either the retry or the next run.
- const content = await readFile(join(workspace, "chain.txt"), "utf8").catch(() => "");
- expect(content).toBe("x");
+ // Polled, not read once: t1 was dispatched by an attempt that then timed out, so the turn
+ // was abandoned with nobody awaiting the spawned process — on a slow-spawning host
+ // (Windows CI) it can still be in flight here. A second dispatch would settle on "xx",
+ // which this still catches.
+ const chainFile = join(workspace, "chain.txt");
+ const readChain = (): Promise<string> => readFile(chainFile, "utf8").catch(() => "");
+ for (let i = 0; i < 100 && (await readChain()) !== "x"; i++) {
+ await new Promise((resolve) => setTimeout(resolve, 20));
+ }
+ expect(await readChain()).toBe("x");
});
it("user abort after a failed retry: [turn_retried] un-nests into the [turn_aborted] flatten", async () => {
diff --git a/packages/core/tsup.config.ts b/packages/core/tsup.config.ts
index aef753ec..673bafea 100644
--- a/packages/core/tsup.config.ts
+++ b/packages/core/tsup.config.ts
@@ -10,6 +10,8 @@ export default defineConfig({
"src/omnimessage/markers/index.ts",
"src/interfaces.ts",
"src/state/model-catalog.ts",
+ // Hot-update kernel: zero-dependency subpath so web can bundle it directly.
+ "src/kernel/index.ts",
],
format: ["esm"],
target: "node20",
diff --git a/packages/desktop/scripts/stage.mjs b/packages/desktop/scripts/stage.mjs
index 7d7c8e36..5332c99e 100644
--- a/packages/desktop/scripts/stage.mjs
+++ b/packages/desktop/scripts/stage.mjs
@@ -88,7 +88,7 @@ for (const [what, file] of [
["server entry", path.join(serverPkg, "dist", "index.js")],
[
"CLI entry",
- path.join(appDir, "node_modules", "@prismshadow", "penguin-cli", "dist", "index.js"),
+ path.join(appDir, "node_modules", "@prismshadow", "penguin-cli", "dist", "penguin.js"),
],
["launcher generator (dist/launcher.js)", launcherModule],
]) {
diff --git a/packages/desktop/src/launcher.ts b/packages/desktop/src/launcher.ts
index a678a186..4f9ac951 100644
--- a/packages/desktop/src/launcher.ts
+++ b/packages/desktop/src/launcher.ts
@@ -11,7 +11,7 @@
*/
/** CLI entry inside the staged app directory (pnpm-deploy layout, asar off). */
-export const CLI_ENTRY_RELPATH = "node_modules/@prismshadow/penguin-cli/dist/index.js";
+export const CLI_ENTRY_RELPATH = "node_modules/@prismshadow/penguin-cli/dist/penguin.js";
/**
* Platform executable names, fixed by electron-builder.yml: productName PenguinHarness
@@ -94,7 +94,9 @@ export function appImageBootstrapJs(): string {
return (
'const path=require("path");' +
'const cli=path.join(path.dirname(process.execPath),"resources","app",' +
- '"node_modules","@prismshadow","penguin-cli","dist","index.js");' +
+ // Same entry CLI_ENTRY_RELPATH names — "index.js" here was left behind by b77ddea
+ // ("two bins, no router"), which renamed the CLI entry to penguin.js.
+ '"node_modules","@prismshadow","penguin-cli","dist","penguin.js");' +
"process.argv.splice(1,0,cli);" +
"import(cli).catch((err)=>{console.error(err);process.exit(1);});"
);
diff --git a/packages/desktop/src/main.ts b/packages/desktop/src/main.ts
index 9d3b25d1..fd44e4cc 100644
--- a/packages/desktop/src/main.ts
+++ b/packages/desktop/src/main.ts
@@ -1,6 +1,14 @@
/**
* Desktop shell main process.
*
+ * RUNTIME LAYER — MECHANISM ONLY (see packages/server/src/hmr/README.md). The
+ * shell boots and hosts; it does not implement product behavior. It is also
+ * the least updatable code in the system — a change here reaches users only
+ * through a new installer — so a capability that could instead be delivered
+ * by a platform push must be. A rejected example: adding a preload bridge so
+ * the web UI could open DevTools, when the shell's own View menu already
+ * does it.
+ *
* One window over the embedded server: fork penguin-server as a utilityProcess on the
* shared data root (PENGUIN_HOME or ~/.penguin/data), learn its port (last launch's when
* still free, so origin-scoped localStorage preferences survive restarts), and load
diff --git a/packages/desktop/test/launcher.test.ts b/packages/desktop/test/launcher.test.ts
index a30f2ebe..1f7fa7fb 100644
--- a/packages/desktop/test/launcher.test.ts
+++ b/packages/desktop/test/launcher.test.ts
@@ -89,7 +89,15 @@ describe("appImageBootstrapJs", () => {
it("resolves the CLI entry relative to process.execPath and fixes argv", () => {
expect(js).toContain("process.execPath");
expect(js).toContain('"resources","app"');
- expect(js).toContain('"penguin-cli","dist","index.js"');
+ // Derived from CLI_ENTRY_RELPATH rather than spelled out: this assertion used to pin
+ // "index.js", which is what let the AppImage wrapper keep pointing at an entry
+ // b77ddea ("two bins, no router") had already renamed.
+ expect(js).toContain(
+ CLI_ENTRY_RELPATH.split("/")
+ .slice(1)
+ .map((seg) => `"${seg}"`)
+ .join(","),
+ );
// node -e argv is [execPath, ...args]; the CLI slices argv from index 2, so the
// entry path must be spliced in at index 1.
expect(js).toContain("process.argv.splice(1,0,cli)");
diff --git a/packages/server/README.md b/packages/server/README.md
index 8e0737e4..b0f1736a 100644
--- a/packages/server/README.md
+++ b/packages/server/README.md
@@ -20,6 +20,7 @@ The full route tables and the SSE protocol are documented in the [Server API ref
| `PENGUIN_HOME` | Data root (shared with SDK/CLI) | `~/.penguin/data` |
| `PENGUIN_WEB_DB` | SQLite file path | `<root>/web.db` |
| `PENGUIN_WEB_DIST` | Front-end build dir (static hosting + SPA fallback when present) | `../web/dist`, or the bundled `web-dist/` in the npm package |
+| `PENGUIN_TRUST_PROXY` | Trust `x-forwarded-proto` for the hot-update network gate (`1` to enable) — only behind a reverse proxy that sets/strips the header itself | unset (untrusted) |
`.env` in the process cwd is loaded automatically.
diff --git a/packages/server/package.json b/packages/server/package.json
index 1fb1067a..ff034fe3 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -25,6 +25,10 @@
"./initial-password": {
"types": "./dist/initial-password.d.ts",
"import": "./dist/initial-password.js"
+ },
+ "./hmr/manifest": {
+ "types": "./dist/hmr/manifest.d.ts",
+ "import": "./dist/hmr/manifest.js"
}
},
"main": "./dist/index.js",
diff --git a/packages/server/src/api/types.ts b/packages/server/src/api/types.ts
index df107910..6ad5f1cb 100644
--- a/packages/server/src/api/types.ts
+++ b/packages/server/src/api/types.ts
@@ -1107,6 +1107,8 @@ export type ServerEvent =
| { type: "credentials_updated" }
/** Placeholder handshake on the user channel (reserved for automated task notifications). */
| { type: "hello" }
+ /** The served web assets were hot-swapped by a platform upgrade: clients reload to pick them up. */
+ | { type: "web_updated"; rev: string }
/** New session registered (pushed over the parent session's channel for subagent sessions): frontend refreshes the list in place. */
| {
type: "session_created";
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index ac938795..b99d79ea 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -83,6 +83,9 @@ import { TraceService } from "./services/trace-service.js";
import { UpdateCheckService } from "./services/update-check-service.js";
import { UsageService } from "./services/usage-service.js";
import { WorkspaceFilesService } from "./services/workspace-files-service.js";
+import { HmrHost } from "./hmr/host.js";
+import { hmrRoutes } from "./hmr/routes.js";
+import { platformHttpSeam } from "./hmr/http-seam.js";
import {
createPreviewTokenSigner,
hostOnly,
@@ -133,6 +136,8 @@ export interface AppDeps {
errors: ErrorRecorder;
/** Desktop mode (PENGUIN_DESKTOP_TOKEN): one-shot login + shutdown token holder; null outside desktop mode. */
desktop: DesktopService | null;
+ /** HMR host: loads/swaps/persists the platform and web bundles (park/boot kernel). */
+ hmr: HmrHost;
/** Request log output (minimal one-liner); tests inject a noop. */
log: (line: string) => void;
}
@@ -338,6 +343,7 @@ export function buildAppDeps(config: ServerConfig, overrides: BuildDepsOverrides
sessionSources,
errors,
desktop: config.desktopToken !== null ? new DesktopService(config.desktopToken) : null,
+ hmr: new HmrHost(config.root),
log,
};
}
@@ -422,6 +428,17 @@ export function createApp(deps: AppDeps): Hono<AppEnv> {
if (deps.desktop) {
app.route("/api/desktop", desktopRoutes(deps));
}
+ // Hot platform APIs authenticate themselves (local-agent Bearer token OR
+ // admin cookie session, see hot/routes.ts), so they mount outside the
+ // cookie-only authMiddleware below.
+ app.route("/api/hmr", hmrRoutes(deps));
+
+ // THE seam: from here down, every route is one the platform may take over by push. Mounted
+ // after /api/hmr (which stays runtime-owned — see http-seam.ts) and before both the auth
+ // gate and the built-in routes, so a pushed platform can add endpoints, replace existing
+ // ones, and decide its own authentication. Declining costs one property read and lands on
+ // the runtime's own routes below, which is what a platform without an `http` handler does.
+ app.use("*", platformHttpSeam(deps.hmr));
// Protected routes: cookie -> auth_session -> user.
const auth = authMiddleware(deps.authService);
@@ -457,10 +474,19 @@ export function createApp(deps: AppDeps): Hono<AppEnv> {
// SPA fallback cannot swallow it.
app.route("/preview", previewRoutes(deps));
- // Static hosting (production): serves the frontend build output when webDist exists, with SPA fallback to index.html.
- if (fs.existsSync(deps.config.webDist)) {
- registerStaticRoutes(app, deps.config.webDist);
- }
+ // Static hosting (production): serves the frontend build output with SPA fallback to
+ // index.html. The source resolves per request — the hot host can point it at a
+ // freshly pushed/restored web dist (in memory) without a restart; when nothing has
+ // been pushed, it falls back to the configured webDist. `hmr.ensure()` is awaited
+ // FIRST: web is only restored from harness.json as part of the platform+cli+web
+ // version's lazy first boot (see HmrHost.restore()), which nothing else here
+ // triggers — without this, a request landing right after a restart (before any
+ // /api/hmr/* call warms the host up) would miss a restored version entirely and
+ // silently fall back to the packaged webDist.
+ registerStaticRoutes(app, async () => {
+ await deps.hmr.ensure();
+ return deps.hmr.resolveWebSource() ?? { kind: "dir", dir: deps.config.webDist };
+ });
return app;
}
@@ -513,15 +539,46 @@ const CONTENT_TYPES: Record<string, string> = {
".woff2": "font/woff2",
};
-/** Minimal static file server (avoiding an extra dependency): path traversal protection + SPA fallback. */
-function registerStaticRoutes(app: Hono<AppEnv>, webDist: string): void {
+/** Where registerStaticRoutes reads a request's bytes from, resolved fresh per request. */
+export type WebSource = { kind: "mem"; files: Map<string, Buffer> } | { kind: "dir"; dir: string };
+
+/**
+ * Minimal static file server (avoiding an extra dependency): path traversal
+ * protection + SPA fallback, over either an in-memory pushed/restored dist (the
+ * hot host's primary path — no filesystem at all) or the packaged webDist
+ * directory on disk.
+ */
+function registerStaticRoutes(app: Hono<AppEnv>, resolveSource: () => Promise<WebSource>): void {
app.get("*", async (c) => {
const reqPath = decodeURIComponent(c.req.path);
if (reqPath.startsWith("/api/")) {
return c.json(errorBody("not_found", "Endpoint does not exist."), 404);
}
- const rel = reqPath.replace(/^\/+/, "");
- const resolved = path.resolve(webDist, rel === "" ? "index.html" : rel);
+ const rel = reqPath.replace(/^\/+/, "") || "index.html";
+ // Resolved per request: the hot host may retarget it between requests.
+ const source = await resolveSource();
+
+ if (source.kind === "mem") {
+ // No filesystem involved, so no traversal guard is needed: an unknown
+ // key simply isn't in the map, same as a missing file on disk.
+ const servedPath = source.files.has(rel) ? rel : "index.html"; // SPA fallback
+ const content = source.files.get(servedPath);
+ if (content === undefined) {
+ return c.json(errorBody("not_found", "Resource does not exist."), 404);
+ }
+ const type =
+ CONTENT_TYPES[path.extname(servedPath).toLowerCase()] ?? "application/octet-stream";
+ return new Response(new Uint8Array(content), {
+ status: 200,
+ headers: { "Content-Type": type },
+ });
+ }
+
+ const webDist = source.dir;
+ if (!fs.existsSync(webDist)) {
+ return c.json(errorBody("not_found", "Resource does not exist."), 404);
+ }
+ const resolved = path.resolve(webDist, rel);
// Guard against path traversal: once resolved, it must still be inside webDist.
const base = path.resolve(webDist);
const target =
diff --git a/packages/server/src/auth/middleware.ts b/packages/server/src/auth/middleware.ts
index ba39734b..d103d564 100644
--- a/packages/server/src/auth/middleware.ts
+++ b/packages/server/src/auth/middleware.ts
@@ -45,19 +45,34 @@ export function authMiddleware(auth: AuthService): MiddlewareHandler<AppEnv> {
const WRITE_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/**
+ * Content-Types write requests may carry. application/json is the default
+ * for the whole API; application/gzip and application/octet-stream are the
+ * hot-update web push's binary artifact transport (packages/server/src/hmr) —
+ * like application/json, neither is one of the three Content-Types an HTML
+ * form can forge (application/x-www-form-urlencoded, multipart/form-data,
+ * text/plain), so allowing them here does not reopen the CSRF gap below.
+ */
+const ALLOWED_WRITE_CONTENT_TYPES = [
+ "application/json",
+ "application/gzip",
+ "application/octet-stream",
+];
+
/**
* Content-Type defense for write requests: a write request with a Content-Type
- * other than application/json is rejected (a request with no Content-Type and an
- * empty body is let through — an HTML form always carries a form-type Content-Type).
+ * other than one of ALLOWED_WRITE_CONTENT_TYPES is rejected (a request with no
+ * Content-Type and an empty body is let through — an HTML form always carries
+ * a form-type Content-Type).
*/
export const jsonOnlyWrites: MiddlewareHandler = async (c, next) => {
if (WRITE_METHODS.has(c.req.method)) {
- const contentType = c.req.header("content-type");
- if (contentType && !contentType.toLowerCase().startsWith("application/json")) {
+ const contentType = c.req.header("content-type")?.toLowerCase();
+ if (contentType && !ALLOWED_WRITE_CONTENT_TYPES.some((t) => contentType.startsWith(t))) {
throw new HttpError(
415,
"unsupported_media_type",
- "Write requests only accept application/json.",
+ "Write requests only accept application/json (or, for the hot-update web push, a gzip artifact).",
);
}
}
diff --git a/packages/server/src/config.ts b/packages/server/src/config.ts
index 47eb66a6..1e1c29bc 100644
--- a/packages/server/src/config.ts
+++ b/packages/server/src/config.ts
@@ -65,6 +65,14 @@ export interface ServerConfig {
* it starts the server with PORT=0.
*/
portFile: string | null;
+ /**
+ * Trust `x-forwarded-proto` from the request (PENGUIN_TRUST_PROXY=1). Off by default:
+ * the header is caller-supplied, so on a non-loopback bind an untrusted caller could
+ * set it to `https` to walk through the hot-update network gate (hmr/routes.ts) while
+ * actually speaking plaintext. Enable this only behind a reverse proxy that terminates
+ * TLS and either sets or strips the header itself before it reaches this process.
+ */
+ trustProxy: boolean;
}
const DAY_MS = 24 * 60 * 60 * 1000;
@@ -102,7 +110,7 @@ function normalizePreviewOrigin(raw: string | undefined): string | null {
return url.origin;
}
-/** Parses server config from environment variables (PORT / HOST / PENGUIN_HOME / PENGUIN_WEB_DIST / PENGUIN_WEB_DB / PENGUIN_PREVIEW_ORIGIN / PENGUIN_SEED_ADMIN_PASSWORD / PENGUIN_DESKTOP_TOKEN / PENGUIN_PORT_FILE). */
+/** Parses server config from environment variables (PORT / HOST / PENGUIN_HOME / PENGUIN_WEB_DIST / PENGUIN_WEB_DB / PENGUIN_PREVIEW_ORIGIN / PENGUIN_SEED_ADMIN_PASSWORD / PENGUIN_DESKTOP_TOKEN / PENGUIN_PORT_FILE / PENGUIN_TRUST_PROXY). */
export function resolveServerConfig(env: NodeJS.ProcessEnv = process.env): ServerConfig {
const root = env.PENGUIN_HOME ?? resolveRoot();
// An empty PORT string is treated as unset (the common `.env` case of an empty
@@ -136,5 +144,6 @@ export function resolveServerConfig(env: NodeJS.ProcessEnv = process.env): Serve
authSessionRenewMs: 6 * DAY_MS,
desktopToken,
portFile: env.PENGUIN_PORT_FILE?.trim() || null,
+ trustProxy: env.PENGUIN_TRUST_PROXY === "1",
};
}
diff --git a/packages/server/src/hmr/README.md b/packages/server/src/hmr/README.md
new file mode 100644
index 00000000..98bbd423
--- /dev/null
+++ b/packages/server/src/hmr/README.md
@@ -0,0 +1,97 @@
+# The runtime layer — mechanism only
+
+This directory is the heart of the **runtime**: the layer that boots, transports, authenticates
+and hot-swaps everything else. Read this before changing anything here (or in
+`packages/desktop/`, or in core's environment tooling — the other runtime homes).
+
+## The four layers
+
+| Layer | Lives in | How it ships |
+| ------------ | ----------------------------------------------- | --------------------------------- |
+| **runtime** | `hmr/`, `packages/desktop/`, server transport | Rebuild + redeploy every install |
+| **platform** | `packages/server/src/platform/` | One HTTP push, seconds, no restart|
+| **workflow** | An agent's own folder | Installed/reloaded per agent |
+| **state** | Parked context documents / runtime resources | Rides across swaps, not restarts |
+
+## The rule
+
+**The runtime carries mechanism. It must not carry policy.**
+
+Mechanism is the machinery that is the same no matter what the product does: HTTP transport,
+SSE channels, authentication and the network gate, the kernel's park → migrate → boot swap,
+the resource registry, artifact storage and the atomic `harness.json` commit.
+
+Policy is everything a deployment might reasonably want to change: business APIs, what an agent
+sees, what a command does, how a capability behaves. Policy belongs in the **platform**, which is
+hot-swappable.
+
+## Why this matters more than it looks
+
+A runtime change costs a full artifact rebuild and a redeploy of **every installation** — and
+until that redeploy lands, the fix does not exist for users. A platform change is one HTTP push
+that takes seconds and needs no restart. Every behavior misfiled into the runtime is a fix that
+arrives weeks late.
+
+## The test to apply BEFORE editing runtime code
+
+1. Which layer owns this **behavior** in the four-layer model?
+2. Can it be delivered by a platform push instead? If yes, it must be.
+3. If it truly must live here, be able to say why in one sentence — "it is transport, security,
+ kernel, or a one-time primitive the hot layers build on".
+
+### The trap: "fix where the code is"
+
+The single most common way this rule gets broken is finding the line that misbehaves and editing
+it there. Today most behavior still physically lives in runtime files, so "fix at the fault site"
+lands in the runtime almost every time. **The fault site is not the owner.** Decide the layer
+first, then choose the edit site — not the reverse.
+
+### The enabler people forget
+
+Platform code executes **inside the server process**. Anything achievable in-process is therefore
+deliverable by a hot push, with zero runtime change — including effects that look like they
+belong to the shell, e.g. extending `process.env.PATH` so the agent's spawned shells inherit it.
+Before touching the runtime, ask whether a platform `boot()` could do the same thing.
+
+## The route table is not a runtime asset
+
+The runtime mounts ONE seam (`http-seam.ts`) before its own routes: the running platform gets
+first refusal on every request and answers `null` for the ones it does not own. A pushed
+platform can therefore add an endpoint, replace an existing one, or serve something else
+entirely — with no rebuild. The RPC dispatch route that used to stand in for this
+(`POST /api/hmr/platform/call`) is gone with it: it made *methods* pushable, which is not the
+same thing — a method has no path, no verb and no status code, and every client would have had
+to speak that envelope instead of the API it already speaks.
+
+Two boundaries keep it safe, and both are load-bearing:
+
+- **`/api/hmr/*` is never offered to the platform.** It is the channel a broken platform gets
+ replaced through; if a push could claim it, one bad push would lock the installation out for
+ good.
+- **A platform that throws does not fall through.** It claimed the request; running the
+ runtime's older handler instead would answer with semantics the caller was not promised. The
+ error surfaces as a 500.
+
+Streaming responses (SSE, long downloads) stay runtime-side: the handler returns a whole
+Response. That is a limit of today's seam, not a layer boundary.
+
+## Worked examples (all real, all from review)
+
+- **Opening DevTools from the web UI** — a preload bridge was added to the Electron shell so the
+ app could open DevTools. Rejected and reverted: the shell already ships
+ Ctrl+Shift+I, so the "capability" bought nothing and cost the window's zero-preload security
+ posture. An app-level convenience is never a reason to grow runtime surface.
+- **The agent could not find the `penguin` CLI** — the first fix injected `PATH` when the Electron
+ shell forked the server. Rejected: "what environment the agent sees" is policy. It belongs in
+ the platform's `boot()`, where it also reaches already-deployed machines through a normal push.
+- **New business APIs** — the HTTP seam offers every request to the booted platform, which
+ serves the ones it owns. This is the mechanism that keeps business APIs out of the runtime
+ permanently: a pushed bundle adds, changes or drops endpoints with no route change here.
+ Adding a route per business API is the anti-pattern it exists to prevent.
+
+## What does legitimately justify a runtime change
+
+Transport and security mechanism, kernel evolution, and one-time primitives the hot layers build
+on (for example: making a web push one gzip artifact served from memory, so pushes stop
+serializing on per-file disk writes). If a change is none of those, it is probably policy —
+put it in the platform.
diff --git a/packages/server/src/hmr/host.ts b/packages/server/src/hmr/host.ts
new file mode 100644
index 00000000..db150326
--- /dev/null
+++ b/packages/server/src/hmr/host.ts
@@ -0,0 +1,579 @@
+/**
+ * HmrHost: the runtime side of the stop-the-world hot-update protocol.
+ *
+ * RUNTIME LAYER — MECHANISM ONLY. Nothing here may encode what the product
+ * does; policy belongs in the platform, which ships by HTTP push in seconds
+ * while every line in this file costs a rebuild and a redeploy of every
+ * installation. Before adding anything, read ./README.md — in particular the
+ * "fix where the code is" trap, which is how this rule usually gets broken.
+ *
+ * The host owns everything that must survive a platform swap: the resource
+ * registry (live processes + their output buffers), the operation queue the
+ * HTTP layer gates on, and the committed on-disk state.
+ *
+ * Freeze semantics: requests arriving during a swap are ENQUEUED, not
+ * rejected — the HTTP layer awaits waitIdle() and proceeds once the swap
+ * completes, so a client never observes the stop-the-world window (it only
+ * sees latency). Concurrent upgrade requests serialize on the same queue.
+ *
+ * ONE atomic push, THREE independent artifacts: platform code, the CLI's
+ * command implementations, and the web dist are three separately compiled
+ * single-file products — there is no physical bundle that carries more than
+ * one of them — but they always move together in ONE request to POST
+ * /api/hmr/upgrade and land as ONE atomic version. The pushed `platform` and
+ * `cli` fields are each inline ESM source (delivered as bytes over HTTP —
+ * never a server-side path a remote client could not produce): `platform`
+ * must export `hotPlatform` (this runtime's business unit, imported and
+ * booted here); `cli` is never imported or executed by this process at all —
+ * it is only content-addressed into the store, for packages/cli's own thin
+ * loader to dynamically import later (see hmr/manifest.ts's
+ * resolveCliBundlePath). The web dist rides along in the same request as a
+ * { relPath: base64 } manifest. There is no way to update platform, cli, or
+ * web independently: doUpgradeAll only commits after the platform boots
+ * successfully AND the web manifest validates — a failure in either leaves
+ * the previous committed version untouched.
+ *
+ * Web dist pushes are held in memory (a relPath → bytes map), not written to
+ * disk file-by-file: a dist can be hundreds of small files, and syncing each
+ * one separately serializes on the destination filesystem's per-file
+ * overhead (observed as low as ~100KB/s writing 300 small files to a
+ * Windows/Defender-scanned disk). The pushed bytes are persisted as ONE
+ * artifact instead (see persistVersion).
+ *
+ * Persistence: artifacts are content-addressed under hmr/store/ (platform and
+ * cli each get their own subtree, since they are no longer the same file) and
+ * the whole version (platform + cli + web pointers) is promoted by ONE atomic
+ * rename of hmr/harness.json — committed only AFTER the live in-memory boot
+ * AND web install both succeeded, so a restart can never resume a version
+ * that failed to take effect. A restart resumes harness.json as one unit (see
+ * restore()): any failure — of any one of the three pieces, including a `cli`
+ * pointer whose file is missing — warns and falls back to the packaged
+ * default entirely (never a platform/web mismatch, never a brick). The store
+ * keeps at most STORE_KEEP versions (current + one rollback) per artifact.
+ *
+ * CODE persists; STATE does not. Only platform code, the CLI bundle, and the web
+ * dist are written to disk — never the parked context document a swap produces.
+ * A restart therefore always resumes the pushed CODE, but boots it against a
+ * FRESH initial context (bundle.context — see PlatformBundle below), not
+ * whatever state was live when the process last exited. This is deliberate: the
+ * live resources a parked doc's handles would reference (child processes, etc.)
+ * die with the process anyway, so a restored doc could only ever resume as
+ * "handles that fail to reclaim, nodes stuck degraded" — worse than a clean
+ * boot. State DOES survive a hot swap (park → migrate → boot, entirely
+ * in-memory, see kernel/upgrade.ts) — it just never survives a process restart.
+ *
+ * Reload is strictly request-driven: nothing watches, nothing auto-triggers.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import zlib from "node:zlib";
+import { pathToFileURL } from "node:url";
+import type { Instance, Json } from "@prismshadow/penguin-core/kernel";
+import { boot, initialDoc, upgrade } from "@prismshadow/penguin-core/kernel";
+import { HotResources } from "./resources.js";
+import type { Manifest } from "./manifest.js";
+import type { PlatformApi } from "../platform/platform.js";
+import { packagedPlatform } from "../platform/platform.js";
+import type { AnyIface, AnyImpl } from "@prismshadow/penguin-core/kernel";
+
+/**
+ * The contract every platform bundle must satisfy — packaged or pushed. `context` is the
+ * initial context a fresh boot creates the tree with (see initialDoc): the runtime never
+ * hardcodes a business value of its own, so this is where a business platform's own
+ * starting state belongs (see platform/platform.ts's packagedPlatform).
+ */
+export interface PlatformBundle {
+ id: string;
+ iface: AnyIface;
+ impl: AnyImpl;
+ context: Json;
+}
+
+/** Optional provenance recorded with a pushed version (never executed here). */
+export interface GitSource {
+ repo: string;
+ revision: string;
+}
+
+/**
+ * One atomic push: the platform bundle and the cli bundle (each inline ESM source,
+ * independent single-file artifacts) plus the web dist as a { relPath: base64 }
+ * manifest. All three travel in the SAME request — there is no partial-target
+ * upgrade.
+ */
+export interface UpgradeAllTarget {
+ platform: string;
+ cli: string;
+ web: Record<string, string>;
+ source?: GitSource;
+}
+
+export type UpgradeOutcome =
+ | {
+ status: "ok";
+ mode: "silent" | "migrated";
+ impl: string;
+ source: GitSource | null;
+ web: { rev: string };
+ /**
+ * Whether persistVersion's disk commit succeeded. The live swap always applies
+ * on `status: "ok"` regardless (see the module doc: "never brick"); when this is
+ * false the new version is running but NOT durable — a restart would resume the
+ * previously committed version instead. Callers (routes.ts, scripts/deploy.mjs)
+ * surface this so a filesystem failure during persistence is visible rather than
+ * indistinguishable from a fully-durable push.
+ */
+ persisted: boolean;
+ }
+ | { status: "blocked"; dropped: string[]; missing: string[]; invalid: string[] };
+
+/** How many past versions (platform bundle / cli bundle / web dist, each independently) the store keeps (current + one rollback). */
+const STORE_KEEP = 2;
+
+export class HmrHost {
+ readonly resources = new HotResources();
+
+ private instance: Instance<PlatformApi> | null = null;
+ private implId = packagedPlatform.id;
+ private readonly hmrDir: string;
+ private readonly storeDir: string;
+ private readonly manifestPath: string;
+ /**
+ * Single-flight guard for the first boot (see ensure()): every concurrent caller before the
+ * first successful boot awaits the SAME promise, so restore() and the packaged-default
+ * fallback can never run twice and race each other into assigning `this.instance` (a double
+ * boot, or a restored version clobbered by a concurrently-booted packaged default).
+ */
+ private initPromise: Promise<Instance<PlatformApi>> | null = null;
+ /** The freeze, as a queue: everything the HTTP layer gates on chains here. */
+ private opQueue: Promise<unknown> = Promise.resolve();
+
+ constructor(private readonly root: string) {
+ this.hmrDir = path.join(root, "hmr");
+ this.storeDir = path.join(this.hmrDir, "store");
+ this.manifestPath = path.join(this.hmrDir, "harness.json");
+ }
+
+ private warn(msg: string): void {
+ process.stderr.write(`[hmr] ${msg}\n`);
+ }
+
+ currentImplId(): string {
+ return this.implId;
+ }
+
+ /**
+ * The request gate: resolves once no swap is in flight. Requests arriving
+ * during an upgrade wait here — they observe latency, never an error.
+ */
+ waitIdle(): Promise<void> {
+ return this.opQueue.then(
+ () => undefined,
+ () => undefined,
+ );
+ }
+
+ /**
+ * Lazy first boot. Resumes the last committed version (platform + cli + web)
+ * from disk when present; otherwise boots the packaged platform v1 with a
+ * fresh document. Concurrent callers before the first boot completes share one
+ * in-flight promise (see `initPromise`) rather than each racing their own
+ * restore()/packaged-boot.
+ */
+ ensure(): Promise<Instance<PlatformApi>> {
+ if (this.instance !== null) return Promise.resolve(this.instance);
+ this.initPromise ??= this.initialize();
+ return this.initPromise;
+ }
+
+ /** Runs exactly once per process (guarded by `initPromise` in ensure()). */
+ private async initialize(): Promise<Instance<PlatformApi>> {
+ try {
+ await this.restore();
+ if (this.instance === null) {
+ const bundle = packagedPlatform;
+ this.instance = (await boot(
+ bundle.impl,
+ bundle.iface,
+ initialDoc(bundle.iface, bundle.context),
+ this.resources,
+ )) as Instance<PlatformApi>;
+ }
+ return this.instance;
+ } catch (err) {
+ // A failed init must not permanently strand ensure(): clear the guard so the next
+ // caller gets a fresh attempt instead of the same rejection forever.
+ this.initPromise = null;
+ throw err;
+ }
+ }
+
+ /**
+ * Resume from harness.json, as ONE unit: the platform bundle, the cli bundle's own
+ * existence, and the web artifact are all read and validated BEFORE anything is
+ * committed to `this.instance` / `this.webMem` — so a failure partway through (a
+ * pruned bundle, a missing web artifact, a missing cli artifact) never leaves
+ * platform and web resumed from different versions. The cli bundle is never
+ * imported here (this process never runs it — only packages/cli's own loader
+ * does); its file just has to exist, so a restore can never leave `cli.bundle`
+ * pointing at nothing. Any failure is non-fatal: it warns and leaves the runtime
+ * to boot the packaged default — a bad persisted version must never brick the
+ * runtime. Only ever called once (from initialize(), itself single-flighted by
+ * ensure()'s `initPromise`).
+ *
+ * Boots the restored bundle against its OWN fresh initial context (bundle.context),
+ * not a resumed state — state is never written to disk (see the module doc), so a
+ * restart always resumes the pushed CODE with a clean slate, never last run's doc.
+ */
+ private async restore(): Promise<void> {
+ let manifest: Manifest;
+ try {
+ manifest = JSON.parse(await fsp.readFile(this.manifestPath, "utf8")) as Manifest;
+ } catch {
+ return; // nothing committed yet
+ }
+ if (manifest.platform === undefined && manifest.web === undefined) {
+ return; // nothing committed yet
+ }
+ try {
+ if (manifest.platform === undefined) {
+ throw new Error("harness.json has no `platform` entry");
+ }
+ if (manifest.cli === undefined) {
+ throw new Error("harness.json has no `cli` entry");
+ }
+ if (manifest.web === undefined) {
+ throw new Error("harness.json has no `web` entry");
+ }
+ const cliPath = path.join(this.hmrDir, manifest.cli.bundle);
+ if (!fs.existsSync(cliPath)) {
+ throw new Error(`cli bundle '${manifest.cli.bundle}' does not exist`);
+ }
+ const bundle = await this.importBundleFile(path.join(this.hmrDir, manifest.platform.bundle));
+ const gz = await fsp.readFile(path.join(this.hmrDir, manifest.web.manifest));
+ const webMem = filesMapFromGzip(gz);
+ // Everything validated: commit together. boot() runs last so a boot failure
+ // leaves nothing partially applied either.
+ const instance = (await boot(
+ bundle.impl,
+ bundle.iface,
+ initialDoc(bundle.iface, bundle.context),
+ this.resources,
+ )) as Instance<PlatformApi>;
+ this.instance = instance;
+ this.implId = bundle.id;
+ this.webMem = webMem;
+ } catch (err) {
+ this.warn(
+ `persisted version failed to restore (platform+cli+web are committed as one unit); ` +
+ `using the packaged default: ${errMsg(err)}`,
+ );
+ }
+ }
+
+ /** Strictly request-driven; serialized on the op queue (never auto-triggered). */
+ upgradeAll(target: UpgradeAllTarget): Promise<UpgradeOutcome> {
+ const run = this.opQueue.then(() => this.doUpgradeAll(target));
+ // The queue must survive a failed upgrade: swallow for chaining only.
+ this.opQueue = run.then(
+ () => undefined,
+ () => undefined,
+ );
+ return run;
+ }
+
+ private async doUpgradeAll(target: UpgradeAllTarget): Promise<UpgradeOutcome> {
+ const current = await this.ensure();
+
+ if (typeof target.web["index.html"] !== "string") {
+ throw new Error("web dist manifest has no index.html");
+ }
+ const webMem = new Map<string, Buffer>();
+ for (const [rel, b64] of Object.entries(target.web)) {
+ if (!isSafeRelPath(rel)) throw new Error(`unsafe path in web dist manifest: ${rel}`);
+ webMem.set(rel, Buffer.from(b64, "base64"));
+ }
+
+ const platformPath = await this.writeInlinePlatformBundle(target.platform);
+ const bundle = await this.importBundleFile(platformPath);
+ const source = target.source ?? null;
+
+ const result = await upgrade({
+ current,
+ impl: bundle.impl,
+ iface: bundle.iface,
+ resources: this.resources,
+ });
+ if (result.status === "blocked") {
+ // Old instance + web untouched; the doc + path lists are the input for the
+ // upper upgrade-ladder rungs (auto-upgrader / agent / human).
+ return {
+ status: "blocked",
+ dropped: result.dropped,
+ missing: result.missing,
+ invalid: result.invalid,
+ };
+ }
+
+ // Boot succeeded: commit web to memory too, then persist platform + cli + web
+ // as one atomic version — never a platform that's newer (or older) than the
+ // 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.webMem = webMem;
+
+ const digest = filesDigest(target.web);
+ const gz = zlib.gzipSync(Buffer.from(JSON.stringify({ files: target.web })));
+ const persisted = await this.persistVersion(
+ target.platform,
+ target.cli,
+ gz,
+ digest.slice(0, 16),
+ );
+
+ return {
+ status: "ok",
+ mode: result.mode,
+ impl: bundle.id,
+ source,
+ web: { rev: digest.slice(0, 12) },
+ persisted,
+ };
+ }
+
+ /** Layer (a) core: import one JS file, cache-busted so re-imports load fresh code. */
+ private async importBundleFile(file: string): Promise<PlatformBundle> {
+ const resolved = path.resolve(file);
+ if (!fs.existsSync(resolved)) throw new Error(`bundle file '${file}' does not exist`);
+ const url = `${pathToFileURL(resolved).href}?v=${Date.now()}`;
+ const mod = (await import(url)) as { hotPlatform?: PlatformBundle };
+ if (mod.hotPlatform === undefined) {
+ throw new Error(`${file} does not export 'hotPlatform'`);
+ }
+ if (mod.hotPlatform.context === undefined) {
+ // Every bundle carries its own initial context now (see PlatformBundle above):
+ // state is never persisted, so a boot with no context to fall back on would have
+ // nothing to boot a fresh tree with — reject it the same way a missing
+ // `hotPlatform` export is rejected, rather than booting with `undefined`.
+ throw new Error(`${file}'s 'hotPlatform' has no 'context'`);
+ }
+ return mod.hotPlatform;
+ }
+
+ /**
+ * 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.
+ */
+ private async writeInlinePlatformBundle(content: string): Promise<string> {
+ const dir = path.join(this.hmrDir, "uploads");
+ await fsp.mkdir(dir, { recursive: true });
+ const file = path.join(dir, `platform-${sha1(content).slice(0, 16)}.mjs`);
+ await fsp.writeFile(file, content, "utf8");
+ return file;
+ }
+
+ // -- Web platform (the frontend package's built dist) ---------------------
+
+ /**
+ * The pushed web dist held in memory (relPath → bytes) — always installed
+ * together with a platform + cli version (see doUpgradeAll); never written or
+ * read file-by-file (see persistVersion). Null before anything has ever been
+ * pushed or restored.
+ */
+ private webMem: Map<string, Buffer> | null = null;
+
+ /** Static hosting's resolution: an in-memory pushed/restored dist, or null (the caller falls back to the configured webDist). */
+ resolveWebSource(): { kind: "mem"; files: Map<string, Buffer> } | null {
+ return this.webMem !== null ? { kind: "mem", files: this.webMem } : null;
+ }
+
+ // -- 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
+ * 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
+ * manifest keys.
+ *
+ * Returns whether the commit succeeded — the caller surfaces this to clients
+ * (`persisted` in UpgradeOutcome) so a live swap that could not be written to disk
+ * is visibly at risk of reverting on the next restart, rather than silently ok.
+ */
+ private async persistVersion(
+ platformContent: string,
+ cliContent: string,
+ webGz: Buffer,
+ webSha: string,
+ ): 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");
+
+ const cliSha = sha1(cliContent).slice(0, 16);
+ const cliDir = path.join(this.storeDir, "cli");
+ await fsp.mkdir(cliDir, { recursive: true });
+ await fsp.writeFile(path.join(cliDir, `${cliSha}.mjs`), cliContent, "utf8");
+
+ const webDir = path.join(this.storeDir, "web");
+ await fsp.mkdir(webDir, { recursive: true });
+ await fsp.writeFile(path.join(webDir, `${webSha}.webz`), webGz);
+
+ await this.commitManifest(() => ({
+ platform: { bundle: `store/platform/${platformSha}.mjs` },
+ cli: { bundle: `store/cli/${cliSha}.mjs` },
+ web: { manifest: `store/web/${webSha}.webz` },
+ }));
+ return true;
+ } catch (err) {
+ this.warn(`update not persisted (filesystem unavailable?): ${errMsg(err)}`);
+ return false;
+ }
+ }
+
+ /** Writes and atomically replaces harness.json (the single commit point for a whole version). */
+ private async commitManifest(next: () => Manifest): Promise<void> {
+ await fsp.mkdir(this.hmrDir, { recursive: true });
+ const manifest = next();
+ const tmp = `${this.manifestPath}.${process.pid}.tmp`;
+ await fsp.writeFile(tmp, JSON.stringify(manifest, null, 2));
+ // Atomic within the same directory/filesystem (libuv maps this to
+ // MoveFileEx REPLACE_EXISTING on Windows, rename(2) on POSIX).
+ await fsp.rename(tmp, this.manifestPath);
+ await this.pruneStore(manifest);
+ }
+
+ /**
+ * Store GC: keep at most STORE_KEEP versions — the committed one is always
+ * kept, the rest by recency. Best-effort; ordered after the manifest flip so
+ * nothing referenced can be pruned. `platform`, `cli`, and `web` are three
+ * independent subtrees now (no shared file to piggyback a sweep on), so each
+ * gets its own pass.
+ */
+ private async pruneStore(manifest: Manifest): Promise<void> {
+ const keepNewest = async (
+ dir: string,
+ keys: (name: string) => string | null,
+ referenced: string | null,
+ remove: (key: string) => Promise<void>,
+ ): Promise<void> => {
+ let names: string[];
+ try {
+ names = await fsp.readdir(dir);
+ } catch {
+ return;
+ }
+ const byKey = new Map<string, number>();
+ for (const name of names) {
+ const key = keys(name);
+ if (key === null) continue;
+ try {
+ const mtime = (await fsp.stat(path.join(dir, name))).mtimeMs;
+ byKey.set(key, Math.max(byKey.get(key) ?? 0, mtime));
+ } catch {
+ // raced with a concurrent prune
+ }
+ }
+ const ranked = [...byKey.entries()].sort((a, b) => b[1] - a[1]).map(([k]) => k);
+ const kept = new Set(ranked.slice(0, STORE_KEEP));
+ if (referenced !== null) kept.add(referenced);
+ for (const key of ranked) {
+ if (!kept.has(key)) await remove(key).catch(() => undefined);
+ }
+ };
+
+ const platformDir = path.join(this.storeDir, "platform");
+ const platformBundleRef = manifest.platform?.bundle.match(/([0-9a-f]+)\.mjs$/)?.[1] ?? null;
+ await keepNewest(
+ platformDir,
+ (name) => /^([0-9a-f]+)\.mjs$/.exec(name)?.[1] ?? null,
+ platformBundleRef,
+ (sha) => fsp.rm(path.join(platformDir, `${sha}.mjs`), { force: true }),
+ );
+
+ const cliDir = path.join(this.storeDir, "cli");
+ const cliRef = manifest.cli?.bundle.match(/([0-9a-f]+)\.mjs$/)?.[1] ?? null;
+ await keepNewest(
+ cliDir,
+ (name) => /^([0-9a-f]+)\.mjs$/.exec(name)?.[1] ?? null,
+ cliRef,
+ (sha) => fsp.rm(path.join(cliDir, `${sha}.mjs`), { force: true }),
+ );
+
+ const webDir = path.join(this.storeDir, "web");
+ const webRef = manifest.web?.manifest.match(/([0-9a-f]+)\.webz$/)?.[1] ?? null;
+ await keepNewest(
+ webDir,
+ (name) => /^([0-9a-f]+)\.webz$/.exec(name)?.[1] ?? null,
+ webRef,
+ (sha) => fsp.rm(path.join(webDir, `${sha}.webz`), { force: true }),
+ );
+ }
+
+ /** Process-exit sweep only; never part of an upgrade. */
+ dispose(): void {
+ this.instance?.dispose();
+ this.instance = null;
+ this.resources.disposeAll();
+ }
+}
+
+function errMsg(err: unknown): string {
+ return err instanceof Error ? err.message : String(err);
+}
+
+function sha1(content: string): string {
+ return crypto.createHash("sha1").update(content).digest("hex");
+}
+
+/** Content hash over a web dist manifest: stable across re-pushes of identical content. */
+function filesDigest(files: Record<string, string>): string {
+ const hash = crypto.createHash("sha1");
+ for (const rel of Object.keys(files).sort()) hash.update(rel).update("\0").update(files[rel]!);
+ return hash.digest("hex");
+}
+
+/** No absolute paths, no `..` segments — the map is looked up by exact key, but a malformed key must never be stored. */
+function isSafeRelPath(rel: string): boolean {
+ if (rel === "" || rel.startsWith("/") || rel.includes("\\")) return false;
+ return rel.split("/").every((seg) => seg !== "" && seg !== "." && seg !== "..");
+}
+
+/** Decodes a gzip(JSON.stringify({ files })) artifact into its manifest. */
+function filesFromGzip(gz: Buffer): Record<string, string> {
+ let parsed: { files?: unknown };
+ try {
+ parsed = JSON.parse(zlib.gunzipSync(gz).toString("utf8")) as { files?: unknown };
+ } catch (err) {
+ throw new Error(`invalid gzip web dist artifact: ${errMsg(err)}`);
+ }
+ if (typeof parsed.files !== "object" || parsed.files === null) {
+ throw new Error("gzip web dist artifact has no `files`");
+ }
+ return parsed.files as Record<string, string>;
+}
+
+/** Decodes a gzip artifact straight into the in-memory relPath → bytes map (the restore path). */
+function filesMapFromGzip(gz: Buffer): Map<string, Buffer> {
+ const files = filesFromGzip(gz);
+ const mem = new Map<string, Buffer>();
+ for (const [rel, b64] of Object.entries(files)) {
+ if (!isSafeRelPath(rel)) throw new Error(`unsafe path in web dist manifest: ${rel}`);
+ mem.set(rel, Buffer.from(b64, "base64"));
+ }
+ return mem;
+}
diff --git a/packages/server/src/hmr/http-seam.ts b/packages/server/src/hmr/http-seam.ts
new file mode 100644
index 00000000..60bc82a4
--- /dev/null
+++ b/packages/server/src/hmr/http-seam.ts
@@ -0,0 +1,92 @@
+/**
+ * The platform's HTTP seam — the one place the runtime hands a request over.
+ *
+ * Without this, the route table is a runtime asset: adding or fixing an endpoint means
+ * rebuilding and redeploying every installation, which is exactly what the hot channel exists
+ * to avoid. The RPC dispatch route that used to stand in for this (`/api/hmr/platform/call`,
+ * removed with the seam) only made METHODS pushable; a method is not a route — no path, no
+ * verb, no status, no headers — and every client would have had to speak that envelope instead
+ * of the API it already speaks.
+ *
+ * So: the running platform gets first refusal on every request, and answers `null` for the ones
+ * it does not own. A pushed platform can therefore add a route, replace one, or serve something
+ * entirely different, with no runtime change at all.
+ *
+ * Two boundaries make that safe:
+ *
+ * - **`/api/hmr/*` is never offered.** It is the channel a broken platform is replaced through;
+ * if a push could claim it, one bad push would lock the installation out permanently.
+ * - **A platform that throws does not fall through.** It claimed the request by throwing rather
+ * than declining, and quietly running the runtime's older handler instead would answer with
+ * different semantics than the caller was promised. The error surfaces as a 500.
+ *
+ * Streaming responses (SSE, long downloads) stay runtime-side for now: the handler returns a
+ * whole Response, which is enough for the request/response API surface and keeps the contract
+ * one function wide.
+ */
+import type { MiddlewareHandler } from "hono";
+import type { HmrHost } from "./host.js";
+
+/** Prefix the runtime keeps for itself, whatever the platform says. */
+const RESERVED_PREFIX = "/api/hmr";
+
+/**
+ * A platform that wants to serve HTTP exposes this. Optional on purpose: a platform pushed
+ * before the seam existed simply has no `http`, and everything falls through to the runtime's
+ * own routes, so old bundles keep working.
+ *
+ * Deliberately NOT in the iface's `methods` list: that list is the allow-list for the JSON-RPC
+ * dispatch route, and a Request/Response pair is not Json. This is an in-process call on the
+ * booted implementation object, like `terminals()`.
+ */
+export interface PlatformHttp {
+ http?(request: Request): Promise<Response | null> | Response | null;
+}
+
+/**
+ * Offers each request to the running platform before the runtime's own routes see it.
+ * `hmr.ensure()` returns the already-booted instance after the first call, so this costs a
+ * property read per request once the platform is up.
+ */
+export function platformHttpSeam(hmr: HmrHost): MiddlewareHandler {
+ return async (c, next) => {
+ if (c.req.path.startsWith(RESERVED_PREFIX)) return next();
+ // Wait out any in-flight swap FIRST, same as /api/hmr/*'s own gate (routes.ts): the
+ // kernel's upgrade() disposes the old tree before it awaits the new one's boot, and for
+ // that whole window `hmr.ensure()` still resolves synchronously to the OLD instance —
+ // it only reassigns once the swap is done. Without this wait, a request landing in that
+ // window would be handed to an already-disposed tree instead of observing the freeze as
+ // latency (see host.ts's module doc: "a client never observes the stop-the-world
+ // window").
+ await hmr.waitIdle();
+ let handler: PlatformHttp["http"];
+ try {
+ const instance = await hmr.ensure();
+ handler = (instance.api as PlatformHttp).http?.bind(instance.api);
+ } catch {
+ // The platform cannot boot: the runtime's own routes are the fallback, and the
+ // upgrade channel above is still reachable to push a working one.
+ return next();
+ }
+ if (!handler) return next();
+
+ let response: Response | null;
+ try {
+ response = await handler(c.req.raw);
+ } catch (err) {
+ return c.json(
+ {
+ error: {
+ code: "platform_error",
+ message: `The platform failed to handle ${c.req.method} ${c.req.path}: ${
+ err instanceof Error ? err.message : String(err)
+ }`,
+ },
+ },
+ 500,
+ );
+ }
+ if (response === null) return next();
+ return response;
+ };
+}
diff --git a/packages/server/src/hmr/manifest.ts b/packages/server/src/hmr/manifest.ts
new file mode 100644
index 00000000..ca097628
--- /dev/null
+++ b/packages/server/src/hmr/manifest.ts
@@ -0,0 +1,76 @@
+/**
+ * The harness.json shape (`<root>/hmr/harness.json`) and pure readers over it.
+ *
+ * Split out of host.ts so a reader never needs a running HmrHost: `penguin` is a
+ * separate, short-lived process per invocation (see packages/cli/src/index.ts) — it
+ * has no host instance to ask, only the data root's own harness.json on disk.
+ * `resolveCliBundlePath` is that reader: a plain disk read, no HTTP, no boot, no
+ * in-memory state.
+ *
+ * ONE atomic version, THREE independent artifacts: `platform`, `cli`, and `web` are
+ * always written together by HmrHost's single merged upgrade path (see host.ts's
+ * persistVersion), but each is content-addressed and stored on its own — a push to
+ * POST /api/hmr/upgrade carries `platform` and `cli` as two separate single-file ESM
+ * sources, so `cli.bundle` points at its OWN file, a different sha from
+ * `platform.bundle`. They are read back together too (see host.ts's restore): a
+ * partial record (e.g. `platform` present but `web` or `cli` missing) is never
+ * trusted — the whole version is treated as absent instead of partially applied.
+ */
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * The committed on-disk record: a runtime restart resumes exactly this CODE (platform,
+ * cli, web). It carries no STATE — a restart always boots the resumed platform bundle
+ * against its own fresh initial context (bundle.context, see host.ts's PlatformBundle),
+ * never a document parked from a previous run (see host.ts's module doc for why: a
+ * parked doc's live-resource handles die with the process anyway, so resuming one could
+ * only ever produce handles that fail to reclaim). Paths are relative to hmrDir
+ * (`<root>/hmr`).
+ */
+export interface Manifest {
+ platform?: { bundle: string };
+ /**
+ * The CLI's own bundle pointer — its own independent file (a different sha from
+ * `platform.bundle`; the two are separately compiled artifacts), kept as its own
+ * field so a reader that only wants "which bundle does the CLI load right now"
+ * never has to reach into `platform` at all.
+ */
+ cli?: { bundle: string };
+ /** One gzip(JSON.stringify({ files })) artifact, restored straight into memory. */
+ web?: { manifest: string };
+}
+
+/** Reads and parses `<root>/hmr/harness.json`; null when missing or corrupt (nothing committed yet). */
+export async function readManifest(root: string): Promise<Manifest | null> {
+ try {
+ const raw = await fsp.readFile(path.join(root, "hmr", "harness.json"), "utf8");
+ return JSON.parse(raw) as Manifest;
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * Resolves the current CLI bundle's absolute path from a data root, or null when
+ * nothing has been pushed yet: a fresh root, a missing/corrupt manifest, no `cli`
+ * entry, a `cli.bundle` that isn't a non-empty string (e.g. `{"cli":{}}` — a
+ * hand-edited or truncated harness.json), a path that resolves outside `<root>/hmr/`
+ * (defense in depth: `manifest.cli.bundle` is trusted content today, written only by
+ * this same process's persistVersion, but a reader must never let a malformed or
+ * malicious manifest value walk it out of the store directory via `..` segments), or
+ * a referenced file that no longer exists (e.g. pruned from the store — see host.ts's
+ * pruneStore). A null return means "use the packaged default" to every caller;
+ * nothing here ever throws for an ordinary unconfigured or malformed root.
+ */
+export async function resolveCliBundlePath(root: string): Promise<string | null> {
+ const manifest = await readManifest(root);
+ const bundle = manifest?.cli?.bundle;
+ if (typeof bundle !== "string" || bundle.length === 0) return null;
+ const hmrDir = path.join(root, "hmr");
+ const abs = path.resolve(hmrDir, bundle);
+ const withinHmrDir = abs === hmrDir || abs.startsWith(hmrDir + path.sep);
+ if (!withinHmrDir) return null;
+ return fs.existsSync(abs) ? abs : null;
+}
diff --git a/packages/server/src/hmr/resources.ts b/packages/server/src/hmr/resources.ts
new file mode 100644
index 00000000..a0ed6f4f
--- /dev/null
+++ b/packages/server/src/hmr/resources.ts
@@ -0,0 +1,46 @@
+/**
+ * Runtime-side live resources for the hot platform tree — the registry, and nothing
+ * about what a resource IS.
+ *
+ * The linear-state rule for live resources: a pty/child process never enters the parked
+ * context document — it lives here, the document only carries its handle id, and boot
+ * claims it back. Because the registry sits outside the reloadable tree, a platform swap
+ * never interrupts the resource and never loses output produced during the freeze window.
+ *
+ * Kind-agnostic on purpose (see ./README.md): a registrant supplies its own disposer, so
+ * a pushed platform can introduce a resource type this file has never heard of and still
+ * have it shut down at process exit. Spawning anything — a shell, a pty, a connection —
+ * is the platform's business and lives there.
+ */
+import type { Resources } from "@prismshadow/penguin-core/kernel";
+
+export class HotResources implements Resources {
+ private readonly map = new Map<string, { resource: unknown; dispose?: () => void }>();
+
+ register(id: string, resource: unknown, dispose?: () => void): void {
+ this.map.set(id, { resource, dispose });
+ }
+
+ claim<T = unknown>(id: string): T | undefined {
+ return this.map.get(id)?.resource as T | undefined;
+ }
+
+ release(id: string): void {
+ this.map.delete(id);
+ }
+
+ /**
+ * Process-exit sweep: run every registered disposer. Not part of any upgrade path —
+ * resources are meant to outlive swaps. A throwing disposer must not strand the rest.
+ */
+ disposeAll(): void {
+ for (const entry of this.map.values()) {
+ try {
+ entry.dispose?.();
+ } catch {
+ // Best-effort: the process is going away regardless.
+ }
+ }
+ this.map.clear();
+ }
+}
diff --git a/packages/server/src/hmr/routes.ts b/packages/server/src/hmr/routes.ts
new file mode 100644
index 00000000..34f10de9
--- /dev/null
+++ b/packages/server/src/hmr/routes.ts
@@ -0,0 +1,172 @@
+/**
+ * /api/hmr/*: the hot-update surface.
+ *
+ * The gate middleware is the runtime half of the stop-the-world protocol:
+ * requests arriving during a swap are ENQUEUED on the host's operation queue
+ * (awaiting waitIdle), never rejected — a client only ever observes latency,
+ * not the freeze. The routes are runtime code: they orchestrate through the
+ * platform api, so they survive impl swaps unchanged.
+ *
+ * RUNTIME LAYER — MECHANISM ONLY (see ./README.md). A new business API must NOT
+ * become a route here. It is served by the platform itself, through the HTTP
+ * seam (../hmr/http-seam.ts) that offers every request to the booted platform
+ * before the runtime's own routes see it — a real route with its own path,
+ * verb and status, rather than an RPC envelope clients would have to learn.
+ *
+ * What remains here is the upgrade channel and the status it needs, which is
+ * the one thing the platform is never offered: it is how a broken platform
+ * gets replaced.
+ */
+import zlib from "node:zlib";
+import { Hono } from "hono";
+import type { AppDeps } from "../app.js";
+import { authMiddleware } from "../auth/middleware.js";
+import type { AppEnv } from "../auth/middleware.js";
+import { HttpError } from "../http/errors.js";
+
+/** Bind addresses considered safe by default; anything else needs HTTPS. */
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
+
+export function hmrRoutes(deps: AppDeps): Hono<AppEnv> {
+ const routes = new Hono<AppEnv>();
+ const hmr = deps.hmr;
+ // Mounted BEFORE the global cookie-auth middleware (see app.ts): this gate
+ // does its own auth (admin cookie only — see the network gate above for the
+ // other half) rather than relying on the generic middleware being mounted
+ // later.
+ const cookieAuth = authMiddleware(deps.authService);
+
+ routes.use("*", async (c, next) => {
+ // Dangerous-network off: hot APIs load and run code, so on a non-loopback
+ // bind (e.g. 0.0.0.0) without HTTPS they answer 403. There is no override
+ // via the request itself — see the header note below.
+ if (!LOOPBACK_HOSTS.has(deps.config.host.toLowerCase())) {
+ // `x-forwarded-proto` is caller-supplied and UNTRUSTED by default: anyone who can
+ // reach this bind at all can set it to `https` and walk straight through this gate
+ // while actually speaking plaintext HTTP (the gate exists precisely for the case
+ // where the caller is not a trusted party). Only a request's own URL scheme (real
+ // TLS terminated by this process) counts unless the deployment explicitly says a
+ // reverse proxy is in front and strips/overwrites the header itself
+ // (PENGUIN_TRUST_PROXY=1 / config.trustProxy) — the same opt-in a real proxy setup
+ // requires anyway.
+ const proto = deps.config.trustProxy
+ ? (c.req.header("x-forwarded-proto") ?? new URL(c.req.url).protocol.replace(":", ""))
+ : new URL(c.req.url).protocol.replace(":", "");
+ if (proto !== "https") {
+ throw new HttpError(
+ 403,
+ "hmr_disabled",
+ "Hot platform APIs are disabled on a non-loopback bind without HTTPS. " +
+ "Serve over HTTPS to enable them.",
+ );
+ }
+ }
+ const gated = async (): Promise<void> => {
+ // The upgrade endpoint enqueues internally; everything else waits out
+ // any in-flight swap here (unobservable freeze: latency, not errors).
+ if (!c.req.path.endsWith("/upgrade")) await hmr.waitIdle();
+ await next();
+ };
+ // Admin cookie session only. There used to be a second credential here — a
+ // per-boot Bearer token published to $PENGUIN_HOME/hmr/api.json — for local
+ // tools to call in without a browser session. It was removed: it ran as
+ // plaintext on disk, readable by anything running as the same OS user
+ // (including an agent's own shell/exec tools, which inherit that user and
+ // PENGUIN_HOME), and it was admin-equivalent — making it the single
+ // plaintext admin-equivalent secret on disk, i.e. the vulnerability itself.
+ // Session tokens and passwords are hashed at rest (auth/service.ts); a local
+ // caller now authenticates the same way an operator does: log in with the
+ // admin password and present the resulting cookie.
+ return cookieAuth(c, async () => {
+ if (!c.get("user").isAdmin) {
+ throw new HttpError(403, "forbidden", "Hot platform APIs are admin-only.");
+ }
+ await gated();
+ });
+ });
+
+ /**
+ * THE ONE upgrade endpoint: platform + cli + web move together, atomically —
+ * there is no route that updates any of the three alone (see host.ts's module
+ * doc). Content-Type application/gzip or application/octet-stream; the raw body
+ * is gzip(JSON.stringify({ platform, cli, web: { files }, source? })):
+ * - `platform` — the platform's single-file JS ESM source, inline (works over
+ * HTTP alone, remote runtimes included); it must export `hotPlatform`.
+ * - `cli` — the CLI's own single-file JS ESM source, inline, a SEPARATE
+ * artifact from `platform`; the server never imports or runs it, only
+ * content-addresses it into the store for packages/cli's own loader.
+ * - `web.files` — a { relPath: base64 } manifest of the built web dist.
+ * - `source?` — optional provenance (repo + revision), recorded but not run.
+ * The server boots the platform AND installs the web dist in memory first;
+ * only once BOTH succeed does it persist the version — platform, cli, and web
+ * together (one atomic harness.json rename — see host.ts's persistVersion). A
+ * boot failure or a bad web manifest leaves the previously committed version
+ * untouched.
+ */
+ routes.post("/upgrade", async (c) => {
+ const contentType = (c.req.header("content-type") ?? "").split(";")[0]!.trim().toLowerCase();
+ if (contentType !== "application/gzip" && contentType !== "application/octet-stream") {
+ throw new HttpError(
+ 400,
+ "bad_request",
+ "expected a gzip(JSON.stringify({ platform, cli, web })) body " +
+ "(Content-Type application/gzip or application/octet-stream)",
+ );
+ }
+ let payload: {
+ platform?: string;
+ cli?: string;
+ web?: { files?: Record<string, string> };
+ source?: { repo: string; revision: string };
+ };
+ try {
+ const gz = Buffer.from(await c.req.arrayBuffer());
+ payload = JSON.parse(zlib.gunzipSync(gz).toString("utf8"));
+ } catch (err) {
+ throw new HttpError(
+ 400,
+ "bad_request",
+ `invalid gzip upgrade payload: ${err instanceof Error ? err.message : String(err)}`,
+ );
+ }
+ if (typeof payload.platform !== "string") {
+ throw new HttpError(400, "bad_request", "payload has no `platform` (string)");
+ }
+ if (typeof payload.cli !== "string") {
+ throw new HttpError(400, "bad_request", "payload has no `cli` (string)");
+ }
+ if (typeof payload.web?.files !== "object" || payload.web.files === null) {
+ throw new HttpError(
+ 400,
+ "bad_request",
+ "payload has no `web.files` (a { relPath: base64 } map)",
+ );
+ }
+ let outcome;
+ try {
+ outcome = await hmr.upgradeAll({
+ platform: payload.platform,
+ cli: payload.cli,
+ web: payload.web.files,
+ ...(payload.source ? { source: payload.source } : {}),
+ });
+ } catch (err) {
+ throw new HttpError(400, "bad_request", err instanceof Error ? err.message : String(err));
+ }
+ // Live clients (browser tabs AND the desktop window) reload to pick up the
+ // new web assets once a version actually lands.
+ if (outcome.status === "ok") {
+ deps.channels.broadcast(
+ "user:",
+ { type: "web_updated", rev: outcome.web.rev },
+ "server_event",
+ );
+ }
+ // Blocked is a first-class outcome, not an HTTP error: the body carries
+ // status + the dropped/missing/invalid paths (input for the upper
+ // upgrade-ladder rungs), so clients keep one parsing path.
+ return c.json(outcome);
+ });
+
+ return routes;
+}
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
index 5c6ebebc..d78f7990 100644
--- a/packages/server/src/index.ts
+++ b/packages/server/src/index.ts
@@ -177,6 +177,7 @@ async function shutdown(signal: string, exitCode = 0): Promise<void> {
console.log(`Received ${signal}, shutting down…`);
deps.scheduler.stop();
await deps.manager.shutdown(5000);
+ deps.hmr.dispose();
deps.channels.dispose();
ipv6Loopback?.close();
server.close(() => {
diff --git a/packages/server/src/platform/entry.ts b/packages/server/src/platform/entry.ts
new file mode 100644
index 00000000..cd9ae06c
--- /dev/null
+++ b/packages/server/src/platform/entry.ts
@@ -0,0 +1,21 @@
+/**
+ * The server package's platform export: the entry the dev watch-and-push loop
+ * (`scripts/deploy.mjs`) compiles to one file and pushes to a waiting
+ * runtime as this build's business platform.
+ *
+ * `platform`, `cli` (packages/cli/src/index.ts), and the web dist are three
+ * independently compiled artifacts pushed together in ONE atomic request to
+ * POST /api/hmr/upgrade — see packages/server/src/hmr/host.ts's module doc for
+ * why "one atomic push" does not mean "one physical bundle". This file's only
+ * job is to re-export the package's hot-swappable surface as `hotPlatform`
+ * (`{ id, iface, impl }`, the contract HmrHost.doUpgradeAll loads and boots) —
+ * it carries no `cli` export, and none is expected of it.
+ *
+ * It is NOT a tsup entry point (tsup only bundles this package's own dist
+ * surface: index/api/lock/initial-password/hmr/manifest), so it adds nothing
+ * to the shipped server build; only esbuild (in deploy.mjs) compiles it,
+ * straight from source, never through the published dist. As more of the
+ * package's services move under the platform tree, this entry stays the
+ * same — the watcher just recompiles a bigger graph.
+ */
+export { packagedPlatform as hotPlatform } from "./platform.js";
diff --git a/packages/server/src/platform/platform.ts b/packages/server/src/platform/platform.ts
new file mode 100644
index 00000000..73167128
--- /dev/null
+++ b/packages/server/src/platform/platform.ts
@@ -0,0 +1,65 @@
+/**
+ * THE platform: the one hot-swappable unit this build of the server packages.
+ *
+ * The repo carries exactly one platform — versions exist BETWEEN deployments
+ * (this packaged build vs the next bundle pushed over HTTP), not as parallel
+ * files. When a future build changes the context shape, it bumps `version`
+ * and ships the migrator alongside the new schema; the previous shape lives
+ * only in already-parked documents out in the world.
+ *
+ * PLATFORM LAYER — WHERE POLICY BELONGS. Anything a deployment might want to
+ * change (business APIs, what an agent sees, how a capability behaves) goes
+ * here rather than in the runtime, and reaches installations by one HTTP push
+ * instead of a rebuild. Worth remembering when something looks like it must
+ * live in the shell: this code runs INSIDE the server process, so in-process
+ * effects (e.g. extending process.env for the shells agents spawn) are
+ * deliverable from boot() with no runtime change. See ../hmr/README.md.
+ *
+ * This packaged default is deliberately a bare stub: the runtime (HmrHost,
+ * routes.ts) is mechanism only, and carries no business methods of its own.
+ * A real business platform is pushed over HTTP and serves its own HTTP through
+ * the seam in ../hmr/http-seam.ts: it sees every request before the runtime's
+ * own routes do and answers null for the ones it does not own, so adding or
+ * changing an endpoint needs no runtime change.
+ */
+import type { Impl, Json, Park } from "@prismshadow/penguin-core/kernel";
+import { defineIface, schema, type } from "@prismshadow/penguin-core/kernel";
+import type { PlatformBundle } from "../hmr/host.js";
+
+export interface PlatformApi extends Park {
+ info(): Json;
+}
+
+export type PlatformCtx = { motd: string };
+
+export const PlatformIface = defineIface<PlatformApi, PlatformCtx>({
+ name: "platform",
+ version: 1,
+ context: schema<PlatformCtx>(type({ motd: "string" })),
+ methods: ["park", "info"],
+});
+
+export const platformImpl: Impl<PlatformApi, PlatformCtx> = {
+ create(_ctx, context) {
+ return {
+ park: () => ({ motd: context.motd }),
+ info: () => ({
+ impl: "packaged",
+ ifaceVersion: PlatformIface.version,
+ motd: context.motd,
+ }),
+ };
+ },
+};
+
+/**
+ * The packaged bundle the runtime boots when nothing has been pushed yet — code AND its
+ * initial context together, so the runtime never hardcodes a business value of its own
+ * (see hmr/host.ts's PlatformBundle: every bundle, packaged or pushed, carries `context`).
+ */
+export const packagedPlatform: PlatformBundle = {
+ id: "packaged",
+ iface: PlatformIface,
+ impl: platformImpl,
+ context: { motd: "hello from the penguin hot platform" } satisfies PlatformCtx,
+};
diff --git a/packages/server/src/runtime/channel.ts b/packages/server/src/runtime/channel.ts
index 252d6a59..39568f3a 100644
--- a/packages/server/src/runtime/channel.ts
+++ b/packages/server/src/runtime/channel.ts
@@ -192,6 +192,18 @@ export class ChannelHub {
return this.channels.get(key);
}
+ /**
+ * Publishes to every live channel whose key starts with `prefix` — global
+ * notices (e.g. `user:` for "the web assets were hot-swapped, reload").
+ * Only reaches channels that exist (i.e. someone connected at least once);
+ * that is the right scope for a notice that only matters to live clients.
+ */
+ broadcast(prefix: string, data: unknown, event?: string): void {
+ for (const [key, ch] of this.channels) {
+ if (key.startsWith(prefix)) ch.publish(data, event);
+ }
+ }
+
/** Reclaim idle channels (skips active Sessions: no reclaim even without a publish while awaiting approval); `now` is injectable for tests. */
sweep(now: number = Date.now()): void {
for (const [key, ch] of this.channels) {
diff --git a/packages/server/test/fixtures/platform-http.bundle.mjs b/packages/server/test/fixtures/platform-http.bundle.mjs
new file mode 100644
index 00000000..47a9efa6
--- /dev/null
+++ b/packages/server/test/fixtures/platform-http.bundle.mjs
@@ -0,0 +1,80 @@
+/**
+ * Test fixture: a pushed platform that SERVES HTTP.
+ *
+ * The point of the seam it exercises: this bundle adds `/api/demo/ping`, replaces the
+ * runtime's `/api/version`, and tries (and fails) to claim `/api/hmr/platform` — none of which
+ * the runtime knows anything about. It arrives as bytes over one HTTP push, with no rebuild.
+ *
+ * Standalone on purpose, like the other fixtures: no kernel or arktype imports, only what an
+ * independently built artifact can rely on.
+ */
+
+const ok = (value) => ({ ok: true, value });
+const fail = (p) => ({
+ ok: false,
+ dropped: p.dropped ?? [],
+ missing: p.missing ?? [],
+ invalid: p.invalid ?? [],
+});
+
+// The schema contract is structural: strictParse + describe (see kernel/schema.ts) — the
+// status route reads the description, so a fixture missing it 500s there.
+const anySchema = {
+ strictParse(doc) {
+ return ok(doc === undefined ? {} : doc);
+ },
+ describe: () => ({ kind: "any" }),
+};
+
+const iface = {
+ kind: "iface",
+ name: "platform",
+ version: 1,
+ context: anySchema,
+ methods: ["park", "info"],
+ children: {},
+ migrations: {},
+};
+
+const impl = {
+ create(_ctx, context) {
+ return {
+ park: () => context,
+ info: () => ({ impl: "http-fixture" }),
+
+ /**
+ * The seam: answer the requests this platform owns, decline everything else with null.
+ * Not listed in `methods` — that list is the JSON-RPC allow-list, and a Request is not
+ * Json; the runtime calls this directly on the booted object.
+ */
+ http(request) {
+ const url = new URL(request.url);
+ if (url.pathname === "/api/demo/ping") {
+ // A route the runtime has never heard of, shipped by push alone.
+ return new Response(JSON.stringify({ pong: true, from: "pushed-platform" }), {
+ status: 200,
+ headers: { "content-type": "application/json" },
+ });
+ }
+ if (url.pathname === "/api/version") {
+ // Replacing an existing runtime route, which is the other half of the point.
+ return new Response(JSON.stringify({ version: "from-platform" }), {
+ status: 200,
+ headers: { "content-type": "application/json" },
+ });
+ }
+ if (url.pathname === "/api/demo/boom") {
+ throw new Error("deliberate platform failure");
+ }
+ if (url.pathname.startsWith("/api/hmr")) {
+ // Never reached: the runtime keeps its upgrade channel, so a push cannot lock the
+ // installation out of being replaced.
+ return new Response("hijacked", { status: 418 });
+ }
+ return null; // not mine — the runtime's own routes answer
+ },
+ };
+ },
+};
+
+export const hotPlatform = { id: "http-fixture", iface, impl, context: {} };
diff --git a/packages/server/test/helpers.ts b/packages/server/test/helpers.ts
index 12e092b7..112b8949 100644
--- a/packages/server/test/helpers.ts
+++ b/packages/server/test/helpers.ts
@@ -47,6 +47,7 @@ export function testConfig(root: string): ServerConfig {
authSessionRenewMs: 6 * DAY_MS,
desktopToken: null,
portFile: null,
+ trustProxy: false,
};
}
@@ -81,6 +82,7 @@ export async function createTestApp(options: TestAppOptions = {}): Promise<TestA
root,
adminPassword,
cleanup: async () => {
+ deps.hmr.dispose();
deps.channels.dispose();
deps.db.close();
// maxRetries: Windows can report ENOTEMPTY/EBUSY while handles from the test's own
diff --git a/packages/server/test/hmr-host.test.ts b/packages/server/test/hmr-host.test.ts
new file mode 100644
index 00000000..2e6eadba
--- /dev/null
+++ b/packages/server/test/hmr-host.test.ts
@@ -0,0 +1,301 @@
+/**
+ * HmrHost mechanism tests that don't fit the seam's own file: the single-flight first
+ * boot, "code persists across a restart, state does not" (see host.ts's module doc),
+ * a bundle missing `context` being rejected the same way a missing `hotPlatform` is,
+ * and the durability flag an upgrade's HTTP response carries.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import zlib from "node:zlib";
+import { afterEach, describe, expect, it } from "vitest";
+import type { Hono } from "hono";
+import type { AppEnv } from "../src/auth/middleware.js";
+import { HmrHost } from "../src/hmr/host.js";
+import { apiClient, createTestApp, loginAdmin } from "./helpers.js";
+import type { TestApp } from "./helpers.js";
+
+/** Minimal but content-distinguishable platform bundle, inline (see hmr-http-seam.test.ts). */
+function platformServing(paths: string[], id: string): string {
+ return `
+const anySchema = {
+ strictParse: (doc) => ({ ok: true, value: doc === undefined ? {} : doc }),
+ describe: () => ({ kind: "any" }),
+};
+const iface = {
+ kind: "iface",
+ name: "platform",
+ version: 1,
+ context: anySchema,
+ methods: ["park", "info"],
+ children: {},
+ migrations: {},
+};
+const SERVED = ${JSON.stringify(paths)};
+const impl = {
+ create(_ctx, context) {
+ return {
+ park: () => context,
+ info: () => ({ impl: ${JSON.stringify(id)} }),
+ http(request) {
+ const { pathname } = new URL(request.url);
+ if (!SERVED.includes(pathname)) return null;
+ return new Response(JSON.stringify({ servedBy: ${JSON.stringify(id)}, pathname }), {
+ status: 200,
+ headers: { "content-type": "application/json" },
+ });
+ },
+ };
+ },
+};
+export const hotPlatform = { id: ${JSON.stringify(id)}, iface, impl, context: {} };
+`;
+}
+
+/**
+ * A platform whose context carries one number, mutable at runtime through
+ * `POST /api/demo/bump` (in memory only — nothing here ever touches disk itself). Used
+ * to tell "the swap's live (migrated-forward) state" apart from "the bundle's own
+ * initial context": a live push carries the PRIOR instance's doc forward through
+ * migration (kernel/upgrade.ts) — it never resets to this bundle's `context` — so the
+ * schema below marks any doc that didn't already look like this shape with a sentinel
+ * (-1), distinguishable from both the bundle's declared initial value and anything a
+ * live mutation could produce. A restart, never a live push, is what boots fresh
+ * against `context`.
+ */
+function platformWithState(id: string, initialN: number): string {
+ return `
+const anySchema = {
+ strictParse: (doc) => ({
+ ok: true,
+ value: doc && typeof doc.n === "number" ? doc : { n: -1 },
+ }),
+ describe: () => ({ kind: "any" }),
+};
+const iface = {
+ kind: "iface",
+ name: "platform",
+ version: 1,
+ context: anySchema,
+ methods: ["park", "info"],
+ children: {},
+ migrations: {},
+};
+const impl = {
+ create(_ctx, context) {
+ return {
+ park: () => context,
+ info: () => ({ impl: ${JSON.stringify(id)}, n: context.n }),
+ http(request) {
+ const { pathname } = new URL(request.url);
+ if (pathname !== "/api/demo/bump") return null;
+ context.n += 1;
+ return new Response(JSON.stringify({ n: context.n }), {
+ status: 200,
+ headers: { "content-type": "application/json" },
+ });
+ },
+ };
+ },
+};
+export const hotPlatform = { id: ${JSON.stringify(id)}, iface, impl, context: { n: ${initialN} } };
+`;
+}
+
+/** Same shape as platformServing, except its export has no `context` at all. */
+function platformMissingContext(id: string): string {
+ return `
+const anySchema = {
+ strictParse: (doc) => ({ ok: true, value: doc === undefined ? {} : doc }),
+ describe: () => ({ kind: "any" }),
+};
+const iface = {
+ kind: "iface",
+ name: "platform",
+ version: 1,
+ context: anySchema,
+ methods: ["park", "info"],
+ children: {},
+ migrations: {},
+};
+const impl = {
+ create(_ctx, context) {
+ return { park: () => context, info: () => ({ impl: ${JSON.stringify(id)} }) };
+ },
+};
+export const hotPlatform = { id: ${JSON.stringify(id)}, iface, impl };
+`;
+}
+
+const MINIMAL_CLI = "export async function cli(argv) { return 0; }\n";
+const MINIMAL_WEB = { "index.html": Buffer.from("<html>host</html>").toString("base64") };
+
+async function pushPlatform(app: Hono<AppEnv>, cookie: string, platform: string) {
+ const gz = zlib.gzipSync(
+ Buffer.from(JSON.stringify({ platform, cli: MINIMAL_CLI, web: { files: MINIMAL_WEB } })),
+ );
+ return app.request("/api/hmr/upgrade", {
+ method: "POST",
+ headers: { cookie, "content-type": "application/gzip" },
+ body: gz,
+ });
+}
+
+describe("HmrHost.ensure(): single-flight first boot", () => {
+ let t: TestApp | undefined;
+ let freshRoot: string | undefined;
+
+ afterEach(async () => {
+ if (t) await t.cleanup();
+ if (freshRoot) await fs.rm(freshRoot, { recursive: true, force: true });
+ t = undefined;
+ freshRoot = undefined;
+ });
+
+ it("concurrent ensure() calls on a fresh host share one init and all resolve to the restored (pushed) instance", async () => {
+ // Push a version and let it persist, then tear down that host WITHOUT touching the
+ // root directory — simulating a restart of the same data root.
+ t = await createTestApp();
+ const cookie = (await loginAdmin(t.app)).cookie;
+ const push = await pushPlatform(t.app, cookie, platformServing(["/api/demo/ping"], "pushed"));
+ expect(push.status).toBe(200);
+ expect(((await push.json()) as { persisted: boolean }).persisted).toBe(true);
+
+ const root = t.root;
+ freshRoot = root;
+ t.deps.hmr.dispose();
+ t.deps.channels.dispose();
+ t.deps.db.close();
+ t = undefined; // already torn down by hand; skip the normal cleanup() (it would rm(root))
+
+ // A brand-new HmrHost over the SAME root: nothing has called ensure() yet.
+ const fresh = new HmrHost(root);
+ try {
+ const [a, b, c] = await Promise.all([fresh.ensure(), fresh.ensure(), fresh.ensure()]);
+ // Same object: only one restore()/boot ever ran.
+ expect(a).toBe(b);
+ expect(b).toBe(c);
+ const info = (a.api as unknown as { info(): { impl: string } }).info();
+ expect(info.impl).toBe("pushed");
+ } finally {
+ fresh.dispose();
+ }
+ });
+});
+
+describe("HmrHost: code persists across a restart, state does not", () => {
+ let t: TestApp | undefined;
+ let freshRoot: string | undefined;
+
+ afterEach(async () => {
+ if (t) await t.cleanup();
+ if (freshRoot) await fs.rm(freshRoot, { recursive: true, force: true });
+ t = undefined;
+ freshRoot = undefined;
+ });
+
+ it("a pushed version's harness.json platform entry carries no `park`, and the store writes no .park.json", async () => {
+ t = await createTestApp();
+ const cookie = (await loginAdmin(t.app)).cookie;
+ const push = await pushPlatform(t.app, cookie, platformWithState("stateful", 5));
+ expect(push.status).toBe(200);
+ expect(((await push.json()) as { persisted: boolean }).persisted).toBe(true);
+
+ const manifest = JSON.parse(
+ await fs.readFile(path.join(t.root, "hmr", "harness.json"), "utf8"),
+ ) as { platform: Record<string, unknown> };
+ expect(Object.keys(manifest.platform)).toEqual(["bundle"]);
+
+ const storeFiles = await fs.readdir(path.join(t.root, "hmr", "store", "platform"));
+ expect(storeFiles.some((name) => name.endsWith(".park.json"))).toBe(false);
+ });
+
+ it("a restart resumes the pushed CODE against a FRESH initial context, not the live-mutated state", async () => {
+ t = await createTestApp();
+ const cookie = (await loginAdmin(t.app)).cookie;
+ const api = apiClient(t.app, cookie);
+ const push = await pushPlatform(t.app, cookie, platformWithState("stateful", 5));
+ expect(push.status).toBe(200);
+
+ // The live push migrated FORWARD from whatever was already running (the packaged
+ // default, which has no `n`) — never reset to the pushed bundle's `context` — so it
+ // starts at the schema's sentinel (-1), not 5. Bumping it twice makes doubly sure a
+ // restore couldn't accidentally land on either the sentinel or the bumped value.
+ const live = await t.deps.hmr.ensure();
+ expect((live.api as unknown as { info(): { n: number } }).info().n).toBe(-1);
+ expect((await api.post("/api/demo/bump")).status).toBe(200);
+ expect((await api.post("/api/demo/bump")).status).toBe(200);
+ expect((live.api as unknown as { info(): { n: number } }).info().n).toBe(1);
+
+ const root = t.root;
+ freshRoot = root;
+ t.deps.hmr.dispose();
+ t.deps.channels.dispose();
+ t.deps.db.close();
+ t = undefined; // torn down by hand; skip cleanup() (it would rm(root))
+
+ const fresh = new HmrHost(root);
+ try {
+ const instance = await fresh.ensure();
+ const restored = (instance.api as unknown as { info(): { impl: string; n: number } }).info();
+ // CODE resumed (the pushed impl id)...
+ expect(restored.impl).toBe("stateful");
+ // ...but state did not: it's the bundle's fresh initial context (5), never the
+ // migrated-forward-then-bumped live value (1) that was running when the process
+ // "exited".
+ expect(restored.n).toBe(5);
+ } finally {
+ fresh.dispose();
+ }
+ });
+});
+
+describe("upgrade: a bundle missing `context` is rejected", () => {
+ let t: TestApp;
+ afterEach(async () => {
+ await t.cleanup();
+ });
+
+ it("400s with a message naming `context`, the same rejection path as a missing `hotPlatform`", async () => {
+ t = await createTestApp();
+ const cookie = (await loginAdmin(t.app)).cookie;
+ const res = await pushPlatform(t.app, cookie, platformMissingContext("no-context"));
+ expect(res.status).toBe(400);
+ const body = (await res.json()) as { error: { message: string } };
+ expect(body.error.message).toContain("context");
+ });
+});
+
+describe("upgrade outcome: persisted flag", () => {
+ let t: TestApp;
+ afterEach(async () => {
+ await t.cleanup();
+ });
+
+ it("a persistVersion failure still applies the live swap but marks persisted: false", async () => {
+ t = await createTestApp();
+ 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");
+
+ const res = await pushPlatform(
+ t.app,
+ cookie,
+ platformServing(["/api/demo/ping"], "unpersisted"),
+ );
+ expect(res.status).toBe(200);
+ const outcome = (await res.json()) as { status: string; persisted: boolean };
+ expect(outcome.status).toBe("ok");
+ expect(outcome.persisted).toBe(false);
+
+ // The live swap took effect regardless — "never brick" holds even when disk fails.
+ const ping = await api.get("/api/demo/ping");
+ expect(ping.status).toBe(200);
+ expect(await ping.json()).toEqual({ servedBy: "unpersisted", pathname: "/api/demo/ping" });
+ });
+});
diff --git a/packages/server/test/hmr-http-seam.test.ts b/packages/server/test/hmr-http-seam.test.ts
new file mode 100644
index 00000000..5bf85905
--- /dev/null
+++ b/packages/server/test/hmr-http-seam.test.ts
@@ -0,0 +1,304 @@
+/**
+ * The platform's HTTP seam: routes ship by push, not by rebuild.
+ *
+ * Until this existed, the route table was a runtime asset — every new or changed endpoint cost
+ * a rebuild and a redeploy of every installation, which is the thing the hot channel exists to
+ * avoid. These tests push a platform that serves HTTP and check the properties that make the
+ * seam usable and safe: a new route appears, an existing one can be replaced, the upgrade
+ * channel cannot be claimed, and a platform that throws does not silently fall through to a
+ * different implementation. The last block walks a whole lifecycle — the set of reachable
+ * endpoints following the pushes that add and remove them.
+ */
+import zlib from "node:zlib";
+import fs from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { Hono } from "hono";
+import type { AppEnv } from "../src/auth/middleware.js";
+import { apiClient, createTestApp, loginAdmin } from "./helpers.js";
+import type { TestApp } from "./helpers.js";
+
+const HTTP_BUNDLE_FILE = fileURLToPath(
+ new URL("./fixtures/platform-http.bundle.mjs", import.meta.url),
+);
+
+const MINIMAL_CLI = "export async function cli(argv) { return 0; }\n";
+const MINIMAL_WEB = { "index.html": Buffer.from("<html>seam</html>").toString("base64") };
+
+async function pushPlatform(app: Hono<AppEnv>, cookie: string, platform: string) {
+ const gz = zlib.gzipSync(
+ Buffer.from(JSON.stringify({ platform, cli: MINIMAL_CLI, web: { files: MINIMAL_WEB } })),
+ );
+ return app.request("/api/hmr/upgrade", {
+ method: "POST",
+ headers: { cookie, "content-type": "application/gzip" },
+ body: gz,
+ });
+}
+
+describe("platform HTTP seam", () => {
+ let t: TestApp;
+ let cookie: string;
+ let api: ReturnType<typeof apiClient>;
+ let bundle: string;
+
+ beforeEach(async () => {
+ t = await createTestApp();
+ const admin = await loginAdmin(t.app);
+ cookie = admin.cookie;
+ api = apiClient(t.app, cookie);
+ bundle = await fs.readFile(HTTP_BUNDLE_FILE, "utf8");
+ });
+ afterEach(async () => {
+ await t.cleanup();
+ });
+
+ it("a pushed platform adds a route the runtime has never heard of", async () => {
+ // Before: nothing serves it, and no rebuild is going to happen in between.
+ expect((await api.get("/api/demo/ping")).status).toBe(404);
+
+ expect((await pushPlatform(t.app, cookie, bundle)).status).toBe(200);
+
+ const res = await api.get("/api/demo/ping");
+ expect(res.status).toBe(200);
+ expect(await res.json()).toEqual({ pong: true, from: "pushed-platform" });
+ });
+
+ it("…and can replace one the runtime already serves", async () => {
+ const before = (await (await api.get("/api/version")).json()) as { version: string };
+ expect(before.version).not.toBe("from-platform");
+
+ await pushPlatform(t.app, cookie, bundle);
+
+ expect(await (await api.get("/api/version")).json()).toEqual({ version: "from-platform" });
+ });
+
+ it("routes the platform declines still reach the runtime's own", async () => {
+ await pushPlatform(t.app, cookie, bundle);
+ const me = await api.get("/api/me");
+ expect(me.status).toBe(200);
+ expect(((await me.json()) as { user: { userId: string } }).user.userId).toBe("admin");
+ });
+
+ it("cannot claim the upgrade channel — one bad push must not lock the box out", async () => {
+ await pushPlatform(t.app, cookie, bundle);
+ // The fixture answers 418 for anything under /api/hmr; the runtime never offers
+ // it, so an unrouted path there is the runtime's own 404 rather than the
+ // platform's 418 — proof the claim was refused, not merely unmatched.
+ const probe = await api.get("/api/hmr/upgrade");
+ expect(probe.status).not.toBe(418);
+ expect(probe.status).toBe(404);
+ // …and the channel still accepts the next push, which is the property that matters.
+ expect((await pushPlatform(t.app, cookie, bundle)).status).toBe(200);
+ });
+
+ it("a platform that throws answers 500 instead of quietly falling through", async () => {
+ await pushPlatform(t.app, cookie, bundle);
+ const res = await api.get("/api/demo/boom");
+ expect(res.status).toBe(500);
+ const body = (await res.json()) as { error: { code: string; message: string } };
+ expect(body.error.code).toBe("platform_error");
+ expect(body.error.message).toContain("deliberate platform failure");
+ });
+
+ it("a platform with no http handler leaves every runtime route as it was", async () => {
+ // The packaged stub has none: this is the state every installation starts in, and the
+ // state an older pushed bundle stays in.
+ expect((await api.get("/api/me")).status).toBe(200);
+ expect((await api.get("/api/demo/ping")).status).toBe(404);
+ });
+});
+
+/**
+ * A platform bundle that serves exactly `paths` and declines everything else. Built inline
+ * rather than read from a fixture file so the ONLY difference between the versions pushed
+ * below is the route list — which is the thing under test.
+ */
+function platformServing(paths: string[], id = "route-set"): string {
+ return `
+const anySchema = {
+ strictParse: (doc) => ({ ok: true, value: doc === undefined ? {} : doc }),
+ describe: () => ({ kind: "any" }),
+};
+const iface = {
+ kind: "iface",
+ name: "platform",
+ version: 1,
+ context: anySchema,
+ methods: ["park", "info"],
+ children: {},
+ migrations: {},
+};
+const SERVED = ${JSON.stringify(paths)};
+const impl = {
+ create(_ctx, context) {
+ return {
+ park: () => context,
+ info: () => ({ impl: ${JSON.stringify(id)} }),
+ http(request) {
+ const { pathname } = new URL(request.url);
+ if (!SERVED.includes(pathname)) return null;
+ return new Response(JSON.stringify({ servedBy: ${JSON.stringify(id)}, pathname }), {
+ status: 200,
+ headers: { "content-type": "application/json" },
+ });
+ },
+ };
+ },
+};
+export const hotPlatform = { id: ${JSON.stringify(id)}, iface, impl, context: {} };
+`;
+}
+
+describe("platform HTTP seam: the reachable API changes with each push", () => {
+ let t: TestApp;
+ let cookie: string;
+ let api: ReturnType<typeof apiClient>;
+
+ beforeEach(async () => {
+ t = await createTestApp();
+ const admin = await loginAdmin(t.app);
+ cookie = admin.cookie;
+ api = apiClient(t.app, cookie);
+ });
+ afterEach(async () => {
+ await t.cleanup();
+ });
+
+ /** Which of the probed endpoints answer, and who answered them. */
+ const reachable = async (paths: string[]): Promise<Record<string, string>> => {
+ const out: Record<string, string> = {};
+ for (const path of paths) {
+ const res = await api.get(path);
+ out[path] =
+ res.status === 404
+ ? "404"
+ : `${res.status} ${((await res.json()) as { servedBy?: string }).servedBy ?? "runtime"}`;
+ }
+ return out;
+ };
+
+ const PROBED = ["/api/demo/ping", "/api/demo/pong", "/api/me"];
+
+ it("adding, swapping and removing routes changes what the server answers", async () => {
+ // Baseline: the runtime knows /api/me and nothing about the demo endpoints.
+ expect(await reachable(PROBED)).toEqual({
+ "/api/demo/ping": "404",
+ "/api/demo/pong": "404",
+ "/api/me": "200 runtime",
+ });
+
+ // Push #1 ADDS one endpoint.
+ expect(
+ (await pushPlatform(t.app, cookie, platformServing(["/api/demo/ping"], "v1"))).status,
+ ).toBe(200);
+ expect(await reachable(PROBED)).toEqual({
+ "/api/demo/ping": "200 v1",
+ "/api/demo/pong": "404",
+ "/api/me": "200 runtime",
+ });
+
+ // Push #2 SWAPS the route set: the first endpoint is gone, a different one appears.
+ expect(
+ (await pushPlatform(t.app, cookie, platformServing(["/api/demo/pong"], "v2"))).status,
+ ).toBe(200);
+ expect(await reachable(PROBED)).toEqual({
+ "/api/demo/ping": "404",
+ "/api/demo/pong": "200 v2",
+ "/api/me": "200 runtime",
+ });
+
+ // Push #3 REMOVES both: the API is back to exactly what the runtime serves.
+ expect((await pushPlatform(t.app, cookie, platformServing([], "v3"))).status).toBe(200);
+ expect(await reachable(PROBED)).toEqual({
+ "/api/demo/ping": "404",
+ "/api/demo/pong": "404",
+ "/api/me": "200 runtime",
+ });
+ });
+
+ it("a route the platform takes over goes back to the runtime's own when it stops serving it", async () => {
+ const runtimeVersion = (await (await api.get("/api/version")).json()) as { version: string };
+
+ await pushPlatform(t.app, cookie, platformServing(["/api/version"], "takeover"));
+ expect(await (await api.get("/api/version")).json()).toMatchObject({ servedBy: "takeover" });
+
+ await pushPlatform(t.app, cookie, platformServing([], "released"));
+ expect(await (await api.get("/api/version")).json()).toEqual(runtimeVersion);
+ });
+});
+
+/**
+ * Same shape as `platformServing`, except `create()` awaits `delayMs` before returning —
+ * so the window between the kernel disposing the OLD instance and this NEW one finishing
+ * boot (see kernel/upgrade.ts: dispose-then-await-boot) is wide enough to race a request
+ * against on purpose.
+ */
+function platformSlow(delayMs: number, id: string): string {
+ return `
+const anySchema = {
+ strictParse: (doc) => ({ ok: true, value: doc === undefined ? {} : doc }),
+ describe: () => ({ kind: "any" }),
+};
+const iface = {
+ kind: "iface",
+ name: "platform",
+ version: 1,
+ context: anySchema,
+ methods: ["park", "info"],
+ children: {},
+ migrations: {},
+};
+const impl = {
+ async create(_ctx, context) {
+ await new Promise((resolve) => setTimeout(resolve, ${delayMs}));
+ return {
+ park: () => context,
+ info: () => ({ impl: ${JSON.stringify(id)} }),
+ http(request) {
+ const { pathname } = new URL(request.url);
+ if (pathname !== "/api/demo/version") return null;
+ return new Response(JSON.stringify({ impl: ${JSON.stringify(id)} }), {
+ status: 200,
+ headers: { "content-type": "application/json" },
+ });
+ },
+ };
+ },
+};
+export const hotPlatform = { id: ${JSON.stringify(id)}, iface, impl, context: {} };
+`;
+}
+
+describe("platform HTTP seam: a request racing an in-flight swap", () => {
+ let t: TestApp;
+ let cookie: string;
+ let api: ReturnType<typeof apiClient>;
+
+ beforeEach(async () => {
+ t = await createTestApp();
+ const admin = await loginAdmin(t.app);
+ cookie = admin.cookie;
+ api = apiClient(t.app, cookie);
+ });
+ afterEach(async () => {
+ await t.cleanup();
+ });
+
+ it("waits for the new instance instead of landing on the disposed old one", async () => {
+ // Boot v1 first (instant), so there IS an old instance for upgrade() to dispose.
+ expect((await pushPlatform(t.app, cookie, platformSlow(0, "v1"))).status).toBe(200);
+ expect(await (await api.get("/api/demo/version")).json()).toEqual({ impl: "v1" });
+
+ // Push v2 with a slow boot (kernel's upgrade() disposes v1 synchronously, then awaits
+ // v2's boot — see upgrade.ts) and race a seam request against it while it's in flight.
+ const pushed = pushPlatform(t.app, cookie, platformSlow(150, "v2"));
+ await new Promise((resolve) => setTimeout(resolve, 30));
+ const raced = await api.get("/api/demo/version");
+ expect((await pushed).status).toBe(200);
+
+ // Must observe latency (the seam awaited the swap), never the disposed v1 nor an error.
+ expect(raced.status).toBe(200);
+ expect(await raced.json()).toEqual({ impl: "v2" });
+ });
+});
diff --git a/packages/server/test/hmr-manifest.test.ts b/packages/server/test/hmr-manifest.test.ts
new file mode 100644
index 00000000..35d1bdf0
--- /dev/null
+++ b/packages/server/test/hmr-manifest.test.ts
@@ -0,0 +1,88 @@
+/**
+ * hmr/manifest.ts's resolveCliBundlePath: a plain disk reader `penguin-hmr` calls with no
+ * running HmrHost (see packages/cli/src/penguin-hmr.ts). It must return null — never throw —
+ * for every malformed or malicious harness.json, since a crash here breaks the CLI entirely.
+ */
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { resolveCliBundlePath } from "../src/hmr/manifest.js";
+
+async function makeRoot(): Promise<string> {
+ return fs.mkdtemp(path.join(os.tmpdir(), "penguin-hmr-manifest-test-"));
+}
+
+async function writeManifest(root: string, manifest: unknown): Promise<void> {
+ const hmrDir = path.join(root, "hmr");
+ await fs.mkdir(hmrDir, { recursive: true });
+ await fs.writeFile(path.join(hmrDir, "harness.json"), JSON.stringify(manifest));
+}
+
+describe("resolveCliBundlePath", () => {
+ let root: string | undefined;
+ afterEach(async () => {
+ if (root) await fs.rm(root, { recursive: true, force: true });
+ root = undefined;
+ });
+
+ it("returns null (not a throw) for a fresh root with no harness.json at all", async () => {
+ root = await makeRoot();
+ await expect(resolveCliBundlePath(root)).resolves.toBeNull();
+ });
+
+ it("returns null (not a throw) for `cli: {}` — no `bundle` key", async () => {
+ root = await makeRoot();
+ await writeManifest(root, { cli: {} });
+ await expect(resolveCliBundlePath(root)).resolves.toBeNull();
+ });
+
+ it("returns null (not a throw) when `bundle` is not a string", async () => {
+ root = await makeRoot();
+ await writeManifest(root, { cli: { bundle: 42 } });
+ await expect(resolveCliBundlePath(root)).resolves.toBeNull();
+ });
+
+ it("returns null (not a throw) when `bundle` is an empty string", async () => {
+ root = await makeRoot();
+ await writeManifest(root, { cli: { bundle: "" } });
+ await expect(resolveCliBundlePath(root)).resolves.toBeNull();
+ });
+
+ it("returns null for a bundle path that escapes <root>/hmr/ via `..`", async () => {
+ root = await makeRoot();
+ // Plant a real file the escape would otherwise reach, to prove the guard — not the
+ // file's mere non-existence — is what returns null.
+ await fs.writeFile(path.join(root, "escaped.mjs"), "export const cli = async () => 0;\n");
+ await writeManifest(root, { cli: { bundle: "../escaped.mjs" } });
+ await expect(resolveCliBundlePath(root)).resolves.toBeNull();
+ });
+
+ it("returns null for an absolute bundle path (also an escape attempt)", async () => {
+ root = await makeRoot();
+ const outside = path.join(os.tmpdir(), "not-under-hmr.mjs");
+ await fs.writeFile(outside, "export const cli = async () => 0;\n");
+ try {
+ await writeManifest(root, { cli: { bundle: outside } });
+ await expect(resolveCliBundlePath(root)).resolves.toBeNull();
+ } finally {
+ await fs.rm(outside, { force: true });
+ }
+ });
+
+ it("resolves a legitimate, in-store bundle path", async () => {
+ root = await makeRoot();
+ const storeDir = path.join(root, "hmr", "store", "cli");
+ await fs.mkdir(storeDir, { recursive: true });
+ await fs.writeFile(path.join(storeDir, "abc123.mjs"), "export const cli = async () => 0;\n");
+ await writeManifest(root, { cli: { bundle: "store/cli/abc123.mjs" } });
+ const resolved = await resolveCliBundlePath(root);
+ expect(resolved).toBe(path.join(root, "hmr", "store", "cli", "abc123.mjs"));
+ });
+
+ it("returns null when the referenced file does not exist (e.g. pruned)", async () => {
+ root = await makeRoot();
+ await writeManifest(root, { cli: { bundle: "store/cli/nonexistent.mjs" } });
+ await expect(resolveCliBundlePath(root)).resolves.toBeNull();
+ });
+});
diff --git a/packages/server/test/hmr-network-gate.test.ts b/packages/server/test/hmr-network-gate.test.ts
new file mode 100644
index 00000000..9b26aab5
--- /dev/null
+++ b/packages/server/test/hmr-network-gate.test.ts
@@ -0,0 +1,60 @@
+/**
+ * The hot-update network gate (hmr/routes.ts): on a non-loopback bind, hot APIs require
+ * real HTTPS. `x-forwarded-proto` is caller-supplied — trusting it unconditionally would
+ * let ANY client walk through the gate over plaintext just by setting a header, which is
+ * exactly the case the gate exists to block. It is honored only when the deployment
+ * explicitly opts in (`trustProxy` / PENGUIN_TRUST_PROXY=1), same as a real reverse-proxy
+ * setup requires.
+ */
+import { afterEach, describe, expect, it } from "vitest";
+import { createTestApp } from "./helpers.js";
+import type { TestApp } from "./helpers.js";
+
+describe("hmr network gate: non-loopback binds require real HTTPS", () => {
+ let t: TestApp | undefined;
+ afterEach(async () => {
+ if (t) await t.cleanup();
+ t = undefined;
+ });
+
+ it("rejects a spoofed x-forwarded-proto header by default (trustProxy off)", async () => {
+ t = await createTestApp({ config: { host: "0.0.0.0" } });
+ const res = await t.app.request("/api/hmr/upgrade", {
+ method: "POST",
+ headers: { "x-forwarded-proto": "https" },
+ });
+ expect(res.status).toBe(403);
+ const body = (await res.json()) as { error: { code: string } };
+ expect(body.error.code).toBe("hmr_disabled");
+ });
+
+ it("real HTTPS on the request URL itself passes the gate regardless of trustProxy", async () => {
+ t = await createTestApp({ config: { host: "0.0.0.0" } });
+ const res = await t.app.request("https://example.test/api/hmr/upgrade", { method: "POST" });
+ // Past the network gate now — falls through to cookie auth, which rejects with 401
+ // (no cookie sent), proving the gate itself let the request through.
+ expect(res.status).toBe(401);
+ });
+
+ it("plain HTTP on the request URL is still refused when trustProxy is on (no header sent)", async () => {
+ t = await createTestApp({ config: { host: "0.0.0.0", trustProxy: true } });
+ const res = await t.app.request("/api/hmr/upgrade", { method: "POST" });
+ expect(res.status).toBe(403);
+ });
+
+ it("honors x-forwarded-proto once trustProxy is explicitly enabled", async () => {
+ t = await createTestApp({ config: { host: "0.0.0.0", trustProxy: true } });
+ const res = await t.app.request("/api/hmr/upgrade", {
+ method: "POST",
+ headers: { "x-forwarded-proto": "https" },
+ });
+ // Past the network gate — rejected by the (missing) cookie instead.
+ expect(res.status).toBe(401);
+ });
+
+ it("a loopback bind needs neither HTTPS nor the header", async () => {
+ t = await createTestApp(); // default test config binds 127.0.0.1
+ const res = await t.app.request("/api/hmr/upgrade", { method: "POST" });
+ expect(res.status).toBe(401); // past the gate, rejected only by the missing cookie
+ });
+});
diff --git a/packages/server/tsup.config.ts b/packages/server/tsup.config.ts
index 10b02392..cc042c37 100644
--- a/packages/server/tsup.config.ts
+++ b/packages/server/tsup.config.ts
@@ -1,14 +1,20 @@
import { defineConfig } from "tsup";
export default defineConfig({
- // Explicitly name entries to preserve the dist/api/types.js, dist/lock.js and
- // dist/initial-password.js subpaths (exports "./api", "./lock" and "./initial-password"
- // point to them; lock and initial-password are side-effect-free for CLI pre-checks).
+ // Explicitly name entries to preserve subpath exports: "./api", "./lock",
+ // "./initial-password" (lock and initial-password are side-effect-free for CLI
+ // pre-checks); "./hmr/manifest" is the host-less harness.json reader the CLI's thin
+ // loader resolves the current cli bundle through. There is deliberately no
+ // "./platform" subpath: src/platform/entry.ts (this package's platform artifact
+ // compile target — see its own module doc) is compiled straight from source by
+ // esbuild in scripts/deploy.mjs, never through this package's published dist,
+ // so it has no reason to be a tsup entry or a subpath export.
entry: {
index: "src/index.ts",
"api/types": "src/api/types.ts",
lock: "src/lock.ts",
"initial-password": "src/initial-password.ts",
+ "hmr/manifest": "src/hmr/manifest.ts",
},
format: ["esm"],
target: "node22",
diff --git a/packages/web/src/state/sessions.tsx b/packages/web/src/state/sessions.tsx
index 56994a87..d2ad949b 100644
--- a/packages/web/src/state/sessions.tsx
+++ b/packages/web/src/state/sessions.tsx
@@ -412,6 +412,12 @@ export function SessionsProvider({ children }: { children: ReactNode }) {
const conn = openUserEvents({
onOmniMessage: () => undefined,
onServerEvent: (ev) => {
+ // The served web assets were hot-swapped (dev watch-push / platform
+ // upgrade): reload so this window runs the new code.
+ if (ev.type === "web_updated") {
+ window.location.reload();
+ return;
+ }
if (ev.type !== "schedule_fired") return;
// The event carries projectId: a trigger from another Project is unrelated to the current list.
if (ev.projectId === store.getState().projectId) void store.getState().reload();
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index c46256b4..d3a35999 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -27,6 +27,9 @@ importers:
concurrently:
specifier: ^10.0.4
version: 10.0.4
+ esbuild:
+ specifier: ^0.28.1
+ version: 0.28.1
prettier:
specifier: ^3.9.4
version: 3.9.4
@@ -97,6 +100,9 @@ importers:
'@prismshadow/penguin-skills':
specifier: workspace:*
version: link:../skills
+ arktype:
+ specifier: ^2.2.3
+ version: 2.2.3
smol-toml:
specifier: ^1.3.0
version: 1.6.1
@@ -400,6 +406,12 @@ packages:
zod:
optional: true
+ resolution: {integrity: sha512-Qx4D2JFbBWpntiHZaTv7bGG4H/M2rigiknezKg/WVyDSaLdE4YCcWAOoFB7pjjDqHbbV2OqRfntm1nnXvwMexg==}
+
+ resolution: {integrity: sha512-9kU2sUE38FZEGG7l3hamYMBieLYEJh2L1mrYD2eXpT+78EnQSV1bhjxJhnxGBMSTbtwpBSDNSK+K60WvaI/DTQ==}
+
'@aws-crypto/[email protected]':
resolution: {integrity: sha512-IzSgsrxUcsrejQbPVilIKy16kAT52EwB6zSaI+M3xxIhKh5+aldEyvI+z6erM7TCLB2BJsFrtHjp6/4/sr+3dA==}
@@ -1552,6 +1564,12 @@ packages:
resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
+ resolution: {integrity: sha512-PJcx6G1kQTgLKPUbeYlYecDRaKq15AMSGVajlKFYWlPeJRQL+j3dKE6tyMs40HZ99djS1l9Vhl3ezAHy9JBIqQ==}
+
+ resolution: {integrity: sha512-7W+0RLTUNJiBFIIZXwOQxSR8Z273IAd6IvqBeG9+gHnQKFsIx2C0iOtGTmMrPnlX4qLXyc5+ll7A0BIj9WrbTg==}
+
resolution: {integrity: sha512-PCVAQswWemu6UdxsDFFX/+gVeYqKAod3D3UVm91jHwynguOwAvYPhx8nNlM++NqRcK6CxxpUafjmhIdKiHibqg==}
@@ -3738,6 +3756,12 @@ snapshots:
optionalDependencies:
zod: 4.4.3
+ dependencies:
+ '@ark/util': 0.56.2
+
+ '@ark/[email protected]': {}
+
'@aws-crypto/[email protected]':
dependencies:
'@aws-crypto/util': 3.0.0
@@ -4464,6 +4488,7 @@ snapshots:
'@modelcontextprotocol/client': 2.0.0
'@prismshadow/agenthub': 0.4.2([email protected])([email protected])([email protected])
'@prismshadow/penguin-skills': file:packages/skills
+ arktype: 2.2.3
smol-toml: 1.6.1
yaml: 2.9.0
transitivePeerDependencies:
@@ -5165,6 +5190,16 @@ snapshots:
+ dependencies:
+ '@ark/util': 0.56.2
+
+ dependencies:
+ '@ark/schema': 0.56.2
+ '@ark/util': 0.56.2
+ arkregex: 0.0.8
+
diff --git a/scripts/deploy-target-safety.mjs b/scripts/deploy-target-safety.mjs
new file mode 100644
index 00000000..d5579984
--- /dev/null
+++ b/scripts/deploy-target-safety.mjs
@@ -0,0 +1,27 @@
+/**
+ * Pure target-safety check for deploy.mjs, split into its own module so it can be
+ * imported (and smoke-checked with `node -e`) without deploy.mjs's top-level argv/env
+ * side effects — deploy.mjs is a one-shot script, not a library, so everything else in
+ * it runs immediately on import.
+ */
+
+/** Hostnames that never leave this machine, so plaintext HTTP to them is not a wire secret. */
+const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+
+/**
+ * Refuses a target that would send PENGUIN_ADMIN_PASSWORD in the clear: deploy.mjs's
+ * login() posts it as a JSON body, and `http://` to anything off this machine puts it
+ * on the wire readable by anyone on the path. `https://` is always fine; plain
+ * `http://` is only fine to a loopback hostname (the documented `ssh -L` tunnel case —
+ * that traffic never leaves the machine). Returns a human-readable reason string when
+ * unsafe, `null` when the target is fine to send credentials to.
+ */
+export function unsafePlaintextTarget(urlStr) {
+ const url = new URL(urlStr);
+ if (url.protocol === "https:") return null;
+ if (LOOPBACK_HOSTNAMES.has(url.hostname.toLowerCase())) return null;
+ return (
+ `refusing to send PENGUIN_ADMIN_PASSWORD in plaintext to ${url.protocol}//${url.hostname} — ` +
+ "serve over https:// instead, or reach the target through an `ssh -L` tunnel to 127.0.0.1."
+ );
+}
diff --git a/scripts/deploy.mjs b/scripts/deploy.mjs
new file mode 100644
index 00000000..c50f777e
--- /dev/null
+++ b/scripts/deploy.mjs
@@ -0,0 +1,231 @@
+/**
+ * One-shot build-and-deploy to a running runtime: `node scripts/deploy.mjs <port>`.
+ *
+ * Aimed at one ad-hoc target and run once — for deploying to a machine reached through an
+ * ssh tunnel (`ssh -L <port>:127.0.0.1:<remote port> …`) as much as to a local runtime.
+ *
+ * Builds the web dist, compiles the platform and cli entries, and pushes all three as ONE
+ * atomic version to POST /api/hmr/upgrade. Authentication is an admin session established
+ * per run: PENGUIN_ADMIN_PASSWORD is read from the environment and exchanged for a cookie,
+ * so no credential of any kind is written to disk — a file holding an admin-equivalent
+ * secret is readable by everything running as this user, agent shells included, which makes
+ * the file itself the vulnerability.
+ *
+ * Usage:
+ * PENGUIN_ADMIN_PASSWORD=… node scripts/deploy.mjs 53531
+ * PENGUIN_ADMIN_PASSWORD=… node scripts/deploy.mjs 53531 --skip-web-build
+ * PENGUIN_ADMIN_PASSWORD=… node scripts/deploy.mjs https://box.example.com
+ */
+import { createRequire } from "node:module";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import http from "node:http";
+import https from "node:https";
+import os from "node:os";
+import path from "node:path";
+import zlib from "node:zlib";
+import { fileURLToPath } from "node:url";
+import { unsafePlaintextTarget } from "./deploy-target-safety.mjs";
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const WEB_DIST = path.join(ROOT, "packages", "web", "dist");
+const PLATFORM_ENTRY = path.join(ROOT, "packages", "server", "src", "platform", "entry.ts");
+const CLI_ENTRY = path.join(ROOT, "packages", "cli", "src", "index.ts");
+const PLATFORM_BUNDLE = path.join(os.tmpdir(), `penguin-deploy-platform-${process.pid}.mjs`);
+const CLI_BUNDLE = path.join(os.tmpdir(), `penguin-deploy-cli-${process.pid}.mjs`);
+
+const log = (msg) => console.log(`[deploy] ${msg}`);
+
+function usage(problem) {
+ console.error(
+ `${problem}\n\n` +
+ "Usage: PENGUIN_ADMIN_PASSWORD=… node scripts/deploy.mjs <port|url> [--skip-web-build]\n" +
+ " <port> a port on this machine (an ssh -L tunnel to the target runtime, or a local server)\n" +
+ " <url> a full origin, when the target is not reached over loopback\n",
+ );
+ process.exit(1);
+}
+
+const args = process.argv.slice(2);
+const skipWebBuild = args.includes("--skip-web-build");
+const target = args.find((a) => !a.startsWith("--"));
+if (target === undefined) usage("[deploy] no target given.");
+const ADMIN_PASSWORD = process.env.PENGUIN_ADMIN_PASSWORD;
+if (!ADMIN_PASSWORD) usage("[deploy] PENGUIN_ADMIN_PASSWORD is not set.");
+
+/** A bare port means this machine's loopback (typically an ssh -L tunnel to the real target). */
+const baseUrl = /^\d+$/.test(target) ? `http://127.0.0.1:${target}` : target.replace(/\/+$/, "");
+
+const plaintextProblem = unsafePlaintextTarget(baseUrl);
+if (plaintextProblem) usage(`[deploy] ${plaintextProblem}`);
+
+/**
+ * On a loopback bind 127.0.0.1 is the PREVIEW host, where /api answers 401; the API is
+ * served under the canonical app host. A tunnel lands on 127.0.0.1:<port> at this end,
+ * so the request must still be addressed to `localhost` by name.
+ */
+const hostOverride = new URL(baseUrl).hostname === "127.0.0.1" ? "localhost" : undefined;
+
+/**
+ * node:http rather than the global fetch: fetch (undici) silently derives Host from the
+ * URL and ignores an explicit `headers.host`, which breaks the override above.
+ */
+function request(urlStr, { method = "GET", headers = {}, body } = {}) {
+ return new Promise((resolve, reject) => {
+ const url = new URL(urlStr);
+ const lib = url.protocol === "https:" ? https : http;
+ const req = lib.request(
+ {
+ hostname: url.hostname,
+ port: url.port || (url.protocol === "https:" ? 443 : 80),
+ path: `${url.pathname}${url.search}`,
+ method,
+ headers: { ...headers, ...(hostOverride ? { host: hostOverride } : {}) },
+ },
+ (res) => {
+ const chunks = [];
+ res.on("data", (c) => chunks.push(c));
+ res.on("end", () =>
+ resolve({
+ status: res.statusCode ?? 0,
+ headers: res.headers,
+ body: Buffer.concat(chunks),
+ }),
+ );
+ },
+ );
+ req.on("error", reject);
+ if (body !== undefined) req.write(body);
+ req.end();
+ });
+}
+
+/** Signs in as `admin` and returns the session cookie. */
+async function login() {
+ const res = await request(`${baseUrl}/api/auth/login`, {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify({ userId: "admin", password: ADMIN_PASSWORD }),
+ });
+ if (res.status !== 200) {
+ throw new Error(`admin login failed (${res.status}): ${res.body.toString("utf8")}`);
+ }
+ const setCookie = res.headers["set-cookie"];
+ if (!setCookie?.length) throw new Error("login succeeded but set no session cookie");
+ return setCookie.map((c) => c.split(";")[0]).join("; ");
+}
+
+/**
+ * Compiles one entry to a self-contained ESM file. The banner is load-bearing: several
+ * bundled CJS deps call plain `require(...)` inside their own wrapper, and esbuild's ESM
+ * output otherwise routes those to a shim that always throws.
+ */
+async function compileEntry(entry, outfile) {
+ if (!fs.existsSync(entry)) throw new Error(`compile entry missing: ${entry}`);
+ const esbuild = await import("esbuild");
+ await esbuild.build({
+ entryPoints: [entry],
+ bundle: true,
+ format: "esm",
+ platform: "node",
+ outfile,
+ logLevel: "silent",
+ banner: {
+ js: 'import { createRequire as __penguinCreateRequire } from "node:module"; const require = __penguinCreateRequire(import.meta.url);',
+ },
+ alias: {
+ "@prismshadow/penguin-core/kernel": require.resolve("@prismshadow/penguin-core/kernel"),
+ },
+ });
+}
+
+/** The built web dist as a { relPath: base64 } manifest. */
+async function readWebManifest() {
+ const files = {};
+ for (const entry of await fsp.readdir(WEB_DIST, { recursive: true, withFileTypes: true })) {
+ if (!entry.isFile()) continue;
+ const abs = path.join(entry.parentPath, entry.name);
+ files[path.relative(WEB_DIST, abs).split(path.sep).join("/")] = (
+ await fsp.readFile(abs)
+ ).toString("base64");
+ }
+ return files;
+}
+
+async function main() {
+ if (skipWebBuild) {
+ if (!fs.existsSync(path.join(WEB_DIST, "index.html"))) {
+ throw new Error(`--skip-web-build given but ${WEB_DIST} has no index.html`);
+ }
+ log("reusing the existing web dist");
+ } else {
+ log("building the web dist…");
+ execFileSync("pnpm", ["--filter", "@prismshadow/penguin-web", "build"], {
+ cwd: ROOT,
+ stdio: "inherit",
+ });
+ }
+
+ log("compiling platform + cli…");
+ await compileEntry(PLATFORM_ENTRY, PLATFORM_BUNDLE);
+ await compileEntry(CLI_ENTRY, CLI_BUNDLE);
+
+ const files = await readWebManifest();
+ const gz = zlib.gzipSync(
+ Buffer.from(
+ JSON.stringify({
+ platform: await fsp.readFile(PLATFORM_BUNDLE, "utf8"),
+ cli: await fsp.readFile(CLI_BUNDLE, "utf8"),
+ web: { files },
+ }),
+ ),
+ );
+ log(
+ `pushing ${Object.keys(files).length} web files + 2 bundles (${(gz.length / 1048576).toFixed(1)} MB) to ${baseUrl}…`,
+ );
+
+ const cookie = await login();
+ const started = Date.now();
+ const res = await request(`${baseUrl}/api/hmr/upgrade`, {
+ method: "POST",
+ headers: { "content-type": "application/gzip", cookie },
+ body: gz,
+ });
+ const seconds = ((Date.now() - started) / 1000).toFixed(1);
+ const text = res.body.toString("utf8");
+ if (res.status < 200 || res.status >= 300) {
+ throw new Error(`/api/hmr/upgrade → ${res.status}: ${text}`);
+ }
+ const outcome = JSON.parse(text);
+ if (outcome.status === "blocked") {
+ // A blocked upgrade is a first-class outcome, not an HTTP error: the running
+ // version keeps serving and these paths say what would have been discarded.
+ log(`BLOCKED after ${seconds}s — the target kept its current version.`);
+ console.error(JSON.stringify(outcome, null, 2));
+ process.exitCode = 1;
+ return;
+ }
+ log(
+ `ok in ${seconds}s — impl ${outcome.impl}, mode ${outcome.mode}, web rev ${outcome.web?.rev}`,
+ );
+ if (outcome.persisted === false) {
+ // The live swap took effect, but the server could not write it to disk (see
+ // host.ts's persistVersion) — a restart on the target reverts to the previously
+ // committed version, silently undoing this push.
+ console.warn(
+ "[deploy] WARNING: the target could not persist this version to disk (persisted: false). " +
+ "It is live now but will REVERT on the target's next restart — check the target's disk/permissions.",
+ );
+ }
+}
+
+main()
+ .catch((err) => {
+ console.error(`[deploy] ${err instanceof Error ? err.message : String(err)}`);
+ process.exitCode = 1;
+ })
+ .finally(() => {
+ for (const f of [PLATFORM_BUNDLE, CLI_BUNDLE]) fs.rmSync(f, { force: true });
+ });