anon-pi 0.4.0 → 0.6.0

package/dist/anon-pi.js

@@ -1,34 +1,71 @@
 // anon-pi: the PURE logic (no process spawning, no interactive I/O) so every
 // decision is unit-testable. cli.ts wires this to the real filesystem + spawn.
 //
-// What anon-pi does (settled design):
-//   - ALWAYS seed a per-workdir writable copy of the canonical anon-pi config
-//     (~/.config/anon-pi/agent) into a per-session dir keyed by the workdir, and
-//     mount THAT as the container's pi global (PI_CODING_AGENT_DIR). The
-//     canonical config is only ever READ (at seed time), never mounted, so the
-//     container cannot mutate it.
-//   - Mount the workdir separately at /work (pi's cwd; the user's files land on
-//     the host). A user-supplied /work/.pi/ override is just pi's own
-//     project-over-global layering; anon-pi neither creates nor requires it.
-//   - Open exactly ONE direct hole (--allow-direct <ANON_PI_LLM>) so pi can reach
-//     a local model while all other egress stays forced through the proxy.
-//   - NEVER auto-populate the canonical seed: if it is absent, error and tell the
-//     user to populate it (their anon accounts / chosen skills / a valid
-//     trust.json that trusts /work). anon-pi does not synthesize pi's trust.json.
-//   - Session identity = the ABSOLUTE workdir path (hashed). Same folder resumes
-//     the same session config+state; reseed is manual (delete the session dir).
+// The model (machines + projects; see CONTEXT.md + docs/adr/0001):
+//   - A MACHINE is an image + a persistent HOST home (`machines/<M>/home`),
+//     bind-mounted into the jail at /root. It holds shell config, pi config +
+//     extensions, and pi conversations (`~/.pi/agent/sessions/`). The container
+//     is disposable; ALL valuable state is in this host home.
+//   - A PROJECT is a folder under the PROJECTS ROOT, bind-mounted at /projects,
+//     so a project's cwd is /projects/<name>. pi keys a conversation by its
+//     launch cwd, so /projects/<name> is the conversation key (per-machine,
+//     since it lives in that machine's home).
+//   - TWO invariant container mounts, always: /root (the machine home) and
+//     /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.
+//   - 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).
+//   - Seed-if-fresh (marker-guarded, per MACHINE home): on a fresh home, promote
+//     the image's /root defaults + pi staging + the generated models.json into
+//     the home once, then stamp the marker and never clobber it again.
+//
+// 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).
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-/** The container path the workdir is mounted at (pi's cwd). */
-export const CONTAINER_WORKDIR = '/work';
+/**
+ * The jail cwd root for the projects-root launch: the projects root is mounted
+ * here and a project `<name>` is `/projects/<name>` (pi keys a conversation by
+ * its launch cwd, so `/projects/<name>` is the conversation key). This is the
+ * machines + projects mount (distinct from `--mount`'s /work).
+ */
+export const CONTAINER_PROJECTS_ROOT = '/projects';
+/**
+ * The jail cwd root for a `--mount <parent>` launch: the HOST parent is mounted
+ * here (kept DISTINCT from /projects so the two roots never collide), and a
+ * project `<name>` is `/work/<name>`. See ADR-0001 (`--mount` keeps `/work`).
+ */
+export const CONTAINER_MOUNT_ROOT = '/work';
+/**
+ * The jail cwd root for a machine (its persistent home, bind-mounted at /root).
+ * A machine root has no named subfolders: only the root token `.` (a scratch pi
+ * / shell at `~`) is valid. Written as `~` so it reads as "the machine home".
+ */
+export const CONTAINER_MACHINE_HOME = '~';
+/**
+ * The REAL container path the machine home is bind-mounted at (the source is
+ * the host `machineHomeDir`). This is what a shell-at-`~` launch actually cwds
+ * into (`-w /root`), distinct from CONTAINER_MACHINE_HOME (`~`), which is the
+ * human-readable menu token. It is the parent of CONTAINER_AGENT_DIR
+ * (`/root/.pi/agent`); the seed-if-fresh promotes the image's `/root` defaults +
+ * pi staging into the mounted home here.
+ */
+export const CONTAINER_HOME_ROOT = '/root';
 /**
  * The container path pi uses as its config+state home. anon-pi mounts a
  * PERSISTENT host dir here (Model B), so everything pi writes, sessions,
  * history, settings (your model choice), `pi install`ed extensions, downloaded
- * bin/fd, survives across launches. Statefulness is the default; --ephemeral
- * mounts a throwaway dir here instead.
+ * bin/fd, survives across launches. Statefulness is the default.
  */
 export const CONTAINER_AGENT_DIR = '/root/.pi/agent';
 /**
@@ -44,10 +81,25 @@ export const CONTAINER_STAGE_DIR = '/opt/anon-pi-seed/agent';
  * staged defaults. Read-only: the container never writes back to the host seed.
  */
 export const CONTAINER_MODELS_SEED = '/anon-pi-seed/models.json';
+/**
+ * Where anon-pi mounts the generated settings SEED (the local-model default
+ * selection: defaultProvider/defaultModel/enabledModels) read-only, so the
+ * first-launch seed can MERGE it into the fresh home's settings.json (never
+ * clobbering image-staged packages/extensions).
+ */
+export const CONTAINER_SETTINGS_SEED = '/anon-pi-seed/settings.json';
 /** Marker file written into the agent dir after seeding; holds the seed version. */
 export const SEED_MARKER = '.anon-pi-seed';
-/** The single file the host-side seed carries: pi's model/provider registry. */
+/** The file the host-side seed carries: pi's model/provider registry. */
 export const MODELS_FILE = 'models.json';
+/** pi's settings file (holds defaultModel/defaultProvider/enabledModels + more). */
+export const SETTINGS_FILE = 'settings.json';
+/**
+ * The settings SEED file anon-pi writes next to a machine (the local-model
+ * selection fragment). Distinct name so it never collides with a real
+ * settings.json; the seed MERGES it into the home's settings on first launch.
+ */
+export const SETTINGS_SEED_FILE = 'settings-seed.json';
 /**
  * containerRunCmd builds the container command: on a FRESH home (no seed
  * marker), promote the image's staged defaults + the mounted models.json into
@@ -76,24 +128,760 @@ export const SEED_VERSION = '1';
 /** A user-facing error whose message is meant to be printed verbatim (no stack). */
 export class AnonPiError extends Error {
 }
-/** Resolve the anon-pi home dir (holds the seed). */
+/**
+ * The verbatim guidance printed when no proxy is supplied. Kept as a single
+ * source so the fail-closed path (resolveProxy) emits byte-identical
+ * copy-pasteable guidance. The proxy is REQUIRED and never guessed: it is what
+ * anonymizes egress (fail-closed is the anonymity invariant).
+ */
+export const PROXY_REQUIRED_MESSAGE = 'anon-pi: set ANON_PI_PROXY to your socks5h proxy. anon-pi has no default:\n' +
+    'the proxy is what makes the session anonymous, so it is never guessed.\n' +
+    '\n' +
+    'Pick the one you run (copy-paste), then re-run anon-pi:\n' +
+    '\n' +
+    '# Tor (system tor / Tor Browser bundle default port)\n' +
+    'export ANON_PI_PROXY=socks5h://127.0.0.1:9050\n' +
+    '\n' +
+    '# wireproxy -> a WireGuard VPN (Mullvad, Proton, ...); use YOUR configured\n' +
+    '# [Socks5] BindAddress port (1080 in wireproxy examples):\n' +
+    'export ANON_PI_PROXY=socks5h://127.0.0.1:1080\n' +
+    '\n' +
+    '# an SSH dynamic-forward (ssh -D 1080 host) or any other socks5h endpoint\n' +
+    'export ANON_PI_PROXY=socks5h://127.0.0.1:1080\n' +
+    '\n' +
+    'Only socks5h:// is accepted (plain socks5:// resolves DNS locally and leaks).';
+/**
+ * Resolve the anon-pi home dir: the dedicated, browsable workspace folder
+ * (`~/.anon-pi/`, NOT under `~/.config`), holding config.json, machines/<M>/,
+ * and the default global projects root. Overridable via ANON_PI_HOME.
+ */
 export function resolveAnonPiHome(env) {
     if (env.anonPiHome)
         return resolve(env.anonPiHome);
-    const base = env.xdgConfigHome && env.xdgConfigHome.trim() !== ''
-        ? env.xdgConfigHome
-        : join(env.home, '.config');
-    return join(base, 'anon-pi');
+    return join(env.home, '.anon-pi');
+}
+/** A machine's directory: <home>/machines/<name> (holds machine.json + home/). */
+export function machineDir(env, name) {
+    return join(resolveAnonPiHome(env), 'machines', name);
+}
+/** A machine's persistent HOST home: <home>/machines/<name>/home (bind-mounted at /root). */
+export function machineHomeDir(env, name) {
+    return join(machineDir(env, name), 'home');
+}
+/** A machine's machine.json path: <home>/machines/<name>/machine.json. */
+export function machineJsonPath(env, name) {
+    return join(machineDir(env, name), 'machine.json');
+}
+/** The sessions dirname pi keeps its per-cwd conversation dirs under (in the agent dir). */
+export const SESSIONS_DIRNAME = 'sessions';
+/**
+ * A machine's HOST pi agent dir: the host side of the container's
+ * CONTAINER_AGENT_DIR (`/root/.pi/agent`, since the home is bind-mounted at
+ * /root). i.e. <machineHome>/.pi/agent. Where pi's config + sessions live.
+ */
+export function machineAgentDir(env, name) {
+    return join(machineHomeDir(env, name), '.pi', 'agent');
+}
+/**
+ * A machine's HOST pi sessions dir: <machineAgentDir>/sessions. Each per-cwd
+ * conversation is a slug-named subdir here (projectSessionSlug for a project).
+ */
+export function machineSessionsDir(env, name) {
+    return join(machineAgentDir(env, name), SESSIONS_DIRNAME);
+}
+/**
+ * The HOST session dir a given project's conversation occupies in a given
+ * machine's home: <machineSessionsDir>/<projectSessionSlug>. Because the slug is
+ * MACHINE-INVARIANT (pi keys by the `/projects/<name>` cwd, identical on every
+ * machine), the SAME shared project has this dir in each machine that used it.
+ * Validates the project name (rejecting traversal) via projectSessionSlug.
+ */
+export function machineProjectSessionDir(env, machine, project) {
+    return join(machineSessionsDir(env, machine), projectSessionSlug(project));
+}
+/** The built-in default global projects root: <home>/projects. */
+export function builtinProjectsRoot(env) {
+    return join(resolveAnonPiHome(env), 'projects');
+}
+/**
+ * PURE: resolve the affected path for `--delete-home <machine>`: the machine's
+ * HOME dir only (config + convos + shell env), NOT the whole machine dir, so the
+ * image pin (machine.json) survives a re-seed. Validates the machine name
+ * (rejecting traversal) via machineHomeDir's join being under a validated name;
+ * we validate explicitly here so the plan itself is a safe single segment.
+ */
+export function resolveDeleteHome(env, machine) {
+    validateName(machine, 'machine');
+    return { machine, home: machineHomeDir(env, machine) };
+}
+/**
+ * PURE: resolve the affected paths for `--delete-project <project>`: the
+ * project's files under the RESOLVED projects root, plus that project's session
+ * dir in each SUPPLIED machine home (the machine-invariant slug). Validates the
+ * project name (rejecting traversal) so both the folder join and every session
+ * join stay inside their roots. The homes are NOT targeted (only the per-project
+ * slug dir inside each), matching the prd behaviour table.
+ */
+export function resolveDeleteProject(args) {
+    const { env, project, projectsRoot, machines } = args;
+    validateName(project, 'project');
+    return {
+        project,
+        folder: projectHostDir(projectsRoot, project),
+        sessions: machines.map((m) => machineProjectSessionDir(env, m, project)),
+    };
+}
+// --- Name validation + the "." root token ------------------------------------
+/**
+ * The project token meaning "the root itself": cwd `/projects` (projects root),
+ * `/work` (`--mount`), or `~` (a machine home). It is NOT a valid machine or
+ * project name (validateName rejects it) so a folder can never shadow it.
+ */
+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 = ['.', '..'];
+/**
+ * PURE: validate a machine or project name as a safe single path segment, and
+ * return it unchanged on success. Rejects (with AnonPiError):
+ *   - empty
+ *   - a path separator `/` or `\`, or a colon `:`
+ *   - the traversal token `..` (and any leading dot, incl. `.`)
+ *   - any whitespace
+ *   - a reserved name (RESERVED_NAMES)
+ * A valid name is thus a single folder segment safe to join under the projects
+ * root or the machines dir with no traversal or drive/scheme surprises.
+ */
+export function validateName(name, kind) {
+    const bad = (why) => {
+        throw new AnonPiError(`anon-pi: invalid ${kind} name ${JSON.stringify(name)}: ${why}. ` +
+            `A ${kind} name must be a single folder segment (no / \\ : whitespace, ` +
+            `no leading dot, not "..").`);
+    };
+    if (name === '')
+        return bad('it is empty');
+    if (/[/\\:]/.test(name))
+        return bad('it contains / \\ or :');
+    if (/\s/.test(name))
+        return bad('it contains whitespace');
+    if (name.startsWith('.'))
+        return bad('it starts with a dot');
+    if (name === '..')
+        return bad('it is the parent-traversal token');
+    if (RESERVED_NAMES.includes(name))
+        return bad('it is a reserved name');
+    return name;
+}
+/**
+ * PURE: map a validated project `<name>` to its host folder under the resolved
+ * projects root (the parent from resolveProjectsRoot / a `--mount` parent).
+ * Validates the name (rejecting traversal) so the join stays inside the root.
+ */
+export function projectHostDir(projectsRoot, name) {
+    return join(projectsRoot, validateName(name, 'project'));
+}
+/**
+ * PURE: the jail cwd for a validated project `<name>`: `/projects/<name>`. This
+ * is pi's conversation key (pi keys a session by its launch cwd). Validates the
+ * name. For the `--mount` root use resolveCwd('mount', name) (=> /work/<name>).
+ */
+export function projectContainerCwd(name) {
+    return `${CONTAINER_PROJECTS_ROOT}/${validateName(name, 'project')}`;
+}
+/** True iff `token` is exactly the root token `.` ("the root itself"). */
+export function isRootToken(token) {
+    return token === ROOT_TOKEN;
+}
+/** PURE: the jail cwd of a root itself: /projects, /work (mount), or ~ (machine). */
+export function rootCwd(kind) {
+    switch (kind) {
+        case 'projects':
+            return CONTAINER_PROJECTS_ROOT;
+        case 'mount':
+            return CONTAINER_MOUNT_ROOT;
+        case 'machine':
+            return CONTAINER_MACHINE_HOME;
+    }
+}
+/**
+ * PURE: resolve a launch's jail cwd UNIFORMLY from a `token` and its root kind.
+ * The root token `.` means "the root itself" (rootCwd) in every context; any
+ * other token is a project name resolved to `<root>/<name>` (validated). A
+ * machine root has no named subfolders (projects live at /projects or /work,
+ * never under the machine home), so a non-`.` token for a machine is rejected.
+ * This is the one seam so `anon-pi --mount <p> .` and a menu "here" entry agree.
+ */
+export function resolveCwd(kind, token) {
+    if (isRootToken(token))
+        return rootCwd(kind);
+    if (kind === 'machine') {
+        throw new AnonPiError(`anon-pi: a machine root takes only "${ROOT_TOKEN}" (the machine home ${CONTAINER_MACHINE_HOME}), ` +
+            `not a named project ${JSON.stringify(token)}. Projects live under /projects or /work.`);
+    }
+    return `${rootCwd(kind)}/${validateName(token, 'project')}`;
+}
+/** Pick a string field from a parsed-JSON object, or undefined if absent/non-string. */
+function strField(o, key) {
+    if (!o || typeof o !== 'object')
+        return undefined;
+    const v = o[key];
+    return typeof v === 'string' ? v : undefined;
+}
+/**
+ * PURE: parse an already-JSON-decoded config.json value into an AnonPiConfig,
+ * keeping only the known string fields (defensive against a hand-edited file).
+ * Tolerates undefined/null/partial input (an absent config is `{}`).
+ */
+export function parseConfigJson(raw) {
+    const out = {};
+    const proxy = strField(raw, 'proxy');
+    if (proxy !== undefined)
+        out.proxy = proxy;
+    const llm = strField(raw, 'llm');
+    if (llm !== undefined)
+        out.llm = llm;
+    const defaultMachine = strField(raw, 'defaultMachine');
+    if (defaultMachine !== undefined)
+        out.defaultMachine = defaultMachine;
+    const projects = strField(raw, 'projects');
+    if (projects !== undefined)
+        out.projects = projects;
+    return out;
+}
+/**
+ * PURE: parse an already-JSON-decoded machine.json value into a MachineConfig.
+ * Tolerates undefined/null/partial input (an absent machine.json is `{}`).
+ */
+export function parseMachineJson(raw) {
+    const out = {};
+    const image = strField(raw, 'image');
+    if (image !== undefined)
+        out.image = image;
+    const projects = strField(raw, 'projects');
+    if (projects !== undefined)
+        out.projects = projects;
+    return out;
+}
+/** A non-empty (after-trim) string, or undefined. */
+function nonEmpty(v) {
+    return v && v.trim() !== '' ? v.trim() : undefined;
+}
+/**
+ * PURE: resolve the projects root (the host dir mounted at /projects) with the
+ * decided precedence, highest first:
+ *   --mount (CLI) > env ANON_PI_PROJECTS > machine.json.projects >
+ *   config.json.projects > built-in <home>/projects
+ * This task delivers the config/env/machine layers; `mountParent` is the
+ * documented top slot the later --mount CLI task threads in (pass the resolved
+ * host parent). A relative override is resolved to an absolute path.
+ */
+export function resolveProjectsRoot(args) {
+    const { env, config, machine, mountParent } = args;
+    const pick = nonEmpty(mountParent) ??
+        nonEmpty(env.projects) ??
+        nonEmpty(machine?.projects) ??
+        nonEmpty(config?.projects);
+    if (pick !== undefined)
+        return resolve(pick);
+    return builtinProjectsRoot(env);
+}
+/**
+ * PURE: resolve the proxy with env-over-config precedence, REQUIRED /
+ * fail-closed. Throws AnonPiError with the verbatim PROXY_REQUIRED_MESSAGE when
+ * neither env nor config supplies a non-empty proxy (never a guessed default:
+ * fail-closed is the anonymity invariant).
+ */
+export function resolveProxy(args) {
+    const pick = nonEmpty(args.env.proxy) ?? nonEmpty(args.config?.proxy);
+    if (pick === undefined)
+        throw new AnonPiError(PROXY_REQUIRED_MESSAGE);
+    return pick;
+}
+/**
+ * PURE: resolve the local-model direct target with env-over-config precedence.
+ * Unlike the proxy this is NOT fail-closed here (a launch with no local model
+ * is a later decision); returns undefined when neither supplies one.
+ */
+export function resolveLlm(args) {
+    return nonEmpty(args.env.llmDirect) ?? nonEmpty(args.config?.llm);
+}
+// --- Grammar A: the pure argv -> ParsedLaunch parser -------------------------
+//
+// A bare positional is a PROJECT; `-m` picks the machine. The CLI (cli.ts)
+// combines the ParsedLaunch with config/machine reads (proxy, llm, image, home,
+// projects root) into a LaunchIntent and runs resolveRunPlan. Kept PURE (argv
+// in -> struct out, or AnonPiError) so parsing + the reserved-name guard are
+// unit-testable; the CLI stays thin I/O.
+/** The machine bare `anon-pi` launches when no `-m` and no config default. */
+export const DEFAULT_MACHINE = 'default';
+/**
+ * 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
+ * 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. In shell/menu mode a stray extra positional is an error (bash has
+ * no forwarded-args grammar; the menu takes no project).
+ *
+ * Validates the project name and the `-m` machine name via validateName (the
+ * 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.
+ */
+export function parseLaunchArgs(args) {
+    let machine = DEFAULT_MACHINE;
+    let machineSet = false;
+    let shell = false;
+    let mountParent;
+    let keepSeen = false;
+    let rmSeen = false;
+    let project;
+    let piArgs;
+    const fail = (msg) => {
+        throw new AnonPiError(`anon-pi: ${msg}\nRun \`anon-pi --help\`.`);
+    };
+    let i = 0;
+    for (; i < args.length; i++) {
+        const a = args[i];
+        if (a === '-m' || a === '--machine') {
+            const v = args[++i];
+            if (v === undefined)
+                fail(`${a} needs a machine name`);
+            machine = validateName(v, 'machine');
+            machineSet = true;
+            continue;
+        }
+        if (a === '--shell') {
+            shell = true;
+            continue;
+        }
+        if (a === '--mount') {
+            const v = args[++i];
+            if (v === undefined)
+                fail('--mount needs a HOST parent path');
+            mountParent = v;
+            continue;
+        }
+        if (a === '--keep') {
+            keepSeen = true;
+            continue;
+        }
+        if (a === '--rm') {
+            rmSeen = true;
+            continue;
+        }
+        if (a === '.') {
+            // the root token is a valid project positional (not a name).
+            project = ROOT_TOKEN;
+            i++;
+            break;
+        }
+        if (a.startsWith('-')) {
+            fail(`unknown option: ${a}`);
+        }
+        // the first bare positional is the project.
+        project = validateName(a, 'project');
+        i++;
+        break;
+    }
+    if (keepSeen && rmSeen) {
+        fail('--keep and --rm are contradictory (pick one; --rm is the default)');
+    }
+    // tokens remaining after the project.
+    const rest = args.slice(i);
+    if (shell) {
+        if (rest.length > 0) {
+            fail(`--shell takes at most one project, got extra: ${rest.join(' ')} ` +
+                '(a shell forwards no args; run pi from inside it instead)');
+        }
+        return {
+            mode: 'shell',
+            machine,
+            machineExplicit: machineSet,
+            project,
+            mountParent,
+            keep: keepSeen,
+        };
+    }
+    if (project === undefined) {
+        // no project + no --shell: the menu (bare, or -m/--mount with no project).
+        if (rest.length > 0)
+            fail(`unexpected argument: ${rest[0]}`);
+        return {
+            mode: 'menu',
+            machine,
+            machineExplicit: machineSet,
+            project: undefined,
+            mountParent,
+            keep: keepSeen,
+        };
+    }
+    // pi mode: every token after the project is forwarded to pi verbatim.
+    if (rest.length > 0)
+        piArgs = rest.slice();
+    return {
+        mode: 'pi',
+        machine,
+        machineExplicit: machineSet,
+        project,
+        mountParent,
+        keep: keepSeen,
+        piArgs,
+    };
+}
+/**
+ * PURE: resolve a LaunchIntent into a LaunchPlan, composing the netcage argv for
+ * every mode. Never spawns, never touches the filesystem: `homeFresh` reports
+ * whether the machine home has been seeded (so `fresh` is known) and is the only
+ * capability injected.
+ *
+ * Invariants held on EVERY composed argv:
+ *   - 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.
+ *
+ * Throws AnonPiError (a plan is NEVER produced) when the image, the machine
+ * home, the proxy, or the direct-hole llm is missing.
+ */
+export function resolveRunPlan(intent, homeFresh) {
+    const { machine, mode, projectsRoot, project, mountParent } = intent;
+    // Forced egress FIRST, on every path incl. the menu marker: a plan can never
+    // be produced without the proxy + the one direct hole (fail-closed).
+    const proxy = nonEmpty(intent.proxy);
+    if (proxy === undefined)
+        throw new AnonPiError(PROXY_REQUIRED_MESSAGE);
+    const llm = nonEmpty(intent.llmDirect);
+    if (llm === undefined) {
+        throw new AnonPiError('anon-pi: no local-model direct target: set ANON_PI_LLM (or config.llm) to the ' +
+            'RFC1918/link-local IP[:port] of the local model. It is the ONE direct hole; ' +
+            'all other egress stays forced through the proxy.');
+    }
+    if (nonEmpty(machine.image) === undefined) {
+        throw new AnonPiError(`anon-pi: machine ${JSON.stringify(machine.name)} has no image. Set one with ` +
+            '`anon-pi machine set-image` or in its machine.json.');
+    }
+    if (nonEmpty(machine.home) === undefined) {
+        throw new AnonPiError(`anon-pi: machine ${JSON.stringify(machine.name)} has no resolved home dir.`);
+    }
+    // Bare launch: defer to the host-side menu; compose no argv yet (but the
+    // forced-egress checks above have already run, so a menu is never a way to
+    // slip past the proxy requirement).
+    if (mode === 'menu') {
+        return { kind: 'menu', machine };
+    }
+    const mounted = nonEmpty(mountParent) !== undefined;
+    // Which root the cwd resolves under: /work when --mount, else /projects.
+    const rootKind = mounted ? 'mount' : 'projects';
+    // cwd: shell with no project sits at the machine home (/root); otherwise the
+    // project token (a name or `.`) resolves under the active root uniformly.
+    const cwd = project === undefined ? CONTAINER_HOME_ROOT : resolveCwd(rootKind, project);
+    const fresh = homeFresh(machine.home);
+    const seedVersion = intent.seedVersion ?? SEED_VERSION;
+    const directTarget = hostPortKey(llm);
+    const modelsSeed = nonEmpty(intent.modelsSeed);
+    // Interactive modes (interactive pi, shell) need a TTY; a HEADLESS pi run
+    // (`<project> <pi-args…>`) must work WITHOUT one, so `-it` is omitted there
+    // (podman fails to allocate a TTY on a non-tty stdin). The CLI's broader
+    // no-TTY discipline (erroring when an interactive mode has no TTY) is a later
+    // task; here the argv simply omits -it for the one headless shape.
+    const headless = mode === 'pi' && !!intent.piArgs && intent.piArgs.length > 0;
+    const netcageArgs = ['run'];
+    // --rm by DEFAULT (throwaway); --keep leaves the container kept.
+    if (intent.keep !== true)
+        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');
+    // The TWO invariant mounts, ALWAYS.
+    netcageArgs.push('-v', `${machine.home}:${CONTAINER_HOME_ROOT}`);
+    netcageArgs.push('-v', `${projectsRoot}:${CONTAINER_PROJECTS_ROOT}`);
+    // --mount adds EXACTLY the one parent mount at /work (distinct from /projects,
+    // so the two roots never collide). Nothing else changes.
+    if (mounted) {
+        netcageArgs.push('-v', `${mountParent}:${CONTAINER_MOUNT_ROOT}`);
+    }
+    // The generated models.json read-only for the first-launch seed, when present.
+    if (modelsSeed !== undefined) {
+        netcageArgs.push('-v', `${modelsSeed}:${CONTAINER_MODELS_SEED}:ro`);
+    }
+    // The generated settings SEED (the local-model default selection) read-only,
+    // when present; the seed-if-fresh MERGES it into the home's settings.json.
+    const settingsSeed = nonEmpty(intent.settingsSeed);
+    if (settingsSeed !== undefined) {
+        netcageArgs.push('-v', `${settingsSeed}:${CONTAINER_SETTINGS_SEED}:ro`);
+    }
+    // The jail cwd.
+    netcageArgs.push('-w', cwd);
+    // The image, then the command: a marker-guarded seed-if-fresh then the tool.
+    // pi (with forwarded args) for pi mode; bash for a shell. The seed shape is
+    // containerRunCmd re-pointed at the machine home (/root), so a fresh machine
+    // home gets the image's staged defaults + models.json once.
+    netcageArgs.push(machine.image);
+    if (mode === 'shell') {
+        // A jailed bash: seed-if-fresh (so a fresh home still gets .bashrc etc.),
+        // then exec bash.
+        netcageArgs.push('sh', '-c', containerSeedThen(seedVersion, 'exec bash'));
+    }
+    else if (intent.piArgs && intent.piArgs.length > 0) {
+        // Forward args: seed-if-fresh, then exec pi with the args. The args are the
+        // shell's positional argv ($@) so they are forwarded verbatim (no re-quote).
+        netcageArgs.push('sh', '-c', containerSeedThen(seedVersion, 'exec pi "$@"'), 'pi', ...intent.piArgs);
+    }
+    else {
+        // Interactive pi: seed-if-fresh, then exec pi.
+        netcageArgs.push('sh', '-c', containerSeedThen(seedVersion, 'exec pi'));
+    }
+    return { kind: 'launch', machine, cwd, fresh, netcageArgs };
+}
+/**
+ * The marker-guarded seed-if-fresh prefix (reused across pi/bash), followed by
+ * the given exec. On a FRESH machine home (no `.anon-pi-seed` marker under
+ * /root/.pi/agent) it promotes the image's staged pi defaults
+ * (/opt/anon-pi-seed/agent) + the mounted models.json into the home and stamps
+ * the marker; on a seeded home it does nothing. Then it runs `exec`. This is
+ * `containerRunCmd`'s shape (already /root-pointed), generalised over the tool.
+ */
+function containerSeedThen(seedVersion, exec) {
+    const agent = CONTAINER_AGENT_DIR;
+    const marker = `${agent}/${SEED_MARKER}`;
+    const settings = `${agent}/${SETTINGS_FILE}`;
+    // Merge the settings SEED (the local-model default selection) into the home's
+    // settings.json, overwriting ONLY the three selection keys so any staged
+    // packages/extensions survive. Done with a node one-liner (pi is a node app,
+    // so node is on PATH). The seed path + target are shell-quoted single args.
+    const mergeSettings = `{ [ -f "${CONTAINER_SETTINGS_SEED}" ] && node -e '` +
+        `const fs=require("fs");` +
+        `const seed=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));` +
+        `let cur={};try{cur=JSON.parse(fs.readFileSync(process.argv[2],"utf8"))}catch(e){}` +
+        `cur.defaultProvider=seed.defaultProvider;cur.defaultModel=seed.defaultModel;cur.enabledModels=seed.enabledModels;` +
+        `fs.writeFileSync(process.argv[2],JSON.stringify(cur,null,"\\t")+"\\n")` +
+        `' "${CONTAINER_SETTINGS_SEED}" "${settings}" || true; }`;
+    return (`mkdir -p "${agent}" && ` +
+        `if [ ! -f "${marker}" ]; then ` +
+        `{ [ -d "${CONTAINER_STAGE_DIR}" ] && cp -a "${CONTAINER_STAGE_DIR}/." "${agent}/" || true; } && ` +
+        `{ [ -f "${CONTAINER_MODELS_SEED}" ] && cp "${CONTAINER_MODELS_SEED}" "${agent}/${MODELS_FILE}" || true; } && ` +
+        `${mergeSettings} && ` +
+        `printf '%s\\n' "${seedVersion}" > "${marker}"; ` +
+        `fi && ` +
+        `${exec}`);
+}
+/**
+ * PURE: the launch-identity match key for a kept container, derived ENTIRELY
+ * from the (machine, projects-root, project) identity (ADR-0002). It is what
+ * decides whether an existing kept `netcage.managed` container IS the one a
+ * `--keep` launch should resume.
+ *
+ * The fields, and why each is load-bearing:
+ *   - `machine.name`: a kept container mounts THIS machine's home at /root; a
+ *     same-project container on another machine is a different environment.
+ *   - `projectsRoot`: the host dir mounted at /projects; two launches with the
+ *     same project name but different roots are different working trees.
+ *   - `mountParent` (or '' when absent): `--mount` re-roots into a DIFFERENT
+ *     host parent at /work, so a `--mount` launch is a distinct identity from
+ *     the projects-root launch of the same name.
+ *   - the resolved container `cwd`: this already encodes the project token
+ *     (`/projects/<p>`, `/work/<p>`, `.` -> a root, or /root for a bare shell)
+ *     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 function keptContainerKey(intent) {
+    const { machine, projectsRoot, project, mountParent } = intent;
+    const mounted = nonEmpty(mountParent) !== undefined;
+    const rootKind = mounted ? 'mount' : 'projects';
+    // The same cwd resolution resolveRunPlan uses, so the key names the exact
+    // container a matching launch would run in (its conversation key).
+    const cwd = project === undefined ? CONTAINER_HOME_ROOT : resolveCwd(rootKind, project);
+    return [
+        `machine=${machine.name}`,
+        `projectsRoot=${projectsRoot}`,
+        `mountParent=${nonEmpty(mountParent) ?? ''}`,
+        `cwd=${cwd}`,
+    ].join('\n');
+}
+/**
+ * PURE: decide run-vs-start for a launch given a SUPPLIED listing of kept
+ * `netcage.managed` containers (the CLI's netcage query result).
+ *
+ *   - `--rm` (throwaway, `intent.keep !== true`): ALWAYS a fresh `run`. The
+ *     listing is NOT consulted (a throwaway launch never resumes a kept box).
+ *   - `--keep`: a kept container whose `key` equals this launch's
+ *     keptContainerKey is present -> `start` it (by its `ref`); else -> `run`
+ *     (resolveRunPlan leaves it kept because `--keep` omits `--rm`).
+ *
+ * Never spawns, never queries netcage: the listing is injected, so the whole
+ * decision is a pure function of (intent, listing).
+ */
+export function resolveRunVsStart(intent, kept) {
+    // Throwaway short-circuit: a `--rm` launch is always a fresh run and never
+    // consults the listing (it must not resume a kept container).
+    if (intent.keep !== true)
+        return { action: 'run' };
+    const want = keptContainerKey(intent);
+    const match = kept.find((c) => c.key === want);
+    return match ? { action: 'start', ref: match.ref } : { action: 'run' };
+}
+// --- The bare-launch menu: choice-list + per-machine project-usage record ----
+//
+// anon-pi's bare launch shows a HOST-side arrow-key menu of a machine's
+// projects BEFORE any jail runs. This module owns only the PURE data the menu
+// renders; the CLI reads the real dirs (the projects root + each machine home's
+// sessions dir) and renders the raw-mode TUI (the cli-bare-launch-menu-tui
+// task). Everything here takes SUPPLIED listings so it stays unit-testable.
+//
+// Conversations are per-machine (each machine's home keeps its own pi
+// sessions), but project FILES are global (the same folder is shared across
+// machines). pi keys a session by its launch cwd, so a project used on a machine
+// leaves a session dir at machines/<M>/home/.pi/agent/sessions/<slug>/, where
+// <slug> is pi's cwd convention over /projects/<name> (projectSessionSlug),
+// machine-invariant. "Used on" is therefore DERIVED from which machine homes
+// contain that session dir - no marker file.
+/**
+ * PURE: the pi session-dir slug for a project, i.e. pathSlug of its jail cwd
+ * `/projects/<name>`. Because the cwd is the SAME on every machine (files are
+ * global, the projects root is mounted at /projects everywhere), this slug is
+ * MACHINE-INVARIANT: the same shared project is recognised in each machine's
+ * sessions dir. Validates the name (rejecting traversal) as projectContainerCwd
+ * does. e.g. `alpha` -> `--projects-alpha--`.
+ */
+export function projectSessionSlug(name) {
+    return pathSlug(projectContainerCwd(name));
+}
+/**
+ * PURE: build the menu choice-list from a SUPPLIED projects-root listing (the
+ * CLI's real `readdir` of the projects root). Entries that are not folder-safe
+ * project names (dotfiles like `.git`, `..`, path-separator names, whitespace,
+ * reserved tokens) are DROPPED silently: they can never be a valid project
+ * launch (validateName would reject them), and the `.` root is the separate
+ * `here` entry, not a listed project. The surviving names are sorted
+ * case-insensitively so the menu order is stable regardless of dir-read order.
+ *
+ * `canNew` / `canShell` default TRUE (both affordances are always offered
+ * today); they are fields so a later policy can gate them without a signature
+ * change. An empty projects root still offers here / new / shell.
+ */
+export function buildMenuChoiceList(args) {
+    const projects = args.projects.filter(isProjectName).sort((a, b) => {
+        const la = a.toLowerCase();
+        const lb = b.toLowerCase();
+        if (la < lb)
+            return -1;
+        if (la > lb)
+            return 1;
+        // Case-insensitive ties keep a deterministic order via the raw compare.
+        return a < b ? -1 : a > b ? 1 : 0;
+    });
+    return {
+        projects,
+        here: ROOT_TOKEN,
+        canNew: args.canNew ?? true,
+        canShell: args.canShell ?? true,
+    };
+}
+/** True iff `name` is a folder-safe project name (validateName would accept it). */
+function isProjectName(name) {
+    try {
+        validateName(name, 'project');
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 /**
- * The CANONICAL host seed dir holding models.json (written by `anon-pi import`).
- * Mounted read-only so the first-launch seed can copy models.json into a fresh
- * persistent home. Workdir-independent (import does not need a workdir).
+ * PURE: derive the per-machine project-usage record from SUPPLIED session-dir
+ * presence (no marker file). For each supplied project, in the SUPPLIED order,
+ * it reports which machines' homes contain that project's (machine-invariant)
+ * session slug, and whether the CURRENT machine is new for it.
+ *
+ * The project ORDER is preserved (the caller orders the menu, e.g. via
+ * buildMenuChoiceList); only the per-project `machines` list is sorted, so the
+ * "used on" annotation is stable. Validates each project name (rejecting
+ * traversal) via projectSessionSlug.
  */
-export function resolveConfigSeed(env) {
-    if (env.configSeed)
-        return resolve(env.configSeed);
-    return join(resolveAnonPiHome(env), 'agent');
+export function deriveProjectUsage(args) {
+    const { projects, currentMachine, sessions } = args;
+    const machineNames = Object.keys(sessions);
+    return projects.map((project) => {
+        const slug = projectSessionSlug(project);
+        const machines = machineNames
+            .filter((m) => (sessions[m] ?? []).includes(slug))
+            .sort();
+        const currentMachineIsNew = !(sessions[currentMachine] ?? []).includes(slug);
+        return { project, machines, currentMachineIsNew };
+    });
+}
+/** The fixed labels for the non-project affordances (one source, so the TUI + its test agree). */
+export const MENU_HERE_LABEL = '. (here: a scratch pi at the root)';
+export const MENU_NEW_LABEL = '+ new project\u2026';
+export const MENU_SHELL_LABEL = 'shell (a jailed bash on this machine)';
+/**
+ * PURE: render ONE project row's annotation from its usage record. Files are
+ * global but conversations are per-machine, so the row tells the user where a
+ * conversation for this project already lives (`used on: <machines>`) and
+ * whether the CURRENT machine has none yet (`new here`). An unused project on a
+ * fresh machine is just `new here` (no machine list). This is the whole
+ * user-visible surface of the derived usage record, kept pure + testable.
+ */
+export function formatProjectAnnotation(usage) {
+    const parts = [];
+    if (usage.machines.length > 0) {
+        parts.push(`used on: ${usage.machines.join(', ')}`);
+    }
+    if (usage.currentMachineIsNew)
+        parts.push('new here');
+    return parts.length > 0 ? `  (${parts.join('; ')})` : '';
+}
+/**
+ * PURE: assemble the ordered, labelled, selectable menu rows from the choice-
+ * list + the per-project usage record. The order is: the projects (in the
+ * choice-list's stable sorted order), then the `.` "here" scratch entry, then
+ * `+ new project\u2026` (when `canNew`), then `shell` (when `canShell`). Each
+ * project row's label carries its used-on / new-here annotation
+ * (formatProjectAnnotation). This holds ALL the menu's logic (order + wording)
+ * so the raw-mode selector only renders these rows and dispatches the picked
+ * one by its `kind`/`project`.
+ *
+ * The `usage` list is expected to be keyed to `choiceList.projects` (same order,
+ * as deriveProjectUsage produces from the choice-list's projects); a project
+ * with no matching usage entry gets a bare, unannotated row rather than erroring.
+ */
+export function buildMenuEntries(args) {
+    const { choiceList, usage } = args;
+    const byProject = new Map(usage.map((u) => [u.project, u]));
+    const entries = choiceList.projects.map((project) => {
+        const u = byProject.get(project);
+        const annotation = u ? formatProjectAnnotation(u) : '';
+        return { kind: 'project', project, label: `${project}${annotation}` };
+    });
+    entries.push({
+        kind: 'here',
+        project: choiceList.here,
+        label: MENU_HERE_LABEL,
+    });
+    if (choiceList.canNew)
+        entries.push({ kind: 'new', label: MENU_NEW_LABEL });
+    if (choiceList.canShell)
+        entries.push({ kind: 'shell', label: MENU_SHELL_LABEL });
+    return entries;
 }
 /**
  * Encode an absolute path into a directory name using pi's OWN convention (see
@@ -104,14 +892,6 @@ export function resolveConfigSeed(env) {
 export function pathSlug(absPath) {
     return `--${absPath.replace(/^[/\\]/, '').replace(/[/\\:]/g, '-')}--`;
 }
-/**
- * The persistent per-workdir state dir on the host (mounted at the container's
- * ~/.pi/agent). Keyed by the workdir via pi's path-slug convention:
- *   <anonPiHome>/state/<slug>/agent
- */
-export function stateAgentDir(env, absWorkdir) {
-    return join(resolveAnonPiHome(env), 'state', pathSlug(absWorkdir), 'agent');
-}
 /**
  * Normalise a proxy-less host:port key from an ANON_PI_LLM value or a provider
  * baseUrl, so `192.168.1.150:8080` matches `http://192.168.1.150:8080/v1`.
@@ -126,182 +906,476 @@ export function hostPortKey(value) {
     v = v.replace(/^[^@]*@/, ''); // drop any user:pass@
     return v.toLowerCase();
 }
-/** apiKey values that are NOT real secrets (safe to carry into the seed). */
-const BENIGN_API_KEYS = new Set(['', 'none', 'ollama', 'no-key', 'local']);
 /**
- * PURE: given a parsed host models.json and the ANON_PI_LLM value, select the
- * provider whose baseUrl points at that host:port and return a barebones
- * models.json carrying ONLY that provider (verbatim, with its models). Throws
- * AnonPiError if nothing matches. Carries no other provider (so etherplay /
- * google / paid API keys never enter the seed).
+ * The provider key anon-pi gives the single local provider it generates. A
+ * neutral, host-agnostic name (matches the CONTEXT glossary's "local model"):
+ * it carries NO host identity, unlike the old `import` path which kept the
+ * host's own provider key.
+ */
+export const LOCAL_PROVIDER_NAME = 'local';
+/**
+ * The pi `api` dialect the generated local provider speaks. Local model servers
+ * (llama.cpp, ollama, LM Studio, vLLM, ...) are overwhelmingly OpenAI-compatible
+ * and serve the completions API under `/v1`, so this is the safe default for an
+ * endpoint captured by `init` (there is no host models.json to copy a dialect
+ * from anymore). See the ## Decisions note in the done record.
+ */
+export const LOCAL_PROVIDER_API = 'openai-completions';
+/**
+ * A benign, non-secret apiKey for the local provider (a LAN model rarely needs a
+ * real key). It is one of the values pi never flags as a real secret.
+ */
+export const LOCAL_PROVIDER_API_KEY = 'none';
+/**
+ * apiKey values that are NOT real secrets (safe to carry into the anonymized
+ * seed verbatim). Anything else is treated as a REAL secret: `init` refuses to
+ * seed it (which would put a host credential into the anon home) unless the
+ * operator passes `--force-allow-local-llm-api-key`.
+ */
+export const BENIGN_API_KEYS = new Set([
+    '',
+    'none',
+    'ollama',
+    'no-key',
+    'nokey',
+    'local',
+    'dummy',
+    'sk-no-key-required',
+]);
+/** PURE: whether an apiKey looks like a REAL secret (i.e. not in the benign set). */
+export function apiKeyLooksReal(apiKey) {
+    if (apiKey === undefined)
+        return false;
+    return !BENIGN_API_KEYS.has(apiKey.trim().toLowerCase());
+}
+/**
+ * PURE: turn a discovered model `id` into a minimal-but-valid pi model entry.
+ * `name` defaults to the id; a LAN model is free, so every cost is 0.
  */
-export function pickProviderForLlm(hostModels, llmDirect) {
+export function localModelEntry(id) {
+    return {
+        id,
+        name: id,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    };
+}
+/**
+ * PURE: extract the model ids from a parsed OpenAI-compatible `/v1/models`
+ * response (`{ data: [{ id }, ...] }`, as llama.cpp / vLLM / LM Studio serve).
+ * Tolerates a bare array, a `models` key, missing/garbage input (returns []), so
+ * `init` can feed whatever the endpoint returned straight in.
+ */
+export function parseModelsListing(raw) {
+    const rows = Array.isArray(raw)
+        ? raw
+        : raw && typeof raw === 'object'
+            ? (raw.data ??
+                raw.models ??
+                [])
+            : [];
+    if (!Array.isArray(rows))
+        return [];
+    const ids = [];
+    for (const r of rows) {
+        if (typeof r === 'string') {
+            if (r.trim() !== '')
+                ids.push(r.trim());
+        }
+        else if (r && typeof r === 'object') {
+            const id = r.id;
+            if (typeof id === 'string' && id.trim() !== '')
+                ids.push(id.trim());
+        }
+    }
+    return ids;
+}
+/**
+ * PURE: find, in a parsed host `~/.pi/agent/models.json`, the provider whose
+ * `baseUrl` points at `llmEndpoint` (matched via hostPortKey), and return ONLY
+ * that provider's models + apiKey. This is the anonymity-critical scoping: the
+ * ONLY provider considered is the one served by the `--allow-direct` endpoint,
+ * so no other provider (etherplay/google/a paid API) — and no other provider's
+ * key — can ever enter the seed. Returns undefined when no provider matches.
+ *
+ * The `--allow-direct` target and this match both go through hostPortKey, so a
+ * URL / ip:port / bare-ip host config all match the same endpoint.
+ */
+export function pickLocalProviderModels(hostModels, llmEndpoint) {
     const providers = hostModels.providers ?? {};
-    const want = hostPortKey(llmDirect);
-    const matches = [];
-    for (const [name, p] of Object.entries(providers)) {
+    const want = hostPortKey(llmEndpoint);
+    for (const p of Object.values(providers)) {
         if (!p || typeof p !== 'object' || !p.baseUrl)
             continue;
-        if (hostPortKey(p.baseUrl) === want)
-            matches.push(name);
-    }
-    if (matches.length === 0) {
-        const known = Object.entries(providers)
-            .filter(([, p]) => p && p.baseUrl)
-            .map(([n, p]) => `  ${n}: ${p.baseUrl}`)
-            .join('\n');
-        throw new AnonPiError(`anon-pi import: no provider in your host models.json points at ANON_PI_LLM (${want}).\n` +
-            (known
-                ? `Providers found:\n${known}\n`
-                : 'No providers with a baseUrl were found.\n') +
-            'Set ANON_PI_LLM to the host:port of a provider above, or add that provider to pi first.');
-    }
-    const name = matches[0];
-    const provider = providers[name];
-    const key = (provider.apiKey ?? '').trim().toLowerCase();
-    const apiKeyLooksReal = !BENIGN_API_KEYS.has(key);
+        if (hostPortKey(p.baseUrl) !== want)
+            continue;
+        const models = [];
+        for (const m of p.models ?? []) {
+            if (m && typeof m === 'object') {
+                const id = m.id;
+                if (typeof id === 'string' && id.trim() !== '') {
+                    models.push({ ...m, id: id.trim() });
+                }
+            }
+            else if (typeof m === 'string' && m.trim() !== '') {
+                models.push(localModelEntry(m.trim()));
+            }
+        }
+        return {
+            models,
+            apiKey: p.apiKey,
+            apiKeyLooksReal: apiKeyLooksReal(p.apiKey),
+        };
+    }
+    return undefined;
+}
+/**
+ * PURE: merge the host-config models (rich, `configured: true`) with the
+ * endpoint's live `/v1/models` ids (`configured: false` for any the host did not
+ * already carry), into ONE deduped, sorted candidate list. Host config wins on
+ * an id present in both (it has the real config). Every candidate here is served
+ * by the endpoint, so every one is `--allow-direct`-reachable; the merge just
+ * unions "what you already configured" with "what the server also offers".
+ */
+export function mergeModelSources(hostModels, serverIds) {
+    const byId = new Map();
+    for (const m of hostModels) {
+        const id = m.id.trim();
+        if (id === '')
+            continue;
+        byId.set(id, { id, configured: true, entry: { ...m, id } });
+    }
+    for (const raw of serverIds) {
+        const id = raw.trim();
+        if (id === '' || byId.has(id))
+            continue;
+        byId.set(id, { id, configured: false, entry: localModelEntry(id) });
+    }
+    return Array.from(byId.values()).sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * PURE: synthesize a pi `models.json` for the local provider from an endpoint
+ * and the CHOSEN model entries. It normalises the endpoint with hostPortKey and
+ * returns a models.json carrying exactly ONE provider (named LOCAL_PROVIDER_NAME
+ * — a neutral name, no host fingerprint) pointed at that endpoint.
+ *
+ * `apiKey` defaults to the benign LOCAL_PROVIDER_API_KEY. A caller may pass the
+ * host provider's real key ONLY under an explicit force flag; the benign/real
+ * decision (and the refusal) lives in `init`, not here — this pure function just
+ * writes what it is given.
+ *
+ * Accepts either full model entries (from the host config) or bare id strings
+ * (which it turns into minimal entries). Empty models => a provider pointed at
+ * the endpoint with no pickable model (the degraded fallback).
+ */
+export function generateModelsJson(llmEndpoint, models = [], apiKey = LOCAL_PROVIDER_API_KEY) {
+    const hostPort = hostPortKey(llmEndpoint);
+    const entries = [];
+    const seen = new Set();
+    for (const m of models) {
+        const entry = typeof m === 'string' ? localModelEntry(m.trim()) : m;
+        const id = entry.id.trim();
+        if (id === '' || seen.has(id))
+            continue;
+        seen.add(id);
+        entries.push({ ...entry, id });
+    }
+    entries.sort((a, b) => a.id.localeCompare(b.id));
+    const provider = {
+        api: LOCAL_PROVIDER_API,
+        apiKey,
+        baseUrl: `http://${hostPort}/v1`,
+        models: entries,
+    };
+    return { providers: { [LOCAL_PROVIDER_NAME]: provider } };
+}
+/**
+ * PURE: the model-selection settings.json fragment for the seeded local
+ * provider: `defaultProvider` = LOCAL_PROVIDER_NAME, `defaultModel` = the chosen
+ * default id, `enabledModels` = `local/<id>` for each imported model (pi's
+ * `<provider>/<id>` convention). The caller MERGES this into any existing
+ * settings so image-staged settings (packages/extensions) are preserved.
+ */
+export function generateModelSelection(modelIds, defaultId) {
+    const ids = Array.from(new Set(modelIds.map((m) => m.trim()).filter((m) => m !== ''))).sort((a, b) => a.localeCompare(b));
     return {
-        name,
-        models: { providers: { [name]: provider } },
-        apiKeyLooksReal,
+        defaultProvider: LOCAL_PROVIDER_NAME,
+        defaultModel: defaultId.trim(),
+        enabledModels: ids.map((id) => `${LOCAL_PROVIDER_NAME}/${id}`),
     };
 }
 /**
- * The default host models.json path `import` reads FROM. Overridable via
- * ANON_PI_SOURCE_MODELS; defaults to the real pi config (~/.pi/agent/models.json
- * under the container-less host HOME, or PI_CODING_AGENT_DIR if the user set it).
+ * PURE: shallow-merge the local-model selection into an existing (parsed)
+ * settings.json object, returning the merged object. Only the three selection
+ * keys are overwritten; every other key the user/image had (packages,
+ * extensions, thinking level, ...) is preserved. `existing` undefined/garbage is
+ * treated as `{}`.
  */
-export function resolveSourceModelsPath(env) {
-    if (env.sourceModels && env.sourceModels.trim() !== '') {
-        return resolve(env.sourceModels);
-    }
+export function mergeModelSelection(existing, selection) {
+    const base = existing && typeof existing === 'object'
+        ? { ...existing }
+        : {};
+    base.defaultProvider = selection.defaultProvider;
+    base.defaultModel = selection.defaultModel;
+    base.enabledModels = selection.enabledModels;
+    return base;
+}
+/**
+ * The host `~/.pi/agent/models.json` path `init` reads the matching local
+ * provider from. Uses the container-less host HOME (or PI_CODING_AGENT_DIR when
+ * the user relocated pi's agent dir). This is READ-ONLY (init copies only the
+ * ONE matching provider's models); it is never written.
+ */
+export function resolveHostModelsPath(env) {
     const agentDir = env.piAgentDir && env.piAgentDir.trim() !== ''
         ? env.piAgentDir
         : join(env.home, '.pi', 'agent');
     return join(agentDir, MODELS_FILE);
 }
+// --- `anon-pi init` onboarding: the PURE proxy detect/verify DECISIONS --------
+//
+// `anon-pi init` onboards HONESTLY (this is an anonymity tool): its proxy step
+// presents EVIDENCE only (open ports, a real SOCKS5 handshake, a real `netcage
+// verify` exit IP) plus WEAK process hints. It MUST NEVER claim/label the exit
+// provider: a SOCKS proxy does not announce Mullvad/Proton/NordVPN/etc, so a
+// provider label would be a DANGEROUS LIE. This module owns the pure decisions
+// (handshake interpretation, the findings-without-labels formatter, the weak
+// hint wording, the verify exit-IP parse); the socket probes, the `netcage
+// verify` / `podman build` spawns, and the prompts are cli.ts's thin I/O.
 /**
- * Build the run plan from the environment + the (optional) workdir arg. PURE: it
- * resolves paths and composes the netcage argv, performing NO filesystem writes
- * or spawns. It THROWS AnonPiError for the required inputs (image, llm, proxy).
+ * The default SOCKS ports `init` probes, each with a WEAK, structural hint (the
+ * conventional tool that DEFAULTS to that port). The hint names a local tool a
+ * port is CONVENTIONALLY used by, NOT the exit provider: `9050`/`9150` are Tor's
+ * own listeners (Tor IS the tool, so naming it is honest), `1080` is the generic
+ * SOCKS default (wireproxy / `ssh -D` / other), which is why its hint stays
+ * provider-agnostic ("wireproxy / ssh -D / generic"): behind a `1080` wireproxy
+ * could be ANY WireGuard VPN, and we never guess which. See the ADR / Decisions.
+ */
+export const DEFAULT_SOCKS_PROBE_PORTS = [
+    { port: 9050, hint: 'Tor default (system tor)' },
+    { port: 9150, hint: 'Tor Browser default' },
+    { port: 1080, hint: 'generic SOCKS (wireproxy / ssh -D)' },
+];
+/**
+ * The SOCKS5 method-selection greeting `init` sends to CONFIRM a port really
+ * speaks SOCKS5 (RFC 1928 §3): version 5, one method offered, `0x00`
+ * (no-authentication). A real SOCKS5 server replies with two bytes
+ * `[0x05, <method>]`; anything else is not SOCKS5. Exposed as a constant so the
+ * probe I/O and the handshake test send byte-identical bytes.
+ */
+export const SOCKS5_METHOD_SELECTOR = [0x05, 0x01, 0x00];
+/**
+ * PURE: interpret a SOCKS5 method-selection REPLY (the bytes read back after
+ * sending SOCKS5_METHOD_SELECTOR). A valid reply is EXACTLY the two bytes
+ * `[0x05, <method>]` where `<method> != 0xff` (0xff = "no acceptable methods",
+ * i.e. the server IS SOCKS5 but rejected no-auth; that is still a SOCKS5 server,
+ * but for a bare no-auth probe we treat it as a soft failure so the finding does
+ * not imply the port is usable no-auth). Any non-5 first byte, a short reply, or
+ * an empty reply is NOT SOCKS5.
  *
- * Statefulness (Model B): a persistent per-workdir host dir is mounted at the
- * container's ~/.pi/agent, so pi's sessions/history/settings/extensions persist.
- * First-launch seed (Model C): when that home is FRESH, the container run
- * command promotes the image's staged defaults + the imported models.json into
- * it and stamps a marker; thereafter pi OWNS the home and nothing is clobbered.
+ * Reply in -> verdict out; the socket read is cli.ts's job. The reason strings
+ * are deliberately structural ("no reply", "not SOCKS5") and NEVER name a
+ * provider.
+ */
+export function interpretSocks5Handshake(reply) {
+    const bytes = Array.from(reply);
+    if (bytes.length === 0)
+        return { socks5: false, reason: 'no reply' };
+    if (bytes.length < 2)
+        return { socks5: false, reason: 'short reply' };
+    if (bytes[0] !== 0x05)
+        return { socks5: false, reason: 'not SOCKS5' };
+    const method = bytes[1];
+    if (method === 0xff) {
+        return { socks5: false, reason: 'SOCKS5 but no acceptable auth method' };
+    }
+    return { socks5: true, method };
+}
+/**
+ * PURE: map an observed local process name to a WEAK, hedged hint, or undefined
+ * when we have nothing honest to say. The ONLY confident mapping is `tor` ->
+ * "likely Tor", because Tor is a LOCAL tool that runs its OWN SOCKS listener (so
+ * seeing `tor` is real evidence the port is Tor). We do NOT map anything to an
+ * EXIT provider (Mullvad/Proton/...): a `wireproxy` process only tells us the
+ * SOCKS front-end, never which VPN sits behind it, so its hint stays
+ * provider-agnostic. Every returned hint is HEDGED ("likely", "-> a SOCKS
+ * front-end") and never states the exit provider.
+ */
+export function processHint(processName) {
+    const name = processName.trim().toLowerCase();
+    if (name === '')
+        return undefined;
+    if (name === 'tor') {
+        return {
+            process: processName,
+            hint: 'a `tor` process is running -> likely Tor',
+        };
+    }
+    if (name === 'wireproxy') {
+        return {
+            process: processName,
+            // A SOCKS front-end for SOME WireGuard VPN; we NEVER guess which one.
+            hint: 'a `wireproxy` process is running -> a SOCKS front-end for a ' +
+                'WireGuard VPN (which one is not observable here)',
+        };
+    }
+    return undefined;
+}
+/**
+ * The set of substrings a findings line must NEVER contain: known exit-provider
+ * / VPN brand names. This is the machine-checkable half of the never-label rule
+ * (a test asserts formatProxyFindings' output contains NONE of these for any
+ * input). It is not exhaustive of every brand, but it pins the obvious ones so a
+ * regression that starts labelling providers is caught. `tor` is NOT here: Tor
+ * is the LOCAL tool we legitimately hint at, not an opaque exit provider.
+ */
+export const FORBIDDEN_PROVIDER_LABELS = [
+    'mullvad',
+    'proton',
+    'nordvpn',
+    'nord vpn',
+    'expressvpn',
+    'express vpn',
+    'surfshark',
+    'ivpn',
+    'pia',
+    'private internet access',
+    'cyberghost',
+    'windscribe',
+];
+/**
+ * PURE: format the probe findings into the human-readable block `init` shows
+ * before asking the user to CHOOSE a proxy. It renders EVIDENCE ONLY: for each
+ * candidate, the `host:port`, whether it is open, the SOCKS5 handshake verdict,
+ * and the structural PORT hint. It NEVER emits an exit-provider label (a SOCKS
+ * proxy does not announce its provider; a false label is a dangerous lie). The
+ * `## Decisions` note + a test assert the output never contains a
+ * FORBIDDEN_PROVIDER_LABELS substring for any input.
  *
- * `modelsSeedExists` reports whether the canonical import models.json exists (so
- * it is mounted for the seed); `stateExists` reports whether this workdir's
- * state home already exists (so `fresh` is known).
+ * `processNote` is the HOST-WIDE weak process hint (a running `tor`/`wireproxy`
+ * LOCAL process), shown ONCE as a general note rather than glued onto every port
+ * line: the observation is host-wide, not per-port, so repeating it on each
+ * candidate (including closed ports the process is unrelated to) reads as noise.
+ * A per-finding `processHint`, if still set, is also honoured inline for
+ * backward compatibility, but `init` now passes the host-wide note instead.
  *
- * --ephemeral mounts NO writable state: pi writes to the container's own
- * filesystem, which netcage runs with `--rm`, so it is destroyed when the
- * container exits. Nothing writable ever touches a host path; there is no
- * cleanup and no leftover-on-crash. (The read-only models.json seed is still
- * mounted; it is a single file anon-pi never writes to.)
- */
-export function buildRunPlan(env, workdirArg, modelsSeedExists, stateExists) {
-    if (!env.image || env.image.trim() === '') {
-        // dockerfilePath is injected (cli.ts resolves the shipped Dockerfile.pi via
-        // import.meta.url; tests pass a fixed path). Every command is emitted
-        // flush-left so it copy-pastes cleanly: an indented heredoc would bake
-        // leading spaces into the Dockerfile and break the EOF terminator, so we
-        // point at the shipped file instead of printing a heredoc.
-        const df = env.dockerfilePath ?? 'Dockerfile.pi';
-        const wv = env.webveilDockerfilePath ?? 'examples/Dockerfile.pi-webveil';
-        throw new AnonPiError('anon-pi: set ANON_PI_IMAGE to a container image that has `pi` on its PATH.\n' +
-            '\n' +
-            'No image yet? A ready Dockerfile.pi ships with anon-pi (it installs the\n' +
-            'official @earendil-works/pi-coding-agent). Build it and point at it:\n' +
-            '\n' +
-            `podman build -t localhost/anon-pi-pi:latest -f "${df}" "$(dirname "${df}")"\n` +
-            'export ANON_PI_IMAGE=localhost/anon-pi-pi:latest\n' +
-            '\n' +
-            'Or the fuller example with the pi-webveil extension + a local SearXNG\n' +
-            '(anonymized web search):\n' +
-            '\n' +
-            `podman build -t localhost/anon-pi-webveil:latest -f "${wv}" "$(dirname "${wv}")"\n` +
-            'export ANON_PI_IMAGE=localhost/anon-pi-webveil:latest\n' +
-            '\n' +
-            'See the README (Providing a pi image) for details and a community-image note.');
-    }
-    if (!env.llmDirect || env.llmDirect.trim() === '') {
-        throw new AnonPiError('anon-pi: set ANON_PI_LLM to the RFC1918/link-local IP[:port] of the local model pi should reach directly (e.g. ANON_PI_LLM=192.168.1.150:8080). All other egress stays forced through the proxy.');
-    }
-    if (!env.proxy || env.proxy.trim() === '') {
-        // No default: this is an anonymity tool, so the proxy is REQUIRED and never
-        // guessed (mirrors netcage, which fails closed without --proxy). A silent
-        // default would anonymize through the wrong endpoint, or fail deep in the
-        // jail with a confusing DNS error, if the guessed proxy is not actually up.
-        throw new AnonPiError('anon-pi: set ANON_PI_PROXY to your socks5h proxy. anon-pi has no default:\n' +
-            'the proxy is what makes the session anonymous, so it is never guessed.\n' +
-            '\n' +
-            'Pick the one you run (copy-paste), then re-run anon-pi:\n' +
-            '\n' +
-            '# Tor (system tor / Tor Browser bundle default port)\n' +
-            'export ANON_PI_PROXY=socks5h://127.0.0.1:9050\n' +
-            '\n' +
-            '# wireproxy -> a WireGuard VPN (Mullvad, Proton, ...); use YOUR configured\n' +
-            '# [Socks5] BindAddress port (1080 in wireproxy examples):\n' +
-            'export ANON_PI_PROXY=socks5h://127.0.0.1:1080\n' +
-            '\n' +
-            '# an SSH dynamic-forward (ssh -D 1080 host) or any other socks5h endpoint\n' +
-            'export ANON_PI_PROXY=socks5h://127.0.0.1:1080\n' +
-            '\n' +
-            'Only socks5h:// is accepted (plain socks5:// resolves DNS locally and leaks).');
-    }
-    const home = env.home;
-    if (!home || home.trim() === '') {
-        throw new AnonPiError('anon-pi: could not resolve HOME.');
-    }
-    const raw = workdirArg && workdirArg.trim() !== '' ? workdirArg : process.cwd();
-    const workdir = isAbsolute(raw) ? raw : resolve(raw);
-    // Persistent per-workdir state home, unless --ephemeral (no writable mount).
-    const ephemeral = env.ephemeral === true;
-    const stateDir = ephemeral ? '' : stateAgentDir(env, workdir);
-    // Ephemeral home is always fresh (the container's throwaway layer); a
-    // persistent home is fresh iff its dir is absent.
-    const fresh = ephemeral ? true : !stateExists(stateDir);
-    // The canonical imported models.json is mounted (read-only) for the seed only
-    // when it exists; pi can also start with no models and you add them in-session.
-    const modelsSeed = join(resolveConfigSeed(env), MODELS_FILE);
-    const haveModelsSeed = modelsSeedExists(modelsSeed);
-    const proxy = env.proxy.trim();
-    // netcage's --allow-direct wants a bare IP[:port]/CIDR (no scheme/path), but a
-    // user naturally sets ANON_PI_LLM to a URL (http://192.168.1.150:8080). Strip
-    // it to host:port with the same helper `import` uses to match providers, so a
-    // URL, an ip:port, or a bare ip all work.
-    const directTarget = hostPortKey(env.llmDirect);
-    const seedVersion = env.seedVersion ?? SEED_VERSION;
-    const netcageArgs = [
-        'run',
-        '--proxy',
-        proxy,
-        '--allow-direct',
-        directTarget,
-        '-it',
-        '-v',
-        workdir, // netcage defaults a target-less -v to /work and cwd to /work
-    ];
-    // Persistent mode ONLY: mount the per-workdir state home at ~/.pi/agent
-    // (Model B). --ephemeral mounts nothing writable: pi writes to the container's
-    // own --rm layer, gone on exit, no host state.
-    if (!ephemeral) {
-        netcageArgs.push('-v', `${stateDir}:${CONTAINER_AGENT_DIR}`);
-    }
-    // Mount the imported models.json read-only for the first-launch seed, if any.
-    if (haveModelsSeed) {
-        netcageArgs.push('-v', `${modelsSeed}:${CONTAINER_MODELS_SEED}:ro`);
+ * Findings in -> display string out; the socket probes are cli.ts's job.
+ */
+export function formatProxyFindings(findings, processNote) {
+    if (findings.length === 0) {
+        return 'No SOCKS ports responded on the probed set. Enter your proxy as host:port.';
     }
-    netcageArgs.push(env.image, 'sh', '-c', containerRunCmd(seedVersion));
-    return {
-        workdir,
-        stateDir,
-        configSeed: haveModelsSeed ? modelsSeed : '',
-        fresh,
-        netcageArgs,
-    };
+    const lines = [];
+    for (const f of findings) {
+        const where = `${f.host}:${f.port}`;
+        let status;
+        if (!f.open) {
+            status = 'closed (no TCP connection)';
+        }
+        else if (f.handshake && f.handshake.socks5) {
+            status = 'open, SOCKS5 handshake OK';
+        }
+        else if (f.handshake && !f.handshake.socks5) {
+            status = `open, but NOT SOCKS5 (${f.handshake.reason})`;
+        }
+        else {
+            status = 'open';
+        }
+        const hints = [];
+        if (f.portHint)
+            hints.push(f.portHint);
+        if (f.processHint)
+            hints.push(f.processHint);
+        const hintStr = hints.length > 0 ? ` [${hints.join('; ')}]` : '';
+        lines.push(`${where}: ${status}${hintStr}`);
+    }
+    // The host-wide process observation, shown ONCE (not per port). It is a weak
+    // LOCAL hint, never an exit-provider label.
+    if (processNote && processNote.trim() !== '') {
+        lines.push(`Note: ${processNote.trim()}`);
+    }
+    lines.push('These are EVIDENCE only (open ports + a real SOCKS5 handshake). A SOCKS ' +
+        'proxy does not announce its exit provider, so none is claimed here; the ' +
+        '`netcage verify` step below shows the real exit IP as proof.');
+    return lines.join('\n');
+}
+/**
+ * PURE: the `socks5h://<host:port>` URL `init` hands to `netcage verify` and
+ * writes into config.json. Only socks5h:// is accepted downstream (plain
+ * socks5:// resolves DNS locally and leaks), so `init` always emits socks5h.
+ * A value that already carries a scheme is normalised to its host:port first
+ * (via hostPortKey) so `socks5h://socks5h://...` can never be produced.
+ */
+export function socks5hUrl(hostPort) {
+    return `socks5h://${hostPortKey(hostPort)}`;
+}
+/**
+ * PURE: extract the exit IP `netcage verify` reported from its combined output.
+ * `netcage verify` prints the jail's forced-egress exit IP (an IPv4/IPv6 line)
+ * as PROOF the egress leaves via the proxy (not the host IP). We scan the output
+ * for the first plausible IP literal and return it; undefined if none is found
+ * (the caller then shows the raw output and lets the user judge). This is a
+ * best-effort PARSE of another tool's text, kept pure + tested so a format tweak
+ * is caught by a unit test, not only in the field.
+ */
+export function parseVerifyExitIp(output) {
+    // IPv4 first (the common case: ipify returns an IPv4 for most exits).
+    const v4 = output.match(/\b(?:\d{1,3}\.){3}\d{1,3}\b/);
+    if (v4) {
+        const ip = v4[0];
+        if (ip.split('.').every((o) => Number(o) <= 255))
+            return ip;
+    }
+    // IPv6 (a loose match: at least two groups and a colon-run), best-effort.
+    const v6 = output.match(/\b(?:[0-9a-fA-F]{0,4}:){2,}[0-9a-fA-F]{0,4}\b/);
+    if (v6 && v6[0].includes('::'))
+        return v6[0];
+    if (v6 && v6[0].split(':').filter(Boolean).length >= 3)
+        return v6[0];
+    return undefined;
+}
+/**
+ * PURE: the ordered image-menu entries `init` shows. `[1]` basic pi
+ * (Dockerfile.pi), `[2]` pi + webveil/SearXNG (examples/Dockerfile.pi-webveil),
+ * `[3]` an existing image ref, `[4]` skip. A single source so the prompt and its
+ * test agree on the order + wording.
+ */
+export function initImageMenu() {
+    return [
+        { choice: 'basic', label: 'basic pi (build the shipped Dockerfile.pi)' },
+        {
+            choice: 'webveil',
+            label: 'pi + webveil/SearXNG (build the shipped examples/Dockerfile.pi-webveil)',
+        },
+        { choice: 'existing', label: 'an existing image ref (I already have one)' },
+        {
+            choice: 'skip',
+            label: 'skip (create the machine imageless; pin it later)',
+        },
+    ];
+}
+/**
+ * PURE: build the `config.json` body `init` writes, keeping only the non-empty
+ * fields (a skipped image / llm is simply omitted, never written as ""). Emits
+ * pretty-printed JSON (tab indent, trailing newline) matching
+ * serializeMachineJson, so a browsed ~/.anon-pi/config.json reads cleanly. The
+ * proxy is REQUIRED (init only reaches here after a verified proxy), so it is
+ * always present; llm / defaultMachine / projects are included when set.
+ */
+export function serializeConfigJson(config) {
+    const out = {};
+    const proxy = nonEmpty(config.proxy);
+    if (proxy !== undefined)
+        out.proxy = proxy;
+    const llm = nonEmpty(config.llm);
+    if (llm !== undefined)
+        out.llm = llm;
+    const defaultMachine = nonEmpty(config.defaultMachine);
+    if (defaultMachine !== undefined)
+        out.defaultMachine = defaultMachine;
+    const projects = nonEmpty(config.projects);
+    if (projects !== undefined)
+        out.projects = projects;
+    return JSON.stringify(out, null, '\t') + '\n';
 }
 /**
  * Absolute path to the Dockerfile.pi that ships with anon-pi, resolved from this
@@ -337,82 +1411,185 @@ function shippedFile(rel) {
     }
     return undefined;
 }
+/**
+ * PURE: parse the tokens AFTER `machine` into a MachineCommand. Validates the
+ * machine name via validateName (the reserved-name / traversal guard) so the CLI
+ * only ever joins a safe segment under the machines dir. Throws AnonPiError
+ * (printed verbatim, exit 1) for an unknown/missing verb, a missing or extra
+ * positional, an unknown flag, or a bad name.
+ *
+ * The grammar is deliberately small and flag-light (mirrors the launch grammar's
+ * `--yes` / `--image` shape): `--image <ref>` on create, `--yes` on rm; no other
+ * flags. This keeps `machine` a thin, predictable dispatch surface.
+ */
+export function parseMachineArgs(args) {
+    const fail = (msg) => {
+        throw new AnonPiError(`anon-pi: ${msg}\nRun \`anon-pi machine --help\` or \`anon-pi --help\`.`);
+    };
+    const verb = args[0];
+    if (verb === undefined) {
+        fail('`machine` needs a subcommand: create | list | set-image | rm');
+    }
+    const rest = args.slice(1);
+    if (verb === 'list') {
+        if (rest.length > 0)
+            fail(`machine list takes no arguments, got: ${rest.join(' ')}`);
+        return { verb: 'list' };
+    }
+    if (verb === 'create') {
+        let name;
+        let image;
+        for (let i = 0; i < rest.length; i++) {
+            const a = rest[i];
+            if (a === '--image') {
+                const v = rest[++i];
+                if (v === undefined)
+                    fail('--image needs an image ref');
+                image = v;
+                continue;
+            }
+            if (a.startsWith('-'))
+                fail(`unknown option: ${a}`);
+            if (name !== undefined)
+                fail(`machine create takes one name, got extra: ${a}`);
+            name = validateName(a, 'machine');
+        }
+        if (name === undefined)
+            fail('machine create needs a <name>');
+        return { verb: 'create', name: name, image: nonEmpty(image) };
+    }
+    if (verb === 'set-image') {
+        let name;
+        let image;
+        for (const a of rest) {
+            if (a.startsWith('-'))
+                fail(`unknown option: ${a}`);
+            if (name === undefined) {
+                name = validateName(a, 'machine');
+            }
+            else if (image === undefined) {
+                image = a;
+            }
+            else {
+                fail(`machine set-image takes <name> <ref>, got extra: ${a}`);
+            }
+        }
+        if (name === undefined)
+            fail('machine set-image needs a <name> and an <image-ref>');
+        if (nonEmpty(image) === undefined)
+            fail('machine set-image needs an <image-ref>');
+        return {
+            verb: 'set-image',
+            name: name,
+            image: image.trim(),
+        };
+    }
+    if (verb === 'rm') {
+        let name;
+        let yes = false;
+        for (const a of rest) {
+            if (a === '--yes' || a === '-y') {
+                yes = true;
+                continue;
+            }
+            if (a.startsWith('-'))
+                fail(`unknown option: ${a}`);
+            if (name !== undefined)
+                fail(`machine rm takes one name, got extra: ${a}`);
+            name = validateName(a, 'machine');
+        }
+        if (name === undefined)
+            fail('machine rm needs a <name>');
+        return { verb: 'rm', name: name, yes };
+    }
+    return fail(`unknown machine subcommand: ${verb} (create | list | set-image | rm)`);
+}
+/**
+ * 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
+ * source so create + set-image write byte-identical, pretty-printed JSON (tab
+ * indent, trailing newline) that reads cleanly when the user browses
+ * ~/.anon-pi/machines/<M>/machine.json.
+ */
+export function serializeMachineJson(config) {
+    const out = {};
+    if (nonEmpty(config.image) !== undefined)
+        out.image = config.image.trim();
+    if (nonEmpty(config.projects) !== undefined)
+        out.projects = config.projects.trim();
+    return JSON.stringify(out, null, '\t') + '\n';
+}
+/**
+ * PURE: the compatibility WARNING `machine set-image` prints after re-pinning
+ * the image. Re-pinning does NOT reseed or touch the home: the home's pi
+ * extensions / downloaded bin were built against the OLD image, so a mismatched
+ * new image may misbehave. The message tells the user the two remedies (re-run
+ * `pi install` inside the machine, or delete the home to reseed) WITHOUT doing
+ * either automatically. See the ## Decisions note (set-image warning wording).
+ */
+export function setImageWarning(name, oldImage, newImage) {
+    const from = oldImage === undefined ? '(none)' : oldImage;
+    return (`anon-pi: re-pinned machine ${JSON.stringify(name)} image ${from} -> ${newImage}.\n` +
+        'WARNING: the home was NOT reseeded. Its pi extensions and downloaded tools\n' +
+        'were built for the old image; if they misbehave on the new one, re-run\n' +
+        '`pi install` inside the machine, or delete + reseed the home with\n' +
+        `\`anon-pi --delete-home ${name}\` (then relaunch to seed fresh).`);
+}
 /** Read the AnonPiEnv from a process env map (kept separate so tests inject one). */
 export function envFromProcess(penv) {
     return {
         home: penv.HOME ?? homedir(),
         proxy: penv.ANON_PI_PROXY,
         anonPiHome: penv.ANON_PI_HOME,
-        configSeed: penv.ANON_PI_CONFIG,
+        projects: penv.ANON_PI_PROJECTS,
         image: penv.ANON_PI_IMAGE,
         llmDirect: penv.ANON_PI_LLM,
         xdgConfigHome: penv.XDG_CONFIG_HOME,
+        piAgentDir: penv.PI_CODING_AGENT_DIR,
         dockerfilePath: shippedDockerfilePath(),
         webveilDockerfilePath: shippedWebveilDockerfilePath(),
-        sourceModels: penv.ANON_PI_SOURCE_MODELS,
-        piAgentDir: penv.PI_CODING_AGENT_DIR,
-        ephemeral: isTruthy(penv.ANON_PI_EPHEMERAL),
     };
 }
-/** Whether an env-var string is set to a truthy value (1/true/yes, any case). */
-function isTruthy(v) {
-    if (!v)
-        return false;
-    const s = v.trim().toLowerCase();
-    return s === '1' || s === 'true' || s === 'yes' || s === 'on';
-}
 /** The --help text (kept here so it is covered by the same module). */
-export const HELP = `anon-pi - launch pi inside a netcage (anonymized egress + one direct local model)
+export const HELP = `anon-pi - run pi on anonymized, jailed machines (netcage: forced egress + one direct local model)
 
 USAGE
-  anon-pi [WORKDIR]     launch pi jailed, working in WORKDIR (default: cwd)
-  anon-pi import        seed models.json from your local model
-
-  WORKDIR   the host folder pi works in (mounted at ${CONTAINER_WORKDIR}; pi's cwd). Files pi
-            writes there land on the host.
-
-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).
-
-  STATEFUL by default: a persistent per-workdir home
-  (<ANON_PI_HOME>/state/<workdir>/agent) is mounted at the container's
-  ~/.pi/agent, so your conversations, history, settings (model choice), and any
-  extensions you \`pi install\` persist across launches. Re-running in the same
-  folder resumes it. On a FRESH home, the image's staged defaults (extensions,
-  trust) and your imported models.json are seeded in once; after that pi owns the
-  home and nothing is overwritten. Requires \`netcage\`.
+  anon-pi                        MENU: pick a project (pi), a shell, or a new project
+  anon-pi <project>              pi in the project (${CONTAINER_PROJECTS_ROOT}/<project>); exit pi -> host
+  anon-pi <project> <pi-args…>   forward args to pi (headless/one-shot; no TTY needed)
+  anon-pi --shell [<project>]    a jailed bash (at ~, or cd'd into <project>) - the project-hopper
+  anon-pi -m <machine> [<p>]     the same, on <machine> (its own image + home + conversations)
+  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 --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
 
-  --ephemeral (or ANON_PI_EPHEMERAL=1): mount NO writable state; pi writes to the
-  container's own --rm layer, gone on exit. Nothing writable touches the host,
-  no cleanup, no leftover-on-crash.
+  <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 ~).
 
-  --fresh: delete this workdir's persistent state home first, so the (possibly
-  rebuilt) image's defaults + your imported models.json are re-seeded. Use it
-  after rebuilding your image to pick up new extensions/config.
+  [--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.
 
-import
-  Reads your host ~/.pi/agent/models.json, picks the provider whose baseUrl
-  serves ANON_PI_LLM, and writes JUST that provider to the canonical seed
-  (<ANON_PI_CONFIG>/models.json). No other provider's API keys, no sessions, no
-  identity. It SEEDS a fresh home; models you later add inside pi persist and are
-  never clobbered. Re-run with --force to overwrite the canonical seed.
+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
+  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\`.
 
 ENVIRONMENT
-  ANON_PI_IMAGE   (required for run) image with \`pi\` on PATH. No image yet?
-                  Running anon-pi without it prints a ready-to-build
-                  Dockerfile.pi recipe; see the README (Providing a pi image).
-  ANON_PI_LLM     (required) RFC1918/link-local IP[:port] of the local model
   ANON_PI_PROXY   (required) socks5h URL of your proxy (Tor/wireproxy/ssh -D).
                   No default: the proxy is what anonymizes, so it is never guessed.
-  ANON_PI_EPHEMERAL  set to 1 for a throwaway (non-persistent) session
-  ANON_PI_HOME    anon-pi home (default $XDG_CONFIG_HOME/anon-pi or ~/.config/anon-pi)
-  ANON_PI_CONFIG  canonical seed dir holding models.json (default <ANON_PI_HOME>/agent)
-  ANON_PI_SOURCE_MODELS  (import) host models.json to read (default ~/.pi/agent/models.json)
-
-RESET A SESSION
-  anon-pi --fresh [WORKDIR]   drop the session home and re-seed on this launch.
-  Or delete it by hand: rm -rf <ANON_PI_HOME>/state/<workdir-slug>/agent
+  ANON_PI_LLM     (required) RFC1918/link-local IP[:port] of the local model
+  ANON_PI_IMAGE   image with \`pi\` on PATH, used when a machine has no image set.
+                  No image yet? See the README (Providing a pi image).
+  ANON_PI_HOME    anon-pi workspace dir (default ~/.anon-pi; NOT under ~/.config)
+  ANON_PI_PROJECTS  projects root override (host dir mounted at ${CONTAINER_PROJECTS_ROOT})
 
 PLATFORM
   Linux only (via netcage's netns/nft jail). On macOS/Windows it works only