anon-pi 0.14.0 → 0.16.0

package/src/anon-pi.ts

@@ -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';
@@ -427,16 +428,33 @@ 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: readonly string[] = ['.', '..', '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: readonly string[] = [
+	'.',
+	'..',
+	'pi',
+	'machine',
+	'image',
+	'init',
+	'forward',
+	'ports',
+];
 // NOTE: `pi` is reserved so the `anon-pi pi <args…>` passthrough token
-// (PI_PASSTHROUGH_TOKEN) can never be shadowed by a project named `pi`.
+// (PI_PASSTHROUGH_TOKEN) can never be shadowed by a project named `pi`; the
+// subcommand nouns are reserved so a same-named folder is never an unreachable
+// shadow of a dispatched verb.
 
 /** What a name names, for a clear validation error. */
 export type NameKind = 'machine' | 'project';
@@ -535,7 +553,7 @@ export function resolveCwd(kind: RootKind, token: string): string {
  * 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(
@@ -703,6 +721,32 @@ 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: {
+	/** The per-launch `-i`/`--image` override (ParsedLaunch.image), if given. */
+	override?: string;
+	/** The machine's pinned image (machine.json.image), if set. */
+	machineImage?: string;
+	/** The `ANON_PI_IMAGE` env fallback, if set. */
+	envImage?: string;
+}): string | undefined {
+	return (
+		nonEmpty(args.override) ??
+		nonEmpty(args.machineImage) ??
+		nonEmpty(args.envImage)
+	);
+}
+
 // --- The per-machine RunPlan resolver ----------------------------------------
 //
 // The heart of the machines+projects rework: given a resolved launch intent
@@ -771,12 +815,6 @@ export interface LaunchIntent {
 	mountParent?: string;
 	/** Extra args forwarded to `pi` (headless/one-shot). Ignored for shell. */
 	piArgs?: string[];
-	/**
-	 * `--keep`: omit `--rm` so the container is left KEPT (its filesystem
-	 * survives the apt-install/re-enter flow). Default (false) => `--rm`
-	 * (throwaway); the machine home persists regardless (it is a host mount).
-	 */
-	keep?: boolean;
 	/** The resolved socks5h proxy (REQUIRED; the resolver fails closed without it). */
 	proxy: string;
 	/** The resolved local-model direct target (REQUIRED: the one --allow-direct hole). */
@@ -837,9 +875,10 @@ export const DEFAULT_MACHINE = 'default';
  * project): the CLI runs the host-side menu. `pi`/`shell` carry the chosen
  * target. `project` is a validated project name, the `.` root token, or
  * undefined (menu / bare shell, which lands at the active root). `mountParent` is the `--mount` HOST parent
- * (a path, NOT a name-namespaced token). `keep` is `--keep` (default false =>
- * throwaway `--rm`). `piArgs` are the trailing tokens forwarded to pi (pi mode
- * only; undefined otherwise).
+ * (a path, NOT a name-namespaced token). `image` is the ephemeral per-launch
+ * `-i`/`--image` override (undefined when not given). Every launch is throwaway
+ * (`--rm` always; the retired `--keep`/`--rm` flags now error). `piArgs` are the
+ * trailing tokens forwarded to pi (pi mode only; undefined otherwise).
  */
 export interface ParsedLaunch {
 	mode: LaunchMode;
@@ -852,7 +891,16 @@ export interface ParsedLaunch {
 	machineExplicit: boolean;
 	project?: string;
 	mountParent?: string;
-	keep: boolean;
+	/**
+	 * The EPHEMERAL per-launch image override (`-i <ref>` / `--image <ref>`), or
+	 * undefined. Highest priority in the image-resolution chain (see
+	 * resolveLaunchImage): `-i` > machine.json.image > ANON_PI_IMAGE. It NEVER
+	 * mutates machine.json (that persistent pin is `machine set-image` /
+	 * `machine create --image`); `-i` picks the IMAGE for this launch while `-m`
+	 * picks the HOME, and they compose. The ref is passed straight through to
+	 * netcage's private image store: anon-pi does NOT pre-check it or auto-pull.
+	 */
+	image?: string;
 	piArgs?: string[];
 }
 
@@ -1004,6 +1052,28 @@ export function sessionHeaderCwd(headerLine: string): string | undefined {
  */
 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'] as const;
+
+/** PURE: the error message for a retired `--keep`/`--rm` flag, pointing at the image-based replacement. */
+export function retiredKeepRmMessage(flag: string): string {
+	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
@@ -1027,17 +1097,11 @@ function finishPiNoProjectLaunch(args: {
 	machine: string;
 	machineExplicit: boolean;
 	mountParent?: string;
-	keep: boolean;
-	rm: boolean;
+	image?: string;
 	shell: boolean;
 	piArgs: string[];
 	fail: (msg: string) => never;
 }): ParsedLaunch {
-	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.',
@@ -1049,15 +1113,15 @@ 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`,
@@ -1070,15 +1134,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: readonly string[]): ParsedLaunch {
 	let machine = DEFAULT_MACHINE;
 	let machineSet = false;
 	let shell = false;
 	let mountParent: string | undefined;
-	let keepSeen = false;
-	let rmSeen = false;
+	let image: string | undefined;
 	let project: string | undefined;
 	let piArgs: string[] | undefined;
 
@@ -1106,13 +1169,20 @@ export function parseLaunchArgs(args: readonly string[]): ParsedLaunch {
 			mountParent = v as string;
 			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 as string;
 			continue;
 		}
-		if (a === '--rm') {
-			rmSeen = true;
-			continue;
+		if ((RETIRED_LAUNCH_FLAGS as readonly string[]).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).
@@ -1129,8 +1199,7 @@ export function parseLaunchArgs(args: readonly string[]): ParsedLaunch {
 				machine,
 				machineExplicit: machineSet,
 				mountParent,
-				keep: keepSeen,
-				rm: rmSeen,
+				image,
 				shell,
 				piArgs: args.slice(i + 1),
 				fail,
@@ -1172,8 +1241,7 @@ export function parseLaunchArgs(args: readonly string[]): ParsedLaunch {
 				machine,
 				machineExplicit: machineSet,
 				mountParent,
-				keep: keepSeen,
-				rm: rmSeen,
+				image,
 				shell,
 				piArgs,
 				fail,
@@ -1188,10 +1256,6 @@ export function parseLaunchArgs(args: readonly string[]): ParsedLaunch {
 		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) {
@@ -1207,7 +1271,7 @@ export function parseLaunchArgs(args: readonly string[]): ParsedLaunch {
 			machineExplicit: machineSet,
 			project,
 			mountParent,
-			keep: keepSeen,
+			image,
 		};
 	}
 
@@ -1220,7 +1284,7 @@ export function parseLaunchArgs(args: readonly string[]): ParsedLaunch {
 			machineExplicit: machineSet,
 			project: undefined,
 			mountParent,
-			keep: keepSeen,
+			image,
 		};
 	}
 
@@ -1232,7 +1296,7 @@ export function parseLaunchArgs(args: readonly string[]): ParsedLaunch {
 		machineExplicit: machineSet,
 		project,
 		mountParent,
-		keep: keepSeen,
+		image,
 		piArgs,
 	};
 }
@@ -1247,7 +1311,7 @@ export function parseLaunchArgs(args: readonly string[]): ParsedLaunch {
  *   - 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.
@@ -1316,8 +1380,9 @@ export function resolveRunPlan(
 	const headless = mode === 'pi' && isHeadlessPiArgs(intent.piArgs);
 
 	const netcageArgs: string[] = ['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) netcageArgs.push('-it');
@@ -1404,81 +1469,46 @@ function containerSeedThen(seedVersion: string, exec: string): string {
 	);
 }
 
-// --- The run-vs-start decision for kept (netcage.managed) containers ---------
+// --- The per-launch identity label (for `forward`/`ports`/`snapshot`) --------
 //
-// The exploratory `--keep` flow: run a container, tweak the system (apt install
-// ...), quit, then re-enter with the SAME launch and RESUME it via `netcage
-// start` (the container filesystem survives). Throwaway (`--rm`) is the default
-// and is ALWAYS a fresh `run`.
-//
-// This module owns only the PURE decision: given a resolved LaunchIntent and a
-// SUPPLIED listing of kept containers, decide `start` (a matching kept container
-// is present) vs `run` without `--rm` (absent). The netcage QUERY (how to ask
-// netcage for its labelled containers, e.g. `netcage ps` filtered by the
-// `netcage.managed` label) is the CLI's impure job; the pure rule receives its
-// RESULT (the listing) so the decision stays unit-testable. anon-pi invents NO
-// registry file: netcage's `netcage.managed` label IS the record.
-
-/**
- * A kept `netcage.managed` container, as the CLI's netcage query surfaces it to
- * the pure decision. Only the two fields the DECISION needs are typed:
- *   - `key`: the anon-pi launch-identity key (keptContainerKey) the CLI stamped
- *     onto the container at `run` time (a netcage label / container name) and
- *     reads back from the label; this is what a launch matches against.
- *   - `ref`: how to address the container for `netcage start` (its id or name).
- * The CLI is free to carry more; the pure rule reads only these.
- */
-export interface KeptContainer {
-	/** The anon-pi launch-identity key stamped on the container (keptContainerKey). */
-	key: string;
-	/** The container ref (id or name) to pass to `netcage start`. */
-	ref: string;
-}
-
-/**
- * The run-vs-start decision. `run` = `netcage run` a fresh container (WITHOUT
- * `--rm` under `--keep`, so it is left kept; the run argv itself is
- * resolveRunPlan's job). `start` = `netcage start <ref>` an existing kept
- * container whose identity matches this launch.
- */
-export type RunVsStart = {action: 'run'} | {action: 'start'; ref: string};
-
-/**
- * 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.
+// 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.
  *
- * 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 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.
  *
- * 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 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: LaunchIntent): string {
+export function launchIdentityKey(intent: LaunchIntent): string {
 	const {machine, mode, projectsRoot, project, mountParent} = intent;
 	const mounted = nonEmpty(mountParent) !== undefined;
 	const rootKind: 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}`,
@@ -1488,32 +1518,6 @@ export function keptContainerKey(intent: LaunchIntent): string {
 	].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: LaunchIntent,
-	kept: readonly KeptContainer[],
-): RunVsStart {
-	// 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'};
-}
-
 // --- `forward` / `ports`: reach an in-jail server from the host --------------
 //
 // netcage owns two host-access verbs (>= 0.9.0): `netcage forward <container>
@@ -1522,14 +1526,14 @@ export function resolveRunVsStart(
 // (it reads the sidecar's /proc/net/tcp*, so a minimal image with no ss/netstat/nc
 // still works). anon-pi wraps them so the user never handles the raw netcage
 // container name: it resolves the RUNNING anon-pi container(s) by the identity key
-// it now stamps on EVERY launch (withKeyLabel, not just --keep), disambiguates with
+// it stamps on EVERY launch (withKeyLabel + launchIdentityKey), disambiguates with
 // a picker annotated by the open listeners, and shells out to `netcage forward`.
 // The forced-egress invariant is untouched: `forward` adds no OUTPUT rule (ADR-0014)
 // and `ports` only reads /proc; anon-pi composes neither egress flag here.
 
 /**
- * PURE: the decoded fields of a stamped keptContainerKey (the reverse of
- * keptContainerKey's `k=v\n` record). Used by `forward`/`ports` to filter the
+ * PURE: the decoded fields of a stamped launchIdentityKey (the reverse of
+ * launchIdentityKey's `k=v\n` record). Used by `forward`/`ports` to filter the
  * running managed containers by machine + project WITHOUT reconstructing the
  * exact key (which would couple to launchCwd). Unknown/missing fields are ''.
  */
@@ -1540,7 +1544,7 @@ export interface KeptKeyFields {
 	cwd: string;
 }
 
-/** 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: string): KeptKeyFields {
 	const out: KeptKeyFields = {
 		machine: '',
@@ -1604,7 +1608,7 @@ export function resolveManagedMatches(args: {
  * A RUNNING netcage-managed container the CLI surfaces to the pure forward/ports
  * resolution: its anon-pi identity `key` (stamped label, decoded), the `ref` to
  * pass to `netcage forward`/`ports` (id or name), and a human `name` for the
- * picker. Mirrors KeptContainer with the display name added.
+ * picker.
  */
 export interface ManagedContainer {
 	key: string;
@@ -1821,7 +1825,7 @@ export interface NetcagePsEntry {
  * 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: string,
@@ -2033,6 +2037,71 @@ export function deriveProjectUsage(args: {
 	});
 }
 
+/**
+ * ONE session group a snapshot's `--create-machine` carry-over can offer: a `sessions/<slug>/`
+ * dir in the source home. `project` is the project name when the slug matches a
+ * known project's `projectSessionSlug` (else undefined: an ORPHAN slug with no
+ * matching project, still offered, labelled by its raw slug so nothing hides).
+ * `label` is the human row text. `slug` is the exact dir name to copy/delete.
+ */
+export interface SnapshotSessionGroup {
+	slug: string;
+	project?: string;
+	label: string;
+}
+
+/**
+ * PURE: the cpSync filter predicate for a snapshot's "copy the home MINUS the
+ * sessions subtree" copy: true = copy `src`, false = skip it. It rejects the
+ * sessions dir itself and everything beneath it (`<sessionsDir>` and
+ * `<sessionsDir>/...`), and copies everything else. Extracted so the
+ * home-minus-sessions contract is unit-testable without the fs.
+ */
+export function copyIncludesForHomeMinusSessions(
+	src: string,
+	sessionsDir: string,
+): boolean {
+	return src !== sessionsDir && !src.startsWith(sessionsDir + '/');
+}
+
+/**
+ * PURE: map the session-dir slugs PRESENT under a source machine's `sessions/`
+ * to per-project rows a snapshot's carry-over picker offers. For each present
+ * slug, if it equals `projectSessionSlug(<project>)` for a known project, it is a
+ * PROJECT row (labelled by the project name); otherwise an ORPHAN-slug row
+ * (labelled by the raw slug, so a session with no current project folder is
+ * still shown, never silently dropped). Rows are sorted: named projects first
+ * (case-insensitive by name), then orphan slugs (by slug), for a stable picker.
+ * The caller (CLI) does the actual copy/delete of each chosen slug dir.
+ */
+export function snapshotSessionGroups(args: {
+	presentSlugs: readonly string[];
+	projects: readonly string[];
+}): SnapshotSessionGroup[] {
+	const slugToProject = new Map<string, string>();
+	for (const p of args.projects) {
+		// projectSessionSlug validates the name; a bad project name throws, which is
+		// correct (the projects list comes from real folder names).
+		slugToProject.set(projectSessionSlug(p), p);
+	}
+	const rows: SnapshotSessionGroup[] = args.presentSlugs.map((slug) => {
+		const project = slugToProject.get(slug);
+		return project !== undefined
+			? {slug, project, label: project}
+			: {slug, label: `${slug}  (no current project folder)`};
+	});
+	const lc = (s: string): string => s.toLowerCase();
+	return rows.sort((a, b) => {
+		// named projects before orphan slugs; within each, by their label key.
+		const an = a.project !== undefined ? 0 : 1;
+		const bn = b.project !== undefined ? 0 : 1;
+		if (an !== bn) return an - bn;
+		const ak = lc(a.project ?? a.slug);
+		const bk = lc(b.project ?? b.slug);
+		return ak < bk ? -1 : ak > bk ? 1 : 0;
+	});
+}
+
 /**
  * What ONE selectable menu row launches, so the CLI can dispatch a chosen entry
  * without re-deriving anything:
@@ -2908,18 +2977,15 @@ export function anonPiVersion(): string | undefined {
  *   - `set-image <name> <ref>`: name validated; the new image ref (non-empty).
  *   - `rm <name> [--yes]`: name validated; `yes` skips the confirm (the CLI
  *     still enforces the non-TTY abort when `yes` is false).
- *   - `snapshot <new-name> [-m <machine>] [--image-tag <ref>]`: the sole
- *     positional is the NEW machine name (validated); `-m <machine>` is an
- *     OPTIONAL filter (which running container to commit when several are up),
- *     NOT a required source. The CLI auto-detects the running container (picker
- *     when several match), commits it, and creates <new-name> pinned to it.
+ *
+ * Snapshot moved OFF the `machine` noun to the `image` noun (ADR-0003): see
+ * `parseImageArgs` / ImageCommand.
  */
 export type MachineCommand =
 	| {verb: 'create'; name: string; image?: string}
 	| {verb: 'list'}
 	| {verb: 'set-image'; name: string; image: string}
-	| {verb: 'rm'; name: string; yes: boolean}
-	| {verb: 'snapshot'; name: string; machine?: string; imageTag?: string};
+	| {verb: 'rm'; name: string; yes: boolean};
 
 /**
  * PURE: parse the tokens AFTER `machine` into a MachineCommand. Validates the
@@ -2941,9 +3007,7 @@ export function parseMachineArgs(args: readonly string[]): MachineCommand {
 
 	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);
@@ -3015,15 +3079,67 @@ export function parseMachineArgs(args: readonly string[]): MachineCommand {
 		return {verb: 'rm', name: name as string, yes};
 	}
 
+	return fail(
+		`unknown machine subcommand: ${verb} (create | list | set-image | rm)`,
+	);
+}
+
+// --- the `image` noun (ADR-0003): snapshot a running container into a clean
+// image tag with provenance labels, and a read-only list of anon-pi images. The
+// grammar parse, the clean tag derivation, the provenance-label build, and the
+// label read-back parse are all PURE here; the CLI does the netcage commit /
+// images / inspect I/O.
+
+/**
+ * A parsed `image <verb> …` command (ADR-0003 §1). A discriminated union so the
+ * CLI dispatches on `verb` with already-validated fields:
+ *   - `snapshot <name> [-m <machine>] [--create-machine <m>]`: commit the
+ *     RUNNING container into `anon-pi/<name>:latest`. `name` is a validated
+ *     image name (a safe tag segment). `-m <machine>` is an OPTIONAL filter
+ *     (which running container to commit when several are up), NOT a required
+ *     source. `--create-machine <m>` ALSO creates machine <m> from the fresh
+ *     snapshot (running the home-copy + session carry-over).
+ *   - `list`: no args (read-only; zero stored state).
+ */
+export type ImageCommand =
+	| {verb: 'snapshot'; name: string; machine?: string; createMachine?: string}
+	| {verb: 'list'};
+
+/**
+ * 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: readonly string[]): ImageCommand {
+	const fail = (msg: string): never => {
+		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: string | undefined;
 		let machine: string | undefined;
-		let imageTag: string | undefined;
+		let createMachine: string | undefined;
 		for (let i = 0; i < rest.length; i++) {
 			const a = rest[i];
 			if (a === '-m' || a === '--machine') {
@@ -3032,43 +3148,95 @@ export function parseMachineArgs(args: readonly string[]): MachineCommand {
 				machine = validateName(v as string, '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 as string;
+				if (v === undefined) fail('--create-machine needs a machine name');
+				createMachine = validateName(v as string, '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>');
+		if (name === undefined) fail('image snapshot needs a <name>');
 		return {
 			verb: 'snapshot',
 			name: name as string,
 			machine: nonEmpty(machine),
-			imageTag: nonEmpty(imageTag),
+			createMachine: nonEmpty(createMachine),
 		};
 	}
 
-	return fail(
-		`unknown machine subcommand: ${verb} (create | list | set-image | rm | snapshot)`,
-	);
+	return fail(`unknown image subcommand: ${verb} (snapshot | list)`);
 }
 
 /**
- * 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).
+ * 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 snapshotImageRef(name: string, now: Date): string {
-	const p = (n: number, w = 2): string => 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}`;
+export function snapshotImageTag(name: string): string {
+	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: {
+	sourceMachine?: string;
+	sourceImage?: string;
+	at: string;
+}): string[] {
+	const labels: string[] = [];
+	const push = (key: string, value: string | undefined): void => {
+		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;
+}
+
+/** Provenance read back from a snapshot image's labels (any field may be absent). */
+export interface ImageProvenance {
+	sourceMachine?: string;
+	sourceImage?: string;
+	snapshotAt?: string;
+}
+
+/**
+ * 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: Record<string, unknown> | null | undefined,
+): ImageProvenance {
+	const get = (key: string): string | undefined => {
+		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),
+	};
 }
 
 /**
@@ -3144,26 +3312,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\`.