anon-pi 0.14.0 → 0.16.0

package/README.md

@@ -68,13 +68,14 @@ anon-pi -m <machine> [<p>]     the same, on <machine> (its own image + home + co
 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)
+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
 ```
 
 A `<project>` is a folder under the projects root (mounted at `/projects`; pi's cwd). The token `.` means the root itself (a scratch pi at `/projects`, at `/work` under `--mount`, or at `~` for a shell). A named project is created on the host if it does not exist yet.
 
-Every subcommand carries its own help: `anon-pi --help` (the launch surface), `anon-pi init --help`, and `anon-pi machine --help`.
+Every subcommand carries its own help: `anon-pi --help` (the launch surface), `anon-pi init --help`, `anon-pi machine --help`, and `anon-pi image --help`.
 
 ### Common tasks
 
@@ -93,7 +94,7 @@ Every subcommand carries its own help: `anon-pi --help` (the launch surface), `a
 | A scratch pi not tied to a subfolder | `anon-pi .` |
 | Use a separate anonymized environment | `anon-pi -m <machine> <project>` |
 | Jail pi into a host folder you edit with host tools | `anon-pi --mount <host-parent> <subfolder>` |
-| Install system tools and keep them | `anon-pi --keep --shell` (then `apt install …`) |
+| Install system tools and keep them | `anon-pi --shell` (then `apt install …`), then `anon-pi image snapshot <name>` while it is still running |
 | Add a second machine | `anon-pi machine create <name> --image <ref>` |
 | Reset a machine's conversations | `anon-pi --delete-home [<machine>]` |
 | Delete a project (files + its sessions) | `anon-pi --delete-project <project>` |
@@ -154,7 +155,7 @@ The positional is always the **project** (a numeric name like `3001` is a projec
 anon-pi ports recon      # the container's open in-jail TCP listeners
 ```
 
-`ports` reads the jail's listeners **image-independently** (netcage reads `/proc/net/tcp*` via the sidecar), so it works even for a minimal image with no `ss`/`netstat`/`nc`. An explicit `--port` may name a port that **isn't open yet**: the forward binds the host side immediately and reaches into the jail on the first connection, so you can set it up before the server starts. Forwarding works for both throwaway (`--rm`) and `--keep` containers, for as long as the container is running.
+`ports` reads the jail's listeners **image-independently** (netcage reads `/proc/net/tcp*` via the sidecar), so it works even for a minimal image with no `ss`/`netstat`/`nc`. An explicit `--port` may name a port that **isn't open yet**: the forward binds the host side immediately and reaches into the jail on the first connection, so you can set it up before the server starts. Forwarding works for as long as the container is running (every launch is throwaway, so the window is the session's lifetime).
 
 ### Headless / one-shot
 
@@ -205,19 +206,23 @@ anon-pi -m webveil pi --version    # pi's own version, on a machine
 
 The caveat: `<parent>` is a **host parent directory**, not a single project path. anon-pi mounts the parent and treats the positional as a name under it; it does not mount an arbitrary host folder as the project itself. Use `--mount` when you want a whole host tree available at `/work` (for example your real code checkout's parent), and pick the subfolder as the project.
 
-### Kept vs throwaway (`--rm` / `--keep`)
+### Throwaway always; persist with a snapshot image
 
-The container is **throwaway by default** (`--rm`): it is deleted the moment pi exits. Your machine home and project files persist regardless (they are host mounts); only the container's own scratch filesystem is discarded.
+Every launch is **throwaway**: the container is removed the moment pi (or the shell) exits. Your machine home and project files persist regardless (they are host mounts); only the container's own scratch filesystem is discarded. There is no flag to change this: `--keep` and `--rm` are **gone** (see [Migrating](#migrating-from-040)).
 
-Pass `--keep` for an exploratory flow where the container's filesystem should survive across exits (for example you `apt install` something, quit, and re-enter the same container):
+To preserve system state you set up in a session (for example after you `apt install` something), **snapshot the still-running container into a named image** and pin a machine to it, giving you a real, named, immutable environment instead of a murky mutable pet container:
 
 ```sh
-anon-pi --keep recon       # keep this container; re-entering resumes it
+anon-pi --shell recon                 # a jailed shell; apt install / configure as you like
+# in another terminal, while that session is STILL running:
+anon-pi image snapshot toolbox        # freeze the running container -> anon-pi/toolbox:latest
+anon-pi machine create box --image anon-pi/toolbox:latest   # a machine pinned to it
+anon-pi -m box recon                  # later: launch on the snapshot-pinned machine
 ```
 
-anon-pi finds a kept container by netcage's managed label and `netcage start`s it on re-entry. `--keep` and `--rm` together is an error (pick one; `--rm` is the default).
+The catch is timing: the snapshot commits a **running** container, so do it before you exit (once the session ends, the throwaway container is already gone). What you actually care about, your pi config and conversations, is in the machine home and survives every exit anyway.
 
-If you did NOT pass `--keep` but, mid-session, realise you want to preserve what you installed, you can snapshot the **still-running** container into a new machine without exiting (`anon-pi machine snapshot <new-name>`, see below). The catch is timing: once pi exits, a throwaway (`--rm`) container is already gone, so snapshot only works while the session is still up.
+One step does both: `anon-pi image snapshot toolbox --create-machine box` commits the image AND creates machine `box` from it, carrying the source machine's home + conversations over (the same prompts described under [Managing images](#managing-images)). `anon-pi image list` shows your snapshots with their provenance (source machine, source image, when), including orphaned snapshots (an overwritten `:latest`) by their ID.
 
 ## Managing machines
 
@@ -226,17 +231,28 @@ anon-pi machine create <name> [--image <ref>]   create a machine, pin its image
 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>
 ```
 
-`snapshot` captures the current filesystem of a **running** jailed container (for example after you `sudo apt install` some tools) into a new image, then 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 your 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). The new machine gets a **fresh** home (the image is the software; the home, with your config and conversations, is a separate host mount and is not copied). It relaunches through the same forced-egress jail.
-
 A machine's home is seeded on FIRST LAUNCH, not at create. `set-image` re-pins the image only and **warns**: it does not reseed or touch the home, so the home's extensions were built for the old image. `rm` confirms on a TTY, skips the prompt with `--yes`, and aborts non-interactively without it (it never deletes unprompted in a script). `create` with no `--image` and no TTY is an error (a machine needs an image to launch).
 
+`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; with no TTY nothing is copied). Otherwise it is a plain fresh create.
+
 If you never create a machine explicitly, launches use the `default` machine (which `init` creates). Give a machine its own image + home + conversations by naming it with `-m`.
 
+## Managing images
+
+```
+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)
+```
+
+`image snapshot` captures the current filesystem of a **running** jailed container (for example after you `sudo apt install` some tools) into the clean tag `anon-pi/<name>:latest`, baking **provenance** as podman labels (source machine, source image, snapshot time). This is the way to 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 your 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** (your pi config, extensions, and dotfiles, which are correct for the committed image) **minus its conversations**. Conversations are handled separately: you are offered each one **grouped by project**, opt-in per project (default **skip**), choosing **copy** or **skip** for each (with no TTY, none are copied). Copy never touches the source machine; after copying, a single confirmed step (default No) can **delete** the copied groups from the source (the only way to "move" a conversation out). This is equivalent to `image snapshot` followed by a provenance-aware `machine create --image`.
+
+`image 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.
+
 ## Deleting data
 
 The destructive verbs replace the old `--fresh`. Each confirms on a TTY, skips with `--yes`, and aborts non-interactively without it.
@@ -349,7 +365,9 @@ anon-pi 0.4.0 was a **per-workdir** launcher: a bare positional was a host folde
 - **A bare positional is now a PROJECT, not a host path.** `anon-pi ./recon` no longer mounts host `./recon`; it means the project `recon` under the projects root (`/projects/recon`). To make a host folder available, use `--mount <host-parent>` (mounted at `/work`) and select the subfolder as the project.
 - **`anon-pi import` is GONE.** Onboarding is now `anon-pi init`, which (among other things) generates the local-model `models.json` for the default machine. There is no separate import step.
 - **`--fresh` is GONE.** To reset, use the explicit data verbs: `anon-pi --delete-home [<machine>]` (wipe a machine's home, keep its image pin + project files) and `anon-pi --delete-project <project>` (wipe a project's files + its per-machine sessions).
-- **`--ephemeral` / `ANON_PI_EPHEMERAL` are GONE.** The container is **throwaway by default** now (`--rm`); use `--keep` when you want it to survive across exits. There is no separate ephemeral mode.
+- **`--ephemeral` / `ANON_PI_EPHEMERAL` are GONE.** The container is **throwaway** now; there is no separate ephemeral mode.
+- **`--keep` and `--rm` are GONE.** Every launch is throwaway (there is no flag to toggle it): passing either is an error. The exploratory "install, quit, re-enter" flow is served by snapshotting the running container into a named image (`anon-pi image snapshot <name>`) and pinning a machine to it (`anon-pi machine create <m> --image anon-pi/<name>:latest`), which is explicit and named instead of an inferred mutable pet container. Your pi config and conversations were never in the container anyway (they live in the machine home).
+- **`machine snapshot` is now `image snapshot`.** Snapshot moved off the `machine` noun onto the new `image` noun: `anon-pi image snapshot <name>` commits the running container into `anon-pi/<name>:latest` (with provenance labels), and `--create-machine <m>` also builds a machine from it. See [Managing images](#managing-images).
 - **The layout moved.** Everything now lives under `~/.anon-pi/` (`config.json` + `machines/` + `projects/`), **not** under `~/.config/anon-pi`. `ANON_PI_HOME` still overrides the root; the old `ANON_PI_CONFIG` / `ANON_PI_SOURCE_MODELS` variables are gone.
 - **Old state is NOT migrated.** anon-pi does not read or convert your old `~/.config/anon-pi/state/<slug>/` directories. Once you have moved to the new model you can delete the old tree:
 
@@ -368,7 +386,7 @@ Start fresh with `anon-pi init`, then `anon-pi` (the menu) or `anon-pi <project>
 - **`no TTY` on a bare `anon-pi`** — the menu and interactive pi need a terminal. In a script, name the project and forward args: `anon-pi <project> <pi-args…>` (that path needs no TTY).
 - **The exit IP looks like your home IP** — the proxy is not actually anonymizing. Re-run `anon-pi init`; its `netcage verify` step prints the real exit IP as proof. anon-pi never claims a provider, only shows you the exit.
 - **A destructive verb won't run in a script** — `machine rm` / `--delete-home` / `--delete-project` confirm on a TTY and abort non-interactively; pass `--yes` to proceed unattended.
-- **`--keep` re-entry started a fresh container** — a kept container is matched by its `(machine, projects-root, project)` identity; changing any of those (a different `-m`, a different `--mount` parent, a different project) is a different launch and gets its own container.
+- **`--keep` / `--rm` say they are gone** — that is expected: every launch is throwaway now. To keep system changes you made in a session, `anon-pi image snapshot <name>` the **still-running** container into a named image, then pin a machine to it (`anon-pi machine create <m> --image anon-pi/<name>:latest`) and relaunch (`anon-pi -m <m>`). Your pi config + conversations persist regardless (they live in the machine home).
 
 ## Platform
 

package/dist/anon-pi.d.ts

@@ -248,12 +248,18 @@ export declare function resolveDeleteProject(args: {
  */
 export declare 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.
+ * 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 declare const RESERVED_NAMES: readonly string[];
 /** What a name names, for a clear validation error. */
@@ -306,7 +312,7 @@ export declare 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 declare function launchCwd(_mode: LaunchMode, kind: RootKind, project: string | undefined): string;
@@ -404,6 +410,25 @@ export declare function resolveLlm(args: {
         llmDirect?: string;
     };
 }): string | undefined;
+/**
+ * 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 declare 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;
 /** A resolved machine: its host home (bind-mounted at /root) + its image. */
 export interface Machine {
     /** The machine's name (already validated by validateName elsewhere). */
@@ -460,12 +485,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). */
@@ -513,9 +532,10 @@ export declare 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;
@@ -528,7 +548,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[];
 }
 /** True iff `a` is a RESUME-family flag (resolve session cwd; see PI_RESUME_FLAGS). */
@@ -571,6 +600,17 @@ export declare function sessionHeaderCwd(headerLine: string): string | undefined
  * RESERVED project name (see RESERVED_NAMES) so a project can never shadow it.
  */
 export declare 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 declare const RETIRED_LAUNCH_FLAGS: readonly ["--keep", "--rm"];
+/** PURE: the error message for a retired `--keep`/`--rm` flag, pointing at the image-based replacement. */
+export declare function retiredKeepRmMessage(flag: string): string;
 /**
  * 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
@@ -581,8 +621,8 @@ export declare const PI_PASSTHROUGH_TOKEN = "pi";
 export declare function isHeadlessPiArgs(piArgs: readonly string[] | undefined): boolean;
 /**
  * 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`,
@@ -595,7 +635,7 @@ export declare function isHeadlessPiArgs(piArgs: readonly string[] | undefined):
  * 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 declare function parseLaunchArgs(args: readonly string[]): ParsedLaunch;
 /**
@@ -608,87 +648,39 @@ export declare 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.
  */
 export declare function resolveRunPlan(intent: LaunchIntent, homeFresh: (machineHome: string) => boolean): LaunchPlan;
 /**
- * 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.
- *
- * 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.
- *
- * 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).
- */
-export declare function keptContainerKey(intent: LaunchIntent): string;
-/**
- * PURE: decide run-vs-start for a launch given a SUPPLIED listing of kept
- * `netcage.managed` containers (the CLI's netcage query result).
+ * 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.
  *
- *   - `--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`).
+ * 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.
  *
- * Never spawns, never queries netcage: the listing is injected, so the whole
- * decision is a pure function of (intent, listing).
+ * 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 declare function resolveRunVsStart(intent: LaunchIntent, kept: readonly KeptContainer[]): RunVsStart;
+export declare function launchIdentityKey(intent: LaunchIntent): string;
 /**
- * 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 ''.
  */
@@ -698,7 +690,7 @@ export interface KeptKeyFields {
     mountParent: string;
     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 declare function parseKeptKey(key: string): KeptKeyFields;
 /**
  * PURE: the leaf name of a stamped key's cwd, i.e. the project a container hosts
@@ -725,7 +717,7 @@ export declare 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;
@@ -824,7 +816,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 declare function parseNetcagePsJson(stdout: string, opts?: {
     runningOnly?: boolean;
@@ -933,6 +925,40 @@ export declare function deriveProjectUsage(args: {
     currentMachine: string;
     sessions: SessionDirListing;
 }): ProjectUsage[];
+/**
+ * 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 declare function copyIncludesForHomeMinusSessions(src: string, sessionsDir: string): boolean;
+/**
+ * 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 declare function snapshotSessionGroups(args: {
+    presentSlugs: readonly string[];
+    projects: readonly string[];
+}): SnapshotSessionGroup[];
 /**
  * What ONE selectable menu row launches, so the CLI can dispatch a chosen entry
  * without re-deriving anything:
@@ -1389,11 +1415,9 @@ export declare 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';
@@ -1409,11 +1433,6 @@ export type MachineCommand = {
     verb: 'rm';
     name: string;
     yes: boolean;
-} | {
-    verb: 'snapshot';
-    name: string;
-    machine?: string;
-    imageTag?: string;
 };
 /**
  * PURE: parse the tokens AFTER `machine` into a MachineCommand. Validates the
@@ -1428,12 +1447,75 @@ export type MachineCommand = {
  */
 export declare function parseMachineArgs(args: readonly string[]): MachineCommand;
 /**
- * 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).
+ * 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 declare function parseImageArgs(args: readonly string[]): ImageCommand;
+/**
+ * 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 declare function snapshotImageTag(name: string): string;
+/** The podman/anon-pi provenance label keys baked into a snapshot image. */
+export declare const PROVENANCE_LABEL_SOURCE_MACHINE = "anon-pi.source-machine";
+export declare const PROVENANCE_LABEL_SOURCE_IMAGE = "anon-pi.source-image";
+export declare 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 declare function snapshotProvenanceLabels(args: {
+    sourceMachine?: string;
+    sourceImage?: string;
+    at: string;
+}): string[];
+/** 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 declare function snapshotImageRef(name: string, now: Date): string;
+export declare function parseImageProvenance(labels: Record<string, unknown> | null | undefined): ImageProvenance;
 /**
  * PURE: the JSON body a machine.json carries, given the pinned image (and an
  * optional per-machine projects override, preserved on a re-pin). A single
@@ -1454,5 +1536,5 @@ export declare function setImageWarning(name: string, oldImage: string | undefin
 /** Read the AnonPiEnv from a process env map (kept separate so tests inject one). */
 export declare function envFromProcess(penv: Record<string, string | undefined>): AnonPiEnv;
 /** The --help text (kept here so it is covered by the same module). */
-export declare const HELP = "anon-pi - run pi on anonymized, jailed machines (netcage: forced egress + one direct local model)\n\nUSAGE\n  anon-pi                        MENU: pick a project (pi), a shell, or a new project\n  anon-pi <project>              pi in the project (/projects/<project>); exit pi -> host\n  anon-pi <project> <pi-args\u2026>   forward args to pi (e.g. -p for a headless one-shot)\n  anon-pi --session <id>         resume a pi session by id, in its own project (also -r/--resume)\n  anon-pi <project> --fork <id>  fork a session into <project> (`.`=root; --continue too; project required)\n  anon-pi --list-models          list the models pi sees (also --models; no project needed)\n  anon-pi pi <pi-args\u2026>          run pi with ANY args and no project (the passthrough)\n  anon-pi --version              print anon-pi's version (also -V)\n  anon-pi --shell [<project>]    a jailed bash (at /projects, or cd'd into <project>) - the project-hopper\n  anon-pi forward [<p>] [--port \u2026]  open a host port onto a running container's in-jail server\n  anon-pi ports [<project>]      list a running container's open in-jail TCP listeners\n  anon-pi -m <machine> [<p>]     the same, on <machine> (its own image + home + conversations)\n  anon-pi --mount <parent> [<p>] root at a HOST parent folder instead of the projects root\n  anon-pi init                   onboard: verify your proxy, capture your local model, pick an image\n  anon-pi machine \u2026              manage machines (create / list / set-image / rm / snapshot)\n  anon-pi --delete-home [<m>]    delete a machine's home (config + convos); keep its image pin + files\n  anon-pi --delete-project <p>   delete a project's files + its per-machine sessions; keep the homes\n\n  <project>   a folder under the projects root (mounted at /projects; pi's cwd). `.` means\n              the root itself (a scratch pi at /projects, /work for --mount, or ~).\n\n  [--rm]      throwaway container this run (the DEFAULT; deleted on exit).\n  [--keep]    leave the container KEPT so its filesystem survives (apt install,\n              quit, re-enter). anon-pi finds it by netcage's managed label and\n              `netcage start`s it on re-entry.\n\nWHAT IT DOES\n  Runs pi inside netcage with all web/DNS egress forced through the socks5h proxy\n  (fail-closed) and ONE direct hole to your local model (ANON_PI_LLM). A MACHINE\n  is an image + a persistent HOST home (bind-mounted at /root) holding your pi\n  config, extensions, and conversations; the container is disposable, so `--rm`\n  loses nothing. Files (projects) are global by default; conversations are\n  per-machine. On a FRESH machine home the image's staged defaults + your\n  models.json are seeded in once; after that pi owns the home. Requires `netcage`.\n\nENVIRONMENT\n  ANON_PI_PROXY   (required) socks5h URL of your proxy (Tor/wireproxy/ssh -D).\n                  No default: the proxy is what anonymizes, so it is never guessed.\n  ANON_PI_LLM     (required) RFC1918/link-local IP[:port] of the local model\n  ANON_PI_IMAGE   image with `pi` on PATH, used when a machine has no image set.\n                  No image yet? See the README (Providing a pi image).\n  ANON_PI_HOME    anon-pi workspace dir (default ~/.anon-pi; NOT under ~/.config)\n  ANON_PI_PROJECTS  projects root override (host dir mounted at /projects)\n\nPLATFORM\n  Linux only (via netcage's netns/nft jail). On macOS/Windows it works only\n  inside a Linux VM, where --allow-direct to a LAN model is VM-boundary-sensitive.\n";
+export declare const HELP = "anon-pi - run pi on anonymized, jailed machines (netcage: forced egress + one direct local model)\n\nUSAGE\n  anon-pi                        MENU: pick a project (pi), a shell, or a new project\n  anon-pi <project>              pi in the project (/projects/<project>); exit pi -> host\n  anon-pi <project> <pi-args\u2026>   forward args to pi (e.g. -p for a headless one-shot)\n  anon-pi --session <id>         resume a pi session by id, in its own project (also -r/--resume)\n  anon-pi <project> --fork <id>  fork a session into <project> (`.`=root; --continue too; project required)\n  anon-pi --list-models          list the models pi sees (also --models; no project needed)\n  anon-pi pi <pi-args\u2026>          run pi with ANY args and no project (the passthrough)\n  anon-pi --version              print anon-pi's version (also -V)\n  anon-pi --shell [<project>]    a jailed bash (at /projects, or cd'd into <project>) - the project-hopper\n  anon-pi forward [<p>] [--port \u2026]  open a host port onto a running container's in-jail server\n  anon-pi ports [<project>]      list a running container's open in-jail TCP listeners\n  anon-pi -m <machine> [<p>]     the same, on <machine> (its own image + home + conversations)\n  anon-pi -i <ref> [<p>]         run against <ref> for THIS launch only (also --image; ephemeral)\n  anon-pi --mount <parent> [<p>] root at a HOST parent folder instead of the projects root\n  anon-pi init                   onboard: verify your proxy, capture your local model, pick an image\n  anon-pi machine \u2026              manage machines (create / list / set-image / rm)\n  anon-pi image \u2026                snapshot a running container into an image; list anon-pi images\n  anon-pi --delete-home [<m>]    delete a machine's home (config + convos); keep its image pin + files\n  anon-pi --delete-project <p>   delete a project's files + its per-machine sessions; keep the homes\n\n  <project>   a folder under the projects root (mounted at /projects; pi's cwd). `.` means\n              the root itself (a scratch pi at /projects, /work for --mount, or ~).\n\n  -i <ref>, --image <ref>   EPHEMERAL per-launch image override, highest priority\n              (`-i` > the machine's machine.json image > ANON_PI_IMAGE). It picks the\n              IMAGE for this launch only; `-m` picks the HOME, and the two compose.\n              It NEVER changes machine.json (to re-pin a machine's image, use\n              `anon-pi machine set-image` / `machine create --image`). No mismatch\n              warning is printed. <ref> resolves in NETCAGE'S private image store\n              (`anon-pi/<name>:latest` snapshots + `init`-built images live there),\n              NOT your default podman store; anon-pi does NOT pre-check it and does\n              NOT auto-pull (an anonymity tool must not silently fetch a remote\n              image). A \"not found\" means the ref is not in netcage's store: snapshot\n              it (`anon-pi image snapshot <name>`) or build it into that store.\n              On a FRESH machine home `-i` is REFUSED (it would seed the home from\n              the wrong image); establish the machine's image with\n              `anon-pi machine create <m> --image <ref>` first.\n\n  Every launch is THROWAWAY: the container is removed on exit. To persist system\n  state you built in a session, snapshot the running container into a named image\n  (`anon-pi image snapshot <name>`) and pin a machine to it (`anon-pi machine\n  create <m> --image anon-pi/<name>:latest`). Your pi config + conversations live\n  in the machine home (a host mount) and persist regardless.\n\nWHAT IT DOES\n  Runs pi inside netcage with all web/DNS egress forced through the socks5h proxy\n  (fail-closed) and ONE direct hole to your local model (ANON_PI_LLM). A MACHINE\n  is an image + a persistent HOST home (bind-mounted at /root) holding your pi\n  config, extensions, and conversations; the container is disposable (throwaway),\n  so it loses nothing. Files (projects) are global by default; conversations are\n  per-machine. On a FRESH machine home the image's staged defaults + your\n  models.json are seeded in once; after that pi owns the home. Requires `netcage`.\n\nENVIRONMENT\n  ANON_PI_PROXY   (required) socks5h URL of your proxy (Tor/wireproxy/ssh -D).\n                  No default: the proxy is what anonymizes, so it is never guessed.\n  ANON_PI_LLM     (required) RFC1918/link-local IP[:port] of the local model\n  ANON_PI_IMAGE   image with `pi` on PATH, used when a machine has no image set.\n                  No image yet? See the README (Providing a pi image).\n  ANON_PI_HOME    anon-pi workspace dir (default ~/.anon-pi; NOT under ~/.config)\n  ANON_PI_PROJECTS  projects root override (host dir mounted at /projects)\n\nPLATFORM\n  Linux only (via netcage's netns/nft jail). On macOS/Windows it works only\n  inside a Linux VM, where --allow-direct to a LAN model is VM-boundary-sensitive.\n";
 //# sourceMappingURL=anon-pi.d.ts.map