anon-pi 0.4.0 → 0.5.0

package/src/cli.ts

@@ -1,227 +1,1564 @@
 #!/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.
+// 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 {spawnSync} from 'node:child_process';
-import {isAbsolute, join, resolve} from 'node:path';
+import {readSync} from 'node:fs';
+import {spawnSync, execFileSync} from 'node:child_process';
+import {join, dirname} from 'node:path';
 import {
 	AnonPiError,
-	buildRunPlan,
-	envFromProcess,
 	HELP,
 	MODELS_FILE,
-	pickProviderForLlm,
-	resolveConfigSeed,
-	resolveSourceModelsPath,
-	stateAgentDir,
-	type PiModelsFile,
+	SEED_MARKER,
+	DEFAULT_MACHINE,
+	envFromProcess,
+	buildMenuChoiceList,
+	buildMenuEntries,
+	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,
+	parseVerifyExitIp,
+	processHint,
+	socks5hUrl,
+	hostPortKey,
+	shippedDockerfilePath,
+	shippedWebveilDockerfilePath,
+	type MenuEntry,
+	type SessionDirListing,
+	type ProxyFinding,
+	type SocksHandshake,
+	type InitImageChoice,
+	type AnonPiConfig,
+	type AnonPiEnv,
+	type KeptContainer,
+	type LaunchIntent,
+	type Machine,
+	type MachineConfig,
+	type MachineCommand,
+	type ParsedLaunch,
 } 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: string[]): number {
 	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));
+	// `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));
+	}
+
+	// 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));
+	}
+	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: ParsedLaunch;
+	try {
+		parsed = parseLaunchArgs(args);
+	} catch (e) {
+		return reportAnonPiError(e);
 	}
 
-	return runLaunch(args);
+	return runLaunch(parsed);
 }
 
-// --- anon-pi [WORKDIR] : launch pi jailed -----------------------------------
-function runLaunch(args: string[]): number {
-	// 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;
+// --- the launch path --------------------------------------------------------
+function runLaunch(parsed: ParsedLaunch): number {
+	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: string;
+	let llm: string | undefined;
+	let intent: LaunchIntent;
+	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.',
+			);
+		}
+
+		// 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: Machine = {name: machineName, home, image};
+
+		// The generated models.json for this machine (mounted read-only for the
+		// first-launch seed) when present. Keyed per machine, not per import.
+		const modelsSeed = join(machineDir(env, machineName), MODELS_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,
+		};
+	} 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;
 	}
-	if (positionals.length > 1) {
+
+	// Fail loud if netcage is not installed, before we mutate anything.
+	if (!hasNetcage()) {
 		process.stderr.write(
-			'anon-pi: too many arguments (expected at most one WORKDIR).\nRun `anon-pi --help`.\n',
+			'anon-pi: `netcage` not found on PATH. anon-pi is a launcher for netcage; install it first\n' +
+				'(https://github.com/wighawag/netcage). Linux only.\n',
 		);
-		return 2;
+		return 1;
 	}
 
-	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',
+	// 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: LaunchIntent,
+	plan: Extract<ReturnType<typeof resolveRunPlan>, {kind: 'launch'}>,
+): number {
+	// 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 {
+		// 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)),
 		);
-		return 2;
 	}
 
+	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: LaunchIntent, machine: Machine): number {
 	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 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: SessionDirListing = {};
+	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: 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 = buildRunPlan(env, positionals[0], existsSync, existsSync);
+		plan = resolveRunPlan(launchIntent, homeFresh);
 	} catch (e) {
-		if (e instanceof AnonPiError) {
-			process.stderr.write(e.message + '\n');
-			return 1;
+		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;
+	}
+	return executeLaunchPlan(launchIntent, plan);
+}
+
+/**
+ * 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(): string | undefined {
+	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: string): string[] {
+	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: readonly MenuEntry[],
+	opts: {header?: string} = {},
+): MenuEntry | undefined {
+	if (entries.length === 0) return undefined;
+	const out = process.stdout;
+	const stdin = process.stdin;
+	let active = 0;
+
+	const render = (first: boolean): void => {
+		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');
 		}
-		throw e;
+	};
+
+	const wasRaw = stdin.isRaw ?? false;
+	const restore = (): void => {
+		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);
 
-	// Fail loud if netcage is not installed, before we mutate anything.
-	if (!hasNetcage()) {
+	const buf = Buffer.alloc(3);
+	for (;;) {
+		let n: number;
+		try {
+			n = readSync(0, buf, 0, 3, null);
+		} catch (e) {
+			if ((e as NodeJS.ErrnoException).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: string[]): number {
+	if (machineArgs.includes('--help') || machineArgs.includes('-h')) {
+		process.stdout.write(MACHINE_HELP);
+		return 0;
+	}
+
+	const env = envFromProcess(process.env);
+	let cmd: MachineCommand;
+	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: AnonPiEnv,
+	name: string,
+	image: string | undefined,
+): number {
+	const dir = machineDir(env, name);
+	if (existsSync(dir)) {
 		process.stderr.write(
-			'anon-pi: `netcage` not found on PATH. anon-pi is a launcher for netcage; install it first\n' +
-				'(https://github.com/wighawag/netcage). Linux only.\n',
+			`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;
 	}
 
-	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',
-		);
-	} else {
-		// Persistent mode: create the per-workdir state home to mount.
-		mkdirSync(plan.stateDir, {recursive: true});
-		if (plan.fresh) {
+	// 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: new session home ${plan.stateDir} (seeding on first launch)\n`,
+				'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;
 		}
 	}
 
-	// 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) {
+	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: AnonPiEnv): number {
+	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: AnonPiEnv, name: string, image: string): number {
+	const dir = machineDir(env, name);
+	if (!existsSync(dir)) {
 		process.stderr.write(
-			`anon-pi: failed to run netcage: ${res.error.message}\n`,
+			`anon-pi: no machine ${JSON.stringify(name)} (${dir}). ` +
+				'Create it first with `anon-pi machine create`.\n',
 		);
 		return 1;
 	}
-	// Propagate netcage's exit code (which itself propagates the tool's).
-	return res.status ?? 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;
 }
 
-// --- anon-pi import : write the seed models.json ----------------------------
-function runImport(args: string[]): number {
-	const force = args.includes('--force') || args.includes('-f');
-	const stray = args.filter(
-		(a) => a.startsWith('-') && a !== '--force' && a !== '-f',
+/**
+ * `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: AnonPiEnv, name: string, yes: boolean): number {
+	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;
+	}
+
+	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`,
 	);
-	if (stray.length > 0) {
+	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: string[],
+	verb: string,
+): {name?: string; yes: boolean} | number {
+	let name: string | undefined;
+	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: string, yes: boolean): boolean {
+	if (yes) return true;
+	if (!process.stdin.isTTY) {
 		process.stderr.write(
-			`anon-pi import: unknown option(s): ${stray.join(' ')}\nRun \`anon-pi --help\`.\n`,
+			`anon-pi: refusing to delete ${what} without a TTY to confirm. ` +
+				'Re-run with `--yes` to delete it non-interactively.\n',
 		);
-		return 2;
+		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: string[]): number {
+	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;
 
-	if (!env.llmDirect || env.llmDirect.trim() === '') {
+	let plan;
+	try {
+		plan = resolveDeleteHome(env, machine);
+	} catch (e) {
+		return reportAnonPiError(e);
+	}
+
+	if (!existsSync(plan.home)) {
 		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',
+			`anon-pi: no home for machine ${JSON.stringify(plan.machine)} (${plan.home}); nothing to delete.\n`,
 		);
 		return 1;
 	}
 
-	const source = resolveSourceModelsPath(env);
-	if (!existsSync(source)) {
+	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: string[]): number {
+	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 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',
+			'anon-pi: --delete-project needs a <project>. Run `anon-pi --help`.\n',
 		);
 		return 1;
 	}
 
-	let hostModels: PiModelsFile;
+	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 {
-		hostModels = JSON.parse(readFileSync(source, 'utf8')) as PiModelsFile;
+		plan = resolveDeleteProject({
+			env,
+			project: parsed.name,
+			projectsRoot,
+			machines,
+		});
 	} catch (e) {
+		return reportAnonPiError(e);
+	}
+
+	// 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 import: could not parse ${source}: ${(e as Error).message}\n`,
+			`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;
 	}
 
-	let result;
-	try {
-		result = pickProviderForLlm(hostModels, env.llmDirect);
-	} catch (e) {
-		if (e instanceof AnonPiError) {
-			process.stderr.write(e.message + '\n');
-			return 1;
-		}
-		throw e;
+	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;
 	}
 
-	const seedDir = resolveConfigSeed(env);
-	const dest = join(seedDir, MODELS_FILE);
-	if (existsSync(dest) && !force) {
+	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 reachability, generates models.json.
+  3. IMAGE: pick a shipped Dockerfile (built via podman), an existing ref, or skip.
+  Then writes ~/.anon-pi/config.json + the \`default\` machine. Never destroys homes.
+`;
+
+function runInit(args: string[]): number {
+	if (args.includes('--help') || args.includes('-h')) {
+		process.stdout.write(INIT_HELP);
+		return 0;
+	}
+	if (args.length > 0) {
 		process.stderr.write(
-			`anon-pi import: ${dest} already exists. Re-run with --force to overwrite.\n`,
+			`anon-pi: init takes no arguments, got: ${args.join(' ')}. Run \`anon-pi init --help\`.\n`,
 		);
 		return 1;
 	}
 
-	if (result.apiKeyLooksReal) {
+	if (!process.stdin.isTTY) {
 		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`,
+			'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: capture + probe + generate models.json.
+	const llm = initLlmStep(current.llm);
+	// llm may be undefined if the user skipped it (the launch path still errors
+	// without one, but init lets you set it later; we do not force it here).
+
+	// 3) DEFAULT MACHINE IMAGE: menu (shipped Dockerfiles / existing ref / skip).
+	const image = initImageStep();
+	if (image === ABORT) return 1;
+
+	// 4) 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: AnonPiConfig = {
+		proxy: proxyUrl,
+		llm: llm ?? current.llm,
+		defaultMachine: current.defaultMachine ?? DEFAULT_MACHINE,
+		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 seed for the default machine, generated from the
+	// captured endpoint (this is the `import` replacement). Only when we have an
+	// endpoint; written next to the machine so the first-launch seed mounts it.
+	if ((llm ?? current.llm) !== undefined) {
+		const mdir = machineDir(env, DEFAULT_MACHINE);
+		mkdirSync(mdir, {recursive: true});
+		const models = generateModelsJson((llm ?? current.llm) as string);
+		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}".\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: string | undefined): string | undefined {
+	process.stdout.write(
+		'Step 1/3 - 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: ProxyFinding[] = 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: string | undefined;
+		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 (evidence, not a gate), and return the endpoint (undefined if the
+ * user skips it). models.json is generated from it by runInit. The one direct
+ * hole; all other egress stays proxied.
+ */
+function initLlmStep(currentLlm: string | undefined): string | undefined {
+	process.stdout.write(
+		'\nStep 2/3 - 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}: `,
+	);
+	if (ans === undefined) return currentLlm;
+	const trimmed = ans.trim();
+	if (trimmed === '') return currentLlm;
+	const endpoint = trimmed;
+
+	// 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;
+	if (Number.isFinite(port)) {
+		const reachable = probeTcp(host, port);
+		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`,
+		);
+	}
+	return endpoint;
+}
+
+/**
+ * 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(): string | undefined | typeof ABORT {
+	process.stdout.write(
+		'\nStep 3/3 - 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: InitImageChoice = 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;
+	}
+}
+
+/**
+ * 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: AnonPiEnv,
+	image: string | undefined,
+): void {
+	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: string,
+	port: number,
+): {open: boolean; handshake?: SocksHandshake} {
+	// 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: string,
+	port: number,
+	greeting: readonly number[],
+	timeoutMs: number,
+): number[] | undefined {
+	// 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) as number[] | null;
+		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: string, port: number): boolean {
+	return socks5Handshake(host, port, [], 500) !== 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(): string[] {
+	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: readonly string[]): string | undefined {
+	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: string, tag: string): boolean {
+	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: AnonPiEnv): string[] {
+	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: string): string | undefined {
+	process.stderr.write(prompt);
+	const byte = Buffer.alloc(1);
+	let line = '';
+	for (;;) {
+		let n: number;
+		try {
+			n = readSync(0, byte, 0, 1, null);
+		} catch (e) {
+			// EAGAIN on a non-blocking TTY: retry; anything else ends the read.
+			if ((e as NodeJS.ErrnoException).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: AnonPiEnv): AnonPiConfig {
+	const path = join(resolveAnonPiHome(env), 'config.json');
+	return parseConfigJson(readJsonFile(path));
+}
+
+/** Read + parse a machine's machine.json (tolerant: absent/garbage => {}). */
+function readMachineJson(env: AnonPiEnv, name: string): MachineConfig {
+	return parseMachineJson(readJsonFile(machineJsonPath(env, name)));
+}
+
+/** Read + JSON.parse a file, returning undefined if absent or unparseable. */
+function readJsonFile(path: string): unknown {
+	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: string): boolean {
+	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(): KeptContainer[] {
+	// 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: KeptContainer[] = [];
+	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: string): string | undefined {
+	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: string[], key: string): string[] {
+	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: string[]): number {
+	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(): boolean {
 	const which = spawnSync(
 		process.platform === 'win32' ? 'where' : 'command',
@@ -237,4 +1574,13 @@ function hasNetcage(): boolean {
 	return !probe.error;
 }
 
+/** Print an AnonPiError's message verbatim (exit 1) or rethrow anything else. */
+function reportAnonPiError(e: unknown): number {
+	if (e instanceof AnonPiError) {
+		process.stderr.write(e.message + '\n');
+		return 1;
+	}
+	throw e;
+}
+
 process.exit(main(process.argv));