@markjaquith/agency 2.54.4 → 2.55.0

package/README.md

@@ -812,12 +812,13 @@ restore preflight all destinations and graph references before changing files.
 Versioned lifecycle provenance preserves parent declarations and dependency edges
 for restoration. Archived IDs are reserved until restored.
 
-### Work and Pull Requests
+### Work, Publication, and Pull Requests
 
 ```text
 agency work [<directory> | --epic <epic-id>] [--runner <name>] [--auto] [--print-command]
 agency work prepare [target] [--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 [args...]
 ```
@@ -865,6 +866,22 @@ Agency resolves the ref to a commit and creates a detached worktree. Existing
 reference worktrees are reused only while their commit still matches the declared
 ref; use a commit SHA as `ref` when reproducibility matters.
 
+`agency push` publishes the execution unit identified by current Agency context
+without creating a pull request. It requires a valid, registered writable
+checkout in `working` state, fetches the configured delivery remote, verifies
+that the declared base is in the publication history, validates every outgoing
+commit's description, author, and conflict state, and refuses non-fast-forward
+updates.
+
+For Git, YAML `branch` must exactly match the checked-out local branch, the
+worktree must be clean, and `HEAD` is pushed with upstream tracking. For jj, YAML
+`branch` is the authoritative delivery bookmark and need not exist before
+publication. Agency publishes `@` unless it is the canonical empty, undescribed
+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.
+
 Task-aware `agency pr create <task-id> [phase-id]` uses Agency's delivery flow,
 including readiness checks and durable PR recording. Other `agency pr`
 invocations forward every argument to `gh pr`. From an execution task or phase

package/cli-main.ts

@@ -6,6 +6,7 @@ import { parseCli } from "./src/cli-parser"
 import { init, help as initHelp } from "./src/commands/init"
 import { task, help as taskHelp } from "./src/commands/task"
 import { pr, prCreate, help as prHelp } from "./src/commands/pr"
+import { push, help as pushHelp } from "./src/commands/push"
 import { work, workPrepare, help as workHelp } from "./src/commands/work"
 import { worktree, help as worktreeHelp } from "./src/commands/worktree"
 import { status, help as statusHelp } from "./src/commands/status"
@@ -34,6 +35,7 @@ import { TaskService } from "./src/services/TaskService"
 import { PhaseService } from "./src/services/PhaseService"
 import { WorktreeService } from "./src/services/WorktreeService"
 import { PullRequestService } from "./src/services/PullRequestService"
+import { PushService } from "./src/services/PushService"
 import { ArchiveService } from "./src/services/ArchiveService"
 import { IntegrationService } from "./src/services/IntegrationService"
 import { ContextService } from "./src/services/ContextService"
@@ -79,6 +81,7 @@ const CliLayer = Layer.mergeAll(
 	PhaseService.Default,
 	WorktreeService.Default,
 	PullRequestService.Default,
+	PushService.Default,
 	ArchiveService.Default,
 	IntegrationService.Default,
 	ContextService.Default,
@@ -305,6 +308,22 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	push: {
+		run: async (_args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(pushHelp)
+				return
+			}
+			await runCommand(
+				push({
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+					cwd: options.cwd,
+				}),
+			)
+		},
+	},
 	phase: {
 		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) return console.log(phaseHelp)
@@ -742,6 +761,7 @@ Commands:
   vcs <subcommand>       Inspect or migrate the version-control backend
   next                   List or select ready execution units
   pr create / pr [...]  Create an Agency PR or run gh pr with repository focus
+  push                   Validate and publish the current execution unit
   review refresh         Explicitly refresh a pinned review task
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase

package/package.json

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

package/src/cli-parser.test.ts

@@ -616,6 +616,15 @@ describe("strict CLI parsing", () => {
 		).toThrow("cannot be combined")
 	})
 
+	test("parses push without accepting an alternate target", () => {
+		expect(parseCli(["push", "--json"])).toMatchObject({
+			commandName: "push",
+			args: [],
+			values: { json: true },
+		})
+		expectUsageError(["push", "example"], "agency push")
+	})
+
 	test("accepts runner selection and command inspection for work", () => {
 		expect(
 			parseCli([

package/src/cli-parser.ts

@@ -913,6 +913,16 @@ const commands = {
 			},
 		},
 	},
+	push: {
+		usage: "agency push [--json]",
+		options: outputOptions,
+		command: {
+			usage: "agency push [--json]",
+			minArgs: 0,
+			maxArgs: 0,
+			options: ["json"],
+		},
+	},
 	next: {
 		usage: "agency next [--select] [--json]",
 		options: {

package/src/cli.test.ts

@@ -502,6 +502,7 @@ describe("CLI", () => {
 			["archive", "Usage: agency archive"],
 			["restore", "Usage: agency restore"],
 			["work", "Usage: agency work"],
+			["push", "Usage: agency push"],
 			["pr", "Work with GitHub pull requests."],
 			["status", "Usage: agency status"],
 			["validate", "Usage: agency validate"],

package/src/commands/push.ts

@@ -0,0 +1,25 @@
+import { Effect } from "effect"
+import { PushService } from "../services/PushService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+export const push = (options: BaseCommandOptions = {}) =>
+	Effect.gen(function* () {
+		const publications = yield* PushService
+		const { log } = createLoggers(options)
+		const result = yield* publications.publish(options.cwd ?? process.cwd())
+		log(
+			options.json
+				? JSON.stringify(result, null, 2)
+				: `Published ${result.vcs} ${result.branch} at ${result.tip} to ${result.remote}`,
+		)
+	})
+
+export const help = `
+Usage: agency push [--json]
+
+Validate and publish the current Agency execution unit without creating a pull
+request. The command uses the durable base and branch declarations, requires the
+managed writable checkout and working status, refreshes remote state, validates
+every outgoing commit, and rejects non-fast-forward publication.
+`

package/src/protocol.ts

@@ -99,6 +99,7 @@ const errorMetadata: Readonly<Record<string, ErrorMetadata>> = {
 	},
 	ArchiveError: { code: "ARCHIVE_ERROR", retryable: false },
 	WorktreeError: { code: "WORKTREE_ERROR", retryable: false },
+	PushError: { code: "PUSH_ERROR", retryable: false },
 	PullRequestError: { code: "PULL_REQUEST_ERROR", retryable: false },
 	ReviewError: { code: "REVIEW_ERROR", retryable: false },
 	ContextError: {

package/src/services/IntegrationService.test.ts

@@ -422,6 +422,8 @@ describe("IntegrationService", () => {
 		expect(body).toContain("without creating a claim")
 		expect(body).toContain("formatting, type checks, build, dead-code checks")
 		expect(body).toContain("Review and commit the diff")
+		expect(body).toContain("Use `agency push`")
+		expect(body).toContain("never authors semantic commit descriptions")
 		expect(body).toContain("Run `agency validate`")
 		expect(body).toContain("only with explicit user intent")
 		expect(body).toContain("An execution unit remains `working`")

package/src/services/PushService.test.ts

@@ -0,0 +1,516 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { mkdir } from "node:fs/promises"
+import { join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { TaskService } from "./TaskService"
+import { PushService } from "./PushService"
+import { WorktreeService } from "./WorktreeService"
+
+interface CommandResult {
+	readonly stdout: string
+	readonly stderr: string
+	readonly exitCode: number
+}
+
+const runCommand = async (
+	args: readonly string[],
+	cwd?: string,
+): Promise<CommandResult> => {
+	const child = Bun.spawn([...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	})
+	const [stdout, stderr, exitCode] = await Promise.all([
+		new Response(child.stdout).text(),
+		new Response(child.stderr).text(),
+		child.exited,
+	])
+	return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode }
+}
+
+const requireCommand = async (args: readonly string[], cwd?: string) => {
+	const result = await runCommand(args, cwd)
+	if (result.exitCode !== 0) {
+		throw new Error(`${args.join(" ")} failed: ${result.stderr}`)
+	}
+	return result
+}
+
+describe("PushService", () => {
+	const roots: string[] = []
+
+	afterEach(async () => {
+		await Promise.all(roots.splice(0).map(cleanupTempDir))
+	})
+
+	const setup = async (vcs: "git" | "jj") => {
+		const root = await createTempDir()
+		roots.push(root)
+		const remote = join(root, "remote.git")
+		const seed = join(root, "seed")
+		const repository = join(root, "repos", "agency")
+		await mkdir(join(root, "repos"), { recursive: true })
+		await Bun.write(
+			join(root, "agency.json"),
+			`${JSON.stringify({ version: 2, vcs }, null, 2)}\n`,
+		)
+		await requireCommand([
+			"git",
+			"init",
+			"--bare",
+			"--initial-branch=main",
+			remote,
+		])
+		await requireCommand(["git", "init", "--initial-branch=main", seed])
+		await requireCommand(["git", "config", "user.name", "Agency Test"], seed)
+		await requireCommand(
+			["git", "config", "user.email", "agency@example.com"],
+			seed,
+		)
+		await Bun.write(join(seed, "README.md"), "# Test repository\n")
+		await requireCommand(["git", "add", "README.md"], seed)
+		await requireCommand(["git", "commit", "-m", "Initial commit"], seed)
+		await requireCommand(["git", "remote", "add", "origin", remote], seed)
+		await requireCommand(["git", "push", "-u", "origin", "main"], seed)
+		await requireCommand(["git", "clone", "--bare", remote, repository])
+		if (vcs === "jj") {
+			await requireCommand(["jj", "git", "init", "--colocate", repository])
+			await requireCommand(
+				["jj", "git", "remote", "add", "origin", remote],
+				repository,
+			)
+			await requireCommand(
+				["jj", "git", "fetch", "--remote", "origin"],
+				repository,
+			)
+			await requireCommand(
+				["jj", "bookmark", "create", "main", "-r", "main@origin"],
+				repository,
+			)
+			await requireCommand(
+				["jj", "config", "set", "--repo", "user.name", "Agency Test"],
+				repository,
+			)
+			await requireCommand(
+				["jj", "config", "set", "--repo", "user.email", "agency@example.com"],
+				repository,
+			)
+		}
+
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "example",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("example", "working", root),
+				),
+			),
+		)
+		const workspace = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("example", undefined, root),
+				),
+			),
+		)
+		return {
+			root,
+			remote,
+			checkout: workspace.writablePath!,
+			taskPath: join(root, "tasks", "example"),
+		}
+	}
+
+	const publish = (taskPath: string) =>
+		runTestEffect(
+			PushService.pipe(Effect.flatMap((service) => service.publish(taskPath))),
+		)
+
+	const remoteBranch = async (remote: string, branch = "task/example") =>
+		(
+			await requireCommand([
+				"git",
+				"--git-dir",
+				remote,
+				"rev-parse",
+				`refs/heads/${branch}`,
+			])
+		).stdout
+
+	test("publishes a clean Git HEAD and establishes upstream tracking", async () => {
+		const fixture = await setup("git")
+		await requireCommand(
+			["git", "config", "user.name", "Agency Test"],
+			fixture.checkout,
+		)
+		await requireCommand(
+			["git", "config", "user.email", "agency@example.com"],
+			fixture.checkout,
+		)
+		await Bun.write(join(fixture.checkout, "feature.txt"), "published\n")
+		await requireCommand(["git", "add", "feature.txt"], fixture.checkout)
+		await requireCommand(
+			["git", "commit", "-m", "Add published feature"],
+			fixture.checkout,
+		)
+
+		const result = await publish(fixture.taskPath)
+		expect(result).toMatchObject({
+			vcs: "git",
+			branch: "task/example",
+			base: "main",
+			remote: "origin",
+		})
+		expect(await remoteBranch(fixture.remote)).toBe(result.tip)
+		expect(
+			(
+				await requireCommand(
+					["git", "rev-parse", "--abbrev-ref", "@{upstream}"],
+					fixture.checkout,
+				)
+			).stdout,
+		).toBe("origin/task/example")
+	})
+
+	test("rejects dirty, mismatched, and undescribed Git publication", async () => {
+		const dirty = await setup("git")
+		await Bun.write(join(dirty.checkout, "dirty.txt"), "dirty\n")
+		await expect(publish(dirty.taskPath)).rejects.toThrow("dirty Git worktree")
+
+		const mismatched = await setup("git")
+		await requireCommand(
+			["git", "branch", "-m", "wrong-branch"],
+			mismatched.checkout,
+		)
+		await expect(publish(mismatched.taskPath)).rejects.toThrow(
+			"does not match checked-out Git branch",
+		)
+
+		const undescribed = await setup("git")
+		await requireCommand(
+			["git", "config", "user.name", "Agency Test"],
+			undescribed.checkout,
+		)
+		await requireCommand(
+			["git", "config", "user.email", "agency@example.com"],
+			undescribed.checkout,
+		)
+		await requireCommand(
+			["git", "commit", "--allow-empty", "--allow-empty-message", "-m", ""],
+			undescribed.checkout,
+		)
+		await expect(publish(undescribed.taskPath)).rejects.toThrow(
+			"has an empty message",
+		)
+	})
+
+	test("rejects Git remote divergence after refreshing remote state", async () => {
+		const fixture = await setup("git")
+		for (const [key, value] of [
+			["user.name", "Agency Test"],
+			["user.email", "agency@example.com"],
+		] as const) {
+			await requireCommand(["git", "config", key, value], fixture.checkout)
+		}
+		await Bun.write(join(fixture.checkout, "feature.txt"), "first\n")
+		await requireCommand(["git", "add", "feature.txt"], fixture.checkout)
+		await requireCommand(
+			["git", "commit", "-m", "First change"],
+			fixture.checkout,
+		)
+		await publish(fixture.taskPath)
+
+		const other = join(fixture.root, "other")
+		await requireCommand(["git", "clone", fixture.remote, other])
+		await requireCommand(["git", "checkout", "task/example"], 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", "Remote change"], other)
+		await requireCommand(["git", "push", "origin", "task/example"], other)
+
+		await Bun.write(join(fixture.checkout, "local.txt"), "local\n")
+		await requireCommand(["git", "add", "local.txt"], fixture.checkout)
+		await requireCommand(
+			["git", "commit", "-m", "Local change"],
+			fixture.checkout,
+		)
+		await expect(publish(fixture.taskPath)).rejects.toThrow(
+			"refusing a non-fast-forward update",
+		)
+	})
+
+	test("requires working status and the declared Git base in history", async () => {
+		const open = await setup("git")
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("example", "open", open.root),
+				),
+			),
+		)
+		await expect(publish(open.taskPath)).rejects.toThrow(
+			"status 'open'; status must be working",
+		)
+
+		const unrelated = await setup("git")
+		await requireCommand(
+			["git", "config", "user.name", "Agency Test"],
+			unrelated.checkout,
+		)
+		await requireCommand(
+			["git", "config", "user.email", "agency@example.com"],
+			unrelated.checkout,
+		)
+		await requireCommand(
+			["git", "checkout", "--orphan", "unrelated"],
+			unrelated.checkout,
+		)
+		await requireCommand(["git", "rm", "-rf", "."], unrelated.checkout)
+		await Bun.write(join(unrelated.checkout, "unrelated.txt"), "unrelated\n")
+		await requireCommand(["git", "add", "unrelated.txt"], unrelated.checkout)
+		await requireCommand(
+			["git", "commit", "-m", "Unrelated history"],
+			unrelated.checkout,
+		)
+		await requireCommand(
+			["git", "branch", "-M", "task/example"],
+			unrelated.checkout,
+		)
+		await expect(publish(unrelated.taskPath)).rejects.toThrow(
+			"is not an ancestor of Git HEAD",
+		)
+	})
+
+	test("rejects invalid Git and jj authors", async () => {
+		const git = await setup("git")
+		await requireCommand(
+			["git", "config", "user.name", "Agency Test"],
+			git.checkout,
+		)
+		await requireCommand(
+			["git", "config", "user.email", "agency@example.com"],
+			git.checkout,
+		)
+		await requireCommand(
+			[
+				"git",
+				"commit",
+				"--allow-empty",
+				"--author",
+				"Bad <bad>",
+				"-m",
+				"Invalid author",
+			],
+			git.checkout,
+		)
+		await expect(publish(git.taskPath)).rejects.toThrow("has an invalid author")
+
+		if (!Bun.which("jj")) return
+		const jj = await setup("jj")
+		await requireCommand(
+			["jj", "describe", "-m", "Invalid author"],
+			jj.checkout,
+		)
+		await requireCommand(
+			["jj", "metaedit", "--author", "Bad <bad>"],
+			jj.checkout,
+		)
+		const changeId = (
+			await requireCommand(
+				["jj", "log", "--no-graph", "-r", "@", "-T", "change_id"],
+				jj.checkout,
+			)
+		).stdout
+		await expect(publish(jj.taskPath)).rejects.toThrow(
+			`Change ${changeId} has an invalid author. Run: jj metaedit -r ${changeId} --author 'Name <email>'`,
+		)
+	})
+
+	test("publishes a described jj working-copy change under the declared bookmark", async () => {
+		if (!Bun.which("jj")) return
+		const fixture = await setup("jj")
+		await Bun.write(join(fixture.checkout, "feature.txt"), "published\n")
+		await requireCommand(
+			["jj", "describe", "-m", "Add published feature"],
+			fixture.checkout,
+		)
+
+		const result = await publish(fixture.taskPath)
+		expect(result).toMatchObject({
+			vcs: "jj",
+			branch: "task/example",
+			base: "main",
+			remote: "origin",
+		})
+		expect(await remoteBranch(fixture.remote)).toBe(result.tip)
+		expect(
+			(
+				await requireCommand(
+					[
+						"jj",
+						"bookmark",
+						"list",
+						"--all-remotes",
+						"-T",
+						'if(name == "task/example" && remote == "origin", tracked, "")',
+					],
+					fixture.checkout,
+				)
+			).stdout,
+		).toBe("true")
+	})
+
+	test("selects the described parent of a canonical jj post-commit working copy", async () => {
+		if (!Bun.which("jj")) return
+		const fixture = await setup("jj")
+		await Bun.write(join(fixture.checkout, "feature.txt"), "published\n")
+		await requireCommand(
+			["jj", "commit", "-m", "Add published feature"],
+			fixture.checkout,
+		)
+		const parent = (
+			await requireCommand(
+				["jj", "log", "--no-graph", "-r", "@-", "-T", "commit_id"],
+				fixture.checkout,
+			)
+		).stdout
+
+		const result = await publish(fixture.taskPath)
+		expect(result.tip).toBe(parent)
+		expect(await remoteBranch(fixture.remote)).toBe(parent)
+	})
+
+	test("preserves a described empty jj change and diagnoses missing semantics", async () => {
+		if (!Bun.which("jj")) return
+		const described = await setup("jj")
+		await requireCommand(
+			["jj", "describe", "-m", "Record intentional empty change"],
+			described.checkout,
+		)
+		const describedTip = (
+			await requireCommand(
+				["jj", "log", "--no-graph", "-r", "@", "-T", "commit_id"],
+				described.checkout,
+			)
+		).stdout
+		expect((await publish(described.taskPath)).tip).toBe(describedTip)
+
+		const undescribed = await setup("jj")
+		await Bun.write(join(undescribed.checkout, "feature.txt"), "missing\n")
+		const changeId = (
+			await requireCommand(
+				["jj", "log", "--no-graph", "-r", "@", "-T", "change_id"],
+				undescribed.checkout,
+			)
+		).stdout
+		await expect(publish(undescribed.taskPath)).rejects.toThrow(
+			`Change ${changeId} has no description. Run: jj describe -r ${changeId}`,
+		)
+	})
+
+	test("rejects an empty jj task and remote bookmark divergence", async () => {
+		if (!Bun.which("jj")) return
+		const empty = await setup("jj")
+		await expect(publish(empty.taskPath)).rejects.toThrow(
+			"No changes to publish after base 'main'",
+		)
+
+		const fixture = await setup("jj")
+		await Bun.write(join(fixture.checkout, "feature.txt"), "first\n")
+		await requireCommand(
+			["jj", "describe", "-m", "First change"],
+			fixture.checkout,
+		)
+		await publish(fixture.taskPath)
+
+		const other = join(fixture.root, "other")
+		await requireCommand(["git", "clone", fixture.remote, other])
+		await requireCommand(["git", "checkout", "task/example"], 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", "Remote change"], other)
+		await requireCommand(["git", "push", "origin", "task/example"], other)
+
+		await requireCommand(["jj", "new", "@"], fixture.checkout)
+		await Bun.write(join(fixture.checkout, "local.txt"), "local\n")
+		await requireCommand(
+			["jj", "describe", "-m", "Local change"],
+			fixture.checkout,
+		)
+		await expect(publish(fixture.taskPath)).rejects.toThrow(
+			"refusing to move it",
+		)
+	})
+
+	test("rejects conflicted jj changes with an actionable change ID", async () => {
+		if (!Bun.which("jj")) return
+		const fixture = await setup("jj")
+		await Bun.write(join(fixture.checkout, "README.md"), "left\n")
+		await requireCommand(
+			["jj", "describe", "-m", "Left change"],
+			fixture.checkout,
+		)
+		await requireCommand(
+			["jj", "bookmark", "create", "left", "-r", "@"],
+			fixture.checkout,
+		)
+		await requireCommand(["jj", "new", "main@origin"], fixture.checkout)
+		await Bun.write(join(fixture.checkout, "README.md"), "right\n")
+		await requireCommand(
+			["jj", "describe", "-m", "Right change"],
+			fixture.checkout,
+		)
+		await requireCommand(
+			["jj", "bookmark", "create", "right", "-r", "@"],
+			fixture.checkout,
+		)
+		await requireCommand(["jj", "new", "left", "right"], fixture.checkout)
+		await requireCommand(
+			["jj", "describe", "-m", "Conflicted merge"],
+			fixture.checkout,
+		)
+		const changeId = (
+			await requireCommand(
+				["jj", "log", "--no-graph", "-r", "@", "-T", "change_id"],
+				fixture.checkout,
+			)
+		).stdout
+		expect(
+			(
+				await requireCommand(
+					["jj", "log", "--no-graph", "-r", "@", "-T", "conflict"],
+					fixture.checkout,
+				)
+			).stdout,
+		).toBe("true")
+		await expect(publish(fixture.taskPath)).rejects.toThrow(
+			`Change ${changeId} contains conflicts. Run: jj resolve -r ${changeId}`,
+		)
+	})
+})

package/src/services/PushService.ts

@@ -0,0 +1,576 @@
+import { Data, Effect } from "effect"
+import { ContextService } from "./ContextService"
+import { FileSystemService } from "./FileSystemService"
+import { PhaseService } from "./PhaseService"
+import { TaskService } from "./TaskService"
+import { WorkbaseService } from "./WorkbaseService"
+
+class PushError extends Data.TaggedError("PushError")<{
+	readonly message: string
+}> {}
+
+interface CommandResult {
+	readonly exitCode: number
+	readonly stdout: string
+	readonly stderr: string
+}
+
+interface CommitMetadata {
+	readonly commitId: string
+	readonly changeId?: string
+	readonly description: string
+	readonly empty: boolean
+	readonly authorName: string
+	readonly authorEmail: string
+	readonly conflict: boolean
+	readonly parents: readonly string[]
+}
+
+interface PushResult {
+	readonly vcs: "git" | "jj"
+	readonly taskId: string
+	readonly phaseId?: string
+	readonly branch: string
+	readonly base: string
+	readonly remote: string
+	readonly tip: string
+	readonly changeId?: string
+}
+
+const validEmail = (email: string) => /^[^@\s]+@[^@\s]+$/.test(email)
+
+const requireCommand = (
+	fs: FileSystemService,
+	args: readonly string[],
+	cwd: string,
+	label: string,
+) =>
+	fs.runCommand(args, { cwd, captureOutput: true }).pipe(
+		Effect.flatMap((result) =>
+			result.exitCode === 0
+				? Effect.succeed(result)
+				: Effect.fail(
+						new PushError({
+							message: `${label}: ${result.stderr.trim() || result.stdout.trim()}`,
+						}),
+					),
+		),
+	)
+
+const git = (
+	fs: FileSystemService,
+	cwd: string,
+	args: readonly string[],
+	label: string,
+) => requireCommand(fs, ["git", ...args], cwd, label)
+
+const gitRevision = (fs: FileSystemService, cwd: string, revision: string) =>
+	fs
+		.runCommand(["git", "rev-parse", "--verify", `${revision}^{commit}`], {
+			cwd,
+			captureOutput: true,
+		})
+		.pipe(
+			Effect.map((result) =>
+				result.exitCode === 0 ? result.stdout.trim() || null : null,
+			),
+		)
+
+const gitAncestor = (
+	fs: FileSystemService,
+	cwd: string,
+	ancestor: string,
+	descendant: string,
+) =>
+	fs
+		.runCommand(["git", "merge-base", "--is-ancestor", ancestor, descendant], {
+			cwd,
+			captureOutput: true,
+		})
+		.pipe(
+			Effect.flatMap((result) => {
+				if (result.exitCode === 0) return Effect.succeed(true)
+				if (result.exitCode === 1) return Effect.succeed(false)
+				return Effect.fail(
+					new PushError({
+						message: `Failed to inspect Git ancestry: ${result.stderr.trim()}`,
+					}),
+				)
+			}),
+		)
+
+const parseGitCommits = (output: string): readonly CommitMetadata[] =>
+	output
+		.split("\x1e")
+		.map((record) => record.replace(/^\n+|\n+$/g, ""))
+		.filter(Boolean)
+		.map((record) => {
+			const [
+				commitId = "",
+				authorName = "",
+				authorEmail = "",
+				description = "",
+			] = record.split("\0")
+			return {
+				commitId,
+				description,
+				empty: false,
+				authorName,
+				authorEmail,
+				conflict: false,
+				parents: [],
+			}
+		})
+
+const validateGitCommits = (
+	commits: readonly CommitMetadata[],
+	base: string,
+) => {
+	if (commits.length === 0) {
+		throw new PushError({
+			message: `No commits to publish after base '${base}'`,
+		})
+	}
+	const issues: string[] = []
+	for (const commit of commits) {
+		if (!commit.description.trim()) {
+			issues.push(
+				`Commit ${commit.commitId} has an empty message. Run: git rebase -i ${base}`,
+			)
+		}
+		if (!commit.authorName.trim() || !validEmail(commit.authorEmail.trim())) {
+			issues.push(
+				`Commit ${commit.commitId} has an invalid author. Run: git rebase -i ${base}`,
+			)
+		}
+	}
+	if (issues.length > 0) throw new PushError({ message: issues.join("\n") })
+}
+
+const publishGit = (
+	fs: FileSystemService,
+	checkout: string,
+	remote: string,
+	branch: string,
+	base: string,
+) =>
+	Effect.gen(function* () {
+		const currentBranch = yield* git(
+			fs,
+			checkout,
+			["symbolic-ref", "--quiet", "--short", "HEAD"],
+			"Git checkout must be attached to the declared branch",
+		)
+		if (currentBranch.stdout.trim() !== branch) {
+			return yield* new PushError({
+				message: `Declared delivery branch '${branch}' does not match checked-out Git branch '${currentBranch.stdout.trim()}'`,
+			})
+		}
+		const status = yield* git(
+			fs,
+			checkout,
+			["status", "--porcelain=v1"],
+			"Failed to inspect Git status",
+		)
+		if (status.stdout.length > 0) {
+			return yield* new PushError({
+				message:
+					"Cannot publish a dirty Git worktree; commit or discard changes first",
+			})
+		}
+
+		yield* git(
+			fs,
+			checkout,
+			["fetch", remote, `+refs/heads/*:refs/remotes/${remote}/*`],
+			`Failed to fetch remote '${remote}'`,
+		)
+		const tip = yield* gitRevision(fs, checkout, "HEAD")
+		const baseRevision = yield* gitRevision(
+			fs,
+			checkout,
+			`refs/remotes/${remote}/${base}`,
+		)
+		if (!tip || !baseRevision) {
+			return yield* new PushError({
+				message: `Declared base '${base}' was not found on remote '${remote}'`,
+			})
+		}
+		if (!(yield* gitAncestor(fs, checkout, baseRevision, tip))) {
+			return yield* new PushError({
+				message: `Declared base '${base}' (${baseRevision}) is not an ancestor of Git HEAD (${tip})`,
+			})
+		}
+
+		const log = yield* git(
+			fs,
+			checkout,
+			[
+				"log",
+				"--format=%H%x00%an%x00%ae%x00%B%x00%x1e",
+				`${baseRevision}..${tip}`,
+			],
+			"Failed to inspect outgoing Git commits",
+		)
+		yield* Effect.try({
+			try: () => validateGitCommits(parseGitCommits(log.stdout), base),
+			catch: (cause) => cause as PushError,
+		})
+
+		const remoteTip = yield* gitRevision(
+			fs,
+			checkout,
+			`refs/remotes/${remote}/${branch}`,
+		)
+		if (remoteTip && !(yield* gitAncestor(fs, checkout, remoteTip, tip))) {
+			return yield* new PushError({
+				message: `Remote branch '${branch}' on '${remote}' is not an ancestor of Git HEAD; refusing a non-fast-forward update`,
+			})
+		}
+
+		yield* git(
+			fs,
+			checkout,
+			["push", remote, `HEAD:refs/heads/${branch}`],
+			`Failed to push declared branch '${branch}'`,
+		)
+		yield* git(
+			fs,
+			checkout,
+			[
+				"config",
+				`remote.${remote}.fetch`,
+				`+refs/heads/*:refs/remotes/${remote}/*`,
+			],
+			`Failed to configure remote '${remote}' tracking`,
+		)
+		yield* git(
+			fs,
+			checkout,
+			[
+				"fetch",
+				remote,
+				`+refs/heads/${branch}:refs/remotes/${remote}/${branch}`,
+			],
+			`Failed to refresh published branch '${branch}'`,
+		)
+		yield* git(
+			fs,
+			checkout,
+			["branch", "--set-upstream-to", `${remote}/${branch}`, branch],
+			`Failed to establish upstream tracking for branch '${branch}'`,
+		)
+		return { tip }
+	})
+
+const jjTemplate =
+	'"{\\"commitId\\":" ++ json(commit_id) ++ ",\\"changeId\\":" ++ json(change_id) ++ ",\\"description\\":" ++ json(description) ++ ",\\"empty\\":" ++ json(empty) ++ ",\\"authorName\\":" ++ json(author.name()) ++ ",\\"authorEmail\\":" ++ json(author.email()) ++ ",\\"conflict\\":" ++ json(conflict) ++ ",\\"parents\\":" ++ json(parents.map(|parent| parent.commit_id())) ++ "}\\n"'
+
+const jjExact = (value: string) =>
+	value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')
+
+const jj = (
+	fs: FileSystemService,
+	cwd: string,
+	args: readonly string[],
+	label: string,
+) => requireCommand(fs, ["jj", "--no-pager", ...args], cwd, label)
+
+const jjCommits = (fs: FileSystemService, cwd: string, revision: string) =>
+	jj(
+		fs,
+		cwd,
+		["log", "--no-graph", "-r", revision, "-T", jjTemplate],
+		"Failed to inspect jj changes",
+	).pipe(
+		Effect.map((result) =>
+			result.stdout
+				.split("\n")
+				.filter(Boolean)
+				.map((line) => JSON.parse(line) as CommitMetadata),
+		),
+	)
+
+const jjRevision = (fs: FileSystemService, cwd: string, revision: string) =>
+	jjCommits(fs, cwd, revision).pipe(
+		Effect.map((commits) => {
+			if (commits.length === 0) return null
+			if (commits.length === 1) return commits[0]!
+			throw new PushError({
+				message: `Revision '${revision}' resolves to multiple jj commits`,
+			})
+		}),
+	)
+
+const optionalJjRevision = (
+	fs: FileSystemService,
+	cwd: string,
+	revision: string,
+) =>
+	jjCommits(fs, cwd, revision).pipe(
+		Effect.catchTag("PushError", () => Effect.succeed([])),
+		Effect.map((commits) => {
+			if (commits.length === 0) return null
+			if (commits.length === 1) return commits[0]!
+			throw new PushError({
+				message: `Bookmark '${revision}' is conflicted or resolves to multiple commits`,
+			})
+		}),
+	)
+
+const jjAncestor = (
+	fs: FileSystemService,
+	cwd: string,
+	ancestor: string,
+	descendant: string,
+) =>
+	jjCommits(fs, cwd, `${ancestor} & ::${descendant}`).pipe(
+		Effect.map((commits) => commits.length === 1),
+	)
+
+const validateJjCommits = (
+	commits: readonly CommitMetadata[],
+	base: string,
+) => {
+	if (commits.length === 0) {
+		throw new PushError({
+			message: `No changes to publish after base '${base}'`,
+		})
+	}
+	const issues: string[] = []
+	for (const commit of commits) {
+		const id = commit.changeId!
+		if (commit.conflict) {
+			issues.push(`Change ${id} contains conflicts. Run: jj resolve -r ${id}`)
+		}
+		if (!commit.description.trim()) {
+			issues.push(`Change ${id} has no description. Run: jj describe -r ${id}`)
+		}
+		if (!commit.authorName.trim() || !validEmail(commit.authorEmail.trim())) {
+			issues.push(
+				`Change ${id} has an invalid author. Run: jj metaedit -r ${id} --author 'Name <email>'`,
+			)
+		}
+	}
+	if (issues.length > 0) throw new PushError({ message: issues.join("\n") })
+}
+
+const publishJj = (
+	fs: FileSystemService,
+	checkout: string,
+	remote: string,
+	branch: string,
+	base: string,
+) =>
+	Effect.gen(function* () {
+		yield* jj(
+			fs,
+			checkout,
+			["git", "fetch", "--remote", remote],
+			`Failed to fetch remote '${remote}'`,
+		)
+		const workingCopy = yield* jjRevision(fs, checkout, "@")
+		if (!workingCopy) {
+			return yield* new PushError({
+				message: "jj working copy commit was not found",
+			})
+		}
+		const canonicalPostCommit =
+			workingCopy.empty &&
+			!workingCopy.description.trim() &&
+			workingCopy.parents.length === 1
+		const tip = canonicalPostCommit
+			? yield* jjRevision(fs, checkout, "@-")
+			: workingCopy
+		if (!tip) {
+			return yield* new PushError({
+				message: "jj publication tip was not found",
+			})
+		}
+
+		const baseBookmark = `${base}@${remote}`
+		const baseRevision = yield* optionalJjRevision(
+			fs,
+			checkout,
+			`remote_bookmarks(exact:"${jjExact(base)}", exact:"${jjExact(remote)}")`,
+		)
+		if (!baseRevision) {
+			return yield* new PushError({
+				message: `Declared base '${base}' was not found on remote '${remote}'`,
+			})
+		}
+		if (
+			!(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})`,
+			})
+		}
+
+		const outgoing = yield* jjCommits(
+			fs,
+			checkout,
+			`${baseRevision.commitId}..${tip.commitId}`,
+		)
+		yield* Effect.try({
+			try: () => validateJjCommits(outgoing, base),
+			catch: (cause) => cause as PushError,
+		})
+
+		const localBookmark = yield* optionalJjRevision(
+			fs,
+			checkout,
+			`bookmarks(exact:"${jjExact(branch)}")`,
+		)
+		if (
+			localBookmark &&
+			!(yield* jjAncestor(fs, checkout, localBookmark.commitId, tip.commitId))
+		) {
+			return yield* new PushError({
+				message: `Local bookmark '${branch}' is not an ancestor of jj tip ${tip.changeId}; refusing to move it`,
+			})
+		}
+		const remoteBookmark = yield* optionalJjRevision(
+			fs,
+			checkout,
+			`remote_bookmarks(exact:"${jjExact(branch)}", exact:"${jjExact(remote)}")`,
+		)
+		if (
+			remoteBookmark &&
+			!(yield* jjAncestor(fs, checkout, remoteBookmark.commitId, tip.commitId))
+		) {
+			return yield* new PushError({
+				message: `Remote bookmark '${branch}@${remote}' is not an ancestor of jj tip ${tip.changeId}; refusing a non-fast-forward update`,
+			})
+		}
+
+		yield* jj(
+			fs,
+			checkout,
+			["bookmark", "set", branch, "-r", tip.commitId],
+			`Failed to set declared bookmark '${branch}'`,
+		)
+		yield* jj(
+			fs,
+			checkout,
+			["git", "push", "--remote", remote, "--bookmark", branch],
+			`Failed to push declared bookmark '${branch}'`,
+		)
+		yield* jj(
+			fs,
+			checkout,
+			["bookmark", "track", `${branch}@${remote}`],
+			`Failed to track remote bookmark '${branch}@${remote}'`,
+		)
+		return { tip: tip.commitId, changeId: tip.changeId }
+	})
+
+export class PushService extends Effect.Service<PushService>()("PushService", {
+	sync: () => ({
+		publish: (startPath: string = process.cwd()) =>
+			Effect.gen(function* () {
+				const contexts = yield* ContextService
+				const fs = yield* FileSystemService
+				const tasks = yield* TaskService
+				const phases = yield* PhaseService
+				const workbase = yield* WorkbaseService
+				const context = yield* contexts.get({
+					cwd: startPath,
+					target: ".",
+					compact: true,
+				})
+				if (!context.validation.valid) {
+					return yield* new PushError({
+						message: "Cannot publish from an invalid Agency workbase",
+					})
+				}
+				if (context.target.kind !== "task" && context.target.kind !== "phase") {
+					return yield* new PushError({
+						message: "agency push must run from an execution task or phase",
+					})
+				}
+				if (
+					context.authority.mode !== "execution" ||
+					!context.authority.writable
+				) {
+					return yield* new PushError({
+						message:
+							"Current Agency target has no writable execution authority",
+					})
+				}
+				if (
+					!context.workspace?.writable?.materialized ||
+					!context.workspace.writable.registered
+				) {
+					return yield* new PushError({
+						message:
+							"Current Agency writable checkout is not materialized and registered",
+					})
+				}
+				const blockers = context.graph.readiness.blockers.filter(
+					(blocker) =>
+						blocker.kind === "dependency" || blocker.kind === "validation",
+				)
+				if (blockers.length > 0) {
+					return yield* new PushError({
+						message: `Cannot publish blocked Agency work: ${blockers.map((blocker) => blocker.reason).join("; ")}`,
+					})
+				}
+
+				const taskId = context.target.taskId
+				if (!taskId) {
+					return yield* new PushError({
+						message: "Current Agency execution target has no task ID",
+					})
+				}
+				const phaseId =
+					context.target.kind === "phase" ? context.target.phaseId : undefined
+				const task = yield* tasks.show(taskId, context.workbase.root)
+				const execution =
+					"phases" in task.data
+						? phaseId
+							? (yield* phases.show(taskId, phaseId, context.workbase.root))
+									.data
+							: null
+						: task.data
+				if (!execution || "review" in execution) {
+					return yield* new PushError({
+						message: "Current Agency target is not a delivery execution unit",
+					})
+				}
+				if (execution.status !== "working") {
+					return yield* new PushError({
+						message: `Cannot publish Agency work with status '${execution.status}'; status must be working`,
+					})
+				}
+				const checkout = context.authority.writable.checkoutPath
+				const { config } = yield* workbase.loadConfig(context.workbase.root)
+				const remote = config.delivery?.remote ?? "origin"
+				const published =
+					context.workbase.vcs === "jj"
+						? yield* publishJj(
+								fs,
+								checkout,
+								remote,
+								execution.branch,
+								execution.base,
+							)
+						: yield* publishGit(
+								fs,
+								checkout,
+								remote,
+								execution.branch,
+								execution.base,
+							)
+				return {
+					vcs: context.workbase.vcs,
+					taskId,
+					...(phaseId ? { phaseId } : {}),
+					branch: execution.branch,
+					base: execution.base,
+					remote,
+					...published,
+				} satisfies PushResult
+			}),
+	}),
+}) {}

package/src/test-utils.ts

@@ -11,6 +11,7 @@ import { TaskService } from "./services/TaskService"
 import { PhaseService } from "./services/PhaseService"
 import { WorktreeService } from "./services/WorktreeService"
 import { PullRequestService } from "./services/PullRequestService"
+import { PushService } from "./services/PushService"
 import { ArchiveService } from "./services/ArchiveService"
 import { IntegrationService } from "./services/IntegrationService"
 import { ContextService } from "./services/ContextService"
@@ -46,6 +47,7 @@ const TestLayer = Layer.mergeAll(
 	PhaseService.Default,
 	WorktreeService.Default,
 	PullRequestService.Default,
+	PushService.Default,
 	ArchiveService.Default,
 	IntegrationService.Default,
 	ContextService.Default,

package/src/workbase/AGENTS.md

@@ -69,6 +69,11 @@ change only the writable checkout, keep durable decisions current, and run the
 repository's formatting, type checks, build, dead-code checks, and focused tests.
 Review and commit the diff according to the repository's instructions.
 
+Use `agency push` from an execution task or phase to validate and publish its
+declared delivery branch or bookmark without creating a pull request. The
+command never authors semantic commit descriptions; resolve its reported change
+IDs and remediation commands before retrying.
+
 `agency work` is the human launch flow: it reconciles managed integration,
 selects work, checks readiness, prepares checkouts, marks execution work
 `working` without creating a claim, and starts the runner. Epic and multi-phase