@volter/twin-world 0.1.0 → 0.1.2

package/src/cli.ts

@@ -1,5 +1,13 @@
 #!/usr/bin/env bun
-import { activateScript, checkPrerequisites, doctorWorld, downWorld, formatPrerequisiteChecks, listWorlds, runWithWorldEnv, runWorld, shareWorldServices, shellWorld, statusWorld, unshareWorld, upWorld, urlsWorld } from './index.ts';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve, resolve as resolvePath } from 'node:path';
+import { activateScript, approveWorldChangeset, checkPrerequisites, coverWorld, createWorldChangeset, diffWorld, doctorWorld, downWorld, findWorldChangeset, formatCoverageReport, formatInitReport, formatPrerequisiteChecks, formatProjectInspection, initWorld, inspectProject, isRemoteWorldRef, listWorldChangesets, listWorlds, markWorld, planWorldActions, readReflectRoutes, reflectRoutesPath, readReflectManifest, writeReflectManifest, clearReflectManifest, composeOverrideForReflect, splitDockerComposeArgs, dockerComposeWithOverride, CA_TRUST_ENV, ATTACHED_CA_PATH, replayWorldChangeset, resolveWorldRef, reviewWorldActions, runWithWorldEnv, runWorld, shareWorldServices, shellWorld, startReflectFront, startReflectResolver, statusWorld, statusWorldChangeset, tailWorldActions, unshareWorld, upWorld, urlsWorld, urlWorld, verifyWorldChangeset, worldManifest, writeReflectRoutes } from './index.ts';
+import { formatChangeset, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, parseVerifierExpression } from '@volter/twin';
+import { advertiseWorldManifest, fetchRemoteManifest, MANIFEST_PATH, remoteAttachEnv, startManifestServer } from './serve.ts';
+import { clockFile, instanceDir } from './runtime.ts';
+import { appUrlUnsetMessage, detectAppUrl, readAppUrl, setAppUrl } from './app-url.ts';
 import type { PrerequisiteId } from './index.ts';
 
 function optionValue(args: string[], name: string, fallback = ''): string {
@@ -7,21 +15,120 @@ function optionValue(args: string[], name: string, fallback = ''): string {
   return index >= 0 && index + 1 < args.length ? args[index + 1]! : fallback;
 }
 
+/** 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> [--name <name>] [--mode local|share|sealed] [--isolation process|colocated|worker] [--root <repo>]
   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/DATA_AT_REST.md
   volter-world status <name> [--json] [--root <repo>]
+  volter-world plan <name> --service <id> [--root <repo>]
+  volter-world review <name> --service <id> --plan-id <exact-id> --decision approved|rejected --actor-id <id> [--reason <text>] [--root <repo>]
   volter-world doctor <name> [--verify-public] [--json] [--root <repo>]
-  volter-world doctor-prereqs --require docker [--json] [--quiet]
+  volter-world doctor-prereqs --require local-execution [--json] [--quiet]
+  volter-world inspect-project [path] [--json]   # read-only adoption discovery
+  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>] [--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 tail <name> [service...] [--no-follow] [--json] [--requests] [--root <repo>]
+                                                  # 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 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>]
+                                                  # one honest line: hash, verified?, approvals, ready|not-ready + why
+                                                  # (exit 0 when ready; no pushing here — that is v2)
   volter-world list [--root <repo>]
-  volter-world env <name> -- <command...>
-  volter-world activate <name>   # eval "$(volter-world activate <name>)" — a virtualenv for vendor APIs
-  volter-world shell <name>      # drop into a subshell with the world active (any CLI hits the twins)
+  volter-world env <name> [--root <repo>] -- <command...>
+  volter-world attach [<world-ref>] [--via env|direct] [--root <repo>] [-- <command...>]
+                                                  # ref: explicit → $VOLTER_WORLD → nearest .volter-world file (docs/ATTACH.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/ATTACH.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] -- <command...>
-  volter-world share <name> [--service app] [--verify /health|--no-verify] [--command <cmd> [-- <args…>]]  # {url} in args = the service's local URL
+  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.
@@ -32,7 +139,15 @@ 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}`).join('\n')}
+${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}
@@ -52,6 +167,10 @@ async function main(): Promise<void> {
     printHelp();
     return;
   }
+  if (subject === '--help' || subject === '-h') {
+    printHelp();
+    return;
+  }
 
   if (cmd === 'up') {
     if (!subject) throw new Error('volter-world up: missing config');
@@ -100,11 +219,55 @@ async function main(): Promise<void> {
     if (rest.includes('--json')) process.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
     else {
       process.stdout.write(`World ${status.name}: ${status.running ? 'running' : 'stopped'} (${status.config})\n`);
-      for (const service of Object.values(status.services)) process.stdout.write(`  ${service.id}: ${service.url}\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.resources) {
+        process.stdout.write(`  resources: memory=${status.resources.memoryMiB}MiB writable-storage=${status.resources.writableStorageMiB}MiB\n    log: ${status.resources.log}\n`);
+      }
+      for (const service of Object.values(status.services)) {
+        const lifecycle = service.type === 'external' ? 'externally managed'
+          : status.livePids.includes(service.pid) ? 'running' : 'stopped';
+        process.stdout.write(`  ${service.id}: ${service.url ?? '(no World URL)'} (${lifecycle})\n    log: ${service.log}\n`);
+      }
     }
     return;
   }
 
+  if (cmd === 'plan') {
+    if (!subject) throw new Error('volter-world plan: missing world name');
+    const service = optionValue(rest, '--service');
+    if (!service) throw new Error('volter-world plan: --service <id> is required');
+    process.stdout.write(`${JSON.stringify(planWorldActions(subject, service, root), null, 2)}\n`);
+    return;
+  }
+
+  if (cmd === 'review') {
+    if (!subject) throw new Error('volter-world review: missing world name');
+    const service = optionValue(rest, '--service');
+    if (!service) throw new Error('volter-world review: --service <id> is required');
+    const expectedTransactionSetId = optionValue(rest, '--plan-id');
+    if (!expectedTransactionSetId) throw new Error('volter-world review: --plan-id <exact-id> is required');
+    const decision = optionValue(rest, '--decision');
+    if (decision !== 'approved' && decision !== 'rejected') throw new Error('volter-world review: --decision must be approved or rejected');
+    const actorId = optionValue(rest, '--actor-id');
+    if (!actorId) throw new Error('volter-world review: --actor-id is required');
+    const actorKind = optionValue(rest, '--actor-kind', 'human');
+    if (actorKind !== 'human' && actorKind !== 'agent') throw new Error('volter-world review: --actor-kind must be human or agent');
+    const review = reviewWorldActions(subject, service, { expectedTransactionSetId, decision, actor: { kind: actorKind, id: actorId }, reason: optionValue(rest, '--reason') || undefined, root });
+    process.stdout.write(`${JSON.stringify(review, null, 2)}\n`);
+    return;
+  }
+
   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') });
@@ -121,7 +284,7 @@ async function main(): Promise<void> {
   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 : ['docker']);
+    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`);
@@ -133,6 +296,101 @@ async function main(): Promise<void> {
     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 === '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;
+  }
+
+  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);
@@ -147,6 +405,148 @@ async function main(): Promise<void> {
     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');
+    if (set || detect) {
+      const record = set ? setAppUrl(subject, set, { root }) : await detectAppUrl(subject, detect, { 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})` : ''}\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') {
+    if (!subject) throw new Error('volter-world tail: missing world name (usage: volter-world tail <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 === 'mark') {
+    if (!subject) throw new Error('volter-world mark: missing world name (usage: volter-world mark <world> [--id <marker>])');
+    const id = optionValue(rest, '--id');
+    const marker = markWorld(subject, { root, ...(id ? { id } : {}) });
+    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;
+    }
+    throw new Error(`volter-world changeset: unknown subcommand ${JSON.stringify(subject ?? '')} (want create|show|list|replay|verify|approve|status)`);
+  }
+
   if (cmd === 'list') {
     for (const world of listWorlds(root)) {
       process.stdout.write(`${world.name}\t${world.running ? 'running' : 'stopped'}\t${world.config ?? ''}\n`);
@@ -162,6 +562,171 @@ async function main(): Promise<void> {
     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 (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 = resolvePath(import.meta.dir, '../../control-plane/inject.cjs');
+      const env = remoteAttachEnv(manifest, { injectPath, ...(caFile === undefined ? {} : { caFile }) });
+      const result = spawnSync(command[0]!, command.slice(1), { env: { ...process.env, ...env }, stdio: 'inherit' });
+      process.exit(result.status ?? 1);
+    }
+    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 };
+      for (const key of CA_TRUST_ENV) env[key] = manifest.caCertPath;
+      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(runWithWorldEnv(resolved.ref, command, attachRoot, { cwd: process.cwd() }));
+  }
+
+  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/ATTACH.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));
@@ -182,6 +747,12 @@ async function main(): Promise<void> {
     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, keep: rest.includes('--keep') });
+    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`);
+    }
     process.exit(result.exitCode);
   }
 
@@ -195,9 +766,17 @@ async function main(): Promise<void> {
         : 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, command, args });
+    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);