@markjaquith/agency 2.29.0 → 2.30.1

package/src/commands/repo.test.ts

@@ -23,7 +23,7 @@ describe("repo command", () => {
 	test("requires a subcommand", async () => {
 		await expect(
 			runTestEffect(repo({ args: [], silent: true })),
-		).rejects.toThrow("Available subcommands: add, link, list")
+		).rejects.toThrow("Available subcommands: setup, add, link, list")
 	})
 
 	test("requires add arguments", async () => {
@@ -47,7 +47,9 @@ describe("repo command", () => {
 				path: join(root, "repos/agency"),
 				kind: "repository",
 				remote: null,
+				declaredRemote: null,
 				target: null,
+				states: ["materialized", "invalid"],
 			},
 		])
 	})
@@ -75,6 +77,19 @@ describe("repo command", () => {
 			stderr: "ignore",
 		})
 		expect(await git.exited).toBe(0)
+		const remote = Bun.spawn(
+			[
+				"git",
+				"-C",
+				target,
+				"remote",
+				"add",
+				"origin",
+				"https://example.com/linked.git",
+			],
+			{ stdout: "ignore", stderr: "ignore" },
+		)
+		expect(await remote.exited).toBe(0)
 
 		const logs = await captureLogs(() =>
 			runTestEffect(
@@ -101,6 +116,19 @@ describe("repo command", () => {
 			stderr: "ignore",
 		})
 		expect(await git.exited).toBe(0)
+		const remote = Bun.spawn(
+			[
+				"git",
+				"-C",
+				target,
+				"remote",
+				"add",
+				"origin",
+				"https://example.com/unlink.git",
+			],
+			{ stdout: "ignore", stderr: "ignore" },
+		)
+		expect(await remote.exited).toBe(0)
 		await runTestEffect(
 			repo({
 				subcommand: "link",
@@ -120,5 +148,42 @@ describe("repo command", () => {
 		)
 
 		expect(await Bun.file(join(target, ".git/HEAD")).exists()).toBe(true)
+		expect(await Bun.file(join(root, "repos/linked")).exists()).toBe(false)
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				repo({ subcommand: "list", args: [], cwd: root, json: true }),
+			),
+		)
+		expect(
+			JSON.parse(logs[0]!).map(({ alias }: { alias: string }) => alias),
+		).toEqual(["agency", "linked"])
+	})
+
+	test("reports setup plans as JSON without mutating", async () => {
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				repositories: {
+					missing: { remote: "https://example.com/missing.git" },
+				},
+			}),
+		)
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				repo({ subcommand: "setup", args: [], cwd: root, json: true }),
+			),
+		)
+		const result = JSON.parse(logs[0]!)
+		expect(result.mode).toBe("dry-run")
+		expect(result.actions).toEqual([
+			{
+				kind: "materialize",
+				alias: "missing",
+				remote: "https://example.com/missing.git",
+				status: "planned",
+			},
+		])
+		expect(await Bun.file(join(root, "repos/missing")).exists()).toBe(false)
 	})
 })

package/src/commands/repo.ts

@@ -7,6 +7,8 @@ interface RepoOptions extends BaseCommandOptions {
 	readonly subcommand?: string
 	readonly args: readonly string[]
 	readonly json?: boolean
+	readonly apply?: boolean
+	readonly dryRun?: boolean
 }
 
 const requireArg = (args: readonly string[], index: number, usage: string) =>
@@ -19,6 +21,27 @@ export const repo = (options: RepoOptions) =>
 		const cwd = options.cwd ?? process.cwd()
 
 		switch (options.subcommand) {
+			case "setup": {
+				const result = yield* repositories.setup({
+					cwd,
+					apply: options.apply === true,
+				})
+				if (options.json) {
+					log(JSON.stringify(result, null, 2))
+					return
+				}
+				if (result.actions.length === 0) log("Repository setup is current")
+				for (const action of result.actions) {
+					log(
+						`${action.status === "applied" ? "Applied" : "Planned"} ${action.kind} '${action.alias}' from ${action.remote}`,
+					)
+				}
+				for (const issue of result.unresolved) {
+					log(`Unresolved '${issue.alias}': ${issue.message}. ${issue.action}`)
+				}
+				return
+			}
+
 			case "add": {
 				const [alias, remote] = options.args
 				if (!alias || !remote) {
@@ -58,8 +81,9 @@ export const repo = (options: RepoOptions) =>
 					return
 				}
 				for (const item of items) {
-					const detail = item.target ?? item.remote ?? item.path
-					log(`${item.alias}\t${item.kind}\t${detail}`)
+					const detail =
+						item.target ?? item.remote ?? item.declaredRemote ?? item.path
+					log(`${item.alias}\t${item.states.join(",")}\t${detail}`)
 				}
 				return
 			}
@@ -74,7 +98,7 @@ export const repo = (options: RepoOptions) =>
 				log(
 					options.json
 						? JSON.stringify(item, null, 2)
-						: `${item.alias}\t${item.kind}\t${item.target ?? item.remote ?? item.path}`,
+						: `${item.alias}\t${item.states.join(",")}\t${item.target ?? item.remote ?? item.declaredRemote ?? item.path}`,
 				)
 				return
 			}
@@ -136,7 +160,7 @@ export const repo = (options: RepoOptions) =>
 				log(
 					options.json
 						? JSON.stringify(item, null, 2)
-						: (item.remote ?? "No origin remote configured"),
+						: (item.declaredRemote ?? "No portable remote declared"),
 				)
 				return
 			}
@@ -163,7 +187,7 @@ export const repo = (options: RepoOptions) =>
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available subcommands: add, link, list, show, fetch, remove, unlink, rename, remote, verify",
+						"Subcommand is required. Available subcommands: setup, add, link, list, show, fetch, remove, unlink, rename, remote, verify",
 					),
 				)
 		}
@@ -173,17 +197,20 @@ export const help = `
 Usage: agency repo <subcommand>
 
 Subcommands:
+  setup                 Plan or apply portable repository setup
   add <alias> <remote>  Create a bare clone
   link <alias> <path>   Link an existing Git repository
   list                  List repository aliases
   show <alias>          Show a repository alias
   fetch <alias>         Fetch and prune a repository
-  remove <alias>        Remove an unused repository alias
-  unlink <alias>        Remove an unused linked alias
+  remove <alias>        Remove a declaration and local materialization
+  unlink <alias>        Remove only this machine's linked checkout
   rename <old> <new>    Rename an unused repository alias
-  remote <alias> [url]  Show or update the origin remote
+	remote <alias> [url]  Show or update the portable remote declaration
   verify <alias>        Verify repository operation
 
 Options:
+  --dry-run             Report setup changes without applying them (default)
+  --apply               Apply safe setup changes
   --json                Output repository aliases as JSON
 `

package/src/commands/status.test.ts

@@ -41,7 +41,9 @@ describe("status command", () => {
 				path: join(root, "repos/agency"),
 				kind: "repository",
 				remote: null,
+				declaredRemote: null,
 				target: null,
+				states: ["materialized", "invalid"],
 			},
 		])
 	})
@@ -58,6 +60,25 @@ describe("status command", () => {
 				silent: true,
 			}),
 		)
+		await runTestEffect(
+			task({
+				subcommand: "create",
+				args: ["finished"],
+				repo: "agency",
+				branch: "feat/finished",
+				base: "main",
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			task({
+				subcommand: "status",
+				args: ["finished", "done"],
+				cwd: root,
+				silent: true,
+			}),
+		)
 
 		const logs = await captureLogs(() =>
 			runTestEffect(
@@ -71,6 +92,7 @@ describe("status command", () => {
 		expect(logs.at(-1)).toContain(
 			"task  example  -       open    ready      agency        feat/example  absent  absent",
 		)
+		expect(logs.at(-1)).not.toContain("finished")
 	})
 
 	test("reports validation issues without requiring a decodable graph", async () => {

package/src/commands/status.ts

@@ -42,6 +42,7 @@ export const status = (options: StatusOptions = {}) =>
 
 		log(`Workbase: ${report.root}`)
 		log(`Repositories: ${repos.length}`)
+		for (const repo of repos) log(`  ${repo.alias}: ${repo.states.join(", ")}`)
 		log(`Epics: ${report.epicCount}`)
 		log(`Tasks: ${report.taskCount}`)
 		log(`Phases: ${report.phaseCount}`)

package/src/commands/sync.ts

@@ -22,15 +22,17 @@ export const sync = (options: SyncCommandOptions = {}) =>
 export const help = `
 Usage: agency sync [--dry-run | --apply] [--json]
 
-Compare declared execution state with Git worktrees, branches, references, claims,
-and GitHub pull requests. Dry-run is the default.
+Compare portable repository declarations and execution state with local Git
+repositories, worktrees, branches, references, claims, and pull requests.
+Dry-run is the default.
 
 Options:
   --dry-run                 Report planned safe transitions without changing state
   --apply                   Apply safe reconciliation transitions
   --json                    Output one versioned machine result
 
-Apply may materialize unambiguous missing checkouts, release expired claims,
+Apply may materialize declared repositories and unambiguous missing checkouts,
+adopt legacy repositories with portable origins, release expired claims,
 record a uniquely matched PR, and mark merged work done. Dirty, stale, or
 conflicting checkouts are always left unresolved.
 `

package/src/commands/work.test.ts

@@ -67,6 +67,7 @@ interface HarnessOptions {
 	readonly existingDirectories?: readonly string[]
 	readonly guardError?: Error
 	readonly readyTargetIds?: readonly string[]
+	readonly opencodeIntegrationState?: "managed" | "customized"
 }
 
 const createHarness = (options: HarnessOptions = {}) => {
@@ -215,7 +216,15 @@ const createHarness = (options: HarnessOptions = {}) => {
 	const integrations = {
 		sync: () => {
 			integrationSyncs += 1
-			return Effect.succeed({ root: "/workbase", files: [] })
+			return Effect.succeed({
+				root: "/workbase",
+				files: [
+					{
+						name: "opencode",
+						state: options.opencodeIntegrationState ?? "managed",
+					},
+				],
+			})
 		},
 	}
 	const fs = {
@@ -395,6 +404,23 @@ describe("work command", () => {
 			],
 			cwd: "/workbase/epics/delivery",
 		})
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBe(
+			"/workbase/.opencode/opencode.jsonc",
+		)
+		expect(
+			JSON.parse(harness.launchEnvironments[0]!.OPENCODE_CONFIG_CONTENT!),
+		).toEqual({
+			permission: {
+				external_directory: { "/workbase/**": "allow" },
+				edit: { "*": "deny" },
+			},
+			agent: {
+				build: { permission: { edit: { "*": "deny" } } },
+				plan: { permission: { edit: { "*": "deny" } } },
+				general: { permission: { edit: { "*": "deny" } } },
+				explore: { permission: { edit: { "*": "deny" } } },
+			},
+		})
 	})
 
 	test("resolves an existing positional path before treating it as a task ID", async () => {
@@ -444,6 +470,9 @@ describe("work command", () => {
 			],
 			cwd: "/workbase/tasks/delivery",
 		})
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBe(
+			"/workbase/.opencode/opencode.jsonc",
+		)
 	})
 
 	test("infers a phase from a nested checkout directory", async () => {
@@ -472,6 +501,9 @@ describe("work command", () => {
 		expect(harness.statusUpdates).toEqual([
 			"phase:example:implementation:working",
 		])
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBe(
+			"/workbase/.opencode/opencode.jsonc",
+		)
 	})
 
 	test("infers a single-phase task from a nested checkout directory", async () => {
@@ -485,6 +517,9 @@ describe("work command", () => {
 
 		expect(harness.events[0]).toBe("materialize")
 		expect(harness.launches[0]?.cwd).toBe(singlePhaseWorkspace.writablePath)
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBe(
+			"/workbase/.opencode/opencode.jsonc",
+		)
 	})
 
 	test("selects a target when no directory is provided", async () => {
@@ -665,6 +700,9 @@ describe("work command", () => {
 			},
 		])
 		expect(harness.statusUpdates).toEqual(["task:example:working"])
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBe(
+			"/workbase/.opencode/opencode.jsonc",
+		)
 		expect(harness.progressUpdates).toEqual([
 			"start:Preparing workspace...",
 			"succeed:Workspace ready",
@@ -768,6 +806,40 @@ describe("work command", () => {
 		expect(printed.environment.API_TOKEN).toBeUndefined()
 	})
 
+	test("prints the runtime OpenCode integration config", async () => {
+		const harness = createHarness()
+		const output = await captureLogs(() =>
+			harness.run({ taskId: "example", opencode: true, printCommand: true }),
+		)
+		const printed = JSON.parse(output.join("\n"))
+
+		expect(printed.environment.OPENCODE_CONFIG).toBe(
+			"/workbase/.opencode/opencode.jsonc",
+		)
+		expect(JSON.parse(printed.environment.OPENCODE_CONFIG_CONTENT)).toEqual({
+			permission: {
+				external_directory: { "/workbase/**": "allow" },
+				edit: { "../**": "deny" },
+			},
+			agent: {
+				build: { permission: { edit: { "../**": "deny" } } },
+				plan: { permission: { edit: { "../**": "deny" } } },
+				general: { permission: { edit: { "../**": "deny" } } },
+				explore: { permission: { edit: { "../**": "deny" } } },
+			},
+		})
+	})
+
+	test("does not override customized OpenCode access policy", async () => {
+		const harness = createHarness({ opencodeIntegrationState: "customized" })
+		await harness.run({ taskId: "example", opencode: true })
+
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBeUndefined()
+		expect(
+			harness.launchEnvironments[0]?.OPENCODE_CONFIG_CONTENT,
+		).toBeUndefined()
+	})
+
 	test("automatically falls back to Claude", async () => {
 		const harness = createHarness({ available: { opencode: false } })
 
@@ -779,6 +851,7 @@ describe("work command", () => {
 			args: ["claude", "Start the task. Read /workbase/tasks/example/TASK.md."],
 			cwd: singlePhaseWorkspace.writablePath,
 		})
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBeUndefined()
 	})
 
 	test("does not fall back when OpenCode is explicitly required", async () => {

package/src/commands/work.ts

@@ -1,5 +1,5 @@
 import { Effect } from "effect"
-import { dirname, isAbsolute, relative, resolve, sep } from "node:path"
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import type { BaseCommandOptions } from "../utils/command"
 import { WorktreeService } from "../services/WorktreeService"
 import { FileSystemService } from "../services/FileSystemService"
@@ -120,7 +120,10 @@ export const work = (
 		const inputAllowed = options.inputAllowed ?? true
 		const root = yield* resolveWorkbase(startPath, pickBase, inputAllowed)
 		if (!root) return
-		yield* integrations.sync(root)
+		const integration = yield* integrations.sync(root)
+		const managedOpencode = integration.files.some(
+			(file) => file.name === "opencode" && file.state === "managed",
+		)
 		const { config } = yield* workbase.loadConfig(root)
 
 		let target: WorkTarget | null = null
@@ -325,6 +328,25 @@ export const work = (
 			...resolved.environment,
 			...runnerEnvironment(runner, variables),
 		}
+		if (runner === "opencode" && managedOpencode) {
+			environment.OPENCODE_CONFIG = join(root, ".opencode", "opencode.jsonc")
+			const execution =
+				target.kind === "phase" ||
+				(target.kind === "task" && !target.multiPhase)
+			const edit = { [execution ? "../**" : "*"]: "deny" as const }
+			environment.OPENCODE_CONFIG_CONTENT = JSON.stringify({
+				permission: {
+					external_directory: { [join(root, "**")]: "allow" },
+					edit,
+				},
+				agent: {
+					build: { permission: { edit } },
+					plan: { permission: { edit } },
+					general: { permission: { edit } },
+					explore: { permission: { edit } },
+				},
+			})
+		}
 		if (options.printCommand) {
 			log(
 				JSON.stringify(
@@ -422,7 +444,8 @@ Usage: agency work [<directory-or-task-id> | --epic <epic-id>] [--runner <name>]
 Launch an agent for an epic, task, or phase. With no directory, select one
 interactively. A positional argument resolves as a directory first, then as a task
 ID. Use '.' for the current directory. Outside a workbase, select a registered
-workbase first.
+workbase first. OpenCode launches receive whole-workbase read access through the
+runtime environment; Agency context remains authoritative for writes.
 
 The prepare subcommand resolves and materializes an execution workspace without
 launching an agent or changing lifecycle status. --dry-run reports planned Git

package/src/graph-schema.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test"
+import { Schema } from "@effect/schema"
 import jsonSchema from "../schemas/agency-graph-v1.schema.json"
-import { graphJsonlRecords, type AgencyGraph } from "./graph-schema"
+import { AgencyGraph, graphJsonlRecords } from "./graph-schema"
 
 describe("graph contract", () => {
 	test("publishes the v1 JSON Schema", () => {
@@ -29,6 +30,38 @@ describe("graph contract", () => {
 	})
 
 	test("streams records that reconstruct graph semantics", () => {
+		const nodes = [
+			{
+				id: "repository:agency",
+				key: "agency",
+				kind: "repository" as const,
+				dependents: ["repository:effect"],
+				repositories: ["agency"],
+				status: null,
+				readiness: null,
+				aggregate: null,
+				data: { alias: "agency" },
+			},
+			{
+				id: "repository:effect",
+				key: "effect",
+				kind: "repository" as const,
+				dependents: [],
+				repositories: ["effect"],
+				status: null,
+				readiness: null,
+				aggregate: null,
+				data: { alias: "effect" },
+			},
+		]
+		const edges = [
+			{
+				id: "references:repository:agency:repository:effect",
+				kind: "references" as const,
+				from: "repository:agency",
+				to: "repository:effect",
+			},
+		]
 		const graph = {
 			version: 1,
 			workbase: { version: 2 },
@@ -40,8 +73,8 @@ describe("graph contract", () => {
 				kinds: [],
 			},
 			includes: [],
-			nodes: [],
-			edges: [],
+			nodes,
+			edges,
 			summary: {
 				status: "open",
 				total: 0,
@@ -54,6 +87,11 @@ describe("graph contract", () => {
 			},
 			validation: { valid: true, issues: [] },
 		} satisfies AgencyGraph
+		expect(
+			Schema.decodeUnknownSync(AgencyGraph, { onExcessProperty: "error" })(
+				graph,
+			),
+		).toEqual(graph)
 		const records = [...graphJsonlRecords(graph)]
 		const { nodes: _nodes, edges: _edges, ...metadata } = graph
 		expect(records).toEqual([
@@ -62,7 +100,17 @@ describe("graph contract", () => {
 				type: "meta",
 				graph: metadata,
 			},
-			{ version: 1, type: "end", nodeCount: 0, edgeCount: 0 },
+			...nodes.map((node) => ({
+				version: 1 as const,
+				type: "node" as const,
+				node,
+			})),
+			...edges.map((edge) => ({
+				version: 1 as const,
+				type: "edge" as const,
+				edge,
+			})),
+			{ version: 1, type: "end", nodeCount: 2, edgeCount: 1 },
 		])
 	})
 })

package/src/protocol.test.ts

@@ -53,6 +53,34 @@ describe("machine protocol", () => {
 		).rejects.toThrow("more than one result")
 	})
 
+	test("restores collection state after a command throws", async () => {
+		const originalLog = console.log
+		await expect(
+			collectCommandResult(async () => {
+				emitCommandResult("partial")
+				throw new Error("command failed")
+			}),
+		).rejects.toThrow("command failed")
+		expect(console.log).toBe(originalLog)
+
+		await expect(
+			collectCommandResult(async () => {
+				emitCommandResult("recovered")
+			}),
+		).resolves.toBe("recovered")
+	})
+
+	test("rejects nested result collectors without disrupting the outer one", async () => {
+		const result = await collectCommandResult(async () => {
+			await expect(collectCommandResult(async () => {})).rejects.toThrow(
+				"already active",
+			)
+			emitCommandResult("outer")
+		})
+
+		expect(result).toBe("outer")
+	})
+
 	test("normalizes unknown failures into stable error details", () => {
 		expect(errorEnvelope(new Error("boom"))).toEqual({
 			version: 1,
@@ -67,14 +95,15 @@ describe("machine protocol", () => {
 	})
 
 	test("preserves relevant fields from classified errors", () => {
-		expect(
-			errorEnvelope({
-				_tag: "ValidationFailedError",
-				message: "invalid workbase",
-				root: "/work/agency",
-				issues: [{ path: "TASK.md", message: "invalid status" }],
-			}),
-		).toMatchObject({
+		const validation = errorEnvelope({
+			_tag: "ValidationFailedError",
+			message: "invalid workbase",
+			cause: new Error("private cause"),
+			optional: undefined,
+			root: "/work/agency",
+			issues: [{ path: "TASK.md", message: "invalid status" }],
+		})
+		expect(validation).toMatchObject({
 			error: {
 				code: "VALIDATION_FAILED",
 				fields: {
@@ -83,6 +112,10 @@ describe("machine protocol", () => {
 				},
 			},
 		})
+		expect(Object.keys(validation.error.fields).sort()).toEqual([
+			"issues",
+			"root",
+		])
 		expect(
 			errorEnvelope({
 				_tag: "ClaimConflictError",