@markjaquith/agency 2.68.0 → 2.69.1

package/src/services/SyncService.test.ts

@@ -238,7 +238,7 @@ pr: null
 						{
 							taskId: "example",
 							claimant: "orchestrator",
-							runner: "agent",
+							agent: "agent",
 							sessionId: "session-1",
 							revision: inspected.revision,
 							expiresAt: "2099-01-01T00:00:00.000Z",
@@ -523,7 +523,7 @@ process.stdout.write(${JSON.stringify(JSON.stringify(record))})
 						{
 							taskId: "finished-claim",
 							claimant: "orchestrator",
-							runner: "agent",
+							agent: "agent",
 							sessionId: "session-1",
 							revision: initial.revision,
 						},
@@ -575,6 +575,8 @@ process.stdout.write(${JSON.stringify(JSON.stringify(record))})
 	})
 
 	test("materializes missing workspaces but leaves branch conflicts unresolved", async () => {
+		await Bun.write(join(root, "bin", "gh"), "#!/bin/sh\nprintf '[]\\n'\n")
+		await chmod(join(root, "bin", "gh"), 0o755)
 		for (const [id, branch] of [
 			["missing", "feat/missing"],
 			["conflict", "feat/conflict"],
@@ -649,6 +651,158 @@ process.stdout.write(${JSON.stringify(JSON.stringify(record))})
 		).toBe(false)
 	})
 
+	test("reconciles a recorded merged PR without materializing an absent checkout", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "recorded-merged",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await git(
+			["remote", "set-url", "origin", "git@github.com:example/agency.git"],
+			join(root, "repos/agency"),
+		)
+		await runTestEffect(
+			PullRequestService.pipe(
+				Effect.flatMap((service) =>
+					service.setUrl(
+						"recorded-merged",
+						undefined,
+						"https://github.com/example/agency/pull/42",
+						root,
+					),
+				),
+			),
+		)
+
+		const applied = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({
+						cwd: root,
+						apply: true,
+						taskId: "recorded-merged",
+					}),
+				),
+			),
+		)
+		expect(applied.changes.map((change) => change.kind)).toEqual([
+			"record-pr",
+			"mark-done",
+		])
+		expect(applied.executions[0]?.checkouts).toEqual([])
+		expect(
+			await Bun.file(join(root, "tasks/recorded-merged/code/agency")).exists(),
+		).toBe(false)
+	})
+
+	test("reconciles a uniquely discovered merged PR without materializing", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "discovered-merged",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await git(
+			["remote", "set-url", "origin", "git@github.com:example/agency.git"],
+			join(root, "repos/agency"),
+		)
+
+		const applied = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({
+						cwd: root,
+						apply: true,
+						taskId: "discovered-merged",
+					}),
+				),
+			),
+		)
+		expect(applied.changes.map((change) => change.kind)).toEqual([
+			"record-pr",
+			"mark-done",
+		])
+		expect(applied.executions[0]?.checkouts).toEqual([])
+		expect(
+			await Bun.file(
+				join(root, "tasks/discovered-merged/code/agency"),
+			).exists(),
+		).toBe(false)
+	})
+
+	test("materializes when discovered PR evidence is ambiguous", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "ambiguous",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const gh = await Bun.file(join(root, "bin", "gh")).text()
+		await Bun.write(
+			join(root, "bin", "gh"),
+			gh
+				.replace('[{"number":42', '[{"number":42')
+				.replace(
+					"]\nJSON\n",
+					`,{\"number\":43,\"state\":\"MERGED\",\"title\":\"Ship again\",\"isDraft\":false,\"headRefName\":\"feat/example\",\"baseRefName\":\"main\",\"headRepository\":{\"nameWithOwner\":\"example/agency\"},\"url\":\"https://github.com/example/agency/pull/43\",\"mergedAt\":\"2100-01-01T00:00:00Z\",\"mergeCommit\":{\"oid\":\"def\"},\"mergeable\":\"MERGEABLE\"}]\nJSON\n`,
+				),
+		)
+
+		const applied = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({
+						cwd: root,
+						apply: true,
+						taskId: "ambiguous",
+					}),
+				),
+			),
+		)
+		expect(applied.unresolved).toContainEqual(
+			expect.objectContaining({ kind: "multiple-prs" }),
+		)
+		expect(applied.changes).toContainEqual(
+			expect.objectContaining({ kind: "materialize-workspace" }),
+		)
+		expect(
+			await Bun.file(
+				join(root, "tasks/ambiguous/code/agency/README.md"),
+			).text(),
+		).toBe("example\n")
+	})
+
 	test("leaves a missing checkout registration unresolved", async () => {
 		await runTestEffect(
 			TaskService.pipe(

package/src/services/SyncService.ts

@@ -162,6 +162,46 @@ const commandErrorSummary = (stderr: string, fallback: string) =>
 		.map((line) => line.trim())
 		.find(Boolean) ?? fallback
 
+interface PullRequestQuery {
+	readonly remoteUrl: string | null
+	readonly remoteRepository: string
+	readonly result:
+		| {
+				readonly exitCode: number
+				readonly stdout: string
+				readonly stderr: string
+		  }
+		| undefined
+}
+
+const mergedPullRequestFromGitHub = (
+	data: ExecutionData,
+	query: PullRequestQuery | undefined,
+) => {
+	if (!query?.result || query.result.exitCode !== 0) return null
+	const existing = data.pr ? normalizePullRequestRecord(data.pr) : null
+	const details = existing
+		? [parseJson<Record<string, unknown>>(query.result.stdout, {})]
+		: parseJson<Record<string, unknown>[]>(query.result.stdout, []).filter(
+				(item) =>
+					item.headRefName === data.branch && item.baseRefName === data.base,
+			)
+	if (details.length !== 1) return null
+	const current = recordFromGitHubJson(details[0]!)
+	if (
+		current.merged !== true ||
+		current.headRepository?.toLowerCase() !==
+			query.remoteRepository.toLowerCase() ||
+		current.headBranch !== data.branch ||
+		current.baseRepository?.toLowerCase() !==
+			current.repository.toLowerCase() ||
+		current.baseBranch !== data.base
+	) {
+		return null
+	}
+	return current
+}
+
 export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 	sync: () => ({
 		reconcile: (
@@ -463,6 +503,14 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 					let revision = record.revision
 					const codePath = join(dirname(record.path), "code")
 					const checkoutStates: CheckoutState[] = []
+					const query = prQueries.get(record.key)
+					const remoteMergedPr = config.delivery
+						? null
+						: mergedPullRequestFromGitHub(data, query)
+					const skipCheckoutReconciliation =
+						remoteMergedPr !== null &&
+						data.claim?.state !== "active" &&
+						!data.completion
 					let materialize = false
 					let workspaceConflict = false
 					const declared: readonly (
@@ -473,7 +521,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 						...(data.repos ?? []),
 					]
 
-					for (const checkout of declared) {
+					for (const checkout of skipCheckoutReconciliation ? [] : declared) {
 						const repositoryPath = join(root, "repos", checkout.repo)
 						const checkoutPath = join(codePath, checkout.repo)
 						const kind = "branch" in checkout ? "writable" : "reference"
@@ -811,7 +859,11 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 						state: "none",
 					}
 					let prConflict = false
-					const query = prQueries.get(record.key)!
+					if (!query) {
+						return yield* new SyncError({
+							message: `Missing pull request query for '${record.key}'`,
+						})
+					}
 					const { remoteUrl, remoteRepository } = query
 
 					if (config.delivery && !remoteUrl) {

package/src/services/VcsMigrationService.test.ts

@@ -288,7 +288,7 @@ describe("VcsMigrationService", () => {
 						{
 							taskId: "example",
 							claimant: "orchestrator",
-							runner: "agent",
+							agent: "agent",
 							sessionId: "session-1",
 							revision: inspected.revision,
 						},

package/src/services/WorkbaseService.test.ts

@@ -41,6 +41,37 @@ describe("WorkbaseService", () => {
 		).toBe(false)
 	})
 
+	test("loads and validates the global agent", async () => {
+		const configDirectory = join(root, "config")
+		await write(
+			configDirectory,
+			"agency/agency.json",
+			JSON.stringify({ agent: "pi" }),
+		)
+
+		const config = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) => service.loadGlobalConfig(configDirectory)),
+			),
+		)
+		expect(config).toEqual({ agent: "pi" })
+
+		await write(
+			configDirectory,
+			"agency/agency.json",
+			JSON.stringify({ agent: "codex" }),
+		)
+		await expect(
+			runTestEffect(
+				WorkbaseService.pipe(
+					Effect.flatMap((service) =>
+						service.loadGlobalConfig(configDirectory),
+					),
+				),
+			),
+		).rejects.toThrow("Invalid global Agency configuration")
+	})
+
 	test("treats declared but missing repositories as valid aliases", async () => {
 		await write(
 			root,
@@ -415,13 +446,13 @@ status: done
 		).rejects.toThrow("Repository 'agency'")
 	})
 
-	test("rejects an unknown runner command placeholder", async () => {
+	test("rejects an unknown agent command placeholder", async () => {
 		await write(
 			root,
 			"agency.json",
 			JSON.stringify({
 				version: 2,
-				runners: { custom: { command: ["agent", "{unknown}"] } },
+				agents: { custom: { command: ["agent", "{unknown}"] } },
 			}),
 		)
 

package/src/services/WorkbaseService.ts

@@ -8,6 +8,7 @@ import { parseFrontmatter } from "../workbase/frontmatter"
 import {
 	EntityId,
 	EpicFrontmatter,
+	GlobalConfig,
 	LegacyWorkbaseRegistry,
 	PhaseFrontmatter,
 	TaskFrontmatter,
@@ -22,7 +23,7 @@ import {
 import { validateWorktreeCreateCommand } from "../workbase/worktree-command"
 import { validateWorkspaceCreateCommand } from "../workbase/workspace-command"
 import { validatePostCheckoutCommand } from "../workbase/checkout-command"
-import { validateRunners } from "../workbase/runner-command"
+import { validateAgents } from "../workbase/agent-command"
 import { findDependencyCycles } from "../workbase/dependency-graph"
 import { validateDelivery } from "../workbase/delivery-command"
 import { preferredVersionControl } from "../workbase/version-control"
@@ -90,6 +91,15 @@ const registryPath = (configDirectory?: string) =>
 		"workbases.json",
 	)
 
+const globalConfigPath = (configDirectory?: string) =>
+	join(
+		configDirectory ||
+			process.env.XDG_CONFIG_HOME ||
+			join(homedir(), ".config"),
+		"agency",
+		"agency.json",
+	)
+
 const registrationId = (path: string) =>
 	`wb-${new Bun.CryptoHasher("sha256").update(path).digest("hex").slice(0, 12)}`
 
@@ -178,6 +188,32 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 	"WorkbaseService",
 	{
 		sync: () => ({
+			loadGlobalConfig: (configDirectory?: string) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const path = globalConfigPath(configDirectory)
+					if (!(yield* fs.exists(path))) return {}
+					const content = yield* fs.readFile(path)
+					let input: unknown
+					try {
+						input = JSON.parse(content)
+					} catch (cause) {
+						return yield* new WorkbaseConfigError({
+							path,
+							message: `Invalid JSON in global Agency configuration ${path}`,
+							cause,
+						})
+					}
+					const decoded = decode(GlobalConfig, input)
+					if (!decoded.success) {
+						return yield* new WorkbaseConfigError({
+							path,
+							message: `Invalid global Agency configuration in ${path}:\n${decoded.error}`,
+						})
+					}
+					return decoded.value
+				}),
+
 			initialize: (path: string = process.cwd()) =>
 				Effect.gen(function* () {
 					const fs = yield* FileSystemService
@@ -309,7 +345,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 									}
 								}
 								try {
-									validateRunners(decoded.value.runners)
+									validateAgents(decoded.value.agents)
 									validateDelivery(decoded.value.delivery)
 								} catch (cause) {
 									return yield* new WorkbaseConfigError({
@@ -317,7 +353,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 										message:
 											cause instanceof Error
 												? cause.message
-												: "Invalid runner configuration",
+												: "Invalid agent configuration",
 									})
 								}
 								return current

package/src/workbase/AGENTS.md

@@ -121,7 +121,7 @@ Do not rediscover commands that this recipe or a known-current
    prepare the task with
    `agency work prepare <slug> --evidence <creation-json> --dry-run --json`, then
    execute the returned plan through `task-document-split` to prepare the
-   checkout and open or reuse the background tab. Stop before `runner-start`.
+   checkout and open or reuse the background tab. Stop before `agent-start`.
 3. For work/launch/start/kickoff intent, run that same preflight and execute its
    ordered kickoff steps. The plan owns worktree dry-run/preparation, a
    retry-safe background Herdr tab, the side-by-side task document,
@@ -131,8 +131,8 @@ Do not rediscover commands that this recipe or a known-current
    `agency-kickoff-v1` capability, execute the supplied actions directly. Do not
    call Herdr help, skill, or CLI discovery. If capability/version evidence is
    absent or stale, discovery is the compatibility path; then resume the same
-   idempotency key rather than creating another tab, checkout, or runner.
-5. After the one final context verification succeeds, leave the runner in the
+   idempotency key rather than creating another tab, checkout, or agent.
+5. After the one final context verification succeeds, leave the agent in the
    background and stop. Do not inspect, poll, or babysit it unless the user asks.
 
 Validation evidence is a local, auditable optimization, not authority. Preflight
@@ -153,12 +153,12 @@ IDs and remediation commands before retrying.
 
 `agency work` is the human launch flow: it reconciles managed integration,
 selects work, checks readiness, prepares checkouts, marks execution work
-`working` without creating a claim, and starts the runner. Epic and multi-phase
+`working` without creating a claim, and starts the agent. Epic and multi-phase
 task launches remain orchestration-only. External orchestrators instead claim
-an execution unit, launch and monitor their runner separately, and finish or
+an execution unit, launch and monitor their agent separately, and finish or
 release the claim with the current document revision.
 
-An Agency-launched runner receives process-local worker identity through both
+An Agency-launched agent receives process-local worker identity through both
 the `AGENCY_SESSION_ID` and `AGENCY_TARGET` environment variables and a generated
 prompt beginning `Agency worker launch target: <target>.` Treat either form as
 launch evidence only after `agency context . --json` confirms the same target,
@@ -166,7 +166,7 @@ document paths, valid context, and expected write authority. Once confirmed,
 perform the assigned work directly and never invoke `agency work` to start the
 same target again.
 
-Some runner clients attach to a long-lived process and may not preserve launch
+Some agent clients attach to a long-lived process and may not preserve launch
 environment variables. If the variables and prompt marker are absent, fail safe
 when the initial instruction is a generated `Start`, `Continue`, or `Work on`
 prompt whose absolute document paths match the current directory and the active,

package/src/workbase/{runner-command.test.ts → agent-command.test.ts}

@@ -1,10 +1,10 @@
 import { describe, expect, test } from "bun:test"
 import {
 	printableEnvironment,
-	resolveRunnerCommand,
-	runnerEnvironment,
-	validateRunners,
-} from "./runner-command"
+	resolveAgentCommand,
+	agentEnvironment,
+	validateAgents,
+} from "./agent-command"
 
 const variables = {
 	prompt: "Read the task.",
@@ -17,45 +17,55 @@ const variables = {
 	claimRevision: "revision-1",
 }
 
-describe("runner commands", () => {
+describe("agent commands", () => {
 	test("uses promptless interactive commands for built-in presets", () => {
 		expect(
-			resolveRunnerCommand("opencode2", undefined, variables, false).argv,
+			resolveAgentCommand("opencode2", undefined, variables, false).argv,
 		).toEqual(["opencode2"])
 		expect(
-			resolveRunnerCommand("opencode2", undefined, variables, true).argv,
+			resolveAgentCommand("opencode2", undefined, variables, true).argv,
 		).toEqual(["opencode2", "--continue"])
 		expect(
-			resolveRunnerCommand("opencode", undefined, variables, false).argv,
+			resolveAgentCommand("opencode", undefined, variables, false).argv,
 		).toEqual(["opencode"])
 		expect(
-			resolveRunnerCommand("opencode", undefined, variables, true).argv,
+			resolveAgentCommand("opencode", undefined, variables, true).argv,
 		).toEqual(["opencode", "--continue"])
+		expect(resolveAgentCommand("pi", undefined, variables, false).argv).toEqual(
+			["pi"],
+		)
+		expect(resolveAgentCommand("pi", undefined, variables, true).argv).toEqual([
+			"pi",
+			"--continue",
+		])
 		expect(
-			resolveRunnerCommand("claude", undefined, variables, true).argv,
+			resolveAgentCommand("claude", undefined, variables, true).argv,
 		).toEqual(["claude", "--continue"])
 	})
 
 	test("uses autonomous commands when a prompt is requested", () => {
 		expect(
-			resolveRunnerCommand("opencode2", undefined, variables, false, true).argv,
+			resolveAgentCommand("opencode2", undefined, variables, false, true).argv,
 		).toEqual(["opencode2", "--prompt", "Read the task."])
 		expect(
-			resolveRunnerCommand("opencode2", undefined, variables, true, true).argv,
+			resolveAgentCommand("opencode2", undefined, variables, true, true).argv,
 		).toEqual(["opencode2", "--continue", "--prompt", "Read the task."])
 		expect(
-			resolveRunnerCommand("opencode", undefined, variables, false, true).argv,
+			resolveAgentCommand("opencode", undefined, variables, false, true).argv,
 		).toEqual(["opencode", "--prompt", "Read the task."])
 		expect(
-			resolveRunnerCommand("opencode", undefined, variables, true, true).argv,
+			resolveAgentCommand("opencode", undefined, variables, true, true).argv,
 		).toEqual(["opencode", "--continue", "--prompt", "Read the task."])
 		expect(
-			resolveRunnerCommand("claude", undefined, variables, true, true).argv,
+			resolveAgentCommand("pi", undefined, variables, false, true).argv,
+		).toEqual(["pi", "Read the task."])
+		expect(
+			resolveAgentCommand("claude", undefined, variables, true, true).argv,
 		).toEqual(["claude", "--continue", "Read the task."])
 	})
 
 	test("expands configured argv and environment without a shell", () => {
-		const resolved = resolveRunnerCommand(
+		const resolved = resolveAgentCommand(
 			"custom",
 			{
 				custom: {
@@ -79,33 +89,33 @@ describe("runner commands", () => {
 		})
 	})
 
-	test("rejects --auto for configured runners without an auto command", () => {
+	test("rejects --auto for configured agents without an auto command", () => {
 		expect(() =>
-			resolveRunnerCommand(
+			resolveAgentCommand(
 				"custom",
 				{ custom: { command: ["agent"] } },
 				variables,
 				false,
 				true,
 			),
-		).toThrow("Runner 'custom' does not support --auto")
+		).toThrow("Agent 'custom' does not support --auto")
 	})
 
 	test("rejects unknown placeholders", () => {
 		expect(() =>
-			validateRunners({ custom: { command: ["agent", "{unknown}"] } }),
-		).toThrow("Unknown runner 'custom' placeholder: {unknown}")
+			validateAgents({ custom: { command: ["agent", "{unknown}"] } }),
+		).toThrow("Unknown agent 'custom' placeholder: {unknown}")
 	})
 
 	test("provides normalized Agency environment and filters secret values", () => {
 		const environment = {
-			...runnerEnvironment("custom", variables),
+			...agentEnvironment("custom", variables),
 			VISIBLE: "yes",
 			ACCESS_TOKEN: "secret",
 		}
 
 		expect(environment).toMatchObject({
-			AGENCY_RUNNER: "custom",
+			AGENCY_AGENT: "custom",
 			AGENCY_CLAIMANT: "orchestrator",
 			AGENCY_SESSION_ID: "session-1",
 			AGENCY_WORKBASE: "/workbase",