@volter/world-runtime 2.0.0

package/src/cli.ts

@@ -0,0 +1,1111 @@
+#!/usr/bin/env node
+import { sessionTrustEnv } from './ca-trust.ts';
+import { spawn, spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve, resolve as resolvePath } from 'node:path';
+import { activateScript, branchWorld, checkoutWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, resetWorld, seedWorld, worldOrigin, approveWorldChangeset, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, migrateWorldConfig, readReflectRoutes, reflectRoutesPath, replayWorldChangeset, resolveWorldRef, attachWorld, retireWorldConsumers, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, upWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from './index.ts';
+import { formatApplication, formatChangeset, formatRebaseReport, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, parseVerifierExpression } from '@volter/world-core';
+import { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer } from './serve.ts';
+import type { WorldManifest } from './attach.ts';
+import { clockFile, instanceDir, pruneWorlds } from './runtime.ts';
+import { worldResourceReport } from './resources.ts';
+import { worldConsumers, worldUsage } from './consumers.ts';
+import { addAppHosts, appUrlUnsetMessage, detectAppUrl, readAppUrl, setAppUrl } from './app-url.ts';
+import type { PrerequisiteId } from './index.ts';
+import { describeServiceEnd, describeWorldEvent, readServiceEnd, readWorldEvents } from './service-exit.ts';
+import { worldEventsPath } from './runtime.ts';
+import { superviseWorldUp } from './up-task.ts';
+
+/** An option's value, written `--name value` or `--name=value`. */
+function optionValue(args: string[], name: string, fallback = ''): string {
+  const joined = args.find((arg) => arg.startsWith(`${name}=`));
+  if (joined !== undefined) return joined.slice(name.length + 1);
+  const index = args.indexOf(name);
+  return index >= 0 && index + 1 < args.length ? args[index + 1]! : fallback;
+}
+
+function ownerOption(args: string[]): string | undefined {
+  const index = args.indexOf('--owner');
+  if (index < 0) return undefined;
+  const label = args[index + 1];
+  if (!label || label.startsWith('--')) throw new Error('--owner requires a task label');
+  return label;
+}
+
+/** The non-flag args, skipping each value-taking flag's value (so `--root <path>` never
+ * masquerades as a positional service id). */
+function positionalArgs(args: string[], valueFlags: string[] = ['--root']): string[] {
+  const positionals: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]!;
+    if (arg.startsWith('--')) {
+      if (valueFlags.includes(arg)) index += 1;
+      continue;
+    }
+    positionals.push(arg);
+  }
+  return positionals;
+}
+
+/** `--acknowledge vendor=reason` (repeatable) — the shared parse for `covers` and `init`. */
+function acknowledgeOptions(args: string[], command: string): Record<string, string> {
+  const acknowledge: Record<string, string> = {};
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] !== '--acknowledge') continue;
+    const pair = args[index + 1] ?? '';
+    const eq = pair.indexOf('=');
+    if (eq <= 0) throw new Error(`volter-world ${command}: --acknowledge takes vendor=reason (e.g. --acknowledge "svix=verifier-only, no egress")`);
+    acknowledge[pair.slice(0, eq)] = pair.slice(eq + 1);
+  }
+  return acknowledge;
+}
+
+function printHelp(): void {
+  process.stdout.write(`Usage:
+  volter-world init <name> --repo <path> [--out <dir>] [--force] [--allow-unknown] [--acknowledge vendor=reason]... [--json] [--root <repo>]
+                                                  # the FRONT DOOR: detect the repo's vendors, EMIT a world config +
+                                                  # env file OUTSIDE the repo (default <repo>/../<name>-pilot/, the
+                                                  # repo is never written to), then run the coverage proof over the
+                                                  # emission. Exit 0 = ready to \`up\`; exit 1 = the honest worklist.
+                                                  # Deterministic: same repo + same pack catalog => identical bytes.
+                                                  # init DIAGNOSES; it never boots — it prints the exact next commands
+  volter-world up <config> --env-file=<path> [--owner <label>] [--name <name>] [--mode local|share|sealed] [--isolation process|colocated|worker] [--root <repo>]
+  volter-world outdated <world> [--json]            — each mounted twin: pinned / mounted / catalog-current version and protocol standing (R17)
+  volter-world audit <world> [--json]               — the catalog's upkeep verdicts for the mounted twins: matrix debt, census (R17)
+  volter-world down <name> [--grace-ms <ms>] [--purge] [--root <repo>]   # SIGTERM, then SIGKILL survivors after the grace (default 5000ms)
+                                                                          # --purge: after teardown, delete the instance dir (and per-service twin data) too — see docs/concepts/data-and-keys.md
+  volter-world status <name> [--json] [--root <repo>]
+  volter-world consumers retire <world> [--consumer <id>] [--root <repo>] [--json]  # resolve attachments whose runner, command and process group are gone
+  volter-world resources [--json] [--root <repo>]  # actual filesystem capacity and lifecycle inventory; no reservations
+                                                  # up/run/attach accept --owner <label> for task ownership
+  volter-world prune [name] [--apply] [--json] [--root <repo>]
+                                                  # preview by default; --apply deletes only successfully stopped
+                                                  # instance data/logs. Never stops live Worlds; sources survive
+  volter-world doctor <name> [--verify-public] [--json] [--root <repo>]
+  volter-world events <name> [--json] [--root <repo>]   every service start and end, and the World's own stops
+  volter-world doctor-prereqs --require local-execution [--json] [--quiet]
+  volter-world inspect-project [path] [--json]   # read-only adoption discovery
+  volter-world migrate-config <config> [--json] [--root <repo>]   # backed-up, atomic format-1 → format-2 migration
+  volter-world fake-env <NAME...> [--json]       # structurally valid fake env values for a world config
+                                                  # (Google service-account JSON gets a real throwaway RSA key;
+                                                  # opaque bearer keys get a twin-fake scalar)
+  volter-world covers <world> --repo <path> [--allow-unknown] [--acknowledge vendor=reason]... [--json] [--root <repo>]
+                                                  # room-setup PROOF: every external vendor the repo talks to has a twin
+                                                  # in the world. Exit 0 only when fully covered; missing twins and
+                                                  # unmapped external-service-shaped deps exit 1 (--allow-unknown
+                                                  # downgrades the latter to a warning)
+  volter-world clock <world> show | set <iso> | advance <N s|m|h|d>   # THE WORLD CLOCK: frozen instant every twin stamps from; physics door
+  volter-world urls <name> [--json] [--root <repo>]
+  volter-world url <name> [service] [--root <repo>]   # the clean base URL of one running service (no world.env parsing);
+                                                        # without a service: every service, one \`<id> <url>\` per line
+  volter-world app-url <world> [--set <url>|--detect <pid|port>] [--host <name>...] [--json] [--root <repo>]
+                                                  # the recorded APP endpoint of the instance — the attach pattern's
+                                                  # missing output. The BOOTER records it as the last boot step
+                                                  # (--set, or --detect an already-listening pid/port); consumers
+                                                  # read it back (bare URL, or --json). Reading an UNSET record
+                                                  # fails loudly with the registration recipe. A world that boots
+                                                  # the app itself declares an "app" service (type "process") —
+                                                  # its URL answers without any registration
+  volter-world log <name> [service...] [--no-follow] [--json] [--requests] [--root <repo>]   # the log of changes (alias: tail)
+                                                  # merged, occurredAt-ordered feed of the twins' action ledgers — one
+                                                  # \`HH:MM:SS.mmm <service> <operation> <subjectId>\` line per action;
+                                                  # follows until Ctrl-C (--no-follow: dump and exit; --json: raw JSONL;
+                                                  # --requests: also merge the opt-in request journals — reads/404s,
+                                                  # plus WHICH credential arrived in WHICH header/query param, named +
+                                                  # fingerprinted, never the value — written by twins under
+                                                  # VOLTER_TWIN_REQUEST_JOURNAL=1)
+  volter-world seed <world> [--entry <file>] [--cwd <dir>] [--json] [--root <repo>]
+                                                  # pull from the placeholder remote: the seed entry runs with every twin's
+                                                  # window open, so the defaults land as observed state (diff empty, nothing pending)
+  volter-world reset <world> [--entry <file>] [--cwd <dir>] [--json] [--root <repo>]
+                                                  # back to the defaults: down --purge, up, seed (refuses a referenced parent)
+  volter-world branch <world> <name> [--env-file=<path>] [--json] [--root <repo>]
+                                                  # a new world over the base's mirrors (its own log; the base's unpushed changes stay)
+  volter-world checkout <name> [--json] [--root <repo>]   # a stopped world back up, state intact
+  volter-world fetch <world> [--origin <twins url> --namespace <org>/<world>] --key <key> [--full] [--service <id>]... [--json] [--root <repo>]
+                                                  # the origin is a hosted twin's canonical history: --full clones its whole tree
+                                                  # (admin key), plain fetch appends what it observed since the last fetch (read key)
+  volter-world origin <world> [--json] [--root <repo>]   # the origin this world clones from
+  volter-world mark <world> [--id <marker>] [--json] [--root <repo>]
+                                                  # capture a cross-service BASE MARKER (each twin ledger's offset +
+                                                  # last action id) — the position \`diff\` measures from
+  volter-world diff <world> [--base <marker>] [--json] [--root <repo>]
+                                                  # the ledger DELTA since a marker (default: the last mark, else
+                                                  # world-boot), grouped by vendor, ordered by occurredAt
+  volter-world changeset create <world> <name> [--base <marker>] [--verifier "<service> <type>:<id> <field> <op> [value]"]... [--force] [--json] [--root <repo>]
+  volter-world changeset show <name> [--world <world>] [--json] [--root <repo>]
+  volter-world changeset list [--world <world>] [--json] [--root <repo>]
+  volter-world changeset replay <name> --into <world> [--world <world>] [--json] [--root <repo>]
+                                                  # freeze a delta into a named, content-addressed changeset and replay
+                                                  # it into another world's twins (the CI primitive; idempotent)
+  volter-world changeset verify <name> (--into <world> | --ephemeral) [--world <world>] [--json] [--root <repo>]
+                                                  # replay into a clean target, run the changeset's verifiers against
+                                                  # post-replay state, record the outcome ON the object (hash untouched)
+  volter-world changeset approve <name> --as <principal> [--note <text>] [--world <world>] [--json] [--root <repo>]
+                                                  # append an approval bound to the current body hash (drift refuses)
+  volter-world changeset status <name> [--world <world>] [--json] [--root <repo>]
+  volter-world changeset rebase <name> [--world <world>] [--json] [--root <repo>]
+                                                  # the merge onto a moved mirror (v3): re-stamp what still holds, name conflicts, drop approvals
+  volter-world changeset push <name> [--to <twins url> --namespace <org>/<world>] --key <namespace key> [--force] [--world <world>] [--json] [--root <repo>]
+                                                  # the governed push (alias: apply): to the REMOTE — the world's origin by default —
+                                                  # which refreshes, deploys to the vendor with its own keys, and answers with receipts
+                                                  # one honest line: hash, verified?, approvals, ready|not-ready + why
+                                                  # (exit 0 when ready; no pushing here — that is v2)
+  volter-world list [--json] [--root <repo>]
+  volter-world env <name> [--root <repo>] -- <command...>
+  volter-world attach [<world-ref>] [--via env|direct] [--root <repo>] [--verbose] [-- <command...>]
+                                                  # ref: explicit → $VOLTER_WORLD → nearest .volter-world file (docs/guides/route-a-cli-through-the-world.md)
+                                                  # --via env (default): run the command attached; --via direct: print the manifest JSON
+  volter-world manifest <name> [--root <repo>]    # the world manifest (vendors map, CA, traffic proxy, suggested env) as JSON
+  volter-world reflect <name> --target-ip <ip> [--resolver-ip <ip>] [--port <p>] [--resolver-port <p>] [--upstream <dns-ip>] [--root <repo>]
+                                                  # run the reflect front (SNI TLS door) + resolver in the foreground (docs/ATTACH.md);
+                                                  # --port 443 --resolver-port 53 is what containers can reach (attach --via reflect);
+                                                  # --resolver-ip when the Docker host's gateway address answers DNS itself (colima)
+  volter-world route <name> <add|rm|ls> [host]    # attachment-scoped reflect routes (which hosts the resolver intercepts)
+  volter-world serve <name> --advertise <https-origin> [--port <front>] [--manifest-port <p>] [--token <t>] [--root <repo>]
+                                                  # serve the world remotely: manifest endpoint + ONE advertised TLS door (docs/guides/route-a-cli-through-the-world.md)
+                                                  # attachers: volter-world attach <http://host:manifest-port> -- <command...>
+  volter-world activate <name> [--root <repo>]   # eval "$(volter-world activate <name>)" — a virtualenv for vendor APIs
+  volter-world shell <name> [--root <repo>]      # drop into a subshell with the world active (any CLI hits the twins)
+  volter-world run <config> --env-file=<path> [--name <name>] [--mode local|share|sealed] [--keep] [--verbose] -- <command...>
+  volter-world share <name> [--service app] [--verify /health|--no-verify] [--provider cloudflare-quick|command] [--command <cmd> [-- <args…>]]
+                                                  # {url} in command args = the service's local URL;
+                                                  # --provider cloudflare-quick selects raw cloudflared and clears a configured custom command
+  volter-world unshare <name> [--service app]
+
+Configs are stable JSON files, resolved from worlds/configs/<config>.json unless a path is passed.
+`);
+}
+
+function printReady(instance: Awaited<ReturnType<typeof upWorld>>): void {
+  process.stdout.write(`World ${instance.name} is ready (${instance.config})
+
+Services:
+${Object.values(instance.services).map((service) => `  ${service.id}: ${service.url ?? '(no listener — a World output)'}`).join('\n')}
+
+This instance started CLEAN (a world's state lives only while it runs; the world dir is the
+reproducible story) — set the clock and run your seed now, after every up.
+
+The two moves: if the twin stores it, create it through the vendor's own API (seed as the
+person, move the clock first for history). Everything else — judgment, lookups, faults — is
+a handler in the world dir's handlers/<vendor>.json. EVERY twin explains itself at
+GET <url>/twin; a scripted twin's GET <url>/twin/scenario lists handlers + misses.
+
+Env:
+  ${instance.envFile}
+
+Instance:
+  ${instance.dirs.instance}/instance.json
+
+Stop:
+  volter-world down ${instance.name}
+
+For a bounded job, use volter-world run ... -- <command> to tear down automatically on exit.
+Persistent up does not expire or infer that your sessions are idle.
+`);
+}
+
+async function main(): Promise<void> {
+  const [cmd, subject, ...rest] = process.argv.slice(2);
+  const root = optionValue(rest, '--root', process.cwd());
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    printHelp();
+    return;
+  }
+  if (subject === '--help' || subject === '-h') {
+    printHelp();
+    return;
+  }
+
+  if (cmd === 'consumers') {
+    // `volter-world consumers retire <world> [--consumer <id>] [--root <repo>] [--json]`: the owner's
+    // explicit resolution of attachments whose runner and command are provably gone.
+    const args = rest.filter((arg): arg is string => arg !== undefined);
+    if (subject !== 'retire') throw new Error('volter-world consumers: usage: volter-world consumers retire <world> [--consumer <id>] [--root <repo>] [--json]');
+    const world = positionalArgs(args)[0];
+    if (!world) throw new Error('volter-world consumers retire: missing world name');
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--root' || args[i] === '--consumer') {
+        if (!args[i + 1] || args[i + 1]!.startsWith('--')) throw new Error(`${args[i]} requires a value`);
+        i++;
+      } else if (args[i]!.startsWith('--') && args[i] !== '--json') throw new Error(`volter-world consumers retire: unknown option ${args[i]}`);
+    }
+    const consumer = args.includes('--consumer') ? optionValue(args, '--consumer', '') : undefined;
+    const results = retireWorldConsumers(world, optionValue(args, '--root', process.cwd()), consumer ? { consumer } : {});
+    if (args.includes('--json')) process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+    else if (!results.length) process.stdout.write(`World ${world}: no uncertain consumers.\n`);
+    else for (const r of results) process.stdout.write(`${r.retired ? 'RETIRED' : 'KEPT'} ${r.id}${r.owner ? ` (owner ${r.owner})` : ''}: ${r.reason}\n`);
+    return;
+  }
+
+  if (cmd === 'resources' || cmd === 'prune') {
+    const args = [subject, ...rest].filter((arg): arg is string => arg !== undefined);
+    const reportRoot = optionValue(args, '--root', process.cwd());
+    // Destructive commands must reject typos, not silently broaden a target to all Worlds.
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--root') {
+        if (!args[i + 1] || args[i + 1]!.startsWith('--')) throw new Error('--root requires a path');
+        i++;
+      } else if (args[i]!.startsWith('--') && args[i] !== '--json' && !(cmd === 'prune' && args[i] === '--apply')) {
+        throw new Error(`volter-world ${cmd}: unknown option ${args[i]}`);
+      }
+    }
+    const names = positionalArgs(args);
+    if (names.length > (cmd === 'prune' ? 1 : 0)) throw new Error(`volter-world ${cmd}: unexpected positional arguments`);
+    if (cmd === 'prune') {
+      const report = pruneWorlds({ root: reportRoot, name: names[0], apply: args.includes('--apply') });
+      if (args.includes('--json')) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      else {
+        process.stdout.write(`${report.apply ? 'Prune result' : 'Preview only (use --apply to delete eligible instance data/logs)'}; never stops Worlds.\n`);
+        for (const entry of report.entries) {
+          process.stdout.write(`${entry.removed ? 'REMOVED' : entry.eligible ? 'ELIGIBLE' : 'KEEP'} ${entry.name}: ${entry.reason}\n  ${entry.path}${entry.logicalBytes !== undefined ? ` (${entry.logicalBytes} logical bytes; actual disk reclaim may differ)` : ''}\n`);
+        }
+      }
+      if (report.apply && names.length && !report.entries[0]?.removed) process.exitCode = 1;
+    } else {
+      const report = worldResourceReport(reportRoot);
+      const consumers = report.worlds.map((claim) => {
+        let foreground;
+        try {
+          const record = claim.root ? statusWorld(claim.world, claim.root, { readOnly: true }).lastRun : undefined;
+          if (record) foreground = { state: record.state, runnerPid: record.runnerPid, ...('consumerPid' in record ? { consumerPid: record.consumerPid } : {}), startedAt: record.startedAt };
+        } catch { /* unknown */ }
+        const attached = claim.root ? worldConsumers(claim.root, claim.world) : { consumers: [], warnings: ['World root is unknown'] };
+        const usage = claim.root ? worldUsage(claim.root, claim.world, attached)
+          : { createdAt: null, lastUsedAt: null, lastUseSource: null, coverage: 'partial', warnings: attached.warnings };
+        return { identity: claim.identity, owner: claim.owner ?? null, attachments: attached.consumers, usage, warnings: attached.warnings, coverage: 'partial', foreground, otherConsumers: 'unknown (untracked synchronous SDK commands, shell/activate, reflect, remote clients and descendants are not enumerated)' };
+      });
+      if (args.includes('--json')) process.stdout.write(`${JSON.stringify({ ...report, consumers }, null, 2)}\n`);
+      else {
+        const free = report.filesystem.availableBytes;
+        process.stdout.write(`Observed capacity at ${report.measuredAt}; no capacity reservations.\nFilesystem ${report.filesystem.path}: ${free === null ? 'unknown' : `${Math.floor(free / 1048576)} MiB available`}; pool=${report.filesystem.pool ?? 'unknown'}. Physical memory=${Math.floor(report.host.physicalMemoryBytes / 1048576)} MiB (not measured usage).\n`);
+        for (const claim of report.worlds) {
+          process.stdout.write(`${claim.phase} ${claim.world}: root=${claim.root}; owner=${claim.owner ?? 'unrecorded'}; instance=${claim.instanceCreatedAt}\n  tracked service pids=${claim.pids.join(',') || 'none'}; log=${claim.log}\n`);
+          const attached = consumers.find((row) => row.identity === claim.identity);
+          process.stdout.write(`  instance created: ${attached?.usage.createdAt ?? 'unknown'}; last observed command use: ${attached?.usage.lastUsedAt ?? 'unknown'} (${attached?.usage.lastUseSource ?? 'unrecorded'}; partial coverage)\n`);
+          for (const consumer of attached?.attachments ?? []) process.stdout.write(`  ${consumer.state} attachment ${consumer.id}: owner=${consumer.owner ?? 'unrecorded'} runner=${consumer.runnerPid} command-pid=${consumer.consumerPid ?? 'starting'} heartbeat=${consumer.heartbeatAt}\n`);
+          for (const warning of attached?.warnings ?? []) process.stdout.write(`  WARNING: ${warning}\n`);
+          for (const warning of attached?.usage.warnings ?? []) if (!attached?.warnings.includes(warning)) process.stdout.write(`  WARNING: ${warning}\n`);
+        }
+        for (const legacy of report.legacyRecords) process.stdout.write(`LEGACY ${legacy.world ?? 'unknown'}: ${legacy.path}; use its pinned runtime for teardown; no capacity charged here\n`);
+        for (const warning of report.warnings) process.stdout.write(`WARNING: ${warning}\n`);
+        process.stdout.write('Lifecycle records identify ownership, not measured usage. Consumer coverage is partial: local env attachments are registered; run records are available with --json. Untracked synchronous SDK commands, shell/activate, reflect, remote clients and descendants are unknown, not zero.\nReview ownership before explicit down <name>. prune previews stopped disk leftovers only. For bounded jobs, run cleans up on exit unless --keep.\n');
+      }
+    }
+    return;
+  }
+
+  if (cmd === 'up') {
+    if (!subject) throw new Error('volter-world up: missing config');
+    const envFile = optionValue(rest, '--env-file');
+    if (!envFile) throw new Error('volter-world up: missing required --env-file=<path>');
+    const name = optionValue(rest, '--name') || undefined;
+    const mode = optionValue(rest, '--mode', 'local') as 'local' | 'share' | 'sealed';
+    const isolationArg = optionValue(rest, '--isolation');
+    if (isolationArg && isolationArg !== 'process' && isolationArg !== 'colocated' && isolationArg !== 'worker') {
+      throw new Error(`volter-world up: invalid --isolation "${isolationArg}" (want process|colocated|worker)`);
+    }
+    const isolation = (isolationArg || undefined) as 'process' | 'colocated' | 'worker' | undefined;
+    // The boot runs in its own owner process (./up-task.ts): a closed terminal does not leave it half-done.
+    const instance = await superviseWorldUp(subject, { name, root, mode, envFile, owner: ownerOption(rest), ...(isolation ? { isolation } : {}) });
+    printReady(instance);
+    return;
+  }
+
+  if (cmd === 'down') {
+    if (!subject) throw new Error('volter-world down: missing world name');
+    const graceArg = optionValue(rest, '--grace-ms');
+    if (graceArg && !(Number(graceArg) >= 0)) throw new Error(`volter-world down: invalid --grace-ms "${graceArg}" (want a non-negative number)`);
+    const purge = rest.includes('--purge');
+    const result = await downWorld(subject, root, {
+      ...(graceArg ? { graceMs: Number(graceArg) } : {}),
+      ...(purge ? { purge: true } : {}),
+    });
+    process.stdout.write(result.externalErrors.length ? `World ${result.name}: teardown incomplete; lifecycle evidence retained\n`
+      : `Stopped world ${result.name}${result.stopped.length ? `: ${result.stopped.join(', ')}` : ''}\n`);
+    if (result.escalated.length) process.stdout.write(`Escalated to SIGKILL (ignored SIGTERM past the grace): ${result.escalated.join(', ')}\n`);
+    for (const line of result.notSignalled ?? []) process.stdout.write(`Not signalled: ${line}\n`);
+    if (result.externalErrors.length) {
+      for (const message of result.externalErrors) process.stderr.write(`External teardown failed: ${message}\n`);
+    }
+    if (result.purged) {
+      process.stdout.write(`Purged instance data: ${result.purged}\n`);
+    } else if (purge && result.externalErrors.length) {
+      process.stdout.write(`Refused to purge instance data: an external service's teardown failed (see above) — its down command/discovered env must survive.\n`);
+    }
+    // Honest exit code (TWIN-61): a silent 0 here is exactly the gap a failed `supabase stop` +
+    // `--purge` exploited — a still-running external, a deleted stop recipe, and a green exit.
+    if (result.externalErrors.length) process.exitCode = 1;
+    return;
+  }
+
+  if (cmd === 'events') {
+    if (!subject) throw new Error('volter-world events: missing world name');
+    const status = statusWorld(subject, root, { readOnly: true, light: true });
+    const events = readWorldEvents(worldEventsPath(status.dirs.logs));
+    if (rest.includes('--json')) process.stdout.write(`${JSON.stringify(events, null, 2)}\n`);
+    else if (!events.length) process.stdout.write(`World ${subject}: no events recorded (${worldEventsPath(status.dirs.logs)})\n`);
+    else for (const event of events) process.stdout.write(`${describeWorldEvent(event)}\n`);
+    return;
+  }
+
+  if (cmd === 'status') {
+    if (!subject) throw new Error('volter-world status: missing world name');
+    const status = statusWorld(subject, root);
+    const usage = worldUsage(root, subject);
+    // A stopped process service carries its own account of how it ended (./service-exit.ts).
+    const ends = Object.fromEntries(Object.values(status.services)
+      .filter((service) => status.serviceStates[service.id] !== 'running' && status.serviceStates[service.id] !== 'external')
+      .flatMap((service) => { const end = readServiceEnd(service.log); return end ? [[service.id, end] as const] : []; }));
+    if (rest.includes('--json')) {
+      const services = Object.fromEntries(Object.entries(status.services).map(([id, service]) => [id, ends[id] ? { ...service, end: ends[id] } : service]));
+      process.stdout.write(`${JSON.stringify({ ...status, services, usage }, null, 2)}\n`);
+    }
+    else {
+      const down = Object.entries(status.serviceStates).filter(([, state]) => state !== 'running' && state !== 'external').map(([id]) => id);
+      const headline = !status.running ? 'stopped' : status.degraded ? `degraded: ${down.join(', ')} not running` : 'running';
+      process.stdout.write(`World ${status.name}: ${headline} (${status.config})\n`);
+      process.stdout.write(`  instance created: ${usage.createdAt ?? 'unknown'}\n  last observed command use: ${usage.lastUsedAt ?? 'unknown'} (${usage.lastUseSource ?? 'unrecorded'}; partial coverage)\n`);
+      for (const warning of usage.warnings) process.stdout.write(`  WARNING: ${warning}\n`);
+      if (status.lastRun) {
+        if (status.lastRun.state === 'running') {
+          process.stdout.write(`  foreground consumer: running (runner pid ${status.lastRun.runnerPid})\n    log: ${status.lastRun.log}\n`);
+        } else if (status.lastRun.state === 'abrupt') {
+          process.stdout.write(`  foreground consumer: failed abruptly (${status.lastRun.error}; observed ${status.lastRun.observedAt})\n    log: ${status.lastRun.log}\n`);
+        } else {
+          const detail = status.lastRun.error ? `spawn error: ${status.lastRun.error}`
+            : status.lastRun.signal ? `terminated by ${status.lastRun.signal}`
+              : `exited ${status.lastRun.exitCode}`;
+          process.stdout.write(`  foreground consumer: ${status.lastRun.exitCode === 0 ? 'succeeded' : 'failed'} (${detail})\n    log: ${status.lastRun.log}\n`);
+        }
+      }
+      if (status.lifecycle) process.stdout.write(`  lifecycle: ownership recorded, no capacity reserved\n    log: ${status.lifecycle.log}\n`);
+      else if (status.resources) process.stdout.write(`  legacy runtime ownership; use its pinned runtime for teardown\n    log: ${status.resources.log}\n`);
+      for (const service of Object.values(status.services)) {
+        const state = status.serviceStates[service.id];
+        const lifecycle = state === 'external' ? 'externally managed'
+          : state === 'lingering' ? 'stopped; processes of its group are still alive, which `down` stops'
+            : state === 'gave-up' ? `worker gave up: ${service.workerGaveUp?.detail ?? 'exited'}, at ${service.workerGaveUp?.at ?? 'unknown'}`
+              : state;
+        const end = ends[service.id];
+        const how = end ? `\n    it ${describeServiceEnd(end)}${end.lastOutput.length ? `; last output: ${end.lastOutput[end.lastOutput.length - 1]}` : ''}` : '';
+        process.stdout.write(`  ${service.id}: ${service.url ?? '(no World URL)'} (${lifecycle})${how}\n    log: ${service.log}\n`);
+        const own = service.log ? ownLogs(service.log) : [];
+        if (own.length) process.stdout.write(`    its own logs: ${own.join(', ')}\n`);
+      }
+      // The World's events: every service start and end, and the World's own stops.
+      const events = readWorldEvents(worldEventsPath(status.dirs.logs));
+      if (events.length) {
+        process.stdout.write(`  recent events (${worldEventsPath(status.dirs.logs)}):\n`);
+        for (const event of events.slice(-8)) process.stdout.write(`    ${describeWorldEvent(event)}\n`);
+      }
+    }
+    return;
+  }
+
+  // `plan` and `review` retired 2026-09-05: the changeset verbs are the one review path (verify, approve, status, push).
+
+  if (cmd === 'doctor') {
+    if (!subject) throw new Error('volter-world doctor: missing world name');
+    const report = await doctorWorld(subject, { root, verifyPublic: rest.includes('--verify-public') });
+    if (rest.includes('--json')) {
+      process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    } else {
+      process.stdout.write(`World ${report.name}: ${report.ok ? 'ok' : 'failed'}\n`);
+      for (const check of report.checks) process.stdout.write(`  ${check.ok ? 'ok' : 'fail'} ${check.id}: ${check.message}\n`);
+    }
+    if (!report.ok) process.exit(1);
+    return;
+  }
+
+  if (cmd === 'doctor-prereqs') {
+    const required = rest.flatMap((arg, index) => arg === '--require' ? [rest[index + 1]] : [])
+      .filter(Boolean) as PrerequisiteId[];
+    const checks = checkPrerequisites(required.length ? required : ['local-execution']);
+    const ok = checks.every((check) => check.ok);
+    if (rest.includes('--json')) {
+      process.stdout.write(`${JSON.stringify({ ok, checks }, null, 2)}\n`);
+    } else if (!rest.includes('--quiet')) {
+      const output = formatPrerequisiteChecks(checks);
+      process[ok ? 'stdout' : 'stderr'].write(`${output}\n`);
+    }
+    if (!ok) process.exit(1);
+    return;
+  }
+
+  if (cmd === 'inspect-project') {
+    const args = [...(subject ? [subject] : []), ...rest];
+    const path = args.find((arg) => !arg.startsWith('--')) || process.cwd();
+    const report = inspectProject(path);
+    process.stdout.write(args.includes('--json') ? `${JSON.stringify(report, null, 2)}\n` : formatProjectInspection(report));
+    return;
+  }
+
+  if (cmd === 'migrate-config') {
+    if (!subject) throw new Error('volter-world migrate-config: missing config path or name');
+    const migration = migrateWorldConfig(subject, root);
+    if (rest.includes('--json')) process.stdout.write(`${JSON.stringify(migration, null, 2)}\n`);
+    else process.stdout.write(`Migrated ${migration.path}: format ${migration.from} → ${migration.to}\nBackup   ${migration.backup}\n${migration.dropped.length ? `Dropped  ${migration.dropped.join(', ')}\n` : ''}`);
+    return;
+  }
+
+  if (cmd === 'fake-env') {
+    // Structurally valid fake credentials for a world config's env block. Most vendor keys
+    // are opaque bearer tokens (any `twin-fake-…` scalar works against a twin), but a value
+    // the CLIENT SDK parses/signs with (a Google service-account JSON) must be structurally
+    // real — full field set + a genuine throwaway RSA key — or the app throws before its
+    // first request. See fixture-env.ts for the pattern. Pure generator, no lifecycle.
+    const { fakeEnvValue } = await import('./fixture-env.ts');
+    const names = [subject, ...rest].filter((a): a is string => typeof a === 'string' && !a.startsWith('--'));
+    if (names.length === 0) throw new Error('volter-world fake-env: pass one or more env var NAMES (e.g. `volter-world fake-env GOOGLE_VERTEX_JSON STRIPE_SECRET_KEY`)');
+    if (rest.includes('--json') || subject === '--json') {
+      process.stdout.write(`${JSON.stringify(Object.fromEntries(names.map((n) => [n, fakeEnvValue(n)])), null, 2)}\n`);
+    } else {
+      for (const n of names) {
+        const v = fakeEnvValue(n);
+        // multiline values (SA JSON) print as NAME=<value> with the value JSON-escaped so the
+        // output stays one line per name and pastes into a world config env block directly.
+        process.stdout.write(`${n}=${v.includes('\n') ? JSON.stringify(v) : v}\n`);
+      }
+    }
+    return;
+  }
+
+  if (cmd === 'init') {
+    if (!subject) throw new Error('volter-world init: missing world name (usage: volter-world init <name> --repo <path>)');
+    const repo = optionValue(rest, '--repo');
+    if (!repo) throw new Error('volter-world init: --repo <path> is required (the application repo to build the world for)');
+    const out = optionValue(rest, '--out');
+    const result = initWorld(subject, repo, {
+      root,
+      ...(out ? { out } : {}),
+      force: rest.includes('--force'),
+      allowUnknown: rest.includes('--allow-unknown'),
+      acknowledge: acknowledgeOptions(rest, 'init'),
+    });
+    process.stdout.write(rest.includes('--json') ? `${JSON.stringify(result, null, 2)}\n` : formatInitReport(result));
+    // Vendor coverage IS the exit code. App boot risks remain a separate, prominent report field.
+    if (!result.ok) process.exit(1);
+    return;
+  }
+
+  // R17 — the upkeep sweeps, surfaced per world the way npm does: `outdated` is the version
+  // and protocol drift of the twins this world mounted; `audit` is what the catalog knows about
+  // them (matrix debt, census baseline). Both read instance.json and the committed artifacts —
+  // nothing is fetched.
+  if (cmd === 'outdated' || cmd === 'audit') {
+    if (!subject) throw new Error(`volter-world ${cmd}: missing world name (usage: volter-world ${cmd} <world> [--json])`);
+    const status = statusWorld(subject, root);
+    const rows = worldUpkeep(status, cmd);
+    if (rest.includes('--json')) process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
+    else {
+      if (rows.length === 0) process.stdout.write(`World ${status.name}: no twin mounted with a resolved version — boot it once (up) so instance.json records what was mounted\n`);
+      for (const r of rows) process.stdout.write(`${r.line}\n`);
+    }
+    if (rows.some((r) => r.attention)) process.exit(1);
+    return;
+  }
+  if (cmd === 'covers') {
+    if (!subject) throw new Error('volter-world covers: missing world name (usage: volter-world covers <world> --repo <path>)');
+    const repo = optionValue(rest, '--repo');
+    if (!repo) throw new Error('volter-world covers: --repo <path> is required (the application repo to prove coverage for)');
+    const report = coverWorld(subject, repo, { root, allowUnknown: rest.includes('--allow-unknown'), acknowledge: acknowledgeOptions(rest, 'covers') });
+    process.stdout.write(rest.includes('--json') ? `${JSON.stringify(report, null, 2)}\n` : formatCoverageReport(report));
+    if (!report.ok) process.exit(1);
+    return;
+  }
+
+  if (cmd === 'clock') {
+    // THE operator door for world time (physics): show / set <iso> / advance <duration>.
+    // The clock is a frozen instant every twin reads per request (kernel worldNow()); setting
+    // or advancing takes effect live, no restarts. `advance` requires a set clock (advancing
+    // wall-clock would silently freeze time as a side effect).
+    // argv shape here: cmd='clock', subject=<world>, rest=[action, value?, flags...]
+    const name = subject;
+    const [action, value] = rest;
+    if (!name || !action || (action !== 'show' && action !== 'set' && action !== 'advance')) {
+      console.error('usage: volter-world clock <world> show | set <iso-8601> | advance <N s|m|h|d> [--root <repo>]');
+      process.exit(2);
+    }
+    const rootDir = resolve(optionValue(rest, '--root') ?? process.cwd());
+    const file = clockFile(rootDir, name);
+    if (action === 'show') {
+      console.log(existsSync(file) ? `${readFileSync(file, 'utf8').trim()} (frozen)` : `${new Date().toISOString()} (wall clock — no world clock set)`);
+      return;
+    }
+    if (action === 'set') {
+      const parsed = Date.parse(value ?? '');
+      if (Number.isNaN(parsed)) { console.error(`clock set: ${JSON.stringify(value)} is not an ISO-8601 instant`); process.exit(2); }
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(file, `${new Date(parsed).toISOString()}\n`);
+      console.log(new Date(parsed).toISOString());
+      return;
+    }
+    const m = /^(\d+(?:\.\d+)?)(s|m|h|d)$/.exec((value ?? '').trim());
+    if (!m) { console.error(`clock advance: ${JSON.stringify(value)} is not <N>(s|m|h|d)`); process.exit(2); }
+    if (!existsSync(file)) { console.error('clock advance: no world clock is set (advance from wall-clock would freeze time as a side effect) — `clock set <iso>` first'); process.exit(2); }
+    const base = Date.parse(readFileSync(file, 'utf8').trim());
+    const unit = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2] as 's' | 'm' | 'h' | 'd'];
+    const next = new Date(base + Number(m[1]) * unit).toISOString();
+    writeFileSync(file, `${next}\n`);
+    console.log(next);
+    return;
+  }
+
+  if (cmd === 'urls') {
+    if (!subject) throw new Error('volter-world urls: missing world name');
+    const urls = urlsWorld(subject, root);
+    if (rest.includes('--json')) {
+      process.stdout.write(`${JSON.stringify(urls, null, 2)}\n`);
+    } else {
+      process.stdout.write(`World ${urls.name} (${urls.mode})\n`);
+      for (const [serviceId, service] of Object.entries(urls.services)) {
+        process.stdout.write(`  ${serviceId}: ${service.localUrl}${service.publicUrl ? ` public=${service.publicUrl}` : ''}\n`);
+      }
+    }
+    return;
+  }
+
+  if (cmd === 'url') {
+    if (!subject) throw new Error('volter-world url: missing world name (usage: volter-world url <world> [service])');
+    const [service] = positionalArgs(rest);
+    const urls = urlWorld(subject, { root, ...(service === undefined ? {} : { service }) });
+    if (service !== undefined) process.stdout.write(`${urls[0]!.url}\n`);
+    else for (const entry of urls) process.stdout.write(`${entry.id} ${entry.url}\n`);
+    return;
+  }
+
+  if (cmd === 'app-url') {
+    if (!subject) throw new Error('volter-world app-url: missing world name (usage: volter-world app-url <world> [--set <url>|--detect <pid|port>])');
+    const set = optionValue(rest, '--set');
+    const detect = optionValue(rest, '--detect');
+    if (set && detect) throw new Error('volter-world app-url: pass --set OR --detect, not both');
+    const json = rest.includes('--json');
+    // --host (repeatable): a hostname the app answers as in production, routed to it inside the World
+    const hosts = rest.flatMap((arg, index) => (arg === '--host' ? [rest[index + 1] ?? ''] : []));
+    if (set || detect || hosts.length) {
+      let record = set ? setAppUrl(subject, set, { root }) : detect ? await detectAppUrl(subject, detect, { root }) : undefined;
+      if (hosts.length) record = addAppHosts(subject, hosts, { root });
+      if (json) process.stdout.write(`${JSON.stringify(record, null, 2)}\n`);
+      else process.stdout.write(`Recorded app URL for world ${subject}: ${record!.url}${record!.detail ? ` (${record!.detail})` : ''}${record!.hosts?.length ? `; answering as ${record!.hosts.join(', ')}` : ''}\n`);
+      return;
+    }
+    const record = readAppUrl(subject, { root });
+    if (record === null) {
+      // LOUD when unset — a consumer must never mistake "nobody registered it" for an endpoint.
+      process.stderr.write(`${appUrlUnsetMessage(subject)}\n`);
+      if (json) process.stdout.write(`${JSON.stringify({ world: subject, url: null }, null, 2)}\n`);
+      process.exit(1);
+    }
+    // bare URL on stdout: ready for `curl "$(volter-world app-url <world>)/health"` interpolation
+    process.stdout.write(json ? `${JSON.stringify(record, null, 2)}\n` : `${record.url}\n`);
+    return;
+  }
+
+  if (cmd === 'tail' || cmd === 'log') {
+    if (!subject) throw new Error(`volter-world ${cmd}: missing world name (usage: volter-world log <world> [service...])`);
+    const services = positionalArgs(rest);
+    const controller = new AbortController();
+    process.once('SIGINT', () => controller.abort());
+    process.once('SIGTERM', () => controller.abort());
+    await tailWorldActions(subject, {
+      root,
+      ...(services.length ? { services } : {}),
+      follow: !rest.includes('--no-follow'),
+      json: rest.includes('--json'),
+      requests: rest.includes('--requests'),
+      signal: controller.signal,
+    });
+    return;
+  }
+
+  if (cmd === 'seed' || cmd === 'reset') {
+    if (!subject) throw new Error(`volter-world ${cmd}: missing world name (usage: volter-world ${cmd} <world> [--entry <file>] [--cwd <dir>])`);
+    const entry = optionValue(rest, '--entry') || undefined;
+    const cwd = optionValue(rest, '--cwd') || undefined;
+    const json = rest.includes('--json');
+    const outcome = cmd === 'seed' ? await seedWorld(subject, { root, ...(entry ? { entry } : {}), ...(cwd ? { cwd } : {}) }) : await resetWorld(subject, { root, ...(entry ? { entry } : {}), ...(cwd ? { cwd } : {}) });
+    if (json) process.stdout.write(`${JSON.stringify({ world: outcome.world, entry: outcome.entry, exitCode: outcome.exitCode, observed: outcome.observed }, null, 2)}\n`);
+    else process.stdout.write(`${cmd === 'reset' ? 'Reset' : 'Seeded'} world ${subject} from the placeholder remote (${outcome.entry})\n${Object.entries(outcome.observed).map(([s, n]) => `  ${s}: ${n} observed`).join('\n')}\n${outcome.exitCode === 0 ? '' : `  seed entry exited ${outcome.exitCode}\n`}`);
+    process.exitCode = outcome.exitCode === 0 ? 0 : 1;
+    return;
+  }
+
+  if (cmd === 'branch') {
+    const [name] = positionalArgs(rest);
+    if (!subject || !name) throw new Error('volter-world branch: usage: volter-world branch <world> <name> [--env-file=<path>]');
+    const envFile = optionValue(rest, '--env-file') || undefined;
+    const { instance, forked } = await branchWorld(subject, name, { root, ...(envFile ? { envFile } : {}) });
+    if (rest.includes('--json')) process.stdout.write(`${JSON.stringify({ name: instance.name, base: subject, forked }, null, 2)}\n`);
+    else { process.stdout.write(`Branched world ${name} from ${subject}\n${Object.entries(forked).map(([s, states]) => `  ${s}: mirror forked (${states.join(', ')})`).join('\n')}\n`); printReady(instance); }
+    return;
+  }
+  if (cmd === 'checkout') {
+    if (!subject) throw new Error('volter-world checkout: missing world name');
+    const instance = await checkoutWorld(subject, { root });
+    if (rest.includes('--json')) process.stdout.write(`${JSON.stringify({ name: instance.name }, null, 2)}\n`); else printReady(instance);
+    return;
+  }
+  if (cmd === 'fetch') {
+    if (!subject) throw new Error('volter-world fetch: missing world name (usage: volter-world fetch <world> --key <key> [--origin <url> --namespace <org>/<world>] [--full])');
+    const key = optionValue(rest, '--key') || process.env.VOLTER_TWINS_READ_KEY || process.env.VOLTER_TWINS_KEY || '';
+    if (!key) throw new Error('volter-world fetch: --key <twins key> is required (the read key for a fetch, the admin key for --full)');
+    const services: string[] = []; for (let i = 0; i < rest.length; i++) if (rest[i] === '--service' && rest[i + 1]) services.push(rest[i + 1]!);
+    const url = optionValue(rest, '--origin') || undefined; const namespace = optionValue(rest, '--namespace') || undefined;
+    const outcome = await fetchFromOrigin(subject, { root, key, ...(url ? { url } : {}), ...(namespace ? { namespace } : {}), ...(rest.includes('--full') ? { full: true } : {}), ...(services.length ? { services } : {}) });
+    if (rest.includes('--json')) process.stdout.write(`${JSON.stringify(outcome, null, 2)}\n`);
+    else if (outcome.full) process.stdout.write(`Cloned ${outcome.origin.namespace} from ${outcome.origin.url} into world ${subject} (${outcome.files} files)\n`);
+    else process.stdout.write(`Fetched from ${outcome.origin.namespace} at ${outcome.origin.url} into world ${subject}\n${Object.entries(outcome.appended).map(([k, n]) => `  ${k}: ${n} observed`).join('\n')}\n`);
+    return;
+  }
+  if (cmd === 'origin') {
+    if (!subject) throw new Error('volter-world origin: missing world name');
+    const origin = worldOrigin(subject, root);
+    if (rest.includes('--json')) process.stdout.write(`${JSON.stringify(origin, null, 2)}\n`);
+    else process.stdout.write(origin ? `${origin.namespace} at ${origin.url}${origin.fetchedAt ? ` (fetched ${origin.fetchedAt})` : ''}\n` : 'placeholder (no hosted origin recorded — `volter-world fetch <world> --full --origin <url> --namespace <org>/<world> --key <admin key>` clones one)\n');
+    return;
+  }
+
+  if (cmd === 'mark') {
+    if (!subject) throw new Error('volter-world mark: missing world name (usage: volter-world mark <world> [--id <marker>] [--note <text>])');
+    const id = optionValue(rest, '--id');
+    const note = optionValue(rest, '--note');
+    const marker = markWorld(subject, { root, ...(id ? { id } : {}), ...(note ? { note } : {}) });
+    if (rest.includes('--json')) process.stdout.write(`${JSON.stringify(marker, null, 2)}\n`);
+    else process.stdout.write(`Marked world ${marker.world} at ${marker.id} (${marker.createdAt})\n  ${marker.ledgers.length} ledger(s): ${marker.ledgers.map((ledger) => `${ledger.service}=${ledger.count}`).join(', ') || 'none yet'}\n`);
+    return;
+  }
+
+  if (cmd === 'diff') {
+    if (!subject) throw new Error('volter-world diff: missing world name (usage: volter-world diff <world> [--base <marker>])');
+    const base = optionValue(rest, '--base');
+    const delta = diffWorld(subject, { root, ...(base ? { base } : {}) });
+    process.stdout.write(rest.includes('--json') ? `${JSON.stringify(delta, null, 2)}\n` : formatLedgerDelta(delta));
+    return;
+  }
+
+  if (cmd === 'changeset') {
+    const CHANGESET_VALUE_FLAGS = ['--root', '--base', '--into', '--world', '--verifier', '--as', '--note'];
+    const args = positionalArgs(rest, CHANGESET_VALUE_FLAGS);
+    const world = optionValue(rest, '--world');
+    const json = rest.includes('--json');
+    if (subject === 'create') {
+      const [worldName, name] = args;
+      if (!worldName || !name) throw new Error('volter-world changeset create: usage: volter-world changeset create <world> <name> [--base <marker>] [--verifier "<service> <type>:<id> <field> <op> [value]"]...');
+      const base = optionValue(rest, '--base');
+      const verifiers = rest
+        .flatMap((flag, index) => (flag === '--verifier' && rest[index + 1] ? [rest[index + 1]!] : []))
+        .map((expression, index) => parseVerifierExpression(expression, `v${index + 1}`));
+      const changeset = createWorldChangeset(worldName, name, { root, overwrite: rest.includes('--force'), ...(base ? { base } : {}), ...(verifiers.length ? { verifiers } : {}) });
+      process.stdout.write(json ? `${JSON.stringify(changeset, null, 2)}\n` : formatChangeset(changeset));
+      return;
+    }
+    if (subject === 'show') {
+      const [name] = args;
+      if (!name) throw new Error('volter-world changeset show: usage: volter-world changeset show <name> [--world <world>]');
+      const located = findWorldChangeset(name, { root, ...(world ? { world } : {}) });
+      process.stdout.write(json ? `${JSON.stringify(located.changeset, null, 2)}\n` : formatChangeset(located.changeset));
+      return;
+    }
+    if (subject === 'list') {
+      const found = listWorldChangesets({ root, ...(world ? { world } : {}) });
+      if (json) {
+        process.stdout.write(`${JSON.stringify(found.map((entry) => ({ ...entry.changeset, path: entry.path })), null, 2)}\n`);
+        return;
+      }
+      if (!found.length) process.stdout.write('No changesets yet — create one with `volter-world changeset create <world> <name>`\n');
+      for (const entry of found) {
+        process.stdout.write(`${entry.changeset.name}\t${entry.world}\t${entry.changeset.actions.length} action(s)\tbase=${entry.changeset.base}\t${entry.changeset.contentHash}\n`);
+      }
+      return;
+    }
+    if (subject === 'replay') {
+      const [name] = args;
+      if (!name) throw new Error('volter-world changeset replay: usage: volter-world changeset replay <name> --into <world>');
+      const into = optionValue(rest, '--into');
+      if (!into) throw new Error('volter-world changeset replay: --into <world> is required (the world to replay the changeset into)');
+      const report = await replayWorldChangeset(name, { root, into, ...(world ? { world } : {}) });
+      process.stdout.write(json ? `${JSON.stringify(report, null, 2)}\n` : formatReplayReport(report));
+      return;
+    }
+    if (subject === 'verify') {
+      const [name] = args;
+      if (!name) throw new Error('volter-world changeset verify: usage: volter-world changeset verify <name> (--into <world> | --ephemeral)');
+      const into = optionValue(rest, '--into');
+      const outcome = await verifyWorldChangeset(name, { root, ...(into ? { into } : {}), ephemeral: rest.includes('--ephemeral'), ...(world ? { world } : {}) });
+      process.stdout.write(json ? `${JSON.stringify(outcome.verification, null, 2)}\n` : formatVerification(name, outcome.verification, outcome.report));
+      if (!outcome.verification.passed) process.exitCode = 1;
+      return;
+    }
+    if (subject === 'approve') {
+      const [name] = args;
+      if (!name) throw new Error('volter-world changeset approve: usage: volter-world changeset approve <name> --as <principal> [--note <text>]');
+      const principal = optionValue(rest, '--as');
+      if (!principal) throw new Error('volter-world changeset approve: --as <principal> is required (who is signing)');
+      const note = optionValue(rest, '--note');
+      const outcome = approveWorldChangeset(name, { root, principal, ...(note ? { note } : {}), ...(world ? { world } : {}) });
+      if (json) process.stdout.write(`${JSON.stringify(outcome.approval, null, 2)}\n`);
+      else process.stdout.write(`Approved changeset ${name} as ${outcome.approval.principal} at ${outcome.approval.at}\n  bound to ${outcome.approval.contentHash}\n`);
+      return;
+    }
+    if (subject === 'status') {
+      const [name] = args;
+      if (!name) throw new Error('volter-world changeset status: usage: volter-world changeset status <name> [--world <world>]');
+      const readiness = statusWorldChangeset(name, { root, ...(world ? { world } : {}) });
+      process.stdout.write(json ? `${JSON.stringify(readiness, null, 2)}\n` : formatChangesetStatus(readiness));
+      if (!readiness.ready) process.exitCode = 1;
+      return;
+    }
+    if (subject === 'rebase') {
+      const [name] = args;
+      if (!name) throw new Error('volter-world changeset rebase: usage: volter-world changeset rebase <name> [--world <world>]');
+      const outcome = rebaseWorldChangeset(name, { root, ...(world ? { world } : {}) });
+      process.stdout.write(json ? `${JSON.stringify(outcome.report, null, 2)}\n` : formatRebaseReport(outcome.report));
+      if (outcome.report.outcome === 'conflict') process.exitCode = 1;
+      return;
+    }
+    if (subject === 'apply' || subject === 'push') {
+      const [name] = args;
+      if (!name) throw new Error('volter-world changeset push: usage: volter-world changeset push <name> --key <namespace key> [--to <twins url> --namespace <org>/<world>] [--force]');
+      const key = optionValue(rest, '--key') || process.env.VOLTER_TWINS_KEY || '';
+      if (!key) throw new Error('volter-world changeset push: --key <namespace key> is required (a push is a write: the read key is refused; a vendor credential never leaves the remote)');
+      const to = optionValue(rest, '--to') || undefined; const namespace = optionValue(rest, '--namespace') || undefined;
+      const outcome = await pushWorldChangeset(name, { root, key, ...(to ? { to } : {}), ...(namespace ? { namespace } : {}), ...(rest.includes('--force') ? { force: true } : {}), ...(world ? { world } : {}) });
+      process.stdout.write(json ? `${JSON.stringify(outcome.application, null, 2)}\n` : `${formatApplication(name, outcome.application)}  remote: ${outcome.remote.namespace} at ${outcome.remote.url}\n`);
+      if (outcome.unsent) process.stderr.write(`warning: ${outcome.unsent}\n`);
+      if (outcome.application.outcome !== 'applied') process.exitCode = 1;
+      return;
+    }
+    throw new Error(`volter-world changeset: unknown subcommand ${JSON.stringify(subject ?? '')} (want create|show|list|replay|verify|approve|status|rebase|push)`);
+  }
+
+  if (cmd === 'list') {
+    const listArgs = [subject, ...rest].filter((arg): arg is string => arg !== undefined);
+    const listRoot = optionValue(listArgs, '--root', process.cwd());
+    const worlds = listWorlds(listRoot).map(world => ({ ...world, usage: worldUsage(listRoot, world.name) }));
+    if (rest.includes('--json') || subject === '--json') process.stdout.write(`${JSON.stringify(worlds, null, 2)}\n`);
+    else for (const world of worlds) {
+      process.stdout.write(`${world.name}\t${!world.running ? 'stopped' : world.degraded ? 'degraded' : 'running'}\t${world.config ?? ''}\tcreated=${world.usage.createdAt ?? 'unknown'}\tlast-observed-use=${world.usage.lastUsedAt ?? 'unknown'} (${world.usage.lastUseSource ?? 'unrecorded'}; partial coverage)\n`);
+      for (const warning of world.usage.warnings) process.stdout.write(`  WARNING: ${warning}\n`);
+    }
+    return;
+  }
+
+  if (cmd === 'env') {
+    if (!subject) throw new Error('volter-world env: missing world name');
+    const split = rest.indexOf('--');
+    if (split < 0) throw new Error('volter-world env: pass command after --');
+    const exitCode = await attachWorld(subject, rest.slice(split + 1), root, { owner: ownerOption(rest.slice(0, split)), verbose: rest.slice(0, split).includes('--verbose') });
+    process.exit(exitCode);
+  }
+
+  if (cmd === 'attach') {
+    // `subject` may be the ref, a flag, or the `--` separator — reassemble and split.
+    const args = [subject, ...rest].filter((arg): arg is string => arg !== undefined);
+    const split = args.indexOf('--');
+    const head = split >= 0 ? args.slice(0, split) : args;
+    const command = split >= 0 ? args.slice(split + 1) : [];
+    const explicit = head[0] !== undefined && !head[0].startsWith('-') ? head[0] : undefined;
+    const via = optionValue(head, '--via', 'env');
+    // when the ref is omitted, `subject` was a flag — the global root parse missed its value
+    const attachRoot = optionValue(head, '--root', process.cwd());
+    const resolved = resolveWorldRef(explicit, { cwd: process.cwd(), env: process.env });
+    if (ownerOption(head) !== undefined && (isRemoteWorldRef(resolved.ref) || via !== 'env')) {
+      throw new Error('--owner is supported for local attach --via env commands');
+    }
+    if (isRemoteWorldRef(resolved.ref)) {
+      // remote world: fetch the manifest, synthesize the attach env, exec
+      const attachToken = optionValue(head, '--token') || process.env.VOLTER_WORLD_TOKEN || undefined;
+      const manifest = await fetchRemoteManifest(resolved.ref, attachToken === undefined ? {} : { token: attachToken });
+      if (via === 'direct') {
+        process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
+        return;
+      }
+      if (via !== 'env') throw new Error(`volter-world attach: --via ${via} is not available for a remote world (env|direct)`);
+      if (command.length === 0) throw new Error('volter-world attach: pass the command after --');
+      let caFile: string | undefined;
+      if (manifest.ca !== null) {
+        caFile = join(mkdtempSync(join(tmpdir(), 'volter-attach-')), 'ca.pem');
+        writeFileSync(caFile, manifest.ca);
+      }
+      const injectPath = createRequire(import.meta.url).resolve('@volter/world-core/inject');
+      const env = remoteAttachEnv(manifest, { injectPath, ...(caFile === undefined ? {} : { caFile }) });
+      // the world's byte-stream doors, bridged to loopback listeners here, beside a command in any language
+      const { bridgeStreams, drainStreams } = createRequire(import.meta.url)('@volter/world-core/stream-bridge') as { bridgeStreams: (streams: WorldManifest['streams'], token: string) => Promise<{ env: Record<string, string> }>; drainStreams: (ms?: number) => Promise<void> };
+      const bridged = manifest.streams ? await bridgeStreams(manifest.streams, attachToken ?? manifest.env.VOLTER_TWINS_KEY ?? '') : { env: {} };
+      // VOLTER_WORLD names the World to the injector: a request addressed to its paths carries its key
+      const commandEnv: Record<string, string | undefined> = { ...process.env, ...env, ...bridged.env, VOLTER_WORLD: resolved.ref };
+      commandEnv.VOLTER_TWIN_INJECT_QUIET = head.includes('--verbose') ? '0' : commandEnv.VOLTER_TWIN_INJECT_QUIET ?? '1';
+      const child = spawn(command[0]!, command.slice(1), { env: commandEnv, stdio: 'inherit' });
+      const code = await new Promise<number>((resolveExit) => { child.on('exit', (status) => resolveExit(status ?? 1)); child.on('error', () => resolveExit(127)); });
+      // a client that wrote and exited at once still has bytes on their way through a bridge
+      await drainStreams();
+      process.exit(code);
+    }
+    if (via === 'direct') {
+      process.stdout.write(`${JSON.stringify(worldManifest(resolved.ref, attachRoot), null, 2)}\n`);
+      return;
+    }
+    if (via === 'reflect') {
+      // The reflect attachment (docs/ATTACH.md): the consumer is unmodified; its DNS is the world's resolver
+      // and its TLS trust is the session CA. A `docker compose` command is composed here — every service
+      // gets the override — and everything else runs with the trust env and VOLTER_WORLD set, its DNS
+      // being the caller's to point (a container's --dns, a resolver on the host).
+      if (command.length === 0) throw new Error('volter-world attach: pass the command after --');
+      const manifest = readReflectManifest(attachRoot, resolved.ref);
+      if (!manifest) throw new Error(`volter-world attach --via reflect: no reflect front is running for world ${resolved.ref} — start one: volter-world reflect ${resolved.ref} --target-ip <ip> --port 443 --resolver-port 53`);
+      const env: Record<string, string> = { ...process.env as Record<string, string>, VOLTER_WORLD: resolved.ref, VOLTER_REFLECT_DNS: manifest.targetIp, VOLTER_WORLD_CA: manifest.caCertPath };
+      Object.assign(env, sessionTrustEnv(manifest.caCertPath, env));
+      let toRun = command;
+      const compose = splitDockerComposeArgs(command);
+      if (compose) {
+        // the consumer's own service names, from its own files, through its own docker
+        const listed = spawnSync(compose.head[0]!, [...compose.head.slice(1), ...compose.composeFlags, 'config', '--services'], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+        if (listed.status !== 0) throw new Error(`volter-world attach --via reflect: docker compose config --services failed:\n${listed.stderr.toString().trim()}`);
+        const services = listed.stdout.toString().split('\n').map((s) => s.trim()).filter(Boolean);
+        const overridePath = join(instanceDir(attachRoot, resolved.ref), 'reflect-compose.override.yml');
+        writeFileSync(overridePath, composeOverrideForReflect(manifest, services, resolved.ref));
+        toRun = dockerComposeWithOverride(command, overridePath);
+        process.stderr.write(`volter-world attach --via reflect: ${services.length} service(s) attached — dns ${manifest.resolverIp}:53, front ${manifest.targetIp}:443, CA ${ATTACHED_CA_PATH}\n`);
+      }
+      const result = spawnSync(toRun[0]!, toRun.slice(1), { env, stdio: 'inherit' });
+      process.exit(result.status ?? 1);
+    }
+    if (via !== 'env') {
+      throw new Error(`volter-world attach: --via ${via} is not available (env|reflect|direct)`);
+    }
+    if (command.length === 0) throw new Error('volter-world attach: pass the command after -- (or use --via direct for the manifest)');
+    // the world resolves at --root; the COMMAND runs where the caller stands —
+    // an attached repo's `pnpm start` must run in the repo, not the twin root
+    // (ponder blind-adoption finding)
+    process.exit(await attachWorld(resolved.ref, command, attachRoot, { cwd: process.cwd(), owner: ownerOption(head), verbose: head.includes('--verbose') }));
+  }
+
+  if (cmd === 'manifest') {
+    if (!subject) throw new Error('volter-world manifest: missing world name');
+    process.stdout.write(`${JSON.stringify(worldManifest(subject, root), null, 2)}\n`);
+    return;
+  }
+
+  if (cmd === 'reflect') {
+    if (!subject) throw new Error('volter-world reflect: missing world name');
+    const targetIp = optionValue(rest, '--target-ip');
+    if (!targetIp) throw new Error('volter-world reflect: --target-ip <ip> is required (the address attachers reach the front at)');
+    const routesPath = reflectRoutesPath(root, subject);
+    const front = await startReflectFront({
+      envLoader: () => statusWorld(subject, root).env,
+      tlsDir: join(instanceDir(root, subject), 'tls'),
+      port: Number(optionValue(rest, '--port', '0')) || 0,
+    });
+    const resolver = await startReflectResolver({
+      routesLoader: () => readReflectRoutes(routesPath),
+      targetIp,
+      upstream: optionValue(rest, '--upstream') || undefined,
+      port: Number(optionValue(rest, '--resolver-port', '0')) || 0,
+    });
+    const resolverIp = optionValue(rest, '--resolver-ip') || targetIp;
+    writeReflectManifest(root, subject, { targetIp, resolverIp, frontPort: front.port, resolverPort: resolver.port, caCertPath: front.caCertPath });
+    process.stdout.write(`Reflect attachment for world ${subject}:\n`);
+    process.stdout.write(`  front:    ${targetIp}:${front.port} (SNI TLS door — session CA: ${front.caCertPath})\n`);
+    process.stdout.write(`  resolver: ${resolverIp}:${resolver.port} (point the attacher's DNS here, e.g. docker run --dns)\n`);
+    process.stdout.write(`  routes:   ${routesPath} (volter-world route ${subject} add <host>)\n`);
+    process.stdout.write('Foreground — Ctrl+C to stop. The runtime supervises nothing (see docs/guides/route-a-cli-through-the-world.md).\n');
+    await new Promise<void>((resolveSignal) => {
+      process.once('SIGINT', () => resolveSignal());
+      process.once('SIGTERM', () => resolveSignal());
+    });
+    clearReflectManifest(root, subject);
+    await resolver.close();
+    await front.close();
+    return;
+  }
+
+  if (cmd === 'serve') {
+    if (!subject) throw new Error('volter-world serve: missing world name');
+    const advertise = optionValue(rest, '--advertise');
+    if (!advertise) throw new Error('volter-world serve: --advertise <https-origin> is required (how attachers reach the door, e.g. https://worlds.corp:8443)');
+    let advertisedUrl: URL;
+    try {
+      advertisedUrl = new URL(advertise);
+    } catch {
+      throw new Error(`volter-world serve: --advertise must be an origin URL, got "${advertise}"`);
+    }
+    if (advertisedUrl.protocol !== 'https:') throw new Error('volter-world serve: the advertised origin must be https (the door terminates TLS with the session CA)');
+    const frontPort = Number(advertisedUrl.port) || 443;
+    const front = await startReflectFront({
+      envLoader: () => statusWorld(subject, root).env,
+      tlsDir: join(instanceDir(root, subject), 'tls'),
+      port: Number(optionValue(rest, '--port', String(frontPort))) || frontPort,
+      extraHosts: [advertisedUrl.hostname],
+    });
+    const serveToken = optionValue(rest, '--token') || undefined;
+    const manifestServer = await startManifestServer({
+      manifest: () => advertiseWorldManifest(subject, root, advertisedUrl.origin),
+      port: Number(optionValue(rest, '--manifest-port', '0')) || 0,
+      ...(serveToken === undefined ? {} : { token: serveToken }),
+    });
+    process.stdout.write(`Serving world ${subject}:\n`);
+    process.stdout.write(`  door:     ${advertisedUrl.origin} (SNI TLS — vendors + the advertised name; session CA: ${front.caCertPath})\n`);
+    process.stdout.write(`  manifest: http://0.0.0.0:${manifestServer.port}${MANIFEST_PATH}\n`);
+    process.stdout.write(`  attach:   volter-world attach http://<this-host>:${manifestServer.port} -- <command...>\n`);
+    process.stdout.write('Foreground — Ctrl+C to stop. Read-only publication; the runtime supervises nothing.\n');
+    await new Promise<void>((resolveSignal) => {
+      process.once('SIGINT', () => resolveSignal());
+      process.once('SIGTERM', () => resolveSignal());
+    });
+    await manifestServer.close();
+    await front.close();
+    return;
+  }
+
+  if (cmd === 'route') {
+    if (!subject) throw new Error('volter-world route: missing world name');
+    const [verb, host] = rest.filter((arg) => !arg.startsWith('--'));
+    const routesPath = reflectRoutesPath(root, subject);
+    const routes = readReflectRoutes(routesPath);
+    if (verb === 'ls' || verb === undefined) {
+      for (const entry of [...routes].sort()) process.stdout.write(`${entry}\n`);
+      return;
+    }
+    if (!host) throw new Error(`volter-world route: ${verb} needs a host`);
+    if (verb === 'add') routes.add(host.toLowerCase());
+    else if (verb === 'rm') routes.delete(host.toLowerCase());
+    else throw new Error(`volter-world route: unknown verb "${verb}" (add|rm|ls)`);
+    writeReflectRoutes(routesPath, routes);
+    process.stdout.write(`${[...routes].sort().join('\n')}${routes.size > 0 ? '\n' : ''}`);
+    return;
+  }
+
+  if (cmd === 'activate') {
+    if (!subject) throw new Error('volter-world activate: missing world name');
+    process.stdout.write(activateScript(subject, root));
+    return;
+  }
+
+  if (cmd === 'shell') {
+    if (!subject) throw new Error('volter-world shell: missing world name');
+    process.exit(await shellWorld(subject, root));
+  }
+
+  if (cmd === 'run') {
+    if (!subject) throw new Error('volter-world run: missing config');
+    const split = rest.indexOf('--');
+    if (split < 0) throw new Error('volter-world run: pass command after --');
+    const envFile = optionValue(rest, '--env-file');
+    if (!envFile) throw new Error('volter-world run: missing required --env-file=<path>');
+    const name = optionValue(rest, '--name') || undefined;
+    const mode = optionValue(rest, '--mode', 'local') as 'local' | 'share' | 'sealed';
+    const result = await runWorld(subject, rest.slice(split + 1), { root, name, mode, envFile, owner: ownerOption(rest.slice(0, split)), keep: rest.slice(0, split).includes('--keep'), verbose: rest.slice(0, split).includes('--verbose') });
+    if (result.exitCode !== 0) {
+      const detail = result.outcome.error ? `could not start (${result.outcome.error})`
+        : result.outcome.signal ? `was terminated by ${result.outcome.signal}`
+          : `exited with code ${result.outcome.exitCode}`;
+      process.stderr.write(`World ${result.instance.name}: foreground consumer failed: ${detail}\nLog: ${result.outcome.log}\n`);
+      // A command that failed because a service under it died says so: each service that ended on its own during the
+      // run (not by the World's teardown after it) is named with its end.
+      for (const service of Object.values(result.instance.services)) {
+        if (service.type === 'external' || !service.log) continue;
+        const end = readServiceEnd(service.log);
+        if (!end?.exited || end.exited.stopRequested) continue;
+        process.stderr.write(`  service ${service.id} ended during the run: it ${describeServiceEnd(end)}${end.lastOutput.length ? `; last output: ${end.lastOutput[end.lastOutput.length - 1]}` : ''}\n    log: ${service.log}\n`);
+      }
+    }
+    process.exit(result.exitCode);
+  }
+
+  if (cmd === 'share') {
+    if (!subject) throw new Error('volter-world share: missing world name');
+    const service = optionValue(rest, '--service') || undefined;
+    const verifyPath = rest.includes('--no-verify')
+      ? false
+      : rest.includes('--verify')
+        ? optionValue(rest, '--verify', '/health')
+        : undefined;
+    const split = rest.indexOf('--');
+    const command = optionValue(rest, '--command') || undefined;
+    const providerValue = optionValue(rest, '--provider') || undefined;
+    if (providerValue !== undefined && providerValue !== 'cloudflare-quick' && providerValue !== 'command') {
+      throw new Error('volter-world share: --provider must be cloudflare-quick or command');
+    }
+    const provider = providerValue as 'cloudflare-quick' | 'command' | undefined;
+    if (provider === 'cloudflare-quick' && command) {
+      throw new Error('volter-world share: --provider cloudflare-quick uses the built-in cloudflared command and cannot be combined with --command');
+    }
+    if (split >= 0 && !command) throw new Error('volter-world share: -- <args> requires --command <cmd>');
+    const args = command && split >= 0 ? rest.slice(split + 1) : undefined;
+    const instance = await shareWorldServices(subject, { root, service, verifyPath, provider, command, args, ephemeral: rest.includes('--ephemeral') || undefined });
+    const serviceIds = service ? [service] : Object.values(instance.services)
+      .filter((candidate) => candidate.publicUrl)
+      .map((candidate) => candidate.id);
+    for (const serviceId of serviceIds) {
+      const shared = instance.services[serviceId];
+      process.stdout.write(`${shared?.publicReady ? 'Shared' : 'Shared (unverified)'} ${subject}/${serviceId}: ${shared?.publicUrl}\n`);
+    }
+    return;
+  }
+
+  if (cmd === 'unshare') {
+    if (!subject) throw new Error('volter-world unshare: missing world name');
+    const service = optionValue(rest, '--service') || undefined;
+    const result = unshareWorld(subject, { root, service });
+    process.stdout.write(`Unshared world ${subject}${service ? `/${service}` : ''}\n`);
+    if (result.escalated.length) process.stdout.write(`Escalated to SIGKILL (tunnel ignored SIGTERM past the grace): ${result.escalated.join(', ')}\n`);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${cmd}`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});
+
+/** The rows `outdated` / `audit` print. `outdated`: pinned vs mounted vs catalog-current version and the
+ *  protocol standing; `audit`: the catalog's upkeep verdicts for each mounted twin — the invariant
+ *  matrix's grandfathered cells and the spec census baseline — read from the pack's committed
+ *  census.json. `attention` marks a row the operator should act on (exit 1). */
+function worldUpkeep(status: ReturnType<typeof statusWorld>, kind: 'outdated' | 'audit'): Array<{ id: string; line: string; attention: boolean }> {
+  const twinRoot = join(import.meta.dir, '..', '..', 'twin'); // the catalog: packages/twin
+  const out: Array<{ id: string; line: string; attention: boolean }> = [];
+  for (const [id, svc] of Object.entries(status.services)) {
+    if (svc.type !== 'twin' && svc.resolvedVersion === undefined) continue;
+    const vendor = id;
+    let current: string | undefined;
+    try { current = (JSON.parse(readFileSync(join(twinRoot, vendor, 'package.json'), 'utf8')) as { version?: string }).version; } catch { current = undefined; }
+    const pinned = status.services[id] && (svc as { version?: string }).version;
+    if (kind === 'outdated') {
+      const behind = svc.resolvedVersion !== undefined && current !== undefined && svc.resolvedVersion !== current;
+      const standing = svc.protocol?.standing ?? 'unknown';
+      const attention = behind || standing === 'deprecated' || standing === 'refused';
+      out.push({ id, attention, line: `${id.padEnd(18)} mounted ${(svc.resolvedVersion ?? '?').padEnd(8)} catalog ${(current ?? '?').padEnd(8)} ${behind ? 'BEHIND' : 'current'}   protocol ${svc.protocol ? `major ${svc.protocol.major} (${standing})` : 'unknown'}${pinned ? `   pinned ${pinned}` : ''}` });
+    } else {
+      let census: { invariants?: Record<string, string>; spec?: unknown } | undefined;
+      try { census = JSON.parse(readFileSync(join(twinRoot, vendor, 'census.json'), 'utf8')); } catch { census = undefined; }
+      const debt = Object.entries(census?.invariants ?? {}).filter(([, v]) => v === 'grandfathered').map(([k]) => k);
+      const attention = debt.length > 0;
+      // R19 — the pin's age: MAINTAINERS.md's `last verified` cell is when this package's vendor
+      // generation was last proven against a fresh spec; a stale one is drift nobody has looked for.
+      let maintained = '';
+      try {
+        const row = readFileSync(join(twinRoot, '..', '..', 'policy', 'MAINTAINERS.md'), 'utf8').split('\n').find((l) => l.startsWith(`| ${vendor} |`));
+        const cells = row ? row.split('|').map((c) => c.trim()) : [];
+        if (cells.length > 8) {
+          const days = Math.floor((Date.now() - Date.parse(cells[8]!)) / 86_400_000);
+          maintained = `   ${cells[2]}, last verified ${cells[8]}${Number.isFinite(days) ? ` (${days}d ago)` : ''}`;
+          if (Number.isFinite(days) && days > 30) maintained += ' STALE';
+        }
+      } catch { maintained = ''; }
+      out.push({ id, attention: attention || maintained.endsWith('STALE'), line: `${id.padEnd(18)} matrix debt: ${debt.length ? debt.join(', ') : 'none'}   census: ${census ? 'committed' : 'NONE (not Supported)'}${maintained}` });
+    }
+  }
+  return out;
+}
+
+/** The files a service wrote into its own log directory (`<log>.d`, VOLTER_WORLD_SERVICE_LOG_DIR), paths in full. */
+function ownLogs(log: string): string[] {
+  const dir = `${log.replace(/\.log$/, '')}.d`;
+  try { return readdirSync(dir).map((entry) => join(dir, entry)); } catch { return []; }
+}