@runeditrun/rer 0.1.0 → 0.2.0

package/global/launch/dev.mjs

@@ -10,13 +10,14 @@ import { open, realpath, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { processInfo } from '../../modules/job-queue/processes.mjs';
 import { dispatcher } from '../checkout.mjs';
 import { delegate } from '../delegate.mjs';
 import { ownRoot } from '../package-info.mjs';
 import { LaunchFailure } from './failure.mjs';
+import { describeCheckout } from './facts.mjs';
 import { prepare } from './prepare.mjs';
 import { printer } from './render.mjs';
+import { stopLaunch } from './stop.mjs';
 import { launchDirectory, liveWorker } from './state.mjs';
 
 const workerPath = fileURLToPath(new URL('./worker.mjs', import.meta.url));
@@ -24,19 +25,30 @@ const workerPath = fileURLToPath(new URL('./worker.mjs', import.meta.url));
 export async function launchDev(target) {
  const args = target.args.slice(1);
  if (args.includes('--detach') && args.includes('--foreground')) { process.stderr.write('Choose one of --detach and --foreground.\n'); return 2; }
- const devArgs = args.filter(arg => arg !== '--detach' && arg !== '--foreground');
+ // --door-start: the front door is starting this checkout (internal).
+ const doorStart = args.includes('--door-start');
+ const devArgs = args.filter(arg => !['--detach', '--foreground', '--door-start'].includes(arg));
+ // A pin from before the front door cannot move to it: say so in one line.
+ if ((devArgs.includes('--door') || devArgs.includes('--direct')) && !await doorCapable(target.root)) {
+  process.stderr.write('This checkout\'s pinned Base has no front-door support, so it stays direct. Refresh its Base to serve it through the door; rer door add still lists it and starts it on a visit.\n');
+  return 2;
+ }
  // An invocation the pinned dispatcher refuses goes straight to it, so the
  // refusal is its own, with nothing prepared first.
  if (!await accepted(target.root, devArgs)) return delegate(target, ['dev', ...devArgs]);
  const checkout = await realpath(target.root), directory = await launchDirectory(checkout);
  if (devArgs.includes('--stop')) {
-  try { await stopWorker(directory); } catch (failure) { process.stderr.write(failure.message + '\n'); return failure.exitCode ?? 1; }
-  return delegate(target, ['dev', ...devArgs]);
+  try { return await stopLaunch(target, devArgs, { checkout, directory }); }
+  catch (failure) { if (!(failure instanceof LaunchFailure)) throw failure; process.stderr.write(failure.message + '\n'); return failure.exitCode; }
  }
  const here = await realpath(process.cwd()).catch(() => undefined);
- const out = printer({ json: devArgs.includes('--json'), login: devArgs.includes('--login'), stopHint: `rer dev --stop${here === checkout ? '' : ` --cwd ${JSON.stringify(checkout)}`}` });
+ const out = printer({ json: devArgs.includes('--json'), login: devArgs.includes('--login'), stopHint: `rer dev --stop${here === checkout ? '' : ` --cwd ${JSON.stringify(checkout)}`}`, keyless: doorStart });
  const detach = args.includes('--detach') || (!args.includes('--foreground') && !process.stdout.isTTY);
- return detach ? detached(target, devArgs, directory, out) : foreground(target, devArgs, directory, out);
+ return detach ? detached(target, devArgs, directory, out, doorStart) : foreground(target, devArgs, directory, out, doorStart);
+}
+
+async function doorCapable(root) {
+ try { return Boolean((await describeCheckout(root, dispatcher(root).entry, process.env)).door); } catch { return true; }
 }
 
 async function accepted(root, devArgs) {
@@ -45,7 +57,7 @@ async function accepted(root, devArgs) {
  try { (await import(pathToFileURL(parser).href)).parse(['dev', ...devArgs], process.cwd()); return true; } catch { return false; }
 }
 
-async function foreground(target, devArgs, directory, out) {
+async function foreground(target, devArgs, directory, out, doorStart) {
  const holder = await liveWorker(directory);
  if (holder) {
   out.attaching(holder.startedAt);
@@ -56,20 +68,22 @@ async function foreground(target, devArgs, directory, out) {
  let prepared;
  // The same progress lines as a detached launch while install or setup runs.
  const heartbeat = setInterval(() => out.heartbeat(), 1000);
- try { prepared = await prepare({ root: target.root, args: devArgs, env: process.env, report: fields => out.phase(fields), directory, log: text => log.write(text + '\n'), children: new Set() }); }
+ try { prepared = await prepare({ root: target.root, args: devArgs, env: process.env, report: fields => out.phase(fields), directory, log: text => log.write(text + '\n'), children: new Set(), doorStart }); }
  catch (failure) { if (!(failure instanceof LaunchFailure)) throw failure; out.failure(failure); return failure.exitCode; }
  finally { clearInterval(heartbeat); log.end(); }
  Object.assign(process.env, prepared.added);
  return delegate(target, ['dev', ...devArgs]);
 }
 
-async function detached(target, devArgs, directory, out) {
+async function detached(target, devArgs, directory, out, doorStart) {
  let token, worker;
  const holder = await liveWorker(directory);
  if (holder) { token = holder.token; out.attaching(holder.startedAt); }
  else {
   token = randomUUID();
-  worker = spawn(process.execPath, [workerPath, target.root, token, JSON.stringify(devArgs.filter(arg => arg !== '--json'))], { cwd: target.root, env: process.env, detached: true, stdio: 'ignore' });
+  // The worker ends itself for a stop that ran after this command started.
+  worker = spawn(process.execPath, [workerPath, target.root, token, JSON.stringify(devArgs.filter(arg => arg !== '--json')), String(performance.timeOrigin), ...(doorStart ? ['door-start'] : [])], { cwd: target.root, env: process.env, detached: true, stdio: 'ignore' });
+  worker.once('error', () => {});
   worker.unref();
  }
  return follow(directory, token, out, { worker });
@@ -81,6 +95,7 @@ async function follow(directory, token, out, { worker, quiet = false }) {
  const path = join(directory, `events-${token}.jsonl`);
  let offset = 0, rest = '', exited = false, missingSince, polls = 0;
  worker?.once('exit', () => { exited = true; });
+ worker?.once('error', () => { exited = true; });
  for (;;) {
   let size = 0;
   try { size = (await stat(path)).size; } catch (error) { if (error.code !== 'ENOENT') throw error; }
@@ -114,16 +129,3 @@ function missing(directory) {
  process.stderr.write(`rer dev: the launch stopped before it finished. Run rer dev again; its log is ${join(directory, 'launch.log')}.\n`);
  return 1;
 }
-
-// rer dev --stop also ends a preparation still running for this checkout.
-async function stopWorker(directory) {
- const holder = await liveWorker(directory);
- if (!holder) return;
- try { process.kill(holder.pid, 'SIGTERM'); } catch (error) { if (error.code === 'ESRCH') return; throw error; }
- for (let waited = 0; waited < 60000; waited += 250) {
-  const current = await processInfo(holder.pid);
-  if (!current || current.zombie || current.start !== holder.start) return;
-  await delay(250);
- }
- throw new LaunchFailure(1, `The launch worker (PID ${holder.pid}) did not stop within a minute.`);
-}

package/global/launch/door.mjs

@@ -0,0 +1,36 @@
+// What the front door means for one `rer dev`. With the door enabled, a fresh
+// checkout whose pin supports it is set up at its door origin; a checkout
+// already there needs the door running, which `rer dev` brings back only for
+// the registry the door recorded (a fleet agent or a test with its own
+// RER_DOOR_DIR or RER_SERVERS_DIR never starts the owner's door). --port,
+// --host and --direct always mean direct mode.
+import { doorProtocol, doorSite, readDoorState, runningDoor } from '../../cli/door.mjs';
+import { startDoor } from '../door/control.mjs';
+import { ownsRegistry } from '../door/policy.mjs';
+import { LaunchFailure } from './failure.mjs';
+
+const has = (args, flag) => args.includes(flag);
+
+export async function doorPlan(described, args, env) {
+ const capable = described?.door?.protocol === doorProtocol;
+ const direct = has(args, '--direct') || has(args, '--port') || has(args, '--host');
+ const state = await readDoorState(env).catch(() => undefined), door = state?.door;
+ const running = door?.enabled ? await runningDoor(env).catch(() => undefined) : undefined;
+ const protocol = running?.protocol ?? door?.protocol;
+ const known = Boolean(door?.enabled) && protocol === doorProtocol;
+ const note = door?.enabled && !known ? `The front door speaks protocol ${protocol}, which this rer does not know, so this checkout stays direct. Run rer door restart.` : undefined;
+ const saved = Boolean(described?.local?.origin && doorSite(described.local.origin));
+ return { door, known, note, freshAtDoor: known && capable && !direct, atDoor: !direct && (saved || has(args, '--door')) };
+}
+
+// Bring an enabled door back before a door-mode checkout starts.
+export async function bringBackDoor(plan, env, report) {
+ if (!plan.atDoor || !plan.door?.enabled || !plan.known) return;
+ if (await runningDoor(env)) return;
+ if (!ownsRegistry(plan.door, env)) {
+  report({ phase: 'note', message: 'the front door is not running and this shell uses another RER_DOOR_DIR or RER_SERVERS_DIR than the one it recorded, so it was not started' });
+  return;
+ }
+ report({ phase: 'door', message: 'starting the front door (it was not running)' });
+ try { await startDoor(env); } catch (error) { throw new LaunchFailure(error.exitCode ?? 1, error.message); }
+}

package/global/launch/facts.mjs

@@ -11,11 +11,12 @@ const run = promisify(execFile);
 async function mtime(path) { try { return (await stat(path)).mtimeMs; } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; } }
 
 // The pinned dispatcher's own read-only description.
-export async function describeCheckout(root, entry, env) {
+export async function describeCheckout(root, entry, env, signal) {
  try {
-  const { stdout } = await run(process.execPath, [entry, 'describe', '--json'], { cwd: root, env, maxBuffer: 16 * 1024 * 1024 });
+  const { stdout } = await run(process.execPath, [entry, 'describe', '--json'], { cwd: root, env, maxBuffer: 16 * 1024 * 1024, signal });
   return JSON.parse(stdout);
  } catch (error) {
+  if (signal?.aborted) throw signal.reason;
   throw new LaunchFailure(error.code ?? 1, (error.stderr?.trim() || `rer describe failed in ${root}.`));
  }
 }

package/global/launch/install-pinned.mjs

@@ -0,0 +1,22 @@
+// 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.
+import { spawn } from 'node:child_process';
+import { pinnedPackage } from '../checkout.mjs';
+import { packageName } from '../package-info.mjs';
+import { LaunchFailure } from './failure.mjs';
+
+export async function installPinned(root, { env = process.env, output = text => process.stderr.write(text), children, signal } = {}) {
+ signal?.throwIfAborted();
+ const child = spawn('pnpm', ['install', '--frozen-lockfile'], { cwd: root, env: { ...env, CI: 'true' }, stdio: ['ignore', 'pipe', 'pipe'] });
+ children?.add(child);
+ if (signal?.aborted) child.kill('SIGTERM');
+ let tail = '';
+ for (const stream of [child.stdout, child.stderr]) stream.on('data', data => { tail = (tail + data).slice(-4096); output(String(data)); });
+ const code = await new Promise((resolve, reject) => { child.once('error', reject); child.once('close', (exit, name) => resolve(exit ?? (name ? 128 : 1))); });
+ children?.delete(child);
+ if (code !== 0) throw new LaunchFailure(code, `pnpm install --frozen-lockfile failed in ${root} (exit ${code}):\n${tail.trim().split('\n').slice(-8).join('\n')}`);
+ const pinned = pinnedPackage(root);
+ if (!pinned?.ready) throw new LaunchFailure(3, `${root} pins ${packageName} ${pinned?.declared}, but after pnpm install node_modules holds ${pinned?.installed ?? 'no copy of it'}. Correct the pin or the lockfile (pnpm install), then run rer again.`);
+}

package/global/launch/prepare.mjs

@@ -5,39 +5,73 @@
 // settings are never changed. An install or setup this launcher started and
 // that did not finish runs again on the next launch.
 import { realpath } from 'node:fs/promises';
-import { dispatcher } from '../checkout.mjs';
+import { dispatcher, pinnedPackage } from '../checkout.mjs';
 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 { runVerb } from './steps.mjs';
 import { localDefaults } from './local-defaults.mjs';
+import { installPinned } from './install-pinned.mjs';
 
 // The value given for a flag in the user's dev arguments.
 export const flagValue = (args, flag) => { const index = args.indexOf(flag); return index < 0 ? undefined : args[index + 1]; };
 
-export async function prepare({ root, args, env, report, directory, log, children }) {
+// A worker passes the signal a stop aborts: no step starts after it, and the
+// step running then is signalled through `children`. `doorStart`: the front
+// door is starting this checkout on a visit, which never installs or sets up;
+// an unprepared checkout is refused with the reason.
+export async function prepare({ root, args, env, report, directory, log, children, signal, doorStart = false }) {
+ // A checkout pinning the rer package whose node_modules lacks that version
+ // installs it first (after the same quick server-limit check: a pin with
+ // package mode has the person defaults); every step after this runs the
+ // pinned package's verbs.
+ let installed = false;
+ if (pinnedPackage(root)?.ready === false) {
+  if (doorStart) throw new LaunchFailure(3, `${root} is not installed, and the front door starts only prepared checkouts. Run rer dev in it once.`);
+  const current = await pinPolicy(root, 'package');
+  report({ phase: 'check', message: 'checking the server limit' });
+  const capacity = await checkCapacity(await realpath(root), { ...env, ...personEnvironment(env, args, current) }, current);
+  if (capacity.own) throw new LaunchFailure(3, `A server of ${root} is running, but its node_modules lacks the rer version it pins. Stop it with rer dev --stop, then run rer dev again.`);
+  report({ phase: 'install', message: 'installing dependencies' });
+  await recorded(directory, installState, () => installPinned(root, { env, output: text => log(text.trimEnd()), children, signal }));
+  installed = true;
+ }
  const checkout = await realpath(root), { mode, entry } = dispatcher(root);
- const described = await describeCheckout(root, entry, env);
+ const described = await describeCheckout(root, entry, env, signal);
  const pin = await pinPolicy(root, mode, described);
  const added = personEnvironment(env, args, pin), childEnv = { ...env, ...added };
+ const plan = await doorPlan(described, args, env);
+ if (plan.note) report({ phase: 'note', message: plan.note });
  report({ phase: 'check', message: 'checking the server limit' });
  const capacity = await checkCapacity(checkout, childEnv, pin);
- if (capacity.own) return { entry, added, own: capacity.own };
+ if (capacity.own) { await bringBackDoor(plan, env, report); return { entry, added, own: capacity.own }; }
  const note = message => report({ phase: 'note', message });
- const step = (record, args, fields, env = childEnv) => recorded(directory, record, () => runVerb(entry, args, { root, env, note, log, children }), fields);
+ const step = (record, args, fields, env = childEnv) => recorded(directory, record, () => runVerb(entry, args, { root, env, note, log, children, signal }), fields);
  // Only this setup fills the seed's declared local defaults.
  const setupEnv = { ...childEnv, [localDefaults]: '1' };
- if (await needsInstall(root, await installState.read(directory))) {
+ const unprepared = what => new LaunchFailure(3, `${checkout} is not ${what}, and the front door starts only prepared checkouts. Run rer dev in it once.`);
+ if (!installed && await needsInstall(root, await installState.read(directory))) {
+  if (doorStart) throw unprepared('installed');
   report({ phase: 'install', message: 'installing dependencies' });
   await step(installState, ['install']);
  }
  const last = await setupState.read(directory), setup = await setupNeeded(root, described, last);
+ if (setup && doorStart) throw unprepared('set up');
  const host = flagValue(args, '--host'), hostArgs = host ? ['--host', host] : [];
  if (setup === 'resume') {
   // Saved settings hold an owner and origin; setup keeps them.
   report({ phase: 'setup', message: 'finishing this checkout\'s setup, keeping its saved owner and port' });
   await step(setupState, ['setup', ...hostArgs], {}, setupEnv);
+ } else if (setup === 'fresh' && plan.freshAtDoor) {
+  // With the door enabled, a fresh checkout is set up at its door origin.
+  const owner = localOwner(checkout);
+  report({ phase: 'setup', message: `setting up a local owner (${owner}) at its front-door address` });
+  await step(setupState, ['setup', '--owner-email', owner, '--door'], { owner, door: true }, setupEnv);
+  await bringBackDoor({ ...plan, atDoor: true }, env, report);
+  return { entry, added };
  } else if (setup === 'fresh') {
   // An interrupted setup resumes on the port it chose while that port is free.
   const owner = localOwner(checkout), explicit = flagValue(args, '--port');
@@ -48,6 +82,7 @@ export async function prepare({ root, args, env, report, directory, log, childre
   // 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/render.mjs

@@ -3,7 +3,9 @@
 const elapsed = ms => { const s = Math.round(ms / 1000); return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`; };
 const quiet = 20000;
 
-export function printer({ json, login, stopHint }) {
+// `keyless` (a start by the front door, whose log this is): the ready lines
+// leave out the dev-key link, so the door's files never hold a key.
+export function printer({ json, login, stopHint, keyless = false }) {
  const started = Date.now();
  let current = 'preparing', last = Date.now();
  const event = (name, fields) => process.stdout.write(JSON.stringify({ version: 1, verb: 'dev', event: name, ...fields }) + '\n');
@@ -19,6 +21,7 @@ export function printer({ json, login, stopHint }) {
   heartbeat() { if (Date.now() - last >= quiet) progress('waiting', `still ${current} (${elapsed(Date.now() - started)}). Allow up to 10 minutes; if this command is stopped, run rer dev again to reattach.`); },
   // The dispatcher's ready event, as its own human ready lines.
   ready(ready, { log, pid }) {
+   if (keyless) { const { openUrl, ...rest } = ready; ready = rest; }
    if (json) { event('server', { pid, log }); process.stdout.write(JSON.stringify(ready) + '\n'); return; }
    const out = [`RER_READY ${ready.url}`];
    if (ready.openUrl && !login) {
@@ -29,6 +32,8 @@ export function printer({ json, login, stopHint }) {
     if (ready.openUrl) out.push(`RER_OPEN ${ready.openUrl}`);
     out.push(`Open ${ready.openUrl ? 'the last link on this computer (it carries the dev key; never share it)' : 'the outbox'}, choose the newest sign-in message and follow its link. No email was sent.`);
    }
+   // A seed with a run site: its static homepage, /run and docs, served locally.
+   if (ready.siteUrl) out.push(`RER_SITE ${ready.siteUrl}`);
    out.push(`The server keeps running in the background${pid ? ` (PID ${pid})` : ''}. Stop it with: ${stopHint}`);
    if (log) out.push(`Server log (private): ${log}`);
    process.stdout.write(out.join('\n') + '\n');

package/global/launch/state.mjs

@@ -6,7 +6,8 @@
 //   setup.json    whether a setup this launcher started has finished
 //   launch.log    the worker's private log (child output)
 //   server.log    the private log of the server rer started
-//   server.json   that server's PID
+//   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
 import { createHash } from 'node:crypto';
 import { appendFile, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
@@ -91,6 +92,14 @@ const stepRecord = name => ({
 });
 export const installState = stepRecord('install'), setupState = stepRecord('setup');
 
+// 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.
+export const stopRequest = {
+ write: directory => writeFile(join(directory, 'stop.json'), JSON.stringify({ at: Date.now(), pid: process.pid }), { mode: 0o600 }),
+ covers: async (directory, requestedAt) => ((await readJson(join(directory, 'stop.json')))?.at ?? -Infinity) >= requestedAt,
+};
+
 export const serverRecord = {
  read: directory => readJson(join(directory, 'server.json')),
  write: (directory, record) => writeFile(join(directory, 'server.json'), JSON.stringify(record), { mode: 0o600 }),

package/global/launch/steps.mjs

@@ -21,10 +21,18 @@ export function failureFrom(code, error, output) {
  return new LaunchFailure(code || 1, error?.message ?? (output.trim().split('\n').slice(-5).join('\n') || `The command stopped with exit ${code}.`), error);
 }
 
+// A child joins the set a stop signals; one spawned as the stop arrives is
+// signalled at once rather than left to finish.
+function own(children, child, signal) {
+ children.add(child);
+ if (signal?.aborted) child.kill('SIGTERM');
+}
+
 // One bounded verb, never prompting: no stdin, --non-interactive, --json.
-export async function runVerb(entry, args, { root, env, note, log, children }) {
+export async function runVerb(entry, args, { root, env, note, log, children, signal }) {
+ signal?.throwIfAborted();
  const child = spawn(process.execPath, [entry, ...args, '--json', '--non-interactive'], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] });
- children.add(child);
+ own(children, child, signal);
  let error, output = '';
  const lines = createInterface({ input: child.stdout });
  lines.on('line', line => { const event = events(line); if (event?.event === 'error') error = event; const text = event && waitingNote(event); if (text) note(text); log(line); });
@@ -55,18 +63,24 @@ async function follow(path, from, onLine, stopped) {
 // Start `dev` detached into its own process group with its output in a private
 // log, and return its ready event once it prints one. The server outlives this
 // process and stops on rer dev --stop or its idle timeout.
-export async function startServer(entry, args, { root, env, logPath, children }) {
+export async function startServer(entry, args, { root, env, logPath, children, signal, note = () => {} }) {
+ signal?.throwIfAborted();
  const handle = await open(logPath, 'a', 0o600), from = (await handle.stat()).size;
- let child;
- try { child = spawn(process.execPath, [entry, 'dev', ...args, '--json'], { cwd: root, env, detached: true, stdio: ['ignore', handle.fd, handle.fd] }); }
- finally { await handle.close(); }
- children.add(child);
- let exit, ready, error, output = '';
- child.once('exit', (code, signal) => { exit = code ?? (signal ? 128 : 1); });
+ let child, exit, spawnError;
+ // Listening before anything is awaited: a spawn that fails reports it on the next tick.
+ try {
+  child = spawn(process.execPath, [entry, 'dev', ...args, '--json'], { cwd: root, env, detached: true, stdio: ['ignore', handle.fd, handle.fd] });
+  child.once('error', failure => { spawnError = failure; exit ??= 1; });
+  child.once('exit', (code, name) => { exit = code ?? (name ? 128 : 1); });
+ } finally { await handle.close(); }
+ own(children, child, signal);
+ let ready, error, output = '';
  await follow(logPath, from, line => {
   const event = events(line);
   if (event?.event === 'ready') { ready = event; return true; }
   if (event?.event === 'error') error = event;
+  // rer dev --door / --direct: where the checkout moved.
+  if (event?.event === 'moved') note(`moved this checkout from ${event.from} to ${event.to}; its data is kept`);
   if (!event) output = (output + line + '\n').slice(-8192);
   return false;
  }, () => exit !== undefined);
@@ -75,7 +89,7 @@ export async function startServer(entry, args, { root, env, logPath, children })
   for await (const line of createInterface({ input: createReadStream(logPath, { start: from }) })) { const event = events(line); if (event?.event === 'ready') ready = event; if (event?.event === 'error') error = event; }
  }
  children.delete(child);
- if (!ready) throw failureFrom(exit, error, output);
+ if (!ready) throw failureFrom(exit, error, spawnError ? `rer could not run in ${root}: ${spawnError.code ?? spawnError.message}.` : output);
  child.unref();
  return { ready, pid: child.pid, reused: exit === 0 };
 }

package/global/launch/stop.mjs

@@ -0,0 +1,89 @@
+// rer dev --stop for a checkout the launcher may be preparing or serving.
+// It ends a launch still preparing (or one that has not yet claimed the
+// checkout), has the pinned dispatcher stop the registered server, and then
+// checks that every process it found -- the worker, the server rer started,
+// the registered server and everything they spawned -- has exited. It says
+// what it stopped, or exits non-zero naming what is still running.
+import { setTimeout as delay } from 'node:timers/promises';
+import { processInfo } from '../../modules/job-queue/processes.mjs';
+import { readProcessTable, sameBirth } from '../../onboarding/process-table.mjs';
+import { delegate } from '../delegate.mjs';
+import { liveServers } from '../registry.mjs';
+import { LaunchFailure } from './failure.mjs';
+import { liveWorker, serverRecord, stopRequest } from './state.mjs';
+
+export async function stopLaunch(target, devArgs, { checkout, directory }) {
+ // Written before looking for a worker: one that claims the launch after this
+ // look reads it and ends itself (worker.mjs).
+ await stopRequest.write(directory);
+ const holder = await liveWorker(directory);
+ const launch = holder ? await tree([holder]) : [];
+ if (holder) await endWorker(holder);
+ // Only now: a worker stopped while its server came up has registered it.
+ const record = (await liveServers()).find(item => item.checkout === checkout);
+ const started = await serverRecord.read(directory);
+ const server = await tree([record?.owner, record?.runtimeProcess, started, started?.spawned]);
+ await delegate(target, ['dev', ...devArgs]);
+ if (process.exitCode) return process.exitCode;
+ const left = await exited([...launch, ...server], 15000);
+ if (left.length) {
+  const pids = left.map(item => item.pid).join(' ');
+  process.stderr.write(`rer dev --stop: ${left.length === 1 ? 'a process' : `${left.length} processes`} of this checkout's dev server ${left.length === 1 ? 'is' : 'are'} still running 15 seconds after the stop (PID ${pids}). Stop ${left.length === 1 ? 'it' : 'them'} with kill -TERM ${pids}, then run rer dev --stop again.\n`);
+  return 1;
+ }
+ if (!devArgs.includes('--json')) process.stdout.write(said({ checkout, record, started, server, holder, launch }) + '\n');
+ return 0;
+}
+
+// SIGTERM the preparing worker and wait for it to exit.
+async function endWorker(holder) {
+ try { process.kill(holder.pid, 'SIGTERM'); } catch (error) { if (error.code === 'ESRCH') return; throw error; }
+ for (let waited = 0; waited < 60000; waited += 250) {
+  const current = await processInfo(holder.pid);
+  if (!current || current.zombie || current.start !== holder.start) return;
+  await delay(250);
+ }
+ throw new LaunchFailure(1, `The launch worker (PID ${holder.pid}) did not stop within a minute.`);
+}
+
+// The live processes among these recorded identities ({pid, start}), with
+// every process descended from them, as process-table entries.
+async function tree(identities) {
+ const roots = new Set();
+ for (const identity of identities) {
+  if (!identity?.pid || !identity.start) continue;
+  const current = await processInfo(identity.pid);
+  if (current && !current.zombie && current.start === identity.start) roots.add(identity.pid);
+ }
+ if (!roots.size) return [];
+ const table = await readProcessTable(), found = table.filter(entry => roots.has(entry.pid));
+ for (let index = 0; index < found.length; index++) {
+  for (const entry of table) if (entry.ppid === found[index].pid && !found.includes(entry)) found.push(entry);
+ }
+ return found;
+}
+
+// Wait until none of these processes is running; return those still running.
+async function exited(processes, within) {
+ const deadline = Date.now() + within;
+ for (;;) {
+  const table = processes.length ? await readProcessTable() : [];
+  const left = processes.filter(item => table.some(entry => sameBirth(item, entry) && !entry.state.startsWith('Z')));
+  if (!left.length || Date.now() >= deadline) return left;
+  await delay(250);
+ }
+}
+
+function said({ checkout, record, started, server, holder, launch }) {
+ const lines = [], more = n => n > 0 ? ` with ${n} more ${n === 1 ? 'process' : 'processes'}` : '';
+ if (server.length) {
+  const pid = record?.owner?.pid ?? started?.pid ?? server[0].pid;
+  lines.push(`Stopped the dev server${record?.url ? ` at ${record.url}` : ''} for ${checkout} (PID ${pid})${more(server.length - 1)}.`);
+ }
+ if (holder) {
+  const own = launch.filter(item => !server.some(entry => sameBirth(item, entry)));
+  lines.push(`Stopped the launch still running for ${checkout} (PID ${holder.pid})${more(own.length - 1)}.`);
+ }
+ if (!lines.length) lines.push(`No dev server was running for ${checkout}.`);
+ return lines.join('\n');
+}

package/global/launch/worker.mjs

@@ -1,41 +1,60 @@
-// The detached launch worker: node worker.mjs ROOT TOKEN ARGS_JSON
+// The detached launch worker: node worker.mjs ROOT TOKEN ARGS_JSON REQUESTED_AT
+// (REQUESTED_AT: when the `rer dev` that spawned it started, epoch ms).
 // It runs in its own session, so killing the `rer dev` that started it (or that
 // command's whole process group) leaves it running; a rerun attaches to it.
+// rer dev --stop ends it: SIGTERM, or, for a stop that ran before this worker
+// claimed the launch, the stop request it reads right after claiming. Either
+// way no further step starts, the running one is signalled, and the launch
+// reports that it was stopped instead of ready.
 import { createWriteStream } from 'node:fs';
 import { realpath } from 'node:fs/promises';
 import { join } from 'node:path';
+import { processInfo } from '../../modules/job-queue/processes.mjs';
 import { liveServers } from '../registry.mjs';
+import { LaunchFailure } from './failure.mjs';
 import { prepare } from './prepare.mjs';
-import { claimLaunch, eventLog, launchDirectory, liveWorker, releaseLaunch, serverRecord } from './state.mjs';
+import { claimLaunch, eventLog, launchDirectory, liveWorker, releaseLaunch, serverRecord, stopRequest } from './state.mjs';
 import { startServer } from './steps.mjs';
 
-const [root, token, argsJSON] = process.argv.slice(2), args = JSON.parse(argsJSON);
+const [root, token, argsJSON, requestedAtText, mode] = process.argv.slice(2), args = JSON.parse(argsJSON), requestedAt = Number(requestedAtText), doorStart = mode === 'door-start';
 const checkout = await realpath(root), directory = await launchDirectory(checkout), events = eventLog(directory, token);
+// Listening before the claim: a stop may signal this worker as soon as it is the holder.
+const children = new Set(), stopping = new AbortController();
+const stop = () => { stopping.abort(); for (const child of children) child.kill('SIGTERM'); };
+for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, stop);
+process.on('SIGHUP', () => {});
 if (!await claimLaunch(directory, token)) {
  const holder = await liveWorker(directory);
  await events.write({ event: 'redirect', token: holder?.token });
 } else {
  const logFile = createWriteStream(join(directory, 'launch.log'), { flags: 'a', mode: 0o600 });
  const log = text => logFile.write(text + '\n');
- const children = new Set();
- for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => { for (const child of children) child.kill('SIGTERM'); });
- process.on('SIGHUP', () => {});
  try {
-  const prepared = await prepare({ root, args, env: process.env, report: fields => events.write({ event: 'phase', ...fields }), directory, log, children });
+  if (await stopRequest.covers(directory, requestedAt)) stop();
+  stopping.signal.throwIfAborted();
+  const prepared = await prepare({ root, args, env: process.env, report: fields => events.write({ event: 'phase', ...fields }), directory, log, children, signal: stopping.signal, doorStart });
   await events.write({ event: 'phase', phase: 'start', message: prepared.own ? 'the app is already running; checking it' : 'starting the app' });
   // A server rer started logs to server.log; asking a running one for its
   // ready lines goes to reuse.log, and names server.log only when rer started it.
   const serverLog = join(directory, 'server.log');
-  const started = await startServer(prepared.entry, args, { root, env: { ...process.env, ...prepared.added }, logPath: prepared.own ? join(directory, 'reuse.log') : serverLog, children });
+  let started;
+  try { started = await startServer(prepared.entry, args, { root, env: { ...process.env, ...prepared.added }, logPath: prepared.own ? join(directory, 'reuse.log') : serverLog, children, signal: stopping.signal, note: message => events.write({ event: 'phase', phase: 'note', message }) }); }
+  finally { await prepared.release?.(); }
   const record = (await liveServers(process.env)).find(item => item.checkout === checkout);
-  await prepared.release?.();
   const pid = record?.owner?.pid ?? started.pid;
-  if (!prepared.own) await serverRecord.write(directory, { pid });
+  // The server's PID, and the process rer spawned for it (the same one unless
+  // the pin re-runs itself under its own Node), each with its start time.
+  const identity = async id => ({ pid: id, start: (await processInfo(id))?.start });
+  if (!prepared.own) await serverRecord.write(directory, { ...await identity(pid), spawned: await identity(started.pid) });
   const ours = !prepared.own || (await serverRecord.read(directory))?.pid === pid;
+  // A stop that arrived while the server came up finds it registered and
+  // stops it; this launch reports the stop rather than a server about to end.
+  stopping.signal.throwIfAborted();
   await events.write({ event: 'ready', ready: started.ready, pid, ...(ours ? { log: serverLog } : {}) });
  } catch (error) {
   log(String(error?.stack ?? error));
-  await events.write({ event: 'failed', exitCode: error.exitCode ?? 1, message: error.exitCode ? error.message : `The launch failed unexpectedly; see ${join(directory, 'launch.log')}.`, ...(error.event ? { error: error.event } : {}) });
+  const failure = stopping.signal.aborted ? new LaunchFailure(1, 'rer dev --stop stopped this launch before the app was ready.') : error;
+  await events.write({ event: 'failed', exitCode: failure.exitCode ?? 1, message: failure.exitCode ? failure.message : `The launch failed unexpectedly; see ${join(directory, 'launch.log')}.`, ...(failure.event ? { error: failure.event } : {}) });
  } finally {
   await releaseLaunch(directory, token);
   logFile.end();

package/global/list.mjs

@@ -4,7 +4,7 @@ import { execFile } from 'node:child_process';
 import { readdir, realpath, stat } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { promisify } from 'node:util';
-import { descriptorProfile, dispatcher } from './checkout.mjs';
+import { descriptorProfile, dispatcher, pinnedPackage } from './checkout.mjs';
 import { liveServers } from './registry.mjs';
 import { describeCheckout, setupNeeded } from './launch/facts.mjs';
 import { launchPath, setupState } from './launch/state.mjs';
@@ -27,8 +27,11 @@ async function entry(path, running) {
  if (!result.launchable) result.reason = reasons[facts.profile] ?? `OPERATIONS.json is version ${facts.version ?? '(none)'}, which rer does not run`;
  result.prepared = null;
  if (profile === 'first-party') {
-  // Set up: saved settings, and no setup a launch started left unfinished.
-  try { result.prepared = !await setupNeeded(path, await describeCheckout(path, dispatcher(path).entry, process.env), await setupState.read(launchPath(path))); }
+  // Set up: saved settings, and no setup a launch started left unfinished. A
+  // checkout whose pinned rer package is not installed yet has never been
+  // launched: rer dev installs it first.
+  if (pinnedPackage(path)?.ready === false) result.prepared = false;
+  else try { result.prepared = !await setupNeeded(path, await describeCheckout(path, dispatcher(path).entry, process.env), await setupState.read(launchPath(path))); }
   catch (failure) { result.launchable = false; result.reason = `rer describe fails here: ${failure.message.split('\n')[0]}`; }
  }
  result.url = running.get(path) ?? null;