@volter/world-runtime 2.0.0

package/src/service-exit.ts

@@ -0,0 +1,175 @@
+// How a process service ended, read back from its own log: the runtime's parent writes a `world.service.started`
+// line when it spawns the service and a `world.service.exited` line when the service ends (runtime.ts,
+// ./service-recorder.ts). `status` and `doctor` report the last run's end with the service's last lines of output, so
+// a service that died after `up` returned says how and what it last said instead of only "not live". The World's own
+// stop of a service (`down`, a boot's rollback) is recorded in the same log (`world.service.stop`, and
+// `world.service.killed` for a SIGKILL after the grace), so its end reads as the World's act and not an outsider's.
+import { closeSync, existsSync, fstatSync, openSync, readSync } from 'node:fs';
+
+export type ServiceExitRecord = {
+  event: 'world.service.exited';
+  status: number;
+  code?: number | null;
+  signal?: string | null;
+  error?: string;
+  pid?: number;
+  uptimeMs?: number;
+  stopRequested?: string;
+  at: string;
+};
+export type WorldStopRecord = { event: 'world.service.stop' | 'world.service.killed'; by: string; signal: string; at: string };
+export type ServiceEnd = {
+  startedAt?: string;
+  exited?: ServiceExitRecord;
+  /** The World's stop of this run, and its SIGKILL after the grace, when it sent them. */
+  stopped?: WorldStopRecord;
+  killed?: WorldStopRecord;
+  /** The service's own last lines of output in its last run, oldest first. */
+  lastOutput: string[];
+};
+
+const TAIL_BYTES = 256 * 1024;
+// How far back the start of a run is looked for when its output has pushed the start record out of the tail.
+const DEEP_BYTES = 64 * 1024 * 1024;
+const CHUNK_BYTES = 1024 * 1024;
+const OUTPUT_LINES = 20;
+const LINE_CHARS = 400;
+// ANSI colour and cursor sequences, which a terminal-minded service writes into a file log too.
+const ANSI = /\u001b\[[0-9;?]*[ -/]*[@-~]/g;
+
+function fstatSize(path: string): number {
+  const fd = openSync(path, 'r');
+  try { return fstatSync(fd).size; } finally { closeSync(fd); }
+}
+
+function tailWithOffset(log: string): { text: string; start: number } {
+  const fd = openSync(log, 'r');
+  try {
+    const size = fstatSync(fd).size, start = Math.max(0, size - TAIL_BYTES), buffer = Buffer.alloc(size - start);
+    readSync(fd, buffer, 0, buffer.length, start);
+    const text = buffer.toString('utf8');
+    return { text: start > 0 ? text.slice(text.indexOf('\n') + 1) : text, start };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** The last `world.service.started` record in the bytes of `log` before `end`, read backwards a chunk at a time (a
+ *  chatty service can write far more than the tail between its start and its end). */
+function startBefore(log: string, end: number): { at?: string } | undefined {
+  const fd = openSync(log, 'r');
+  try {
+    const floor = Math.max(0, end - DEEP_BYTES);
+    for (let hi = end; hi > floor; hi -= CHUNK_BYTES) {
+      const lo = Math.max(floor, hi - CHUNK_BYTES - 512), buffer = Buffer.alloc(hi - lo);
+      readSync(fd, buffer, 0, buffer.length, lo);
+      const text = buffer.toString('utf8'), at = text.lastIndexOf(`${MARK}started"`);
+      if (at < 0) continue;
+      const line = text.slice(at, text.indexOf('\n', at) < 0 ? undefined : text.indexOf('\n', at));
+      try { return JSON.parse(line) as { at?: string }; } catch { return {}; }
+    }
+    return undefined;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+// A record the parent wrote. The service shares the file, so a record can follow output the service left without a
+// newline on the same line: it is found wherever it starts, and what precedes it is the service's output.
+const MARK = '{"event":"world.service.';
+function split(line: string): { output: string; record?: { event?: unknown; at?: unknown } } {
+  const at = line.indexOf(MARK);
+  if (at < 0) return { output: line };
+  try { return { output: line.slice(0, at), record: JSON.parse(line.slice(at)) as { event?: unknown; at?: unknown } }; } catch { return { output: line }; }
+}
+
+/** A log's text as the service wrote it, without the recorder's records: what a `stdoutMatch` readiness pattern is
+ *  matched against. */
+export function serviceOutput(text: string): string {
+  return text.includes(MARK) ? text.split('\n').map((line) => split(line).output).join('\n') : text;
+}
+
+/** The last run's end in a service log: its start, its exit record (absent while it runs, or when its parent was killed
+ *  with it), and the output it wrote last. Undefined for a log the parent never wrote to (a co-located twin's host log),
+ *  which has no runs to tell apart. A run is bounded by its start record or, for a spawn that failed before starting
+ *  or a log from before start records, by the previous run's exit. */
+export function readServiceEnd(log: string): ServiceEnd | undefined {
+  if (!existsSync(log)) return undefined;
+  const { text, start: tailStart } = tailWithOffset(log);
+  const lines = text.split('\n').map(split);
+  let from = -1, startedAt: string | undefined, exited: ServiceExitRecord | undefined, until = lines.length;
+  let stopped: WorldStopRecord | undefined, killed: WorldStopRecord | undefined;
+  const marks: Array<{ i: number; record: WorldStopRecord }> = [];
+  for (let i = lines.length - 1; i >= 0 && from < 0; i--) {
+    const r = lines[i].record;
+    if (r?.event === 'world.service.started') { from = i + 1; startedAt = typeof r.at === 'string' ? r.at : undefined; }
+    else if (r?.event === 'world.service.exited') {
+      if (exited === undefined) { exited = r as ServiceExitRecord; until = i; } else from = i + 1;
+    } else if (r?.event === 'world.service.stop' || r?.event === 'world.service.killed') marks.push({ i, record: r as WorldStopRecord });
+  }
+  // A stop written after the run's exit (a later `down` finding it already dead) was not this end's cause.
+  for (const { i, record } of marks) {
+    if (i >= until) continue;
+    if (record.event === 'world.service.stop') stopped ??= record; else killed ??= record;
+  }
+  // The run began before the tail: its start is found further back, and all of the tail is this run's.
+  if (from < 0 && tailStart > 0) { const deep = startBefore(log, tailStart); if (deep) startedAt = deep.at ?? ''; }
+  // The recorder rotates a full log to `<log>.1`: a run older than the rotation began there.
+  if (from < 0 && startedAt === undefined && existsSync(`${log}.1`)) {
+    const size = fstatSize(`${log}.1`), deep = startBefore(`${log}.1`, size);
+    if (deep) startedAt = deep.at ?? '';
+  }
+  if (startedAt === undefined && exited === undefined) return undefined;
+  // The output a record line carried before it belongs to the run before the record.
+  const own = [...lines.slice(Math.max(0, from), until).map((line) => line.output), ...(until < lines.length ? [lines[until].output] : [])];
+  const lastOutput = own
+    .map((line) => line.replace(ANSI, '').replace(/\r/g, '').trimEnd())
+    .filter((line) => line.trim() !== '')
+    .slice(-OUTPUT_LINES)
+    .map((line) => (line.length > LINE_CHARS ? `${line.slice(0, LINE_CHARS)}…` : line));
+  return { ...(startedAt !== undefined ? { startedAt } : {}), ...(exited !== undefined ? { exited } : {}), ...(stopped ? { stopped } : {}), ...(killed ? { killed } : {}), lastOutput };
+}
+
+const duration = (ms: number): string => {
+  const s = Math.round(ms / 1000);
+  return s < 60 ? `${s}s` : s < 3600 ? `${Math.floor(s / 60)}m${String(s % 60).padStart(2, '0')}s` : `${Math.floor(s / 3600)}h${String(Math.floor((s % 3600) / 60)).padStart(2, '0')}m`;
+};
+
+/** One line for a service that is not live: how it ended, who stopped it, when, and after how long. */
+export function describeServiceEnd(end: ServiceEnd): string {
+  const exit = end.exited;
+  // A log from before exit records split code from signal: a status past 128 is 128 + the signal's number.
+  if (exit && exit.code === undefined && exit.signal === undefined && exit.status > 128) exit.signal = `signal ${exit.status - 128}`;
+  if (!exit) {
+    if (end.killed) return `was killed by the World (${end.killed.by}: SIGKILL after it did not stop within the grace), at ${end.killed.at}`;
+    if (end.stopped) return `recorded no exit after the World's stop (${end.stopped.by}, at ${end.stopped.at}): its World parent died with it`;
+    return end.startedAt !== undefined
+      ? 'recorded no exit: its World parent died with it (a SIGKILL to the group from outside the World, the OOM killer, or a machine restart)'
+      : 'recorded no start in its log';
+  }
+  const ended = exit.signal ? `ended by ${exit.signal}` : `exit code ${exit.code ?? exit.status}`;
+  const how = exit.error ? `failed to spawn (${exit.error})`
+    : exit.stopRequested && end.stopped ? `was stopped by the World (${end.stopped.by}; ${ended})`
+      : exit.stopRequested ? `was stopped by a ${exit.stopRequested} from outside the World (no World stop was recorded; ${ended})`
+        : exit.signal ? `was killed by ${exit.signal}` : `exited with code ${exit.code ?? exit.status}`;
+  const ran = exit.uptimeMs !== undefined ? ` after running ${duration(exit.uptimeMs)}` : '';
+  return `${how}${ran}, at ${exit.at}`;
+}
+
+// ---- the World's events file ----------------------------------------------------------------------------------------
+export type WorldEvent = { event: string; service?: string; at: string; [key: string]: unknown };
+/** The World's events (logs/events.jsonl), oldest first; unreadable lines are skipped. */
+export function readWorldEvents(path: string): WorldEvent[] {
+  if (!existsSync(path)) return [];
+  const { text } = tailWithOffset(path);
+  return text.split('\n').flatMap((line) => { if (!line.trim()) return []; try { return [JSON.parse(line) as WorldEvent]; } catch { return []; } });
+}
+/** One event as a line a person reads. */
+export function describeWorldEvent(event: WorldEvent): string {
+  const who = event.service ?? '(world)';
+  if (event.event === 'world.service.started') return `${event.at} ${who} started (pid ${event.pid})`;
+  if (event.event === 'world.service.exited') return `${event.at} ${who} ${describeServiceEnd({ exited: event as unknown as ServiceExitRecord, lastOutput: [] }).replace(/, at [^,]*$/, '')}`;
+  if (event.event === 'world.service.stop') return `${event.at} ${who} stopped by the World (${event.by}, ${event.signal})`;
+  if (event.event === 'world.service.killed') return `${event.at} ${who} killed by the World (${event.by}, SIGKILL after the grace)`;
+  return `${event.at} ${who} ${event.event}`;
+}

package/src/service-recorder.ts

@@ -0,0 +1,89 @@
+// A World service's parent for its whole life (runtime.ts, spawnRecorded). Node, not a POSIX shell, because job control
+// is not something every place a World runs provides. The service writes its output straight to its log (this
+// parent's stdout and stderr are that file, opened for append, and the service inherits them): a pipe through here
+// would lose the last output of a Node service that exits right after a large write, reorder stdout against stderr,
+// and tie the service's life to this parent's. This parent:
+// - writes a `world.service.started` record when the service starts and a `world.service.exited` record (exit code or
+//   signal, pid, run time, whether it was asked to stop) when it ends, into the log and into the World's events file
+//   (VOLTER_WORLD_EVENTS), the one place every service end in the World is listed;
+// - caps the log, checked every second: past VOLTER_WORLD_SERVICE_LOG_MAX bytes it copies the log's last cap bytes to
+//   `<log>.1` and truncates it in place (the service's append-mode descriptor then writes from the new end), so a
+//   chatty or runaway service cannot fill the disk; lines written between the copy and the truncate are lost, the usual
+//   cost of rotating a file a program holds, and a writer that reopened the log without O_APPEND (Linux's /dev/stdout)
+//   keeps its old offset and leaves a gap of NULs;
+// - stamps the time into the log about every ten seconds while output flows (`world.service.time`), since the
+//   service's own lines carry none: lines between two marks were written between those times;
+// - forwards TERM/INT/HUP to the service and exits with its status (128+n for a signal).
+// The World's NODE_OPTIONS (the injector) is for the service, not this parent: it arrives renamed and is restored.
+import { spawn } from 'node:child_process';
+import { constants } from 'node:os';
+import { appendFileSync, closeSync, fstatSync, openSync, readSync, statSync, truncateSync, writeFileSync } from 'node:fs';
+
+const [command = '', ...args] = process.argv.slice(2);
+const env = { ...process.env };
+if (env.VOLTER_WORLD_SERVICE_NODE_OPTIONS !== undefined) { env.NODE_OPTIONS = env.VOLTER_WORLD_SERVICE_NODE_OPTIONS; delete env.VOLTER_WORLD_SERVICE_NODE_OPTIONS; }
+const service = env.VOLTER_WORLD_SERVICE_ID;
+const logPath = env.VOLTER_WORLD_SERVICE_LOG;
+const eventsPath = env.VOLTER_WORLD_EVENTS;
+const cap = Number(env.VOLTER_WORLD_SERVICE_LOG_MAX) > 0 ? Number(env.VOLTER_WORLD_SERVICE_LOG_MAX) : 64 * 1024 * 1024;
+for (const key of ['VOLTER_WORLD_EVENTS', 'VOLTER_WORLD_SERVICE_LOG_MAX']) delete env[key];
+
+/** The log's size and whether its last byte ends a line (a record never lands inside a service's line). */
+const logEnd = (): { size: number; atLineStart: boolean } => {
+  if (!logPath) return { size: 0, atLineStart: true };
+  try {
+    const fd = openSync(logPath, 'r');
+    try {
+      const { size } = fstatSync(fd), last = Buffer.alloc(1);
+      return { size, atLineStart: !size || (readSync(fd, last, 0, 1, size - 1) === 1 && last[0] === 10) };
+    } finally { closeSync(fd); }
+  } catch { return { size: 0, atLineStart: true }; }
+};
+const record = (entry: Record<string, unknown>, then?: () => void): void => {
+  const line = `${JSON.stringify({ ...entry, service, at: new Date().toISOString() })}\n`;
+  if (eventsPath && entry.event !== 'world.service.time') { try { appendFileSync(eventsPath, line, { mode: 0o600 }); } catch { /* the log still has it */ } }
+  process.stdout.write(`${logEnd().atLineStart ? '' : '\n'}${line}`, () => then?.());
+};
+
+const started = Date.now();
+const child = spawn(command, args, { stdio: 'inherit', env });
+if (child.pid !== undefined) record({ event: 'world.service.started', pid: child.pid, parentPid: process.pid });
+
+/** The log's last `bytes` (from a line start) as the rotation `<log>.1`: however far a runaway writer overshot the cap,
+ *  the rotation and the live log together stay within twice it. */
+const rotate = (path: string, size: number): void => {
+  const fd = openSync(path, 'r');
+  try {
+    const start = Math.max(0, size - cap), buffer = Buffer.alloc(size - start);
+    readSync(fd, buffer, 0, buffer.length, start);
+    const from = start > 0 ? buffer.indexOf(10) + 1 : 0;
+    writeFileSync(`${path}.1`, buffer.subarray(from), { mode: 0o600 });
+  } finally { closeSync(fd); }
+  truncateSync(path, 0);
+};
+// The cap every second; a time mark every ten while output flows.
+let marked = logEnd().size, ticks = 0;
+const watch = setInterval(() => {
+  const end = logEnd();
+  if (logPath && end.size >= cap) {
+    try { rotate(logPath, end.size); marked = 0; } catch { /* the log keeps growing rather than lose it */ }
+  }
+  if (++ticks % 10 === 0 && end.size > marked && end.atLineStart) { record({ event: 'world.service.time' }); marked = statSize(); }
+}, 1_000);
+const statSize = (): number => { try { return logPath ? statSync(logPath).size : 0; } catch { return 0; } };
+
+let forwarded: string | null = null;
+for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'] as const) process.on(signal, () => { forwarded = forwarded || signal; try { child.kill('SIGTERM'); } catch { /* already gone */ } });
+let ended = false;
+const done = (status: number, end: Record<string, unknown>): void => {
+  if (ended) return;
+  ended = true;
+  clearInterval(watch);
+  record({ event: 'world.service.exited', status, ...end, pid: child.pid, uptimeMs: Date.now() - started, ...(forwarded ? { stopRequested: forwarded } : {}) }, () => process.exit(status));
+};
+child.once('error', (error: Error) => {
+  const message = String(error?.message || error);
+  process.stderr.write(`${message}\n`);
+  done(127, { code: null, signal: null, error: message });
+});
+child.once('exit', (code, signal) => done(signal ? 128 + (constants.signals[signal as NodeJS.Signals] || 0) : (code ?? 1), { code, signal }));

package/src/sibling.ts

@@ -0,0 +1,10 @@
+// A sibling script of the calling module, in the form this package is RUNNING AS: `.ts` from the
+// checkout, `.js` from the built package (scripts/publish/build.mjs emits dist/src/*.js beside
+// nothing else). A spawn by a hard `.ts` path was the built runtime's first failure (2026-09-07:
+// "Module not found …/dist/src/host-cli.ts" under the tutorial registry).
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function siblingScript(fromUrl: string, stem: string): string {
+  return join(dirname(fileURLToPath(fromUrl)), `${stem}${fromUrl.endsWith('.js') ? '.js' : '.ts'}`);
+}

package/src/signals.ts

@@ -0,0 +1,10 @@
+// Removing a signal listener without removing the others. Under Bun (measured on 1.3.10),
+// `process.off('SIGINT', fn)` uninstalls the process's OS handler even while other listeners remain
+// (`listenerCount` still answers 1): the next SIGINT then takes the default action and kills the
+// process, so a caller's own handler (a harness's teardown) never runs. Re-registering the remaining
+// listeners reinstalls the handler. Node keeps it either way.
+export function offSignal(signal: NodeJS.Signals, listener: (...args: never[]) => void): void {
+  const rest = process.listeners(signal).filter((l) => l !== listener);
+  process.removeAllListeners(signal);
+  for (const l of rest) process.on(signal, l as (...args: unknown[]) => void);
+}

package/src/storage-capacity.ts

@@ -0,0 +1,60 @@
+import { execFileSync } from 'node:child_process';
+import { statSync } from 'node:fs';
+
+export type StorageProbeFailure = { root: string; stage: string; reason: string };
+
+/** Storage capacity is shared by APFS volumes in a container. Device numbers alone do not identify shared backing capacity. Unknown topology
+ * stays unknown; this is inspection metadata, never a speculative admission budget. */
+export function storagePoolResolver(onFailure?: (failure: StorageProbeFailure) => void): (root: string) => string | undefined {
+  const devices = new Map<number, string | undefined>();
+  return (root) => {
+    let stage = 'filesystem identity';
+    try {
+      const device = statSync(root).dev;
+      if (devices.has(device)) return devices.get(device);
+      // Unknown is a result too. A failed macOS probe must not be repeated for every
+      // World on this device within one report/admission attempt. A new resolver retries.
+      devices.set(device, undefined);
+      let pool: string | undefined;
+      if (process.platform === 'darwin') {
+        stage = 'volume lookup';
+        const df = execFileSync('/bin/df', ['-P', root], { encoding: 'utf8', timeout: 3000, killSignal: 'SIGKILL', stdio: ['ignore', 'pipe', 'ignore'] });
+        const disk = df.trim().split('\n').at(-1)?.trim().split(/\s+/)[0];
+        if (disk && /^\/dev\/disk\d+(?:s\d+)*$/.test(disk)) {
+          stage = 'volume metadata';
+          const info = diskInfo(disk);
+          const container = plistString(info, 'APFSContainerReference');
+          if (container && /^disk\d+$/.test(container)) {
+            stage = 'pool metadata';
+            const uuid = plistString(diskInfo(container), 'DiskUUID');
+            if (uuid && /^[a-f0-9-]+$/i.test(uuid)) pool = `apfs:${uuid.toLowerCase()}`;
+          } else if (plistString(info, 'FilesystemType') !== 'apfs') {
+            const uuid = plistString(info, 'VolumeUUID');
+            if (uuid && /^[a-f0-9-]+$/i.test(uuid)) pool = `volume:${uuid.toLowerCase()}`;
+          }
+        }
+      }
+      // Other hosts remain unresolved: distinct filesystem devices can still share a
+      // backing capacity pool (for example subvolumes or thin provisioning).
+      if (!pool) onFailure?.({ root, stage, reason: 'metadata did not identify a supported storage pool' });
+      devices.set(device, pool);
+      return pool;
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      const reason = typeof code === 'string' ? code : 'metadata probe failed';
+      onFailure?.({ root, stage, reason: reason.replace(/[\x00-\x1f\x7f]/g, '').slice(0, 120) });
+      return undefined;
+    }
+  };
+}
+
+function diskInfo(disk: string): string {
+  return execFileSync('/usr/sbin/diskutil', ['info', '-plist', disk], {
+    encoding: 'utf8', timeout: 3000, killSignal: 'SIGKILL', stdio: ['ignore', 'pipe', 'ignore'],
+  });
+}
+
+// Only fixed keys and ASCII identifiers are consumed, never arbitrary XML values.
+function plistString(xml: string, key: string): string | undefined {
+  return new RegExp(`<key>${key}</key>\\s*<string>([^<]*)</string>`).exec(xml)?.[1];
+}

package/src/tail.ts

@@ -0,0 +1,205 @@
+// `volter-world tail` — the live observability verb: one merged, causally-ordered (by
+// `occurredAt`) feed of a world's twin action ledgers. Strictly READ-ONLY over data at rest
+// (the per-service `actions.jsonl` files the control plane appends to — see
+// control-plane/src/actions.ts, plus — under `--requests` — the opt-in
+// `requests.jsonl` request journals serve.ts writes, shape + credential shape); the runtime stays a lifecycle primitive,
+// this just watches what the twins already record. A ledger dir may not exist until a service
+// records its first action, so discovery re-runs on every poll and a missing ledger is a
+// notice, never an error.
+import { closeSync, existsSync, openSync, readSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { stateDirName } from '@volter/world-core';
+import { statusWorld } from './runtime.ts';
+
+/** The slice of a ledger row `tail` renders. Rows are vendor-recorded TwinActions
+ * (control-plane/src/actions.ts); everything else passes through untouched under `--json`. */
+type TailRecord = Record<string, unknown> & {
+  occurredAt?: string;
+  /** request-journal rows (requests.jsonl) carry `at` instead of `occurredAt`. */
+  at?: string;
+  op?: string;
+  operation?: string;
+  method?: string;
+  path?: string;
+  status?: number;
+  /** how long the twin took to answer a request row, in milliseconds (serve.ts journalingFetch) */
+  ms?: number;
+  /** credential SHAPE on a request row: which header/query name carried a credential, and a
+   *  truncated sha256 of the value. Never the value — see control-plane/src/serve.ts. */
+  credentials?: Array<{ name?: string; in?: string; scheme?: string; fp?: string; empty?: true }>;
+  subject?: { type?: string; id?: string };
+};
+
+type TailEntry = { service: string; record: TailRecord; source: 'actions' | 'requests' };
+
+export type TailWorldOptions = {
+  root?: string;
+  /** Restrict the feed to these world service ids (default: every service in the world). */
+  services?: string[];
+  /** Keep watching for new entries after the initial dump (default true; `--no-follow` clears it). */
+  follow?: boolean;
+  /** Raw JSONL passthrough with the world service id injected as `service` (default: human lines). */
+  json?: boolean;
+  /** Also merge each service's opt-in REQUEST journal into the feed (`requests.jsonl`, written
+   * by twins running under VOLTER_TWIN_REQUEST_JOURNAL=1 — shape-only `{at, method, path,
+   * status}` rows; control-plane/src/serve.ts). Reads are otherwise invisible here: an
+   * empty-catalog GET that 404s leaves no trace in an actions-only tail. */
+  requests?: boolean;
+  /** Poll interval while following (ledger appends are cross-process, so this polls rather than
+   * fs.watch — watch descriptors can't see a file that doesn't exist yet). */
+  pollMs?: number;
+  /** Entry sink — one already-formatted line per call (default: process.stdout). */
+  write?: (line: string) => void;
+  /** Diagnostics sink for the one-time "no ledger yet" notices (default: process.stderr). */
+  notice?: (line: string) => void;
+  /** Aborting stops a following tail (the CLI wires Ctrl-C here). */
+  signal?: AbortSignal;
+};
+
+/** Every action ledger a world service currently owns. One world service can record actions
+ * under one or more STATE services (see runtime.ts `worldServiceStateService`), so this returns
+ * every `<data>/<service>/<state-dir>/world/<state-service>/actions.jsonl` present right now. */
+function serviceLedgers(dataDir: string, service: string, file: 'actions.jsonl' | 'requests.jsonl' = 'actions.jsonl'): string[] {
+  const stateRoot = join(dataDir, service, stateDirName(), 'world');
+  if (!existsSync(stateRoot)) return [];
+  return readdirSync(stateRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(stateRoot, entry.name, file)))
+    .map((entry) => join(stateRoot, entry.name, file))
+    .sort();
+}
+
+/** Read the complete lines appended to `path` since the recorded offset, advancing the offset
+ * only past the last newline — a half-written trailing line stays unconsumed until the writer
+ * finishes it, so a poll can never emit a torn row. */
+function readNewLines(path: string, offsets: Map<string, number>): string[] {
+  let offset = offsets.get(path) ?? 0;
+  let size: number;
+  try {
+    size = statSync(path).size;
+  } catch {
+    return []; // vanished between discovery and read (e.g. a purge mid-tail) — next poll rediscovers
+  }
+  if (size < offset) offset = 0; // rewritten shorter (scrub/rebuild) — replay rather than silently skip
+  if (size === offset) return [];
+  const fd = openSync(path, 'r');
+  const buffer = Buffer.alloc(size - offset);
+  try {
+    readSync(fd, buffer, 0, buffer.length, offset);
+  } finally {
+    closeSync(fd);
+  }
+  const lastNewline = buffer.lastIndexOf(0x0a);
+  if (lastNewline < 0) return [];
+  offsets.set(path, offset + lastNewline + 1);
+  return buffer.subarray(0, lastNewline).toString('utf8').split('\n').filter((line) => line.trim() !== '');
+}
+
+/** Local wall-clock `HH:MM:SS.mmm` — the operator is watching a live feed on this machine. */
+function formatOccurredAt(occurredAt: string | undefined): string {
+  const date = occurredAt === undefined ? new Date(NaN) : new Date(occurredAt);
+  if (Number.isNaN(date.getTime())) return '??:??:??.???';
+  const pad = (value: number, width = 2) => String(value).padStart(width, '0');
+  return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}`;
+}
+
+/** The instant an entry sorts (and renders) by: actions carry `occurredAt`, request rows `at`. */
+function entryInstant(entry: TailEntry): string | undefined {
+  return entry.record.occurredAt ?? entry.record.at;
+}
+
+function formatEntry(entry: TailEntry, json: boolean): string {
+  if (json) return JSON.stringify({ ...entry.record, service: entry.service });
+  const { record } = entry;
+  if (entry.source === 'requests') {
+    // a served request, not an action: `HH:MM:SS.mmm <service> <METHOD> <path> <status> in <ms>ms`, and —
+    // when the caller presented one — which credential arrived, named and fingerprinted. The
+    // fingerprint is short on purpose: enough to see "these two headers carried DIFFERENT keys"
+    // and "this is the same key as the line above" at a glance, never enough to be a secret.
+    const creds = (record.credentials ?? [])
+      .map((c) => `${c.name ?? '?'}${c.in === 'query' ? '(query)' : ''}=${c.empty ? 'EMPTY' : `${c.scheme ? `${c.scheme} ` : ''}${(c.fp ?? '').replace(/^sha256:/, '').slice(0, 8)}`}`)
+      .join(' ');
+    return `${formatOccurredAt(entryInstant(entry))} ${entry.service} ${record.method ?? '?'} ${record.path ?? '?'} ${record.status ?? '?'}${typeof record.ms === 'number' ? ` in ${record.ms}ms` : ''}${creds ? ` [${creds}]` : ''}`;
+  }
+  return `${formatOccurredAt(record.occurredAt)} ${entry.service} ${record.operation ?? record.op ?? '?'} ${record.subject?.id ?? '?'}`;
+}
+
+/** Stable causal order: the entry instant first; ties keep discovery order (service, file, line). */
+function byOccurredAt(a: TailEntry, b: TailEntry): number {
+  return (entryInstant(a) ?? '') < (entryInstant(b) ?? '') ? -1
+    : (entryInstant(a) ?? '') > (entryInstant(b) ?? '') ? 1 : 0;
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const finish = (): void => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', finish);
+      resolve();
+    };
+    const timer = setTimeout(finish, ms);
+    signal?.addEventListener('abort', finish, { once: true });
+  });
+}
+
+/**
+ * Stream a world's action ledgers as one merged feed: dump everything recorded so far in
+ * `occurredAt` order, then (unless `follow` is false) poll for appends until `signal` aborts.
+ * New entries within each poll batch are `occurredAt`-sorted too, so concurrent services still
+ * read causally; cross-batch order is arrival order, as in any live tail.
+ */
+export async function tailWorldActions(name: string, options: TailWorldOptions = {}): Promise<void> {
+  const root = options.root ?? process.cwd();
+  const instance = statusWorld(name, root);
+  const known = Object.keys(instance.services);
+  for (const service of options.services ?? []) {
+    if (!instance.services[service]) {
+      throw new Error(`World ${name} has no service "${service}"; it has: ${known.join(', ')}`);
+    }
+  }
+  const services = options.services?.length ? options.services : known;
+  const follow = options.follow ?? true;
+  const json = options.json ?? false;
+  const pollMs = options.pollMs ?? 200;
+  const write = options.write ?? ((line: string) => process.stdout.write(`${line}\n`));
+  const notice = options.notice ?? ((line: string) => process.stderr.write(`${line}\n`));
+
+  const offsets = new Map<string, number>();
+  const sources: Array<'actions' | 'requests'> = options.requests ? ['actions', 'requests'] : ['actions'];
+  const collect = (): TailEntry[] => {
+    const entries: TailEntry[] = [];
+    for (const service of services) {
+      for (const source of sources) {
+        for (const ledger of serviceLedgers(instance.dirs.data, service, source === 'actions' ? 'actions.jsonl' : 'requests.jsonl')) {
+          for (const line of readNewLines(ledger, offsets)) {
+            try {
+              entries.push({ service, record: JSON.parse(line) as TailRecord, source });
+            } catch {
+              // a corrupt row must not kill a live feed; the ledger itself is untouched
+            }
+          }
+        }
+      }
+    }
+    return entries.sort(byOccurredAt);
+  };
+
+  const emit = (entries: TailEntry[]): void => {
+    for (const entry of entries) write(formatEntry(entry, json));
+  };
+
+  emit(collect());
+  for (const service of services) {
+    if (serviceLedgers(instance.dirs.data, service).length === 0) {
+      notice(`World ${name}: service "${service}" has no action ledger yet${follow
+        ? ' — watching; drive the app (or a vendor SDK) through the world to record actions'
+        : '; drive the app (or a vendor SDK) through the world to record actions, then tail again'}`);
+    }
+  }
+  if (!follow) return;
+
+  while (!options.signal?.aborted) {
+    await sleep(pollMs, options.signal);
+    if (options.signal?.aborted) return;
+    emit(collect());
+  }
+}

package/src/tcp-port.ts

@@ -0,0 +1,35 @@
+import { createServer } from 'node:net';
+
+/** Select a port and exclude it from later selections. The probe closes before returning. */
+export async function allocatePort(excluded: Set<number> = new Set()): Promise<number> {
+  for (let attempt = 0; attempt < 32; attempt++) {
+    let port: number;
+    try {
+      port = await probePort();
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'EADDRINUSE') continue;
+      throw error;
+    }
+    if (excluded.has(port)) continue;
+    excluded.add(port);
+    return port;
+  }
+  throw new Error('Could not allocate a TCP port after 32 attempts');
+}
+
+function probePort(): Promise<number> {
+  return new Promise((resolvePort, reject) => {
+    const server = createServer();
+    server.once('error', reject);
+    // Match serveHttp's default scope; a loopback-only probe can miss a wildcard listener.
+    server.listen(0, '0.0.0.0', () => {
+      const address = server.address();
+      if (!address || typeof address === 'string') {
+        server.close(() => reject(new Error('Could not allocate a TCP port')));
+        return;
+      }
+      const port = address.port;
+      server.close((error) => error ? reject(error) : resolvePort(port));
+    });
+  });
+}

package/src/up-task-worker.ts

@@ -0,0 +1,40 @@
+import { recordWorldLifecycleEvent } from './lifecycle-record.ts';
+import { upWorld } from './runtime.ts';
+import { loadWorldConfig } from './configs.ts';
+
+const worldNameOf = (configId: string, root: string): string => { try { return loadWorldConfig(configId, root).config.id; } catch { return configId; } };
+import type { UpTaskReply, UpTaskRequest } from './up-task.ts';
+
+// The boot's owner (./up-task.ts). Only the caller's explicit cancel aborts the boot; a lost caller does not, and the
+// boot's outcome, which the caller can no longer print, goes to the lifecycle log.
+if (!process.send) throw new Error('World boot owner requires its private lifetime channel');
+const abort = new AbortController();
+let started = false;
+let callerLost = false;
+process.on('disconnect', () => {
+  callerLost = true;
+  if (!started) process.exit(0);
+});
+// A dead caller may also close the output reader. Reporting must not kill the boot.
+process.stdout.on('error', () => {});
+process.stderr.on('error', () => {});
+process.on('message', async message => {
+  const request = message as UpTaskRequest | { type: 'cancel'; signal: 'SIGINT' | 'SIGTERM' };
+  if (request.type === 'cancel') { abort.abort(request.signal); return; }
+  if (request.type !== 'start' || started) return;
+  started = true;
+  let reply: UpTaskReply;
+  try { reply = { instance: await upWorld(request.configId, request.options, abort.signal) }; }
+  catch (error) { reply = { error: error instanceof Error ? error.message : String(error) }; }
+  if (callerLost && 'instance' in reply) {
+    try { recordWorldLifecycleEvent(reply.instance.root, reply.instance.name, 'boot completed after its caller went away; the World is up'); } catch { /* the World is up regardless */ }
+  }
+  if (callerLost && 'error' in reply) {
+    // The caller that would have printed the reason is gone; the lifecycle log keeps it (upWorld also records its own
+    // boot failure there, but a failure before the lifecycle claim would otherwise leave nothing).
+    try { recordWorldLifecycleEvent(request.options.root ?? process.cwd(), request.options.name ?? worldNameOf(request.configId, request.options.root ?? process.cwd()), `boot failed after its caller went away: ${reply.error}`); } catch { /* nowhere left to write it */ }
+  }
+  if ('error' in reply && !process.connected) process.stderr.write(`${reply.error}\n`);
+  if (process.connected) process.send!(reply, () => process.exit('error' in reply ? 1 : 0));
+  else process.exit('error' in reply ? 1 : 0);
+});