@schilderlabs/pitown-package 0.2.1 → 0.2.6

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 //#region src/index.d.ts
-declare const bundledAgentNames: readonly ["leader", "supervisor", "scout", "planner", "worker", "reviewer", "docs-keeper"];
+declare const bundledAgentNames: readonly ["mayor", "supervisor", "scout", "planner", "worker", "reviewer", "docs-keeper"];
 declare const townPackageName = "@schilderlabs/pitown-package";
 declare function resolvePiTownPackageRoot(): string;
 declare function resolvePiTownExtensionPath(): string;

package/dist/index.mjs

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 
 //#region src/index.ts
 const bundledAgentNames = [
-	"leader",
+	"mayor",
 	"supervisor",
 	"scout",
 	"planner",
@@ -23,7 +23,7 @@ function resolvePiTownExtensionPath() {
 	return join(resolvePackageRoot(), "pi", "extensions", "index.ts");
 }
 function resolvePiTownMayorPromptPath() {
-	return join(resolvePackageRoot(), "pi", "agents", "leader.md");
+	return join(resolvePackageRoot(), "pi", "agents", "mayor.md");
 }
 function readPiTownMayorPrompt() {
 	return readFileSync(resolvePiTownMayorPromptPath(), "utf-8");

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\"\nimport { dirname, join } from \"node:path\"\nimport { fileURLToPath } from \"node:url\"\n\nexport const bundledAgentNames = [\n\t\"leader\",\n\t\"supervisor\",\n\t\"scout\",\n\t\"planner\",\n\t\"worker\",\n\t\"reviewer\",\n\t\"docs-keeper\",\n] as const\n\nexport const townPackageName = \"@schilderlabs/pitown-package\"\n\nfunction resolvePackageRoot() {\n\treturn join(dirname(fileURLToPath(import.meta.url)), \"..\")\n}\n\nexport function resolvePiTownPackageRoot() {\n\treturn resolvePackageRoot()\n}\n\nexport function resolvePiTownExtensionPath() {\n\treturn join(resolvePackageRoot(), \"pi\", \"extensions\", \"index.ts\")\n}\n\nexport function resolvePiTownMayorPromptPath() {\n\treturn join(resolvePackageRoot(), \"pi\", \"agents\", \"leader.md\")\n}\n\nexport function readPiTownMayorPrompt() {\n\treturn readFileSync(resolvePiTownMayorPromptPath(), \"utf-8\")\n}\n"],"mappings":";;;;;AAIA,MAAa,oBAAoB;CAChC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AAED,MAAa,kBAAkB;AAE/B,SAAS,qBAAqB;AAC7B,QAAO,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC,EAAE,KAAK;;AAG3D,SAAgB,2BAA2B;AAC1C,QAAO,oBAAoB;;AAG5B,SAAgB,6BAA6B;AAC5C,QAAO,KAAK,oBAAoB,EAAE,MAAM,cAAc,WAAW;;AAGlE,SAAgB,+BAA+B;AAC9C,QAAO,KAAK,oBAAoB,EAAE,MAAM,UAAU,YAAY;;AAG/D,SAAgB,wBAAwB;AACvC,QAAO,aAAa,8BAA8B,EAAE,QAAQ"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\"\nimport { dirname, join } from \"node:path\"\nimport { fileURLToPath } from \"node:url\"\n\nexport const bundledAgentNames = [\n\t\"mayor\",\n\t\"supervisor\",\n\t\"scout\",\n\t\"planner\",\n\t\"worker\",\n\t\"reviewer\",\n\t\"docs-keeper\",\n] as const\n\nexport const townPackageName = \"@schilderlabs/pitown-package\"\n\nfunction resolvePackageRoot() {\n\treturn join(dirname(fileURLToPath(import.meta.url)), \"..\")\n}\n\nexport function resolvePiTownPackageRoot() {\n\treturn resolvePackageRoot()\n}\n\nexport function resolvePiTownExtensionPath() {\n\treturn join(resolvePackageRoot(), \"pi\", \"extensions\", \"index.ts\")\n}\n\nexport function resolvePiTownMayorPromptPath() {\n\treturn join(resolvePackageRoot(), \"pi\", \"agents\", \"mayor.md\")\n}\n\nexport function readPiTownMayorPrompt() {\n\treturn readFileSync(resolvePiTownMayorPromptPath(), \"utf-8\")\n}\n"],"mappings":";;;;;AAIA,MAAa,oBAAoB;CAChC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AAED,MAAa,kBAAkB;AAE/B,SAAS,qBAAqB;AAC7B,QAAO,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC,EAAE,KAAK;;AAG3D,SAAgB,2BAA2B;AAC1C,QAAO,oBAAoB;;AAG5B,SAAgB,6BAA6B;AAC5C,QAAO,KAAK,oBAAoB,EAAE,MAAM,cAAc,WAAW;;AAGlE,SAAgB,+BAA+B;AAC9C,QAAO,KAAK,oBAAoB,EAAE,MAAM,UAAU,WAAW;;AAG9D,SAAgB,wBAAwB;AACvC,QAAO,aAAa,8BAA8B,EAAE,QAAQ"}

package/package.json

@@ -1,37 +1,54 @@
 {
   "name": "@schilderlabs/pitown-package",
-  "version": "0.2.1",
-  "description": "Pi package resources for Pi Town",
+  "version": "0.2.6",
   "type": "module",
-  "imports": {
-    "#pitown-extension": "./pi/extensions/index.ts",
-    "#pitown-package-api": "./src/index.ts",
-    "#pitown-mayor-plan": "./pi/extensions/mayor-plan.ts",
-    "#pitown-town-tools": "./pi/extensions/town-tools.ts"
-  },
+  "types": "./dist/index.d.mts",
   "exports": {
     ".": {
       "import": "./dist/index.mjs",
       "types": "./dist/index.d.mts"
     }
   },
-  "types": "./dist/index.d.mts",
+  "engines": {
+    "node": ">=24"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "dependencies": {
+    "@mariozechner/pi-ai": "0.58.3",
+    "@schilderlabs/pitown-core": "0.2.6"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "0.58.3",
+    "eslint": "9.39.3",
+    "tsdown": "0.20.3",
+    "typescript": "5.9.2",
+    "vitest": "4.0.18"
+  },
+  "bugs": "https://github.com/RobSchilderr/pitown/issues",
+  "description": "Pi package resources for Pi Town",
   "files": [
     "dist",
     "pi",
     "README.md"
   ],
-  "engines": {
-    "node": ">=24"
+  "homepage": "https://github.com/RobSchilderr/pitown#readme",
+  "imports": {
+    "#pitown-extension": "./pi/extensions/index.ts",
+    "#pitown-package-api": "./src/index.ts",
+    "#pitown-mayor-plan": "./pi/extensions/mayor-plan.ts",
+    "#pitown-town-tools": "./pi/extensions/town-tools.ts"
   },
   "keywords": [
-    "pitown",
-    "pi-package",
-    "pi",
     "agents",
+    "night-shift",
     "orchestration",
-    "night-shift"
+    "pi",
+    "pi-package",
+    "pitown"
   ],
+  "license": "MIT",
   "pi": {
     "extensions": [
       "./pi/extensions"
@@ -40,32 +57,10 @@
       "./pi/prompts"
     ]
   },
-  "dependencies": {
-    "@mariozechner/pi-ai": "0.58.3",
-    "@schilderlabs/pitown-core": "0.2.1"
-  },
-  "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*"
-  },
-  "devDependencies": {
-    "@mariozechner/pi-coding-agent": "0.58.3",
-    "eslint": "9.39.3",
-    "tsdown": "0.20.3",
-    "typescript": "5.9.2",
-    "vitest": "4.0.18"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/RobSchilderr/pitown.git"
-  },
-  "homepage": "https://github.com/RobSchilderr/pitown#readme",
-  "bugs": {
-    "url": "https://github.com/RobSchilderr/pitown/issues"
-  },
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT",
+  "repository": "RobSchilderr/pitown.git",
   "scripts": {
     "build": "tsdown",
     "lint": "eslint .",

package/pi/agents/{leader.md → mayor.md}

@@ -19,3 +19,4 @@ Rules:
 - prefer spawning focused workers over doing everything yourself
 - check blockers, open questions, and active agent state before creating more work
 - escalate clearly when the next step depends on a human product or policy decision
+- when delegating multiple independent tasks, call pitown_delegate for ALL of them in the same response — do not wait between delegates

package/pi/extensions/index.test.ts

@@ -15,30 +15,30 @@ import { describe, expect, it, vi } from "vitest"
 
 import piTownPackage from "#pitown-extension"
 
-type RegisteredHandler = (event: unknown, ctx: unknown) => unknown | Promise<unknown>
+type RegisteredHandler = (...args: unknown[]) => unknown | Promise<unknown>
 
 function createRepoArtifacts() {
 	const repoRoot = mkdtempSync(join(tmpdir(), "pitown-repo-"))
 	const artifactsDir = join(mkdtempSync(join(tmpdir(), "pitown-home-")), "repos", "demo-repo")
 
-	const leaderSessionDir = join(artifactsDir, "agents", "leader", "sessions")
+	const mayorSessionDir = join(artifactsDir, "agents", "mayor", "sessions")
 	const workerSessionDir = join(artifactsDir, "agents", "worker-001", "sessions")
 	const reviewerSessionDir = join(artifactsDir, "agents", "reviewer-001", "sessions")
-	const leaderSessionFile = join(leaderSessionDir, "session_leader.jsonl")
+	const mayorSessionFile = join(mayorSessionDir, "session_mayor.jsonl")
 	const workerSessionFile = join(workerSessionDir, "session_worker.jsonl")
 
 	writeAgentState(
 		artifactsDir,
 		createAgentState({
-			agentId: "leader",
-			role: "leader",
+			agentId: "mayor",
+			role: "mayor",
 			status: "running",
 			task: "coordinate town work",
 			lastMessage: "checking board",
 			session: createAgentSessionRecord({
-				sessionDir: leaderSessionDir,
-				sessionPath: leaderSessionFile,
-				sessionId: "leader",
+				sessionDir: mayorSessionDir,
+				sessionPath: mayorSessionFile,
+				sessionId: "mayor",
 			}),
 		}),
 	)
@@ -79,11 +79,11 @@ function createRepoArtifacts() {
 			status: "queued",
 			role: "worker",
 			assignedAgentId: "worker-001",
-			createdBy: "leader",
+			createdBy: "mayor",
 		}),
 	)
 
-	return { repoRoot, artifactsDir, leaderSessionFile, workerSessionFile }
+	return { repoRoot, artifactsDir, mayorSessionFile, workerSessionFile }
 }
 
 function setup() {
@@ -161,13 +161,13 @@ function createToolContext(repoRoot: string, sessionFile: string) {
 }
 
 describe("pi town extension", () => {
-	it("injects hidden town context for managed leader sessions", async () => {
-		const { repoRoot, leaderSessionFile } = createRepoArtifacts()
+	it("injects hidden town context for managed mayor sessions", async () => {
+		const { repoRoot, mayorSessionFile } = createRepoArtifacts()
 		const { handlers } = setup()
 
 		const result = await handlers["before_agent_start"]?.[0]?.(
 			{ systemPrompt: "base", prompt: "coordinate", images: [] },
-			createToolContext(repoRoot, leaderSessionFile),
+			createToolContext(repoRoot, mayorSessionFile),
 		)
 
 		expect(result).toEqual(
@@ -182,11 +182,11 @@ describe("pi town extension", () => {
 	})
 
 	it("renders the live board for town-managed sessions", async () => {
-		const { repoRoot, leaderSessionFile } = createRepoArtifacts()
+		const { repoRoot, mayorSessionFile } = createRepoArtifacts()
 		const { tools } = setup()
 		const boardTool = tools.get("pitown_board")
 
-		const result = await boardTool?.execute("tool-call", {}, undefined, () => {}, createToolContext(repoRoot, leaderSessionFile))
+		const result = await boardTool?.execute("tool-call", {}, undefined, () => {}, createToolContext(repoRoot, mayorSessionFile))
 
 		expect(result).toEqual(
 			expect.objectContaining({
@@ -195,7 +195,7 @@ describe("pi town extension", () => {
 		)
 	})
 
-	it("blocks workers from messaging non-leader agents directly", async () => {
+	it("blocks workers from messaging non-mayor agents directly", async () => {
 		const { repoRoot, workerSessionFile } = createRepoArtifacts()
 		const { tools } = setup()
 		const messageTool = tools.get("pitown_message_agent")
@@ -208,7 +208,7 @@ describe("pi town extension", () => {
 				() => {},
 				createToolContext(repoRoot, workerSessionFile),
 			),
-		).rejects.toThrow("Only the leader may message non-leader agents")
+		).rejects.toThrow("Only the mayor may message non-mayor agents")
 	})
 
 	it("updates worker state and task status through the status tool", async () => {
@@ -238,10 +238,10 @@ describe("pi town extension", () => {
 	})
 
 	it("enables mayor plan mode with a read-only tool set", async () => {
-		const { repoRoot, leaderSessionFile } = createRepoArtifacts()
+		const { repoRoot, mayorSessionFile } = createRepoArtifacts()
 		const { commands, activeTools, appendedEntries } = setup()
 		const planCommand = commands.get("plan") as { handler: RegisteredHandler } | undefined
-		const ctx = createToolContext(repoRoot, leaderSessionFile)
+		const ctx = createToolContext(repoRoot, mayorSessionFile)
 
 		await planCommand?.handler([], ctx)
 
@@ -254,10 +254,10 @@ describe("pi town extension", () => {
 	})
 
 	it("captures numbered mayor plan steps after a planning turn", async () => {
-		const { repoRoot, leaderSessionFile } = createRepoArtifacts()
+		const { repoRoot, mayorSessionFile } = createRepoArtifacts()
 		const { commands, handlers, pi } = setup()
 		const planCommand = commands.get("plan") as { handler: RegisteredHandler } | undefined
-		const ctx = createToolContext(repoRoot, leaderSessionFile)
+		const ctx = createToolContext(repoRoot, mayorSessionFile)
 
 		await planCommand?.handler([], ctx)
 		await handlers["agent_end"]?.[0]?.(

package/pi/extensions/index.ts

@@ -2,8 +2,9 @@ import { existsSync, readdirSync, readFileSync } from "node:fs"
 import { dirname, join } from "node:path"
 import { fileURLToPath } from "node:url"
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"
+import { listAgentStates } from "@schilderlabs/pitown-core"
 import { registerMayorPlanMode } from "#pitown-mayor-plan"
-import { registerTownTools } from "#pitown-town-tools"
+import { registerTownTools, resolveTownAgentContext } from "#pitown-town-tools"
 
 const extensionDir = dirname(fileURLToPath(import.meta.url))
 const agentsDir = join(extensionDir, "..", "agents")
@@ -61,4 +62,26 @@ export default function piTownPackage(pi: ExtensionAPI) {
 			ctx.ui.notify(lines.join("\n"), "info")
 		},
 	})
+
+	pi.registerCommand("workers", {
+		description: "Show current worker status",
+		handler: async (_args, ctx) => {
+			const context = resolveTownAgentContext(ctx.sessionManager.getSessionFile())
+			if (!context) {
+				ctx.ui.notify("Not in a Pi Town session.", "warning")
+				return
+			}
+			const agents = listAgentStates(context.artifactsDir)
+			const workers = agents.filter((a) => a.agentId !== "mayor")
+			if (workers.length === 0) {
+				ctx.ui.notify("No workers spawned yet.", "info")
+				return
+			}
+			const lines = workers.map((w) => {
+				const task = w.task ? (w.task.length > 60 ? w.task.slice(0, 59) + "…" : w.task) : "—"
+				return `${w.agentId.padEnd(16)} ${w.status.padEnd(10)} ${task}`
+			})
+			ctx.ui.notify(["Workers:", ...lines].join("\n"), "info")
+		},
+	})
 }

package/pi/extensions/mayor-plan.ts

@@ -1,8 +1,12 @@
-import type { AgentMessage } from "@mariozechner/pi-agent-core"
 import type { AssistantMessage, TextContent } from "@mariozechner/pi-ai"
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent"
 import { resolveTownAgentContext } from "#pitown-town-tools"
 
+interface AgentMessage {
+	role: string
+	content?: unknown
+}
+
 interface PlanTodo {
 	step: number
 	text: string
@@ -46,7 +50,7 @@ function resolvePlanTools(candidateTools: string[]): string[] {
 function isMayorSession(ctx: ExtensionContext): boolean {
 	const context = resolveTownAgentContext(ctx.sessionManager.getSessionFile())
 	if (context === null) return false
-	return context.agentId === "leader" || context.role === "leader" || context.role === "mayor"
+	return context.agentId === "mayor" || context.role === "mayor"
 }
 
 function persistPlanState(pi: ExtensionAPI, enabled: boolean, savedTools: string[], todos: PlanTodo[]) {
@@ -163,7 +167,7 @@ export function registerMayorPlanMode(pi: ExtensionAPI) {
 				return
 			}
 
-			ctx.ui.notify(renderTodos(todos), todos.length === 0 ? "info" : "success")
+			ctx.ui.notify(renderTodos(todos), "info")
 		},
 	})
 

package/pi/extensions/town-tools.ts

@@ -6,6 +6,7 @@ import {
 	queueAgentMessage,
 	readAgentMessages,
 	readAgentState,
+	stopManagedAgents,
 	updateAgentStatus,
 } from "@schilderlabs/pitown-core"
 import { readPiTownMayorPrompt, resolvePiTownExtensionPath } from "#pitown-package-api"
@@ -15,6 +16,7 @@ type TownToolName =
 	| "pitown_delegate"
 	| "pitown_message_agent"
 	| "pitown_peek_agent"
+	| "pitown_stop"
 	| "pitown_update_status"
 
 interface TownAgentContext {
@@ -32,10 +34,11 @@ const ROLE_STATUS = Type.Union([
 	Type.Literal("blocked"),
 	Type.Literal("completed"),
 	Type.Literal("failed"),
+	Type.Literal("stopped"),
 ])
 
 const toolPermissions: Record<string, TownToolName[]> = {
-	leader: ["pitown_board", "pitown_delegate", "pitown_message_agent", "pitown_peek_agent", "pitown_update_status"],
+	mayor: ["pitown_board", "pitown_delegate", "pitown_message_agent", "pitown_peek_agent", "pitown_stop", "pitown_update_status"],
 	worker: ["pitown_board", "pitown_message_agent", "pitown_peek_agent", "pitown_update_status"],
 	reviewer: ["pitown_board", "pitown_message_agent", "pitown_peek_agent", "pitown_update_status"],
 	"docs-keeper": ["pitown_board", "pitown_message_agent", "pitown_peek_agent", "pitown_update_status"],
@@ -74,18 +77,18 @@ function assertPermission(context: TownAgentContext, toolName: TownToolName, tar
 		throw new Error(`${context.role} agents may not use ${toolName}`)
 	}
 
-	if (toolName === "pitown_delegate" && context.role !== "leader") {
-		throw new Error("Only the leader may delegate work")
+	if (toolName === "pitown_delegate" && context.role !== "mayor") {
+		throw new Error("Only the mayor may delegate work")
 	}
 
-	if (toolName === "pitown_message_agent" && context.role !== "leader" && targetAgentId && targetAgentId !== "leader") {
-		throw new Error("Only the leader may message non-leader agents")
+	if (toolName === "pitown_message_agent" && context.role !== "mayor" && targetAgentId && targetAgentId !== "mayor") {
+		throw new Error("Only the mayor may message non-mayor agents")
 	}
 
-	if (toolName === "pitown_peek_agent" && context.role !== "leader" && targetAgentId) {
-		const allowedTargets = new Set([context.agentId, "leader"])
+	if (toolName === "pitown_peek_agent" && context.role !== "mayor" && targetAgentId) {
+		const allowedTargets = new Set([context.agentId, "mayor"])
 		if (!allowedTargets.has(targetAgentId)) {
-			throw new Error("Non-leader agents may only peek themselves or the leader")
+			throw new Error("Non-mayor agents may only peek themselves or the mayor")
 		}
 	}
 }
@@ -139,6 +142,8 @@ function requireTownContext(ctx: ExtensionContext): TownAgentContext {
 	return context
 }
 
+const notifiedCompletions = new Set<string>()
+
 export function registerTownTools(pi: ExtensionAPI) {
 	pi.on("before_agent_start", async (_event, ctx) => {
 		const context = resolveTownAgentContext(ctx.sessionManager.getSessionFile())
@@ -153,6 +158,50 @@ export function registerTownTools(pi: ExtensionAPI) {
 		}
 	})
 
+	pi.on("before_agent_start", async (_event, ctx) => {
+		const context = resolveTownAgentContext(ctx.sessionManager.getSessionFile())
+		if (!context || context.agentId !== "mayor") return
+		if (!ctx.hasUI) return
+
+		const agents = listAgentStates(context.artifactsDir)
+		const workers = agents.filter((a) => a.agentId !== "mayor")
+		if (workers.length === 0) {
+			ctx.ui.setStatus("pitown-workers", undefined)
+			ctx.ui.setWidget("pitown-workers", undefined)
+			return
+		}
+
+		for (const w of workers) {
+			if ((w.status === "idle" || w.status === "completed") && !notifiedCompletions.has(w.agentId)) {
+				notifiedCompletions.add(w.agentId)
+				ctx.ui.notify(`✓ ${w.agentId} finished: ${w.lastMessage ?? w.task ?? "done"}`, "info")
+			}
+			if ((w.status === "blocked" || w.status === "failed" || w.status === "stopped") && !notifiedCompletions.has(w.agentId)) {
+				notifiedCompletions.add(w.agentId)
+				ctx.ui.notify(`✗ ${w.agentId} blocked: ${w.lastMessage ?? "needs attention"}`, "warning")
+			}
+		}
+
+		const running = workers.filter((a) => a.status === "running" || a.status === "starting").length
+		const done = workers.filter((a) => a.status === "idle" || a.status === "completed").length
+		const blocked = workers.filter((a) => a.status === "blocked" || a.status === "failed" || a.status === "stopped").length
+
+		const parts: string[] = []
+		if (running > 0) parts.push(`${running} running`)
+		if (done > 0) parts.push(`${done} done`)
+		if (blocked > 0) parts.push(`${blocked} blocked`)
+
+		const label = `workers: ${parts.join(", ")}`
+		ctx.ui.setStatus("pitown-workers", label)
+		ctx.ui.setWidget(
+			"pitown-workers",
+			workers.map((w) => {
+				const task = w.task ? (w.task.length > 50 ? w.task.slice(0, 49) + "…" : w.task) : "—"
+				return `${w.agentId}: ${w.status} — ${task}`
+			}),
+		)
+	})
+
 	pi.registerTool({
 		name: "pitown_board",
 		label: "Pi Town Board",
@@ -191,20 +240,21 @@ export function registerTownTools(pi: ExtensionAPI) {
 				task: input.task,
 				agentId: input.agentId ?? null,
 				extensionPath: resolvePiTownExtensionPath(),
-				appendedSystemPrompt: input.role === "leader" ? readPiTownMayorPrompt() : null,
+				appendedSystemPrompt: input.role === "mayor" ? readPiTownMayorPrompt() : null,
 			})
 
 			return {
 				content: [
 					{
 						type: "text",
-						text: `Delegated ${result.task.taskId} to ${result.agentId} (${input.role}). Exit code: ${result.piResult.exitCode}.`,
+						text: `Delegated ${result.task.taskId} to ${result.agentId} (${input.role}). Status: ${result.task.status}.`,
 					},
 				],
 				details: {
 					taskId: result.task.taskId,
 					agentId: result.agentId,
 					status: result.task.status,
+					processId: result.launch.processId,
 					sessionPath: result.latestSession.sessionPath,
 				},
 			}
@@ -271,6 +321,61 @@ export function registerTownTools(pi: ExtensionAPI) {
 		},
 	})
 
+	pi.registerTool({
+		name: "pitown_stop",
+		label: "Pi Town Stop",
+		description: "Stop a managed Pi Town agent, or stop the other agents in this repo",
+		parameters: Type.Object({
+			scope: Type.Optional(Type.Union([Type.Literal("repo"), Type.Literal("agent")])),
+			agentId: Type.Optional(Type.String({ description: "Required when scope is agent" })),
+			force: Type.Optional(Type.Boolean({ description: "Escalate to SIGKILL if SIGTERM does not stop the process" })),
+			reason: Type.Optional(Type.String({ description: "Optional stop reason recorded on the board" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const context = requireTownContext(ctx)
+			assertPermission(context, "pitown_stop")
+			const input = params as {
+				scope?: "repo" | "agent"
+				agentId?: string
+				force?: boolean
+				reason?: string
+			}
+			const scope = input.scope ?? "repo"
+
+			if (scope === "agent" && !input.agentId) throw new Error("pitown_stop requires agentId when scope=agent")
+			if (scope === "agent" && input.agentId === context.agentId) {
+				throw new Error("pitown_stop may not stop the current live mayor session; use the CLI for self-stop")
+			}
+
+			const result = stopManagedAgents({
+				artifactsDir: context.artifactsDir,
+				agentId: scope === "agent" ? input.agentId! : null,
+				excludeAgentIds: scope === "repo" ? [context.agentId] : [],
+				actorId: context.agentId,
+				reason: input.reason ?? `Stopped by ${context.agentId} via pitown_stop`,
+				force: input.force ?? false,
+			})
+
+			return {
+				content: [
+					{
+						type: "text",
+						text:
+							scope === "agent"
+								? `Stopped ${input.agentId}. Agents updated: ${result.stoppedAgents}. Signaled processes: ${result.signaledProcesses}.`
+								: `Stopped repo agents except ${context.agentId}. Agents updated: ${result.stoppedAgents}. Signaled processes: ${result.signaledProcesses}.`,
+					},
+				],
+				details: {
+					scope,
+					agentId: input.agentId ?? null,
+					stoppedAgents: result.stoppedAgents,
+					signaledProcesses: result.signaledProcesses,
+				},
+			}
+		},
+	})
+
 	pi.registerTool({
 		name: "pitown_update_status",
 		label: "Pi Town Update Status",
@@ -285,7 +390,7 @@ export function registerTownTools(pi: ExtensionAPI) {
 			const context = requireTownContext(ctx)
 			assertPermission(context, "pitown_update_status")
 			const input = params as {
-				status: "queued" | "running" | "idle" | "blocked" | "completed" | "failed"
+				status: "queued" | "running" | "idle" | "blocked" | "completed" | "failed" | "stopped"
 				lastMessage?: string
 				waitingOn?: string
 				blocked?: boolean
@@ -297,7 +402,7 @@ export function registerTownTools(pi: ExtensionAPI) {
 				status: input.status,
 				lastMessage: input.lastMessage ?? null,
 				waitingOn: input.waitingOn ?? null,
-				blocked: input.blocked,
+				...(input.blocked === undefined ? {} : { blocked: input.blocked }),
 			})
 
 			return {