anon-pi 0.4.0 → 0.6.0

package/dist/anon-pi.d.ts

@@ -1,11 +1,36 @@
-/** The container path the workdir is mounted at (pi's cwd). */
-export declare 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 declare 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 declare 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 declare 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 declare 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 declare const CONTAINER_AGENT_DIR = "/root/.pi/agent";
 /**
@@ -21,10 +46,25 @@ export declare const CONTAINER_STAGE_DIR = "/opt/anon-pi-seed/agent";
  * staged defaults. Read-only: the container never writes back to the host seed.
  */
 export declare 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 declare const CONTAINER_SETTINGS_SEED = "/anon-pi-seed/settings.json";
 /** Marker file written into the agent dir after seeding; holds the seed version. */
 export declare 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 declare const MODELS_FILE = "models.json";
+/** pi's settings file (holds defaultModel/defaultProvider/enabledModels + more). */
+export declare 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 declare 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
@@ -44,16 +84,26 @@ export interface AnonPiEnv {
     home: string;
     /** socks5h proxy URL. REQUIRED (no default: the proxy is what anonymizes). */
     proxy?: string;
-    /** The anon-pi home dir. Default $XDG_CONFIG_HOME/anon-pi or ~/.config/anon-pi. */
+    /** The anon-pi home dir. Default ~/.anon-pi (NOT under ~/.config). */
     anonPiHome?: string;
-    /** Override the canonical seed dir. Default <anonPiHome>/agent. */
-    configSeed?: string;
+    /**
+     * Projects-root override from env (ANON_PI_PROJECTS). Sits above
+     * machine.json/config.json in the projects-root chain, below the later
+     * --mount CLI override. See resolveProjectsRoot.
+     */
+    projects?: string;
     /** The container image that has `pi` on PATH. REQUIRED. */
     image?: string;
     /** The RFC1918/link-local IP[:port] of the local model. REQUIRED. */
     llmDirect?: string;
     /** XDG_CONFIG_HOME, if set (used to derive the default anon-pi home). */
     xdgConfigHome?: string;
+    /**
+     * The host pi agent dir (PI_CODING_AGENT_DIR), used ONLY to locate the host
+     * `~/.pi/agent/models.json` that `init` reads the matching local provider
+     * from. Defaults to ~/.pi/agent. Never written.
+     */
+    piAgentDir?: string;
     /**
      * Absolute path to the Dockerfile.pi that ships with anon-pi, used only to
      * make the missing-image error's build command concrete. cli.ts resolves it
@@ -66,43 +116,591 @@ export interface AnonPiEnv {
      * + SearXNG), used to make the missing-image error mention the fuller build.
      */
     webveilDockerfilePath?: string;
-    /** `import` source models.json override (ANON_PI_SOURCE_MODELS). */
-    sourceModels?: string;
-    /** The host pi agent dir override (PI_CODING_AGENT_DIR), used to find models.json. */
-    piAgentDir?: string;
-    /** When true, use a throwaway state home (no persistence). Default false. */
-    ephemeral?: boolean;
     /** The seed version anon-pi stamps into a fresh home. Default SEED_VERSION. */
     seedVersion?: string;
 }
-/** The fully-resolved run plan cli.ts executes. */
-export interface RunPlan {
-    /** Absolute workdir on the host (mounted at /work). */
-    workdir: string;
+/** A user-facing error whose message is meant to be printed verbatim (no stack). */
+export declare class AnonPiError extends Error {
+}
+/**
+ * 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 declare const PROXY_REQUIRED_MESSAGE: string;
+/**
+ * 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 declare function resolveAnonPiHome(env: AnonPiEnv): string;
+/** A machine's directory: <home>/machines/<name> (holds machine.json + home/). */
+export declare function machineDir(env: AnonPiEnv, name: string): string;
+/** A machine's persistent HOST home: <home>/machines/<name>/home (bind-mounted at /root). */
+export declare function machineHomeDir(env: AnonPiEnv, name: string): string;
+/** A machine's machine.json path: <home>/machines/<name>/machine.json. */
+export declare function machineJsonPath(env: AnonPiEnv, name: string): string;
+/** The sessions dirname pi keeps its per-cwd conversation dirs under (in the agent dir). */
+export declare 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 declare function machineAgentDir(env: AnonPiEnv, name: string): string;
+/**
+ * A machine's HOST pi sessions dir: <machineAgentDir>/sessions. Each per-cwd
+ * conversation is a slug-named subdir here (projectSessionSlug for a project).
+ */
+export declare function machineSessionsDir(env: AnonPiEnv, name: string): string;
+/**
+ * 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 declare function machineProjectSessionDir(env: AnonPiEnv, machine: string, project: string): string;
+/** The built-in default global projects root: <home>/projects. */
+export declare function builtinProjectsRoot(env: AnonPiEnv): string;
+/** The affected-path plan for `--delete-home <machine>`. */
+export interface DeleteHomePlan {
+    /** The machine whose home is dropped. */
+    machine: string;
+    /**
+     * The single dir removed: the machine's persistent HOST home
+     * (machineHomeDir). The machine dir's machine.json (its image pin) is KEPT, so
+     * the machine can be relaunched to seed a FRESH home.
+     */
+    home: string;
+}
+/**
+ * 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 declare function resolveDeleteHome(env: AnonPiEnv, machine: string): DeleteHomePlan;
+/** The affected-path plan for `--delete-project <project>`. */
+export interface DeleteProjectPlan {
+    /** The project whose files + per-machine sessions are dropped. */
+    project: string;
+    /** The project's files: <projectsRoot>/<project> (the host folder). */
+    folder: string;
     /**
-     * The PERSISTENT per-workdir state dir on the host, mounted at the container's
-     * ~/.pi/agent. Everything pi writes here survives. For --ephemeral this is a
-     * throwaway path cli.ts creates + discards.
+     * The per-machine session dirs for this project's (machine-invariant) slug,
+     * ONE per supplied machine, in the SUPPLIED order. The homes themselves are
+     * kept; only these slug dirs are dropped. The CLI supplies the machine names
+     * (readdir of machines/) and skips any that do not exist on disk.
      */
-    stateDir: string;
-    /** The canonical host models.json (from `import`) mounted read-only for the seed, or '' if absent. */
-    configSeed: string;
-    /** True when this workdir has no state yet (fresh home; the seed will run). */
+    sessions: string[];
+}
+/**
+ * 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 declare function resolveDeleteProject(args: {
+    env: AnonPiEnv;
+    project: string;
+    /** The resolved projects root (host dir mounted at /projects). */
+    projectsRoot: string;
+    /** The machine names whose homes may hold this project's session dir. */
+    machines: readonly string[];
+}): DeleteProjectPlan;
+/**
+ * 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 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.
+ */
+export declare const RESERVED_NAMES: readonly string[];
+/** What a name names, for a clear validation error. */
+export type NameKind = 'machine' | 'project';
+/**
+ * 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 declare function validateName(name: string, kind: NameKind): string;
+/**
+ * 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 declare function projectHostDir(projectsRoot: string, name: string): string;
+/**
+ * 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 declare function projectContainerCwd(name: string): string;
+/** Which mounted root a launch cwds into (see the CONTAINER_* root constants). */
+export type RootKind = 'projects' | 'mount' | 'machine';
+/** True iff `token` is exactly the root token `.` ("the root itself"). */
+export declare function isRootToken(token: string | undefined): boolean;
+/** PURE: the jail cwd of a root itself: /projects, /work (mount), or ~ (machine). */
+export declare function rootCwd(kind: RootKind): string;
+/**
+ * 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 declare function resolveCwd(kind: RootKind, token: string): string;
+/** Parsed shape of config.json. All fields optional (a hand-edited file may omit any). */
+export interface AnonPiConfig {
+    /** socks5h proxy URL. */
+    proxy?: string;
+    /** The local-model direct target (host[:port]). */
+    llm?: string;
+    /** The machine bare `anon-pi` launches by default. */
+    defaultMachine?: string;
+    /** Override the projects root (host dir mounted at /projects). */
+    projects?: string;
+}
+/** Parsed shape of a per-machine machine.json. All fields optional. */
+export interface MachineConfig {
+    /** The container image with `pi` on PATH for this machine. */
+    image?: string;
+    /** Per-machine projects-root override (above config, below env/--mount). */
+    projects?: string;
+}
+/**
+ * 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 declare function parseConfigJson(raw: unknown): AnonPiConfig;
+/**
+ * PURE: parse an already-JSON-decoded machine.json value into a MachineConfig.
+ * Tolerates undefined/null/partial input (an absent machine.json is `{}`).
+ */
+export declare function parseMachineJson(raw: unknown): MachineConfig;
+/**
+ * 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 declare function resolveProjectsRoot(args: {
+    env: AnonPiEnv;
+    config?: AnonPiConfig;
+    machine?: MachineConfig;
+    /** The later --mount CLI override (a HOST parent path); top of the chain. */
+    mountParent?: string;
+}): string;
+/**
+ * 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 declare function resolveProxy(args: {
+    config?: AnonPiConfig;
+    env: {
+        proxy?: string;
+    };
+}): string;
+/**
+ * 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 declare function resolveLlm(args: {
+    config?: AnonPiConfig;
+    env: {
+        llmDirect?: 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). */
+    name: string;
+    /** The persistent HOST home dir (machineHomeDir), bind-mounted at /root. */
+    home: string;
+    /** The container image with `pi` on PATH for this machine. */
+    image: string;
+}
+/**
+ * What a launch runs. `menu` is the BARE launch: no target is chosen yet, so no
+ * netcage argv is composed (the host-side TUI picks a project/shell, THEN a
+ * fresh intent is resolved into a launch plan). `pi` runs pi (optionally with
+ * forwarded args); `shell` runs bash (the project-hopper, since pi cannot cd).
+ */
+export type LaunchMode = 'menu' | 'pi' | 'shell';
+/**
+ * A parsed launch intent, injected so the resolver stays pure. The proxy + the
+ * direct-hole llm are threaded in RESOLVED (via resolveProxy/resolveLlm); the
+ * resolver re-asserts them non-empty so a plan can NEVER be produced without the
+ * forced-egress flags (fail-closed is the anonymity invariant).
+ */
+export interface LaunchIntent {
+    /** The machine to launch on (home + image). */
+    machine: Machine;
+    /** menu (bare) | pi | shell. */
+    mode: LaunchMode;
+    /**
+     * The resolved HOST projects root, bind-mounted at /projects. One of the two
+     * invariant mounts, present on every launch regardless of --mount.
+     */
+    projectsRoot: string;
+    /**
+     * The project token: a validated project name, the root token `.`, or
+     * undefined (shell-at-home / menu). Resolves the cwd via resolveCwd.
+     */
+    project?: string;
+    /**
+     * `--mount <parent>`: a resolved HOST parent path. When set it adds EXACTLY
+     * one mount (<parent>:/work) and re-roots the cwd there (/work[/<project>]);
+     * it changes nothing else (the two invariant mounts stay). Sidesteps podman
+     * mount immutability (we never remount a running box).
+     */
+    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). */
+    llmDirect: string;
+    /**
+     * The host models.json to mount read-only for the first-launch seed, keyed to
+     * THIS machine (e.g. <machine-dir>/models.json). Omitted => no seed mount (pi
+     * starts with no models; you add them in-session).
+     */
+    modelsSeed?: string;
+    /**
+     * The settings SEED to mount read-only for the first-launch seed (the
+     * local-model default selection, e.g. <machine-dir>/settings-seed.json).
+     * Omitted => no settings seed (no default model is pre-selected).
+     */
+    settingsSeed?: string;
+    /** The seed version stamped into a fresh home's marker. Default SEED_VERSION. */
+    seedVersion?: string;
+}
+/**
+ * The resolved launch plan. A discriminated union so the BARE `menu` mode is a
+ * distinct, argv-less marker (the host-side TUI runs first) while every real
+ * launch carries a composed netcage argv. The forced-egress invariant is
+ * asserted on the `launch` variant's netcageArgs by construction.
+ */
+export type LaunchPlan = {
+    /** Bare launch: run the host-side menu, then re-resolve into a launch. */
+    kind: 'menu';
+    machine: Machine;
+} | {
+    kind: 'launch';
+    machine: Machine;
+    /** The jail cwd (`-w`): /projects[/<p>], /work[/<p>] (--mount), or /root (shell ~). */
+    cwd: string;
+    /** True when the machine home is fresh (informational; the seed is marker-guarded). */
     fresh: boolean;
     /** The argv passed to `netcage` (after the `netcage` program name). */
     netcageArgs: string[];
+};
+/** The machine bare `anon-pi` launches when no `-m` and no config default. */
+export declare const DEFAULT_MACHINE = "default";
+/**
+ * A parsed grammar-A launch. `mode` is `menu` when no project/shell target was
+ * chosen (bare `anon-pi`, or `-m <machine>` / `--mount <parent>` with no
+ * 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 / shell-at-home). `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).
+ */
+export interface ParsedLaunch {
+    mode: LaunchMode;
+    machine: string;
+    /**
+     * True iff `-m`/`--machine` was given explicitly (so the CLI can let an
+     * explicit `-m default` win over `config.defaultMachine`, rather than treat
+     * the DEFAULT_MACHINE value as "unset").
+     */
+    machineExplicit: boolean;
+    project?: string;
+    mountParent?: string;
+    keep: boolean;
+    piArgs?: string[];
 }
-/** A user-facing error whose message is meant to be printed verbatim (no stack). */
-export declare class AnonPiError extends Error {
+/**
+ * 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 declare function parseLaunchArgs(args: readonly string[]): ParsedLaunch;
+/**
+ * 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 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;
 }
-/** Resolve the anon-pi home dir (holds the seed). */
-export declare function resolveAnonPiHome(env: AnonPiEnv): string;
 /**
- * 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).
+ * 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 declare function resolveConfigSeed(env: AnonPiEnv): string;
+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>`, `.` -> 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 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).
+ *
+ *   - `--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 declare function resolveRunVsStart(intent: LaunchIntent, kept: readonly KeptContainer[]): RunVsStart;
+/**
+ * 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 declare function projectSessionSlug(name: string): string;
+/**
+ * The pure choice-list the bare-launch menu renders. `projects` are the
+ * folder-safe project names (sorted, case-insensitive) offered as pi launches;
+ * `here` is the `.` root token (a scratch pi at the root itself); `canNew` /
+ * `canShell` gate the `+ new project…` and `shell` affordances. It carries NO
+ * usage annotation (that is deriveProjectUsage, keyed by project name), so a
+ * caller can render the list alone or joined with usage.
+ */
+export interface MenuChoiceList {
+    /** The folder-safe project names, sorted case-insensitively for a stable menu. */
+    projects: string[];
+    /** The `.` "here" entry: a scratch pi at the root itself (ROOT_TOKEN). */
+    here: string;
+    /** Whether the `+ new project…` affordance is offered (always true today). */
+    canNew: boolean;
+    /** Whether the `shell` affordance is offered (always true today). */
+    canShell: boolean;
+}
+/**
+ * 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 declare function buildMenuChoiceList(args: {
+    projects: readonly string[];
+    canNew?: boolean;
+    canShell?: boolean;
+}): MenuChoiceList;
+/**
+ * A per-machine session-dir listing: for each machine name, the slugs present
+ * under machines/<M>/home/.pi/agent/sessions/. The CLI derives this by reading
+ * each machine home's sessions dir; the pure derivation takes it as input. Only
+ * the project session slugs (projectSessionSlug) are matched; any other slug
+ * (e.g. a `.`/`~`/`--mount` scratch session) is simply not a project so it does
+ * not appear in the usage record.
+ */
+export type SessionDirListing = Record<string, readonly string[]>;
+/** The usage record for ONE project: which machines used it + a current-new flag. */
+export interface ProjectUsage {
+    /** The project name (as supplied; validated). */
+    project: string;
+    /**
+     * The machine names whose home contains this project's session dir, sorted
+     * (a stable, machine-invariant "used on" list derived from session presence).
+     */
+    machines: string[];
+    /**
+     * True when the CURRENT machine has NO session dir for this project yet (it is
+     * new for this machine, even if other machines have used the shared files).
+     */
+    currentMachineIsNew: boolean;
+}
+/**
+ * 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 declare function deriveProjectUsage(args: {
+    projects: readonly string[];
+    currentMachine: string;
+    sessions: SessionDirListing;
+}): ProjectUsage[];
+/**
+ * What ONE selectable menu row launches, so the CLI can dispatch a chosen entry
+ * without re-deriving anything:
+ *   - `project` -> pi in `/projects/<project>` (the `anon-pi <project>` launch);
+ *   - `here`    -> a scratch pi at the root itself (the `.` root token launch);
+ *   - `new`     -> prompt+validate a new project name, then launch it as pi;
+ *   - `shell`   -> the `--shell` jailed-bash launch.
+ */
+export type MenuEntryKind = 'project' | 'here' | 'new' | 'shell';
+/** One rendered, selectable menu row: what it launches + its human label. */
+export interface MenuEntry {
+    /** Which launch this row dispatches to (project | here | new | shell). */
+    kind: MenuEntryKind;
+    /**
+     * The project token this row launches: a validated project name (`project`),
+     * the root token `.` (`here`), or undefined (`new` prompts for it, `shell`
+     * takes none). This is exactly the `project` field a launch dispatch feeds
+     * back into the grammar, so no re-parsing is needed.
+     */
+    project?: string;
+    /**
+     * The rendered row text the selector prints: the project name plus its
+     * used-on / new-here annotation (project rows), or the fixed affordance label
+     * (here / new / shell). The annotation is the ONLY place the usage record
+     * surfaces to the user, so the wording lives here (pure) not in the TUI.
+     */
+    label: string;
+}
+/** The fixed labels for the non-project affordances (one source, so the TUI + its test agree). */
+export declare const MENU_HERE_LABEL = ". (here: a scratch pi at the root)";
+export declare const MENU_NEW_LABEL = "+ new project\u2026";
+export declare 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 declare function formatProjectAnnotation(usage: ProjectUsage): string;
+/**
+ * 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 declare function buildMenuEntries(args: {
+    choiceList: MenuChoiceList;
+    usage: readonly ProjectUsage[];
+}): MenuEntry[];
 /**
  * Encode an absolute path into a directory name using pi's OWN convention (see
  * pi coding-agent session-manager: `--${cwd without leading slash, / \ : -> -}--`),
@@ -110,18 +708,160 @@ export declare function resolveConfigSeed(env: AnonPiEnv): string;
  * hash). e.g. /home/u/dev/x -> --home-u-dev-x--
  */
 export declare function pathSlug(absPath: string): string;
-/**
- * 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 declare function stateAgentDir(env: AnonPiEnv, absWorkdir: string): string;
 /**
  * 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`.
  * Returns `host` (no port) or `host:port`, lowercased, scheme/path stripped.
  */
 export declare function hostPortKey(value: string): string;
+/**
+ * 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 declare 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 declare 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 declare 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 declare const BENIGN_API_KEYS: ReadonlySet<string>;
+/** PURE: whether an apiKey looks like a REAL secret (i.e. not in the benign set). */
+export declare function apiKeyLooksReal(apiKey: string | undefined): boolean;
+/**
+ * A pi model entry as anon-pi seeds it for the local provider. pi keys a model
+ * by `id`; `name` is the display label and `cost` is all-zero (a LAN model is
+ * free). A "server"-sourced entry is minimal (id/name/cost); a "configured"
+ * entry (imported from the host models.json) preserves whatever extra fields it
+ * carried (`contextWindow`, `maxTokens`, `reasoning`, `input`, ...) via the
+ * index signature.
+ */
+export interface GeneratedModel {
+    id: string;
+    name: string;
+    cost?: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    [k: string]: unknown;
+}
+/**
+ * PURE: a candidate model for the `init` picker. `configured` means it came from
+ * the host `~/.pi/agent/models.json` provider that matches the endpoint (a
+ * well-tuned entry with its real config); otherwise it was only reported by the
+ * endpoint's `/v1/models` (a bare id we synthesize a minimal entry for). The
+ * picker marks configured ones so the user knows which are more likely correct.
+ */
+export interface ModelCandidate {
+    id: string;
+    configured: boolean;
+    /** The full pi model entry to seed (rich for configured, minimal otherwise). */
+    entry: GeneratedModel;
+}
+/**
+ * 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 declare function localModelEntry(id: string): GeneratedModel;
+/**
+ * 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 declare function parseModelsListing(raw: unknown): string[];
+/** The result of scanning a host models.json for the endpoint's provider. */
+export interface HostProviderMatch {
+    /** The matching provider's models as full pi entries (verbatim host config). */
+    models: GeneratedModel[];
+    /** The matching provider's apiKey (verbatim), for the benign/real check. */
+    apiKey?: string;
+    /** True iff that apiKey looks like a REAL secret (init refuses without --force). */
+    apiKeyLooksReal: boolean;
+}
+/**
+ * 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 declare function pickLocalProviderModels(hostModels: PiModelsFile, llmEndpoint: string): HostProviderMatch | 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 declare function mergeModelSources(hostModels: readonly GeneratedModel[], serverIds: readonly string[]): ModelCandidate[];
+/**
+ * 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 declare function generateModelsJson(llmEndpoint: string, models?: readonly (GeneratedModel | string)[], apiKey?: string): PiModelsFile;
+/** The pi settings.json keys anon-pi sets for the local-model default selection. */
+export interface ModelSelection {
+    defaultProvider: string;
+    defaultModel: string;
+    enabledModels: string[];
+}
+/**
+ * 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 declare function generateModelSelection(modelIds: readonly string[], defaultId: string): ModelSelection;
+/**
+ * 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 declare function mergeModelSelection(existing: unknown, selection: ModelSelection): Record<string, unknown>;
+/**
+ * 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 declare function resolveHostModelsPath(env: AnonPiEnv): string;
 /**
  * A pi provider entry (as it appears under models.json `providers[name]`). Only
  * the fields anon-pi reads are typed; the rest is preserved verbatim.
@@ -138,51 +878,170 @@ export interface PiModelsFile {
     providers?: Record<string, PiProvider>;
     [k: string]: unknown;
 }
-/** The result of picking the ANON_PI_LLM provider out of a host models.json. */
-export interface ImportResult {
-    /** The provider key (e.g. "llamacpp-router"). */
-    name: string;
-    /** The barebones models.json to write (just the matched provider). */
-    models: PiModelsFile;
-    /** True if the matched provider's apiKey looks like a REAL secret (warn). */
-    apiKeyLooksReal: boolean;
-}
 /**
- * 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 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 declare function pickProviderForLlm(hostModels: PiModelsFile, llmDirect: string): ImportResult;
+export declare const DEFAULT_SOCKS_PROBE_PORTS: readonly {
+    port: number;
+    hint: string;
+}[];
 /**
- * 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).
+ * 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 declare function resolveSourceModelsPath(env: AnonPiEnv): string;
+export declare const SOCKS5_METHOD_SELECTOR: readonly number[];
+/** How a SOCKS5 handshake probe against a port came out (the pure verdict). */
+export type SocksHandshake = {
+    /** The server replied with a well-formed SOCKS5 method-selection reply. */
+    socks5: true;
+    /** The selected method byte the server chose (informational). */
+    method: number;
+} | {
+    /** The reply was absent, too short, or not a SOCKS5 version-5 reply. */
+    socks5: false;
+    /** A terse, provider-agnostic reason (for the findings line). */
+    reason: string;
+};
 /**
- * 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).
+ * 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 declare function interpretSocks5Handshake(reply: readonly number[] | Uint8Array | Buffer): SocksHandshake;
+/**
+ * A weak process hint: a LOCAL tool whose presence SUGGESTS what a port is
+ * (e.g. a `tor` process -> likely Tor). It is a hint about the LOCAL software
+ * only, never a claim about the EXIT provider. cli.ts supplies the observed
+ * process name (e.g. from `ps`/`/proc`); the pure mapping stays testable.
+ */
+export interface ProcessHint {
+    /** The observed local process name (as cli.ts read it). */
+    process: string;
+    /** The weak, hedged hint text ("a `tor` process is running -> likely Tor"). */
+    hint: string;
+}
+/**
+ * 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 declare function processHint(processName: string): ProcessHint | undefined;
+/**
+ * One probed SOCKS candidate, as `init` gathers it for the findings display. All
+ * fields are EVIDENCE the probe actually observed; there is DELIBERATELY no
+ * "provider" field, so the type itself cannot carry a provider label.
+ */
+export interface ProxyFinding {
+    /** The host that was probed (usually 127.0.0.1). */
+    host: string;
+    /** The port that was probed. */
+    port: number;
+    /** Whether the TCP port was open (a connection succeeded). */
+    open: boolean;
+    /** The SOCKS5 handshake verdict (only meaningful when `open`). */
+    handshake?: SocksHandshake;
+    /** The port's structural hint (DEFAULT_SOCKS_PROBE_PORTS), if any. */
+    portHint?: string;
+    /** Any weak LOCAL process hint (processHint), if one was observed. */
+    processHint?: string;
+}
+/**
+ * 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 declare const FORBIDDEN_PROVIDER_LABELS: readonly string[];
+/**
+ * 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.)
+ * Findings in -> display string out; the socket probes are cli.ts's job.
+ */
+export declare function formatProxyFindings(findings: readonly ProxyFinding[], processNote?: string): string;
+/**
+ * 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 declare function socks5hUrl(hostPort: string): string;
+/**
+ * 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 declare function parseVerifyExitIp(output: string): string | undefined;
+/**
+ * The image-menu choices `init` offers for the default machine's image. `[1]`
+ * and `[2]` build a SHIPPED Dockerfile via `podman build`; `[3]` takes an
+ * existing image ref verbatim; `[4]` skips (the machine is created imageless and
+ * pinned later). The pure list keeps the menu wording testable; cli.ts renders
+ * it, runs `podman build`, and writes the machine.
+ */
+export type InitImageChoice = 'basic' | 'webveil' | 'existing' | 'skip';
+/** One rendered image-menu entry: its choice tag + the human label. */
+export interface InitImageMenuEntry {
+    choice: InitImageChoice;
+    label: string;
+}
+/**
+ * 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 declare function initImageMenu(): InitImageMenuEntry[];
+/**
+ * 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 declare function buildRunPlan(env: AnonPiEnv, workdirArg: string | undefined, modelsSeedExists: (modelsJsonPath: string) => boolean, stateExists: (stateDir: string) => boolean): RunPlan;
+export declare function serializeConfigJson(config: AnonPiConfig): string;
 /**
  * Absolute path to the Dockerfile.pi that ships with anon-pi, resolved from this
  * module's location (package root, one level up from dist/anon-pi.js), or
@@ -195,8 +1054,62 @@ export declare function shippedDockerfilePath(): string | undefined;
  * anon-pi (examples/Dockerfile.pi-webveil), or undefined if not found.
  */
 export declare function shippedWebveilDockerfilePath(): string | undefined;
+/**
+ * A parsed `machine <verb> …` command. A discriminated union so the CLI
+ * dispatches on `verb` with the already-validated fields:
+ *   - `create <name> [--image <ref>]`: name validated; image optional here (the
+ *     CLI prompts for it when absent, on a TTY).
+ *   - `list`: no args.
+ *   - `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).
+ */
+export type MachineCommand = {
+    verb: 'create';
+    name: string;
+    image?: string;
+} | {
+    verb: 'list';
+} | {
+    verb: 'set-image';
+    name: string;
+    image: string;
+} | {
+    verb: 'rm';
+    name: string;
+    yes: boolean;
+};
+/**
+ * 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 declare function parseMachineArgs(args: readonly string[]): MachineCommand;
+/**
+ * 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 declare function serializeMachineJson(config: MachineConfig): string;
+/**
+ * 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 declare function setImageWarning(name: string, oldImage: string | undefined, newImage: string): string;
 /** 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 - launch pi inside a netcage (anonymized egress + one direct local model)\n\nUSAGE\n  anon-pi [WORKDIR]     launch pi jailed, working in WORKDIR (default: cwd)\n  anon-pi import        seed models.json from your local model\n\n  WORKDIR   the host folder pi works in (mounted at /work; pi's cwd). Files pi\n            writes there land on the host.\n\nWHAT IT DOES\n  Runs pi inside netcage with all web/DNS egress forced through the socks5h\n  proxy (fail-closed) and ONE direct hole to your local model (ANON_PI_LLM).\n\n  STATEFUL by default: a persistent per-workdir home\n  (<ANON_PI_HOME>/state/<workdir>/agent) is mounted at the container's\n  ~/.pi/agent, so your conversations, history, settings (model choice), and any\n  extensions you `pi install` persist across launches. Re-running in the same\n  folder resumes it. On a FRESH home, the image's staged defaults (extensions,\n  trust) and your imported models.json are seeded in once; after that pi owns the\n  home and nothing is overwritten. Requires `netcage`.\n\n  --ephemeral (or ANON_PI_EPHEMERAL=1): mount NO writable state; pi writes to the\n  container's own --rm layer, gone on exit. Nothing writable touches the host,\n  no cleanup, no leftover-on-crash.\n\n  --fresh: delete this workdir's persistent state home first, so the (possibly\n  rebuilt) image's defaults + your imported models.json are re-seeded. Use it\n  after rebuilding your image to pick up new extensions/config.\n\nimport\n  Reads your host ~/.pi/agent/models.json, picks the provider whose baseUrl\n  serves ANON_PI_LLM, and writes JUST that provider to the canonical seed\n  (<ANON_PI_CONFIG>/models.json). No other provider's API keys, no sessions, no\n  identity. It SEEDS a fresh home; models you later add inside pi persist and are\n  never clobbered. Re-run with --force to overwrite the canonical seed.\n\nENVIRONMENT\n  ANON_PI_IMAGE   (required for run) image with `pi` on PATH. No image yet?\n                  Running anon-pi without it prints a ready-to-build\n                  Dockerfile.pi recipe; see the README (Providing a pi image).\n  ANON_PI_LLM     (required) RFC1918/link-local IP[:port] of the local model\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_EPHEMERAL  set to 1 for a throwaway (non-persistent) session\n  ANON_PI_HOME    anon-pi home (default $XDG_CONFIG_HOME/anon-pi or ~/.config/anon-pi)\n  ANON_PI_CONFIG  canonical seed dir holding models.json (default <ANON_PI_HOME>/agent)\n  ANON_PI_SOURCE_MODELS  (import) host models.json to read (default ~/.pi/agent/models.json)\n\nRESET A SESSION\n  anon-pi --fresh [WORKDIR]   drop the session home and re-seed on this launch.\n  Or delete it by hand: rm -rf <ANON_PI_HOME>/state/<workdir-slug>/agent\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 (headless/one-shot; no TTY needed)\n  anon-pi --shell [<project>]    a jailed bash (at ~, or cd'd into <project>) - the project-hopper\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)\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";
 //# sourceMappingURL=anon-pi.d.ts.map