@markjaquith/agency 2.55.0 → 2.56.1

package/README.md

@@ -235,6 +235,56 @@ Supplemental read-only repositories remain detached Git worktrees at their
 declared refs so they do not acquire writable branches. Jj workbases always use
 jj workspaces and ignore this Git-specific customization.
 
+### Post-checkout Commands
+
+Each repository declaration may provide a VCS-neutral `postCheckoutCommand` argv
+template for repository-specific setup. Agency invokes it directly, without a
+shell, with the new checkout as its working directory:
+
+```json
+{
+	"version": 2,
+	"repositories": {
+		"frontend": {
+			"remote": "git@example.com:team/frontend.git",
+			"postCheckoutCommand": ["bun", "install", "--frozen-lockfile"]
+		}
+	}
+}
+```
+
+The hook runs for each newly created managed checkout, including writable and
+reference checkouts, after Git worktree or jj workspace creation has completed
+and Agency has validated the checkout. It does not run for a reused checkout or
+for inspection-only commands. A custom `worktreeCreateCommand` completes and is
+validated before this hook runs.
+
+Available placeholders and matching environment variables are:
+
+| Placeholder        | Environment              | Value                                          |
+| ------------------ | ------------------------ | ---------------------------------------------- |
+| `{repoAlias}`      | `AGENCY_REPO_ALIAS`      | Repository alias                               |
+| `{repositoryPath}` | `AGENCY_REPOSITORY_PATH` | Absolute source repository path under `repos/` |
+| `{checkoutPath}`   | `AGENCY_CHECKOUT_PATH`   | Absolute managed checkout path                 |
+| `{checkoutKind}`   | `AGENCY_CHECKOUT_KIND`   | `writable` or `reference`                      |
+| `{requestedRef}`   | `AGENCY_REQUESTED_REF`   | Requested branch, reference, or review commit  |
+| `{base}`           | `AGENCY_BASE`            | Configured execution base                      |
+| `{vcs}`            | `AGENCY_VCS`             | `git` or `jj`                                  |
+| `{workbaseRoot}`   | `AGENCY_WORKBASE_ROOT`   | Absolute workbase root                         |
+| `{taskId}`         | `AGENCY_TASK_ID`         | Task ID                                        |
+| `{phaseId}`        | `AGENCY_PHASE_ID`        | Phase ID                                       |
+
+`{base}` and `{phaseId}` and their environment variables are empty strings when
+they do not apply. Dry runs report a planned `post-checkout` operation but never
+execute it. Verbose output identifies the repository and expanded command.
+
+Hook success is part of checkout creation. A non-zero exit or failure to start
+rolls back the checkout and any branch created by the same operation; if cleanup
+also fails, Agency reports the exact manual recovery action. A later command
+retries checkout creation and the hook rather than reusing an uninitialized
+checkout. Hook commands should be idempotent so a retry is safe after any
+external effects the failed invocation may have completed.
+
 ### Agent Runners
 
 OpenCode and Claude Code are built-in runner presets. Select either preset or a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.55.0",
+  "version": "2.56.1",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",
@@ -58,6 +58,7 @@
     "tag": "latest"
   },
   "scripts": {
+    "benchmark:sync": "bun scripts/benchmark-sync.ts",
     "test": "find src \\( -name '*.test.ts' -o -name '*.test.tsx' \\) -print0 | xargs -0 -n 1 -P 4 bun test",
     "test:opencode": "AGENCY_TEST_OPENCODE=1 bun test src/cli.test.ts --test-name-pattern 'provides effective whole-workbase OpenCode access'",
     "format": "oxfmt",

package/src/commands/sync.test.ts

@@ -9,6 +9,7 @@ import {
 	createTempDir,
 	runTestEffect,
 } from "../test-utils"
+import type { Progress } from "../utils/progress"
 import { sync } from "./sync"
 
 const git = async (args: string[], cwd: string) => {
@@ -97,4 +98,30 @@ describe("sync command", () => {
 			],
 		})
 	})
+
+	test("reports human-readable progress without polluting JSON output", 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}`),
+		}
+
+		await captureLogs(() =>
+			runTestEffect(sync({ cwd: root, silent: false }, progress)),
+		)
+		expect(updates).toEqual([
+			"start:Validating workbase",
+			"start:Inspected 1 repositories",
+			"start:Queried pull requests 1/1 (task:example)",
+			"start:Reconciled execution units 1/1 (task:example)",
+			"succeed:Synchronized 1 execution units",
+		])
+
+		updates.length = 0
+		await captureLogs(() =>
+			runTestEffect(sync({ cwd: root, dryRun: true, json: true }, progress)),
+		)
+		expect(updates).toEqual([])
+	})
 })

package/src/commands/sync.ts

@@ -2,19 +2,54 @@ import { Effect } from "effect"
 import { SyncService } from "../services/SyncService"
 import type { BaseCommandOptions } from "../utils/command"
 import { createLoggers } from "../utils/effect"
+import { createProgress, type Progress } from "../utils/progress"
 
 interface SyncCommandOptions extends BaseCommandOptions {
 	readonly dryRun?: boolean
 }
 
-export const sync = (options: SyncCommandOptions = {}) =>
+export const sync = (
+	options: SyncCommandOptions = {},
+	progress: Progress = createProgress({
+		silent: options.silent || options.json,
+	}),
+) =>
 	Effect.gen(function* () {
 		const service = yield* SyncService
 		const { log } = createLoggers(options)
-		const result = yield* service.reconcile({
-			cwd: options.cwd,
-			apply: options.dryRun !== true,
-		})
+		const showProgress = !options.silent && !options.json
+		if (showProgress) progress.start("Validating workbase")
+		const result = yield* service
+			.reconcile({
+				cwd: options.cwd,
+				apply: options.dryRun !== true,
+				onProgress: showProgress
+					? ({ stage, current, total, target }) => {
+							if (stage === "repositories") {
+								progress.start(`Inspected ${total} repositories`)
+							} else if (stage === "pull-requests") {
+								progress.start(
+									`Queried pull requests ${current}/${total}${target ? ` (${target})` : ""}`,
+								)
+							} else {
+								progress.start(
+									`Reconciled execution units ${current}/${total}${target ? ` (${target})` : ""}`,
+								)
+							}
+						}
+					: undefined,
+			})
+			.pipe(
+				Effect.tapError(() =>
+					Effect.sync(() => {
+						if (showProgress) progress.fail("Workbase sync failed")
+					}),
+				),
+			)
+		if (showProgress)
+			progress.succeed(
+				`Synchronized ${result.executions.length} execution units`,
+			)
 		if (options.json) return log(JSON.stringify(result, null, 2))
 
 		for (const action of result.repositories.actions) {

package/src/services/DoctorService.ts

@@ -173,6 +173,18 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 									] as const,
 								]
 							: []),
+						...Object.entries(config.repositories ?? {}).flatMap(
+							([alias, repository]) =>
+								repository.postCheckoutCommand
+									? [
+											[
+												`integration.repository.${alias}.post-checkout`,
+												repository.postCheckoutCommand,
+												`Repository '${alias}' post-checkout hook`,
+											] as const,
+										]
+									: [],
+						),
 						...Object.entries(config.runners ?? {}).map(
 							([name, runner]) =>
 								[

package/src/services/SyncService.test.ts

@@ -796,4 +796,119 @@ process.stdout.write(${JSON.stringify(JSON.stringify(record))})
 			),
 		).toMatchObject({ valid: true, issues: [] })
 	})
+
+	test("reads each repository workspace inventory once", async () => {
+		for (const id of ["first", "second"]) {
+			await runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.create(
+							{
+								id,
+								ticketUrl: null,
+								repo: "agency",
+								branch: `feat/${id}`,
+								base: "main",
+							},
+							root,
+						),
+					),
+				),
+			)
+			await runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) => service.materialize(id, undefined, root)),
+				),
+			)
+			await runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.setStatus(id, "done", root, {
+							summary: `Completed ${id}`,
+						}),
+					),
+				),
+			)
+		}
+
+		const callsPath = join(root, "workspace-list-calls")
+		const realGit = Bun.which("git")!
+		const gitWrapper = join(root, "bin", "git")
+		await Bun.write(
+			gitWrapper,
+			`#!/bin/sh
+case "$*" in
+*"worktree list --porcelain -z"*) printf 'call\\n' >> ${JSON.stringify(callsPath)} ;;
+esac
+exec ${JSON.stringify(realGit)} "$@"
+`,
+		)
+		await chmod(gitWrapper, 0o755)
+
+		await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) => service.reconcile({ cwd: root })),
+			),
+		)
+		expect((await Bun.file(callsPath).text()).trim().split("\n")).toHaveLength(
+			1,
+		)
+	})
+
+	test("queries pull request providers concurrently", async () => {
+		for (const id of ["first", "second", "third"]) {
+			await runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.create(
+							{
+								id,
+								ticketUrl: null,
+								repo: "agency",
+								branch: `feat/${id}`,
+								base: "main",
+							},
+							root,
+						),
+					),
+				),
+			)
+		}
+
+		const barrier = join(root, "query-barrier")
+		await mkdir(barrier)
+		await Bun.write(
+			join(root, "bin", "gh"),
+			`#!/bin/sh
+branch=""
+while [ "$#" -gt 0 ]; do
+  if [ "$1" = "--head" ]; then branch="$2"; break; fi
+  shift
+done
+id="\${branch##*/}"
+touch ${JSON.stringify(barrier)}/"\${id}"
+attempt=0
+while [ "$attempt" -lt 200 ]; do
+  set -- ${JSON.stringify(barrier)}/*
+  if [ -e "$1" ] && [ "$#" -ge 3 ]; then printf '[]\\n'; exit 0; fi
+  attempt=$((attempt + 1))
+  sleep 0.01
+done
+echo "provider queries were serialized" >&2
+exit 9
+`,
+		)
+		await chmod(join(root, "bin", "gh"), 0o755)
+
+		const result = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) => service.reconcile({ cwd: root })),
+			),
+		)
+		expect(
+			result.warnings.filter(
+				(warning) => warning.kind === "pr-discovery-unavailable",
+			),
+		).toEqual([])
+	})
 })