@markjaquith/agency 3.2.2 → 3.2.3

package/README.md

@@ -336,19 +336,18 @@ Custom agents are direct argv commands, never shell snippets:
 ```
 
 Available placeholders are `{prompt}`, `{workbase}`, `{target}`, `{task}`,
-`{phase}`, `{claimant}`, `{sessionId}`, and `{claimRevision}`. Task and phase
+`{phase}`, and `{sessionId}`. Task and phase
 placeholders are empty when they do not apply. `{prompt}` is empty unless
 `--auto` is set. If `resumeCommand` is omitted, the fresh command is also used
 for resumed sessions. If `autoResumeCommand` is omitted, `autoCommand` is used;
 configured agents without `autoCommand` reject `--auto`.
 
-Every agent receives the same `AGENCY_AGENT`, `AGENCY_CLAIMANT`,
-`AGENCY_SESSION_ID`, `AGENCY_CLAIM_REVISION`, `AGENCY_WORKBASE`, `AGENCY_TARGET`,
+Every agent receives the same `AGENCY_AGENT`, `AGENCY_SESSION_ID`,
+`AGENCY_WORKBASE`, `AGENCY_TARGET`,
 `AGENCY_TASK_ID`, `AGENCY_PHASE_ID`, and `AGENCY_PROMPT` environment. Configured
 environment is added without overriding these normalized values.
 Execution-unit agents also receive `AGENCY_WRITABLE_CHECKOUT` with the
 authoritative writable checkout path.
-`AGENCY_CLAIM_REVISION` is empty for local `agency work` launches.
 `AGENCY_PROMPT` is empty unless `--auto` is set.
 Autonomous prompts begin `Agency worker launch target: <target>.`, carrying the
 same canonical target as `AGENCY_TARGET`. This is the process-local fallback for
@@ -624,8 +623,8 @@ untargeted `agency pr` invocations leave command semantics to `gh`.
 
 `agency sync` first compares portable repository declarations with local
 materializations, then compares every execution declaration with local branch
-and worktree registration, checkout dirtiness, resolved reference commits, claim
-expiry, and pull request state, merge state, and mergeability. It reports
+and worktree registration, checkout dirtiness, resolved reference commits, and
+pull request state, merge state, and mergeability. It reports
 structured `changes`, `warnings`, `unresolved`, and per-execution evidence. The
 default mode applies safe reconciliation transitions; `--dry-run` is explicitly
 observational.
@@ -639,13 +638,12 @@ phase. Scoped sync does not query, materialize, or reconcile unrelated work.
 - materialize declared but missing repositories from their canonical remotes;
 - adopt legacy materializations only when they have an unambiguous portable origin;
 - materialize missing checkouts when no registration, branch, or path conflicts;
-- release an active claim only after its declared expiry has passed;
 - record or refresh a single PR whose head and base match the declaration; and
-- mark work done after its authoritative PR is merged and no active claim remains.
+- mark work done after its authoritative PR is merged.
 
 Apply never overwrites linked or invalid repositories, repairs remote drift,
 modifies dirty checkouts, moves worktrees, switches branches, resets reference
-commits, chooses among conflicting remotes or PRs, or bypasses active claims.
+commits, or chooses among conflicting remotes or PRs.
 Those conditions remain visible in `warnings` or `unresolved` with a suggested
 action.
 
@@ -836,8 +834,8 @@ fork pull requests exposed through that ref. Review workspaces contain one
 detached checkout and no writable branch. Source movement is observed separately
 from the pin and applied only by `review refresh`; sync, doctor, work, cleanup,
 and archive never move the pin implicitly. Dirty or structurally unexpected
-review checkouts block refresh and cleanup. Review tasks support normal status
-and claim lifecycle, but reject phase conversion and delivery PR operations.
+review checkouts block refresh and cleanup. Review tasks support the normal status
+lifecycle, but reject phase conversion and delivery PR operations.
 Each active or archived review task owns one internal task-scoped pin ref. A
 refresh advances that ref transactionally; failed creation removes it. Archiving
 retains the pin so a deleted source can still be restored and inspected.
@@ -926,23 +924,20 @@ 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.
+before launch. Running `agency work` again can relaunch `working` work.
 By default, `done` requires an authoritative merged pull request and is applied
 by `agency sync`. 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`
-or assigned a terminal outcome. Done and dropped work are terminal and may only
+The interactive work selector displays status markers before execution units.
+Existing working and delegated work may be returned to `open` or assigned a
+terminal outcome. Done and dropped work are terminal and may only
 remain unchanged or transition to open; reopen terminal work before changing its
 outcome.
 
 `delegated` remains readable for existing workbases but cannot be newly assigned.
-Delegation is now explicit: the claimant identifies the orchestrator and the
-agent identifies the assigned agent.
 
 Human list output is a compact table with lifecycle, readiness, parent,
 repository, branch, recorded PR, and worktree state where applicable. List and
@@ -951,37 +946,6 @@ filters, plus `--ready`, `--blocked`, `--pr`, and `--no-pr`. Status and reposito
 filters are repeatable. Rows follow task and phase declaration order; plain text
 labels remain complete without color or icon fonts.
 
-### Claims
-
-Claim mutations require the SHA-256 revision exposed by `agency context` or
-`agency graph`. Every operation compares that revision while holding an exclusive
-document lock and atomically replaces the execution document.
-
-```text
-agency claim <task-id> [phase-id] --claimant <id> --agent <id>
-  --session-id <id> --revision <sha256> [--expires-at <timestamp>] [--json]
-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>
-  [--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. 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 agent. External
-orchestrators use `agency claim`, launch and monitor their agent separately, and
-later call `agency release` or `agency finish`.
-
 ### Archive
 
 ```text
@@ -1012,8 +976,8 @@ default; `--dry-run` performs the same preflight without mutation. A dependency
 is work required by a candidate, while a dependent is work that requires the
 candidate. Dependencies within the selected cohort can be archived together,
 but a retained dependent excludes its dependency, including exclusions that
-propagate through a dependency chain. Active claims, dirty or otherwise unsafe
-managed checkouts, and occupied archive destinations are reported as per-task
+propagate through a dependency chain. Dirty or otherwise unsafe managed
+checkouts and occupied archive destinations are reported as per-task
 skips. Invalid workbase structure and infrastructure failures abort the command.
 
 Task and phase archiving update active parent documents. Agency removes
@@ -1047,7 +1011,8 @@ promptless by default; use `--auto` to send Agency's generated context prompt.
 
 `agency work prepare` resolves an execution unit and creates or reuses its
 writable and reference worktrees, or its single pinned review checkout, without
-launching an agent or changing status.
+launching an agent or changing status. Its target may be a task ID or any path
+inside the task or phase, including its `TASK.md` or `PHASE.md` document.
 Managed workbase guidance provides exact fast paths for 15 common intents:
 single-phase creation; create-and-start; materialization; remote PR sync; phase
 conversion; archive; review creation and start; status inspection; drop;
@@ -1065,8 +1030,8 @@ either. Use `--dry-run` to report planned fetch, branch, and worktree changes
 without applying them. Use `--force` to prepare work blocked by readiness, such
 as a follow-on phase whose dependency is still active; preparation still does
 not launch an agent or change lifecycle status. Validation reuse never skips
-readiness, active-claim, repository, ownership, reference-drift, dirty-workspace,
-or worktree safety checks.
+readiness, repository, ownership, reference-drift, dirty-workspace, or worktree
+safety checks.
 
 The authoritative implementation locations for this contract are
 `src/commands/task.ts` (creation output),
@@ -1193,10 +1158,7 @@ recovery action. Version 1 defines these codes:
 | `EPIC_ERROR`              | Epic operation failed                                     |
 | `TASK_ERROR`              | Task operation failed                                     |
 | `PHASE_ERROR`             | Phase operation failed                                    |
-| `CLAIM_ERROR`             | Claim input or lifecycle state is invalid                 |
-| `CLAIM_CONFLICT`          | Active or legacy ownership conflicts with an operation    |
 | `REVISION_CONFLICT`       | A durable document changed since inspection               |
-| `CLAIM_OWNERSHIP`         | The session does not own the active claim                 |
 | `ARCHIVE_ERROR`           | Archive operation failed                                  |
 | `WORKTREE_ERROR`          | Worktree operation failed                                 |
 | `PULL_REQUEST_ERROR`      | Pull request operation failed                             |
@@ -1219,7 +1181,7 @@ Success, help, and version output exit `0`; usage and command failures exit `1`.
 There are no error-specific exit statuses. `graph --jsonl` streams versioned
 records on success instead of wrapping them in an envelope; JSONL failures still
 use one error envelope. Revision and concurrency behavior is documented under
-Tasks, Phases, and Claims; selector behavior under Noninteractive Use; projection
+Tasks and Phases; selector behavior under Noninteractive Use; projection
 behavior under Target Context and Workbase Graph; and retry behavior in the
 machine error contract above.
 

package/cli-main.ts

@@ -40,7 +40,6 @@ import { ArchiveService } from "./src/services/ArchiveService"
 import { IntegrationService } from "./src/services/IntegrationService"
 import { ContextService } from "./src/services/ContextService"
 import { GraphService } from "./src/services/GraphService"
-import { ClaimService } from "./src/services/ClaimService"
 import { SyncService } from "./src/services/SyncService"
 import { ReadinessService } from "./src/services/ReadinessService"
 import { GraphMutationService } from "./src/services/GraphMutationService"
@@ -52,12 +51,6 @@ import {
 } from "./src/services/VersionControlService"
 import { review, help as reviewHelp } from "./src/commands/review"
 import { act, help as actHelp } from "./src/commands/act"
-import {
-	claimCommand,
-	claimHelp,
-	releaseHelp,
-	finishHelp,
-} from "./src/commands/claim"
 import {
 	collectCommandResult,
 	errorEnvelope,
@@ -83,7 +76,6 @@ const CliLayer = Layer.mergeAll(
 	IntegrationService.Default,
 	ContextService.Default,
 	GraphService.Default,
-	ClaimService.Default,
 	SyncService.Default,
 	ReadinessService.Default,
 	GraphMutationService.Default,
@@ -199,67 +191,6 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
-	claim: {
-		run: async (args: string[], options: Record<string, any>) => {
-			if (options.help) return console.log(claimHelp)
-			await runCommand(
-				claimCommand({
-					operation: "claim",
-					taskId: args[0],
-					phaseId: args[1],
-					claimant: options.claimant,
-					agent: options.agent,
-					sessionId: options["session-id"],
-					revision: options.revision,
-					expiresAt: options["expires-at"],
-					json: options.json,
-					silent: options.silent,
-					verbose: options.verbose,
-					cwd: options.cwd,
-				}),
-			)
-		},
-	},
-	release: {
-		run: async (args: string[], options: Record<string, any>) => {
-			if (options.help) return console.log(releaseHelp)
-			await runCommand(
-				claimCommand({
-					operation: "release",
-					taskId: args[0],
-					phaseId: args[1],
-					sessionId: options["session-id"],
-					revision: options.revision,
-					json: options.json,
-					silent: options.silent,
-					verbose: options.verbose,
-					cwd: options.cwd,
-				}),
-			)
-		},
-	},
-	finish: {
-		run: async (args: string[], options: Record<string, any>) => {
-			if (options.help) return console.log(finishHelp)
-			await runCommand(
-				claimCommand({
-					operation: "finish",
-					taskId: args[0],
-					phaseId: args[1],
-					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,
-					cwd: options.cwd,
-				}),
-			)
-		},
-	},
 	init: {
 		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) {
@@ -779,9 +710,6 @@ Commands:
   usage export          Export local usage events as JSON Lines
   epic <subcommand>      Manage epics
   phase <subcommand>     Manage task phases
-  claim <task> [phase]   Claim an execution unit
-  release <task> [phase] Release an execution unit
-  finish <task> [phase]  Finish an execution unit
   archive <type>         Archive a work item
   task <subcommand>      Manage tasks
   work [directory|task]  Work on an epic, task, or phase

package/fixtures/protocol/orchestration-recipes.json

@@ -22,20 +22,6 @@
     "agency",
     "--json"
   ],
-  [
-    "claim",
-    "checkout",
-    "ui",
-    "--claimant",
-    "orchestrator-1",
-    "--agent",
-    "opencode",
-    "--session-id",
-    "session-123",
-    "--revision",
-    "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-    "--json"
-  ],
   [
     "work",
     "prepare",
@@ -50,29 +36,18 @@
   ["work", "tasks/checkout/phases/ui", "--agent", "opencode"],
   ["sync", "--dry-run", "--json"],
   ["sync", "--json"],
-  ["pr", "create", "checkout", "ui", "--json"],
   [
-    "finish",
-    "checkout",
-    "ui",
-    "--session-id",
-    "session-123",
-    "--revision",
-    "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-    "--outcome",
+    "task",
+    "status",
+    "implement-checkout",
     "done",
+    "--no-pull-request",
+    "--summary",
+    "Completed without a pull request",
     "--json"
   ],
+  ["pr", "create", "checkout", "ui", "--json"],
+  ["sync", "checkout", "ui", "--json"],
   ["doctor", "--json"],
-  ["worktree", "repair", "checkout", "ui", "--dry-run", "--json"],
-  [
-    "release",
-    "checkout",
-    "ui",
-    "--session-id",
-    "session-123",
-    "--revision",
-    "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-    "--json"
-  ]
+  ["worktree", "repair", "checkout", "ui", "--dry-run", "--json"]
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "3.2.2",
+  "version": "3.2.3",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",
@@ -67,7 +67,6 @@
     "preuninstall": "bun scripts/install-pi-extension.ts uninstall",
     "benchmark:act": "bun scripts/benchmark-act.ts",
     "benchmark:pr": "bun scripts/benchmark-pr.ts",
-    "benchmark:release": "bun scripts/benchmark-release.ts",
     "benchmark:repositories": "bun scripts/benchmark-repositories.ts",
     "benchmark:status": "bun scripts/benchmark-status.ts",
     "benchmark:next": "bun scripts/benchmark-next.ts",
@@ -76,8 +75,6 @@
     "benchmark:workbase": "bun scripts/benchmark-workbase.ts",
     "benchmark:doctor": "bun scripts/benchmark-doctor.ts",
     "benchmark:context": "bun scripts/benchmark-context.ts",
-    "benchmark:claim": "bun scripts/benchmark-claim.ts",
-    "benchmark:finish": "bun scripts/benchmark-finish.ts",
     "benchmark:epic": "bun scripts/benchmark-epic.ts",
     "benchmark:phase": "bun scripts/benchmark-phase.ts",
     "benchmark:graph": "bun scripts/benchmark-graph.ts",

package/schemas/agency-graph-v1.schema.json

@@ -344,7 +344,6 @@
         "base": { "type": "string" },
         "pr": { "type": ["string", "null"] },
         "status": { "$ref": "#/$defs/status" },
-        "claim": { "$ref": "#/$defs/claim" },
         "sha256": { "type": "string" }
       }
     },
@@ -424,7 +423,6 @@
         "handoff": { "$ref": "#/$defs/taskHandoff" },
         "review": { "$ref": "#/$defs/reviewRecord" },
         "status": { "$ref": "#/$defs/status" },
-        "claim": { "$ref": "#/$defs/claim" },
         "sha256": { "type": "string" }
       }
     },
@@ -443,7 +441,6 @@
         "base": { "type": "string" },
         "pr": { "type": ["string", "null"] },
         "status": { "$ref": "#/$defs/status" },
-        "claim": { "$ref": "#/$defs/claim" },
         "sha256": { "type": "string" }
       }
     },
@@ -469,8 +466,7 @@
             "branch": { "type": "string" },
             "base": { "type": "string" },
             "pr": { "type": ["string", "null"] },
-            "status": { "$ref": "#/$defs/status" },
-            "claim": { "$ref": "#/$defs/claim" }
+            "status": { "$ref": "#/$defs/status" }
           }
         },
         {
@@ -485,8 +481,7 @@
             "purpose": { "$ref": "#/$defs/taskPurpose" },
             "handoff": { "$ref": "#/$defs/taskHandoff" },
             "review": { "$ref": "#/$defs/reviewRecord" },
-            "status": { "$ref": "#/$defs/status" },
-            "claim": { "$ref": "#/$defs/claim" }
+            "status": { "$ref": "#/$defs/status" }
           }
         }
       ]
@@ -534,30 +529,6 @@
         "sourceRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
       }
     },
-    "claim": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "claimant",
-        "agent",
-        "sessionId",
-        "startedAt",
-        "targetRevision",
-        "state"
-      ],
-      "properties": {
-        "claimant": { "type": "string", "minLength": 1 },
-        "agent": { "type": "string", "minLength": 1 },
-        "sessionId": { "type": "string", "minLength": 1 },
-        "startedAt": { "type": "string", "format": "date-time" },
-        "targetRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
-        "expiresAt": { "type": "string", "format": "date-time" },
-        "state": { "enum": ["active", "released", "finished"] },
-        "releasedAt": { "type": "string", "format": "date-time" },
-        "finishedAt": { "type": "string", "format": "date-time" },
-        "outcome": { "enum": ["done", "dropped"] }
-      }
-    },
     "repositoryData": {
       "type": "object",
       "additionalProperties": false,

package/src/cli-parser.test.ts

@@ -338,51 +338,6 @@ describe("strict CLI parsing", () => {
 			[["graph", "extra"], "agency graph"],
 			[["next", "extra"], "agency next"],
 			[["sync", "one", "two", "three"], "agency sync"],
-			[
-				[
-					"claim",
-					"one",
-					"two",
-					"three",
-					"--claimant",
-					"a",
-					"--agent",
-					"r",
-					"--session-id",
-					"s",
-					"--revision",
-					"0".repeat(64),
-				],
-				"agency claim",
-			],
-			[
-				[
-					"release",
-					"one",
-					"two",
-					"three",
-					"--session-id",
-					"s",
-					"--revision",
-					"0".repeat(64),
-				],
-				"agency release",
-			],
-			[
-				[
-					"finish",
-					"one",
-					"two",
-					"three",
-					"--session-id",
-					"s",
-					"--revision",
-					"0".repeat(64),
-					"--outcome",
-					"done",
-				],
-				"agency finish",
-			],
 		] as const) {
 			expectUsageError([...args], usage)
 		}
@@ -500,76 +455,10 @@ describe("strict CLI parsing", () => {
 		)
 	})
 
-	test("validates revision-guarded claim operations", () => {
-		const revision = "0".repeat(64)
-		expect(
-			parseCli([
-				"claim",
-				"task",
-				"phase",
-				"--claimant",
-				"orchestrator",
-				"--agent",
-				"agent",
-				"--session-id",
-				"job-1",
-				"--revision",
-				revision,
-				"--expires-at",
-				"2026-07-17T13:00:00.000Z",
-			]),
-		).toMatchObject({ commandName: "claim", args: ["task", "phase"] })
-		expect(() =>
-			parseCli(["release", "task", "--session-id", "job-1"]),
-		).toThrow("--revision' is required")
-		expect(() =>
-			parseCli([
-				"finish",
-				"task",
-				"--session-id",
-				"job-1",
-				"--revision",
-				revision,
-				"--outcome",
-				"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")
+	test("rejects removed claim protocol commands", () => {
+		for (const command of ["claim", "release", "finish"]) {
+			expect(() => parseCli([command])).toThrow(`Unknown command '${command}'`)
+		}
 		expect(() =>
 			parseCli([
 				"task",
@@ -649,6 +538,15 @@ describe("strict CLI parsing", () => {
 		expect(() => parseCli(["work", "prepare", "--opencode"])).toThrow(
 			"cannot be combined",
 		)
+		expect(() => parseCli(["work", "prepare", "first", "second"])).toThrow(
+			"Expected 0-2 positional arguments",
+		)
+		expect(() =>
+			parseCli(["work", "prepare", "example", "--task", "other"]),
+		).toThrow("Entity selector options cannot be combined")
+		expect(() => parseCli(["work", "prepare", "--phase", "build"])).toThrow(
+			"requires '--task'",
+		)
 	})
 
 	test("parses worktree lifecycle commands and selectors", () => {
@@ -977,23 +875,6 @@ describe("strict CLI parsing", () => {
 			commandName: "phase",
 			args: ["status", "ship", "release", "done"],
 		})
-		expect(
-			parseCli([
-				"claim",
-				"--task",
-				"ship",
-				"--phase",
-				"release",
-				"--claimant",
-				"agent",
-				"--agent",
-				"opencode",
-				"--session-id",
-				"session",
-				"--revision",
-				"0".repeat(64),
-			]),
-		).toMatchObject({ args: ["ship", "release"] })
 		expect(parseCli(["context", "--epic", "delivery"]).values.epic).toBe(
 			"delivery",
 		)