anon-pi 0.15.0 → 0.16.0

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 // anon-pi CLI: the THIN impure launch path. Parses grammar A (pure
 // parseLaunchArgs), reads config.json / machine.json + resolves the machine,
-// composes the LaunchIntent, resolves the RunPlan (pure resolveRunPlan), decides
-// run-vs-start against real netcage for `--keep`, and spawns netcage with
-// inherited stdio (so -it is a real interactive TTY), propagating the exit code.
+// composes the LaunchIntent, resolves the RunPlan (pure resolveRunPlan; every
+// launch is throwaway), and spawns netcage with inherited stdio (so -it is a
+// real interactive TTY), propagating the exit code.
 //
 // All the DECISIONS live in the pure module (anon-pi.ts); this file only does
 // I/O: fs reads/mkdirs, the netcage query, the spawn, and the TTY discipline.
@@ -14,11 +14,12 @@ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, write
 import { readSync } from 'node:fs';
 import { spawnSync, execFileSync } from 'node:child_process';
 import { join, dirname, resolve } from 'node:path';
-import { AnonPiError, HELP, MODELS_FILE, SETTINGS_FILE, SETTINGS_SEED_FILE, SEED_MARKER, DEFAULT_MACHINE, envFromProcess, buildMenuChoiceList, buildMenuEntries, builtinProjectsRoot, deriveProjectUsage, expandTilde, findingsFromNetcageDetect, processNoteFromNetcageDetect, resolveNetcageGraphroot, globalModelsSeedPath, globalSettingsSeedPath, machineAgentDir, machineDir, machineHomeDir, machineJsonPath, machineModelsSeedPath, machineSessionsDir, mergeModelSelection, resolveModelsSeedPath, resolveSettingsSeedPath, validateName, resolveDeleteHome, resolveDeleteProject, parseConfigJson, parseLaunchArgs, parseForwardArgs, parsePortsArgs, parsePortArg, parseKeptKey, keyProject, resolveManagedMatches, parseNetcagePsJson, parseNetcagePortsJson, forwardablePorts, formatPortsHint, isHeadlessPiArgs, resumeSessionId, sessionHeaderCwd, anonPiVersion, parseMachineArgs, parseMachineJson, projectHostDir, resolveAnonPiHome, resolveLlm, resolveProjectsRoot, resolveProxy, resolveRunPlan, resolveRunVsStart, serializeMachineJson, snapshotImageRef, snapshotSessionGroups, copyIncludesForHomeMinusSessions, serializeConfigJson, setImageWarning, keptContainerKey, DEFAULT_SOCKS_PROBE_PORTS, SOCKS5_METHOD_SELECTOR, formatProxyFindings, interpretSocks5Handshake, initImageMenu, generateModelsJson, generateModelSelection, pickLocalProviderModels, parseModelsListing, mergeModelSources, resolveHostModelsPath, LOCAL_PROVIDER_API_KEY, parseVerifyExitIp, processHint, socks5hUrl, hostPortKey, shippedDockerfilePath, shippedWebveilDockerfilePath, } from './anon-pi.js';
-// The netcage label anon-pi stamps its launch-identity key onto (keptContainerKey)
-// so a `--keep` re-entry can find and `netcage start` the same kept container.
-// netcage's `netcage.managed` label marks it a managed container; this adds the
-// anon-pi identity ON TOP (netcage's label IS the registry; anon-pi adds no file).
+import { AnonPiError, HELP, MODELS_FILE, SETTINGS_FILE, SETTINGS_SEED_FILE, SEED_MARKER, DEFAULT_MACHINE, envFromProcess, buildMenuChoiceList, buildMenuEntries, builtinProjectsRoot, deriveProjectUsage, expandTilde, findingsFromNetcageDetect, processNoteFromNetcageDetect, resolveNetcageGraphroot, globalModelsSeedPath, globalSettingsSeedPath, machineAgentDir, machineDir, machineHomeDir, machineJsonPath, machineModelsSeedPath, machineSessionsDir, mergeModelSelection, resolveModelsSeedPath, resolveSettingsSeedPath, validateName, resolveDeleteHome, resolveDeleteProject, parseConfigJson, parseLaunchArgs, parseForwardArgs, parsePortsArgs, parsePortArg, parseKeptKey, keyProject, resolveManagedMatches, parseNetcagePsJson, parseNetcagePortsJson, forwardablePorts, formatPortsHint, isHeadlessPiArgs, resumeSessionId, sessionHeaderCwd, anonPiVersion, parseMachineArgs, parseMachineJson, projectHostDir, resolveAnonPiHome, resolveLaunchImage, resolveLlm, resolveProjectsRoot, resolveProxy, resolveRunPlan, serializeMachineJson, parseImageArgs, snapshotImageTag, snapshotProvenanceLabels, parseImageProvenance, PROVENANCE_LABEL_SOURCE_MACHINE, snapshotSessionGroups, copyIncludesForHomeMinusSessions, serializeConfigJson, setImageWarning, launchIdentityKey, DEFAULT_SOCKS_PROBE_PORTS, SOCKS5_METHOD_SELECTOR, formatProxyFindings, interpretSocks5Handshake, initImageMenu, generateModelsJson, generateModelSelection, pickLocalProviderModels, parseModelsListing, mergeModelSources, resolveHostModelsPath, LOCAL_PROVIDER_API_KEY, parseVerifyExitIp, processHint, socks5hUrl, hostPortKey, shippedDockerfilePath, shippedWebveilDockerfilePath, } from './anon-pi.js';
+// The netcage label anon-pi stamps its launch-identity key onto (launchIdentityKey)
+// so `forward`/`ports`/`snapshot` can find the RUNNING container by machine +
+// project while it is up. netcage's `netcage.managed` label marks it a managed
+// container; this adds the anon-pi identity ON TOP (netcage's label IS the
+// registry; anon-pi adds no file).
 const ANON_PI_KEY_LABEL = 'anon-pi.key';
 function main(argv) {
     const args = argv.slice(2);
@@ -34,7 +35,13 @@ function main(argv) {
     // and `anon-pi machine --help` show THEIR help, not the global one). Those
     // subcommands route to runInit / runMachine, which print INIT_HELP /
     // MACHINE_HELP respectively.
-    const OWN_HELP_SUBCOMMANDS = new Set(['init', 'machine', 'forward', 'ports']);
+    const OWN_HELP_SUBCOMMANDS = new Set([
+        'init',
+        'machine',
+        'image',
+        'forward',
+        'ports',
+    ]);
     if ((args.includes('--help') || args.includes('-h')) &&
         !OWN_HELP_SUBCOMMANDS.has(args[0] ?? '')) {
         process.stdout.write(HELP);
@@ -46,6 +53,12 @@ function main(argv) {
     if (args[0] === 'machine') {
         return runMachine(args.slice(1));
     }
+    // `image …` is the image-management surface (snapshot/list), dispatched BEFORE
+    // the launch grammar so a bare `image` is never parsed as a project named
+    // "image" (ADR-0003 §1: snapshot moved off `machine` onto this new noun).
+    if (args[0] === 'image') {
+        return runImage(args.slice(1));
+    }
     // The destructive cleanup verbs (replacing the old `--fresh`). Dispatched
     // BEFORE the launch grammar: they are top-level data verbs, not launch flags,
     // each with the confirm/`--yes`/non-TTY discipline. `--delete-home` takes an
@@ -149,8 +162,32 @@ function runLaunch(parsed) {
                 'of your local model. It is the ONE direct hole; all other egress stays\n' +
                 'forced through the proxy.');
         }
-        // The machine's image: machine.json wins, ANON_PI_IMAGE is the fallback.
-        const image = machineConf.image ?? env.image ?? '';
+        // The machine's image, highest-priority first: the EPHEMERAL per-launch
+        // `-i`/`--image` override > machine.json.image > ANON_PI_IMAGE. `-i` is
+        // strictly ephemeral (it is NEVER written back to machine.json; that pin is
+        // `machine set-image` / `machine create --image`) and no mismatch warning is
+        // printed (ADR-0003 section 3). `-i` picks the IMAGE; `-m` picks the HOME;
+        // they compose.
+        const iSet = (parsed.image ?? '').trim().length > 0;
+        const home = machineHomeDir(env, machineName);
+        // A fresh (unseeded) home has no established image/home baseline yet.
+        // Seeding it from the ephemeral `-i` image would poison the home with the
+        // wrong-image seed; skipping the seed would run pi unconfigured. So refuse
+        // and channel "make this the machine's image" to the explicit machine verb.
+        // (An ALREADY-SEEDED home just runs the override image against it; the
+        // runtime extension-compat risk is accepted silently, ADR-0003.)
+        if (iSet && homeFresh(home)) {
+            throw new AnonPiError(`anon-pi: machine ${JSON.stringify(machineName)} has no home yet; \`-i\` is ` +
+                `ephemeral (it never seeds the home).\n` +
+                `Establish its image first with \`anon-pi machine create ${machineName} ` +
+                `--image ${parsed.image}\` (or launch once normally to seed), then use ` +
+                `\`-i\` to override per-launch.`);
+        }
+        const image = resolveLaunchImage({
+            override: parsed.image,
+            machineImage: machineConf.image,
+            envImage: env.image,
+        }) ?? '';
         // --mount re-roots at a HOST parent; otherwise the resolved projects root.
         // Expand a leading `~` + absolutize the mount path so it is a real host dir
         // everywhere it is used (the mount, the mkdir, the intent). path.resolve
@@ -164,7 +201,6 @@ function runLaunch(parsed) {
             machine: machineConf,
             mountParent,
         });
-        const home = machineHomeDir(env, machineName);
         const machine = { name: machineName, home, image };
         // The local-model models.json + settings seed for this machine's FRESH-home
         // promotion. GLOBAL by default (<home>/models.json, shared across every
@@ -179,7 +215,6 @@ function runLaunch(parsed) {
             project: parsed.project,
             mountParent,
             piArgs: parsed.piArgs,
-            keep: parsed.keep,
             proxy,
             llmDirect: llm,
             modelsSeed,
@@ -237,10 +272,10 @@ function runLaunch(parsed) {
 }
 /**
  * Execute a RESOLVED non-menu LaunchPlan: create the host dirs the mounts need,
- * then run netcage (or `netcage start` a matching kept container under --keep).
- * Shared by the direct launch path (runLaunch) and the menu dispatch (runMenu),
- * so a menu-picked project/here/shell launches BYTE-FOR-BYTE identically to the
- * same command typed directly.
+ * then run netcage (always a fresh throwaway `run`; ADR-0004). Shared by the
+ * direct launch path (runLaunch) and the menu dispatch (runMenu), so a
+ * menu-picked project/here/shell launches BYTE-FOR-BYTE identically to the same
+ * command typed directly.
  */
 function executeLaunchPlan(intent, plan) {
     // Create the host dirs the mounts need BEFORE spawn: the machine home and,
@@ -258,26 +293,12 @@ function executeLaunchPlan(intent, plan) {
         // has a real dir to cwd into).
         mkdirSync(intent.mountParent ?? intent.projectsRoot, { recursive: true });
     }
-    // The anon-pi identity key, stamped on EVERY launch (not just --keep) as an
-    // additive netcage label. Under --keep it lets a re-entry find + `netcage
-    // start` the kept container; on a throwaway --rm run it lets `anon-pi forward`
+    // The anon-pi identity key, stamped on EVERY launch as an additive netcage
+    // label. On a throwaway `--rm` run it lets `anon-pi forward`/`ports`/`snapshot`
     // find the RUNNING container while it is up (the label goes away with the
     // container on exit). It touches NO egress flag (the RunPlan owns those).
-    const keyed = withKeyLabel(plan.netcageArgs, keptContainerKey(intent));
-    // Run-vs-start: under --keep, ask netcage for its kept managed containers and
-    // resume a matching one via `netcage start`; else run the composed argv. A
-    // throwaway (`--rm`) launch is always a fresh run (the pure rule never
-    // consults the listing for it).
-    if (intent.keep) {
-        const decision = resolveRunVsStart(intent, queryKeptContainers());
-        if (decision.action === 'start') {
-            return spawnNetcage(['start', '-a', '-i', decision.ref], {
-                enteringJail: true,
-            });
-        }
-        // A fresh `--keep` run: the RunPlan already omits --rm so it is left kept.
-        return spawnNetcage(keyed, { enteringJail: true });
-    }
+    const keyed = withKeyLabel(plan.netcageArgs, launchIdentityKey(intent));
+    // Every launch is a fresh throwaway `run` (the RunPlan always carries --rm).
     return spawnNetcage(keyed, { enteringJail: true });
 }
 // --- the interactive host-side menu (the ONLY untested I/O) -------------------
@@ -524,8 +545,6 @@ function runMachine(machineArgs) {
                 return machineSetImage(env, cmd.name, cmd.image);
             case 'rm':
                 return machineRm(env, cmd.name, cmd.yes);
-            case 'snapshot':
-                return machineSnapshot(env, cmd.name, cmd.machine, cmd.imageTag);
         }
     }
     catch (e) {
@@ -564,6 +583,28 @@ function machineCreate(env, name, image) {
     writeFileSync(machineJsonPath(env, name), serializeMachineJson({ image: pinned }));
     process.stdout.write(`anon-pi: created machine ${JSON.stringify(name)} (image ${pinned.trim()}) at ${dir}.\n` +
         `Its home is seeded on first launch, e.g. \`anon-pi -m ${name} --shell\`.\n`);
+    // PROVENANCE-AWARE (ADR-0003 §5): if the pinned image was produced by
+    // `image snapshot` (it carries `anon-pi.source-machine=<M>`) AND that source
+    // machine's home still exists on disk, OFFER the home-copy (minus sessions) +
+    // per-project session carry-over from it, so a machine built from a snapshot
+    // inherits the source's config + conversations (opt-in). Absent provenance /
+    // source home gone => a plain fresh create (today's behaviour) with a quiet
+    // note. Guarded no-TTY inside carryOverHomeFromMachine (copy nothing). This
+    // reads the image via netcage inspect; when netcage is absent it is skipped
+    // (a create must not require netcage), so provenance carry-over is best-effort.
+    if (hasNetcage()) {
+        const prov = inspectImageProvenance(pinned.trim());
+        const source = prov.sourceMachine;
+        if (source !== undefined && existsSync(machineHomeDir(env, source))) {
+            process.stderr.write(`anon-pi: image ${pinned.trim()} was snapshotted from machine ${JSON.stringify(source)} ` +
+                '(whose home is present); offering to carry its home + conversations over.\n');
+            carryOverHomeFromMachine(env, source, name);
+        }
+        else if (source !== undefined) {
+            process.stderr.write(`anon-pi: image ${pinned.trim()} names source machine ${JSON.stringify(source)}, ` +
+                'but its home is gone; created a fresh home.\n');
+        }
+    }
     return 0;
 }
 /**
@@ -635,29 +676,63 @@ function machineRm(env, name, yes) {
     process.stdout.write(`anon-pi: removed machine ${JSON.stringify(name)} (${dir}).\n`);
     return 0;
 }
+// --- the `image` verbs (ADR-0003): snapshot a running container into a clean
+// image tag with provenance labels, and a read-only list. Thin I/O over the
+// pure parts (parseImageArgs / snapshotImageTag / snapshotProvenanceLabels /
+// parseImageProvenance); netcage does the commit / images / inspect.
 /**
- * `machine snapshot <new-name> [-m <machine>] [--image-tag <ref>]`: commit a
- * RUNNING jailed container into a new image and create <new-name> pinned to it.
- * The user does interactive system work in a session (e.g. `sudo apt install`),
- * then, WITHOUT having exited (the default `--rm` would have destroyed the
- * container), preserves that exact environment as a new machine. The container
- * to commit is AUTO-DETECTED from the running anon-pi containers (a picker when
- * several are up); `-m <machine>` is an OPTIONAL filter, not a required source.
- * podman pauses the container during commit and unpauses, so the live session
- * survives. The new machine gets a FRESH home (image and home are orthogonal;
- * snapshot keeps the SOFTWARE, not the conversations). Forced egress is
- * untouched: commit is a local podman op, and the snapshot machine relaunches
- * through the same forced-egress jail.
+ * Parse `image <verb> …` (pure parseImageArgs) and dispatch to the snapshot /
+ * list I/O. Prints IMAGE_HELP on `--help`/`-h`.
  */
-function machineSnapshot(env, name, machine, imageTag) {
-    // Refuse to clobber an existing target machine FIRST (before netcage / any
-    // commit), so a name clash fails fast and never leaves an orphan image.
-    // Mirrors machine create.
-    const targetDir = machineDir(env, name);
-    if (existsSync(targetDir)) {
-        process.stderr.write(`anon-pi: machine ${JSON.stringify(name)} already exists (${targetDir}). ` +
-            'Pick a different <new-name> or `anon-pi machine rm` it first.\n');
-        return 1;
+function runImage(imageArgs) {
+    if (imageArgs.includes('--help') || imageArgs.includes('-h')) {
+        process.stdout.write(IMAGE_HELP);
+        return 0;
+    }
+    const env = envFromProcess(process.env);
+    let cmd;
+    try {
+        cmd = parseImageArgs(imageArgs);
+    }
+    catch (e) {
+        return reportAnonPiError(e);
+    }
+    try {
+        switch (cmd.verb) {
+            case 'snapshot':
+                return imageSnapshot(env, cmd.name, cmd.machine, cmd.createMachine);
+            case 'list':
+                return imageList();
+        }
+    }
+    catch (e) {
+        return reportAnonPiError(e);
+    }
+}
+/**
+ * `image snapshot <name> [-m <machine>] [--create-machine <m>]`: commit the
+ * RUNNING jailed container into the clean tag `anon-pi/<name>:latest`, baking
+ * provenance as podman LABELS via `netcage commit -c 'LABEL …'` (ADR-0003 §1+2).
+ * The container to commit is AUTO-DETECTED from the running anon-pi containers
+ * (a picker when several are up); `-m <machine>` is an OPTIONAL filter, not a
+ * required source. podman pauses the container during commit and unpauses, so
+ * the live session survives. A same-name re-snapshot OVERWRITES the `:latest`
+ * tag (the previous image becomes dangling but keeps its provenance label).
+ * `--create-machine <m>` ALSO creates machine <m> from the fresh snapshot,
+ * running the home-copy + per-project session carry-over. Forced egress is
+ * untouched (commit is a local podman op).
+ */
+function imageSnapshot(env, name, machine, createMachine) {
+    // If --create-machine names an EXISTING machine, refuse FIRST (before netcage /
+    // any commit), so a name clash fails fast (mirrors machine create). The
+    // snapshot itself has no such clash: it overwrites its `:latest` tag by design.
+    if (createMachine !== undefined) {
+        const targetDir = machineDir(env, createMachine);
+        if (existsSync(targetDir)) {
+            process.stderr.write(`anon-pi: machine ${JSON.stringify(createMachine)} already exists (${targetDir}). ` +
+                'Pick a different --create-machine name or `anon-pi machine rm` it first.\n');
+            return 1;
+        }
     }
     if (!hasNetcage())
         return netcageMissing();
@@ -666,38 +741,102 @@ function machineSnapshot(env, name, machine, imageTag) {
     const target = resolveRunningContainer(machine, 'snapshot');
     if (target === undefined)
         return 1;
-    const imageRef = imageTag ?? snapshotImageRef(name, new Date());
-    process.stderr.write(`anon-pi: committing ${target.name} -> image ${imageRef} (pausing the container briefly)\u2026\n`);
-    const committed = spawnNetcage(['commit', target.ref, imageRef]);
+    const tag = snapshotImageTag(name);
+    // Provenance (ADR-0003 §2), all best-effort HISTORY:
+    //  - source-machine: the committed container's machine, from its stamped key
+    //    (parseKeptKey.machine, authoritative).
+    //  - source-image: what the snapshot is ACTUALLY built on, read from the
+    //    RUNNING CONTAINER via inspect (NOT machine.json: `-i` makes the container's
+    //    image diverge from the machine's pin). Fall back to machine.json.image if
+    //    the inspect misses; OMIT the label if neither is known.
+    //  - snapshot-at: now, ISO 8601.
+    const sourceMachine = parseKeptKey(target.key).machine;
+    const sourceImage = inspectContainerImage(target.ref) ??
+        (sourceMachine !== undefined
+            ? readMachineJson(env, sourceMachine).image
+            : undefined);
+    const labels = snapshotProvenanceLabels({
+        sourceMachine,
+        sourceImage,
+        at: new Date().toISOString(),
+    });
+    process.stderr.write(`anon-pi: committing ${target.name} -> image ${tag} (pausing the container briefly)\u2026\n`);
+    // One `-c 'LABEL k=v'` per provenance label (each is one argv element; podman
+    // round-trips `/` and `:` in the value un-quoted, verified).
+    const commitArgs = ['commit'];
+    for (const label of labels)
+        commitArgs.push('-c', label);
+    commitArgs.push(target.ref, tag);
+    const committed = spawnNetcage(commitArgs);
     if (committed !== 0) {
-        process.stderr.write(`anon-pi: netcage commit failed; machine ${JSON.stringify(name)} NOT created.\n`);
+        process.stderr.write(`anon-pi: netcage commit failed; image ${tag} NOT written.\n`);
         return committed;
     }
-    // Create the machine pinned to the committed image.
-    mkdirSync(machineHomeDir(env, name), { recursive: true });
-    writeFileSync(machineJsonPath(env, name), serializeMachineJson({ image: imageRef }));
-    // The source machine is the machine of the container we committed (its stamped
-    // key carries it). Copy its home into the new machine's home, EXCEPT the
-    // sessions subtree (conversations are handled separately below). Copying the
-    // config/extensions is safe + preferable to a fresh seed here: the new image IS
-    // the committed source filesystem, so the home's extensions/binaries are
-    // correct-for-the-new-image (and the copied seed marker means no reseed).
-    const sourceMachine = parseKeptKey(target.key).machine;
-    if (sourceMachine !== undefined) {
-        copyHomeMinusSessions(env, sourceMachine, name);
-    }
-    process.stdout.write(`anon-pi: snapshotted ${target.name} into machine ${JSON.stringify(name)} ` +
-        `(image ${imageRef}) at ${targetDir}.\n` +
+    process.stdout.write(`anon-pi: snapshotted ${target.name} into image ${tag}` +
         (sourceMachine !== undefined
-            ? `Copied ${JSON.stringify(sourceMachine)}'s home (config + extensions) into it.\n`
-            : 'Its home seeds fresh on first launch.\n'));
-    // Offer the source's conversation history, grouped by project, opt-in per
-    // project (default none). TTY only; a non-TTY snapshot carries no sessions.
-    if (sourceMachine !== undefined) {
-        carryOverSessions(env, sourceMachine, name);
+            ? ` (from machine ${JSON.stringify(sourceMachine)}).\n`
+            : '.\n'));
+    // --create-machine: create the machine from the fresh snapshot, running the
+    // same home-copy + per-project session carry-over the 0.15 snapshot did. The
+    // source machine is directly known (we just committed its container), so the
+    // shared helper is called with it.
+    if (createMachine !== undefined) {
+        mkdirSync(machineHomeDir(env, createMachine), { recursive: true });
+        writeFileSync(machineJsonPath(env, createMachine), serializeMachineJson({ image: tag }));
+        process.stdout.write(`anon-pi: created machine ${JSON.stringify(createMachine)} pinned to ${tag}.\n`);
+        if (sourceMachine !== undefined) {
+            carryOverHomeFromMachine(env, sourceMachine, createMachine);
+        }
+        else {
+            process.stderr.write('anon-pi: the committed container has no source machine; the new home seeds fresh on first launch.\n');
+        }
+    }
+    return 0;
+}
+/**
+ * `image list`: read-only; list anon-pi images with their provenance. ZERO
+ * stored state. Includes an image if it is `anon-pi/*`-tagged OR (even when
+ * DANGLING/untagged) it carries an `anon-pi.source-machine` label, so an
+ * ORPHANED snapshot (its `:latest` tag overwritten by a re-snapshot) is still
+ * shown by its ID. Prints `<name-or-<none>>  from machine <M>  <when>  id:<short>`.
+ */
+function imageList() {
+    if (!hasNetcage())
+        return netcageMissing();
+    const images = queryAnonPiImages();
+    if (images.length === 0) {
+        process.stdout.write('anon-pi: no anon-pi images yet. Create one with `anon-pi image snapshot <name>`.\n');
+        return 0;
+    }
+    for (const img of images) {
+        const prov = parseImageProvenance(img.labels);
+        const nameCol = img.tag ?? '<none>';
+        const fromCol = prov.sourceMachine !== undefined
+            ? `from machine ${prov.sourceMachine}`
+            : 'from machine <unknown>';
+        const whenCol = prov.snapshotAt ?? '<unknown>';
+        const idCol = `id:${img.id.slice(0, 12)}`;
+        process.stdout.write(`${nameCol}  ${fromCol}  ${whenCol}  ${idCol}\n`);
     }
     return 0;
 }
+/**
+ * Shared home carry-over from a source machine to a dest machine (ADR-0003): the
+ * home-minus-sessions copy (copyHomeMinusSessions) + the interactive per-project
+ * session picker (carryOverSessions). Both the `image snapshot --create-machine`
+ * path and the provenance-aware `machine create --image` path call this; they
+ * differ ONLY in how they learn `sourceMachine`. Honors the no-TTY "copy
+ * nothing" rule already in carryOverSessions (a scripted create stays
+ * non-blocking). A no-op message-wise when the source home is absent.
+ */
+function carryOverHomeFromMachine(env, sourceMachine, destMachine) {
+    if (existsSync(machineHomeDir(env, sourceMachine))) {
+        copyHomeMinusSessions(env, sourceMachine, destMachine);
+        process.stderr.write(`anon-pi: copied ${JSON.stringify(sourceMachine)}'s home (config + extensions) into ` +
+            `${JSON.stringify(destMachine)} (minus conversations).\n`);
+    }
+    carryOverSessions(env, sourceMachine, destMachine);
+}
 /**
  * Recursively copy machine <source>'s home into machine <dest>'s home, EXCLUDING
  * the `.pi/agent/sessions/` subtree (conversations are carried over separately,
@@ -1794,29 +1933,50 @@ USAGE
   anon-pi machine list                            list machines and their images
   anon-pi machine set-image <name> <ref>          re-pin the image (WARNS; no reseed)
   anon-pi machine rm <name> [--yes]               delete the machine + its home
-  anon-pi machine snapshot <new-name> [-m <machine>] [--image-tag <ref>]
-                                                  commit a RUNNING container into a
-                                                  new image + create <new-name>
 
 A machine is an image + a persistent host home (machines/<name>/{machine.json,home/}).
 The home is seeded on FIRST LAUNCH, not at create. \`set-image\` re-pins only and
 warns (the home was built for the old image); \`rm\` confirms on a TTY, skips with
 \`--yes\`, and aborts non-interactively without it.
 
+\`create --image <ref>\` is PROVENANCE-AWARE: if <ref> was produced by
+\`anon-pi image snapshot\` (it carries an \`anon-pi.source-machine\` label) AND
+that machine's home still exists, you are OFFERED its home + conversations to
+carry over (opt-in, no TTY => nothing copied). Otherwise a plain fresh create.
+
+To SNAPSHOT a running container into an image, use \`anon-pi image snapshot\`
+(the verb moved off \`machine\` onto the \`image\` noun).
+`;
+/** The `image` subcommand help. */
+const IMAGE_HELP = `anon-pi image - snapshot a running container into an image, and list anon-pi images
+
+USAGE
+  anon-pi image snapshot <name> [-m <machine>] [--create-machine <m>]
+                                 commit the RUNNING container into anon-pi/<name>:latest
+  anon-pi image list             list anon-pi images with their provenance (read-only)
+
 \`snapshot\` captures the CURRENT filesystem of a RUNNING jailed container (e.g.
-after \`sudo apt install\`) into a new image and creates <new-name> pinned to it,
-so you can preserve an environment you built interactively WITHOUT having
-pre-decided \`--keep\`. The container is auto-detected from the running anon-pi
-containers (a picker when several are up); \`-m <machine>\` is an OPTIONAL filter,
-not a required source. The container must still be RUNNING (do not exit the
-session); podman pauses it briefly during the commit. Same forced-egress jail on
-relaunch.
+after \`sudo apt install\`) into the clean tag \`anon-pi/<name>:latest\`, baking
+provenance as podman labels (source machine, source image, snapshot time). This
+is how you keep container-level system changes (every launch is throwaway):
+freeze the running box into a named image, then pin a machine to it. The
+container is auto-detected from the running anon-pi containers (a picker when
+several are up); \`-m <machine>\` is an OPTIONAL filter, not a required source.
+The container must still be RUNNING (do not exit the session); podman pauses it
+briefly during the commit. A same-name re-snapshot OVERWRITES the \`:latest\` tag
+(the previous image becomes dangling but keeps its provenance, so \`image list\`
+still shows it by ID). To preserve a specific snapshot, snapshot it under a
+different name.
+
+\`--create-machine <m>\` ALSO creates machine <m> pinned to the fresh snapshot,
+copying the source machine's HOME (config + extensions + dotfiles) MINUS its
+conversations, then offering the conversations separately (grouped BY PROJECT,
+opt-in per project, default SKIP; no TTY => none copied). This is equivalent to
+\`image snapshot\` followed by a provenance-aware \`machine create --image\`.
 
-The source machine's HOME is copied into the new machine (config + extensions +
-dotfiles), MINUS its conversations. Conversations are offered separately, grouped
-BY PROJECT, opt-in per project (default SKIP), COPY or SKIP each (no TTY => none
-copied). After copying, one confirmed step (default No) can DELETE the copied
-groups from the source machine (the only "move"); COPY never touches the source.
+\`list\` reads the provenance labels straight off the images (ZERO stored state):
+it shows every \`anon-pi/*\` image plus any dangling image still carrying an
+\`anon-pi.source-machine\` label (an orphaned snapshot), by its ID.
 `;
 // --- impure helpers ---------------------------------------------------------
 /** Read + parse <anon-pi-home>/config.json (tolerant: absent/garbage => {}). */
@@ -1848,23 +2008,9 @@ function homeFresh(machineHome) {
     const marker = join(machineHome, '.pi', 'agent', SEED_MARKER);
     return !existsSync(marker);
 }
-/**
- * Query netcage for its KEPT managed containers, surfacing each one's stamped
- * anon-pi identity key so the pure run-vs-start decision can match it. Thin,
- * best-effort I/O: on any failure (netcage missing the query, no containers, a
- * parse error) it returns an EMPTY listing, so the decision falls back to a
- * fresh `run` (safe: it never wrongly resumes, it just creates a new container).
- */
-function queryKeptContainers() {
-    // Ask netcage for ALL its managed containers as JSON (netcage >= 0.10.0
-    // forwards podman's --format json over its managed scope), then keep the ones
-    // carrying an anon-pi.key label (a sidecar has none) and decode it. -a so a
-    // STOPPED kept container is included (run-vs-start resumes it).
-    return queryManagedContainers({ all: true }).map(({ key, ref }) => ({ key, ref }));
-}
 /**
  * Decode a base64 anon-pi.key label back to its identity key (the reverse of
- * withKeyLabel's encode; keptContainerKey embeds newlines, so it is base64'd to
+ * withKeyLabel's encode; launchIdentityKey embeds newlines, so it is base64'd to
  * stay a single safe label value). undefined on a decode error.
  */
 function decodeKeyLabel(raw) {
@@ -1921,6 +2067,138 @@ function queryNetcagePorts(ref) {
         return [];
     return parseNetcagePortsJson(res.stdout);
 }
+// --- `image`: read a container/image's provenance from netcage inspect --------
+/**
+ * Best-effort: the image ref a RUNNING container is ACTUALLY built on, via
+ * `netcage inspect <ref> --format '{{.ImageName}}'`. Used to bake the
+ * `anon-pi.source-image` label (the container's image can diverge from the
+ * machine's pin when `-i` was passed). undefined on any miss (older netcage, a
+ * parse/format hiccup): the caller falls back to machine.json.image, then omits
+ * the label. NEVER throws.
+ */
+function inspectContainerImage(ref) {
+    const res = spawnSync('netcage', ['inspect', ref, '--format', '{{.ImageName}}'], { encoding: 'utf8' });
+    if (res.error || res.status !== 0 || !res.stdout)
+        return undefined;
+    const out = res.stdout.trim();
+    return out === '' || out === '<no value>' ? undefined : out;
+}
+/**
+ * Best-effort: the anon-pi provenance an IMAGE ref carries, via `netcage inspect
+ * <ref> --format '{{json .Config.Labels}}'` parsed through the pure
+ * parseImageProvenance. Used by provenance-aware `machine create`. Empty
+ * provenance (all fields undefined) on any miss (older netcage, no labels, a
+ * parse hiccup). NEVER throws.
+ */
+function inspectImageProvenance(ref) {
+    const labels = inspectLabels(ref);
+    return parseImageProvenance(labels);
+}
+/**
+ * Best-effort: an image/container's label map via `netcage inspect <ref>
+ * --format '{{json .Config.Labels}}'`. null on any miss / unparseable output, so
+ * the pure parseImageProvenance sees an absent map (all fields undefined).
+ */
+function inspectLabels(ref) {
+    const res = spawnSync('netcage', ['inspect', ref, '--format', '{{json .Config.Labels}}'], { encoding: 'utf8' });
+    if (res.error || res.status !== 0 || !res.stdout)
+        return null;
+    const text = res.stdout.trim();
+    if (text === '' || text === 'null' || text === '<no value>')
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        return parsed !== null && typeof parsed === 'object'
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Best-effort: the anon-pi images in netcage's store for `image list`. Reads
+ * `netcage images --format json`, keeps an image if it is `anon-pi/*`-tagged OR
+ * (even dangling/untagged) it carries an `anon-pi.source-machine` label (so an
+ * orphaned snapshot is still shown by its ID), reading each candidate's labels
+ * via inspect. ZERO stored state. [] on any failure (older netcage, a parse
+ * miss), so `image list` reports "no images" cleanly rather than crashing.
+ */
+function queryAnonPiImages() {
+    const res = spawnSync('netcage', ['images', '--format', 'json'], {
+        encoding: 'utf8',
+    });
+    if (res.error || res.status !== 0 || !res.stdout)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(res.stdout);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const raw of parsed) {
+        if (raw === null || typeof raw !== 'object')
+            continue;
+        const rec = raw;
+        const id = firstString(rec['Id'], rec['ID'], rec['id']);
+        if (id === undefined || seen.has(id))
+            continue;
+        const tags = imageTags(rec);
+        const anonTag = tags.find((t) => t.startsWith('anon-pi/'));
+        // An anon-pi/*-tagged image always qualifies; else inspect it for the
+        // source-machine label (an orphaned/dangling snapshot still qualifies).
+        if (anonTag === undefined) {
+            if (tags.length > 0)
+                continue; // a non-anon-pi tagged image is never ours.
+            const labels = inspectLabels(id);
+            if (labels === null ||
+                typeof labels[PROVENANCE_LABEL_SOURCE_MACHINE] !== 'string')
+                continue;
+            seen.add(id);
+            out.push({ id, labels });
+            continue;
+        }
+        seen.add(id);
+        out.push({ id, tag: anonTag, labels: inspectLabels(id) });
+    }
+    return out;
+}
+/** First defined string among the candidates (tolerant field-name reader). */
+function firstString(...vals) {
+    for (const v of vals) {
+        if (typeof v === 'string' && v.trim() !== '')
+            return v;
+    }
+    return undefined;
+}
+/**
+ * The repository tags on an image record, tolerant of netcage/podman's field
+ * shapes: `Names`/`RepoTags`/`Tags` (an array of `repo:tag`), or a single
+ * `Repository`+`Tag` pair. `<none>:<none>` entries (dangling) are dropped.
+ */
+function imageTags(rec) {
+    const tags = [];
+    for (const key of ['Names', 'RepoTags', 'Tags']) {
+        const v = rec[key];
+        if (Array.isArray(v)) {
+            for (const t of v) {
+                if (typeof t === 'string' && t !== '' && !t.startsWith('<none>'))
+                    tags.push(t);
+            }
+        }
+    }
+    const repo = firstString(rec['Repository']);
+    const tag = firstString(rec['Tag']);
+    if (repo !== undefined && repo !== '<none>' && tag !== undefined) {
+        tags.push(`${repo}:${tag}`);
+    }
+    return tags;
+}
 /**
  * Resolve the ONE running anon-pi container a forward/ports should act on:
  * filter the running managed containers by machine (+ project if given), then
@@ -2147,9 +2425,10 @@ function netcageMissing() {
 }
 /**
  * Insert the anon-pi identity label into a `netcage run` argv (right after
- * `run`), so a kept container can be found on re-entry. The key is base64'd
- * (keptContainerKey embeds newlines) to keep it a single safe label value. This
- * is ADDITIVE and touches NO egress flag (the RunPlan owns --proxy/--allow-direct).
+ * `run`), so `forward`/`ports`/`snapshot` can find the RUNNING container by
+ * machine + project. The key is base64'd (launchIdentityKey embeds newlines) to
+ * keep it a single safe label value. This is ADDITIVE and touches NO egress flag
+ * (the RunPlan owns --proxy/--allow-direct).
  */
 function withKeyLabel(netcageArgs, key) {
     const enc = Buffer.from(key, 'utf8').toString('base64');