@markjaquith/agency 2.71.26 → 2.72.0

package/README.md

@@ -752,6 +752,7 @@ agency integration sync [--json]
 agency repo setup [--dry-run | --apply] [--json]
 agency repo add <alias> <remote> [--json]
 agency repo link <alias> <path> [--json]
+agency repo materialize <alias> [--json]
 agency repo list [--json]
 agency repo show <alias> [--json]
 agency repo fetch <alias> [--json]
@@ -784,7 +785,11 @@ Each registration has a stable ID and may have a unique name. A default workbase
 is used when the current directory is outside every workbase. `prune` removes
 registrations whose workbase configuration no longer exists.
 `repo add` creates a bare clone. `repo link` creates a symlink to an existing Git
-repository. Alias names are then used by all documents and commands. Remove,
+repository. For Git workbases, `repo materialize` replaces a linked alias with a
+managed bare clone while migrating its registered worktrees in place; active
+Agency references continue to use the same alias. The command refuses remote
+drift and stale worktree registrations. Alias names are then used by all
+documents and commands. Remove,
 unlink, and rename refuse aliases referenced by active work or backed by linked
 worktrees, and report each blocker.
 

package/package.json

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

package/src/cli.test.ts

@@ -507,6 +507,49 @@ describe("CLI", () => {
 		})
 	})
 
+	test("preserves the JSON error contract when archiving an already archived task", async () => {
+		const root = await createTempDir()
+		tempDirs.push(root)
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		expect(
+			Bun.spawnSync(["git", "init", "--bare", join(root, "repos/agency")])
+				.exitCode,
+		).toBe(0)
+		await mkdir(join(root, "tasks/example"), { recursive: true })
+		await Bun.write(
+			join(root, "tasks/example/TASK.md"),
+			`---
+ticketUrl: null
+repo: agency
+branch: task/example
+base: main
+pr: null
+status: dropped
+---
+
+# Example
+`,
+		)
+
+		expect((await runCli(["archive", "task", "example"], root)).exitCode).toBe(
+			0,
+		)
+		const result = await runCli(["archive", "task", "example", "--json"], root)
+
+		expect(result.exitCode).toBe(1)
+		expect(result.stderr).toBe("")
+		expect(JSON.parse(result.stdout)).toEqual({
+			version: 1,
+			ok: false,
+			error: {
+				code: "TASK_ERROR",
+				message: "Task 'example' is already archived",
+				fields: {},
+				retryable: false,
+			},
+		})
+	})
+
 	test("rejects malformed input before running a command", async () => {
 		const parent = await createTempDir()
 		tempDirs.push(parent)

package/src/commands/archive.test.ts

@@ -93,6 +93,23 @@ describe("archive command", () => {
 		)
 	})
 
+	test("reports an already archived task", async () => {
+		await runTestEffect(
+			archive({ type: "task", args: ["example"], cwd: root, silent: true }),
+		)
+
+		await expect(
+			runTestEffect(
+				archive({
+					type: "task",
+					args: ["example"],
+					cwd: root,
+					silent: true,
+				}),
+			),
+		).rejects.toThrow("Task 'example' is already archived")
+	})
+
 	test("outputs one deterministic bulk archive object and a concise human summary", async () => {
 		const jsonLogs = await captureLogs(() =>
 			runTestEffect(

package/src/commands/repo.test.ts

@@ -23,7 +23,9 @@ describe("repo command", () => {
 	test("requires a subcommand", async () => {
 		await expect(
 			runTestEffect(repo({ args: [], silent: true })),
-		).rejects.toThrow("Available subcommands: setup, add, link, list")
+		).rejects.toThrow(
+			"Available subcommands: setup, add, link, materialize, list",
+		)
 	})
 
 	test("requires add arguments", async () => {
@@ -34,6 +36,14 @@ describe("repo command", () => {
 		).rejects.toThrow("Usage: agency repo add")
 	})
 
+	test("requires a materialize alias", async () => {
+		await expect(
+			runTestEffect(
+				repo({ subcommand: "materialize", args: [], silent: true }),
+			),
+		).rejects.toThrow("Usage: agency repo materialize <alias>")
+	})
+
 	test("lists repository metadata as JSON", async () => {
 		const logs = await captureLogs(() =>
 			runTestEffect(

package/src/commands/repo.ts

@@ -74,6 +74,21 @@ export const repo = (options: RepoOptions) =>
 				return
 			}
 
+			case "materialize": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					"Usage: agency repo materialize <alias>",
+				)
+				const item = yield* repositories.materialize(alias, cwd)
+				log(
+					options.json
+						? JSON.stringify(item, null, 2)
+						: `Materialized repository '${alias}'`,
+				)
+				return
+			}
+
 			case "list": {
 				const items = yield* repositories.list(cwd)
 				if (options.json) {
@@ -187,7 +202,7 @@ export const repo = (options: RepoOptions) =>
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available subcommands: setup, add, link, list, show, fetch, remove, unlink, rename, remote, verify",
+						"Subcommand is required. Available subcommands: setup, add, link, materialize, list, show, fetch, remove, unlink, rename, remote, verify",
 					),
 				)
 		}
@@ -200,6 +215,7 @@ Subcommands:
   setup                 Plan or apply portable repository setup
   add <alias> <remote>  Create a bare clone
   link <alias> <path>   Link an existing Git repository
+  materialize <alias>   Replace a linked alias with a managed bare clone
   list                  List repository aliases
   show <alias>          Show a repository alias
   fetch <alias>         Fetch and prune a repository

package/src/services/RepositoryService.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
-import { mkdir, stat } from "node:fs/promises"
+import { mkdir, realpath, stat } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { RepositoryService } from "./RepositoryService"
@@ -16,6 +16,18 @@ const runGit = async (args: string[]) => {
 	}
 }
 
+const gitOutput = async (args: string[]) => {
+	const process = Bun.spawn(["git", ...args], {
+		stdout: "pipe",
+		stderr: "pipe",
+	})
+	await process.exited
+	if (process.exitCode !== 0) {
+		throw new Error(await new Response(process.stderr).text())
+	}
+	return (await new Response(process.stdout).text()).trim()
+}
+
 const portableRemote = (name: string) =>
 	`https://example.com/agency-tests/${name}.git`
 
@@ -159,6 +171,143 @@ describe("RepositoryService", () => {
 		})
 	})
 
+	test("materializes a linked alias without invalidating active worktrees", async () => {
+		const target = join(root, "linked-repository")
+		const checkout = join(root, "tasks/active/code/linked")
+		await mkdir(target, { recursive: true })
+		await runGit(["init", "--initial-branch=main", target])
+		await runGit(["-C", target, "config", "user.email", "test@example.com"])
+		await runGit(["-C", target, "config", "user.name", "Test"])
+		await Bun.write(join(target, "README.md"), "linked\n")
+		await runGit(["-C", target, "add", "README.md"])
+		await runGit(["-C", target, "commit", "-m", "initial"])
+		await setPortableOrigin(target, "materialized")
+		await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) => service.link("linked", target, root)),
+			),
+		)
+		await write(
+			root,
+			"tasks/active/TASK.md",
+			`---
+ticketUrl: null
+repo: linked
+branch: task/active
+base: main
+pr: null
+status: working
+---
+`,
+		)
+		await mkdir(dirname(checkout), { recursive: true })
+		await runGit([
+			"-C",
+			target,
+			"worktree",
+			"add",
+			"-b",
+			"task/active",
+			checkout,
+			"main",
+		])
+		await Bun.write(join(checkout, "dirty.txt"), "preserved\n")
+
+		const result = await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) => service.materialize("linked", root)),
+			),
+		)
+
+		expect(result.kind).toBe("bare")
+		expect(result.target).toBeNull()
+		expect(result.states).toEqual(["declared", "materialized"])
+		expect(await Bun.file(join(checkout, "dirty.txt")).text()).toBe(
+			"preserved\n",
+		)
+		expect(await gitOutput(["-C", checkout, "branch", "--show-current"])).toBe(
+			"task/active",
+		)
+		expect(
+			await gitOutput(["-C", checkout, "rev-parse", "--git-common-dir"]),
+		).toBe(await realpath(join(root, "repos/linked")))
+		expect(
+			await gitOutput(["-C", target, "worktree", "list", "--porcelain"]),
+		).not.toContain(checkout)
+		expect(await Bun.file(join(target, ".git/HEAD")).exists()).toBe(true)
+		expect(await Bun.file(join(root, "tasks/active/TASK.md")).text()).toContain(
+			"repo: linked",
+		)
+	})
+
+	test("materializes an alias linked through an existing worktree", async () => {
+		const primary = join(root, "primary-repository")
+		const linkedWorktree = join(root, "linked-worktree")
+		await mkdir(primary, { recursive: true })
+		await runGit(["init", "--initial-branch=main", primary])
+		await runGit(["-C", primary, "config", "user.email", "test@example.com"])
+		await runGit(["-C", primary, "config", "user.name", "Test"])
+		await Bun.write(join(primary, "README.md"), "linked worktree\n")
+		await runGit(["-C", primary, "add", "README.md"])
+		await runGit(["-C", primary, "commit", "-m", "initial"])
+		await setPortableOrigin(primary, "linked-worktree")
+		await runGit([
+			"-C",
+			primary,
+			"worktree",
+			"add",
+			"-b",
+			"linked-branch",
+			linkedWorktree,
+			"main",
+		])
+		await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) =>
+					service.link("linked", linkedWorktree, root),
+				),
+			),
+		)
+
+		await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) => service.materialize("linked", root)),
+			),
+		)
+
+		expect(
+			await gitOutput(["-C", linkedWorktree, "rev-parse", "--git-common-dir"]),
+		).toBe(await realpath(join(root, "repos/linked")))
+		expect(
+			await gitOutput(["-C", primary, "worktree", "list", "--porcelain"]),
+		).not.toContain(linkedWorktree)
+	})
+
+	test("refuses to materialize linked aliases in jj workbases", async () => {
+		if (!Bun.which("jj")) return
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({ version: 2, vcs: "jj" }),
+		)
+		const target = join(root, "linked-jj-repository")
+		await mkdir(target, { recursive: true })
+		await runGit(["init", "--initial-branch=main", target])
+		await setPortableOrigin(target, "linked-jj")
+		await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) => service.link("linked", target, root)),
+			),
+		)
+
+		await expect(
+			runTestEffect(
+				RepositoryService.pipe(
+					Effect.flatMap((service) => service.materialize("linked", root)),
+				),
+			),
+		).rejects.toThrow("only supported for Git workbases")
+	})
+
 	test("rejects invalid and duplicate aliases", async () => {
 		const source = join(root, "source.git")
 		await runGit(["init", "--bare", "--initial-branch=main", source])

package/src/services/RepositoryService.ts

@@ -1,7 +1,7 @@
 import { Schema, TreeFormatter } from "@effect/schema"
 import { Data, Effect, Either } from "effect"
 import { join, resolve } from "node:path"
-import { lstat, rename, rm } from "node:fs/promises"
+import { cp, lstat, realpath, rename, rm } from "node:fs/promises"
 import { FileSystemService } from "./FileSystemService"
 import { GraphService } from "./GraphService"
 import { WorkbaseService } from "./WorkbaseService"
@@ -327,6 +327,27 @@ const replaceWithMoveStep = (
 	manualRecovery: `Restore ${backup} to ${current}`,
 })
 
+const runGit = (
+	fs: Effect.Effect.Success<typeof FileSystemService>,
+	args: readonly string[],
+	label: string,
+) =>
+	Effect.runPromise(
+		fs
+			.runCommand(["git", ...args], { captureOutput: true })
+			.pipe(
+				Effect.flatMap((result) =>
+					result.exitCode === 0
+						? Effect.void
+						: Effect.fail(
+								new Error(
+									`${label}: ${result.stderr.trim() || result.stdout.trim()}`,
+								),
+							),
+				),
+			) as Effect.Effect<void, unknown, never>,
+	)
+
 const runTransaction = (
 	state: Effect.Effect.Success<ReturnType<typeof configState>>,
 	config: WorkbaseConfig,
@@ -501,6 +522,274 @@ export class RepositoryService extends Effect.Service<RepositoryService>()(
 					return destination
 				}),
 
+			materialize: (alias: string, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const versionControl = yield* VersionControlService
+					const repository = yield* find(alias, startPath)
+					if (repository.kind !== "symlink" || !repository.target) {
+						return yield* new RepositoryError({
+							message: `Repository alias '${alias}' is not linked`,
+						})
+					}
+					if (repository.states.includes("invalid")) {
+						return yield* new RepositoryError({
+							message: `Repository alias '${alias}' has an invalid linked repository`,
+						})
+					}
+					if (repository.states.includes("remote-drifted")) {
+						return yield* new RepositoryError({
+							message: `Repository alias '${alias}' cannot be materialized while its origin differs from the portable declaration`,
+						})
+					}
+					if (!repository.declaredRemote) {
+						return yield* new RepositoryError({
+							message: `Repository alias '${alias}' has no portable remote declaration`,
+						})
+					}
+
+					const state = yield* configState(startPath)
+					const backend = yield* versionControl.forWorkbase(state.root)
+					if (backend.kind !== "git") {
+						return yield* new RepositoryError({
+							message: `Repository alias materialization is only supported for Git workbases`,
+						})
+					}
+
+					const source = yield* fs.realPath(repository.path)
+					const registered = yield* backend.listWorkspaces(repository.path)
+					const registeredPaths = registered
+						.map((workspace) => workspace.path)
+						.sort()
+					const worktrees: (typeof registered)[number][] = []
+					for (const workspace of registered) {
+						if (!(yield* fs.isDirectory(workspace.path))) {
+							return yield* new RepositoryError({
+								message: `Repository alias '${alias}' has a stale worktree registration: ${workspace.path}`,
+							})
+						}
+						if (
+							(yield* fs.inspectFile(join(workspace.path, ".git"))).kind ===
+							"file"
+						)
+							worktrees.push(workspace)
+					}
+
+					const commonDirectory = yield* fs
+						.runCommand(
+							[
+								"git",
+								"-C",
+								source,
+								"rev-parse",
+								"--path-format=absolute",
+								"--git-common-dir",
+							],
+							{ captureOutput: true },
+						)
+						.pipe(
+							Effect.flatMap((result) =>
+								result.exitCode === 0
+									? Effect.succeed(result.stdout.trim())
+									: Effect.fail(
+											new RepositoryError({
+												message: `Failed to locate Git metadata for repository alias '${alias}'`,
+											}),
+										),
+							),
+						)
+					const sourceWorktrees = join(commonDirectory, "worktrees")
+					const hasWorktreeMetadata = yield* fs.isDirectory(sourceWorktrees)
+					if (worktrees.length > 0 && !hasWorktreeMetadata) {
+						return yield* new RepositoryError({
+							message: `Repository alias '${alias}' is missing Git metadata for its registered worktrees`,
+						})
+					}
+
+					const suffix = `${process.pid}-${Date.now()}`
+					const staging = join(
+						state.root,
+						"repos",
+						`.agency-materialize-${repository.alias}-${suffix}`,
+					)
+					const aliasBackup = join(
+						state.root,
+						"repos",
+						`.agency-linked-${repository.alias}-${suffix}`,
+					)
+					const metadataBackup = `${sourceWorktrees}.agency-materialize-${suffix}`
+					yield* fs.createDirectory(join(state.root, "repos"))
+					yield* backend.cloneRepository(source, staging).pipe(
+						Effect.catchAll((cause) =>
+							fs.deleteDirectory(staging).pipe(
+								Effect.ignore,
+								Effect.zipRight(
+									Effect.fail(
+										new RepositoryError({
+											message: `Failed to materialize repository '${alias}': ${cause instanceof Error ? cause.message : String(cause)}`,
+											cause,
+										}),
+									),
+								),
+							),
+						),
+					)
+					yield* backend
+						.setRemoteUrl(staging, "origin", repository.declaredRemote)
+						.pipe(
+							Effect.catchAll((cause) =>
+								fs
+									.deleteDirectory(staging)
+									.pipe(Effect.ignore, Effect.zipRight(Effect.fail(cause))),
+							),
+						)
+					for (const workspace of worktrees) {
+						if (!workspace.commit) continue
+						const object = yield* fs.runCommand(
+							[
+								"git",
+								"--git-dir",
+								staging,
+								"cat-file",
+								"-e",
+								`${workspace.commit}^{commit}`,
+							],
+							{ captureOutput: true },
+						)
+						if (object.exitCode !== 0) {
+							yield* fs.deleteDirectory(staging).pipe(Effect.ignore)
+							return yield* new RepositoryError({
+								message: `Registered worktree commit '${workspace.commit}' is missing from the materialized repository`,
+							})
+						}
+					}
+
+					let metadataMoved = false
+					let aliasMoved = false
+					let cloneInstalled = false
+					const workspacePaths = worktrees.map((workspace) => workspace.path)
+					const repair = (gitDirectory: string) =>
+						workspacePaths.length === 0
+							? Promise.resolve()
+							: runGit(
+									fs,
+									[
+										"--git-dir",
+										gitDirectory,
+										"worktree",
+										"repair",
+										...workspacePaths,
+									],
+									"Failed to repair Git worktrees",
+								)
+					const rollbackMigration = async () => {
+						const errors: unknown[] = []
+						if (metadataMoved) {
+							try {
+								await rename(metadataBackup, sourceWorktrees)
+								metadataMoved = false
+								await repair(commonDirectory)
+							} catch (error) {
+								errors.push(error)
+							}
+						}
+						if (cloneInstalled) {
+							try {
+								await rename(repository.path, staging)
+								cloneInstalled = false
+							} catch (error) {
+								errors.push(error)
+							}
+						}
+						if (aliasMoved) {
+							try {
+								await rename(aliasBackup, repository.path)
+								aliasMoved = false
+							} catch (error) {
+								errors.push(error)
+							}
+						}
+						if (errors.length > 0) throw new AggregateError(errors)
+					}
+					const migration: TransactionStep = {
+						label: `materialize linked repository ${repository.alias}`,
+						preflight: async () => {
+							const stats = await lstat(repository.path)
+							if (
+								!stats.isSymbolicLink() ||
+								(await realpath(repository.path)) !== source
+							)
+								throw new Error(
+									`Repository alias '${repository.alias}' changed during materialization`,
+								)
+							const current = await Effect.runPromise(
+								backend
+									.listWorkspaces(repository.path)
+									.pipe(
+										Effect.provideService(FileSystemService, fs),
+									) as unknown as Effect.Effect<
+									readonly { readonly path: string }[],
+									unknown,
+									never
+								>,
+							)
+							const currentPaths = current
+								.map((workspace) => workspace.path)
+								.sort()
+							if (
+								JSON.stringify(currentPaths) !== JSON.stringify(registeredPaths)
+							)
+								throw new Error(
+									`Git worktree registrations changed during materialization`,
+								)
+						},
+						apply: async () => {
+							try {
+								if (hasWorktreeMetadata) {
+									await rename(sourceWorktrees, metadataBackup)
+									metadataMoved = true
+									await cp(metadataBackup, join(staging, "worktrees"), {
+										recursive: true,
+									})
+								}
+								await rename(repository.path, aliasBackup)
+								aliasMoved = true
+								await rename(staging, repository.path)
+								cloneInstalled = true
+								await repair(repository.path)
+							} catch (cause) {
+								try {
+									await rollbackMigration()
+								} catch (rollbackCause) {
+									throw new Error(
+										`Repository materialization failed and rollback requires manual recovery: restore ${aliasBackup} to ${repository.path} and ${metadataBackup} to ${sourceWorktrees}`,
+										{ cause: new AggregateError([cause, rollbackCause]) },
+									)
+								}
+								throw cause
+							}
+						},
+						rollback: rollbackMigration,
+						finalize: async () => {
+							await rm(aliasBackup, { recursive: true, force: true })
+							await rm(metadataBackup, { recursive: true, force: true })
+						},
+						manualRecovery: `Restore ${aliasBackup} to ${repository.path} and ${metadataBackup} to ${sourceWorktrees}`,
+					}
+
+					yield* runLifecycleTransaction({
+						root: state.root,
+						preconditions: [{ path: state.path, revision: state.revision }],
+						steps: [migration],
+					}).pipe(
+						Effect.mapError(
+							(cause) => new RepositoryError({ message: cause.message, cause }),
+						),
+						Effect.ensuring(fs.deleteDirectory(staging).pipe(Effect.ignore)),
+					)
+					return yield* find(alias, startPath)
+				}),
+
 			list: (startPath: string = process.cwd()) =>
 				Effect.gen(function* () {
 					const fs = yield* FileSystemService

package/src/services/TaskService.ts

@@ -589,7 +589,9 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 				const path = join(root, "tasks", validId, "TASK.md")
 				if (!(yield* fs.exists(path))) {
 					return yield* new TaskError({
-						message: `Task '${validId}' does not exist`,
+						message: (yield* fs.exists(archivedTaskDirectory(root, validId)))
+							? `Task '${validId}' is already archived`
+							: `Task '${validId}' does not exist`,
 					})
 				}
 				const content = yield* fs.readFile(path)