anon-pi 0.5.0 → 0.7.0

package/src/cli.ts

@@ -21,21 +21,31 @@ import {
 } from 'node:fs';
 import {readSync} from 'node:fs';
 import {spawnSync, execFileSync} from 'node:child_process';
-import {join, dirname} from 'node:path';
+import {join, dirname, resolve} from 'node:path';
 import {
 	AnonPiError,
 	HELP,
 	MODELS_FILE,
+	SETTINGS_FILE,
+	SETTINGS_SEED_FILE,
 	SEED_MARKER,
 	DEFAULT_MACHINE,
 	envFromProcess,
 	buildMenuChoiceList,
 	buildMenuEntries,
+	builtinProjectsRoot,
 	deriveProjectUsage,
+	globalModelsSeedPath,
+	globalSettingsSeedPath,
+	machineAgentDir,
 	machineDir,
 	machineHomeDir,
 	machineJsonPath,
+	machineModelsSeedPath,
 	machineSessionsDir,
+	mergeModelSelection,
+	resolveModelsSeedPath,
+	resolveSettingsSeedPath,
 	validateName,
 	resolveDeleteHome,
 	resolveDeleteProject,
@@ -60,6 +70,12 @@ import {
 	interpretSocks5Handshake,
 	initImageMenu,
 	generateModelsJson,
+	generateModelSelection,
+	pickLocalProviderModels,
+	parseModelsListing,
+	mergeModelSources,
+	resolveHostModelsPath,
+	LOCAL_PROVIDER_API_KEY,
 	parseVerifyExitIp,
 	processHint,
 	socks5hUrl,
@@ -73,12 +89,16 @@ import {
 	type InitImageChoice,
 	type AnonPiConfig,
 	type AnonPiEnv,
+	type GeneratedModel,
+	type ModelCandidate,
+	type ModelSelection,
 	type KeptContainer,
 	type LaunchIntent,
 	type Machine,
 	type MachineConfig,
 	type MachineCommand,
 	type ParsedLaunch,
+	type PiModelsFile,
 } from './anon-pi.js';
 
 // The netcage label anon-pi stamps its launch-identity key onto (keptContainerKey)
@@ -136,9 +156,57 @@ function main(argv: string[]): number {
 		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(): boolean {
+	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(): number {
+	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: string | undefined): boolean {
+	return typeof v === 'string' && v.trim() !== '';
+}
+
 // --- the launch path --------------------------------------------------------
 function runLaunch(parsed: ParsedLaunch): number {
 	const env = envFromProcess(process.env);
@@ -185,9 +253,12 @@ function runLaunch(parsed: ParsedLaunch): number {
 		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);
+		// The local-model models.json + settings seed for this machine's FRESH-home
+		// promotion. GLOBAL by default (<home>/models.json, shared across every
+		// machine because the `llm` endpoint is global), with an optional
+		// per-machine override (machines/<M>/models.json). Mounted read-only.
+		const modelsSeed = resolveModelsSeedPath(env, machineName, existsSync);
+		const settingsSeed = resolveSettingsSeedPath(env, machineName, existsSync);
 
 		intent = {
 			machine,
@@ -199,7 +270,8 @@ function runLaunch(parsed: ParsedLaunch): number {
 			keep: parsed.keep,
 			proxy,
 			llmDirect: llm,
-			modelsSeed: existsSync(modelsSeed) ? modelsSeed : undefined,
+			modelsSeed,
+			settingsSeed,
 		};
 	} catch (e) {
 		return reportAnonPiError(e);
@@ -900,9 +972,23 @@ 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.
+  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: string[]): number {
@@ -910,9 +996,12 @@ function runInit(args: string[]): number {
 		process.stdout.write(INIT_HELP);
 		return 0;
 	}
-	if (args.length > 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, got: ${args.join(' ')}. Run \`anon-pi init --help\`.\n`,
+			`anon-pi: init takes no arguments (except ${FORCE_KEY_FLAG}), got: ${extra.join(' ')}. Run \`anon-pi init --help\`.\n`,
 		);
 		return 1;
 	}
@@ -940,16 +1029,23 @@ function runInit(args: string[]): number {
 	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).
+	// 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) WRITE config.json + the `default` machine (never destroying an existing
+	// 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});
@@ -958,7 +1054,7 @@ function runInit(args: string[]): number {
 		proxy: proxyUrl,
 		llm: llm ?? current.llm,
 		defaultMachine: current.defaultMachine ?? DEFAULT_MACHINE,
-		projects: current.projects,
+		projects: projects ?? current.projects,
 	};
 	writeFileSync(configPath, serializeConfigJson(nextConfig));
 	process.stdout.write(`\nanon-pi: wrote ${configPath}.\n`);
@@ -967,20 +1063,75 @@ function runInit(args: string[]): number {
 	// 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',
+	// The GLOBAL local-model models.json + settings seed, generated from the
+	// captured endpoint + the CHOSEN models (this is the `import` replacement).
+	const endpoint = llm ?? current.llm;
+	if (endpoint !== undefined) {
+		const models = generateModelsJson(
+			endpoint,
+			llmResult.models,
+			llmResult.apiKey,
 		);
+		const modelsBody = JSON.stringify(models, null, '\t') + '\n';
+		// GLOBAL seed: the local model is a workspace-level thing (config.llm is
+		// global), so its models.json lives once at the workspace root and seeds
+		// EVERY machine's fresh home. A machine may still override with its own
+		// machines/<M>/models.json.
+		mkdirSync(resolveAnonPiHome(env), {recursive: true});
+		writeFileSync(globalModelsSeedPath(env), modelsBody);
+
+		// Migration: earlier versions wrote this seed under machines/default/. Now
+		// that it is global, remove the old default-machine copy so `default`
+		// picks up the global seed like every other machine (leaving it would look
+		// like a deliberate per-machine override and shadow the global one). Only
+		// the `default` machine's init-generated copy is migrated; a per-machine
+		// override you created for ANY OTHER machine is left untouched.
+		for (const stale of [
+			machineModelsSeedPath(env, DEFAULT_MACHINE),
+			join(machineDir(env, DEFAULT_MACHINE), SETTINGS_SEED_FILE),
+		]) {
+			if (existsSync(stale)) rmSync(stale, {force: true});
+		}
 		process.stdout.write(
-			`anon-pi: wrote the local-model models.json for machine "${DEFAULT_MACHINE}".\n`,
+			`anon-pi: wrote the global local-model models.json ` +
+				`(${llmResult.models.length} model${llmResult.models.length === 1 ? '' : 's'}; shared by all machines).\n`,
 		);
+
+		// settings.json seed: the default model + enabledModels for the imported
+		// set. The first-launch promotion merges it into each home's settings (so
+		// image-staged packages/extensions survive). Only when the user picked at
+		// least one model + a default.
+		const selection =
+			llmResult.defaultId !== undefined && llmResult.models.length > 0
+				? generateModelSelection(
+						llmResult.models.map((m) => m.id),
+						llmResult.defaultId,
+					)
+				: undefined;
+		if (selection) {
+			writeFileSync(
+				globalSettingsSeedPath(env),
+				JSON.stringify(selection, null, '\t') + '\n',
+			);
+			process.stdout.write(
+				`anon-pi: default model set to "${llmResult.defaultId}".\n`,
+			);
+		}
+
+		// Re-run reconfigure: the seed above only takes effect on a FRESH home
+		// (the first-launch promotion is marker-guarded). Apply the new
+		// models.json + settings selection DIRECTLY to EVERY already-seeded machine
+		// home now, so re-running `init` updates existing environments without
+		// wiping conversations (init runs on the host; homes are host dirs). Fresh
+		// (unseeded) homes are left to the launch-time seed. A machine with its OWN
+		// per-machine models.json override is skipped (its local model differs).
+		const updated = applyModelsToSeededHomes(env, modelsBody, selection);
+		if (updated.length > 0) {
+			process.stdout.write(
+				`anon-pi: updated ${updated.length} existing machine home${updated.length === 1 ? '' : 's'} ` +
+					`(${updated.join(', ')}); conversations untouched.\n`,
+			);
+		}
 	}
 
 	process.stdout.write(
@@ -990,6 +1141,42 @@ function runInit(args: string[]): number {
 	return 0;
 }
 
+/**
+ * Apply the freshly-generated GLOBAL local-model config to EVERY already-seeded
+ * machine home directly (init runs on the host; homes are host dirs). The
+ * launch-time seed only promotes on a FRESH home (marker-guarded), so without
+ * this a re-run of `init` would update the global seed but never reach existing
+ * homes. For each machine: skip a FRESH home (no marker — the launch seed will
+ * pick up the new global seed), skip a machine with its OWN per-machine
+ * models.json override (its local model differs on purpose), else overwrite the
+ * home's models.json and merge the settings selection. Conversations/sessions
+ * are untouched. Returns the machine names updated.
+ */
+function applyModelsToSeededHomes(
+	env: AnonPiEnv,
+	modelsBody: string,
+	selection: ModelSelection | undefined,
+): string[] {
+	const updated: string[] = [];
+	for (const machine of listMachineNames(env).sort()) {
+		const agentDir = machineAgentDir(env, machine);
+		// Only an already-seeded home (marker present).
+		if (!existsSync(join(agentDir, SEED_MARKER))) continue;
+		// A machine that deliberately overrides the global models.json keeps its
+		// own local model; do not clobber its home with the global one.
+		if (existsSync(machineModelsSeedPath(env, machine))) continue;
+
+		writeFileSync(join(agentDir, MODELS_FILE), modelsBody);
+		if (selection) {
+			const settingsPath = join(agentDir, SETTINGS_FILE);
+			const merged = mergeModelSelection(readJsonFile(settingsPath), selection);
+			writeFileSync(settingsPath, JSON.stringify(merged, null, '\t') + '\n');
+		}
+		updated.push(machine);
+	}
+	return updated;
+}
+
 /** A sentinel a step returns when the user aborted (distinct from "skipped"). */
 const ABORT = Symbol('abort');
 
@@ -1003,7 +1190,7 @@ const ABORT = Symbol('abort');
  */
 function initProxyStep(currentProxy: string | undefined): string | undefined {
 	process.stdout.write(
-		'Step 1/3 - proxy (the socks5h endpoint that anonymizes egress)\n',
+		'Step 1/4 - proxy (the socks5h endpoint that anonymizes egress)\n',
 	);
 	if (currentProxy) {
 		process.stdout.write(`  current: ${currentProxy}\n`);
@@ -1122,15 +1309,31 @@ function initProxyStep(currentProxy: string | undefined): string | undefined {
 	}
 }
 
+/** What initLlmStep resolves: the endpoint, the chosen model entries, the apiKey to seed, and the default id. */
+interface LlmStepResult {
+	endpoint: string | undefined;
+	models: GeneratedModel[];
+	apiKey: string;
+	defaultId: string | undefined;
+}
+
 /**
  * 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.
+ * 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(currentLlm: string | undefined): string | undefined {
+function initLlmStep(
+	env: AnonPiEnv,
+	currentLlm: string | undefined,
+	forceLocalApiKey: boolean,
+): LlmStepResult | typeof ABORT {
 	process.stdout.write(
-		'\nStep 2/3 - local model endpoint (the ONE direct hole)\n',
+		'\nStep 2/4 - local model endpoint (the ONE direct hole)\n',
 	);
 	if (currentLlm) process.stdout.write(`  current: ${currentLlm}\n`);
 	const prefill = currentLlm
@@ -1139,10 +1342,17 @@ function initLlmStep(currentLlm: string | undefined): string | undefined {
 	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;
+	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.
@@ -1150,15 +1360,152 @@ function initLlmStep(currentLlm: string | undefined): string | undefined {
 	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 as PiModelsFile) ?? {},
+		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: string[] = [];
 	if (Number.isFinite(port)) {
-		const reachable = probeTcp(host, port);
+		const listing = fetchModelsListing(host, port);
+		serverIds = parseModelsListing(listing);
+	}
+
+	if (hostModelEntries.length === 0 && serverIds.length === 0) {
 		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`,
+			'  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: readonly ModelCandidate[],
+): GeneratedModel[] | undefined {
+	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<number>();
+			const out: GeneratedModel[] = [];
+			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: readonly GeneratedModel[]): string {
+	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`);
 	}
-	return endpoint;
 }
 
 /**
@@ -1168,7 +1515,7 @@ function initLlmStep(currentLlm: string | undefined): string | undefined {
  */
 function initImageStep(): string | undefined | typeof ABORT {
 	process.stdout.write(
-		'\nStep 3/3 - default machine image (an image with `pi` on PATH)\n',
+		'\nStep 3/4 - default machine image (an image with `pi` on PATH)\n',
 	);
 	const menu = initImageMenu();
 	menu.forEach((e, i) => {
@@ -1220,6 +1567,44 @@ function initImageStep(): string | undefined | typeof ABORT {
 	}
 }
 
+/**
+ * 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: AnonPiEnv,
+	currentProjects: string | undefined,
+): string | undefined {
+	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
@@ -1334,6 +1719,37 @@ function probeTcp(host: string, port: number): boolean {
 	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: string, port: number): unknown {
+	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 []