@markjaquith/agency 2.26.0 → 2.27.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,6 +7,7 @@ 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 { validate, help as validateHelp } from "./src/commands/validate"
 import { context, help as contextHelp } from "./src/commands/context"
@@ -470,6 +471,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)
@@ -607,6 +627,7 @@ 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

package/package.json

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

package/src/cli-parser.test.ts

@@ -404,6 +404,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]",
@@ -902,6 +952,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 () => {

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
+`

package/src/services/FileSystemService.ts

@@ -6,6 +6,7 @@ import {
 	readdir,
 	realpath,
 	rename,
+	rmdir,
 	stat,
 	symlink,
 } from "node:fs/promises"
@@ -175,6 +176,31 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 					),
 				),
 
+			deleteDirectoryIfEmpty: (path: string) =>
+				Effect.tryPromise({
+					try: async () => {
+						try {
+							await rmdir(path)
+							return true
+						} catch (error) {
+							if (
+								typeof error === "object" &&
+								error !== null &&
+								"code" in error &&
+								["ENOENT", "ENOTEMPTY", "EEXIST"].includes(String(error.code))
+							) {
+								return false
+							}
+							throw error
+						}
+					},
+					catch: (error) =>
+						new FileSystemError({
+							message: `Failed to delete empty directory: ${path}`,
+							cause: error,
+						}),
+				}),
+
 			runCommand: (
 				args: readonly string[],
 				options?: {