@markjaquith/agency 2.26.0 → 2.28.0

package/README.md

@@ -610,6 +610,7 @@ for restoration. Archived IDs are reserved until restored.
 ```text
 agency work [<directory> | --epic <epic-id>] [--runner <name>] [--print-command]
 agency work prepare [target] [--dry-run] [--json]
+agency worktree <list|inspect|prepare|remove|rebuild|repair>
 agency pr create <task-id> [phase-id] [--draft] [--json]
 ```
 
@@ -629,6 +630,15 @@ Its JSON result includes document and checkout paths, resolved commits, actions,
 and Git operations. Use `--dry-run` to report planned fetch, branch, and worktree
 changes without applying them.
 
+`agency worktree list` and `inspect` report each declared checkout's expected and
+registered path, branch, commit, Agency owner, dirtiness, and conflicts. `prepare`
+is the explicit lifecycle form of `agency work prepare`. `remove`, `rebuild`, and
+`repair` preflight every writable and reference checkout before changing any of
+them and accept `--dry-run`. Removal preserves branches. Rebuild rejects dirty or
+conflicting worktrees. Repair is deliberately conservative: it repairs safe Git
+registration issues and materializes missing checkouts, but never switches a
+branch, resets a commit, or discards uncommitted work.
+
 Epic and multi-phase task targets launch orchestration agents beside their
 documents. Single-phase tasks and phases fetch repositories, create or reuse
 worktrees under `code/`, and launch an execution agent in the writable checkout

package/cli.ts

@@ -7,7 +7,9 @@ import { init, help as initHelp } from "./src/commands/init"
 import { task, help as taskHelp } from "./src/commands/task"
 import { pr, help as prHelp } from "./src/commands/pr"
 import { work, workPrepare, help as workHelp } from "./src/commands/work"
+import { worktree, help as worktreeHelp } from "./src/commands/worktree"
 import { status, help as statusHelp } from "./src/commands/status"
+import { doctor, help as doctorHelp } from "./src/commands/doctor"
 import { validate, help as validateHelp } from "./src/commands/validate"
 import { context, help as contextHelp } from "./src/commands/context"
 import { graph, help as graphHelp } from "./src/commands/graph"
@@ -40,6 +42,7 @@ import { ClaimService } from "./src/services/ClaimService"
 import { SyncService } from "./src/services/SyncService"
 import { ReadinessService } from "./src/services/ReadinessService"
 import { GraphMutationService } from "./src/services/GraphMutationService"
+import { DoctorService } from "./src/services/DoctorService"
 import {
 	claimCommand,
 	claimHelp,
@@ -71,6 +74,7 @@ const CliLayer = Layer.mergeAll(
 	SyncService.Default,
 	ReadinessService.Default,
 	GraphMutationService.Default,
+	DoctorService.Default,
 )
 
 /**
@@ -470,6 +474,25 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	worktree: {
+		run: async (args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(worktreeHelp)
+				return
+			}
+			await runCommand(
+				worktree({
+					subcommand: args[0],
+					args: args.slice(1),
+					dryRun: options["dry-run"],
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+					cwd: options.cwd,
+				}),
+			)
+		},
+	},
 	next: {
 		run: async (_args: string[], options: Record<string, any>) => {
 			if (options.help) return console.log(nextHelp)
@@ -504,6 +527,22 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	doctor: {
+		run: async (_args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(doctorHelp)
+				return
+			}
+			await runCommand(
+				doctor({
+					silent: options.silent,
+					verbose: options.verbose,
+					json: options.json,
+					cwd: options.cwd,
+				}),
+			)
+		},
+	},
 	validate: {
 		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) {
@@ -607,10 +646,12 @@ Commands:
   archive <type>         Archive a work item
   task <subcommand>      Manage tasks
   work [directory|task]  Work on an epic, task, or phase
+  worktree <subcommand>  Inspect and maintain managed worktrees
   next                   List or select ready execution units
   pr create              Create a pull request for an execution unit
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase
+  doctor                 Diagnose workbase health and integrations
   validate [path]        Validate a workbase
   context [target]       Return complete target context
   graph                  Export the complete workbase graph

package/package.json

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

package/src/cli-parser.test.ts

@@ -123,6 +123,7 @@ describe("strict CLI parsing", () => {
 
 	test("parses addressable resource maintenance commands", () => {
 		for (const args of [
+			["doctor", "--json"],
 			["repo", "show", "agency", "--json"],
 			["repo", "fetch", "agency"],
 			["repo", "remove", "agency"],
@@ -404,6 +405,36 @@ describe("strict CLI parsing", () => {
 		)
 	})
 
+	test("parses worktree lifecycle commands and selectors", () => {
+		expect(parseCli(["worktree", "list", "--json"])).toMatchObject({
+			commandName: "worktree",
+			args: ["list"],
+			values: { json: true },
+		})
+		expect(
+			parseCli([
+				"worktree",
+				"rebuild",
+				"--task",
+				"example",
+				"--phase",
+				"verify",
+				"--dry-run",
+			]),
+		).toMatchObject({
+			commandName: "worktree",
+			args: ["rebuild", "example", "verify"],
+			values: { task: "example", phase: "verify", "dry-run": true },
+		})
+		expectUsageError(
+			["worktree", "inspect", "example", "--dry-run"],
+			"agency worktree inspect",
+		)
+		expect(() => parseCli(["worktree", "repair", "--phase", "verify"])).toThrow(
+			"requires '--task'",
+		)
+	})
+
 	test("accepts runner selection and command inspection for work", () => {
 		expect(
 			parseCli(["work", "example", "--runner", "custom", "--print-command"]),

package/src/cli-parser.ts

@@ -671,6 +671,56 @@ const commands = {
 			},
 		},
 	},
+	worktree: {
+		usage: "agency worktree <list|inspect|prepare|remove|rebuild|repair>",
+		options: {
+			...outputOptions,
+			...entitySelectorOptions,
+			"dry-run": { type: "boolean" },
+		},
+		subcommands: {
+			list: {
+				usage: "agency worktree list [--json]",
+				minArgs: 0,
+				maxArgs: 0,
+				options: ["json"],
+			},
+			inspect: {
+				usage: "agency worktree inspect <task-id> [phase-id] [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["json", "task", "phase"],
+			},
+			prepare: {
+				usage:
+					"agency worktree prepare <task-id> [phase-id] [--dry-run] [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["dry-run", "json", "task", "phase"],
+			},
+			remove: {
+				usage:
+					"agency worktree remove <task-id> [phase-id] [--dry-run] [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["dry-run", "json", "task", "phase"],
+			},
+			rebuild: {
+				usage:
+					"agency worktree rebuild <task-id> [phase-id] [--dry-run] [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["dry-run", "json", "task", "phase"],
+			},
+			repair: {
+				usage:
+					"agency worktree repair <task-id> [phase-id] [--dry-run] [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["dry-run", "json", "task", "phase"],
+			},
+		},
+	},
 	work: {
 		usage:
 			"agency work [<directory-or-task-id> | --epic <epic-id>] [--runner <name>] | agency work prepare [target] [--dry-run] [--json]",
@@ -754,6 +804,16 @@ const commands = {
 			conflicts: viewConflicts,
 		},
 	},
+	doctor: {
+		usage: "agency doctor [--json]",
+		options: outputOptions,
+		command: {
+			usage: "agency doctor [--json]",
+			minArgs: 0,
+			maxArgs: 0,
+			options: ["json"],
+		},
+	},
 	validate: {
 		usage: "agency validate [path] [--json] [--no-input]",
 		options: {
@@ -902,6 +962,9 @@ const targetSlots = (
 				: subcommand === "phase"
 					? ["task", "phase"]
 					: []
+	if (commandName === "worktree" && subcommand !== "list") {
+		return ["task", "phase"]
+	}
 	if (commandName === "pr" && subcommand === "create") return ["task", "phase"]
 	return []
 }

package/src/cli.test.ts

@@ -692,6 +692,40 @@ status: open
 			await runCli(["task", "show", "example", "--json"], root),
 		)
 		expect(task.data.status).toBe("open")
+
+		const listed = parseJson(await runCli(["worktree", "list", "--json"], root))
+		expect(listed).toEqual([
+			expect.objectContaining({
+				owner: expect.objectContaining({ kind: "task", taskId: "example" }),
+				checkouts: [
+					expect.objectContaining({
+						repo: "agency",
+						kind: "writable",
+						registered: true,
+						actualBranch: "feat/example",
+						actualCommit: expect.stringMatching(/^[0-9a-f]{40}$/),
+						dirty: false,
+					}),
+				],
+			}),
+		])
+		const rebuild = parseJson(
+			await runCli(
+				["worktree", "rebuild", "example", "--dry-run", "--json"],
+				root,
+			),
+		)
+		expect(rebuild).toMatchObject({
+			operation: "rebuild",
+			dryRun: true,
+			actions: [
+				`remove ${join(workbaseRoot, "tasks/example/code/agency")}`,
+				`create ${join(workbaseRoot, "tasks/example/code/agency")}`,
+			],
+		})
+		expect(
+			await Bun.file(join(root, "tasks/example/code/agency/README.md")).text(),
+		).toBe("example\n")
 	})
 
 	test("envelopes help and version output in machine mode", async () => {
@@ -901,6 +935,15 @@ status: open
 			valid: true,
 			issues: [],
 		})
+		const doctor = parseJson(await runCli(["doctor", "--json"], root))
+		expect(doctor).toMatchObject({
+			version: 1,
+			root: workbaseRoot,
+			checks: expect.arrayContaining([
+				expect.objectContaining({ id: "tool.git", status: "pass" }),
+				expect.objectContaining({ id: "workbase.validation", status: "pass" }),
+			]),
+		})
 
 		const validation = parseJson(
 			await runCli(["validate", root, "--json"], parent),

package/src/commands/doctor.test.ts

@@ -0,0 +1,156 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { createHash } from "node:crypto"
+import { chmod, mkdir } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
+import { doctor } from "./doctor"
+
+const write = async (root: string, path: string, content: string) => {
+	const fullPath = join(root, path)
+	await mkdir(dirname(fullPath), { recursive: true })
+	await Bun.write(fullPath, content)
+}
+
+const managedAgents = (body: string) =>
+	`<!-- agency-managed: sha256=${createHash("sha256").update(body).digest("hex")} -->\n\n${body}`
+
+describe("doctor command", () => {
+	let root: string
+	let repository: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		repository = join(root, "source")
+		await mkdir(repository)
+		await Bun.$`git init -q -b main ${repository}`
+		await Bun.$`git -C ${repository} config user.email test@example.com`
+		await Bun.$`git -C ${repository} config user.name Test`
+		await write(repository, "README.md", "test\n")
+		await Bun.$`git -C ${repository} add README.md`
+		await Bun.$`git -C ${repository} commit -q -m initial`
+		await Bun.$`git -C ${repository} remote add origin https://example.com/agency.git`
+		await write(
+			root,
+			"agency.json",
+			JSON.stringify({
+				version: 2,
+				runners: { missing: { command: ["definitely-not-installed"] } },
+			}),
+		)
+		await mkdir(join(root, "repos"), { recursive: true })
+		await Bun.$`ln -s ${repository} ${join(root, "repos/agency")}`
+		await write(
+			root,
+			"tasks/example/TASK.md",
+			`---
+ticketUrl: null
+repo: agency
+branch: feat/example
+base: main
+pr: null
+status: open
+---
+
+# Example
+`,
+		)
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("returns stable checks, severities, and remediation in JSON", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(doctor({ cwd: root, json: true })),
+		)
+		const report = JSON.parse(logs[0]!)
+
+		expect(report).toMatchObject({
+			version: 1,
+			root,
+			healthy: false,
+		})
+		expect(report.checks).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
+					id: "tool.git",
+					level: "error",
+					status: "pass",
+				}),
+				expect.objectContaining({
+					id: "integration.runner.missing",
+					level: "error",
+					status: "fail",
+				}),
+				expect.objectContaining({
+					id: "ref.agency.main",
+					status: "pass",
+				}),
+				expect.objectContaining({
+					id: "worktree.task.example",
+					status: "pass",
+				}),
+			]),
+		)
+		for (const check of report.checks) {
+			if (check.status === "fail") expect(check.remediation).toBeTruthy()
+		}
+	})
+
+	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"))
+
+		const logs = await captureLogs(() =>
+			runTestEffect(doctor({ cwd: root, json: true })),
+		)
+		const checks = JSON.parse(logs[0]!).checks
+
+		expect(checks).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
+					id: "repository.agency.remote",
+					status: "fail",
+				}),
+				expect.objectContaining({
+					id: "ref.agency.main",
+					status: "fail",
+				}),
+				expect.objectContaining({
+					id: "integration.file.agents",
+					status: "fail",
+				}),
+			]),
+		)
+	})
+
+	test("is safe when the workbase is read-only", async () => {
+		for (const path of [
+			join(root, "agency.json"),
+			join(root, "tasks/example/TASK.md"),
+		]) {
+			await chmod(path, 0o444)
+		}
+		await chmod(join(root, "tasks/example"), 0o555)
+		await chmod(join(root, "tasks"), 0o555)
+		await chmod(root, 0o555)
+
+		try {
+			await runTestEffect(doctor({ cwd: root, silent: true }))
+		} finally {
+			await chmod(root, 0o755)
+			await chmod(join(root, "tasks"), 0o755)
+			await chmod(join(root, "tasks/example"), 0o755)
+		}
+
+		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
+		expect(
+			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
+		).toBe(false)
+	})
+})

package/src/commands/doctor.ts

@@ -0,0 +1,47 @@
+import { Effect } from "effect"
+import { DoctorService } from "../services/DoctorService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+interface DoctorOptions extends BaseCommandOptions {
+	readonly json?: boolean
+}
+
+export const doctor = (options: DoctorOptions = {}) =>
+	Effect.gen(function* () {
+		const service = yield* DoctorService
+		const { log } = createLoggers(options)
+		const report = yield* service.inspect(options.cwd ?? process.cwd())
+
+		if (options.json) {
+			log(JSON.stringify(report, null, 2))
+			return
+		}
+
+		for (const check of report.checks) {
+			const marker =
+				check.status === "pass"
+					? "PASS"
+					: check.level === "error"
+						? "ERROR"
+						: check.level === "warning"
+							? "WARN"
+							: "OPTIONAL"
+			log(`${marker}\t${check.id}\t${check.message}`)
+			if (check.remediation) log(`  Remediation: ${check.remediation}`)
+		}
+		log("")
+		log(
+			`${report.healthy ? "Healthy" : "Unhealthy"}: ${report.summary.errors} error(s), ${report.summary.warnings} warning(s), ${report.summary.optional} unavailable optional capability(s)`,
+		)
+	})
+
+export const help = `
+Usage: agency doctor [options]
+
+Diagnose tools, integrations, repositories, refs, worktrees, permissions, and
+managed-file drift without changing the workbase.
+
+Options:
+  --json  Output the health report as JSON
+`

package/src/commands/read-only.test.ts

@@ -14,6 +14,7 @@ import { validate } from "./validate"
 import { context } from "./context"
 import { graph } from "./graph"
 import { next } from "./next"
+import { doctor } from "./doctor"
 
 const write = async (root: string, path: string, content: string) => {
 	const fullPath = join(root, path)
@@ -147,6 +148,7 @@ status: open
 		)
 		await runTestEffect(graph({ cwd: root, silent: true }))
 		await runTestEffect(next({ cwd: root, silent: true }))
+		await runTestEffect(doctor({ cwd: root, silent: true }))
 
 		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
 		expect(

package/src/commands/worktree.ts

@@ -0,0 +1,138 @@
+import { Effect } from "effect"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+import { WorktreeService } from "../services/WorktreeService"
+
+interface WorktreeOptions extends BaseCommandOptions {
+	readonly subcommand?: string
+	readonly args?: readonly string[]
+}
+
+const targetLabel = (owner: {
+	readonly kind: "task" | "phase"
+	readonly taskId: string
+	readonly phaseId?: string
+}) =>
+	owner.kind === "phase"
+		? `phase:${owner.taskId}/${owner.phaseId}`
+		: `task:${owner.taskId}`
+
+export const worktree = (options: WorktreeOptions = {}) =>
+	Effect.gen(function* () {
+		const worktrees = yield* WorktreeService
+		const { log } = createLoggers(options)
+		const root = options.cwd ?? process.cwd()
+		const subcommand = options.subcommand
+		const taskId = options.args?.[0]
+		const phaseId = options.args?.[1]
+
+		if (subcommand === "list") {
+			const inspections = yield* worktrees.list(root)
+			if (options.json) return log(JSON.stringify(inspections, null, 2))
+			for (const inspection of inspections) {
+				for (const checkout of inspection.checkouts) {
+					const state = checkout.conflicts.length
+						? `conflict:${checkout.conflicts.map(({ kind }) => kind).join(",")}`
+						: checkout.exists
+							? checkout.dirty
+								? "dirty"
+								: "ready"
+							: "missing"
+					log(
+						`${targetLabel(inspection.owner)}\t${checkout.kind}\t${checkout.repo}\t${state}\t${checkout.path}`,
+					)
+				}
+			}
+			return
+		}
+
+		if (!taskId) {
+			return yield* Effect.fail(
+				new Error("Worktree command requires a task ID"),
+			)
+		}
+		if (subcommand === "inspect") {
+			const inspection = yield* worktrees.inspect(taskId, phaseId, root)
+			if (options.json) return log(JSON.stringify(inspection, null, 2))
+			for (const checkout of inspection.checkouts) {
+				const owners = checkout.owners
+					.map((owner) => targetLabel(owner))
+					.join(",")
+				log(
+					`${checkout.kind} ${checkout.repo}: path=${checkout.path} registered=${checkout.registeredPath ?? "no"} branch=${checkout.actualBranch ?? "detached"} commit=${checkout.actualCommit ?? "unknown"} owner=${owners || "none"} dirty=${checkout.dirty ?? "unknown"}`,
+				)
+				for (const conflict of checkout.conflicts) {
+					log(`  conflict ${conflict.kind}: ${conflict.message}`)
+				}
+			}
+			return
+		}
+		if (subcommand === "prepare") {
+			const workspace = yield* worktrees.materialize(
+				taskId,
+				phaseId,
+				root,
+				options,
+			)
+			return log(
+				options.json
+					? JSON.stringify(workspace, null, 2)
+					: `${options.dryRun ? "Worktree plan" : "Worktrees ready"}: ${workspace.codePath}`,
+			)
+		}
+		if (subcommand === "remove") {
+			const inspection = yield* worktrees.inspect(taskId, phaseId, root)
+			const paths = yield* worktrees.remove(taskId, phaseId, root, options)
+			const result = {
+				operation: "remove",
+				dryRun: options.dryRun === true,
+				inspection,
+				actions: paths.map((path) => `remove ${path}`),
+			}
+			return log(
+				options.json
+					? JSON.stringify(result, null, 2)
+					: `${options.dryRun ? "Would remove" : "Removed"} ${paths.length} worktree${paths.length === 1 ? "" : "s"}`,
+			)
+		}
+		if (subcommand === "rebuild") {
+			const result = yield* worktrees.rebuild(taskId, phaseId, root, options)
+			return log(
+				options.json
+					? JSON.stringify(result, null, 2)
+					: `${options.dryRun ? "Would rebuild" : "Rebuilt"} ${result.inspection.codePath}`,
+			)
+		}
+		if (subcommand === "repair") {
+			const result = yield* worktrees.repair(taskId, phaseId, root, options)
+			return log(
+				options.json
+					? JSON.stringify(result, null, 2)
+					: `${options.dryRun ? "Would repair" : "Repaired"} ${result.inspection.codePath}`,
+			)
+		}
+
+		return yield* Effect.fail(
+			new Error(`Unknown worktree subcommand '${subcommand ?? ""}'`),
+		)
+	})
+
+export const help = `
+Usage: agency worktree <list|inspect|prepare|remove|rebuild|repair>
+
+Inspect and maintain Agency-managed writable and reference worktrees.
+
+Commands:
+  list                              List every managed checkout
+  inspect <task-id> [phase-id]      Show registration, branch, commit, ownership, and dirtiness
+  prepare <task-id> [phase-id]      Create or reuse declared worktrees
+  remove <task-id> [phase-id]       Remove clean worktrees while preserving branches
+  rebuild <task-id> [phase-id]      Remove and recreate clean, conflict-free worktrees
+  repair <task-id> [phase-id]       Repair safe registration issues or missing worktrees
+
+Options:
+  --task <id>          Select a task without positional IDs
+  --phase <id>         Select a phase with --task
+  --dry-run            Preflight and report changes without applying them
+  --json               Print structured output
+`