@volter/world-runtime 3.0.100 → 3.0.102

package/src/pglite-backing.ts

@@ -12,7 +12,8 @@
 // services only. A definition declaring mysql without a container runtime is
 // refused with the kinds named, never half-booted. Redis never reaches it: every
 // redis service is the redis twin's (redis-backing.ts).
-import { appendFileSync, closeSync, cpSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { appendFileSync, closeSync, cpSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { connect } from 'node:net';
 import { dirname, join } from 'node:path';
 import { spawn, type ChildProcess } from 'node:child_process';
@@ -22,7 +23,7 @@ import { publishProcessReceipt, readProcessReceipt, readSpawnReceipt, spawnRecei
 import { errorMessage } from './error-message.ts';
 import { fileURLToPath } from 'node:url';
 import { parse } from 'yaml';
-import { mongodbArgv, mongodbListening, mongodbReady } from './mongodb-backing.ts';
+import { mongodbArgv, mongodbReady, mongodbServes } from './mongodb-backing.ts';
 
 export interface InfraService { kind: string; hostPort: number; replicaSet?: string; postgres?: { user: string; database: string; password?: string } }
 
@@ -154,14 +155,44 @@ export function unsupportedKinds(services: InfraService[]): string[] {
   return [...new Set(services.filter((s) => CONTAINERLESS[s.kind] === undefined).map((s) => s.kind))];
 }
 
-/** The line each host prints once ITS OWN listener is bound: readiness is taken from the child, never
- *  from a connect to the port, which any other process holding the port would answer. */
-function readyLine(port: number): string {
-  return `serving postgres wire protocol on 127.0.0.1:${port}`;
+/**
+ * What `up` means for a managed database (architecture, managed infrastructure): it answers its own protocol on its
+ * port, as pg_isready and a compose healthcheck ask, and the answer is this host's. Readiness never reads a log line.
+ * The PGlite host writes its own listener receipt once its socket is bound ({version, pid, port, boot}, pglite-host.mjs
+ * --listening-file); MongoDB's server names its own pid in serverStatus. The log is for people.
+ */
+function listeningReceiptPath(pidFile: string): string {
+  return pidFile.replace(/\.pid$/, '.listening.json');
+}
+
+function listeningReceipt(path: string): { pid: number; port: number; boot: string | null } | undefined {
+  let text: string;
+  try { text = readFileSync(path, 'utf8'); } catch { return undefined; }
+  try {
+    const value = JSON.parse(text) as { version?: unknown; pid?: unknown; port?: unknown; boot?: unknown };
+    if (value.version !== 1 || !Number.isSafeInteger(value.pid) || !Number.isSafeInteger(value.port)) return undefined;
+    return { pid: value.pid as number, port: value.port as number, boot: typeof value.boot === 'string' ? value.boot : null };
+  } catch { return undefined; }
+}
+
+/** Postgres's own first exchange: an SSLRequest answered with one byte, 'N' or 'S' (pg_isready's question). */
+function postgresAnswers(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = connect({ host: '127.0.0.1', port, timeout: 1000 });
+    socket.once('connect', () => socket.write(Buffer.from([0, 0, 0, 8, 0x04, 0xd2, 0x16, 0x2f])));
+    socket.once('data', (chunk: Buffer) => { socket.destroy(); resolve(chunk[0] === 0x4e || chunk[0] === 0x53); });
+    socket.on('error', () => resolve(false));
+    socket.on('timeout', () => { socket.destroy(); resolve(false); });
+  });
 }
 
-function logSince(log: string, offset: number): string {
-  return readFileSync(log).subarray(offset).toString('utf8');
+/** Whether this host serves: its own receipt names it on the port (for this boot, when one is given), and the port
+ *  answers the service's protocol. */
+async function hostServes(service: InfraService, pidFile: string, pid: number, boot?: string): Promise<boolean> {
+  if (service.kind === 'mongodb') return mongodbServes(service, pid);
+  const receipt = listeningReceipt(listeningReceiptPath(pidFile));
+  if (!receipt || receipt.pid !== pid || receipt.port !== service.hostPort || (boot !== undefined && receipt.boot !== boot)) return false;
+  return postgresAnswers(service.hostPort);
 }
 
 /**
@@ -272,8 +303,10 @@ export async function pgliteUp(services: InfraService[], dataDir: string, launch
       mkdirSync(serviceData, { recursive: true });
       mkdirSync(dirname(log), { recursive: true });
       if (placed.note) { appendFileSync(log, `${placed.note}\n`); launch.note?.(placed.note); }
-      const offset = existsSync(log) ? statSync(log).size : 0;
-      const [command, ...args] = placed.placed ? [...argv, '--prepared'] : argv;
+      // This boot's token, which the host writes into its listener receipt; an earlier receipt is never this one's.
+      const boot = randomUUID();
+      rmSync(listeningReceiptPath(pidFile), { force: true });
+      const [command, ...args] = [...(placed.placed ? [...argv, '--prepared'] : argv), ...(service.kind === 'postgres' ? ['--listening-file', listeningReceiptPath(pidFile), '--boot', boot] : [])];
       // a real fd, not a pipe: the host must outlive this process untethered
       const logFd = openSync(log, 'a');
       const child = spawn(command!, args, {
@@ -300,16 +333,15 @@ export async function pgliteUp(services: InfraService[], dataDir: string, launch
       publishProcessReceipt(pidFile, `${child.pid}\n`);
       launch.note?.(`${name} spawned`);
       const deadline = Date.now() + READY_TIMEOUT_MS;
-      const line = readyLine(service.hostPort);
-      // ready when OUR child says its listener is bound (a squatter that took the port after the check
-      // above makes the child fail its bind and exit, never print this) and the port answers
-      while (!(alive(child.pid!) && (service.kind === 'mongodb' ? mongodbListening(logSince(log, offset), service.hostPort) : logSince(log, offset).includes(line)) && await listening(service.hostPort))) {
+      // Ready when the port answers the service's protocol and the answer is this child's: its own receipt (PGlite)
+      // or its own serverStatus (MongoDB). A squatter that took the port after the check above makes the child fail
+      // its bind and exit, and never answers as this child.
+      while (!(alive(child.pid!) && await hostServes(service, pidFile, child.pid!, service.kind === 'postgres' ? boot : undefined))) {
         if (spawnError) throw spawnError;
         if (!alive(child.pid!)) throw new Error(`${name} exited before serving — see ${log}`);
         if (Date.now() > deadline) throw new Error(`${name} did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
         // an aborted boot (Ctrl-C during up) stops waiting; the catch below ends what this up started
         launch.signal?.throwIfAborted();
-        // the ready line is a small log read, and the port is asked only once it is there
         await sleep(25);
       }
       launch.note?.(`${name} serving on 127.0.0.1:${service.hostPort}`);
@@ -333,7 +365,7 @@ export async function pgliteStatus(services: InfraService[], dataDir: string): P
     const pidFile = pidPath(dataDir, service.kind);
     const ownership = hostOwnership(pidFile);
     if (ownership.errors.length) throw new AggregateError(ownership.errors, 'Managed infrastructure ownership uncertain; retry down');
-    if (!ownership.readyReceipt || !ownership.pid || !alive(ownership.pid) || !(await listening(service.hostPort))) continue;
+    if (!ownership.readyReceipt || !ownership.pid || !alive(ownership.pid) || !(await hostServes(service, pidFile, ownership.pid))) continue;
     if (ownership.identity) await verifySpawnIdentity(ownership.identity);
     if (service.kind === 'mongodb') {
       await mongodbReady(service, {}, Date.now() + READY_TIMEOUT_MS, false);

package/src/pglite-host.mjs

@@ -63,7 +63,7 @@
 // Randomness remains the host's own; no database schema objects are installed.
 import { errorMessage } from './error-message.mjs';
 import net from 'node:net';
-import { mkdirSync, readFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import clockForm from '@volter/world-core/world-clock';
 import { fromNodeSocket } from 'pg-gateway/node';
 import { BackendError } from 'pg-gateway';
@@ -122,6 +122,12 @@ function arg(name) {
 // path a serving host takes, close it cleanly and exit without listening. The World's image build runs it on the
 // host so the tab opens an existing cluster (pglite-backing.ts, pglitePrepare).
 const preparing = process.argv.includes('--prepare');
+// --listening-file <path> --boot <token>: once the listener is bound, the host writes its own receipt there
+// ({version, pid, port, boot}); the backing reads it as this host's ownership of the port (pglite-backing.ts). Readiness
+// is the port answering Postgres's own protocol; the stdout line is for people only.
+const optional = (name) => { const index = process.argv.indexOf(name); return index >= 0 ? process.argv[index + 1] : undefined; };
+const listeningFile = optional('--listening-file');
+const bootToken = optional('--boot');
 // --prepared: the data directory is a cluster `--prepare` made for this declared identity (pglite-backing.ts checks
 // its stamp before passing this), so the declared database and role exist and the maintenance open is skipped.
 const prepared = process.argv.includes('--prepared');
@@ -649,6 +655,11 @@ if (preparing) void dbReady.then(async (db) => {
 else void dbReady.then(() => {
   clearInterval(initKeepAlive);
   server.listen(port, '127.0.0.1', () => {
+    if (listeningFile) {
+      const temporary = `${listeningFile}.${process.pid}.tmp`;
+      writeFileSync(temporary, `${JSON.stringify({ version: 1, pid: process.pid, port, boot: bootToken ?? null })}\n`, { mode: 0o600 });
+      renameSync(temporary, listeningFile);
+    }
     process.stdout.write(`pglite-host serving postgres wire protocol on 127.0.0.1:${port}\n`);
   });
 });

package/src/process-signal.mjs

@@ -20,10 +20,19 @@ export async function processBirth(pid) {
     } catch { return undefined; }
   }
   return new Promise(resolve => {
-    const child = spawn('ps', ['-o', 'pid=,lstart=', '-p', String(pid)], {
-      windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'],
-      env: { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' },
-    });
+    // A probe that cannot run is a birth unknown, never a lifecycle failure: spawn throws synchronously where the
+    // process may not exec `ps` at all (setuid root on macOS, which a sandbox-exec profile refuses: EPERM), and reports
+    // other failures as 'error' (below). Either way the identity is the pid without a start time.
+    let child;
+    try {
+      child = spawn('ps', ['-o', 'pid=,lstart=', '-p', String(pid)], {
+        windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'],
+        env: { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' },
+      });
+    } catch {
+      resolve(undefined);
+      return;
+    }
     let output = '', settled = false;
     const finish = value => { if (!settled) { settled = true; clearTimeout(timer); child.stdout.destroy(); resolve(value); } };
     // This is our still-held inspector, not a PID from a receipt.

package/src/redis-backing.ts

@@ -54,6 +54,27 @@ function listening(port: number): Promise<boolean> {
   });
 }
 
+/** Whether the Redis answering on the port is this child (architecture D9): its own INFO server names its process_id, as
+ *  Redis's does. A port that answers as another process, or does not answer yet, is not this child's. */
+function redisServes(port: number, pid: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = connect({ host: '127.0.0.1', port, timeout: 1000 });
+    let reply = '';
+    socket.once('connect', () => socket.write('*2\r\n$4\r\nINFO\r\n$6\r\nserver\r\n'));
+    socket.on('data', (chunk: Buffer) => {
+      reply += chunk.toString('latin1');
+      // a bulk string: $<length>\r\n<body>\r\n
+      const head = /^\$(\d+)\r\n/.exec(reply);
+      if (!head) { if (!reply.startsWith('$') || reply.includes('\r\n')) { socket.destroy(); resolve(false); } return; }
+      if (Buffer.byteLength(reply, 'latin1') < head[0].length + Number(head[1]) + 2) return;
+      socket.destroy();
+      resolve(Number(/(?:^|\r\n)process_id:(\d+)\r\n/.exec(reply.slice(head[0].length))?.[1]) === pid);
+    });
+    socket.on('error', () => resolve(false));
+    socket.on('timeout', () => { socket.destroy(); resolve(false); });
+  });
+}
+
 const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
 export async function redisTwinUp(services: InfraService[], dataDir: string, cli: string, launch: HostLaunch = {}): Promise<void> {
@@ -93,11 +114,11 @@ export async function redisTwinUp(services: InfraService[], dataDir: string, cli
       publishProcessReceipt(spawnReceiptPath(pidFile), JSON.stringify(identity) + '\n');
       publishProcessReceipt(pidFile, `${held.child.pid}\n`);
       const deadline = Date.now() + READY_TIMEOUT_MS;
-      while (!(await listening(service.hostPort)) || !alive(held.child.pid)) {
+      while (!alive(held.child.pid) || !(await redisServes(service.hostPort, held.child.pid))) {
         if (!alive(held.child.pid)) throw new Error(`redis exited before serving — see ${log}`);
         launch.signal?.throwIfAborted();
         if (Date.now() > deadline) throw new Error(`redis did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
-        await sleep(200);
+        await sleep(25);
       }
       launch.signal?.throwIfAborted();
       held.child.unref();
@@ -116,7 +137,8 @@ export async function redisTwinStatus(services: InfraService[], dataDir: string)
   for (const service of services) {
     const pidFile = pidPath(dataDir, service);
     if (!existsSync(pidFile)) continue;
-    if (alive(Number(readFileSync(pidFile, 'utf8').trim())) && await listening(service.hostPort)) ready += 1;
+    const pid = Number(readFileSync(pidFile, 'utf8').trim());
+    if (alive(pid) && await redisServes(service.hostPort, pid)) ready += 1;
   }
   return ready;
 }

package/src/runtime.ts

@@ -28,7 +28,7 @@ import { packFacts } from './pack-facts.ts';
 import { assertOwnedRealPath, ownedPath } from './owned-path.ts';
 import { isEnvironmentName } from './schema.ts';
 import { infraConnections, parseInfraDefinition } from './pglite-backing.ts';
-import { describeServiceEnd, readServiceEnd, serviceOutput } from './service-exit.ts';
+import { describeServiceEnd, readServiceEnd } from './service-exit.ts';
 import { Socket } from 'node:net';
 import { getActiveWorldStore, withFileLock, stateDirName, PROTOCOL_VERSION, PROTOCOL_MAJOR, protocolStanding, WORLD_BOOT_PATH, WORLD_DATA_ENV, WORLD_ENV_NAMES_ENV } from '@volter/world-core/runtime';
 import { loadWorldConfig } from './configs.ts';
@@ -60,22 +60,6 @@ function heldStarts(): Record<string, string | undefined> {
   return Object.fromEntries([...spawnedIdentities].map(([pid, identity]) => [pid, identity.start]));
 }
 
-/** The latest `limit` bytes of a service log, reaching into its one rotation (`<log>.1`) when the current file is
- *  shorter: a readiness line printed just before a rotation is still found, and a poll never reads 64 MiB files. */
-function readServiceText(log: string, limit = 4 * 1024 * 1024): string {
-  const tailOfFile = (path: string, bytes: number): string => {
-    if (bytes <= 0 || !existsSync(path)) return '';
-    const fd = openSync(path, 'r');
-    try {
-      const size = fstatSync(fd).size, start = Math.max(0, size - bytes), buffer = Buffer.alloc(size - start);
-      readSync(fd, buffer, 0, buffer.length, start);
-      return buffer.toString('utf8');
-    } finally { closeSync(fd); }
-  };
-  const current = tailOfFile(log, limit);
-  return `${tailOfFile(`${log}.1`, limit - Buffer.byteLength(current))}${current}`;
-}
-
 /** The World's events file: every service's start and end, and the World's own stops, one JSON line each. */
 export function worldEventsPath(logs: string): string {
   return join(logs, 'events.jsonl');
@@ -127,39 +111,23 @@ async function untilReadyOrEnded<T>(wait: (abort: AbortSignal) => Promise<T>, en
   });
 }
 
-/** That the process answering a service's port is the service. allocatePort closes its probe before the service
- *  binds, so another process can take the port and answer the first connect; the service then fails to bind and ends
- *  at once, which a short settle catches for any program. A World twin also answers WORLD_BOOT_PATH with the boot it
- *  belongs to, so a leftover World's twin on the port is named exactly; a server that does not answer the path (a
- *  twin from before it, a program that is not a twin) is accepted on the settle alone. When the settle guards this
- *  port alone (`early`), a twin's answer with this boot's id ends it early: a server of this boot holds the port, and
- *  every port this boot assigns is kept apart from its siblings', so short of the kernel handing the just-probed port
- *  to another of this boot's port-0 listeners, that server is the service just started. A settle standing for several
- *  ports runs in full unless an all-started receipt permits each port's own early identity confirmation.
- *  Programs that are not twins are never asked. A shared settle keeps legacy co-located ports within one guard. */
-async function confirmOwnPort(port: number, boot: BootContext, ended: Promise<void> | undefined, twin: boolean, what: string, log: string, early = false, sharedSettle?: Promise<'alive'>): Promise<void> {
-  // A twin is asked at once, raced with the settle: a server slow to answer costs no more than the settle did.
+/** That the process answering a service's port is the service, decided by an answer and never by a timed settle
+ *  (architecture D9). A World twin answers WORLD_BOOT_PATH with the boot it belongs to: this boot's id is the proof; another
+ *  boot's is a leftover World on the port, refused by name. A program that answers no boot identity (one that is not a
+ *  twin) is the service when it is still running once its port answers: another process holding the port makes the
+ *  service's own bind fail, which ends it, and its end is named. A co-located host's twins are vouched for by its
+ *  all-started receipt first (ADR 0012, ADR 0014). */
+async function confirmOwnPort(port: number, boot: BootContext, ended: Promise<void> | undefined, twin: boolean, what: string, log: string): Promise<void> {
   boot.signal.throwIfAborted();
-  const answer = twin ? worldBootOf(port, boot.signal) : Promise.resolve(null);
-  const own = early && twin ? answer.then((a) => (a && a.boot === boot.bootId ? 'own' as const : new Promise<never>(() => undefined))) : new Promise<never>(() => undefined);
-  // `ended` absent: the process was already settled (a co-located host settles once for all its twins).
-  if (ended) {
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    let settled: 'own' | 'ended' | 'alive';
-    try {
-      const settle = sharedSettle ?? new Promise<'alive'>((resolveAlive) => { timer = setTimeout(() => resolveAlive('alive'), 300); });
-      settled = await Promise.race([own, ended.then(() => 'ended' as const), settle]);
-    } finally { if (timer !== undefined) clearTimeout(timer); }
-    boot.signal.throwIfAborted();
-    if (settled === 'own') return;
-    if (settled === 'ended') throw new Error(`${what} ended right after its port first answered, so another process probably holds the port: the service ${endedAccount(log)}\nLog: ${log}`);
-  }
-  if (!twin) return;
-  const answered = await answer;
+  const answered = twin ? await worldBootOf(port, boot.signal) : null;
   boot.signal.throwIfAborted();
-  if (answered && typeof answered.boot === 'string' && answered.boot !== boot.bootId) {
+  if (answered && typeof answered.boot === 'string') {
+    if (answered.boot === boot.bootId) return;
     throw new Error(`${what}: its port is answered by a twin of another World boot (${answered.boot}), not this one; a leftover World holds the port. Stop it (\`volter-world list\`, then \`down\`) and retry.\nLog: ${log}`);
   }
+  // Whether the service has already ended, read now: one turn of the event loop, not a wait for it to fail.
+  const endedNow = ended ? await Promise.race([ended.then(() => true), new Promise<boolean>((resolveNow) => setImmediate(() => resolveNow(false)))]) : false;
+  if (endedNow) throw new Error(`${what} ended right after its port first answered, so another process probably holds the port: the service ${endedAccount(log)}\nLog: ${log}`);
 }
 
 /** What the server on a loopback port says its World boot is (WORLD_BOOT_PATH), or null. A direct loopback request:
@@ -1203,7 +1171,7 @@ async function runOwnInfrastructureUp(command: string[], serviceId: string, env:
 
 /** Resolve `${url}`/`${host}`/`${port}` in a readiness probe's httpUrl against an owned loopback
  * service's allocated port (process/twin readiness — the port is auto-assigned, so it can't be a
- * literal in the config). Other probe kinds (command/stdoutMatch) are returned unchanged. */
+ * literal in the config). A command probe is returned unchanged. */
 function resolveReadyProbe(ready: WorldExternalReadyWhen, svc: { host: string; port: number; url: string }): WorldExternalReadyWhen {
   if (ready.httpUrl === undefined) return ready;
   const httpUrl = ready.httpUrl
@@ -1215,7 +1183,6 @@ function resolveReadyProbe(ready: WorldExternalReadyWhen, svc: { host: string; p
 
 async function awaitReadiness(
   ready: WorldExternalReadyWhen | undefined,
-  logPath: string,
   cwd: string,
   serviceId: string,
   env: NodeJS.ProcessEnv = process.env,
@@ -1244,10 +1211,6 @@ async function awaitReadiness(
       } catch (error) {
         lastError = errorMessage(error);
       }
-    } else if (ready.stdoutMatch !== undefined) {
-      const text = serviceOutput(readServiceText(logPath));
-      if (new RegExp(ready.stdoutMatch).test(text)) return passed(`the log matched /${ready.stdoutMatch}/`);
-      lastError = `pattern /${ready.stdoutMatch}/ not yet in service log`;
     }
     // A service that is nearly ready is seen at once; one that is slow is asked at most every intervalMs.
     await sleep(Math.min(intervalMs, 25 * 2 ** attempt));
@@ -1302,7 +1265,7 @@ async function startExternalService(
   boot?.progress(`${service.id}: up returned`);
 
   // 2. readiness — Docker-backed externals take seconds to boot.
-  const readiness = await awaitReadiness(external.readyWhen, log, cwd, service.id, env, boot?.signal);
+  const readiness = await awaitReadiness(external.readyWhen, cwd, service.id, env, boot?.signal);
   boot?.progress(`${service.id}: ready (${readiness})`);
 
   // 3. status — discover connection info (optional; may reuse up output instead).
@@ -1455,7 +1418,7 @@ async function startService(
   });
   boot.progress(`${service.id}: port ${port} answers`);
 
-  await confirmOwnPort(port, boot, ended, (service.type ?? 'twin') === 'twin', `Service "${service.id}"`, log, true).catch(async (error) => {
+  await confirmOwnPort(port, boot, ended, (service.type ?? 'twin') === 'twin', `Service "${service.id}"`, log).catch(async (error) => {
     if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
     try { await signalHeldChild(child, 'SIGTERM', true, identity); } catch { /* best effort cleanup */ }
     throw error;
@@ -1471,10 +1434,10 @@ async function startService(
   const url = `http://${host}:${port}`;
   boot.progress(`${service.id}: port ${port} is its own`);
 
-  // Optional readiness probe beyond TCP (httpUrl/command/stdoutMatch): a process can bind its port
+  // Optional readiness probe beyond TCP (httpUrl/command): a process can bind its port
   // before it is actually serving, so this makes `up` wait until the service truly responds.
   if (service.ready && service.ready !== 'tcp') {
-    const readiness = await untilReadyOrEnded((abort) => awaitReadiness(resolveReadyProbe(service.ready as Exclude<typeof service.ready, 'tcp' | undefined>, { host, port, url }), log, cwd, service.id, env, abort), ended, boot, 'the service', log).catch(async (error) => {
+    const readiness = await untilReadyOrEnded((abort) => awaitReadiness(resolveReadyProbe(service.ready as Exclude<typeof service.ready, 'tcp' | undefined>, { host, port, url }), cwd, service.id, env, abort), ended, boot, 'the service', log).catch(async (error) => {
       if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (startup failed)', 'SIGTERM');
       try { await signalHeldChild(child, 'SIGTERM', true, identity); } catch { /* best effort cleanup */ }
       throw new Error(`Service "${service.id}" failed its readiness probe: ${errorMessage(error)}\nLog: ${log}`);
@@ -1882,11 +1845,10 @@ async function startColocatedServices(
     // The host's receipt (this boot, every requested port) is published only
     // after every factory bound its own port; a port another process held fails
     // its bind and leaves no receipt. The receipt is the host's ownership proof
-    // for each port, so no twin waits out a settle (ADR 0014). A port that
-    // answers with another boot's identity is still refused.
-    const hostSettle = Promise.resolve('alive' as const);
+    // for each port (ADR 0014). A port that answers with another boot's identity
+    // is still refused.
     await parallelStartup(allocated, async ({ service, port }) => {
-      await confirmOwnPort(port, boot, ended, true, `Co-located twin "${service.id}"`, log, true, hostSettle).catch(async (error) => {
+      await confirmOwnPort(port, boot, ended, true, `Co-located twin "${service.id}"`, log).catch(async (error) => {
         if (undeadPids([child.pid!]).length) recordWorldStop([log], 'world.service.stop', 'up (port not its own)', 'SIGTERM');
         try { await signalHeldChild(child, 'SIGTERM', true, identity); } catch { /* best effort cleanup */ }
         throw error;
@@ -2903,30 +2865,36 @@ function canonicalDottedIpv4(host: string): boolean {
 function parseCustomShareOrigin(handshake: string): string {
   const raw = /^https?:\/\/(\[[0-9a-f:.]+\]|[a-z0-9.-]+)(?::([0-9]{1,5}))?\/?$/i.exec(handshake);
   if (!raw) {
-    throw new Error(`Custom tunnel VOLTER_SHARE_URL must be a strict http(s) origin without path, query, fragment, or backslashes: ${handshake}`);
+    throw new Error(`The URL a custom tunnel wrote to VOLTER_SHARE_URL_FILE must be a strict http(s) origin without path, query, fragment, or backslashes: ${handshake}`);
   }
   const rawHost = raw[1]!;
   const rawPort = raw[2];
   let parsed: URL;
   try { parsed = new URL(handshake); }
-  catch { throw new Error(`Custom tunnel emitted an invalid VOLTER_SHARE_URL handshake: ${handshake}`); }
+  catch { throw new Error(`A custom tunnel wrote an invalid URL to VOLTER_SHARE_URL_FILE: ${handshake}`); }
   const normalizedHostname = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase();
   if (!rawHost.startsWith('[') && isIP(normalizedHostname) === 4
     && (!canonicalDottedIpv4(rawHost) || rawHost !== normalizedHostname)) {
-    throw new Error(`Custom tunnel VOLTER_SHARE_URL must use canonical dotted-decimal IPv4 syntax: ${handshake}`);
+    throw new Error(`The URL a custom tunnel wrote to VOLTER_SHARE_URL_FILE must use canonical dotted-decimal IPv4 syntax: ${handshake}`);
   }
   if (rawPort && rawPort.length > 1 && rawPort.startsWith('0')) {
-    throw new Error(`Custom tunnel VOLTER_SHARE_URL must use canonical decimal port syntax: ${handshake}`);
+    throw new Error(`The URL a custom tunnel wrote to VOLTER_SHARE_URL_FILE must use canonical decimal port syntax: ${handshake}`);
   }
   if ((parsed.protocol !== 'http:' && parsed.protocol !== 'https:') || parsed.username || parsed.password
     || parsed.pathname !== '/' || parsed.search || parsed.hash) {
-    throw new Error(`Custom tunnel VOLTER_SHARE_URL must be a credential-free http(s) origin: ${handshake}`);
+    throw new Error(`The URL a custom tunnel wrote to VOLTER_SHARE_URL_FILE must be a credential-free http(s) origin: ${handshake}`);
   }
   return parsed.origin;
 }
 
-async function waitForPublicUrl(child: ReturnType<typeof spawn>, logPath: string, timeoutMs: number, requireTryCloudflare: boolean): Promise<string> {
-  const urlPattern = /https?:\/\/[^\s"'<>]+/gi;
+/** Where a tunnel answers its public URL: cloudflared's metrics server, or the file a custom command writes. */
+type PublicUrlSource = { metricsPort: number } | { urlFile: string };
+
+/** The tunnel's public URL, from the tunnel's own answer and never its output (architecture D9). cloudflared's metrics
+ *  server answers GET /quicktunnel with {"hostname"} once the quick tunnel is registered (empty before); a custom command
+ *  writes its public URL to VOLTER_SHARE_URL_FILE, ending the line when it is complete, so a half-written URL is never
+ *  read. The process's log is for people. */
+async function waitForPublicUrl(child: ReturnType<typeof spawn>, source: PublicUrlSource, logPath: string, timeoutMs: number): Promise<string> {
   let exited = false;
   let exitSummary = '';
   child.once('exit', (code, signal) => {
@@ -2940,22 +2908,29 @@ async function waitForPublicUrl(child: ReturnType<typeof spawn>, logPath: string
 
   const started = Date.now();
   while (Date.now() - started < timeoutMs) {
-    const text = existsSync(logPath) ? readFileSync(logPath, 'utf8') : '';
-    if (requireTryCloudflare) {
-      for (const candidate of text.match(urlPattern) ?? []) {
-        const parsed = parseCloudflareQuickPublicUrl(candidate);
-        if (parsed) return parsed;
+    if ('metricsPort' in source) {
+      try {
+        const answer = await fetch(`http://127.0.0.1:${source.metricsPort}/quicktunnel`, { signal: AbortSignal.timeout(1000) });
+        const hostname = answer.ok ? ((await answer.json()) as { hostname?: unknown }).hostname : undefined;
+        if (typeof hostname === 'string' && hostname) {
+          const parsed = parseCloudflareQuickPublicUrl(`https://${hostname}`);
+          if (!parsed) throw new Error(`cloudflared answered /quicktunnel with ${JSON.stringify(hostname)}, not a trycloudflare.com hostname. Log: ${logPath}`);
+          return parsed;
+        }
+      } catch (error) {
+        if (error instanceof Error && error.message.startsWith('cloudflared answered')) throw error;
+        // its metrics server not listening yet: asked again
       }
     } else {
-      const handshake = /^VOLTER_SHARE_URL=(\S+)\s*$/m.exec(text)?.[1];
-      if (handshake) return parseCustomShareOrigin(handshake);
+      const text = existsSync(source.urlFile) ? readFileSync(source.urlFile, 'utf8') : '';
+      if (text.endsWith('\n')) return parseCustomShareOrigin(text.trim());
     }
-    if (exited) throw new Error(`Tunnel process exited before printing a public URL (${exitSummary}). Log: ${logPath}`);
-    await new Promise((resolveWait) => setTimeout(resolveWait, 250));
+    if (exited) throw new Error(`Tunnel process exited before answering its public URL (${exitSummary}). Log: ${logPath}`);
+    await new Promise((resolveWait) => setTimeout(resolveWait, 100));
   }
-  throw new Error(requireTryCloudflare
-    ? `Cloudflare tunnel did not print a trycloudflare.com https URL within ${timeoutMs}ms. Log: ${logPath}`
-    : `Custom tunnel did not print VOLTER_SHARE_URL=<http(s)-url> within ${timeoutMs}ms. Log: ${logPath}`);
+  throw new Error('metricsPort' in source
+    ? `cloudflared's metrics server did not answer a trycloudflare.com hostname at /quicktunnel within ${timeoutMs}ms. Log: ${logPath}`
+    : `Custom tunnel did not write its public URL, newline-terminated, to VOLTER_SHARE_URL_FILE within ${timeoutMs}ms. Log: ${logPath}`);
 }
 
 function sleep(ms: number): Promise<void> {
@@ -3128,12 +3103,18 @@ async function shareWorldReserved(name: string, options: ShareWorldOptions): Pro
 
   const tunnel = shareCommand(options, service.url);
   const log = ownedPath(instance.dirs.logs, `${serviceId}.tunnel.log`);
-  // Each spawned tunnel owns one log generation. Truncating before spawn prevents a repeated
-  // share from accepting the previous process's URL handshake as the new process's endpoint.
+  // The public URL is the tunnel's own answer, never its output (architecture D9): cloudflared's metrics server
+  // answers /quicktunnel with the hostname it registered; a custom command writes its URL to VOLTER_SHARE_URL_FILE.
+  // Each spawned tunnel owns one generation of both, so a repeated share never takes the previous process's URL.
+  const source: PublicUrlSource = tunnel.provider === 'cloudflare-quick'
+    ? { metricsPort: await allocatePort(new Set()) }
+    : { urlFile: ownedPath(instance.dirs.logs, `${serviceId}.tunnel.url`) };
+  if ('urlFile' in source) rmSync(source.urlFile, { force: true });
+  const args = 'metricsPort' in source ? ['tunnel', '--metrics', `127.0.0.1:${source.metricsPort}`, ...tunnel.args.slice(1)] : tunnel.args;
   const out = openPrivateLog(log, 'w');
-  const child = spawn(tunnel.command, tunnel.args, { windowsHide: true,
+  const child = spawn(tunnel.command, args, { windowsHide: true,
     cwd: root,
-    env: withoutVaultSignIn(process.env),
+    env: { ...withoutVaultSignIn(process.env), ...('urlFile' in source ? { VOLTER_SHARE_URL_FILE: source.urlFile } : {}) },
     detached: true,
     stdio: ['ignore', out, out],
   });
@@ -3149,7 +3130,7 @@ async function shareWorldReserved(name: string, options: ShareWorldOptions): Pro
     const identity = await birth;
     if (!identity?.start) throw new Error('Tunnel birth capture failed; retiring held child');
     identities[identity.pid] = identity.start;
-    publicUrl = await waitForPublicUrl(child, log, options.timeoutMs ?? 20_000, tunnel.provider === 'cloudflare-quick');
+    publicUrl = await waitForPublicUrl(child, source, log, options.timeoutMs ?? 20_000);
     if (options.verifyPath !== false) {
       publicVerification = await verifyPublicUrl(publicUrl, options.verifyPath ?? '/health', options.timeoutMs ?? 90_000);
     }
@@ -3167,7 +3148,7 @@ async function shareWorldReserved(name: string, options: ShareWorldOptions): Pro
       provider: tunnel.provider,
       pid: child.pid ?? 0,
       log,
-      command: [tunnel.command, ...tunnel.args],
+      command: [tunnel.command, ...args],
       startedAt: new Date().toISOString(),
     };
     writePidsFromInstance(nextInstance, child.pid ? [child.pid] : []);
@@ -3299,12 +3280,11 @@ const DOCTOR_EXTERNAL_PROBE_TIMEOUT_MS = 3_000;
 /** Run an external service's declared readiness probe exactly ONCE (unlike `awaitReadiness`, which
  * polls until it passes or times out — appropriate at boot, wrong for a doctor health check, which
  * must report the CURRENT state, not wait for it to become healthy). Reuses the same probe shapes
- * (`command`/`httpUrl`/`stdoutMatch`) declared in config for the boot-time `readyWhen`. */
+ * (`command`/`httpUrl`) declared in config for the boot-time `readyWhen`. */
 async function probeExternalOnce(
   ready: WorldExternalReadyWhen,
   cwd: string,
   env: NodeJS.ProcessEnv,
-  logPath: string,
 ): Promise<{ ok: boolean; message: string }> {
   if (ready.command !== undefined) {
     if (!commandExists(ready.command)) {
@@ -3327,12 +3307,7 @@ async function probeExternalOnce(
       return { ok: false, message: `probe failed: ${errorMessage(error)}` };
     }
   }
-  if (ready.stdoutMatch !== undefined) {
-    const text = serviceOutput(readServiceText(logPath));
-    if (new RegExp(ready.stdoutMatch).test(text)) return { ok: true, message: 'probe ok (stdoutMatch)' };
-    return { ok: false, message: `probe pattern /${ready.stdoutMatch}/ not found in log` };
-  }
-  return { ok: false, message: 'malformed readiness probe (no command/httpUrl/stdoutMatch)' };
+  return { ok: false, message: 'malformed readiness probe (no command/httpUrl)' };
 }
 
 /** A stopped service's own account for doctor: how it ended, its last output, and where its whole log is. */
@@ -3402,7 +3377,7 @@ export async function doctorWorld(name: string, options: { root?: string; verify
       const probeCwd = service.external?.cwd ?? root;
       const probeEnv = { ...admittedEnv(stripEnvOf(instance.env ?? {})), ...(instance.env ?? {}), ...(service.external?.discoveredEnv ?? {}) };
       if (configuredExternal?.readyWhen) {
-        const probe = await probeExternalOnce(configuredExternal.readyWhen, probeCwd, probeEnv, service.log);
+        const probe = await probeExternalOnce(configuredExternal.readyWhen, probeCwd, probeEnv);
         checks.push({ id: `service:${service.id}:external`, ok: probe.ok, message: `${discoveredMessage}; ${probe.message}` });
       } else if (configuredExternal?.status) {
         try {
@@ -3437,13 +3412,12 @@ export async function doctorWorld(name: string, options: { root?: string; verify
       checks.push({ id: `service:${service.id}:tcp`, ok: true, message: service.url! });
       // A port that accepts is not a service that answers (a stuck event loop still completes the handshake): the
       // readiness probe the service declared is run again, as it was at boot.
-      // A log pattern matched at boot matches forever, so it cannot tell a hung service: only a probe that asks is re-run,
-      // in the service's own cwd and with its PORT, as at boot.
+      // The probe is re-run in the service's own cwd and with its PORT, as at boot.
       const configured = externalProbeConfig?.services.find((candidate) => candidate.id === service.id);
       const declared = configured?.ready;
-      if (pidLive && declared && declared !== 'tcp' && declared.stdoutMatch === undefined) {
+      if (pidLive && declared && declared !== 'tcp') {
         const probe = await probeExternalOnce(resolveReadyProbe(declared, { host: '127.0.0.1', port: service.port!, url: service.url! }), configured?.cwd ? resolve(root, configured.cwd) : root,
-          { ...admittedEnv(stripEnvOf(instance.env ?? {})), ...(instance.env ?? {}), ...(configured?.env ?? {}), PORT: String(service.port) }, service.log);
+          { ...admittedEnv(stripEnvOf(instance.env ?? {})), ...(instance.env ?? {}), ...(configured?.env ?? {}), PORT: String(service.port) });
         checks.push({ id: `service:${service.id}:ready`, ok: probe.ok,
           message: probe.ok ? probe.message : `its port accepts but its declared readiness probe fails (${probe.message}): the service is up but not answering\n      log: ${service.log}` });
       }