@markjaquith/agency 3.2.2 → 3.2.4

package/README.md

@@ -26,14 +26,20 @@ Agency records privacy-safe CLI usage events locally so command journeys,
 failures, and flag adoption can be analyzed. Events are stored in SQLite at
 `$XDG_STATE_HOME/agency/usage.sqlite3` (or
 `~/.local/state/agency/usage.sqlite3`) and retained for 90 days by default.
-Each event contains the normalized command path, flag names, timing, outcome,
-Agency version, and ordered `AGENCY_SESSION_ID` correlation. Raw arguments,
+Each event contains the parser-derived command and subcommand path, flag names,
+timing, a bounded outcome code, Agency version, invocation source, explicit test
+attribution, and ordered journey correlation. Journey IDs are one-way hashes of
+`AGENCY_SESSION_ID`; raw session IDs, positional arguments, entity IDs, paths,
 flag values, free-form input, and the current directory are never recorded.
 
 Export events as JSON Lines with `agency usage export`. Set
 `AGENCY_NO_USAGE_LOG=1` to opt out, `AGENCY_USAGE_RETENTION_DAYS` to change
-retention, or `AGENCY_USAGE_DB` to select a different database path. Logging is
-best effort and never changes command output or exit behavior.
+retention, or `AGENCY_USAGE_DB` to select a different database path. Expired
+events are pruned on every read and write. Set `AGENCY_INVOCATION_SOURCE` to one
+of `human`, `agent`, or `automation`, and set `AGENCY_USAGE_TEST=1` for explicit
+test attribution. Logging is best effort and never changes command output or
+exit behavior. Databases created by versions before this privacy boundary are
+cleared because their command paths may contain positional values.
 
 ## Core Model
 
@@ -336,19 +342,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 +629,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 +644,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 +840,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 +930,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 +952,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 +982,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 +1017,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 +1036,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 +1164,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 +1187,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,19 +51,17 @@ 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,
 	successEnvelope,
 	writeEnvelope,
 } from "./src/protocol"
-import { exportUsageEvents, recordUsageEvent } from "./src/usage-log"
+import {
+	exportUsageEvents,
+	recordUsageEvent,
+	usageOutcomeCode,
+} from "./src/usage-log"
 
 // Create CLI layer with all services
 const CliLayer = Layer.mergeAll(
@@ -83,7 +80,6 @@ const CliLayer = Layer.mergeAll(
 	IntegrationService.Default,
 	ContextService.Default,
 	GraphService.Default,
-	ClaimService.Default,
 	SyncService.Default,
 	ReadinessService.Default,
 	GraphMutationService.Default,
@@ -199,67 +195,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 +714,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
@@ -824,9 +756,7 @@ const machineMode = process.argv
 const invocationStartedAt = performance.now()
 const rawArguments = process.argv.slice(2)
 let usageCommandPath = "invalid"
-let usageFlagNames = rawArguments
-	.filter((argument) => argument.startsWith("--"))
-	.map((argument) => argument.slice(2).split("=", 1)[0]!)
+let usageFlagNames: string[] = []
 
 const pushUsageDetails = (error?: unknown) => {
 	if (usageCommandPath !== "push") return {}
@@ -867,17 +797,12 @@ const pushUsageDetails = (error?: unknown) => {
 try {
 	const {
 		commandName,
+		commandPath,
 		args: commandArgs,
 		passthrough,
 		values,
 	} = parseCli(rawArguments)
-	usageCommandPath =
-		[commandName, commandArgs[0]]
-			.filter(
-				(part): part is string =>
-					typeof part === "string" && part.length > 0 && !part.startsWith("-"),
-			)
-			.join("/") || "root"
+	usageCommandPath = commandPath
 	usageFlagNames = Object.entries(values)
 		.filter(([, value]) => value !== undefined && value !== false)
 		.map(([name]) => name)
@@ -895,6 +820,7 @@ try {
 				flagNames: usageFlagNames,
 				durationMs: performance.now() - invocationStartedAt,
 				outcome: "success",
+				outcomeCode: "SUCCESS",
 				exitStatus: 0,
 			},
 			VERSION,
@@ -913,6 +839,7 @@ try {
 				flagNames: usageFlagNames,
 				durationMs: performance.now() - invocationStartedAt,
 				outcome: exitStatus === 0 ? "success" : "failure",
+				outcomeCode: exitStatus === 0 ? "SUCCESS" : "NONZERO_EXIT",
 				exitStatus,
 			},
 			VERSION,
@@ -956,18 +883,28 @@ try {
 			flagNames: usageFlagNames,
 			durationMs: performance.now() - invocationStartedAt,
 			outcome: exitStatus === 0 ? "success" : "failure",
+			outcomeCode: exitStatus === 0 ? "SUCCESS" : "NONZERO_EXIT",
 			exitStatus,
 			...pushUsageDetails(),
 		},
 		VERSION,
 	)
 } catch (error) {
+	if (
+		typeof error === "object" &&
+		error !== null &&
+		"commandPath" in error &&
+		typeof error.commandPath === "string"
+	) {
+		usageCommandPath = error.commandPath
+	}
 	await recordUsageEvent(
 		{
 			commandPath: usageCommandPath,
 			flagNames: usageFlagNames,
 			durationMs: performance.now() - invocationStartedAt,
 			outcome: "failure",
+			outcomeCode: usageOutcomeCode(error),
 			exitStatus: 1,
 			...pushUsageDetails(error),
 		},

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.4",
   "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,