@markjaquith/agency 2.71.23 → 2.71.24

package/README.md

@@ -269,6 +269,11 @@ Custom commands own writable branch creation. Agency checks for conflicting
 worktrees first, invokes the command only when the branch is not checked out,
 and verifies that `{worktree}` exists afterward.
 
+Agency also reconciles known tool-owned artifacts such as Worktrunk's
+`.worktree.lock` into each managed worktree's local Git exclude file. This keeps
+new and existing managed worktrees clean without changing the repository's
+tracked ignore configuration or overwriting user-maintained local excludes.
+
 The configured command applies only to the writable checkout of a Git workbase.
 Supplemental read-only repositories remain detached Git worktrees at their
 declared refs so they do not acquire writable branches. Jj workbases always use

package/package.json

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

package/src/services/PullRequestService.test.ts

@@ -605,14 +605,14 @@ process.stdout.write(${JSON.stringify(JSON.stringify(providerRecord))})
 		expect("pr" in task.data && task.data.pr).toBeNull()
 	})
 
-	test("reports git status failure before push or gh", async () => {
+	test("reports invalid reused Git checkout before push or gh", async () => {
 		await createTask()
 		const workspace = await materialize()
 		await rm(join(workspace.writablePath!, ".git"))
 		await writeFakeGh({ stdout: "https://github.com/example/agency/pull/48" })
 
 		await expect(createPullRequest()).rejects.toThrow(
-			"Failed to inspect worktree status",
+			"Failed to locate local excludes",
 		)
 
 		await expectRemoteBranch("task/example", false)

package/src/services/SyncService.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test"
 import { Effect } from "effect"
 import { chmod, mkdir, rm } from "node:fs/promises"
 import { join } from "node:path"
@@ -1115,6 +1115,54 @@ exec ${JSON.stringify(realGit)} "$@"
 		)
 	})
 
+	test("reuses documents parsed during validation", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "single-read",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/single-read",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("single-read", "done", root, {
+						summary: "Completed without a pull request",
+					}),
+				),
+			),
+		)
+		const taskPath = join(root, "tasks/single-read/TASK.md")
+		const taskContent = await Bun.file(taskPath).text()
+		const originalFile = Bun.file
+		let reads = 0
+		const fileSpy = spyOn(Bun, "file").mockImplementation(((path: string) => {
+			if (path === taskPath) reads += 1
+			return path === taskPath ? new Blob([taskContent]) : originalFile(path)
+		}) as typeof Bun.file)
+
+		try {
+			await runTestEffect(
+				SyncService.pipe(
+					Effect.flatMap((service) => service.reconcile({ cwd: root })),
+				),
+			)
+		} finally {
+			fileSpy.mockRestore()
+		}
+
+		expect(reads).toBe(1)
+	})
+
 	test("queries pull request providers concurrently", async () => {
 		for (const id of ["first", "second", "third"]) {
 			await runTestEffect(

package/src/services/SyncService.ts

@@ -1,6 +1,5 @@
 import { Data, Effect, Either } from "effect"
 import { dirname, join, resolve } from "node:path"
-import { documentRevision } from "../workbase/document-revision"
 import type {
 	ClaimRecord,
 	PhaseFrontmatter,
@@ -17,8 +16,6 @@ import {
 } from "../workbase/delivery-command"
 import { ClaimService } from "./ClaimService"
 import { FileSystemService } from "./FileSystemService"
-import { PhaseService } from "./PhaseService"
-import { TaskService } from "./TaskService"
 import { WorkbaseService } from "./WorkbaseService"
 import { WorktreeService } from "./WorktreeService"
 import {
@@ -217,15 +214,15 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 			Effect.gen(function* () {
 				const fs = yield* FileSystemService
 				const workbase = yield* WorkbaseService
-				const tasks = yield* TaskService
-				const phases = yield* PhaseService
 				const worktrees = yield* WorktreeService
 				const claims = yield* ClaimService
 				const repositories = yield* RepositoryService
 				const versionControl = yield* VersionControlService
 				const { root, config } = yield* workbase.loadConfig(options.cwd)
 				const backend = yield* versionControl.forWorkbase(root)
-				const validation = yield* workbase.validate(root)
+				const validation = yield* workbase.validate(root, {
+					includeDocuments: true,
+				})
 				if (!validation.valid) {
 					return yield* new SyncError({
 						message: validation.issues
@@ -238,7 +235,8 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 						message: "A phase sync scope requires a task ID",
 					})
 				}
-				const allTaskRecords = yield* tasks.list(root)
+				const documents = validation.documents!
+				const allTaskRecords = documents.tasks
 				const taskRecords = options.taskId
 					? allTaskRecords.filter((task) => task.id === options.taskId)
 					: allTaskRecords
@@ -250,14 +248,14 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 				const records: ExecutionRecord[] = []
 				for (const task of taskRecords) {
 					if ("phases" in task.data) {
-						for (const phase of yield* phases.list(task.id, root)) {
+						for (const phase of documents.phasesByTask.get(task.id) ?? []) {
 							if (options.phaseId && phase.id !== options.phaseId) continue
 							records.push({
 								key: `phase:${task.id}/${phase.id}`,
 								taskId: task.id,
 								phaseId: phase.id,
 								path: phase.path,
-								revision: documentRevision(phase.content),
+								revision: phase.revision,
 								data: phase.data,
 							})
 						}
@@ -266,7 +264,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 							key: `task:${task.id}`,
 							taskId: task.id,
 							path: task.path,
-							revision: documentRevision(task.content),
+							revision: task.revision,
 							data: task.data,
 						})
 					}

package/src/services/WorkbaseService.ts

@@ -27,6 +27,7 @@ import { validateAgents } from "../workbase/agent-command"
 import { findDependencyCycles } from "../workbase/dependency-graph"
 import { validateDelivery } from "../workbase/delivery-command"
 import { preferredVersionControl } from "../workbase/version-control"
+import { documentRevision } from "../workbase/document-revision"
 
 class WorkbaseNotFoundError extends Data.TaggedError("WorkbaseNotFoundError")<{
 	readonly message: string
@@ -62,6 +63,8 @@ export interface ValidationReport {
 interface DocumentRecord<T> {
 	readonly id: string
 	readonly path: string
+	readonly content: string
+	readonly revision: string
 	readonly data: T
 }
 
@@ -729,8 +732,9 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 								issue(path, "Required document is missing")
 								return null
 							}
+							const documentContent = content.value
 							const parsed = yield* Effect.either(
-								parseFrontmatter(content.value, path),
+								parseFrontmatter(documentContent, path),
 							)
 							if (Either.isLeft(parsed)) {
 								issue(path, parsed.left.message)
@@ -742,7 +746,11 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 								issue(path, decoded.error)
 								return null
 							}
-							return decoded.value
+							return {
+								content: documentContent,
+								revision: documentRevision(documentContent),
+								data: decoded.value,
+							}
 						})
 
 					const epicIds = yield* readDirectories(join(root, "epics"))
@@ -750,8 +758,8 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 						epicIds.map((id) =>
 							Effect.gen(function* () {
 								const path = join(root, "epics", id, "EPIC.md")
-								const data = yield* readDocument(path, EpicFrontmatter)
-								return data ? { id, path, data } : null
+								const document = yield* readDocument(path, EpicFrontmatter)
+								return document ? { id, path, ...document } : null
 							}),
 						),
 						{ concurrency: validationConcurrency },
@@ -766,7 +774,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 							Effect.gen(function* () {
 								const taskPath = join(root, "tasks", id)
 								const path = join(taskPath, "TASK.md")
-								const data = yield* readDocument(path, TaskFrontmatter)
+								const document = yield* readDocument(path, TaskFrontmatter)
 								const phaseIds = yield* readDirectories(
 									join(taskPath, "phases"),
 								)
@@ -787,7 +795,12 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 												PhaseFrontmatter,
 											)
 											return phase
-												? { id: phaseId, path: phasePath, data: phase }
+												? {
+														id: phaseId,
+														taskId: id,
+														path: phasePath,
+														...phase,
+													}
 												: null
 										}),
 									),
@@ -795,7 +808,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 								)
 								return {
 									id,
-									task: data ? { id, path, data } : null,
+									task: document ? { id, path, ...document } : null,
 									phases: taskPhases,
 								}
 							}),

package/src/services/WorktreeService.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
 import { chmod, mkdir, realpath, rename, rm, stat } from "node:fs/promises"
-import { join } from "node:path"
+import { join, resolve } from "node:path"
 import {
 	captureErrors,
 	cleanupTempDir,
@@ -23,6 +23,21 @@ const git = async (args: string[], cwd?: string) => {
 		throw new Error(await new Response(process.stderr).text())
 }
 
+const gitOutput = async (args: string[], cwd?: string) => {
+	const process = Bun.spawn(["git", ...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	})
+	const [exitCode, stdout, stderr] = await Promise.all([
+		process.exited,
+		new Response(process.stdout).text(),
+		new Response(process.stderr).text(),
+	])
+	if (exitCode !== 0) throw new Error(stderr)
+	return stdout.trim()
+}
+
 const jj = async (args: string[], cwd?: string) => {
 	const process = Bun.spawn(["jj", ...args], {
 		cwd,
@@ -117,6 +132,63 @@ describe("WorktreeService", () => {
 			{ stdout: "pipe" },
 		)
 		expect(new TextDecoder().decode(branch.stdout).trim()).toBe("task/example")
+		for (const checkout of [
+			workspace.writablePath!,
+			join(workspace.codePath, "effect"),
+		]) {
+			await Bun.write(join(checkout, ".worktree.lock"), "")
+			expect(await gitOutput(["status", "--porcelain"], checkout)).toBe("")
+		}
+	})
+
+	test("reconciles local worktree excludes without overwriting user entries", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "existing-ignore",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/existing-ignore",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const first = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("existing-ignore", undefined, root),
+				),
+			),
+		)
+		const checkout = first.writablePath!
+		const excludePath = resolve(
+			checkout,
+			await gitOutput(["rev-parse", "--git-path", "info/exclude"], checkout),
+		)
+		await Bun.write(excludePath, "user-entry")
+
+		await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("existing-ignore", undefined, root),
+				),
+			),
+		)
+		await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("existing-ignore", undefined, root),
+				),
+			),
+		)
+		const excludes = await Bun.file(excludePath).text()
+		expect(excludes).toBe("user-entry\n/.worktree.lock\n")
+		expect(excludes.match(/^\/\.worktree\.lock$/gm)).toHaveLength(1)
 	})
 
 	test("runs repository hooks for new writable and reference checkouts", async () => {
@@ -2720,5 +2792,14 @@ pr: null
 		expect(
 			await Bun.file(join(workspace.writablePath!, "README.md")).text(),
 		).toBe("example\n")
+		expect(
+			await gitOutput(["status", "--porcelain"], workspace.writablePath!),
+		).toBe("")
+		expect(
+			await gitOutput(
+				["check-ignore", "--no-index", ".worktree.lock"],
+				workspace.writablePath!,
+			),
+		).toBe(".worktree.lock")
 	})
 })

package/src/services/WorktreeService.ts

@@ -80,6 +80,8 @@ interface GitWorktree {
 	readonly branch?: string
 }
 
+const managedWorktreeIgnorePatterns = ["/.worktree.lock"] as const
+
 interface WorktreeOwner {
 	readonly kind: "task" | "phase"
 	readonly taskId: string
@@ -2325,6 +2327,42 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								const registeredAtPath = worktrees.find(
 									(worktree) => worktree.path === canonicalCheckoutPath,
 								)
+								const reconcileManagedWorktreeIgnores = (path: string) =>
+									Effect.gen(function* () {
+										const resolved = yield* fs.runCommand(
+											[
+												"git",
+												"-C",
+												path,
+												"rev-parse",
+												"--git-path",
+												"info/exclude",
+											],
+											{ captureOutput: true },
+										)
+										if (resolved.exitCode !== 0) {
+											return yield* new WorktreeError({
+												message: `Failed to locate local excludes for ${path}: ${resolved.stderr}`,
+											})
+										}
+										const excludePath = resolve(path, resolved.stdout.trim())
+										const existing = (yield* fs.exists(excludePath))
+											? yield* fs.readFile(excludePath)
+											: ""
+										const existingLines = new Set(existing.split(/\r?\n/))
+										const missing = managedWorktreeIgnorePatterns.filter(
+											(pattern) => !existingLines.has(pattern),
+										)
+										if (missing.length === 0) return
+										const prefix =
+											existing.length > 0 && !existing.endsWith("\n")
+												? "\n"
+												: ""
+										yield* fs.writeFile(
+											excludePath,
+											`${existing}${prefix}${missing.join("\n")}\n`,
+										)
+									})
 
 								if ("branch" in checkout) {
 									const branchRef = `refs/heads/${checkout.branch}`
@@ -2341,6 +2379,9 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									}
 									if (yield* fs.isDirectory(checkoutPath)) {
 										if (registeredAtPath?.branch === branchRef) {
+											if (!options.dryRun) {
+												yield* reconcileManagedWorktreeIgnores(checkoutPath)
+											}
 											checkoutReports.push({
 												repo: alias,
 												kind: "writable",
@@ -2545,6 +2586,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											message: `Created worktree for '${alias}' failed validation for branch '${checkout.branch}'`,
 										})
 									}
+									yield* reconcileManagedWorktreeIgnores(checkoutPath)
 									yield* runPostCheckoutHook({
 										command: config.repositories?.[alias]?.postCheckoutCommand,
 										variables: {
@@ -2620,6 +2662,9 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											currentHead.exitCode === 0 &&
 											currentHead.stdout.trim() === commit
 										) {
+											if (!options.dryRun) {
+												yield* reconcileManagedWorktreeIgnores(checkoutPath)
+											}
 											checkoutReports.push({
 												repo: alias,
 												kind: "reference",
@@ -2709,6 +2754,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											message: `Created reference checkout for '${alias}' failed validation for '${checkout.ref}'`,
 										})
 									}
+									yield* reconcileManagedWorktreeIgnores(checkoutPath)
 									yield* runPostCheckoutHook({
 										command: config.repositories?.[alias]?.postCheckoutCommand,
 										variables: {