@markjaquith/agency 2.54.4 → 2.56.0

package/src/services/WorktreeService.ts

@@ -8,7 +8,12 @@ import {
 	expandWorktreeCreateCommand,
 	worktreeCommandEnvironment,
 } from "../workbase/worktree-command"
-import type { RepositoryReference } from "../workbase/schemas"
+import {
+	expandPostCheckoutCommand,
+	postCheckoutCommandEnvironment,
+	type CheckoutCommandVariables,
+} from "../workbase/checkout-command"
+import type { RepositoryReference, WorkbaseConfig } from "../workbase/schemas"
 import type { BaseCommandOptions } from "../utils/command"
 import { createLoggers } from "../utils/effect"
 import { withWorktreeLocks } from "./WorktreeLock"
@@ -35,6 +40,7 @@ interface WorkspaceOperation {
 		| "create-branch"
 		| "create-worktree"
 		| "create-workspace"
+		| "post-checkout"
 	readonly repo: string
 	readonly command: readonly string[]
 	readonly status: "planned" | "completed"
@@ -176,6 +182,70 @@ const formatCommand = (args: readonly string[]) =>
 		)
 		.join(" ")
 
+const runPostCheckoutHook = (options: {
+	readonly command: readonly string[] | undefined
+	readonly variables: CheckoutCommandVariables
+	readonly dryRun: boolean
+	readonly forwardOutput: boolean
+	readonly verboseLog: (...args: unknown[]) => void
+	readonly operations: WorkspaceOperation[]
+}) =>
+	Effect.gen(function* () {
+		if (!options.command) return
+		let command: string[]
+		try {
+			command = expandPostCheckoutCommand(options.command, options.variables)
+		} catch (cause) {
+			return yield* new WorktreeError({
+				message:
+					cause instanceof Error
+						? cause.message
+						: "Invalid postCheckoutCommand",
+				cause,
+			})
+		}
+		options.verboseLog(
+			`${options.dryRun ? "Planning" : "Running"} post-checkout command for '${options.variables.repoAlias}': ${formatCommand(command)}`,
+		)
+		if (options.dryRun) {
+			options.operations.push({
+				action: "post-checkout",
+				repo: options.variables.repoAlias,
+				command,
+				status: "planned",
+			})
+			return
+		}
+		const result = yield* FileSystemService.pipe(
+			Effect.flatMap((fs) =>
+				fs.runCommand(command, {
+					cwd: options.variables.checkoutPath,
+					captureOutput: true,
+					forwardOutput: options.forwardOutput,
+					env: postCheckoutCommandEnvironment(options.variables),
+				}),
+			),
+			Effect.mapError(
+				(cause) =>
+					new WorktreeError({
+						message: `Failed to start post-checkout command for '${options.variables.repoAlias}': ${cause.message}`,
+						cause,
+					}),
+			),
+		)
+		if (result.exitCode !== 0) {
+			return yield* new WorktreeError({
+				message: `Post-checkout command failed for '${options.variables.repoAlias}' with exit code ${result.exitCode}${result.stderr ? `: ${result.stderr}` : ""}`,
+			})
+		}
+		options.operations.push({
+			action: "post-checkout",
+			repo: options.variables.repoAlias,
+			command,
+			status: "completed",
+		})
+	})
+
 const isCommitId = (ref: string) => /^[0-9a-f]{40,64}$/i.test(ref)
 
 const originRef = (ref: string) =>
@@ -812,6 +882,7 @@ const materializeJj = (options: {
 		| { readonly repo: string; readonly branch: string }
 		| RepositoryReference
 	)[]
+	readonly config: WorkbaseConfig
 	readonly commandOptions: MaterializeOptions
 }) =>
 	Effect.gen(function* () {
@@ -826,6 +897,11 @@ const materializeJj = (options: {
 			workspaceName: string
 		}[] = []
 		const base = "base" in options.execution ? options.execution.base : null
+		const { verboseLog } = createLoggers(options.commandOptions)
+		const forwardCommandOutput =
+			options.commandOptions.verbose === true &&
+			!options.commandOptions.silent &&
+			!options.commandOptions.json
 
 		if (!options.commandOptions.dryRun)
 			yield* fs.createDirectory(options.codePath)
@@ -920,7 +996,37 @@ const materializeJj = (options: {
 						...("branch" in checkout ? { branch: checkout.branch } : {}),
 					})
 					created.push({ repositoryPath, workspacePath, workspaceName })
+					const canonicalWorkspacePath = yield* fs.realPath(workspacePath)
+					const registeredAfterCreate = (yield* backend.listWorkspaces(
+						repositoryPath,
+					)).find((workspace) => workspace.path === canonicalWorkspacePath)
+					const head = yield* backend.workspaceHead(workspacePath)
+					if (!registeredAfterCreate || head !== revision) {
+						return yield* new WorktreeError({
+							message: `Created jj workspace for '${checkout.repo}' failed validation`,
+						})
+					}
 				}
+				yield* runPostCheckoutHook({
+					command:
+						options.config.repositories?.[checkout.repo]?.postCheckoutCommand,
+					variables: {
+						repoAlias: checkout.repo,
+						repositoryPath,
+						checkoutPath: workspacePath,
+						checkoutKind: "branch" in checkout ? "writable" : "reference",
+						requestedRef: requestedRevision,
+						base: base ?? "",
+						vcs: "jj",
+						workbaseRoot: options.root,
+						taskId: options.taskId,
+						phaseId: options.phaseId ?? "",
+					},
+					dryRun: options.commandOptions.dryRun === true,
+					forwardOutput: forwardCommandOutput,
+					verboseLog,
+					operations,
+				})
 				reports.push({
 					repo: checkout.repo,
 					kind: "branch" in checkout ? "writable" : "reference",
@@ -957,16 +1063,36 @@ const materializeJj = (options: {
 		}).pipe(
 			Effect.catchAll((cause) =>
 				Effect.gen(function* () {
+					const rolledBack: string[] = []
+					const manualRecovery: string[] = []
 					for (const workspace of [...created].reverse()) {
-						yield* backend
+						const removed = yield* backend
 							.removeWorkspace({
 								repositoryPath: workspace.repositoryPath,
 								workspacePath: workspace.workspacePath,
 								workspaceName: workspace.workspaceName,
 							})
-							.pipe(Effect.ignore)
+							.pipe(
+								Effect.as(true),
+								Effect.catchAll(() => Effect.succeed(false)),
+							)
+						if (removed)
+							rolledBack.push(`create-workspace ${workspace.workspaceName}`)
+						else
+							manualRecovery.push(
+								`Remove jj workspace ${workspace.workspacePath}`,
+							)
 					}
-					return yield* Effect.fail(cause)
+					return yield* new WorktreeError({
+						message: `${cause instanceof Error ? cause.message : "Workspace creation failed"}. ${
+							manualRecovery.length
+								? "Some effects require manual recovery"
+								: "Created jj workspaces were rolled back"
+						}`,
+						rolledBack,
+						manualRecovery,
+						cause,
+					})
 				}),
 			),
 		)
@@ -1245,6 +1371,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								codePath,
 								execution,
 								requestedCheckouts,
+								config,
 								commandOptions: options,
 							})
 						}
@@ -1695,6 +1822,26 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 												{ captureOutput: true },
 											)
 										}
+										yield* runPostCheckoutHook({
+											command:
+												config.repositories?.[alias]?.postCheckoutCommand,
+											variables: {
+												repoAlias: alias,
+												repositoryPath,
+												checkoutPath,
+												checkoutKind: "writable",
+												requestedRef: checkout.branch,
+												base: executionBase,
+												vcs: "git",
+												workbaseRoot: root,
+												taskId,
+												phaseId: phaseId ?? "",
+											},
+											dryRun: true,
+											forwardOutput: false,
+											verboseLog,
+											operations,
+										})
 										checkoutReports.push({
 											repo: alias,
 											kind: "writable",
@@ -1739,6 +1886,38 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 										["git", "-C", checkoutPath, "rev-parse", "HEAD"],
 										{ captureOutput: true },
 									)
+									const currentBranch = yield* fs.runCommand(
+										["git", "-C", checkoutPath, "branch", "--show-current"],
+										{ captureOutput: true },
+									)
+									if (
+										head.exitCode !== 0 ||
+										currentBranch.exitCode !== 0 ||
+										currentBranch.stdout.trim() !== checkout.branch
+									) {
+										return yield* new WorktreeError({
+											message: `Created worktree for '${alias}' failed validation for branch '${checkout.branch}'`,
+										})
+									}
+									yield* runPostCheckoutHook({
+										command: config.repositories?.[alias]?.postCheckoutCommand,
+										variables: {
+											repoAlias: alias,
+											repositoryPath,
+											checkoutPath,
+											checkoutKind: "writable",
+											requestedRef: checkout.branch,
+											base: executionBase,
+											vcs: "git",
+											workbaseRoot: root,
+											taskId,
+											phaseId: phaseId ?? "",
+										},
+										dryRun: false,
+										forwardOutput: forwardCommandOutput,
+										verboseLog,
+										operations,
+									})
 									checkoutReports.push({
 										repo: alias,
 										kind: "writable",
@@ -1831,6 +2010,26 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											command,
 											status: "planned",
 										})
+										yield* runPostCheckoutHook({
+											command:
+												config.repositories?.[alias]?.postCheckoutCommand,
+											variables: {
+												repoAlias: alias,
+												repositoryPath,
+												checkoutPath,
+												checkoutKind: "reference",
+												requestedRef: checkout.ref,
+												base: executionBase,
+												vcs: "git",
+												workbaseRoot: root,
+												taskId,
+												phaseId: phaseId ?? "",
+											},
+											dryRun: true,
+											forwardOutput: false,
+											verboseLog,
+											operations,
+										})
 										checkoutReports.push({
 											repo: alias,
 											kind: "reference",
@@ -1855,6 +2054,34 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 										command,
 										status: "completed",
 									})
+									const head = yield* fs.runCommand(
+										["git", "-C", checkoutPath, "rev-parse", "HEAD"],
+										{ captureOutput: true },
+									)
+									if (head.exitCode !== 0 || head.stdout.trim() !== commit) {
+										return yield* new WorktreeError({
+											message: `Created reference checkout for '${alias}' failed validation for '${checkout.ref}'`,
+										})
+									}
+									yield* runPostCheckoutHook({
+										command: config.repositories?.[alias]?.postCheckoutCommand,
+										variables: {
+											repoAlias: alias,
+											repositoryPath,
+											checkoutPath,
+											checkoutKind: "reference",
+											requestedRef: checkout.ref,
+											base: executionBase,
+											vcs: "git",
+											workbaseRoot: root,
+											taskId,
+											phaseId: phaseId ?? "",
+										},
+										dryRun: false,
+										forwardOutput: forwardCommandOutput,
+										verboseLog,
+										operations,
+									})
 									checkoutReports.push({
 										repo: alias,
 										kind: "reference",
@@ -1918,6 +2145,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 												join(root, "repos", checkout.repo),
 												"worktree",
 												"remove",
+												"--force",
 												checkoutPath,
 											],
 											{ captureOutput: true },

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

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

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test"
+import {
+	expandPostCheckoutCommand,
+	postCheckoutCommandEnvironment,
+} from "./checkout-command"
+
+const variables = {
+	repoAlias: "app",
+	repositoryPath: "/work/repos/app",
+	checkoutPath: "/work/tasks/example/code/app",
+	checkoutKind: "reference" as const,
+	requestedRef: "main",
+	base: "",
+	vcs: "jj" as const,
+	workbaseRoot: "/work",
+	taskId: "example",
+	phaseId: "",
+}
+
+describe("post-checkout command templates", () => {
+	test("expands all context placeholders without shell interpolation", () => {
+		expect(
+			expandPostCheckoutCommand(
+				[
+					"tool",
+					"{repoAlias}",
+					"{repositoryPath}",
+					"{checkoutPath}",
+					"{checkoutKind}",
+					"{requestedRef}",
+					"{base}",
+					"{vcs}",
+					"{workbaseRoot}",
+					"{taskId}",
+					"{phaseId}",
+				],
+				variables,
+			),
+		).toEqual(["tool", ...Object.values(variables)])
+	})
+
+	test("rejects unknown placeholders", () => {
+		expect(() =>
+			expandPostCheckoutCommand(["tool", "{unknown}"], variables),
+		).toThrow("{unknown}")
+	})
+
+	test("provides matching environment variables with empty optional values", () => {
+		expect(postCheckoutCommandEnvironment(variables)).toEqual({
+			AGENCY_REPO_ALIAS: variables.repoAlias,
+			AGENCY_REPOSITORY_PATH: variables.repositoryPath,
+			AGENCY_CHECKOUT_PATH: variables.checkoutPath,
+			AGENCY_CHECKOUT_KIND: variables.checkoutKind,
+			AGENCY_REQUESTED_REF: variables.requestedRef,
+			AGENCY_BASE: "",
+			AGENCY_VCS: variables.vcs,
+			AGENCY_WORKBASE_ROOT: variables.workbaseRoot,
+			AGENCY_TASK_ID: variables.taskId,
+			AGENCY_PHASE_ID: "",
+		})
+	})
+})

package/src/workbase/checkout-command.ts

@@ -0,0 +1,66 @@
+export interface CheckoutCommandVariables {
+	readonly repoAlias: string
+	readonly repositoryPath: string
+	readonly checkoutPath: string
+	readonly checkoutKind: "writable" | "reference"
+	readonly requestedRef: string
+	readonly base: string
+	readonly vcs: "git" | "jj"
+	readonly workbaseRoot: string
+	readonly taskId: string
+	readonly phaseId: string
+}
+
+const PLACEHOLDERS = new Set<keyof CheckoutCommandVariables>([
+	"repoAlias",
+	"repositoryPath",
+	"checkoutPath",
+	"checkoutKind",
+	"requestedRef",
+	"base",
+	"vcs",
+	"workbaseRoot",
+	"taskId",
+	"phaseId",
+])
+
+export const validatePostCheckoutCommand = (command: readonly string[]) => {
+	for (const argument of command) {
+		for (const match of argument.matchAll(/\{([^{}]+)\}/g)) {
+			const placeholder = match[1]!
+			if (!PLACEHOLDERS.has(placeholder as keyof CheckoutCommandVariables)) {
+				throw new Error(
+					`Unknown postCheckoutCommand placeholder: {${placeholder}}`,
+				)
+			}
+		}
+	}
+}
+
+export const expandPostCheckoutCommand = (
+	command: readonly string[],
+	variables: CheckoutCommandVariables,
+): string[] => {
+	validatePostCheckoutCommand(command)
+
+	return command.map((argument) =>
+		argument.replaceAll(/\{([^{}]+)\}/g, (match, placeholder: string) => {
+			return variables[placeholder as keyof CheckoutCommandVariables] ?? match
+		}),
+	)
+}
+
+export const postCheckoutCommandEnvironment = (
+	variables: CheckoutCommandVariables,
+): Record<string, string> => ({
+	AGENCY_REPO_ALIAS: variables.repoAlias,
+	AGENCY_REPOSITORY_PATH: variables.repositoryPath,
+	AGENCY_CHECKOUT_PATH: variables.checkoutPath,
+	AGENCY_CHECKOUT_KIND: variables.checkoutKind,
+	AGENCY_REQUESTED_REF: variables.requestedRef,
+	AGENCY_BASE: variables.base,
+	AGENCY_VCS: variables.vcs,
+	AGENCY_WORKBASE_ROOT: variables.workbaseRoot,
+	AGENCY_TASK_ID: variables.taskId,
+	AGENCY_PHASE_ID: variables.phaseId,
+})

package/src/workbase/schemas.test.ts

@@ -187,6 +187,40 @@ describe("body-of-work descriptions", () => {
 	})
 })
 
+describe("repository post-checkout configuration", () => {
+	test("accepts a per-repository argv command", () => {
+		const config = Schema.decodeUnknownSync(WorkbaseConfig)({
+			version: 2,
+			repositories: {
+				agency: {
+					remote: "https://example.com/agency.git",
+					postCheckoutCommand: ["bun", "install", "--frozen-lockfile"],
+				},
+			},
+		})
+
+		expect(config.repositories?.agency?.postCheckoutCommand).toEqual([
+			"bun",
+			"install",
+			"--frozen-lockfile",
+		])
+	})
+
+	test("rejects shell strings in place of argv arrays", () => {
+		expect(() =>
+			Schema.decodeUnknownSync(WorkbaseConfig)({
+				version: 2,
+				repositories: {
+					agency: {
+						remote: "https://example.com/agency.git",
+						postCheckoutCommand: "bun install",
+					},
+				},
+			}),
+		).toThrow()
+	})
+})
+
 describe("runner configuration", () => {
 	test("accepts named argv commands with resume commands and environment", () => {
 		const config = Schema.decodeUnknownSync(WorkbaseConfig)({

package/src/workbase/schemas.ts

@@ -24,6 +24,7 @@ export const RepositoryRemote = NonEmptyString.pipe(
 
 export const RepositoryDeclaration = Schema.Struct({
 	remote: RepositoryRemote,
+	postCheckoutCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 })
 
 export const RepositoryReference = Schema.Struct({