anon-pi 0.9.1 → 0.11.0

package/src/anon-pi.ts

@@ -748,6 +748,15 @@ export interface LaunchIntent {
 	 * undefined (shell-at-home / menu). Resolves the cwd via resolveCwd.
 	 */
 	project?: string;
+	/**
+	 * A RESUME-family launch's resolved session cwd (e.g. `/projects/test`), the
+	 * cwd pi keyed the resumed session by. Set by the CLI ONLY for a NO-project
+	 * `--session`/`--resume <id>` whose id it found in the host session store; it
+	 * OVERRIDES the default no-project cwd (the projects root) so pi resumes in
+	 * place instead of prompting to fork. Ignored when a project is given (the
+	 * user is trusted) or when the id is unresolvable (pi decides, as before).
+	 */
+	sessionCwd?: string;
 	/**
 	 * `--mount <parent>`: a resolved HOST parent path. When set it adds EXACTLY
 	 * one mount (<parent>:/work) and re-roots the cwd there (/work[/<project>]);
@@ -843,13 +852,18 @@ export interface ParsedLaunch {
 }
 
 /**
- * pi flags that make sense with NO anon-pi project, so `anon-pi <flag> ...`
- * launches pi (at the projects root) and forwards this flag + everything after
- * it verbatim. Two families:
- *  - SESSION selection (`--session <id>` etc.): pi finds the session file (in the
- *    always-mounted machine home) and switches to its own project cwd, so no
- *    project is needed. Mirrors pi's own resume hint (`pi --session <id>`), so
- *    pasting `anon-pi --session <id>` just works.
+ * pi flags anon-pi RECOGNISES in the no-project position, so `anon-pi <flag> ...`
+ * forwards this flag + everything after it verbatim. Three families with three
+ * no-project policies:
+ *  - RESUME (`--session`/`--session-id`/`--resume`/`-r <id>`): resume ONE session
+ *    in place. anon-pi resolves the session's recorded cwd from the host store
+ *    and cds there (isPiResumeFlag / resumeSessionId), so pi resumes cleanly.
+ *    Mirrors pi's own resume hint (`pi --session <id>`), so pasting `anon-pi
+ *    --session <id>` just works.
+ *  - NEEDS-PROJECT (`--fork`, `--continue`/`-c`): REFUSED without a project
+ *    (isPiNeedsProjectFlag) so the (new / newest) conversation never lands in
+ *    the projects root by surprise. Add a project (`.` for the root; created on
+ *    demand): `anon-pi <project> --fork <id>`.
  *  - QUERY (`--list-models`/`--models`): pi prints + exits, no project relevant.
  * For arbitrary pi flags with no project (e.g. `--model x`), use the explicit
  * `anon-pi pi <args…>` passthrough instead.
@@ -873,6 +887,111 @@ function isPiNoProjectFlag(a: string): boolean {
 	return PI_NO_PROJECT_FLAGS.has(a);
 }
 
+/**
+ * The RESUME family: session-selecting flags that resume ONE existing session in
+ * place (`--session`/`--session-id <id>`, `--resume`/`-r <id>`). With NO project,
+ * anon-pi resolves the session's recorded cwd from the host session store and
+ * cds THERE (setSessionCwd), so pi resumes cleanly instead of prompting to fork
+ * (its guard fires when the launch cwd differs from the session cwd). With an
+ * explicit project the user is trusted verbatim: anon-pi cds into that project
+ * and lets pi's own fork-prompt guard a mismatch. `--continue`/`--fork` are NOT
+ * here: they need a project (see PI_RESUME_NEEDS_PROJECT_FLAGS).
+ */
+const PI_RESUME_FLAGS: ReadonlySet<string> = new Set([
+	'--session',
+	'--session-id',
+	'--resume',
+	'-r',
+]);
+
+/**
+ * Session flags that REQUIRE an explicit project with no-project: `--fork` and
+ * `--continue`/`-c`. `--fork` writes a NEW session and would otherwise land it
+ * silently in the projects ROOT (a surprise); `--continue`/`-c` resumes the
+ * newest session for the launch cwd, so at the root it resolves ambiguously.
+ * anon-pi refuses both without a project (the project may be `.` for the root,
+ * and is created on demand), so where the conversation lands is always explicit.
+ */
+const PI_RESUME_NEEDS_PROJECT_FLAGS: ReadonlySet<string> = new Set([
+	'--fork',
+	'--continue',
+	'-c',
+]);
+
+/** True iff `a` is a RESUME-family flag (resolve session cwd; see PI_RESUME_FLAGS). */
+export function isPiResumeFlag(a: string): boolean {
+	return PI_RESUME_FLAGS.has(a);
+}
+
+/** True iff `a` is a session flag that needs an explicit project (--fork/--continue). */
+export function isPiNeedsProjectFlag(a: string): boolean {
+	return PI_RESUME_NEEDS_PROJECT_FLAGS.has(a);
+}
+
+/**
+ * PURE: the human name a --fork/--continue no-project refusal quotes. `-c` is
+ * spelled as its long form `--continue` in the message (clearer guidance).
+ */
+export function needsProjectFlagName(flag: string): string {
+	return flag === '-c' ? '--continue' : flag;
+}
+
+/**
+ * PURE: the leading session-id `--fork <id>` / `--continue <id>` accepts, or
+ * undefined. Used only to build a copy-pasteable "add a project" hint in the
+ * refusal (`anon-pi . --fork <id>`); the id is the token right after the flag
+ * when it is not itself another flag.
+ */
+export function resumeFlagId(piArgs: readonly string[]): string | undefined {
+	if (piArgs.length < 2) return undefined;
+	const id = piArgs[1];
+	return id.startsWith('-') ? undefined : id;
+}
+
+/**
+ * PURE: extract the session id a RESUME-family launch selects, so the CLI can
+ * look its cwd up in the host session store. Scans forwarded pi args for a
+ * resume flag (isPiResumeFlag) and returns the NEXT token when it is an id (not
+ * another flag). Returns undefined when there is no resume flag or no id after
+ * it (e.g. a bare `--resume` picker), in which case the CLI cds nowhere and pi
+ * decides as today.
+ */
+export function resumeSessionId(
+	piArgs: readonly string[] | undefined,
+): string | undefined {
+	if (!piArgs) return undefined;
+	for (let i = 0; i < piArgs.length; i++) {
+		if (isPiResumeFlag(piArgs[i])) {
+			const next = piArgs[i + 1];
+			if (next !== undefined && !next.startsWith('-')) return next;
+			return undefined;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * PURE: read a pi session's recorded cwd from its session-file HEADER line (the
+ * first JSONL record, `{"type":"session","id":"…","cwd":"/projects/x"}`). This
+ * is the authoritative cwd (what pi keys the conversation by), better than
+ * reversing the lossy `--…--` dir slug. Returns the cwd string, or undefined if
+ * the line is not the expected session header with a non-empty string cwd. The
+ * caller (CLI) supplies the file's first line; this stays pure + testable.
+ */
+export function sessionHeaderCwd(headerLine: string): string | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(headerLine);
+	} catch {
+		return undefined;
+	}
+	if (!parsed || typeof parsed !== 'object') return undefined;
+	const rec = parsed as Record<string, unknown>;
+	if (rec.type !== 'session') return undefined;
+	const cwd = rec.cwd;
+	return typeof cwd === 'string' && cwd.length > 0 ? cwd : undefined;
+}
+
 /**
  * The explicit pi-passthrough token: `anon-pi pi <args…>` runs pi with the given
  * args and NO project (the general escape hatch for any pi flag). It is a
@@ -1013,13 +1132,34 @@ export function parseLaunchArgs(args: readonly string[]): ParsedLaunch {
 			});
 		}
 		if (isPiNoProjectFlag(a)) {
-			// A pi flag that needs NO anon-pi project (`--session <id>`/`--continue`/
-			// `--fork` resume by id; `--list-models`/`--models` print + exit). pi
-			// resolves its own cwd (or just prints), so anon-pi launches pi at the
-			// projects root and forwards this flag + everything after it verbatim.
-			// This makes pi's own "To resume: pi --session <id>" hint usable as
-			// `anon-pi --session <id>`. (For ARBITRARY pi flags with no project, use
-			// the explicit `anon-pi pi <args…>` passthrough.)
+			// A pi flag that needs NO anon-pi project (RESUME family `--session <id>`/
+			// `--resume <id>`; `--list-models`/`--models` print + exit). pi resolves
+			// its own cwd (or just prints), so anon-pi launches pi at the projects
+			// root and forwards this flag + everything after it verbatim. For the
+			// RESUME family the CLI then resolves the session's recorded cwd and cds
+			// there so pi resumes in place (no fork prompt). This makes pi's own "To
+			// resume: pi --session <id>" hint usable as `anon-pi --session <id>`. (For
+			// ARBITRARY pi flags with no project, use `anon-pi pi <args…>`.)
+			//
+			// --fork / --continue are REFUSED with no project: they would land a
+			// (new / newest) conversation in the projects ROOT silently. Require an
+			// explicit project (created on demand; `.` for the root) so where the
+			// conversation lands is never a surprise.
+			if (isPiNeedsProjectFlag(a)) {
+				const rest = args.slice(i);
+				const name = needsProjectFlagName(a);
+				const id = resumeFlagId(rest);
+				const example = id
+					? `anon-pi <project> ${name} ${id}` +
+						` (or \`anon-pi . ${name} ${id}\` for the root)`
+					: `anon-pi <project> ${name} …` +
+						` (or \`anon-pi . ${name} …\` for the root)`;
+				fail(
+					`${name} needs a project so the conversation lands in a known ` +
+						`directory, not the projects root. Add one (it is created on ` +
+						`demand): ${example}.`,
+				);
+			}
 			piArgs = args.slice(i);
 			project = undefined;
 			i = args.length;
@@ -1148,7 +1288,15 @@ export function resolveRunPlan(
 	// Which root the cwd resolves under: /work when --mount, else /projects.
 	const rootKind: RootKind = mounted ? 'mount' : 'projects';
 
-	const cwd = launchCwd(mode, rootKind, project);
+	// A RESUME-family launch with NO project overrides the default no-project cwd
+	// (the projects root) with the session's own recorded cwd, so pi resumes in
+	// place. Only honoured for a projectless pi launch; a given project always
+	// wins (the user is trusted, pi guards a mismatch).
+	const sessionCwd = nonEmpty(intent.sessionCwd);
+	const cwd =
+		mode === 'pi' && project === undefined && sessionCwd !== undefined
+			? sessionCwd
+			: launchCwd(mode, rootKind, project);
 
 	const fresh = homeFresh(machine.home);
 	const seedVersion = intent.seedVersion ?? SEED_VERSION;
@@ -1360,6 +1508,318 @@ export function resolveRunVsStart(
 	return match ? {action: 'start', ref: match.ref} : {action: 'run'};
 }
 
+// --- `forward` / `ports`: reach an in-jail server from the host --------------
+//
+// netcage owns two host-access verbs (>= 0.9.0): `netcage forward <container>
+// [<hostPort>:]<jailPort>` stands up ONE host->jail inbound forward, and `netcage
+// ports <container> --json` lists the jail's TCP LISTEN sockets image-independently
+// (it reads the sidecar's /proc/net/tcp*, so a minimal image with no ss/netstat/nc
+// still works). anon-pi wraps them so the user never handles the raw netcage
+// container name: it resolves the RUNNING anon-pi container(s) by the identity key
+// it now stamps on EVERY launch (withKeyLabel, not just --keep), disambiguates with
+// a picker annotated by the open listeners, and shells out to `netcage forward`.
+// The forced-egress invariant is untouched: `forward` adds no OUTPUT rule (ADR-0014)
+// and `ports` only reads /proc; anon-pi composes neither egress flag here.
+
+/**
+ * PURE: the decoded fields of a stamped keptContainerKey (the reverse of
+ * keptContainerKey's `k=v\n` record). Used by `forward`/`ports` to filter the
+ * running managed containers by machine + project WITHOUT reconstructing the
+ * exact key (which would couple to launchCwd). Unknown/missing fields are ''.
+ */
+export interface KeptKeyFields {
+	machine: string;
+	projectsRoot: string;
+	mountParent: string;
+	cwd: string;
+}
+
+/** PURE: parse a stamped keptContainerKey back into its fields (best-effort). */
+export function parseKeptKey(key: string): KeptKeyFields {
+	const out: KeptKeyFields = {
+		machine: '',
+		projectsRoot: '',
+		mountParent: '',
+		cwd: '',
+	};
+	for (const line of key.split('\n')) {
+		const eq = line.indexOf('=');
+		if (eq < 0) continue;
+		const k = line.slice(0, eq);
+		const v = line.slice(eq + 1);
+		if (k === 'machine') out.machine = v;
+		else if (k === 'projectsRoot') out.projectsRoot = v;
+		else if (k === 'mountParent') out.mountParent = v;
+		else if (k === 'cwd') out.cwd = v;
+	}
+	return out;
+}
+
+/**
+ * PURE: the leaf name of a stamped key's cwd, i.e. the project a container hosts
+ * (`/projects/recon` -> `recon`, `/projects` -> '.', `/work/x` -> `x`, `/root`
+ * -> '' for a bare shell). Used to filter the picker by `<project>` and to label
+ * each row. A root cwd (`/projects`, `/work`) maps to the `.` root token.
+ */
+export function keyProject(fields: KeptKeyFields): string {
+	const cwd = fields.cwd;
+	if (cwd === CONTAINER_PROJECTS_ROOT || cwd === CONTAINER_MOUNT_ROOT) {
+		return ROOT_TOKEN;
+	}
+	if (cwd === CONTAINER_HOME_ROOT) return ''; // a bare shell, no project
+	const slash = cwd.lastIndexOf('/');
+	return slash < 0 ? cwd : cwd.slice(slash + 1);
+}
+
+/**
+ * PURE: pick the RUNNING anon-pi containers a `forward`/`ports` should offer.
+ * Filters the supplied running managed containers (each with its decoded key
+ * fields) to those on `machine`, optionally narrowed to `project` (its leaf cwd
+ * name). With no project, every anon-pi container on the machine qualifies. The
+ * caller resolves 0 (error) / 1 (auto) / many (picker).
+ */
+export function resolveManagedMatches(args: {
+	containers: readonly ManagedContainer[];
+	machine: string;
+	project?: string;
+}): ManagedContainer[] {
+	const {containers, machine, project} = args;
+	return containers.filter((c) => {
+		const f = parseKeptKey(c.key);
+		if (f.machine !== machine) return false;
+		if (project !== undefined && keyProject(f) !== project) return false;
+		return true;
+	});
+}
+
+/**
+ * A RUNNING netcage-managed container the CLI surfaces to the pure forward/ports
+ * resolution: its anon-pi identity `key` (stamped label, decoded), the `ref` to
+ * pass to `netcage forward`/`ports` (id or name), and a human `name` for the
+ * picker. Mirrors KeptContainer with the display name added.
+ */
+export interface ManagedContainer {
+	key: string;
+	ref: string;
+	name: string;
+}
+
+/**
+ * A parsed, validated port argument for `forward`: the in-jail port to reach and
+ * the host port to bind it on (equal to the jail port unless a `<hostPort>:`
+ * prefix remapped it). `raw` is the exact token to hand to netcage verbatim
+ * (`3001` or `8080:3001`), so anon-pi never re-serialises netcage's grammar.
+ */
+export interface ForwardPort {
+	hostPort: number;
+	jailPort: number;
+	raw: string;
+}
+
+/**
+ * PURE: parse a `forward` port token `[<hostPort>:]<jailPort>` (docker/kubectl
+ * host-first order). One port `3001` maps host 3001 -> jail 3001; `8080:3001`
+ * maps host 8080 -> jail 3001. Both sides must be integers in 1..65535. Throws
+ * AnonPiError on a bad shape / out-of-range / extra colon, with copy-pasteable
+ * guidance. `raw` is normalised to `<host>:<jail>` only when they differ, else
+ * the bare jail port, matching netcage's own accepted forms.
+ */
+export function parsePortArg(token: string): ForwardPort {
+	const bad = (why: string): never => {
+		throw new AnonPiError(
+			`anon-pi: invalid --port ${JSON.stringify(token)}: ${why}. ` +
+				'Use <jailPort> (e.g. 3001) or <hostPort>:<jailPort> (e.g. 8080:3001), ' +
+				'each 1..65535.',
+		);
+	};
+	const parts = token.split(':');
+	if (parts.length > 2) bad('too many colons');
+	const toPort = (s: string): number => {
+		if (!/^[0-9]+$/.test(s)) bad(`${JSON.stringify(s)} is not a port number`);
+		const n = Number(s);
+		if (n < 1 || n > 65535) bad(`${s} is out of range (1..65535)`);
+		return n;
+	};
+	if (parts.length === 1) {
+		const p = toPort(parts[0]);
+		return {hostPort: p, jailPort: p, raw: String(p)};
+	}
+	const hostPort = toPort(parts[0]);
+	const jailPort = toPort(parts[1]);
+	const raw =
+		hostPort === jailPort ? String(jailPort) : `${hostPort}:${jailPort}`;
+	return {hostPort, jailPort, raw};
+}
+
+/** A parsed `anon-pi forward` command (pure; the CLI does the netcage I/O). */
+export interface ForwardCommand {
+	project?: string;
+	machine: string;
+	machineExplicit: boolean;
+	/** The parsed port, or undefined to prompt from the container's listeners. */
+	port?: ForwardPort;
+	/** `--bind <addr>` passed through to netcage verbatim (undefined => netcage default). */
+	bind?: string;
+}
+
+/**
+ * PURE: parse `anon-pi forward [<project>] [--port <[hostPort:]jailPort>]
+ * [--bind <addr>] [-m <machine>]`. The bare positional is ALWAYS the project (so
+ * a numeric name like `3001` is a project, never a port); the port is the
+ * `--port`/`-p` flag, removing the number-vs-project ambiguity. `--bind` is
+ * passed through to netcage (which validates 127.0.0.1 / 0.0.0.0). Throws
+ * AnonPiError on an unknown flag, a missing flag argument, a second positional,
+ * or a bad port.
+ */
+export function parseForwardArgs(args: readonly string[]): ForwardCommand {
+	const fail = (msg: string): never => {
+		throw new AnonPiError(`anon-pi: ${msg}\nRun \`anon-pi forward --help\`.`);
+	};
+	let project: string | undefined;
+	let machine = DEFAULT_MACHINE;
+	let machineExplicit = false;
+	let port: ForwardPort | undefined;
+	let bind: string | undefined;
+	for (let i = 0; i < args.length; i++) {
+		const a = args[i];
+		if (a === '-m' || a === '--machine') {
+			const v = args[++i];
+			if (v === undefined) fail(`${a} needs a machine name`);
+			machine = validateName(v as string, 'machine');
+			machineExplicit = true;
+		} else if (a === '-p' || a === '--port') {
+			const v = args[++i];
+			if (v === undefined) fail(`${a} needs a port ([hostPort:]jailPort)`);
+			port = parsePortArg(v as string);
+		} else if (a === '--bind') {
+			const v = args[++i];
+			if (v === undefined)
+				fail('--bind needs an address (127.0.0.1 or 0.0.0.0)');
+			bind = v as string;
+		} else if (a.startsWith('-')) {
+			fail(`unknown option: ${a}`);
+		} else if (project === undefined) {
+			project = validateName(a, 'project');
+		} else {
+			fail(`unexpected argument: ${a} (forward takes at most one project)`);
+		}
+	}
+	return {project, machine, machineExplicit, port, bind};
+}
+
+/** A parsed `anon-pi ports` command (pure). */
+export interface PortsCommand {
+	project?: string;
+	machine: string;
+	machineExplicit: boolean;
+}
+
+/**
+ * PURE: parse `anon-pi ports [<project>] [-m <machine>]`. Like forward but with
+ * no port/bind: it lists a container's open in-jail listeners. The bare
+ * positional is the project filter.
+ */
+export function parsePortsArgs(args: readonly string[]): PortsCommand {
+	const fail = (msg: string): never => {
+		throw new AnonPiError(`anon-pi: ${msg}\nRun \`anon-pi ports --help\`.`);
+	};
+	let project: string | undefined;
+	let machine = DEFAULT_MACHINE;
+	let machineExplicit = false;
+	for (let i = 0; i < args.length; i++) {
+		const a = args[i];
+		if (a === '-m' || a === '--machine') {
+			const v = args[++i];
+			if (v === undefined) fail(`${a} needs a machine name`);
+			machine = validateName(v as string, 'machine');
+			machineExplicit = true;
+		} else if (a.startsWith('-')) {
+			fail(`unknown option: ${a}`);
+		} else if (project === undefined) {
+			project = validateName(a, 'project');
+		} else {
+			fail(`unexpected argument: ${a} (ports takes at most one project)`);
+		}
+	}
+	return {project, machine, machineExplicit};
+}
+
+/**
+ * A jail TCP LISTEN socket, as netcage's `ports --json` reports it: the bind
+ * `address`, the `port`, and `loopbackOnly` (bound 127.0.0.0/8 or ::1). The
+ * contract is netcage's (ADR-0015); anon-pi only consumes it.
+ */
+export interface NetcageListener {
+	address: string;
+	port: number;
+	loopbackOnly: boolean;
+}
+
+/**
+ * PURE: parse `netcage ports --json` output into listeners (best-effort). Keeps
+ * only well-formed `{address:string, port:int, loopbackOnly:bool}` entries;
+ * anything else (a netcage version drift, a non-array) yields []. The caller
+ * treats [] as "no hint", never an error.
+ */
+export function parseNetcagePortsJson(stdout: string): NetcageListener[] {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(stdout);
+	} catch {
+		return [];
+	}
+	if (!Array.isArray(parsed)) return [];
+	const out: NetcageListener[] = [];
+	for (const e of parsed) {
+		if (!e || typeof e !== 'object') continue;
+		const r = e as Record<string, unknown>;
+		if (
+			typeof r.address === 'string' &&
+			typeof r.port === 'number' &&
+			typeof r.loopbackOnly === 'boolean'
+		) {
+			out.push({
+				address: r.address,
+				port: r.port,
+				loopbackOnly: r.loopbackOnly,
+			});
+		}
+	}
+	return out;
+}
+
+/** netcage's in-jail DNS forwarder always listens here; anon-pi hides it from the port hint. */
+export const NETCAGE_DNS_PORT = 53;
+
+/**
+ * PURE: the in-jail ports worth offering as forward targets: the listeners with
+ * netcage's own `127.0.0.1:53` DNS forwarder dropped (it is never something a
+ * user forwards), de-duplicated by port, sorted ascending. A server bound on
+ * both IPv4 and IPv6 (two listeners, same port) collapses to one entry.
+ */
+export function forwardablePorts(
+	listeners: readonly NetcageListener[],
+): number[] {
+	const ports = new Set<number>();
+	for (const l of listeners) {
+		if (l.port === NETCAGE_DNS_PORT && l.loopbackOnly) continue;
+		ports.add(l.port);
+	}
+	return [...ports].sort((a, b) => a - b);
+}
+
+/**
+ * PURE: a compact one-line hint of a container's forwardable in-jail ports for
+ * the picker / the pre-forward confirmation, e.g. `open: 3001, 5173` or
+ * `open: (none detected)`. Never includes the DNS forwarder (forwardablePorts).
+ */
+export function formatPortsHint(listeners: readonly NetcageListener[]): string {
+	const ports = forwardablePorts(listeners);
+	return ports.length === 0
+		? 'open: (none detected)'
+		: `open: ${ports.join(', ')}`;
+}
+
 // --- The bare-launch menu: choice-list + per-machine project-usage record ----
 //
 // anon-pi's bare launch shows a HOST-side arrow-key menu of a machine's
@@ -2550,12 +3010,14 @@ USAGE
   anon-pi                        MENU: pick a project (pi), a shell, or a new project
   anon-pi <project>              pi in the project (${CONTAINER_PROJECTS_ROOT}/<project>); exit pi -> host
   anon-pi <project> <pi-args…>   forward args to pi (e.g. -p for a headless one-shot)
-  anon-pi --session <id>         resume a pi session by id (forwarded to pi; no project needed)
-  anon-pi --continue             continue your most recent pi session (also -r/--resume, --fork)
+  anon-pi --session <id>         resume a pi session by id, in its own project (also -r/--resume)
+  anon-pi <project> --fork <id>  fork a session into <project> (\`.\`=root; --continue too; project required)
   anon-pi --list-models          list the models pi sees (also --models; no project needed)
   anon-pi pi <pi-args…>          run pi with ANY args and no project (the passthrough)
   anon-pi --version              print anon-pi's version (also -V)
   anon-pi --shell [<project>]    a jailed bash (at ~, or cd'd into <project>) - the project-hopper
+  anon-pi forward [<p>] [--port …]  open a host port onto a running container's in-jail server
+  anon-pi ports [<project>]      list a running container's open in-jail TCP listeners
   anon-pi -m <machine> [<p>]     the same, on <machine> (its own image + home + conversations)
   anon-pi --mount <parent> [<p>] root at a HOST parent folder instead of the projects root
   anon-pi init                   onboard: verify your proxy, capture your local model, pick an image