anon-pi 0.2.0 → 0.4.0

package/src/anon-pi.ts

@@ -27,34 +27,69 @@ import {fileURLToPath} from 'node:url';
 export const CONTAINER_WORKDIR = '/work';
 
 /**
- * Where the seed (just models.json) is mounted read-only in the container. The
- * run command copies models.json FROM here INTO the container's own
- * ~/.pi/agent, so it LAYERS onto the image's config (extensions/skills the image
- * installed survive) instead of replacing it. This is why we mount+copy rather
- * than mount-as-agent-dir: mounting over ~/.pi/agent would shadow the image's
- * extensions.
+ * The container path pi uses as its config+state home. anon-pi mounts a
+ * PERSISTENT host dir here (Model B), so everything pi writes, sessions,
+ * history, settings (your model choice), `pi install`ed extensions, downloaded
+ * bin/fd, survives across launches. Statefulness is the default; --ephemeral
+ * mounts a throwaway dir here instead.
  */
-export const CONTAINER_SEED_DIR = '/anon-pi-seed';
+export const CONTAINER_AGENT_DIR = '/root/.pi/agent';
 
 /**
- * The container command: copy the seeded models.json into pi's own config dir
- * (creating it if absent), then exec pi. `$HOME/.pi/agent` is pi's default
- * config dir when PI_CODING_AGENT_DIR is unset, i.e. exactly where the image
- * installed pi + any extensions, so the copy augments rather than shadows.
+ * Where the image STAGES its first-launch defaults (extensions + trust.json).
+ * NOT the agent dir, so it never conflicts with the persistent mount. The
+ * entrypoint promotes these into the mounted agent dir only when the home is
+ * FRESH (Model C seed-if-fresh).
  */
-export const CONTAINER_RUN_CMD =
-	`mkdir -p "$HOME/.pi/agent" && ` +
-	`cp ${CONTAINER_SEED_DIR}/models.json "$HOME/.pi/agent/models.json" && ` +
-	`exec pi`;
+export const CONTAINER_STAGE_DIR = '/opt/anon-pi-seed/agent';
 
-/** The single file the seed carries: pi's model/provider registry. */
+/**
+ * Where anon-pi mounts the canonical models.json (from `import`) read-only, so
+ * the first-launch seed can copy it into the fresh home alongside the image's
+ * staged defaults. Read-only: the container never writes back to the host seed.
+ */
+export const CONTAINER_MODELS_SEED = '/anon-pi-seed/models.json';
+
+/** Marker file written into the agent dir after seeding; holds the seed version. */
+export const SEED_MARKER = '.anon-pi-seed';
+
+/** The single file the host-side seed carries: pi's model/provider registry. */
 export const MODELS_FILE = 'models.json';
 
+/**
+ * containerRunCmd builds the container command: on a FRESH home (no seed
+ * marker), promote the image's staged defaults + the mounted models.json into
+ * the persistent agent dir and stamp the marker; then exec pi. On a seeded home
+ * it does nothing but exec pi, so pi's persisted state (incl. anything you
+ * `pi install`ed or models pi added) is used as-is and NEVER clobbered.
+ *
+ * seedVersion is written into the marker so a future image can re-seed changed
+ * defaults on a version bump; v1 only seeds when the marker is absent.
+ */
+export function containerRunCmd(seedVersion: string): string {
+	const agent = CONTAINER_AGENT_DIR;
+	const marker = `${agent}/${SEED_MARKER}`;
+	return (
+		`mkdir -p "${agent}" && ` +
+		`if [ ! -f "${marker}" ]; then ` +
+		// image-staged defaults (extensions, trust.json), if the image provides them
+		`{ [ -d "${CONTAINER_STAGE_DIR}" ] && cp -a "${CONTAINER_STAGE_DIR}/." "${agent}/" || true; } && ` +
+		// the host-imported models.json, if mounted
+		`{ [ -f "${CONTAINER_MODELS_SEED}" ] && cp "${CONTAINER_MODELS_SEED}" "${agent}/${MODELS_FILE}" || true; } && ` +
+		`printf '%s\\n' "${seedVersion}" > "${marker}"; ` +
+		`fi && ` +
+		`exec pi`
+	);
+}
+
+/** The seed version anon-pi stamps when it seeds a fresh home (bump to re-seed). */
+export const SEED_VERSION = '1';
+
 /** Inputs resolved from the environment + argv, injected so this stays pure. */
 export interface AnonPiEnv {
 	/** $HOME (or an override) used to derive default paths. */
 	home: string;
-	/** socks5h proxy URL. Default socks5h://127.0.0.1:9050. */
+	/** socks5h proxy URL. REQUIRED (no default: the proxy is what anonymizes). */
 	proxy?: string;
 	/** The anon-pi home dir. Default $XDG_CONFIG_HOME/anon-pi or ~/.config/anon-pi. */
 	anonPiHome?: string;
@@ -73,24 +108,39 @@ export interface AnonPiEnv {
 	 * `Dockerfile.pi`.
 	 */
 	dockerfilePath?: string;
+	/**
+	 * Absolute path to the shipped examples/Dockerfile.pi-webveil (pi + pi-webveil
+	 * + SearXNG), used to make the missing-image error mention the fuller build.
+	 */
+	webveilDockerfilePath?: string;
 	/** `import` source models.json override (ANON_PI_SOURCE_MODELS). */
 	sourceModels?: string;
 	/** The host pi agent dir override (PI_CODING_AGENT_DIR), used to find models.json. */
 	piAgentDir?: string;
+	/** When true, use a throwaway state home (no persistence). Default false. */
+	ephemeral?: boolean;
+	/** The seed version anon-pi stamps into a fresh home. Default SEED_VERSION. */
+	seedVersion?: string;
 }
 
 /** The fully-resolved run plan cli.ts executes. */
 export interface RunPlan {
 	/** Absolute workdir on the host (mounted at /work). */
 	workdir: string;
-	/** The seed dir on the host (holds models.json), mounted read-only at /anon-pi-seed. */
+	/**
+	 * The PERSISTENT per-workdir state dir on the host, mounted at the container's
+	 * ~/.pi/agent. Everything pi writes here survives. For --ephemeral this is a
+	 * throwaway path cli.ts creates + discards.
+	 */
+	stateDir: string;
+	/** The canonical host models.json (from `import`) mounted read-only for the seed, or '' if absent. */
 	configSeed: string;
+	/** True when this workdir has no state yet (fresh home; the seed will run). */
+	fresh: boolean;
 	/** The argv passed to `netcage` (after the `netcage` program name). */
 	netcageArgs: string[];
 }
 
-const DEFAULT_PROXY = 'socks5h://127.0.0.1:9050';
-
 /** A user-facing error whose message is meant to be printed verbatim (no stack). */
 export class AnonPiError extends Error {}
 
@@ -104,12 +154,35 @@ export function resolveAnonPiHome(env: AnonPiEnv): string {
 	return join(base, 'anon-pi');
 }
 
-/** The seed dir (holds models.json), mounted read-only into the container. */
+/**
+ * The CANONICAL host seed dir holding models.json (written by `anon-pi import`).
+ * Mounted read-only so the first-launch seed can copy models.json into a fresh
+ * persistent home. Workdir-independent (import does not need a workdir).
+ */
 export function resolveConfigSeed(env: AnonPiEnv): string {
 	if (env.configSeed) return resolve(env.configSeed);
 	return join(resolveAnonPiHome(env), 'agent');
 }
 
+/**
+ * Encode an absolute path into a directory name using pi's OWN convention (see
+ * pi coding-agent session-manager: `--${cwd without leading slash, / \ : -> -}--`),
+ * so an anon-pi state dir is readable and matches pi's mental model (no opaque
+ * hash). e.g. /home/u/dev/x -> --home-u-dev-x--
+ */
+export function pathSlug(absPath: string): string {
+	return `--${absPath.replace(/^[/\\]/, '').replace(/[/\\:]/g, '-')}--`;
+}
+
+/**
+ * The persistent per-workdir state dir on the host (mounted at the container's
+ * ~/.pi/agent). Keyed by the workdir via pi's path-slug convention:
+ *   <anonPiHome>/state/<slug>/agent
+ */
+export function stateAgentDir(env: AnonPiEnv, absWorkdir: string): string {
+	return join(resolveAnonPiHome(env), 'state', pathSlug(absWorkdir), 'agent');
+}
+
 /**
  * Normalise a proxy-less host:port key from an ANON_PI_LLM value or a provider
  * baseUrl, so `192.168.1.150:8080` matches `http://192.168.1.150:8080/v1`.
@@ -220,18 +293,29 @@ export function resolveSourceModelsPath(env: AnonPiEnv): string {
 /**
  * Build the run plan from the environment + the (optional) workdir arg. PURE: it
  * resolves paths and composes the netcage argv, performing NO filesystem writes
- * or spawns. It THROWS AnonPiError for the hard preconditions (missing image,
- * missing llm, missing seed models.json) so the required inputs fail loud.
+ * or spawns. It THROWS AnonPiError for the required inputs (image, llm, proxy).
+ *
+ * Statefulness (Model B): a persistent per-workdir host dir is mounted at the
+ * container's ~/.pi/agent, so pi's sessions/history/settings/extensions persist.
+ * First-launch seed (Model C): when that home is FRESH, the container run
+ * command promotes the image's staged defaults + the imported models.json into
+ * it and stamps a marker; thereafter pi OWNS the home and nothing is clobbered.
  *
- * The seed (models.json) is mounted READ-ONLY at /anon-pi-seed and copied into
- * the container's own ~/.pi/agent by the run command, so it LAYERS onto the
- * image's config (image-installed extensions/skills survive) rather than
- * shadowing it.
+ * `modelsSeedExists` reports whether the canonical import models.json exists (so
+ * it is mounted for the seed); `stateExists` reports whether this workdir's
+ * state home already exists (so `fresh` is known).
+ *
+ * --ephemeral mounts NO writable state: pi writes to the container's own
+ * filesystem, which netcage runs with `--rm`, so it is destroyed when the
+ * container exits. Nothing writable ever touches a host path; there is no
+ * cleanup and no leftover-on-crash. (The read-only models.json seed is still
+ * mounted; it is a single file anon-pi never writes to.)
  */
 export function buildRunPlan(
 	env: AnonPiEnv,
 	workdirArg: string | undefined,
-	seedModelsExists: (modelsJsonPath: string) => boolean,
+	modelsSeedExists: (modelsJsonPath: string) => boolean,
+	stateExists: (stateDir: string) => boolean,
 ): RunPlan {
 	if (!env.image || env.image.trim() === '') {
 		// dockerfilePath is injected (cli.ts resolves the shipped Dockerfile.pi via
@@ -240,6 +324,7 @@ export function buildRunPlan(
 		// leading spaces into the Dockerfile and break the EOF terminator, so we
 		// point at the shipped file instead of printing a heredoc.
 		const df = env.dockerfilePath ?? 'Dockerfile.pi';
+		const wv = env.webveilDockerfilePath ?? 'examples/Dockerfile.pi-webveil';
 		throw new AnonPiError(
 			'anon-pi: set ANON_PI_IMAGE to a container image that has `pi` on its PATH.\n' +
 				'\n' +
@@ -249,6 +334,12 @@ export function buildRunPlan(
 				`podman build -t localhost/anon-pi-pi:latest -f "${df}" "$(dirname "${df}")"\n` +
 				'export ANON_PI_IMAGE=localhost/anon-pi-pi:latest\n' +
 				'\n' +
+				'Or the fuller example with the pi-webveil extension + a local SearXNG\n' +
+				'(anonymized web search):\n' +
+				'\n' +
+				`podman build -t localhost/anon-pi-webveil:latest -f "${wv}" "$(dirname "${wv}")"\n` +
+				'export ANON_PI_IMAGE=localhost/anon-pi-webveil:latest\n' +
+				'\n' +
 				'See the README (Providing a pi image) for details and a community-image note.',
 		);
 	}
@@ -257,6 +348,30 @@ export function buildRunPlan(
 			'anon-pi: set ANON_PI_LLM to the RFC1918/link-local IP[:port] of the local model pi should reach directly (e.g. ANON_PI_LLM=192.168.1.150:8080). All other egress stays forced through the proxy.',
 		);
 	}
+	if (!env.proxy || env.proxy.trim() === '') {
+		// No default: this is an anonymity tool, so the proxy is REQUIRED and never
+		// guessed (mirrors netcage, which fails closed without --proxy). A silent
+		// default would anonymize through the wrong endpoint, or fail deep in the
+		// jail with a confusing DNS error, if the guessed proxy is not actually up.
+		throw new AnonPiError(
+			'anon-pi: set ANON_PI_PROXY to your socks5h proxy. anon-pi has no default:\n' +
+				'the proxy is what makes the session anonymous, so it is never guessed.\n' +
+				'\n' +
+				'Pick the one you run (copy-paste), then re-run anon-pi:\n' +
+				'\n' +
+				'# Tor (system tor / Tor Browser bundle default port)\n' +
+				'export ANON_PI_PROXY=socks5h://127.0.0.1:9050\n' +
+				'\n' +
+				'# wireproxy -> a WireGuard VPN (Mullvad, Proton, ...); use YOUR configured\n' +
+				'# [Socks5] BindAddress port (1080 in wireproxy examples):\n' +
+				'export ANON_PI_PROXY=socks5h://127.0.0.1:1080\n' +
+				'\n' +
+				'# an SSH dynamic-forward (ssh -D 1080 host) or any other socks5h endpoint\n' +
+				'export ANON_PI_PROXY=socks5h://127.0.0.1:1080\n' +
+				'\n' +
+				'Only socks5h:// is accepted (plain socks5:// resolves DNS locally and leaks).',
+		);
+	}
 
 	const home = env.home;
 	if (!home || home.trim() === '') {
@@ -267,48 +382,54 @@ export function buildRunPlan(
 		workdirArg && workdirArg.trim() !== '' ? workdirArg : process.cwd();
 	const workdir = isAbsolute(raw) ? raw : resolve(raw);
 
-	const configSeed = resolveConfigSeed(env);
-	const modelsJson = join(configSeed, MODELS_FILE);
-	if (!seedModelsExists(modelsJson)) {
-		throw new AnonPiError(
-			`anon-pi: no seed models.json at ${modelsJson}.\n` +
-				'\n' +
-				'anon-pi never populates it for you. Generate it from your local model:\n' +
-				'\n' +
-				'anon-pi import\n' +
-				'\n' +
-				'`import` reads your host ~/.pi/agent/models.json, picks the provider that\n' +
-				'serves ANON_PI_LLM, and writes just that provider here (no auth for other\n' +
-				'providers, no sessions, no identity). See the README (Populating the seed).',
-		);
-	}
+	// Persistent per-workdir state home, unless --ephemeral (no writable mount).
+	const ephemeral = env.ephemeral === true;
+	const stateDir = ephemeral ? '' : stateAgentDir(env, workdir);
+	// Ephemeral home is always fresh (the container's throwaway layer); a
+	// persistent home is fresh iff its dir is absent.
+	const fresh = ephemeral ? true : !stateExists(stateDir);
 
-	const proxy =
-		env.proxy && env.proxy.trim() !== '' ? env.proxy : DEFAULT_PROXY;
+	// The canonical imported models.json is mounted (read-only) for the seed only
+	// when it exists; pi can also start with no models and you add them in-session.
+	const modelsSeed = join(resolveConfigSeed(env), MODELS_FILE);
+	const haveModelsSeed = modelsSeedExists(modelsSeed);
+
+	const proxy = env.proxy.trim();
+
+	// netcage's --allow-direct wants a bare IP[:port]/CIDR (no scheme/path), but a
+	// user naturally sets ANON_PI_LLM to a URL (http://192.168.1.150:8080). Strip
+	// it to host:port with the same helper `import` uses to match providers, so a
+	// URL, an ip:port, or a bare ip all work.
+	const directTarget = hostPortKey(env.llmDirect);
+	const seedVersion = env.seedVersion ?? SEED_VERSION;
 
 	const netcageArgs = [
 		'run',
 		'--proxy',
 		proxy,
 		'--allow-direct',
-		env.llmDirect,
+		directTarget,
 		'-it',
 		'-v',
 		workdir, // netcage defaults a target-less -v to /work and cwd to /work
-		'-v',
-		// Mount the seed READ-ONLY at a neutral path; the run command copies
-		// models.json into the container's own ~/.pi/agent so image extensions
-		// survive (see CONTAINER_RUN_CMD).
-		`${configSeed}:${CONTAINER_SEED_DIR}:ro`,
-		env.image,
-		'sh',
-		'-c',
-		CONTAINER_RUN_CMD,
 	];
+	// Persistent mode ONLY: mount the per-workdir state home at ~/.pi/agent
+	// (Model B). --ephemeral mounts nothing writable: pi writes to the container's
+	// own --rm layer, gone on exit, no host state.
+	if (!ephemeral) {
+		netcageArgs.push('-v', `${stateDir}:${CONTAINER_AGENT_DIR}`);
+	}
+	// Mount the imported models.json read-only for the first-launch seed, if any.
+	if (haveModelsSeed) {
+		netcageArgs.push('-v', `${modelsSeed}:${CONTAINER_MODELS_SEED}:ro`);
+	}
+	netcageArgs.push(env.image, 'sh', '-c', containerRunCmd(seedVersion));
 
 	return {
 		workdir,
-		configSeed,
+		stateDir,
+		configSeed: haveModelsSeed ? modelsSeed : '',
+		fresh,
 		netcageArgs,
 	};
 }
@@ -320,13 +441,26 @@ export function buildRunPlan(
  * build command concrete.
  */
 export function shippedDockerfilePath(): string | undefined {
+	return shippedFile('Dockerfile.pi');
+}
+
+/**
+ * Absolute path to the fuller pi-webveil + SearXNG example that ships with
+ * anon-pi (examples/Dockerfile.pi-webveil), or undefined if not found.
+ */
+export function shippedWebveilDockerfilePath(): string | undefined {
+	return shippedFile(join('examples', 'Dockerfile.pi-webveil'));
+}
+
+/**
+ * Resolve a file shipped in the package root, from this module's location
+ * (package root is one level up from dist/anon-pi.js). Returns undefined if it
+ * cannot be found or import.meta.url is unavailable.
+ */
+function shippedFile(rel: string): string | undefined {
 	try {
 		const here = dirname(fileURLToPath(import.meta.url));
-		// dist/anon-pi.js -> ../Dockerfile.pi; also try alongside for safety.
-		for (const p of [
-			join(here, '..', 'Dockerfile.pi'),
-			join(here, 'Dockerfile.pi'),
-		]) {
+		for (const p of [join(here, '..', rel), join(here, rel)]) {
 			if (existsSync(p)) return p;
 		}
 	} catch {
@@ -348,17 +482,26 @@ export function envFromProcess(
 		llmDirect: penv.ANON_PI_LLM,
 		xdgConfigHome: penv.XDG_CONFIG_HOME,
 		dockerfilePath: shippedDockerfilePath(),
+		webveilDockerfilePath: shippedWebveilDockerfilePath(),
 		sourceModels: penv.ANON_PI_SOURCE_MODELS,
 		piAgentDir: penv.PI_CODING_AGENT_DIR,
+		ephemeral: isTruthy(penv.ANON_PI_EPHEMERAL),
 	};
 }
 
+/** Whether an env-var string is set to a truthy value (1/true/yes, any case). */
+function isTruthy(v: string | undefined): boolean {
+	if (!v) return false;
+	const s = v.trim().toLowerCase();
+	return s === '1' || s === 'true' || s === 'yes' || s === 'on';
+}
+
 /** The --help text (kept here so it is covered by the same module). */
 export const HELP = `anon-pi - launch pi inside a netcage (anonymized egress + one direct local model)
 
 USAGE
   anon-pi [WORKDIR]     launch pi jailed, working in WORKDIR (default: cwd)
-  anon-pi import        write the seed models.json from your local model
+  anon-pi import        seed models.json from your local model
 
   WORKDIR   the host folder pi works in (mounted at ${CONTAINER_WORKDIR}; pi's cwd). Files pi
             writes there land on the host.
@@ -366,28 +509,45 @@ USAGE
 WHAT IT DOES
   Runs pi inside netcage with all web/DNS egress forced through the socks5h
   proxy (fail-closed) and ONE direct hole to your local model (ANON_PI_LLM).
-  The seed models.json is mounted read-only and COPIED into the container's own
-  ~/.pi/agent at start, so it layers onto the image's config: extensions and
-  skills you baked into the image survive. Requires \`netcage\`.
+
+  STATEFUL by default: a persistent per-workdir home
+  (<ANON_PI_HOME>/state/<workdir>/agent) is mounted at the container's
+  ~/.pi/agent, so your conversations, history, settings (model choice), and any
+  extensions you \`pi install\` persist across launches. Re-running in the same
+  folder resumes it. On a FRESH home, the image's staged defaults (extensions,
+  trust) and your imported models.json are seeded in once; after that pi owns the
+  home and nothing is overwritten. Requires \`netcage\`.
+
+  --ephemeral (or ANON_PI_EPHEMERAL=1): mount NO writable state; pi writes to the
+  container's own --rm layer, gone on exit. Nothing writable touches the host,
+  no cleanup, no leftover-on-crash.
+
+  --fresh: delete this workdir's persistent state home first, so the (possibly
+  rebuilt) image's defaults + your imported models.json are re-seeded. Use it
+  after rebuilding your image to pick up new extensions/config.
 
 import
   Reads your host ~/.pi/agent/models.json, picks the provider whose baseUrl
-  serves ANON_PI_LLM, and writes JUST that provider to the seed
+  serves ANON_PI_LLM, and writes JUST that provider to the canonical seed
   (<ANON_PI_CONFIG>/models.json). No other provider's API keys, no sessions, no
-  identity. Re-run with --force to overwrite an existing seed.
+  identity. It SEEDS a fresh home; models you later add inside pi persist and are
+  never clobbered. Re-run with --force to overwrite the canonical seed.
 
 ENVIRONMENT
   ANON_PI_IMAGE   (required for run) image with \`pi\` on PATH. No image yet?
                   Running anon-pi without it prints a ready-to-build
                   Dockerfile.pi recipe; see the README (Providing a pi image).
   ANON_PI_LLM     (required) RFC1918/link-local IP[:port] of the local model
-  ANON_PI_PROXY   socks5h URL (default ${DEFAULT_PROXY})
+  ANON_PI_PROXY   (required) socks5h URL of your proxy (Tor/wireproxy/ssh -D).
+                  No default: the proxy is what anonymizes, so it is never guessed.
+  ANON_PI_EPHEMERAL  set to 1 for a throwaway (non-persistent) session
   ANON_PI_HOME    anon-pi home (default $XDG_CONFIG_HOME/anon-pi or ~/.config/anon-pi)
-  ANON_PI_CONFIG  seed dir holding models.json (default <ANON_PI_HOME>/agent)
+  ANON_PI_CONFIG  canonical seed dir holding models.json (default <ANON_PI_HOME>/agent)
   ANON_PI_SOURCE_MODELS  (import) host models.json to read (default ~/.pi/agent/models.json)
 
-RESEED
-  anon-pi import --force  regenerates the seed models.json.
+RESET A SESSION
+  anon-pi --fresh [WORKDIR]   drop the session home and re-seed on this launch.
+  Or delete it by hand: rm -rf <ANON_PI_HOME>/state/<workdir-slug>/agent
 
 PLATFORM
   Linux only (via netcage's netns/nft jail). On macOS/Windows it works only

package/src/cli.ts

@@ -8,9 +8,15 @@
 //   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, writeFileSync} from 'node:fs';
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from 'node:fs';
 import {spawnSync} from 'node:child_process';
-import {join} from 'node:path';
+import {isAbsolute, join, resolve} from 'node:path';
 import {
 	AnonPiError,
 	buildRunPlan,
@@ -20,6 +26,7 @@ import {
 	pickProviderForLlm,
 	resolveConfigSeed,
 	resolveSourceModelsPath,
+	stateAgentDir,
 	type PiModelsFile,
 } from './anon-pi.js';
 
@@ -41,11 +48,14 @@ function main(argv: string[]): number {
 
 // --- anon-pi [WORKDIR] : launch pi jailed -----------------------------------
 function runLaunch(args: string[]): number {
-	// The only positional is the optional workdir. Reject stray flags so a typo
-	// (e.g. --allow-direct) is not silently swallowed: anon-pi owns the netcage
-	// argv, extra flags are not passed through.
+	// 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('-'));
+	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`,
@@ -59,11 +69,35 @@ function runLaunch(args: string[]): number {
 		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;
+	}
+
 	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`);
+		}
+	}
 
 	let plan;
 	try {
-		plan = buildRunPlan(env, positionals[0], existsSync);
+		plan = buildRunPlan(env, positionals[0], existsSync, existsSync);
 	} catch (e) {
 		if (e instanceof AnonPiError) {
 			process.stderr.write(e.message + '\n');
@@ -81,8 +115,22 @@ function runLaunch(args: string[]): number {
 		return 1;
 	}
 
-	// Ensure the workdir exists (a fresh named folder is fine).
 	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) {
+			process.stderr.write(
+				`anon-pi: new session home ${plan.stateDir} (seeding on first launch)\n`,
+			);
+		}
+	}
 
 	// Hand off to netcage with inherited stdio so -it is a real interactive TTY.
 	const res = spawnSync('netcage', plan.netcageArgs, {stdio: 'inherit'});