@markjaquith/agency 2.50.0 → 2.52.0

package/README.md

@@ -2,13 +2,14 @@
 
 Agency manages durable agentic work across repositories. Epics, tasks, and
 phases live as Markdown documents in a filesystem-backed workbase. Repository
-aliases and Git worktrees provide each execution unit with the code it may read
-or write.
+aliases and managed workspaces provide each execution unit with the code it may
+read or write.
 
 ## Requirements
 
 - [Bun](https://bun.sh) 1.0 or newer
 - Git
+- [Jujutsu](https://jj-vcs.github.io/jj/) is preferred when available
 - [GitHub CLI](https://cli.github.com/) for `agency pr create`
 - OpenCode, Claude Code, or a configured runner for `agency work`
 
@@ -122,14 +123,15 @@ The plugin grants whole-workbase access dynamically, while the portable
 reference advertises that context to agents. Bash and Agency operations must
 still follow the write authority reported by `agency context`.
 
-Repository aliases and canonical fetch remotes are declared in tracked
-`agency.json`; local bare clones and symlinks remain ignored under
+Repository aliases, the version-control backend, and canonical fetch remotes are
+declared in tracked `agency.json`; local clones and symlinks remain ignored under
 `repos/{alias}`. A declaration contains no local path, symlink target, checkout,
 or credential:
 
 ```json
 {
 	"version": 2,
+	"vcs": "jj",
 	"repositories": {
 		"frontend": {
 			"remote": "git@example.com:team/frontend.git"
@@ -138,6 +140,29 @@ or credential:
 }
 ```
 
+New workbases select `"jj"` when the `jj` executable is available and otherwise
+select `"git"`. Existing version 2 workbases without `vcs` remain Git workbases.
+The selected backend is a workbase-level invariant: jj workbases initialize
+managed clones with `jj git init` and create jj workspaces, while Git workbases
+continue to use Git worktrees.
+
+Inspect the current backend and migration readiness with:
+
+```bash
+agency vcs status
+agency vcs migrate jj          # dry-run
+agency vcs migrate jj --apply
+agency vcs migrate git --apply
+```
+
+Migration is workbase-wide and transactional. Agency locks every execution
+unit, requires clean registered workspaces, blocks active claims and working or
+delegated units, converts repository metadata, recreates checkout paths with the
+target backend, and updates `agency.json` last. Migration from jj to Git also
+blocks jj-only heads that are not preserved by a bookmark or workspace. Failed
+migrations restore the source repositories and workspaces when rollback is
+possible and report explicit manual recovery paths otherwise.
+
 Existing version 2 workbases without `repositories` remain valid. Run
 `agency repo setup` to preview deterministic adoption of legacy local aliases;
 `agency repo setup --apply` writes declarations only when a portable origin is
@@ -146,7 +171,7 @@ creation command.
 
 ### Custom Worktree Command
 
-By default, Agency creates worktrees with Git. Set `worktreeCreateCommand` to an
+Git workbases create worktrees with Git. Set `worktreeCreateCommand` to an
 argv template when another tool should create writable worktrees:
 
 ```json
@@ -205,9 +230,10 @@ 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.
 
-The configured command applies only to the writable checkout. Supplemental
-read-only repositories remain detached Git worktrees at their declared refs so
-they do not acquire writable branches.
+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
+jj workspaces and ignore this Git-specific customization.
 
 ### Agent Runners
 

package/cli.ts

@@ -44,7 +44,14 @@ import { ReadinessService } from "./src/services/ReadinessService"
 import { GraphMutationService } from "./src/services/GraphMutationService"
 import { DoctorService } from "./src/services/DoctorService"
 import { ReviewService } from "./src/services/ReviewService"
+import {
+	GitVersionControlService,
+	JjVersionControlService,
+	VersionControlService,
+} from "./src/services/VersionControlService"
 import { review, help as reviewHelp } from "./src/commands/review"
+import { vcs, help as vcsHelp } from "./src/commands/vcs"
+import { VcsMigrationService } from "./src/services/VcsMigrationService"
 import {
 	claimCommand,
 	claimHelp,
@@ -62,6 +69,10 @@ import {
 const CliLayer = Layer.mergeAll(
 	FileSystemService.Default,
 	WorkbaseService.Default,
+	GitVersionControlService.Default,
+	JjVersionControlService.Default,
+	VersionControlService.Default,
+	VcsMigrationService.Default,
 	RepositoryService.Default,
 	EpicService.Default,
 	TaskService.Default,
@@ -547,6 +558,26 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	vcs: {
+		run: async (args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(vcsHelp)
+				return
+			}
+			await runCommand(
+				vcs({
+					subcommand: args[0],
+					target: args[1],
+					apply: options.apply,
+					dryRun: options["dry-run"],
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+					cwd: options.cwd,
+				}),
+			)
+		},
+	},
 	next: {
 		run: async (_args: string[], options: Record<string, any>) => {
 			if (options.help) return console.log(nextHelp)
@@ -702,7 +733,8 @@ Commands:
   archive <type>         Archive a work item
   task <subcommand>      Manage tasks
   work [directory|task]  Work on an epic, task, or phase
-  worktree <subcommand>  Inspect and maintain managed worktrees
+  worktree <subcommand>  Inspect and maintain managed workspaces
+  vcs <subcommand>       Inspect or migrate the version-control backend
   next                   List or select ready execution units
   pr create              Create a pull request for an execution unit
   review refresh         Explicitly refresh a pinned review task

package/package.json

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

package/schemas/agency-graph-v1.schema.json

@@ -22,6 +22,7 @@
       "required": ["version"],
       "properties": {
         "version": { "const": 2 },
+        "vcs": { "enum": ["git", "jj"] },
         "root": { "type": "string" }
       }
     },

package/src/cli-parser.test.ts

@@ -571,6 +571,25 @@ describe("strict CLI parsing", () => {
 		)
 	})
 
+	test("parses VCS status and migration commands", () => {
+		expect(parseCli(["vcs", "status", "--json"])).toMatchObject({
+			commandName: "vcs",
+			args: ["status"],
+			values: { json: true },
+		})
+		expect(
+			parseCli(["vcs", "migrate", "jj", "--apply", "--json"]),
+		).toMatchObject({
+			commandName: "vcs",
+			args: ["migrate", "jj"],
+			values: { apply: true, json: true },
+		})
+		expectUsageError(["vcs", "migrate"], "agency vcs migrate")
+		expect(() =>
+			parseCli(["vcs", "migrate", "jj", "--dry-run", "--apply"]),
+		).toThrow("cannot be combined")
+	})
+
 	test("accepts runner selection and command inspection for work", () => {
 		expect(
 			parseCli([

package/src/cli-parser.ts

@@ -832,6 +832,29 @@ const commands = {
 			},
 		},
 	},
+	vcs: {
+		usage: "agency vcs <status|migrate>",
+		options: {
+			...outputOptions,
+			apply: { type: "boolean" },
+			"dry-run": { type: "boolean" },
+		},
+		subcommands: {
+			status: {
+				usage: "agency vcs status [--json]",
+				minArgs: 0,
+				maxArgs: 0,
+				options: ["json"],
+			},
+			migrate: {
+				usage: "agency vcs migrate <git|jj> [--dry-run | --apply] [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["apply", "dry-run", "json"],
+				conflicts: [["apply", "dry-run"]],
+			},
+		},
+	},
 	work: {
 		usage:
 			"agency work [<directory-or-task-id> | --epic <epic-id>] [--runner <name>] [--auto] | agency work prepare [target] [--dry-run] [--json]",

package/src/cli.test.ts

@@ -1,5 +1,5 @@
 import { afterAll, afterEach, describe, expect, test } from "bun:test"
-import { access, mkdir, realpath, symlink } from "node:fs/promises"
+import { access, mkdir, realpath, stat, symlink } from "node:fs/promises"
 import { join, sep } from "node:path"
 import errorFixture from "../fixtures/protocol/error.json"
 import successFixture from "../fixtures/protocol/success.json"
@@ -1762,9 +1762,9 @@ status: open
 				alias: "agency",
 				status: "applied",
 			})
-			expect(await Bun.file(join(restored, "repos/agency/HEAD")).exists()).toBe(
-				true,
-			)
+			expect(
+				(await stat(join(restored, "repos/agency/.jj"))).isDirectory(),
+			).toBe(true)
 
 			const prepared = parseJson(
 				await runCli(["work", "prepare", "portable", "--json"], restored),

package/src/commands/init.test.ts

@@ -8,6 +8,7 @@ import {
 	runTestEffect,
 } from "../test-utils"
 import { init } from "./init"
+import { preferredVersionControl } from "../workbase/version-control"
 
 describe("init command", () => {
 	let parent: string
@@ -26,6 +27,7 @@ describe("init command", () => {
 
 		expect(await Bun.file(join(root, "agency.json")).json()).toEqual({
 			version: 2,
+			vcs: preferredVersionControl(),
 		})
 		for (const directory of ["repos", "epics", "tasks"]) {
 			expect((await stat(join(root, directory))).isDirectory()).toBe(true)

package/src/commands/vcs.test.ts

@@ -0,0 +1,75 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
+import { vcs } from "./vcs"
+
+describe("vcs command", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await Bun.write(
+			`${root}/agency.json`,
+			JSON.stringify({ version: 2, vcs: "git" }),
+		)
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("reports structured backend status", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(vcs({ subcommand: "status", cwd: root, json: true })),
+		)
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			root,
+			configured: "git",
+			source: "git",
+			target: "git",
+			workspaceCount: 0,
+			blockers: [],
+		})
+	})
+
+	test("persists the inferred Git backend for a legacy workbase", async () => {
+		await Bun.write(`${root}/agency.json`, JSON.stringify({ version: 2 }))
+		await captureLogs(() =>
+			runTestEffect(
+				vcs({
+					subcommand: "migrate",
+					target: "git",
+					cwd: root,
+					apply: true,
+					json: true,
+				}),
+			),
+		)
+		expect(await Bun.file(`${root}/agency.json`).json()).toEqual({
+			version: 2,
+			vcs: "git",
+		})
+	})
+
+	test("treats migration to the configured backend as a no-op", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				vcs({
+					subcommand: "migrate",
+					target: "git",
+					cwd: root,
+					apply: true,
+					json: true,
+				}),
+			),
+		)
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			source: "git",
+			target: "git",
+			mode: "apply",
+			actions: [],
+		})
+	})
+})

package/src/commands/vcs.ts

@@ -0,0 +1,72 @@
+import { Effect } from "effect"
+import { VcsMigrationService } from "../services/VcsMigrationService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+interface VcsOptions extends BaseCommandOptions {
+	readonly subcommand?: string
+	readonly target?: string
+	readonly apply?: boolean
+}
+
+export const vcs = (options: VcsOptions = {}) =>
+	Effect.gen(function* () {
+		const migrations = yield* VcsMigrationService
+		const { log } = createLoggers(options)
+		const root = options.cwd ?? process.cwd()
+		if (options.subcommand === "status") {
+			const status = yield* migrations.status(root)
+			if (options.json) return log(JSON.stringify(status, null, 2))
+			log(
+				`Version control: ${status.source}${status.configured ? "" : " (inferred for legacy workbase)"}`,
+			)
+			log(
+				`Tools: git=${status.available.git ? "available" : "missing"} jj=${status.available.jj ? "available" : "missing"}`,
+			)
+			log(
+				`Repositories: ${status.repositories.length}; managed workspaces: ${status.workspaceCount}; blockers: ${status.blockers.length}`,
+			)
+			for (const blocker of status.blockers)
+				log(`blocker ${blocker.kind} ${blocker.target}: ${blocker.message}`)
+			return
+		}
+		if (options.subcommand === "migrate") {
+			if (options.target !== "git" && options.target !== "jj") {
+				return yield* Effect.fail(
+					new Error("VCS migration target must be 'git' or 'jj'"),
+				)
+			}
+			const result = yield* migrations.migrate(options.target, root, {
+				apply: options.apply,
+			})
+			if (options.json) return log(JSON.stringify(result, null, 2))
+			log(
+				result.mode === "apply"
+					? `Migrated workbase to ${options.target}`
+					: `Migration plan: ${result.source} -> ${options.target}`,
+			)
+			for (const action of result.actions) log(`- ${action}`)
+			if (result.mode === "dry-run" && result.actions.length > 0)
+				log("Run again with --apply to perform the migration.")
+			return
+		}
+		return yield* Effect.fail(
+			new Error(`Unknown vcs subcommand '${options.subcommand ?? ""}'`),
+		)
+	})
+
+export const help = `
+Usage: agency vcs <status|migrate>
+
+Inspect or migrate the workbase-wide version-control backend.
+
+Commands:
+  status                         Show the configured backend, tools, repositories, and blockers
+  migrate <git|jj> [--dry-run | --apply]
+                                 Preview or apply a clean, transactional backend migration
+
+Options:
+  --apply              Apply the migration; omission performs a dry run
+  --dry-run            Explicitly preview the migration without applying it
+  --json               Print structured output
+`

package/src/commands/worktree.ts

@@ -120,7 +120,7 @@ export const worktree = (options: WorktreeOptions = {}) =>
 export const help = `
 Usage: agency worktree <list|inspect|prepare|remove|rebuild|repair>
 
-Inspect and maintain Agency-managed writable and reference worktrees.
+Inspect and maintain Agency-managed writable and reference workspaces.
 
 Commands:
   list                              List every managed checkout

package/src/graph-schema.test.ts

@@ -64,7 +64,7 @@ describe("graph contract", () => {
 		]
 		const graph = {
 			version: 1,
-			workbase: { version: 2 },
+			workbase: { version: 2, vcs: "git" },
 			filters: {
 				ready: null,
 				blocked: null,

package/src/graph-schema.ts

@@ -56,6 +56,7 @@ export const GraphReadiness = Schema.Struct({
 
 export const GraphWorkbase = Schema.Struct({
 	version: Schema.Literal(2),
+	vcs: Schema.optional(Schema.Literal("git", "jj")),
 	root: Schema.optional(Schema.String),
 })
 

package/src/services/ArchiveService.ts

@@ -11,6 +11,11 @@ import {
 	WorktreeService,
 	type WorktreeRemovalSnapshot,
 } from "./WorktreeService"
+import {
+	GitVersionControlService,
+	JjVersionControlService,
+	VersionControlService,
+} from "./VersionControlService"
 import {
 	formatMarkdownDocument,
 	parseFrontmatter,
@@ -268,6 +273,9 @@ const applyMutation = (moves: readonly Move[], writes: readonly Write[]) =>
 const WorktreeLayer = Layer.mergeAll(
 	FileSystemService.Default,
 	WorkbaseService.Default,
+	GitVersionControlService.Default,
+	JjVersionControlService.Default,
+	VersionControlService.Default,
 	TaskService.Default,
 	PhaseService.Default,
 	WorktreeService.Default,
@@ -298,6 +306,21 @@ const restoreWorktreeSnapshots = async (
 			continue
 		} catch {}
 		await mkdir(dirname(snapshot.path), { recursive: true })
+		if (snapshot.vcs === "jj") {
+			await runGit([
+				"jj",
+				"-R",
+				snapshot.repositoryPath,
+				"workspace",
+				"add",
+				"--name",
+				snapshot.workspaceName!,
+				"-r",
+				snapshot.head,
+				snapshot.path,
+			])
+			continue
+		}
 		await runGit(
 			snapshot.branch
 				? [

package/src/services/ContextService.ts

@@ -8,6 +8,7 @@ import { RepositoryService } from "./RepositoryService"
 import { aggregateProgress, readinessState } from "../readiness"
 import { parseFrontmatter } from "../workbase/frontmatter"
 import { documentRevision } from "../workbase/document-revision"
+import { VersionControlService } from "./VersionControlService"
 import {
 	EpicFrontmatter,
 	PhaseFrontmatter,
@@ -127,6 +128,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 					const fs = yield* FileSystemService
 					const workbase = yield* WorkbaseService
 					const repositoryService = yield* RepositoryService
+					const versionControl = yield* VersionControlService
 					const cwd = resolve(options.cwd ?? process.cwd())
 					const suppliedTarget = options.target ?? "."
 					const candidate = resolve(cwd, suppliedTarget)
@@ -134,6 +136,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 					const { root, config } = yield* workbase.loadConfig(
 						candidateExists ? candidate : cwd,
 					)
+					const backend = yield* versionControl.forWorkbase(root)
 
 					if (relative(root, candidate) === "") {
 						const compact = !options.full
@@ -214,6 +217,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 								root,
 								configPath: join(root, "agency.json"),
 								version: config.version,
+								vcs: config.vcs ?? "git",
 							},
 							target: { kind: "workbase", path: root },
 							hint: compact
@@ -801,9 +805,45 @@ export class ContextService extends Effect.Service<ContextService>()(
 					const inspectCheckout = (
 						repositoryPath: string,
 						checkoutPath: string,
+						expectedBranch: string | null = null,
 					) =>
 						Effect.gen(function* (): Generator<any, CheckoutInspection, any> {
 							const materialized = yield* fs.isDirectory(checkoutPath)
+							if (backend.kind === "jj") {
+								const listed = yield* Effect.either(
+									backend.listWorkspaces(repositoryPath),
+								)
+								const workspaces = Either.isRight(listed) ? listed.right : []
+								if (Either.isLeft(listed)) {
+									inspectionWarnings.push(
+										`Unable to inspect jj workspace registrations for ${repositoryPath}`,
+									)
+								}
+								const canonicalCheckoutPath = materialized
+									? yield* fs.realPath(checkoutPath)
+									: resolve(checkoutPath)
+								const registered = workspaces.some(
+									(workspace) => workspace.path === canonicalCheckoutPath,
+								)
+								if (!materialized) {
+									return {
+										materialized: false,
+										registered,
+										checkoutCommit: null,
+										checkoutBranch: null,
+										detached: null,
+										dirty: null,
+									}
+								}
+								return {
+									materialized: true,
+									registered,
+									checkoutCommit: yield* backend.workspaceHead(checkoutPath),
+									checkoutBranch: expectedBranch,
+									detached: expectedBranch === null,
+									dirty: yield* backend.workspaceDirty(checkoutPath),
+								}
+							}
 							const listed = yield* runGit(fs, repositoryPath, [
 								"worktree",
 								"list",
@@ -870,14 +910,22 @@ export class ContextService extends Effect.Service<ContextService>()(
 								const repositoryPath =
 									repository?.path ?? join(root, "repos", executionData.repo)
 								const checkoutPath = join(codePath, executionData.repo)
-								const branchCommit = yield* runGit(fs, repositoryPath, [
-									"rev-parse",
-									`${executionData.branch}^{commit}`,
-								])
-								const baseCommit = yield* runGit(fs, repositoryPath, [
-									"rev-parse",
-									`${executionData.base}^{commit}`,
-								])
+								let branchCommit = yield* backend.resolveRevision(
+									repositoryPath,
+									executionData.branch,
+								)
+								const baseCommit = yield* backend.resolveRevision(
+									repositoryPath,
+									executionData.base,
+								)
+								const checkout = yield* inspectCheckout(
+									repositoryPath,
+									checkoutPath,
+									executionData.branch,
+								)
+								if (backend.kind === "jj" && branchCommit === null) {
+									branchCommit = checkout.checkoutCommit
+								}
 								if (branchCommit === null) {
 									inspectionWarnings.push(
 										`Unable to resolve branch '${executionData.branch}' in ${repositoryPath}`,
@@ -896,7 +944,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 									base: executionData.base,
 									branchCommit,
 									baseCommit,
-									...(yield* inspectCheckout(repositoryPath, checkoutPath)),
+									...checkout,
 								}
 							})
 						: null
@@ -907,10 +955,10 @@ export class ContextService extends Effect.Service<ContextService>()(
 						const repositoryPath =
 							repository?.path ?? join(root, "repos", reference.repo)
 						const checkoutPath = join(codePath, reference.repo)
-						const resolvedCommit = yield* runGit(fs, repositoryPath, [
-							"rev-parse",
-							`${reference.ref}^{commit}`,
-						])
+						const resolvedCommit = yield* backend.resolveRevision(
+							repositoryPath,
+							reference.ref,
+						)
 						if (resolvedCommit === null) {
 							inspectionWarnings.push(
 								`Unable to resolve reference '${reference.ref}' in ${repositoryPath}`,
@@ -968,6 +1016,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 							root,
 							configPath: join(root, "agency.json"),
 							version: config.version,
+							vcs: config.vcs ?? "git",
 						},
 						target,
 						documents: {

package/src/services/DoctorService.ts

@@ -126,6 +126,14 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 					}
 
 					const gitAvailable = yield* tool("tool.git", "git", "error", "Git")
+					const jjAvailable = yield* tool(
+						"tool.jj",
+						"jj",
+						config.vcs === "jj" ? "error" : "optional",
+						"Jujutsu",
+					)
+					const versionControlAvailable =
+						gitAvailable && (config.vcs !== "jj" || jjAvailable)
 					yield* tool(
 						"capability.runner.opencode",
 						"opencode",
@@ -321,18 +329,17 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 						}
 					}
 
-					const repositoryList = gitAvailable
+					const repositoryList = versionControlAvailable
 						? yield* repositories.list(root)
 						: []
-					if (!gitAvailable) {
+					if (!versionControlAvailable) {
 						add({
 							id: "repository.inspection",
 							category: "repository",
 							level: "warning",
 							status: "fail",
-							message:
-								"Repository, ref, remote, and worktree checks were skipped because Git is unavailable",
-							remediation: "Install 'git' and rerun 'agency doctor'.",
+							message: `Repository, ref, remote, and workspace checks were skipped because the ${config.vcs ?? "git"} backend is unavailable`,
+							remediation: `Install '${config.vcs === "jj" ? "jj" : "git"}' and rerun 'agency doctor'.`,
 						})
 					}
 					for (const repository of repositoryList) {
@@ -439,7 +446,7 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 						}
 					}
 
-					if (validation.valid && gitAvailable) {
+					if (validation.valid && versionControlAvailable) {
 						const inspected = yield* Effect.either(worktrees.list(root))
 						if (Either.isLeft(inspected)) {
 							add({

package/src/services/GraphService.ts

@@ -943,6 +943,7 @@ export class GraphService extends Effect.Service<GraphService>()(
 						version: GRAPH_VERSION,
 						workbase: {
 							version: config.version,
+							vcs: config.vcs ?? "git",
 							...(include.has("workspace") ? { root } : {}),
 						},
 						filters,