anon-pi 0.4.0 → 0.6.0

package/dist/cli.js

@@ -1,77 +1,185 @@
 #!/usr/bin/env node
-// anon-pi CLI. Two commands:
-//   anon-pi [WORKDIR]   resolve the run plan (pure) and exec `netcage run ...`
-//                       with inherited stdio (so -it is a real interactive TTY).
-//                       The seed models.json is mounted read-only and copied
-//                       into the container's ~/.pi/agent by the run command, so
-//                       it layers onto the image's config (extensions survive).
-//   anon-pi import      generate the seed models.json from the host models.json,
-//                       carrying only the provider that serves ANON_PI_LLM.
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
-import { spawnSync } from 'node:child_process';
-import { isAbsolute, join, resolve } from 'node:path';
-import { AnonPiError, buildRunPlan, envFromProcess, HELP, MODELS_FILE, pickProviderForLlm, resolveConfigSeed, resolveSourceModelsPath, stateAgentDir, } from './anon-pi.js';
+// anon-pi CLI: the THIN impure launch path. Parses grammar A (pure
+// parseLaunchArgs), reads config.json / machine.json + resolves the machine,
+// composes the LaunchIntent, resolves the RunPlan (pure resolveRunPlan), decides
+// run-vs-start against real netcage for `--keep`, and spawns netcage with
+// inherited stdio (so -it is a real interactive TTY), propagating the exit code.
+//
+// All the DECISIONS live in the pure module (anon-pi.ts); this file only does
+// I/O: fs reads/mkdirs, the netcage query, the spawn, and the TTY discipline.
+// The forced-egress invariant is the RunPlan's guarantee: the composed argv
+// ALWAYS carries --proxy + the one --allow-direct; the CLI never strips or adds
+// egress.
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { readSync } from 'node:fs';
+import { spawnSync, execFileSync } from 'node:child_process';
+import { join, dirname, resolve } from 'node:path';
+import { AnonPiError, HELP, MODELS_FILE, SETTINGS_SEED_FILE, SEED_MARKER, DEFAULT_MACHINE, envFromProcess, buildMenuChoiceList, buildMenuEntries, builtinProjectsRoot, deriveProjectUsage, machineDir, machineHomeDir, machineJsonPath, machineSessionsDir, validateName, resolveDeleteHome, resolveDeleteProject, parseConfigJson, parseLaunchArgs, parseMachineArgs, parseMachineJson, projectHostDir, resolveAnonPiHome, resolveLlm, resolveProjectsRoot, resolveProxy, resolveRunPlan, resolveRunVsStart, serializeMachineJson, serializeConfigJson, setImageWarning, keptContainerKey, DEFAULT_SOCKS_PROBE_PORTS, SOCKS5_METHOD_SELECTOR, formatProxyFindings, interpretSocks5Handshake, initImageMenu, generateModelsJson, generateModelSelection, pickLocalProviderModels, parseModelsListing, mergeModelSources, resolveHostModelsPath, LOCAL_PROVIDER_API_KEY, parseVerifyExitIp, processHint, socks5hUrl, hostPortKey, shippedDockerfilePath, shippedWebveilDockerfilePath, } from './anon-pi.js';
+// The netcage label anon-pi stamps its launch-identity key onto (keptContainerKey)
+// so a `--keep` re-entry can find and `netcage start` the same kept container.
+// netcage's `netcage.managed` label marks it a managed container; this adds the
+// anon-pi identity ON TOP (netcage's label IS the registry; anon-pi adds no file).
+const ANON_PI_KEY_LABEL = 'anon-pi.key';
 function main(argv) {
     const args = argv.slice(2);
-    if (args.includes('--help') || args.includes('-h')) {
+    // The global `--help`/`-h` prints the top-level HELP, EXCEPT when the first
+    // token is a subcommand that owns its own `--help` (so `anon-pi init --help`
+    // and `anon-pi machine --help` show THEIR help, not the global one). Those
+    // subcommands route to runInit / runMachine, which print INIT_HELP /
+    // MACHINE_HELP respectively.
+    const OWN_HELP_SUBCOMMANDS = new Set(['init', 'machine']);
+    if ((args.includes('--help') || args.includes('-h')) &&
+        !OWN_HELP_SUBCOMMANDS.has(args[0] ?? '')) {
         process.stdout.write(HELP);
         return 0;
     }
-    // Subcommand dispatch: the first bare token may be `import`.
-    if (args[0] === 'import') {
-        return runImport(args.slice(1));
-    }
-    return runLaunch(args);
-}
-// --- anon-pi [WORKDIR] : launch pi jailed -----------------------------------
-function runLaunch(args) {
-    // One optional positional (the workdir) + the --ephemeral / --fresh flags.
-    // Reject other flags so a typo is not silently swallowed: anon-pi owns the
-    // netcage argv.
-    const known = new Set(['--ephemeral', '--eph', '--fresh']);
-    const ephemeralFlag = args.includes('--ephemeral') || args.includes('--eph');
-    const freshFlag = args.includes('--fresh');
-    const positionals = args.filter((a) => !a.startsWith('-'));
-    const flags = args.filter((a) => a.startsWith('-') && !known.has(a));
-    if (flags.length > 0) {
-        process.stderr.write(`anon-pi: unknown option(s): ${flags.join(' ')}\nRun \`anon-pi --help\`.\n`);
-        return 2;
-    }
-    if (positionals.length > 1) {
-        process.stderr.write('anon-pi: too many arguments (expected at most one WORKDIR).\nRun `anon-pi --help`.\n');
-        return 2;
-    }
-    if (freshFlag && ephemeralFlag) {
-        process.stderr.write('anon-pi: --fresh has no effect with --ephemeral (an ephemeral session is always fresh and never persisted).\nRun `anon-pi --help`.\n');
-        return 2;
+    // `machine …` is the machine-management surface (create/list/set-image/rm),
+    // dispatched BEFORE the launch grammar so a bare `machine` is never parsed as
+    // a project named "machine". Everything else is a launch.
+    if (args[0] === 'machine') {
+        return runMachine(args.slice(1));
     }
-    const env = envFromProcess(process.env);
-    if (ephemeralFlag)
-        env.ephemeral = true;
-    // --fresh: delete this workdir's persistent state home BEFORE planning, so the
-    // home is fresh and the image's (possibly rebuilt) defaults + models.json are
-    // re-seeded on this launch. No-op for --ephemeral (handled above).
-    if (freshFlag && !env.ephemeral) {
-        const raw = positionals[0] && positionals[0].trim() !== ''
-            ? positionals[0]
-            : process.cwd();
-        const wd = isAbsolute(raw) ? raw : resolve(raw);
-        const stateDir = stateAgentDir(env, wd);
-        if (existsSync(stateDir)) {
-            rmSync(stateDir, { recursive: true, force: true });
-            process.stderr.write(`anon-pi: --fresh removed ${stateDir}\n`);
-        }
+    // The destructive cleanup verbs (replacing the old `--fresh`). Dispatched
+    // BEFORE the launch grammar: they are top-level data verbs, not launch flags,
+    // each with the confirm/`--yes`/non-TTY discipline. `--delete-home` takes an
+    // OPTIONAL machine (default machine when omitted); `--delete-project` REQUIRES
+    // a project.
+    if (args[0] === '--delete-home') {
+        return runDeleteHome(args.slice(1));
     }
-    let plan;
+    if (args[0] === '--delete-project') {
+        return runDeleteProject(args.slice(1));
+    }
+    // `init` onboards: verify the proxy, capture the llm endpoint, pick/build the
+    // default machine image, write config.json + the default machine. Re-runnable.
+    if (args[0] === 'init') {
+        return runInit(args.slice(1));
+    }
+    let parsed;
     try {
-        plan = buildRunPlan(env, positionals[0], existsSync, existsSync);
+        parsed = parseLaunchArgs(args);
     }
     catch (e) {
-        if (e instanceof AnonPiError) {
-            process.stderr.write(e.message + '\n');
-            return 1;
+        return reportAnonPiError(e);
+    }
+    // FIRST RUN: no config.json yet. Rather than fail deep in the launch with the
+    // bare "set ANON_PI_PROXY" wall (which reads like a doc dump the first time),
+    // welcome the user and run `init` automatically, then continue into the
+    // launch they asked for. Needs a TTY (init is interactive); without one we
+    // fall through to the launch path, whose fail-closed proxy error is the right
+    // signal for a script. An explicit ANON_PI_PROXY/ANON_PI_LLM env pair also
+    // skips this (the user is driving config via env, not the file).
+    if (isFirstRun()) {
+        const code = runFirstRunInit();
+        if (code !== 0)
+            return code; // init aborted / failed: do not launch.
+    }
+    return runLaunch(parsed);
+}
+/**
+ * First run = no config.json in the anon-pi home AND the user has not supplied
+ * the forced-egress inputs via env (ANON_PI_PROXY is what the launch fails
+ * closed on; if it is set the user is configuring via env and we do not
+ * onboard). We only auto-onboard on an interactive terminal.
+ */
+function isFirstRun() {
+    const env = envFromProcess(process.env);
+    if (nonEmptyEnv(env.proxy))
+        return false; // env-driven config; no onboarding.
+    if (!process.stdin.isTTY)
+        return false; // scripts get the fail-closed error.
+    const configPath = join(resolveAnonPiHome(env), 'config.json');
+    return !existsSync(configPath);
+}
+/** Show a first-time welcome, then run `init`. Returns init's exit code. */
+function runFirstRunInit() {
+    process.stdout.write('\n' +
+        "Welcome to anon-pi. It looks like this is your first run (there's no\n" +
+        'config yet), so let us set things up before launching.\n' +
+        '\n' +
+        'anon-pi runs pi on anonymized, jailed MACHINES: all of pi\u2019s web/DNS egress\n' +
+        'is forced through your socks5h proxy (fail-closed), with ONE direct hole to\n' +
+        'a local model. Your machines + conversations live in ~/.anon-pi/.\n' +
+        '\n' +
+        'Running `anon-pi init` now (re-runnable any time; nothing is destroyed).\n' +
+        '\n');
+    return runInit([]);
+}
+/** Whether an env value is present + non-blank. */
+function nonEmptyEnv(v) {
+    return typeof v === 'string' && v.trim() !== '';
+}
+// --- the launch path --------------------------------------------------------
+function runLaunch(parsed) {
+    const env = envFromProcess(process.env);
+    // config.json (the workspace default proxy/llm/defaultMachine/projects).
+    const config = readJsonConfig(env);
+    // Resolve the machine: an explicit -m wins, else config.defaultMachine, else
+    // the built-in DEFAULT_MACHINE (so an explicit `-m default` is honoured too).
+    const machineName = parsed.machineExplicit
+        ? parsed.machine
+        : (config.defaultMachine ?? DEFAULT_MACHINE);
+    const machineConf = readMachineJson(env, machineName);
+    // Forced-egress inputs, resolved (env over config); the proxy is REQUIRED and
+    // fails closed with the verbatim guidance.
+    let proxy;
+    let llm;
+    let intent;
+    try {
+        proxy = resolveProxy({ env, config });
+        llm = resolveLlm({ env, config });
+        if (llm === undefined) {
+            throw new AnonPiError('anon-pi: set ANON_PI_LLM (or config.llm) to the RFC1918/link-local IP[:port]\n' +
+                'of your local model. It is the ONE direct hole; all other egress stays\n' +
+                'forced through the proxy.');
         }
-        throw e;
+        // The machine's image: machine.json wins, ANON_PI_IMAGE is the fallback.
+        const image = machineConf.image ?? env.image ?? '';
+        // --mount re-roots at a HOST parent; otherwise the resolved projects root.
+        const mountParent = parsed.mountParent;
+        const projectsRoot = resolveProjectsRoot({
+            env,
+            config,
+            machine: machineConf,
+            mountParent,
+        });
+        const home = machineHomeDir(env, machineName);
+        const machine = { name: machineName, home, image };
+        // The generated models.json + settings seed for this machine (mounted
+        // read-only for the first-launch seed) when present. Keyed per machine.
+        const modelsSeed = join(machineDir(env, machineName), MODELS_FILE);
+        const settingsSeed = join(machineDir(env, machineName), SETTINGS_SEED_FILE);
+        intent = {
+            machine,
+            mode: parsed.mode,
+            projectsRoot,
+            project: parsed.project,
+            mountParent,
+            piArgs: parsed.piArgs,
+            keep: parsed.keep,
+            proxy,
+            llmDirect: llm,
+            modelsSeed: existsSync(modelsSeed) ? modelsSeed : undefined,
+            settingsSeed: existsSync(settingsSeed) ? settingsSeed : undefined,
+        };
+    }
+    catch (e) {
+        return reportAnonPiError(e);
+    }
+    // No-TTY discipline: the bare MENU and every INTERACTIVE launch (interactive
+    // pi, or a shell) need a TTY; a HEADLESS pi run (`<project> <pi-args…>`) does
+    // NOT. Check BEFORE we mutate anything or spawn.
+    const headless = parsed.mode === 'pi' && !!parsed.piArgs && parsed.piArgs.length > 0;
+    if (!headless && !process.stdin.isTTY) {
+        if (parsed.mode === 'menu') {
+            process.stderr.write('anon-pi: no TTY. The menu needs an interactive terminal. Pick a project\n' +
+                'directly, e.g. `anon-pi <project>`, or run anon-pi in a terminal.\n');
+        }
+        else {
+            process.stderr.write(`anon-pi: no TTY. An interactive ${parsed.mode === 'shell' ? 'shell' : 'pi session'} needs a terminal.\n` +
+                'Forward a one-shot pi prompt instead, e.g. `anon-pi <project> -p "..."`.\n');
+        }
+        return 1;
     }
     // Fail loud if netcage is not installed, before we mutate anything.
     if (!hasNetcage()) {
@@ -79,83 +187,1367 @@ function runLaunch(args) {
             '(https://github.com/wighawag/netcage). Linux only.\n');
         return 1;
     }
-    mkdirSync(plan.workdir, { recursive: true });
-    if (env.ephemeral) {
-        // No host state dir: pi writes to the container's own --rm layer, so the
-        // session leaves NO trace on the host and there is nothing to clean up.
-        process.stderr.write('anon-pi: ephemeral session (nothing persisted; no host state)\n');
+    // Resolve the RunPlan (pure). homeFresh reads the real seed marker.
+    let plan;
+    try {
+        plan = resolveRunPlan(intent, homeFresh);
+    }
+    catch (e) {
+        return reportAnonPiError(e);
+    }
+    // Bare launch: hand off to the interactive host-side menu, which re-resolves
+    // the user's pick into a concrete launch and executes it.
+    if (plan.kind === 'menu') {
+        return runMenu(intent, plan.machine);
+    }
+    return executeLaunchPlan(intent, plan);
+}
+/**
+ * Execute a RESOLVED non-menu LaunchPlan: create the host dirs the mounts need,
+ * then run netcage (or `netcage start` a matching kept container under --keep).
+ * Shared by the direct launch path (runLaunch) and the menu dispatch (runMenu),
+ * so a menu-picked project/here/shell launches BYTE-FOR-BYTE identically to the
+ * same command typed directly.
+ */
+function executeLaunchPlan(intent, plan) {
+    // Create the host dirs the mounts need BEFORE spawn: the machine home and,
+    // for a named project (not the root token `.` / a bare shell), its folder
+    // under the active root (the --mount parent or the projects root).
+    mkdirSync(plan.machine.home, { recursive: true });
+    if (intent.project !== undefined &&
+        intent.project !== '.' &&
+        intent.mode !== 'shell') {
+        const root = intent.mountParent ?? intent.projectsRoot;
+        mkdirSync(projectHostDir(root, intent.project), { recursive: true });
     }
     else {
-        // Persistent mode: create the per-workdir state home to mount.
-        mkdirSync(plan.stateDir, { recursive: true });
-        if (plan.fresh) {
-            process.stderr.write(`anon-pi: new session home ${plan.stateDir} (seeding on first launch)\n`);
+        // still ensure the active root exists (so a shell/`.`/menu-picked launch
+        // has a real dir to cwd into).
+        mkdirSync(intent.mountParent ?? intent.projectsRoot, { recursive: true });
+    }
+    // Run-vs-start: under --keep, ask netcage for its kept managed containers and
+    // resume a matching one via `netcage start`; else run the composed argv. A
+    // throwaway (`--rm`) launch is always a fresh run (the pure rule never
+    // consults the listing for it).
+    if (intent.keep) {
+        const decision = resolveRunVsStart(intent, queryKeptContainers());
+        if (decision.action === 'start') {
+            return spawnNetcage(['start', '-a', '-i', decision.ref]);
         }
+        // A fresh `--keep` run: stamp the identity key so a later re-entry can
+        // find this container. The RunPlan already omits --rm under --keep.
+        return spawnNetcage(withKeyLabel(plan.netcageArgs, keptContainerKey(intent)));
     }
-    // Hand off to netcage with inherited stdio so -it is a real interactive TTY.
-    const res = spawnSync('netcage', plan.netcageArgs, { stdio: 'inherit' });
-    if (res.error) {
-        process.stderr.write(`anon-pi: failed to run netcage: ${res.error.message}\n`);
+    return spawnNetcage(plan.netcageArgs);
+}
+// --- the interactive host-side menu (the ONLY untested I/O) -------------------
+//
+// Bare `anon-pi` (and bare `-m <machine>` / `--mount <parent>` with no project)
+// dispatches here. The menu is a PURE host-side read: it lists the active root's
+// projects (readdir) + each machine's pi session dirs (readdir) and feeds them
+// to the pure buildMenuChoiceList / deriveProjectUsage / buildMenuEntries, which
+// own ALL the logic (the entry order + the used-on / new-here annotation). This
+// function does ONLY the I/O the pure seam cannot: the real dir reads, the raw-
+// mode arrow-key render/select (select()), the new-project name prompt, and the
+// dispatch of the pick back through resolveRunPlan + executeLaunchPlan (so a
+// menu pick launches identically to the same command typed directly). No jail
+// runs until the user chooses; the no-TTY case is handled BEFORE we reach here
+// (runLaunch's discipline), so a TTY is guaranteed.
+function runMenu(intent, machine) {
+    const env = envFromProcess(process.env);
+    // The active root the menu lists projects from: a --mount parent re-roots, else
+    // the resolved projects root. (Named projects live under it; `.` is the root.)
+    const root = intent.mountParent ?? intent.projectsRoot;
+    const rawProjects = readDirNames(root);
+    const choiceList = buildMenuChoiceList({ projects: rawProjects });
+    // Per-machine usage: the session-slug set present in each machine home's pi
+    // sessions dir, machine-invariant, so a shared project is credited on each.
+    const sessions = {};
+    for (const name of listMachineNames(env)) {
+        sessions[name] = readDirNames(machineSessionsDir(env, name));
+    }
+    // The current machine may be brand-new (no sessions dir yet); an absent entry
+    // reads as "new for it" in deriveProjectUsage.
+    if (sessions[machine.name] === undefined)
+        sessions[machine.name] = [];
+    const usage = deriveProjectUsage({
+        projects: choiceList.projects,
+        currentMachine: machine.name,
+        sessions,
+    });
+    const entries = buildMenuEntries({ choiceList, usage });
+    const picked = select(entries, {
+        header: `anon-pi: machine "${machine.name}" (\u2191/\u2193 move, Enter select, Ctrl-C quit)`,
+    });
+    if (picked === undefined) {
+        // Ctrl-C / EOF: a clean quit, nothing launched (the terminal is restored).
+        process.stderr.write('anon-pi: cancelled; nothing launched.\n');
+        return 130; // 128 + SIGINT, the conventional Ctrl-C exit code.
+    }
+    // Turn the pick into a concrete launch intent, then re-resolve + execute it
+    // EXACTLY as the equivalent direct command would (same resolveRunPlan path).
+    let launchIntent;
+    switch (picked.kind) {
+        case 'project':
+        case 'here':
+            launchIntent = { ...intent, mode: 'pi', project: picked.project };
+            break;
+        case 'shell':
+            launchIntent = { ...intent, mode: 'shell', project: undefined };
+            break;
+        case 'new': {
+            const name = promptNewProject();
+            if (name === undefined)
+                return 1;
+            launchIntent = { ...intent, mode: 'pi', project: name };
+            break;
+        }
+    }
+    let plan;
+    try {
+        plan = resolveRunPlan(launchIntent, homeFresh);
+    }
+    catch (e) {
+        return reportAnonPiError(e);
+    }
+    // A menu pick is always a concrete launch (never the menu marker again).
+    if (plan.kind !== 'launch') {
+        process.stderr.write('anon-pi: internal error resolving the menu pick.\n');
         return 1;
     }
-    // Propagate netcage's exit code (which itself propagates the tool's).
-    return res.status ?? 1;
+    return executeLaunchPlan(launchIntent, plan);
 }
-// --- anon-pi import : write the seed models.json ----------------------------
-function runImport(args) {
-    const force = args.includes('--force') || args.includes('-f');
-    const stray = args.filter((a) => a.startsWith('-') && a !== '--force' && a !== '-f');
-    if (stray.length > 0) {
-        process.stderr.write(`anon-pi import: unknown option(s): ${stray.join(' ')}\nRun \`anon-pi --help\`.\n`);
-        return 2;
+/**
+ * Prompt for a NEW project name and validate it (validateName, the same guard a
+ * direct `anon-pi <name>` uses), so a menu-created project is a safe single
+ * folder segment. Returns the validated name, or undefined on an empty entry /
+ * EOF / a rejected name (with the error printed). TTY is guaranteed here.
+ */
+function promptNewProject() {
+    const ans = promptLine('New project name (a single folder segment): ');
+    if (ans === undefined || ans.trim() === '') {
+        process.stderr.write('anon-pi: no name given; nothing launched.\n');
+        return undefined;
+    }
+    try {
+        return validateName(ans.trim(), 'project');
+    }
+    catch (e) {
+        reportAnonPiError(e);
+        return undefined;
+    }
+}
+/**
+ * Read the entry NAMES of a directory (best-effort): the plain names of its
+ * direct children, or [] if the dir is absent / unreadable. Used for both the
+ * projects-root listing (pure buildMenuChoiceList filters it to folder-safe
+ * project names) and each machine's sessions dir (the session slugs present).
+ */
+function readDirNames(dir) {
+    if (!existsSync(dir))
+        return [];
+    try {
+        return readdirSync(dir, { withFileTypes: true }).map((d) => d.name);
+    }
+    catch {
+        return [];
+    }
+}
+// --- the hand-rolled, zero-dependency raw-mode selector ----------------------
+//
+// A small supply-chain surface is on-brand for a security tool and the project
+// list is short, so instead of a prompt library we drive stdin in raw mode
+// ourselves: up/down (arrows or k/j) move a `>` cursor, Enter selects, Ctrl-C /
+// q / Esc cancels. The active row is highlighted (reverse video). The terminal
+// is ALWAYS restored (raw mode off, cursor shown) on every exit path, including
+// Ctrl-C. Isolated here behind a tiny signature so a well-regarded prompt lib
+// could swap in later as a localized change. This is the ONLY untested I/O in
+// the menu; all logic (entries + labels) is the pure buildMenuEntries.
+const ESC = '\u001b';
+/**
+ * Present `entries` as an arrow-key list and return the chosen one, or undefined
+ * on cancel (Ctrl-C / q / Esc / EOF). Blocks on raw stdin; restores the terminal
+ * on every path. An empty entry list returns undefined immediately (nothing to
+ * pick), though the menu always offers at least the `.` here entry.
+ */
+function select(entries, opts = {}) {
+    if (entries.length === 0)
+        return undefined;
+    const out = process.stdout;
+    const stdin = process.stdin;
+    let active = 0;
+    const render = (first) => {
+        if (!first) {
+            // move cursor up over the previously drawn rows to redraw in place.
+            out.write(`${ESC}[${entries.length}A`);
+        }
+        for (let i = 0; i < entries.length; i++) {
+            const selected = i === active;
+            const cursor = selected ? '>' : ' ';
+            const text = `${cursor} ${entries[i].label}`;
+            // clear the line, then draw; reverse-video the active row.
+            out.write(`${ESC}[2K`);
+            out.write(selected ? `${ESC}[7m${text}${ESC}[0m` : text);
+            out.write('\n');
+        }
+    };
+    const wasRaw = stdin.isRaw ?? false;
+    const restore = () => {
+        try {
+            if (stdin.setRawMode)
+                stdin.setRawMode(wasRaw);
+        }
+        catch {
+            /* best-effort */
+        }
+        out.write(`${ESC}[?25h`); // show the cursor again
+    };
+    if (opts.header)
+        out.write(opts.header + '\n');
+    out.write(`${ESC}[?25l`); // hide the cursor while navigating
+    try {
+        if (stdin.setRawMode)
+            stdin.setRawMode(true);
+    }
+    catch {
+        /* if raw mode is unavailable we still render + read line-ish below */
+    }
+    render(true);
+    const buf = Buffer.alloc(3);
+    for (;;) {
+        let n;
+        try {
+            n = readSync(0, buf, 0, 3, null);
+        }
+        catch (e) {
+            if (e.code === 'EAGAIN')
+                continue;
+            restore();
+            return undefined;
+        }
+        if (n === 0) {
+            restore();
+            return undefined; // EOF
+        }
+        const s = buf.toString('utf8', 0, n);
+        // Ctrl-C (ETX \x03), q, or a bare Esc: cancel.
+        if (s === '\u0003' || s === 'q' || s === ESC) {
+            restore();
+            return undefined;
+        }
+        // Enter (CR or LF): select the active row.
+        if (s === '\r' || s === '\n') {
+            restore();
+            return entries[active];
+        }
+        // Up: arrow `Esc [ A` / `Esc O A`, or k. Down: `Esc [ B` / `Esc O B`, or j.
+        if (s === `${ESC}[A` || s === `${ESC}OA` || s === 'k') {
+            active = (active - 1 + entries.length) % entries.length;
+            render(false);
+            continue;
+        }
+        if (s === `${ESC}[B` || s === `${ESC}OB` || s === 'j') {
+            active = (active + 1) % entries.length;
+            render(false);
+            continue;
+        }
+        // any other key: ignore, keep waiting.
+    }
+}
+// --- the `machine` verbs (thin dispatch over the pure parts) -----------------
+//
+// Parse the `machine <verb> …` grammar (pure parseMachineArgs), then do only the
+// I/O: mkdir/write the machine layout (create), read machines/*/machine.json
+// (list), rewrite machine.json + WARN (set-image), and rm the machine dir with
+// the confirm/`--yes`/non-TTY discipline (rm). All validation + the machine.json
+// body + the warning wording live in the pure module.
+function runMachine(machineArgs) {
+    if (machineArgs.includes('--help') || machineArgs.includes('-h')) {
+        process.stdout.write(MACHINE_HELP);
+        return 0;
     }
     const env = envFromProcess(process.env);
-    if (!env.llmDirect || env.llmDirect.trim() === '') {
-        process.stderr.write('anon-pi import: set ANON_PI_LLM to the RFC1918/link-local IP[:port] of the local\n' +
-            'model whose provider should be imported (e.g. ANON_PI_LLM=192.168.1.150:8080).\n');
+    let cmd;
+    try {
+        cmd = parseMachineArgs(machineArgs);
+    }
+    catch (e) {
+        return reportAnonPiError(e);
+    }
+    try {
+        switch (cmd.verb) {
+            case 'create':
+                return machineCreate(env, cmd.name, cmd.image);
+            case 'list':
+                return machineList(env);
+            case 'set-image':
+                return machineSetImage(env, cmd.name, cmd.image);
+            case 'rm':
+                return machineRm(env, cmd.name, cmd.yes);
+        }
+    }
+    catch (e) {
+        return reportAnonPiError(e);
+    }
+}
+/**
+ * `machine create <name> [--image <ref>]`: write machines/<name>/{machine.json,
+ * home/} and PIN the image (from --image or a TTY prompt). The home is only a
+ * dir here; it is SEEDED on first LAUNCH, not now. Refuses to clobber an
+ * existing machine.
+ */
+function machineCreate(env, name, image) {
+    const dir = machineDir(env, name);
+    if (existsSync(dir)) {
+        process.stderr.write(`anon-pi: machine ${JSON.stringify(name)} already exists (${dir}). ` +
+            'Use `anon-pi machine set-image` to re-pin its image, or `anon-pi machine rm` first.\n');
         return 1;
     }
-    const source = resolveSourceModelsPath(env);
-    if (!existsSync(source)) {
-        process.stderr.write(`anon-pi import: host models.json not found at ${source}.\n` +
-            'Set ANON_PI_SOURCE_MODELS to your pi models.json, or run pi once to create it.\n');
+    // Pin the image: --image wins; else prompt on a TTY; else it is an error (a
+    // machine with no image cannot launch, so we refuse a headless imageless create).
+    let pinned = image;
+    if (pinned === undefined) {
+        if (!process.stdin.isTTY) {
+            process.stderr.write('anon-pi: no image and no TTY to prompt. Pass `--image <ref>` to pin the ' +
+                "machine's image (a container ref with `pi` on PATH).\n");
+            return 1;
+        }
+        pinned = promptLine(`Image ref for machine ${JSON.stringify(name)} (a container with \`pi\` on PATH): `);
+        if (pinned === undefined || pinned.trim() === '') {
+            process.stderr.write('anon-pi: no image given; aborting create.\n');
+            return 1;
+        }
+    }
+    mkdirSync(machineHomeDir(env, name), { recursive: true });
+    writeFileSync(machineJsonPath(env, name), serializeMachineJson({ image: pinned }));
+    process.stdout.write(`anon-pi: created machine ${JSON.stringify(name)} (image ${pinned.trim()}) at ${dir}.\n` +
+        `Its home is seeded on first launch, e.g. \`anon-pi -m ${name} --shell\`.\n`);
+    return 0;
+}
+/**
+ * `machine list`: print each machine under machines/ with its pinned image
+ * (reading each machine's machine.json). An absent/garbage machine.json shows
+ * `(no image)` rather than erroring, so a hand-edited workspace still lists.
+ */
+function machineList(env) {
+    const root = join(resolveAnonPiHome(env), 'machines');
+    const names = existsSync(root)
+        ? readdirSync(root, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name)
+            .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+        : [];
+    if (names.length === 0) {
+        process.stdout.write('anon-pi: no machines yet. Create one with `anon-pi machine create <name> --image <ref>`.\n');
+        return 0;
+    }
+    for (const name of names) {
+        const conf = readMachineJson(env, name);
+        const image = conf.image ?? '(no image)';
+        process.stdout.write(`${name}\t${image}\n`);
+    }
+    return 0;
+}
+/**
+ * `machine set-image <name> <ref>`: RE-PIN the image and WARN only. It does NOT
+ * reseed or touch the home (the home's extensions/bin were built for the OLD
+ * image). Preserves any per-machine projects override. The machine must exist.
+ */
+function machineSetImage(env, name, image) {
+    const dir = machineDir(env, name);
+    if (!existsSync(dir)) {
+        process.stderr.write(`anon-pi: no machine ${JSON.stringify(name)} (${dir}). ` +
+            'Create it first with `anon-pi machine create`.\n');
+        return 1;
+    }
+    const prev = readMachineJson(env, name);
+    writeFileSync(machineJsonPath(env, name), serializeMachineJson({ image, projects: prev.projects }));
+    process.stderr.write(setImageWarning(name, prev.image, image.trim()) + '\n');
+    return 0;
+}
+/**
+ * `machine rm <name> [--yes]`: delete the machine dir (its machine.json + home)
+ * after a confirm. Mirrors the destructive data-verb discipline: confirm on a
+ * TTY, `--yes` skips it, and a non-TTY WITHOUT `--yes` ABORTS (never deletes
+ * unprompted in a script). The machine must exist.
+ */
+function machineRm(env, name, yes) {
+    const dir = machineDir(env, name);
+    if (!existsSync(dir)) {
+        process.stderr.write(`anon-pi: no machine ${JSON.stringify(name)} (${dir}); nothing to remove.\n`);
         return 1;
     }
-    let hostModels;
+    if (!yes) {
+        if (!process.stdin.isTTY) {
+            process.stderr.write(`anon-pi: refusing to delete machine ${JSON.stringify(name)} without a TTY to confirm. ` +
+                'Re-run with `--yes` to delete it (its home + conversations) non-interactively.\n');
+            return 1;
+        }
+        const answer = promptLine(`Delete machine ${JSON.stringify(name)} and its home (conversations, config) at ${dir}? [y/N] `);
+        if (answer === undefined || !/^y(es)?$/i.test(answer.trim())) {
+            process.stderr.write('anon-pi: aborted; nothing deleted.\n');
+            return 1;
+        }
+    }
+    rmSync(dir, { recursive: true, force: true });
+    process.stdout.write(`anon-pi: removed machine ${JSON.stringify(name)} (${dir}).\n`);
+    return 0;
+}
+// --- the destructive cleanup verbs (thin I/O over the pure resolvers) --------
+//
+// `--delete-home [<machine>]` and `--delete-project <project>` REPLACE the old
+// `--fresh`. The pure module resolves the affected host paths (resolveDeleteHome
+// / resolveDeleteProject); the CLI does ONLY the I/O: read config (for the
+// default machine + the projects root), filter the resolved paths to those that
+// exist, run the shared confirm/`--yes`/non-TTY discipline, then `rm`.
+/**
+ * Parse the shared `[<positional>] [--yes|-y]` tail of a data verb. Returns the
+ * (optional) positional (a machine or project name) + the `--yes` flag, or an
+ * AnonPiError-style exit for an unknown flag / an extra positional.
+ */
+function parseDeleteArgs(args, verb) {
+    let name;
+    let yes = false;
+    for (const a of args) {
+        if (a === '--yes' || a === '-y') {
+            yes = true;
+            continue;
+        }
+        if (a.startsWith('-')) {
+            process.stderr.write(`anon-pi: unknown option for ${verb}: ${a}. Run \`anon-pi --help\`.\n`);
+            return 1;
+        }
+        if (name !== undefined) {
+            process.stderr.write(`anon-pi: ${verb} takes one name, got extra: ${a}. Run \`anon-pi --help\`.\n`);
+            return 1;
+        }
+        name = a;
+    }
+    return { name, yes };
+}
+/**
+ * Run the confirm/`--yes`/non-TTY discipline for a destructive delete: `--yes`
+ * skips the prompt; a non-TTY WITHOUT `--yes` ABORTS (never deletes unprompted
+ * in a script); a TTY prompts `[y/N]`. Returns true to PROCEED, false to abort
+ * (the caller has already printed nothing; this prints the abort/refusal note).
+ */
+function confirmDelete(what, yes) {
+    if (yes)
+        return true;
+    if (!process.stdin.isTTY) {
+        process.stderr.write(`anon-pi: refusing to delete ${what} without a TTY to confirm. ` +
+            'Re-run with `--yes` to delete it non-interactively.\n');
+        return false;
+    }
+    const answer = promptLine(`Delete ${what}? [y/N] `);
+    if (answer === undefined || !/^y(es)?$/i.test(answer.trim())) {
+        process.stderr.write('anon-pi: aborted; nothing deleted.\n');
+        return false;
+    }
+    return true;
+}
+/**
+ * `--delete-home [<machine>]`: delete ONE machine's HOME (config + convos + shell
+ * env), keeping its machine.json image pin (so it can be relaunched to reseed a
+ * fresh home) and ALL project files (they live under the projects root). Default
+ * machine (config.defaultMachine, else the built-in DEFAULT_MACHINE) when the
+ * name is omitted. Confirm / `--yes` / non-TTY abort.
+ */
+function runDeleteHome(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    const env = envFromProcess(process.env);
+    const parsed = parseDeleteArgs(args, '--delete-home');
+    if (typeof parsed === 'number')
+        return parsed;
+    const config = readJsonConfig(env);
+    const machine = parsed.name ?? config.defaultMachine ?? DEFAULT_MACHINE;
+    let plan;
     try {
-        hostModels = JSON.parse(readFileSync(source, 'utf8'));
+        plan = resolveDeleteHome(env, machine);
     }
     catch (e) {
-        process.stderr.write(`anon-pi import: could not parse ${source}: ${e.message}\n`);
+        return reportAnonPiError(e);
+    }
+    if (!existsSync(plan.home)) {
+        process.stderr.write(`anon-pi: no home for machine ${JSON.stringify(plan.machine)} (${plan.home}); nothing to delete.\n`);
+        return 1;
+    }
+    if (!confirmDelete(`machine ${JSON.stringify(plan.machine)} home (conversations + config) at ${plan.home}`, parsed.yes)) {
+        return 1;
+    }
+    rmSync(plan.home, { recursive: true, force: true });
+    process.stdout.write(`anon-pi: deleted machine ${JSON.stringify(plan.machine)} home (${plan.home}). ` +
+        'Its image pin is kept; relaunch to seed a fresh home.\n');
+    return 0;
+}
+/**
+ * `--delete-project <project>`: delete the project's FILES (its folder under the
+ * resolved projects root) AND that project's per-machine session dir in EVERY
+ * machine home (the machine-invariant slug), keeping the homes otherwise intact.
+ * Confirm / `--yes` / non-TTY abort. The project name is REQUIRED.
+ */
+function runDeleteProject(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    const env = envFromProcess(process.env);
+    const parsed = parseDeleteArgs(args, '--delete-project');
+    if (typeof parsed === 'number')
+        return parsed;
+    if (parsed.name === undefined) {
+        process.stderr.write('anon-pi: --delete-project needs a <project>. Run `anon-pi --help`.\n');
         return 1;
     }
-    let result;
+    const config = readJsonConfig(env);
+    // The RESOLVED projects root (config/env override, else the built-in). No
+    // --mount here: a data verb targets the durable projects root, not a per-run
+    // host parent.
+    const projectsRoot = resolveProjectsRoot({ env, config });
+    const machines = listMachineNames(env);
+    let plan;
     try {
-        result = pickProviderForLlm(hostModels, env.llmDirect);
+        plan = resolveDeleteProject({
+            env,
+            project: parsed.name,
+            projectsRoot,
+            machines,
+        });
     }
     catch (e) {
-        if (e instanceof AnonPiError) {
-            process.stderr.write(e.message + '\n');
-            return 1;
-        }
-        throw e;
+        return reportAnonPiError(e);
     }
-    const seedDir = resolveConfigSeed(env);
-    const dest = join(seedDir, MODELS_FILE);
-    if (existsSync(dest) && !force) {
-        process.stderr.write(`anon-pi import: ${dest} already exists. Re-run with --force to overwrite.\n`);
+    // Only the paths that actually exist: the folder (maybe absent) + whichever
+    // machine homes hold this project's session dir.
+    const targets = [plan.folder, ...plan.sessions].filter((p) => existsSync(p));
+    if (targets.length === 0) {
+        process.stderr.write(`anon-pi: no files or sessions found for project ${JSON.stringify(plan.project)} ` +
+            `(looked in ${plan.folder} and each machine home); nothing to delete.\n`);
         return 1;
     }
-    if (result.apiKeyLooksReal) {
-        process.stderr.write(`anon-pi import: WARNING: provider "${result.name}" carries a real-looking apiKey; it\n` +
-            'will be written into the seed. For a local model this is usually fine, but review\n' +
-            `${dest} if that key identifies you.\n`);
+    const sessionCount = targets.length - (existsSync(plan.folder) ? 1 : 0);
+    if (!confirmDelete(`project ${JSON.stringify(plan.project)}: its files (${plan.folder}) ` +
+        `and ${sessionCount} per-machine session dir(s)`, parsed.yes)) {
+        return 1;
+    }
+    for (const p of targets)
+        rmSync(p, { recursive: true, force: true });
+    process.stdout.write(`anon-pi: deleted project ${JSON.stringify(plan.project)} ` +
+        `(files + ${sessionCount} per-machine session dir(s)). The machine homes are kept.\n`);
+    return 0;
+}
+// --- `anon-pi init` onboarding (thin I/O over the pure detect/verify decisions) --
+//
+// init is the HONEST, re-runnable onboarding. It captures the socks5h PROXY (by
+// evidence: open ports + a real SOCKS5 handshake + a real `netcage verify` exit
+// IP, NEVER a provider label), the local-model ENDPOINT (generating models.json
+// from it), and the default machine IMAGE (menu from shipped Dockerfiles / an
+// existing ref / skip, building via `podman build`), then writes config.json +
+// the `default` machine. It REPLACES the old `import`. All the DECISIONS are
+// pure (anon-pi.ts); this does only the socket probes, the netcage/podman
+// spawns, and the prompts. It NEVER destroys machines/homes: it pre-fills
+// current values and only ADDS/updates config + a fresh default machine.
+const INIT_HELP = `anon-pi init - onboard: verify your proxy, capture your local model, pick an image
+
+USAGE
+  anon-pi init                    interactive onboarding (re-runnable reconfigure)
+
+WHAT IT DOES
+  1. PROXY: probes common SOCKS ports, confirms SOCKS5 via a real handshake,
+     shows the findings (EVIDENCE only, never a provider label), then runs
+     \`netcage verify\` and shows the real EXIT IP as proof. You confirm.
+  2. LOCAL MODEL: captures host:port, probes it, then IMPORTS models. It merges
+     your pi config's matching provider ([configured], well-tuned) with the
+     endpoint's live /v1/models ([server]); you pick which to import + the
+     default. Only the provider served by this endpoint (the one --allow-direct
+     hole) is ever read, so no other provider or key can enter the seed. Writes
+     models.json + a settings seed (the default-model selection).
+  3. IMAGE: pick a shipped Dockerfile (built via podman), an existing ref, or skip.
+  4. PROJECTS ROOT: the host folder mounted at /projects (default ~/.anon-pi/
+     projects); point it at your own dev folder, or keep the default.
+  Then writes ~/.anon-pi/config.json + the \`default\` machine. Never destroys homes.
+
+  Runs AUTOMATICALLY the first time you launch anon-pi with no config yet.
+
+FLAGS
+  --force-allow-local-llm-api-key  carry a REAL apiKey from the matching host
+     provider into the seed (init refuses by default: a host credential should
+     not enter the anonymized machine home unless you say so).
+`;
+function runInit(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        process.stdout.write(INIT_HELP);
+        return 0;
+    }
+    const FORCE_KEY_FLAG = '--force-allow-local-llm-api-key';
+    const forceLocalApiKey = args.includes(FORCE_KEY_FLAG);
+    const extra = args.filter((a) => a !== FORCE_KEY_FLAG);
+    if (extra.length > 0) {
+        process.stderr.write(`anon-pi: init takes no arguments (except ${FORCE_KEY_FLAG}), got: ${extra.join(' ')}. Run \`anon-pi init --help\`.\n`);
+        return 1;
+    }
+    if (!process.stdin.isTTY) {
+        process.stderr.write('anon-pi: init is interactive and needs a TTY. Run it in a terminal. To set\n' +
+            'values non-interactively, write ~/.anon-pi/config.json + a machine.json by hand,\n' +
+            'or export ANON_PI_PROXY / ANON_PI_LLM (they override config.json).\n');
+        return 1;
+    }
+    const env = envFromProcess(process.env);
+    // Pre-fill from the CURRENT config (re-runnable: init doubles as reconfigure).
+    const current = readJsonConfig(env);
+    process.stdout.write('anon-pi init: honest, evidence-based onboarding. Nothing is destroyed; your\n' +
+        'current values are pre-filled. Press Ctrl-C to abort at any prompt.\n\n');
+    // 1) PROXY: probe + handshake + findings + netcage verify + confirm.
+    const proxyHostPort = initProxyStep(current.proxy);
+    if (proxyHostPort === undefined)
+        return 1;
+    const proxyUrl = socks5hUrl(proxyHostPort);
+    // 2) LOCAL MODEL endpoint + model import: capture the endpoint, then merge the
+    //    host config's matching provider (well-tuned) with the endpoint's live
+    //    /v1/models, let the user pick which to import + the default. May ABORT
+    //    (a real host apiKey without --force-allow-local-llm-api-key).
+    const llmResult = initLlmStep(env, current.llm, forceLocalApiKey);
+    if (llmResult === ABORT)
+        return 1;
+    const llm = llmResult.endpoint;
+    // 3) DEFAULT MACHINE IMAGE: menu (shipped Dockerfiles / existing ref / skip).
+    const image = initImageStep();
+    if (image === ABORT)
+        return 1;
+    // 4) PROJECTS ROOT: the host dir mounted at /projects (default ~/.anon-pi/
+    //    projects). Overridable per-launch with `--mount`; this sets the default.
+    const projects = initProjectsStep(env, current.projects);
+    // 5) WRITE config.json + the `default` machine (never destroying an existing
+    //    home). The proxy is always present (we only reach here on a chosen proxy).
+    const anonHome = resolveAnonPiHome(env);
+    mkdirSync(anonHome, { recursive: true });
+    const configPath = join(anonHome, 'config.json');
+    const nextConfig = {
+        proxy: proxyUrl,
+        llm: llm ?? current.llm,
+        defaultMachine: current.defaultMachine ?? DEFAULT_MACHINE,
+        projects: projects ?? current.projects,
+    };
+    writeFileSync(configPath, serializeConfigJson(nextConfig));
+    process.stdout.write(`\nanon-pi: wrote ${configPath}.\n`);
+    // The `default` machine: create it if absent (NEVER wipe an existing home),
+    // pin/re-pin its image when one was chosen. Its home seeds on first launch.
+    initWriteDefaultMachine(env, image);
+    // The per-machine models.json + settings.json seed for the default machine,
+    // generated from the captured endpoint + the CHOSEN models (this is the
+    // `import` replacement). Written next to the machine so the first-launch seed
+    // promotes them into the fresh home.
+    const endpoint = llm ?? current.llm;
+    if (endpoint !== undefined) {
+        const mdir = machineDir(env, DEFAULT_MACHINE);
+        mkdirSync(mdir, { recursive: true });
+        const models = generateModelsJson(endpoint, llmResult.models, llmResult.apiKey);
+        writeFileSync(join(mdir, MODELS_FILE), JSON.stringify(models, null, '\t') + '\n');
+        process.stdout.write(`anon-pi: wrote the local-model models.json for machine "${DEFAULT_MACHINE}" ` +
+            `(${llmResult.models.length} model${llmResult.models.length === 1 ? '' : 's'}).\n`);
+        // settings.json: set the default model + enabledModels for the imported
+        // set. Written as a SEED that the first-launch promotion merges into the
+        // home's settings (so image-staged packages/extensions survive). Only when
+        // the user picked at least one model + a default.
+        if (llmResult.defaultId !== undefined && llmResult.models.length > 0) {
+            const selection = generateModelSelection(llmResult.models.map((m) => m.id), llmResult.defaultId);
+            writeFileSync(join(mdir, SETTINGS_SEED_FILE), JSON.stringify(selection, null, '\t') + '\n');
+            process.stdout.write(`anon-pi: default model set to "${llmResult.defaultId}".\n`);
+        }
     }
-    mkdirSync(seedDir, { recursive: true });
-    writeFileSync(dest, JSON.stringify(result.models, null, 2) + '\n');
-    process.stderr.write(`anon-pi import: wrote ${dest} (provider "${result.name}"). Run \`anon-pi\` to launch.\n`);
+    process.stdout.write('\nanon-pi: onboarding complete. Launch with `anon-pi <project>` or ' +
+        '`anon-pi --shell`.\n');
     return 0;
 }
+/** A sentinel a step returns when the user aborted (distinct from "skipped"). */
+const ABORT = Symbol('abort');
+/**
+ * The PROXY step: probe the default SOCKS ports, confirm SOCKS5 via a real
+ * handshake, show the EVIDENCE (never a provider label), let the user CHOOSE a
+ * SOCKS5-confirmed port or enter host:port, then run `netcage verify` and show
+ * the real EXIT IP before confirming. Returns the chosen host:port, or undefined
+ * on abort. The socket probes + the netcage spawn are the only I/O; the display
+ * + the handshake verdict come from the pure module.
+ */
+function initProxyStep(currentProxy) {
+    process.stdout.write('Step 1/4 - proxy (the socks5h endpoint that anonymizes egress)\n');
+    if (currentProxy) {
+        process.stdout.write(`  current: ${currentProxy}\n`);
+    }
+    process.stdout.write('  Probing common SOCKS ports (evidence only)...\n');
+    // Probe each default port: TCP-open + a real SOCKS5 handshake. The weak
+    // process hint (a running `tor`/`wireproxy` LOCAL process, never the exit
+    // provider) is HOST-WIDE, so gather it ONCE and pass it as the formatter's
+    // single general note rather than gluing it onto every port line. The display
+    // is the PURE formatter's job.
+    const runningProcesses = observeRunningProcesses();
+    const processNote = matchProcessHint(runningProcesses);
+    const findings = DEFAULT_SOCKS_PROBE_PORTS.map(({ port, hint }) => {
+        const { open, handshake } = probeSocks5('127.0.0.1', port);
+        return {
+            host: '127.0.0.1',
+            port,
+            open,
+            handshake,
+            portHint: hint,
+        };
+    });
+    process.stdout.write('\n' + formatProxyFindings(findings, processNote) + '\n\n');
+    // Offer the SOCKS5-confirmed candidates as quick picks; always allow a manual
+    // host:port entry (and pre-fill the current one).
+    const confirmed = findings.filter((f) => f.open && f.handshake?.socks5);
+    for (;;) {
+        if (confirmed.length > 0) {
+            process.stdout.write('SOCKS5-confirmed ports:\n');
+            confirmed.forEach((f, i) => {
+                process.stdout.write(`  [${i + 1}] ${f.host}:${f.port}\n`);
+            });
+        }
+        const prefill = currentProxy
+            ? ` (or Enter to keep ${hostPortKey(currentProxy)})`
+            : '';
+        const ans = promptLine(`Choose a number, or enter host:port${prefill}: `);
+        if (ans === undefined) {
+            process.stderr.write('anon-pi: aborted; nothing written.\n');
+            return undefined;
+        }
+        const trimmed = ans.trim();
+        let chosen;
+        if (trimmed === '' && currentProxy) {
+            chosen = hostPortKey(currentProxy);
+        }
+        else if (/^\d+$/.test(trimmed) && confirmed.length > 0) {
+            const idx = Number(trimmed) - 1;
+            if (idx >= 0 && idx < confirmed.length) {
+                const f = confirmed[idx];
+                chosen = `${f.host}:${f.port}`;
+            }
+        }
+        else if (trimmed !== '') {
+            chosen = hostPortKey(trimmed);
+        }
+        if (chosen === undefined || chosen === '') {
+            process.stdout.write('  Please pick a listed number or enter a host:port.\n');
+            continue;
+        }
+        // VERIFY: run `netcage verify --proxy socks5h://<chosen>` and show the real
+        // exit IP as evidence it is NOT the host IP. The user confirms ON that
+        // evidence. netcage never announces the provider, so neither do we.
+        const url = socks5hUrl(chosen);
+        process.stdout.write(`\n  Verifying via netcage: netcage verify --proxy ${url}\n`);
+        if (!hasNetcage()) {
+            process.stderr.write('anon-pi: `netcage` not found on PATH, cannot verify the exit IP. Install\n' +
+                'it first (https://github.com/wighawag/netcage). Linux only.\n');
+            return undefined;
+        }
+        const verify = spawnSync('netcage', ['verify', '--proxy', url], {
+            encoding: 'utf8',
+        });
+        const output = `${verify.stdout ?? ''}${verify.stderr ?? ''}`;
+        if (verify.error || verify.status !== 0) {
+            process.stdout.write(output.trimEnd() + '\n');
+            process.stdout.write(`  netcage verify FAILED for ${url} (exit ${verify.status ?? 'n/a'}). ` +
+                'Pick another port or fix the proxy.\n\n');
+            continue;
+        }
+        const exitIp = parseVerifyExitIp(output);
+        if (exitIp) {
+            process.stdout.write(`  Exit IP (via the proxy, NOT your host): ${exitIp}\n`);
+        }
+        else {
+            process.stdout.write('  netcage verify succeeded but no exit IP was parsed; raw output:\n' +
+                output.trimEnd() +
+                '\n');
+        }
+        const ok = promptLine(`  Use ${url} as your proxy? [Y/n] `);
+        if (ok === undefined) {
+            process.stderr.write('anon-pi: aborted; nothing written.\n');
+            return undefined;
+        }
+        if (/^n(o)?$/i.test(ok.trim())) {
+            process.stdout.write('  OK, pick another.\n\n');
+            continue;
+        }
+        return chosen;
+    }
+}
+/**
+ * The LOCAL MODEL step: capture host:port (pre-filled from config), probe TCP
+ * reachability, then IMPORT models. It merges TWO sources, both scoped to the
+ * endpoint (the one `--allow-direct` hole, so no other provider can enter the
+ * seed): the host `~/.pi/agent/models.json` provider whose baseUrl matches the
+ * endpoint (well-tuned entries, marked [configured]) and the endpoint's live
+ * `/v1/models` (bare ids, marked [server]). The user picks which to import and
+ * the default. Returns the endpoint + chosen entries + apiKey + default, or
+ * ABORT (a real host apiKey without --force-allow-local-llm-api-key).
+ */
+function initLlmStep(env, currentLlm, forceLocalApiKey) {
+    process.stdout.write('\nStep 2/4 - local model endpoint (the ONE direct hole)\n');
+    if (currentLlm)
+        process.stdout.write(`  current: ${currentLlm}\n`);
+    const prefill = currentLlm
+        ? ` (or Enter to keep ${currentLlm})`
+        : ' (or Enter to skip)';
+    const ans = promptLine(`  Local model host:port, e.g. 192.168.1.150:8080${prefill}: `);
+    const raw = ans === undefined ? '' : ans.trim();
+    const endpoint = raw === '' ? currentLlm : raw;
+    if (endpoint === undefined) {
+        // No endpoint at all: nothing to import.
+        return {
+            endpoint: undefined,
+            models: [],
+            apiKey: LOCAL_PROVIDER_API_KEY,
+            defaultId: undefined,
+        };
+    }
+    // Probe reachability: evidence only. A closed port is not fatal (the model may
+    // start later); we just report it.
+    const key = hostPortKey(endpoint);
+    const colon = key.lastIndexOf(':');
+    const host = colon > 0 ? key.slice(0, colon) : key;
+    const port = colon > 0 ? Number(key.slice(colon + 1)) : 80;
+    const reachable = Number.isFinite(port) ? probeTcp(host, port) : false;
+    process.stdout.write(reachable
+        ? `  reachable: ${host}:${port} accepted a TCP connection.\n`
+        : `  note: ${host}:${port} did not accept a connection now (the model may not be up yet).\n`);
+    // SOURCE A: the host models.json provider matching this endpoint (only that
+    // one — the anonymity scoping). Its apiKey is checked: a REAL key is refused
+    // unless --force-allow-local-llm-api-key.
+    const hostModels = readJsonFile(resolveHostModelsPath(env));
+    const match = pickLocalProviderModels(hostModels ?? {}, endpoint);
+    let apiKey = LOCAL_PROVIDER_API_KEY;
+    if (match && match.apiKeyLooksReal) {
+        if (!forceLocalApiKey) {
+            process.stderr.write(`\n  anon-pi: the matching provider in your pi config carries a real-looking\n` +
+                `  apiKey. Seeding it would put a host credential into the anonymized machine\n` +
+                `  home. Refusing. If this key is genuinely safe for the local model, re-run\n` +
+                `  \`anon-pi init --force-allow-local-llm-api-key\` to carry it through.\n`);
+            return ABORT;
+        }
+        apiKey = (match.apiKey ?? LOCAL_PROVIDER_API_KEY).trim();
+        process.stdout.write('  WARNING: carrying the host provider apiKey into the seed (--force-allow-local-llm-api-key).\n');
+    }
+    const hostModelEntries = match?.models ?? [];
+    // SOURCE B: the endpoint's live /v1/models (bare ids).
+    let serverIds = [];
+    if (Number.isFinite(port)) {
+        const listing = fetchModelsListing(host, port);
+        serverIds = parseModelsListing(listing);
+    }
+    if (hostModelEntries.length === 0 && serverIds.length === 0) {
+        process.stdout.write('  No models found (no matching provider in your pi config, and the server\n' +
+            '  returned none). The provider is still seeded; add models in pi later.\n');
+        return { endpoint, models: [], apiKey, defaultId: undefined };
+    }
+    const candidates = mergeModelSources(hostModelEntries, serverIds);
+    const chosen = initModelPicker(candidates);
+    if (chosen === undefined) {
+        // Skip: seed the provider with no models.
+        return { endpoint, models: [], apiKey, defaultId: undefined };
+    }
+    const defaultId = initDefaultModelPicker(chosen);
+    return { endpoint, models: chosen, apiKey, defaultId };
+}
+/**
+ * Present the merged candidate list and let the user choose which to import.
+ * Options: Enter/`c` = all CONFIGURED (host-tuned; the safe default), `a` = ALL
+ * (server + configured), space/comma-separated NUMBERS = those, `s` = skip.
+ * Returns the chosen entries, or undefined to skip (seed no models).
+ */
+function initModelPicker(candidates) {
+    const configured = candidates.filter((c) => c.configured);
+    process.stdout.write('\n  Models served by this endpoint:\n');
+    candidates.forEach((c, i) => {
+        const tag = c.configured ? '[configured]' : '[server]';
+        process.stdout.write(`    [${i + 1}] ${c.id} ${tag}\n`);
+    });
+    process.stdout.write('  [configured] = from your pi config (well-tuned); [server] = the server\n' +
+        '  also reports it (a minimal entry is synthesized).\n');
+    const hasConfigured = configured.length > 0;
+    const defaultHint = hasConfigured
+        ? 'Enter/c = all configured, a = all, numbers = pick, s = skip'
+        : 'Enter/a = all, numbers = pick, s = skip';
+    for (;;) {
+        const ans = promptLine(`  Import which? (${defaultHint}): `);
+        const v = (ans ?? '').trim().toLowerCase();
+        if (v === 's')
+            return undefined;
+        if (v === '' && hasConfigured)
+            return configured.map((c) => c.entry);
+        if (v === 'c') {
+            if (!hasConfigured) {
+                process.stdout.write('  No [configured] models; pick numbers or `a` for all.\n');
+                continue;
+            }
+            return configured.map((c) => c.entry);
+        }
+        if (v === 'a' || (v === '' && !hasConfigured)) {
+            return candidates.map((c) => c.entry);
+        }
+        // Numbers (space/comma separated).
+        const picks = v
+            .split(/[\s,]+/)
+            .filter((t) => t !== '')
+            .map((t) => Number(t) - 1);
+        if (picks.length > 0 &&
+            picks.every((i) => i >= 0 && i < candidates.length)) {
+            // De-dup, keep list order.
+            const seen = new Set();
+            const out = [];
+            for (const i of picks) {
+                if (!seen.has(i)) {
+                    seen.add(i);
+                    out.push(candidates[i].entry);
+                }
+            }
+            return out;
+        }
+        process.stdout.write(`  Please enter Enter/c/a/s or numbers 1-${candidates.length}.\n`);
+    }
+}
+/**
+ * Pick the DEFAULT model among the chosen ones. Defaults to the first (Enter);
+ * accepts a number. Returns the chosen id.
+ */
+function initDefaultModelPicker(chosen) {
+    if (chosen.length === 1)
+        return chosen[0].id;
+    process.stdout.write('\n  Which is the DEFAULT model?\n');
+    chosen.forEach((m, i) => {
+        process.stdout.write(`    [${i + 1}] ${m.id}\n`);
+    });
+    for (;;) {
+        const ans = promptLine(`  Default [1-${chosen.length}] (Enter = ${chosen[0].id}): `);
+        const v = (ans ?? '').trim();
+        if (v === '')
+            return chosen[0].id;
+        const idx = Number(v) - 1;
+        if (Number.isInteger(idx) && idx >= 0 && idx < chosen.length) {
+            return chosen[idx].id;
+        }
+        process.stdout.write(`  Please pick a number 1-${chosen.length}.\n`);
+    }
+}
+/**
+ * The IMAGE step: the pure menu (shipped Dockerfiles / existing ref / skip), then
+ * the impure action for the pick (build via `podman build`, take a ref, or
+ * skip). Returns the resolved image ref, undefined for skip, or ABORT.
+ */
+function initImageStep() {
+    process.stdout.write('\nStep 3/4 - default machine image (an image with `pi` on PATH)\n');
+    const menu = initImageMenu();
+    menu.forEach((e, i) => {
+        process.stdout.write(`  [${i + 1}] ${e.label}\n`);
+    });
+    for (;;) {
+        const ans = promptLine('  Choose [1-4]: ');
+        if (ans === undefined)
+            return ABORT;
+        const idx = Number(ans.trim()) - 1;
+        if (!Number.isInteger(idx) || idx < 0 || idx >= menu.length) {
+            process.stdout.write('  Please pick a number 1-4.\n');
+            continue;
+        }
+        const choice = menu[idx].choice;
+        if (choice === 'skip') {
+            process.stdout.write('  Skipping the image; pin it later with `anon-pi machine set-image`.\n');
+            return undefined;
+        }
+        if (choice === 'existing') {
+            const ref = promptLine('  Image ref (a container with `pi` on PATH): ');
+            if (ref === undefined || ref.trim() === '') {
+                process.stdout.write('  No ref given; pick again.\n');
+                continue;
+            }
+            return ref.trim();
+        }
+        // basic | webveil: build the shipped Dockerfile via `podman build`.
+        const dockerfile = choice === 'basic'
+            ? shippedDockerfilePath()
+            : shippedWebveilDockerfilePath();
+        if (dockerfile === undefined || !existsSync(dockerfile)) {
+            process.stderr.write(`  anon-pi: could not locate the shipped ${choice === 'basic' ? 'Dockerfile.pi' : 'examples/Dockerfile.pi-webveil'}. ` +
+                'Pick an existing ref instead.\n');
+            continue;
+        }
+        const tag = choice === 'basic' ? 'anon-pi/pi:latest' : 'anon-pi/pi-webveil:latest';
+        const built = buildImage(dockerfile, tag);
+        if (!built) {
+            process.stdout.write('  Build failed; pick another option.\n');
+            continue;
+        }
+        return tag;
+    }
+}
+/**
+ * The PROJECTS-ROOT step: the host directory mounted into the jail at /projects
+ * (pi's cwd; a project is /projects/<name>). It defaults to the built-in
+ * `~/.anon-pi/projects/`; the user may point it at their own dev folder so bare
+ * `anon-pi` works there without passing `--mount` every time. `--mount <parent>`
+ * still overrides it per-launch. Returns the chosen root, or undefined to keep
+ * the current/default (so an omitted `projects` in config.json means the
+ * built-in default). Enter accepts the shown default.
+ */
+function initProjectsStep(env, currentProjects) {
+    process.stdout.write('\nStep 4/4 - projects root (the host folder mounted at /projects)\n');
+    const builtin = builtinProjectsRoot(env);
+    const shown = currentProjects ?? builtin;
+    if (currentProjects) {
+        process.stdout.write(`  current: ${currentProjects}\n`);
+    }
+    process.stdout.write('  This is where bare `anon-pi` looks for projects. Point it at your own\n' +
+        '  dev folder to jail pi into files you edit with host tools; `--mount\n' +
+        '  <parent>` still overrides it per-launch. Leave it at the default if\n' +
+        "  you're unsure.\n");
+    const ans = promptLine(`  Projects root (Enter to keep ${shown}): `);
+    if (ans === undefined)
+        return currentProjects;
+    const trimmed = ans.trim();
+    if (trimmed === '')
+        return currentProjects;
+    // Store the built-in as "unset" (undefined) so config.json stays clean when
+    // the user just accepts the default path explicitly.
+    const chosen = resolve(trimmed);
+    if (chosen === builtin)
+        return undefined;
+    return chosen;
+}
+/**
+ * Create or update the `default` machine: create it (dir + machine.json) if
+ * absent, pinning the chosen image; if it already exists, re-pin the image only
+ * when one was chosen (preserving any per-machine projects override), and NEVER
+ * touch its home (init is non-destructive). A skipped image leaves an existing
+ * machine's image as-is, or creates an imageless machine.
+ */
+function initWriteDefaultMachine(env, image) {
+    const name = DEFAULT_MACHINE;
+    const dir = machineDir(env, name);
+    const existed = existsSync(dir);
+    mkdirSync(machineHomeDir(env, name), { recursive: true });
+    if (!existed) {
+        writeFileSync(machineJsonPath(env, name), serializeMachineJson({ image }));
+        process.stdout.write(`anon-pi: created machine "${name}"${image ? ` (image ${image})` : ' (imageless; pin it later)'} at ${dir}.\n`);
+        return;
+    }
+    // Existing machine: re-pin only if a new image was chosen; keep its projects
+    // override and its home untouched.
+    const prev = readMachineJson(env, name);
+    if (image !== undefined) {
+        writeFileSync(machineJsonPath(env, name), serializeMachineJson({ image, projects: prev.projects }));
+        process.stdout.write(`anon-pi: re-pinned machine "${name}" image to ${image} (home kept intact).\n`);
+    }
+    else {
+        process.stdout.write(`anon-pi: machine "${name}" already exists; kept its image + home.\n`);
+    }
+}
+// --- init's thin I/O primitives (socket probes, process observe, podman build) --
+/**
+ * Probe a TCP port for openness AND a SOCKS5 handshake: connect, send the
+ * no-auth method-selection greeting, read the reply, and interpret it with the
+ * PURE interpretSocks5Handshake. Fully synchronous + best-effort with a short
+ * timeout so init stays a simple linear prompt flow. On any connect failure the
+ * port is `open: false` with no handshake.
+ */
+function probeSocks5(host, port) {
+    // A synchronous SOCKS5 probe: node's net is async, so we drive a tiny state
+    // machine over a blocking loop using a short deadline. To keep it simple and
+    // dependency-free we use a child `bash`+`/dev/tcp`-style probe is unavailable
+    // portably, so instead we do a promise-free spin with a hard cap via a
+    // separate helper that returns synchronously.
+    const reply = socks5Handshake(host, port, SOCKS5_METHOD_SELECTOR, 600);
+    if (reply === undefined)
+        return { open: false };
+    return { open: true, handshake: interpretSocks5Handshake(reply) };
+}
+/**
+ * Best-effort synchronous SOCKS5 handshake: open a TCP connection, write the
+ * greeting, and collect the reply bytes, blocking up to `timeoutMs`. Returns the
+ * reply bytes when the connection opened (possibly empty if the server sent
+ * nothing), or undefined when the connection could not be opened at all (port
+ * closed / refused). Implemented with a nested event loop drained via a shared
+ * flag, so the caller stays a simple linear script.
+ */
+function socks5Handshake(host, port, greeting, timeoutMs) {
+    // node has no synchronous socket API; run a tiny worker via execFileSync on
+    // the same node binary so the probe is fully synchronous and portable. The
+    // worker connects, sends the greeting, reads up to 2 bytes, and prints them as
+    // JSON (or prints "null" when the connection was refused).
+    const script = `const net=require('net');` +
+        `const s=net.connect({host:${JSON.stringify(host)},port:${port}});` +
+        `let done=false;const bytes=[];` +
+        `const fin=(v)=>{if(done)return;done=true;try{s.destroy()}catch(e){}` +
+        `process.stdout.write(JSON.stringify(v));process.exit(0)};` +
+        `s.setTimeout(${timeoutMs});` +
+        `s.on('connect',()=>{s.write(Buffer.from(${JSON.stringify([...greeting])}))});` +
+        `s.on('data',(d)=>{for(const b of d)bytes.push(b);if(bytes.length>=2)fin(bytes)});` +
+        `s.on('timeout',()=>fin(bytes));` +
+        `s.on('error',()=>fin(null));` +
+        `s.on('close',()=>fin(bytes));`;
+    try {
+        const out = execFileSync(process.execPath, ['-e', script], {
+            encoding: 'utf8',
+            timeout: timeoutMs + 1500,
+        });
+        const parsed = JSON.parse(out);
+        return parsed === null ? undefined : parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Best-effort synchronous TCP reachability probe (open a connection, succeed or
+ * not) for the local-model endpoint. Reuses the socks5Handshake worker with an
+ * empty greeting: a non-undefined return means the connection opened.
+ */
+function probeTcp(host, port) {
+    return socks5Handshake(host, port, [], 500) !== undefined;
+}
+/**
+ * Best-effort SYNCHRONOUS HTTP GET of `http://<host:port>/v1/models` (the
+ * OpenAI-compatible model listing llama.cpp / vLLM / LM Studio serve). Runs a
+ * tiny worker on the same node binary (node has no sync HTTP), which fetches +
+ * prints the body, so init stays synchronous. Returns the PARSED JSON body, or
+ * undefined on any failure (unreachable / timeout / non-JSON) — init then falls
+ * back to manual entry. This is a DIRECT LAN fetch on the operator's host at
+ * init time (not inside the jail); it only ever touches the local-model
+ * endpoint, the same host:port that becomes the one `--allow-direct` hole.
+ */
+function fetchModelsListing(host, port) {
+    const timeoutMs = 3000;
+    const script = `const http=require('http');` +
+        `const req=http.get({host:${JSON.stringify(host)},port:${port},path:'/v1/models',timeout:${timeoutMs}},(res)=>{` +
+        `let b='';res.on('data',(c)=>{b+=c;if(b.length>1_000_000)req.destroy()});` +
+        `res.on('end',()=>{process.stdout.write(b);process.exit(0)})});` +
+        `req.on('timeout',()=>{req.destroy();process.exit(1)});` +
+        `req.on('error',()=>process.exit(1));`;
+    try {
+        const out = execFileSync(process.execPath, ['-e', script], {
+            encoding: 'utf8',
+            timeout: timeoutMs + 1500,
+            maxBuffer: 4 * 1024 * 1024,
+        });
+        return JSON.parse(out);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Observe LOCAL process names (best-effort) so init can offer WEAK hints (a
+ * running `tor` -> likely Tor). Returns the lowercased process names seen, or []
+ * on any failure. This is a LOCAL observation only; it never claims the exit
+ * provider.
+ */
+function observeRunningProcesses() {
+    const res = spawnSync('ps', ['-eo', 'comm='], { encoding: 'utf8' });
+    if (res.error || res.status !== 0 || !res.stdout)
+        return [];
+    return res.stdout
+        .split('\n')
+        .map((l) => l.trim().split('/').pop() ?? '')
+        .filter((n) => n !== '')
+        .map((n) => n.toLowerCase());
+}
+/**
+ * The weak process-hint text for the observed processes, if any maps (via the
+ * PURE processHint). Returns the FIRST matching hint (tor before wireproxy), or
+ * undefined. Never names the exit provider.
+ */
+function matchProcessHint(processes) {
+    for (const p of processes) {
+        const h = processHint(p);
+        if (h)
+            return h.hint;
+    }
+    return undefined;
+}
+/**
+ * Build a shipped Dockerfile into `tag` via `podman build`. Streams podman's
+ * output (inherited stdio) so the user sees the build. Returns true on success.
+ * The build CONTEXT is the Dockerfile's own directory (the shipped examples/
+ * dir or the package root), which is where its COPY sources live.
+ */
+function buildImage(dockerfile, tag) {
+    const context = dirname(dockerfile);
+    process.stdout.write(`  Building ${tag} from ${dockerfile} (podman build)...\n`);
+    const res = spawnSync('podman', ['build', '-t', tag, '-f', dockerfile, context], { stdio: 'inherit' });
+    if (res.error) {
+        process.stderr.write(`  anon-pi: failed to run podman: ${res.error.message}. Is podman installed?\n`);
+        return false;
+    }
+    return res.status === 0;
+}
+/** List machine names (readdir of machines/), or [] if the dir is absent. */
+function listMachineNames(env) {
+    const root = join(resolveAnonPiHome(env), 'machines');
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+}
+/**
+ * Read one line from stdin synchronously for a confirm/value prompt, writing the
+ * prompt to stderr first. Returns undefined on EOF/error. Only called on a TTY
+ * (the verbs enforce the non-TTY discipline before prompting), so a blocking
+ * byte-at-a-time read from fd 0 is fine: the user types a line and hits enter.
+ */
+function promptLine(prompt) {
+    process.stderr.write(prompt);
+    const byte = Buffer.alloc(1);
+    let line = '';
+    for (;;) {
+        let n;
+        try {
+            n = readSync(0, byte, 0, 1, null);
+        }
+        catch (e) {
+            // EAGAIN on a non-blocking TTY: retry; anything else ends the read.
+            if (e.code === 'EAGAIN')
+                continue;
+            break;
+        }
+        if (n === 0)
+            break; // EOF
+        const ch = byte.toString('utf8', 0, 1);
+        if (ch === '\n')
+            return line;
+        if (ch !== '\r')
+            line += ch;
+    }
+    return line === '' ? undefined : line;
+}
+/** The `machine` subcommand help. */
+const MACHINE_HELP = `anon-pi machine - manage machines (an image + a persistent host home)
+
+USAGE
+  anon-pi machine create <name> [--image <ref>]   create a machine, pin its image
+  anon-pi machine list                            list machines and their images
+  anon-pi machine set-image <name> <ref>          re-pin the image (WARNS; no reseed)
+  anon-pi machine rm <name> [--yes]               delete the machine + its home
+
+A machine is an image + a persistent host home (machines/<name>/{machine.json,home/}).
+The home is seeded on FIRST LAUNCH, not at create. \`set-image\` re-pins only and
+warns (the home was built for the old image); \`rm\` confirms on a TTY, skips with
+\`--yes\`, and aborts non-interactively without it.
+`;
+// --- impure helpers ---------------------------------------------------------
+/** Read + parse <anon-pi-home>/config.json (tolerant: absent/garbage => {}). */
+function readJsonConfig(env) {
+    const path = join(resolveAnonPiHome(env), 'config.json');
+    return parseConfigJson(readJsonFile(path));
+}
+/** Read + parse a machine's machine.json (tolerant: absent/garbage => {}). */
+function readMachineJson(env, name) {
+    return parseMachineJson(readJsonFile(machineJsonPath(env, name)));
+}
+/** Read + JSON.parse a file, returning undefined if absent or unparseable. */
+function readJsonFile(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True iff a machine home is FRESH (no seed marker): the seed will run. The
+ * marker lives under the mounted home at `.pi/agent/<SEED_MARKER>` (the host
+ * side of the container's /root/.pi/agent = CONTAINER_AGENT_DIR).
+ */
+function homeFresh(machineHome) {
+    const marker = join(machineHome, '.pi', 'agent', SEED_MARKER);
+    return !existsSync(marker);
+}
+/**
+ * Query netcage for its KEPT managed containers, surfacing each one's stamped
+ * anon-pi identity key so the pure run-vs-start decision can match it. Thin,
+ * best-effort I/O: on any failure (netcage missing the query, no containers, a
+ * parse error) it returns an EMPTY listing, so the decision falls back to a
+ * fresh `run` (safe: it never wrongly resumes, it just creates a new container).
+ */
+function queryKeptContainers() {
+    // Ask netcage for its managed containers as JSON, reading back the anon-pi
+    // key label. netcage is a podman drop-in, so `ps` accepts the same
+    // label-filter + Go-template/JSON format flags.
+    const res = spawnSync('netcage', [
+        'ps',
+        '-a',
+        '--filter',
+        'label=netcage.managed',
+        '--format',
+        '{{.ID}}\t{{.Labels}}',
+    ], { encoding: 'utf8' });
+    if (res.error || res.status !== 0 || !res.stdout)
+        return [];
+    const out = [];
+    for (const line of res.stdout.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        const tab = trimmed.indexOf('\t');
+        if (tab < 0)
+            continue;
+        const ref = trimmed.slice(0, tab).trim();
+        const labels = trimmed.slice(tab + 1);
+        const key = extractKeyLabel(labels);
+        if (ref !== '' && key !== undefined)
+            out.push({ key, ref });
+    }
+    return out;
+}
+/**
+ * Pull the anon-pi key out of a podman `{{.Labels}}` rendering (a
+ * comma-separated `k=v` list). The key is stamped as `anon-pi.key=<opaque>`;
+ * because keptContainerKey embeds newlines, the CLI base64-encodes it when
+ * stamping (withKeyLabel) and decodes it here, so a `\n` never breaks the label.
+ */
+function extractKeyLabel(labels) {
+    for (const pair of labels.split(',')) {
+        const eq = pair.indexOf('=');
+        if (eq < 0)
+            continue;
+        const k = pair.slice(0, eq).trim();
+        if (k !== ANON_PI_KEY_LABEL)
+            continue;
+        const v = pair.slice(eq + 1).trim();
+        try {
+            return Buffer.from(v, 'base64').toString('utf8');
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Insert the anon-pi identity label into a `netcage run` argv (right after
+ * `run`), so a kept container can be found on re-entry. The key is base64'd
+ * (keptContainerKey embeds newlines) to keep it a single safe label value. This
+ * is ADDITIVE and touches NO egress flag (the RunPlan owns --proxy/--allow-direct).
+ */
+function withKeyLabel(netcageArgs, key) {
+    const enc = Buffer.from(key, 'utf8').toString('base64');
+    const out = netcageArgs.slice();
+    // netcageArgs[0] is 'run'; splice the label right after it.
+    out.splice(1, 0, '--label', `${ANON_PI_KEY_LABEL}=${enc}`);
+    return out;
+}
+/** Spawn netcage with inherited stdio; propagate its exit code. */
+function spawnNetcage(netcageArgs) {
+    const res = spawnSync('netcage', netcageArgs, { stdio: 'inherit' });
+    if (res.error) {
+        process.stderr.write(`anon-pi: failed to run netcage: ${res.error.message}\n`);
+        return 1;
+    }
+    return res.status ?? 1;
+}
 function hasNetcage() {
     const which = spawnSync(process.platform === 'win32' ? 'where' : 'command', ['-v', 'netcage'], {
         stdio: 'ignore',
@@ -167,5 +1559,13 @@ function hasNetcage() {
     const probe = spawnSync('netcage', ['--help'], { stdio: 'ignore' });
     return !probe.error;
 }
+/** Print an AnonPiError's message verbatim (exit 1) or rethrow anything else. */
+function reportAnonPiError(e) {
+    if (e instanceof AnonPiError) {
+        process.stderr.write(e.message + '\n');
+        return 1;
+    }
+    throw e;
+}
 process.exit(main(process.argv));
 //# sourceMappingURL=cli.js.map