@markjaquith/agency 2.65.1 → 2.66.0

package/README.md

@@ -347,8 +347,10 @@ external effects the failed invocation may have completed.
 
 ### Agent Runners
 
-OpenCode and Claude Code are built-in runner presets. Select either preset or a
-configured runner with `agency work --runner <name>`. A launch is fresh unless
+OpenCode (`opencode2` and `opencode`) and Claude Code are built-in runner presets.
+Without an explicit runner, Agency uses the first available executable in this
+order: `opencode2`, `opencode`, then `claude`. Select a preset or configured
+runner with `agency work --runner <name>`. A launch is fresh unless
 `AGENCY_SESSION_ID` is already set; resumed launches use the runner's
 `resumeCommand` when configured. The built-in presets use `--continue` only for
 resumed launches. By default Agency opens the runner without a prompt. `--auto`
@@ -399,8 +401,9 @@ to the receiving OpenCode session, injects an explicit active-worker system
 instruction, and restores Agency identity for that session's shell environment.
 This session bridge is necessary because an OpenCode client can attach to a
 long-lived server process that did not inherit the client's launch environment.
-The `opencode` runner remains rooted in its task or epic working directory so
-the workbase `AGENTS.md` and managed OpenCode config are discovered normally.
+The `opencode2` and `opencode` runners remain rooted in their task or epic
+working directory so the workbase `AGENTS.md` and managed OpenCode config are
+discovered normally.
 Agency's managed OpenCode plugin grants the active workbase external-directory
 access and adds existing checkout-local `.claude/skills`, `.agents/skills`, and
 `.opencode/{skill,skills}` directories to `skills.paths`.
@@ -650,8 +653,8 @@ detailed dependency, validation, or status blockers for orchestrators.
 
 `agency work` consults this shared readiness model before materializing. Blocked,
 done, and dropped targets are rejected unless `--force` is supplied explicitly.
-`agency pr` leaves command semantics to `gh`; run `agency context . --json` first
-when readiness or validation state needs inspection.
+Task-aware `agency pr create` applies Agency readiness and validation checks;
+untargeted `agency pr` invocations leave command semantics to `gh`.
 
 ### Reconciliation
 
@@ -663,6 +666,10 @@ structured `changes`, `warnings`, `unresolved`, and per-execution evidence. The
 default mode applies safe reconciliation transitions; `--dry-run` is explicitly
 observational.
 
+Pass `<task-id>` to scope reconciliation to one task and its repositories. A
+multi-phase task scope includes all of its phases; add `[phase-id]` to select one
+phase. Scoped sync does not query, materialize, or reconcile unrelated work.
+
 `agency sync` performs only these safe transitions:
 
 - materialize declared but missing repositories from their canonical remotes;
@@ -1050,7 +1057,7 @@ agency work [<directory> | --epic <epic-id>] [--runner <name>] [--auto] [--print
 agency work prepare [target] [--evidence <json-or-path>] [--dry-run] [--json]
 agency worktree <list|inspect|prepare|remove|rebuild|repair>
 agency push [--json]
-agency pr create <task-id> [phase-id] [--draft] [--force] [--json]
+agency pr create <task-id> [phase-id] [--draft] [--title <title>] [--head <branch>] [--base <branch>] [--label <label>] [--force] [--json]
 agency pr [args...]
 ```
 
@@ -1059,10 +1066,10 @@ configured external chooser. Pass a directory, including `.` for the current
 directory, to infer its epic, task, or phase. Outside a workbase, Agency first
 presents the registered workbases, then the selected workbase's hierarchy.
 
-OpenCode is the default runner, with automatic Claude fallback when neither is
-explicitly selected. `--opencode` and `--claude` remain aliases for requiring
-their built-in presets. Launches are interactive and promptless by default; use
-`--auto` to send Agency's generated context prompt.
+Agency automatically uses the first available runner in this order: `opencode2`,
+`opencode`, then `claude`. `--opencode` and `--claude` remain aliases for
+requiring their corresponding built-in presets. Launches are interactive and
+promptless by default; use `--auto` to send Agency's generated context prompt.
 
 `agency work prepare` resolves an execution unit and creates or reuses its
 writable and reference worktrees, or its single pinned review checkout, without
@@ -1137,9 +1144,16 @@ post-commit working copy, in which case it publishes `@-`; described empty
 changes remain intentional publication tips. Missing descriptions or authors
 stop with exact change IDs and remediation commands. Agency creates or safely
 advances only the declared bookmark and never invents a `push-*` bookmark.
+If the fetched remote base advanced outside the local stack, Agency prints the
+exact `jj rebase` command needed to move the stack onto `<base>@<remote>`. Push
+reports deterministic fetch, inspection, validation, and publication progress
+on stderr, including while `--json` reserves stdout for one machine result.
 
 Task-aware `agency pr create <task-id> [phase-id]` uses Agency's delivery flow,
-including readiness checks and durable PR recording. Other `agency pr`
+including readiness checks and durable PR recording. It accepts draft, title,
+declared head/base confirmation, and repeatable label options; a contradicting
+head or base is rejected rather than recording inconsistent delivery metadata.
+Other `agency pr`
 invocations forward every argument to `gh pr`. From an execution task or phase
 directory, including descendants, passthrough runs in that execution unit's
 authoritative writable checkout. Otherwise it runs in the caller's current

package/cli-main.ts

@@ -322,6 +322,10 @@ const commands: Record<string, Command> = {
 					phaseId: args[2],
 					draft: options.draft,
 					force: options.force,
+					title: options.title,
+					head: options.head,
+					base: options.base,
+					labels: options.label,
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
@@ -750,13 +754,15 @@ const commands: Record<string, Command> = {
 		},
 	},
 	sync: {
-		run: async (_args: string[], options: Record<string, any>) => {
+		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) {
 				console.log(syncHelp)
 				return
 			}
 			await runCommand(
 				sync({
+					taskId: args[0],
+					phaseId: args[1],
 					dryRun: options["dry-run"],
 					json: options.json,
 					silent: options.silent,

package/package.json

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

package/src/cli-parser.test.ts

@@ -334,7 +334,7 @@ describe("strict CLI parsing", () => {
 			[["context", "one", "two"], "agency context"],
 			[["graph", "extra"], "agency graph"],
 			[["next", "extra"], "agency next"],
-			[["sync", "extra"], "agency sync"],
+			[["sync", "one", "two", "three"], "agency sync"],
 			[
 				[
 					"claim",
@@ -430,6 +430,31 @@ describe("strict CLI parsing", () => {
 			args: ["create", "ship"],
 		})
 		expect(selected.passthrough).toBeUndefined()
+		expect(
+			parseCli([
+				"pr",
+				"create",
+				"ship",
+				"--title",
+				"Ship it",
+				"--head",
+				"task/ship",
+				"--base",
+				"main",
+				"--label",
+				"ai-assisted",
+				"--label",
+				"product-area:platform",
+			]),
+		).toMatchObject({
+			args: ["create", "ship"],
+			values: {
+				title: "Ship it",
+				head: "task/ship",
+				base: "main",
+				label: ["ai-assisted", "product-area:platform"],
+			},
+		})
 	})
 
 	test("parses explicit dry-run reconciliation", () => {
@@ -441,6 +466,11 @@ describe("strict CLI parsing", () => {
 			commandName: "sync",
 			values: { "dry-run": true, json: true },
 		})
+		expect(parseCli(["sync", "ship", "release", "--json"])).toMatchObject({
+			commandName: "sync",
+			args: ["ship", "release"],
+			values: { json: true },
+		})
 		expect(() => parseCli(["sync", "--apply"])).toThrow("Unknown option")
 	})
 

package/src/cli-parser.ts

@@ -732,16 +732,17 @@ const commands = {
 		},
 	},
 	sync: {
-		usage: "agency sync [--dry-run] [--json]",
+		usage: "agency sync [<task-id> [phase-id]] [--dry-run] [--json]",
 		options: {
 			...outputOptions,
+			...entitySelectorOptions,
 			"dry-run": { type: "boolean" },
 		},
 		command: {
-			usage: "agency sync [--dry-run] [--json]",
+			usage: "agency sync [<task-id> [phase-id]] [--dry-run] [--json]",
 			minArgs: 0,
-			maxArgs: 0,
-			options: ["dry-run", "json"],
+			maxArgs: 2,
+			options: ["dry-run", "json", "task", "phase"],
 		},
 	},
 	archive: {
@@ -964,14 +965,28 @@ const commands = {
 			force: { type: "boolean" },
 			task: { type: "string" },
 			phase: { type: "string" },
+			title: { type: "string" },
+			head: { type: "string" },
+			base: { type: "string" },
+			label: { type: "string", multiple: true },
 		},
 		subcommands: {
 			create: {
-				usage:
-					"agency pr create <task-id> [phase-id] [--draft] [--force] [--json]",
+				usage: "agency pr create <task-id> [phase-id] [options]",
 				minArgs: 1,
 				maxArgs: 2,
-				options: ["draft", "force", "json", "task", "phase"],
+				options: [
+					"draft",
+					"force",
+					"json",
+					"task",
+					"phase",
+					"title",
+					"head",
+					"base",
+					"label",
+				],
+				repeatable: ["label"],
 			},
 		},
 	},

package/src/commands/context.test.ts

@@ -219,6 +219,73 @@ Phase prose.
 		)
 	})
 
+	test("reports the current jj change without inventing a missing bookmark", async () => {
+		if (!Bun.which("jj")) return
+		await cleanupTempDir(root)
+		root = await createTempDir()
+		const remote = join(root, "remote.git")
+		const seed = join(root, "seed")
+		const repository = join(root, "repos/agency")
+		const checkout = join(root, "tasks/example/code/agency")
+		await mkdir(join(root, "repos"), { recursive: true })
+		await write(root, "agency.json", '{"version":2,"vcs":"jj"}\n')
+		await run(root, ["git", "init", "--bare", "--initial-branch=main", remote])
+		await run(root, ["git", "init", "--initial-branch=main", seed])
+		await run(seed, ["git", "config", "user.email", "test@example.com"])
+		await run(seed, ["git", "config", "user.name", "Test"])
+		await Bun.write(join(seed, "README.md"), "example\n")
+		await run(seed, ["git", "add", "README.md"])
+		await run(seed, ["git", "commit", "-m", "initial"])
+		await run(seed, ["git", "remote", "add", "origin", remote])
+		await run(seed, ["git", "push", "origin", "main"])
+		await run(root, ["jj", "git", "clone", "--no-colocate", remote, repository])
+		await write(
+			root,
+			"tasks/example/TASK.md",
+			`---
+ticketUrl: null
+repo: agency
+branch: task/example
+base: main
+pr: null
+status: working
+---
+
+# Example
+`,
+		)
+		await mkdir(dirname(checkout), { recursive: true })
+		await run(repository, [
+			"jj",
+			"workspace",
+			"add",
+			"--name",
+			"task-example",
+			"-r",
+			"main",
+			checkout,
+		])
+		await Bun.write(join(checkout, "feature.txt"), "current change\n")
+		const current = Bun.spawn(
+			["jj", "log", "--no-graph", "-r", "@", "-T", "commit_id"],
+			{ cwd: checkout, stdout: "pipe", stderr: "pipe" },
+		)
+		const currentCommit = (await new Response(current.stdout).text()).trim()
+		expect(await current.exited).toBe(0)
+
+		const result = await readContext(root, "tasks/example")
+		expect(result.workspace.writable).toMatchObject({
+			branchCommit: null,
+			checkoutCommit: currentCommit,
+			checkoutBranch: null,
+			detached: true,
+			dirty: false,
+		})
+		expect(result.workspace.warnings).toContain(
+			`Unable to resolve branch 'task/example' in ${repository}`,
+		)
+	})
+
 	test("makes compact projection explicit without omitting essential identity", async () => {
 		const result = await readContext(
 			root,

package/src/commands/pr.test.ts

@@ -158,6 +158,10 @@ status: open
 					phaseId: "implementation",
 					draft: true,
 					force: true,
+					title: "Ship it",
+					head: "task/example",
+					base: "main",
+					labels: ["ai-assisted"],
 					cwd: "/workbase",
 					json: true,
 				}).pipe(
@@ -177,7 +181,15 @@ status: open
 			"implementation",
 			true,
 			"/workbase",
-			expect.objectContaining({ force: true, draft: true, json: true }),
+			expect.objectContaining({
+				force: true,
+				draft: true,
+				title: "Ship it",
+				head: "task/example",
+				base: "main",
+				labels: ["ai-assisted"],
+				json: true,
+			}),
 		])
 	})
 

package/src/commands/pr.ts

@@ -14,6 +14,10 @@ interface PrCreateOptions extends BaseCommandOptions {
 	readonly phaseId?: string
 	readonly draft?: boolean
 	readonly force?: boolean
+	readonly title?: string
+	readonly head?: string
+	readonly base?: string
+	readonly labels?: readonly string[]
 }
 
 const branchTargetCommands = new Set([
@@ -126,11 +130,21 @@ export const pr = (args: readonly string[], cwd: string = process.cwd()) =>
 	})
 
 export const help = `
-Usage: agency pr create <task-id> [phase-id] [--draft] [--force] [--json]
+Usage: agency pr create <task-id> [phase-id] [options]
        agency pr [args...]
 
-Create records a pull request for an Agency execution unit. Other invocations
-run gh pr unchanged, focusing the writable repository checkout when invoked from
+Create records a pull request for an Agency execution unit and accepts the
+options listed below. Invocations without an Agency task target run gh pr
+unchanged, focusing the writable repository checkout when invoked from
 an Agency execution task or phase. In jj workbases, Agency supplies the declared
 branch and repository to gh subcommands that would otherwise infer Git context.
+
+Options:
+  --draft                   Create the pull request as a draft
+  --title <title>           Override the generated pull request title
+  --head <branch>           Confirm the declared head branch
+  --base <branch>           Confirm the declared base branch
+  --label <label>           Add a label (repeatable)
+  --force                   Override readiness checks
+  --json                    Output one versioned machine result
 `

package/src/commands/push.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { PushService } from "../services/PushService"
+import { captureLogs } from "../test-utils"
+import type { Progress } from "../utils/progress"
+import { push } from "./push"
+
+describe("push command", () => {
+	test("reports deterministic progress while preserving one JSON result", async () => {
+		const updates: string[] = []
+		const progress: Progress = {
+			start: (message) => updates.push(`start:${message}`),
+			succeed: (message) => updates.push(`succeed:${message}`),
+			fail: (message) => updates.push(`fail:${message}`),
+		}
+		const result = {
+			vcs: "jj" as const,
+			taskId: "example",
+			branch: "task/example",
+			base: "main",
+			remote: "origin",
+			tip: "abc123",
+			changeId: "change",
+		}
+		const logs = await captureLogs(() =>
+			Effect.runPromise(
+				push({ cwd: "/workbase", json: true }, progress).pipe(
+					Effect.provideService(PushService, {
+						publish: (_cwd: string, options: any) => {
+							for (const stage of [
+								"context",
+								"fetch",
+								"inspect",
+								"validate",
+								"publish",
+							] as const)
+								options.onProgress(stage)
+							return Effect.succeed(result)
+						},
+					} as never),
+				) as Effect.Effect<void, unknown, never>,
+			),
+		)
+
+		expect(logs).toEqual([JSON.stringify(result, null, 2)])
+		expect(updates).toEqual([
+			"start:Inspecting Agency execution context",
+			"start:Fetching remote state",
+			"start:Selecting the publication tip",
+			"start:Validating outgoing changes",
+			"start:Publishing the declared branch",
+			"succeed:Published task/example to origin",
+		])
+	})
+})

package/src/commands/push.ts

@@ -2,12 +2,39 @@ import { Effect } from "effect"
 import { PushService } from "../services/PushService"
 import type { BaseCommandOptions } from "../utils/command"
 import { createLoggers } from "../utils/effect"
+import { createProgress, type Progress } from "../utils/progress"
 
-export const push = (options: BaseCommandOptions = {}) =>
+const stageMessage = {
+	context: "Inspecting Agency execution context",
+	fetch: "Fetching remote state",
+	inspect: "Selecting the publication tip",
+	validate: "Validating outgoing changes",
+	publish: "Publishing the declared branch",
+} as const
+
+export const push = (
+	options: BaseCommandOptions = {},
+	progress: Progress = createProgress({ silent: options.silent }),
+) =>
 	Effect.gen(function* () {
 		const publications = yield* PushService
 		const { log } = createLoggers(options)
-		const result = yield* publications.publish(options.cwd ?? process.cwd())
+		const showProgress = !options.silent
+		const result = yield* publications
+			.publish(options.cwd ?? process.cwd(), {
+				onProgress: showProgress
+					? (stage) => progress.start(stageMessage[stage])
+					: undefined,
+			})
+			.pipe(
+				Effect.tapError(() =>
+					Effect.sync(() => {
+						if (showProgress) progress.fail("Publication failed")
+					}),
+				),
+			)
+		if (showProgress)
+			progress.succeed(`Published ${result.branch} to ${result.remote}`)
 		log(
 			options.json
 				? JSON.stringify(result, null, 2)

package/src/commands/sync.test.ts

@@ -82,6 +82,41 @@ describe("sync command", () => {
 		).toBe(false)
 	})
 
+	test("scopes reconciliation to one task", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "second",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/second",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+
+		const logs = await captureLogs(() =>
+			runTestEffect(sync({ cwd: root, taskId: "example", json: true })),
+		)
+		const result = JSON.parse(logs[0]!)
+		expect(result.executions.map((execution: any) => execution.target)).toEqual(
+			["task:example"],
+		)
+		expect(
+			await Bun.file(
+				join(root, "tasks/example/code/agency/README.md"),
+			).exists(),
+		).toBe(true)
+		expect(
+			await Bun.file(join(root, "tasks/second/code/agency/README.md")).exists(),
+		).toBe(false)
+	})
+
 	test("preserves structured output behind --json", async () => {
 		const logs = await captureLogs(() =>
 			runTestEffect(sync({ cwd: root, dryRun: true, json: true })),

package/src/commands/sync.ts

@@ -6,6 +6,8 @@ import { createProgress, type Progress } from "../utils/progress"
 
 interface SyncCommandOptions extends BaseCommandOptions {
 	readonly dryRun?: boolean
+	readonly taskId?: string
+	readonly phaseId?: string
 }
 
 interface Notice {
@@ -44,6 +46,8 @@ export const sync = (
 			.reconcile({
 				cwd: options.cwd,
 				apply: options.dryRun !== true,
+				taskId: options.taskId,
+				phaseId: options.phaseId,
 				onProgress: showProgress
 					? ({ stage, current, total, target }) => {
 							if (stage === "repositories") {
@@ -118,11 +122,13 @@ export const sync = (
 	})
 
 export const help = `
-Usage: agency sync [--dry-run] [--json]
+Usage: agency sync [<task-id> [phase-id]] [--dry-run] [--json]
 
 Compare portable repository declarations and execution state with local Git
 repositories, worktrees, branches, references, claims, and pull requests.
 Safe reconciliation transitions are applied by default.
+When a task or phase is provided, only that target and its repositories are
+queried or reconciled. Task scope includes all phases of a multi-phase task.
 
 Options:
   --dry-run                 Report planned safe transitions without changing state

package/src/commands/work.test.ts

@@ -1050,18 +1050,45 @@ describe("work command", () => {
 		).toBeUndefined()
 	})
 
-	test("automatically falls back to Claude", async () => {
-		const harness = createHarness({ available: { opencode: false } })
+	test("automatically prefers opencode2", async () => {
+		const harness = createHarness()
+
+		await harness.run({ taskId: "example" })
+
+		expect(harness.probes).toEqual(["opencode2"])
+		expect(harness.launches[0]).toEqual({
+			cli: "opencode2",
+			args: ["opencode2"],
+			cwd: taskDirectory,
+		})
+	})
+
+	test("automatically falls back from opencode2 to opencode", async () => {
+		const harness = createHarness({ available: { opencode2: false } })
 
 		await harness.run({ taskId: "example" })
 
-		expect(harness.probes).toEqual(["opencode", "claude"])
+		expect(harness.probes).toEqual(["opencode2", "opencode"])
+		expect(harness.launches[0]).toEqual({
+			cli: "opencode",
+			args: ["opencode"],
+			cwd: taskDirectory,
+		})
+	})
+
+	test("automatically falls back from OpenCode to Claude", async () => {
+		const harness = createHarness({
+			available: { opencode2: false, opencode: false },
+		})
+
+		await harness.run({ taskId: "example" })
+
+		expect(harness.probes).toEqual(["opencode2", "opencode", "claude"])
 		expect(harness.launches[0]).toEqual({
 			cli: "claude",
 			args: ["claude"],
 			cwd: taskDirectory,
 		})
-		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBeUndefined()
 	})
 
 	test("does not fall back when OpenCode is explicitly required", async () => {
@@ -1090,13 +1117,13 @@ describe("work command", () => {
 
 	test("fails when neither agent tool is available", async () => {
 		const harness = createHarness({
-			available: { opencode: false, claude: false },
+			available: { opencode2: false, opencode: false, claude: false },
 		})
 
 		await expect(harness.run({ taskId: "example" })).rejects.toThrow(
 			"claude CLI tool not found",
 		)
-		expect(harness.probes).toEqual(["opencode", "claude"])
+		expect(harness.probes).toEqual(["opencode2", "opencode", "claude"])
 		expect(harness.launches).toEqual([])
 	})
 
@@ -1150,7 +1177,7 @@ describe("work command", () => {
 			verboseHarness.run({ taskId: "example", verbose: true }),
 		)
 		expect(verboseLogs).toEqual([
-			"Launching command: opencode (cwd: /workbase/tasks/example)",
+			"Launching command: opencode2 (cwd: /workbase/tasks/example)",
 		])
 		expect(verboseHarness.materializeOptions[0]?.verbose).toBe(true)
 

package/src/commands/work.ts

@@ -280,10 +280,16 @@ export const work = (
 			options.claude ||
 			process.env.AGENCY_RUNNER,
 		)
-		let runner =
+		const defaultRunners = ["opencode2", "opencode", "claude"] as const
+		let defaultRunnerIndex = 0
+		let runner: string =
 			options.runner ??
 			process.env.AGENCY_RUNNER ??
-			(options.claude ? "claude" : "opencode")
+			(options.claude
+				? "claude"
+				: options.opencode
+					? "opencode"
+					: defaultRunners[defaultRunnerIndex]!)
 		const claimant = process.env.AGENCY_CLAIMANT ?? process.env.USER ?? "agency"
 		const sessionId =
 			process.env.AGENCY_SESSION_ID ?? `${process.pid}-${Date.now()}`
@@ -311,12 +317,12 @@ export const work = (
 		let available = yield* fs.runCommand(["which", cli], {
 			captureOutput: true,
 		})
-		if (
+		while (
 			available.exitCode !== 0 &&
 			!explicitlyRequested &&
-			runner === "opencode"
+			defaultRunnerIndex < defaultRunners.length - 1
 		) {
-			runner = "claude"
+			runner = defaultRunners[++defaultRunnerIndex]!
 			resolved = resolveRunnerCommand(
 				runner,
 				config.runners,
@@ -580,7 +586,8 @@ 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. Managed OpenCode launches receive whole-workbase access through
-Agency's project plugin; Agency context remains authoritative for writes.
+Agency's project plugin; Agency context remains authoritative for writes. Automatic
+runner discovery checks opencode2, opencode, then claude.
 
 The prepare subcommand resolves and materializes an execution workspace without
 launching an agent or changing lifecycle status. --dry-run reports planned Git

package/src/services/ContextService.ts

@@ -898,6 +898,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 						repositoryPath: string,
 						checkoutPath: string,
 						expectedBranch: string | null = null,
+						branchCommit: string | null = null,
 					) =>
 						Effect.gen(function* (): Generator<any, CheckoutInspection, any> {
 							const materialized = yield* fs.isDirectory(checkoutPath)
@@ -914,9 +915,10 @@ export class ContextService extends Effect.Service<ContextService>()(
 								const canonicalCheckoutPath = materialized
 									? yield* fs.realPath(checkoutPath)
 									: resolve(checkoutPath)
-								const registered = workspaces.some(
+								const workspace = workspaces.find(
 									(workspace) => workspace.path === canonicalCheckoutPath,
 								)
+								const registered = workspace !== undefined
 								if (!materialized) {
 									return {
 										materialized: false,
@@ -930,10 +932,14 @@ export class ContextService extends Effect.Service<ContextService>()(
 								return {
 									materialized: true,
 									registered,
-									checkoutCommit: yield* backend.workspaceHead(checkoutPath),
-									checkoutBranch: expectedBranch,
-									detached: expectedBranch === null,
-									dirty: yield* backend.workspaceDirty(checkoutPath),
+									checkoutCommit: workspace?.commit ?? null,
+									checkoutBranch:
+										expectedBranch && branchCommit === workspace?.commit
+											? expectedBranch
+											: null,
+									detached:
+										!expectedBranch || branchCommit !== workspace?.commit,
+									dirty: workspace ? false : null,
 								}
 							}
 							const listed = yield* runGit(fs, repositoryPath, [
@@ -1014,10 +1020,8 @@ export class ContextService extends Effect.Service<ContextService>()(
 									repositoryPath,
 									checkoutPath,
 									executionData.branch,
+									branchCommit,
 								)
-								if (backend.kind === "jj" && branchCommit === null) {
-									branchCommit = checkout.checkoutCommit
-								}
 								if (branchCommit === null) {
 									inspectionWarnings.push(
 										`Unable to resolve branch '${executionData.branch}' in ${repositoryPath}`,

package/src/services/PullRequestService.test.ts

@@ -68,11 +68,12 @@ describe("PullRequestService", () => {
 		phaseId?: string,
 		draft = false,
 		force = false,
+		options: Record<string, unknown> = {},
 	) =>
 		runTestEffect(
 			PullRequestService.pipe(
 				Effect.flatMap((service) =>
-					service.create(taskId, phaseId, draft, root, { force }),
+					service.create(taskId, phaseId, draft, root, { force, ...options }),
 				),
 			),
 		)
@@ -303,6 +304,51 @@ process.exit(${exitCode})
 		])
 	})
 
+	test("passes task-aware GitHub title and labels with declared refs", async () => {
+		await createTask()
+		await writeFakeGh({
+			stdout: "https://github.com/example/agency/pull/45\n",
+		})
+
+		await createPullRequest("example", undefined, true, false, {
+			title: "Ship the workflow",
+			head: "task/example",
+			base: "main",
+			labels: ["ai-assisted", "platform"],
+		})
+
+		expect((await readGhCall()).args).toEqual([
+			"pr",
+			"create",
+			"--fill",
+			"--title",
+			"Ship the workflow",
+			"--base",
+			"main",
+			"--head",
+			"task/example",
+			"--draft",
+			"--label",
+			"ai-assisted",
+			"--label",
+			"platform",
+		])
+	})
+
+	test("rejects task-aware head and base values that contradict declarations", async () => {
+		await createTask()
+		await expect(
+			createPullRequest("example", undefined, false, false, {
+				head: "other",
+			}),
+		).rejects.toThrow("does not match declared branch")
+		await expect(
+			createPullRequest("example", undefined, false, false, {
+				base: "release",
+			}),
+		).rejects.toThrow("does not match declared base")
+	})
+
 	test("guards terminal targets before materializing unless forced", async () => {
 		await createTask()
 		await runTestEffect(

package/src/services/PullRequestService.ts

@@ -27,6 +27,10 @@ class PullRequestError extends Data.TaggedError("PullRequestError")<{
 
 interface PullRequestOptions extends BaseCommandOptions {
 	readonly force?: boolean
+	readonly title?: string
+	readonly head?: string
+	readonly base?: string
+	readonly labels?: readonly string[]
 }
 
 export class PullRequestService extends Effect.Service<PullRequestService>()(
@@ -158,6 +162,25 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 						})
 					}
 					const remote = config.delivery?.remote ?? "origin"
+					if (options.head && options.head !== execution.branch) {
+						return yield* new PullRequestError({
+							message: `Requested head '${options.head}' does not match declared branch '${execution.branch}'`,
+						})
+					}
+					if (options.base && options.base !== execution.base) {
+						return yield* new PullRequestError({
+							message: `Requested base '${options.base}' does not match declared base '${execution.base}'`,
+						})
+					}
+					if (
+						config.delivery &&
+						(options.title || (options.labels?.length ?? 0) > 0)
+					) {
+						return yield* new PullRequestError({
+							message:
+								"Task-aware --title and --label options require the default GitHub delivery provider",
+						})
+					}
 
 					const dirty = yield* backend.workspaceDirty(workspace.writablePath)
 					if (dirty === null) {
@@ -211,6 +234,9 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 								repository,
 								draft,
 								vcs: config.vcs ?? "git",
+								title: options.title,
+								head: options.head,
+								labels: options.labels,
 								...(defaults ? { defaults } : {}),
 							})
 					const gitEnvironment = config.delivery

package/src/services/PushService.test.ts

@@ -376,6 +376,42 @@ describe("PushService", () => {
 				)
 			).stdout,
 		).toBe("true")
+
+		await requireCommand(["jj", "new", "@"], fixture.checkout)
+		await Bun.write(join(fixture.checkout, "follow-up.txt"), "follow up\n")
+		await requireCommand(
+			["jj", "describe", "-m", "Add follow-up"],
+			fixture.checkout,
+		)
+		const advanced = await publish(fixture.taskPath)
+		expect(advanced.tip).not.toBe(result.tip)
+		expect(await remoteBranch(fixture.remote)).toBe(advanced.tip)
+	}, 15_000)
+
+	test("diagnoses a jj stack whose remote base advanced", async () => {
+		if (!Bun.which("jj")) return
+		const fixture = await setup("jj")
+		await Bun.write(join(fixture.checkout, "feature.txt"), "local\n")
+		await requireCommand(
+			["jj", "describe", "-m", "Local feature"],
+			fixture.checkout,
+		)
+
+		const other = join(fixture.root, "other-main")
+		await requireCommand(["git", "clone", fixture.remote, other])
+		await requireCommand(["git", "config", "user.name", "Other"], other)
+		await requireCommand(
+			["git", "config", "user.email", "other@example.com"],
+			other,
+		)
+		await Bun.write(join(other, "remote.txt"), "remote\n")
+		await requireCommand(["git", "add", "remote.txt"], other)
+		await requireCommand(["git", "commit", "-m", "Advance main"], other)
+		await requireCommand(["git", "push", "origin", "main"], other)
+
+		await expect(publish(fixture.taskPath)).rejects.toThrow(
+			"jj rebase -s 'roots(main@origin..@)' -d main@origin",
+		)
 	})
 
 	test("selects the described parent of a canonical jj post-commit working copy", async () => {
@@ -424,7 +460,7 @@ describe("PushService", () => {
 		await expect(publish(undescribed.taskPath)).rejects.toThrow(
 			`Change ${changeId} has no description. Run: jj describe -r ${changeId}`,
 		)
-	})
+	}, 15_000)
 
 	test("rejects an empty jj task and remote bookmark divergence", async () => {
 		if (!Bun.which("jj")) return
@@ -463,7 +499,7 @@ describe("PushService", () => {
 		await expect(publish(fixture.taskPath)).rejects.toThrow(
 			"refusing to move it",
 		)
-	})
+	}, 15_000)
 
 	test("rejects conflicted jj changes with an actionable change ID", async () => {
 		if (!Bun.which("jj")) return

package/src/services/PushService.ts

@@ -37,6 +37,12 @@ interface PushResult {
 	readonly changeId?: string
 }
 
+type PushStage = "context" | "fetch" | "inspect" | "validate" | "publish"
+
+interface PushOptions {
+	readonly onProgress?: (stage: PushStage) => void
+}
+
 const validEmail = (email: string) => /^[^@\s]+@[^@\s]+$/.test(email)
 
 const requireCommand = (
@@ -153,8 +159,10 @@ const publishGit = (
 	remote: string,
 	branch: string,
 	base: string,
+	onProgress?: (stage: PushStage) => void,
 ) =>
 	Effect.gen(function* () {
+		onProgress?.("inspect")
 		const currentBranch = yield* git(
 			fs,
 			checkout,
@@ -179,6 +187,7 @@ const publishGit = (
 			})
 		}
 
+		onProgress?.("fetch")
 		yield* git(
 			fs,
 			checkout,
@@ -202,6 +211,7 @@ const publishGit = (
 			})
 		}
 
+		onProgress?.("validate")
 		const log = yield* git(
 			fs,
 			checkout,
@@ -228,6 +238,7 @@ const publishGit = (
 			})
 		}
 
+		onProgress?.("publish")
 		yield* git(
 			fs,
 			checkout,
@@ -361,14 +372,17 @@ const publishJj = (
 	remote: string,
 	branch: string,
 	base: string,
+	onProgress?: (stage: PushStage) => void,
 ) =>
 	Effect.gen(function* () {
+		onProgress?.("fetch")
 		yield* jj(
 			fs,
 			checkout,
 			["git", "fetch", "--remote", remote],
 			`Failed to fetch remote '${remote}'`,
 		)
+		onProgress?.("inspect")
 		const workingCopy = yield* jjRevision(fs, checkout, "@")
 		if (!workingCopy) {
 			return yield* new PushError({
@@ -403,10 +417,11 @@ const publishJj = (
 			!(yield* jjAncestor(fs, checkout, baseRevision.commitId, tip.commitId))
 		) {
 			return yield* new PushError({
-				message: `Declared base '${base}' (${baseRevision.commitId}) is not an ancestor of jj tip ${tip.changeId} (${tip.commitId})`,
+				message: `Declared base '${base}' (${baseRevision.commitId}) is not an ancestor of jj tip ${tip.changeId} (${tip.commitId}). Rebase the stack with: jj rebase -s 'roots(${baseBookmark}..@)' -d ${baseBookmark}`,
 			})
 		}
 
+		onProgress?.("validate")
 		const outgoing = yield* jjCommits(
 			fs,
 			checkout,
@@ -444,6 +459,7 @@ const publishJj = (
 			})
 		}
 
+		onProgress?.("publish")
 		yield* jj(
 			fs,
 			checkout,
@@ -467,8 +483,9 @@ const publishJj = (
 
 export class PushService extends Effect.Service<PushService>()("PushService", {
 	sync: () => ({
-		publish: (startPath: string = process.cwd()) =>
+		publish: (startPath: string = process.cwd(), options: PushOptions = {}) =>
 			Effect.gen(function* () {
+				options.onProgress?.("context")
 				const contexts = yield* ContextService
 				const fs = yield* FileSystemService
 				const tasks = yield* TaskService
@@ -554,6 +571,7 @@ export class PushService extends Effect.Service<PushService>()("PushService", {
 								remote,
 								execution.branch,
 								execution.base,
+								options.onProgress,
 							)
 						: yield* publishGit(
 								fs,
@@ -561,6 +579,7 @@ export class PushService extends Effect.Service<PushService>()("PushService", {
 								remote,
 								execution.branch,
 								execution.base,
+								options.onProgress,
 							)
 				return {
 					vcs: context.workbase.vcs,

package/src/services/RepositoryService.ts

@@ -811,7 +811,11 @@ export class RepositoryService extends Effect.Service<RepositoryService>()(
 				}),
 
 			setup: (
-				options: { readonly cwd?: string; readonly apply?: boolean } = {},
+				options: {
+					readonly cwd?: string
+					readonly apply?: boolean
+					readonly aliases?: readonly string[]
+				} = {},
 			) =>
 				Effect.gen(function* () {
 					const service = yield* RepositoryService
@@ -819,7 +823,13 @@ export class RepositoryService extends Effect.Service<RepositoryService>()(
 					const versionControl = yield* VersionControlService
 					const state = yield* configState(options.cwd ?? process.cwd())
 					const backend = yield* versionControl.forWorkbase(state.root)
-					const repositories = yield* service.list(state.root)
+					const requestedAliases = options.aliases
+						? new Set(options.aliases)
+						: null
+					const repositories = (yield* service.list(state.root)).filter(
+						(repository) =>
+							!requestedAliases || requestedAliases.has(repository.alias),
+					)
 					const planned: Omit<RepositorySetupAction, "status">[] = []
 					const unresolved: RepositorySetupIssue[] = []
 
@@ -933,7 +943,11 @@ export class RepositoryService extends Effect.Service<RepositoryService>()(
 						unresolved,
 						repositories:
 							options.apply === true
-								? yield* service.list(state.root)
+								? (yield* service.list(state.root)).filter(
+										(repository) =>
+											!requestedAliases ||
+											requestedAliases.has(repository.alias),
+									)
 								: repositories,
 					} satisfies RepositorySetupResult
 				}),

package/src/services/SyncService.ts

@@ -170,6 +170,8 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 				readonly apply?: boolean
 				readonly now?: Date
 				readonly onProgress?: (progress: SyncProgress) => void
+				readonly taskId?: string
+				readonly phaseId?: string
 			} = {},
 		) =>
 			Effect.gen(function* () {
@@ -191,9 +193,66 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 							.join("\n"),
 					})
 				}
+				if (options.phaseId && !options.taskId) {
+					return yield* new SyncError({
+						message: "A phase sync scope requires a task ID",
+					})
+				}
+				const allTaskRecords = yield* tasks.list(root)
+				const taskRecords = options.taskId
+					? allTaskRecords.filter((task) => task.id === options.taskId)
+					: allTaskRecords
+				if (options.taskId && taskRecords.length === 0) {
+					return yield* new SyncError({
+						message: `Task '${options.taskId}' does not exist`,
+					})
+				}
+				const records: ExecutionRecord[] = []
+				for (const task of taskRecords) {
+					if ("phases" in task.data) {
+						for (const phase of yield* phases.list(task.id, root)) {
+							if (options.phaseId && phase.id !== options.phaseId) continue
+							records.push({
+								key: `phase:${task.id}/${phase.id}`,
+								taskId: task.id,
+								phaseId: phase.id,
+								path: phase.path,
+								revision: documentRevision(phase.content),
+								data: phase.data,
+							})
+						}
+					} else if (!options.phaseId && !("review" in task.data)) {
+						records.push({
+							key: `task:${task.id}`,
+							taskId: task.id,
+							path: task.path,
+							revision: documentRevision(task.content),
+							data: task.data,
+						})
+					}
+				}
+				const reviewRecords = options.phaseId
+					? []
+					: taskRecords.filter((task) => "review" in task.data)
+				if (options.phaseId && records.length === 0) {
+					return yield* new SyncError({
+						message: `Phase '${options.taskId}/${options.phaseId}' does not exist`,
+					})
+				}
+				const repositoryAliases = new Set<string>()
+				for (const record of records) {
+					repositoryAliases.add(record.data.repo)
+					for (const reference of record.data.repos ?? [])
+						repositoryAliases.add(reference.repo)
+				}
+				for (const task of reviewRecords) {
+					if ("review" in task.data)
+						repositoryAliases.add(task.data.review.repo)
+				}
 				const repositorySetup = yield* repositories.setup({
 					cwd: root,
 					apply: options.apply === true,
+					...(options.taskId ? { aliases: [...repositoryAliases] } : {}),
 				})
 				options.onProgress?.({
 					stage: "repositories",
@@ -241,30 +300,6 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 								}),
 							),
 						)
-				const taskRecords = yield* tasks.list(root)
-				const records: ExecutionRecord[] = []
-				for (const task of taskRecords) {
-					if ("phases" in task.data) {
-						for (const phase of yield* phases.list(task.id, root)) {
-							records.push({
-								key: `phase:${task.id}/${phase.id}`,
-								taskId: task.id,
-								phaseId: phase.id,
-								path: phase.path,
-								revision: documentRevision(phase.content),
-								data: phase.data,
-							})
-						}
-					} else if (!("review" in task.data)) {
-						records.push({
-							key: `task:${task.id}`,
-							taskId: task.id,
-							path: task.path,
-							revision: documentRevision(task.content),
-							data: task.data,
-						})
-					}
-				}
 				const listRegistered = (repositoryPath: string) =>
 					Effect.gen(function* () {
 						if (registeredByRepository.has(repositoryPath))
@@ -409,9 +444,6 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 						{ concurrency: 8 },
 					),
 				)
-				const reviewRecords = taskRecords.filter(
-					(task) => "review" in task.data,
-				)
 				const executionTotal = records.length + reviewRecords.length
 				let reconciledExecutions = 0
 				const reportExecution = (target: string) => {

package/src/workbase/delivery-command.test.ts

@@ -67,6 +67,55 @@ describe("delivery commands", () => {
 			argv: ["gh", "pr", "create", "--fill", "--base", "main"],
 			environment: {},
 		})
+		expect(
+			resolveGitHubCreateCommand({
+				...input,
+				vcs: "git",
+				head: "feat/example",
+			}),
+		).toEqual({
+			argv: [
+				"gh",
+				"pr",
+				"create",
+				"--fill",
+				"--base",
+				"main",
+				"--head",
+				"feat/example",
+			],
+			environment: {},
+		})
+		expect(
+			resolveGitHubCreateCommand({
+				...input,
+				vcs: "jj",
+				defaults: { title: "Generated", body: "Details" },
+				title: "Requested",
+				labels: ["ai-assisted", "platform"],
+			}),
+		).toEqual({
+			argv: [
+				"gh",
+				"pr",
+				"create",
+				"--title",
+				"Requested",
+				"--body",
+				"Details",
+				"--base",
+				"main",
+				"--head",
+				"feat/example",
+				"--repo",
+				"example/agency",
+				"--label",
+				"ai-assisted",
+				"--label",
+				"platform",
+			],
+			environment: {},
+		})
 	})
 
 	test("rejects unknown placeholders", () => {

package/src/workbase/delivery-command.ts

@@ -25,6 +25,9 @@ export const resolveGitHubCreateCommand = ({
 	draft,
 	vcs,
 	defaults,
+	title,
+	head,
+	labels = [],
 }: {
 	readonly base: string
 	readonly branch: string
@@ -32,18 +35,25 @@ export const resolveGitHubCreateCommand = ({
 	readonly draft: boolean
 	readonly vcs: "git" | "jj"
 	readonly defaults?: { readonly title: string; readonly body: string }
+	readonly title?: string
+	readonly head?: string
+	readonly labels?: readonly string[]
 }) => ({
 	argv: [
 		"gh",
 		"pr",
 		"create",
 		...(defaults
-			? ["--title", defaults.title, "--body", defaults.body]
-			: ["--fill"]),
+			? ["--title", title ?? defaults.title, "--body", defaults.body]
+			: title
+				? ["--fill", "--title", title]
+				: ["--fill"]),
 		"--base",
 		base,
-		...(vcs === "jj" ? ["--head", branch, "--repo", repository] : []),
+		...(vcs === "jj" || head ? ["--head", head ?? branch] : []),
+		...(vcs === "jj" ? ["--repo", repository] : []),
 		...(draft ? ["--draft"] : []),
+		...labels.flatMap((label) => ["--label", label]),
 	],
 	environment: {},
 })

package/src/workbase/runner-command.test.ts

@@ -19,6 +19,12 @@ const variables = {
 
 describe("runner commands", () => {
 	test("uses promptless interactive commands for built-in presets", () => {
+		expect(
+			resolveRunnerCommand("opencode2", undefined, variables, false).argv,
+		).toEqual(["opencode2"])
+		expect(
+			resolveRunnerCommand("opencode2", undefined, variables, true).argv,
+		).toEqual(["opencode2", "--continue"])
 		expect(
 			resolveRunnerCommand("opencode", undefined, variables, false).argv,
 		).toEqual(["opencode"])
@@ -31,6 +37,12 @@ describe("runner commands", () => {
 	})
 
 	test("uses autonomous commands when a prompt is requested", () => {
+		expect(
+			resolveRunnerCommand("opencode2", undefined, variables, false, true).argv,
+		).toEqual(["opencode2", "--prompt", "Read the task."])
+		expect(
+			resolveRunnerCommand("opencode2", undefined, variables, true, true).argv,
+		).toEqual(["opencode2", "--continue", "--prompt", "Read the task."])
 		expect(
 			resolveRunnerCommand("opencode", undefined, variables, false, true).argv,
 		).toEqual(["opencode", "--prompt", "Read the task."])

package/src/workbase/runner-command.ts

@@ -31,6 +31,12 @@ const PLACEHOLDERS = new Set<keyof RunnerCommandVariables>([
 ])
 
 const BUILTIN_RUNNERS: Readonly<Record<string, RunnerDefinition>> = {
+	opencode2: {
+		command: ["opencode2"],
+		autoCommand: ["opencode2", "--prompt", "{prompt}"],
+		resumeCommand: ["opencode2", "--continue"],
+		autoResumeCommand: ["opencode2", "--continue", "--prompt", "{prompt}"],
+	},
 	opencode: {
 		command: ["opencode"],
 		autoCommand: ["opencode", "--prompt", "{prompt}"],