@markjaquith/agency 2.45.0 → 2.46.0

package/README.md

@@ -52,8 +52,10 @@ workbase/
     AGENTS.md              # managed Agency instructions
   .opencode/
     opencode.jsonc         # managed @agency subagent, instructions, and reference
+    tui.jsonc              # managed TUI plugin registration
     command/agency.md      # managed /agency workflow command
     plugin/agency-repository-skills.ts # managed checkout skill discovery
+    tui/agency-debug.ts    # managed /agency-debug TUI diagnostic
   agency.json              # tracked config and portable repository declarations
   repos/                   # ignored local materializations
     frontend/              # bare Git repository or symlink
@@ -82,9 +84,10 @@ workbase/
 
 Agency keeps discovery and other observational commands read-only. Run
 `agency integration status` to inspect `.agency/AGENTS.md` and
-`.opencode/opencode.jsonc`, and `.opencode/command/agency.md`, then `agency
-integration sync` to create missing files or refresh checksum-safe managed
-files. Customized files are reported but never overwritten. The root
+`.opencode/opencode.jsonc`, `.opencode/tui.jsonc`, and their managed command and
+plugin files, then `agency integration sync` to create missing files or refresh
+checksum-safe managed files. Customized files are reported but 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
@@ -99,6 +102,11 @@ and replaces the built-in Plan agent with `agency-plan`. That planning agent can
 update `TASK.md`, `PHASE.md`, and `EPIC.md` while other edits remain disabled.
 When the subagent launches work in another agent, it verifies that the runner
 started and returns without waiting for the task to finish.
+The TUI-only `/agency-debug` command reports TUI companion initialization and
+whether the server plugin registered writable-checkout skills. It uses a native
+toast and does not submit a prompt to an LLM. When no writable checkout skill
+directory is available, server initialization is reported as indeterminate
+rather than inferred from plugin discovery.
 OpenCode discovers the config from task and epic launch directories. Agents
 receive whole-workbase visibility from that reference. Bash and Agency operations
 must still follow the write authority reported by `agency context`.

package/package.json

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

package/src/cli.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, afterEach, describe, expect, test } from "bun:test"
 import { access, mkdir, realpath, symlink } from "node:fs/promises"
-import { join } from "node:path"
+import { join, sep } from "node:path"
 import errorFixture from "../fixtures/protocol/error.json"
 import successFixture from "../fixtures/protocol/success.json"
 import { cleanupTempDir, createTempDir } from "./test-utils"
@@ -528,6 +528,8 @@ describe("CLI", () => {
 			{ name: "opencode", state: "managed" },
 			{ name: "opencode-command", state: "managed" },
 			{ name: "opencode-plugin", state: "managed" },
+			{ name: "opencode-tui", state: "managed" },
+			{ name: "opencode-tui-plugin", state: "managed" },
 		])
 
 		const synced = parseJson(
@@ -538,6 +540,8 @@ describe("CLI", () => {
 			{ name: "opencode", state: "managed", changed: false },
 			{ name: "opencode-command", state: "managed", changed: false },
 			{ name: "opencode-plugin", state: "managed", changed: false },
+			{ name: "opencode-tui", state: "managed", changed: false },
+			{ name: "opencode-tui-plugin", state: "managed", changed: false },
 		])
 	})
 
@@ -1097,7 +1101,9 @@ status: open
 					]),
 				)
 				if (launch.skillPath) {
-					expect(effectiveConfig.skills.paths).toContain(launch.skillPath)
+					expect(effectiveConfig.skills.paths).toContain(
+						`${launch.skillPath}${sep}.`,
+					)
 					const skillProbe = Bun.spawnSync(
 						[
 							"opencode",
@@ -1115,6 +1121,12 @@ status: open
 					expect(
 						JSON.parse(skillProbe.stdout.toString()).result.output,
 					).toContain("Repository skill content.")
+				} else {
+					expect(
+						(effectiveConfig.skills?.paths ?? []).filter((path: string) =>
+							path.endsWith(`${sep}.`),
+						),
+					).toEqual([])
 				}
 				if (launch === launches[0]) {
 					expect(effectiveConfig.instructions).toContain(".agency/AGENTS.md")

package/src/commands/init.test.ts

@@ -71,6 +71,17 @@ describe("init command", () => {
 		).text()
 		expect(plugin).toContain("AGENCY_WRITABLE_CHECKOUT")
 		expect(plugin).toContain("config.skills.paths")
+		const tui = await Bun.file(join(root, ".opencode/tui.jsonc")).text()
+		expect(JSON.parse(tui.slice(tui.indexOf("\n\n") + 2))).toEqual({
+			$schema: "https://opencode.ai/tui.json",
+			plugin: ["./tui/agency-debug.ts"],
+		})
+		const tuiPlugin = await Bun.file(
+			join(root, ".opencode/tui/agency-debug.ts"),
+		).text()
+		expect(tuiPlugin).toContain('slashName: "agency-debug"')
+		expect(tuiPlugin).toContain("api.ui.toast")
+		expect(tuiPlugin).not.toContain("chat.message")
 	})
 
 	test("preserves existing gitignore entries", async () => {

package/src/commands/integration.test.ts

@@ -46,6 +46,16 @@ describe("integration command", () => {
 					state: "missing",
 					remediation: expect.stringContaining("integration sync"),
 				},
+				{
+					name: "opencode-tui",
+					state: "missing",
+					remediation: expect.stringContaining("integration sync"),
+				},
+				{
+					name: "opencode-tui-plugin",
+					state: "missing",
+					remediation: expect.stringContaining("integration sync"),
+				},
 			],
 		})
 	})
@@ -89,7 +99,17 @@ OpenCode /agency command: missing
 OpenCode checkout skills: missing
   Path: .opencode/plugin/agency-repository-skills.ts
   The managed OpenCode checkout-skill plugin needs synchronization.
-  Action: Run 'agency integration sync' to expose writable-checkout skills in OpenCode.`)
+  Action: Run 'agency integration sync' to expose writable-checkout skills in OpenCode.
+
+OpenCode TUI config: missing
+  Path: .opencode/tui.jsonc
+  The managed OpenCode TUI config needs synchronization.
+  Action: Run 'agency integration sync' to register /agency-debug.
+
+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.`)
 	})
 
 	test("explicitly synchronizes integration files", async () => {
@@ -102,6 +122,8 @@ OpenCode checkout skills: missing
 			{ name: "opencode", state: "managed", changed: true },
 			{ name: "opencode-command", state: "managed", changed: true },
 			{ name: "opencode-plugin", state: "managed", changed: true },
+			{ name: "opencode-tui", state: "managed", changed: true },
+			{ name: "opencode-tui-plugin", 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)
@@ -116,6 +138,12 @@ OpenCode checkout skills: missing
 				join(root, ".opencode/plugin/agency-repository-skills.ts"),
 			).exists(),
 		).toBe(true)
+		expect(await Bun.file(join(root, ".opencode/tui.jsonc")).exists()).toBe(
+			true,
+		)
+		expect(
+			await Bun.file(join(root, ".opencode/tui/agency-debug.ts")).exists(),
+		).toBe(true)
 	})
 
 	test("formats integration sync results for people", async () => {
@@ -139,6 +167,14 @@ OpenCode /agency command: synced
 
 OpenCode checkout skills: synced
   Path: .opencode/plugin/agency-repository-skills.ts
-  Agency's managed OpenCode plugin exposes writable-checkout skills to work-item sessions.`)
+  Agency's managed OpenCode plugin exposes writable-checkout skills to work-item sessions.
+
+OpenCode TUI config: synced
+  Path: .opencode/tui.jsonc
+  Agency's managed OpenCode TUI config explicitly loads /agency-debug.
+
+OpenCode /agency-debug: synced
+  Path: .opencode/tui/agency-debug.ts
+  Agency's managed OpenCode TUI diagnostic companion is current.`)
 	})
 })

package/src/commands/integration.ts

@@ -17,6 +17,8 @@ interface IntegrationResult {
 			| "opencode"
 			| "opencode-command"
 			| "opencode-plugin"
+			| "opencode-tui"
+			| "opencode-tui-plugin"
 		readonly path: string
 		readonly state: string
 		readonly diagnostic: string
@@ -30,6 +32,8 @@ const integrationNames = {
 	opencode: "OpenCode config",
 	"opencode-command": "OpenCode /agency command",
 	"opencode-plugin": "OpenCode checkout skills",
+	"opencode-tui": "OpenCode TUI config",
+	"opencode-tui-plugin": "OpenCode /agency-debug",
 } as const
 
 const logHumanResult = (
@@ -88,8 +92,8 @@ Usage: agency integration <subcommand>
 
 Inspect or explicitly synchronize managed agent integration files. OpenCode
 launches load the managed instructions and project config at runtime, and expose
-the managed /agency command and writable-checkout skills, without changing
-Agency write authority.
+the managed /agency command, writable-checkout skills, and /agency-debug TUI
+diagnostic, without changing Agency write authority.
 
 Subcommands:
   status  Report file state, access diagnostics, and safe remediation

package/src/services/IntegrationService.test.ts

@@ -3,6 +3,7 @@ import { Effect } from "effect"
 import { createHash } from "node:crypto"
 import { mkdir, stat, symlink, unlink, utimes } from "node:fs/promises"
 import { dirname, join } from "node:path"
+import { pathToFileURL } from "node:url"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { managedWorkbaseAgents } from "../workbase/agents-file"
 import {
@@ -14,6 +15,11 @@ import {
 	canUpdateManagedWorkbaseOpencodePlugin,
 	managedWorkbaseOpencodePlugin,
 } from "../workbase/opencode-plugin-file"
+import { managedWorkbaseOpencodeTui } from "../workbase/opencode-tui-file"
+import {
+	canUpdateManagedWorkbaseOpencodeTuiPlugin,
+	managedWorkbaseOpencodeTuiPlugin,
+} from "../workbase/opencode-tui-plugin-file"
 import { IntegrationService } from "./IntegrationService"
 
 const write = async (root: string, path: string, content: string) => {
@@ -56,6 +62,8 @@ describe("IntegrationService", () => {
 			"missing",
 			"missing",
 			"missing",
+			"missing",
+			"missing",
 		])
 		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(false)
 
@@ -71,11 +79,19 @@ describe("IntegrationService", () => {
 			".opencode/plugin/agency-repository-skills.ts",
 			managedWorkbaseOpencodePlugin,
 		)
+		await write(root, ".opencode/tui.jsonc", managedWorkbaseOpencodeTui)
+		await write(
+			root,
+			".opencode/tui/agency-debug.ts",
+			managedWorkbaseOpencodeTuiPlugin,
+		)
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"managed",
 			"managed",
 			"managed",
 			"managed",
+			"managed",
+			"managed",
 		])
 	})
 
@@ -92,6 +108,8 @@ describe("IntegrationService", () => {
 			"drifted",
 			"missing",
 			"missing",
+			"missing",
+			"missing",
 		])
 	})
 
@@ -114,6 +132,9 @@ describe("IntegrationService", () => {
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			"config.skills.paths = [...new Set",
 		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			".map((path) => `${path}${sep}.`)",
+		)
 		expect(
 			canUpdateManagedWorkbaseOpencodePlugin(managedWorkbaseOpencodePlugin),
 		).toBe(true)
@@ -124,6 +145,73 @@ describe("IntegrationService", () => {
 		).toBe(false)
 	})
 
+	test("registers a TUI-only /agency-debug diagnostic", async () => {
+		const config = JSON.parse(managedBody(managedWorkbaseOpencodeTui))
+		expect(config).toEqual({
+			$schema: "https://opencode.ai/tui.json",
+			plugin: ["./tui/agency-debug.ts"],
+		})
+
+		const path = join(root, ".opencode/tui/agency-debug.ts")
+		await write(
+			root,
+			".opencode/tui/agency-debug.ts",
+			managedWorkbaseOpencodeTuiPlugin,
+		)
+		const module = await import(pathToFileURL(path).href)
+		let clientReads = 0
+
+		const runDiagnostic = async (paths: string[], ready = true) => {
+			let command:
+				| {
+						slashName?: string
+						namespace?: string
+						run: () => void
+				  }
+				| undefined
+			let toast: { variant: string; message: string } | undefined
+			await module.default.tui({
+				get client() {
+					clientReads += 1
+					throw new Error("diagnostic must not access the server client")
+				},
+				state: { ready, config: { skills: { paths } } },
+				keymap: {
+					registerLayer: (layer: { commands: (typeof command)[] }) => {
+						command = layer.commands[0]
+					},
+				},
+				ui: {
+					toast: (input: { variant: string; message: string }) => {
+						toast = input
+					},
+				},
+			} as never)
+			expect(command).toMatchObject({
+				namespace: "palette",
+				slashName: "agency-debug",
+			})
+			command?.run()
+			return toast
+		}
+
+		expect(await runDiagnostic(["/checkout/.agents/skills/."])).toMatchObject({
+			variant: "success",
+			message: expect.stringContaining("Server plugin: initialized"),
+		})
+		expect(await runDiagnostic([])).toMatchObject({
+			variant: "warning",
+			message: expect.stringContaining("Server plugin: indeterminate"),
+		})
+		expect(clientReads).toBe(0)
+		expect(managedWorkbaseOpencodeTuiPlugin).not.toContain("chat.message")
+		expect(
+			canUpdateManagedWorkbaseOpencodeTuiPlugin(
+				managedWorkbaseOpencodeTuiPlugin,
+			),
+		).toBe(true)
+	})
+
 	test("generates a positional OpenCode command for Agency workflows", () => {
 		expect(managedWorkbaseOpencodeCommand).toContain(
 			"description: Operate Agency work",
@@ -289,6 +377,8 @@ describe("IntegrationService", () => {
 			{ name: "opencode", state: "managed", changed: true },
 			{ name: "opencode-command", state: "managed", changed: true },
 			{ name: "opencode-plugin", state: "managed", changed: true },
+			{ name: "opencode-tui", state: "managed", changed: true },
+			{ name: "opencode-tui-plugin", state: "managed", changed: true },
 		])
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
 			customRootAgents,
@@ -307,6 +397,12 @@ describe("IntegrationService", () => {
 				join(root, ".opencode/plugin/agency-repository-skills.ts"),
 			).text(),
 		).toBe(managedWorkbaseOpencodePlugin)
+		expect(await Bun.file(join(root, ".opencode/tui.jsonc")).text()).toBe(
+			managedWorkbaseOpencodeTui,
+		)
+		expect(
+			await Bun.file(join(root, ".opencode/tui/agency-debug.ts")).text(),
+		).toBe(managedWorkbaseOpencodeTuiPlugin)
 
 		await unlink(join(root, ".agency/AGENTS.md"))
 		const second = await sync(root)
@@ -346,6 +442,34 @@ describe("IntegrationService", () => {
 		})
 	})
 
+	test("preserves user-owned TUI config and diagnostic plugin", async () => {
+		const customConfig = '{"theme":"custom"}\n'
+		const customPlugin =
+			"export default { id: 'agency.debug', tui: async () => {} }\n"
+		await write(root, ".opencode/tui.json", customConfig)
+		await write(root, ".opencode/tui/agency-debug.ts", customPlugin)
+
+		const result = await sync(root)
+		expect(result.files[4]).toMatchObject({
+			name: "opencode-tui",
+			path: join(root, ".opencode/tui.json"),
+			state: "customized",
+			changed: false,
+			remediation: expect.stringContaining("plugin list"),
+		})
+		expect(result.files[5]).toMatchObject({
+			name: "opencode-tui-plugin",
+			state: "customized",
+			changed: false,
+		})
+		expect(await Bun.file(join(root, ".opencode/tui.json")).text()).toBe(
+			customConfig,
+		)
+		expect(
+			await Bun.file(join(root, ".opencode/tui/agency-debug.ts")).text(),
+		).toBe(customPlugin)
+	})
+
 	test("preserves user-owned OpenCode commands at either supported path", async () => {
 		const custom = "---\ndescription: Custom Agency command\n---\n\nCustom.\n"
 		await write(root, ".opencode/commands/agency.md", custom)

package/src/services/IntegrationService.ts

@@ -18,11 +18,25 @@ import {
 	canUpdateManagedWorkbaseOpencodePlugin,
 	managedWorkbaseOpencodePlugin,
 } from "../workbase/opencode-plugin-file"
+import {
+	canUpdateManagedWorkbaseOpencodeTui,
+	managedWorkbaseOpencodeTui,
+} from "../workbase/opencode-tui-file"
+import {
+	canUpdateManagedWorkbaseOpencodeTuiPlugin,
+	managedWorkbaseOpencodeTuiPlugin,
+} from "../workbase/opencode-tui-plugin-file"
 
 type IntegrationFileState = "managed" | "customized" | "missing" | "drifted"
 
 interface IntegrationFileStatus {
-	readonly name: "agents" | "opencode" | "opencode-command" | "opencode-plugin"
+	readonly name:
+		| "agents"
+		| "opencode"
+		| "opencode-command"
+		| "opencode-plugin"
+		| "opencode-tui"
+		| "opencode-tui-plugin"
 	readonly path: string
 	readonly state: IntegrationFileState
 	readonly diagnostic: string
@@ -99,6 +113,47 @@ const describe = (
 							"Run 'agency integration sync' to expose writable-checkout skills in OpenCode.",
 					}
 	}
+	if (name === "opencode-tui") {
+		return state === "managed"
+			? {
+					diagnostic:
+						"Agency's managed OpenCode TUI config explicitly loads /agency-debug.",
+					remediation: null,
+				}
+			: state === "customized"
+				? {
+						diagnostic:
+							"A user-owned OpenCode TUI config is present and was preserved.",
+						remediation:
+							"Add './tui/agency-debug.ts' to its plugin list to enable /agency-debug.",
+					}
+				: {
+						diagnostic:
+							"The managed OpenCode TUI config needs synchronization.",
+						remediation:
+							"Run 'agency integration sync' to register /agency-debug.",
+					}
+	}
+	if (name === "opencode-tui-plugin") {
+		return state === "managed"
+			? {
+					diagnostic:
+						"Agency's managed OpenCode TUI diagnostic companion is current.",
+					remediation: null,
+				}
+			: state === "customized"
+				? {
+						diagnostic:
+							"A user-owned OpenCode /agency-debug TUI plugin is present and was preserved.",
+						remediation: null,
+					}
+				: {
+						diagnostic:
+							"The managed OpenCode TUI diagnostic companion needs synchronization.",
+						remediation:
+							"Run 'agency integration sync' to install /agency-debug.",
+					}
+	}
 
 	return state === "missing" || state === "drifted"
 		? {
@@ -145,6 +200,8 @@ const inspect = (root: string) =>
 		const opencodeDirectory = join(root, ".opencode")
 		const opencodePath = join(opencodeDirectory, "opencode.jsonc")
 		const opencodeJsonPath = join(opencodeDirectory, "opencode.json")
+		const tuiPath = join(opencodeDirectory, "tui.jsonc")
+		const tuiJsonPath = join(opencodeDirectory, "tui.json")
 		const commandPath = join(opencodeDirectory, "command", "agency.md")
 		const pluralCommandPath = join(opencodeDirectory, "commands", "agency.md")
 		const pluginPath = join(
@@ -157,6 +214,7 @@ const inspect = (root: string) =>
 			"plugins",
 			"agency-repository-skills.ts",
 		)
+		const tuiPluginPath = join(opencodeDirectory, "tui", "agency-debug.ts")
 		const files: IntegrationFileStatus[] = []
 
 		files.push(
@@ -238,6 +296,43 @@ const inspect = (root: string) =>
 			files.push(fileStatus("opencode-plugin", pluginPath, "missing"))
 		}
 
+		if ((yield* fs.readSymlinkTarget(tuiPath)) !== null) {
+			files.push(fileStatus("opencode-tui", tuiPath, "customized"))
+		} else if (
+			(yield* fs.readSymlinkTarget(tuiJsonPath)) !== null ||
+			(yield* fs.exists(tuiJsonPath))
+		) {
+			files.push(fileStatus("opencode-tui", tuiJsonPath, "customized"))
+		} else if (yield* fs.exists(tuiPath)) {
+			files.push(
+				classify(
+					"opencode-tui",
+					tuiPath,
+					yield* fs.readFile(tuiPath),
+					managedWorkbaseOpencodeTui,
+					canUpdateManagedWorkbaseOpencodeTui,
+				),
+			)
+		} else {
+			files.push(fileStatus("opencode-tui", tuiPath, "missing"))
+		}
+
+		if ((yield* fs.readSymlinkTarget(tuiPluginPath)) !== null) {
+			files.push(fileStatus("opencode-tui-plugin", tuiPluginPath, "customized"))
+		} else if (yield* fs.exists(tuiPluginPath)) {
+			files.push(
+				classify(
+					"opencode-tui-plugin",
+					tuiPluginPath,
+					yield* fs.readFile(tuiPluginPath),
+					managedWorkbaseOpencodeTuiPlugin,
+					canUpdateManagedWorkbaseOpencodeTuiPlugin,
+				),
+			)
+		} else {
+			files.push(fileStatus("opencode-tui-plugin", tuiPluginPath, "missing"))
+		}
+
 		return files
 	})
 
@@ -290,9 +385,18 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 							} else if (status.name === "opencode-command") {
 								yield* fs.createDirectory(join(root, ".opencode", "command"))
 								yield* fs.writeFile(status.path, managedWorkbaseOpencodeCommand)
-							} else {
+							} else if (status.name === "opencode-plugin") {
 								yield* fs.createDirectory(join(root, ".opencode", "plugin"))
 								yield* fs.writeFile(status.path, managedWorkbaseOpencodePlugin)
+							} else if (status.name === "opencode-tui") {
+								yield* fs.createDirectory(join(root, ".opencode"))
+								yield* fs.writeFile(status.path, managedWorkbaseOpencodeTui)
+							} else {
+								yield* fs.createDirectory(join(root, ".opencode", "tui"))
+								yield* fs.writeFile(
+									status.path,
+									managedWorkbaseOpencodeTuiPlugin,
+								)
 							}
 						}
 						files.push({

package/src/workbase/AGENTS.md

@@ -72,8 +72,9 @@ a refinement loop, or pausing or handing off completed implementation work):
 `missing` generated files. Agency keeps these instructions in
 `.agency/AGENTS.md`, and its managed OpenCode config loads them automatically.
 It also installs `.opencode/command/agency.md`, which provides safe `/agency`
-workflows for active OpenCode sessions, and a managed plugin that exposes skills
-from the authoritative writable checkout without changing the project root.
+workflows for active OpenCode sessions, a managed server plugin that exposes
+skills from the authoritative writable checkout, and an explicitly registered
+TUI companion providing `/agency-debug` without submitting an LLM prompt.
 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

package/src/workbase/opencode-plugin-file.ts

@@ -7,7 +7,7 @@ const checksum = (content: string) =>
 	createHash("sha256").update(content).digest("hex")
 
 const body = `import { existsSync } from "node:fs"
-import { join } from "node:path"
+import { join, sep } from "node:path"
 import type { Plugin } from "@opencode-ai/plugin"
 
 const contextCheckout = async (directory: string) => {
@@ -36,7 +36,7 @@ const plugin: Plugin = async ({ directory }) => ({
       join(checkout, ".agents", "skills"),
       join(checkout, ".opencode", "skill"),
       join(checkout, ".opencode", "skills"),
-    ].filter(existsSync)
+    ].filter(existsSync).map((path) => \`\${path}\${sep}.\`)
     if (paths.length === 0) return
 
     config.skills ??= {}

package/src/workbase/opencode-tui-file.ts

@@ -0,0 +1,30 @@
+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 = () =>
+	`${JSON.stringify(
+		{
+			$schema: "https://opencode.ai/tui.json",
+			plugin: ["./tui/agency-debug.ts"],
+		},
+		null,
+		2,
+	)}\n`
+
+const renderManagedWorkbaseOpencodeTui = (content: string) =>
+	`// agency-managed: sha256=${checksum(content)}\n\n${content}`
+
+export const managedWorkbaseOpencodeTui =
+	renderManagedWorkbaseOpencodeTui(body())
+
+export const canUpdateManagedWorkbaseOpencodeTui = (content: string) => {
+	const match = content.match(managedHeaderPattern)
+	if (!match?.[1]) return false
+
+	return checksum(content.slice(match[0].length)) === match[1]
+}

package/src/workbase/opencode-tui-plugin-file.ts

@@ -0,0 +1,65 @@
+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 type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui"
+
+const serverMarker = /[\\\\/]\\.$/
+
+const tui: TuiPlugin = async (api) => {
+  api.keymap.registerLayer({
+    commands: [
+      {
+        name: "agency.debug",
+        title: "Agency integration diagnostic",
+        desc: "Check Agency's OpenCode TUI and server plugin initialization",
+        category: "Agency",
+        namespace: "palette",
+        slashName: "agency-debug",
+        run() {
+          const paths = api.state.config.skills?.paths
+          const serverInitialized = paths?.some(
+            (path) => typeof path === "string" && serverMarker.test(path),
+          )
+          const message = serverInitialized
+            ? "TUI companion: initialized. Server plugin: initialized; checkout skills registered."
+            : api.state.ready
+              ? "TUI companion: initialized. Server plugin: indeterminate; no checkout skill marker is present."
+              : "TUI companion: initialized. Server plugin: indeterminate; server state is not ready."
+
+          api.ui.toast({
+            variant: serverInitialized ? "success" : "warning",
+            title: "Agency integration",
+            message,
+            duration: 5000,
+          })
+        },
+      },
+    ],
+  })
+}
+
+const plugin: TuiPluginModule & { id: string } = {
+  id: "agency.debug",
+  tui,
+}
+
+export default plugin
+`
+
+const renderManagedWorkbaseOpencodeTuiPlugin = (content: string) =>
+	`// agency-managed: sha256=${checksum(content)}\n\n${content}`
+
+export const managedWorkbaseOpencodeTuiPlugin =
+	renderManagedWorkbaseOpencodeTuiPlugin(body)
+
+export const canUpdateManagedWorkbaseOpencodeTuiPlugin = (content: string) => {
+	const match = content.match(managedHeaderPattern)
+	if (!match?.[1]) return false
+
+	return checksum(content.slice(match[0].length)) === match[1]
+}