@markjaquith/agency 2.7.1 → 2.7.2

package/package.json

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

package/src/commands/work.test.ts

@@ -193,7 +193,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 epic. Read /workbase/epics/delivery/EPIC.md.",
+			],
 			cwd: "/workbase/epics/delivery",
 		})
 	})
@@ -210,7 +215,7 @@ describe("work command", () => {
 		})
 
 		expect(harness.shownTasks).toEqual(["delivery"])
-		expect(harness.launches[0]?.cwd).toBe("/workbase/tasks/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 () => {
@@ -223,7 +228,7 @@ describe("work command", () => {
 		})
 
 		expect(harness.shownTasks).toEqual(["delivery"])
-		expect(harness.launches[0]?.cwd).toBe("/workbase/tasks/delivery")
+		expect(harness.launches[0]?.cwd).toBe(singlePhaseWorkspace.writablePath)
 	})
 
 	test("launches a multi-phase task agent without materializing", async () => {
@@ -238,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",
 		})
 	})
@@ -257,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",
 		])
@@ -273,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 () => {
@@ -307,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 () => {
@@ -387,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 })
@@ -400,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"])
@@ -411,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({
@@ -420,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 () => {
@@ -432,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,
 		})
 	})
 
@@ -456,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,
 		})
 	})
 
@@ -493,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

@@ -206,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"
@@ -227,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})`,
 		)

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",