@schilderlabs/pitown 0.2.1 → 0.2.7

package/dist/index.mjs

@@ -1,293 +1,21 @@
 #!/usr/bin/env node
-import { a as createAgentState, c as getLatestAgentSession, d as readAgentState, f as writeAgentState, i as createAgentSessionRecord, l as listAgentStates, n as computeMetrics, o as getAgentDir, p as appendJsonl, r as appendAgentMessage, s as getAgentSessionsDir, t as runController, u as readAgentMessages } from "./controller-9ihAZj3V.mjs";
-import { a as runCommandSync, i as runCommandInteractive, n as assertCommandAvailable, t as isDirectExecution } from "./entrypoint-CyJDLudQ.mjs";
-import { a as getRecommendedPlanDir, d as createRepoSlug, h as isGitRepo, i as getLatestRunPointerPath, l as getTownHomeDir, m as getRepoRoot, n as parseOptionalRepoFlag, o as getRepoAgentsDir, p as getRepoIdentity, s as getRepoArtifactsDir, u as getUserConfigPath } from "./config-CUpe9o0x.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 { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
-import { homedir } from "node:os";
+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, hostname } from "node:os";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import { readPiTownMayorPrompt, resolvePiTownExtensionPath } from "@schilderlabs/pitown-package";
 
-//#region ../core/src/tasks.ts
-function writeJson$1(path, value) {
-	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
-}
-function getTasksDir(artifactsDir) {
-	return join(artifactsDir, "tasks");
-}
-function getTaskPath(artifactsDir, taskId) {
-	return join(getTasksDir(artifactsDir), `${taskId}.json`);
-}
-function createTaskRecord(input) {
-	const now = (/* @__PURE__ */ new Date()).toISOString();
-	return {
-		taskId: input.taskId,
-		title: input.title,
-		status: input.status,
-		role: input.role,
-		assignedAgentId: input.assignedAgentId,
-		createdBy: input.createdBy,
-		createdAt: now,
-		updatedAt: now
-	};
-}
-function writeTaskRecord(artifactsDir, task) {
-	writeJson$1(getTaskPath(artifactsDir, task.taskId), task);
-}
-function readTaskRecord(artifactsDir, taskId) {
-	const path = getTaskPath(artifactsDir, taskId);
-	try {
-		return JSON.parse(readFileSync(path, "utf-8"));
-	} catch {
-		return null;
-	}
-}
-function listTaskRecords(artifactsDir) {
-	const tasksDir = getTasksDir(artifactsDir);
-	let entries;
-	try {
-		entries = readdirSync(tasksDir);
-	} catch {
-		return [];
-	}
-	return entries.filter((entry) => entry.endsWith(".json")).map((entry) => readTaskRecord(artifactsDir, entry.replace(/\.json$/, ""))).filter((task) => task !== null).sort((left, right) => left.taskId.localeCompare(right.taskId));
-}
-
-//#endregion
-//#region ../core/src/loop.ts
-const DEFAULT_MAX_ITERATIONS$1 = 10;
-const DEFAULT_MAX_WALL_TIME_MS = 36e5;
-function createLoopId() {
-	return `loop-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`;
-}
-function writeJson(path, value) {
-	writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
-}
-function snapshotBoard(artifactsDir) {
-	const tasks = listTaskRecords(artifactsDir);
-	const agents = listAgentStates(artifactsDir);
-	return {
-		tasks: tasks.map((task) => ({
-			taskId: task.taskId,
-			status: task.status
-		})),
-		agents: agents.map((agent) => ({
-			agentId: agent.agentId,
-			status: agent.status,
-			blocked: agent.blocked
-		})),
-		allTasksCompleted: tasks.length > 0 && tasks.every((task) => task.status === "completed"),
-		allRemainingTasksBlocked: tasks.length > 0 && tasks.every((task) => task.status === "completed" || task.status === "blocked"),
-		leaderBlocked: agents.find((agent) => agent.agentId === "leader")?.blocked === true,
-		hasQueuedOrRunningWork: agents.some((agent) => agent.status === "queued" || agent.status === "running" || agent.status === "starting") || tasks.some((task) => task.status === "queued" || task.status === "running")
-	};
-}
-function evaluateStopCondition(input) {
-	if (input.iteration >= input.maxIterations) return {
-		stopReason: "max-iterations-reached",
-		continueReason: null
-	};
-	if (input.elapsedMs >= input.maxWallTimeMs) return {
-		stopReason: "max-wall-time-reached",
-		continueReason: null
-	};
-	if (input.stopOnPiFailure && input.piExitCode !== 0) return {
-		stopReason: "pi-exit-nonzero",
-		continueReason: null
-	};
-	if (input.board.allTasksCompleted) return {
-		stopReason: "all-tasks-completed",
-		continueReason: null
-	};
-	if (input.board.leaderBlocked) return {
-		stopReason: "leader-blocked",
-		continueReason: null
-	};
-	if (input.board.allRemainingTasksBlocked) return {
-		stopReason: "all-remaining-tasks-blocked",
-		continueReason: null
-	};
-	if (input.interruptRateThreshold !== null && input.metrics.interruptRate > input.interruptRateThreshold) return {
-		stopReason: "high-interrupt-rate",
-		continueReason: null
-	};
-	const reasons = [];
-	if (input.board.hasQueuedOrRunningWork) reasons.push("queued or running work remains");
-	if (input.board.tasks.length === 0) reasons.push("no tasks tracked yet");
-	if (reasons.length === 0) reasons.push("leader idle, no stop condition met");
-	return {
-		stopReason: null,
-		continueReason: reasons.join("; ")
-	};
-}
-function aggregateMetrics(iterations) {
-	if (iterations.length === 0) return computeMetrics({
-		taskAttempts: [],
-		interrupts: []
-	});
-	let totalTaskAttempts = 0;
-	let totalCompletedTasks = 0;
-	let totalInterrupts = 0;
-	let totalObservedInterruptCategories = 0;
-	let totalCoveredInterruptCategories = 0;
-	let interruptRateSum = 0;
-	let autonomousCompletionRateSum = 0;
-	let contextCoverageScoreSum = 0;
-	let mttcValues = [];
-	let ftdValues = [];
-	for (const iter of iterations) {
-		const m = iter.metrics;
-		totalTaskAttempts += m.totals.taskAttempts;
-		totalCompletedTasks += m.totals.completedTasks;
-		totalInterrupts += m.totals.interrupts;
-		totalObservedInterruptCategories += m.totals.observedInterruptCategories;
-		totalCoveredInterruptCategories += m.totals.coveredInterruptCategories;
-		interruptRateSum += m.interruptRate;
-		autonomousCompletionRateSum += m.autonomousCompletionRate;
-		contextCoverageScoreSum += m.contextCoverageScore;
-		if (m.meanTimeToCorrectHours !== null) mttcValues.push(m.meanTimeToCorrectHours);
-		if (m.feedbackToDemoCycleTimeHours !== null) ftdValues.push(m.feedbackToDemoCycleTimeHours);
-	}
-	const count = iterations.length;
-	const round = (v) => Math.round(v * 1e3) / 1e3;
-	const avg = (values) => values.length === 0 ? null : round(values.reduce((s, v) => s + v, 0) / values.length);
-	return {
-		interruptRate: round(interruptRateSum / count),
-		autonomousCompletionRate: round(autonomousCompletionRateSum / count),
-		contextCoverageScore: round(contextCoverageScoreSum / count),
-		meanTimeToCorrectHours: avg(mttcValues),
-		feedbackToDemoCycleTimeHours: avg(ftdValues),
-		totals: {
-			taskAttempts: totalTaskAttempts,
-			completedTasks: totalCompletedTasks,
-			interrupts: totalInterrupts,
-			observedInterruptCategories: totalObservedInterruptCategories,
-			coveredInterruptCategories: totalCoveredInterruptCategories
-		}
-	};
-}
-function runLoop(options) {
-	const maxIterations = options.maxIterations ?? DEFAULT_MAX_ITERATIONS$1;
-	const maxWallTimeMs = options.maxWallTimeMs ?? DEFAULT_MAX_WALL_TIME_MS;
-	const stopOnPiFailure = options.stopOnPiFailure ?? true;
-	const interruptRateThreshold = options.interruptRateThreshold ?? null;
-	const loopId = createLoopId();
-	const artifactsDir = options.runOptions.artifactsDir;
-	const loopDir = join(artifactsDir, "loops", loopId);
-	mkdirSync(loopDir, { recursive: true });
-	const loopStartedAt = Date.now();
-	const iterations = [];
-	let finalStopReason = "max-iterations-reached";
-	appendJsonl(join(loopDir, "events.jsonl"), {
-		type: "loop_started",
-		loopId,
-		maxIterations,
-		maxWallTimeMs,
-		stopOnPiFailure,
-		createdAt: (/* @__PURE__ */ new Date()).toISOString()
-	});
-	for (let iteration = 1; iteration <= maxIterations; iteration++) {
-		const iterationStart = Date.now();
-		let controllerResult;
-		try {
-			controllerResult = runController(options.runOptions);
-		} catch (error) {
-			appendJsonl(join(loopDir, "events.jsonl"), {
-				type: "loop_iteration_error",
-				loopId,
-				iteration,
-				error: error.message,
-				createdAt: (/* @__PURE__ */ new Date()).toISOString()
-			});
-			finalStopReason = "pi-exit-nonzero";
-			break;
-		}
-		const iterationElapsedMs = Date.now() - iterationStart;
-		const totalElapsedMs = Date.now() - loopStartedAt;
-		const board = snapshotBoard(artifactsDir);
-		const metrics = controllerResult.metrics;
-		const { stopReason, continueReason } = evaluateStopCondition({
-			iteration,
-			maxIterations,
-			elapsedMs: totalElapsedMs,
-			maxWallTimeMs,
-			piExitCode: controllerResult.piInvocation.exitCode,
-			stopOnPiFailure,
-			board,
-			metrics,
-			interruptRateThreshold
-		});
-		const iterationResult = {
-			iteration,
-			controllerResult,
-			boardSnapshot: board,
-			metrics,
-			elapsedMs: iterationElapsedMs,
-			continueReason,
-			stopReason
-		};
-		iterations.push(iterationResult);
-		writeJson(join(loopDir, `iteration-${iteration}.json`), {
-			iteration,
-			runId: controllerResult.runId,
-			boardSnapshot: board,
-			metrics,
-			elapsedMs: iterationElapsedMs,
-			continueReason,
-			stopReason
-		});
-		appendJsonl(join(loopDir, "events.jsonl"), {
-			type: "loop_iteration_completed",
-			loopId,
-			iteration,
-			runId: controllerResult.runId,
-			piExitCode: controllerResult.piInvocation.exitCode,
-			stopReason,
-			continueReason,
-			createdAt: (/* @__PURE__ */ new Date()).toISOString()
-		});
-		if (options.onIterationComplete) options.onIterationComplete(iterationResult);
-		if (stopReason !== null) {
-			finalStopReason = stopReason;
-			break;
-		}
-	}
-	const totalElapsedMs = Date.now() - loopStartedAt;
-	const finalBoard = iterations.length > 0 ? iterations[iterations.length - 1].boardSnapshot : snapshotBoard(artifactsDir);
-	const aggregate = aggregateMetrics(iterations);
-	const loopResult = {
-		loopId,
-		iterations,
-		stopReason: finalStopReason,
-		totalIterations: iterations.length,
-		totalElapsedMs,
-		finalBoardSnapshot: finalBoard,
-		aggregateMetrics: aggregate
-	};
-	writeJson(join(loopDir, "loop-summary.json"), {
-		loopId,
-		stopReason: finalStopReason,
-		totalIterations: iterations.length,
-		totalElapsedMs,
-		finalBoardSnapshot: finalBoard,
-		aggregateMetrics: aggregate
-	});
-	appendJsonl(join(loopDir, "events.jsonl"), {
-		type: "loop_finished",
-		loopId,
-		stopReason: finalStopReason,
-		totalIterations: iterations.length,
-		totalElapsedMs,
-		createdAt: (/* @__PURE__ */ new Date()).toISOString()
-	});
-	return loopResult;
-}
-
-//#endregion
 //#region ../core/src/orchestration.ts
 function createPiInvocationArgs(input) {
 	const args = [];
@@ -299,11 +27,29 @@ function createPiInvocationArgs(input) {
 	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 "leader": return [
-			"You are the Pi Town leader.",
+		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}`,
@@ -350,6 +96,7 @@ function resolveAgentSession(agentId, artifactsDir) {
 			sessionDir,
 			sessionId,
 			sessionPath,
+			processId: state.session.processId,
 			lastAttachedAt: (/* @__PURE__ */ new Date()).toISOString()
 		})
 	};
@@ -374,6 +121,7 @@ function queueAgentMessage(input) {
 			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
 		})
 	}));
@@ -414,46 +162,42 @@ function spawnAgentRun(options) {
 		appendedSystemPrompt: options.appendedSystemPrompt,
 		extensionPath: options.extensionPath
 	});
-	const piResult = runCommandSync("pi", piArgs, {
+	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,
+		autoResumeTarget: options.autoResumeTarget ?? null
+	}), "utf-8").toString("base64url"));
+	const child = spawn(runner.command, runner.args, {
 		cwd: options.repoRoot,
-		env: process.env
+		detached: true,
+		env: process.env,
+		stdio: "ignore"
 	});
-	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({
+	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: piResult.exitCode,
+		exitCode: null,
 		sessionDir,
-		sessionPath: latestSession.sessionPath,
-		sessionId: latestSession.sessionId
+		sessionPath: null,
+		sessionId: null,
+		processId: child.pid,
+		startedAt
 	}, null, 2)}\n`, "utf-8");
-	const completionMessage = piResult.stdout.trim() || (piResult.exitCode === 0 ? `${options.role} run completed` : `${options.role} run exited with code ${piResult.exitCode}`);
-	appendAgentMessage({
-		artifactsDir: options.artifactsDir,
-		agentId: options.agentId,
-		box: "outbox",
-		from: options.agentId,
-		body: completionMessage
-	});
-	writeAgentState(options.artifactsDir, createAgentState({
-		...state,
-		status: piResult.exitCode === 0 ? "idle" : "blocked",
-		lastMessage: completionMessage,
-		blocked: piResult.exitCode !== 0,
-		waitingOn: piResult.exitCode === 0 ? null : "human-or-follow-up-run",
-		session: createAgentSessionRecord({
-			sessionDir: latestSession.sessionDir,
-			sessionId: latestSession.sessionId,
-			sessionPath: latestSession.sessionPath
-		})
-	}));
 	return {
-		piResult,
-		latestSession,
-		completionMessage
+		launch: {
+			processId: child.pid,
+			startedAt
+		},
+		latestSession: createAgentSessionRecord({ sessionDir })
 	};
 }
 function runAgentTurn(options) {
@@ -505,7 +249,8 @@ function runAgentTurn(options) {
 		session: createAgentSessionRecord({
 			sessionDir: latestSession.sessionDir,
 			sessionId: latestSession.sessionId,
-			sessionPath: latestSession.sessionPath
+			sessionPath: latestSession.sessionPath,
+			processId: null
 		})
 	}));
 	return {
@@ -533,13 +278,14 @@ function delegateTask(options) {
 		from: options.fromAgentId,
 		body: `Delegated ${task.taskId} to ${agentId}: ${options.task}`
 	});
-	const { piResult, latestSession } = spawnAgentRun({
+	const { launch, latestSession } = spawnAgentRun({
 		repoRoot: options.repoRoot,
 		artifactsDir: options.artifactsDir,
 		role: options.role,
 		agentId,
 		appendedSystemPrompt: options.appendedSystemPrompt,
 		extensionPath: options.extensionPath,
+		autoResumeTarget: options.completionAutoResumeTarget,
 		task: options.task,
 		taskId: task.taskId
 	});
@@ -552,31 +298,198 @@ function delegateTask(options) {
 	});
 	writeTaskRecord(options.artifactsDir, {
 		...task,
-		status: piResult.exitCode === 0 ? "completed" : "blocked",
+		status: "running",
 		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
 	});
 	return {
 		task: {
 			...task,
-			status: piResult.exitCode === 0 ? "completed" : "blocked",
+			status: "running",
 			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
 		},
 		agentId,
-		piResult,
+		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 === "mayor" ? "leader" : agentId;
+	return agentId;
 }
 
 //#endregion
 //#region src/pi-runtime.ts
 function isMayorAgent(agentId) {
-	return agentId === "leader" || agentId === "mayor";
+	return agentId === "mayor";
 }
 function createPiTownRuntimeArgs(options) {
 	const args = ["--extension", resolvePiTownExtensionPath()];
@@ -589,46 +502,6 @@ function createPiTownRuntimeArgs(options) {
 	return args;
 }
 
-//#endregion
-//#region src/repo-context.ts
-function resolveRepoContext(argv) {
-	const { repo, rest } = parseOptionalRepoFlag(argv);
-	if (repo) {
-		const repoRoot = getRepoRoot(repo);
-		const repoSlug = createRepoSlug(getRepoIdentity(repoRoot), repoRoot);
-		return {
-			repoRoot,
-			repoSlug,
-			artifactsDir: getRepoArtifactsDir(repoSlug),
-			rest
-		};
-	}
-	const cwd = process.cwd();
-	const repoRoot = getRepoRoot(cwd);
-	const repoSlug = createRepoSlug(getRepoIdentity(repoRoot), repoRoot);
-	const artifactsDir = getRepoArtifactsDir(repoSlug);
-	if (isGitRepo(cwd) || existsSync(artifactsDir)) return {
-		repoRoot,
-		repoSlug,
-		artifactsDir,
-		rest
-	};
-	const latestPointerPath = getLatestRunPointerPath();
-	if (!existsSync(latestPointerPath)) return {
-		repoRoot,
-		repoSlug,
-		artifactsDir,
-		rest
-	};
-	const latest = JSON.parse(readFileSync(latestPointerPath, "utf-8"));
-	return {
-		repoRoot: latest.repoRoot,
-		repoSlug: latest.repoSlug,
-		artifactsDir: getRepoArtifactsDir(latest.repoSlug),
-		rest
-	};
-}
-
 //#endregion
 //#region src/attach.ts
 function attachTownAgent(argv = process.argv.slice(2)) {
@@ -658,23 +531,71 @@ function attachTownAgent(argv = process.argv.slice(2)) {
 
 //#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);
-	console.log("[pitown] board");
-	console.log(`- repo root: ${repo.repoRoot}`);
-	console.log(`- agents dir: ${getRepoAgentsDir(repo.repoSlug)}`);
-	if (agents.length === 0) {
-		console.log("- no agents found yet");
-		return;
+	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(", ")}`);
 	}
-	for (const agent of agents) {
-		const task = agent.task ?? "no active task";
-		const note = agent.lastMessage ? ` | ${agent.lastMessage}` : "";
-		const waitingOn = agent.waitingOn ? ` | waiting on: ${agent.waitingOn}` : "";
-		const taskId = agent.taskId ? ` [${agent.taskId}]` : "";
-		console.log(`${agent.agentId.padEnd(12)} ${agent.status.padEnd(8)} ${task}${taskId}${note}${waitingOn}`);
+	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
@@ -711,12 +632,13 @@ function continueTownAgent(argv = process.argv.slice(2)) {
 //#endregion
 //#region src/delegate.ts
 function parseDelegateFlags(argv) {
-	let from = "leader";
+	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;
@@ -768,14 +690,20 @@ function delegateTownTask(argv = process.argv.slice(2)) {
 	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, piResult, task } = delegateTask({
+	const { agentId, latestSession, launch, task } = delegateTask({
 		repoRoot: repo.repoRoot,
 		artifactsDir: repo.artifactsDir,
 		fromAgentId,
 		role: flags.role,
 		agentId: flags.agentId,
 		task: flags.task,
-		extensionPath: resolvePiTownExtensionPath()
+		extensionPath: resolvePiTownExtensionPath(),
+		completionAutoResumeTarget: fromAgentId === "mayor" ? {
+			agentId: "mayor",
+			message: "New agent check-ins arrived. Review the latest board and inbox updates, then decide the next bounded action.",
+			extensionPath: resolvePiTownExtensionPath(),
+			appendedSystemPrompt: readPiTownMayorPrompt()
+		} : null
 	});
 	console.log("[pitown] delegate");
 	console.log(`- repo root: ${repo.repoRoot}`);
@@ -783,8 +711,10 @@ function delegateTownTask(argv = process.argv.slice(2)) {
 	console.log(`- task id: ${task.taskId}`);
 	console.log(`- agent: ${agentId}`);
 	console.log(`- role: ${flags.role}`);
-	console.log(`- pi exit code: ${piResult.exitCode}`);
+	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
@@ -806,6 +736,7 @@ 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;
@@ -926,11 +857,11 @@ function loopTown(argv = process.argv.slice(2)) {
 		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 leaderStatus = board.agents.find((a) => a.agentId === "leader")?.status ?? "unknown";
+			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}, leader ${leaderStatus}`);
+			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}`);
@@ -945,10 +876,10 @@ function loopTown(argv = process.argv.slice(2)) {
 //#endregion
 //#region src/mayor.ts
 function startFreshMayorSession(repoRoot, artifactsDir) {
-	const sessionDir = getAgentSessionsDir(artifactsDir, "leader");
+	const sessionDir = getAgentSessionsDir(artifactsDir, "mayor");
 	writeAgentState(artifactsDir, createAgentState({
-		agentId: "leader",
-		role: "leader",
+		agentId: "mayor",
+		role: "mayor",
 		status: "running",
 		task: "open the mayor session and plan the next steps for this repository",
 		lastMessage: "Mayor session opened",
@@ -958,14 +889,14 @@ function startFreshMayorSession(repoRoot, artifactsDir) {
 	console.log(`- repo root: ${repoRoot}`);
 	console.log("- starting a new mayor session");
 	const exitCode = runCommandInteractive("pi", createPiTownRuntimeArgs({
-		agentId: "leader",
+		agentId: "mayor",
 		sessionDir
 	}), {
 		cwd: repoRoot,
 		env: process.env
 	});
-	const latestSession = getLatestAgentSession(artifactsDir, "leader");
-	const previousState = readAgentState(artifactsDir, "leader");
+	const latestSession = getLatestAgentSession(artifactsDir, "mayor");
+	const previousState = readAgentState(artifactsDir, "mayor");
 	if (previousState !== null) writeAgentState(artifactsDir, createAgentState({
 		...previousState,
 		status: exitCode === 0 ? "idle" : "blocked",
@@ -983,7 +914,7 @@ function startFreshMayorSession(repoRoot, artifactsDir) {
 function openTownMayor(argv = process.argv.slice(2)) {
 	const repo = resolveRepoContext(argv);
 	const message = repo.rest.join(" ").trim();
-	if (readAgentState(repo.artifactsDir, "leader") === null) {
+	if (readAgentState(repo.artifactsDir, "mayor") === null) {
 		assertCommandAvailable("pi");
 		if (message) {
 			runTown([
@@ -1029,7 +960,7 @@ function messageTownAgent(argv = process.argv.slice(2)) {
 		from: "human",
 		body
 	});
-	const deliveredResult = state.role === "leader" ? runAgentTurn({
+	const deliveredResult = state.role === "mayor" ? runAgentTurn({
 		repoRoot: repo.repoRoot,
 		artifactsDir: repo.artifactsDir,
 		agentId,
@@ -1047,7 +978,7 @@ function messageTownAgent(argv = process.argv.slice(2)) {
 	console.log(`- queued message: ${body}`);
 	if (deliveredResult) {
 		console.log(`- delivered to session: ${deliveredResult.latestSession.sessionPath}`);
-		console.log(`- leader response: ${deliveredResult.completionMessage}`);
+		console.log(`- mayor response: ${deliveredResult.completionMessage}`);
 	}
 }
 
@@ -1093,6 +1024,7 @@ function parseSpawnFlags(argv) {
 	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;
@@ -1137,7 +1069,7 @@ function spawnTownAgent(argv = process.argv.slice(2)) {
 	const flags = parseSpawnFlags(repo.rest);
 	const agentId = flags.agentId ?? `${flags.role}-${Date.now()}`;
 	const task = flags.task;
-	const { piResult, latestSession } = spawnAgent({
+	const { launch, latestSession } = spawnAgent({
 		repoRoot: repo.repoRoot,
 		artifactsDir: repo.artifactsDir,
 		role: flags.role,
@@ -1149,18 +1081,122 @@ function spawnTownAgent(argv = process.argv.slice(2)) {
 	console.log(`- repo root: ${repo.repoRoot}`);
 	console.log(`- agent: ${agentId}`);
 	console.log(`- role: ${flags.role}`);
-	console.log(`- pi exit code: ${piResult.exitCode}`);
+	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 package.json
-var version = "0.2.1";
+//#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 CLI_VERSION = version;
+const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+const CLI_VERSION = packageJson.version;
 
 //#endregion
 //#region src/index.ts
@@ -1169,27 +1205,23 @@ function printHelp(showAdvanced = false) {
 		"pitown",
 		"",
 		"Usage:",
-		"  pitown",
-		"  pitown mayor [--repo <path>] [\"message\"]",
+		"  pitown [--repo <path>] [\"message\"]",
 		"  pitown board [--repo <path>]",
 		"  pitown peek [--repo <path>] [agent]",
-		"  pitown msg [--repo <path>] mayor \"message\"",
+		"  pitown msg [--repo <path>] <agent> \"message\"",
 		"  pitown status [--repo <path>]",
+		"  pitown stop [--repo <path>] [--agent <id>] [--all] [--force]",
 		"  pitown doctor",
-		"  pitown help",
-		"  pitown help --all",
-		"  pitown --help",
-		"  pitown -v",
 		"  pitown --version",
 		"",
 		"Mayor workflow:",
 		"  pitown",
-		"  pitown mayor",
-		"  pitown mayor \"plan the next milestones\"",
+		"  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 ? [
@@ -1224,7 +1256,8 @@ function runCli(argv = process.argv.slice(2)) {
 			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": {
@@ -1260,6 +1293,9 @@ function runCli(argv = process.argv.slice(2)) {
 		case "status":
 			showTownStatus(args);
 			break;
+		case "stop":
+			stopTown(args);
+			break;
 		case "watch":
 			watchTown(args);
 			break;