@markjaquith/agency 3.2.1 → 3.2.2

package/README.md

@@ -1107,13 +1107,21 @@ 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.
+updates. Local commit validation runs before network access when cached remote
+state is available, and the network fetch is limited to the declared base and
+delivery branch.
 
 YAML `branch` must exactly match the checked-out local branch, the worktree must
 be clean, and `HEAD` is pushed with upstream tracking. Missing commit descriptions
 or authors stop publication with exact commits and remediation commands. Push
 reports deterministic fetch, inspection, validation, and publication progress on
-stderr, including while `--json` reserves stdout for one machine result.
+stderr, including while `--json` reserves stdout for one machine result. Git
+authentication is non-interactive. Fetch defaults to a 30-second deadline and
+one retry for transient failures; push defaults to a 120-second deadline. Set
+`AGENCY_PUSH_FETCH_TIMEOUT_MS` or `AGENCY_PUSH_TIMEOUT_MS` to positive millisecond
+values to override them. After a failed or timed-out push, Agency compares the
+exact remote delivery ref with the expected tip before reporting success, a safe
+retryable failure, or an unknown publication outcome.
 
 Task-aware `agency pr create <task-id> [phase-id]` uses Agency's delivery flow,
 including readiness checks and durable PR recording. It accepts draft, title,

package/cli-main.ts

@@ -828,6 +828,42 @@ let usageFlagNames = rawArguments
 	.filter((argument) => argument.startsWith("--"))
 	.map((argument) => argument.slice(2).split("=", 1)[0]!)
 
+const pushUsageDetails = (error?: unknown) => {
+	if (usageCommandPath !== "push") return {}
+	const seen = new Set<object>()
+	const visit = (
+		value: unknown,
+	): { stage?: string; category?: string } | null => {
+		if (typeof value !== "object" || value === null || seen.has(value))
+			return null
+		seen.add(value)
+		if (
+			"stage" in value &&
+			typeof value.stage === "string" &&
+			"category" in value &&
+			typeof value.category === "string"
+		) {
+			return { stage: value.stage, category: value.category }
+		}
+		for (const nestedValue of [
+			...Object.values(value),
+			...Object.getOwnPropertySymbols(value).map(
+				(symbol) => (value as Record<symbol, unknown>)[symbol],
+			),
+		]) {
+			const nested = visit(nestedValue)
+			if (nested) return nested
+		}
+		return null
+	}
+	const details = error ? visit(error) : null
+	return {
+		vcs: "git" as const,
+		terminalStage: details?.stage ?? (error ? "unknown" : "publish"),
+		category: details?.category ?? (error ? "unknown" : "success"),
+	}
+}
+
 try {
 	const {
 		commandName,
@@ -921,6 +957,7 @@ try {
 			durationMs: performance.now() - invocationStartedAt,
 			outcome: exitStatus === 0 ? "success" : "failure",
 			exitStatus,
+			...pushUsageDetails(),
 		},
 		VERSION,
 	)
@@ -932,6 +969,7 @@ try {
 			durationMs: performance.now() - invocationStartedAt,
 			outcome: "failure",
 			exitStatus: 1,
+			...pushUsageDetails(error),
 		},
 		VERSION,
 	)

package/package.json

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

package/src/commands/push.test.ts

@@ -28,9 +28,10 @@ describe("push command", () => {
 						publish: (_cwd: string, options: any) => {
 							for (const stage of [
 								"context",
-								"fetch",
 								"inspect",
 								"validate",
+								"fetch",
+								"validate",
 								"publish",
 							] as const)
 								options.onProgress(stage)
@@ -44,9 +45,10 @@ describe("push command", () => {
 		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:Fetching remote state",
+			"start:Validating outgoing changes",
 			"start:Publishing the declared branch",
 			"succeed:Published task/example to origin",
 		])

package/src/commands/push.ts

@@ -10,6 +10,7 @@ const stageMessage = {
 	inspect: "Selecting the publication tip",
 	validate: "Validating outgoing changes",
 	publish: "Publishing the declared branch",
+	reconcile: "Confirming the remote publication outcome",
 } as const
 
 export const push = (
@@ -22,6 +23,7 @@ export const push = (
 		const showProgress = !options.silent
 		const result = yield* publications
 			.publish(options.cwd ?? process.cwd(), {
+				forwardOutput: options.verbose,
 				onProgress: showProgress
 					? (stage) => progress.start(stageMessage[stage])
 					: undefined,

package/src/protocol.test.ts

@@ -161,4 +161,28 @@ describe("machine protocol", () => {
 			},
 		})
 	})
+
+	test("uses dynamic protocol metadata without duplicating it in fields", () => {
+		expect(
+			errorEnvelope({
+				_tag: "PushError",
+				message: "remote timed out",
+				protocolCode: "PUSH_TIMEOUT",
+				retryable: true,
+				remediation: "Retry after checking connectivity.",
+				category: "timeout",
+				stage: "fetch",
+			}),
+		).toEqual({
+			version: 1,
+			ok: false,
+			error: {
+				code: "PUSH_TIMEOUT",
+				message: "remote timed out",
+				fields: { category: "timeout", stage: "fetch" },
+				retryable: true,
+				remediation: "Retry after checking connectivity.",
+			},
+		})
+	})
 })

package/src/protocol.ts

@@ -198,6 +198,36 @@ const errorTag = (error: unknown): string | undefined => {
 	return undefined
 }
 
+const unwrapEffectError = (error: unknown): unknown => {
+	const seen = new Set<object>()
+	const visit = (value: unknown): unknown => {
+		if (typeof value !== "object" || value === null || seen.has(value))
+			return null
+		seen.add(value)
+		if ("protocolCode" in value && typeof value.protocolCode === "string") {
+			return value
+		}
+		for (const nested of [
+			...Object.values(value),
+			...Object.getOwnPropertySymbols(value).map(
+				(symbol) => (value as Record<symbol, unknown>)[symbol],
+			),
+		]) {
+			const found = visit(nested)
+			if (found) return found
+		}
+		if (
+			"_tag" in value &&
+			typeof value._tag === "string" &&
+			value._tag.endsWith("Error")
+		) {
+			return value
+		}
+		return null
+	}
+	return visit(error) ?? error
+}
+
 const errorMessage = (error: unknown): string => {
 	if (
 		typeof error === "object" &&
@@ -219,6 +249,9 @@ const errorFields = (error: unknown): Record<string, unknown> => {
 				key !== "name" &&
 				key !== "message" &&
 				key !== "cause" &&
+				key !== "protocolCode" &&
+				key !== "retryable" &&
+				key !== "remediation" &&
 				value !== undefined,
 		),
 	)
@@ -231,17 +264,36 @@ export const successEnvelope = (result: unknown): SuccessEnvelope => ({
 })
 
 export const errorEnvelope = (error: unknown): ErrorEnvelope => {
-	const metadata = errorMetadata[errorTag(error) ?? ""] ?? {
+	const normalized = unwrapEffectError(error)
+	const defaults = errorMetadata[errorTag(normalized) ?? ""] ?? {
 		code: "COMMAND_FAILED",
 		retryable: false,
 	}
+	const dynamic =
+		typeof normalized === "object" && normalized !== null
+			? {
+					...("protocolCode" in normalized &&
+					typeof normalized.protocolCode === "string"
+						? { code: normalized.protocolCode }
+						: {}),
+					...("retryable" in normalized &&
+					typeof normalized.retryable === "boolean"
+						? { retryable: normalized.retryable }
+						: {}),
+					...("remediation" in normalized &&
+					typeof normalized.remediation === "string"
+						? { remediation: normalized.remediation }
+						: {}),
+				}
+			: {}
 	return {
 		version: PROTOCOL_VERSION,
 		ok: false,
 		error: {
-			...metadata,
-			message: errorMessage(error),
-			fields: errorFields(error),
+			...defaults,
+			...dynamic,
+			message: errorMessage(normalized),
+			fields: errorFields(normalized),
 		},
 	}
 }

package/src/services/FileSystemService.ts

@@ -245,6 +245,7 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 					readonly forwardOutput?: boolean
 					readonly passthrough?: boolean
 					readonly env?: Record<string, string>
+					readonly timeoutMs?: number
 				},
 			) =>
 				pipe(
@@ -264,6 +265,7 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 								? "tee"
 								: "pipe",
 						env: options?.env,
+						timeoutMs: options?.timeoutMs,
 					}),
 					Effect.mapError(
 						(processError) =>

package/src/services/PushService.test.ts

@@ -1,8 +1,9 @@
 import { afterEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
-import { mkdir } from "node:fs/promises"
-import { join } from "node:path"
+import { chmod, mkdir } from "node:fs/promises"
+import { join, resolve } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { errorEnvelope } from "../protocol"
 import { PushService } from "./PushService"
 import { TaskService } from "./TaskService"
 import { WorktreeService } from "./WorktreeService"
@@ -130,9 +131,18 @@ describe("PushService", () => {
 		}
 	}
 
-	const publish = (taskPath: string) =>
+	const publish = (
+		taskPath: string,
+		options: {
+			fetchTimeoutMs?: number
+			pushTimeoutMs?: number
+			retryDelayMs?: number
+		} = {},
+	) =>
 		runTestEffect(
-			PushService.pipe(Effect.flatMap((service) => service.publish(taskPath))),
+			PushService.pipe(
+				Effect.flatMap((service) => service.publish(taskPath, options)),
+			),
 		)
 
 	const remoteBranch = async (remote: string) =>
@@ -157,6 +167,17 @@ describe("PushService", () => {
 		)
 	}
 
+	const prePushHook = async (checkout: string) =>
+		resolve(
+			checkout,
+			(
+				await requireCommand(
+					["git", "rev-parse", "--git-path", "hooks/pre-push"],
+					checkout,
+				)
+			).stdout,
+		)
+
 	test("publishes a clean Git HEAD and establishes upstream tracking", async () => {
 		const fixture = await setup()
 		await configureAuthor(fixture.checkout)
@@ -299,4 +320,89 @@ describe("PushService", () => {
 			"has an invalid author",
 		)
 	})
+
+	test("bounds a stalled pre-push hook and confirms non-publication", async () => {
+		const fixture = await setup()
+		await configureAuthor(fixture.checkout)
+		await Bun.write(join(fixture.checkout, "feature.txt"), "timeout\n")
+		await requireCommand(["git", "add", "feature.txt"], fixture.checkout)
+		await requireCommand(
+			["git", "commit", "-m", "Add timed publication"],
+			fixture.checkout,
+		)
+		const hook = await prePushHook(fixture.checkout)
+		await Bun.write(hook, "#!/bin/sh\nsleep 30\n")
+		await chmod(hook, 0o755)
+
+		const startedAt = performance.now()
+		const failure = await publish(fixture.taskPath, {
+			pushTimeoutMs: 25,
+		}).catch((error) => error)
+		expect(performance.now() - startedAt).toBeLessThan(1_000)
+		expect(errorEnvelope(failure).error).toMatchObject({
+			code: "PUSH_TIMEOUT",
+			fields: { category: "timeout", stage: "publish" },
+			retryable: true,
+		})
+		await expect(remoteBranch(fixture.remote)).rejects.toThrow()
+	})
+
+	test("classifies hook rejection separately from transport failure", async () => {
+		const fixture = await setup()
+		await configureAuthor(fixture.checkout)
+		await Bun.write(join(fixture.checkout, "feature.txt"), "rejected\n")
+		await requireCommand(["git", "add", "feature.txt"], fixture.checkout)
+		await requireCommand(
+			["git", "commit", "-m", "Add rejected publication"],
+			fixture.checkout,
+		)
+		const hook = await prePushHook(fixture.checkout)
+		await Bun.write(
+			hook,
+			"#!/bin/sh\necho 'pre-push hook declined' >&2\nexit 1\n",
+		)
+		await chmod(hook, 0o755)
+
+		const failure = await publish(fixture.taskPath).catch((error) => error)
+		expect(errorEnvelope(failure).error).toMatchObject({
+			code: "PUSH_HOOK_REJECTED",
+			fields: { category: "hook_rejection", stage: "publish" },
+			retryable: false,
+		})
+	})
+
+	test("retries one transient fetch with non-interactive authentication", async () => {
+		const fixture = await setup()
+		await configureAuthor(fixture.checkout)
+		await Bun.write(join(fixture.checkout, "feature.txt"), "retried\n")
+		await requireCommand(["git", "add", "feature.txt"], fixture.checkout)
+		await requireCommand(
+			["git", "commit", "-m", "Add retried publication"],
+			fixture.checkout,
+		)
+		const attempts = join(fixture.root, "upload-pack-attempts")
+		const uploadPack = join(fixture.root, "upload-pack")
+		await Bun.write(
+			uploadPack,
+			`#!/bin/sh
+echo x >> ${JSON.stringify(attempts)}
+test "$GIT_TERMINAL_PROMPT" = 0 || exit 2
+test "$GCM_INTERACTIVE" = Never || exit 2
+if test "$(wc -l < ${JSON.stringify(attempts)})" -eq 1; then
+  echo 'Connection reset by peer' >&2
+  exit 1
+fi
+exec git-upload-pack "$@"
+`,
+		)
+		await chmod(uploadPack, 0o755)
+		await requireCommand(
+			["git", "config", "remote.origin.uploadpack", uploadPack],
+			fixture.checkout,
+		)
+
+		const result = await publish(fixture.taskPath, { retryDelayMs: 0 })
+		expect(result.tip).toBe(await remoteBranch(fixture.remote))
+		expect((await Bun.file(attempts).text()).trim().split("\n")).toHaveLength(2)
+	})
 })

package/src/services/PushService.ts

@@ -1,4 +1,4 @@
-import { Data, Effect } from "effect"
+import { Data, Effect, Either } from "effect"
 import { ContextService } from "./ContextService"
 import { FileSystemService } from "./FileSystemService"
 import { PhaseService } from "./PhaseService"
@@ -6,8 +6,77 @@ import { TaskService } from "./TaskService"
 import { WorkbaseService } from "./WorkbaseService"
 import { parseGitCommits, type PushCommitMetadata } from "./push-validation"
 
+type PushCategory =
+	| "precondition"
+	| "commit_validation"
+	| "remote_divergence"
+	| "hook_rejection"
+	| "authentication"
+	| "transport"
+	| "timeout"
+	| "ambiguous_publication"
+	| "git"
+
+const categoryMetadata: Record<
+	PushCategory,
+	{ code: string; retryable: boolean; remediation: string }
+> = {
+	precondition: {
+		code: "PUSH_PRECONDITION",
+		retryable: false,
+		remediation: "Resolve the local publication precondition and retry.",
+	},
+	commit_validation: {
+		code: "PUSH_COMMIT_VALIDATION",
+		retryable: false,
+		remediation: "Rewrite the reported outgoing commits and retry.",
+	},
+	remote_divergence: {
+		code: "PUSH_REMOTE_DIVERGENCE",
+		retryable: false,
+		remediation: "Rebase onto the remote delivery branch before retrying.",
+	},
+	hook_rejection: {
+		code: "PUSH_HOOK_REJECTED",
+		retryable: false,
+		remediation: "Resolve the hook failure and retry; hooks are not bypassed.",
+	},
+	authentication: {
+		code: "PUSH_AUTHENTICATION",
+		retryable: false,
+		remediation: "Authenticate Git for the configured remote and retry.",
+	},
+	transport: {
+		code: "PUSH_TRANSPORT",
+		retryable: true,
+		remediation: "Check remote connectivity and retry.",
+	},
+	timeout: {
+		code: "PUSH_TIMEOUT",
+		retryable: true,
+		remediation: "Check remote connectivity and retry the bounded operation.",
+	},
+	ambiguous_publication: {
+		code: "PUSH_OUTCOME_UNKNOWN",
+		retryable: false,
+		remediation:
+			"Inspect the exact remote delivery ref before retrying publication.",
+	},
+	git: {
+		code: "PUSH_GIT_ERROR",
+		retryable: false,
+		remediation: "Resolve the reported Git failure and retry.",
+	},
+}
+
 class PushError extends Data.TaggedError("PushError")<{
 	readonly message: string
+	readonly category: PushCategory
+	readonly stage: PushStage
+	readonly elapsedMs?: number
+	readonly protocolCode: string
+	readonly retryable: boolean
+	readonly remediation: string
 }> {}
 
 interface CommandResult {
@@ -28,46 +97,162 @@ interface PushResult {
 	readonly tip: string
 }
 
-type PushStage = "context" | "fetch" | "inspect" | "validate" | "publish"
+type PushStage =
+	| "context"
+	| "inspect"
+	| "validate"
+	| "fetch"
+	| "publish"
+	| "reconcile"
 
 interface PushOptions {
 	readonly onProgress?: (stage: PushStage) => void
+	readonly fetchTimeoutMs?: number
+	readonly pushTimeoutMs?: number
+	readonly retryDelayMs?: number
+	readonly forwardOutput?: boolean
 }
 
 const validEmail = (email: string) => /^[^@\s]+@[^@\s]+$/.test(email)
 
+const pushError = (
+	message: string,
+	category: PushCategory,
+	stage: PushStage,
+	elapsedMs?: number,
+) =>
+	new PushError({
+		message,
+		category,
+		stage,
+		...(elapsedMs === undefined ? {} : { elapsedMs }),
+		protocolCode: categoryMetadata[category].code,
+		retryable: categoryMetadata[category].retryable,
+		remediation: categoryMetadata[category].remediation,
+	})
+
+const processTimeout = (error: unknown): { elapsedMs?: number } | null => {
+	if (typeof error !== "object" || error === null) return null
+	if ("timedOut" in error && error.timedOut === true) {
+		return {
+			elapsedMs:
+				"elapsedMs" in error && typeof error.elapsedMs === "number"
+					? error.elapsedMs
+					: undefined,
+		}
+	}
+	return "cause" in error ? processTimeout(error.cause) : null
+}
+
+const classifyGitFailure = (
+	message: string,
+	stage: PushStage,
+	elapsedMs?: number,
+) => {
+	const normalized = message.toLowerCase()
+	const category: PushCategory =
+		/authentication failed|permission denied|could not read username|terminal prompts disabled|credential/.test(
+			normalized,
+		)
+			? "authentication"
+			: /pre-push hook|hook declined|remote rejected/.test(normalized)
+				? "hook_rejection"
+				: /non-fast-forward|fetch first|stale info/.test(normalized)
+					? "remote_divergence"
+					: /could not resolve|connection|network|remote end hung up|unable to access|repository not found/.test(
+								normalized,
+						  )
+						? "transport"
+						: "git"
+	return pushError(message, category, stage, elapsedMs)
+}
+
 const requireCommand = (
 	fs: FileSystemService,
 	args: readonly string[],
 	cwd: string,
 	label: string,
+	stage: PushStage,
+	options: {
+		readonly timeoutMs?: number
+		readonly env?: Record<string, string>
+		readonly forwardOutput?: boolean
+	} = {},
 ) =>
-	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()}`,
-						}),
-					),
-		),
-	)
+	Effect.suspend(() => {
+		const startedAt = performance.now()
+		return fs
+			.runCommand(args, {
+				cwd,
+				captureOutput: true,
+				forwardOutput: options.forwardOutput,
+				env: options.env,
+				timeoutMs: options.timeoutMs,
+			})
+			.pipe(
+				Effect.mapError((error) => {
+					const timeout = processTimeout(error)
+					const elapsedMs =
+						timeout?.elapsedMs ?? Math.round(performance.now() - startedAt)
+					return timeout
+						? pushError(
+								`${label} timed out after ${elapsedMs} ms`,
+								"timeout",
+								stage,
+								elapsedMs,
+							)
+						: classifyGitFailure(`${label}: ${error.message}`, stage, elapsedMs)
+				}),
+				Effect.flatMap((result) =>
+					result.exitCode === 0
+						? Effect.succeed(result)
+						: Effect.fail(
+								classifyGitFailure(
+									`${label}: ${result.stderr.trim() || result.stdout.trim()}`,
+									stage,
+									Math.round(performance.now() - startedAt),
+								),
+							),
+				),
+			)
+	})
 
 const git = (
 	fs: FileSystemService,
 	cwd: string,
 	args: readonly string[],
 	label: string,
-) => requireCommand(fs, ["git", ...args], cwd, label)
+	stage: PushStage,
+	options?: Parameters<typeof requireCommand>[5],
+) => requireCommand(fs, ["git", ...args], cwd, label, stage, options)
 
-const gitRevision = (fs: FileSystemService, cwd: string, revision: string) =>
+const gitRevision = (
+	fs: FileSystemService,
+	cwd: string,
+	revision: string,
+	stage: PushStage = "inspect",
+) =>
 	fs
 		.runCommand(["git", "rev-parse", "--verify", `${revision}^{commit}`], {
 			cwd,
 			captureOutput: true,
+			timeoutMs: 10_000,
 		})
 		.pipe(
+			Effect.mapError((error) => {
+				const timeout = processTimeout(error)
+				return timeout
+					? pushError(
+							`Git revision inspection timed out after ${timeout.elapsedMs ?? 10_000} ms`,
+							"timeout",
+							stage,
+							timeout.elapsedMs,
+						)
+					: classifyGitFailure(
+							`Failed to inspect Git revision '${revision}': ${error.message}`,
+							stage,
+						)
+			}),
 			Effect.map((result) =>
 				result.exitCode === 0 ? result.stdout.trim() || null : null,
 			),
@@ -78,20 +263,37 @@ const gitAncestor = (
 	cwd: string,
 	ancestor: string,
 	descendant: string,
+	stage: PushStage,
 ) =>
 	fs
 		.runCommand(["git", "merge-base", "--is-ancestor", ancestor, descendant], {
 			cwd,
 			captureOutput: true,
+			timeoutMs: 10_000,
 		})
 		.pipe(
+			Effect.mapError((error) => {
+				const timeout = processTimeout(error)
+				return timeout
+					? pushError(
+							`Git ancestry inspection timed out after ${timeout.elapsedMs ?? 10_000} ms`,
+							"timeout",
+							stage,
+							timeout.elapsedMs,
+						)
+					: classifyGitFailure(
+							`Failed to inspect Git ancestry: ${error.message}`,
+							stage,
+						)
+			}),
 			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()}`,
-					}),
+					classifyGitFailure(
+						`Failed to inspect Git ancestry: ${result.stderr.trim()}`,
+						stage,
+					),
 				)
 			}),
 		)
@@ -101,9 +303,11 @@ const validateGitCommits = (
 	base: string,
 ) => {
 	if (commits.length === 0) {
-		throw new PushError({
-			message: `No commits to publish after base '${base}'`,
-		})
+		throw pushError(
+			`No commits to publish after base '${base}'`,
+			"precondition",
+			"validate",
+		)
 	}
 	const issues: string[] = []
 	for (const commit of commits) {
@@ -118,66 +322,152 @@ const validateGitCommits = (
 			)
 		}
 	}
-	if (issues.length > 0) throw new PushError({ message: issues.join("\n") })
+	if (issues.length > 0)
+		throw pushError(issues.join("\n"), "commit_validation", "validate")
+}
+
+const positiveInteger = (value: string | undefined, fallback: number) => {
+	const parsed = Number.parseInt(value ?? "", 10)
+	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback
 }
 
+const gitEnvironment = (): Record<string, string> => ({
+	GIT_TERMINAL_PROMPT: "0",
+	GCM_INTERACTIVE: "Never",
+	GIT_SSH_COMMAND:
+		process.env.GIT_SSH_COMMAND ?? "ssh -o BatchMode=yes -o ConnectTimeout=15",
+})
+
 const publishGit = (
 	fs: FileSystemService,
 	checkout: string,
 	remote: string,
 	branch: string,
 	base: string,
-	onProgress?: (stage: PushStage) => void,
+	options: PushOptions,
 ) =>
 	Effect.gen(function* () {
+		const onProgress = options.onProgress
+		const fetchTimeoutMs =
+			options.fetchTimeoutMs ??
+			positiveInteger(process.env.AGENCY_PUSH_FETCH_TIMEOUT_MS, 30_000)
+		const pushTimeoutMs =
+			options.pushTimeoutMs ??
+			positiveInteger(process.env.AGENCY_PUSH_TIMEOUT_MS, 120_000)
+		const retryDelayMs = options.retryDelayMs ?? 250
+		const env = gitEnvironment()
 		onProgress?.("inspect")
 		const currentBranch = yield* git(
 			fs,
 			checkout,
 			["symbolic-ref", "--quiet", "--short", "HEAD"],
 			"Git checkout must be attached to the declared branch",
+			"inspect",
 		)
 		if (currentBranch.stdout.trim() !== branch) {
-			return yield* new PushError({
-				message: `Declared delivery branch '${branch}' does not match checked-out Git branch '${currentBranch.stdout.trim()}'`,
-			})
+			return yield* pushError(
+				`Declared delivery branch '${branch}' does not match checked-out Git branch '${currentBranch.stdout.trim()}'`,
+				"precondition",
+				"inspect",
+			)
 		}
 		const status = yield* git(
 			fs,
 			checkout,
 			["status", "--porcelain=v1"],
 			"Failed to inspect Git status",
+			"inspect",
 		)
 		if (status.stdout.length > 0) {
-			return yield* new PushError({
-				message:
-					"Cannot publish a dirty Git worktree; commit or discard changes first",
-			})
+			return yield* pushError(
+				"Cannot publish a dirty Git worktree; commit or discard changes first",
+				"precondition",
+				"inspect",
+			)
 		}
 
-		onProgress?.("fetch")
-		yield* git(
+		const initialTip = yield* gitRevision(fs, checkout, "HEAD")
+		const initialBase = yield* gitRevision(
 			fs,
 			checkout,
-			["fetch", remote, `+refs/heads/*:refs/remotes/${remote}/*`],
-			`Failed to fetch remote '${remote}'`,
+			`refs/remotes/${remote}/${base}`,
 		)
+		if (initialTip && initialBase) {
+			const cachedBaseIsAncestor = yield* gitAncestor(
+				fs,
+				checkout,
+				initialBase,
+				initialTip,
+				"validate",
+			)
+			if (cachedBaseIsAncestor) {
+				onProgress?.("validate")
+				const initialLog = yield* git(
+					fs,
+					checkout,
+					[
+						"log",
+						"--format=%H%x00%an%x00%ae%x00%B%x00%x1e",
+						`${initialBase}..${initialTip}`,
+					],
+					"Failed to inspect outgoing Git commits",
+					"validate",
+				)
+				yield* Effect.try({
+					try: () =>
+						validateGitCommits(parseGitCommits(initialLog.stdout), base),
+					catch: (cause) => cause as PushError,
+				})
+			}
+		}
+
+		onProgress?.("fetch")
+		const fetchRemote = (
+			attempt: number,
+		): Effect.Effect<CommandResult, PushError> =>
+			git(
+				fs,
+				checkout,
+				[
+					"fetch",
+					"--prune",
+					remote,
+					`+refs/heads/${base}:refs/remotes/${remote}/${base}`,
+					`+refs/heads/${branch}*:refs/remotes/${remote}/${branch}*`,
+				],
+				`Failed to fetch remote '${remote}'`,
+				"fetch",
+				{ timeoutMs: fetchTimeoutMs, env },
+			).pipe(
+				Effect.catchAll((error) =>
+					attempt < 2 && ["timeout", "transport"].includes(error.category)
+						? Effect.sleep(retryDelayMs + Math.floor(Math.random() * 100)).pipe(
+								Effect.flatMap(() => fetchRemote(attempt + 1)),
+							)
+						: Effect.fail(error),
+				),
+			)
+		yield* fetchRemote(1)
 		const [tip, baseRevision] = yield* Effect.all(
 			[
-				gitRevision(fs, checkout, "HEAD"),
-				gitRevision(fs, checkout, `refs/remotes/${remote}/${base}`),
+				gitRevision(fs, checkout, "HEAD", "validate"),
+				gitRevision(fs, checkout, `refs/remotes/${remote}/${base}`, "validate"),
 			],
 			{ concurrency: "unbounded" },
 		)
 		if (!tip || !baseRevision) {
-			return yield* new PushError({
-				message: `Declared base '${base}' was not found on remote '${remote}'`,
-			})
+			return yield* pushError(
+				`Declared base '${base}' was not found on remote '${remote}'`,
+				"precondition",
+				"validate",
+			)
 		}
-		if (!(yield* gitAncestor(fs, checkout, baseRevision, tip))) {
-			return yield* new PushError({
-				message: `Declared base '${base}' (${baseRevision}) is not an ancestor of Git HEAD (${tip})`,
-			})
+		if (!(yield* gitAncestor(fs, checkout, baseRevision, tip, "validate"))) {
+			return yield* pushError(
+				`Declared base '${base}' (${baseRevision}) is not an ancestor of Git HEAD (${tip})`,
+				"precondition",
+				"validate",
+			)
 		}
 
 		onProgress?.("validate")
@@ -190,6 +480,7 @@ const publishGit = (
 				`${baseRevision}..${tip}`,
 			],
 			"Failed to inspect outgoing Git commits",
+			"validate",
 		)
 		yield* Effect.try({
 			try: () => validateGitCommits(parseGitCommits(log.stdout), base),
@@ -200,11 +491,17 @@ const publishGit = (
 			fs,
 			checkout,
 			`refs/remotes/${remote}/${branch}`,
+			"validate",
 		)
-		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`,
-			})
+		if (
+			remoteTip &&
+			!(yield* gitAncestor(fs, checkout, remoteTip, tip, "validate"))
+		) {
+			return yield* pushError(
+				`Remote branch '${branch}' on '${remote}' is not an ancestor of Git HEAD; refusing a non-fast-forward update`,
+				"remote_divergence",
+				"validate",
+			)
 		}
 
 		onProgress?.("publish")
@@ -217,19 +514,58 @@ const publishGit = (
 				`+refs/heads/*:refs/remotes/${remote}/*`,
 			],
 			`Failed to configure remote '${remote}' tracking`,
+			"publish",
 		)
-		yield* git(
-			fs,
-			checkout,
-			[
-				"push",
-				"-u",
-				remote,
-				`HEAD:refs/heads/${branch}`,
-				`--force-if-includes`,
-			],
-			`Failed to push declared branch '${branch}'`,
+		const pushed = yield* Effect.either(
+			git(
+				fs,
+				checkout,
+				[
+					"push",
+					"-u",
+					remote,
+					`HEAD:refs/heads/${branch}`,
+					`--force-if-includes`,
+				],
+				`Failed to push declared branch '${branch}'`,
+				"publish",
+				{
+					timeoutMs: pushTimeoutMs,
+					env,
+					forwardOutput: options.forwardOutput,
+				},
+			),
 		)
+		if (Either.isLeft(pushed)) {
+			onProgress?.("reconcile")
+			const reconciled = yield* Effect.either(
+				git(
+					fs,
+					checkout,
+					["ls-remote", "--heads", remote, `refs/heads/${branch}`],
+					`Failed to reconcile remote branch '${branch}'`,
+					"reconcile",
+					{ timeoutMs: fetchTimeoutMs, env },
+				),
+			)
+			if (Either.isLeft(reconciled)) {
+				return yield* pushError(
+					`Publication outcome is unknown after '${pushed.left.message}' and remote reconciliation also failed: ${reconciled.left.message}`,
+					"ambiguous_publication",
+					"reconcile",
+				)
+			}
+			const reconciledTip = reconciled.right.stdout.split(/\s+/, 1)[0] || null
+			if (reconciledTip === tip) return { tip }
+			if (reconciledTip !== remoteTip) {
+				return yield* pushError(
+					`Publication outcome is unknown: remote branch '${branch}' changed to ${reconciledTip ?? "a missing ref"} while publishing ${tip}`,
+					"ambiguous_publication",
+					"reconcile",
+				)
+			}
+			return yield* pushed.left
+		}
 		return { tip }
 	})
 
@@ -249,48 +585,58 @@ export class PushService extends Effect.Service<PushService>()("PushService", {
 					compact: true,
 				})
 				if (!context.validation.valid) {
-					return yield* new PushError({
-						message: "Cannot publish from an invalid Agency workbase",
-					})
+					return yield* pushError(
+						"Cannot publish from an invalid Agency workbase",
+						"precondition",
+						"context",
+					)
 				}
 				if (context.target.kind !== "task" && context.target.kind !== "phase") {
-					return yield* new PushError({
-						message: "agency push must run from an execution task or phase",
-					})
+					return yield* pushError(
+						"agency push must run from an execution task or phase",
+						"precondition",
+						"context",
+					)
 				}
 				if (
 					context.authority.mode !== "execution" ||
 					!context.authority.writable
 				) {
-					return yield* new PushError({
-						message:
-							"Current Agency target has no writable execution authority",
-					})
+					return yield* pushError(
+						"Current Agency target has no writable execution authority",
+						"precondition",
+						"context",
+					)
 				}
 				if (
 					!context.workspace?.writable?.materialized ||
 					!context.workspace.writable.registered
 				) {
-					return yield* new PushError({
-						message:
-							"Current Agency writable checkout is not materialized and registered",
-					})
+					return yield* pushError(
+						"Current Agency writable checkout is not materialized and registered",
+						"precondition",
+						"context",
+					)
 				}
 				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("; ")}`,
-					})
+					return yield* pushError(
+						`Cannot publish blocked Agency work: ${blockers.map((blocker) => blocker.reason).join("; ")}`,
+						"precondition",
+						"context",
+					)
 				}
 
 				const taskId = context.target.taskId
 				if (!taskId) {
-					return yield* new PushError({
-						message: "Current Agency execution target has no task ID",
-					})
+					return yield* pushError(
+						"Current Agency execution target has no task ID",
+						"precondition",
+						"context",
+					)
 				}
 				const phaseId =
 					context.target.kind === "phase" ? context.target.phaseId : undefined
@@ -303,14 +649,18 @@ export class PushService extends Effect.Service<PushService>()("PushService", {
 							: null
 						: task.data
 				if (!execution || "review" in execution) {
-					return yield* new PushError({
-						message: "Current Agency target is not a delivery execution unit",
-					})
+					return yield* pushError(
+						"Current Agency target is not a delivery execution unit",
+						"precondition",
+						"context",
+					)
 				}
 				if (execution.status !== "working") {
-					return yield* new PushError({
-						message: `Cannot publish Agency work with status '${execution.status}'; status must be working`,
-					})
+					return yield* pushError(
+						`Cannot publish Agency work with status '${execution.status}'; status must be working`,
+						"precondition",
+						"context",
+					)
 				}
 				const checkout = context.authority.writable.checkoutPath
 				const { config } = yield* workbase.loadConfig(context.workbase.root)
@@ -321,7 +671,7 @@ export class PushService extends Effect.Service<PushService>()("PushService", {
 					remote,
 					execution.branch,
 					execution.base,
-					options.onProgress,
+					options,
 				)
 				return {
 					vcs: "git",

package/src/usage-log.test.ts

@@ -24,6 +24,13 @@ describe("usage logging", () => {
 					durationMs: 12.4,
 					outcome: "success",
 					exitStatus: 0,
+					...(commandPath === "context"
+						? {
+								vcs: "git" as const,
+								terminalStage: "publish",
+								category: "success",
+							}
+						: {}),
 				},
 				"1.2.3",
 				env,
@@ -35,7 +42,7 @@ describe("usage logging", () => {
 		)
 		expect(await exportUsageEvents(env)).toEqual([
 			expect.objectContaining({
-				version: 1,
+				version: 2,
 				sessionId: "session-1",
 				sessionSequence: 1,
 				agencyVersion: "1.2.3",
@@ -48,6 +55,9 @@ describe("usage logging", () => {
 			expect.objectContaining({
 				sessionSequence: 2,
 				commandPath: "context",
+				vcs: "git",
+				terminalStage: "publish",
+				category: "success",
 			}),
 		])
 	})

package/src/usage-log.ts

@@ -2,7 +2,7 @@ import { Database } from "bun:sqlite"
 import { mkdir } from "node:fs/promises"
 import { dirname, join } from "node:path"
 
-const USAGE_EVENT_VERSION = 1 as const
+const USAGE_EVENT_VERSION = 2 as const
 const DEFAULT_RETENTION_DAYS = 90
 
 export interface UsageEvent {
@@ -11,6 +11,9 @@ export interface UsageEvent {
 	readonly durationMs: number
 	readonly exitStatus: number
 	readonly outcome: "success" | "failure"
+	readonly vcs?: "git"
+	readonly terminalStage?: string
+	readonly category?: string
 }
 
 const stateDirectory = (env: NodeJS.ProcessEnv) =>
@@ -50,6 +53,13 @@ const openDatabase = async (env: NodeJS.ProcessEnv) => {
 			exit_status INTEGER NOT NULL
 		)
 	`)
+	for (const column of ["vcs", "terminal_stage", "category"]) {
+		try {
+			database.run(`ALTER TABLE usage_events ADD COLUMN ${column} TEXT`)
+		} catch {
+			// Existing databases already have migrated columns.
+		}
+	}
 	database.run(
 		"CREATE INDEX IF NOT EXISTS usage_events_session ON usage_events(session_id, session_sequence)",
 	)
@@ -74,11 +84,11 @@ export async function recordUsageEvent(
 					INSERT INTO usage_events (
 						event_version, session_id, session_sequence, occurred_at,
 						agency_version, command_path, flag_names, duration_ms,
-						outcome, exit_status
+						outcome, exit_status, vcs, terminal_stage, category
 					) VALUES (
 						?, ?,
 						(SELECT COALESCE(MAX(session_sequence), 0) + 1 FROM usage_events WHERE session_id = ?),
-						?, ?, ?, ?, ?, ?, ?
+						?, ?, ?, ?, ?, ?, ?, ?, ?, ?
 					)
 				`)
 			.run(
@@ -92,6 +102,9 @@ export async function recordUsageEvent(
 				Math.max(0, Math.round(event.durationMs)),
 				event.outcome,
 				event.exitStatus,
+				event.vcs ?? null,
+				event.terminalStage ?? null,
+				event.category ?? null,
 			)
 		if (Math.random() < 0.01) {
 			const days = retentionDays(env)
@@ -119,7 +132,7 @@ export async function exportUsageEvents(
 			.query(`
 				SELECT event_version, session_id, session_sequence, occurred_at,
 					agency_version, command_path, flag_names, duration_ms,
-					outcome, exit_status
+					outcome, exit_status, vcs, terminal_stage, category
 				FROM usage_events ORDER BY occurred_at, id
 			`)
 			.all() as Record<string, string | number>[]
@@ -134,6 +147,11 @@ export async function exportUsageEvents(
 			durationMs: row.duration_ms,
 			outcome: row.outcome,
 			exitStatus: row.exit_status,
+			...(row.vcs == null ? {} : { vcs: row.vcs }),
+			...(row.terminal_stage == null
+				? {}
+				: { terminalStage: row.terminal_stage }),
+			...(row.category == null ? {} : { category: row.category }),
 		}))
 	} catch {
 		return []

package/src/utils/process.test.ts

@@ -64,4 +64,14 @@ describe("spawnProcess", () => {
 		expect(result.stderr).toContain("err:0:")
 		expect(result.stderr).toContain(`err:${lineCount - 1}:`)
 	})
+
+	test("terminates timed-out process groups", async () => {
+		const startedAt = performance.now()
+		await expect(
+			Effect.runPromise(
+				spawnProcess(["sh", "-c", "sleep 30 & wait"], { timeoutMs: 25 }),
+			),
+		).rejects.toThrow("Process timed out")
+		expect(performance.now() - startedAt).toBeLessThan(1_000)
+	})
 })

package/src/utils/process.ts

@@ -18,6 +18,7 @@ interface SpawnOptions {
 	readonly stdout?: "pipe" | "inherit" | "tee"
 	readonly stderr?: "pipe" | "inherit" | "tee"
 	readonly env?: Record<string, string>
+	readonly timeoutMs?: number
 }
 
 const readOutput = async (
@@ -45,8 +46,14 @@ class ProcessError extends Data.TaggedError("ProcessError")<{
 	command: string
 	exitCode: number
 	stderr: string
+	timedOut?: boolean
+	timeoutMs?: number
+	elapsedMs?: number
 }> {
 	override get message(): string {
+		if (this.timedOut) {
+			return `Process timed out after ${this.elapsedMs ?? this.timeoutMs} ms: ${this.command}${this.stderr ? `\n${this.stderr}` : ""}`
+		}
 		return (
 			this.stderr ||
 			`Process failed with exit code ${this.exitCode}: ${this.command}`
@@ -65,12 +72,14 @@ export const spawnProcess = (
 ): Effect.Effect<ProcessResult, ProcessError> =>
 	Effect.tryPromise({
 		try: async () => {
+			const startedAt = performance.now()
 			const proc = Bun.spawn([...args], {
 				cwd: options?.cwd ?? process.cwd(),
 				stdin: options?.stdin ?? "pipe",
 				stdout: options?.stdout === "inherit" ? "inherit" : "pipe",
 				stderr: options?.stderr === "inherit" ? "inherit" : "pipe",
 				env: options?.env ? { ...process.env, ...options.env } : process.env,
+				detached: options?.timeoutMs !== undefined,
 			})
 			// Start draining stdout/stderr immediately so verbose subprocesses
 			// cannot block on filled pipe buffers before they exit.
@@ -89,11 +98,53 @@ export const spawnProcess = (
 							options?.stderr === "tee" ? process.stderr : undefined,
 						)
 
+			let timedOut = false
+			let timer: ReturnType<typeof setTimeout> | undefined
+			const exited =
+				options?.timeoutMs === undefined
+					? proc.exited
+					: Promise.race([
+							proc.exited,
+							new Promise<number>((resolve) => {
+								timer = setTimeout(async () => {
+									timedOut = true
+									try {
+										process.kill(-proc.pid, "SIGTERM")
+									} catch {
+										proc.kill("SIGTERM")
+									}
+									const stopped = await Promise.race([
+										proc.exited.then(() => true),
+										Bun.sleep(250).then(() => false),
+									])
+									if (!stopped) {
+										try {
+											process.kill(-proc.pid, "SIGKILL")
+										} catch {
+											proc.kill("SIGKILL")
+										}
+									}
+									resolve(await proc.exited)
+								}, options.timeoutMs)
+							}),
+						])
 			const [exitCode, stdout, stderr] = await Promise.all([
-				proc.exited,
+				exited,
 				stdoutPromise,
 				stderrPromise,
 			])
+			if (timer) clearTimeout(timer)
+			if (timedOut) {
+				throw new ProcessError({
+					command: args.join(" "),
+					exitCode:
+						typeof exitCode === "number" ? exitCode : (proc.exitCode ?? -1),
+					stderr: stderr.trim(),
+					timedOut: true,
+					timeoutMs: options?.timeoutMs,
+					elapsedMs: Math.round(performance.now() - startedAt),
+				})
+			}
 
 			return {
 				stdout: stdout.trim(),
@@ -103,9 +154,11 @@ export const spawnProcess = (
 			}
 		},
 		catch: (error) =>
-			new ProcessError({
-				command: args.join(" "),
-				exitCode: -1,
-				stderr: error instanceof Error ? error.message : String(error),
-			}),
+			error instanceof ProcessError
+				? error
+				: new ProcessError({
+						command: args.join(" "),
+						exitCode: -1,
+						stderr: error instanceof Error ? error.message : String(error),
+					}),
 	})