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.ymlindex 2dc06129..f13b4d2f 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -115,3 +115,65 @@ jobs:- name: Windows installer testsshell: pwshrun: ./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-x64diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 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" "$@"EOFchmod +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%EOFdiff --git a/changelog/unreleased/2026-08-18-hot-update.md b/changelog/unreleased/2026-08-18-hot-update.mdnew file mode 100644index 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.mdindex 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.jsonindex 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.jsonindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.jsonindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.mjsindex 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.tsindex 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.tsindex 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 loaddiff --git a/packages/desktop/test/launcher.test.ts b/packages/desktop/test/launcher.test.tsindex 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.mdindex 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.jsonindex 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.tsindex 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.tsindex 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: BuildDepsOverridessessionSources,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.tsindex 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.tsindex 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): ServeauthSessionRenewMs: 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.mdnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.mjsnew file mode 100644index 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.tsindex 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<TestAroot,adminPassword,cleanup: async () => {+ deps.hmr.dispose();deps.channels.dispose();deps.db.close();// maxRetries: Windows can report ENOTEMPTY/EBUSY while handles from the test's owndiff --git a/packages/server/test/hmr-host.test.ts b/packages/server/test/hmr-host.test.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsxindex 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.yamlindex c46256b4..d3a35999 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -27,6 +27,9 @@ importers:concurrently:specifier: ^10.0.4version: 10.0.4+ esbuild:+ specifier: ^0.28.1+ version: 0.28.1prettier:specifier: ^3.9.4version: 3.9.4@@ -97,6 +100,9 @@ importers:'@prismshadow/penguin-skills':specifier: workspace:*version: link:../skills+ arktype:+ specifier: ^2.2.3+ version: 2.2.3smol-toml:specifier: ^1.3.0version: 1.6.1@@ -400,6 +406,12 @@ packages:zod:optional: true+ '@ark/[email protected]':+ resolution: {integrity: sha512-Qx4D2JFbBWpntiHZaTv7bGG4H/M2rigiknezKg/WVyDSaLdE4YCcWAOoFB7pjjDqHbbV2OqRfntm1nnXvwMexg==}++ '@ark/[email protected]':+ 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+ '@ark/[email protected]':+ 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/penguin-skills': file:packages/skills+ arktype: 2.2.3smol-toml: 1.6.1yaml: 2.9.0transitivePeerDependencies:@@ -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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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 });+ });