@markjaquith/agency 3.2.1 → 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),
@@ -1107,13 +1072,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,
@@ -1185,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                             |
@@ -1211,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
@@ -828,6 +756,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 +885,7 @@ try {
 			durationMs: performance.now() - invocationStartedAt,
 			outcome: exitStatus === 0 ? "success" : "failure",
 			exitStatus,
+			...pushUsageDetails(),
 		},
 		VERSION,
 	)
@@ -932,6 +897,7 @@ try {
 			durationMs: performance.now() - invocationStartedAt,
 			outcome: "failure",
 			exitStatus: 1,
+			...pushUsageDetails(error),
 		},
 		VERSION,
 	)

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.1",
+  "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,