@markjaquith/agency 2.13.0 → 2.15.0

package/README.md

@@ -11,7 +11,6 @@ or write.
 - Git
 - [GitHub CLI](https://cli.github.com/) for `agency pr create`
 - OpenCode or Claude Code for `agency work`
-- [fzf](https://github.com/junegunn/fzf) for interactive work target selection
 
 ## Installation
 
@@ -146,6 +145,29 @@ The configured command applies only to the writable checkout. Supplemental
 read-only repositories remain detached Git worktrees at their declared refs so
 they do not acquire writable branches.
 
+### Custom Chooser Command
+
+Interactive selection uses a native numbered chooser by default. To use an
+external chooser, configure an argv command in `agency.json`:
+
+```json
+{
+	"version": 2,
+	"chooserCommand": ["fzf", "--ansi", "--delimiter=\\t", "--with-nth=2.."]
+}
+```
+
+Agency writes one `key<TAB>label` record per choice to the command's stdin. The
+command must write the selected opaque key or selected record to stdout; commands
+such as `["gum", "filter"]` therefore work without wrappers. Exit codes 1 and
+130, empty stdout, native `q`, and an empty native response cancel selection.
+Other nonzero exits, unknown keys, and invalid native numbers are errors.
+
+Selectors are opened only when stdin and stderr are terminals and neither
+`--no-input` nor JSON output is active. Labels use color only when stderr is a
+terminal, `TERM` is not `dumb`, and `NO_COLOR` is unset; otherwise selectors use
+plain labels without ANSI styling or icon-font dependencies.
+
 ## Frontmatter
 
 ### Epic
@@ -357,7 +379,7 @@ Inspect tasks:
 ```text
 agency task list [--json]
 agency task show <id> [--json]
-agency task status <id> <open|working|delegated|done|dropped> [--json]
+agency task status <id> <open|done|dropped> [--json]
 ```
 
 To add a phase to an existing single-phase task, name the phase that will own
@@ -384,16 +406,48 @@ agency phase create <task-id> <phase-id>
 
 agency phase list <task-id> [--json]
 agency phase show <task-id> <phase-id> [--json]
-agency phase status <task-id> <phase-id> <open|working|delegated|done|dropped> [--json]
+agency phase status <task-id> <phase-id> <open|done|dropped> [--json]
 ```
 
 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. Use the status subcommands to mark work `delegated`, `done`,
-`dropped`, or open it again. The interactive work selector displays status
-markers before execution units. Open, working, and delegated work may transition
-to any status. Done and dropped work are terminal and may only remain unchanged
-or transition to open; reopen terminal work before changing its outcome.
+before launch. Use claims for coordinated ownership and the status subcommands
+for manual lifecycle overrides. 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 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
+runner identifies the assigned agent.
+
+### 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> --runner <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> [--json]
+```
+
+An active claim sets status to `working`. Release returns it to `open`; finish
+sets the terminal outcome. Released and finished ownership metadata remains in
+frontmatter. 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` claims an execution unit before launching its agent. Set
+`AGENCY_CLAIMANT`, `AGENCY_RUNNER`, or `AGENCY_SESSION_ID` to supply orchestrator
+identities; otherwise Agency derives them from the user, selected agent, and
+process. The launched agent receives `AGENCY_SESSION_ID` and
+`AGENCY_CLAIM_REVISION` for a later release or finish operation.
 
 ### Archive
 

package/cli.ts

@@ -32,6 +32,13 @@ 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 {
+	claimCommand,
+	claimHelp,
+	releaseHelp,
+	finishHelp,
+} from "./src/commands/claim"
 import {
 	collectCommandResult,
 	errorEnvelope,
@@ -53,6 +60,7 @@ const CliLayer = Layer.mergeAll(
 	IntegrationService.Default,
 	ContextService.Default,
 	GraphService.Default,
+	ClaimService.Default,
 )
 
 /**
@@ -99,6 +107,61 @@ const VERSION = packageJson.version
 
 // Define commands
 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,
+					runner: options.runner,
+					sessionId: options["session-id"],
+					revision: options.revision,
+					expiresAt: options["expires-at"],
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+				}),
+			)
+		},
+	},
+	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,
+				}),
+			)
+		},
+	},
+	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,
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+				}),
+			)
+		},
+	},
 	init: {
 		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) {
@@ -375,6 +438,9 @@ Commands:
   integration <command> Inspect or sync managed integration files
   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/package.json

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

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

@@ -339,6 +339,7 @@
         "base": { "type": "string" },
         "pr": { "type": ["string", "null"] },
         "status": { "$ref": "#/$defs/status" },
+        "claim": { "$ref": "#/$defs/claim" },
         "sha256": { "type": "string" }
       }
     },
@@ -372,6 +373,7 @@
         "base": { "type": "string" },
         "pr": { "type": ["string", "null"] },
         "status": { "$ref": "#/$defs/status" },
+        "claim": { "$ref": "#/$defs/claim" },
         "sha256": { "type": "string" }
       }
     },
@@ -393,7 +395,32 @@
         "branch": { "type": "string" },
         "base": { "type": "string" },
         "pr": { "type": ["string", "null"] },
-        "status": { "$ref": "#/$defs/status" }
+        "status": { "$ref": "#/$defs/status" },
+        "claim": { "$ref": "#/$defs/claim" }
+      }
+    },
+    "claim": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "claimant",
+        "runner",
+        "sessionId",
+        "startedAt",
+        "targetRevision",
+        "state"
+      ],
+      "properties": {
+        "claimant": { "type": "string", "minLength": 1 },
+        "runner": { "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": {

package/skills/agency/SKILL.md

@@ -213,7 +213,9 @@ details explicitly with `--include bodies|workspace|git|pr`. For large workbases
 - Epic frontmatter owns the child-task dependency graph.
 - `pr` is either a GitHub PR URL string or `null`.
 - Execution-unit `status` is `open`, `working`, `delegated`, `done`, or `dropped`.
-  New work starts open, and `agency work` marks it working before agent launch.
+  New work starts open, and an active claim sets it working before agent launch.
+  `delegated` is readable legacy state; distinct claimant and runner identities
+  now represent delegation.
 - Keep directory IDs stable; encode sequencing with `dependsOn`, not numeric
   directory prefixes.
 - Do not use YAML duplicate keys, anchors, aliases, or custom tags.
@@ -224,8 +226,17 @@ prose, preserve backlinks and run validation immediately afterward.
 Update execution status with:
 
 ```bash
-agency task status <task-id> <open|working|delegated|done|dropped>
-agency phase status <task-id> <phase-id> <open|working|delegated|done|dropped>
+agency task status <task-id> <open|done|dropped>
+agency phase status <task-id> <phase-id> <open|done|dropped>
+```
+
+Coordinate execution ownership with a document revision from `agency context`
+or `agency graph`:
+
+```bash
+agency claim <task-id> [phase-id] --claimant <id> --runner <id> --session-id <id> --revision <sha256>
+agency release <task-id> [phase-id] --session-id <id> --revision <sha256>
+agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped>
 ```
 
 ## Archive Completed Work

package/src/cli-parser.test.ts

@@ -141,11 +141,92 @@ describe("strict CLI parsing", () => {
 			[["validate", "one", "two"], "agency validate"],
 			[["context", "one", "two"], "agency context"],
 			[["graph", "extra"], "agency graph"],
+			[
+				[
+					"claim",
+					"one",
+					"two",
+					"three",
+					"--claimant",
+					"a",
+					"--runner",
+					"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)
 		}
 	})
 
+	test("validates revision-guarded claim operations", () => {
+		const revision = "0".repeat(64)
+		expect(
+			parseCli([
+				"claim",
+				"task",
+				"phase",
+				"--claimant",
+				"orchestrator",
+				"--runner",
+				"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'")
+	})
+
 	test("accepts context projections and keeps compact command-local", () => {
 		expect(parseCli(["context", ".", "--json", "--compact"])).toMatchObject({
 			commandName: "context",

package/src/cli-parser.ts

@@ -59,6 +59,21 @@ const phaseCreateOptions = {
 	"first-phase": { type: "string" },
 } satisfies OptionConfig
 
+const claimOptions = {
+	...outputOptions,
+	claimant: { type: "string" },
+	runner: { type: "string" },
+	"session-id": { type: "string" },
+	revision: { type: "string" },
+	"expires-at": { type: "string" },
+} satisfies OptionConfig
+
+const ownedClaimOptions = {
+	...outputOptions,
+	"session-id": { type: "string" },
+	revision: { type: "string" },
+} satisfies OptionConfig
+
 const commands = {
 	init: {
 		usage: "agency init [path] [--json]",
@@ -258,6 +273,52 @@ const commands = {
 			},
 		},
 	},
+	claim: {
+		usage: "agency claim <task-id> [phase-id] [options]",
+		options: claimOptions,
+		command: {
+			usage:
+				"agency claim <task-id> [phase-id] --claimant <id> --runner <id> --session-id <id> --revision <sha256> [--expires-at <timestamp>] [--json]",
+			minArgs: 1,
+			maxArgs: 2,
+			options: [
+				"claimant",
+				"runner",
+				"session-id",
+				"revision",
+				"expires-at",
+				"json",
+			],
+			required: ["claimant", "runner", "session-id", "revision"],
+		},
+	},
+	release: {
+		usage: "agency release <task-id> [phase-id] [options]",
+		options: ownedClaimOptions,
+		command: {
+			usage:
+				"agency release <task-id> [phase-id] --session-id <id> --revision <sha256> [--json]",
+			minArgs: 1,
+			maxArgs: 2,
+			options: ["session-id", "revision", "json"],
+			required: ["session-id", "revision"],
+		},
+	},
+	finish: {
+		usage: "agency finish <task-id> [phase-id] [options]",
+		options: {
+			...ownedClaimOptions,
+			outcome: { type: "string" },
+		},
+		command: {
+			usage:
+				"agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped> [--json]",
+			minArgs: 1,
+			maxArgs: 2,
+			options: ["session-id", "revision", "outcome", "json"],
+			required: ["session-id", "revision", "outcome"],
+		},
+	},
 	archive: {
 		usage: "agency archive <epic|task|phase>",
 		options: outputOptions,
@@ -653,6 +714,16 @@ export function parseCli(args: readonly string[]): ParsedCli {
 	if (commandName === "graph") {
 		validateGraphOptions(parsed.values, spec)
 	}
+	if (
+		commandName === "finish" &&
+		parsed.values.outcome !== "done" &&
+		parsed.values.outcome !== "dropped"
+	) {
+		throw usageError(
+			"Option '--outcome' must be 'done' or 'dropped'.",
+			spec.usage,
+		)
+	}
 	if (commandName === "work") {
 		const preparing = commandPositionals[0] === "prepare"
 		if (

package/src/cli.test.ts

@@ -81,6 +81,91 @@ describe("CLI", () => {
 		expect(taggedError.stderr).not.toContain("An error has occurred")
 	})
 
+	test("coordinates claims through revision-guarded machine commands", async () => {
+		const root = await createTempDir()
+		tempDirs.push(root)
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		await mkdir(join(root, "repos", "agency"), { recursive: true })
+		parseJson(
+			await runCli(
+				["task", "create", "claimed", "--repo", "agency", "--json"],
+				root,
+			),
+		)
+		const context = parseJson(
+			await runCli(["context", "tasks/claimed", "--json"], root),
+		)
+		const revision = context.documents.task.sha256
+		const claimed = parseJson(
+			await runCli(
+				[
+					"claim",
+					"claimed",
+					"--claimant",
+					"orchestrator",
+					"--runner",
+					"agent",
+					"--session-id",
+					"job-1",
+					"--revision",
+					revision,
+					"--json",
+				],
+				root,
+			),
+		)
+		expect(claimed.claim).toMatchObject({
+			claimant: "orchestrator",
+			runner: "agent",
+			sessionId: "job-1",
+			state: "active",
+		})
+
+		const conflict = await runCli(
+			[
+				"claim",
+				"claimed",
+				"--claimant",
+				"other",
+				"--runner",
+				"other-agent",
+				"--session-id",
+				"job-2",
+				"--revision",
+				claimed.revision,
+				"--json",
+			],
+			root,
+		)
+		expect(conflict.exitCode).toBe(1)
+		expect(JSON.parse(conflict.stdout)).toMatchObject({
+			ok: false,
+			error: {
+				code: "CLAIM_CONFLICT",
+				retryable: true,
+				fields: { claim: { runner: "agent", sessionId: "job-1" } },
+			},
+		})
+
+		const finished = parseJson(
+			await runCli(
+				[
+					"finish",
+					"claimed",
+					"--session-id",
+					"job-1",
+					"--revision",
+					claimed.revision,
+					"--outcome",
+					"done",
+					"--json",
+				],
+				root,
+			),
+		)
+		expect(finished.claim).toMatchObject({ state: "finished", outcome: "done" })
+	})
+
 	test("emits one versioned error envelope for usage and command failures", async () => {
 		const usage = await runCli(["unknown", "--json"])
 		expect(usage.exitCode).toBe(1)

package/src/commands/claim.ts

@@ -0,0 +1,97 @@
+import { Effect } from "effect"
+import { ClaimService } from "../services/ClaimService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+interface ClaimCommandOptions extends BaseCommandOptions {
+	readonly operation: "claim" | "release" | "finish"
+	readonly taskId?: string
+	readonly phaseId?: string
+	readonly claimant?: string
+	readonly runner?: string
+	readonly sessionId?: string
+	readonly revision?: string
+	readonly expiresAt?: string
+	readonly outcome?: string
+	readonly json?: boolean
+}
+
+export const claimCommand = (options: ClaimCommandOptions) =>
+	Effect.gen(function* () {
+		const claims = yield* ClaimService
+		const { log } = createLoggers(options)
+		const cwd = options.cwd ?? process.cwd()
+		if (!options.taskId || !options.sessionId || !options.revision) {
+			return yield* Effect.fail(new Error("Missing required claim arguments"))
+		}
+		if (
+			options.operation === "claim" &&
+			(!options.claimant || !options.runner)
+		) {
+			return yield* Effect.fail(
+				new Error("Claimant and runner identities are required"),
+			)
+		}
+		if (
+			options.operation === "finish" &&
+			options.outcome !== "done" &&
+			options.outcome !== "dropped"
+		) {
+			return yield* Effect.fail(
+				new Error("Finish outcome must be done or dropped"),
+			)
+		}
+
+		const common = {
+			taskId: options.taskId,
+			...(options.phaseId ? { phaseId: options.phaseId } : {}),
+			sessionId: options.sessionId,
+			revision: options.revision,
+		}
+		const result =
+			options.operation === "claim"
+				? yield* claims.claim(
+						{
+							...common,
+							claimant: options.claimant!,
+							runner: options.runner!,
+							...(options.expiresAt ? { expiresAt: options.expiresAt } : {}),
+						},
+						cwd,
+					)
+				: options.operation === "release"
+					? yield* claims.release(common, cwd)
+					: yield* claims.finish(
+							{
+								...common,
+								outcome: options.outcome as "done" | "dropped",
+							},
+							cwd,
+						)
+
+		const { data: _, ...output } = result
+		log(
+			options.json
+				? JSON.stringify(output, null, 2)
+				: `${options.operation === "claim" ? "Claimed" : options.operation === "release" ? "Released" : "Finished"} ${result.target} at revision ${result.revision}`,
+		)
+	})
+
+export const claimHelp = `
+Usage: agency claim <task-id> [phase-id] --claimant <id> --runner <id> --session-id <id> --revision <sha256>
+
+Claim an execution unit. Use distinct claimant and runner identities for delegated
+work. --expires-at accepts an optional future ISO-8601 timestamp.
+`
+
+export const releaseHelp = `
+Usage: agency release <task-id> [phase-id] --session-id <id> --revision <sha256>
+
+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>
+
+Finish an execution unit owned by the session.
+`

package/src/commands/phase.ts

@@ -125,7 +125,7 @@ Subcommands:
   list <task>           List task phases
   show <task> <phase>   Show a phase
   status <task> <phase> <status>
-                        Set open, working, delegated, done, or dropped
+                        Set open, done, or dropped
 
 Create options:
   --description <text>  Short description of the phase