@markjaquith/agency 2.68.0 → 2.69.1

package/src/commands/work.test.ts

@@ -54,7 +54,8 @@ interface HarnessOptions {
 	readonly materializeError?: Error
 	readonly available?: Readonly<Record<string, boolean>>
 	readonly chooserCommand?: readonly string[]
-	readonly runners?: Record<
+	readonly agent?: "opencode2" | "opencode" | "pi" | "claude"
+	readonly agents?: Record<
 		string,
 		{
 			command: readonly [string, ...string[]]
@@ -121,6 +122,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 		},
 	}
 	const workbase = {
+		loadGlobalConfig: () => Effect.succeed({ agent: options.agent }),
 		discover: (path: string) =>
 			options.outsideWorkbase && path === "/outside"
 				? Effect.fail({
@@ -136,7 +138,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 				config: {
 					version: 2 as const,
 					chooserCommand: options.chooserCommand,
-					runners: options.runners,
+					agents: options.agents,
 				},
 			}),
 		repositoryAliases: () => Effect.succeed(["agency"]),
@@ -307,8 +309,11 @@ const createHarness = (options: HarnessOptions = {}) => {
 		commandOptions: Parameters<typeof work>[0],
 		pick: PickWorkTarget = defaultPick,
 		pickBase: PickWorkbase = defaultPickWorkbase,
-	) =>
-		Effect.runPromise(
+		preserveSession = false,
+	) => {
+		const agencySessionId = process.env.AGENCY_SESSION_ID
+		if (!preserveSession) delete process.env.AGENCY_SESSION_ID
+		return Effect.runPromise(
 			work(commandOptions, launch, pick, progress, pickBase).pipe(
 				Effect.provideService(WorktreeService, worktrees as never),
 				Effect.provideService(FileSystemService, fs as never),
@@ -319,7 +324,12 @@ const createHarness = (options: HarnessOptions = {}) => {
 				Effect.provideService(ReadinessService, readiness as never),
 				Effect.provideService(IntegrationService, integrations as never),
 			) as Effect.Effect<void, unknown, never>,
-		)
+		).finally(() => {
+			if (agencySessionId !== undefined) {
+				process.env.AGENCY_SESSION_ID = agencySessionId
+			}
+		})
+	}
 	const runPrepare = (commandOptions: Parameters<typeof workPrepare>[0]) =>
 		Effect.runPromise(
 			workPrepare(commandOptions).pipe(
@@ -805,7 +815,7 @@ describe("work command", () => {
 
 		await expect(
 			harness.run({ taskId: "example", opencode: true, claude: true }),
-		).rejects.toThrow("Cannot combine --runner, --opencode, and --claude")
+		).rejects.toThrow("Cannot combine --agent, --opencode, and --claude")
 		expect(harness.events).toEqual([])
 	})
 
@@ -897,12 +907,17 @@ describe("work command", () => {
 		const harness = createHarness({ workspace: multiPhaseWorkspace })
 		process.env.AGENCY_SESSION_ID = "existing-session"
 		try {
-			await harness.run({
-				taskId: "example",
-				phaseId: "implementation",
-				opencode: true,
-				auto: true,
-			})
+			await harness.run(
+				{
+					taskId: "example",
+					phaseId: "implementation",
+					opencode: true,
+					auto: true,
+				},
+				undefined,
+				undefined,
+				true,
+			)
 		} finally {
 			delete process.env.AGENCY_SESSION_ID
 		}
@@ -919,10 +934,10 @@ describe("work command", () => {
 		})
 	})
 
-	test("expands a named runner with shared context", async () => {
+	test("expands a named agent with shared context", async () => {
 		const harness = createHarness({
 			available: { codex: true },
-			runners: {
+			agents: {
 				custom: {
 					command: ["codex"],
 					autoCommand: ["codex", "--task", "{task}", "{prompt}"],
@@ -934,7 +949,7 @@ describe("work command", () => {
 			},
 		})
 
-		await harness.run({ taskId: "example", runner: "custom", auto: true })
+		await harness.run({ taskId: "example", agent: "custom", auto: true })
 
 		expect(harness.probes).toEqual(["codex"])
 		expect(harness.launches[0]).toEqual({
@@ -948,7 +963,7 @@ describe("work command", () => {
 			cwd: taskDirectory,
 		})
 		expect(harness.launchEnvironments[0]).toMatchObject({
-			AGENCY_RUNNER: "custom",
+			AGENCY_AGENT: "custom",
 			AGENCY_CLAIMANT: process.env.USER ?? "agency",
 			AGENCY_WORKBASE: "/workbase",
 			AGENCY_TARGET: "execution-unit:task/example",
@@ -962,7 +977,7 @@ describe("work command", () => {
 	test("prints the exact command contract without launching and omits secrets", async () => {
 		const harness = createHarness({
 			available: { agent: true },
-			runners: {
+			agents: {
 				custom: {
 					command: ["agent"],
 					autoCommand: ["agent", "{prompt}"],
@@ -977,7 +992,7 @@ describe("work command", () => {
 		const output = await captureLogs(() =>
 			harness.run({
 				taskId: "example",
-				runner: "custom",
+				agent: "custom",
 				printCommand: true,
 			}),
 		)
@@ -1078,12 +1093,12 @@ describe("work command", () => {
 
 	test("automatically falls back from OpenCode to Claude", async () => {
 		const harness = createHarness({
-			available: { opencode2: false, opencode: false },
+			available: { opencode2: false, opencode: false, pi: false },
 		})
 
 		await harness.run({ taskId: "example" })
 
-		expect(harness.probes).toEqual(["opencode2", "opencode", "claude"])
+		expect(harness.probes).toEqual(["opencode2", "opencode", "pi", "claude"])
 		expect(harness.launches[0]).toEqual({
 			cli: "claude",
 			args: ["claude"],
@@ -1091,6 +1106,38 @@ describe("work command", () => {
 		})
 	})
 
+	test("automatically falls back from OpenCode to Pi", async () => {
+		const harness = createHarness({
+			available: { opencode2: false, opencode: false },
+		})
+
+		await harness.run({ taskId: "example" })
+
+		expect(harness.probes).toEqual(["opencode2", "opencode", "pi"])
+		expect(harness.launches[0]).toMatchObject({ cli: "pi", args: ["pi"] })
+	})
+
+	test("uses the global agent before automatic detection", async () => {
+		const harness = createHarness({ agent: "pi" })
+
+		await harness.run({ taskId: "example" })
+
+		expect(harness.probes).toEqual(["pi"])
+		expect(harness.launches[0]).toMatchObject({ cli: "pi", args: ["pi"] })
+	})
+
+	test("lets an invocation agent override the global agent", async () => {
+		const harness = createHarness({ agent: "pi" })
+
+		await harness.run({ taskId: "example", agent: "claude" })
+
+		expect(harness.probes).toEqual(["claude"])
+		expect(harness.launches[0]).toMatchObject({
+			cli: "claude",
+			args: ["claude"],
+		})
+	})
+
 	test("does not fall back when OpenCode is explicitly required", async () => {
 		const harness = createHarness({ available: { opencode: false } })
 
@@ -1117,13 +1164,18 @@ describe("work command", () => {
 
 	test("fails when neither agent tool is available", async () => {
 		const harness = createHarness({
-			available: { opencode2: false, opencode: false, claude: false },
+			available: {
+				opencode2: false,
+				opencode: false,
+				pi: false,
+				claude: false,
+			},
 		})
 
 		await expect(harness.run({ taskId: "example" })).rejects.toThrow(
 			"claude CLI tool not found",
 		)
-		expect(harness.probes).toEqual(["opencode2", "opencode", "claude"])
+		expect(harness.probes).toEqual(["opencode2", "opencode", "pi", "claude"])
 		expect(harness.launches).toEqual([])
 	})
 

package/src/commands/work.ts

@@ -26,9 +26,9 @@ import {
 } from "../workbase/workbase-choice"
 import {
 	printableEnvironment,
-	resolveRunnerCommand,
-	runnerEnvironment,
-} from "../workbase/runner-command"
+	resolveAgentCommand,
+	agentEnvironment,
+} from "../workbase/agent-command"
 import {
 	assessValidationEvidence,
 	buildKickoffPlan,
@@ -44,7 +44,7 @@ export interface WorkOptions extends BaseCommandOptions {
 	readonly epicId?: string
 	readonly opencode?: boolean
 	readonly claude?: boolean
-	readonly runner?: string
+	readonly agent?: string
 	readonly printCommand?: boolean
 	readonly auto?: boolean
 	readonly force?: boolean
@@ -94,10 +94,10 @@ export const work = (
 	Effect.gen(function* () {
 		if (
 			(options.opencode && options.claude) ||
-			(options.runner && (options.opencode || options.claude))
+			(options.agent && (options.opencode || options.claude))
 		) {
 			return yield* Effect.fail(
-				new Error("Cannot combine --runner, --opencode, and --claude"),
+				new Error("Cannot combine --agent, --opencode, and --claude"),
 			)
 		}
 		const previousEnvironment = { ...process.env }
@@ -132,6 +132,7 @@ export const work = (
 		if (!root) return
 		yield* integrations.sync(root)
 		const { config } = yield* workbase.loadConfig(root)
+		const globalConfig = yield* workbase.loadGlobalConfig()
 
 		let target: WorkTarget | null = null
 		if (options.epicId) {
@@ -274,22 +275,15 @@ export const work = (
 		}
 		prompt = `Agency worker launch target: ${targetNodeId(target)}. ${prompt}`
 
-		const explicitlyRequested = Boolean(
-			options.runner ||
-			options.opencode ||
-			options.claude ||
-			process.env.AGENCY_RUNNER,
-		)
-		const defaultRunners = ["opencode2", "opencode", "claude"] as const
-		let defaultRunnerIndex = 0
-		let runner: string =
-			options.runner ??
-			process.env.AGENCY_RUNNER ??
-			(options.claude
-				? "claude"
-				: options.opencode
-					? "opencode"
-					: defaultRunners[defaultRunnerIndex]!)
+		const invocationAgent =
+			options.agent ??
+			process.env.AGENCY_AGENT ??
+			(options.claude ? "claude" : options.opencode ? "opencode" : undefined)
+		const selectedAgent = invocationAgent ?? globalConfig.agent
+		const explicitlyRequested = selectedAgent !== undefined
+		const defaultAgents = ["opencode2", "opencode", "pi", "claude"] as const
+		let defaultAgentIndex = 0
+		let agent: string = selectedAgent ?? defaultAgents[defaultAgentIndex]!
 		const claimant = process.env.AGENCY_CLAIMANT ?? process.env.USER ?? "agency"
 		const sessionId =
 			process.env.AGENCY_SESSION_ID ?? `${process.pid}-${Date.now()}`
@@ -306,9 +300,9 @@ export const work = (
 			sessionId,
 			claimRevision: "",
 		}
-		let resolved = resolveRunnerCommand(
-			runner,
-			config.runners,
+		let resolved = resolveAgentCommand(
+			agent,
+			config.agents,
 			variables,
 			resume,
 			options.auto,
@@ -320,12 +314,12 @@ export const work = (
 		while (
 			available.exitCode !== 0 &&
 			!explicitlyRequested &&
-			defaultRunnerIndex < defaultRunners.length - 1
+			defaultAgentIndex < defaultAgents.length - 1
 		) {
-			runner = defaultRunners[++defaultRunnerIndex]!
-			resolved = resolveRunnerCommand(
-				runner,
-				config.runners,
+			agent = defaultAgents[++defaultAgentIndex]!
+			resolved = resolveAgentCommand(
+				agent,
+				config.agents,
 				variables,
 				resume,
 				options.auto,
@@ -336,9 +330,9 @@ export const work = (
 		if (available.exitCode !== 0) {
 			return yield* Effect.fail(new Error(`${cli} CLI tool not found`))
 		}
-		resolved = resolveRunnerCommand(
-			runner,
-			config.runners,
+		resolved = resolveAgentCommand(
+			agent,
+			config.agents,
 			variables,
 			resume,
 			options.auto,
@@ -346,7 +340,7 @@ export const work = (
 		cli = resolved.argv[0]!
 		const environment = {
 			...resolved.environment,
-			...runnerEnvironment(runner, variables),
+			...agentEnvironment(agent, variables),
 		}
 		if (writablePath) environment.AGENCY_WRITABLE_CHECKOUT = writablePath
 		if (options.printCommand) {
@@ -579,7 +573,7 @@ export const workPrepare = (options: WorkOptions = {}) =>
 	})
 
 export const help = `
-Usage: agency work [<directory-or-task-id> | --epic <epic-id>] [--runner <name>] [--auto]
+Usage: agency work [<directory-or-task-id> | --epic <epic-id>] [--agent <name>] [--auto]
        agency work prepare [target] [--evidence <json-or-path>] [--dry-run] [--json]
 
 Launch an agent for an epic, task, or phase. With no directory, select one
@@ -587,7 +581,7 @@ interactively. A positional argument resolves as a directory first, then as a ta
 ID. Use '.' for the current directory. Outside a workbase, select a registered
 workbase first. Managed OpenCode launches receive whole-workbase access through
 Agency's project plugin; Agency context remains authoritative for writes. Automatic
-runner discovery checks opencode2, opencode, then claude.
+agent discovery checks opencode2, opencode, pi, then claude.
 
 The prepare subcommand resolves and materializes an execution workspace without
 launching an agent or changing lifecycle status. --dry-run reports planned Git
@@ -603,8 +597,8 @@ Options:
   --phase <id>         Work on a phase selected with --task
   --workbase <target>  Select a workbase by ID, name, or path
   --cwd <path>         Resolve context from a specific directory
-  --runner <name>      Select a configured runner or built-in preset
-  --auto               Send the generated context prompt to the runner
+  --agent <name>      Select a configured agent or built-in preset
+  --auto               Send the generated context prompt to the agent
   --print-command      Print cwd, argv, and non-secret environment without launch
   --opencode           Require the OpenCode preset
   --claude             Require the Claude Code preset

package/src/protocol.test.ts

@@ -124,7 +124,7 @@ describe("machine protocol", () => {
 				currentRevision: "a".repeat(64),
 				claim: {
 					claimant: "orchestrator",
-					runner: "agent",
+					agent: "agent",
 					sessionId: "job-1",
 					startedAt: "2026-07-17T12:00:00.000Z",
 					targetRevision: "0".repeat(64),
@@ -137,7 +137,7 @@ describe("machine protocol", () => {
 				retryable: true,
 				fields: {
 					target: "task 'example'",
-					claim: { runner: "agent", sessionId: "job-1" },
+					claim: { agent: "agent", sessionId: "job-1" },
 				},
 			},
 		})

package/src/services/ArchiveBulkService.test.ts

@@ -324,7 +324,7 @@ describe("ArchiveService bulk task archive", () => {
 				`status: dropped
 claim:
   claimant: orchestrator
-  runner: opencode
+  agent: opencode
   sessionId: task-session
   startedAt: 2026-08-07T00:00:00.000Z
   targetRevision: ${"a".repeat(64)}
@@ -373,7 +373,7 @@ claim:
 				`status: dropped
 claim:
   claimant: orchestrator
-  runner: opencode
+  agent: opencode
   sessionId: phase-session
   startedAt: 2026-08-07T00:00:00.000Z
   targetRevision: ${"b".repeat(64)}

package/src/services/ClaimService.test.ts

@@ -56,7 +56,7 @@ describe("claim service", () => {
 						{
 							taskId: "single",
 							claimant: "orchestrator-1",
-							runner: "agent-1",
+							agent: "agent-1",
 							sessionId,
 							revision,
 							now,
@@ -79,7 +79,7 @@ describe("claim service", () => {
 
 		expect(acquired.claim).toEqual({
 			claimant: "orchestrator-1",
-			runner: "agent-1",
+			agent: "agent-1",
 			sessionId: "session-1",
 			startedAt: "2026-07-17T12:00:00.000Z",
 			targetRevision: initial.revision,
@@ -315,7 +315,7 @@ describe("claim service", () => {
 							taskId: "multi",
 							phaseId: "implementation",
 							claimant: "orchestrator",
-							runner: "agent",
+							agent: "agent",
 							sessionId: "phase-session",
 							revision: phase.revision,
 						},

package/src/services/ClaimService.ts

@@ -70,7 +70,7 @@ interface ClaimInput {
 	readonly taskId: string
 	readonly phaseId?: string
 	readonly claimant: string
-	readonly runner: string
+	readonly agent: string
 	readonly sessionId: string
 	readonly revision: string
 	readonly expiresAt?: string
@@ -401,7 +401,7 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 				Effect.gen(function* () {
 					for (const [label, value] of [
 						["Claimant", input.claimant],
-						["Runner", input.runner],
+						["Agent", input.agent],
 						["Session ID", input.sessionId],
 					] as const) {
 						assertIdentity(label, value)
@@ -435,7 +435,7 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 										target: inspected.target.label,
 										currentRevision: input.revision,
 										claim: data.claim,
-										message: `${inspected.target.label} is claimed by '${data.claim.runner}'`,
+										message: `${inspected.target.label} is claimed by '${data.claim.agent}'`,
 									})
 								}
 								if (
@@ -457,7 +457,7 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 								}
 								const claim: ClaimRecord = {
 									claimant: input.claimant.trim(),
-									runner: input.runner.trim(),
+									agent: input.agent.trim(),
 									sessionId: input.sessionId.trim(),
 									startedAt: operationTime.toISOString(),
 									targetRevision: input.revision,

package/src/services/DoctorService.ts

@@ -138,16 +138,16 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 					const versionControlAvailable =
 						gitAvailable && (config.vcs !== "jj" || jjAvailable)
 					yield* tool(
-						"capability.runner.opencode",
+						"capability.agent.opencode",
 						"opencode",
 						"optional",
-						"OpenCode runner",
+						"OpenCode agent",
 					)
 					yield* tool(
-						"capability.runner.claude",
+						"capability.agent.claude",
 						"claude",
 						"optional",
-						"Claude runner",
+						"Claude agent",
 					)
 
 					const configuredCommands: readonly (readonly [
@@ -194,43 +194,43 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 										]
 									: [],
 						),
-						...Object.entries(config.runners ?? {}).map(
-							([name, runner]) =>
+						...Object.entries(config.agents ?? {}).map(
+							([name, agent]) =>
 								[
-									`integration.runner.${name}`,
-									runner.command,
-									`Configured runner '${name}'`,
+									`integration.agent.${name}`,
+									agent.command,
+									`Configured agent '${name}'`,
 								] as const,
 						),
-						...Object.entries(config.runners ?? {}).flatMap(([name, runner]) =>
-							runner.autoCommand
+						...Object.entries(config.agents ?? {}).flatMap(([name, agent]) =>
+							agent.autoCommand
 								? [
 										[
-											`integration.runner.${name}.auto`,
-											runner.autoCommand,
-											`Configured runner '${name}' auto`,
+											`integration.agent.${name}.auto`,
+											agent.autoCommand,
+											`Configured agent '${name}' auto`,
 										] as const,
 									]
 								: [],
 						),
-						...Object.entries(config.runners ?? {}).flatMap(([name, runner]) =>
-							runner.resumeCommand
+						...Object.entries(config.agents ?? {}).flatMap(([name, agent]) =>
+							agent.resumeCommand
 								? [
 										[
-											`integration.runner.${name}.resume`,
-											runner.resumeCommand,
-											`Configured runner '${name}' resume`,
+											`integration.agent.${name}.resume`,
+											agent.resumeCommand,
+											`Configured agent '${name}' resume`,
 										] as const,
 									]
 								: [],
 						),
-						...Object.entries(config.runners ?? {}).flatMap(([name, runner]) =>
-							runner.autoResumeCommand
+						...Object.entries(config.agents ?? {}).flatMap(([name, agent]) =>
+							agent.autoResumeCommand
 								? [
 										[
-											`integration.runner.${name}.auto-resume`,
-											runner.autoResumeCommand,
-											`Configured runner '${name}' auto resume`,
+											`integration.agent.${name}.auto-resume`,
+											agent.autoResumeCommand,
+											`Configured agent '${name}' auto resume`,
 										] as const,
 									]
 								: [],

package/src/services/IntegrationService.test.ts

@@ -131,7 +131,7 @@ describe("IntegrationService", () => {
 			"call Herdr help, skill, or CLI discovery",
 		)
 		expect(managedWorkbaseAgents).toContain("exactly one final")
-		expect(managedWorkbaseAgents).toContain("leave the runner in the")
+		expect(managedWorkbaseAgents).toContain("leave the agent in the")
 	})
 
 	test("generates a dynamic workbase plugin", () => {
@@ -777,7 +777,7 @@ describe("IntegrationService", () => {
 		expect(config.agent.agency.hidden).toBeUndefined()
 		expect(config.agent.agency.steps).toBeUndefined()
 		expect(config.agent.agency.prompt).toContain(
-			"verify that the runner started successfully",
+			"verify that the agent started successfully",
 		)
 		expect(config.agent.agency.prompt).toContain(
 			"return without waiting for the task to finish",

package/src/services/ReadinessService.test.ts

@@ -235,7 +235,7 @@ pr: null
 status: working
 claim:
   claimant: orchestrator
-  runner: opencode
+  agent: opencode
   sessionId: session-1
   startedAt: 2026-07-20T00:00:00.000Z
   targetRevision: ${"a".repeat(64)}

package/src/services/ReviewService.test.ts

@@ -275,7 +275,7 @@ describe("ReviewService", () => {
 						{
 							taskId: "review",
 							claimant: "reviewer",
-							runner: "opencode",
+							agent: "opencode",
 							sessionId: "session",
 							revision: task.revision,
 						},
@@ -311,7 +311,7 @@ describe("ReviewService", () => {
 						{
 							taskId: "review",
 							claimant: "reviewer",
-							runner: "opencode",
+							agent: "opencode",
 							sessionId: "active",
 							revision: task.revision,
 						},