@markjaquith/agency 2.12.0 → 2.14.0

package/README.md

@@ -357,7 +357,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 +384,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
 
@@ -412,6 +444,7 @@ before moving files, refuses dirty worktrees, and preserves branches.
 
 ```text
 agency work [<directory> | --epic <epic-id>] [--opencode | --claude]
+agency work prepare [target] [--dry-run] [--json]
 agency pr create <task-id> [phase-id] [--draft] [--json]
 ```
 
@@ -421,6 +454,12 @@ workbase, Agency first presents the registered workbases, then the selected
 workbase's hierarchy. If `fzf` is not installed, Agency prints the available
 choices and asks for an explicit directory.
 
+`agency work prepare` resolves an execution unit and creates or reuses its
+writable and reference worktrees without launching an agent or changing status.
+Its JSON result includes document and checkout paths, resolved commits, actions,
+and Git operations. Use `--dry-run` to report planned fetch, branch, and worktree
+changes without applying them.
+
 Epic and multi-phase task targets launch orchestration agents beside their
 documents. Single-phase tasks and phases fetch repositories, create or reuse
 worktrees under `code/`, and launch an execution agent in the writable checkout

package/cli.ts

@@ -5,7 +5,7 @@ import { parseCli } from "./src/cli-parser"
 import { init, help as initHelp } from "./src/commands/init"
 import { task, help as taskHelp } from "./src/commands/task"
 import { pr, help as prHelp } from "./src/commands/pr"
-import { work, help as workHelp } from "./src/commands/work"
+import { work, workPrepare, help as workHelp } from "./src/commands/work"
 import { status, help as statusHelp } from "./src/commands/status"
 import { validate, help as validateHelp } from "./src/commands/validate"
 import { context, help as contextHelp } from "./src/commands/context"
@@ -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) {
@@ -274,10 +337,13 @@ const commands: Record<string, Command> = {
 				console.log(workHelp)
 				return
 			}
+			const preparing = args[0] === "prepare"
 			await runCommand(
-				work({
-					directory: args[0],
+				(preparing ? workPrepare : work)({
+					directory: args[preparing ? 1 : 0],
 					epicId: options.epic,
+					json: options.json,
+					dryRun: options["dry-run"],
 					silent: options.silent,
 					verbose: options.verbose,
 					opencode: options.opencode,
@@ -372,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.12.0",
+  "version": "2.14.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",
@@ -155,6 +236,22 @@ describe("strict CLI parsing", () => {
 		expectUsageError(["status", "--compact"], "agency status")
 	})
 
+	test("accepts work preparation options only for the prepare subcommand", () => {
+		expect(
+			parseCli(["work", "prepare", "tasks/example", "--dry-run", "--json"]),
+		).toMatchObject({
+			commandName: "work",
+			args: ["prepare", "tasks/example"],
+			values: { "dry-run": true, json: true },
+		})
+		expect(() => parseCli(["work", "example", "--dry-run"])).toThrow(
+			"only valid with 'agency work prepare'",
+		)
+		expect(() => parseCli(["work", "prepare", "--opencode"])).toThrow(
+			"cannot be combined",
+		)
+	})
+
 	test("accepts repeatable graph filters and rejects output conflicts", () => {
 		expect(
 			parseCli([

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,
@@ -283,18 +344,22 @@ const commands = {
 		},
 	},
 	work: {
-		usage: "agency work [<directory-or-task-id> | --epic <epic-id>]",
+		usage:
+			"agency work [<directory-or-task-id> | --epic <epic-id>] | agency work prepare [target] [--dry-run] [--json]",
 		options: {
 			...commonOptions,
+			json: { type: "boolean" },
+			"dry-run": { type: "boolean" },
 			epic: { type: "string" },
 			opencode: { type: "boolean" },
 			claude: { type: "boolean" },
 		},
 		command: {
-			usage: "agency work [<directory-or-task-id> | --epic <epic-id>]",
+			usage:
+				"agency work [<directory-or-task-id> | --epic <epic-id>] | agency work prepare [target] [--dry-run] [--json]",
 			minArgs: 0,
-			maxArgs: 1,
-			options: ["epic", "opencode", "claude"],
+			maxArgs: 2,
+			options: ["json", "dry-run", "epic", "opencode", "claude"],
 			conflicts: [
 				["opencode", "claude"],
 				["epic", "$positional"],
@@ -649,6 +714,37 @@ 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 (
+			(!preparing && commandPositionals.length > 1) ||
+			(preparing &&
+				(parsed.values.epic || parsed.values.opencode || parsed.values.claude))
+		) {
+			throw usageError(
+				preparing
+					? "Work preparation cannot be combined with agent or epic options."
+					: "The work command accepts at most one target.",
+				spec.usage,
+			)
+		}
+		if (!preparing && (parsed.values.json || parsed.values["dry-run"])) {
+			throw usageError(
+				"Options '--json' and '--dry-run' are only valid with 'agency work prepare'.",
+				spec.usage,
+			)
+		}
+	}
 
 	return {
 		commandName: commandName as keyof typeof commands,