promigence 0.1.0-beta.12

package/dist/surface.js

@@ -0,0 +1,1452 @@
+import { VERSION, DOCS_URL } from "./sdk/index.js";
+import { SANDBOX_STATES } from "./generated.js";
+export { VERSION, DOCS_URL };
+export const SCHEMA = "promigence.cli/v1";
+export const GUIDE_POINTER = "AI agents: run 'promigence agent-guide' (~1.4k tokens) before using this tool.";
+export const DESCRIPTION = "Promigence — verified, reproducible, forkable execution environments for agents.";
+export const GOLDEN_PATH = "promigence run --snapshot promigence/base --count 2 --cap 1 --json -- python3 -c 'print(6*7)'";
+export const WAIT_TIMEOUT_DEFAULT = "100s";
+export const REQUEST_TIMEOUT_DEFAULT = "30s";
+export const LIVE_COMMANDS = [
+    "login", "signup", "logout", "auth login", "keys list", "keys create", "keys revoke",
+    "org list", "org create", "org switch", "org members", "org invite", "org invites", "org uninvite", "org resend", "org role", "org remove", "org leave", "org join", "org audit", "org rename", "org delete",
+    "project list", "project create", "project rename", "project delete", "project cap", "project move",
+    "me", "billing card", "doctor", "ping", "init", "examples", "templates", "templates show", "agent-guide", "mcp",
+    "snapshot create", "snapshot status", "snapshot list", "snapshot inspect", "snapshot verify",
+    "snapshot export",
+    "fork", "exec", "exec output", "exec ps", "exec kill", "files put", "files get", "files ls",
+    "run", "run quote", "run report", "run status", "run cancel", "run kill", "run replay",
+    "run open", "run captures",
+    "sandbox kill", "sandbox shell", "sandbox ssh", "sandbox network", "port expose", "port list", "port revoke",
+    "secrets set", "bench burst",
+    "status", "billing usage", "billing portal", "snapshot delete", "snapshot builds", "snapshot alias",
+    "run list", "sandbox list", "sandbox info", "sandbox pause", "sandbox resume", "sandbox extend",
+    "sandbox probe", "files rm", "secrets list", "secrets delete",
+    "image resolve",
+    "sandbox snapshot",
+    "files search", "files mkdir", "files mv", "files cp", "files chmod", "exec stdin",
+    "sandbox autopause",
+    "agent start",
+    "referrals", "referrals apply",
+    "credits", "credits claim",
+    "runners github", "runners gitlab",
+    "pricing",
+    "github connect", "github status", "github disconnect", "github untrack", "repos",
+    "gitlab connect", "gitlab status", "gitlab disconnect", "gitlab untrack",
+    "billing history",
+];
+export const GUIDE_COMMON_ERRORS = [
+    "auth", "credit_unclaimed", "not_found", "not_verified", "cap_exceeded", "timeout", "nonzero_exit",
+];
+export const TIER_NOTE = "a sandbox has its snapshot's size (base: small); another size: snapshot create --image REF --tier T";
+export const BACKGROUND_NOTE = "background commands started with `exec --background` are ended; anything else you started keeps running when the sandbox resumes";
+const json = { name: "--json", summary: "force the JSON envelope" };
+const signInFlag = { name: "--no-browser", summary: "sign in headless (or PROMIGENCE_ID_TOKEN)" };
+const signInYes = { name: "--yes", summary: "sign in to PROMIGENCE_API_URL without the prompt" };
+const orgFlag = { name: "--org", arg: "ORG", summary: "another org than this key's" };
+const wait = { name: "--wait", summary: `bounded by --wait-timeout (default ${WAIT_TIMEOUT_DEFAULT})` };
+const waitTimeout = { name: "--wait-timeout", arg: "DUR", summary: `bound (${WAIT_TIMEOUT_DEFAULT}); expiry = exit 11, nothing killed` };
+const snapshot = { name: "--snapshot", arg: "H", summary: "snap_<id> | alias[@commit7] | ./env.promigence", required: true };
+const count = { name: "--count", arg: "N", summary: "number of sandboxes", required: true };
+const cap = { name: "--cap", arg: "USD", summary: "spend cap; refused above it (exit 5)", required: true };
+const idem = { name: "--idempotency-key", arg: "K", summary: "a key you pick (24 h)" };
+const verbose = { name: "--verbose", summary: "text: fork timings and totals too" };
+const stream = { name: "--stream", summary: "live output (auto on a TTY)" };
+const noStream = { name: "--no-stream", summary: "one envelope even on a TTY" };
+const fresh = { name: "--fresh", summary: "skip idempotent replay" };
+const gradeFlags = [
+    { name: "--grade", arg: "CMD", summary: "score the work in a clean env" },
+    { name: "--holdout", arg: "CMD", summary: "second test set; gap reported" },
+    { name: "--grade-score", arg: "M", summary: "exit|last_line_json|tap (exit)" },
+    { name: "--grade-timeout", arg: "DUR", summary: "per grader (10m)" },
+    { name: "--grade-output", summary: "keep last 16 KiB" },
+];
+const optimizeFor = { name: "--optimize-for", arg: "start|compute", summary: "default start" };
+const forkFlags = [
+    snapshot,
+    count,
+    { name: "--timeout", arg: "DUR", summary: "sandbox timeout (15m)" },
+    cap,
+    { name: "--allow-partial", summary: "start what the cap allows; the rest not_started" },
+    { name: "--secret", arg: "NAME", summary: "stored secret as an env var", repeatable: true },
+    { name: "--verify-each", summary: "verify forks before hand-over" },
+    { name: "--network", arg: "none|egress", summary: "default egress" },
+    { name: "--allow", arg: "HOST", summary: "outbound allow-list", repeatable: true },
+    optimizeFor,
+    { name: "--label", arg: "K=V", summary: "run label", repeatable: true },
+    waitTimeout,
+];
+export const COMMANDS = [
+    {
+        name: "login", group: "Setup", status: "released", signIn: "always",
+        helpRow: { key: "login", summary: "sign up or in · sign out · store a key" },
+        summary: "sign up or sign in (email; GitHub/Google where enabled); stores a new API key",
+        flags: [
+            { name: "--provider", arg: "NAME", summary: "a sign-in method the API offers (email; github|google where enabled): skip the chooser" },
+            { name: "--no-browser", summary: "headless: print the URL, paste the code back" },
+            { name: "--key-name", arg: "N", summary: "label for the key this login mints (default cli@<host>)" },
+            { name: "--api-url", arg: "URL", summary: "sign in to this API instead of the default (no prompt)" },
+            { name: "--yes", summary: "accept a non-default API from PROMIGENCE_API_URL without the prompt" },
+            { name: "--ref", arg: "CODE", summary: "a referral code (new accounts)" },
+            json,
+        ],
+        next: ["promigence me"],
+    },
+    {
+        name: "signup", group: "Setup", status: "released", signIn: "always",
+        helpRow: { key: "login", summary: "" },
+        summary: "create an account",
+        flags: [
+            { name: "--invite", arg: "CODE", summary: "the code (prefer the prompt; argv is visible)" },
+            { name: "--provider", arg: "NAME", summary: "a sign-in method the API offers (email; github|google where enabled): skip the chooser" },
+            { name: "--no-browser", summary: "headless: print the URL, paste the code back" },
+            { name: "--key-name", arg: "N", summary: "label for the key this sign-in mints (default cli@<host>)" },
+            { name: "--api-url", arg: "URL", summary: "sign up on this API instead of the default (no prompt)" },
+            { name: "--yes", summary: "accept a non-default API from PROMIGENCE_API_URL without the prompt" },
+            { name: "--ref", arg: "CODE", summary: "a referral code (new accounts)" },
+            json,
+        ],
+        next: ["promigence me"],
+    },
+    {
+        name: "logout", group: "Setup", status: "released",
+        helpRow: { key: "login", summary: "" },
+        summary: "forget this CLI's key (revoked when `promigence login` minted it)",
+        flags: [{ name: "--keep-key", summary: "only forget it locally; the key keeps working" }, json],
+        next: ["promigence login"],
+    },
+    {
+        name: "auth login", group: "Setup", status: "released",
+        helpRow: { key: "login", summary: "" },
+        summary: "store an API key (--from-env VAR | stdin; never on argv)",
+        flags: [
+            { name: "--from-env", arg: "VAR", summary: "read the key from an environment variable" },
+            { name: "--api-key", arg: "K", summary: "accepted but warns: key on argv" },
+        ],
+        next: ["promigence me"],
+    },
+    {
+        name: "keys list", group: "Setup", status: "released", signIn: "with --project",
+        helpRow: { key: "keys", summary: "org API keys; secret shown once" },
+        summary: "your org's API keys",
+        flags: [
+            { name: "--all", summary: "include revoked keys" },
+            { name: "--project", arg: "P", summary: "another project's" },
+            { name: "--org", arg: "ORG", summary: "with --project: in this org" },
+            signInFlag, signInYes, json,
+        ],
+        next: ["promigence keys create --name NAME"],
+    },
+    {
+        name: "keys create", group: "Setup", status: "released", signIn: "with --project or --service, or --org naming another org",
+        helpRow: { key: "keys", summary: "" },
+        summary: "mint a key (secret printed once)",
+        flags: [
+            { name: "--name", arg: "N", summary: "label, e.g. ci-prod" },
+            { name: "--org", arg: "ORG", summary: "in this org (default: this key's)" },
+            { name: "--project", arg: "P", summary: "in this project" },
+            { name: "--service", summary: "owners: outlives your membership (CI)" },
+            { name: "--access", arg: "A", summary: "full (default) | run: sandboxes, runs, builds; no secret/key/billing changes | read: reads all, files and output too; changes nothing" },
+            { name: "--expires", arg: "WHEN", summary: "1h, 30d, 1y, a date, or a UTC time (2027-01-31T12:00:00Z); any future time; default never" },
+            signInFlag, signInYes, json,
+        ],
+        next: ["promigence keys list"],
+    },
+    {
+        name: "keys revoke", group: "Setup", status: "released", signIn: "with --project",
+        helpRow: { key: "keys", summary: "" },
+        summary: "revoke a key", args: "KEY_ID",
+        flags: [
+            { name: "--project", arg: "P", summary: "a key in another project" },
+            { name: "--org", arg: "ORG", summary: "with --project: in this org" },
+            signInFlag, signInYes, json,
+        ],
+        next: ["promigence keys list"],
+    },
+    {
+        name: "org list", group: "Setup", status: "released", signIn: "with --all",
+        helpRow: { key: "org", summary: "orgs, members" },
+        summary: "your organizations (* = default)",
+        flags: [{ name: "--all", summary: "every one" }, signInFlag, signInYes, json],
+        next: ["promigence org switch <org>"],
+    },
+    {
+        name: "org create", group: "Setup", status: "released", signIn: "always",
+        helpRow: { key: "org", summary: "" },
+        summary: "create one you own (no trial credit)", args: "NAME", flags: [signInFlag, signInYes, json],
+        next: ["promigence org switch <org>"],
+    },
+    {
+        name: "org switch", group: "Setup", status: "released", signIn: "always",
+        helpRow: { key: "org", summary: "" },
+        summary: "sign in, make ORG the default, store a key for it", args: "ORG",
+        flags: [
+            { name: "--project", arg: "P", summary: "the new key's project" },
+            { name: "--keep-old-key", summary: "keep the replaced key working" },
+            signInFlag,
+            signInYes, json,
+        ],
+        next: ["promigence me"],
+    },
+    {
+        name: "org members", group: "Setup", status: "released", signIn: "with --org naming another org",
+        helpRow: { key: "org", summary: "" },
+        summary: "members and roles", flags: [orgFlag, signInFlag, signInYes, json],
+        next: ["promigence org invite <email>"],
+    },
+    {
+        name: "org invite", group: "Setup", status: "released", signIn: "always",
+        helpRow: { key: "org", summary: "" },
+        summary: "invite an email (owners)", args: "EMAIL",
+        flags: [{ name: "--role", arg: "R", summary: "owner|member (member)" }, orgFlag, signInFlag, signInYes, json],
+        next: ["promigence org invites"],
+    },
+    {
+        name: "org invites", group: "Setup", status: "released", signIn: "with --mine, or --org naming another org",
+        helpRow: { key: "org", summary: "" },
+        summary: "pending invites (14-day expiry)",
+        flags: [{ name: "--mine", summary: "sent to you" }, orgFlag, signInFlag, signInYes, json],
+        next: ["promigence org uninvite <invite_id>"],
+    },
+    {
+        name: "org uninvite", group: "Setup", status: "released", signIn: "always",
+        helpRow: { key: "org", summary: "" },
+        summary: "revoke an invite (owners)", args: "INVITE_ID", flags: [orgFlag, signInFlag, signInYes, json],
+        next: ["promigence org invites"],
+    },
+    {
+        name: "org resend", group: "Setup", status: "released", signIn: "always",
+        helpRow: { key: "org", summary: "" },
+        summary: "send an invite again (owners)", args: "INVITE_ID", flags: [orgFlag, signInFlag, signInYes, json],
+        next: ["promigence org invites"],
+    },
+    {
+        name: "org role", group: "Setup", status: "released", signIn: "always",
+        helpRow: { key: "org", summary: "" },
+        summary: "set owner|member (owners)", args: "USER_ID ROLE", flags: [orgFlag, signInFlag, signInYes, json],
+        next: ["promigence org members"],
+    },
+    {
+        name: "org remove", group: "Setup", status: "released", signIn: "always",
+        helpRow: { key: "org", summary: "" },
+        summary: "remove a member; their keys die (owners)", args: "USER_ID", flags: [orgFlag, signInFlag, signInYes, json],
+        next: ["promigence org members"],
+    },
+    {
+        name: "org leave", group: "Setup", status: "released", signIn: "for an org other than this key's",
+        helpRow: { key: "org", summary: "" },
+        summary: "leave an organization", args: "[ORG]", flags: [signInFlag, signInYes, json],
+        next: ["promigence org list"],
+    },
+    {
+        name: "org join", group: "Setup", status: "released", signIn: "always",
+        helpRow: { key: "org", summary: "" },
+        summary: "accept an invite sent to you", args: "INVITE_ID",
+        flags: [{ name: "--decline", summary: "decline it instead" }, signInFlag, signInYes, json],
+        next: ["promigence org switch <org>"],
+    },
+    {
+        name: "org audit", group: "Setup", status: "released", signIn: "with --sign-in (never on its own)",
+        helpRow: { key: "org", summary: "" },
+        summary: "who did what (owners; needs --sign-in)",
+        flags: [{ name: "--before", arg: "SEQ", summary: "older entries" }, { name: "--limit", arg: "N", summary: "how many (100)" }, orgFlag,
+            { name: "--sign-in", summary: "sign in in your browser: the log is read as you, never with a key" }, signInFlag, signInYes, json],
+        next: ["promigence org members"],
+    },
+    {
+        name: "org rename", group: "Setup", status: "released", signIn: "always",
+        helpRow: { key: "org", summary: "" },
+        summary: "rename it (owners)", args: "ORG NAME", flags: [signInFlag, signInYes, json],
+        next: ["promigence org list --all"],
+    },
+    {
+        name: "org delete", group: "Setup", status: "released", signIn: "always",
+        helpRow: { key: "org", summary: "" },
+        summary: "delete it; keys die (owners)", args: "ORG",
+        flags: [{ name: "--confirm", arg: "NAME", summary: "its name (required)" }, signInFlag, signInYes, json],
+        next: ["promigence org list --all"],
+    },
+    {
+        name: "project list", group: "Setup", status: "released", signIn: "with --org naming another org",
+        helpRow: { key: "project", summary: "projects: keys belong to one" },
+        summary: "projects and their spend this month", flags: [{ name: "--month", arg: "YYYY-MM", summary: "another month" }, orgFlag, signInFlag, signInYes, json],
+        next: ["promigence project create <name>"],
+    },
+    {
+        name: "project create", group: "Setup", status: "released", signIn: "with --org naming another org",
+        helpRow: { key: "project", summary: "" },
+        summary: "create a project", args: "NAME", flags: [orgFlag, signInFlag, signInYes, json],
+        next: ["promigence keys create --project <name>"],
+    },
+    {
+        name: "project rename", group: "Setup", status: "released", signIn: "with --org naming another org",
+        helpRow: { key: "project", summary: "" },
+        summary: "rename (not `default`)", args: "PROJECT NAME", flags: [orgFlag, signInFlag, signInYes, json],
+        next: ["promigence project list"],
+    },
+    {
+        name: "project delete", group: "Setup", status: "released", signIn: "always",
+        helpRow: { key: "project", summary: "" },
+        summary: "delete an empty one (owners)", args: "PROJECT", flags: [orgFlag, signInFlag, signInYes, json],
+        next: ["promigence project list"],
+    },
+    {
+        name: "project cap", group: "Setup", status: "released", signIn: "always",
+        helpRow: { key: "project", summary: "" },
+        summary: "monthly USD cap, or off (owners)", args: "PROJECT USD|off", flags: [orgFlag, signInFlag, signInYes, json],
+        next: ["promigence project list"],
+    },
+    {
+        name: "project move", group: "Setup", status: "released", signIn: "always",
+        helpRow: { key: "project", summary: "" },
+        summary: "to another org; keys die (owners)", args: "PROJECT",
+        flags: [{ name: "--to", arg: "ORG", summary: "yours, with a card" }, orgFlag, signInFlag, signInYes, json],
+        next: ["promigence keys create --org <to> --project <name>"],
+    },
+    {
+        name: "me", group: "Setup", status: "released",
+        helpRow: { key: "me", summary: "org limits, spend · live prices" },
+        summary: "plan, concurrency in use, trial credit, spend, limits",
+        flags: [json],
+        next: ["promigence billing usage"],
+    },
+    {
+        name: "billing card", group: "Setup", status: "released",
+        helpRow: { key: "billing", summary: "add a card · spend · the portal" },
+        summary: "add a card: prints a checkout URL (trial credits kept)",
+        flags: [json],
+        next: ["promigence me"],
+    },
+    {
+        name: "doctor", group: "Setup", status: "released",
+        helpRow: { key: "doctor", summary: "check client, auth, API · services, concurrency" },
+        summary: "check client, auth and API",
+        flags: [json],
+        next: ["promigence examples"],
+    },
+    {
+        name: "ping", group: "Setup", status: "released",
+        helpRow: { key: "doctor", summary: "" },
+        summary: "your distance to our servers",
+        flags: [json],
+        next: ["promigence doctor"],
+    },
+    {
+        name: "init", group: "Setup", status: "released",
+        summary: "write promigence.toml",
+        flags: [
+            { name: "--repo", arg: "U", summary: "git URL (default: the `origin` remote)" },
+            { name: "--commit", arg: "SHA", summary: "commit to pin (default: HEAD)" },
+            { name: "--setup", arg: "CMD", summary: "override the inferred setup step", repeatable: true },
+            { name: "--verify", arg: "CMD", summary: "override the inferred verify command" },
+            { name: "--tier", arg: "xsmall|small|medium|large-16|large|xlarge|2xlarge", summary: "default medium" },
+            { name: "--force", summary: "overwrite an existing promigence.toml" },
+            { name: "--print", summary: "write nothing; print what it would write" },
+            json,
+        ],
+        next: ["promigence snapshot create --image IMAGE --setup 'git clone …' --verify CMD --wait"],
+    },
+    {
+        name: "examples", group: "Setup", status: "released",
+        helpRow: { key: "examples", summary: "no-build forks (no auth)" },
+        summary: "what forks with no build (no auth)",
+        flags: [
+            { name: "--limit", arg: "N", summary: "how many to list (default 20)" },
+            { name: "--bundle", summary: "write each public snapshot as a .promigence file (none yet)" },
+            json,
+        ],
+        next: [GOLDEN_PATH],
+    },
+    {
+        name: "templates", group: "Setup", status: "released",
+        helpRow: { key: "examples", summary: "" },
+        summary: "the templates: ready-made starting points to fork (no auth)",
+        flags: [json],
+        next: ["promigence templates show <name>"],
+    },
+    {
+        name: "templates show", group: "Setup", status: "released",
+        helpRow: { key: "examples", summary: "" },
+        summary: "one template: everything it has installed, and its versions (no auth)", args: "NAME",
+        flags: [{ name: "--packages", summary: "list every installed package, not only the count" }, json],
+        next: ["promigence fork --snapshot <name> --count 1 --cap 1"],
+    },
+    {
+        name: "agent-guide", group: "Setup", status: "released",
+        helpRow: { key: "agent-guide", summary: "~1.4k-token guide for agents · MCP server on stdio" },
+        summary: "~1.4k-token guide for agents (--section commands|errors|cost)",
+        flags: [
+            { name: "--section", arg: "commands|errors|cost", summary: "one section instead of the core" },
+            { name: "--code", arg: "C", summary: "the entry for one error code" },
+            { name: "--format", arg: "md|json", summary: "default md" },
+            { name: "--install", summary: "write the fence into AGENTS.md/CLAUDE.md, .claude/skills, .cursor/rules" },
+            { name: "--create", summary: "with --install: create AGENTS.md if neither file exists" },
+            { name: "--check", summary: "report what --install would change; write nothing; exit 13 if it would" },
+        ],
+        next: [GOLDEN_PATH],
+    },
+    {
+        name: "mcp", group: "Setup", status: "released",
+        helpRow: { key: "agent-guide", summary: "" },
+        summary: "MCP server on stdio: `claude mcp add promigence -- promigence mcp` (Windows: `-- cmd /c promigence mcp`)",
+        flags: [
+            { name: "--read-only", summary: "offer only the tools that read (not a fence around data: they still return what a sandbox holds)" },
+            { name: "--root", arg: "PATH", summary: "keep the file tools to this directory of the sandbox (sandbox_exec is not fenced)" },
+            { name: "--allow-tools", arg: "A,B", summary: "offer only these tools (comma-separated names)" },
+            { name: "--cap", arg: "USD", summary: "spend cap for every sandbox and batch it starts (else PROMIGENCE_SPEND_CAP, else the org default)" },
+            { name: "--keep", summary: "leave the sandboxes this session created running at shutdown" },
+        ],
+        noGuidePointer: true,
+        next: [],
+    },
+    {
+        name: "snapshot create", group: "Snapshots", status: "released",
+        summary: "build + verify a snapshot (--image | --dockerfile | --devcontainer)",
+        flags: [
+            { name: "--repo", arg: "R", summary: "owner/name (connected GitHub) or a git URL" },
+            { name: "--ref", arg: "R", summary: "with owner/name: branch|tag|sha" },
+            { name: "--commit", arg: "SHA", summary: "40-char sha, never a branch" },
+            { name: "--also-repo", arg: "URL@SHA[:PATH]", summary: "another pinned repo, before setup", repeatable: true, hidden: true },
+            { name: "--image", arg: "REF", summary: "a tag (we pin it) or REF@sha256:D" },
+            { name: "--dockerfile", arg: "PATH", summary: "a Dockerfile we build" },
+            { name: "--context", arg: "DIR|URL@SHA", summary: "default: the Dockerfile's dir" },
+            { name: "--devcontainer", arg: "PATH", summary: "a devcontainer.json (default: the one here)" },
+            { name: "--no-devcontainer", summary: "ignore the repo's devcontainer.json" },
+            { name: "--devcontainer-local-env", summary: "let its ${localEnv:VAR} read your environment (baked in)", hidden: true },
+            { name: "--dir", arg: "PATH", summary: "upload the files git tracks there" },
+            { name: "--from", arg: "SNAP", summary: "owner/name|--dir: start from (base)" },
+            { name: "--track", summary: "owner/name: rebuild on every push" },
+            { name: "--include-untracked", summary: "--dir: also untracked files git does not ignore", hidden: true },
+            { name: "--allow-secrets", summary: "--dir/--dockerfile: also send files that look like credentials (a best-effort check by file name); each is named, and asked about on a terminal unless --yes", hidden: true },
+            { name: "--list-files", summary: "--dir/--dockerfile: print every file that would be uploaded, and send nothing", hidden: true },
+            { name: "--yes", summary: "--allow-secrets/--devcontainer-local-env: send without the question on a terminal", hidden: true },
+            { name: "--keep-sandbox", summary: "--dir: keep the sandbox after (debugging)", hidden: true },
+            { name: "--timeout", arg: "DUR", summary: "--dir: the sandbox's life (30m)", hidden: true },
+            { name: "--setup", arg: "CMD", summary: "setup step (ordered)", repeatable: true },
+            { name: "--verify", arg: "CMD", summary: "a command that must exit 0 or nothing is stored (it checks the command, not any one file)" },
+            { name: "--start", arg: "CMD", summary: "a command started at build time and already running in every sandbox made from the snapshot" },
+            { name: "--tier", arg: "xsmall|small|medium|large-16|large|xlarge|2xlarge", summary: "build and fork size" },
+            { name: "--alias", arg: "N", summary: "unique per org" },
+            ...gradeFlags.map((f) => (f.name === "--grade" ? f : { ...f, hidden: true })),
+            { ...fresh, summary: "no 10-min replay (identical inputs still reuse their snapshot)" },
+            wait, waitTimeout, idem, json,
+        ],
+        autoIdempotencyKey: true,
+        next: ["promigence snapshot status <build_id> --wait"],
+    },
+    {
+        name: "snapshot status", group: "Snapshots", status: "released",
+        helpRow: { key: "snapshot", summary: "poll (--wait) · re-verify · .promigence export" },
+        summary: "poll a build by build_id", args: "<build_id>",
+        flags: [wait, waitTimeout, { name: "--log", arg: "N", summary: "print the last N lines of the build log" }, json],
+        next: ["promigence run quote --snapshot <snapshot_id> --count N"],
+    },
+    {
+        name: "snapshot list", group: "Snapshots", status: "released",
+        helpRow: { key: "snapshot", summary: "" }, summary: "list snapshots in your org", flags: [json],
+        next: ["promigence snapshot inspect <hash>"],
+    },
+    {
+        name: "snapshot inspect", group: "Snapshots", status: "released",
+        helpRow: { key: "snapshot", summary: "" }, summary: "show a snapshot's record", args: "<hash>", flags: [json],
+        next: ["promigence run quote --snapshot <hash> --count N"],
+    },
+    {
+        name: "snapshot verify", group: "Snapshots", status: "released",
+        helpRow: { key: "snapshot", summary: "" }, summary: "re-verify a snapshot in a fork", args: "<hash>", flags: [json],
+        next: ["promigence snapshot inspect <hash>"],
+    },
+    {
+        name: "snapshot export", group: "Snapshots", status: "released",
+        helpRow: { key: "snapshot", summary: "" },
+        summary: "write a portable .promigence bundle (commit it, cite it, mail it)", args: "<hash>",
+        flags: [
+            { name: "--out", arg: "FILE", summary: "default <alias>.promigence; `-` or a pipe writes stdout" },
+            { name: "--citation", summary: "accepted; every export is the same form", hidden: true },
+            { name: "--full", summary: "accepted; every export is the same form", hidden: true },
+            { name: "--no-layers", summary: "old name of --citation", hidden: true },
+            { name: "--layers", summary: "old name of --full", hidden: true },
+            json,
+        ],
+        next: ["promigence run --snapshot ./<alias>.promigence --count N --cap USD -- CMD"],
+    },
+    {
+        name: "image resolve", group: "Snapshots", status: "released",
+        helpRow: { key: "image", summary: "pin a tag to a digest, server-side (no local docker)" },
+        summary: "resolve REF (python:3.12) to REF@sha256:… without a local container runtime",
+        args: "REF",
+        flags: [
+            { name: "--registry-secret", arg: "NAME", summary: "stored secret holding user:password for a private registry" },
+            json,
+        ],
+        next: ["promigence snapshot create --image <pinned> --tier small"],
+    },
+    {
+        name: "github connect", group: "Snapshots", status: "released",
+        helpRow: { key: "github", summary: "private repos for --repo" },
+        summary: "connect GitHub in the console; waits for it",
+        flags: [
+            { name: "--no-open", summary: "print the page, open nothing" },
+            { name: "--no-wait", summary: "print the page and return" },
+            { name: "--wait-timeout", arg: "DUR", summary: "for the connection (10m); expiry = exit 11" },
+            json,
+        ],
+        next: ["promigence repos"],
+    },
+    {
+        name: "github status", group: "Snapshots", status: "released",
+        helpRow: { key: "github", summary: "" },
+        summary: "connected accounts, pending installs, tracked branches",
+        flags: [json],
+        next: ["promigence repos"],
+    },
+    {
+        name: "github disconnect", group: "Snapshots", status: "released",
+        helpRow: { key: "github", summary: "" },
+        summary: "stop building from a GitHub account", args: "<installation_id|account>",
+        flags: [json],
+        next: ["promigence github status"],
+    },
+    {
+        name: "github untrack", group: "Snapshots", status: "released",
+        helpRow: { key: "github", summary: "" },
+        summary: "stop rebuilding on push (the snapshot stays)", args: "<track_id|alias>",
+        flags: [json],
+        next: ["promigence github status"],
+    },
+    {
+        name: "repos", group: "Snapshots", status: "released",
+        helpRow: { key: "github", summary: "" },
+        summary: "repos your GitHub/GitLab connection reads (for --repo)",
+        flags: [
+            { name: "--page", arg: "N", summary: "page (100 a page)" },
+            { name: "--provider", arg: "NAME", summary: "github (default) | gitlab" },
+            { name: "--connection", arg: "ID", summary: "gitlab: one connection (glc_…)" },
+            json,
+        ],
+        next: ["promigence snapshot create --repo <owner/name> --wait"],
+    },
+    {
+        name: "gitlab connect", group: "Snapshots", status: "released",
+        helpRow: { key: "github", summary: "", via: "gitlab" },
+        summary: "connect GitLab read-only in the console; waits",
+        flags: [
+            { name: "--no-open", summary: "print the page, open nothing" },
+            { name: "--no-wait", summary: "print the page and return" },
+            { name: "--wait-timeout", arg: "DUR", summary: "for the connection (10m); expiry = exit 11" },
+            json,
+        ],
+        next: ["promigence repos --provider gitlab"],
+    },
+    {
+        name: "gitlab status", group: "Snapshots", status: "released",
+        helpRow: { key: "github", summary: "", via: "gitlab" },
+        summary: "GitLab users, pending confirmations, tracks",
+        flags: [json],
+        next: ["promigence repos --provider gitlab"],
+    },
+    {
+        name: "gitlab disconnect", group: "Snapshots", status: "released",
+        helpRow: { key: "github", summary: "", via: "gitlab" },
+        summary: "revoke a GitLab connection", args: "<connection_id|username>",
+        flags: [json],
+        next: ["promigence gitlab status"],
+    },
+    {
+        name: "gitlab untrack", group: "Snapshots", status: "released",
+        helpRow: { key: "github", summary: "", via: "gitlab" },
+        summary: "stop rebuilding on commits (snapshot stays)", args: "<track_id|alias>",
+        flags: [json],
+        next: ["promigence gitlab status"],
+    },
+    {
+        name: "run", group: "Runs", status: "released",
+        summary: "fork N, exec CMD in each, print the validity report",
+        args: "-- CMD",
+        flags: [
+            { ...snapshot, required: false, summary: "id | alias[@commit7] | ./env.promigence (default promigence/base)" },
+            { name: "--image", arg: "REF", summary: "not with --snapshot: a tag or REF@sha256:D" },
+            ...forkFlags.slice(1).map((f) => (f.name === "--count"
+                ? { ...f, summary: "sandboxes; each has PROMIGENCE_INDEX (0..N-1) and PROMIGENCE_SEED" }
+                : f)),
+            ...gradeFlags.map((f) => (f.name === "--grade-score"
+                ? { ...f, summary: "exit|last_line_json|tap (exit); JSON: {\"score\":0.8,\"pass\":true}" }
+                : f)),
+            { name: "--fail-on", arg: "task|env|none", summary: "what exits non-zero (task)" },
+            { name: "--keep", summary: "keep sandboxes after CMD" },
+            stream, noStream,
+            { name: "--max-output", arg: "BYTES", summary: "output cap (64k)" },
+            idem,
+            verbose,
+        ],
+        next: ["promigence run report <run_id>", "promigence run status <run_id> --wait"],
+    },
+    {
+        name: "run quote", group: "Runs", status: "released",
+        summary: "price a run before launch",
+        flags: [
+            { ...snapshot, required: false, summary: "id | alias[@commit7] | ./env.promigence (default promigence/base)" }, count,
+            { name: "--timeout", arg: "DUR", summary: "sandbox timeout (15m)" },
+            { name: "--tier", arg: "T", summary: "must match the snapshot's assigned tier" },
+            { name: "--cap", arg: "USD", summary: "price it against this cap; spends nothing" },
+            json,
+        ],
+        next: ["promigence fork --snapshot H --count N --cap USD"],
+    },
+    {
+        name: "run report", group: "Runs", status: "released",
+        summary: "validity report: env vs task failures", args: "ID",
+        flags: [
+            json,
+            { name: "--sandboxes", arg: "all|failed", summary: "default: summary + non-completed sandboxes" },
+            { name: "--sandbox", arg: "SID", summary: "one sandbox" },
+            { name: "--repro", summary: "print the repro command for --sandbox" },
+            { name: "--limit", arg: "N", summary: "text rows before '… N more' (50; 0 = all). --json is never paged" },
+        ],
+        next: ["promigence run replay <run_id> --sandbox <sid>"],
+    },
+    {
+        name: "run status", group: "Runs", status: "released",
+        helpRow: { key: "run", summary: "list · poll (--wait) · stop queued · kill all · replay · open a failure" },
+        summary: "poll a run", args: "ID", flags: [wait, waitTimeout, json],
+        next: ["promigence run report <run_id>"],
+    },
+    {
+        name: "run cancel", group: "Runs", status: "released",
+        helpRow: { key: "run", summary: "" }, summary: "stop queued starts", args: "ID", flags: [json],
+        next: ["promigence run report <run_id>"],
+    },
+    {
+        name: "run kill", group: "Runs", status: "released",
+        helpRow: { key: "run", summary: "" }, summary: "kill every sandbox of a run", args: "ID", flags: [json],
+        next: ["promigence run report <run_id>"],
+    },
+    {
+        name: "run replay", group: "Runs", status: "released",
+        helpRow: { key: "run", summary: "" }, summary: "replay sandboxes (client-triggered, never automatic)", args: "ID",
+        flags: [
+            { name: "--sandbox", arg: "SID", summary: "only these sandboxes", repeatable: true },
+            {
+                name: "--env", arg: "K=V", repeatable: true,
+                summary: "a value for each variable the run's command was started with (runs keep names, never values)",
+            },
+            json,
+        ],
+        next: ["promigence run report <run_id>"],
+    },
+    {
+        name: "run open", group: "Runs", status: "released",
+        helpRow: { key: "run", summary: "" },
+        summary: "reopen a failed sandbox as a live one, at the moment it failed", args: "ID",
+        flags: [
+            { name: "--sandbox", arg: "SID", summary: "which failure (default: the only one)" },
+            { name: "--cap", arg: "USD", summary: "what the reopened sandbox may spend" },
+            { name: "--timeout", arg: "DUR", summary: "how long it may run (default: the run's)" },
+            json,
+        ],
+        next: ["promigence exec --sandbox <sid> -- ls -la"],
+    },
+    {
+        name: "run captures", group: "Runs", status: "released",
+        helpRow: { key: "run", summary: "" },
+        summary: "what of this run is preserved, and when it expires", args: "ID",
+        flags: [{ name: "--delete", arg: "SNAPSHOT_ID", summary: "destroy one now, before it expires" }, json],
+        next: ["promigence run open <run_id>"],
+    },
+    {
+        name: "fork", group: "Sandboxes", status: "released",
+        summary: "fork N sandboxes from a snapshot (--count --cap)",
+        note: TIER_NOTE,
+        flags: [{ ...snapshot, required: false, summary: "snap_<id> | alias[@commit7] | ./env.promigence (default promigence/base)" }, ...forkFlags.slice(1), { name: "--no-wait", summary: "return after POST /runs" }, fresh, stream, noStream, idem, verbose, json],
+        autoIdempotencyKey: true,
+        next: ["promigence exec --run <run_id> --all -- CMD"],
+    },
+    {
+        name: "exec", group: "Sandboxes", status: "released",
+        summary: "run CMD in a sandbox (--sandbox SID) or a run (--run ID --all)",
+        args: "-- CMD",
+        flags: [
+            { name: "--sandbox", arg: "SID", summary: "stdout is the child's own bytes (JSON only with --json or PROMIGENCE_OUTPUT=json); its exit code passes through; not found 127; Promigence's own failures 125" },
+            { name: "--run", arg: "ID", summary: "with --all: every ready sandbox; queued reported skipped unless --wait" },
+            { name: "--all", summary: "0 if every child exits 0, else 4" },
+            { name: "--no-passthrough", summary: "return 0–12 instead of the child's code" },
+            { name: "--background", summary: "with --sandbox: start it, print its exec_id, return now" },
+            { name: "--stdin", summary: "with --background: keep stdin open for `promigence exec stdin`" },
+            { name: "--secret", arg: "NAME", summary: "stored secret as an env var", repeatable: true },
+            stream, noStream,
+            { name: "--max-output", arg: "BYTES", summary: "per stream (64k; 32m, the most, into a pipe or file); past it the rest is cut, and text exits 12" },
+            { name: "--timeout", arg: "DUR", summary: "child timeout (default 15m)" },
+            wait, waitTimeout, idem,
+        ],
+        noGuidePointer: true,
+        passthroughExit: 125,
+        next: ["promigence exec output <x_id> --sandbox <sid> --follow", "promigence run report <run_id>"],
+    },
+    {
+        name: "exec output", group: "Sandboxes", status: "released",
+        helpRow: { key: "exec", summary: "output · background: list · write stdin · kill" },
+        summary: "an exec's output by id (background x_…: --follow)", args: "EXEC_ID",
+        flags: [
+            { name: "--range", arg: "A-B", summary: "byte range, 0-based and B inclusive; `A-` runs to the end" },
+            { name: "--sandbox", arg: "SID", summary: "resolve the exec inside this sandbox (required for x_…)" },
+            { name: "--run", arg: "ID", summary: "resolve the exec inside this run" },
+            { name: "--stderr", summary: "the child's stderr instead of its stdout" },
+            { name: "--follow", summary: "background exec: stream until it exits, pass its code through" },
+            json,
+        ],
+        noGuidePointer: true,
+        next: ["promigence run report <run_id>"],
+    },
+    {
+        name: "exec ps", group: "Sandboxes", status: "released",
+        helpRow: { key: "exec", summary: "" },
+        summary: "list a sandbox's background execs", flags: [{ name: "--sandbox", arg: "SID", summary: "the sandbox", required: true }, json],
+        next: ["promigence exec output <exec_id> --sandbox <sid> --follow"],
+    },
+    {
+        name: "exec stdin", group: "Sandboxes", status: "released",
+        helpRow: { key: "exec", summary: "" },
+        summary: "write to a background exec's stdin (needs `exec --background --stdin`)", args: "EXEC_ID",
+        flags: [
+            { name: "--sandbox", arg: "SID", summary: "the sandbox it runs in", required: true },
+            { name: "--data", arg: "TEXT", summary: "write this (default: read stdin to EOF)" },
+            { name: "--file", arg: "P", summary: "write this local file's bytes" },
+            { name: "--eof", summary: "close stdin after writing (implied when reading a pipe)" },
+            { name: "--no-eof", summary: "keep it open after piped input" },
+            json,
+        ],
+        next: ["promigence exec output <exec_id> --sandbox <sid> --follow"],
+    },
+    {
+        name: "exec kill", group: "Sandboxes", status: "released",
+        helpRow: { key: "exec", summary: "" },
+        summary: "signal a background exec (default SIGKILL)", args: "EXEC_ID",
+        flags: [
+            { name: "--sandbox", arg: "SID", summary: "the sandbox it runs in", required: true },
+            { name: "--signal", arg: "SIG", summary: "TERM | INT | HUP | KILL | a number" },
+            { name: "--forget", summary: "then drop its handle and buffered output" },
+            json,
+        ],
+        next: ["promigence exec ps --sandbox <sid>"],
+    },
+    {
+        name: "files put", group: "Sandboxes", status: "released",
+        helpRow: { key: "files", summary: "in / out, or inside" },
+        summary: "copy a local file into a sandbox (--recursive: a directory)", args: "SRC DST",
+        flags: [
+            { name: "--sandbox", arg: "SID", summary: "target sandbox", required: true },
+            { name: "--recursive", summary: "SRC is a local directory; DST is a directory in the sandbox" },
+            json,
+        ],
+        next: ["promigence exec --sandbox <sid> -- CMD"],
+    },
+    {
+        name: "files get", group: "Sandboxes", status: "released",
+        helpRow: { key: "files", summary: "" },
+        summary: "copy a file out of a sandbox (--recursive: a directory)", args: "SRC DST",
+        flags: [
+            { name: "--sandbox", arg: "SID", summary: "source sandbox", required: true },
+            { name: "--recursive", summary: "SRC is a directory in the sandbox; DST a local directory" },
+            { name: "--exclude", arg: "GLOB", summary: "with --recursive: leave these out, e.g. .git", repeatable: true },
+            { name: "--keep-links", summary: "with --recursive: keep links leaving DST" },
+            json,
+        ],
+        next: ["promigence files ls <dir> --sandbox <sid>"],
+    },
+    {
+        name: "files ls", group: "Sandboxes", status: "released",
+        helpRow: { key: "files", summary: "" },
+        summary: "list a directory in a sandbox (lstat per entry)", args: "[PATH]",
+        flags: [
+            { name: "--sandbox", arg: "SID", summary: "the sandbox", required: true },
+            { name: "--recursive", summary: "walk below PATH, not one level" },
+            { name: "--depth", arg: "N", summary: "with --recursive: how many levels" },
+            { name: "--limit", arg: "N", summary: "stop after N entries (truncated is reported)" },
+            { name: "--no-hidden", summary: "drop dotfiles (they are listed by default)" },
+            json,
+        ],
+        next: ["promigence files get SRC DST --sandbox <sid>"],
+    },
+    {
+        name: "files search", group: "Sandboxes", status: "released",
+        helpRow: { key: "files", summary: "" },
+        summary: "find files by name glob and/or text inside them", args: "[PATH]",
+        flags: [
+            { name: "--sandbox", arg: "SID", summary: "the sandbox", required: true },
+            { name: "--name", arg: "GLOB", summary: "name glob, e.g. '*.py'" },
+            { name: "--contains", arg: "TEXT", summary: "literal text to find inside matching files" },
+            { name: "--ignore-case", summary: "case-insensitive --contains" },
+            { name: "--limit", arg: "N", summary: "stop after N hits (truncated is reported)" },
+            { name: "--no-hidden", summary: "skip dotfiles and dot-directories" },
+            json,
+        ],
+        next: ["promigence files get SRC DST --sandbox <sid>"],
+    },
+    {
+        name: "files mkdir", group: "Sandboxes", status: "released",
+        helpRow: { key: "files", summary: "" },
+        summary: "create a directory in a sandbox", args: "PATH",
+        flags: [
+            { name: "--sandbox", arg: "SID", summary: "the sandbox", required: true },
+            { name: "--parents", summary: "mkdir -p: intermediate directories, and no error if it exists" },
+            { name: "--mode", arg: "OCTAL", summary: "e.g. 755" },
+            json,
+        ],
+        next: ["promigence files ls <path> --sandbox <sid>"],
+    },
+    {
+        name: "files mv", group: "Sandboxes", status: "released",
+        helpRow: { key: "files", summary: "" },
+        summary: "move or rename a path inside a sandbox", args: "SRC DST",
+        flags: [
+            { name: "--sandbox", arg: "SID", summary: "the sandbox", required: true },
+            { name: "--overwrite", summary: "replace DST if it is already there" },
+            json,
+        ],
+        next: ["promigence files ls <path> --sandbox <sid>"],
+    },
+    {
+        name: "files cp", group: "Sandboxes", status: "released",
+        helpRow: { key: "files", summary: "" },
+        summary: "copy a path inside a sandbox (both ends are in the sandbox)", args: "SRC DST",
+        flags: [
+            { name: "--sandbox", arg: "SID", summary: "the sandbox", required: true },
+            { name: "--recursive", summary: "a directory and everything under it" },
+            { name: "--overwrite", summary: "replace DST if it is already there" },
+            json,
+        ],
+        next: ["promigence files ls <path> --sandbox <sid>"],
+    },
+    {
+        name: "files chmod", group: "Sandboxes", status: "released",
+        helpRow: { key: "files", summary: "" },
+        summary: "change mode and/or owner of a path in a sandbox", args: "PATH",
+        flags: [
+            { name: "--sandbox", arg: "SID", summary: "the sandbox", required: true },
+            { name: "--mode", arg: "OCTAL", summary: "e.g. 755" },
+            { name: "--uid", arg: "N", summary: "owner" },
+            { name: "--gid", arg: "N", summary: "group" },
+            { name: "--recursive", summary: "the directory and everything under it" },
+            json,
+        ],
+        next: ["promigence files ls <path> --sandbox <sid>"],
+    },
+    {
+        name: "agent start", group: "Sandboxes", status: "released",
+        ownExtraWords: true,
+        summary: "a coding agent in a new sandbox", args: "claude|codex|opencode",
+        flags: [
+            { name: "--key-secret", arg: "NAME[=VAR]", summary: "stored secret with the model key (default ANTHROPIC_API_KEY; codex: OPENAI_API_KEY)" },
+            { name: "--key-from-env", arg: "VAR", summary: "store the key from this variable first (never argv)" },
+            { name: "--snapshot", arg: "H", summary: "start from this snapshot (default promigence/base; the agent is installed if missing)" },
+            { name: "--image", arg: "REF@sha256:D", summary: "instead of --snapshot" },
+            { name: "--repo", arg: "URL", summary: "clone this public repository and start the agent in it" },
+            { name: "--prompt", arg: "TEXT", summary: "work on this task headless, in the background" },
+            { name: "--model", arg: "M", summary: "the agent's model (opencode: provider/model, e.g. xai/grok-4-0709)" },
+            { name: "--attach", summary: "open the agent's terminal now" },
+            { name: "--timeout", arg: "DUR", summary: "sandbox lifetime (default 1h)" },
+            { name: "--cap", arg: "USD", summary: "spend cap (else PROMIGENCE_SPEND_CAP, else the org default)" },
+            waitTimeout, json,
+        ],
+        next: ["promigence sandbox shell <sid> --secret ANTHROPIC_API_KEY -- claude", "promigence sandbox kill <sid>"],
+    },
+    {
+        name: "sandbox kill", group: "Sandboxes", status: "released",
+        helpRow: { key: "sandbox", summary: "list · kill · pause/resume · interactive terminal · what it may reach" },
+        summary: "kill one sandbox", args: "SID", flags: [json],
+        next: ["promigence run report <run_id>"],
+    },
+    {
+        name: "sandbox network", group: "Sandboxes", status: "released",
+        helpRow: { key: "sandbox", summary: "" },
+        summary: "what it may reach; with an allow-list, hosts it was refused", args: "SID",
+        flags: [
+            { name: "--cut", summary: "cut this sandbox's egress now; it cannot be turned back on" },
+            json,
+        ],
+        next: ["promigence run report <run_id>"],
+    },
+    {
+        name: "sandbox shell", group: "Sandboxes", status: "released",
+        helpRow: { key: "sandbox", summary: "" },
+        summary: "interactive terminal (raw TTY, follows window size)", args: "SID [-- CMD]",
+        flags: [
+            { name: "--cmd", arg: "CMD", summary: "run this instead of the login shell (sh -c)" },
+            { name: "--cwd", arg: "DIR", summary: "start in this directory" },
+            { name: "--env", arg: "K=V", summary: "environment variable", repeatable: true },
+            {
+                name: "--secret",
+                arg: "NAME[=VAR]",
+                summary: "stored secret in the terminal's environment; NAME=VAR binds it to VAR",
+                repeatable: true,
+            },
+        ],
+        noGuidePointer: true,
+        passthroughExit: 125,
+        next: ["promigence sandbox kill <sid>"],
+    },
+    {
+        name: "sandbox ssh", group: "Sandboxes", status: "released",
+        helpRow: { key: "sandbox", summary: "" },
+        summary: "log in over SSH (scp, sftp and -L work too)", args: "SID [-- CMD]",
+        flags: [
+            { name: "--config", summary: "print an ssh config block instead of logging in" },
+            { name: "--print", summary: "print the connection details instead of logging in" },
+            { name: "--key", arg: "PATH", summary: "use this key pair instead of making one" },
+            { name: "--ttl", arg: "S", summary: "how long the access lasts (default 3600, max 3600)" },
+            { name: "--idle", arg: "S", summary: "close a session after this long with no activity" },
+            { name: "--proxy", summary: "carry one connection on stdin/stdout (used by ssh itself)" },
+            { name: "--list", summary: "the keys that have access, then exit" },
+            { name: "--revoke", arg: "KEY_ID", summary: "end one key's access (and the access credential), then exit" },
+            json,
+        ],
+        noGuidePointer: true,
+        passthroughExit: 125,
+        next: ["promigence sandbox ssh <sid> --config"],
+    },
+    {
+        name: "port expose", group: "Sandboxes", status: "released", notOnHosted: "preview URLs",
+        helpRow: { key: "port", summary: "preview URLs" },
+        summary: "publish a port as a preview URL (anyone with it can reach it)", args: "PORT",
+        flags: [{ name: "--sandbox", arg: "SID", summary: "the sandbox", required: true }, json],
+        next: ["promigence port revoke PORT --sandbox <sid>"],
+    },
+    {
+        name: "port list", group: "Sandboxes", status: "released", notOnHosted: "preview URLs",
+        helpRow: { key: "port", summary: "" },
+        summary: "list a sandbox's preview URLs",
+        flags: [{ name: "--sandbox", arg: "SID", summary: "the sandbox", required: true }, json],
+        next: ["promigence port revoke PORT --sandbox <sid>"],
+    },
+    {
+        name: "port revoke", group: "Sandboxes", status: "released", notOnHosted: "preview URLs",
+        helpRow: { key: "port", summary: "" },
+        summary: "take a preview URL down (a token, or every URL for a port)", args: "TOKEN|PORT",
+        flags: [{ name: "--sandbox", arg: "SID", summary: "the sandbox", required: true }, json],
+        next: ["promigence port list --sandbox <sid>"],
+    },
+    {
+        name: "secrets set", group: "Sandboxes", status: "released",
+        ownExtraWords: true,
+        summary: "store secret NAME (env/file/stdin, never argv)", args: "NAME",
+        flags: [
+            { name: "--from-env", arg: "VAR", summary: "read the value from an environment variable" },
+            { name: "--from-file", arg: "P", summary: "read the value from a file" },
+            { name: "--host", arg: "HOST", summary: "bind it to a host: requests sent to the address this command prints are authenticated for you; the value stays out of the sandbox unless a run asks (see --no-raw)", repeatable: true },
+            { name: "--header", arg: "NAME", summary: "with --host: the request header the key is sent in (default: the usual key headers)", repeatable: true },
+            { name: "--no-raw", summary: "with --host: the value itself can never be given to a sandbox" },
+            { name: "--list", summary: "list stored secret names (no values, ever)" },
+            { name: "--delete", summary: "remove NAME" },
+            json,
+        ],
+        next: [
+            "promigence run --snapshot H --count N --cap USD --secret NAME -- CMD",
+            "promigence secrets set --list",
+        ],
+    },
+    {
+        name: "bench burst", group: "Ops", status: "released",
+        summary: "N sandboxes at once: hand-off percentiles + success rate",
+        flags: [
+            snapshot, count,
+            { name: "--timeout", arg: "D", summary: "per-sandbox timeout (default 120s, the public burst harness's)" },
+            { name: "--cap", arg: "USD", summary: "spend cap for the burst (required unless PROMIGENCE_SPEND_CAP is set)" },
+            { name: "--keep", summary: "leave the sandboxes running (default: killed once measured)" },
+            json,
+        ],
+        next: ["promigence run report <run_id>"],
+    },
+    {
+        name: "runners github", group: "Ops", status: "released",
+        helpRow: { key: "runners", summary: "GitHub Actions / GitLab CI jobs in sandboxes" },
+        summary: "GitHub Actions jobs in sandboxes: `runs-on: promigence` (until Ctrl-C)",
+        note: "token from the environment, GitHub API only: Administration (--org: Self-hosted runners) write + Actions read; classic: repo (+ admin:org)",
+        flags: [
+            { name: "--repo", arg: "OWNER/REPO", summary: "take this repository's jobs" },
+            { name: "--org", arg: "ORG", summary: "or every repository's of an organization" },
+            { name: "--runner-group", arg: "NAME", summary: "with --org: the runner group (Default)" },
+            { name: "--token-env", arg: "VAR", summary: "variable holding a GitHub token (GH_TOKEN, then GITHUB_TOKEN)" },
+            { name: "--labels", arg: "A,B", summary: "the runs-on labels (promigence); promigence-small|medium|large pick a size" },
+            { name: "--tier", arg: "small|medium|large", summary: "size of a job that names none (small)" },
+            { name: "--warm", arg: "N", summary: "keep N runners waiting: instant pickup, billed while idle" },
+            { name: "--max", arg: "M", summary: "sandboxes at once (10)" },
+            { name: "--cap", arg: "USD", summary: "most one job may cost (default: its timeout at its size)" },
+            { name: "--timeout", arg: "DUR", summary: "longest job (default: your plan's longest sandbox)" },
+            { name: "--idle-timeout", arg: "DUR", summary: "stop an on-demand runner no job took (90s)" },
+            { name: "--kill-on-exit", summary: "Ctrl-C cancels running jobs instead of waiting" },
+            { name: "--prepare", summary: "build the --tier runner snapshot, then exit" },
+            { name: "--yes", summary: "build a missing runner snapshot (billed per second, per size) without asking" },
+            { name: "--github-api", arg: "URL", summary: "GitHub Enterprise Server's API URL" },
+            { name: "--poll", arg: "DUR", summary: "how often GitHub is asked for queued jobs", hidden: true },
+            json,
+        ],
+        next: ["promigence billing usage"],
+    },
+    {
+        name: "runners gitlab", group: "Ops", status: "released",
+        helpRow: { key: "runners", summary: "" },
+        summary: "GitLab CI jobs in sandboxes, as a runner with your tags (until Ctrl-C)",
+        note: "its token (glrt-…) comes from the environment; its jobs can read it in their sandbox",
+        flags: [
+            { name: "--url", arg: "URL", summary: "your GitLab (https://gitlab.com)" },
+            { name: "--token-env", arg: "VAR", summary: "variable holding the runner authentication token (GITLAB_RUNNER_TOKEN)" },
+            { name: "--executor", arg: "docker|shell", summary: "jobs in containers (docker) or in the sandbox" },
+            { name: "--default-image", arg: "REF", summary: "docker: image of a job with no image: (ubuntu:24.04)" },
+            { name: "--pool", arg: "N", summary: "runners kept up, billed while idle (1)" },
+            { name: "--api-token-env", arg: "VAR", summary: "read_api token: start runners only for pending jobs" },
+            { name: "--max", arg: "M", summary: "sandboxes at once (10)" },
+            { name: "--tier", arg: "small|medium|large", summary: "runner size (small)" },
+            { name: "--cap", arg: "USD", summary: "most one job may cost (default: its timeout at its size)" },
+            { name: "--timeout", arg: "DUR", summary: "longest job (default: your plan's longest sandbox)" },
+            { name: "--idle-timeout", arg: "DUR", summary: "with --api-token-env: a runner no job took exits (90s)" },
+            { name: "--kill-on-exit", summary: "Ctrl-C cancels running jobs instead of waiting" },
+            { name: "--prepare", summary: "build the --tier runner snapshot, then exit" },
+            { name: "--yes", summary: "build a missing runner snapshot (billed per second) without asking" },
+            { name: "--poll", arg: "DUR", summary: "how often GitLab is asked for pending jobs", hidden: true },
+            json,
+        ],
+        next: ["promigence billing usage"],
+    },
+    {
+        name: "status", group: "Setup", status: "released",
+        helpRow: { key: "doctor", summary: "" },
+        summary: "services · your concurrency in use vs your limit",
+        flags: [json],
+        next: ["promigence me"],
+    },
+    {
+        name: "billing usage", group: "Setup", status: "released",
+        helpRow: { key: "billing", summary: "" },
+        summary: "this month's spend: plan, usage by tier, credits, next invoice",
+        flags: [
+            { name: "--ledger", summary: "also print this key's project's metered rows" },
+            { name: "--limit", arg: "N", summary: "with --ledger: how many rows (default 20)" },
+            { name: "--cursor", arg: "C", summary: "with --ledger: the next_cursor of an earlier page" },
+            json,
+        ],
+        next: ["promigence billing card"],
+    },
+    {
+        name: "billing history", group: "Setup", status: "released",
+        helpRow: { key: "billing", summary: "" },
+        summary: "credits and payments, newest first (owners)",
+        flags: [
+            { name: "--kind", arg: "K", summary: "all | credits | payments (default all)" },
+            { name: "--limit", arg: "N", summary: "how many (default 50, at most 100)" },
+            { name: "--cursor", arg: "C", summary: "the next_cursor of an earlier page" },
+            json,
+        ],
+        next: ["promigence billing usage"],
+    },
+    {
+        name: "referrals", group: "Setup", status: "released",
+        helpRow: { key: "referrals", summary: "your code · apply one" },
+        summary: "your referral code, its offer, your referrals",
+        flags: [json],
+        next: ["promigence referrals apply <code>"],
+    },
+    {
+        name: "referrals apply", group: "Setup", status: "released",
+        helpRow: { key: "referrals", summary: "" },
+        summary: "apply a code (owner, before the first paid invoice)", args: "<code>",
+        flags: [json],
+        next: ["promigence referrals"],
+    },
+    {
+        name: "pricing", group: "Setup", status: "released",
+        helpRow: { key: "me", summary: "" },
+        summary: "your prices, live (list prices with no key)",
+        flags: [{ name: "--new-account", summary: "the published list" }, json],
+        next: ["promigence run quote --snapshot promigence/base --count 1"],
+    },
+    {
+        name: "credits", group: "Setup", status: "released",
+        helpRow: { key: "credits", summary: "free credit" },
+        summary: "your free-credit offer: state, credit, expiry, campaign",
+        flags: [json],
+        next: ["promigence credits claim"],
+    },
+    {
+        name: "credits claim", group: "Setup", status: "released",
+        helpRow: { key: "credits", summary: "" },
+        summary: "open the claim page (accept the terms in the browser); prints its URL",
+        flags: [{ name: "--no-open", summary: "print the URL, open nothing" }, json],
+        next: ["promigence credits"],
+    },
+    {
+        name: "snapshot delete", group: "Snapshots", status: "released",
+        helpRow: { key: "snapshot", summary: "" },
+        summary: "remove one of your snapshots (refused while a fork of it is alive)", args: "<hash|alias>",
+        flags: [json],
+        next: ["promigence snapshot list"],
+    },
+    {
+        name: "sandbox list", group: "Sandboxes", status: "released",
+        helpRow: { key: "sandbox", summary: "" },
+        summary: "your sandboxes, newest first",
+        flags: [
+            { name: "--limit", arg: "N", summary: "how many (default 50)" },
+            { name: "--state", arg: "S", summary: `only these states, comma-separated: ${SANDBOX_STATES.join(", ")}`, repeatable: true },
+            { name: "--label", arg: "K=V", summary: "only sandboxes whose run carries every label given", repeatable: true },
+            { name: "--cursor", arg: "C", summary: "the next_cursor of an earlier page" },
+            json,
+        ],
+        next: ["promigence sandbox kill <sid>"],
+    },
+    {
+        name: "sandbox pause", group: "Sandboxes", status: "released",
+        helpRow: { key: "sandbox", summary: "" },
+        summary: "park a sandbox: it bills no seconds and does not count against your limit", args: "SID",
+        note: BACKGROUND_NOTE,
+        flags: [json],
+        next: ["promigence sandbox resume <sid>"],
+    },
+    {
+        name: "sandbox resume", group: "Sandboxes", status: "released",
+        helpRow: { key: "sandbox", summary: "" },
+        summary: "bring a paused sandbox back and restart its clock", args: "SID",
+        flags: [
+            { ...optimizeFor, summary: "default: as created" },
+            { name: "--cap", arg: "USD", summary: "for a sandbox paused at its run's spend cap: the run's new, higher cap" },
+            json,
+        ],
+        next: ["promigence exec --sandbox <sid> -- CMD"],
+    },
+    {
+        name: "sandbox snapshot", group: "Sandboxes", status: "released",
+        helpRow: { key: "sandbox", summary: "" },
+        summary: "snapshot it without stopping it", args: "SID",
+        note: BACKGROUND_NOTE,
+        flags: [
+            json,
+            { name: "--alias", arg: "NAME", summary: "name it" },
+            { name: "--move-alias", summary: "take the alias from the snapshot that has it" },
+            { name: "--force", summary: "take it even though the sandbox was given a secret; the snapshot, and what starts from it, can then contain that value" },
+        ],
+        next: ["promigence run --snapshot <snap>"],
+    },
+    {
+        name: "secrets list", group: "Sandboxes", status: "released",
+        helpRow: { key: "secrets", summary: "list · delete (a value is never shown)" },
+        summary: "stored secret names (never a value)",
+        flags: [json],
+        next: ["promigence secrets set NAME --from-env VAR"],
+    },
+    {
+        name: "secrets delete", group: "Sandboxes", status: "released",
+        helpRow: { key: "secrets", summary: "" },
+        summary: "remove a stored secret", args: "NAME",
+        flags: [json],
+        next: ["promigence secrets list"],
+    },
+    {
+        name: "billing portal", group: "Setup", status: "released",
+        helpRow: { key: "billing", summary: "" },
+        summary: "manage the card on file and past invoices: prints a portal URL",
+        flags: [json],
+        next: ["promigence billing usage"],
+    },
+    {
+        name: "snapshot builds", group: "Snapshots", status: "released",
+        helpRow: { key: "snapshot", summary: "" },
+        summary: "your builds, newest first (a rejected build keeps its reason)",
+        flags: [{ name: "--limit", arg: "N", summary: "how many (default 20)" }, { name: "--state", arg: "S", summary: "only this state, e.g. running | rejected" }, { name: "--cursor", arg: "C", summary: "the next_cursor of an earlier page" }, json],
+        next: ["promigence snapshot status <build_id>"],
+    },
+    {
+        name: "snapshot alias", group: "Snapshots", status: "released",
+        helpRow: { key: "snapshot", summary: "" },
+        summary: "name a snapshot, or clear its name (unique per org)", args: "<hash> [NAME]",
+        flags: [{ name: "--clear", summary: "remove the alias instead" }, json],
+        next: ["promigence snapshot list"],
+    },
+    {
+        name: "run list", group: "Runs", status: "released",
+        helpRow: { key: "run", summary: "" },
+        summary: "your runs, newest first",
+        flags: [{ name: "--limit", arg: "N", summary: "how many (default 20)" }, { name: "--state", arg: "S", summary: "only this state" }, { name: "--cursor", arg: "C", summary: "the next_cursor of an earlier page" }, json],
+        next: ["promigence run report <run_id>"],
+    },
+    {
+        name: "sandbox info", group: "Sandboxes", status: "released",
+        helpRow: { key: "sandbox", summary: "" },
+        summary: "one sandbox: state, tier, time left, cost so far, and its execs", args: "SID",
+        flags: [json],
+        next: ["promigence exec output <exec_id> --sandbox <sid>"],
+    },
+    {
+        name: "sandbox extend", group: "Sandboxes", status: "released",
+        helpRow: { key: "sandbox", summary: "" },
+        summary: "give a live sandbox more time, within its run's quote and --cap (exit 5 past them)", args: "SID",
+        flags: [{ name: "--timeout", arg: "DUR", summary: "the new total timeout", required: true }, json],
+        next: ["promigence sandbox info <sid>"],
+    },
+    {
+        name: "sandbox autopause", group: "Sandboxes", status: "released",
+        helpRow: { key: "sandbox", summary: "" },
+        summary: "pause it once it has sat idle, or read the rule it is under", args: "SID",
+        flags: [
+            { name: "--after", arg: "DUR", summary: "idle this long and it pauses itself (2s or more)" },
+            { name: "--off", summary: "never pause it on idle; only its timeout ends it" },
+            { name: "--mode", arg: "MODE", summary: "requests (default) | activity: also no CPU, no bytes, no open connection inside" },
+            json,
+        ],
+        next: ["promigence sandbox info <sid>"],
+    },
+    {
+        name: "sandbox probe", group: "Sandboxes", status: "released",
+        helpRow: { key: "sandbox", summary: "" },
+        summary: "is this still the verified environment? (its recorded paths, or --path)", args: "SID",
+        flags: [{ name: "--path", arg: "P", summary: "check these paths instead; PATH=blake3:<hex> where the snapshot recorded none (base, --image)", repeatable: true }, json],
+        next: ["promigence run report <run_id>"],
+    },
+    {
+        name: "files rm", group: "Sandboxes", status: "released",
+        helpRow: { key: "files", summary: "" },
+        summary: "delete a path in a sandbox", args: "PATH",
+        flags: [
+            { name: "--sandbox", arg: "SID", summary: "the sandbox", required: true },
+            { name: "--recursive", summary: "a directory and everything under it" },
+            json,
+        ],
+        next: ["promigence files ls --sandbox <sid>"],
+    },
+];
+export function compactNames(names) {
+    const heads = [];
+    const subs = new Map();
+    const bare = new Set();
+    for (const n of names) {
+        const [head, ...rest] = n.split(" ");
+        if (!subs.has(head)) {
+            subs.set(head, []);
+            heads.push(head);
+        }
+        if (rest.length)
+            subs.get(head).push(rest.join(" "));
+        else
+            bare.add(head);
+    }
+    return heads.map((h) => {
+        const list = subs.get(h);
+        if (!list.length)
+            return h;
+        return bare.has(h) ? `${h} +${list.join("/")}` : `${h} ${list.join("/")}`;
+    }).join(" · ");
+}
+export const LISTED_COMMANDS = COMMANDS.filter((c) => c.status === "released");
+export const LIVE_SUMMARY = compactNames(LISTED_COMMANDS.map((c) => c.name));
+export const NOT_LIVE_SUMMARY = "";
+export const STATUS_LINE = `Status: v${VERSION} — all ${LISTED_COMMANDS.length} commands live; preview URLs (port expose) may be off in this beta.`;
+export const GROUPS = ["Setup", "Snapshots", "Runs", "Sandboxes", "Ops"];
+export const GLOBAL_FLAGS = [
+    { name: "--json", summary: "one JSON document on stdout (default when stdout is not a TTY, except exec --sandbox: --json or PROMIGENCE_OUTPUT=json there)" },
+    { name: "--text", summary: "human text: a result on stdout, an error on stderr" },
+    { name: "--api-key", arg: "K", summary: "precedence: --api-key > PROMIGENCE_API_KEY > the stored sign-in" },
+    { name: "--request-timeout", arg: "DUR", summary: `how long one API request may take (default ${REQUEST_TIMEOUT_DEFAULT}); PROMIGENCE_REQUEST_TIMEOUT` },
+    { name: "--version", summary: "print the version" },
+    { name: "--help", summary: "this help; `promigence <command> --help` for one command" },
+];
+export function knownFlags(cmd) {
+    const out = new Set();
+    for (const f of GLOBAL_FLAGS)
+        out.add(f.name);
+    for (const f of cmd.flags)
+        out.add(f.name);
+    if (cmd.autoIdempotencyKey)
+        out.add("--fresh");
+    return out;
+}
+export function unknownFlags(cmd, typed) {
+    const known = knownFlags(cmd);
+    return [...typed].filter((f) => !known.has(f));
+}
+export function nearestFlag(typo, cmd) {
+    const known = [...knownFlags(cmd)];
+    const near = known.filter((k) => k.includes(typo) || typo.includes(k));
+    if (near.length)
+        return near.sort((a, b) => Math.abs(a.length - typo.length) - Math.abs(b.length - typo.length))[0];
+    const scored = known.map((k) => [k, levenshtein(k, typo)]).filter(([, d]) => d <= 2).sort((a, b) => a[1] - b[1]);
+    if (!scored.length || (scored.length > 1 && scored[0][1] === scored[1][1]))
+        return undefined;
+    return scored[0][0];
+}
+function levenshtein(a, b) {
+    const d = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let prev = d[0];
+        d[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cur = d[j];
+            d[j] = Math.min(d[j] + 1, d[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = cur;
+        }
+    }
+    return d[b.length];
+}
+export const EXIT_CODES = [
+    { code: 0, name: "ok", summary: "success" },
+    { code: 1, name: "internal", summary: "Promigence's own failure (incl. not_released)" },
+    { code: 2, name: "usage", summary: "bad arguments / unknown command" },
+    { code: 3, name: "env_failed", summary: "the environment failed (ours, never the task's)" },
+    { code: 4, name: "task_failed", summary: "the task/command failed" },
+    { code: 5, name: "spend_cap", summary: "a spend cap or an account limit refused it; nothing started" },
+    { code: 6, name: "not_verified", summary: "fork/run against a snapshot whose build is not verified" },
+    { code: 7, name: "auth", summary: "missing/invalid key; fix names the issuance contact" },
+    { code: 8, name: "not_found", summary: "snapshot / run / sandbox not found" },
+    { code: 9, name: "unreachable", summary: "API unreachable" },
+    { code: 10, name: "rate_limited", summary: "429; Retry-After honoured" },
+    { code: 11, name: "timeout", summary: "a bounded wait expired; nothing is killed; next is id-based" },
+    { code: 12, name: "partial", summary: "some sandboxes not_started | cap_killed | expired | stopped_by_support" },
+    { code: 13, name: "changes_pending", summary: "agent-guide --check: the files would change; nothing was written" },
+    { code: 125, name: "passthrough", summary: "exec --sandbox: Promigence's own failure (child code otherwise passes through; a command not found exits 127)" },
+    { code: 130, name: "interrupted", summary: "SIGINT/SIGTERM/SIGHUP; sandboxes killed unless --keep" },
+];
+export const EXIT_PRECEDENCE = [2, 5, 6, 7, 8, 9, 10, 11, 3, 12, 4, 1, 0];
+export const EXIT_PRECEDENCE_TEXT = "2 > 5 > 6 > 7/8/9/10 > 11 > 3 > 12 > 4 > 1 > 0";
+export const OUTPUT_MODE_PRECEDENCE = ["--json | --text", "PROMIGENCE_OUTPUT=json|text", "stdout TTY → text, else json"];
+export function findCommand(words) {
+    for (let n = Math.min(2, words.length); n >= 1; n--) {
+        const name = words.slice(0, n).join(" ");
+        const c = COMMANDS.find((x) => x.name === name);
+        if (c)
+            return c;
+    }
+    return undefined;
+}
+function pad(s, w) {
+    return s.length >= w ? s + " " : s + " ".repeat(w - s.length);
+}
+function groupRows(group) {
+    const rows = [];
+    const merged = new Map();
+    for (const c of LISTED_COMMANDS) {
+        if (c.group !== group)
+            continue;
+        if (!c.helpRow) {
+            rows.push([c.name, c.summary]);
+            continue;
+        }
+        const m = merged.get(c.helpRow.key);
+        const via = c.helpRow.via;
+        if (via && m && c.name.startsWith(via + " ")) {
+            if (!m.vias.includes(via))
+                m.vias.push(via);
+            const sub = c.name.slice(via.length + 1);
+            if (!m.subs.includes(sub)) {
+                m.subs.push(sub);
+                m.names.push(sub);
+            }
+            continue;
+        }
+        const bare = c.name === c.helpRow.key;
+        const prefixed = c.name.startsWith(c.helpRow.key + " ");
+        const sub = prefixed ? c.name.slice(c.helpRow.key.length + 1) : c.name;
+        if (m) {
+            if (bare)
+                m.bare = true;
+            else {
+                m.names.push(sub);
+                (prefixed ? m.subs : m.fulls).push(sub);
+                m.prefixed &&= prefixed;
+            }
+        }
+        else {
+            merged.set(c.helpRow.key, {
+                names: bare ? [] : [sub], subs: bare || !prefixed ? [] : [sub], fulls: bare || prefixed ? [] : [sub],
+                summary: c.helpRow.summary, prefixed: bare || prefixed, bare, vias: [],
+            });
+            rows.push([c.helpRow.key, ""]);
+        }
+    }
+    return rows.map(([name, summary]) => {
+        const m = merged.get(name);
+        if (!m || summary !== "")
+            return [name, summary];
+        if (m.bare && m.prefixed)
+            return [m.names.length ? `${name} [${m.names.join("|")}]` : name, m.summary];
+        const head = [name, ...m.vias].join("|");
+        if (!m.bare && m.subs.length && m.fulls.length)
+            return [`${head} ${m.subs.join("|")} · ${m.fulls.join("|")}`, m.summary];
+        return [m.prefixed ? `${name} ${m.names.join("|")}` : [...(m.bare ? [name] : []), ...m.names].join("|"), m.summary];
+    });
+}
+export function renderHelp() {
+    const out = [GUIDE_POINTER, DESCRIPTION, ""];
+    out.push("Usage: promigence <command> [flags] [-- CMD]   (--json | --text · --api-key K · --version)");
+    for (const g of GROUPS) {
+        out.push(g);
+        for (const [name, summary] of groupRows(g))
+            out.push(`  ${pad(name, 26)}${summary}`);
+    }
+    out.push("", `Golden path: ${GOLDEN_PATH}`, "");
+    out.push("Output: --json|--text > PROMIGENCE_OUTPUT > TTY (non-TTY = JSON; exec --sandbox prints its command's own output); no ANSI if NO_COLOR or piped.");
+    const codes = EXIT_CODES.filter((e) => e.code !== 125 && e.code !== 13).map((e) => `${e.code} ${e.name}`).join(" · ");
+    out.push(`Exit: ${codes}`);
+    out.push(`      precedence ${EXIT_PRECEDENCE_TEXT}; waits bounded (--wait-timeout ${WAIT_TIMEOUT_DEFAULT})`);
+    out.push("", STATUS_LINE);
+    return out.join("\n") + "\n";
+}
+export function signInLine(c) {
+    if (!c.signIn)
+        return undefined;
+    const when = c.signIn === "always" ? "always" : `only ${c.signIn}`;
+    return `Sign-in: ${when}, in your browser (--no-browser on a headless box).`;
+}
+export function renderCommandHelp(c) {
+    const out = [`promigence ${c.name} — ${c.summary}`];
+    const req = c.flags.filter((f) => f.required).map((f) => `${f.name} ${f.arg ?? ""}`.trim()).join(" ");
+    out.push(`Usage: promigence ${c.name}${req ? " " + req : ""}${c.args ? " " + c.args : ""} [flags]`);
+    const shown = c.flags.filter((f) => !f.hidden);
+    if (shown.length) {
+        out.push("Flags:");
+        for (const f of shown) {
+            const head = `${f.name}${f.arg ? " " + f.arg : ""}${f.repeatable ? " …" : ""}`;
+            out.push(`  ${pad(head, 24)}${f.summary}`);
+        }
+    }
+    if (c.note)
+        out.push(`Note: ${c.note}.`);
+    if (c.passthroughExit)
+        out.push(`Exit: child's code passes through; a command not found in the sandbox exits 127; Promigence's own failures exit ${c.passthroughExit} (promigence_exit in JSON).`);
+    if (c.autoIdempotencyKey)
+        out.push("Idempotency: auto-keyed per 10-min bucket.");
+    const signIn = signInLine(c);
+    if (signIn)
+        out.push(signIn);
+    if (c.next.length)
+        out.push(`Next: ${c.next.join("  ·  ")}`);
+    if (c.status !== "released")
+        out.push(`Status: not released in v${VERSION} (exits 1 not_released).`);
+    return out.join("\n") + "\n";
+}
+export function notReleasedEnvelope(c) {
+    const env = {
+        schema: SCHEMA,
+        command: c.name,
+        ok: false,
+        error: {
+            code: "not_released",
+            message: `promigence ${c.name} is not released yet: promigence@${VERSION} does not implement it.`,
+            fix: `Update with 'npm i -g promigence' once a release implements '${c.name}' (support@promigence.ai can tell you when). ` +
+                `Until then read ${DOCS_URL}.`,
+            docs: DOCS_URL,
+            guide: "promigence agent-guide --section errors --code not_released",
+        },
+        next: [
+            { cmd: "promigence agent-guide", why: "the primitive, golden path, output contract and exit codes" },
+            { cmd: "promigence --version", why: "the version you have now" },
+        ],
+    };
+    if (c.passthroughExit)
+        env.promigence_exit = 1;
+    return env;
+}
+export function notReleasedLines(c, env) {
+    return [
+        `promigence ${c.name}: not yet released (error not_released, exit 1)`,
+        `  ${env.error.message}`,
+        `  fix: ${env.error.fix}`,
+        "  next: promigence agent-guide",
+    ];
+}