@markjaquith/agency 2.7.0 → 2.7.2

package/cli.ts

@@ -240,7 +240,9 @@ const commands: Record<string, Command> = {
 				return
 			}
 			if (args.length > 1) {
-				throw new Error("Usage: agency work [<directory> | --epic <epic-id>]")
+				throw new Error(
+					"Usage: agency work [<directory-or-task-id> | --epic <epic-id>]",
+				)
 			}
 
 			await runCommand(
@@ -301,7 +303,7 @@ Commands:
   phase <subcommand>     Manage task phases
   archive <type>         Archive a work item
   task <subcommand>      Manage tasks
-  work [directory]       Work on an epic, task, or phase
+  work [directory|task]  Work on an epic, task, or phase
   pr create              Create a pull request for an execution unit
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase

package/package.json

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

package/src/commands/work.test.ts

@@ -46,12 +46,14 @@ interface HarnessOptions {
 	readonly phaseRecords?: readonly any[]
 	readonly outsideWorkbase?: boolean
 	readonly registeredWorkbases?: readonly string[]
+	readonly existingDirectories?: readonly string[]
 }
 
 const createHarness = (options: HarnessOptions = {}) => {
 	const events: string[] = []
 	const probes: string[] = []
 	const statusUpdates: string[] = []
+	const shownTasks: string[] = []
 	const progressUpdates: string[] = []
 	const launches: Array<{
 		cli: string
@@ -95,14 +97,16 @@ const createHarness = (options: HarnessOptions = {}) => {
 		list: () => Effect.succeed(options.epicRecords ?? []),
 	}
 	const tasks = {
-		show: (id: string) =>
-			Effect.succeed({
+		show: (id: string) => {
+			shownTasks.push(id)
+			return Effect.succeed({
 				id,
 				path: `/workbase/tasks/${id}/TASK.md`,
 				data: options.multiPhaseTasks?.includes(id)
 					? { phases: [] }
 					: { repo: "agency", branch: `task/${id}`, base: "main" },
-			}),
+			})
+		},
 		list: () => Effect.succeed(options.taskRecords ?? []),
 		setStatus: (id: string, status: string) => {
 			statusUpdates.push(`task:${id}:${status}`)
@@ -124,7 +128,8 @@ const createHarness = (options: HarnessOptions = {}) => {
 		},
 	}
 	const fs = {
-		isDirectory: () => Effect.succeed(true),
+		isDirectory: (path: string) =>
+			Effect.succeed(options.existingDirectories?.includes(path) ?? true),
 		runCommand: (args: readonly string[]) => {
 			const cli = args[1] as "opencode" | "claude"
 			events.push(`probe:${cli}`)
@@ -169,6 +174,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 		launches,
 		materializeOptions,
 		statusUpdates,
+		shownTasks,
 		progressUpdates,
 		run,
 	}
@@ -187,11 +193,44 @@ describe("work command", () => {
 		expect(harness.events).toEqual(["probe:opencode", "launch:opencode"])
 		expect(harness.launches[0]).toEqual({
 			cli: "opencode",
-			args: ["opencode", "--continue"],
+			args: [
+				"opencode",
+				"--continue",
+				"--prompt",
+				"Work on the epic. Read /workbase/epics/delivery/EPIC.md.",
+			],
 			cwd: "/workbase/epics/delivery",
 		})
 	})
 
+	test("resolves an existing positional path before treating it as a task ID", async () => {
+		const harness = createHarness({
+			existingDirectories: ["/workbase/tasks/delivery"],
+		})
+
+		await harness.run({
+			cwd: "/workbase/tasks/delivery",
+			directory: ".",
+			opencode: true,
+		})
+
+		expect(harness.shownTasks).toEqual(["delivery"])
+		expect(harness.launches[0]?.cwd).toBe(singlePhaseWorkspace.writablePath)
+	})
+
+	test("treats a positional value as a task ID when it is not a directory", async () => {
+		const harness = createHarness({ existingDirectories: [] })
+
+		await harness.run({
+			cwd: "/workbase",
+			directory: "delivery",
+			opencode: true,
+		})
+
+		expect(harness.shownTasks).toEqual(["delivery"])
+		expect(harness.launches[0]?.cwd).toBe(singlePhaseWorkspace.writablePath)
+	})
+
 	test("launches a multi-phase task agent without materializing", async () => {
 		const harness = createHarness({ multiPhaseTasks: ["delivery"] })
 
@@ -204,7 +243,12 @@ describe("work command", () => {
 		expect(harness.events).toEqual(["probe:opencode", "launch:opencode"])
 		expect(harness.launches[0]).toEqual({
 			cli: "opencode",
-			args: ["opencode", "--continue"],
+			args: [
+				"opencode",
+				"--continue",
+				"--prompt",
+				"Work on the task. Read /workbase/tasks/delivery/TASK.md.",
+			],
 			cwd: "/workbase/tasks/delivery",
 		})
 	})
@@ -223,7 +267,16 @@ describe("work command", () => {
 			"probe:opencode",
 			"launch:opencode",
 		])
-		expect(harness.launches[0]?.args).toEqual(["opencode", "--continue"])
+		expect(harness.launches[0]).toEqual({
+			cli: "opencode",
+			args: [
+				"opencode",
+				"--continue",
+				"--prompt",
+				"Start the task. Read /workbase/tasks/example/TASK.md and /workbase/tasks/example/phases/implementation/PHASE.md.",
+			],
+			cwd: multiPhaseWorkspace.writablePath,
+		})
 		expect(harness.statusUpdates).toEqual([
 			"phase:example:implementation:working",
 		])
@@ -239,7 +292,7 @@ describe("work command", () => {
 		})
 
 		expect(harness.events[0]).toBe("materialize")
-		expect(harness.launches[0]?.cwd).toBe("/workbase/tasks/example")
+		expect(harness.launches[0]?.cwd).toBe(singlePhaseWorkspace.writablePath)
 	})
 
 	test("selects a target with fzf when no directory is provided", async () => {
@@ -273,9 +326,7 @@ describe("work command", () => {
 			"probe:opencode",
 			"launch:opencode",
 		])
-		expect(harness.launches[0]?.cwd).toBe(
-			"/workbase/tasks/delivery/phases/build",
-		)
+		expect(harness.launches[0]?.cwd).toBe(multiPhaseWorkspace.writablePath)
 	})
 
 	test("selects a registered workbase when local discovery fails", async () => {
@@ -353,7 +404,7 @@ describe("work command", () => {
 		expect(harness.events).toEqual([])
 	})
 
-	test("launches OpenCode in the task directory and continues its session", async () => {
+	test("launches OpenCode in the writable checkout with explicit context", async () => {
 		const harness = createHarness()
 
 		await harness.run({ taskId: "example", opencode: true })
@@ -366,8 +417,13 @@ describe("work command", () => {
 		expect(harness.launches).toEqual([
 			{
 				cli: "opencode",
-				args: ["opencode", "--continue"],
-				cwd: "/workbase/tasks/example",
+				args: [
+					"opencode",
+					"--continue",
+					"--prompt",
+					"Start the task. Read /workbase/tasks/example/TASK.md.",
+				],
+				cwd: singlePhaseWorkspace.writablePath,
 			},
 		])
 		expect(harness.statusUpdates).toEqual(["task:example:working"])
@@ -377,7 +433,7 @@ describe("work command", () => {
 		])
 	})
 
-	test("continues OpenCode for a multi-phase task", async () => {
+	test("continues OpenCode with explicit task and phase context", async () => {
 		const harness = createHarness({ workspace: multiPhaseWorkspace })
 
 		await harness.run({
@@ -386,7 +442,16 @@ describe("work command", () => {
 			opencode: true,
 		})
 
-		expect(harness.launches[0]?.args).toEqual(["opencode", "--continue"])
+		expect(harness.launches[0]).toEqual({
+			cli: "opencode",
+			args: [
+				"opencode",
+				"--continue",
+				"--prompt",
+				"Start the task. Read /workbase/tasks/example/TASK.md and /workbase/tasks/example/phases/implementation/PHASE.md.",
+			],
+			cwd: multiPhaseWorkspace.writablePath,
+		})
 	})
 
 	test("automatically falls back to Claude", async () => {
@@ -398,7 +463,7 @@ describe("work command", () => {
 		expect(harness.launches[0]).toEqual({
 			cli: "claude",
 			args: ["claude", "Start the task. Read /workbase/tasks/example/TASK.md."],
-			cwd: "/workbase/tasks/example",
+			cwd: singlePhaseWorkspace.writablePath,
 		})
 	})
 
@@ -422,7 +487,7 @@ describe("work command", () => {
 		expect(harness.launches[0]).toEqual({
 			cli: "claude",
 			args: ["claude", "Start the task. Read /workbase/tasks/example/TASK.md."],
-			cwd: "/workbase/tasks/example",
+			cwd: singlePhaseWorkspace.writablePath,
 		})
 	})
 
@@ -459,7 +524,7 @@ describe("work command", () => {
 			verboseHarness.run({ taskId: "example", verbose: true }),
 		)
 		expect(verboseLogs).toEqual([
-			"Launching command: opencode --continue (cwd: /workbase/tasks/example)",
+			"Launching command: opencode --continue --prompt 'Start the task. Read /workbase/tasks/example/TASK.md.' (cwd: /workbase/tasks/example/code/agency)",
 		])
 		expect(verboseHarness.materializeOptions[0]?.verbose).toBe(true)
 

package/src/commands/work.ts

@@ -77,12 +77,13 @@ export const work = (
 		const phases = yield* PhaseService
 		const { log, verboseLog } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
-		const startPath = options.directory ? resolve(cwd, options.directory) : cwd
-		if (options.directory && !(yield* fs.isDirectory(startPath))) {
-			return yield* Effect.fail(
-				new Error(`Work directory does not exist: ${startPath}`),
-			)
-		}
+		const directoryPath = options.directory
+			? resolve(cwd, options.directory)
+			: undefined
+		const isDirectory = directoryPath
+			? yield* fs.isDirectory(directoryPath)
+			: false
+		const startPath = isDirectory && directoryPath ? directoryPath : cwd
 		const root = yield* resolveWorkbase(startPath, log, pickBase)
 		if (!root) return
 
@@ -108,7 +109,15 @@ export const work = (
 					multiPhase: "phases" in task.data,
 				}
 			}
-		} else if (options.directory) {
+		} else if (options.directory && !isDirectory) {
+			const task = yield* tasks.show(options.directory, root)
+			target = {
+				kind: "task",
+				taskId: task.id,
+				path: task.path,
+				multiPhase: "phases" in task.data,
+			}
+		} else if (directoryPath) {
 			const path = relative(root, startPath)
 			const parts =
 				!path || isAbsolute(path) || path.startsWith(`..${sep}`)
@@ -197,7 +206,7 @@ export const work = (
 			prompt = workspace.phasePath
 				? `Start the task. Read ${workspace.taskPath} and ${workspace.phasePath}.`
 				: `Start the task. Read ${workspace.taskPath}.`
-			launchPath = dirname(target.path)
+			launchPath = workspace.writablePath
 		}
 
 		const requested = options.claude ? "claude" : "opencode"
@@ -218,7 +227,8 @@ export const work = (
 			yield* tasks.setStatus(target.taskId, "working", root)
 		}
 
-		const args = cli === "opencode" ? ["--continue"] : [prompt]
+		const args =
+			cli === "opencode" ? ["--continue", "--prompt", prompt] : [prompt]
 		verboseLog(
 			`Launching command: ${formatCommand([cli, ...args])} (cwd: ${launchPath})`,
 		)
@@ -226,11 +236,12 @@ export const work = (
 	})
 
 export const help = `
-Usage: agency work [<directory> | --epic <epic-id>]
+Usage: agency work [<directory-or-task-id> | --epic <epic-id>]
 
 Launch an agent for an epic, task, or phase. With no directory, select one
-with fzf. Use '.' for the current directory. Outside a workbase, select a
-registered workbase first.
+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.
 
 Options:
   --epic <id>         Work on an epic

package/src/services/PullRequestService.test.ts

@@ -314,6 +314,20 @@ process.exit(${exitCode})
 		expect(await Bun.file(ghCallPath).exists()).toBe(false)
 	})
 
+	test("blocks PR creation when workbase validation fails", async () => {
+		await createTask()
+		await materialize()
+		await mkdir(join(root, "tasks", "missing-document"), { recursive: true })
+		await writeFakeGh({ stdout: "https://github.com/example/agency/pull/45" })
+
+		await expect(createPullRequest()).rejects.toThrow(
+			"Required document is missing",
+		)
+
+		await expectRemoteBranch("task/example", false)
+		expect(await Bun.file(ghCallPath).exists()).toBe(false)
+	})
+
 	test("reports push failure and does not invoke gh", async () => {
 		await createTask()
 		await materialize()

package/src/services/WorktreeService.test.ts

@@ -85,7 +85,7 @@ describe("WorktreeService", () => {
 		expect(new TextDecoder().decode(branch.stdout).trim()).toBe("task/example")
 	})
 
-	test("does not fetch origins for existing worktrees", async () => {
+	test("does not fetch the origin for an existing writable worktree", async () => {
 		await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>
@@ -94,7 +94,6 @@ describe("WorktreeService", () => {
 							id: "existing",
 							ticketUrl: "https://example.com/task",
 							repo: "agency",
-							repos: [{ repo: "effect", ref: "main" }],
 							branch: "task/existing",
 							base: "main",
 						},
@@ -114,6 +113,50 @@ 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),
+					),
+				),
+			),
+		).resolves.toMatchObject({ repo: "agency" })
+	})
+
+	test("reuses an immutable reference checkout without fetching", async () => {
+		const commit = new TextDecoder()
+			.decode(
+				Bun.spawnSync(
+					["git", "-C", join(root, "repos/effect"), "rev-parse", "main"],
+					{ stdout: "pipe" },
+				).stdout,
+			)
+			.trim()
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "immutable-reference",
+							ticketUrl: "https://example.com/task",
+							repo: "agency",
+							repos: [{ repo: "effect", ref: commit }],
+							branch: "task/immutable-reference",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("immutable-reference", undefined, root),
+				),
+			),
+		)
 		await git(
 			["remote", "set-url", "origin", join(root, "missing")],
 			join(root, "repos/effect"),
@@ -123,11 +166,44 @@ describe("WorktreeService", () => {
 			runTestEffect(
 				WorktreeService.pipe(
 					Effect.flatMap((service) =>
-						service.materialize("existing", undefined, root),
+						service.materialize("immutable-reference", undefined, root),
 					),
 				),
 			),
-		).resolves.toMatchObject({ repo: "agency" })
+		).resolves.toMatchObject({ repos: [{ repo: "effect", ref: commit }] })
+	})
+
+	test("stops before materializing when workbase validation fails", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "valid-target",
+							ticketUrl: "https://example.com/task",
+							repo: "agency",
+							branch: "task/valid-target",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await mkdir(join(root, "tasks", "missing-document"), { recursive: true })
+
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.materialize("valid-target", undefined, root),
+					),
+				),
+			),
+		).rejects.toThrow("Required document is missing")
+		expect(
+			await Bun.file(join(root, "tasks", "valid-target", "code")).exists(),
+		).toBe(false)
 	})
 
 	test("uses a configured worktree creation command", async () => {
@@ -330,7 +406,7 @@ describe("WorktreeService", () => {
 				repo: "missing",
 				base: "main",
 				config: { version: 2 },
-				expected: "Repository alias 'missing' does not exist",
+				expected: "Unknown repository alias 'missing'",
 			},
 			{
 				id: "bad-base",
@@ -392,6 +468,7 @@ pr: null
 					),
 				),
 			).rejects.toThrow(fixture.expected)
+			await rm(taskDirectory, { recursive: true, force: true })
 		}
 	})
 
@@ -561,7 +638,7 @@ pr: null
 		).rejects.toThrow("is not registered to branch 'task/expected'")
 	})
 
-	test("rejects a reused reference checkout after its ref advances", async () => {
+	test("fetches a moving ref before checking a reused reference checkout", async () => {
 		await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>
@@ -570,7 +647,7 @@ pr: null
 							id: "pinned-reference",
 							ticketUrl: "https://example.com/task",
 							repo: "agency",
-							repos: [{ repo: "effect", ref: "main" }],
+							repos: [{ repo: "effect", ref: "origin/main" }],
 							branch: "task/pinned-reference",
 							base: "main",
 						},
@@ -590,7 +667,6 @@ pr: null
 		await Bun.write(join(source, "README.md"), "updated\n")
 		await git(["add", "README.md"], source)
 		await git(["-c", "commit.gpgsign=false", "commit", "-m", "update"], source)
-		await git(["push", join(root, "repos/effect"), "main"], source)
 
 		await expect(
 			runTestEffect(
@@ -600,7 +676,7 @@ pr: null
 					),
 				),
 			),
-		).rejects.toThrow("does not match reference 'main'")
+		).rejects.toThrow("does not match reference 'origin/main'")
 	})
 
 	test("rejects a reference checkout attached to a branch", async () => {

package/src/services/WorktreeService.ts

@@ -60,6 +60,11 @@ const formatCommand = (args: readonly string[]) =>
 		)
 		.join(" ")
 
+const isCommitId = (ref: string) => /^[0-9a-f]{40,64}$/i.test(ref)
+
+const originRef = (ref: string) =>
+	ref.replace(/^refs\/remotes\/origin\//, "").replace(/^origin\//, "")
+
 export class WorktreeService extends Effect.Service<WorktreeService>()(
 	"WorktreeService",
 	{
@@ -80,12 +85,10 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						options.verbose === true && !options.silent && !options.json
 					const { root, config } = yield* workbase.loadConfig(startPath)
 					const report = yield* workbase.validate(root)
-					const ownershipIssue = report.issues.find((issue) =>
-						issue.message.startsWith("Writable branch "),
-					)
-					if (ownershipIssue) {
+					const validationIssue = report.issues[0]
+					if (validationIssue) {
 						return yield* new WorktreeError({
-							message: `${ownershipIssue.path}: ${ownershipIssue.message}`,
+							message: `${validationIssue.path}: ${validationIssue.message}`,
 						})
 					}
 					const task = yield* tasks.show(taskId, root)
@@ -136,23 +139,32 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 							})
 						}
 
-						const fetchOrigin = Effect.gen(function* () {
-							const remote = yield* fs.runCommand(
-								["git", "-C", repositoryPath, "remote", "get-url", "origin"],
-								{ captureOutput: true },
-							)
-							if (remote.exitCode !== 0) return
+						const fetchOrigin = (ref?: string) =>
+							Effect.gen(function* () {
+								const remote = yield* fs.runCommand(
+									["git", "-C", repositoryPath, "remote", "get-url", "origin"],
+									{ captureOutput: true },
+								)
+								if (remote.exitCode !== 0) return false
 
-							const fetch = yield* fs.runCommand(
-								["git", "-C", repositoryPath, "fetch", "origin"],
-								{ captureOutput: true },
-							)
-							if (fetch.exitCode !== 0) {
-								return yield* new WorktreeError({
-									message: `Failed to fetch '${alias}': ${fetch.stderr}`,
-								})
-							}
-						})
+								const fetch = yield* fs.runCommand(
+									[
+										"git",
+										"-C",
+										repositoryPath,
+										"fetch",
+										"origin",
+										...(ref ? [ref] : []),
+									],
+									{ captureOutput: true },
+								)
+								if (fetch.exitCode !== 0) {
+									return yield* new WorktreeError({
+										message: `Failed to fetch '${alias}': ${fetch.stderr}`,
+									})
+								}
+								return true
+							})
 
 						const listed = yield* fs.runCommand(
 							[
@@ -210,7 +222,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									message: `Worktree registry contains a missing checkout at ${checkoutPath}`,
 								})
 							}
-							yield* fetchOrigin
+							yield* fetchOrigin()
 
 							let args: string[]
 							let env: Record<string, string> | undefined
@@ -297,6 +309,10 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								})
 							}
 						} else {
+							const fetched = isCommitId(checkout.ref)
+								? false
+								: yield* fetchOrigin(originRef(checkout.ref))
+							const resolvedRefName = fetched ? "FETCH_HEAD" : checkout.ref
 							const resolvedRef = yield* fs.runCommand(
 								[
 									"git",
@@ -304,7 +320,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									repositoryPath,
 									"rev-parse",
 									"--verify",
-									`${checkout.ref}^{commit}`,
+									`${resolvedRefName}^{commit}`,
 								],
 								{ captureOutput: true },
 							)
@@ -344,7 +360,6 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									message: `Worktree registry contains a missing checkout at ${checkoutPath}`,
 								})
 							}
-							yield* fetchOrigin
 							const result = yield* fs.runCommand(
 								[
 									"git",