anon-pi 0.15.0 → 0.16.0

package/dist/anon-pi.js

@@ -14,9 +14,10 @@
 //     /projects (the projects root). `--mount <parent>` adds EXACTLY one more
 //     mount at the DISTINCT /work and re-roots cwd there; nothing else changes,
 //     so we never remount a running container.
-//   - Throwaway (`--rm`) is the DEFAULT; `--keep` leaves the container kept so
-//     its filesystem survives (found + resumed by netcage's `netcage.managed`
-//     label via `netcage start`). The machine home persists either way.
+//   - Every launch is THROWAWAY (the container is always `--rm`): it is removed
+//     on exit. Durable state is EXPLICIT and image-based (snapshot a running
+//     container into a named image, then a machine pinned to it); the machine
+//     home persists regardless (it is a host mount). See docs/adr/0004.
 //   - Open exactly ONE direct hole (--allow-direct <llm>) so pi can reach a
 //     local model while ALL other egress stays forced through the socks5h proxy
 //     (fail-closed; the proxy is REQUIRED and never guessed).
@@ -26,9 +27,9 @@
 //
 // This module holds every DECISION as a pure function (config load + precedence,
 // machine/project resolvers, name validation, the RunPlan argv, the menu
-// choice-list, project usage, the run-vs-start rule, models.json generation,
-// init's proxy detect/verify decisions). cli.ts owns only the impure edges (fs,
-// the interactive TUI, the netcage query, the spawn).
+// choice-list, project usage, models.json generation, init's proxy detect/verify
+// decisions). cli.ts owns only the impure edges (fs, the interactive TUI, the
+// netcage query, the spawn).
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -291,14 +292,29 @@ export function resolveDeleteProject(args) {
  */
 export const ROOT_TOKEN = '.';
 /**
- * Reserved names that a machine/project may NOT take (case-sensitive). Kept
- * DELIBERATELY minimal: only the two structural path tokens. `.` is the root
- * token (see ROOT_TOKEN); `..` is parent-traversal. Both are also rejected by
- * the leading-dot / `..` structural checks below, but are listed here so the
- * reserved-name concept is explicit and extendable. `--mount`'s `/work` is a
- * CONTAINER path, not a name in this namespace, so it needs no reservation.
- */
-export const RESERVED_NAMES = ['.', '..', 'pi'];
+ * Reserved names that a machine/project/image may NOT take (case-sensitive).
+ * `.` is the root token (see ROOT_TOKEN); `..` is parent-traversal (both are
+ * also rejected by the structural checks below, but listed here so the
+ * reserved-name concept is explicit). `pi` is the passthrough token. The
+ * SUBCOMMAND NOUN words (`machine`, `image`, `init`, `forward`, `ports`) are
+ * reserved too: each is dispatched BEFORE the launch grammar, so a folder so
+ * named would be UNREACHABLE by bare name (a latent trap). Reserving them makes
+ * validateName refuse such a name up front with a clear error, closing the
+ * trap. `--mount`'s `/work` is a CONTAINER path, not a name here, so it needs no
+ * reservation. The reservation is GLOBAL (validateName is the one validator);
+ * the menu tolerates a pre-existing folder now reserved by FILTERING it out via
+ * the try/catch isProjectName, so a now-reserved folder is skipped, not a crash.
+ */
+export const RESERVED_NAMES = [
+    '.',
+    '..',
+    'pi',
+    'machine',
+    'image',
+    'init',
+    'forward',
+    'ports',
+];
 /**
  * PURE: validate a machine or project name as a safe single path segment, and
  * return it unchanged on success. Rejects (with AnonPiError):
@@ -387,7 +403,7 @@ export function resolveCwd(kind, token) {
  * and files written under the home land in the machine's config home on the
  * host; a shell is the project-hopper, so `/projects` is the natural landing.
  * The machine home is one `cd ~` away for the rare case. `menu` never reaches
- * here (it is argv-less). Shared by resolveRunPlan + keptContainerKey so the run
+ * here (it is argv-less). Shared by resolveRunPlan + launchIdentityKey so the run
  * cwd and the container-identity key always agree.
  */
 export function launchCwd(_mode, kind, project) {
@@ -516,6 +532,22 @@ export function resolveProxy(args) {
 export function resolveLlm(args) {
     return nonEmpty(args.env.llmDirect) ?? nonEmpty(args.config?.llm);
 }
+/**
+ * PURE: resolve the IMAGE a launch runs against, highest-priority first:
+ * a per-launch `-i`/`--image` override > the machine's pinned image
+ * (machine.json) > `ANON_PI_IMAGE` (the env fallback) > undefined (the CLL then
+ * errors). The `-i` override is STRICTLY EPHEMERAL: it selects the image for
+ * THIS launch only and is NEVER written back to machine.json (that persistent
+ * pin is `machine set-image` / `machine create --image`). No mismatch warning is
+ * ever emitted (ADR-0003 section 3: `-i` is explicit + ephemeral, so a warning
+ * carries no information the user lacks). Empty strings are treated as unset at
+ * every tier (nonEmpty), so a blank env/pin falls through cleanly.
+ */
+export function resolveLaunchImage(args) {
+    return (nonEmpty(args.override) ??
+        nonEmpty(args.machineImage) ??
+        nonEmpty(args.envImage));
+}
 // --- Grammar A: the pure argv -> ParsedLaunch parser -------------------------
 //
 // A bare positional is a PROJECT; `-m` picks the machine. The CLI (cli.ts)
@@ -666,6 +698,24 @@ export function sessionHeaderCwd(headerLine) {
  * RESERVED project name (see RESERVED_NAMES) so a project can never shadow it.
  */
 export const PI_PASSTHROUGH_TOKEN = 'pi';
+/**
+ * The retired launch flags. `--keep`/`--rm` are GONE (ADR-0004): every launch is
+ * throwaway now, so there is no flag to toggle. `--keep`'s exploratory
+ * "apt install, quit, re-enter" use case is served, better, by snapshotting a
+ * running container into a named image and pinning a machine to it (explicit +
+ * named, no inference). The label a launch is passed one of these RETIRED flags
+ * gets a clear error pointing there.
+ */
+export const RETIRED_LAUNCH_FLAGS = ['--keep', '--rm'];
+/** PURE: the error message for a retired `--keep`/`--rm` flag, pointing at the image-based replacement. */
+export function retiredKeepRmMessage(flag) {
+    return (`${flag} is gone: every launch is throwaway now (the container is always ` +
+        `removed on exit). To persist system state you set up in a session (e.g. after ` +
+        `\`apt install\`), snapshot the RUNNING container into a named image and use it:\n` +
+        `  anon-pi image snapshot <name>        (freeze the running container -> anon-pi/<name>:latest)\n` +
+        `  anon-pi machine create <m> --image anon-pi/<name>:latest   (a durable machine pinned to it)\n` +
+        `Your pi config + conversations live in the machine home (a host mount) and persist regardless.`);
+}
 /**
  * PURE: whether forwarded pi args request pi's NON-INTERACTIVE (print) mode,
  * i.e. contain `-p`/`--print`. This is the ONLY headless shape (it needs no
@@ -683,9 +733,6 @@ export function isHeadlessPiArgs(piArgs) {
  * `--shell` is incompatible (a shell forwards no pi args).
  */
 function finishPiNoProjectLaunch(args) {
-    if (args.keep && args.rm) {
-        args.fail('--keep and --rm are contradictory (pick one; --rm is the default)');
-    }
     if (args.shell) {
         args.fail('--shell forwards no pi args (a shell has no session/query). Drop --shell.');
     }
@@ -695,14 +742,14 @@ function finishPiNoProjectLaunch(args) {
         machineExplicit: args.machineExplicit,
         project: undefined,
         mountParent: args.mountParent,
-        keep: args.keep,
+        image: args.image,
         piArgs: args.piArgs,
     };
 }
 /**
  * PURE: parse grammar A into a ParsedLaunch. Consumes the anon-pi flags
- * (`-m <machine>`, `--shell`, `--mount <parent>`, `--keep`/`--rm`) LEFT of the
- * project positional; the FIRST bare positional is the project (`.` allowed as
+ * (`-m <machine>`, `--shell`, `--mount <parent>`, `-i`/`--image <ref>`) LEFT of
+ * the project positional; the FIRST bare positional is the project (`.` allowed as
  * the root token). In pi mode every token AFTER the project is forwarded to pi
  * verbatim (so `anon-pi recon -p '...'` works) — anon-pi flags must come before
  * the project. A pi session-resume flag (`--session <id>`, `--continue`,
@@ -715,15 +762,14 @@ function finishPiNoProjectLaunch(args) {
  * reserved-name guard); `--mount <parent>` is a HOST path in its own namespace,
  * distinct from the project-name namespace (NAME vs `--mount` exclusivity), so
  * it is NOT name-validated here. Throws AnonPiError for an unknown option, a
- * missing `-m`/`--mount` argument, a contradictory `--keep --rm`, or a bad name.
+ * missing `-m`/`--mount` argument, a RETIRED `--keep`/`--rm` flag, or a bad name.
  */
 export function parseLaunchArgs(args) {
     let machine = DEFAULT_MACHINE;
     let machineSet = false;
     let shell = false;
     let mountParent;
-    let keepSeen = false;
-    let rmSeen = false;
+    let image;
     let project;
     let piArgs;
     const fail = (msg) => {
@@ -751,13 +797,21 @@ export function parseLaunchArgs(args) {
             mountParent = v;
             continue;
         }
-        if (a === '--keep') {
-            keepSeen = true;
+        if (a === '-i' || a === '--image') {
+            // The EPHEMERAL per-launch image override. A raw ref, NOT a
+            // name-namespaced anon-pi token (it resolves in netcage's private
+            // image store, so any podman ref / `anon-pi/<name>:latest` snapshot tag
+            // is valid): not name-validated here. It never mutates machine.json.
+            const v = args[++i];
+            if (v === undefined)
+                fail(`${a} needs an image ref`);
+            image = v;
             continue;
         }
-        if (a === '--rm') {
-            rmSeen = true;
-            continue;
+        if (RETIRED_LAUNCH_FLAGS.includes(a)) {
+            // `--keep`/`--rm` are retired (ADR-0004): throwaway is the only
+            // behaviour now. Point at the image-based replacement.
+            fail(retiredKeepRmMessage(a));
         }
         if (a === '.') {
             // the root token is a valid project positional (not a name).
@@ -774,8 +828,7 @@ export function parseLaunchArgs(args) {
                 machine,
                 machineExplicit: machineSet,
                 mountParent,
-                keep: keepSeen,
-                rm: rmSeen,
+                image,
                 shell,
                 piArgs: args.slice(i + 1),
                 fail,
@@ -815,8 +868,7 @@ export function parseLaunchArgs(args) {
                 machine,
                 machineExplicit: machineSet,
                 mountParent,
-                keep: keepSeen,
-                rm: rmSeen,
+                image,
                 shell,
                 piArgs,
                 fail,
@@ -830,9 +882,6 @@ export function parseLaunchArgs(args) {
         i++;
         break;
     }
-    if (keepSeen && rmSeen) {
-        fail('--keep and --rm are contradictory (pick one; --rm is the default)');
-    }
     // tokens remaining after the project.
     const rest = args.slice(i);
     if (shell) {
@@ -846,7 +895,7 @@ export function parseLaunchArgs(args) {
             machineExplicit: machineSet,
             project,
             mountParent,
-            keep: keepSeen,
+            image,
         };
     }
     if (project === undefined) {
@@ -859,7 +908,7 @@ export function parseLaunchArgs(args) {
             machineExplicit: machineSet,
             project: undefined,
             mountParent,
-            keep: keepSeen,
+            image,
         };
     }
     // pi mode: every token after the project is forwarded to pi verbatim.
@@ -871,7 +920,7 @@ export function parseLaunchArgs(args) {
         machineExplicit: machineSet,
         project,
         mountParent,
-        keep: keepSeen,
+        image,
         piArgs,
     };
 }
@@ -885,7 +934,7 @@ export function parseLaunchArgs(args) {
  *   - the two mounts <home>:/root and <projectsRoot>:/projects, always;
  *   - --mount adds EXACTLY <parent>:/work and re-roots cwd, nothing else;
  *   - --proxy <p> + exactly one --allow-direct <llm> (forced egress, fail-closed);
- *   - --rm by default, omitted only under --keep.
+ *   - --rm on EVERY launch (throwaway always; ADR-0004).
  *
  * Throws AnonPiError (a plan is NEVER produced) when the image, the machine
  * home, the proxy, or the direct-hole llm is missing.
@@ -938,9 +987,9 @@ export function resolveRunPlan(intent, homeFresh) {
     // task; here the argv simply omits -it for the one headless shape.
     const headless = mode === 'pi' && isHeadlessPiArgs(intent.piArgs);
     const netcageArgs = ['run'];
-    // --rm by DEFAULT (throwaway); --keep leaves the container kept.
-    if (intent.keep !== true)
-        netcageArgs.push('--rm');
+    // Throwaway ALWAYS: every launch is `--rm` (ADR-0004). Durable state is
+    // image-based (snapshot + a pinned machine), never an accreting container.
+    netcageArgs.push('--rm');
     // Forced egress: the proxy + the ONE direct hole. Never omitted.
     netcageArgs.push('--proxy', proxy, '--allow-direct', directTarget);
     if (!headless)
@@ -1018,42 +1067,45 @@ function containerSeedThen(seedVersion, exec) {
         `fi && ` +
         `${exec}`);
 }
-/**
- * PURE: the launch-identity match key for a kept container, derived ENTIRELY
- * from the (machine, projects-root, project) identity (ADR-0002). It is what
- * decides whether an existing kept `netcage.managed` container IS the one a
- * `--keep` launch should resume.
- *
- * The fields, and why each is load-bearing:
- *   - `machine.name`: a kept container mounts THIS machine's home at /root; a
- *     same-project container on another machine is a different environment.
- *   - `projectsRoot`: the host dir mounted at /projects; two launches with the
- *     same project name but different roots are different working trees.
- *   - `mountParent` (or '' when absent): `--mount` re-roots into a DIFFERENT
- *     host parent at /work, so a `--mount` launch is a distinct identity from
- *     the projects-root launch of the same name.
- *   - the resolved container `cwd`: this already encodes the project token
- *     (`/projects/<p>`, `/work/<p>`, or a root `/projects`/`/work`; legacy kept
- *     containers may still carry /root from the pre-0.12 bare-shell-at-home)
- *     AND which root it sits under, so it is pi's conversation key too. Using
- *     the cwd keeps the container identity aligned with the conversation the
- *     kept container hosts.
+// --- The per-launch identity label (for `forward`/`ports`/`snapshot`) --------
+//
+// anon-pi stamps an identity key onto EVERY launch's container (an additive
+// netcage label; see withKeyLabel in cli.ts). It is NOT a kept-container match
+// key (there are no kept containers: every launch is throwaway, ADR-0004). Its
+// sole job is to let `forward`/`ports`/`snapshot` find a RUNNING container and
+// read back which machine + project it hosts (parseKeptKey -> keyProject),
+// while the container is up (the label goes away with the `--rm` container on
+// exit). netcage's `netcage.managed` label marks the container managed; this
+// adds anon-pi's own identity on top. anon-pi invents NO registry file.
+/**
+ * PURE: the anon-pi launch-identity key stamped on EVERY (throwaway) launch,
+ * derived from the (machine, projects-root, project) identity (ADR-0002's
+ * cwd/project reasoning still underpins it). It is NOT a kept-container MATCH
+ * key (every launch is throwaway; nothing is ever resumed). It exists ONLY so
+ * `forward`/`ports`/`snapshot` can resolve a RUNNING container by machine +
+ * project: the CLI stamps it onto a netcage label and reads it back with
+ * parseKeptKey -> keyProject.
  *
- * DELIBERATELY EXCLUDED (not part of identity): `--keep`/`--rm` (the throwaway
- * choice for THIS run), the proxy + the direct-hole llm (forced-egress inputs),
- * forwarded pi args, and the seed. Two launches that differ only in those must
- * resolve to the SAME kept container.
+ * The fields, and why each is retained:
+ *   - `machine.name`: the forward/ports filter scopes by machine.
+ *   - `cwd` (the resolved container cwd, via launchCwd): encodes the project
+ *     token (`/projects/<p>`, `/work/<p>`, or a root), so keyProject can name
+ *     the project a running container hosts.
+ *   - `projectsRoot` + `mountParent`: kept in the record for stability of the
+ *     decode shape (parseKeptKey reads them best-effort); no consumer filters on
+ *     them today, but they cost nothing and keep the label self-describing.
  *
- * The key is a single opaque string (a `\n`-joined, field-tagged record) so the
- * CLI can stamp it verbatim onto a netcage label and match on string equality;
- * its internal shape is not a contract (compare only keys this function makes).
+ * Independent of the forced-egress inputs and forwarded pi args (identity only).
+ * The key is a single opaque string (a `\n`-joined, field-tagged record) the CLI
+ * stamps verbatim onto a netcage label; its internal shape is not a contract
+ * (decode only with parseKeptKey).
  */
-export function keptContainerKey(intent) {
+export function launchIdentityKey(intent) {
     const { machine, mode, projectsRoot, project, mountParent } = intent;
     const mounted = nonEmpty(mountParent) !== undefined;
     const rootKind = mounted ? 'mount' : 'projects';
-    // The same cwd resolution resolveRunPlan uses, so the key names the exact
-    // container a matching launch would run in (its conversation key).
+    // The same cwd resolution resolveRunPlan uses, so keyProject names the exact
+    // project the running container hosts (its conversation key).
     const cwd = launchCwd(mode, rootKind, project);
     return [
         `machine=${machine.name}`,
@@ -1062,29 +1114,7 @@ export function keptContainerKey(intent) {
         `cwd=${cwd}`,
     ].join('\n');
 }
-/**
- * PURE: decide run-vs-start for a launch given a SUPPLIED listing of kept
- * `netcage.managed` containers (the CLI's netcage query result).
- *
- *   - `--rm` (throwaway, `intent.keep !== true`): ALWAYS a fresh `run`. The
- *     listing is NOT consulted (a throwaway launch never resumes a kept box).
- *   - `--keep`: a kept container whose `key` equals this launch's
- *     keptContainerKey is present -> `start` it (by its `ref`); else -> `run`
- *     (resolveRunPlan leaves it kept because `--keep` omits `--rm`).
- *
- * Never spawns, never queries netcage: the listing is injected, so the whole
- * decision is a pure function of (intent, listing).
- */
-export function resolveRunVsStart(intent, kept) {
-    // Throwaway short-circuit: a `--rm` launch is always a fresh run and never
-    // consults the listing (it must not resume a kept container).
-    if (intent.keep !== true)
-        return { action: 'run' };
-    const want = keptContainerKey(intent);
-    const match = kept.find((c) => c.key === want);
-    return match ? { action: 'start', ref: match.ref } : { action: 'run' };
-}
-/** PURE: parse a stamped keptContainerKey back into its fields (best-effort). */
+/** PURE: parse a stamped launchIdentityKey back into its fields (best-effort). */
 export function parseKeptKey(key) {
     const out = {
         machine: '',
@@ -1308,7 +1338,7 @@ export const ANON_PI_KEY_LABEL = 'anon-pi.key';
  * ref: <Id>, name: <first Names entry or Id>}. When `runningOnly`, entries whose
  * State is not "running" are dropped (forward/ports can only reach a live jail).
  * The base64 DECODE of `key` is the CLI's job (Buffer), so this stays pure; the
- * caller decodes before matching against a keptContainerKey. [] on bad JSON.
+ * caller decodes before matching against a launchIdentityKey. [] on bad JSON.
  */
 export function parseNetcagePsJson(stdout, opts = {}) {
     let parsed;
@@ -2171,7 +2201,7 @@ export function parseMachineArgs(args) {
     };
     const verb = args[0];
     if (verb === undefined) {
-        fail('`machine` needs a subcommand: create | list | set-image | rm | snapshot');
+        fail('`machine` needs a subcommand: create | list | set-image | rm');
     }
     const rest = args.slice(1);
     if (verb === 'list') {
@@ -2245,15 +2275,37 @@ export function parseMachineArgs(args) {
             fail('machine rm needs a <name>');
         return { verb: 'rm', name: name, yes };
     }
+    return fail(`unknown machine subcommand: ${verb} (create | list | set-image | rm)`);
+}
+/**
+ * PURE: parse the tokens AFTER `image` into an ImageCommand. Validates the image
+ * name + the `-m` / `--create-machine` machine names via validateName (the
+ * reserved-name / traversal guard), so the CLI only ever joins safe segments.
+ * Throws AnonPiError (printed verbatim, exit 1) for an unknown/missing verb, a
+ * missing or extra positional, an unknown flag, or a bad name.
+ *
+ * `<name>` is validated with the `machine` kind: it shares the same
+ * folder-safe / reserved-name rules, and a snapshot name is an image-tag
+ * segment (`anon-pi/<name>:latest`), so the same guard applies.
+ */
+export function parseImageArgs(args) {
+    const fail = (msg) => {
+        throw new AnonPiError(`anon-pi: ${msg}\nRun \`anon-pi image --help\` or \`anon-pi --help\`.`);
+    };
+    const verb = args[0];
+    if (verb === undefined) {
+        fail('`image` needs a subcommand: snapshot | list');
+    }
+    const rest = args.slice(1);
+    if (verb === 'list') {
+        if (rest.length > 0)
+            fail(`image list takes no arguments, got: ${rest.join(' ')}`);
+        return { verb: 'list' };
+    }
     if (verb === 'snapshot') {
-        // snapshot <new-name> [-m <machine>] [--image-tag <ref>]: commit a RUNNING
-        // container into a new image and create <new-name> pinned to it. The sole
-        // positional is the new machine name; `-m` is an OPTIONAL filter (which
-        // container when several are up), not a required source. The CLI auto-detects
-        // the container (picker when several match).
         let name;
         let machine;
-        let imageTag;
+        let createMachine;
         for (let i = 0; i < rest.length; i++) {
             const a = rest[i];
             if (a === '-m' || a === '--machine') {
@@ -2263,41 +2315,81 @@ export function parseMachineArgs(args) {
                 machine = validateName(v, 'machine');
                 continue;
             }
-            if (a === '--image-tag') {
+            if (a === '--create-machine') {
                 const v = rest[++i];
                 if (v === undefined)
-                    fail('--image-tag needs an image ref');
-                imageTag = v;
+                    fail('--create-machine needs a machine name');
+                createMachine = validateName(v, 'machine');
                 continue;
             }
             if (a.startsWith('-'))
                 fail(`unknown option: ${a}`);
             if (name !== undefined)
-                fail(`machine snapshot takes one <new-name>, got extra: ${a}`);
+                fail(`image snapshot takes one <name>, got extra: ${a}`);
             name = validateName(a, 'machine');
         }
         if (name === undefined)
-            fail('machine snapshot needs a <new-name>');
+            fail('image snapshot needs a <name>');
         return {
             verb: 'snapshot',
             name: name,
             machine: nonEmpty(machine),
-            imageTag: nonEmpty(imageTag),
+            createMachine: nonEmpty(createMachine),
         };
     }
-    return fail(`unknown machine subcommand: ${verb} (create | list | set-image | rm | snapshot)`);
-}
-/**
- * PURE: the default image ref a `machine snapshot` writes when `--image-tag` is
- * not given: `anon-pi/<name>:snapshot-<ts>`, where <ts> is a compact UTC stamp
- * (YYYYMMDDHHMMSS) derived from `now`. Deterministic in `now` so it is unit
- * testable. The name is a validated machine name (a safe image-path segment).
- */
-export function snapshotImageRef(name, now) {
-    const p = (n, w = 2) => String(n).padStart(w, '0');
-    const ts = `${now.getUTCFullYear()}${p(now.getUTCMonth() + 1)}${p(now.getUTCDate())}` +
-        `${p(now.getUTCHours())}${p(now.getUTCMinutes())}${p(now.getUTCSeconds())}`;
-    return `anon-pi/${name}:snapshot-${ts}`;
+    return fail(`unknown image subcommand: ${verb} (snapshot | list)`);
+}
+/**
+ * PURE: the clean image tag a `image snapshot <name>` writes:
+ * `anon-pi/<name>:latest`. A same-name re-snapshot OVERWRITES this tag (that is
+ * what `:latest` means); the previous image becomes dangling but keeps its
+ * provenance label. The name is a validated image/machine name (a safe
+ * image-path segment).
+ */
+export function snapshotImageTag(name) {
+    return `anon-pi/${validateName(name, 'machine')}:latest`;
+}
+/** The podman/anon-pi provenance label keys baked into a snapshot image. */
+export const PROVENANCE_LABEL_SOURCE_MACHINE = 'anon-pi.source-machine';
+export const PROVENANCE_LABEL_SOURCE_IMAGE = 'anon-pi.source-image';
+export const PROVENANCE_LABEL_SNAPSHOT_AT = 'anon-pi.snapshot-at';
+/**
+ * PURE: build the `LABEL k=v` change instructions a `netcage commit -c '…'`
+ * bakes into a snapshot image (ADR-0003 §2). Provenance is best-effort HISTORY:
+ * a label whose value is undefined/empty is OMITTED (a missing label beats a
+ * wrong one). `at` is required (the snapshot time is always known). Each string
+ * is ONE `LABEL key=value` instruction (the CLI passes each as a `-c` argv
+ * element; podman round-trips `/` and `:` in the value un-quoted, verified).
+ */
+export function snapshotProvenanceLabels(args) {
+    const labels = [];
+    const push = (key, value) => {
+        const v = nonEmpty(value);
+        if (v !== undefined)
+            labels.push(`LABEL ${key}=${v}`);
+    };
+    push(PROVENANCE_LABEL_SOURCE_MACHINE, args.sourceMachine);
+    push(PROVENANCE_LABEL_SOURCE_IMAGE, args.sourceImage);
+    push(PROVENANCE_LABEL_SNAPSHOT_AT, args.at);
+    return labels;
+}
+/**
+ * PURE: parse the anon-pi provenance labels read back off an image (the CLI
+ * supplies the label map from `inspect --format '{{json .Config.Labels}}'`).
+ * Returns only the anon-pi provenance fields (a missing/empty label => an
+ * undefined field). Tolerant: any non-string / absent value is dropped, so a
+ * hand-edited or partial label set never throws.
+ */
+export function parseImageProvenance(labels) {
+    const get = (key) => {
+        const v = labels?.[key];
+        return typeof v === 'string' ? nonEmpty(v) : undefined;
+    };
+    return {
+        sourceMachine: get(PROVENANCE_LABEL_SOURCE_MACHINE),
+        sourceImage: get(PROVENANCE_LABEL_SOURCE_IMAGE),
+        snapshotAt: get(PROVENANCE_LABEL_SNAPSHOT_AT),
+    };
 }
 /**
  * PURE: the JSON body a machine.json carries, given the pinned image (and an
@@ -2361,26 +2453,44 @@ USAGE
   anon-pi forward [<p>] [--port …]  open a host port onto a running container's in-jail server
   anon-pi ports [<project>]      list a running container's open in-jail TCP listeners
   anon-pi -m <machine> [<p>]     the same, on <machine> (its own image + home + conversations)
+  anon-pi -i <ref> [<p>]         run against <ref> for THIS launch only (also --image; ephemeral)
   anon-pi --mount <parent> [<p>] root at a HOST parent folder instead of the projects root
   anon-pi init                   onboard: verify your proxy, capture your local model, pick an image
-  anon-pi machine …              manage machines (create / list / set-image / rm / snapshot)
+  anon-pi machine …              manage machines (create / list / set-image / rm)
+  anon-pi image …                snapshot a running container into an image; list anon-pi images
   anon-pi --delete-home [<m>]    delete a machine's home (config + convos); keep its image pin + files
   anon-pi --delete-project <p>   delete a project's files + its per-machine sessions; keep the homes
 
   <project>   a folder under the projects root (mounted at ${CONTAINER_PROJECTS_ROOT}; pi's cwd). \`.\` means
               the root itself (a scratch pi at ${CONTAINER_PROJECTS_ROOT}, ${CONTAINER_MOUNT_ROOT} for --mount, or ~).
 
-  [--rm]      throwaway container this run (the DEFAULT; deleted on exit).
-  [--keep]    leave the container KEPT so its filesystem survives (apt install,
-              quit, re-enter). anon-pi finds it by netcage's managed label and
-              \`netcage start\`s it on re-entry.
+  -i <ref>, --image <ref>   EPHEMERAL per-launch image override, highest priority
+              (\`-i\` > the machine's machine.json image > ANON_PI_IMAGE). It picks the
+              IMAGE for this launch only; \`-m\` picks the HOME, and the two compose.
+              It NEVER changes machine.json (to re-pin a machine's image, use
+              \`anon-pi machine set-image\` / \`machine create --image\`). No mismatch
+              warning is printed. <ref> resolves in NETCAGE'S private image store
+              (\`anon-pi/<name>:latest\` snapshots + \`init\`-built images live there),
+              NOT your default podman store; anon-pi does NOT pre-check it and does
+              NOT auto-pull (an anonymity tool must not silently fetch a remote
+              image). A "not found" means the ref is not in netcage's store: snapshot
+              it (\`anon-pi image snapshot <name>\`) or build it into that store.
+              On a FRESH machine home \`-i\` is REFUSED (it would seed the home from
+              the wrong image); establish the machine's image with
+              \`anon-pi machine create <m> --image <ref>\` first.
+
+  Every launch is THROWAWAY: the container is removed on exit. To persist system
+  state you built in a session, snapshot the running container into a named image
+  (\`anon-pi image snapshot <name>\`) and pin a machine to it (\`anon-pi machine
+  create <m> --image anon-pi/<name>:latest\`). Your pi config + conversations live
+  in the machine home (a host mount) and persist regardless.
 
 WHAT IT DOES
   Runs pi inside netcage with all web/DNS egress forced through the socks5h proxy
   (fail-closed) and ONE direct hole to your local model (ANON_PI_LLM). A MACHINE
   is an image + a persistent HOST home (bind-mounted at ${CONTAINER_HOME_ROOT}) holding your pi
-  config, extensions, and conversations; the container is disposable, so \`--rm\`
-  loses nothing. Files (projects) are global by default; conversations are
+  config, extensions, and conversations; the container is disposable (throwaway),
+  so it loses nothing. Files (projects) are global by default; conversations are
   per-machine. On a FRESH machine home the image's staged defaults + your
   models.json are seeded in once; after that pi owns the home. Requires \`netcage\`.