@markjaquith/agency 2.60.0 → 2.61.1

package/src/services/LifecycleTransaction.ts

@@ -25,6 +25,18 @@ export interface TransactionStep {
 	readonly manualRecovery?: string
 }
 
+export const pathMustNotExistStep = (
+	root: string,
+	path: string,
+	message: string,
+): TransactionStep => ({
+	label: `verify ${relative(root, path)} is available`,
+	preflight: async () => {
+		if (await exists(path)) throw new Error(message)
+	},
+	apply: async () => {},
+})
+
 interface DocumentWrite {
 	readonly path: string
 	readonly content: string

package/src/services/PhaseService.ts

@@ -249,6 +249,8 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 								? { description: task.data.description }
 								: {}),
 							...(task.data.epic ? { epic: task.data.epic } : {}),
+							...(task.data.purpose ? { purpose: task.data.purpose } : {}),
+							...(task.data.handoff ? { handoff: task.data.handoff } : {}),
 							phases: [
 								{ id: firstPhaseId! },
 								{

package/src/services/PullRequestService.ts

@@ -239,7 +239,15 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 							})
 							if (!url)
 								throw new Error("GitHub CLI did not return a pull request URL")
-							return { ...normalizePullRequestRecord(url), draft }
+							const normalized = normalizePullRequestRecord(url)
+							return {
+								...normalized,
+								headRepository: repository,
+								headBranch: execution.branch,
+								baseRepository: normalized.repository,
+								baseBranch: execution.base,
+								draft,
+							}
 						},
 						catch: (cause) =>
 							new PullRequestError({
@@ -249,7 +257,8 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 					if (
 						config.delivery &&
 						(record.provider !== config.delivery.provider ||
-							record.repository.toLowerCase() !== repository.toLowerCase())
+							(record.headRepository ?? record.repository).toLowerCase() !==
+								repository.toLowerCase())
 					) {
 						return yield* new PullRequestError({
 							message:

package/src/services/SyncService.test.ts

@@ -66,12 +66,12 @@ case "$*" in
 esac
 if [ "$2" = "view" ]; then
 cat <<'JSON'
-{"number":42,"state":"MERGED","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","url":"https://github.com/example/agency/pull/42","mergedAt":"2100-01-01T00:00:00Z","mergeCommit":{"oid":"abc"},"mergeable":"MERGEABLE"}
+{"number":42,"state":"MERGED","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","headRepository":{"nameWithOwner":"example/agency"},"baseRepository":{"nameWithOwner":"example/agency"},"url":"https://github.com/example/agency/pull/42","mergedAt":"2100-01-01T00:00:00Z","mergeCommit":{"oid":"abc"},"mergeable":"MERGEABLE"}
 JSON
 exit 0
 fi
 cat <<'JSON'
-[{"number":42,"state":"MERGED","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","url":"https://github.com/example/agency/pull/42","mergedAt":"2100-01-01T00:00:00Z","mergeCommit":{"oid":"abc"},"mergeable":"MERGEABLE"}]
+[{"number":42,"state":"MERGED","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","headRepository":{"nameWithOwner":"example/agency"},"baseRepository":{"nameWithOwner":"example/agency"},"url":"https://github.com/example/agency/pull/42","mergedAt":"2100-01-01T00:00:00Z","mergeCommit":{"oid":"abc"},"mergeable":"MERGEABLE"}]
 JSON
 `,
 		)
@@ -307,6 +307,10 @@ pr: null
 				state: "merged",
 				draft: false,
 				merged: true,
+				headRepository: "example/agency",
+				headBranch: "feat/example",
+				baseRepository: "example/agency",
+				baseBranch: "main",
 				mergeable: true,
 			},
 			claim: { state: "released", sessionId: "session-1" },
@@ -357,7 +361,7 @@ pr: null
 			join(root, "bin", "gh"),
 			`#!/bin/sh
 cat <<'JSON'
-{"number":42,"state":"OPEN","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","url":"https://github.com/example/agency/pull/42","mergedAt":null,"mergeCommit":null,"mergeable":"CONFLICTING"}
+{"number":42,"state":"OPEN","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","headRepository":{"nameWithOwner":"example/agency"},"baseRepository":{"nameWithOwner":"example/agency"},"url":"https://github.com/example/agency/pull/42","mergedAt":null,"mergeCommit":null,"mergeable":"CONFLICTING"}
 JSON
 `,
 		)
@@ -747,6 +751,89 @@ process.stdout.write(${JSON.stringify(JSON.stringify(record))})
 		expect(task.data).toMatchObject({ status: "open" })
 	})
 
+	test("reconciles a merged upstream PR whose head is the writable fork", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "forked",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/polish-readme",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("forked", undefined, root),
+				),
+			),
+		)
+		await git(
+			["remote", "set-url", "origin", "git@github.com:markjaquith/Pasted.git"],
+			join(root, "repos/agency"),
+		)
+		await runTestEffect(
+			PullRequestService.pipe(
+				Effect.flatMap((service) =>
+					service.setUrl(
+						"forked",
+						undefined,
+						"https://github.com/getpasted/pasted/pull/17",
+						root,
+					),
+				),
+			),
+		)
+		await Bun.write(
+			join(root, "bin", "gh"),
+			`#!/bin/sh
+cat <<'JSON'
+{"number":17,"state":"MERGED","title":"Polish README","isDraft":false,"headRefName":"task/polish-readme","baseRefName":"main","headRepository":{"nameWithOwner":"markjaquith/Pasted"},"baseRepository":{"nameWithOwner":"getpasted/pasted"},"url":"https://github.com/getpasted/pasted/pull/17","mergedAt":"2026-08-11T00:00:00Z","mergeCommit":{"oid":"241d45da1115ef685c91a5e6882d118c16801550"},"mergeable":"UNKNOWN"}
+JSON
+`,
+		)
+		await chmod(join(root, "bin", "gh"), 0o755)
+
+		const applied = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({ cwd: root, apply: true }),
+				),
+			),
+		)
+		expect(
+			applied.unresolved.filter((notice) => notice.target === "task:forked"),
+		).toEqual([])
+		expect(applied.changes.map((change) => change.kind)).toEqual([
+			"record-pr",
+			"mark-done",
+		])
+		const task = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("forked", root)),
+			),
+		)
+		expect(task.data).toMatchObject({
+			status: "done",
+			pr: {
+				repository: "getpasted/pasted",
+				headRepository: "markjaquith/Pasted",
+				headBranch: "task/polish-readme",
+				baseRepository: "getpasted/pasted",
+				baseBranch: "main",
+				state: "merged",
+				merged: true,
+			},
+		})
+	})
+
 	test("leaves non-PR completion unchanged when a matching PR is discoverable", async () => {
 		await runTestEffect(
 			TaskService.pipe(

package/src/services/SyncService.ts

@@ -349,7 +349,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 											"view",
 											existing.url,
 											"--json",
-											"number,state,title,isDraft,headRefName,baseRefName,url,mergedAt,mergeCommit,mergeable",
+											"number,state,title,isDraft,headRefName,baseRefName,headRepository,baseRepository,url,mergedAt,mergeCommit,mergeable",
 										],
 										{
 											cwd: repositoryPath,
@@ -372,7 +372,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 											"--state",
 											"all",
 											"--json",
-											"number,state,title,isDraft,headRefName,baseRefName,url,mergedAt,mergeCommit,mergeable",
+											"number,state,title,isDraft,headRefName,baseRefName,headRepository,baseRepository,url,mergedAt,mergeCommit,mergeable",
 										],
 										{
 											cwd: repositoryPath,
@@ -773,19 +773,6 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 					const query = prQueries.get(record.key)!
 					const { remoteUrl, remoteRepository } = query
 
-					if (
-						existing &&
-						remoteRepository.toLowerCase() !== existing.repository.toLowerCase()
-					) {
-						prConflict = true
-						unresolved.push({
-							kind: "pr-repository-conflict",
-							target: record.key,
-							message: `Recorded PR repository does not match writable repository remote '${remoteName}'`,
-							action: "Correct the configured remote or recorded PR",
-						})
-					}
-
 					if (config.delivery && !remoteUrl) {
 						warnings.push({
 							kind: "delivery-remote-unavailable",
@@ -812,8 +799,9 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 							} else if (
 								parsed.right &&
 								(parsed.right.provider !== config.delivery.provider ||
-									parsed.right.repository.toLowerCase() !==
-										remoteRepository.toLowerCase())
+									(
+										parsed.right.headRepository ?? parsed.right.repository
+									).toLowerCase() !== remoteRepository.toLowerCase())
 							) {
 								if (parsed.right) {
 									prConflict = true
@@ -850,14 +838,18 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 							current = recordFromGitHubJson(detail)
 							pr = { ...detail, ...current }
 							if (
-								detail.headRefName !== data.branch ||
-								detail.baseRefName !== data.base
+								current.headRepository?.toLowerCase() !==
+									remoteRepository.toLowerCase() ||
+								current.headBranch !== data.branch ||
+								current.baseRepository?.toLowerCase() !==
+									current.repository.toLowerCase() ||
+								current.baseBranch !== data.base
 							) {
 								prConflict = true
 								unresolved.push({
-									kind: "pr-branch-conflict",
+									kind: "pr-repository-conflict",
 									target: record.key,
-									message: `Recorded PR branches do not match '${data.branch}' -> '${data.base}'`,
+									message: `Recorded PR head does not match '${remoteRepository}:${data.branch}' or base '${current.repository}:${data.base}'`,
 									action: "Correct the declaration or recorded PR URL",
 								})
 							}
@@ -883,6 +875,20 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 							if (matches.length === 1) {
 								current = recordFromGitHubJson(matches[0]!)
 								pr = { ...matches[0], ...current }
+								if (
+									current.headRepository?.toLowerCase() !==
+										remoteRepository.toLowerCase() ||
+									current.baseRepository?.toLowerCase() !==
+										current.repository.toLowerCase()
+								) {
+									prConflict = true
+									unresolved.push({
+										kind: "pr-repository-conflict",
+										target: record.key,
+										message: `Discovered PR repositories do not match writable repository '${remoteRepository}' and base '${current.repository}'`,
+										action: "Record the authoritative PR URL manually",
+									})
+								}
 							} else if (matches.length > 1) {
 								unresolved.push({
 									kind: "multiple-prs",

package/src/services/TaskPhaseService.test.ts

@@ -116,6 +116,234 @@ describe("task and phase services", () => {
 		expect(epic.data.tasks).toEqual([])
 	})
 
+	test("creates revision-bound task and phase investigation handoffs", async () => {
+		const source = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "investigate",
+							ticketUrl: null,
+							multiPhase: true,
+							purpose: "investigation",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const phase = await runTestEffect(
+			PhaseService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							taskId: "investigate",
+							id: "evidence",
+							repo: "agency",
+							branch: "task/investigate-evidence",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const currentSource = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("investigate", root)),
+			),
+		)
+		const sourceContent = await Bun.file(source.path).text()
+		const phaseContent = await Bun.file(phase.path).text()
+
+		const fromTask = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.handoff(
+						{
+							sourceTaskId: "investigate",
+							id: "implement-task",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/implement-task",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const fromPhase = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.handoff(
+						{
+							sourceTaskId: "investigate",
+							sourcePhaseId: "evidence",
+							id: "implement-phase",
+							ticketUrl: null,
+							repo: "effect",
+							branch: "task/implement-phase",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+
+		expect(fromTask.source).toEqual({
+			selector: "task/investigate",
+			documentPath: source.path,
+			revision: currentSource.revision,
+		})
+		expect(fromPhase.source).toEqual({
+			selector: "phase/investigate/evidence",
+			documentPath: phase.path,
+			revision: phase.revision,
+		})
+		expect(fromPhase.validation.valid).toBe(true)
+		expect(fromPhase.worktreePrepare.command).toEqual([
+			"agency",
+			"worktree",
+			"prepare",
+			"implement-phase",
+		])
+		expect(await Bun.file(source.path).text()).toBe(sourceContent)
+		expect(await Bun.file(phase.path).text()).toBe(phaseContent)
+		expect(
+			await Bun.file(join(root, "tasks/implement-phase/code")).exists(),
+		).toBe(false)
+
+		const created = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("implement-phase", root)),
+			),
+		)
+		expect(created.data).toMatchObject({
+			purpose: "implementation",
+			handoff: {
+				source: {
+					kind: "phase",
+					taskId: "investigate",
+					phaseId: "evidence",
+				},
+				sourceRevision: phase.revision,
+			},
+			status: "open",
+		})
+		await Bun.write(
+			phase.path,
+			phaseContent.replace(
+				"Describe the phase outcome.",
+				"Recorded evidence remains stale-safe.",
+			),
+		)
+		const staleSource = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("implement-phase", root)),
+			),
+		)
+		expect(staleSource.data.handoff?.sourceRevision).toBe(phase.revision)
+
+		await expect(
+			runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.handoff(
+							{
+								sourceTaskId: "investigate",
+								id: "implement-task",
+								ticketUrl: null,
+								repo: "agency",
+								branch: "task/duplicate",
+								base: "main",
+							},
+							root,
+						),
+					),
+				),
+			),
+		).rejects.toThrow("already exists")
+
+		await mkdir(join(root, "archive/tasks/reserved"), { recursive: true })
+		await expect(
+			runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.handoff(
+							{
+								sourceTaskId: "investigate",
+								id: "reserved",
+								ticketUrl: null,
+								repo: "agency",
+								branch: "task/reserved",
+								base: "main",
+							},
+							root,
+						),
+					),
+				),
+			),
+		).rejects.toThrow("explicit creation requires a different ID")
+	})
+
+	test("rolls back handoff creation when a source revision is stale", async () => {
+		const source = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "stale-investigation",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/stale-investigation",
+							base: "main",
+							purpose: "investigation",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const staleRevision = source.revision
+		await Bun.write(
+			source.path,
+			`${source.content}\nChanged after inspection.\n`,
+		)
+
+		await expect(
+			runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.create(
+							{
+								id: "stale-implementation",
+								ticketUrl: null,
+								repo: "effect",
+								branch: "task/stale-implementation",
+								base: "main",
+								purpose: "implementation",
+								handoff: {
+									source: {
+										kind: "task",
+										taskId: "stale-investigation",
+									},
+									sourceRevision: staleRevision,
+								},
+								preconditions: [{ path: source.path, revision: staleRevision }],
+							},
+							root,
+						),
+					),
+				),
+			),
+		).rejects.toThrow("Revision conflict")
+		expect(
+			await Bun.file(join(root, "tasks/stale-implementation/TASK.md")).exists(),
+		).toBe(false)
+	})
+
 	test("creates and sequences phases on a multi-phase task", async () => {
 		await runTestEffect(
 			TaskService.pipe(
@@ -192,6 +420,11 @@ describe("task and phase services", () => {
 							repos: [{ repo: "effect", ref: "main" }],
 							branch: "task/single",
 							base: "main",
+							purpose: "implementation",
+							handoff: {
+								source: { kind: "task", taskId: "investigation" },
+								sourceRevision: "a".repeat(64),
+							},
 						},
 						root,
 					),
@@ -256,6 +489,11 @@ describe("task and phase services", () => {
 		expect(task.data).toEqual({
 			ticketUrl: "https://example.com/task",
 			description: "Deliver the complete task.",
+			purpose: "implementation",
+			handoff: {
+				source: { kind: "task", taskId: "investigation" },
+				sourceRevision: "a".repeat(64),
+			},
 			phases: [
 				{ id: "implementation" },
 				{ id: "extra", dependsOn: ["implementation"] },