@volter/world-runtime 2.0.0

package/dist/src/cli.js

@@ -0,0 +1,1262 @@
+#!/usr/bin/env node
+import { sessionTrustEnv } from "./ca-trust.js";
+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 } 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, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, ATTACHED_CA_PATH } from "./index.js";
+import { formatApplication, formatChangeset, formatRebaseReport, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, parseVerifierExpression } from '@volter/world-core';
+import { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer } from "./serve.js";
+import { clockFile, instanceDir, pruneWorlds } from "./runtime.js";
+import { worldResourceReport } from "./resources.js";
+import { worldConsumers, worldUsage } from "./consumers.js";
+import { addAppHosts, appUrlUnsetMessage, detectAppUrl, readAppUrl, setAppUrl } from "./app-url.js";
+import { describeServiceEnd, describeWorldEvent, readServiceEnd, readWorldEvents } from "./service-exit.js";
+import { worldEventsPath } from "./runtime.js";
+import { superviseWorldUp } from "./up-task.js";
+/** An option's value, written `--name value` or `--name=value`. */
+function optionValue(args, name, fallback = '') {
+    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) {
+    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, valueFlags = ['--root']) {
+    const positionals = [];
+    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, command) {
+    const acknowledge = {};
+    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() {
+    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) {
+    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() {
+    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 !== 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 !== 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');
+        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);
+        // 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]] : []; }));
+        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);
+        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.js");
+        const names = [subject, ...rest].filter((a) => 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]];
+        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 = [];
+        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 !== 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 !== 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;
+            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');
+            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 = { ...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((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 = { ...process.env, 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((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;
+        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((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');
+        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;
+        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, kind) {
+    const twinRoot = join(import.meta.dir, '..', '..', 'twin'); // the catalog: packages/twin
+    const out = [];
+    for (const [id, svc] of Object.entries(status.services)) {
+        if (svc.type !== 'twin' && svc.resolvedVersion === undefined)
+            continue;
+        const vendor = id;
+        let current;
+        try {
+            current = JSON.parse(readFileSync(join(twinRoot, vendor, 'package.json'), 'utf8')).version;
+        }
+        catch {
+            current = undefined;
+        }
+        const pinned = status.services[id] && svc.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;
+            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) {
+    const dir = `${log.replace(/\.log$/, '')}.d`;
+    try {
+        return readdirSync(dir).map((entry) => join(dir, entry));
+    }
+    catch {
+        return [];
+    }
+}