@schilderlabs/pitown 0.1.2 → 0.2.6

package/dist/index.mjs

@@ -1,42 +1,1299 @@
 #!/usr/bin/env node
-import { m as isDirectExecution } from "./config-Bw-mNdF5.mjs";
+import { a as appendAgentMessage, c as getAgentDir, d as listAgentStates, f as readAgentMessages, i as writeTaskRecord, l as getAgentSessionsDir, m as writeAgentState, n as listTaskRecords, o as createAgentSessionRecord, p as readAgentState, r as updateTaskRecordStatus, s as createAgentState, t as createTaskRecord, u as getLatestAgentSession } from "./tasks-De4IAy3x.mjs";
+import { t as runLoop } from "./loop-CocC9qO1.mjs";
+import { a as runCommandSync, i as runCommandInteractive, n as assertCommandAvailable, t as isDirectExecution } from "./entrypoint-WBAQmFbT.mjs";
+import { a as getRecommendedPlanDir, c as getReposRootDir, d as createRepoSlug, f as getCurrentBranch, l as getTownHomeDir, m as getRepoRoot, n as parseOptionalRepoFlag, o as getRepoArtifactsDir, p as getRepoIdentity, u as getUserConfigPath } from "./config-BG1v4iIi.mjs";
+import { t as resolveRepoContext } from "./repo-context-BuA2JqPm.mjs";
+import { runDoctor } from "./doctor.mjs";
 import { runTown } from "./run.mjs";
 import { showTownStatus } from "./status.mjs";
 import { watchTown } from "./watch.mjs";
+import { createRequire } from "node:module";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { readPiTownMayorPrompt, resolvePiTownExtensionPath } from "@schilderlabs/pitown-package";
 
+//#region ../core/src/orchestration.ts
+function createPiInvocationArgs(input) {
+	const args = [];
+	if (input.extensionPath) args.push("--extension", input.extensionPath);
+	if (input.appendedSystemPrompt) args.push("--append-system-prompt", input.appendedSystemPrompt);
+	if (input.sessionPath) args.push("--session", input.sessionPath);
+	else if (input.sessionDir) args.push("--session-dir", input.sessionDir);
+	else throw new Error("Pi invocation requires a session path or session directory");
+	if (input.prompt) args.push("-p", input.prompt);
+	return args;
+}
+function createDetachedRunnerInvocation(encodedPayload) {
+	if (fileURLToPath(import.meta.url).endsWith(".ts")) {
+		const require = createRequire(import.meta.url);
+		return {
+			command: process.execPath,
+			args: [
+				"--import",
+				require.resolve("tsx"),
+				fileURLToPath(new URL("./agent-runner.ts", import.meta.url)),
+				encodedPayload
+			]
+		};
+	}
+	return {
+		command: process.execPath,
+		args: [fileURLToPath(new URL("./agent-runner.mjs", import.meta.url)), encodedPayload]
+	};
+}
+function createRolePrompt(input) {
+	const task = input.task ?? "pick the next bounded task from the current repo context";
+	switch (input.role) {
+		case "mayor": return [
+			"You are the Pi Town mayor.",
+			"You coordinate work for this repository and act as the primary human-facing agent.",
+			"",
+			`Repository: ${input.repoRoot}`,
+			`Task: ${task}`,
+			"Keep updates concise, choose bounded next steps, and leave a durable artifact trail."
+		].join("\n");
+		case "reviewer": return [
+			"You are the Pi Town reviewer.",
+			"You review work for correctness, safety, and completeness.",
+			"",
+			`Repository: ${input.repoRoot}`,
+			`Task: ${task}`,
+			"Focus on validation confidence, regressions, and whether the output is ready for a human handoff."
+		].join("\n");
+		case "docs-keeper": return [
+			"You are the Pi Town docs keeper.",
+			"You summarize outcomes, blockers, and continuity in compact factual language.",
+			"",
+			`Repository: ${input.repoRoot}`,
+			`Task: ${task}`,
+			"Keep the output concise and useful for the next run or human review."
+		].join("\n");
+		default: return [
+			"You are the Pi Town worker.",
+			"You implement one bounded task at a time.",
+			"",
+			`Repository: ${input.repoRoot}`,
+			`Task: ${task}`,
+			"Keep scope tight, prefer explicit validations, and summarize what changed and what still needs follow-up."
+		].join("\n");
+	}
+}
+function resolveAgentSession(agentId, artifactsDir) {
+	const state = readAgentState(artifactsDir, agentId);
+	if (state === null) throw new Error(`Unknown agent: ${agentId}`);
+	const latestSession = getLatestAgentSession(artifactsDir, agentId);
+	const sessionPath = state.session.sessionPath ?? latestSession.sessionPath;
+	const sessionId = state.session.sessionId ?? latestSession.sessionId;
+	const sessionDir = state.session.sessionDir ?? latestSession.sessionDir ?? getAgentSessionsDir(artifactsDir, agentId);
+	if (sessionPath === null) throw new Error(`Agent ${agentId} does not have a persisted Pi session yet.`);
+	return {
+		state,
+		session: createAgentSessionRecord({
+			sessionDir,
+			sessionId,
+			sessionPath,
+			processId: state.session.processId,
+			lastAttachedAt: (/* @__PURE__ */ new Date()).toISOString()
+		})
+	};
+}
+function queueAgentMessage(input) {
+	const state = readAgentState(input.artifactsDir, input.agentId);
+	if (state === null) throw new Error(`Unknown agent: ${input.agentId}`);
+	appendAgentMessage({
+		artifactsDir: input.artifactsDir,
+		agentId: input.agentId,
+		box: "inbox",
+		from: input.from,
+		body: input.body
+	});
+	writeAgentState(input.artifactsDir, createAgentState({
+		...state,
+		status: state.status === "idle" ? "queued" : state.status,
+		lastMessage: input.body,
+		waitingOn: null,
+		blocked: false,
+		session: createAgentSessionRecord({
+			sessionDir: state.session.sessionDir ?? getAgentSessionsDir(input.artifactsDir, input.agentId),
+			sessionId: state.session.sessionId,
+			sessionPath: state.session.sessionPath,
+			processId: state.session.processId,
+			lastAttachedAt: state.session.lastAttachedAt
+		})
+	}));
+}
+function spawnAgentRun(options) {
+	const sessionDir = getAgentSessionsDir(options.artifactsDir, options.agentId);
+	if (readAgentState(options.artifactsDir, options.agentId) !== null) throw new Error(`Agent already exists: ${options.agentId}`);
+	assertCommandAvailable("pi");
+	const state = createAgentState({
+		agentId: options.agentId,
+		role: options.role,
+		status: "queued",
+		taskId: options.taskId ?? null,
+		task: options.task,
+		lastMessage: options.task ? `Spawned with task: ${options.task}` : `Spawned ${options.role} agent`,
+		session: createAgentSessionRecord({ sessionDir })
+	});
+	writeAgentState(options.artifactsDir, state);
+	if (options.task) appendAgentMessage({
+		artifactsDir: options.artifactsDir,
+		agentId: options.agentId,
+		box: "inbox",
+		from: "system",
+		body: options.task
+	});
+	writeAgentState(options.artifactsDir, createAgentState({
+		...state,
+		status: "running",
+		lastMessage: options.task ? `Running ${options.role} task: ${options.task}` : `Running ${options.role} agent`
+	}));
+	const piArgs = createPiInvocationArgs({
+		sessionDir,
+		prompt: createRolePrompt({
+			role: options.role,
+			task: options.task,
+			repoRoot: options.repoRoot
+		}),
+		appendedSystemPrompt: options.appendedSystemPrompt,
+		extensionPath: options.extensionPath
+	});
+	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const runner = createDetachedRunnerInvocation(Buffer.from(JSON.stringify({
+		repoRoot: options.repoRoot,
+		artifactsDir: options.artifactsDir,
+		agentId: options.agentId,
+		role: options.role,
+		task: options.task,
+		taskId: options.taskId ?? null,
+		sessionDir,
+		piArgs
+	}), "utf-8").toString("base64url"));
+	const child = spawn(runner.command, runner.args, {
+		cwd: options.repoRoot,
+		detached: true,
+		env: process.env,
+		stdio: "ignore"
+	});
+	child.unref();
+	if (!child.pid) throw new Error(`Failed to launch detached ${options.role} run for ${options.agentId}`);
+	writeFileSync(`${getAgentDir(options.artifactsDir, options.agentId)}/latest-invocation.json`, `${JSON.stringify({
+		command: "pi",
+		args: piArgs,
+		exitCode: null,
+		sessionDir,
+		sessionPath: null,
+		sessionId: null,
+		processId: child.pid,
+		startedAt
+	}, null, 2)}\n`, "utf-8");
+	return {
+		launch: {
+			processId: child.pid,
+			startedAt
+		},
+		latestSession: createAgentSessionRecord({ sessionDir })
+	};
+}
+function runAgentTurn(options) {
+	assertCommandAvailable("pi");
+	const resolved = resolveAgentSession(options.agentId, options.artifactsDir);
+	const messageSource = options.from ?? "human";
+	writeAgentState(options.artifactsDir, createAgentState({
+		...resolved.state,
+		status: "running",
+		lastMessage: `Responding to ${messageSource}: ${options.message}`,
+		waitingOn: null,
+		blocked: false,
+		session: resolved.session
+	}));
+	const piArgs = options.runtimeArgs && options.runtimeArgs.length > 0 ? options.runtimeArgs : createPiInvocationArgs({
+		sessionPath: resolved.session.sessionPath,
+		prompt: options.message
+	});
+	const piResult = runCommandSync("pi", piArgs, {
+		cwd: options.repoRoot,
+		env: process.env
+	});
+	const latestSession = getLatestAgentSession(options.artifactsDir, options.agentId);
+	const agentArtifactsDir = getAgentDir(options.artifactsDir, options.agentId);
+	writeFileSync(`${agentArtifactsDir}/latest-stdout.txt`, piResult.stdout, "utf-8");
+	writeFileSync(`${agentArtifactsDir}/latest-stderr.txt`, piResult.stderr, "utf-8");
+	writeFileSync(`${agentArtifactsDir}/latest-invocation.json`, `${JSON.stringify({
+		command: "pi",
+		args: piArgs,
+		exitCode: piResult.exitCode,
+		sessionDir: latestSession.sessionDir,
+		sessionPath: latestSession.sessionPath,
+		sessionId: latestSession.sessionId
+	}, null, 2)}\n`, "utf-8");
+	const completionMessage = piResult.stdout.trim() || (piResult.exitCode === 0 ? `${resolved.state.role} turn completed` : `${resolved.state.role} turn exited with code ${piResult.exitCode}`);
+	appendAgentMessage({
+		artifactsDir: options.artifactsDir,
+		agentId: options.agentId,
+		box: "outbox",
+		from: options.agentId,
+		body: completionMessage
+	});
+	writeAgentState(options.artifactsDir, createAgentState({
+		...resolved.state,
+		status: piResult.exitCode === 0 ? "idle" : "blocked",
+		lastMessage: completionMessage,
+		waitingOn: piResult.exitCode === 0 ? null : "human-or-follow-up-run",
+		blocked: piResult.exitCode !== 0,
+		session: createAgentSessionRecord({
+			sessionDir: latestSession.sessionDir,
+			sessionId: latestSession.sessionId,
+			sessionPath: latestSession.sessionPath,
+			processId: null
+		})
+	}));
+	return {
+		piResult,
+		latestSession,
+		completionMessage
+	};
+}
+function delegateTask(options) {
+	if (readAgentState(options.artifactsDir, options.fromAgentId) === null) throw new Error(`Unknown delegating agent: ${options.fromAgentId}`);
+	const agentId = options.agentId ?? `${options.role}-${Date.now()}`;
+	const task = createTaskRecord({
+		taskId: `task-${Date.now()}`,
+		title: options.task,
+		status: "queued",
+		role: options.role,
+		assignedAgentId: agentId,
+		createdBy: options.fromAgentId
+	});
+	writeTaskRecord(options.artifactsDir, task);
+	appendAgentMessage({
+		artifactsDir: options.artifactsDir,
+		agentId: options.fromAgentId,
+		box: "outbox",
+		from: options.fromAgentId,
+		body: `Delegated ${task.taskId} to ${agentId}: ${options.task}`
+	});
+	const { launch, latestSession } = spawnAgentRun({
+		repoRoot: options.repoRoot,
+		artifactsDir: options.artifactsDir,
+		role: options.role,
+		agentId,
+		appendedSystemPrompt: options.appendedSystemPrompt,
+		extensionPath: options.extensionPath,
+		task: options.task,
+		taskId: task.taskId
+	});
+	appendAgentMessage({
+		artifactsDir: options.artifactsDir,
+		agentId,
+		box: "inbox",
+		from: options.fromAgentId,
+		body: `Delegated by ${options.fromAgentId} as ${task.taskId}: ${options.task}`
+	});
+	writeTaskRecord(options.artifactsDir, {
+		...task,
+		status: "running",
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	});
+	return {
+		task: {
+			...task,
+			status: "running",
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		},
+		agentId,
+		launch,
+		latestSession
+	};
+}
+
+//#endregion
+//#region ../core/src/stop.ts
+const DEFAULT_GRACE_MS = 750;
+function sleepMs(ms) {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function getLocksDir() {
+	return join(homedir(), ".pi-town", "locks");
+}
+function processAlive(pid) {
+	if (!Number.isFinite(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function terminateProcess(pid, options) {
+	if (!processAlive(pid)) return {
+		signal: null,
+		exited: true
+	};
+	try {
+		process.kill(pid, "SIGTERM");
+	} catch {
+		return {
+			signal: null,
+			exited: !processAlive(pid)
+		};
+	}
+	const graceMs = options.graceMs ?? DEFAULT_GRACE_MS;
+	const deadline = Date.now() + graceMs;
+	while (Date.now() < deadline) {
+		if (!processAlive(pid)) return {
+			signal: "SIGTERM",
+			exited: true
+		};
+		sleepMs(25);
+	}
+	if (!options.force) return {
+		signal: "SIGTERM",
+		exited: !processAlive(pid)
+	};
+	try {
+		process.kill(pid, "SIGKILL");
+	} catch {
+		return {
+			signal: "SIGTERM",
+			exited: !processAlive(pid)
+		};
+	}
+	return {
+		signal: "SIGKILL",
+		exited: !processAlive(pid)
+	};
+}
+function readLease(path) {
+	try {
+		return {
+			...JSON.parse(readFileSync(path, "utf-8")),
+			path
+		};
+	} catch {
+		return null;
+	}
+}
+function createStopMessage(options) {
+	if (options.reason) return options.reason;
+	if (options.actorId) return `Stopped by ${options.actorId}`;
+	return "Stopped by operator";
+}
+function createStopMessageInput(options) {
+	return {
+		...options.actorId === void 0 ? {} : { actorId: options.actorId },
+		...options.reason === void 0 ? {} : { reason: options.reason }
+	};
+}
+function createTerminateOptions(options) {
+	return {
+		...options.force === void 0 ? {} : { force: options.force },
+		...options.graceMs === void 0 ? {} : { graceMs: options.graceMs }
+	};
+}
+function listRepoLeases(repoId) {
+	let entries;
+	try {
+		entries = readdirSync(getLocksDir());
+	} catch {
+		return [];
+	}
+	return entries.filter((entry) => entry.endsWith(".json")).map((entry) => readLease(join(getLocksDir(), entry))).filter((record) => record !== null).filter((record) => repoId === void 0 || repoId === null || record.repoId === repoId);
+}
+function stopRepoLeases(options) {
+	const results = listRepoLeases(options.repoId).map((lease) => {
+		const termination = terminateProcess(lease.pid, options);
+		if (termination.exited) rmSync(lease.path, { force: true });
+		return {
+			path: lease.path,
+			runId: lease.runId,
+			repoId: lease.repoId,
+			branch: lease.branch,
+			processId: lease.pid,
+			signal: termination.signal,
+			exited: termination.exited
+		};
+	});
+	return {
+		results,
+		signaledProcesses: results.filter((result) => result.signal !== null).length
+	};
+}
+function stopManagedAgents(options) {
+	const reason = createStopMessage(createStopMessageInput(options));
+	const excluded = new Set(options.excludeAgentIds ?? []);
+	const results = listAgentStates(options.artifactsDir).filter((agent) => {
+		if (excluded.has(agent.agentId)) return false;
+		if (options.agentId && agent.agentId !== options.agentId) return false;
+		return ![
+			"completed",
+			"failed",
+			"stopped"
+		].includes(agent.status);
+	}).map((state) => {
+		const processId = state.session.processId;
+		const termination = processId === null ? {
+			signal: null,
+			exited: true
+		} : terminateProcess(processId, createTerminateOptions(options));
+		if (state.taskId) updateTaskRecordStatus(options.artifactsDir, state.taskId, "aborted");
+		appendAgentMessage({
+			artifactsDir: options.artifactsDir,
+			agentId: state.agentId,
+			box: "outbox",
+			from: options.actorId ?? "system",
+			body: reason
+		});
+		writeAgentState(options.artifactsDir, createAgentState({
+			...state,
+			status: "stopped",
+			lastMessage: reason,
+			waitingOn: "stopped",
+			blocked: true,
+			session: createAgentSessionRecord({
+				sessionDir: state.session.sessionDir,
+				sessionId: state.session.sessionId,
+				sessionPath: state.session.sessionPath,
+				processId: null,
+				lastAttachedAt: state.session.lastAttachedAt
+			})
+		}));
+		return {
+			agentId: state.agentId,
+			previousStatus: state.status,
+			nextStatus: "stopped",
+			processId,
+			signal: termination.signal,
+			exited: termination.exited
+		};
+	});
+	return {
+		results,
+		stoppedAgents: results.length,
+		signaledProcesses: results.filter((result) => result.signal !== null).length
+	};
+}
+
+//#endregion
+//#region src/agent-id.ts
+function normalizeAgentId(agentId) {
+	return agentId;
+}
+
+//#endregion
+//#region src/pi-runtime.ts
+function isMayorAgent(agentId) {
+	return agentId === "mayor";
+}
+function createPiTownRuntimeArgs(options) {
+	const args = ["--extension", resolvePiTownExtensionPath()];
+	if (isMayorAgent(options.agentId)) args.push("--append-system-prompt", readPiTownMayorPrompt());
+	if (options.sessionPath) args.push("--session", options.sessionPath);
+	else if (options.sessionDir) args.push("--session-dir", options.sessionDir);
+	else throw new Error("Pi Town runtime requires either a session path or a session directory");
+	if (options.prompt) args.push("-p", options.prompt);
+	if (options.message) args.push(options.message);
+	return args;
+}
+
+//#endregion
+//#region src/attach.ts
+function attachTownAgent(argv = process.argv.slice(2)) {
+	const repo = resolveRepoContext(argv);
+	const [agentArg] = repo.rest;
+	if (!agentArg) throw new Error("Usage: pitown attach [--repo <path>] <agent>");
+	const agentId = normalizeAgentId(agentArg);
+	assertCommandAvailable("pi");
+	const resolved = resolveAgentSession(agentId, repo.artifactsDir);
+	writeAgentState(repo.artifactsDir, {
+		...resolved.state,
+		session: resolved.session
+	});
+	console.log("[pitown] attach");
+	console.log(`- repo root: ${repo.repoRoot}`);
+	console.log(`- agent: ${agentId}`);
+	console.log(`- session: ${resolved.session.sessionPath}`);
+	const exitCode = runCommandInteractive("pi", createPiTownRuntimeArgs({
+		agentId,
+		sessionPath: resolved.session.sessionPath
+	}), {
+		cwd: repo.repoRoot,
+		env: process.env
+	});
+	if (exitCode !== 0) process.exitCode = exitCode;
+}
+
+//#endregion
+//#region src/board.ts
+function truncate(text, max) {
+	if (!text) return "—";
+	const single = text.replace(/\n/g, " ").trim();
+	if (single.length <= max) return single;
+	return `${single.slice(0, max - 1)}…`;
+}
+function showTownBoard(argv = process.argv.slice(2)) {
+	const repo = resolveRepoContext(argv);
+	const agents = listAgentStates(repo.artifactsDir);
+	const tasks = listTaskRecords(repo.artifactsDir);
+	const repoName = basename(repo.repoRoot);
+	const branch = getCurrentBranch(repo.repoRoot);
+	const branchLabel = branch ? ` (${branch})` : "";
+	const mayor = agents.find((a) => a.agentId === "mayor");
+	const workers = agents.filter((a) => a.agentId !== "mayor");
+	const workersByStatus = (status) => workers.filter((a) => a.status === status).length;
+	console.log(`[pitown] board — ${repoName}${branchLabel}`);
+	if (mayor) {
+		const spawned = workers.length;
+		const running = workersByStatus("running") + workersByStatus("starting");
+		const completed = workersByStatus("completed") + workersByStatus("idle");
+		const blocked = workersByStatus("blocked") + workersByStatus("failed");
+		const parts = [`${spawned} spawned`];
+		if (running > 0) parts.push(`${running} running`);
+		if (completed > 0) parts.push(`${completed} done`);
+		if (blocked > 0) parts.push(`${blocked} blocked`);
+		console.log(`Mayor workers: ${parts.join(", ")}`);
+	}
+	console.log("");
+	console.log("Agents:");
+	if (agents.length === 0) console.log("  (no agents)");
+	else for (const agent of agents) {
+		const id = agent.agentId.padEnd(14);
+		const role = agent.role.padEnd(10);
+		const status = agent.status.padEnd(10);
+		const task = truncate(agent.task, 60);
+		const msg = agent.lastMessage ? ` | ${truncate(agent.lastMessage, 40)}` : "";
+		const waiting = agent.waitingOn ? ` | waiting on: ${agent.waitingOn}` : "";
+		console.log(`  ${id}${role}${status}${task}${msg}${waiting}`);
+	}
+	console.log("");
+	console.log("Tasks:");
+	if (tasks.length === 0) console.log("  (no tasks)");
+	else for (const task of tasks) {
+		const id = task.taskId.padEnd(14);
+		const status = task.status.padEnd(12);
+		const assignee = (task.assignedAgentId ?? "—").padEnd(14);
+		const title = truncate(task.title, 60);
+		console.log(`  ${id}${status}${assignee}${title}`);
+	}
+	const metricsPath = join(repo.artifactsDir, "latest", "metrics.json");
+	if (existsSync(metricsPath)) try {
+		const metrics = JSON.parse(readFileSync(metricsPath, "utf-8"));
+		console.log("");
+		console.log("Metrics (latest run):");
+		console.log(`  Interrupt Rate:              ${fmt(metrics.interruptRate)}`);
+		console.log(`  Autonomous Completion Rate:  ${fmt(metrics.autonomousCompletionRate)}`);
+		console.log(`  Context Coverage Score:      ${fmt(metrics.contextCoverageScore)}`);
+		console.log(`  MTTC:                        ${metrics.meanTimeToCorrectHours != null ? `${metrics.meanTimeToCorrectHours}h` : "—"}`);
+		console.log(`  Feedback-to-Demo:            ${metrics.feedbackToDemoCycleTimeHours != null ? `${metrics.feedbackToDemoCycleTimeHours}h` : "—"}`);
+	} catch {}
+}
+function fmt(value) {
+	if (value == null) return "—";
+	return String(value);
+}
+
+//#endregion
+//#region src/continue.ts
+function continueTownAgent(argv = process.argv.slice(2)) {
+	const repo = resolveRepoContext(argv);
+	const [agentArg, ...messageParts] = repo.rest;
+	if (!agentArg) throw new Error("Usage: pitown continue [--repo <path>] <agent> [\"message\"]");
+	const agentId = normalizeAgentId(agentArg);
+	assertCommandAvailable("pi");
+	const resolved = resolveAgentSession(agentId, repo.artifactsDir);
+	writeAgentState(repo.artifactsDir, {
+		...resolved.state,
+		session: resolved.session
+	});
+	const message = messageParts.join(" ").trim();
+	const args = createPiTownRuntimeArgs({
+		agentId,
+		sessionPath: resolved.session.sessionPath,
+		message: message || null
+	});
+	console.log("[pitown] continue");
+	console.log(`- repo root: ${repo.repoRoot}`);
+	console.log(`- agent: ${agentId}`);
+	console.log(`- session: ${resolved.session.sessionPath}`);
+	if (message) console.log(`- message: ${message}`);
+	const exitCode = runCommandInteractive("pi", args, {
+		cwd: repo.repoRoot,
+		env: process.env
+	});
+	if (exitCode !== 0) process.exitCode = exitCode;
+}
+
+//#endregion
+//#region src/delegate.ts
+function parseDelegateFlags(argv) {
+	let from = "mayor";
+	let role = "worker";
+	let agentId = null;
+	let task = null;
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === void 0) continue;
+		if (arg.startsWith("--from=")) {
+			from = arg.slice(7);
+			continue;
+		}
+		if (arg === "--from") {
+			from = argv[index + 1] ?? from;
+			index += 1;
+			continue;
+		}
+		if (arg.startsWith("--role=")) {
+			role = arg.slice(7);
+			continue;
+		}
+		if (arg === "--role") {
+			role = argv[index + 1] ?? role;
+			index += 1;
+			continue;
+		}
+		if (arg.startsWith("--agent=")) {
+			agentId = arg.slice(8);
+			continue;
+		}
+		if (arg === "--agent") {
+			agentId = argv[index + 1] ?? null;
+			index += 1;
+			continue;
+		}
+		if (arg.startsWith("--task=")) {
+			task = arg.slice(7);
+			continue;
+		}
+		if (arg === "--task") {
+			task = argv[index + 1] ?? null;
+			index += 1;
+			continue;
+		}
+		throw new Error(`Unknown argument: ${arg}`);
+	}
+	if (!task) throw new Error("Usage: pitown delegate [--repo <path>] [--from <agent>] [--role <role>] [--agent <id>] --task <text>");
+	return {
+		from,
+		role,
+		agentId,
+		task
+	};
+}
+function delegateTownTask(argv = process.argv.slice(2)) {
+	const repo = resolveRepoContext(argv);
+	const flags = parseDelegateFlags(repo.rest);
+	const fromAgentId = normalizeAgentId(flags.from);
+	if (readAgentState(repo.artifactsDir, fromAgentId) === null) throw new Error(`Unknown delegating agent: ${fromAgentId}`);
+	const { agentId, latestSession, launch, task } = delegateTask({
+		repoRoot: repo.repoRoot,
+		artifactsDir: repo.artifactsDir,
+		fromAgentId,
+		role: flags.role,
+		agentId: flags.agentId,
+		task: flags.task,
+		extensionPath: resolvePiTownExtensionPath()
+	});
+	console.log("[pitown] delegate");
+	console.log(`- repo root: ${repo.repoRoot}`);
+	console.log(`- from: ${fromAgentId}`);
+	console.log(`- task id: ${task.taskId}`);
+	console.log(`- agent: ${agentId}`);
+	console.log(`- role: ${flags.role}`);
+	console.log(`- status: ${task.status}`);
+	console.log(`- launch pid: ${launch.processId}`);
+	if (latestSession.sessionPath) console.log(`- session: ${latestSession.sessionPath}`);
+	else if (latestSession.sessionDir) console.log(`- session dir: ${latestSession.sessionDir}`);
+}
+
+//#endregion
+//#region src/loop-config.ts
+const DEFAULT_GOAL = "continue from current scaffold state";
+const DEFAULT_MAX_ITERATIONS = 10;
+const DEFAULT_MAX_TIME_MINUTES = 60;
+function expandHome(value) {
+	if (value === "~") return homedir();
+	if (value.startsWith("~/")) return resolve(homedir(), value.slice(2));
+	return value;
+}
+function resolvePathValue(value, baseDir) {
+	if (!value) return void 0;
+	const expanded = expandHome(value);
+	return isAbsolute(expanded) ? resolve(expanded) : resolve(baseDir, expanded);
+}
+function parseLoopCliFlags(argv) {
+	const flags = { noStopOnFailure: false };
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === void 0) continue;
+		if (arg.startsWith("--repo=")) {
+			flags.repo = arg.slice(7);
+			continue;
+		}
+		if (arg === "--repo") {
+			const value = argv[index + 1];
+			if (!value) throw new Error("Missing value for --repo");
+			flags.repo = value;
+			index += 1;
+			continue;
+		}
+		if (arg.startsWith("--plan=")) {
+			flags.plan = arg.slice(7);
+			continue;
+		}
+		if (arg === "--plan") {
+			const value = argv[index + 1];
+			if (!value) throw new Error("Missing value for --plan");
+			flags.plan = value;
+			index += 1;
+			continue;
+		}
+		if (arg.startsWith("--goal=")) {
+			flags.goal = arg.slice(7);
+			continue;
+		}
+		if (arg === "--goal") {
+			const value = argv[index + 1];
+			if (!value) throw new Error("Missing value for --goal");
+			flags.goal = value;
+			index += 1;
+			continue;
+		}
+		if (arg.startsWith("--max-iterations=")) {
+			flags.maxIterations = Number.parseInt(arg.slice(17), 10);
+			continue;
+		}
+		if (arg === "--max-iterations") {
+			const value = argv[index + 1];
+			if (!value) throw new Error("Missing value for --max-iterations");
+			flags.maxIterations = Number.parseInt(value, 10);
+			index += 1;
+			continue;
+		}
+		if (arg.startsWith("--max-time=")) {
+			flags.maxTime = Number.parseInt(arg.slice(11), 10);
+			continue;
+		}
+		if (arg === "--max-time") {
+			const value = argv[index + 1];
+			if (!value) throw new Error("Missing value for --max-time");
+			flags.maxTime = Number.parseInt(value, 10);
+			index += 1;
+			continue;
+		}
+		if (arg === "--no-stop-on-failure") {
+			flags.noStopOnFailure = true;
+			continue;
+		}
+		throw new Error(`Unknown argument: ${arg}`);
+	}
+	return flags;
+}
+function loadUserConfig() {
+	const configPath = getUserConfigPath();
+	if (!existsSync(configPath)) return {};
+	return JSON.parse(readFileSync(configPath, "utf-8"));
+}
+function resolveLoopConfig(argv) {
+	const flags = parseLoopCliFlags(argv);
+	const configPath = getUserConfigPath();
+	const userConfig = loadUserConfig();
+	const configDir = dirname(configPath);
+	return {
+		repo: resolvePathValue(flags.repo, process.cwd()) ?? resolvePathValue(userConfig.repo, configDir) ?? resolve(process.cwd()),
+		plan: resolvePathValue(flags.plan, process.cwd()) ?? resolvePathValue(userConfig.plan, configDir) ?? null,
+		goal: flags.goal ?? userConfig.goal ?? DEFAULT_GOAL,
+		maxIterations: flags.maxIterations ?? DEFAULT_MAX_ITERATIONS,
+		maxTimeMinutes: flags.maxTime ?? DEFAULT_MAX_TIME_MINUTES,
+		stopOnPiFailure: !flags.noStopOnFailure
+	};
+}
+
+//#endregion
+//#region src/loop.ts
+function assertDirectory(path, label) {
+	if (!existsSync(path)) throw new Error(`${label} does not exist: ${path}`);
+	if (!statSync(path).isDirectory()) throw new Error(`${label} is not a directory: ${path}`);
+}
+function formatMs(ms) {
+	if (ms < 1e3) return `${ms}ms`;
+	return `${(ms / 1e3).toFixed(1)}s`;
+}
+function loopTown(argv = process.argv.slice(2)) {
+	const config = resolveLoopConfig(argv);
+	assertDirectory(config.repo, "Target repo");
+	if (config.plan) assertDirectory(config.plan, "Plan path");
+	mkdirSync(getTownHomeDir(), { recursive: true });
+	const repoRoot = getRepoRoot(config.repo);
+	const repoSlug = createRepoSlug(getRepoIdentity(repoRoot), repoRoot);
+	const recommendedPlanDir = config.plan ? null : getRecommendedPlanDir(repoSlug);
+	const artifactsDir = getRepoArtifactsDir(repoSlug);
+	console.log(`[pitown-loop] starting loop (max ${config.maxIterations} iterations, ${config.maxTimeMinutes}min wall time)`);
+	const result = runLoop({
+		runOptions: {
+			artifactsDir,
+			cwd: repoRoot,
+			goal: config.goal,
+			mode: "single-pi",
+			planPath: config.plan,
+			recommendedPlanDir,
+			appendedSystemPrompt: readPiTownMayorPrompt(),
+			extensionPath: resolvePiTownExtensionPath()
+		},
+		maxIterations: config.maxIterations,
+		maxWallTimeMs: config.maxTimeMinutes * 6e4,
+		stopOnPiFailure: config.stopOnPiFailure,
+		onIterationComplete(iteration) {
+			const board = iteration.boardSnapshot;
+			const taskSummary = board.tasks.length > 0 ? `${board.tasks.length} tasks (${board.tasks.filter((t) => t.status === "completed").length} completed, ${board.tasks.filter((t) => t.status === "running").length} running)` : "no tasks tracked";
+			const mayorStatus = board.agents.find((a) => a.agentId === "mayor")?.status ?? "unknown";
+			console.log(`[pitown-loop] iteration ${iteration.iteration}/${config.maxIterations} completed (${formatMs(iteration.elapsedMs)})`);
+			console.log(`  - pi exit code: ${iteration.controllerResult.piInvocation.exitCode}`);
+			console.log(`  - run: ${iteration.controllerResult.runId}`);
+			console.log(`  - board: ${taskSummary}, mayor ${mayorStatus}`);
+			console.log(`  - metrics: interrupt rate ${iteration.metrics.interruptRate}, autonomous completion ${iteration.metrics.autonomousCompletionRate}`);
+			if (iteration.stopReason) console.log(`  - stopping: ${iteration.stopReason}`);
+			else console.log(`  - continuing: ${iteration.continueReason}`);
+		}
+	});
+	console.log(`[pitown-loop] stopped after ${result.totalIterations} iteration${result.totalIterations === 1 ? "" : "s"} (${formatMs(result.totalElapsedMs)} total)`);
+	console.log(`  - reason: ${result.stopReason}`);
+	console.log(`  - aggregate metrics: interrupt rate ${result.aggregateMetrics.interruptRate}, autonomous completion ${result.aggregateMetrics.autonomousCompletionRate}`);
+	return result;
+}
+
+//#endregion
+//#region src/mayor.ts
+function startFreshMayorSession(repoRoot, artifactsDir) {
+	const sessionDir = getAgentSessionsDir(artifactsDir, "mayor");
+	writeAgentState(artifactsDir, createAgentState({
+		agentId: "mayor",
+		role: "mayor",
+		status: "running",
+		task: "open the mayor session and plan the next steps for this repository",
+		lastMessage: "Mayor session opened",
+		session: createAgentSessionRecord({ sessionDir })
+	}));
+	console.log("[pitown] mayor");
+	console.log(`- repo root: ${repoRoot}`);
+	console.log("- starting a new mayor session");
+	const exitCode = runCommandInteractive("pi", createPiTownRuntimeArgs({
+		agentId: "mayor",
+		sessionDir
+	}), {
+		cwd: repoRoot,
+		env: process.env
+	});
+	const latestSession = getLatestAgentSession(artifactsDir, "mayor");
+	const previousState = readAgentState(artifactsDir, "mayor");
+	if (previousState !== null) writeAgentState(artifactsDir, createAgentState({
+		...previousState,
+		status: exitCode === 0 ? "idle" : "blocked",
+		lastMessage: exitCode === 0 ? "Mayor session closed" : `Mayor session exited with code ${exitCode}`,
+		blocked: exitCode !== 0,
+		waitingOn: exitCode === 0 ? null : "human-or-follow-up-run",
+		session: createAgentSessionRecord({
+			sessionDir: latestSession.sessionDir,
+			sessionId: latestSession.sessionId,
+			sessionPath: latestSession.sessionPath
+		})
+	}));
+	if (exitCode !== 0) process.exitCode = exitCode;
+}
+function openTownMayor(argv = process.argv.slice(2)) {
+	const repo = resolveRepoContext(argv);
+	const message = repo.rest.join(" ").trim();
+	if (readAgentState(repo.artifactsDir, "mayor") === null) {
+		assertCommandAvailable("pi");
+		if (message) {
+			runTown([
+				"--repo",
+				repo.repoRoot,
+				"--goal",
+				message
+			]);
+			return;
+		}
+		startFreshMayorSession(repo.repoRoot, repo.artifactsDir);
+		return;
+	}
+	if (message) {
+		continueTownAgent([
+			"--repo",
+			repo.repoRoot,
+			"mayor",
+			message
+		]);
+		return;
+	}
+	attachTownAgent([
+		"--repo",
+		repo.repoRoot,
+		"mayor"
+	]);
+}
+
+//#endregion
+//#region src/msg.ts
+function messageTownAgent(argv = process.argv.slice(2)) {
+	const repo = resolveRepoContext(argv);
+	const [agentArg, ...messageParts] = repo.rest;
+	if (!agentArg || messageParts.length === 0) throw new Error("Usage: pitown msg [--repo <path>] <agent> \"message\"");
+	const agentId = normalizeAgentId(agentArg);
+	const state = readAgentState(repo.artifactsDir, agentId);
+	if (state === null) throw new Error(`Unknown agent: ${agentId}`);
+	const body = messageParts.join(" ").trim();
+	queueAgentMessage({
+		artifactsDir: repo.artifactsDir,
+		agentId,
+		from: "human",
+		body
+	});
+	const deliveredResult = state.role === "mayor" ? runAgentTurn({
+		repoRoot: repo.repoRoot,
+		artifactsDir: repo.artifactsDir,
+		agentId,
+		message: body,
+		from: "human",
+		runtimeArgs: createPiTownRuntimeArgs({
+			agentId,
+			sessionPath: state.session.sessionPath,
+			prompt: body
+		})
+	}) : null;
+	console.log("[pitown] msg");
+	console.log(`- repo root: ${repo.repoRoot}`);
+	console.log(`- agent: ${agentId}`);
+	console.log(`- queued message: ${body}`);
+	if (deliveredResult) {
+		console.log(`- delivered to session: ${deliveredResult.latestSession.sessionPath}`);
+		console.log(`- mayor response: ${deliveredResult.completionMessage}`);
+	}
+}
+
+//#endregion
+//#region src/peek.ts
+function printMessages(label, lines) {
+	console.log(`- ${label}:`);
+	if (lines.length === 0) {
+		console.log("  (empty)");
+		return;
+	}
+	for (const line of lines) console.log(`  ${line.createdAt} ${line.from}: ${line.body}`);
+}
+function peekTownAgent(argv = process.argv.slice(2)) {
+	const repo = resolveRepoContext(argv);
+	const [agentArg] = repo.rest;
+	const agentId = normalizeAgentId(agentArg ?? "mayor");
+	const state = readAgentState(repo.artifactsDir, agentId);
+	if (state === null) throw new Error(`Unknown agent: ${agentId}`);
+	console.log("[pitown] peek");
+	console.log(`- repo root: ${repo.repoRoot}`);
+	console.log(`- agent: ${state.agentId}`);
+	console.log(`- role: ${state.role}`);
+	console.log(`- status: ${state.status}`);
+	if (state.taskId) console.log(`- task id: ${state.taskId}`);
+	if (state.task) console.log(`- task: ${state.task}`);
+	if (state.branch) console.log(`- branch: ${state.branch}`);
+	console.log(`- blocked: ${state.blocked}`);
+	if (state.waitingOn) console.log(`- waiting on: ${state.waitingOn}`);
+	if (state.lastMessage) console.log(`- last message: ${state.lastMessage}`);
+	if (state.session.sessionId) console.log(`- session id: ${state.session.sessionId}`);
+	if (state.session.sessionPath) console.log(`- session path: ${state.session.sessionPath}`);
+	console.log(`- updated at: ${state.updatedAt}`);
+	printMessages("recent inbox", readAgentMessages(repo.artifactsDir, agentId, "inbox").slice(-5));
+	printMessages("recent outbox", readAgentMessages(repo.artifactsDir, agentId, "outbox").slice(-5));
+}
+
+//#endregion
+//#region src/spawn.ts
+function parseSpawnFlags(argv) {
+	let role = null;
+	let agentId = null;
+	let task = null;
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === void 0) continue;
+		if (arg.startsWith("--role=")) {
+			role = arg.slice(7);
+			continue;
+		}
+		if (arg === "--role") {
+			role = argv[index + 1] ?? null;
+			index += 1;
+			continue;
+		}
+		if (arg.startsWith("--agent=")) {
+			agentId = arg.slice(8);
+			continue;
+		}
+		if (arg === "--agent") {
+			agentId = argv[index + 1] ?? null;
+			index += 1;
+			continue;
+		}
+		if (arg.startsWith("--task=")) {
+			task = arg.slice(7);
+			continue;
+		}
+		if (arg === "--task") {
+			task = argv[index + 1] ?? null;
+			index += 1;
+			continue;
+		}
+		throw new Error(`Unknown argument: ${arg}`);
+	}
+	if (!role) throw new Error("Usage: pitown spawn [--repo <path>] --role <role> [--agent <id>] [--task <text>]");
+	return {
+		role,
+		agentId,
+		task
+	};
+}
+function spawnAgent(options) {
+	return spawnAgentRun(options);
+}
+function spawnTownAgent(argv = process.argv.slice(2)) {
+	const repo = resolveRepoContext(argv);
+	const flags = parseSpawnFlags(repo.rest);
+	const agentId = flags.agentId ?? `${flags.role}-${Date.now()}`;
+	const task = flags.task;
+	const { launch, latestSession } = spawnAgent({
+		repoRoot: repo.repoRoot,
+		artifactsDir: repo.artifactsDir,
+		role: flags.role,
+		agentId,
+		task,
+		extensionPath: resolvePiTownExtensionPath()
+	});
+	console.log("[pitown] spawn");
+	console.log(`- repo root: ${repo.repoRoot}`);
+	console.log(`- agent: ${agentId}`);
+	console.log(`- role: ${flags.role}`);
+	console.log(`- status: running`);
+	console.log(`- launch pid: ${launch.processId}`);
+	if (task) console.log(`- task: ${task}`);
+	if (latestSession.sessionPath) console.log(`- session: ${latestSession.sessionPath}`);
+	else if (latestSession.sessionDir) console.log(`- session dir: ${latestSession.sessionDir}`);
+}
+
+//#endregion
+//#region src/stop.ts
+function parseStopFlags(argv) {
+	let all = false;
+	let agentId = null;
+	let force = false;
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === void 0) continue;
+		if (arg === "--all") {
+			all = true;
+			continue;
+		}
+		if (arg === "--force") {
+			force = true;
+			continue;
+		}
+		if (arg.startsWith("--agent=")) {
+			agentId = normalizeAgentId(arg.slice(8));
+			continue;
+		}
+		if (arg === "--agent") {
+			const value = argv[index + 1];
+			if (!value) throw new Error("Missing value for --agent");
+			agentId = normalizeAgentId(value);
+			index += 1;
+			continue;
+		}
+		throw new Error(`Unknown argument: ${arg}`);
+	}
+	return {
+		all,
+		agentId,
+		force
+	};
+}
+function stopRepo(repoRoot, artifactsDir, flags) {
+	const repoId = getRepoIdentity(repoRoot);
+	const leaseResult = flags.agentId ? { signaledProcesses: 0 } : stopRepoLeases({
+		repoId,
+		force: flags.force
+	});
+	const agentResult = stopManagedAgents({
+		artifactsDir,
+		agentId: flags.agentId,
+		actorId: "human",
+		reason: flags.agentId ? `Stopped ${flags.agentId} via pitown stop` : "Stopped via pitown stop",
+		force: flags.force
+	});
+	return {
+		repoLabel: repoRoot,
+		stoppedAgents: agentResult.stoppedAgents,
+		signaledAgentProcesses: agentResult.signaledProcesses,
+		signaledLeaseProcesses: leaseResult.signaledProcesses
+	};
+}
+function listTrackedArtifactsDirs() {
+	const reposRoot = getReposRootDir();
+	if (!existsSync(reposRoot)) return [];
+	return readdirSync(reposRoot).map((entry) => getRepoArtifactsDir(entry)).filter((path) => existsSync(path));
+}
+function stopTown(argv = process.argv.slice(2)) {
+	const { repo, rest } = parseOptionalRepoFlag(argv);
+	const flags = parseStopFlags(rest);
+	if (flags.all && repo) throw new Error("Do not combine --all with --repo");
+	if (flags.all && flags.agentId) throw new Error("Do not combine --all with --agent");
+	if (flags.all) {
+		const repoSummaries = listTrackedArtifactsDirs().map((artifactsDir) => {
+			const result = stopManagedAgents({
+				artifactsDir,
+				actorId: "human",
+				reason: "Stopped via pitown stop --all",
+				force: flags.force
+			});
+			return {
+				repoLabel: artifactsDir,
+				stoppedAgents: result.stoppedAgents,
+				signaledAgentProcesses: result.signaledProcesses,
+				signaledLeaseProcesses: 0
+			};
+		});
+		const leaseResult = stopRepoLeases({ force: flags.force });
+		const totalAgents = repoSummaries.reduce((sum, result) => sum + result.stoppedAgents, 0);
+		const totalAgentProcesses = repoSummaries.reduce((sum, result) => sum + result.signaledAgentProcesses, 0);
+		const totalLeaseProcesses = leaseResult.signaledProcesses + repoSummaries.reduce((sum, result) => sum + result.signaledLeaseProcesses, 0);
+		console.log("[pitown] stop");
+		console.log("- scope: all repos");
+		console.log(`- stopped agents: ${totalAgents}`);
+		console.log(`- signaled agent processes: ${totalAgentProcesses}`);
+		console.log(`- signaled lease processes: ${totalLeaseProcesses}`);
+		if (repoSummaries.length === 0 && leaseResult.results.length === 0) console.log("- nothing was running");
+		return repoSummaries;
+	}
+	const resolved = repo ? resolveRepoContext(["--repo", repo]) : resolveRepoContext([]);
+	const result = stopRepo(resolved.repoRoot, resolved.artifactsDir, flags);
+	console.log("[pitown] stop");
+	console.log(`- repo root: ${result.repoLabel}`);
+	if (flags.agentId) console.log(`- agent: ${flags.agentId}`);
+	console.log(`- stopped agents: ${result.stoppedAgents}`);
+	console.log(`- signaled agent processes: ${result.signaledAgentProcesses}`);
+	if (!flags.agentId) console.log(`- signaled lease processes: ${result.signaledLeaseProcesses}`);
+	if (result.stoppedAgents === 0 && result.signaledAgentProcesses === 0 && result.signaledLeaseProcesses === 0) console.log("- nothing was running");
+	return [result];
+}
+
+//#endregion
+//#region src/version.ts
+const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+const CLI_VERSION = packageJson.version;
+
+//#endregion
 //#region src/index.ts
-function printHelp() {
+function printHelp(showAdvanced = false) {
 	console.log([
 		"pitown",
 		"",
 		"Usage:",
-		"  pitown run [--repo <path>] [--plan <path>] [--goal <text>]",
+		"  pitown [--repo <path>] [\"message\"]",
+		"  pitown board [--repo <path>]",
+		"  pitown peek [--repo <path>] [agent]",
+		"  pitown msg [--repo <path>] <agent> \"message\"",
 		"  pitown status [--repo <path>]",
-		"  pitown watch [--repo <path>]",
-		"  pitown help",
-		"  pitown --help"
+		"  pitown stop [--repo <path>] [--agent <id>] [--all] [--force]",
+		"  pitown doctor",
+		"  pitown --version",
+		"",
+		"Mayor workflow:",
+		"  pitown",
+		"  pitown \"plan the next milestones\"",
+		"  /plan",
+		"  /todos",
+		"",
+		"Inside the mayor session, `/plan` toggles read-only planning mode and `/todos` shows the captured plan.",
+		"Aliases still work: `pitown mayor`, `pitown help`, `pitown --help`, `pitown -v`.",
+		"",
+		"If --repo is omitted, Pi Town uses the repo for the current working directory when possible.",
+		...showAdvanced ? [
+			"",
+			"Advanced commands:",
+			"  pitown run [--repo <path>] [--plan <path>] [--goal <text>]",
+			"  pitown loop [--repo <path>] [--plan <path>] [--goal <text>] [--max-iterations N] [--max-time M] [--no-stop-on-failure]",
+			"  pitown attach [--repo <path>] <agent>",
+			"  pitown continue [--repo <path>] <agent> [\"message\"]",
+			"  pitown delegate [--repo <path>] [--from <agent>] [--role <role>] [--agent <id>] --task <text>",
+			"  pitown spawn [--repo <path>] --role <role> [--agent <id>] [--task <text>]",
+			"  pitown watch [--repo <path>]"
+		] : []
 	].join("\n"));
 }
 function runCli(argv = process.argv.slice(2)) {
 	const [command, ...args] = argv;
+	const showAdvancedHelp = args.includes("--all");
 	switch (command) {
 		case void 0:
+			openTownMayor([]);
+			break;
 		case "help":
 		case "--help":
 		case "-h":
-			printHelp();
+			printHelp(showAdvancedHelp);
+			break;
+		case "-v":
+		case "--version":
+		case "version":
+			console.log(CLI_VERSION);
 			break;
 		case "run": {
 			const result = runTown(args);
-			if (result.piInvocation.exitCode !== 0) process.exitCode = result.piInvocation.exitCode;
+			const latestIteration = result.iterations[result.iterations.length - 1];
+			if (latestIteration && latestIteration.controllerResult.piInvocation.exitCode !== 0) process.exitCode = latestIteration.controllerResult.piInvocation.exitCode;
+			break;
+		}
+		case "loop": {
+			const result = loopTown(args);
+			const lastIteration = result.iterations[result.iterations.length - 1];
+			if (lastIteration && lastIteration.controllerResult.piInvocation.exitCode !== 0) process.exitCode = lastIteration.controllerResult.piInvocation.exitCode;
 			break;
 		}
+		case "attach":
+			attachTownAgent(args);
+			break;
+		case "board":
+			showTownBoard(args);
+			break;
+		case "continue":
+			continueTownAgent(args);
+			break;
+		case "delegate":
+			delegateTownTask(args);
+			break;
+		case "mayor":
+			openTownMayor(args);
+			break;
+		case "msg":
+			messageTownAgent(args);
+			break;
+		case "peek":
+			peekTownAgent(args);
+			break;
+		case "spawn":
+			spawnTownAgent(args);
+			break;
 		case "status":
 			showTownStatus(args);
 			break;
+		case "stop":
+			stopTown(args);
+			break;
 		case "watch":
 			watchTown(args);
 			break;
+		case "doctor":
+			if (!runDoctor().ok) process.exitCode = 1;
+			break;
 		default:
 			console.log(`Unknown command: ${command}`);
 			printHelp();