@markjaquith/agency 3.12.0 → 3.13.0

package/README.md

@@ -184,8 +184,8 @@ existing Git repositories.
 Existing version 2 workbases without `repositories` remain valid. Run
 `agency repo setup` to preview deterministic adoption of legacy local aliases;
 `agency repo setup --apply` writes declarations only when a portable origin is
-unambiguous. Workbase configuration may also provide a custom writable-worktree
-creation command.
+unambiguous. Workbase configuration may also provide custom writable-worktree
+creation and removal commands.
 
 ### Custom Branch Names
 
@@ -299,6 +299,43 @@ The configured command applies only to the writable checkout.
 Supplemental read-only repositories remain detached Git worktrees at their
 declared refs so they do not acquire writable branches.
 
+### Custom Worktree Remove Command
+
+Git workbases remove worktrees with `git worktree remove`. Set
+`worktreeRemoveCommand` to an argv template when another tool should remove
+writable worktrees:
+
+```json
+{
+	"version": 2,
+	"worktreeRemoveCommand": [
+		"wt",
+		"-C",
+		"{repo}",
+		"-y",
+		"remove",
+		"{worktree}",
+		"--no-delete-branch",
+		"--foreground",
+		"--format",
+		"json"
+	]
+}
+```
+
+It accepts the same placeholders and environment variables as
+`worktreeCreateCommand`, and `{repo}` and `{worktree}` are required. Agency
+invokes it directly without a shell whenever it removes an existing writable
+checkout, including `agency worktree remove`, rebuilds, archives, and rollback
+of a failed materialization. Agency still refuses dirty or mismatched checkouts
+before running the command.
+
+The command must remove the checkout synchronously, unregister it from Git, and
+preserve the execution branch; Agency verifies all three afterward. Rollback of
+a newly created checkout may delete the branch because Agency discards it
+anyway. Reference checkouts and stale registrations are still removed or pruned
+with Git.
+
 ### Post-checkout Commands
 
 Each repository declaration may provide a `postCheckoutCommand` argv

package/package.json

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

package/src/services/DoctorService.ts

@@ -172,6 +172,15 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 									] as const,
 								]
 							: []),
+						...(config.worktreeRemoveCommand
+							? [
+									[
+										"integration.worktree-remove",
+										config.worktreeRemoveCommand,
+										"Worktree remover",
+									] as const,
+								]
+							: []),
 						...Object.entries(config.repositories ?? {}).flatMap(
 							([alias, repository]) =>
 								repository.postCheckoutCommand

package/src/services/WorkbaseService.ts

@@ -20,7 +20,7 @@ import {
 	type WorkbaseRegistry as WorkbaseRegistryData,
 	type WorkbaseRegistration,
 } from "../workbase/schemas"
-import { validateWorktreeCreateCommand } from "../workbase/worktree-command"
+import { validateWorktreeCommand } from "../workbase/worktree-command"
 import { validatePostCheckoutCommand } from "../workbase/checkout-command"
 import { validateBranchNameCommand } from "../workbase/branch-name-template"
 import { validateAgents } from "../workbase/agent-command"
@@ -315,18 +315,21 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 										message: `Invalid workbase configuration in ${configPath}:\n${decoded.error}`,
 									})
 								}
-								if (decoded.value.worktreeCreateCommand) {
+								for (const setting of [
+									"worktreeCreateCommand",
+									"worktreeRemoveCommand",
+								] as const) {
+									const command = decoded.value[setting]
+									if (!command) continue
 									try {
-										validateWorktreeCreateCommand(
-											decoded.value.worktreeCreateCommand,
-										)
+										validateWorktreeCommand(setting, command)
 									} catch (cause) {
 										return yield* new WorkbaseConfigError({
 											path: configPath,
 											message:
 												cause instanceof Error
 													? cause.message
-													: "Invalid worktreeCreateCommand",
+													: `Invalid ${setting}`,
 										})
 									}
 								}

package/src/services/WorktreeService.ts

@@ -5,7 +5,7 @@ import { WorkbaseService } from "./WorkbaseService"
 import { TaskService } from "./TaskService"
 import { PhaseService } from "./PhaseService"
 import {
-	expandWorktreeCreateCommand,
+	expandWorktreeCommand,
 	worktreeCommandEnvironment,
 } from "../workbase/worktree-command"
 import {
@@ -258,6 +258,105 @@ const runPostCheckoutHook = (options: {
 		})
 	})
 
+const runWorktreeRemoveCommand = (options: {
+	readonly command: readonly string[]
+	readonly alias: string
+	readonly repositoryPath: string
+	readonly checkoutPath: string
+	readonly branch: string
+	readonly base: string
+	readonly preserveBranch: boolean
+	readonly forwardOutput: boolean
+	readonly verboseLog: (...args: unknown[]) => void
+}) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const variables = {
+			repo: options.repositoryPath,
+			worktree: options.checkoutPath,
+			branch: options.branch,
+			base: options.base,
+		}
+		let args: string[]
+		try {
+			args = expandWorktreeCommand(
+				"worktreeRemoveCommand",
+				options.command,
+				variables,
+			)
+		} catch (cause) {
+			return yield* new WorktreeError({
+				message:
+					cause instanceof Error
+						? cause.message
+						: "Invalid worktreeRemoveCommand",
+			})
+		}
+		const canonicalCheckoutPath = yield* fs.realPath(options.checkoutPath)
+		options.verboseLog(
+			`Running worktree remove command: ${formatCommand(args)}`,
+		)
+		const result = yield* fs.runCommand(args, {
+			cwd: options.repositoryPath,
+			captureOutput: true,
+			forwardOutput: options.forwardOutput,
+			env: worktreeCommandEnvironment(variables),
+		})
+		if (result.exitCode !== 0) {
+			return yield* new WorktreeError({
+				message: `Failed to remove worktree for '${options.alias}': ${result.stderr}`,
+			})
+		}
+		if (yield* fs.exists(options.checkoutPath)) {
+			return yield* new WorktreeError({
+				message: `Worktree remove command did not remove ${options.checkoutPath}`,
+			})
+		}
+		const listed = yield* fs.runCommand(
+			[
+				"git",
+				"-C",
+				options.repositoryPath,
+				"worktree",
+				"list",
+				"--porcelain",
+				"-z",
+			],
+			{ captureOutput: true },
+		)
+		if (
+			listed.exitCode !== 0 ||
+			parseWorktreeList(listed.stdout).some(
+				(worktree) =>
+					resolve(worktree.path) === canonicalCheckoutPath ||
+					resolve(worktree.path) === resolve(options.checkoutPath),
+			)
+		) {
+			return yield* new WorktreeError({
+				message: `Worktree remove command left ${options.checkoutPath} registered as a Git worktree`,
+			})
+		}
+		if (options.preserveBranch) {
+			const branchExists = yield* fs.runCommand(
+				[
+					"git",
+					"-C",
+					options.repositoryPath,
+					"show-ref",
+					"--verify",
+					"--quiet",
+					`refs/heads/${options.branch}`,
+				],
+				{ captureOutput: true },
+			)
+			if (branchExists.exitCode !== 0) {
+				return yield* new WorktreeError({
+					message: `Worktree remove command deleted branch '${options.branch}' in repository '${options.alias}'; it must preserve the branch`,
+				})
+			}
+		}
+	})
+
 const isCommitId = (ref: string) => /^[0-9a-f]{40,64}$/i.test(ref)
 
 const originRef = (ref: string) =>
@@ -1083,12 +1182,16 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								}
 								if (config.worktreeCreateCommand) {
 									try {
-										expandWorktreeCreateCommand(config.worktreeCreateCommand, {
-											repo: repositoryPath,
-											worktree: checkoutPath,
-											branch: checkout.branch,
-											base: executionBase,
-										})
+										expandWorktreeCommand(
+											"worktreeCreateCommand",
+											config.worktreeCreateCommand,
+											{
+												repo: repositoryPath,
+												worktree: checkoutPath,
+												branch: checkout.branch,
+												base: executionBase,
+											},
+										)
 									} catch (cause) {
 										return yield* new WorktreeError({
 											message:
@@ -1364,7 +1467,8 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											base: executionBase,
 										}
 										try {
-											args = expandWorktreeCreateCommand(
+											args = expandWorktreeCommand(
+												"worktreeCreateCommand",
 												config.worktreeCreateCommand,
 												variables,
 											)
@@ -1781,18 +1885,37 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											!(yield* fs.isDirectory(checkoutPath))
 										)
 											continue
-										const removed = yield* fs.runCommand(
-											[
-												"git",
-												"-C",
-												join(root, "repos", checkout.repo),
-												"worktree",
-												"remove",
-												"--force",
-												checkoutPath,
-											],
-											{ captureOutput: true },
-										)
+										const repositoryPath = join(root, "repos", checkout.repo)
+										const removed =
+											config.worktreeRemoveCommand && "branch" in checkout
+												? yield* runWorktreeRemoveCommand({
+														command: config.worktreeRemoveCommand,
+														alias: checkout.repo,
+														repositoryPath,
+														checkoutPath,
+														branch: checkout.branch,
+														base: executionBase,
+														preserveBranch: false,
+														forwardOutput: forwardCommandOutput,
+														verboseLog,
+													}).pipe(
+														Effect.as({ exitCode: 0 }),
+														Effect.catchAll(() =>
+															Effect.succeed({ exitCode: 1 }),
+														),
+													)
+												: yield* fs.runCommand(
+														[
+															"git",
+															"-C",
+															repositoryPath,
+															"worktree",
+															"remove",
+															"--force",
+															checkoutPath,
+														],
+														{ captureOutput: true },
+													)
 										if (removed.exitCode === 0)
 											rolledBack.push(`create-worktree ${checkout.repo}`)
 										else manualRecovery.push(`Remove ${checkoutPath}`)
@@ -1821,6 +1944,24 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 										]),
 									).values()
 									for (const branch of branchCandidates) {
+										if (config.worktreeRemoveCommand) {
+											const branchExists = yield* fs.runCommand(
+												[
+													"git",
+													"-C",
+													join(root, "repos", branch.repo),
+													"show-ref",
+													"--verify",
+													"--quiet",
+													`refs/heads/${branch.branch}`,
+												],
+												{ captureOutput: true },
+											)
+											if (branchExists.exitCode !== 0) {
+												rolledBack.push(`create-branch ${branch.repo}`)
+												continue
+											}
+										}
 										const deleted = yield* fs.runCommand(
 											[
 												"git",
@@ -1881,7 +2022,10 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 					const workbase = yield* WorkbaseService
 					const tasks = yield* TaskService
 					const phases = yield* PhaseService
-					const root = yield* workbase.discover(startPath)
+					const { verboseLog } = createLoggers(options)
+					const forwardCommandOutput =
+						options.verbose === true && !options.silent && !options.json
+					const { root, config } = yield* workbase.loadConfig(startPath)
 					const removal = Effect.gen(function* () {
 						const inspection = yield* inspectExecution(taskId, phaseId, root)
 						const blockingConflicts = inspection.conflicts.filter(
@@ -1907,6 +2051,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									repo: string
 									repos?: readonly RepositoryReference[]
 									branch: string
+									base: string
 							  }
 							| { review: { repo: string; commit: string } }
 						let codePath: string
@@ -1959,6 +2104,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 							checkoutPath: string
 							registeredPath: string
 							checkoutExists: boolean
+							writable: boolean
 							head?: string
 							branch?: string
 						}[] = []
@@ -2115,6 +2261,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								checkoutPath,
 								registeredPath: registered.path,
 								checkoutExists,
+								writable: "branch" in checkout,
 								head: registered.head,
 								branch: registered.branch?.replace(/^refs\/heads\//, ""),
 							})
@@ -2188,6 +2335,34 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 							})
 						const removed = yield* Effect.gen(function* () {
 							for (const plan of removalPlans) {
+								if (
+									config.worktreeRemoveCommand &&
+									plan.writable &&
+									plan.checkoutExists &&
+									plan.branch &&
+									!("review" in execution)
+								) {
+									yield* runWorktreeRemoveCommand({
+										command: config.worktreeRemoveCommand,
+										alias: plan.alias,
+										repositoryPath: plan.repositoryPath,
+										checkoutPath: plan.checkoutPath,
+										branch: plan.branch,
+										base: execution.base,
+										preserveBranch: true,
+										forwardOutput: forwardCommandOutput,
+										verboseLog,
+									}).pipe(
+										Effect.tapError(() =>
+											Effect.gen(function* () {
+												if (!(yield* fs.exists(plan.checkoutPath)))
+													completed.push(plan)
+											}),
+										),
+									)
+									completed.push(plan)
+									continue
+								}
 								const command = plan.checkoutExists
 									? [
 											"git",

package/src/workbase/schemas.ts

@@ -109,6 +109,7 @@ export const WorkbaseConfig = Schema.Struct({
 	chooserCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 	branchNameCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 	worktreeCreateCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
+	worktreeRemoveCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 	agents: Schema.optional(
 		Schema.Record({
 			key: EntityId,

package/src/workbase/worktree-command.ts

@@ -5,15 +5,20 @@ interface WorktreeCommandVariables {
 	readonly base: string
 }
 
+type WorktreeCommandSetting = "worktreeCreateCommand" | "worktreeRemoveCommand"
+
 const REQUIRED_PLACEHOLDERS = ["repo", "worktree"] as const
 const PLACEHOLDERS = new Set(["repo", "worktree", "branch", "base"])
 
-export const validateWorktreeCreateCommand = (command: readonly string[]) => {
+export const validateWorktreeCommand = (
+	setting: WorktreeCommandSetting,
+	command: readonly string[],
+) => {
 	const template = command.join("\u0000")
 	for (const placeholder of REQUIRED_PLACEHOLDERS) {
 		if (!template.includes(`{${placeholder}}`)) {
 			throw new Error(
-				`worktreeCreateCommand must include the {${placeholder}} placeholder`,
+				`${setting} must include the {${placeholder}} placeholder`,
 			)
 		}
 	}
@@ -21,19 +26,18 @@ export const validateWorktreeCreateCommand = (command: readonly string[]) => {
 		for (const match of argument.matchAll(/\{([^{}]+)\}/g)) {
 			const placeholder = match[1]!
 			if (!PLACEHOLDERS.has(placeholder)) {
-				throw new Error(
-					`Unknown worktreeCreateCommand placeholder: {${placeholder}}`,
-				)
+				throw new Error(`Unknown ${setting} placeholder: {${placeholder}}`)
 			}
 		}
 	}
 }
 
-export const expandWorktreeCreateCommand = (
+export const expandWorktreeCommand = (
+	setting: WorktreeCommandSetting,
 	command: readonly string[],
 	variables: WorktreeCommandVariables,
 ): string[] => {
-	validateWorktreeCreateCommand(command)
+	validateWorktreeCommand(setting, command)
 
 	return command.map((argument) =>
 		argument.replaceAll(/\{([^{}]+)\}/g, (match, placeholder: string) => {