@markjaquith/agency 2.69.0 → 2.70.0

package/README.md

@@ -56,8 +56,6 @@ workbase/
     tui.jsonc              # managed TUI plugin registration
     plugins/agency-repository-skills.ts # managed workbase access and checkout skills
     tui/agency-debug.ts    # managed /agency-debug TUI diagnostic
-  .pi/
-    extensions/agency-workbase.ts # managed workbase context and checkout skills
   agency.json              # tracked config and portable repository declarations
   repos/                   # ignored local materializations
     frontend/              # bare Git repository or symlink
@@ -86,8 +84,8 @@ workbase/
 
 Agency keeps discovery and other observational commands read-only. Run
 `agency integration status` to inspect `.agency/AGENTS.md`, the managed
-OpenCode configuration and plugins, and `.pi/extensions/agency-workbase.ts`,
-then `agency integration sync` to create missing files or refresh checksum-safe
+OpenCode configuration and plugins, then `agency integration sync` to create
+missing files or refresh checksum-safe
 managed files. Customized files are reported but never overwritten. Sync also
 removes checksum-valid retired managed artifacts while
 preserving customized files at their former paths. The root
@@ -128,15 +126,15 @@ The plugin grants whole-workbase access dynamically, while the portable
 reference advertises that context to agents. Bash and Agency operations must
 still follow the write authority reported by `agency context`.
 
-Pi discovers the managed project extension automatically when launched from
-the workbase root after the project is trusted. When launching Pi from a task,
-phase, or epic directory, pass the managed file with `--extension`, for example
-`pi -e /path/to/workbase/.pi/extensions/agency-workbase.ts`. The extension loads
-the managed Agency instructions into Pi's system prompt, advertises the complete
-workbase, and exposes skills from the writable checkout's `.claude/skills`,
-`.agents/skills`, `.opencode/{skill,skills}`, and `.pi/skills` directories.
-Agency context still determines write authority; reference checkouts remain
-read-only.
+Agency's package lifecycle installs one Pi extension at
+`~/.pi/agent/extensions/agency.ts`. Pi loads it globally, so it works from
+workbase roots and nested epic, task, phase, or checkout directories without
+project trust or an explicit `--extension` flag. Outside an Agency workbase it
+registers no resources and changes no prompt. Inside one, it loads the managed
+Agency instructions, advertises the complete workbase, and exposes skills from
+the writable checkout's `.claude/skills`, `.agents/skills`,
+`.opencode/{skill,skills}`, and `.pi/skills` directories. `agency context`
+remains the authority for writes; reference checkouts remain read-only.
 
 Repository aliases, the version-control backend, and canonical fetch remotes are
 declared in tracked `agency.json`; local clones and symlinks remain ignored under
@@ -434,11 +432,11 @@ working directory so the workbase `AGENTS.md` and managed OpenCode config are
 discovered normally.
 Agency's managed OpenCode plugin grants the active workbase external-directory
 access and adds existing checkout-local `.claude/skills`, `.agents/skills`, and
-`.opencode/{skill,skills}` directories to `skills.paths`. The managed Pi
+`.opencode/{skill,skills}` directories to `skills.paths`. The global Pi
 extension provides equivalent whole-workbase context and additionally discovers
 checkout-local `.pi/skills` through Pi's `resources_discover` lifecycle.
-`agency work` supplies the checkout directly; plain OpenCode launches and Pi
-launches with the managed extension loaded resolve a materialized execution-unit
+`agency work` supplies the checkout directly; plain OpenCode and Pi launches
+resolve a materialized execution-unit
 checkout through `agency context`. A multi-phase
 task root has no single checkout, so launch from its phase directory when using
 plain OpenCode or Pi. Other checkout-local configuration is not composed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.69.0",
+  "version": "2.70.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",
@@ -22,6 +22,8 @@
     "cli.ts",
     "cli-main.ts",
     "src",
+    "pi-extensions",
+    "scripts/install-pi-extension.ts",
     "schemas",
     "fixtures/protocol",
     "README.md",
@@ -61,6 +63,8 @@
     "tag": "latest"
   },
   "scripts": {
+    "postinstall": "bun scripts/install-pi-extension.ts install",
+    "preuninstall": "bun scripts/install-pi-extension.ts uninstall",
     "benchmark:sync": "bun scripts/benchmark-sync.ts",
     "test": "find src \\( -name '*.test.ts' -o -name '*.test.tsx' \\) -print0 | xargs -0 -n 1 -P 4 bun test",
     "test:opencode": "AGENCY_TEST_OPENCODE=1 bun test src/cli.test.ts --test-name-pattern 'provides effective whole-workbase OpenCode access'",

package/pi-extensions/agency.test.ts

@@ -0,0 +1,117 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdir } from "node:fs/promises"
+import { join } from "node:path"
+import { cleanupTempDir, createTempDir } from "../src/test-utils"
+import agencyExtension from "./agency"
+
+describe("global Pi extension", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	const load = (response?: object) => {
+		const handlers = new Map<string, (...args: any[]) => any>()
+		const pi = {
+			exec: async () => ({
+				code: response ? 0 : 1,
+				stdout: response ? JSON.stringify(response) : "",
+				stderr: "",
+			}),
+			on: (name: string, handler: (...args: any[]) => any) => {
+				handlers.set(name, handler)
+			},
+		}
+		agencyExtension(pi as never)
+		return handlers
+	}
+
+	test("no-ops outside Agency workbases without invoking the CLI", async () => {
+		let executions = 0
+		const handlers = new Map<string, (...args: any[]) => any>()
+		agencyExtension({
+			exec: async () => {
+				executions += 1
+				return { code: 1, stdout: "", stderr: "" }
+			},
+			on: (name: string, handler: (...args: any[]) => any) => {
+				handlers.set(name, handler)
+			},
+		} as never)
+
+		expect(
+			await handlers.get("resources_discover")?.({ cwd: root }),
+		).toBeUndefined()
+		expect(
+			await handlers.get("before_agent_start")?.(
+				{ systemPrompt: "Base" },
+				{ cwd: root },
+			),
+		).toBeUndefined()
+		expect(executions).toBe(0)
+	})
+
+	test("uses CLI context from nested directories for skills and authority", async () => {
+		const task = join(root, "tasks", "example")
+		const nested = join(task, "code", "agency", "src")
+		const checkout = join(task, "code", "agency")
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		await mkdir(join(root, ".agency"), { recursive: true })
+		await Bun.write(
+			join(root, ".agency", "AGENTS.md"),
+			"# Managed instructions\n",
+		)
+		await mkdir(join(checkout, ".agents", "skills"), { recursive: true })
+		await mkdir(nested, { recursive: true })
+
+		const handlers = load({
+			ok: true,
+			result: {
+				workbase: { root },
+				target: {
+					kind: "task",
+					taskId: "example",
+					path: join(task, "TASK.md"),
+				},
+				authority: { mode: "execution", writable: { checkoutPath: checkout } },
+				documents: { task: { data: { status: "working" } } },
+				validation: { valid: true },
+			},
+		})
+		const resources = await handlers.get("resources_discover")?.({
+			cwd: nested,
+		})
+		expect(resources.skillPaths).toEqual([join(checkout, ".agents", "skills")])
+
+		const prompt = await handlers.get("before_agent_start")?.(
+			{ systemPrompt: "Base" },
+			{ cwd: nested },
+		)
+		expect(prompt.systemPrompt).toContain("# Managed instructions")
+		expect(prompt.systemPrompt).toContain(
+			`${checkout} as the default implementation directory`,
+		)
+	})
+
+	test("rejects CLI context for a different workbase", async () => {
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		const handlers = load({
+			ok: true,
+			result: {
+				workbase: { root: join(root, "other") },
+				target: { kind: "epic", epicId: "example" },
+				validation: { valid: true },
+			},
+		})
+
+		expect(
+			await handlers.get("before_agent_start")?.(
+				{ systemPrompt: "Base" },
+				{ cwd: root },
+			),
+		).toBeUndefined()
+	})
+})

package/pi-extensions/agency.ts

@@ -0,0 +1,141 @@
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+
+type ExtensionAPI = {
+	exec: (
+		command: string,
+		args: string[],
+		options: { timeout: number },
+	) => Promise<{ code: number; stdout: string }>
+	on: (
+		name: "resources_discover" | "before_agent_start",
+		handler: (...args: any[]) => unknown,
+	) => void
+}
+
+type AgencyContext = {
+	root?: string
+	checkout?: string
+	target?: string
+}
+
+const contextTarget = (result: Record<string, any>): string | undefined => {
+	const target = result.target
+	if (target?.kind === "epic") return `epic:${target.epicId}`
+	if (target?.kind === "phase") {
+		return `execution-unit:phase/${target.taskId}/${target.phaseId}`
+	}
+	if (target?.kind === "task") {
+		return result.authority?.mode === "execution"
+			? `execution-unit:task/${target.taskId}`
+			: `task:${target.taskId}`
+	}
+}
+
+const discoverWorkbase = (directory: string) => {
+	let current = resolve(directory)
+	while (true) {
+		if (existsSync(join(current, "agency.json"))) return current
+		const parent = dirname(current)
+		if (parent === current) return
+		current = parent
+	}
+}
+
+const agencyContext = async (
+	pi: ExtensionAPI,
+	directory: string,
+): Promise<AgencyContext | undefined> => {
+	const root = discoverWorkbase(directory)
+	if (!root) return
+
+	const command = await pi.exec(
+		"agency",
+		["context", directory, "--compact", "--json"],
+		{ timeout: 5000 },
+	)
+	if (command.code !== 0) return
+
+	const envelope = JSON.parse(command.stdout)
+	if (envelope.ok !== true) return
+	const result = envelope.result ?? {}
+	const target = contextTarget(result)
+	const status =
+		result.documents?.phase?.data?.status ??
+		result.documents?.task?.data?.status
+	if (
+		result.validation?.valid !== true ||
+		result.workbase?.root !== root ||
+		!target ||
+		(target.startsWith("execution-unit:") &&
+			(!result.authority?.writable?.checkoutPath || status !== "working"))
+	)
+		return
+
+	return {
+		root,
+		checkout: result.authority?.writable?.checkoutPath,
+		target,
+	}
+}
+
+export default function agencyExtension(pi: ExtensionAPI) {
+	const contexts = new Map<string, Promise<AgencyContext | undefined>>()
+	const runtimeContext = (directory: string) => {
+		const key = resolve(directory)
+		let context = contexts.get(key)
+		if (!context) {
+			context = agencyContext(pi, key).catch(() => undefined)
+			contexts.set(key, context)
+		}
+		return context
+	}
+
+	pi.on("resources_discover", async (event: { cwd: string }) => {
+		const context = await runtimeContext(event.cwd)
+		if (!context?.checkout) return
+
+		const skillPaths = [
+			join(context.checkout, ".claude", "skills"),
+			join(context.checkout, ".agents", "skills"),
+			join(context.checkout, ".opencode", "skill"),
+			join(context.checkout, ".opencode", "skills"),
+			join(context.checkout, ".pi", "skills"),
+		].filter(existsSync)
+		if (skillPaths.length > 0) return { skillPaths: [...new Set(skillPaths)] }
+	})
+
+	pi.on(
+		"before_agent_start",
+		async (event: { systemPrompt: string }, ctx: { cwd: string }) => {
+			const context = await runtimeContext(ctx.cwd)
+			if (!context?.root) return
+
+			const instructionsPath = join(context.root, ".agency", "AGENTS.md")
+			const instructions = existsSync(instructionsPath)
+				? readFileSync(instructionsPath, "utf8").trim()
+				: undefined
+			const activeTarget = process.env.AGENCY_TARGET
+			const worker =
+				activeTarget && context.target === activeTarget
+					? `Agency verified this Pi session as the active worker for ${activeTarget}. Perform the assigned work directly. Do not invoke agency work for this target or launch a replacement worker.`
+					: undefined
+			const access = `The complete Agency workbase is available at ${context.root}. Use absolute paths under that root when workbase context is needed. Agency context remains the authority for writes.`
+			const implementation = context.checkout
+				? `Pi remains rooted in the task or phase directory for Agency instructions and context. Treat ${context.checkout} as the default implementation directory for source reads, edits, repository status, builds, tests, formatting, and other repository-local commands. Run Agency lifecycle and context commands from the task or phase directory. Any reference checkouts reported by Agency context are read-only.`
+				: undefined
+
+			return {
+				systemPrompt: [
+					event.systemPrompt,
+					instructions,
+					access,
+					worker,
+					implementation,
+				]
+					.filter(Boolean)
+					.join("\n\n"),
+			}
+		},
+	)
+}

package/scripts/install-pi-extension.ts

@@ -0,0 +1,25 @@
+import { cp, mkdir, rm } from "node:fs/promises"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+
+export const piExtensionPath = (home = homedir()) =>
+	join(home, ".pi", "agent", "extensions", "agency.ts")
+
+export const installPiExtension = async (
+	source = join(import.meta.dir, "..", "pi-extensions", "agency.ts"),
+	destination = piExtensionPath(),
+) => {
+	await mkdir(dirname(destination), { recursive: true })
+	await cp(source, destination)
+}
+
+export const uninstallPiExtension = async (destination = piExtensionPath()) => {
+	await rm(destination, { force: true })
+}
+
+if (import.meta.main) {
+	const command = process.argv[2] ?? "install"
+	if (command === "install") await installPiExtension()
+	else if (command === "uninstall") await uninstallPiExtension()
+	else throw new Error(`Unknown Pi extension lifecycle command: ${command}`)
+}

package/src/cli.test.ts

@@ -642,7 +642,6 @@ exit 23
 			{ name: "opencode-plugin", state: "managed" },
 			{ name: "opencode-tui", state: "managed" },
 			{ name: "opencode-tui-plugin", state: "managed" },
-			{ name: "pi-extension", state: "managed" },
 		])
 
 		const synced = parseJson(
@@ -654,7 +653,6 @@ exit 23
 			{ name: "opencode-plugin", state: "managed", changed: false },
 			{ name: "opencode-tui", state: "managed", changed: false },
 			{ name: "opencode-tui-plugin", state: "managed", changed: false },
-			{ name: "pi-extension", state: "managed", changed: false },
 		])
 	})
 

package/src/commands/init.test.ts

@@ -89,12 +89,9 @@ describe("init command", () => {
 		expect(tuiPlugin).toContain('slashName: "agency-debug"')
 		expect(tuiPlugin).toContain("api.ui.toast")
 		expect(tuiPlugin).not.toContain("chat.message")
-		const piExtension = await Bun.file(
-			join(root, ".pi/extensions/agency-workbase.ts"),
-		).text()
-		expect(piExtension).toContain('pi.on("resources_discover"')
-		expect(piExtension).toContain('pi.on("before_agent_start"')
-		expect(piExtension).toContain("AGENCY_WRITABLE_CHECKOUT")
+		expect(
+			await Bun.file(join(root, ".pi/extensions/agency-workbase.ts")).exists(),
+		).toBe(false)
 	})
 
 	test("preserves existing gitignore entries", async () => {

package/src/commands/integration.test.ts

@@ -51,11 +51,6 @@ describe("integration command", () => {
 					state: "missing",
 					remediation: expect.stringContaining("integration sync"),
 				},
-				{
-					name: "pi-extension",
-					state: "missing",
-					remediation: expect.stringContaining("integration sync"),
-				},
 			],
 		})
 	})
@@ -104,12 +99,7 @@ OpenCode TUI config: missing
 OpenCode /agency-debug: missing
   Path: .opencode/tui/agency-debug.ts
   The managed OpenCode TUI diagnostic companion needs synchronization.
-  Action: Run 'agency integration sync' to install /agency-debug.
-
-Pi workbase extension: missing
-  Path: .pi/extensions/agency-workbase.ts
-  The managed Pi workbase extension needs synchronization.
-  Action: Run 'agency integration sync' to provide workbase context and expose writable-checkout skills in Pi.`)
+  Action: Run 'agency integration sync' to install /agency-debug.`)
 	})
 
 	test("explicitly synchronizes integration files", async () => {
@@ -123,7 +113,6 @@ Pi workbase extension: missing
 			{ name: "opencode-plugin", state: "managed", changed: true },
 			{ name: "opencode-tui", state: "managed", changed: true },
 			{ name: "opencode-tui-plugin", state: "managed", changed: true },
-			{ name: "pi-extension", state: "managed", changed: true },
 		])
 		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
 		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(true)
@@ -144,9 +133,6 @@ Pi workbase extension: missing
 		expect(
 			await Bun.file(join(root, ".opencode/tui/agency-debug.ts")).exists(),
 		).toBe(true)
-		expect(
-			await Bun.file(join(root, ".pi/extensions/agency-workbase.ts")).exists(),
-		).toBe(true)
 	})
 
 	test("formats integration sync results for people", async () => {
@@ -174,10 +160,6 @@ OpenCode TUI config: synced
 
 OpenCode /agency-debug: synced
   Path: .opencode/tui/agency-debug.ts
-  Agency's managed OpenCode TUI diagnostic companion is current.
-
-Pi workbase extension: synced
-  Path: .pi/extensions/agency-workbase.ts
-  Agency's managed Pi extension provides whole-workbase context and exposes writable-checkout skills.`)
+  Agency's managed OpenCode TUI diagnostic companion is current.`)
 	})
 })

package/src/commands/integration.ts

@@ -18,7 +18,6 @@ interface IntegrationResult {
 			| "opencode-plugin"
 			| "opencode-tui"
 			| "opencode-tui-plugin"
-			| "pi-extension"
 		readonly path: string
 		readonly state: string
 		readonly diagnostic: string
@@ -33,7 +32,6 @@ const integrationNames = {
 	"opencode-plugin": "OpenCode workbase plugin",
 	"opencode-tui": "OpenCode TUI config",
 	"opencode-tui-plugin": "OpenCode /agency-debug",
-	"pi-extension": "Pi workbase extension",
 } as const
 
 const logHumanResult = (
@@ -92,9 +90,9 @@ Usage: agency integration <subcommand>
 
 Inspect or explicitly synchronize managed agent integration files. OpenCode
 launches load the managed instructions and project config at runtime. Managed
-OpenCode and Pi extensions provide whole-workbase context and writable-checkout
-skills, and the /agency-debug TUI diagnostic reports OpenCode integration state
-without changing Agency write authority.
+The managed OpenCode extension provides whole-workbase context and
+writable-checkout skills, and the /agency-debug TUI diagnostic reports OpenCode
+integration state without changing Agency write authority.
 
 Subcommands:
   status  Report file state, access diagnostics, and safe remediation

package/src/services/IntegrationService.test.ts

@@ -16,10 +16,6 @@ import {
 	canUpdateManagedWorkbaseOpencodeTuiPlugin,
 	managedWorkbaseOpencodeTuiPlugin,
 } from "../workbase/opencode-tui-plugin-file"
-import {
-	canUpdateManagedWorkbasePiExtension,
-	managedWorkbasePiExtension,
-} from "../workbase/pi-extension-file"
 import { IntegrationService } from "./IntegrationService"
 
 const write = async (root: string, path: string, content: string) => {
@@ -69,7 +65,6 @@ describe("IntegrationService", () => {
 			"missing",
 			"missing",
 			"missing",
-			"missing",
 		])
 		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(false)
 
@@ -86,18 +81,12 @@ describe("IntegrationService", () => {
 			".opencode/tui/agency-debug.ts",
 			managedWorkbaseOpencodeTuiPlugin,
 		)
-		await write(
-			root,
-			".pi/extensions/agency-workbase.ts",
-			managedWorkbasePiExtension,
-		)
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"managed",
 			"managed",
 			"managed",
 			"managed",
 			"managed",
-			"managed",
 		])
 	})
 
@@ -115,7 +104,6 @@ describe("IntegrationService", () => {
 			"missing",
 			"missing",
 			"missing",
-			"missing",
 		])
 	})
 
@@ -220,131 +208,6 @@ describe("IntegrationService", () => {
 		).toBe(false)
 	})
 
-	test("generates a Pi extension with workbase context and checkout skills", async () => {
-		expect(managedWorkbasePiExtension).toContain(
-			'import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent"',
-		)
-		expect(managedWorkbasePiExtension).toContain('pi.on("resources_discover"')
-		expect(managedWorkbasePiExtension).toContain('pi.on("before_agent_start"')
-		expect(managedWorkbasePiExtension).toContain(
-			'join(checkout, ".agents", "skills")',
-		)
-		expect(managedWorkbasePiExtension).toContain(
-			'join(checkout, CONFIG_DIR_NAME, "skills")',
-		)
-		expect(managedWorkbasePiExtension).toContain(
-			"The complete Agency workbase is available",
-		)
-		expect(managedWorkbasePiExtension).toContain(
-			"Agency context remains the authority for writes",
-		)
-		expect(
-			canUpdateManagedWorkbasePiExtension(managedWorkbasePiExtension),
-		).toBe(true)
-		expect(
-			canUpdateManagedWorkbasePiExtension(
-				managedWorkbasePiExtension.replace("resources_discover", "discover"),
-			),
-		).toBe(false)
-
-		const taskDirectory = join(root, "tasks/example")
-		const checkoutPath = join(taskDirectory, "code/agency")
-		await write(root, ".agency/AGENTS.md", "# Managed Agency instructions\n")
-		await write(
-			root,
-			"tasks/example/TASK.md",
-			"---\nrepo: agency\nstatus: working\n---\n",
-		)
-		await write(
-			root,
-			"tasks/example/code/agency/.agents/skills/example/SKILL.md",
-			"---\nname: example\ndescription: Example.\n---\n",
-		)
-		await write(
-			root,
-			"tasks/example/code/agency/.pi/skills/pi-example/SKILL.md",
-			"---\nname: pi-example\ndescription: Pi example.\n---\n",
-		)
-		const path = join(root, ".pi/extensions/agency-workbase.ts")
-		await write(
-			root,
-			".pi/extensions/agency-workbase.ts",
-			managedWorkbasePiExtension.replace(
-				'import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent"',
-				'const CONFIG_DIR_NAME = ".pi"\ntype ExtensionAPI = any',
-			),
-		)
-
-		const contextResponse = JSON.stringify({
-			version: 1,
-			ok: true,
-			result: {
-				workbase: { root },
-				target: {
-					kind: "task",
-					taskId: "example",
-					path: join(taskDirectory, "TASK.md"),
-				},
-				authority: {
-					mode: "execution",
-					writable: { checkoutPath },
-				},
-				documents: { task: { data: { status: "working" } } },
-				validation: { valid: true, warnings: [] },
-			},
-		})
-		const handlers = new Map<string, (...args: any[]) => any>()
-		const pi = {
-			exec: async () => ({ code: 0, stdout: contextResponse, stderr: "" }),
-			on: (name: string, handler: (...args: any[]) => any) => {
-				handlers.set(name, handler)
-			},
-		}
-		const previousTarget = process.env.AGENCY_TARGET
-		const previousWorkbase = process.env.AGENCY_WORKBASE
-		const previousCheckout = process.env.AGENCY_WRITABLE_CHECKOUT
-		delete process.env.AGENCY_WORKBASE
-		delete process.env.AGENCY_WRITABLE_CHECKOUT
-		process.env.AGENCY_TARGET = "execution-unit:task/example"
-		try {
-			const generated = await import(
-				`${pathToFileURL(path).href}?pi-extension=${Date.now()}`
-			)
-			generated.default(pi)
-			const resources = await handlers.get("resources_discover")?.({
-				cwd: taskDirectory,
-				reason: "startup",
-			})
-			expect(resources.skillPaths).toEqual([
-				join(checkoutPath, ".agents/skills"),
-				join(checkoutPath, ".pi/skills"),
-			])
-
-			const prompt = await handlers.get("before_agent_start")?.(
-				{ systemPrompt: "Base prompt" },
-				{ cwd: taskDirectory },
-			)
-			expect(prompt.systemPrompt).toContain("# Managed Agency instructions")
-			expect(prompt.systemPrompt).toContain(
-				`The complete Agency workbase is available at ${root}`,
-			)
-			expect(prompt.systemPrompt).toContain(
-				"active worker for execution-unit:task/example",
-			)
-			expect(prompt.systemPrompt).toContain(
-				`${checkoutPath} as the default implementation directory`,
-			)
-		} finally {
-			if (previousTarget === undefined) delete process.env.AGENCY_TARGET
-			else process.env.AGENCY_TARGET = previousTarget
-			if (previousWorkbase === undefined) delete process.env.AGENCY_WORKBASE
-			else process.env.AGENCY_WORKBASE = previousWorkbase
-			if (previousCheckout === undefined)
-				delete process.env.AGENCY_WRITABLE_CHECKOUT
-			else process.env.AGENCY_WRITABLE_CHECKOUT = previousCheckout
-		}
-	})
-
 	const testWorkerIdentity = async ({
 		target,
 		launchTarget,
@@ -870,7 +733,6 @@ describe("IntegrationService", () => {
 			{ name: "opencode-plugin", state: "managed", changed: true },
 			{ name: "opencode-tui", state: "managed", changed: true },
 			{ name: "opencode-tui-plugin", state: "managed", changed: true },
-			{ name: "pi-extension", state: "managed", changed: true },
 		])
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
 			customRootAgents,
@@ -895,9 +757,6 @@ describe("IntegrationService", () => {
 		expect(
 			await Bun.file(join(root, ".opencode/tui/agency-debug.ts")).text(),
 		).toBe(managedWorkbaseOpencodeTuiPlugin)
-		expect(
-			await Bun.file(join(root, ".pi/extensions/agency-workbase.ts")).text(),
-		).toBe(managedWorkbasePiExtension)
 
 		await unlink(join(root, ".agency/AGENTS.md"))
 		const second = await sync(root)
@@ -962,6 +821,30 @@ describe("IntegrationService", () => {
 		})
 	})
 
+	test("removes a checksum-valid workbase-local Pi extension", async () => {
+		const body = "export default function legacyAgencyExtension() {}\n"
+		const checksum = createHash("sha256").update(body).digest("hex")
+		const path = join(root, ".pi/extensions/agency-workbase.ts")
+		await write(
+			root,
+			".pi/extensions/agency-workbase.ts",
+			`// agency-managed: sha256=${checksum}\n\n${body}`,
+		)
+
+		await sync(root)
+		expect(await Bun.file(path).exists()).toBe(false)
+		expect(await Bun.file(join(root, ".pi")).exists()).toBe(false)
+	})
+
+	test("preserves a customized workbase-local Pi extension", async () => {
+		const custom = "export default function customPiExtension() {}\n"
+		const path = join(root, ".pi/extensions/agency-workbase.ts")
+		await write(root, ".pi/extensions/agency-workbase.ts", custom)
+
+		await sync(root)
+		expect(await Bun.file(path).text()).toBe(custom)
+	})
+
 	test("migrates a checksum-valid plugin from the legacy singular path", async () => {
 		const legacyPath = join(
 			root,
@@ -991,21 +874,6 @@ describe("IntegrationService", () => {
 		expect(await Bun.file(legacyPath).exists()).toBe(false)
 	})
 
-	test("preserves a user-owned Pi extension", async () => {
-		const custom = "export default function customPiExtension() {}\n"
-		await write(root, ".pi/extensions/agency-workbase.ts", custom)
-
-		const result = await sync(root)
-		expect(result.files[5]).toMatchObject({
-			name: "pi-extension",
-			state: "customized",
-			changed: false,
-		})
-		expect(
-			await Bun.file(join(root, ".pi/extensions/agency-workbase.ts")).text(),
-		).toBe(custom)
-	})
-
 	test("preserves user-owned TUI config and diagnostic plugin", async () => {
 		const customConfig = '{"theme":"custom"}\n'
 		const customPlugin =

package/src/services/IntegrationService.ts

@@ -1,6 +1,6 @@
 import { Effect } from "effect"
 import { createHash } from "node:crypto"
-import { join } from "node:path"
+import { dirname, join } from "node:path"
 import { FileSystemService } from "./FileSystemService"
 import { WorkbaseService } from "./WorkbaseService"
 import {
@@ -23,10 +23,19 @@ import {
 	canUpdateManagedWorkbaseOpencodeTuiPlugin,
 	managedWorkbaseOpencodeTuiPlugin,
 } from "../workbase/opencode-tui-plugin-file"
-import {
-	canUpdateManagedWorkbasePiExtension,
-	managedWorkbasePiExtension,
-} from "../workbase/pi-extension-file"
+
+const managedHeaderPattern =
+	/^\/\/ agency-managed: sha256=([a-f0-9]{64})\r?\n\r?\n/
+
+const canRemoveLegacyPiExtension = (content: string) => {
+	const match = content.match(managedHeaderPattern)
+	if (!match?.[1]) return false
+	return (
+		createHash("sha256")
+			.update(content.slice(match[0].length))
+			.digest("hex") === match[1]
+	)
+}
 
 type IntegrationFileState = "managed" | "customized" | "missing" | "drifted"
 
@@ -37,7 +46,6 @@ interface IntegrationFileStatus {
 		| "opencode-plugin"
 		| "opencode-tui"
 		| "opencode-tui-plugin"
-		| "pi-extension"
 	readonly path: string
 	readonly state: IntegrationFileState
 	readonly diagnostic: string
@@ -136,27 +144,6 @@ const describe = (
 							"Run 'agency integration sync' to install /agency-debug.",
 					}
 	}
-	if (name === "pi-extension") {
-		return state === "managed"
-			? {
-					diagnostic:
-						"Agency's managed Pi extension provides whole-workbase context and exposes writable-checkout skills.",
-					remediation: null,
-				}
-			: state === "customized"
-				? {
-						diagnostic:
-							"A user-owned Pi workbase extension is present and was preserved.",
-						remediation: null,
-					}
-				: {
-						diagnostic:
-							"The managed Pi workbase extension needs synchronization.",
-						remediation:
-							"Run 'agency integration sync' to provide workbase context and expose writable-checkout skills in Pi.",
-					}
-	}
-
 	return state === "missing" || state === "drifted"
 		? {
 				diagnostic: "Managed workbase instructions need synchronization.",
@@ -215,12 +202,6 @@ const inspect = (root: string) =>
 			"agency-repository-skills.ts",
 		)
 		const tuiPluginPath = join(opencodeDirectory, "tui", "agency-debug.ts")
-		const piExtensionPath = join(
-			root,
-			".pi",
-			"extensions",
-			"agency-workbase.ts",
-		)
 		const files: IntegrationFileStatus[] = []
 
 		files.push(
@@ -325,22 +306,6 @@ const inspect = (root: string) =>
 			files.push(fileStatus("opencode-tui-plugin", tuiPluginPath, "missing"))
 		}
 
-		if ((yield* fs.readSymlinkTarget(piExtensionPath)) !== null) {
-			files.push(fileStatus("pi-extension", piExtensionPath, "customized"))
-		} else if (yield* fs.exists(piExtensionPath)) {
-			files.push(
-				classify(
-					"pi-extension",
-					piExtensionPath,
-					yield* fs.readFile(piExtensionPath),
-					managedWorkbasePiExtension,
-					canUpdateManagedWorkbasePiExtension,
-				),
-			)
-		} else {
-			files.push(fileStatus("pi-extension", piExtensionPath, "missing"))
-		}
-
 		return files
 	})
 
@@ -418,6 +383,16 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 						yield* canRemoveLegacyOpencodeCommand(root)
 					const removeLegacyOpencodePlugin =
 						yield* canRemoveLegacyOpencodePlugin(root)
+					const legacyPiExtension = join(
+						root,
+						".pi",
+						"extensions",
+						"agency-workbase.ts",
+					)
+					const removeLegacyPiExtension =
+						(yield* fs.readSymlinkTarget(legacyPiExtension)) === null &&
+						(yield* fs.exists(legacyPiExtension)) &&
+						canRemoveLegacyPiExtension(yield* fs.readFile(legacyPiExtension))
 					const files: IntegrationSyncFile[] = []
 
 					for (const status of statuses) {
@@ -442,9 +417,6 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 									status.path,
 									managedWorkbaseOpencodeTuiPlugin,
 								)
-							} else {
-								yield* fs.createDirectory(join(root, ".pi", "extensions"))
-								yield* fs.writeFile(status.path, managedWorkbasePiExtension)
 							}
 						}
 						files.push({
@@ -472,6 +444,13 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 							join(root, ".opencode", "command", "agency.md"),
 						)
 					}
+					if (removeLegacyPiExtension) {
+						yield* fs.deleteFile(legacyPiExtension)
+						yield* fs.deleteDirectoryIfEmpty(dirname(legacyPiExtension))
+						yield* fs.deleteDirectoryIfEmpty(
+							dirname(dirname(legacyPiExtension)),
+						)
+					}
 
 					return { root, files }
 				}),

package/src/services/SyncService.test.ts

@@ -575,6 +575,8 @@ process.stdout.write(${JSON.stringify(JSON.stringify(record))})
 	})
 
 	test("materializes missing workspaces but leaves branch conflicts unresolved", async () => {
+		await Bun.write(join(root, "bin", "gh"), "#!/bin/sh\nprintf '[]\\n'\n")
+		await chmod(join(root, "bin", "gh"), 0o755)
 		for (const [id, branch] of [
 			["missing", "feat/missing"],
 			["conflict", "feat/conflict"],
@@ -649,6 +651,158 @@ process.stdout.write(${JSON.stringify(JSON.stringify(record))})
 		).toBe(false)
 	})
 
+	test("reconciles a recorded merged PR without materializing an absent checkout", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "recorded-merged",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await git(
+			["remote", "set-url", "origin", "git@github.com:example/agency.git"],
+			join(root, "repos/agency"),
+		)
+		await runTestEffect(
+			PullRequestService.pipe(
+				Effect.flatMap((service) =>
+					service.setUrl(
+						"recorded-merged",
+						undefined,
+						"https://github.com/example/agency/pull/42",
+						root,
+					),
+				),
+			),
+		)
+
+		const applied = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({
+						cwd: root,
+						apply: true,
+						taskId: "recorded-merged",
+					}),
+				),
+			),
+		)
+		expect(applied.changes.map((change) => change.kind)).toEqual([
+			"record-pr",
+			"mark-done",
+		])
+		expect(applied.executions[0]?.checkouts).toEqual([])
+		expect(
+			await Bun.file(join(root, "tasks/recorded-merged/code/agency")).exists(),
+		).toBe(false)
+	})
+
+	test("reconciles a uniquely discovered merged PR without materializing", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "discovered-merged",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await git(
+			["remote", "set-url", "origin", "git@github.com:example/agency.git"],
+			join(root, "repos/agency"),
+		)
+
+		const applied = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({
+						cwd: root,
+						apply: true,
+						taskId: "discovered-merged",
+					}),
+				),
+			),
+		)
+		expect(applied.changes.map((change) => change.kind)).toEqual([
+			"record-pr",
+			"mark-done",
+		])
+		expect(applied.executions[0]?.checkouts).toEqual([])
+		expect(
+			await Bun.file(
+				join(root, "tasks/discovered-merged/code/agency"),
+			).exists(),
+		).toBe(false)
+	})
+
+	test("materializes when discovered PR evidence is ambiguous", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "ambiguous",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const gh = await Bun.file(join(root, "bin", "gh")).text()
+		await Bun.write(
+			join(root, "bin", "gh"),
+			gh
+				.replace('[{"number":42', '[{"number":42')
+				.replace(
+					"]\nJSON\n",
+					`,{\"number\":43,\"state\":\"MERGED\",\"title\":\"Ship again\",\"isDraft\":false,\"headRefName\":\"feat/example\",\"baseRefName\":\"main\",\"headRepository\":{\"nameWithOwner\":\"example/agency\"},\"url\":\"https://github.com/example/agency/pull/43\",\"mergedAt\":\"2100-01-01T00:00:00Z\",\"mergeCommit\":{\"oid\":\"def\"},\"mergeable\":\"MERGEABLE\"}]\nJSON\n`,
+				),
+		)
+
+		const applied = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({
+						cwd: root,
+						apply: true,
+						taskId: "ambiguous",
+					}),
+				),
+			),
+		)
+		expect(applied.unresolved).toContainEqual(
+			expect.objectContaining({ kind: "multiple-prs" }),
+		)
+		expect(applied.changes).toContainEqual(
+			expect.objectContaining({ kind: "materialize-workspace" }),
+		)
+		expect(
+			await Bun.file(
+				join(root, "tasks/ambiguous/code/agency/README.md"),
+			).text(),
+		).toBe("example\n")
+	})
+
 	test("leaves a missing checkout registration unresolved", async () => {
 		await runTestEffect(
 			TaskService.pipe(

package/src/services/SyncService.ts

@@ -162,6 +162,46 @@ const commandErrorSummary = (stderr: string, fallback: string) =>
 		.map((line) => line.trim())
 		.find(Boolean) ?? fallback
 
+interface PullRequestQuery {
+	readonly remoteUrl: string | null
+	readonly remoteRepository: string
+	readonly result:
+		| {
+				readonly exitCode: number
+				readonly stdout: string
+				readonly stderr: string
+		  }
+		| undefined
+}
+
+const mergedPullRequestFromGitHub = (
+	data: ExecutionData,
+	query: PullRequestQuery | undefined,
+) => {
+	if (!query?.result || query.result.exitCode !== 0) return null
+	const existing = data.pr ? normalizePullRequestRecord(data.pr) : null
+	const details = existing
+		? [parseJson<Record<string, unknown>>(query.result.stdout, {})]
+		: parseJson<Record<string, unknown>[]>(query.result.stdout, []).filter(
+				(item) =>
+					item.headRefName === data.branch && item.baseRefName === data.base,
+			)
+	if (details.length !== 1) return null
+	const current = recordFromGitHubJson(details[0]!)
+	if (
+		current.merged !== true ||
+		current.headRepository?.toLowerCase() !==
+			query.remoteRepository.toLowerCase() ||
+		current.headBranch !== data.branch ||
+		current.baseRepository?.toLowerCase() !==
+			current.repository.toLowerCase() ||
+		current.baseBranch !== data.base
+	) {
+		return null
+	}
+	return current
+}
+
 export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 	sync: () => ({
 		reconcile: (
@@ -463,6 +503,14 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 					let revision = record.revision
 					const codePath = join(dirname(record.path), "code")
 					const checkoutStates: CheckoutState[] = []
+					const query = prQueries.get(record.key)
+					const remoteMergedPr = config.delivery
+						? null
+						: mergedPullRequestFromGitHub(data, query)
+					const skipCheckoutReconciliation =
+						remoteMergedPr !== null &&
+						data.claim?.state !== "active" &&
+						!data.completion
 					let materialize = false
 					let workspaceConflict = false
 					const declared: readonly (
@@ -473,7 +521,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 						...(data.repos ?? []),
 					]
 
-					for (const checkout of declared) {
+					for (const checkout of skipCheckoutReconciliation ? [] : declared) {
 						const repositoryPath = join(root, "repos", checkout.repo)
 						const checkoutPath = join(codePath, checkout.repo)
 						const kind = "branch" in checkout ? "writable" : "reference"
@@ -811,7 +859,11 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 						state: "none",
 					}
 					let prConflict = false
-					const query = prQueries.get(record.key)!
+					if (!query) {
+						return yield* new SyncError({
+							message: `Missing pull request query for '${record.key}'`,
+						})
+					}
 					const { remoteUrl, remoteRepository } = query
 
 					if (config.delivery && !remoteUrl) {

package/src/workbase/pi-extension-file.ts

@@ -1,158 +0,0 @@
-import { createHash } from "node:crypto"
-
-const managedHeaderPattern =
-	/^\/\/ agency-managed: sha256=([a-f0-9]{64})\r?\n\r?\n/
-
-const checksum = (content: string) =>
-	createHash("sha256").update(content).digest("hex")
-
-const body = `import { existsSync, readFileSync } from "node:fs"
-import { dirname, join, resolve } from "node:path"
-import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent"
-
-type AgencyContext = {
-  root?: string
-  checkout?: string
-  target?: string
-}
-
-const contextTarget = (result: Record<string, any>): string | undefined => {
-  const target = result.target
-  if (target?.kind === "epic") return \`epic:\${target.epicId}\`
-  if (target?.kind === "phase") {
-    return \`execution-unit:phase/\${target.taskId}/\${target.phaseId}\`
-  }
-  if (target?.kind === "task") {
-    return result.authority?.mode === "execution"
-      ? \`execution-unit:task/\${target.taskId}\`
-      : \`task:\${target.taskId}\`
-  }
-}
-
-const discoverWorkbase = (directory: string) => {
-  let current = directory
-  while (true) {
-    if (existsSync(join(current, "agency.json"))) return current
-    const parent = dirname(current)
-    if (parent === current) return
-    current = parent
-  }
-}
-
-const discoverCheckout = (directory: string, root: string | undefined) => {
-  if (!root) return
-  let current = directory
-  while (current.startsWith(root)) {
-    for (const name of ["PHASE.md", "TASK.md"]) {
-      const document = join(current, name)
-      if (!existsSync(document)) continue
-      const repo = readFileSync(document, "utf8").match(/^repo:\\s*([^\\s]+)\\s*$/m)?.[1]
-      if (!repo) return
-      const checkout = join(current, "code", repo.replace(/^['\"]|['\"]$/g, ""))
-      return existsSync(checkout) ? checkout : undefined
-    }
-    if (current === root) return
-    current = dirname(current)
-  }
-}
-
-const agencyContext = async (
-  pi: ExtensionAPI,
-  directory: string,
-): Promise<AgencyContext | undefined> => {
-  const task = process.env.AGENCY_TASK_ID
-  const phase = process.env.AGENCY_PHASE_ID
-  const args = task
-    ? ["context", "--task", task, ...(phase ? ["--phase", phase] : []), "--compact", "--json"]
-    : ["context", ".", "--compact", "--json"]
-  const command = await pi.exec("agency", args, { timeout: 5000 })
-  if (command.code !== 0) return
-  const envelope = JSON.parse(command.stdout)
-  if (envelope.ok !== true) return
-  const result = envelope.result ?? {}
-  const target = contextTarget(result)
-  const document = result.target?.path
-  const status = result.documents?.phase?.data?.status ?? result.documents?.task?.data?.status
-  if (
-    result.validation?.valid !== true ||
-    !target ||
-    !document ||
-    dirname(document) !== resolve(directory) ||
-    (target.startsWith("execution-unit:") &&
-      (!result.authority?.writable?.checkoutPath || status !== "working"))
-  ) return
-  return {
-    root: result.workbase?.root,
-    checkout: result.authority?.writable?.checkoutPath,
-    target,
-  }
-}
-
-const extension = (pi: ExtensionAPI) => {
-  const contexts = new Map<string, Promise<AgencyContext | undefined>>()
-  const runtimeContext = (directory: string) => {
-    let context = contexts.get(directory)
-    if (!context) {
-      context = agencyContext(pi, directory).catch(() => undefined)
-      contexts.set(directory, context)
-    }
-    return context
-  }
-
-  pi.on("resources_discover", async (event) => {
-    const context = await runtimeContext(event.cwd)
-    const root = process.env.AGENCY_WORKBASE ?? context?.root ?? discoverWorkbase(event.cwd)
-    const checkout = process.env.AGENCY_WRITABLE_CHECKOUT ?? context?.checkout ?? discoverCheckout(event.cwd, root)
-    if (!checkout) return
-
-    const skillPaths = [
-      join(checkout, ".claude", "skills"),
-      join(checkout, ".agents", "skills"),
-      join(checkout, ".opencode", "skill"),
-      join(checkout, ".opencode", "skills"),
-      join(checkout, CONFIG_DIR_NAME, "skills"),
-    ].filter(existsSync)
-    if (skillPaths.length === 0) return
-    return { skillPaths: [...new Set(skillPaths)] }
-  })
-
-  pi.on("before_agent_start", async (event, ctx) => {
-    const context = await runtimeContext(ctx.cwd)
-    const root = process.env.AGENCY_WORKBASE ?? context?.root ?? discoverWorkbase(ctx.cwd)
-    if (!root) return
-    const checkout = process.env.AGENCY_WRITABLE_CHECKOUT ?? context?.checkout ?? discoverCheckout(ctx.cwd, root)
-    const instructionsPath = join(root, ".agency", "AGENTS.md")
-    const instructions = existsSync(instructionsPath)
-      ? readFileSync(instructionsPath, "utf8").trim()
-      : undefined
-    const activeTarget = process.env.AGENCY_TARGET
-    const worker = activeTarget && context?.target === activeTarget
-      ? \`Agency verified this Pi session as the active worker for \${activeTarget}. Perform the assigned work directly. Do not invoke agency work for this target or launch a replacement worker.\`
-      : undefined
-    const access = \`The complete Agency workbase is available at \${root}. Use absolute paths under that root when workbase context is needed. Agency context remains the authority for writes.\`
-    const implementation = checkout
-      ? \`Pi remains rooted in the task or phase directory for Agency instructions and context. Treat \${checkout} as the default implementation directory for source reads, edits, repository status, builds, tests, formatting, and other repository-local commands. Run Agency lifecycle and context commands from the task or phase directory. Any reference checkouts reported by Agency context are read-only.\`
-      : undefined
-
-    return {
-      systemPrompt: [event.systemPrompt, instructions, access, worker, implementation]
-        .filter(Boolean)
-        .join("\\n\\n"),
-    }
-  })
-}
-
-export default extension
-`
-
-const renderManagedWorkbasePiExtension = (content: string) =>
-	`// agency-managed: sha256=${checksum(content)}\n\n${content}`
-
-export const managedWorkbasePiExtension = renderManagedWorkbasePiExtension(body)
-
-export const canUpdateManagedWorkbasePiExtension = (content: string) => {
-	const match = content.match(managedHeaderPattern)
-	if (!match?.[1]) return false
-
-	return checksum(content.slice(match[0].length)) === match[1]
-}