@markjaquith/agency 2.65.0 → 2.65.2

package/README.md

@@ -650,8 +650,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 +663,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 +1054,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...]
 ```
 
@@ -1137,9 +1141,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.0",
+  "version": "2.65.2",
   "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/services/ArchiveBulkService.test.ts

@@ -17,6 +17,13 @@ const git = (args: readonly string[], cwd?: string) => {
 	}
 }
 
+const jj = (args: readonly string[], cwd?: string) => {
+	const result = Bun.spawnSync(["jj", ...args], { cwd })
+	if (result.exitCode !== 0) {
+		throw new Error(new TextDecoder().decode(result.stderr))
+	}
+}
+
 describe("ArchiveService bulk task archive", () => {
 	let root: string
 	let source: string
@@ -436,6 +443,98 @@ claim:
 		).toBe(true)
 	})
 
+	test("archives a jj working-copy commit preserved by its task bookmark", async () => {
+		if (!Bun.which("jj")) return
+		const repository = join(root, "repos/agency")
+		await rm(repository, { recursive: true, force: true })
+		git(["clone", source, repository])
+		jj(["git", "init", "--colocate", repository])
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({ version: 2, vcs: "jj" }),
+		)
+		await createTask("jj-bookmarked")
+		await dropTask("jj-bookmarked")
+		const workspace = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("jj-bookmarked", undefined, root),
+				),
+			),
+		)
+		await Bun.write(join(workspace.writablePath!, "preserved.txt"), "keep\n")
+		jj(
+			["bookmark", "set", "task/jj-bookmarked", "-r", "@"],
+			workspace.writablePath!,
+		)
+
+		const preview = await archiveTasks(true)
+		expect(preview.tasks[0]).toMatchObject({
+			id: "jj-bookmarked",
+			disposition: "planned",
+			removedWorktrees: [workspace.writablePath!],
+		})
+		expect(
+			await Bun.file(join(workspace.writablePath!, "preserved.txt")).text(),
+		).toBe("keep\n")
+
+		const result = await archiveTasks()
+		expect(result.tasks[0]).toMatchObject({
+			id: "jj-bookmarked",
+			disposition: "archived",
+		})
+		expect(await Bun.file(workspace.writablePath!).exists()).toBe(false)
+		const preserved = Bun.spawnSync([
+			"jj",
+			"-R",
+			repository,
+			"file",
+			"show",
+			"-r",
+			"task/jj-bookmarked",
+			'root:"preserved.txt"',
+		])
+		if (preserved.exitCode !== 0) {
+			throw new Error(preserved.stderr.toString())
+		}
+		expect(preserved.stdout.toString()).toBe("keep\n")
+	})
+
+	test("archives a forgotten jj workspace preserved by its task bookmark", async () => {
+		if (!Bun.which("jj")) return
+		const repository = join(root, "repos/agency")
+		await rm(repository, { recursive: true, force: true })
+		git(["clone", source, repository])
+		jj(["git", "init", "--colocate", repository])
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({ version: 2, vcs: "jj" }),
+		)
+		await createTask("jj-stale")
+		await dropTask("jj-stale")
+		const workspace = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("jj-stale", undefined, root),
+				),
+			),
+		)
+		await Bun.write(join(workspace.writablePath!, "preserved.txt"), "keep\n")
+		jj(["bookmark", "set", "task/jj-stale", "-r", "@"], workspace.writablePath!)
+		jj(["-R", repository, "workspace", "forget", "agency-jj-stale-task-agency"])
+
+		const result = await archiveTasks(true)
+
+		expect(result.tasks[0]).toMatchObject({
+			id: "jj-stale",
+			disposition: "planned",
+			removedWorktrees: [workspace.writablePath!],
+		})
+		expect(
+			await Bun.file(join(workspace.writablePath!, "preserved.txt")).text(),
+		).toBe("keep\n")
+	})
+
 	test("rolls back the entire cohort when application fails", async () => {
 		await runTestEffect(
 			EpicService.pipe(

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/services/WorktreeService.ts

@@ -474,7 +474,9 @@ const inspectExecution = (
 						: yield* backend.workspaceHead(checkoutPath)
 					: null
 				const dirty =
-					exists && atPath ? yield* backend.workspaceDirty(checkoutPath) : null
+					exists && atPath
+						? yield* backend.workspaceDirty(checkoutPath)
+						: (atPath?.dirty ?? null)
 				const expectedCommit =
 					"branch" in checkout && context?.skipWritableRevisionResolution
 						? actualCommit
@@ -1659,10 +1661,26 @@ const removeJj = (
 			bookmark: string
 		}[] = []
 		for (const checkout of inspection.checkouts) {
+			const repositoryPath = join(root, "repos", checkout.repo)
+			const registered = checkout.registeredPath
+				? (yield* backend.listWorkspaces(repositoryPath)).find(
+						(workspace) => workspace.path === checkout.registeredPath,
+					)
+				: undefined
 			if (checkout.dirty === true && options.persistResume === false) {
-				return yield* new WorktreeError({
-					message: `Failed to remove workspace for '${checkout.repo}': checkout has uncommitted changes`,
-				})
+				const preservedByBookmark =
+					checkout.kind === "writable" &&
+					registered?.commit !== null &&
+					registered?.commit !== undefined &&
+					(yield* backend.resolveRevision(
+						repositoryPath,
+						checkout.requestedRef,
+					)) === registered.commit
+				if (!preservedByBookmark) {
+					return yield* new WorktreeError({
+						message: `Failed to remove workspace for '${checkout.repo}': checkout has uncommitted changes`,
+					})
+				}
 			}
 			if (
 				checkout.exists &&
@@ -1673,7 +1691,6 @@ const removeJj = (
 					message: `Failed to remove workspace for '${checkout.repo}': checkout cleanliness could not be verified`,
 				})
 			}
-			const repositoryPath = join(root, "repos", checkout.repo)
 			if (!checkout.registeredPath) {
 				const recoveryRevision = recoverable.get(checkout.path)
 				if (!recoveryRevision) continue
@@ -1696,9 +1713,6 @@ const removeJj = (
 				})
 				continue
 			}
-			const registered = (yield* backend.listWorkspaces(repositoryPath)).find(
-				(workspace) => workspace.path === checkout.registeredPath,
-			)
 			if (!registered?.name || !checkout.actualCommit || !registered.commit) {
 				return yield* new WorktreeError({
 					message: `Cannot identify jj workspace at ${checkout.registeredPath}`,

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: {},
 })