@markjaquith/agency 2.35.0 → 2.37.0

package/README.md

@@ -47,9 +47,11 @@ and customized documents remain valid.
 
 ```text
 workbase/
-  AGENTS.md                # managed workbase instructions
+  AGENTS.md                # optional user-owned workbase instructions
+  .agency/
+    AGENTS.md              # managed Agency instructions
   .opencode/
-    opencode.jsonc         # managed whole-workbase reference
+    opencode.jsonc         # managed instructions and whole-workbase reference
   agency.json              # tracked config and portable repository declarations
   repos/                   # ignored local materializations
     frontend/              # bare Git repository or symlink
@@ -77,18 +79,26 @@ workbase/
 ```
 
 Agency keeps discovery and other observational commands read-only. Run
-`agency integration status` to inspect `AGENTS.md` and
+`agency integration status` to inspect `.agency/AGENTS.md` and
 `.opencode/opencode.jsonc`, then `agency integration sync` to create missing
 files or refresh checksum-safe managed files. Customized files are reported but
-never overwritten.
-
-The OpenCode config advertises the complete workbase as one portable relative
-reference. `agency work` sets `OPENCODE_CONFIG` to the managed file and injects
-runtime-only absolute rules that allow external access across the workbase while
-denying edits outside the execution unit's writable checkout. This makes the
-config effective from nested task and phase Git checkouts without persisting a
-machine-specific path or granting access outside the workbase. Bash and Agency
-operations must still follow the write authority reported by `agency context`.
+never overwritten. The root `AGENTS.md` is user-owned and is not inspected or
+modified by Agency.
+
+When upgrading an existing workbase, synchronization moves a checksum-valid
+Agency-managed root `AGENTS.md` to `.agency/AGENTS.md` once the OpenCode config
+can load the hidden file. A customized root file, including a symlink, is
+preserved as user-owned content.
+
+The OpenCode config loads Agency's hidden instructions in addition to any
+user-owned root `AGENTS.md` and advertises the complete workbase as one portable
+relative reference. `agency work` sets `OPENCODE_CONFIG` to the managed file and
+injects runtime-only absolute rules that allow external access across the
+workbase while denying edits outside the execution unit's writable checkout.
+This makes the config effective from nested task and phase Git checkouts without
+persisting a machine-specific path or granting access outside the workbase. Bash
+and Agency operations must still follow the write authority reported by
+`agency context`.
 
 Repository aliases and canonical fetch remotes are declared in tracked
 `agency.json`; local bare clones and symlinks remain ignored under

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.35.0",
+  "version": "2.37.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

package/src/commands/doctor.test.ts

@@ -114,7 +114,7 @@ status: open
 	test("reports repository, ref, remote, and managed-file failures", async () => {
 		await Bun.$`git -C ${repository} remote remove origin`
 		await Bun.$`git -C ${repository} branch -m other`
-		await write(root, "AGENTS.md", managedAgents("old\n"))
+		await write(root, ".agency/AGENTS.md", managedAgents("old\n"))
 
 		const logs = await captureLogs(() =>
 			runTestEffect(doctor({ cwd: root, json: true })),
@@ -153,7 +153,7 @@ status: open
 		expect(check).toMatchObject({
 			level: "warning",
 			status: "fail",
-			message: expect.stringContaining("cannot guarantee whole-workbase"),
+			message: expect.stringContaining("cannot guarantee its instructions"),
 			remediation: expect.stringContaining("global config"),
 		})
 		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
@@ -181,6 +181,7 @@ status: open
 		}
 
 		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
+		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(false)
 		expect(
 			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
 		).toBe(false)

package/src/commands/init.test.ts

@@ -33,11 +33,13 @@ describe("init command", () => {
 		expect(await Bun.file(join(root, ".gitignore")).text()).toBe(
 			"/repos/\n/tasks/*/code/\n/tasks/*/phases/*/code/\n",
 		)
-		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(true)
+		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
+		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(true)
 		const opencode = await Bun.file(
 			join(root, ".opencode/opencode.jsonc"),
 		).text()
 		const config = JSON.parse(opencode.slice(opencode.indexOf("\n\n") + 2))
+		expect(config.instructions).toEqual([".agency/AGENTS.md"])
 		expect(config.references).toEqual({
 			workbase: expect.objectContaining({ path: ".." }),
 		})

package/src/commands/integration.test.ts

@@ -50,7 +50,7 @@ describe("integration command", () => {
 			runTestEffect(integration({ subcommand: "status", cwd: root })),
 		)
 
-		expect(logs.join("\n")).toContain("cannot guarantee whole-workbase")
+		expect(logs.join("\n")).toContain("cannot guarantee its instructions")
 		expect(logs.join("\n")).toContain("global config")
 	})
 
@@ -63,7 +63,8 @@ describe("integration command", () => {
 			{ name: "agents", state: "managed", changed: true },
 			{ name: "opencode", state: "managed", changed: true },
 		])
-		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(true)
+		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
+		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(true)
 		expect(
 			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
 		).toBe(true)

package/src/services/FileSystemService.ts

@@ -9,6 +9,7 @@ import {
 	rmdir,
 	stat,
 	symlink,
+	unlink,
 } from "node:fs/promises"
 import { spawnProcess } from "../utils/process"
 
@@ -117,6 +118,16 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 						}),
 				}),
 
+			deleteFile: (path: string) =>
+				Effect.tryPromise({
+					try: () => unlink(path),
+					catch: (error) =>
+						new FileSystemError({
+							message: `Failed to delete file: ${path}`,
+							cause: error,
+						}),
+				}),
+
 			createDirectory: (path: string) =>
 				Effect.tryPromise({
 					try: () => mkdir(path, { recursive: true }),

package/src/services/IntegrationService.test.ts

@@ -47,9 +47,9 @@ describe("IntegrationService", () => {
 			"missing",
 			"missing",
 		])
-		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
+		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(false)
 
-		await write(root, "AGENTS.md", managedWorkbaseAgents)
+		await write(root, ".agency/AGENTS.md", managedWorkbaseAgents)
 		await write(root, ".opencode/opencode.jsonc", managedWorkbaseOpencode)
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"managed",
@@ -58,7 +58,7 @@ describe("IntegrationService", () => {
 	})
 
 	test("reports customized and checksum-safe drifted files", async () => {
-		await write(root, "AGENTS.md", "# Custom instructions\n")
+		await write(root, ".agency/AGENTS.md", "# Custom instructions\n")
 		await write(
 			root,
 			".opencode/opencode.jsonc",
@@ -97,6 +97,7 @@ describe("IntegrationService", () => {
 	test("grants OpenCode access to the complete workbase", () => {
 		const config = JSON.parse(managedBody(managedWorkbaseOpencode))
 
+		expect(config.instructions).toEqual([".agency/AGENTS.md"])
 		expect(config.references).toEqual({
 			workbase: {
 				path: "..",
@@ -151,8 +152,10 @@ describe("IntegrationService", () => {
 	})
 
 	test("syncs missing and drifted files while preserving customized files", async () => {
-		const customAgents = "# Custom instructions\n"
-		await write(root, "AGENTS.md", customAgents)
+		const customRootAgents = "# User-owned workbase instructions\n"
+		const customManagedAgents = "# Customized Agency instructions\n"
+		await write(root, "AGENTS.md", customRootAgents)
+		await write(root, ".agency/AGENTS.md", customManagedAgents)
 		await write(
 			root,
 			".opencode/opencode.jsonc",
@@ -164,14 +167,50 @@ describe("IntegrationService", () => {
 			{ name: "agents", state: "customized", changed: false },
 			{ name: "opencode", state: "managed", changed: true },
 		])
-		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(customAgents)
+		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
+			customRootAgents,
+		)
+		expect(await Bun.file(join(root, ".agency/AGENTS.md")).text()).toBe(
+			customManagedAgents,
+		)
 		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
 			managedWorkbaseOpencode,
 		)
 
-		await unlink(join(root, "AGENTS.md"))
+		await unlink(join(root, ".agency/AGENTS.md"))
 		const second = await sync(root)
 		expect(second.files[0]).toMatchObject({ state: "managed", changed: true })
+		expect(await Bun.file(join(root, ".agency/AGENTS.md")).text()).toBe(
+			managedWorkbaseAgents,
+		)
+		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
+			customRootAgents,
+		)
+	})
+
+	test("migrates checksum-valid root instructions", async () => {
+		await write(root, "AGENTS.md", managedWorkbaseAgents)
+
+		const result = await sync(root)
+
+		expect(result.files[0]).toMatchObject({ state: "managed", changed: true })
+		expect(await Bun.file(join(root, ".agency/AGENTS.md")).text()).toBe(
+			managedWorkbaseAgents,
+		)
+		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
+	})
+
+	test("preserves legacy instructions when the OpenCode config is customized", async () => {
+		await write(root, "AGENTS.md", managedWorkbaseAgents)
+		await write(root, ".opencode/opencode.json", '{"model":"test/model"}\n')
+
+		const result = await sync(root)
+
+		expect(result.files[0]).toMatchObject({ state: "managed", changed: true })
+		expect(result.files[1]).toMatchObject({
+			state: "customized",
+			changed: false,
+		})
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
 			managedWorkbaseAgents,
 		)
@@ -198,14 +237,16 @@ describe("IntegrationService", () => {
 			"# Previous Agency instructions\n",
 			" -->",
 		)}User edit\n`
-		await write(root, "AGENTS.md", tampered)
+		await write(root, ".agency/AGENTS.md", tampered)
 
 		const result = await sync(root)
 		expect(result.files[0]).toMatchObject({
 			state: "customized",
 			changed: false,
 		})
-		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(tampered)
+		expect(await Bun.file(join(root, ".agency/AGENTS.md")).text()).toBe(
+			tampered,
+		)
 	})
 
 	test("does not overwrite a user-modified OpenCode configuration", async () => {
@@ -228,7 +269,8 @@ describe("IntegrationService", () => {
 	test("does not follow symlinked integration files", async () => {
 		const target = join(root, "custom-agents.md")
 		await Bun.write(target, "# External instructions\n")
-		await symlink(target, join(root, "AGENTS.md"))
+		await mkdir(join(root, ".agency"), { recursive: true })
+		await symlink(target, join(root, ".agency/AGENTS.md"))
 
 		const result = await sync(root)
 		expect(result.files[0]).toMatchObject({

package/src/services/IntegrationService.ts

@@ -33,23 +33,23 @@ const describe = (
 		if (state === "managed") {
 			return {
 				diagnostic:
-					"Agency's managed OpenCode launch config is ready to provide whole-workbase read access.",
+					"Agency's managed OpenCode launch config is ready to load Agency instructions and provide whole-workbase read access.",
 				remediation: null,
 			}
 		}
 		if (state === "customized") {
 			return {
 				diagnostic:
-					"Agency cannot guarantee whole-workbase read access from this customized OpenCode config.",
+					"Agency cannot guarantee its instructions or whole-workbase read access from this customized OpenCode config.",
 				remediation:
 					"Back up and remove the customized file, run 'agency integration sync', then move any retained custom settings to OpenCode's global config.",
 			}
 		}
 		return {
 			diagnostic:
-				"Agency OpenCode launches cannot load current whole-workbase access.",
+				"Agency OpenCode launches cannot load current Agency instructions or whole-workbase access.",
 			remediation:
-				"Run 'agency integration sync' to install whole-workbase OpenCode access.",
+				"Run 'agency integration sync' to install Agency instructions and whole-workbase OpenCode access.",
 		}
 	}
 
@@ -94,7 +94,7 @@ const classify = (
 const inspect = (root: string) =>
 	Effect.gen(function* () {
 		const fs = yield* FileSystemService
-		const agentsPath = join(root, "AGENTS.md")
+		const agentsPath = join(root, ".agency", "AGENTS.md")
 		const opencodeDirectory = join(root, ".opencode")
 		const opencodePath = join(opencodeDirectory, "opencode.jsonc")
 		const opencodeJsonPath = join(opencodeDirectory, "opencode.json")
@@ -138,6 +138,18 @@ const inspect = (root: string) =>
 		return files
 	})
 
+const canRemoveLegacyAgents = (root: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const path = join(root, "AGENTS.md")
+		if (
+			(yield* fs.readSymlinkTarget(path)) !== null ||
+			!(yield* fs.exists(path))
+		)
+			return false
+		return canUpdateManagedWorkbaseAgents(yield* fs.readFile(path))
+	})
+
 export class IntegrationService extends Effect.Service<IntegrationService>()(
 	"IntegrationService",
 	{
@@ -155,13 +167,19 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 					const workbase = yield* WorkbaseService
 					const root = yield* workbase.discover(startPath)
 					const statuses = yield* inspect(root)
+					const removeLegacyAgents =
+						statuses.some(
+							(status) =>
+								status.name === "opencode" && status.state !== "customized",
+						) && (yield* canRemoveLegacyAgents(root))
 					const files: IntegrationSyncFile[] = []
 
 					for (const status of statuses) {
-						const changed =
+						const needsWrite =
 							status.state === "missing" || status.state === "drifted"
-						if (changed) {
+						if (needsWrite) {
 							if (status.name === "agents") {
+								yield* fs.createDirectory(join(root, ".agency"))
 								yield* fs.writeFile(status.path, managedWorkbaseAgents)
 							} else {
 								yield* fs.createDirectory(join(root, ".opencode"))
@@ -172,12 +190,15 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 							...fileStatus(
 								status.name,
 								status.path,
-								changed ? "managed" : status.state,
+								needsWrite ? "managed" : status.state,
 							),
-							changed,
+							changed:
+								needsWrite || (status.name === "agents" && removeLegacyAgents),
 						})
 					}
 
+					if (removeLegacyAgents) yield* fs.deleteFile(join(root, "AGENTS.md"))
+
 					return { root, files }
 				}),
 		}),

package/src/utils/interactive.pty.test.ts

@@ -0,0 +1,128 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { join } from "node:path"
+import { cleanupTempDir, createTempDir } from "../test-utils"
+
+const projectRoot = join(import.meta.dir, "../..")
+const cliPath = join(projectRoot, "cli.ts")
+const tempDirs: string[] = []
+
+afterEach(() => Promise.all(tempDirs.splice(0).map(cleanupTempDir)))
+
+const modes = (terminal: Bun.Terminal) => ({
+	input: terminal.inputFlags,
+	output: terminal.outputFlags,
+	local: terminal.localFlags,
+	control: terminal.controlFlags,
+})
+
+const waitFor = async (condition: () => boolean, output: () => string) => {
+	const deadline = Date.now() + 8_000
+	while (!condition()) {
+		if (Date.now() >= deadline) {
+			throw new Error(`Timed out waiting for terminal output:\n${output()}`)
+		}
+		await Bun.sleep(10)
+	}
+}
+
+const waitForExit = (subprocess: Bun.Subprocess, output: () => string) =>
+	new Promise<number>((resolve, reject) => {
+		const timeout = setTimeout(() => {
+			reject(new Error(`Timed out waiting for CLI exit:\n${output()}`))
+		}, 8_000)
+		subprocess.exited.then(
+			(exitCode) => {
+				clearTimeout(timeout)
+				resolve(exitCode)
+			},
+			(error) => {
+				clearTimeout(timeout)
+				reject(error)
+			},
+		)
+	})
+
+const createWorkbase = async () => {
+	const root = await createTempDir()
+	tempDirs.push(root)
+	const initialized = Bun.spawnSync(
+		[process.execPath, cliPath, "init", root, "--silent"],
+		{ stdout: "pipe", stderr: "pipe" },
+	)
+	if (initialized.exitCode !== 0) {
+		throw new Error(new TextDecoder().decode(initialized.stderr))
+	}
+	return root
+}
+
+const runPrompt = async (
+	drive: (terminal: Bun.Terminal, output: () => string) => Promise<void>,
+) => {
+	const root = await createWorkbase()
+	const decoder = new TextDecoder()
+	let output = ""
+	const terminal = new Bun.Terminal({
+		cols: 80,
+		rows: 24,
+		data: (_terminal, bytes) => {
+			output += decoder.decode(bytes, { stream: true })
+		},
+	})
+	const initialModes = modes(terminal)
+	const subprocess = Bun.spawn([process.execPath, cliPath, "task", "new"], {
+		cwd: root,
+		env: { ...process.env, TERM: "xterm-256color" },
+		terminal,
+	})
+
+	try {
+		await waitFor(
+			() => output.includes("Task ID:"),
+			() => output,
+		)
+		const activeModes = modes(terminal)
+		expect(activeModes).not.toEqual(initialModes)
+		await drive(terminal, () => output)
+		const exitCode = await waitForExit(subprocess, () => output)
+		output += decoder.decode()
+		expect(exitCode).toBe(1)
+		expect(modes(terminal)).toEqual(initialModes)
+		expect(output.lastIndexOf("\x1b[?25h")).toBeGreaterThan(
+			output.lastIndexOf("\x1b[?25l"),
+		)
+		expect(output.lastIndexOf("\x1b[?2004l")).toBeGreaterThan(
+			output.lastIndexOf("\x1b[?2004h"),
+		)
+		return output
+	} finally {
+		if (subprocess.exitCode === null) {
+			subprocess.kill("SIGKILL")
+			await subprocess.exited
+		}
+		terminal.close()
+	}
+}
+
+describe("interactive CLI terminal restoration", () => {
+	test("restores terminal state after submission, resize, and escape", async () => {
+		const output = await runPrompt(async (terminal, currentOutput) => {
+			terminal.resize(30, 8)
+			terminal.write("pty-contract\r")
+			await waitFor(
+				() => currentOutput().includes("Ticket URL (optional):"),
+				currentOutput,
+			)
+			terminal.write("\x1b")
+		})
+
+		expect(output).toContain("Failed to read task input")
+	}, 12_000)
+
+	test("restores terminal state after ctrl-c", async () => {
+		const output = await runPrompt(async (terminal) => {
+			terminal.write("\x03")
+		})
+
+		expect(output).toContain("Failed to read task input")
+	}, 12_000)
+})

package/src/utils/interactive.test.tsx

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test"
+import { KeyCodes, type MockInput } from "@opentui/core/testing"
 import { testRender } from "@opentui/solid"
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"
 import { tmpdir } from "node:os"
@@ -10,6 +11,34 @@ import {
 	interactiveRendererConfig,
 } from "./interactive"
 
+const submitEditedText = async (
+	edit: (input: MockInput) => void | Promise<void>,
+) => {
+	let submitted: string | null | undefined
+	const setup = await testRender(
+		() => (
+			<InteractiveTextPrompt
+				prompt="Text"
+				onDone={(value) => {
+					submitted = value
+				}}
+			/>
+		),
+		{ width: 60, height: 4 },
+	)
+	try {
+		await setup.renderer.setupTerminal()
+		await setup.renderOnce()
+		await Bun.sleep(0)
+		await edit(setup.mockInput)
+		setup.mockInput.pressEnter()
+		await setup.waitFor(() => submitted !== undefined)
+		return submitted
+	} finally {
+		setup.renderer.destroy()
+	}
+}
+
 describe("OpenTUI interaction", () => {
 	test("selects the Solid JSX runtime without the project preload", async () => {
 		const source = await Bun.file(
@@ -109,8 +138,8 @@ describe("OpenTUI interaction", () => {
 		expect(await selectAfter("down")).toBe("web")
 	})
 
-	test("uses printable j, k, and q characters as the fuzzy query", async () => {
-		for (const query of ["j", "k", "q"]) {
+	test("uses printable j, k, q, and ? characters as the fuzzy query", async () => {
+		for (const query of ["j", "k", "q", "?"]) {
 			let selected: string | null | undefined
 			const setup = await testRender(
 				() => (
@@ -141,6 +170,163 @@ describe("OpenTUI interaction", () => {
 		}
 	})
 
+	test("supports the readline movement and deletion contract", async () => {
+		const cases = [
+			{
+				name: "left arrow",
+				expected: "aXb",
+				edit: async (input: MockInput) => {
+					await input.typeText("ab")
+					input.pressArrow("left")
+					await input.typeText("X")
+				},
+			},
+			{
+				name: "home and end",
+				expected: "XabY",
+				edit: async (input: MockInput) => {
+					await input.typeText("ab")
+					input.pressKey(KeyCodes.HOME)
+					await input.typeText("X")
+					input.pressKey(KeyCodes.END)
+					await input.typeText("Y")
+				},
+			},
+			{
+				name: "backspace and delete",
+				expected: "a",
+				edit: async (input: MockInput) => {
+					await input.typeText("abc")
+					input.pressBackspace()
+					input.pressArrow("left")
+					input.pressKey(KeyCodes.DELETE)
+				},
+			},
+			{
+				name: "ctrl-a and ctrl-e",
+				expected: "XabY",
+				edit: async (input: MockInput) => {
+					await input.typeText("ab")
+					input.pressKey("a", { ctrl: true })
+					await input.typeText("X")
+					input.pressKey("e", { ctrl: true })
+					await input.typeText("Y")
+				},
+			},
+			{
+				name: "ctrl-b and ctrl-f",
+				expected: "aXb",
+				edit: async (input: MockInput) => {
+					await input.typeText("ab")
+					input.pressKey("b", { ctrl: true })
+					input.pressKey("b", { ctrl: true })
+					input.pressKey("f", { ctrl: true })
+					await input.typeText("X")
+				},
+			},
+			{
+				name: "meta-b and meta-f",
+				expected: "one Xtwo",
+				edit: async (input: MockInput) => {
+					await input.typeText("one two")
+					input.pressKey("b", { meta: true })
+					input.pressKey("b", { meta: true })
+					input.pressKey("f", { meta: true })
+					await input.typeText("X")
+				},
+			},
+			{
+				name: "ctrl-u",
+				expected: "c",
+				edit: async (input: MockInput) => {
+					await input.typeText("abc")
+					input.pressArrow("left")
+					input.pressKey("u", { ctrl: true })
+				},
+			},
+			{
+				name: "ctrl-k",
+				expected: "ab",
+				edit: async (input: MockInput) => {
+					await input.typeText("abc")
+					input.pressArrow("left")
+					input.pressKey("k", { ctrl: true })
+				},
+			},
+			{
+				name: "ctrl-w",
+				expected: "one ",
+				edit: async (input: MockInput) => {
+					await input.typeText("one two")
+					input.pressKey("w", { ctrl: true })
+				},
+			},
+			{
+				name: "ctrl-d",
+				expected: "ab",
+				edit: async (input: MockInput) => {
+					await input.typeText("abc")
+					input.pressArrow("left")
+					input.pressKey("d", { ctrl: true })
+				},
+			},
+			{
+				name: "ctrl-h",
+				expected: "ab",
+				edit: async (input: MockInput) => {
+					await input.typeText("abc")
+					input.pressKey("h", { ctrl: true })
+				},
+			},
+		]
+
+		for (const contract of cases) {
+			expect(await submitEditedText(contract.edit), contract.name).toBe(
+				contract.expected,
+			)
+		}
+	})
+
+	test("yanks the most recently killed text in both prompt inputs", async () => {
+		expect(
+			await submitEditedText(async (input) => {
+				await input.typeText("one two")
+				input.pressKey("w", { ctrl: true })
+				input.pressKey("y", { ctrl: true })
+			}),
+		).toBe("one two")
+
+		let selected: string | null | undefined
+		const setup = await testRender(
+			() => (
+				<InteractiveSelectPrompt
+					prompt="Repository"
+					choices={[
+						{ key: "agency", label: "agency" },
+						{ key: "web", label: "web" },
+					]}
+					onDone={(value) => {
+						selected = value
+					}}
+				/>
+			),
+			{ width: 60, height: 4 },
+		)
+		try {
+			await setup.renderer.setupTerminal()
+			await setup.renderOnce()
+			await Bun.sleep(0)
+			await setup.mockInput.typeText("web")
+			setup.mockInput.pressKey("u", { ctrl: true })
+			setup.mockInput.pressKey("y", { ctrl: true })
+			setup.mockInput.pressEnter()
+			await setup.waitFor(() => selected !== undefined)
+			expect(selected).toBe("web")
+		} finally {
+			setup.renderer.destroy()
+		}
+	})
+
 	test("does not select an empty result and supports ctrl-u editing", async () => {
 		let selected: string | null | undefined
 		const setup = await testRender(
@@ -232,6 +418,98 @@ describe("OpenTUI interaction", () => {
 		}
 	})
 
+	test("keeps empty and single-item list boundaries safe", async () => {
+		let emptyResult: string | null | undefined
+		const empty = await testRender(
+			() => (
+				<InteractiveSelectPrompt
+					prompt="Empty"
+					choices={[]}
+					onDone={(value) => {
+						emptyResult = value
+					}}
+				/>
+			),
+			{ width: 60, height: 4 },
+		)
+		try {
+			await empty.renderer.setupTerminal()
+			await empty.renderOnce()
+			await Bun.sleep(0)
+			empty.mockInput.pressArrow("up")
+			empty.mockInput.pressArrow("down")
+			empty.mockInput.pressKey("p", { ctrl: true })
+			empty.mockInput.pressKey("n", { ctrl: true })
+			empty.mockInput.pressEnter()
+			await Bun.sleep(0)
+			expect(emptyResult).toBeUndefined()
+			expect(empty.captureCharFrame()).toContain("No matches")
+		} finally {
+			empty.renderer.destroy()
+		}
+
+		for (const move of ["up", "down"] as const) {
+			let singleResult: string | null | undefined
+			const single = await testRender(
+				() => (
+					<InteractiveSelectPrompt
+						prompt="Single"
+						choices={[{ key: "one", label: "One" }]}
+						onDone={(value) => {
+							singleResult = value
+						}}
+					/>
+				),
+				{ width: 60, height: 4 },
+			)
+			try {
+				await single.renderer.setupTerminal()
+				await single.renderOnce()
+				await Bun.sleep(0)
+				single.mockInput.pressArrow(move)
+				single.mockInput.pressEnter()
+				await single.waitFor(() => singleResult !== undefined)
+				expect(singleResult).toBe("one")
+			} finally {
+				single.renderer.destroy()
+			}
+		}
+	})
+
+	test("remains usable after a narrow terminal resize", async () => {
+		let selected: string | null | undefined
+		const setup = await testRender(
+			() => (
+				<InteractiveSelectPrompt
+					prompt="Repository with a long prompt"
+					choices={[
+						{ key: "agency", label: "agency" },
+						{ key: "docs", label: "docs" },
+					]}
+					onDone={(value) => {
+						selected = value
+					}}
+				/>
+			),
+			{ width: 60, height: 4 },
+		)
+		try {
+			await setup.renderer.setupTerminal()
+			await setup.renderOnce()
+			await Bun.sleep(0)
+			setup.resize(18, 4)
+			await setup.renderOnce()
+			await setup.mockInput.typeText("docs")
+			await setup.renderOnce()
+			expect(setup.captureCharFrame()).toContain("> docs")
+			setup.mockInput.pressEnter()
+			await setup.waitFor(() => selected !== undefined)
+			expect(selected).toBe("docs")
+		} finally {
+			setup.renderer.destroy()
+		}
+	})
+
 	test("submits text and cancels with ctrl-c or escape", async () => {
 		let submitted: string | null | undefined
 		const input = await testRender(

package/src/utils/interactive.tsx

@@ -34,9 +34,77 @@ interface PromptProps<T> {
 const isCancel = (key: { name: string; ctrl: boolean }) =>
 	key.name === "escape" || (key.ctrl && key.name === "c")
 
+interface PromptKey {
+	readonly name: string
+	readonly ctrl: boolean
+	preventDefault(): void
+	stopPropagation(): void
+}
+
+const removedText = (before: string, after: string) => {
+	let start = 0
+	while (
+		start < before.length &&
+		start < after.length &&
+		before[start] === after[start]
+	) {
+		start++
+	}
+
+	let end = 0
+	while (
+		before[before.length - end - 1] === after[after.length - end - 1] &&
+		end < before.length - start &&
+		end < after.length - start
+	) {
+		end++
+	}
+
+	return before.slice(start, before.length - end)
+}
+
+const createReadlineEditing = (
+	getInput: () => TextareaRenderable | undefined,
+	onInput?: (value: string) => void,
+) => {
+	let value = ""
+	let killBuffer = ""
+	let beforeKill: string | undefined
+
+	return {
+		get value() {
+			return value
+		},
+		handleInput(next: string) {
+			if (beforeKill !== undefined) {
+				const killed = removedText(beforeKill, next)
+				if (killed) killBuffer = killed
+				beforeKill = undefined
+			}
+			value = next
+			onInput?.(next)
+		},
+		handleKey(key: PromptKey) {
+			const current = getInput()?.plainText
+			if (current !== undefined && current !== value) this.handleInput(current)
+			if (!key.ctrl) return false
+			if (key.name === "y") {
+				key.preventDefault()
+				key.stopPropagation()
+				if (killBuffer) getInput()?.insertText(killBuffer)
+				return true
+			}
+			if (key.name === "u" || key.name === "k" || key.name === "w") {
+				beforeKill = value
+			}
+			return false
+		},
+	}
+}
+
 export const InteractiveTextPrompt = (props: PromptProps<string>) => {
 	let input: TextareaRenderable | undefined
-	let value = ""
+	const editing = createReadlineEditing(() => input)
 	useKeyboard((key) => {
 		if (isCancel(key)) {
 			key.preventDefault()
@@ -44,10 +112,11 @@ export const InteractiveTextPrompt = (props: PromptProps<string>) => {
 			props.onDone(null)
 			return
 		}
+		if (editing.handleKey(key)) return
 		if (key.name !== "return") return
 		key.preventDefault()
 		key.stopPropagation()
-		props.onDone(value)
+		props.onDone(editing.value)
 	})
 
 	return (
@@ -59,7 +128,7 @@ export const InteractiveTextPrompt = (props: PromptProps<string>) => {
 				wrapMode="word"
 				keyBindings={[{ name: "return", action: "submit" }]}
 				onContentChange={() => {
-					value = input?.plainText ?? ""
+					editing.handleInput(input?.plainText ?? "")
 				}}
 				ref={(next) => {
 					input = next
@@ -68,7 +137,9 @@ export const InteractiveTextPrompt = (props: PromptProps<string>) => {
 					})
 				}}
 			/>
-			<text fg="#6c7086">enter submit | esc cancel</text>
+			<text fg="#6c7086" wrapMode="none">
+				enter submit | esc cancel | ctrl-y yank
+			</text>
 		</box>
 	)
 }
@@ -145,6 +216,7 @@ export const fuzzyChoices = (
 export const InteractiveSelectPrompt = (props: SelectPromptProps) => {
 	let input: TextareaRenderable | undefined
 	const [query, setQuery] = createSignal("")
+	const editing = createReadlineEditing(() => input, setQuery)
 	const [selected, setSelected] = createSignal(0)
 	const choices = createMemo(() => fuzzyChoices(props.choices, query()))
 	const move = (offset: -1 | 1) => {
@@ -171,6 +243,7 @@ export const InteractiveSelectPrompt = (props: SelectPromptProps) => {
 			move(1)
 			return
 		}
+		if (editing.handleKey(key)) return
 		if (key.name !== "return") return
 		key.preventDefault()
 		key.stopPropagation()
@@ -207,7 +280,7 @@ export const InteractiveSelectPrompt = (props: SelectPromptProps) => {
 					placeholder="filter"
 					keyBindings={[{ name: "return", action: "submit" }]}
 					onContentChange={() => {
-						setQuery(input?.plainText ?? "")
+						editing.handleInput(input?.plainText ?? "")
 						setSelected(0)
 					}}
 					ref={(next) => {
@@ -232,7 +305,7 @@ export const InteractiveSelectPrompt = (props: SelectPromptProps) => {
 				</For>
 			</box>
 			<text fg="#6c7086" wrapMode="none">
-				enter select | esc cancel | ctrl-n/p or arrows
+				enter select | esc cancel | arrows/ctrl-n/p | ctrl-y yank
 			</text>
 		</box>
 	)

package/src/workbase/AGENTS.md

@@ -67,9 +67,13 @@ a refinement loop, or pausing or handing off completed implementation work):
 ## Managed Integration
 
 `agency integration status` reports `managed`, `drifted`, `customized`, or
-`missing` generated files. `agency integration sync` updates only missing or
-checksum-safe drifted files and preserves user-customized files. `agency init`
-creates these files, and `agency work` reconciles them before launching an agent.
+`missing` generated files. Agency keeps these instructions in
+`.agency/AGENTS.md`, and its managed OpenCode config loads them automatically.
+The workbase-root `AGENTS.md`, when present, belongs entirely to the workbase
+owner and composes with these instructions through OpenCode's normal discovery.
+`agency integration sync` updates only missing or checksum-safe drifted managed
+files and preserves user-customized files. `agency init` creates the managed
+files, and `agency work` reconciles them before launching an agent.
 
 OpenCode can access the complete workbase tree, but this filesystem permission
 does not expand Agency write authority beyond the checkout reported by

package/src/workbase/opencode-file.ts

@@ -10,6 +10,7 @@ const body = () =>
 	`${JSON.stringify(
 		{
 			$schema: "https://opencode.ai/config.json",
+			instructions: [".agency/AGENTS.md"],
 			references: {
 				workbase: {
 					path: "..",