@markjaquith/agency 2.12.0 → 2.13.0

package/README.md

@@ -412,6 +412,7 @@ before moving files, refuses dirty worktrees, and preserves branches.
 
 ```text
 agency work [<directory> | --epic <epic-id>] [--opencode | --claude]
+agency work prepare [target] [--dry-run] [--json]
 agency pr create <task-id> [phase-id] [--draft] [--json]
 ```
 
@@ -421,6 +422,12 @@ workbase, Agency first presents the registered workbases, then the selected
 workbase's hierarchy. If `fzf` is not installed, Agency prints the available
 choices and asks for an explicit directory.
 
+`agency work prepare` resolves an execution unit and creates or reuses its
+writable and reference worktrees without launching an agent or changing status.
+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.
+
 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

@@ -5,7 +5,7 @@ import { parseCli } from "./src/cli-parser"
 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, help as workHelp } from "./src/commands/work"
+import { work, workPrepare, help as workHelp } from "./src/commands/work"
 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"
@@ -274,10 +274,13 @@ const commands: Record<string, Command> = {
 				console.log(workHelp)
 				return
 			}
+			const preparing = args[0] === "prepare"
 			await runCommand(
-				work({
-					directory: args[0],
+				(preparing ? workPrepare : work)({
+					directory: args[preparing ? 1 : 0],
 					epicId: options.epic,
+					json: options.json,
+					dryRun: options["dry-run"],
 					silent: options.silent,
 					verbose: options.verbose,
 					opencode: options.opencode,

package/package.json

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

package/src/cli-parser.test.ts

@@ -155,6 +155,22 @@ describe("strict CLI parsing", () => {
 		expectUsageError(["status", "--compact"], "agency status")
 	})
 
+	test("accepts work preparation options only for the prepare subcommand", () => {
+		expect(
+			parseCli(["work", "prepare", "tasks/example", "--dry-run", "--json"]),
+		).toMatchObject({
+			commandName: "work",
+			args: ["prepare", "tasks/example"],
+			values: { "dry-run": true, json: true },
+		})
+		expect(() => parseCli(["work", "example", "--dry-run"])).toThrow(
+			"only valid with 'agency work prepare'",
+		)
+		expect(() => parseCli(["work", "prepare", "--opencode"])).toThrow(
+			"cannot be combined",
+		)
+	})
+
 	test("accepts repeatable graph filters and rejects output conflicts", () => {
 		expect(
 			parseCli([

package/src/cli-parser.ts

@@ -283,18 +283,22 @@ const commands = {
 		},
 	},
 	work: {
-		usage: "agency work [<directory-or-task-id> | --epic <epic-id>]",
+		usage:
+			"agency work [<directory-or-task-id> | --epic <epic-id>] | agency work prepare [target] [--dry-run] [--json]",
 		options: {
 			...commonOptions,
+			json: { type: "boolean" },
+			"dry-run": { type: "boolean" },
 			epic: { type: "string" },
 			opencode: { type: "boolean" },
 			claude: { type: "boolean" },
 		},
 		command: {
-			usage: "agency work [<directory-or-task-id> | --epic <epic-id>]",
+			usage:
+				"agency work [<directory-or-task-id> | --epic <epic-id>] | agency work prepare [target] [--dry-run] [--json]",
 			minArgs: 0,
-			maxArgs: 1,
-			options: ["epic", "opencode", "claude"],
+			maxArgs: 2,
+			options: ["json", "dry-run", "epic", "opencode", "claude"],
 			conflicts: [
 				["opencode", "claude"],
 				["epic", "$positional"],
@@ -649,6 +653,27 @@ export function parseCli(args: readonly string[]): ParsedCli {
 	if (commandName === "graph") {
 		validateGraphOptions(parsed.values, spec)
 	}
+	if (commandName === "work") {
+		const preparing = commandPositionals[0] === "prepare"
+		if (
+			(!preparing && commandPositionals.length > 1) ||
+			(preparing &&
+				(parsed.values.epic || parsed.values.opencode || parsed.values.claude))
+		) {
+			throw usageError(
+				preparing
+					? "Work preparation cannot be combined with agent or epic options."
+					: "The work command accepts at most one target.",
+				spec.usage,
+			)
+		}
+		if (!preparing && (parsed.values.json || parsed.values["dry-run"])) {
+			throw usageError(
+				"Options '--json' and '--dry-run' are only valid with 'agency work prepare'.",
+				spec.usage,
+			)
+		}
+	}
 
 	return {
 		commandName: commandName as keyof typeof commands,

package/src/cli.test.ts

@@ -301,6 +301,76 @@ status: open
 		})
 	})
 
+	test("prepares a workspace and reports a non-mutating dry-run", async () => {
+		const parent = await createTempDir()
+		tempDirs.push(parent)
+		const root = join(parent, "workbase")
+		const source = join(parent, "source")
+		expect(
+			Bun.spawnSync(["git", "init", "--initial-branch=main", source]).exitCode,
+		).toBe(0)
+		await Bun.write(join(source, "README.md"), "example\n")
+		for (const args of [
+			["config", "user.email", "test@example.com"],
+			["config", "user.name", "Test"],
+			["add", "README.md"],
+			["-c", "commit.gpgsign=false", "commit", "-m", "initial"],
+		]) {
+			expect(Bun.spawnSync(["git", "-C", source, ...args]).exitCode).toBe(0)
+		}
+
+		parseJson(await runCli(["init", root, "--json"], parent))
+		parseJson(await runCli(["repo", "link", "agency", source, "--json"], root))
+		parseJson(
+			await runCli(
+				[
+					"task",
+					"create",
+					"example",
+					"--repo",
+					"agency",
+					"--branch",
+					"feat/example",
+					"--base",
+					"main",
+					"--json",
+				],
+				root,
+			),
+		)
+
+		const planned = parseJson(
+			await runCli(["work", "prepare", "example", "--dry-run", "--json"], root),
+		)
+		const workbaseRoot = await realpath(root)
+		expect(planned).toMatchObject({
+			dryRun: true,
+			taskPath: join(workbaseRoot, "tasks/example/TASK.md"),
+			phasePath: null,
+			checkouts: [
+				{
+					repo: "agency",
+					kind: "writable",
+					action: "created",
+					resolvedCommit: expect.stringMatching(/^[0-9a-f]{40}$/),
+				},
+			],
+		})
+		await expect(access(join(root, "tasks/example/code"))).rejects.toThrow()
+
+		const prepared = parseJson(
+			await runCli(["work", "prepare", "example", "--json"], root),
+		)
+		expect(prepared).toMatchObject({
+			dryRun: false,
+			checkouts: [{ action: "created", kind: "writable" }],
+		})
+		const task = parseJson(
+			await runCli(["task", "show", "example", "--json"], root),
+		)
+		expect(task.data.status).toBe("open")
+	})
+
 	test("envelopes help and version output in machine mode", async () => {
 		const help = await runCli(["status", "--help", "--json"])
 		expect(parseJson(help)).toContain("Usage: agency status")

package/src/commands/work.test.ts

@@ -7,7 +7,7 @@ import { TaskService } from "../services/TaskService"
 import { PhaseService } from "../services/PhaseService"
 import { WorktreeService } from "../services/WorktreeService"
 import { captureErrors, captureLogs } from "../test-utils"
-import { work } from "./work"
+import { work, workPrepare } from "./work"
 import type { PickWorkTarget } from "../workbase/work-target"
 import type { PickWorkbase } from "../workbase/workbase-choice"
 import type { Progress } from "../utils/progress"
@@ -24,6 +24,9 @@ const singlePhaseWorkspace: ExecutionWorkspace = {
 	writablePath: "/workbase/tasks/example/code/agency",
 	repo: "agency",
 	repos: [],
+	dryRun: false,
+	checkouts: [],
+	operations: [],
 }
 
 const multiPhaseWorkspace: ExecutionWorkspace = {
@@ -34,6 +37,9 @@ const multiPhaseWorkspace: ExecutionWorkspace = {
 	writablePath: "/workbase/tasks/example/phases/implementation/code/agency",
 	repo: "agency",
 	repos: [],
+	dryRun: false,
+	checkouts: [],
+	operations: [],
 }
 
 interface HarnessOptions {
@@ -167,6 +173,16 @@ const createHarness = (options: HarnessOptions = {}) => {
 				Effect.provideService(PhaseService, phases as never),
 			) as Effect.Effect<void, unknown, never>,
 		)
+	const runPrepare = (commandOptions: Parameters<typeof workPrepare>[0]) =>
+		Effect.runPromise(
+			workPrepare(commandOptions).pipe(
+				Effect.provideService(WorktreeService, worktrees as never),
+				Effect.provideService(FileSystemService, fs as never),
+				Effect.provideService(WorkbaseService, workbase as never),
+				Effect.provideService(TaskService, tasks as never),
+				Effect.provideService(PhaseService, phases as never),
+			) as Effect.Effect<void, unknown, never>,
+		)
 
 	return {
 		events,
@@ -177,10 +193,32 @@ const createHarness = (options: HarnessOptions = {}) => {
 		shownTasks,
 		progressUpdates,
 		run,
+		runPrepare,
 	}
 }
 
 describe("work command", () => {
+	test("prepares without launching or changing lifecycle status", async () => {
+		const harness = createHarness({ existingDirectories: [] })
+
+		await captureLogs(() =>
+			harness.runPrepare({
+				cwd: "/workbase",
+				directory: "example",
+				json: true,
+				dryRun: true,
+			}),
+		)
+
+		expect(harness.events).toEqual(["materialize"])
+		expect(harness.launches).toEqual([])
+		expect(harness.statusUpdates).toEqual([])
+		expect(harness.materializeOptions[0]).toMatchObject({
+			json: true,
+			dryRun: true,
+		})
+	})
+
 	test("launches an epic agent from an epic directory", async () => {
 		const harness = createHarness()
 

package/src/commands/work.ts

@@ -243,14 +243,74 @@ export const work = (
 		launch(cli, [cli, ...args], launchPath)
 	})
 
+export const workPrepare = (options: WorkOptions = {}) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const workbase = yield* WorkbaseService
+		const tasks = yield* TaskService
+		const phases = yield* PhaseService
+		const worktrees = yield* WorktreeService
+		const { log } = createLoggers(options)
+		const cwd = options.cwd ?? process.cwd()
+		const targetPath = options.directory ? resolve(cwd, options.directory) : cwd
+		const isDirectory = yield* fs.isDirectory(targetPath)
+		const root = yield* workbase.discover(isDirectory ? targetPath : cwd)
+
+		let taskId: string | undefined
+		let phaseId: string | undefined
+		if (options.directory && !isDirectory) {
+			const task = yield* tasks.show(options.directory, root)
+			taskId = task.id
+		} else {
+			const path = relative(root, targetPath)
+			const parts =
+				!path || isAbsolute(path) || path.startsWith(`..${sep}`)
+					? []
+					: path.split(sep)
+			if (parts[0] === "tasks" && parts[1]) {
+				const task = yield* tasks.show(parts[1], root)
+				taskId = task.id
+				if (parts[2] === "phases" && parts[3]) {
+					const phase = yield* phases.show(task.id, parts[3], root)
+					phaseId = phase.id
+				}
+			}
+		}
+
+		if (!taskId) {
+			return yield* Effect.fail(
+				new Error(
+					"Work preparation requires a task ID or a path inside an execution unit",
+				),
+			)
+		}
+
+		const workspace = yield* worktrees.materialize(taskId, phaseId, root, {
+			...options,
+			dryRun: options.dryRun,
+		})
+		if (options.json) {
+			log(JSON.stringify(workspace, null, 2))
+		} else {
+			log(
+				`${workspace.dryRun ? "Workspace plan" : "Workspace ready"}: ${workspace.writablePath}`,
+			)
+		}
+	})
+
 export const help = `
 Usage: agency work [<directory-or-task-id> | --epic <epic-id>]
+       agency work prepare [target] [--dry-run] [--json]
 
 Launch an agent for an epic, task, or phase. With no directory, select one
 with fzf. A positional argument resolves as a directory first, then as a task
 ID. Use '.' for the current directory. Outside a workbase, select a registered
 workbase first.
 
+The prepare subcommand resolves and materializes an execution workspace without
+launching an agent or changing lifecycle status. --dry-run reports planned Git
+changes without fetching, creating branches, or creating worktrees.
+
 Options:
   --epic <id>         Work on an epic
   --opencode           Require OpenCode

package/src/services/WorktreeService.test.ts

@@ -113,15 +113,17 @@ describe("WorktreeService", () => {
 			["remote", "set-url", "origin", join(root, "missing")],
 			join(root, "repos/agency"),
 		)
-		await expect(
-			runTestEffect(
-				WorktreeService.pipe(
-					Effect.flatMap((service) =>
-						service.materialize("existing", undefined, root),
-					),
+		const reused = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("existing", undefined, root),
 				),
 			),
-		).resolves.toMatchObject({ repo: "agency" })
+		)
+		expect(reused.checkouts).toEqual([
+			expect.objectContaining({ repo: "agency", action: "reused" }),
+		])
+		expect(reused.operations).toEqual([])
 	})
 
 	test("reuses an immutable reference checkout without fetching", async () => {
@@ -771,6 +773,79 @@ pr: null
 			"refs/heads/task/removable",
 		])
 		expect(branch.exitCode).toBe(0)
+		expect(workspace.checkouts).toEqual([
+			expect.objectContaining({
+				repo: "agency",
+				kind: "writable",
+				action: "created",
+				resolvedCommit: expect.stringMatching(/^[0-9a-f]{40}$/),
+			}),
+			expect.objectContaining({
+				repo: "effect",
+				kind: "reference",
+				action: "created",
+				resolvedCommit: expect.stringMatching(/^[0-9a-f]{40}$/),
+			}),
+		])
+	})
+
+	test("reports dry-run fetch and worktree changes without mutating", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "planned",
+							ticketUrl: "https://example.com/task",
+							repo: "agency",
+							repos: [{ repo: "effect", ref: "main" }],
+							branch: "task/planned",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+
+		const workspace = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("planned", undefined, root, { dryRun: true }),
+				),
+			),
+		)
+
+		expect(workspace.dryRun).toBe(true)
+		expect(
+			workspace.checkouts.every(({ resolvedCommit }) => resolvedCommit),
+		).toBe(true)
+		expect(
+			workspace.checkouts.map(({ repo, action }) => ({ repo, action })),
+		).toEqual([
+			{ repo: "agency", action: "created" },
+			{ repo: "effect", action: "created" },
+		])
+		expect(workspace.operations).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({ action: "fetch", status: "planned" }),
+				expect.objectContaining({
+					action: "create-worktree",
+					status: "planned",
+				}),
+			]),
+		)
+		expect(await Bun.file(workspace.codePath).exists()).toBe(false)
+		expect(
+			Bun.spawnSync([
+				"git",
+				"-C",
+				join(root, "repos/agency"),
+				"show-ref",
+				"--verify",
+				"refs/heads/task/planned",
+			]).exitCode,
+		).not.toBe(0)
 	})
 
 	test("refuses to remove a worktree with uncommitted changes", async () => {

package/src/services/WorktreeService.ts

@@ -16,6 +16,22 @@ class WorktreeError extends Data.TaggedError("WorktreeError")<{
 	readonly message: string
 }> {}
 
+interface WorkspaceOperation {
+	readonly action: "fetch" | "create-branch" | "create-worktree"
+	readonly repo: string
+	readonly command: readonly string[]
+	readonly status: "planned" | "completed"
+}
+
+interface WorkspaceCheckout {
+	readonly repo: string
+	readonly kind: "writable" | "reference"
+	readonly path: string
+	readonly requestedRef: string
+	readonly resolvedCommit: string | null
+	readonly action: "created" | "reused"
+}
+
 interface ExecutionWorkspace {
 	readonly root: string
 	readonly taskPath: string
@@ -24,6 +40,9 @@ interface ExecutionWorkspace {
 	readonly writablePath: string
 	readonly repo: string
 	readonly repos: readonly RepositoryReference[]
+	readonly dryRun: boolean
+	readonly checkouts: readonly WorkspaceCheckout[]
+	readonly operations: readonly WorkspaceOperation[]
 }
 
 interface GitWorktree {
@@ -121,7 +140,9 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						codePath = join(dirname(task.path), "code")
 					}
 
-					yield* fs.createDirectory(codePath)
+					if (!options.dryRun) yield* fs.createDirectory(codePath)
+					const operations: WorkspaceOperation[] = []
+					const checkoutReports: WorkspaceCheckout[] = []
 					const checkouts: readonly (
 						| { readonly repo: string; readonly branch: string }
 						| RepositoryReference
@@ -146,23 +167,38 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									{ captureOutput: true },
 								)
 								if (remote.exitCode !== 0) return false
+								const command = [
+									"git",
+									"-C",
+									repositoryPath,
+									"fetch",
+									"origin",
+									...(ref ? [ref] : []),
+								]
+								if (options.dryRun) {
+									operations.push({
+										action: "fetch",
+										repo: alias,
+										command,
+										status: "planned",
+									})
+									return false
+								}
 
-								const fetch = yield* fs.runCommand(
-									[
-										"git",
-										"-C",
-										repositoryPath,
-										"fetch",
-										"origin",
-										...(ref ? [ref] : []),
-									],
-									{ captureOutput: true },
-								)
+								const fetch = yield* fs.runCommand(command, {
+									captureOutput: true,
+								})
 								if (fetch.exitCode !== 0) {
 									return yield* new WorktreeError({
 										message: `Failed to fetch '${alias}': ${fetch.stderr}`,
 									})
 								}
+								operations.push({
+									action: "fetch",
+									repo: alias,
+									command,
+									status: "completed",
+								})
 								return true
 							})
 
@@ -183,7 +219,9 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								message: `Failed to inspect worktrees for '${alias}': ${listed.stderr}`,
 							})
 						}
-						const canonicalCodePath = yield* fs.realPath(codePath)
+						const canonicalCodePath = (yield* fs.exists(codePath))
+							? yield* fs.realPath(codePath)
+							: resolve(codePath)
 						const canonicalCheckoutPath = join(canonicalCodePath, alias)
 						const worktrees: GitWorktree[] = []
 						for (const worktree of parseWorktreeList(listed.stdout)) {
@@ -212,7 +250,17 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								})
 							}
 							if (yield* fs.isDirectory(checkoutPath)) {
-								if (registeredAtPath?.branch === branchRef) continue
+								if (registeredAtPath?.branch === branchRef) {
+									checkoutReports.push({
+										repo: alias,
+										kind: "writable",
+										path: checkoutPath,
+										requestedRef: checkout.branch,
+										resolvedCommit: registeredAtPath.head ?? null,
+										action: "reused",
+									})
+									continue
+								}
 								return yield* new WorktreeError({
 									message: `Existing checkout ${checkoutPath} is not registered to branch '${checkout.branch}'`,
 								})
@@ -260,21 +308,29 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									{ captureOutput: true },
 								)
 								if (branchExists.exitCode !== 0) {
-									const createBranch = yield* fs.runCommand(
-										[
-											"git",
-											"-C",
-											repositoryPath,
-											"branch",
-											checkout.branch,
-											execution.base,
-										],
-										{ captureOutput: true },
-									)
-									if (createBranch.exitCode !== 0) {
-										return yield* new WorktreeError({
-											message: `Failed to create branch '${checkout.branch}': ${createBranch.stderr}`,
+									const command = [
+										"git",
+										"-C",
+										repositoryPath,
+										"branch",
+										checkout.branch,
+										execution.base,
+									]
+									operations.push({
+										action: "create-branch",
+										repo: alias,
+										command,
+										status: options.dryRun ? "planned" : "completed",
+									})
+									if (!options.dryRun) {
+										const createBranch = yield* fs.runCommand(command, {
+											captureOutput: true,
 										})
+										if (createBranch.exitCode !== 0) {
+											return yield* new WorktreeError({
+												message: `Failed to create branch '${checkout.branch}': ${createBranch.stderr}`,
+											})
+										}
 									}
 								}
 								args = [
@@ -287,6 +343,48 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									checkout.branch,
 								]
 							}
+							if (options.dryRun) {
+								operations.push({
+									action: "create-worktree",
+									repo: alias,
+									command: args,
+									status: "planned",
+								})
+								let resolved = yield* fs.runCommand(
+									[
+										"git",
+										"-C",
+										repositoryPath,
+										"rev-parse",
+										"--verify",
+										`${checkout.branch}^{commit}`,
+									],
+									{ captureOutput: true },
+								)
+								if (resolved.exitCode !== 0) {
+									resolved = yield* fs.runCommand(
+										[
+											"git",
+											"-C",
+											repositoryPath,
+											"rev-parse",
+											"--verify",
+											`${execution.base}^{commit}`,
+										],
+										{ captureOutput: true },
+									)
+								}
+								checkoutReports.push({
+									repo: alias,
+									kind: "writable",
+									path: checkoutPath,
+									requestedRef: checkout.branch,
+									resolvedCommit:
+										resolved.exitCode === 0 ? resolved.stdout.trim() : null,
+									action: "created",
+								})
+								continue
+							}
 
 							if (config.worktreeCreateCommand) {
 								verboseLog(`Running worktree command: ${formatCommand(args)}`)
@@ -308,6 +406,24 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									message: `Worktree command did not create ${checkoutPath}`,
 								})
 							}
+							operations.push({
+								action: "create-worktree",
+								repo: alias,
+								command: args,
+								status: "completed",
+							})
+							const head = yield* fs.runCommand(
+								["git", "-C", checkoutPath, "rev-parse", "HEAD"],
+								{ captureOutput: true },
+							)
+							checkoutReports.push({
+								repo: alias,
+								kind: "writable",
+								path: checkoutPath,
+								requestedRef: checkout.branch,
+								resolvedCommit: head.exitCode === 0 ? head.stdout.trim() : null,
+								action: "created",
+							})
 						} else {
 							const fetched = isCommitId(checkout.ref)
 								? false
@@ -349,6 +465,14 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									currentHead.exitCode === 0 &&
 									currentHead.stdout.trim() === commit
 								) {
+									checkoutReports.push({
+										repo: alias,
+										kind: "reference",
+										path: checkoutPath,
+										requestedRef: checkout.ref,
+										resolvedCommit: commit,
+										action: "reused",
+									})
 									continue
 								}
 								return yield* new WorktreeError({
@@ -360,24 +484,55 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									message: `Worktree registry contains a missing checkout at ${checkoutPath}`,
 								})
 							}
-							const result = yield* fs.runCommand(
-								[
-									"git",
-									"-C",
-									repositoryPath,
-									"worktree",
-									"add",
-									"--detach",
-									checkoutPath,
-									commit,
-								],
-								{ captureOutput: true },
-							)
+							const command = [
+								"git",
+								"-C",
+								repositoryPath,
+								"worktree",
+								"add",
+								"--detach",
+								checkoutPath,
+								commit,
+							]
+							if (options.dryRun) {
+								operations.push({
+									action: "create-worktree",
+									repo: alias,
+									command,
+									status: "planned",
+								})
+								checkoutReports.push({
+									repo: alias,
+									kind: "reference",
+									path: checkoutPath,
+									requestedRef: checkout.ref,
+									resolvedCommit: commit,
+									action: "created",
+								})
+								continue
+							}
+							const result = yield* fs.runCommand(command, {
+								captureOutput: true,
+							})
 							if (result.exitCode !== 0) {
 								return yield* new WorktreeError({
 									message: `Failed to create worktree for '${alias}': ${result.stderr}`,
 								})
 							}
+							operations.push({
+								action: "create-worktree",
+								repo: alias,
+								command,
+								status: "completed",
+							})
+							checkoutReports.push({
+								repo: alias,
+								kind: "reference",
+								path: checkoutPath,
+								requestedRef: checkout.ref,
+								resolvedCommit: commit,
+								action: "created",
+							})
 						}
 					}
 
@@ -389,6 +544,9 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						writablePath: join(codePath, execution.repo),
 						repo: execution.repo,
 						repos: execution.repos ?? [],
+						dryRun: options.dryRun === true,
+						checkouts: checkoutReports,
+						operations,
 					} satisfies ExecutionWorkspace
 				}),
 

package/src/utils/command.ts

@@ -5,6 +5,7 @@ export interface BaseCommandOptions {
 	readonly silent?: boolean
 	readonly verbose?: boolean
 	readonly json?: boolean
+	readonly dryRun?: boolean
 	/** Whether this invocation may open prompts or selectors. */
 	readonly inputAllowed?: boolean
 	/**