@runeditrun/rer 0.2.2 → 0.2.5

package/global/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 0.2.5
+
+- `rer deploy` with a seed's own deploy hook claims the hosted owner from what the hook returns, `{ deployed: true, origin }`, once the origin's `/health` names the checkout's commit, and prints the sign-in address. A hook that keeps its own deployment record (Penny's does) no longer ends in `missing-owner-receipt` with a live, unclaimed app; such a hook returns `setupToken` too when its Worker holds a setup token other than the `SETUP_TOKEN` rer passed it. A hook that reports no deployment, or whose app never names the commit, fails saying so and claims nothing.
+- `rer deploy` with uncommitted changes to tracked files stops before building, lists the files, says to commit them and that nothing was uploaded (exit 4), instead of building first and failing with `owner-source-not-committed`.
+- `rer deploy --demo --dry-run` and `rer build --platform container` work on an exported seed: the container import boundary admits the demo guard's `import { env } from 'cloudflare:workers'` in `src/modules/demo/index.mjs` (that file and that import only) and still refuses a Cloudflare import anywhere else in `src/`. The release smoke now runs the hosted demo dry run on a package-mode export.
+- `rer describe` lists `demo` as a verb (`rer dev --demo`), with its effects and the flags a demo takes.
+- Two launches claiming the same port, or two workers claiming the same checkout's launch, get exactly one winner: the claim is written complete and linked into place, so the other never reads it half-written and takes it as abandoned.
+- `node scripts/export-cli.mjs --to-package` on a composed foundation drops the removed `scripts/base-cli` copy's entries from `composition.lock.json` along with its files, so `rer check` no longer fails `SC-05.auth-copy` for files the conversion deleted.
+- `rer deploy` refuses a seed deploy hook's `http://` origin (other than a loopback host such as `localhost`, `127.0.0.1` or `[::1]`) before sending it anything, so the one-time setup token only travels over https; it says to make the hook return its https origin.
+- After a redeploy whose app answers unhealthy, the owner state in `.rer/deploy/` keeps each health check's status and timing but not the response text, so a secret an app echoes is never saved there; the secret command already kept none.
+- A secret change `rer deploy` could not yet confirm stays recorded until the provider's records agree, and blocks another secret change, deploy or removal until then; a secret added or removed outside rer meanwhile is refused instead of adopted.
+
+### Upgrade notes
+
+- A seed's custom deploy hook returns `{ deployed: true, origin }` with an https origin (and may add `setupToken`); `rer deploy` waits for that origin's `/health` to name the checkout's commit, then claims the owner itself.
+- A seed adopting `rer demo` needs rer 0.2.5 for `rer deploy --demo`.
+
+## 0.2.4
+
+0.2.3 was tagged but not published; its changes are in 0.2.4.
+
+- A first `rer deploy` waits up to two minutes (it was 30 seconds) for Cloudflare's account listing to show a database, bucket, namespace or queue it has just created, whether the listing disagrees with its own page counts or leaves the new resource out; one that never appears stops the deploy before any upload, names the resource, and the same command resumes with it.
+- A first `rer dev` no longer chooses the port another, stopped checkout was set up on, so both checkouts keep working origins.
+- Seed recovery code can check the deploy migration ledger with one call: `migrationLedgerShape(rows)` from `@runeditrun/rer/modules/deploy-kit/migration-ledger`, given the rows of its `ledgerShapeQuery`, accepts all four ledger shapes a deployment can hold (Wrangler's `d1_migrations`, that table after a kit deploy adopted it, the kit's own `d1_migrations` since 0.2.2, and the `_rer_deploy_migrations` ledger a 0.2.1 or earlier deploy left, shape `legacy`, which wins when both tables exist) and refuses any other. A seed whose recovery checks that the ledger is exactly Wrangler's three columns refuses ledgers from 0.2.2 on (`MIGRATION_MISMATCH`); replace that check with this call.
+- `rer import` and hosted restores refuse an archive that records a migration this installation has not applied (`schema_mismatch`), even when that migration left the schema unchanged (an index or a data-only change); such an archive is newer than the installation.
+- After a pulled change to a checkout's `@runeditrun/rer` pin, every verb (`rer deploy` included) installs the pinned version with the frozen lockfile before it runs, instead of asking you to run `rer install` first.
+- Two verbs started at the same moment after a pulled pin change share one install of the new pin: the second waits for the first's install, then runs, instead of racing it and failing with "The declared adapter could not be loaded".
+- The publication scan accepts AI-generated PNGs whose C2PA manifest carries the signing certificate's email address (certificate names are metadata) and phone JPEGs that store more images after the first (every image's pixels are skipped as pixels), while an address in the rest of the manifest, XMP or EXIF is still flagged.
+- Dependency installs receive only the environment an install needs, never your credentials: the frozen `pnpm install` that `rer install`, a fresh clone's first verb, `rer dev`, the installer and `rer release` run, the pnpm version check, `rer update`'s npm install and local data migrations get `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `TMPDIR`/`TMP`/`TEMP`, `TERM`, `LANG`/`LANGUAGE`/`LC_*`, `TZ`, `CI`, `SSH_AUTH_SOCK` (git+ssh dependencies), `NODE_OPTIONS`, `NODE_EXTRA_CA_CERTS`, `XDG_*`, proxy settings without their user:password, and `npm_config_*`, `PNPM_*`, `COREPACK_*` and `RER_*` settings except credentials (by name, such as `_authToken` or `*_SESSION`, or by value: a URL with a password, a credential query or connection-string parameter, a JWT, a private key, an Authorization header or a provider token). Every other variable stays with you, so dependency build scripts (esbuild, workerd, sharp, oxide) never see vault sessions (`BW_SESSION`, `OP_SESSION_*`), connection strings, keys or tokens under any name. `rer deploy` and the seed's own `verify` still receive everything.
+- A proxy setting reaches a dependency install without its user:password even when the password contains spaces, an extra `@` or the value starts with whitespace.
+- `rer deploy` setting or removing a secret whose answer was lost settles against the Worker version it recorded, so a later deploy recognises the change instead of refusing it.
+- A secret change whose answer was lost while the read-back also failed stays recorded as pending, so the next `rer deploy` recognises it instead of locking you out; replacing an existing secret after a lost answer writes it again and confirms it before reporting success.
+- After it claims the hosted owner, retires the setup token or sets or removes a secret, `rer deploy` checks the app's health on the new Worker version and fails with the HTTP status and the response's first line, instead of reporting success, when the app is not healthy.
+- `rer setup` finishes provider-free when a seed declares an optional dependency that you leave unconnected.
+- A seed adapter can declare `resetPreflight`; `rer reset` runs it before listing or deleting anything, and `--yes` cannot skip it.
+- A first `rer dev` whose chosen port is taken by another program before setup can use it moves to the next free port and says which.
+- `rer deploy` says it is deploying to your Cloudflare account and names the live address, instead of saying the application is running locally; `rer build` ends with "Your application is built".
+- `rer describe` in the default seed and new foundations names the release keygen, sign and receipt subcommands again.
+- Importing an archive whose bytes are not valid UTF-8 is refused with the same `archive_json` diagnostic (exit 2) as invalid JSON.
+- Converting a seed to package mode no longer leaves a broken queue sentence in its README or `scripts/base-cli` paths in its operations guide and erasure README.
+- The owner's sign-in settings page (`/auth/settings/identity`) wears the seed's declared theme, like sign-in and setup.
+- `rer demo` (the same as `rer dev --demo`) runs a seed as a throwaway local demo: signed in as the saved owner, filled with the seed's demo data, marked by a Demo bar, unable to send anything, and deleted on `--stop`, Ctrl-C or after an hour; the checkout's own state is never written.
+- Under `rer demo`, `fetch`, redirects, `WebSocket`, `navigator.sendBeacon`, `EventSource`, `node:net`/`node:tls` and `cloudflare:sockets` reach loopback hosts only, and every refused send is listed in the Demo bar.
+- `rer demo` refuses a seed that has not adopted it (no `withDemo` guard, no `demoSockets()` or a state path that ignores `RER_STATE_DIR`), and `rer deploy`, including `--dry-run`, refuses a deploy declaration or `--env-file` that carries `RER_DEMO` and names the key.
+- `rer deploy --demo` hosts a seed's demo at `demo.<domain>`: each visitor passes a Turnstile check and gets their own signed-in, throwaway container of the seed that can send nothing, ended after an hour or 15 idle minutes. `export/run-demo.yml` deploys it when `RUN_DEMO_DEPLOY` is on.
+- `rer deploy` claims the hosted owner after every deploy, including seeds whose own deploy hooks run, retires the setup token, keeps an existing native identity-provider owner and keeps a live owner token you supply.
+- Container images built by `rer build --platform container` start again; they exited at start.
+- The default seed's sign-in serves the signed owner claim whenever its public keys are configured.
+- A seed can declare a reviewed rewrite of an already released migration in `migrations/rewrites.json`; deploys and local builds accept the released bytes for that migration only and still refuse every undeclared change.
+- Seed table inventories can use the exported portability exclusion list, so native ZIP and remote export no longer refuse the deploy controller's migration ledger table.
+- The publication scan skips only the compressed pixel and sample data of recognised images and videos; their comments, XMP, EXIF and tags are checked, and a text file behind a fake media header is checked whole.
+- With `--public-base`, the publication scan reports a file identical to the public base's copy as pre-existing instead of a finding.
+- Base's default seed and source import kit (outside the rer npm package) prepare and verify 100,000-row imports across requests within the Worker CPU limit and resume after a killed step; a changed re-upload under a published key is refused.
+- Base's default seed and source import kit erase a person named in other people's imported records at seed scale, across requests, and when they never became a native record; an interrupted erasure is finished by a cron sweep within about 10 minutes.
+
+### Upgrade notes
+
+- Existing OIDC provider links show **not linked** until the next successful sign-in through each provider, because older stores have no verified token-exchange observation for them.
+- The default seed's erasure queue message is now `{ redact, chain }` instead of `{ redact, operator, continuation }`; a message still queued in the old shape when you deploy is refused, so let the erasure queue drain first. Default-seed migrations 0021 to 0023 add the import-step, stream-source and erasure-progress tables, and its cron trigger sweeps erasures every 10 minutes.
+- A seed adopting `rer demo` adds `src/demo.ts` (exporting an idempotent `seedDemo`), copies Base's `modules/demo/` and wraps its Worker entry's default export in `withDemo` as the entry's first import, and makes three `vite.config` changes: the state path reads `RER_STATE_DIR`, the dev entry's vars pass `RER_DEMO` and `RER_DEMO_EXPIRES`, and `demoSockets()` comes first in `plugins`; add `.rer/demo/` to `.gitignore`. `export/DEMO.md` has the steps.
+- A private registry's auth must be in `~/.npmrc` (or the registry config your package manager reads from `HOME`): dependency installs now get only an allowlisted environment, so a token passed as an environment variable no longer reaches them.
+- A seed with custom recovery code that checks the deploy migration ledger is exactly Wrangler's three columns uses `migrationLedgerShape` instead; the old check refuses ledgers from 0.2.2 on (`MIGRATION_MISMATCH`).
+
 ## 0.2.2
 
 - `rer deploy` claims the hosted owner, exits cleanly when it finishes, changes and removes secrets safely, and removes the resources it created when you ask it to.

package/global/README.md

@@ -182,8 +182,15 @@ as an exact devDependency instead (`"@runeditrun/rer": "0.2.0"`, locked in
 which inside `pnpm run` is the pinned copy in `node_modules/.bin`, so
 `pnpm install --frozen-lockfile && pnpm run build` needs no global `rer`. A global
 `rer` hands every verb to the pinned package, launching included. Until
-`node_modules` holds the pinned version, `rer install` and `rer dev` install it
-first (the frozen `pnpm install`) and every other verb says to run `rer install`.
+`node_modules` holds the pinned version (a fresh clone, or a pulled pin change),
+every verb installs it first (the frozen `pnpm install`), then runs it; verbs
+started at once share that one install.
+Every dependency install, `rer release`'s included, receives an allowlisted
+environment: the shell, locale, terminal and temporary-folder variables, `CI`,
+`TZ`, `SSH_AUTH_SOCK`, `NODE_OPTIONS`, `NODE_EXTRA_CA_CERTS`, `XDG_*`, proxy
+settings without their user:password, and `npm_config_*`, `PNPM_*`,
+`COREPACK_*` and `RER_*` settings that carry no credential by name or value.
+No other variable reaches the package manager or a dependency's build script.
 
 Heavy package scripts wait for this computer's job queue with
 `rer queue NAME -- COMMAND [ARGS]` (in vendored mode,

package/global/launch/capacity.mjs

@@ -13,7 +13,7 @@ import { LaunchFailure } from './failure.mjs';
 export const personDefaults = { limit: 10, idleSeconds: 43200 };
 const unboundedLoad = '1000000';
 // The verbs that start a server or enter the job queue on every pin.
-export const personVerbs = new Set(['dev', 'preview', 'install', 'setup', 'build', 'verify', 'deploy', 'export', 'import']);
+export const personVerbs = new Set(['dev', 'demo', 'preview', 'install', 'setup', 'build', 'verify', 'deploy', 'export', 'import']);
 
 // How the pinned dispatcher counts servers, and which person defaults it lacks.
 // describe's `defaults` (from rer-cli-2) is authoritative: the launcher supplies

package/global/launch/facts.mjs

@@ -76,14 +76,20 @@ async function bindable(host, port) {
  finally { if (socket.listening) await new Promise(resolve => socket.close(resolve)); }
 }
 
-// The first port from 8787 (RER_DEV_PORT_FROM moves the start) that no
-// registered server holds, nothing listens on, binds on both 127.0.0.1 and ::1
-// (a browser that tries ::1 first never reaches another server) and that
-// `claim` secures against another launch choosing it at the same time.
-export async function freePort(servers, claim, env = process.env) {
+// Whether something now listens on a port or keeps it from binding.
+export async function portTaken(port) {
+ return (await listeningPorts()).has(port) || !await bindable('127.0.0.1', port) || !await bindable('::1', port);
+}
+
+// The first port from 8787 (RER_DEV_PORT_FROM moves the start) that is not
+// `held` (by a registered server, or saved by another checkout that is stopped),
+// nothing listens on, binds on both 127.0.0.1 and ::1 (a browser that tries
+// ::1 first never reaches another server) and that `claim` secures against
+// another launch choosing it at the same time.
+export async function freePort(ports, claim, env = process.env) {
  const from = Number(env.RER_DEV_PORT_FROM ?? 8787);
  if (!Number.isInteger(from) || from < 1 || from > 65535) throw new LaunchFailure(2, 'RER_DEV_PORT_FROM must be a port number.');
- const held = new Set(servers.map(record => record.port).filter(Boolean)), busy = await listeningPorts();
+ const held = new Set(ports.filter(Boolean)), busy = await listeningPorts();
  for (let port = from; port <= 65535; port++) {
   if (held.has(port) || busy.has(port)) continue;
   if (!await bindable('127.0.0.1', port) || !await bindable('::1', port)) continue;

package/global/launch/install-pinned.mjs

@@ -1,19 +1,43 @@
 // A checkout that pins the @runeditrun/rer package runs its own rer once
 // node_modules holds the pinned version; until then none of it can run (its
 // adapter imports the package). So its first dependency install is this
-// launcher's: the frozen pnpm install that `rer install` runs.
+// launcher's: the frozen pnpm install that `rer install` runs. Like every
+// dependency install, it runs with an allowlisted environment. Verbs started
+// at once share one install: each takes the checkout's install claim and
+// installs only if the pin is still missing once it holds it.
 import { spawn } from 'node:child_process';
+import { realpath } from 'node:fs/promises';
+import { dependencyEnvironment } from '../../onboarding/dependency-environment.mjs';
 import { pinnedPackage } from '../checkout.mjs';
 import { packageName } from '../package-info.mjs';
 import { ensureProjectPnpm } from '../../cli/project-pnpm.mjs';
 import { RerError } from '../../cli/errors.mjs';
 import { LaunchFailure } from './failure.mjs';
+import { claimPinInstall, settledPinInstall } from './state.mjs';
+
+const waiting = (root, output) => pid => output(`Another rer (PID ${pid}) is installing ${root}'s pinned ${packageName}; waiting for it.\n`);
 
 export async function installPinned(root, { env = process.env, output = text => process.stderr.write(text), children, signal } = {}) {
  signal?.throwIfAborted();
+ const release = await claimPinInstall(await realpath(root), { env, signal, onWait: waiting(root, output) });
+ try {
+  const pinned = pinnedPackage(root);
+  if (pinned?.ready) return;
+  if (pinned?.installed) output(`${root} pins ${packageName} ${pinned.declared}, but node_modules holds ${pinned.installed}; installing the pinned version first.\n`);
+  await install(root, { env, output, children, signal });
+ } finally { await release(); }
+}
+
+// A verb on a checkout whose pin looks installed still waits for an install
+// another verb is running there: node_modules is not complete until it ends.
+export async function settledPin(root, { env = process.env, output = text => process.stderr.write(text), signal } = {}) {
+ await settledPinInstall(await realpath(root), { env, signal, onWait: waiting(root, output) });
+}
+
+async function install(root, { env, output, children, signal }) {
  try { await ensureProjectPnpm(root, { env, signal, report: text => output(text + '\n') }); }
  catch (error) { if (error instanceof RerError) throw new LaunchFailure(error.exitCode, error.message); throw error; }
- const child = spawn('pnpm', ['install', '--frozen-lockfile'], { cwd: root, env: { ...env, CI: 'true' }, stdio: ['ignore', 'pipe', 'pipe'] });
+ const child = spawn('pnpm', ['install', '--frozen-lockfile'], { cwd: root, env: { ...dependencyEnvironment(env), CI: 'true' }, stdio: ['ignore', 'pipe', 'pipe'] });
  children?.add(child);
  if (signal?.aborted) child.kill('SIGTERM');
  let tail = '';

package/global/launch/prepare.mjs

@@ -10,8 +10,8 @@ import { liveServers } from '../registry.mjs';
 import { checkCapacity, personEnvironment, pinPolicy } from './capacity.mjs';
 import { bringBackDoor, doorPlan } from './door.mjs';
 import { LaunchFailure } from './failure.mjs';
-import { describeCheckout, freePort, localOwner, needsInstall, setupNeeded } from './facts.mjs';
-import { claimPort, installState, setupState } from './state.mjs';
+import { describeCheckout, freePort, localOwner, needsInstall, portTaken, setupNeeded } from './facts.mjs';
+import { claimPort, installState, savedPorts, setupState } from './state.mjs';
 import { runVerb } from './steps.mjs';
 import { localDefaults } from './local-defaults.mjs';
 import { installPinned } from './install-pinned.mjs';
@@ -74,13 +74,25 @@ export async function prepare({ root, args, env, report, directory, log, childre
   return { entry, added };
  } else if (setup === 'fresh') {
   // An interrupted setup resumes on the port it chose while that port is free.
+  // A port another process takes between choosing it and setup refusing it is
+  // passed over for the next free one; a port the person passed is kept.
   const owner = localOwner(checkout), explicit = flagValue(args, '--port');
-  const { port, release } = explicit ? { port: Number(explicit) } : await freePort(await liveServers(childEnv), port => claimPort(port, childEnv), last?.port ? { ...childEnv, RER_DEV_PORT_FROM: String(last.port) } : childEnv);
-  report({ phase: 'setup', message: `setting up a local owner (${owner}) on port ${port}` });
-  try { await step(setupState, ['setup', '--owner-email', owner, '--port', String(port), ...hostArgs], { port, owner }, setupEnv); }
-  catch (failure) { await release?.(); throw failure; }
-  // The claim lasts until the server registers the port: the caller releases it.
-  return { entry, added, release };
+  let from = last?.port;
+  for (let attempt = 1; ; attempt++) {
+   const held = explicit ? [] : [...(await liveServers(childEnv)).map(record => record.port), ...await savedPorts(checkout, childEnv)];
+   const { port, release } = explicit ? { port: Number(explicit) } : await freePort(held, port => claimPort(port, childEnv), from ? { ...childEnv, RER_DEV_PORT_FROM: String(from) } : childEnv);
+   report({ phase: 'setup', message: `setting up a local owner (${owner}) on port ${port}` });
+   try { await step(setupState, ['setup', '--owner-email', owner, '--port', String(port), ...hostArgs], { port, owner }, setupEnv); }
+   catch (failure) {
+    await release?.();
+    if (explicit || attempt === 3 || failure.exitCode !== 4 || !await portTaken(port)) throw failure;
+    report({ phase: 'note', message: `port ${port} was taken by another process; choosing another free port` });
+    from = port + 1;
+    continue;
+   }
+   // The claim lasts until the server registers the port: the caller releases it.
+   return { entry, added, release };
+  }
  }
  await bringBackDoor(plan, env, report);
  return { entry, added };

package/global/launch/state.mjs

@@ -8,8 +8,9 @@
 //   server.log    the private log of the server rer started
 //   server.json   that server's PID and start time, and the process rer spawned
 //   stop.json     when rer dev --stop last ran: a launch requested before it stops
+//   pin-install.json  the process installing the checkout's pinned rer package
 import { createHash } from 'node:crypto';
-import { appendFile, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { appendFile, link, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { processInfo } from '../../modules/job-queue/processes.mjs';
 import { serversDirectory } from '../registry.mjs';
@@ -38,6 +39,19 @@ export async function liveWorker(directory) {
  return await live(holder) ? holder : undefined;
 }
 
+// A claim file is written to a private file first and hard-linked into place,
+// so it appears complete or not at all: a process finding it never reads a
+// half-written claim as a dead one and removes it. False when one is there.
+async function linkClaim(path, record) {
+ const written = `${path}.${process.pid}`;
+ await writeFile(written, JSON.stringify(record), { mode: 0o600 });
+ try {
+  await link(written, path);
+  return true;
+ } catch (error) { if (error.code !== 'EEXIST') throw error; return false; }
+ finally { await rm(written, { force: true }); }
+}
+
 // A port chosen for a setup stays claimed while the process that chose it
 // lives, so two launches preparing at once never pick the same port.
 export async function claimPort(port, env = process.env) {
@@ -45,31 +59,55 @@ export async function claimPort(port, env = process.env) {
  await mkdir(directory, { recursive: true, mode: 0o700 });
  const { start } = await processInfo(process.pid);
  for (let attempt = 0; attempt < 2; attempt++) {
-  try {
-   await writeFile(path, JSON.stringify({ pid: process.pid, start }), { flag: 'wx', mode: 0o600 });
-   return { release: async () => { if ((await readJson(path))?.pid === process.pid) await rm(path, { force: true }); } };
-  } catch (error) { if (error.code !== 'EEXIST') throw error; }
+  if (await linkClaim(path, { pid: process.pid, start })) return { release: async () => { if ((await readJson(path))?.pid === process.pid) await rm(path, { force: true }); } };
   if (await live(await readJson(path))) return undefined;
   await rm(path, { force: true });
  }
  return undefined;
 }
 
+// One pinned-package install per checkout at a time: two verbs started at once
+// after a pin change share it. claimPinInstall resolves to a release function
+// once this process holds the claim; both wait (onWait once) while another
+// live process holds it.
+const pinInstallPath = (checkout, env) => join(launchPath(checkout, env), 'pin-install.json');
+const pause = () => new Promise(resolveWait => setTimeout(resolveWait, 200));
+
+export async function claimPinInstall(checkout, { env = process.env, signal, onWait } = {}) {
+ await launchDirectory(checkout, env);
+ const path = pinInstallPath(checkout, env), { start } = await processInfo(process.pid);
+ for (let waited = false; ; ) {
+  signal?.throwIfAborted();
+  if (await linkClaim(path, { pid: process.pid, start })) return async () => { if ((await readJson(path))?.pid === process.pid) await rm(path, { force: true }); };
+  const holder = await readJson(path);
+  if (!await live(holder)) { await rm(path, { force: true }); continue; }
+  if (!waited) { waited = true; onWait?.(holder.pid); }
+  await pause();
+ }
+}
+
+export async function settledPinInstall(checkout, { env = process.env, signal, onWait } = {}) {
+ for (let waited = false; ; ) {
+  signal?.throwIfAborted();
+  const holder = await readJson(pinInstallPath(checkout, env));
+  if (!await live(holder)) return;
+  if (!waited) { waited = true; onWait?.(holder.pid); }
+  await pause();
+ }
+}
+
 // The worker claims the checkout's launch; a second worker started at the
 // same moment finds the first and leaves.
 export async function claimLaunch(directory, token) {
  const path = join(directory, 'worker.json');
  for (let attempt = 0; attempt < 3; attempt++) {
   const { start } = await processInfo(process.pid);
-  try {
-   await writeFile(path, JSON.stringify({ token, pid: process.pid, start, startedAt: Date.now(), events: `events-${token}.jsonl` }), { flag: 'wx', mode: 0o600 });
+  if (await linkClaim(path, { token, pid: process.pid, start, startedAt: Date.now(), events: `events-${token}.jsonl` })) {
    for (const entry of await readdir(directory)) if (/^events-.*\.jsonl$/.test(entry) && entry !== `events-${token}.jsonl`) await rm(join(directory, entry), { force: true });
    return true;
-  } catch (error) {
-   if (error.code !== 'EEXIST') throw error;
-   if (await liveWorker(directory)) return false;
-   await rm(path, { force: true });
   }
+  if (await liveWorker(directory)) return false;
+  await rm(path, { force: true });
  }
  return false;
 }
@@ -92,6 +130,21 @@ const stepRecord = name => ({
 });
 export const installState = stepRecord('install'), setupState = stepRecord('setup');
 
+// The ports other checkouts were set up on by this launcher. A stopped
+// checkout keeps its saved origin, so a fresh launch must not take its port.
+export async function savedPorts(checkout, env = process.env) {
+ const launches = join(serversDirectory(env), 'launches'), own = launchPath(checkout, env);
+ let entries = [];
+ try { entries = await readdir(launches, { withFileTypes: true }); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+ const ports = [];
+ for (const entry of entries) {
+  if (!entry.isDirectory() || join(launches, entry.name) === own) continue;
+  const port = (await setupState.read(join(launches, entry.name)))?.port;
+  if (Number.isInteger(port)) ports.push(port);
+ }
+ return ports;
+}
+
 // A stop asks every launch started before it to end. A worker reads this right
 // after it claims the launch; a stop that ran before the claim found no worker
 // to signal, so the worker ends itself here instead of starting anything.

package/global/main.mjs

@@ -1,14 +1,14 @@
+import { verbs } from '../cli/contract.mjs';
 import { dispatcher, locate, pinnedPackage, unsupportedMessage } from './checkout.mjs';
 import { delegate } from './delegate.mjs';
 import { localDefaults } from './launch/local-defaults.mjs';
 import { handleBrokenPipes } from './output.mjs';
-import { packageName as pinnedName } from './package-info.mjs';
 
 const help = `Usage: rer VERB [FLAGS]
 
 Inside a project (the nearest OPERATIONS.json at or above this folder, or --cwd DIR),
 every verb runs that checkout's own pinned rer: the @runeditrun/rer version its package.json
-pins (installed first by rer install, rer setup or rer dev), else its vendored scripts/rer.mjs.
+pins (installed first by any verb when node_modules holds another), else its vendored scripts/rer.mjs.
 
   rer dev              Launch a first-party checkout with no setup steps: installs dependencies,
                        sets up a local owner and a free port when needed, starts the app and prints
@@ -30,12 +30,13 @@ pins (installed first by rer install, rer setup or rer dev), else its vendored s
                        Run COMMAND once this computer's job queue admits it (heavy package scripts
                        of a checkout that pins the rer package use it).
 
-Checkout verbs: install, setup, dev, preview, build, verify, reset, deploy, export, import,
+Checkout verbs: install, setup, dev, demo, preview, build, verify, reset, deploy, export, import,
 outbox, doctor, describe, check, release. Run rer VERB --help in a checkout for its flags.
 `;
 
-// The verbs that install an uninstalled pinned package before they run.
-const installsFirst = new Set(['install', 'setup', 'check', 'describe']);
+// The checkout verbs that install the pinned package before they run when
+// node_modules holds another version or none (dev installs it in its launch).
+const installsFirst = new Set([...Object.keys(verbs), 'release'].filter(verb => verb !== 'dev'));
 
 export async function main(argv) {
  handleBrokenPipes();
@@ -86,23 +87,20 @@ export async function main(argv) {
   return (await import('../onboarding/queued-entry.mjs')).queuedCommandLine(argv.slice(1));
  }
  // A checkout that pins its own rer package runs all of it, launching included.
- // Until node_modules holds the pinned version, install, setup, check and describe
- // install it with the frozen lockfile (then run the pinned verb, so a fresh
- // clone checks with the pinned bytes), the zero-setup launch installs it
- // first, and every other verb says to install.
+ // Until node_modules holds the pinned version (a fresh clone, or a pulled pin
+ // change), every checkout verb installs it with the frozen lockfile and then
+ // runs the pinned verb, so a fresh clone checks and a changed pin deploys with
+ // the pinned bytes; the zero-setup launch installs it first.
+ // Verbs started at once share one install, and one whose pin already looks
+ // installed waits for an install still running.
  const pinned = first && mode !== 'package' ? pinnedPackage(target.root) : undefined;
- if (pinned && !pinned.ready && !argv.includes('--help')) {
-  if (installsFirst.has(verb)) {
-   const { installPinned } = await import('./launch/install-pinned.mjs'), { LaunchFailure } = await import('./launch/failure.mjs');
-   try { await installPinned(target.root); }
-   catch (failure) { if (!(failure instanceof LaunchFailure)) throw failure; process.stderr.write(failure.message + '\n'); return failure.exitCode; }
-   return delegate(target, target.args);
-  }
-  if (verb !== 'dev') {
-   process.stderr.write(`${target.root} pins ${pinnedName} ${pinned.declared}, ${pinned.installed ? `but node_modules holds ${pinned.installed}` : 'which is not installed yet'}. Run rer install, then rer ${verb} again.\n`);
-   return 3;
-  }
+ if (pinned && !pinned.ready && !argv.includes('--help') && installsFirst.has(verb)) {
+  const { installPinned } = await import('./launch/install-pinned.mjs'), { LaunchFailure } = await import('./launch/failure.mjs');
+  try { await installPinned(target.root); }
+  catch (failure) { if (!(failure instanceof LaunchFailure)) throw failure; process.stderr.write(failure.message + '\n'); return failure.exitCode; }
+  return delegate(target, target.args);
  }
+ if (mode === 'package' && installsFirst.has(verb)) await (await import('./launch/install-pinned.mjs')).settledPin(target.root);
  if (verb === 'dev' && mode && mode !== 'package' && !argv.includes('--help')) return (await import('./launch/dev.mjs')).launchDev(target);
  // Every other server start or queued job on a vendored pin gets the person
  // defaults too (a pinned package applies its own).

package/global/update/command.mjs

@@ -8,6 +8,7 @@ import { spawn } from 'node:child_process';
 import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
+import { dependencyEnvironment } from '../../onboarding/dependency-environment.mjs';
 import { layout } from '../cli/layout.mjs';
 import { channelOf } from '../cli/status.mjs';
 import { ownManifest, ownRoot, packageDigest, packageName } from '../package-info.mjs';
@@ -47,7 +48,7 @@ async function npmGlobal(version) {
  const command = `npm ${args.map(arg => /^[\w@./:=-]+$/.test(arg) ? arg : JSON.stringify(arg)).join(' ')}`;
  process.stdout.write(`Updating the npm global rer: ${command}\n`);
  let code;
- try { code = await run('npm', args); } catch (error) { code = 127; process.stderr.write(`Could not run npm (${error.code ?? error.message}).\n`); }
+ try { code = await run('npm', args, dependencyEnvironment()); } catch (error) { code = 127; process.stderr.write(`Could not run npm (${error.code ?? error.message}).\n`); }
  if (code !== 0) {
   process.stderr.write(`npm could not update rer (exit ${code}); rer is unchanged. Fix the problem npm reports (for example, a prefix you cannot write), then run:\n  ${command}\n`);
   return code || 1;

package/modules/container/README.md

@@ -13,7 +13,9 @@ selected through `cacheContract` when the seed implements that contract. This
 is not a general Durable Object adapter. A seed requiring KV or other
 Cloudflare-only APIs cannot use Node.
 The import boundary rejects those APIs and new Cloudflare imports outside the
-platform binding/cache boundary.
+platform binding/cache boundary. The one other file it admits is an exported
+seed's demo guard, `src/modules/demo/index.mjs`, and there only
+`import { env } from 'cloudflare:workers'` (it reads `RER_DEMO`).
 
 The entrypoint holds a Linux kernel `flock` for the lifetime of the host. Each
 installation has one local data volume and one writer. The lock inode retains

package/modules/container/boundary.mjs

@@ -1,5 +1,5 @@
 import { readdir, readFile } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { join, relative, sep } from 'node:path';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 export async function checkBoundary(root, { engine='node', cacheContract }={}) {
@@ -10,6 +10,9 @@ export async function checkBoundary(root, { engine='node', cacheContract }={}) {
    const name=relative(root,path),tree=ts.createSourceFile(path,await readFile(path,'utf8'),ts.ScriptTarget.Latest,true);
    const cache=cacheContract==='lamp-retained-v1'&&/(?:^|\/)platform\/blobs\/snapshot-cache\.ts$/.test(name);
    const bindings=/(?:^|\/)platform\/bindings\.server\.ts$/.test(name);
+   // The demo guard an exported seed carries reads RER_DEMO from env: that one
+   // file, and only its unrenamed `env` import.
+   const demo=name.split(sep).join('/')==='src/modules/demo/index.mjs';
    const fail=api=>failures.push({path:name,api}),localNames=new Set();
    function names(node){if((ts.isVariableDeclaration(node)||ts.isFunctionDeclaration(node)||ts.isImportSpecifier(node))&&node.name&&ts.isIdentifier(node.name))localNames.add(node.name.text);ts.forEachChild(node,names);}names(tree);
    function visit(node){
@@ -17,7 +20,7 @@ export async function checkBoundary(root, { engine='node', cacheContract }={}) {
      const module=node.moduleSpecifier.text;
      if(module.startsWith('cloudflare:')){
       const imports=node.importClause?.namedBindings;
-      const allowed=module==='cloudflare:workers'&&imports&&ts.isNamedImports(imports)&&imports.elements.every(element=>(bindings&&(element.propertyName??element.name).text==='env')||(cache&&(element.propertyName??element.name).text==='DurableObject'));
+      const allowed=module==='cloudflare:workers'&&imports&&ts.isNamedImports(imports)&&imports.elements.every(element=>(demo&&!node.importClause.name&&!element.propertyName&&element.name.text==='env')||(bindings&&(element.propertyName??element.name).text==='env')||(cache&&(element.propertyName??element.name).text==='DurableObject'));
       if(!allowed)fail('Cloudflare import outside binding/cache contract');
      }
     }

package/modules/container/build.mjs

@@ -6,6 +6,7 @@ import { createHash } from 'node:crypto';
 import { parseJsonc } from '../../cli/jsonc.mjs';
 import { portabilityPlan } from './portability-schema.mjs';
 import { checkBoundary } from './boundary.mjs';
+import { readMigrationRewrites, withRewrites } from '../deploy-kit/migrations.mjs';
 const hash = source => createHash('sha256').update(source).digest('hex');
 export async function buildContainer(root, options={}) {
  const previous=process.cwd();process.chdir(root);
@@ -36,12 +37,13 @@ async function buildImage(root, { output = join(root,'.rer/container/image'), en
  if (engine === 'workerd') workerConfig = JSON.parse(await readFile(join(root,'dist/server/wrangler.json'),'utf8'));
  else workerConfig = parseJsonc(await readFile(join(root,'wrangler.jsonc'),'utf8'));
  const { unstable_splitSqlQuery:split } = require('wrangler');
- const migrations = {};
+ const migrations = {}, rewrites = await readMigrationRewrites(root);
  for (const db of workerConfig.d1_databases ?? []) {
   let directory = resolve(root,db.migrations_dir ?? 'migrations');
   try { await readdir(directory); } catch { directory = resolve(root,'dist/server',db.migrations_dir); }
   migrations[db.binding] = [];
   for (const name of (await readdir(directory)).filter(name => name.endsWith('.sql')).sort()) { const sql = await readFile(join(directory,name),'utf8'); migrations[db.binding].push({ name,sql,sha256:hash(sql),statements:split(sql) }); }
+  migrations[db.binding] = withRewrites(migrations[db.binding], rewrites, { partial:true });
  }
  const entry = engine === 'workerd' ? 'dist/server/'+workerConfig.main : 'dist/server/index.mjs';
  await readFile(join(root,entry));
@@ -62,4 +64,4 @@ async function buildImage(root, { output = join(root,'.rer/container/image'), en
  await writeFile(join(output,'Dockerfile'),`FROM node:26.8.1-bookworm-slim\nRUN apt-get update && apt-get install -y --no-install-recommends util-linux ca-certificates && apt-get clean\nRUN mkdir -p /private /archive\nWORKDIR /runtime\nCOPY runtime/package.json ./package.json\nRUN npm install --omit=dev --no-audit --no-fund\nCOPY runtime/ /runtime/\nCOPY app/ /app/\nENV NODE_ENV=production PORT=8080 WRANGLER_SEND_METRICS=false\nEXPOSE 8080\nVOLUME /data\nENTRYPOINT ["sh", "/runtime/modules/container/entrypoint.sh"]\n`);
  return { output,manifest };
 }
-if (process.argv[1] === import.meta.filename) { try { const result=await buildContainer(resolve(process.argv[2])); console.log(JSON.stringify({output:result.output,engine:result.manifest.engine})); } catch(cause) { console.error(cause.message); if(cause.failures)console.error(JSON.stringify(cause.failures));process.exitCode=1; } }
+if (process.argv[1] === import.meta.filename) { try { const {output,engine}=JSON.parse(process.argv[3]??'{}'),result=await buildContainer(resolve(process.argv[2]),{...(output?{output:resolve(output)}:{}),...(engine?{engine}:{})}); console.log(JSON.stringify({output:result.output,engine:result.manifest.engine})); } catch(cause) { console.error(cause.message); if(cause.failures)console.error(JSON.stringify(cause.failures));process.exitCode=1; } }

package/modules/container/host.mjs

@@ -18,7 +18,7 @@ export async function startHost({ root = '/app', data = '/data', settings = proc
   server = createServer(async (req, res) => {
    try {
     lastRequest=Date.now();
-    const request = await incoming(req, { trustedProxy:settings.TRUSTED_PROXY, maxRequestBytes:manifest.maxRequestBytes });
+    const request = await incoming(req, { trustedProxy:settings.TRUSTED_PROXY, origin:settings.RER_INGRESS_ORIGIN, maxRequestBytes:manifest.maxRequestBytes });
     let response = await engine.fetch(request);
     if (new URL(request.url).pathname === '/health' && response.ok) {
      const body = await response.json(); const deadJobs = engine.dead();

package/modules/container/ingress.mjs

@@ -1,12 +1,15 @@
 import { Readable } from 'node:stream';
 import { lookup } from 'node:dns/promises';
 import { isIP } from 'node:net';
-export async function incoming(req, { trustedProxy, maxRequestBytes = 25 * 1024 * 1024 } = {}) {
+// `origin` (RER_INGRESS_ORIGIN) fixes the public origin for a container whose only
+// peer is its own front, such as a hosted demo's Durable Object.
+export async function incoming(req, { trustedProxy, origin, maxRequestBytes = 25 * 1024 * 1024 } = {}) {
  const headers = new Headers(); for (const [name, value] of Object.entries(req.headers)) if (value !== undefined) headers.set(name, Array.isArray(value) ? value.join(',') : value);
  const peer = req.socket.remoteAddress?.replace('::ffff:', '') ?? '';
  const trusted = trustedProxy && (isIP(trustedProxy) ? peer===trustedProxy : (await lookup(trustedProxy,{all:true})).some(item=>item.address.replace('::ffff:','')===peer));
  let host = req.headers.host, proto = 'http', address = peer;
  if (trusted) { host = req.headers['x-forwarded-host'] ?? host; proto = req.headers['x-forwarded-proto'] ?? proto; address = req.headers['x-forwarded-for']?.split(',').at(-1)?.trim() ?? peer; }
+ if (origin) { const fixed = new URL(origin); host = fixed.host; proto = fixed.protocol.slice(0, -1); }
  for (const name of ['cf-connecting-ip','x-forwarded-host','x-forwarded-proto','x-forwarded-for','forwarded','x-rer-original-url']) headers.delete(name);
  if (!['http', 'https'].includes(proto) || typeof host !== 'string' || !/^(?:[a-zA-Z0-9.-]+|\[[0-9a-fA-F:]+\])(?::[0-9]+)?$/.test(host)) throw new Error('Invalid ingress origin');
  headers.set('cf-connecting-ip', address); headers.set('host', host);

package/modules/container/migrations.mjs

@@ -1,10 +1,11 @@
 import { validateMigrations } from '../deploy-kit/migrations.mjs';
+import { recorded } from '../deploy-kit/migration-ledger.mjs';
 export async function migrate(db, migrations, { ledger = '_rer_deploy_migrations' } = {}) {
  if (!['_rer_deploy_migrations', '_rer_portability_migrations'].includes(ledger)) throw new Error('Invalid migration ledger');
  validateMigrations(migrations);
  await db.prepare(`CREATE TABLE IF NOT EXISTS ${ledger}(name TEXT PRIMARY KEY,sha256 TEXT NOT NULL,state TEXT NOT NULL CHECK(state IN ('applying','applied')))`).run();
  const history = (await db.prepare(`SELECT name,sha256,state FROM ${ledger} ORDER BY name`).all()).results;
- if (history.some((row, i) => row.name !== migrations[i]?.name || row.sha256 !== migrations[i]?.sha256 || row.state !== 'applied')) throw new Error('changed-or-uncertain-migration-history');
+ if (history.some((row, i) => !recorded(row, migrations[i]) || row.state !== 'applied')) throw new Error('changed-or-uncertain-migration-history');
  const legacy = await db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='d1_migrations'").first();
  if (ledger === '_rer_deploy_migrations' && legacy && (await db.prepare('SELECT name FROM d1_migrations ORDER BY id').all()).results.some(row => !history.some(prior => prior.name === row.name))) throw new Error('legacy-migration-history-needs-reviewed-hash-adoption');
  for (const migration of migrations.slice(history.length)) {

package/modules/container/worker-engine.mjs

@@ -19,7 +19,9 @@ export async function workerEngine({ root, data, manifest, settings, edge }) {
  };
  const mf = new Miniflare(convertV4MiniflareOptions({ host:'127.0.0.1',port:0,cf:false,resourcePersistencePath:data,unsafeLocalExplorer:false,
   workers:[{ name:'ingress',modules:true,script:`export default {fetch(request,env){const observed=request.headers.get('x-rer-original-url');if(!observed)return new Response(null,{status:400});const url=new URL(observed),headers=new Headers(request.headers);headers.delete('x-rer-original-url');headers.set('host',url.host);return env.APP.fetch(new Request(url,{method:request.method,headers,redirect:'manual',...(!['GET','HEAD'].includes(request.method)?{body:request.body}:{})}))}}`,serviceBindings:{ APP:'app' } }, app,
-   { name:'egress',modules:true,script:'export default {fetch(request,env){return env.NETWORK.fetch(request)}}',serviceBindings:{ NETWORK:{ network:{ allow:['public'],tlsOptions:{ trustBrowserCas:true,trustedCertificates:[...rootCertificates] } } } } }],
+   // A demo (RER_DEMO=1) sends nothing: its egress worker refuses every request.
+   settings.RER_DEMO === '1' ? { name:'egress',modules:true,script:"export default {fetch(request){throw new TypeError('fetch failed: demo egress is denied ('+new URL(request.url).host+')')}}" }
+    : { name:'egress',modules:true,script:'export default {fetch(request,env){return env.NETWORK.fetch(request)}}',serviceBindings:{ NETWORK:{ network:{ allow:['public'],tlsOptions:{ trustBrowserCas:true,trustedCertificates:[...rootCertificates] } } } } }],
  }));
  await mf.ready; const databases = {}, objects = {};
  for (const [binding, plan] of Object.entries(manifest.migrations)) { const db = await mf.getD1Database(binding, 'app'); databases[binding] = db; await migrate(db, plan); await ensurePortabilitySchema(db, manifest.portabilityMigrations); }

package/modules/demo-host/README.md

@@ -0,0 +1,30 @@
+# Hosted demo
+
+The front Worker `rer deploy --demo` deploys at `demo.<domain>` for a seed
+that adopted demo mode (`withDemo`, export/DEMO.md). `plan.mjs` turns `deploy-demo.json`
+into the Worker's Wrangler configuration; the CLI (`cli/demo-host.mjs`) writes
+it with these files and the seed's container image folder (workerd engine) to
+`.rer/demo-host/` and runs `wrangler deploy` there.
+
+- `worker.mjs`: `GET /` is the start page; `POST /__demo/start` checks the
+  exact Origin, the `STARTS` rate limit (3 per IP per 60 s), Turnstile's
+  siteverify and capacity, then starts the visitor's demo and answers with the
+  owner claim's 303, its session cookie and the `rer_demo` cookie. A request
+  with that cookie goes to the visitor's Durable Object; nothing else reaches
+  a container.
+- `container.mjs`: `DemoContainer`, one per visitor (`newUniqueId`, checked
+  with `idFromString`). It starts the container with `enableInternet: false`,
+  `RER_DEMO=1`, the fixed origin (`RER_INGRESS_ORIGIN` and the seed's origin
+  variable), fresh `SESSION_SECRET` and `SETUP_TOKEN`,
+  `OWNER_EMAIL=owner@demo.invalid` and the owner claim's issuer, installation
+  id and public key; waits for `/health`; and posts a five-minute ES256 claim
+  (`claim.mjs`) to `/auth/owner-claim`. Its alarm ends the demo at its hour or
+  after 15 idle minutes: `destroy()`, `deleteAll()` and the place released. A
+  container that stops by itself ends its demo too.
+- `capacity.mjs`: `DemoCapacity` admits at most `max_instances` live demos.
+- `pages.mjs`: the start and ended pages (12ui designs), strict CSP.
+
+`node --test modules/demo-host/tests/*.test.mjs` runs the Worker in workerd
+with its real Durable Objects and rate limit; Turnstile and the container
+platform are the only fakes. The end-to-end proof (`wrangler dev` with Docker)
+is in DEMO.md.