sparta_worlds 0.6.0

package/dist/cli/index.js

@@ -0,0 +1,1014 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { Command, Option } from "commander";
+import { authOptionsFromEnv, buildServer, createLayeredSeedLibrary, describeAuth, parseSeed, resolveLibraryDirs, resolveUserDir, SeedValidationError, seedHash, } from "#server";
+import { globalOptionAfterSubcommand, shellLine } from "./argv.js";
+import { commandAllowlist } from "./commands.js";
+import { readDoc } from "./load.js";
+import { installStdioGuard } from "./stdio.js";
+import { cliVersion } from "./version.js";
+installStdioGuard();
+const program = new Command();
+const DEFAULT_URL = process.env.WORLDS_URL ?? "http://127.0.0.1:4242";
+function adminUrl() {
+    return (program.opts().url ?? DEFAULT_URL).replace(/\/$/, "");
+}
+function adminToken() {
+    return program.opts().adminToken ?? (process.env.WORLDS_ADMIN_TOKEN || undefined);
+}
+async function admin(method, path, body) {
+    const headers = { "content-type": "application/json" };
+    const token = adminToken();
+    if (token)
+        headers.authorization = `Bearer ${token}`;
+    let res;
+    try {
+        res = await fetch(`${adminUrl()}${path}`, {
+            method,
+            headers,
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+    }
+    catch {
+        fail(`could not reach a worlds server at ${adminUrl()} — start one with \`worlds serve\` (or pass --url)`);
+    }
+    const text = await res.text();
+    const parsed = text ? JSON.parse(text) : undefined;
+    if (!res.ok) {
+        const msg = parsed?.error?.message ?? text;
+        const hint = res.status === 401
+            ? "\n  hint: this server requires an admin token — pass --admin-token or set WORLDS_ADMIN_TOKEN (worlds serve prints an auto-provisioned token on the start that mints it, and its file path on every later start)"
+            : res.status === 403
+                ? "\n  hint: a world token only drives its own world; server-level commands need the operator token"
+                : "";
+        fail(`${method} ${path} → ${res.status}: ${msg}${hint}`);
+    }
+    return parsed;
+}
+function fail(message, code = 1) {
+    console.error(`error: ${message}`);
+    process.exit(code);
+}
+function out(value) {
+    console.log(typeof value === "string" ? value : JSON.stringify(value, null, 2));
+}
+program
+    .name("worlds")
+    .description("worlds — a flight simulator for AI agents that touch money.\nRun a high-fidelity fake Stripe, point your agent at it, and grade the world afterward.")
+    .option("--url <url>", `admin API URL of a running server (default: $WORLDS_URL or ${DEFAULT_URL})`)
+    .option("--admin-token <token>", "operator or world token for the admin API (default: $WORLDS_ADMIN_TOKEN; not needed on loopback with auth off)")
+    .option("--commands-json", "print the commands the docs and the site may show (the allowlist), as JSON, and exit")
+    .enablePositionalOptions()
+    .version(cliVersion());
+program
+    .command("serve")
+    .description("start the worlds server (twin API at /v1/*, admin API at /admin/*)")
+    .option("-p, --port <port>", "port to listen on", "4242")
+    .option("--host <host>", "host to bind", "127.0.0.1")
+    .option("--data-dir <dir>", "directory for world SQLite files (default: $WORLDS_DATA_DIR, else ./.worlds)")
+    .option("--seeds-dir <dir>", "your seeds directory, layered over the bundled library (default: $WORLDS_SEEDS_DIR, else ./seeds)")
+    .option("--scenarios-dir <dir>", "your scenarios directory, layered over the bundled library (default: $WORLDS_SCENARIOS_DIR, else ./scenarios)")
+    .option("--public-url <url>", "origin handed back as base_url (default: $WORLDS_PUBLIC_URL, else derived from each request's Host)")
+    .option("--trust-proxy", "honor X-Forwarded-Host/Proto when deriving base_url (default: $WORLDS_TRUST_PROXY=1)")
+    .option("--no-trust-proxy", "ignore X-Forwarded-* even when $WORLDS_TRUST_PROXY=1")
+    .option("--admin-token <token>", "operator token for /admin/* (16+ chars; default: $WORLDS_ADMIN_TOKEN; auto-provisioned when required and unset)")
+    .option("--auth <mode>", "force admin auth: off | required (default: $WORLDS_AUTH, else off on loopback / required otherwise)")
+    .action(async (opts) => {
+    const envUrl = process.env.WORLDS_PUBLIC_URL || undefined;
+    const publicUrl = opts.publicUrl ?? envUrl;
+    const pinnedBy = opts.publicUrl ? "--public-url" : envUrl ? "WORLDS_PUBLIC_URL" : undefined;
+    const trustProxy = opts.trustProxy ?? process.env.WORLDS_TRUST_PROXY === "1";
+    const adminTokenFlag = opts.adminToken ?? program.opts().adminToken;
+    let auth = {};
+    try {
+        auth = authOptionsFromEnv({
+            ...process.env,
+            ...(adminTokenFlag !== undefined ? { WORLDS_ADMIN_TOKEN: adminTokenFlag } : {}),
+            ...(opts.auth !== undefined ? { WORLDS_AUTH: opts.auth } : {}),
+        }, {
+            token: adminTokenFlag !== undefined ? "--admin-token" : undefined,
+            mode: opts.auth !== undefined ? "--auth" : undefined,
+        });
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
+    const server = buildServer({
+        dataDir: opts.dataDir,
+        seedsDir: opts.seedsDir,
+        scenariosDir: opts.scenariosDir,
+        publicUrl,
+        trustProxy,
+        auth,
+    });
+    const address = await server.listen(Number(opts.port), opts.host);
+    const wildcard = opts.host === "0.0.0.0" || opts.host === "::";
+    const note = pinnedBy
+        ? `  (pinned by ${pinnedBy})`
+        : wildcard
+            ? "  (wildcard bind: each caller gets its own Host back as base_url; set WORLDS_PUBLIC_URL to pin it)"
+            : "";
+    console.log(`worlds server listening at ${address}`);
+    console.log(`  twin API    ${address}/v1/*   (Stripe-compatible — authenticate with a world API key)`);
+    console.log(`  admin API   ${address}/admin/*`);
+    console.log(`  public URL  ${server.publicUrl()}${note}`);
+    console.log(`  ${describeAuth(server.auth())}`);
+    const refused = server.manager.refusedFiles().length;
+    if (refused > 0)
+        console.log(`  ${refused} world file(s) this runtime refuses — run: worlds world ls`);
+    console.log(`  seeds: ${server.manager.seedLibrary
+        .list()
+        .map((s) => s.name)
+        .join(", ") || "(none found)"}`);
+    console.log(`  scenarios: ${server.scenarios
+        .list()
+        .map((s) => s.name)
+        .join(", ") || "(none found)"}`);
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        process.on(signal, () => void server.close().then(() => process.exit(0)));
+    }
+});
+program
+    .command("demo")
+    .description("60-second demo, zero config: watch a naive agent double-refund under a rate-limit storm — and the world diff catch it")
+    .action(async () => {
+    const { runDemo } = await import("./demo.js");
+    process.exit(await runDemo());
+});
+program
+    .command("run")
+    .description("one terminal: a server in this process on a free port, then your command with WORLDS_URL, WORLDS_ADMIN_TOKEN and WORLDS_PUBLIC_URL in its environment (and one world's WORLDS_BASE_URL / WORLDS_API_KEY / WORLDS_WORLD_ID with --seed) — evidence exported when it fails, the server stopped, the command's exit code returned.\n" +
+    "Exit: the command's; 124 on --timeout; 2 when the server could not be started as asked or the command could not be spawned.")
+    .passThroughOptions()
+    .option("--seed <name>", "create one world from this seed first and hand the command its bindings")
+    .option("--evidence <dir>", "where a failing command's evidence goes: the world list, every world's dump and request log, the run's log (default: a temp directory, named on stderr)")
+    .option("--port <n>", "bind this port instead of a free one (refused when it is taken)")
+    .option("--timeout <sec>", "kill the command's tree after this many seconds (exit 124)")
+    .option("--keep", "keep the server's data directory after the run", false)
+    .option("--no-preload", "leave the SDK preload out of the agent's environment (NODE_OPTIONS --import, PYTHONPATH): the agent points its Stripe SDK at the world itself; WORLDS_PRELOAD=0 does the same")
+    .option("--seeds-dir <dir>", "your seeds directory, layered over the bundled library")
+    .option("--scenarios-dir <dir>", "your scenarios directory, layered over the bundled library")
+    .argument("<command...>", "the command to run (put it after --)")
+    .action(async (command, opts) => {
+    const port = opts.port === undefined ? undefined : Number(opts.port);
+    if (port !== undefined && (!Number.isInteger(port) || port < 1 || port > 65535))
+        fail(`--port must be a port number (got '${opts.port}')`, 2);
+    const timeout = opts.timeout === undefined ? undefined : Number(opts.timeout);
+    if (timeout !== undefined && (!Number.isInteger(timeout) || timeout < 1))
+        fail(`--timeout must be a positive integer of seconds (got '${opts.timeout}')`, 2);
+    const { RunSetupError, runCommand } = await import("./run.js");
+    try {
+        process.exit(await runCommand({
+            preload: opts.preload,
+            seed: opts.seed,
+            evidence: opts.evidence,
+            port,
+            timeoutSec: timeout,
+            keep: opts.keep,
+            seedsDir: opts.seedsDir,
+            scenariosDir: opts.scenariosDir,
+            command,
+            log: (line) => console.error(line),
+        }));
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err), err instanceof RunSetupError ? err.code : 1);
+    }
+});
+async function ownServer(keep) {
+    const { RunSetupError, startServer } = await import("./run.js");
+    try {
+        return await startServer({ keep, log: (line) => console.error(line) });
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err), err instanceof RunSetupError ? err.code : 1);
+    }
+}
+function tokenSource() {
+    if (program.opts().adminToken !== undefined)
+        return "--admin-token";
+    if (process.env.WORLDS_ADMIN_TOKEN !== undefined)
+        return "WORLDS_ADMIN_TOKEN";
+    return "none";
+}
+program
+    .command("selftest")
+    .description("a deterministic check of the evaluator, not of your agent: five known agents on the built-in task (one correct, four wrong in the ways that matter), graded as a customer's agent would be — exit 0 when every verdict is as expected, 1 when one is not")
+    .option("--server <mode>", "auto: a server in this process for the run, instead of --url (one terminal)")
+    .option("--timeout <sec>", "kill a known agent after this many seconds", "120")
+    .option("--json", "print every variant's verdict as JSON on stdout", false)
+    .action(async (opts) => {
+    if (opts.server !== undefined && opts.server !== "auto")
+        fail(`--server must be auto (got '${opts.server}')`, 2);
+    const timeout = Number(opts.timeout);
+    if (!Number.isInteger(timeout) || timeout < 1)
+        fail(`--timeout must be a positive integer (got '${opts.timeout}')`, 2);
+    const { PasskConfigError, PasskInconclusiveError, PasskInterrupted, PasskSetupError } = await import("./passk.js");
+    const { runSelftest } = await import("./selftest.js");
+    const own = opts.server === "auto" ? await ownServer(false) : undefined;
+    let code = 1;
+    try {
+        code = await runSelftest({
+            adminUrl: own?.url ?? adminUrl(),
+            adminToken: own?.token ?? adminToken(),
+            timeoutSec: timeout,
+            json: opts.json,
+        });
+    }
+    catch (err) {
+        await own?.close();
+        fail(err instanceof Error ? err.message : String(err), err instanceof PasskInterrupted
+            ? err.exitCode
+            : err instanceof PasskConfigError
+                ? 2
+                : err instanceof PasskSetupError
+                    ? 3
+                    : err instanceof PasskInconclusiveError
+                        ? 4
+                        : 1);
+    }
+    await own?.close();
+    process.exit(code);
+});
+program.command("selftest-agent <variant>", { hidden: true }).action(async (variant) => {
+    const { runSelftestAgent } = await import("./selftest.js");
+    try {
+        process.exit(await runSelftestAgent(variant));
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err), 1);
+    }
+});
+program
+    .command("doctor")
+    .description("the dead ends explained: what the server looks like from here, one world and the topology its base URL implies, then a probe the way your agent's SDK would make it (the agent command after --, or the env file's base URL and key, or doctor's own) and whether the world's request log recorded it — a wrong host, a wrong scheme, a missing base URL, a key that is not the world's and plain silence each get their own line.\n" +
+    "Exit 0 the probe was recorded, 2 the environment or the command is wrong in a way doctor can name, 3 no server, 4 no traffic with no named cause.")
+    .passThroughOptions()
+    .option("--env-file <file>", "the file your agent's environment is loaded from (KEY=VALUE lines): its WORLDS_BASE_URL and WORLDS_API_KEY are checked")
+    .option("--server <mode>", "auto: a server in this process for the check, instead of --url (one terminal)")
+    .option("--no-preload", "leave the SDK preload out of the agent's environment (NODE_OPTIONS --import, PYTHONPATH): the agent points its Stripe SDK at the world itself; WORLDS_PRELOAD=0 does the same")
+    .option("--timeout <sec>", "kill the agent after this many seconds", "120")
+    .option("--json", "print the report as JSON on stdout", false)
+    .argument("[agent-command...]", "the agent command to run once against the world (put it after --)")
+    .action(async (agentCommand, opts) => {
+    if (opts.server !== undefined && opts.server !== "auto")
+        fail(`--server must be auto (got '${opts.server}')`, 2);
+    const timeout = Number(opts.timeout);
+    if (!Number.isInteger(timeout) || timeout < 1)
+        fail(`--timeout must be a positive integer (got '${opts.timeout}')`, 2);
+    if (opts.envFile !== undefined && agentCommand.length > 0)
+        fail("--env-file or an agent command after --, not both: doctor probes one way at a time", 2);
+    const { runDoctor } = await import("./doctor.js");
+    const own = opts.server === "auto" ? await ownServer(false) : undefined;
+    let code = 1;
+    try {
+        code = await runDoctor({
+            adminUrl: own?.url ?? adminUrl(),
+            adminToken: own?.token ?? adminToken(),
+            tokenSource: own ? "minted for this run" : tokenSource(),
+            ...(own
+                ? { own: { host: new URL(own.url).hostname, port: Number(new URL(own.url).port), dataDir: own.dataDir } }
+                : {}),
+            envFile: opts.envFile,
+            agentCommand,
+            timeoutSec: timeout,
+            preload: opts.preload,
+            json: opts.json,
+        });
+    }
+    catch (err) {
+        await own?.close();
+        fail(err instanceof Error ? err.message : String(err), 1);
+    }
+    await own?.close();
+    process.exit(code);
+});
+program
+    .command("try")
+    .description("the hello world: one world from the bundled account, one built-in task (a customer charged twice, asking for one refund), your agent — then what it did to the money, its reply, and the verdict.\n" +
+    "Exit 0 when the world ended right, 1 when it did not (or no Stripe traffic was recorded), 2 for configuration.")
+    .passThroughOptions()
+    .option("--mode <mode>", "isolated (the task on the agent's stdin and in WORLDS_TASK_JSON, stdout as the reply) or shift (the task on the world's help desk)", "isolated")
+    .option("--timeout <sec>", "kill the agent after this many seconds", "300")
+    .option("--keep-worlds", "keep the world for post-mortem instead of destroying it", false)
+    .option("--server <mode>", "auto: a server in this process for the run, instead of --url (one terminal)")
+    .option("--no-preload", "leave the SDK preload out of the agent's environment (NODE_OPTIONS --import, PYTHONPATH): the agent points its Stripe SDK at the world itself; WORLDS_PRELOAD=0 does the same")
+    .argument("<agent-command...>", "the agent command to run (put it after --)")
+    .action(async (agentCommand, opts) => {
+    if (opts.mode !== "isolated" && opts.mode !== "shift")
+        fail(`--mode must be isolated or shift (got '${opts.mode}')`, 2);
+    const timeout = Number(opts.timeout);
+    if (!Number.isInteger(timeout) || timeout < 1)
+        fail(`--timeout must be a positive integer (got '${opts.timeout}')`, 2);
+    if (opts.server !== undefined && opts.server !== "auto")
+        fail(`--server must be auto (got '${opts.server}')`, 2);
+    const { PasskConfigError, PasskInconclusiveError, PasskInterrupted, PasskSetupError } = await import("./passk.js");
+    const { runTry } = await import("./try.js");
+    const own = opts.server === "auto" ? await ownServer(opts.keepWorlds) : undefined;
+    let code = 1;
+    try {
+        code = await runTry({
+            adminUrl: own?.url ?? adminUrl(),
+            adminToken: own?.token ?? adminToken(),
+            mode: opts.mode,
+            timeoutSec: timeout,
+            keepWorlds: opts.keepWorlds,
+            preload: opts.preload,
+            serverAuto: opts.server === "auto",
+            agentCommand,
+        });
+    }
+    catch (err) {
+        await own?.close();
+        fail(err instanceof Error ? err.message : String(err), err instanceof PasskInterrupted
+            ? err.exitCode
+            : err instanceof PasskConfigError
+                ? 2
+                : err instanceof PasskSetupError
+                    ? 3
+                    : err instanceof PasskInconclusiveError
+                        ? 4
+                        : 1);
+    }
+    await own?.close();
+    process.exit(code);
+});
+program
+    .command("init")
+    .description("your account and your agent first — the Stripe key of the account to copy in (used once, written nowhere) and the command that runs your agent — then the policy (the defaults in one question, or five), then the crash test scaffolded into this repo: worlds/seeds/my-account.json and worlds/tasks.yaml on it (two tasks on your own customers; without a key, the bundled account and a starter pack), worlds/policy.md, the harness test, the CI workflow, the .gitignore line. Never overwrites.")
+    .option("--dir <dir>", "target directory", ".")
+    .option("--python", "generate a pytest harness instead of vitest", false)
+    .option("--stripe-key <key>", "the Stripe key of the account to copy in: a restricted read-only key (rk_…) or a test-mode key (default: $STRIPE_API_KEY, else asked); used once, in process, written nowhere")
+    .option("--no-import", "skip the key and the import: start on the bundled account")
+    .option("--agent <command>", "the command that runs your agent once on a ticket, into the harness and the workflow (default: asked, else a TODO)")
+    .option("--tickets <file>", "a help desk export to import now: its requesters are copied in from the account by email, each with its invoices, charges and subscriptions, and its rows become your first tasks (default: asked beside a key, else none)")
+    .option("--sample <n>", "objects per resource copied from the account beyond the customers the export names", "100")
+    .addOption(new Option("--stripe-base-url <url>", "the Stripe API origin to import from (tests)").hideHelp())
+    .option("--runtime <spec>", "what the generated harness and workflow run the runtime from: sparta_worlds@<version> on the registry (default: this CLI's own package and version), or a versioned tarball URL for a pinned copy")
+    .option("--tarball <url>", "a versioned runtime tarball URL, for a pinned copy instead of the registry package (the same as --runtime <url>)")
+    .option("--action <ref>", "write the two-step workflow on the setup action (e.g. Sparta-AI/twinlab/action@v0): the server for the job, the crash test against it, the evidence in the artifact — instead of the one-step passk --server auto")
+    .option("--refunds <days|none>", "may the agent refund, and within how many days (default: asked, else 60)")
+    .option("--credits <cents>x<count>|none", "goodwill credits: the amount in cents and how many a day, e.g. 5000x3 (default: asked, else 5000x3)")
+    .option("--cancel <mode>", "period-end | immediate | none (default: asked, else period-end)")
+    .option("--plan-changes <yes|no>", "may it change plans (default: asked, else yes)")
+    .option("--escalate <who>", "who takes what it may not do (default: asked, else 'the billing lead')")
+    .option("--pack <authorities>", "the starter packs to merge, overriding the answers' choice: refunds,credits,cancellations,plan-changes,invoices (the first task of each kind of failure, fifteen at most) — or all (every pack, uncapped: the whole starter library)")
+    .option("--no-prompt", "ask nothing: the defaults stand for every answer not given as a flag")
+    .action(async (opts) => {
+    const sample = Number(opts.sample);
+    if (!Number.isInteger(sample) || sample < 1)
+        fail(`--sample must be a positive integer (got '${opts.sample}')`, 2);
+    const { runInit } = await import("./init.js");
+    let result;
+    try {
+        result = await runInit({
+            dir: resolve(opts.dir),
+            python: opts.python,
+            stripeKey: opts.stripeKey,
+            noImport: !opts.import,
+            agent: opts.agent,
+            tickets: opts.tickets,
+            sample,
+            stripeBaseUrl: opts.stripeBaseUrl,
+            runtime: opts.runtime ?? opts.tarball,
+            action: opts.action,
+            refunds: opts.refunds,
+            credits: opts.credits,
+            cancel: opts.cancel,
+            planChanges: opts.planChanges,
+            escalate: opts.escalate,
+            pack: opts.pack,
+            noPrompt: !opts.prompt,
+        }, (line) => console.error(line));
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err), 2);
+    }
+    console.log(`policy: refunds ${result.answers.refundDays === null ? "none" : `within ${result.answers.refundDays} days`} · credits ${result.answers.credits === null ? "none" : `${result.answers.credits.amountCents}x${result.answers.credits.perDay}`} · cancel ${result.answers.cancel} · plan changes ${result.answers.planChanges ? "yes" : "no"} · escalate to ${result.answers.escalateTo}`);
+    if (result.account) {
+        const a = result.account;
+        console.log(`account: ${a.seed} (${a.customers} customers, ${a.invoices} invoices, ${a.charges} charges, ${a.subscriptions} subscriptions; names, emails and free text pseudonymized — worlds/my-account.manifest.json)`);
+    }
+    if (result.account?.named && result.account.named.emails > 0) {
+        const n = result.account.named;
+        const missing = n.missing.length
+            ? `; not in Stripe: ${n.missing.slice(0, 5).join(", ")}${n.missing.length > 5 ? ` and ${n.missing.length - 5} more` : ""}`
+            : "";
+        console.log(`  named by the export: ${n.found} of ${n.emails} email(s) found in the account and copied in${missing}`);
+    }
+    if (result.imported)
+        console.log(`tickets: ${result.imported.tasks} task(s) from ${result.imported.file}${result.imported.unknown.length ? ` (${result.imported.unknown.length} requester(s) the account does not know were skipped)` : ""} → worlds/tasks.yaml`);
+    const packsLabel = result.packsAll
+        ? "all"
+        : result.packs.length
+            ? result.packs.join(", ")
+            : "(none: the tasks every pack carries)";
+    const library = result.packsAll
+        ? ", the whole starter library"
+        : result.library !== undefined && result.packs.length > 0
+            ? ` of ${result.library.tasks} in the starter library (--pack all takes them all)`
+            : "";
+    if (result.starter)
+        console.log(`packs: ${packsLabel} → ${result.starter.tasks} task(s)${library} in ${result.starter.file} (the starter library's account)`);
+    else if (result.account && result.packs.length === 0)
+        console.log(`packs: (none: two tasks on your own customers) → ${result.tasks} task(s)`);
+    else
+        console.log(`packs: ${packsLabel} → ${result.tasks} task(s)${library}`);
+    for (const f of result.created)
+        console.log(`created  ${f}`);
+    for (const f of result.updated)
+        console.log(`updated  ${f} (+ worlds/*.identities.json)`);
+    for (const f of result.skipped)
+        console.log(`skipped  ${f} (already exists — not touching it)`);
+    console.log("\nWhat's left (the parts only you can do):");
+    result.nextSteps.forEach((s, i) => {
+        console.log(`  ${i + 1}. ${s}`);
+    });
+});
+program
+    .command("passk")
+    .description("run an agent command k times, each against a fresh world, and grade every run by the world diff.\n" +
+    "The agent command receives WORLDS_BASE_URL, WORLDS_API_KEY, WORLDS_WORLD_ID, and WORLDS_URL.\n" +
+    "Example:\n" +
+    "  worlds passk --seed saas-billing-small --scenario rate-limit-storm --runs 8 \\\n" +
+    "    --expect 'created.refunds==1' --expect 'created.refunds[0].amount==4000' \\\n" +
+    "    -- pnpm --filter @worlds/demo-agent agent")
+    .passThroughOptions()
+    .option("--seed <name>", "library seed each run's world is created from (or --tasks, whose file names it)")
+    .option("--tasks <file>", "the tasks file (worlds/tasks.yaml, docs/tasks.md): the seed, your tickets and their keys in one document; exclusive with --seed and --rubric; its runs, scenario, mode, budget and policy are defaults the flags override")
+    .option("--mode <mode>", "with --tasks: isolated (one world per task, the task handed to the agent on stdin and in WORLDS_TASK_JSON, stdout as the reply) or shift (every task in one world, read from the desk); default: the file's")
+    .option("--task <id>", "with --tasks: only this task (its id, or its position), repeatable — the replay of one task", (v, prev) => [...prev, v], [])
+    .option("--scenario <name-or-file>", "failure scenario to apply to every world (library name or YAML/JSON file)")
+    .option("--runs <k>", "how many times to run the agent (default: the tasks file's runs, else 5)")
+    .option("--expect <expr>", "world-diff assertion, repeatable — e.g. 'created.refunds==1', 'money.usd.net_movement==-4000'", (v, prev) => [...prev, v], [])
+    .option("--rubric <file>", "per-ticket answer key (YAML/JSON) for a shift: grades every ticket and the whole shift, reports per-ticket accuracy")
+    .option("--mark <name>", "mark name set before each run", "passk-start")
+    .option("--timeout <sec>", "kill an agent run after this many seconds", "300")
+    .option("--json", "print a machine-readable report on stdout", false)
+    .option("--server <mode>", "auto: a server in this process for the run, instead of --url (one terminal)")
+    .option("--no-preload", "leave the SDK preload out of the agent's environment (NODE_OPTIONS --import, PYTHONPATH): the agent points its Stripe SDK at the world itself; WORLDS_PRELOAD=0 does the same")
+    .option("--json-file <file>", "also write the machine-readable results to this file (what CI uploads beside the report)")
+    .option("--report <file>", "write a self-contained HTML report (shareable, projector-ready)")
+    .option("--keep-worlds", "keep each run's world for post-mortem instead of destroying it", false)
+    .option("--evidence <dir>", "where a run that could not be graded leaves its world's dump and request log, and where --judge writes every ticket's judge/<ticket>.json (default: a temp directory, named on stderr)")
+    .option("--judge", "grade every ticket against a policy text with a model — advisory: verdicts land beside the run's own and never change pass or the exit code", false)
+    .option("--policy <file>", "the policy text --judge grades against (plain text or markdown; written once, not per ticket)")
+    .option("--judge-model <id>", "the judge's model", process.env.WORLDS_JUDGE_MODEL ?? "claude-sonnet-5")
+    .option("--judge-runs <n>", "samples per ticket; the majority is the verdict and every sample is kept", "1")
+    .option("--judge-budget <cents>", "the shift-wide credit cap the judge tracks when no rubric supplies one")
+    .argument("<agent-command...>", "the agent command to run (put it after --)")
+    .action(async (agentCommand, opts) => {
+    const runs = opts.runs === undefined ? undefined : Number(opts.runs);
+    if (runs !== undefined && (!Number.isInteger(runs) || runs < 1))
+        fail(`--runs must be a positive integer (got '${opts.runs}')`, 2);
+    if (opts.tasks !== undefined && opts.seed !== undefined)
+        fail("--tasks names its seed: drop --seed", 2);
+    if (opts.tasks !== undefined && opts.rubric !== undefined)
+        fail("--tasks carries its own key: drop --rubric", 2);
+    if (opts.tasks === undefined && opts.seed === undefined)
+        fail("--seed <name> or --tasks <file> is required", 2);
+    if (opts.mode !== undefined && opts.tasks === undefined)
+        fail("--mode belongs to --tasks", 2);
+    if (opts.mode !== undefined && opts.mode !== "isolated" && opts.mode !== "shift")
+        fail(`--mode must be isolated or shift (got '${opts.mode}')`, 2);
+    if (opts.task.length > 0 && opts.tasks === undefined)
+        fail("--task names a task of a tasks file: add --tasks <file>", 2);
+    if (opts.judge && !opts.policy && !opts.tasks)
+        fail("--judge needs --policy <file>: the policy text the judge grades against", 2);
+    if (opts.policy && !opts.judge)
+        fail("--policy is the judge's policy: add --judge, or drop --policy", 2);
+    const judgeRuns = Number(opts.judgeRuns);
+    if (!Number.isInteger(judgeRuns) || judgeRuns < 1) {
+        fail(`--judge-runs must be a positive integer (got '${opts.judgeRuns}')`, 2);
+    }
+    const judgeBudget = opts.judgeBudget === undefined ? undefined : Number(opts.judgeBudget);
+    if (judgeBudget !== undefined && (!Number.isInteger(judgeBudget) || judgeBudget < 0)) {
+        fail(`--judge-budget must be a non-negative integer of cents (got '${opts.judgeBudget}')`, 2);
+    }
+    if (opts.expect.length === 0 && !opts.rubric && !opts.tasks) {
+        fail("at least one --expect (or a --rubric, or --tasks) is required — passk grades the world, so say what the world should look like (e.g. --expect 'created.refunds==1')", 2);
+    }
+    if (opts.server !== undefined && opts.server !== "auto")
+        fail(`--server must be auto (got '${opts.server}')`, 2);
+    const { PasskConfigError, PasskInconclusiveError, PasskInterrupted, PasskSetupError, runPassk } = await import("./passk.js");
+    const own = opts.server === "auto" ? await ownServer(opts.keepWorlds) : undefined;
+    let code = 1;
+    try {
+        code = await runPassk({
+            adminUrl: own?.url ?? adminUrl(),
+            adminToken: own?.token ?? adminToken(),
+            ...(opts.seed !== undefined ? { seed: opts.seed } : {}),
+            ...(opts.tasks !== undefined
+                ? {
+                    tasks: {
+                        file: opts.tasks,
+                        ...(opts.mode !== undefined ? { mode: opts.mode } : {}),
+                    },
+                }
+                : {}),
+            ...(opts.task.length > 0 ? { taskFilter: opts.task } : {}),
+            scenario: opts.scenario,
+            ...(runs !== undefined ? { runs } : {}),
+            expects: opts.expect,
+            rubric: opts.rubric,
+            mark: opts.mark,
+            timeoutSec: Number(opts.timeout),
+            json: opts.json,
+            ...(opts.jsonFile !== undefined ? { jsonFile: opts.jsonFile } : {}),
+            keepWorlds: opts.keepWorlds,
+            preload: opts.preload,
+            report: opts.report,
+            evidence: opts.evidence,
+            agentCommand,
+            invocation: shellLine(["worlds", ...process.argv.slice(2)]),
+            ...(opts.judge
+                ? { judge: { policyFile: opts.policy, model: opts.judgeModel, runs: judgeRuns, budget: judgeBudget } }
+                : {}),
+        });
+    }
+    catch (err) {
+        await own?.close();
+        fail(err instanceof Error ? err.message : String(err), err instanceof PasskInterrupted
+            ? err.exitCode
+            : err instanceof PasskConfigError
+                ? 2
+                : err instanceof PasskSetupError
+                    ? 3
+                    : err instanceof PasskInconclusiveError
+                        ? 4
+                        : 1);
+    }
+    await own?.close();
+    process.exit(code);
+});
+program
+    .command("judge [world_id]")
+    .description("judge a kept world against a policy text, post hoc — the diff since a mark, every ticket's verdict from the world's records, advisory.\n" +
+    "Iterate on the policy without re-running the agent: worlds passk --keep-worlds, then worlds judge <world> --policy p.md.\n" +
+    "With --transcript <jsonl> instead of a world: the same judge over the agent's own transcript (a WORLDS_TRAJECTORY_FILE), no world needed")
+    .option("--from <mark>", "the mark the shift started at", "passk-start")
+    .option("--transcript <jsonl>", "judge from the agent's transcript (one JSON line per ticket) instead of a world's records")
+    .option("--clock <iso>", "with --transcript: the world's clock at the shift's start, so ages are precomputed as for a world")
+    .requiredOption("--policy <file>", "the policy text (plain text or markdown; written once, not per ticket)")
+    .option("--judge-model <id>", "the judge's model", process.env.WORLDS_JUDGE_MODEL ?? "claude-sonnet-5")
+    .option("--judge-runs <n>", "samples per ticket; the majority is the verdict", "1")
+    .option("--judge-budget <cents>", "the shift-wide credit cap when no rubric supplies one")
+    .option("--rubric <file>", "the answer key, to report the judge's agreement with it")
+    .option("--json", "print the verdicts as JSON on stdout", false)
+    .option("--json-file <file>", "also write the JSON to this file")
+    .option("--evidence <dir>", "write every ticket's input, raw model output and verdict under <dir>/<world>/judge/")
+    .action(async (worldId, opts) => {
+    const runs = Number(opts.judgeRuns);
+    if (!Number.isInteger(runs) || runs < 1)
+        fail(`--judge-runs must be a positive integer (got '${opts.judgeRuns}')`, 2);
+    const budget = opts.judgeBudget === undefined ? undefined : Number(opts.judgeBudget);
+    if (budget !== undefined && (!Number.isInteger(budget) || budget < 0)) {
+        fail(`--judge-budget must be a non-negative integer of cents (got '${opts.judgeBudget}')`, 2);
+    }
+    if (!opts.transcript && !worldId)
+        fail("judge needs a world id, or --transcript <jsonl>", 2);
+    if (opts.transcript && worldId)
+        fail("judge takes a world id or --transcript <jsonl>, not both", 2);
+    if (opts.transcript && opts.rubric)
+        fail("--rubric grades a world's diff; pair transcript verdicts with a passk --json run instead", 2);
+    if (opts.clock && !opts.transcript)
+        fail("--clock goes with --transcript; a world carries its own clock", 2);
+    const { runJudgeCommand, runTranscriptJudgeCommand } = await import("./judge-command.js");
+    const { PasskConfigError } = await import("./passk.js");
+    try {
+        if (opts.transcript) {
+            process.exit(await runTranscriptJudgeCommand({
+                transcript: opts.transcript,
+                clock: opts.clock,
+                policyFile: opts.policy,
+                model: opts.judgeModel,
+                runs,
+                budget,
+                json: opts.json,
+                jsonFile: opts.jsonFile,
+                evidence: opts.evidence,
+            }));
+        }
+        process.exit(await runJudgeCommand({
+            adminUrl: adminUrl(),
+            adminToken: adminToken(),
+            worldId: worldId,
+            mark: opts.from,
+            policyFile: opts.policy,
+            model: opts.judgeModel,
+            runs,
+            budget,
+            rubric: opts.rubric,
+            json: opts.json,
+            jsonFile: opts.jsonFile,
+            evidence: opts.evidence,
+        }));
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err), err instanceof PasskConfigError ? 2 : 1);
+    }
+});
+const seed = program.command("seed").description("inspect and validate seeds (local, no server needed)");
+seed
+    .command("ls")
+    .description("list library seeds: the bundled library plus your own seeds directory ($WORLDS_SEEDS_DIR or ./seeds), which wins on name collisions")
+    .option("--seeds-dir <dir>", "your seeds directory (default: $WORLDS_SEEDS_DIR, else ./seeds)")
+    .action((opts) => {
+    const lib = createLayeredSeedLibrary(resolveLibraryDirs("seeds", opts.seedsDir));
+    const seeds = lib.list();
+    if (seeds.length === 0)
+        fail(`no valid seeds found (looked in: ${lib.dirs.join(", ")})`);
+    for (const s of seeds) {
+        const d = s.seed.data;
+        console.log(`${s.name}  (v${s.seed.version}, ${s.seed.clock_mode} clock)`);
+        console.log(`  hash ${s.hash}`);
+        console.log(`  customers=${d.customers.length} products=${d.products.length} prices=${d.prices.length} invoices=${d.invoices.length} subscriptions=${d.subscriptions.length}`);
+        console.log(`  file ${s.file}`);
+    }
+});
+seed
+    .command("validate <file>")
+    .description("validate a seed file: structure, referential integrity, and its canonical hash")
+    .action((file) => {
+    const path = resolve(file);
+    if (!existsSync(path))
+        fail(`no such file: ${path}`);
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        fail(`not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+        const parsed = parseSeed(doc);
+        console.log(`OK: ${parsed.name} is a valid seed`);
+        console.log(`  seed_hash ${seedHash(parsed)}`);
+    }
+    catch (err) {
+        if (err instanceof SeedValidationError) {
+            console.error("INVALID seed:");
+            for (const issue of err.issues)
+                console.error(`  - ${issue.path}: ${issue.message}`);
+            process.exit(1);
+        }
+        throw err;
+    }
+});
+seed
+    .command("import")
+    .description("import a Stripe account's shape (products, prices, invoice states, subscriptions — identities and free text pseudonymized) into a seed file")
+    .requiredOption("--from-stripe", "import from a Stripe-compatible API (the only source in the MVP)")
+    .option("--key <key>", "read-only API key (default: $STRIPE_API_KEY)")
+    .option("--base-url <url>", "API origin — api.stripe.com, or a world's base_url", "https://api.stripe.com")
+    .option("--name <name>", "seed name (also the default output filename)", "imported-stripe")
+    .option("--out <file>", "output path (default: $WORLDS_SEEDS_DIR or ./seeds, <name>.json)")
+    .option("--limit <n>", "max objects fetched per resource", "100")
+    .option("--tickets <file>", "copy in the customers this help desk export names (by email, each with its invoices, charges and subscriptions) beyond the --limit sample")
+    .option("--keep-metadata", "keep customer metadata verbatim (only for test-mode accounts — metadata may name a person)", false)
+    .option("--keep-names", "keep product names and price nicknames verbatim (default: hash-derived placeholders — free text can name a client)", false)
+    .option("--keep-descriptions", "keep invoice line descriptions verbatim (default: the line's price nickname (kept or placeholder), else 'Line item N')", false)
+    .option("--manifest <file>", "also write the import manifest (what was replaced, kept, folded, unsupported) as JSON")
+    .option("--identity-map <file>", "also write the identity map — each customer's real id, email and name beside the seed's pseudonym — mode 0600, for `tasks build` on this machine only; never commit it (`worlds init` adds worlds/*.identities.json to .gitignore)")
+    .option("--epoch <unix>", "override the epoch (default: newest object's `created`, rounded up to UTC midnight)")
+    .action(async (opts) => {
+    const { identityMapDoc, importStripeSeed } = await import("./import.js");
+    const { writeFileSync, mkdirSync, chmodSync } = await import("node:fs");
+    const { dirname } = await import("node:path");
+    const apiKey = opts.key ?? process.env.STRIPE_API_KEY;
+    if (!apiKey)
+        fail("no API key: pass --key or set $STRIPE_API_KEY (a read-only restricted key is enough)");
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(opts.name))
+        fail(`invalid --name '${opts.name}' (kebab-case required)`);
+    let customerEmails;
+    if (opts.tickets !== undefined) {
+        const { exportRequesterEmails } = await import("./tasks.js");
+        try {
+            customerEmails = exportRequesterEmails(resolve(opts.tickets));
+        }
+        catch (err) {
+            fail(`--tickets ${opts.tickets}: ${err instanceof Error ? err.message : String(err)}`, 2);
+        }
+    }
+    let result;
+    try {
+        result = await importStripeSeed({
+            baseUrl: opts.baseUrl.replace(/\/$/, ""),
+            apiKey,
+            name: opts.name,
+            limit: Number(opts.limit),
+            customerEmails,
+            keepMetadata: opts.keepMetadata,
+            keepNames: opts.keepNames,
+            keepDescriptions: opts.keepDescriptions,
+            epoch: opts.epoch !== undefined ? Number(opts.epoch) : undefined,
+        });
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
+    const seed = parseSeed(result.seedDoc);
+    const outFile = resolve(opts.out ?? join(resolveUserDir("seeds"), `${opts.name}.json`));
+    mkdirSync(dirname(outFile), { recursive: true });
+    writeFileSync(outFile, `${JSON.stringify(result.seedDoc, null, 2)}\n`);
+    const s = result.stats;
+    const m = result.manifest;
+    console.log(`wrote ${outFile}`);
+    if (opts.manifest) {
+        const manifestFile = resolve(opts.manifest);
+        mkdirSync(dirname(manifestFile), { recursive: true });
+        writeFileSync(manifestFile, `${JSON.stringify(m, null, 2)}\n`);
+        console.log(`manifest written ${manifestFile}`);
+    }
+    if (opts.identityMap) {
+        const mapFile = resolve(opts.identityMap);
+        mkdirSync(dirname(mapFile), { recursive: true });
+        const map = identityMapDoc(seed.name, seedHash(seed), result.identities);
+        writeFileSync(mapFile, `${JSON.stringify(map, null, 2)}\n`, { mode: 0o600 });
+        chmodSync(mapFile, 0o600);
+        console.log(`identity map written ${mapFile} (mode 0600 — real identities; keep it on this machine, never commit it)`);
+    }
+    if (s.named.emails > 0)
+        console.log(`  named by --tickets: ${s.named.found} of ${s.named.emails} email(s) found in the account and copied in with their invoices, charges and subscriptions${s.named.missing.length ? `; not in the account: ${s.named.missing.slice(0, 5).join(", ")}${s.named.missing.length > 5 ? ` and ${s.named.missing.length - 5} more` : ""}` : ""}`);
+    console.log(`  seed_hash ${seedHash(seed)}`);
+    console.log(`  customers=${s.customers} products=${s.products} prices=${s.prices} invoices=${s.invoices} (charges attached: ${s.charges_attached}) subscriptions=${s.subscriptions}`);
+    const r = m.scrub.replaced;
+    const kept = m.scrub.retained.product_names || m.scrub.retained.line_descriptions
+        ? " (some kept by flag — see the manifest samples)"
+        : "";
+    const fromKept = r.line_descriptions_from_kept_nickname > 0
+        ? `, ${r.line_descriptions_from_kept_nickname} line(s) carry their price's kept nickname`
+        : "";
+    console.log(`  pseudonymized: ${r.customer_names} name(s), ${r.customer_emails} email(s); replaced ${r.product_names} product name(s), ${r.price_nicknames} price nickname(s), ${r.line_descriptions} line description(s)${fromKept}${kept}; ids remapped — pseudonymization, not anonymity`);
+    const v = m.scrub.verbatim;
+    if (v.product_ids.count + v.price_ids.count > 0) {
+        const examples = [...v.product_ids.samples, ...v.price_ids.samples].slice(0, 3).join(", ");
+        console.log(`  verbatim: ${v.product_ids.count} merchant-chosen product id(s), ${v.price_ids.count} price id(s) kept as-is — agent code references them, so an id that names a client is not scrubbed (e.g. ${examples}; the manifest lists them)`);
+    }
+    for (const note of m.lossy.notes)
+        console.log(`  lossy: ${note}`);
+    if (s.skipped.length > 0) {
+        console.log(`  skipped ${s.skipped.length} object(s):`);
+        for (const line of s.skipped.slice(0, 10))
+            console.log(`    - ${line}`);
+        if (s.skipped.length > 10)
+            console.log(`    ... and ${s.skipped.length - 10} more`);
+    }
+    console.log(`\nCreate a world from it: worlds world create --seed ${seed.name}`);
+});
+const tasks = program
+    .command("tasks")
+    .description("the tasks file (worlds/tasks.yaml): your tickets with one-line expected: keys, compiled into a seed and a rubric — validate, build, import. Local, no server.\n" +
+    "expected: forms — refund <amount> [on any | on duplicate | on <charge id>] · credit <amount> · credit up to <amount> · void [<invoice id>] · cancel [<subscription id> | duplicate] · cancel at period end [<subscription id>] · plan change to <price id> [<subscription id>] · none · escalate");
+async function buildTasksFile(file, seedsDir, keepSeedTickets) {
+    const { buildTasks, loadTasks, readIdentityMap, resolveSeedRef, TaskErrors } = await import("./tasks.js");
+    const path = resolve(file);
+    if (!existsSync(path))
+        fail(`no such file: ${path}`, 2);
+    let loaded;
+    try {
+        loaded = loadTasks(path);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err), 2);
+    }
+    const { doc, dir, text } = loaded;
+    try {
+        const base = resolveSeedRef(doc.seed, dir, seedsDir);
+        const map = doc.identity_map === undefined ? undefined : readIdentityMap(resolve(dir, doc.identity_map));
+        const built = buildTasks(doc, base, map, { keepSeedTickets, name: basename(path), text });
+        return { doc, dir, text, path, built };
+    }
+    catch (err) {
+        if (err instanceof TaskErrors) {
+            console.error(`${path}: ${err.errors.length} problem(s):`);
+            for (const e of err.errors)
+                console.error(`  ✗ ${e.message}`);
+            process.exit(2);
+        }
+        fail(err instanceof Error ? err.message : String(err), 2);
+    }
+}
+tasks
+    .command("validate <file>")
+    .description("parse the file, resolve every expected: line against the seed, check the identity map; every problem by task id, exit 2 on any")
+    .option("--seeds-dir <dir>", "your seeds directory for a library seed name (default: $WORLDS_SEEDS_DIR, else ./seeds)")
+    .option("--keep-seed-tickets", "keep the base seed's own tickets ahead of the tasks", false)
+    .action(async (file, opts) => {
+    const { describeBuild } = await import("./tasks.js");
+    const { doc, built, path } = await buildTasksFile(file, opts.seedsDir, opts.keepSeedTickets);
+    console.log(`OK: ${path}`);
+    console.log(`  ${describeBuild(doc, built)}`);
+    for (const t of built.record.tasks)
+        console.log(`  ${t.position}. ${t.label}: ${t.customer ?? `(escalate: ${built.rubric.tickets[t.position - 1].candidates.join(", ")})`} — ${t.resolution}`);
+});
+tasks
+    .command("build <file>")
+    .description("compile the tasks file: the seed (the account with the tasks on its desk), the rubric, and <name>.build.json beside the file")
+    .option("--out-seed <file>", "write the seed document (JSON)")
+    .option("--out-rubric <file>", "write the rubric (JSON)")
+    .option("--out-record <file>", "write the build record here instead of beside the tasks file")
+    .option("--rewrite", "write the tasks file back with every requester replaced by the seed's email (for a file going to CI)", false)
+    .option("--keep-seed-tickets", "keep the base seed's own tickets ahead of the tasks", false)
+    .option("--seeds-dir <dir>", "your seeds directory for a library seed name (default: $WORLDS_SEEDS_DIR, else ./seeds)")
+    .action(async (file, opts) => {
+    const { buildRecordPath, describeBuild, rewriteRequesters } = await import("./tasks.js");
+    const { writeFileSync, mkdirSync } = await import("node:fs");
+    const { dirname } = await import("node:path");
+    const { doc, built, path, text } = await buildTasksFile(file, opts.seedsDir, opts.keepSeedTickets);
+    const write = (target, content) => {
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, content);
+        console.log(`wrote ${target}`);
+    };
+    if (opts.outSeed)
+        write(resolve(opts.outSeed), `${JSON.stringify(built.seedDoc, null, 2)}\n`);
+    if (opts.outRubric)
+        write(resolve(opts.outRubric), `${JSON.stringify(built.rubric, null, 2)}\n`);
+    write(opts.outRecord ? resolve(opts.outRecord) : buildRecordPath(path), `${JSON.stringify(built.record, null, 2)}\n`);
+    if (opts.rewrite) {
+        const rewritten = rewriteRequesters(text, built);
+        if (rewritten !== text) {
+            writeFileSync(path, rewritten);
+            console.log(`rewrote ${path}: requesters are the seed's emails now`);
+        }
+        else
+            console.log(`${path}: every requester is already the seed's email`);
+    }
+    console.log(describeBuild(doc, built));
+    console.log(`  seed ${built.record.seed.name} (${built.record.seed.seed_hash.slice(0, 12)}…) · rubric ${built.record.rubric_hash.slice(0, 12)}…`);
+});
+tasks
+    .command("import <file>")
+    .description("one task per row of a help-desk export or a dataset — CSV, a JSON array, JSON lines — the format from the file, the columns from their names (the mapping is printed; --map overrides an entry), appended to the tasks file without duplicating ids. A requester the account does not know is skipped and counted; on an imported account, a real email becomes its pseudonym through the identity map beside the seed")
+    .option("--from <format>", "csv | json | jsonl (default: the file's extension, else its content)")
+    .option("--map <spec>", "field=column,… (requester=customer_email) to override the detection, with the fields id, requester, requester_name, subject, body, priority, tags, expected, created, trap_class; unmapped columns land in metadata")
+    .option("--requester <email>", "the requester for every row that has none")
+    .option("--tag <tag>", "keep rows whose tags column holds this tag")
+    .option("--since <date>", "keep rows whose created column is on or after this date")
+    .option("--limit <n>", "keep the first n rows after the filters")
+    .option("--into <file>", "the tasks file to append to (default: worlds/tasks.yaml when it exists; created when absent, with --seed)")
+    .option("--seed <name-or-file>", "the seed a new tasks file names (required when --into does not exist yet)")
+    .option("--mode <mode>", "the mode a new tasks file names: isolated | shift", "isolated")
+    .option("--identity-map <file>", "the identity map to resolve real emails through (default: <seed name>.identities.json beside the tasks file, when it exists)")
+    .option("--keep-unknown", "keep rows whose requester neither the account nor the map knows (validate will name them)", false)
+    .action(async (file, opts) => {
+    const { runTasksImport, TasksImportError } = await import("./tasks.js");
+    try {
+        const report = runTasksImport({
+            file: resolve(file),
+            from: opts.from,
+            map: opts.map,
+            requester: opts.requester,
+            tag: opts.tag,
+            since: opts.since,
+            limit: opts.limit === undefined ? undefined : Number(opts.limit),
+            into: opts.into === undefined ? undefined : resolve(opts.into),
+            intoShown: opts.into,
+            cwd: process.cwd(),
+            seed: opts.seed,
+            mode: opts.mode,
+            identityMap: opts.identityMap,
+            keepUnknown: opts.keepUnknown,
+        });
+        for (const line of report.lines)
+            console.log(line);
+    }
+    catch (err) {
+        if (err instanceof TasksImportError)
+            fail(err.message, 2);
+        throw err;
+    }
+});
+const world = program.command("world").description("create, inspect, reset, and destroy worlds");
+world
+    .command("create")
+    .description("create a world from a seed; prints world_id, base URL, and API key")
+    .requiredOption("--seed <name>", "library seed name (see `worlds seed ls`)")
+    .option("--json", "print the raw JSON response")
+    .action(async (opts) => {
+    const res = await admin("POST", "/admin/worlds", { seed: opts.seed });
+    if (opts.json)
+        return out(res);
+    console.log(`world_id    ${res.world_id}`);
+    console.log(`base_url    ${res.base_url}`);
+    console.log(`api_key     ${res.api_key}`);
+    console.log(`admin_token ${res.admin_token}`);
+    console.log(`seed_hash   ${res.seed_hash}`);
+    console.log(`clock       ${res.clock} (${new Date(res.clock * 1000).toISOString()})`);
+    console.log(`\nGive the agent the base URL + API key; keep the admin token for your harness (marks, diffs, reset).`);
+});
+world
+    .command("ls")
+    .description("list worlds on the server")
+    .action(async () => {
+    const res = await admin("GET", "/admin/worlds");
+    const unreadable = res.unreadable ?? [];
+    if (res.worlds.length === 0 && unreadable.length === 0)
+        return console.log("no worlds. create one: worlds world create --seed saas-billing-small");
+    for (const w of res.worlds) {
+        console.log(`${w.world_id}  seed=${w.seed_name}  clock=${new Date(w.clock * 1000).toISOString()} (${w.clock_mode})`);
+    }
+    for (const u of unreadable) {
+        const head = `world ${u.world_id} `;
+        const reason = u.reason.startsWith(head) ? u.reason.slice(head.length) : u.reason;
+        console.log(`${u.world_id}  unreadable — ${reason}`);
+    }
+});
+world
+    .command("export <world_id>")
+    .description("export a world's live state back into a seed file (fork a world into a new starting universe)")
+    .option("--name <name>", "seed name (kebab-case; default: <original seed>-export)")
+    .option("--out <file>", "output path (default: $WORLDS_SEEDS_DIR or ./seeds, <name>.json)")
+    .option("--json", "print the raw endpoint response instead of writing a file")
+    .action(async (id, opts) => {
+    const qs = opts.name ? `?name=${encodeURIComponent(opts.name)}` : "";
+    const res = await admin("GET", `/admin/worlds/${id}/export-seed${qs}`);
+    if (opts.json)
+        return out(res);
+    const { writeFileSync, mkdirSync } = await import("node:fs");
+    const { dirname } = await import("node:path");
+    const outFile = resolve(opts.out ?? join(resolveUserDir("seeds"), `${res.name}.json`));
+    mkdirSync(dirname(outFile), { recursive: true });
+    writeFileSync(outFile, `${JSON.stringify(res.seed_doc, null, 2)}\n`);
+    const c = res.counts;
+    console.log(`wrote ${outFile}`);
+    console.log(`  seed_hash ${res.seed_hash}`);
+    console.log(`  customers=${c.customers} products=${c.products} prices=${c.prices} invoices=${c.invoices} (charges attached: ${c.charges_attached}) subscriptions=${c.subscriptions}`);
+    for (const note of res.lossy.notes)
+        console.log(`  lossy: ${note}`);
+    console.log(`\nCreate a world from it: worlds world create --seed ${res.name}`);
+});
+world
+    .command("reset <world_id>")
+    .description("reset a world to its seed (keeps API keys)")
+    .action(async (id) => {
+    await admin("POST", `/admin/worlds/${id}/reset`, {});
+    console.log(`reset ${id} to its seed`);
+});
+world
+    .command("destroy <world_id>")
+    .description("destroy a world and delete its database")
+    .action(async (id) => {
+    await admin("DELETE", `/admin/worlds/${id}`);
+    console.log(`destroyed ${id}`);
+});
+const scenario = program.command("scenario").description("apply failure-injection scenarios to a world");
+scenario
+    .command("apply <world_id> <file-or-name>")
+    .description("apply a scenario from a YAML/JSON file, or a library scenario by name")
+    .action(async (id, source) => {
+    const body = existsSync(source) ? { scenario_doc: readDoc(source) } : { name: source };
+    const res = await admin("POST", `/admin/worlds/${id}/scenario`, body);
+    console.log(`applied scenario '${res.applied}' (${res.rules} rule${res.rules === 1 ? "" : "s"}) to ${id}`);
+});
+scenario
+    .command("clear <world_id>")
+    .description("clear the active scenario (and its counters)")
+    .action(async (id) => {
+    await admin("DELETE", `/admin/worlds/${id}/scenario`);
+    console.log(`cleared scenario on ${id}`);
+});
+scenario
+    .command("ls")
+    .description("list library scenarios on the server")
+    .action(async () => {
+    const res = await admin("GET", "/admin/scenarios");
+    if (res.scenarios.length === 0)
+        return console.log("no library scenarios found");
+    for (const s of res.scenarios)
+        console.log(`${s.name}  ${s.description ?? ""}`);
+});
+const clock = program.command("clock").description("inspect and advance a world's logical clock");
+clock
+    .command("advance <world_id> <duration>")
+    .description('advance logical time, e.g. "30d", "12h", "45m", "90s" — due renewals bill immediately')
+    .action(async (id, duration) => {
+    const res = await admin("POST", `/admin/worlds/${id}/clock/advance`, { duration });
+    console.log(`advanced ${id} by ${res.advanced_by}s → ${res.iso}`);
+    if (res.renewals_billed > 0)
+        console.log(`  ${res.renewals_billed} subscription renewal${res.renewals_billed === 1 ? "" : "s"} billed`);
+    if (res.renewals_pending > 0)
+        console.log(`  ${res.renewals_pending} subscription${res.renewals_pending === 1 ? "" : "s"} still due — advance again to continue`);
+});
+clock
+    .command("show <world_id>")
+    .description("show the world's current logical time")
+    .action(async (id) => {
+    const res = await admin("GET", `/admin/worlds/${id}/clock`);
+    console.log(`${res.iso} (unix ${res.clock}, ${res.clock_mode} mode)`);
+});
+if (process.argv.slice(2).includes("--commands-json")) {
+    out(commandAllowlist());
+    process.exit(0);
+}
+const misplaced = globalOptionAfterSubcommand(process.argv.slice(2), Object.fromEntries(program.commands.map((c) => [
+    c.name(),
+    [c, ...c.commands].flatMap((cmd) => cmd.options.map((o) => o.long)).filter((l) => l !== undefined),
+])));
+if (misplaced !== undefined)
+    fail(misplaced, 2);
+program.parseAsync(process.argv).catch((err) => {
+    fail(err instanceof Error ? err.message : String(err));
+});