@markjaquith/agency 2.54.3 → 2.55.0

package/README.md

@@ -276,6 +276,19 @@ Execution-unit runners also receive `AGENCY_WRITABLE_CHECKOUT` with the
 authoritative writable checkout path.
 `AGENCY_CLAIM_REVISION` is empty for local `agency work` launches.
 `AGENCY_PROMPT` is empty unless `--auto` is set.
+Autonomous prompts begin `Agency worker launch target: <target>.`, carrying the
+same canonical target as `AGENCY_TARGET`. This is the process-local fallback for
+runner clients that attach to a long-lived process and lose launch environment
+variables. A worker must verify either signal against `agency context . --json`
+before acting; a matching worker performs the task directly and must not invoke
+`agency work` for the same target. Managed guidance also fails safe for older
+generated prompts when their document paths, current directory, and active valid
+context all agree. Herdr is not part of this identity contract.
+The managed OpenCode plugin validates the marker against Agency context, binds it
+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.
 Agency's managed OpenCode plugin grants the active workbase external-directory
@@ -799,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...]
 ```
@@ -852,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.3",
+  "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"],
@@ -1177,7 +1178,7 @@ status: open
 					cwd: contract.cwd,
 					env: environment,
 				})
-				expect(probe.exitCode).toBe(0)
+				expect(probe.exitCode, probe.stderr.toString()).toBe(0)
 				const agent = JSON.parse(probe.stdout.toString())
 				expect(agent.permission).toEqual(
 					expect.arrayContaining([

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/commands/work.test.ts

@@ -98,6 +98,8 @@ const createHarness = (options: HarnessOptions = {}) => {
 		cwd: string
 	}> = []
 	const launchEnvironments: Array<Readonly<Record<string, string>>> = []
+	const launchProcessEnvironments: Array<Record<string, string | undefined>> =
+		[]
 	const materializeOptions: Array<
 		Parameters<WorktreeService["materialize"]>[3]
 	> = []
@@ -265,6 +267,11 @@ const createHarness = (options: HarnessOptions = {}) => {
 		events.push(`launch:${cli}`)
 		launches.push({ cli, args, cwd })
 		launchEnvironments.push(environment)
+		launchProcessEnvironments.push({
+			AGENCY_SESSION_ID: process.env.AGENCY_SESSION_ID,
+			AGENCY_TARGET: process.env.AGENCY_TARGET,
+			AGENCY_PROMPT: process.env.AGENCY_PROMPT,
+		})
 		if (options.launchError) throw options.launchError
 	}
 	const defaultPick: PickWorkTarget = () => Effect.succeed(null)
@@ -307,6 +314,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 		probes,
 		launches,
 		launchEnvironments,
+		launchProcessEnvironments,
 		materializeOptions,
 		statusUpdates,
 		taskStatuses,
@@ -484,7 +492,7 @@ describe("work command", () => {
 			args: [
 				"opencode",
 				"--prompt",
-				"Work on the epic. Read /workbase/epics/delivery/EPIC.md.",
+				"Agency worker launch target: epic:delivery. Work on the epic. Read /workbase/epics/delivery/EPIC.md.",
 			],
 			cwd: "/workbase/epics/delivery",
 		})
@@ -538,7 +546,7 @@ describe("work command", () => {
 			args: [
 				"opencode",
 				"--prompt",
-				"Work on the task. Read /workbase/tasks/delivery/TASK.md.",
+				"Agency worker launch target: task:delivery. Work on the task. Read /workbase/tasks/delivery/TASK.md.",
 			],
 			cwd: "/workbase/tasks/delivery",
 		})
@@ -565,7 +573,7 @@ describe("work command", () => {
 			args: [
 				"opencode",
 				"--prompt",
-				"Start the task. Read /workbase/tasks/example/TASK.md and /workbase/tasks/example/phases/implementation/PHASE.md.",
+				"Agency worker launch target: execution-unit:phase/example/implementation. Start the task. Read /workbase/tasks/example/TASK.md and /workbase/tasks/example/phases/implementation/PHASE.md.",
 			],
 			cwd: phaseDirectory,
 		})
@@ -797,11 +805,17 @@ describe("work command", () => {
 		expect(harness.launches[0]?.args).toEqual([
 			"opencode",
 			"--prompt",
-			"Start the task. Read /workbase/tasks/example/TASK.md.",
+			"Agency worker launch target: execution-unit:task/example. Start the task. Read /workbase/tasks/example/TASK.md.",
 		])
 		expect(harness.launchEnvironments[0]?.AGENCY_PROMPT).toBe(
-			"Start the task. Read /workbase/tasks/example/TASK.md.",
+			"Agency worker launch target: execution-unit:task/example. Start the task. Read /workbase/tasks/example/TASK.md.",
 		)
+		expect(harness.launchProcessEnvironments[0]).toEqual({
+			AGENCY_SESSION_ID: harness.launchEnvironments[0]?.AGENCY_SESSION_ID,
+			AGENCY_TARGET: "execution-unit:task/example",
+			AGENCY_PROMPT:
+				"Agency worker launch target: execution-unit:task/example. Start the task. Read /workbase/tasks/example/TASK.md.",
+		})
 	})
 
 	test("continues existing work with the resume command", async () => {
@@ -813,10 +827,10 @@ describe("work command", () => {
 			"opencode",
 			"--continue",
 			"--prompt",
-			"Continue the task. Read /workbase/tasks/example/TASK.md.",
+			"Agency worker launch target: execution-unit:task/example. Continue the task. Read /workbase/tasks/example/TASK.md.",
 		])
 		expect(harness.launchEnvironments[0]?.AGENCY_PROMPT).toBe(
-			"Continue the task. Read /workbase/tasks/example/TASK.md.",
+			"Agency worker launch target: execution-unit:task/example. Continue the task. Read /workbase/tasks/example/TASK.md.",
 		)
 	})
 
@@ -840,7 +854,7 @@ describe("work command", () => {
 				"opencode",
 				"--continue",
 				"--prompt",
-				"Continue the task. Read /workbase/tasks/example/TASK.md and /workbase/tasks/example/phases/implementation/PHASE.md.",
+				"Agency worker launch target: execution-unit:phase/example/implementation. Continue the task. Read /workbase/tasks/example/TASK.md and /workbase/tasks/example/phases/implementation/PHASE.md.",
 			],
 			cwd: phaseDirectory,
 		})
@@ -870,7 +884,7 @@ describe("work command", () => {
 				"codex",
 				"--task",
 				"example",
-				"Start the task. Read /workbase/tasks/example/TASK.md.",
+				"Agency worker launch target: execution-unit:task/example. Start the task. Read /workbase/tasks/example/TASK.md.",
 			],
 			cwd: taskDirectory,
 		})

package/src/commands/work.ts

@@ -264,6 +264,7 @@ export const work = (
 			launchPath = dirname(workspace.phasePath ?? workspace.taskPath)
 			writablePath = workspace.writablePath ?? undefined
 		}
+		prompt = `Agency worker launch target: ${targetNodeId(target)}. ${prompt}`
 
 		const explicitlyRequested = Boolean(
 			options.runner ||

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

@@ -129,6 +129,36 @@ describe("IntegrationService", () => {
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			"config.skills.paths = [...new Set",
 		)
+		expect(managedWorkbaseOpencodePlugin).toContain('"chat.message"')
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"if (!Array.isArray(parts)) return",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			'"experimental.chat.system.transform"',
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain('"shell.env"')
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"if (context?.target !== launchTarget) return",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"agencyContext(directory, false)",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"result.validation?.valid !== true",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"dirname(document) !== resolve(directory)",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"!result.authority?.writable?.checkoutPath",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain('status !== "working"')
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"output.env.AGENCY_SESSION_ID = sessionID",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"Do not invoke agency work for this target",
+		)
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			".map((path) => `${path}${sep}.`)",
 		)
@@ -142,6 +172,121 @@ describe("IntegrationService", () => {
 		).toBe(false)
 	})
 
+	test("binds validated worker identity to an OpenCode session", async () => {
+		const path = join(root, "agency-repository-skills.ts")
+		const contextResponse = JSON.stringify({
+			version: 1,
+			ok: true,
+			result: {
+				workbase: { root },
+				target: {
+					kind: "task",
+					taskId: "example",
+					path: join(root, "TASK.md"),
+				},
+				authority: {
+					mode: "execution",
+					writable: { checkoutPath: join(root, "tasks/example/code/agency") },
+				},
+				documents: { task: { data: { status: "working" } } },
+				validation: { valid: true, warnings: [] },
+			},
+		})
+		await Bun.write(
+			path,
+			managedWorkbaseOpencodePlugin
+				.replace("const contextTarget =", "export const contextTarget =")
+				.replace("const agencyContext =", "export const agencyContext =")
+				.replace(
+					"const workerLaunchTarget =",
+					"export const workerLaunchTarget =",
+				),
+		)
+		const originalSpawn = Bun.spawn
+		Bun.spawn = (() =>
+			({
+				stdout: new Response(contextResponse).body!,
+				exited: Promise.resolve(0),
+			}) as ReturnType<typeof Bun.spawn>) as typeof Bun.spawn
+		try {
+			const generated = await import(
+				`${pathToFileURL(path).href}?worker-identity`
+			)
+			expect(
+				generated.workerLaunchTarget([
+					{
+						type: "text",
+						text: "Agency worker launch target: execution-unit:task/example. Start the task.",
+					},
+				]),
+			).toBe("execution-unit:task/example")
+			expect(generated.workerLaunchTarget(undefined)).toBeUndefined()
+			expect(
+				generated.contextTarget({
+					target: { kind: "task", taskId: "example" },
+					authority: { mode: "execution" },
+				}),
+			).toBe("execution-unit:task/example")
+			expect(await generated.agencyContext(root)).toMatchObject({
+				root,
+				target: "execution-unit:task/example",
+				task: "example",
+			})
+			const hooks = await generated.default({ directory: root } as never)
+			await hooks["chat.message"]!(
+				{ sessionID: "worker-session" } as never,
+				{
+					parts: [
+						{
+							type: "text",
+							text: "Agency worker launch target: execution-unit:task/example. Start the task.",
+						},
+					],
+				} as never,
+			)
+			await hooks["chat.message"]!(
+				{ sessionID: "mismatched-session" } as never,
+				{
+					parts: [
+						{
+							type: "text",
+							text: "Agency worker launch target: execution-unit:task/other. Start the task.",
+						},
+					],
+				} as never,
+			)
+
+			const system = { system: [] as string[] }
+			await hooks["experimental.chat.system.transform"]!(
+				{ sessionID: "worker-session" } as never,
+				system,
+			)
+			expect(system.system).toEqual([
+				expect.stringContaining(
+					"active worker for execution-unit:task/example",
+				),
+			])
+			const mismatchedSystem = { system: [] as string[] }
+			await hooks["experimental.chat.system.transform"]!(
+				{ sessionID: "mismatched-session" } as never,
+				mismatchedSystem,
+			)
+			expect(mismatchedSystem.system).toEqual([])
+
+			const shell = { env: {} as Record<string, string> }
+			await hooks["shell.env"]!({ sessionID: "worker-session" } as never, shell)
+			expect(shell.env).toMatchObject({
+				AGENCY_SESSION_ID: "worker-session",
+				AGENCY_TARGET: "execution-unit:task/example",
+				AGENCY_WORKBASE: root,
+				AGENCY_TASK_ID: "example",
+				AGENCY_WRITABLE_CHECKOUT: join(root, "tasks/example/code/agency"),
+			})
+		} finally {
+			Bun.spawn = originalSpawn
+		}
+	})
+
 	test("registers a TUI-only /agency-debug diagnostic", async () => {
 		const config = JSON.parse(managedBody(managedWorkbaseOpencodeTui))
 		expect(config).toEqual({
@@ -268,10 +413,17 @@ describe("IntegrationService", () => {
 		expect(body).toContain("Preserve parent backlinks")
 		expect(body).toContain("dirty-worktree, active-claim, revision")
 		expect(body).toContain("`agency work` is the human launch flow")
+		expect(body).toContain("Agency worker launch target: <target>.")
+		expect(body).toContain("environment variables and a generated")
+		expect(body).toContain("the initial instruction is a generated")
+		expect(body).toContain("Herdr state is never part of worker identity")
+		expect(body).toMatch(/If the prompt\s+and context disagree/)
 		expect(body).toContain("marks execution work")
 		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`")