@markjaquith/agency 2.48.1 → 2.49.0

package/README.md

@@ -610,7 +610,8 @@ Inspect tasks:
 ```text
 agency task list [filters] [--json]
 agency task show <id> [--json]
-agency task status <id> <open|working|dropped> [--json]
+agency task status <id> <open|working|done|dropped>
+  [--no-pull-request --summary <text> [--evidence-url <url>]] [--json]
 agency task update <id> [metadata options] [--json]
 agency task rename <id> <new-id> [--json]
 agency task move <id> (--epic <epic-id> | --no-epic) [--json]
@@ -649,7 +650,8 @@ agency phase create <task-id> <phase-id>
 
 agency phase list <task-id> [filters] [--json]
 agency phase show <task-id> <phase-id> [--json]
-agency phase status <task-id> <phase-id> <open|working|dropped> [--json]
+agency phase status <task-id> <phase-id> <open|working|done|dropped>
+  [--no-pull-request --summary <text> [--evidence-url <url>]] [--json]
 agency phase update <task-id> <phase-id> [metadata options] [--json]
 agency phase rename <task-id> <phase-id> <new-id> [--json]
 agency phase dependency <add|remove> <task-id> <phase-id> <dependency-id>
@@ -672,8 +674,12 @@ writing anything.
 Single-phase tasks and phases store status in YAML. New execution units start
 `open`, and `agency work` marks the selected execution unit `working` immediately
 before launch. Running `agency work` again can relaunch unclaimed `working` work.
-The `done` status is reserved for an authoritative merged pull request and is
-applied by `agency sync --apply`, not by task or phase status commands.
+By default, `done` requires an authoritative merged pull request and is applied
+by `agency sync --apply`. Work whose intended outcome genuinely requires no pull
+request may instead use an explicit `--no-pull-request --summary <text>` status
+transition. Agency records the summary, completion time, and optional evidence
+URL durably; reopening removes that evidence. This exceptional path refuses work
+that already has a recorded pull request.
 Use explicit claims only when an external orchestrator needs coordinated
 ownership. The interactive work selector displays status markers before
 execution units. Existing working and delegated work may be released to `open`
@@ -704,15 +710,19 @@ agency claim <task-id> [phase-id] --claimant <id> --runner <id>
 agency release <task-id> [phase-id] --session-id <id>
   --revision <sha256> [--json]
 agency finish <task-id> [phase-id] --session-id <id>
-  --revision <sha256> --outcome <done|dropped> [--json]
+  --revision <sha256> --outcome <done|dropped>
+  [--no-pull-request --summary <text> [--evidence-url <url>]] [--json]
 ```
 
 An active claim sets status to `working`. Release returns it to `open`. Finish
 records the claim outcome and ownership history; a `done` claim outcome leaves
 the execution unit `working` until its pull request is merged, while `dropped`
-remains terminal. Conflicts return the current revision and complete ownership
-record in the machine error envelope rather than overwriting it. Expired claims
-may be replaced with a revision-guarded claim.
+remains terminal. For a genuine non-PR outcome, `--no-pull-request` atomically
+records completion evidence, finishes the claim, and sets the execution unit to
+`done`; `--summary` is required and `--evidence-url` is optional. Conflicts return
+the current revision and complete ownership record in the machine error envelope
+rather than overwriting it. Expired claims may be replaced with a
+revision-guarded claim.
 
 `agency work` does not claim execution units. It refuses active explicit claims,
 marks open execution work `working`, and launches the runner. External

package/cli.ts

@@ -205,6 +205,9 @@ const commands: Record<string, Command> = {
 					sessionId: options["session-id"],
 					revision: options.revision,
 					outcome: options.outcome,
+					noPullRequest: options["no-pull-request"],
+					summary: options.summary,
+					evidenceUrl: options["evidence-url"],
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
@@ -298,6 +301,9 @@ const commands: Record<string, Command> = {
 					clearReferences: options["clear-references"],
 					prUrl: options["pr-url"],
 					clearPr: options["clear-pr"],
+					noPullRequest: options["no-pull-request"],
+					summary: options.summary,
+					evidenceUrl: options["evidence-url"],
 					ifRevision: options["if-revision"],
 					dependsOn: options["depends-on"],
 					firstPhase: options["first-phase"],
@@ -449,6 +455,9 @@ const commands: Record<string, Command> = {
 					clearReferences: options["clear-references"],
 					prUrl: options["pr-url"],
 					clearPr: options["clear-pr"],
+					noPullRequest: options["no-pull-request"],
+					summary: options.summary,
+					evidenceUrl: options["evidence-url"],
 					ifRevision: options["if-revision"],
 					noEpic: options["no-epic"],
 					multiPhase: options["multi-phase"],

package/package.json

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

package/src/cli-parser.test.ts

@@ -362,6 +362,64 @@ describe("strict CLI parsing", () => {
 				"working",
 			]),
 		).toThrow("must be 'done' or 'dropped'")
+		expect(
+			parseCli([
+				"finish",
+				"task",
+				"--session-id",
+				"job-1",
+				"--revision",
+				revision,
+				"--outcome",
+				"done",
+				"--no-pull-request",
+				"--summary",
+				"Investigation completed",
+				"--evidence-url",
+				"https://example.com/result",
+			]),
+		).toMatchObject({
+			values: {
+				"no-pull-request": true,
+				summary: "Investigation completed",
+				"evidence-url": "https://example.com/result",
+			},
+		})
+		expect(() =>
+			parseCli([
+				"finish",
+				"task",
+				"--session-id",
+				"job-1",
+				"--revision",
+				revision,
+				"--outcome",
+				"done",
+				"--no-pull-request",
+			]),
+		).toThrow("--summary' is required")
+		expect(() =>
+			parseCli([
+				"task",
+				"status",
+				"example",
+				"working",
+				"--no-pull-request",
+				"--summary",
+				"Not done",
+			]),
+		).toThrow("valid only with a done status")
+		expect(() =>
+			parseCli([
+				"phase",
+				"status",
+				"task",
+				"phase",
+				"done",
+				"--summary",
+				"Missing explicit flag",
+			]),
+		).toThrow("require '--no-pull-request'")
 	})
 
 	test("accepts valid mutation revisions and rejects malformed hashes", () => {

package/src/cli-parser.ts

@@ -120,6 +120,12 @@ const ownedClaimOptions = {
 	revision: { type: "string" },
 } satisfies OptionConfig
 
+const nonPrCompletionOptions = {
+	"no-pull-request": { type: "boolean" },
+	summary: { type: "string" },
+	"evidence-url": { type: "string" },
+} satisfies OptionConfig
+
 const commands = {
 	init: {
 		usage: "agency init [path] [--json]",
@@ -360,6 +366,7 @@ const commands = {
 			...newWorkOptions,
 			...viewOptions,
 			...mutationOptions,
+			...nonPrCompletionOptions,
 			"pr-url": { type: "string" },
 			task: { type: "string" },
 		},
@@ -417,10 +424,10 @@ const commands = {
 				options: ["json", "task"],
 			},
 			status: {
-				usage: "agency task status <id> <status> [--json]",
+				usage: "agency task status <id> <status> [options] [--json]",
 				minArgs: 2,
 				maxArgs: 2,
-				options: ["json", "task"],
+				options: ["json", "task", "no-pull-request", "summary", "evidence-url"],
 			},
 			update: {
 				usage: "agency task update <id> [options] [--json]",
@@ -479,6 +486,7 @@ const commands = {
 			...newWorkOptions,
 			...viewOptions,
 			...mutationOptions,
+			...nonPrCompletionOptions,
 			"pr-url": { type: "string" },
 			task: { type: "string" },
 			phase: { type: "string" },
@@ -542,10 +550,18 @@ const commands = {
 				options: ["json", "task", "phase"],
 			},
 			status: {
-				usage: "agency phase status <task-id> <phase-id> <status> [--json]",
+				usage:
+					"agency phase status <task-id> <phase-id> <status> [options] [--json]",
 				minArgs: 3,
 				maxArgs: 3,
-				options: ["json", "task", "phase"],
+				options: [
+					"json",
+					"task",
+					"phase",
+					"no-pull-request",
+					"summary",
+					"evidence-url",
+				],
 			},
 			update: {
 				usage: "agency phase update <task-id> <phase-id> [options] [--json]",
@@ -631,16 +647,27 @@ const commands = {
 		usage: "agency finish <task-id> [phase-id] [options]",
 		options: {
 			...ownedClaimOptions,
+			...nonPrCompletionOptions,
 			outcome: { type: "string" },
 			task: { type: "string" },
 			phase: { type: "string" },
 		},
 		command: {
 			usage:
-				"agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped> [--json]",
+				"agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped> [options] [--json]",
 			minArgs: 1,
 			maxArgs: 2,
-			options: ["session-id", "revision", "outcome", "json", "task", "phase"],
+			options: [
+				"session-id",
+				"revision",
+				"outcome",
+				"no-pull-request",
+				"summary",
+				"evidence-url",
+				"json",
+				"task",
+				"phase",
+			],
 			required: ["session-id", "revision", "outcome"],
 		},
 	},
@@ -1409,6 +1436,40 @@ export function parseCli(args: readonly string[]): ParsedCli {
 			spec.usage,
 		)
 	}
+	const nonPrCompletion = parsed.values["no-pull-request"] === true
+	const completionSummary = parsed.values.summary
+	const completionEvidenceUrl = parsed.values["evidence-url"]
+	if (
+		(completionSummary !== undefined || completionEvidenceUrl !== undefined) &&
+		!nonPrCompletion
+	) {
+		throw usageError(
+			"Options '--summary' and '--evidence-url' require '--no-pull-request'.",
+			spec.usage,
+		)
+	}
+	if (nonPrCompletion) {
+		if (
+			typeof completionSummary !== "string" ||
+			completionSummary.trim().length === 0
+		) {
+			throw usageError(
+				"Option '--summary' is required with '--no-pull-request'.",
+				spec.usage,
+			)
+		}
+		const completesDone =
+			(commandName === "finish" && parsed.values.outcome === "done") ||
+			(["task", "phase"].includes(commandName) &&
+				subcommand === "status" &&
+				commandPositionals.at(-1) === "done")
+		if (!completesDone) {
+			throw usageError(
+				"Option '--no-pull-request' is valid only with a done status or outcome.",
+				spec.usage,
+			)
+		}
+	}
 	if (commandName === "work") {
 		const preparing = commandPositionals[0] === "prepare"
 		if (

package/src/cli.test.ts

@@ -248,6 +248,77 @@ describe("CLI", () => {
 			parseJson(await runCli(["task", "show", "claimed", "--json"], root)).data
 				.status,
 		).toBe("working")
+
+		parseJson(
+			await runCli(
+				["task", "create", "non-pr", "--repo", "agency", "--json"],
+				root,
+			),
+		)
+		const nonPrContext = parseJson(
+			await runCli(["context", "tasks/non-pr", "--json"], root),
+		)
+		const nonPrClaim = parseJson(
+			await runCli(
+				[
+					"claim",
+					"non-pr",
+					"--claimant",
+					"orchestrator",
+					"--runner",
+					"agent",
+					"--session-id",
+					"job-2",
+					"--revision",
+					nonPrContext.documents.task.sha256,
+					"--json",
+				],
+				root,
+			),
+		)
+		parseJson(
+			await runCli(
+				[
+					"finish",
+					"non-pr",
+					"--session-id",
+					"job-2",
+					"--revision",
+					nonPrClaim.revision,
+					"--outcome",
+					"done",
+					"--no-pull-request",
+					"--summary",
+					"Investigation completed without changes.",
+					"--evidence-url",
+					"https://example.com/result",
+					"--json",
+				],
+				root,
+			),
+		)
+		expect(
+			parseJson(await runCli(["task", "show", "non-pr", "--json"], root)).data,
+		).toMatchObject({
+			status: "done",
+			completion: {
+				mode: "non-pr",
+				summary: "Investigation completed without changes.",
+				evidenceUrl: "https://example.com/result",
+			},
+		})
+		const prUpdate = await runCli(
+			[
+				"task",
+				"update",
+				"non-pr",
+				"--pr-url",
+				"https://github.com/example/agency/pull/1",
+			],
+			root,
+		)
+		expect(prUpdate.exitCode).toBe(1)
+		expect(prUpdate.stderr).toContain("Reopen non-PR completed work")
 	})
 
 	test("routes graph mutations through structured output", async () => {

package/src/commands/claim.ts

@@ -13,6 +13,9 @@ interface ClaimCommandOptions extends BaseCommandOptions {
 	readonly revision?: string
 	readonly expiresAt?: string
 	readonly outcome?: string
+	readonly noPullRequest?: boolean
+	readonly summary?: string
+	readonly evidenceUrl?: string
 	readonly json?: boolean
 }
 
@@ -32,6 +35,16 @@ export const claimCommand = (options: ClaimCommandOptions) =>
 				new Error("Claimant and runner identities are required"),
 			)
 		}
+		if (options.noPullRequest && !options.summary?.trim()) {
+			return yield* Effect.fail(
+				new Error("Non-PR completion requires a non-empty summary"),
+			)
+		}
+		if (options.noPullRequest && options.outcome !== "done") {
+			return yield* Effect.fail(
+				new Error("Non-PR completion is valid only with a done outcome"),
+			)
+		}
 		if (
 			options.operation === "finish" &&
 			options.outcome !== "done" &&
@@ -65,6 +78,16 @@ export const claimCommand = (options: ClaimCommandOptions) =>
 							{
 								...common,
 								outcome: options.outcome as "done" | "dropped",
+								...(options.noPullRequest
+									? {
+											nonPrCompletion: {
+												summary: options.summary!,
+												...(options.evidenceUrl
+													? { evidenceUrl: options.evidenceUrl }
+													: {}),
+											},
+										}
+									: {}),
 							},
 							cwd,
 						)
@@ -91,8 +114,9 @@ Release an execution unit owned by the session.
 `
 
 export const finishHelp = `
-Usage: agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped>
+Usage: agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped> [--no-pull-request --summary <text> [--evidence-url <url>]]
 
 Finish a claim owned by the session. A done claim outcome leaves unmerged work
-working; agency sync --apply marks the execution unit done after merge.
+working; agency sync --apply marks the execution unit done after merge. Use
+--no-pull-request with a summary for an explicit non-PR completion.
 `

package/src/commands/phase.ts

@@ -31,6 +31,9 @@ interface PhaseOptions extends BaseCommandOptions {
 	readonly pr?: boolean
 	readonly work?: boolean
 	readonly auto?: boolean
+	readonly noPullRequest?: boolean
+	readonly summary?: string
+	readonly evidenceUrl?: string
 }
 
 export const phase = (options: PhaseOptions, work: StartWork = startWork) =>
@@ -166,7 +169,20 @@ export const phase = (options: PhaseOptions, work: StartWork = startWork) =>
 						),
 					)
 				}
-				const record = yield* phases.setStatus(taskId, phaseId, status, cwd)
+				const record = yield* phases.setStatus(
+					taskId,
+					phaseId,
+					status,
+					cwd,
+					options.noPullRequest
+						? {
+								summary: options.summary ?? "",
+								...(options.evidenceUrl
+									? { evidenceUrl: options.evidenceUrl }
+									: {}),
+							}
+						: undefined,
+				)
 				const { content: _, ...output } = record
 				log(
 					options.json
@@ -275,7 +291,7 @@ Subcommands:
   list <task>           List task phases
   show <task> <phase>   Show a phase
   status <task> <phase> <status>
-                        Set open, working, or dropped
+                        Set open, working, dropped, or explicit non-PR done
   update <task> <phase> Update phase metadata
   rename <task> <phase> <new-id>
                         Rename a phase and update dependencies
@@ -285,6 +301,11 @@ Subcommands:
 Mutation option:
   --if-revision <hash>  Require the target's current revision
 
+Non-PR completion options (status done only):
+  --no-pull-request     Complete without a pull request
+  --summary <text>      Required durable outcome summary
+  --evidence-url <url>  Optional supporting record
+
 Create options:
   --description <text>  Short description of the phase
   --repo <alias>        Writable repository

package/src/commands/task.ts

@@ -38,6 +38,9 @@ interface TaskOptions extends BaseCommandOptions {
 	readonly pr?: boolean
 	readonly work?: boolean
 	readonly auto?: boolean
+	readonly noPullRequest?: boolean
+	readonly summary?: string
+	readonly evidenceUrl?: string
 }
 
 export interface TaskInteraction {
@@ -304,7 +307,19 @@ export const task = (
 						new Error("Usage: agency task status <id> <status>"),
 					)
 				}
-				const record = yield* tasks.setStatus(id, status, cwd)
+				const record = yield* tasks.setStatus(
+					id,
+					status,
+					cwd,
+					options.noPullRequest
+						? {
+								summary: options.summary ?? "",
+								...(options.evidenceUrl
+									? { evidenceUrl: options.evidenceUrl }
+									: {}),
+							}
+						: undefined,
+				)
 				const { content: _, ...output } = record
 				log(
 					options.json
@@ -423,7 +438,7 @@ Subcommands:
   create <id>           Create a task without prompting
   list                  List tasks
   show <id>             Show a task
-  status <id> <status>  Set open, working, or dropped
+  status <id> <status>  Set open, working, dropped, or explicit non-PR done
   update <id>           Update task metadata
   rename <id> <new-id>  Rename a task and update graph references
   move <id>             Move a task with --epic or --no-epic
@@ -433,6 +448,11 @@ Subcommands:
 Mutation option:
   --if-revision <hash>  Require the target's current revision
 
+Non-PR completion options (status done only):
+  --no-pull-request     Complete without a pull request
+  --summary <text>      Required durable outcome summary
+  --evidence-url <url>  Optional supporting record
+
 Create options:
   --ticket-url <url>    External ticket URL (optional)
   --description <text>  Short description of the task

package/src/services/ClaimService.test.ts

@@ -147,6 +147,65 @@ describe("claim service", () => {
 		})
 	})
 
+	test("finishes claimed non-PR work with durable completion evidence", async () => {
+		const initial = await inspect()
+		const acquired = await claim(initial.revision)
+		const finished = await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.finish(
+						{
+							taskId: "single",
+							sessionId: "session-1",
+							revision: acquired.revision,
+							outcome: "done",
+							nonPrCompletion: {
+								summary: "Review completed; no code change was needed.",
+								evidenceUrl: "https://example.com/review",
+							},
+							now: at("2026-07-17T12:45:00.000Z"),
+						},
+						root,
+					),
+				),
+			),
+		)
+
+		expect(finished.data).toMatchObject({
+			status: "done",
+			claim: { state: "finished", outcome: "done" },
+			completion: {
+				mode: "non-pr",
+				completedAt: "2026-07-17T12:45:00.000Z",
+				summary: "Review completed; no code change was needed.",
+				evidenceUrl: "https://example.com/review",
+			},
+		})
+	})
+
+	test("rejects invalid claimed non-PR completion", async () => {
+		const initial = await inspect()
+		const acquired = await claim(initial.revision)
+		await expect(
+			runTestEffect(
+				ClaimService.pipe(
+					Effect.flatMap((service) =>
+						service.finish(
+							{
+								taskId: "single",
+								sessionId: "session-1",
+								revision: acquired.revision,
+								outcome: "done",
+								nonPrCompletion: { summary: " " },
+							},
+							root,
+						),
+					),
+				),
+			),
+		).rejects.toThrow("summary must not be empty")
+	})
+
 	test("returns structured ownership and revision conflicts", async () => {
 		const initial = await inspect()
 		const acquired = await claim(initial.revision)

package/src/services/ClaimService.ts

@@ -31,6 +31,10 @@ import {
 	type PhaseFrontmatter as PhaseData,
 	type TaskFrontmatter as TaskData,
 } from "../workbase/schemas"
+import {
+	buildNonPrCompletion,
+	type NonPrCompletionInput,
+} from "../workbase/completion"
 
 class ClaimError extends Data.TaggedError("ClaimError")<{
 	readonly message: string
@@ -83,6 +87,7 @@ interface OwnedClaimInput {
 
 interface FinishInput extends OwnedClaimInput {
 	readonly outcome: "done" | "dropped"
+	readonly nonPrCompletion?: NonPrCompletionInput
 }
 
 interface ExpireClaimInput {
@@ -507,6 +512,11 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 			finish: (input: FinishInput, startPath: string = process.cwd()) =>
 				Effect.gen(function* () {
 					assertIdentity("Session ID", input.sessionId)
+					if (input.nonPrCompletion && input.outcome !== "done") {
+						return yield* new ClaimError({
+							message: "Non-PR completion is valid only with a done outcome",
+						})
+					}
 					const service = yield* ClaimService
 					const inspected = yield* service.inspect(
 						input.taskId,
@@ -531,6 +541,22 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 										message: `Session '${input.sessionId}' does not own ${inspected.target.label}`,
 									})
 								}
+								if (input.nonPrCompletion && data.pr !== null) {
+									throw new ClaimError({
+										target: inspected.target.label,
+										message:
+											"Cannot complete without a pull request while an authoritative pull request is recorded",
+									})
+								}
+								const completionResult = input.nonPrCompletion
+									? buildNonPrCompletion(input.nonPrCompletion, now)
+									: undefined
+								if (completionResult && "error" in completionResult) {
+									throw new ClaimError({
+										target: inspected.target.label,
+										message: completionResult.error,
+									})
+								}
 								const claim: ClaimRecord = {
 									...data.claim,
 									state: "finished",
@@ -540,8 +566,15 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 								return {
 									data: {
 										...data,
-										status: input.outcome === "done" ? "working" : "dropped",
+										status: completionResult
+											? "done"
+											: input.outcome === "done"
+												? "working"
+												: "dropped",
 										claim,
+										...(completionResult
+											? { completion: completionResult.value }
+											: {}),
 									},
 									claim,
 								}