@markjaquith/agency 2.55.0 → 2.56.0

package/README.md

@@ -235,6 +235,56 @@ Supplemental read-only repositories remain detached Git worktrees at their
 declared refs so they do not acquire writable branches. Jj workbases always use
 jj workspaces and ignore this Git-specific customization.
 
+### Post-checkout Commands
+
+Each repository declaration may provide a VCS-neutral `postCheckoutCommand` argv
+template for repository-specific setup. Agency invokes it directly, without a
+shell, with the new checkout as its working directory:
+
+```json
+{
+	"version": 2,
+	"repositories": {
+		"frontend": {
+			"remote": "git@example.com:team/frontend.git",
+			"postCheckoutCommand": ["bun", "install", "--frozen-lockfile"]
+		}
+	}
+}
+```
+
+The hook runs for each newly created managed checkout, including writable and
+reference checkouts, after Git worktree or jj workspace creation has completed
+and Agency has validated the checkout. It does not run for a reused checkout or
+for inspection-only commands. A custom `worktreeCreateCommand` completes and is
+validated before this hook runs.
+
+Available placeholders and matching environment variables are:
+
+| Placeholder        | Environment              | Value                                          |
+| ------------------ | ------------------------ | ---------------------------------------------- |
+| `{repoAlias}`      | `AGENCY_REPO_ALIAS`      | Repository alias                               |
+| `{repositoryPath}` | `AGENCY_REPOSITORY_PATH` | Absolute source repository path under `repos/` |
+| `{checkoutPath}`   | `AGENCY_CHECKOUT_PATH`   | Absolute managed checkout path                 |
+| `{checkoutKind}`   | `AGENCY_CHECKOUT_KIND`   | `writable` or `reference`                      |
+| `{requestedRef}`   | `AGENCY_REQUESTED_REF`   | Requested branch, reference, or review commit  |
+| `{base}`           | `AGENCY_BASE`            | Configured execution base                      |
+| `{vcs}`            | `AGENCY_VCS`             | `git` or `jj`                                  |
+| `{workbaseRoot}`   | `AGENCY_WORKBASE_ROOT`   | Absolute workbase root                         |
+| `{taskId}`         | `AGENCY_TASK_ID`         | Task ID                                        |
+| `{phaseId}`        | `AGENCY_PHASE_ID`        | Phase ID                                       |
+
+`{base}` and `{phaseId}` and their environment variables are empty strings when
+they do not apply. Dry runs report a planned `post-checkout` operation but never
+execute it. Verbose output identifies the repository and expanded command.
+
+Hook success is part of checkout creation. A non-zero exit or failure to start
+rolls back the checkout and any branch created by the same operation; if cleanup
+also fails, Agency reports the exact manual recovery action. A later command
+retries checkout creation and the hook rather than reusing an uninitialized
+checkout. Hook commands should be idempotent so a retry is safe after any
+external effects the failed invocation may have completed.
+
 ### Agent Runners
 
 OpenCode and Claude Code are built-in runner presets. Select either preset or a

package/package.json

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

package/src/services/DoctorService.ts

@@ -173,6 +173,18 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 									] as const,
 								]
 							: []),
+						...Object.entries(config.repositories ?? {}).flatMap(
+							([alias, repository]) =>
+								repository.postCheckoutCommand
+									? [
+											[
+												`integration.repository.${alias}.post-checkout`,
+												repository.postCheckoutCommand,
+												`Repository '${alias}' post-checkout hook`,
+											] as const,
+										]
+									: [],
+						),
 						...Object.entries(config.runners ?? {}).map(
 							([name, runner]) =>
 								[

package/src/services/WorkbaseService.test.ts

@@ -371,6 +371,30 @@ status: done
 		).rejects.toThrow("{worktree}")
 	})
 
+	test("rejects an unknown post-checkout command placeholder", async () => {
+		await write(
+			root,
+			"agency.json",
+			JSON.stringify({
+				version: 2,
+				repositories: {
+					agency: {
+						remote: "https://example.com/agency.git",
+						postCheckoutCommand: ["tool", "{unknown}"],
+					},
+				},
+			}),
+		)
+
+		await expect(
+			runTestEffect(
+				WorkbaseService.pipe(
+					Effect.flatMap((service) => service.discover(root)),
+				),
+			),
+		).rejects.toThrow("Repository 'agency'")
+	})
+
 	test("rejects an unknown runner command placeholder", async () => {
 		await write(
 			root,

package/src/services/WorkbaseService.ts

@@ -20,6 +20,7 @@ import {
 	type WorkbaseRegistration,
 } from "../workbase/schemas"
 import { validateWorktreeCreateCommand } from "../workbase/worktree-command"
+import { validatePostCheckoutCommand } from "../workbase/checkout-command"
 import { validateRunners } from "../workbase/runner-command"
 import { findDependencyCycles } from "../workbase/dependency-graph"
 import { validateDelivery } from "../workbase/delivery-command"
@@ -274,6 +275,23 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 										})
 									}
 								}
+								for (const [alias, repository] of Object.entries(
+									decoded.value.repositories ?? {},
+								)) {
+									if (!repository.postCheckoutCommand) continue
+									try {
+										validatePostCheckoutCommand(repository.postCheckoutCommand)
+									} catch (cause) {
+										return yield* new WorkbaseConfigError({
+											path: configPath,
+											message: `Repository '${alias}': ${
+												cause instanceof Error
+													? cause.message
+													: "Invalid postCheckoutCommand"
+											}`,
+										})
+									}
+								}
 								try {
 									validateRunners(decoded.value.runners)
 									validateDelivery(decoded.value.delivery)

package/src/services/WorktreeService.test.ts

@@ -104,6 +104,126 @@ describe("WorktreeService", () => {
 		expect(new TextDecoder().decode(branch.stdout).trim()).toBe("task/example")
 	})
 
+	test("runs repository hooks for new writable and reference checkouts", async () => {
+		await ensureEffectRepository()
+		const hook = [
+			"sh",
+			"-c",
+			'printf "%s\\n" "$@" > post-checkout-argv; env | grep "^AGENCY_" | sort > post-checkout-env; printf x >> post-checkout-count',
+			"post-checkout",
+			"{repoAlias}",
+			"{repositoryPath}",
+			"{checkoutPath}",
+			"{checkoutKind}",
+			"{requestedRef}",
+			"{base}",
+			"{vcs}",
+			"{workbaseRoot}",
+			"{taskId}",
+			"{phaseId}",
+		]
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				repositories: {
+					agency: {
+						remote: "https://example.com/agency.git",
+						postCheckoutCommand: hook,
+					},
+					effect: {
+						remote: "https://example.com/effect.git",
+						postCheckoutCommand: hook,
+					},
+				},
+			}),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "hooked",
+							ticketUrl: null,
+							repo: "agency",
+							repos: [{ repo: "effect", ref: "main" }],
+							branch: "task/hooked",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+
+		const workspace = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("hooked", undefined, root),
+				),
+			),
+		)
+		const writable = workspace.writablePath!
+		const reference = join(workspace.codePath, "effect")
+		expect(await Bun.file(join(writable, "post-checkout-argv")).text()).toBe(
+			[
+				"agency",
+				join(root, "repos/agency"),
+				writable,
+				"writable",
+				"task/hooked",
+				"main",
+				"git",
+				root,
+				"hooked",
+				"",
+				"",
+			].join("\n"),
+		)
+		expect(
+			await Bun.file(join(reference, "post-checkout-argv")).text(),
+		).toContain("reference\nmain\nmain\ngit")
+		const environment = await Bun.file(
+			join(writable, "post-checkout-env"),
+		).text()
+		expect(environment).toContain(`AGENCY_CHECKOUT_PATH=${writable}\n`)
+		expect(environment).toContain("AGENCY_CHECKOUT_KIND=writable\n")
+		expect(environment).toContain("AGENCY_PHASE_ID=\n")
+		expect(workspace.operations).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
+					action: "post-checkout",
+					repo: "agency",
+					status: "completed",
+				}),
+				expect.objectContaining({
+					action: "post-checkout",
+					repo: "effect",
+					status: "completed",
+				}),
+			]),
+		)
+
+		const reused = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("hooked", undefined, root),
+				),
+			),
+		)
+		expect(
+			reused.operations.filter(
+				(operation) => operation.action === "post-checkout",
+			),
+		).toEqual([])
+		expect(await Bun.file(join(writable, "post-checkout-count")).text()).toBe(
+			"x",
+		)
+		expect(await Bun.file(join(reference, "post-checkout-count")).text()).toBe(
+			"x",
+		)
+	})
+
 	test("materializes and removes a jj workspace for a jj workbase", async () => {
 		if (!Bun.which("jj")) return
 		const repository = join(root, "repos/agency")
@@ -112,7 +232,20 @@ describe("WorktreeService", () => {
 		await jj(["git", "init", "--colocate", repository])
 		await Bun.write(
 			join(root, "agency.json"),
-			JSON.stringify({ version: 2, vcs: "jj" }),
+			JSON.stringify({
+				version: 2,
+				vcs: "jj",
+				repositories: {
+					agency: {
+						remote: "https://example.com/agency.git",
+						postCheckoutCommand: [
+							"sh",
+							"-c",
+							'printf "%s:%s" "$AGENCY_VCS" "$AGENCY_CHECKOUT_KIND" > post-checkout',
+						],
+					},
+				},
+			}),
 		)
 		await runTestEffect(
 			TaskService.pipe(
@@ -140,6 +273,9 @@ describe("WorktreeService", () => {
 		)
 		const jjMetadata = await stat(join(workspace.writablePath!, ".jj"))
 		expect(jjMetadata.isFile() || jjMetadata.isDirectory()).toBe(true)
+		expect(
+			await Bun.file(join(workspace.writablePath!, "post-checkout")).text(),
+		).toBe("jj:writable")
 		const inspection = await runTestEffect(
 			WorktreeService.pipe(
 				Effect.flatMap((service) =>
@@ -440,6 +576,22 @@ describe("WorktreeService", () => {
 	})
 
 	test("selects phases and rejects missing or unexpected phase IDs", async () => {
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				repositories: {
+					agency: {
+						remote: "https://example.com/agency.git",
+						postCheckoutCommand: [
+							"sh",
+							"-c",
+							'printf "%s:%s" "$AGENCY_TASK_ID" "$AGENCY_PHASE_ID" > post-checkout-owner',
+						],
+					},
+				},
+			}),
+		)
 		await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>
@@ -503,6 +655,11 @@ describe("WorktreeService", () => {
 		expect(workspace.writablePath).toBe(
 			join(root, "tasks/multi/phases/selected/code/agency"),
 		)
+		expect(
+			await Bun.file(
+				join(workspace.writablePath!, "post-checkout-owner"),
+			).text(),
+		).toBe("multi:selected")
 
 		await runTestEffect(
 			TaskService.pipe(
@@ -663,6 +820,231 @@ pr: null
 		).not.toBe(0)
 	})
 
+	test("reports a planned hook in dry runs without executing it", async () => {
+		const marker = join(root, "dry-run-hook")
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				repositories: {
+					agency: {
+						remote: "https://example.com/agency.git",
+						postCheckoutCommand: ["sh", "-c", 'touch "$1"', "hook", marker],
+					},
+				},
+			}),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "dry-hook",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/dry-hook",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+
+		const materializeDry = () =>
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.materialize("dry-hook", undefined, root, {
+							dryRun: true,
+							verbose: true,
+						}),
+					),
+				),
+			)
+		let workspace!: Awaited<ReturnType<typeof materializeDry>>
+		const logs = await captureErrors(async () => {
+			workspace = await materializeDry()
+		})
+		expect(workspace.operations).toContainEqual({
+			action: "post-checkout",
+			repo: "agency",
+			command: ["sh", "-c", 'touch "$1"', "hook", marker],
+			status: "planned",
+		})
+		expect(await Bun.file(marker).exists()).toBe(false)
+		expect(await Bun.file(workspace.writablePath!).exists()).toBe(false)
+		expect(logs).toEqual([
+			expect.stringContaining("Planning post-checkout command for 'agency':"),
+		])
+	})
+
+	test("rolls back a failed hook and runs it again on retry", async () => {
+		const retryMarker = join(root, "retry-hook")
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				repositories: {
+					agency: {
+						remote: "https://example.com/agency.git",
+						postCheckoutCommand: [
+							"sh",
+							"-c",
+							'if [ ! -f "$1" ]; then touch partial-bootstrap "$1"; echo bootstrap-failed >&2; exit 7; fi',
+							"hook",
+							retryMarker,
+						],
+					},
+				},
+			}),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "retry-hook",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/retry-hook",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const checkoutPath = join(root, "tasks/retry-hook/code/agency")
+
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.materialize("retry-hook", undefined, root),
+					),
+				),
+			),
+		).rejects.toThrow("bootstrap-failed")
+		expect(await Bun.file(checkoutPath).exists()).toBe(false)
+		expect(
+			Bun.spawnSync([
+				"git",
+				"-C",
+				join(root, "repos/agency"),
+				"show-ref",
+				"--verify",
+				"refs/heads/task/retry-hook",
+			]).exitCode,
+		).not.toBe(0)
+
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.materialize("retry-hook", undefined, root),
+					),
+				),
+			),
+		).resolves.toMatchObject({ writablePath: checkoutPath })
+	})
+
+	test("does not run a hook when checkout validation fails", async () => {
+		const marker = join(root, "invalid-checkout-hook")
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				worktreeCreateCommand: [
+					"git",
+					"-C",
+					"{repo}",
+					"worktree",
+					"add",
+					"--detach",
+					"{worktree}",
+					"{base}",
+				],
+				repositories: {
+					agency: {
+						remote: "https://example.com/agency.git",
+						postCheckoutCommand: ["sh", "-c", 'touch "$1"', "hook", marker],
+					},
+				},
+			}),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "invalid-hook-order",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/invalid-hook-order",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.materialize("invalid-hook-order", undefined, root),
+					),
+				),
+			),
+		).rejects.toThrow("failed validation")
+		expect(await Bun.file(marker).exists()).toBe(false)
+	})
+
+	test("rolls back when a hook executable cannot be started", async () => {
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				repositories: {
+					agency: {
+						remote: "https://example.com/agency.git",
+						postCheckoutCommand: ["agency-missing-hook-executable"],
+					},
+				},
+			}),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "missing-hook-command",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/missing-hook-command",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const checkoutPath = join(root, "tasks/missing-hook-command/code/agency")
+
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.materialize("missing-hook-command", undefined, root),
+					),
+				),
+			),
+		).rejects.toThrow("Failed to start post-checkout command for 'agency'")
+		expect(await Bun.file(checkoutPath).exists()).toBe(false)
+	})
+
 	test("moves and repairs an existing worktree when converting a task", async () => {
 		await runTestEffect(
 			TaskService.pipe(

package/src/services/WorktreeService.ts

@@ -8,7 +8,12 @@ import {
 	expandWorktreeCreateCommand,
 	worktreeCommandEnvironment,
 } from "../workbase/worktree-command"
-import type { RepositoryReference } from "../workbase/schemas"
+import {
+	expandPostCheckoutCommand,
+	postCheckoutCommandEnvironment,
+	type CheckoutCommandVariables,
+} from "../workbase/checkout-command"
+import type { RepositoryReference, WorkbaseConfig } from "../workbase/schemas"
 import type { BaseCommandOptions } from "../utils/command"
 import { createLoggers } from "../utils/effect"
 import { withWorktreeLocks } from "./WorktreeLock"
@@ -35,6 +40,7 @@ interface WorkspaceOperation {
 		| "create-branch"
 		| "create-worktree"
 		| "create-workspace"
+		| "post-checkout"
 	readonly repo: string
 	readonly command: readonly string[]
 	readonly status: "planned" | "completed"
@@ -176,6 +182,70 @@ const formatCommand = (args: readonly string[]) =>
 		)
 		.join(" ")
 
+const runPostCheckoutHook = (options: {
+	readonly command: readonly string[] | undefined
+	readonly variables: CheckoutCommandVariables
+	readonly dryRun: boolean
+	readonly forwardOutput: boolean
+	readonly verboseLog: (...args: unknown[]) => void
+	readonly operations: WorkspaceOperation[]
+}) =>
+	Effect.gen(function* () {
+		if (!options.command) return
+		let command: string[]
+		try {
+			command = expandPostCheckoutCommand(options.command, options.variables)
+		} catch (cause) {
+			return yield* new WorktreeError({
+				message:
+					cause instanceof Error
+						? cause.message
+						: "Invalid postCheckoutCommand",
+				cause,
+			})
+		}
+		options.verboseLog(
+			`${options.dryRun ? "Planning" : "Running"} post-checkout command for '${options.variables.repoAlias}': ${formatCommand(command)}`,
+		)
+		if (options.dryRun) {
+			options.operations.push({
+				action: "post-checkout",
+				repo: options.variables.repoAlias,
+				command,
+				status: "planned",
+			})
+			return
+		}
+		const result = yield* FileSystemService.pipe(
+			Effect.flatMap((fs) =>
+				fs.runCommand(command, {
+					cwd: options.variables.checkoutPath,
+					captureOutput: true,
+					forwardOutput: options.forwardOutput,
+					env: postCheckoutCommandEnvironment(options.variables),
+				}),
+			),
+			Effect.mapError(
+				(cause) =>
+					new WorktreeError({
+						message: `Failed to start post-checkout command for '${options.variables.repoAlias}': ${cause.message}`,
+						cause,
+					}),
+			),
+		)
+		if (result.exitCode !== 0) {
+			return yield* new WorktreeError({
+				message: `Post-checkout command failed for '${options.variables.repoAlias}' with exit code ${result.exitCode}${result.stderr ? `: ${result.stderr}` : ""}`,
+			})
+		}
+		options.operations.push({
+			action: "post-checkout",
+			repo: options.variables.repoAlias,
+			command,
+			status: "completed",
+		})
+	})
+
 const isCommitId = (ref: string) => /^[0-9a-f]{40,64}$/i.test(ref)
 
 const originRef = (ref: string) =>
@@ -812,6 +882,7 @@ const materializeJj = (options: {
 		| { readonly repo: string; readonly branch: string }
 		| RepositoryReference
 	)[]
+	readonly config: WorkbaseConfig
 	readonly commandOptions: MaterializeOptions
 }) =>
 	Effect.gen(function* () {
@@ -826,6 +897,11 @@ const materializeJj = (options: {
 			workspaceName: string
 		}[] = []
 		const base = "base" in options.execution ? options.execution.base : null
+		const { verboseLog } = createLoggers(options.commandOptions)
+		const forwardCommandOutput =
+			options.commandOptions.verbose === true &&
+			!options.commandOptions.silent &&
+			!options.commandOptions.json
 
 		if (!options.commandOptions.dryRun)
 			yield* fs.createDirectory(options.codePath)
@@ -920,7 +996,37 @@ const materializeJj = (options: {
 						...("branch" in checkout ? { branch: checkout.branch } : {}),
 					})
 					created.push({ repositoryPath, workspacePath, workspaceName })
+					const canonicalWorkspacePath = yield* fs.realPath(workspacePath)
+					const registeredAfterCreate = (yield* backend.listWorkspaces(
+						repositoryPath,
+					)).find((workspace) => workspace.path === canonicalWorkspacePath)
+					const head = yield* backend.workspaceHead(workspacePath)
+					if (!registeredAfterCreate || head !== revision) {
+						return yield* new WorktreeError({
+							message: `Created jj workspace for '${checkout.repo}' failed validation`,
+						})
+					}
 				}
+				yield* runPostCheckoutHook({
+					command:
+						options.config.repositories?.[checkout.repo]?.postCheckoutCommand,
+					variables: {
+						repoAlias: checkout.repo,
+						repositoryPath,
+						checkoutPath: workspacePath,
+						checkoutKind: "branch" in checkout ? "writable" : "reference",
+						requestedRef: requestedRevision,
+						base: base ?? "",
+						vcs: "jj",
+						workbaseRoot: options.root,
+						taskId: options.taskId,
+						phaseId: options.phaseId ?? "",
+					},
+					dryRun: options.commandOptions.dryRun === true,
+					forwardOutput: forwardCommandOutput,
+					verboseLog,
+					operations,
+				})
 				reports.push({
 					repo: checkout.repo,
 					kind: "branch" in checkout ? "writable" : "reference",
@@ -957,16 +1063,36 @@ const materializeJj = (options: {
 		}).pipe(
 			Effect.catchAll((cause) =>
 				Effect.gen(function* () {
+					const rolledBack: string[] = []
+					const manualRecovery: string[] = []
 					for (const workspace of [...created].reverse()) {
-						yield* backend
+						const removed = yield* backend
 							.removeWorkspace({
 								repositoryPath: workspace.repositoryPath,
 								workspacePath: workspace.workspacePath,
 								workspaceName: workspace.workspaceName,
 							})
-							.pipe(Effect.ignore)
+							.pipe(
+								Effect.as(true),
+								Effect.catchAll(() => Effect.succeed(false)),
+							)
+						if (removed)
+							rolledBack.push(`create-workspace ${workspace.workspaceName}`)
+						else
+							manualRecovery.push(
+								`Remove jj workspace ${workspace.workspacePath}`,
+							)
 					}
-					return yield* Effect.fail(cause)
+					return yield* new WorktreeError({
+						message: `${cause instanceof Error ? cause.message : "Workspace creation failed"}. ${
+							manualRecovery.length
+								? "Some effects require manual recovery"
+								: "Created jj workspaces were rolled back"
+						}`,
+						rolledBack,
+						manualRecovery,
+						cause,
+					})
 				}),
 			),
 		)
@@ -1245,6 +1371,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								codePath,
 								execution,
 								requestedCheckouts,
+								config,
 								commandOptions: options,
 							})
 						}
@@ -1695,6 +1822,26 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 												{ captureOutput: true },
 											)
 										}
+										yield* runPostCheckoutHook({
+											command:
+												config.repositories?.[alias]?.postCheckoutCommand,
+											variables: {
+												repoAlias: alias,
+												repositoryPath,
+												checkoutPath,
+												checkoutKind: "writable",
+												requestedRef: checkout.branch,
+												base: executionBase,
+												vcs: "git",
+												workbaseRoot: root,
+												taskId,
+												phaseId: phaseId ?? "",
+											},
+											dryRun: true,
+											forwardOutput: false,
+											verboseLog,
+											operations,
+										})
 										checkoutReports.push({
 											repo: alias,
 											kind: "writable",
@@ -1739,6 +1886,38 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 										["git", "-C", checkoutPath, "rev-parse", "HEAD"],
 										{ captureOutput: true },
 									)
+									const currentBranch = yield* fs.runCommand(
+										["git", "-C", checkoutPath, "branch", "--show-current"],
+										{ captureOutput: true },
+									)
+									if (
+										head.exitCode !== 0 ||
+										currentBranch.exitCode !== 0 ||
+										currentBranch.stdout.trim() !== checkout.branch
+									) {
+										return yield* new WorktreeError({
+											message: `Created worktree for '${alias}' failed validation for branch '${checkout.branch}'`,
+										})
+									}
+									yield* runPostCheckoutHook({
+										command: config.repositories?.[alias]?.postCheckoutCommand,
+										variables: {
+											repoAlias: alias,
+											repositoryPath,
+											checkoutPath,
+											checkoutKind: "writable",
+											requestedRef: checkout.branch,
+											base: executionBase,
+											vcs: "git",
+											workbaseRoot: root,
+											taskId,
+											phaseId: phaseId ?? "",
+										},
+										dryRun: false,
+										forwardOutput: forwardCommandOutput,
+										verboseLog,
+										operations,
+									})
 									checkoutReports.push({
 										repo: alias,
 										kind: "writable",
@@ -1831,6 +2010,26 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											command,
 											status: "planned",
 										})
+										yield* runPostCheckoutHook({
+											command:
+												config.repositories?.[alias]?.postCheckoutCommand,
+											variables: {
+												repoAlias: alias,
+												repositoryPath,
+												checkoutPath,
+												checkoutKind: "reference",
+												requestedRef: checkout.ref,
+												base: executionBase,
+												vcs: "git",
+												workbaseRoot: root,
+												taskId,
+												phaseId: phaseId ?? "",
+											},
+											dryRun: true,
+											forwardOutput: false,
+											verboseLog,
+											operations,
+										})
 										checkoutReports.push({
 											repo: alias,
 											kind: "reference",
@@ -1855,6 +2054,34 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 										command,
 										status: "completed",
 									})
+									const head = yield* fs.runCommand(
+										["git", "-C", checkoutPath, "rev-parse", "HEAD"],
+										{ captureOutput: true },
+									)
+									if (head.exitCode !== 0 || head.stdout.trim() !== commit) {
+										return yield* new WorktreeError({
+											message: `Created reference checkout for '${alias}' failed validation for '${checkout.ref}'`,
+										})
+									}
+									yield* runPostCheckoutHook({
+										command: config.repositories?.[alias]?.postCheckoutCommand,
+										variables: {
+											repoAlias: alias,
+											repositoryPath,
+											checkoutPath,
+											checkoutKind: "reference",
+											requestedRef: checkout.ref,
+											base: executionBase,
+											vcs: "git",
+											workbaseRoot: root,
+											taskId,
+											phaseId: phaseId ?? "",
+										},
+										dryRun: false,
+										forwardOutput: forwardCommandOutput,
+										verboseLog,
+										operations,
+									})
 									checkoutReports.push({
 										repo: alias,
 										kind: "reference",
@@ -1918,6 +2145,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 												join(root, "repos", checkout.repo),
 												"worktree",
 												"remove",
+												"--force",
 												checkoutPath,
 											],
 											{ captureOutput: true },

package/src/workbase/checkout-command.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test"
+import {
+	expandPostCheckoutCommand,
+	postCheckoutCommandEnvironment,
+} from "./checkout-command"
+
+const variables = {
+	repoAlias: "app",
+	repositoryPath: "/work/repos/app",
+	checkoutPath: "/work/tasks/example/code/app",
+	checkoutKind: "reference" as const,
+	requestedRef: "main",
+	base: "",
+	vcs: "jj" as const,
+	workbaseRoot: "/work",
+	taskId: "example",
+	phaseId: "",
+}
+
+describe("post-checkout command templates", () => {
+	test("expands all context placeholders without shell interpolation", () => {
+		expect(
+			expandPostCheckoutCommand(
+				[
+					"tool",
+					"{repoAlias}",
+					"{repositoryPath}",
+					"{checkoutPath}",
+					"{checkoutKind}",
+					"{requestedRef}",
+					"{base}",
+					"{vcs}",
+					"{workbaseRoot}",
+					"{taskId}",
+					"{phaseId}",
+				],
+				variables,
+			),
+		).toEqual(["tool", ...Object.values(variables)])
+	})
+
+	test("rejects unknown placeholders", () => {
+		expect(() =>
+			expandPostCheckoutCommand(["tool", "{unknown}"], variables),
+		).toThrow("{unknown}")
+	})
+
+	test("provides matching environment variables with empty optional values", () => {
+		expect(postCheckoutCommandEnvironment(variables)).toEqual({
+			AGENCY_REPO_ALIAS: variables.repoAlias,
+			AGENCY_REPOSITORY_PATH: variables.repositoryPath,
+			AGENCY_CHECKOUT_PATH: variables.checkoutPath,
+			AGENCY_CHECKOUT_KIND: variables.checkoutKind,
+			AGENCY_REQUESTED_REF: variables.requestedRef,
+			AGENCY_BASE: "",
+			AGENCY_VCS: variables.vcs,
+			AGENCY_WORKBASE_ROOT: variables.workbaseRoot,
+			AGENCY_TASK_ID: variables.taskId,
+			AGENCY_PHASE_ID: "",
+		})
+	})
+})

package/src/workbase/checkout-command.ts

@@ -0,0 +1,66 @@
+export interface CheckoutCommandVariables {
+	readonly repoAlias: string
+	readonly repositoryPath: string
+	readonly checkoutPath: string
+	readonly checkoutKind: "writable" | "reference"
+	readonly requestedRef: string
+	readonly base: string
+	readonly vcs: "git" | "jj"
+	readonly workbaseRoot: string
+	readonly taskId: string
+	readonly phaseId: string
+}
+
+const PLACEHOLDERS = new Set<keyof CheckoutCommandVariables>([
+	"repoAlias",
+	"repositoryPath",
+	"checkoutPath",
+	"checkoutKind",
+	"requestedRef",
+	"base",
+	"vcs",
+	"workbaseRoot",
+	"taskId",
+	"phaseId",
+])
+
+export const validatePostCheckoutCommand = (command: readonly string[]) => {
+	for (const argument of command) {
+		for (const match of argument.matchAll(/\{([^{}]+)\}/g)) {
+			const placeholder = match[1]!
+			if (!PLACEHOLDERS.has(placeholder as keyof CheckoutCommandVariables)) {
+				throw new Error(
+					`Unknown postCheckoutCommand placeholder: {${placeholder}}`,
+				)
+			}
+		}
+	}
+}
+
+export const expandPostCheckoutCommand = (
+	command: readonly string[],
+	variables: CheckoutCommandVariables,
+): string[] => {
+	validatePostCheckoutCommand(command)
+
+	return command.map((argument) =>
+		argument.replaceAll(/\{([^{}]+)\}/g, (match, placeholder: string) => {
+			return variables[placeholder as keyof CheckoutCommandVariables] ?? match
+		}),
+	)
+}
+
+export const postCheckoutCommandEnvironment = (
+	variables: CheckoutCommandVariables,
+): Record<string, string> => ({
+	AGENCY_REPO_ALIAS: variables.repoAlias,
+	AGENCY_REPOSITORY_PATH: variables.repositoryPath,
+	AGENCY_CHECKOUT_PATH: variables.checkoutPath,
+	AGENCY_CHECKOUT_KIND: variables.checkoutKind,
+	AGENCY_REQUESTED_REF: variables.requestedRef,
+	AGENCY_BASE: variables.base,
+	AGENCY_VCS: variables.vcs,
+	AGENCY_WORKBASE_ROOT: variables.workbaseRoot,
+	AGENCY_TASK_ID: variables.taskId,
+	AGENCY_PHASE_ID: variables.phaseId,
+})

package/src/workbase/schemas.test.ts

@@ -187,6 +187,40 @@ describe("body-of-work descriptions", () => {
 	})
 })
 
+describe("repository post-checkout configuration", () => {
+	test("accepts a per-repository argv command", () => {
+		const config = Schema.decodeUnknownSync(WorkbaseConfig)({
+			version: 2,
+			repositories: {
+				agency: {
+					remote: "https://example.com/agency.git",
+					postCheckoutCommand: ["bun", "install", "--frozen-lockfile"],
+				},
+			},
+		})
+
+		expect(config.repositories?.agency?.postCheckoutCommand).toEqual([
+			"bun",
+			"install",
+			"--frozen-lockfile",
+		])
+	})
+
+	test("rejects shell strings in place of argv arrays", () => {
+		expect(() =>
+			Schema.decodeUnknownSync(WorkbaseConfig)({
+				version: 2,
+				repositories: {
+					agency: {
+						remote: "https://example.com/agency.git",
+						postCheckoutCommand: "bun install",
+					},
+				},
+			}),
+		).toThrow()
+	})
+})
+
 describe("runner configuration", () => {
 	test("accepts named argv commands with resume commands and environment", () => {
 		const config = Schema.decodeUnknownSync(WorkbaseConfig)({

package/src/workbase/schemas.ts

@@ -24,6 +24,7 @@ export const RepositoryRemote = NonEmptyString.pipe(
 
 export const RepositoryDeclaration = Schema.Struct({
 	remote: RepositoryRemote,
+	postCheckoutCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 })
 
 export const RepositoryReference = Schema.Struct({