@markjaquith/agency 3.1.0 → 3.1.1

package/README.md

@@ -66,7 +66,7 @@ workbase/
   .agency/
     AGENTS.md              # managed Agency instructions
   .opencode/
-    opencode.jsonc         # managed @agency subagent, instructions, and reference
+    opencode.jsonc         # managed planning agent, instructions, and reference
     tui.jsonc              # managed TUI plugin registration
     plugins/agency-repository-skills.ts # managed workbase access and checkout skills
     tui/agency-debug.ts    # managed /agency-debug TUI diagnostic
@@ -116,17 +116,14 @@ Agency-managed root `AGENTS.md` to `.agency/AGENTS.md` once the OpenCode config
 can load the hidden file. A customized root file, including a symlink, is
 preserved as user-owned content.
 
-The OpenCode config defines an `@agency` subagent for delegated workbase
-orchestration, loads Agency's hidden instructions in addition to any user-owned
-root `AGENTS.md`, advertises the complete workbase as one portable reference,
-and replaces the built-in Plan agent with `agency-plan`. That planning agent can
-update `TASK.md`, `PHASE.md`, and `EPIC.md`, inspect the workbase through
-read-only Agency commands, and use explicit Agency CLI permissions to create or
-update planning structure. Its normal research tools and the complete Agency CLI
-remain available; managed Agency instructions and reported authority govern each
-operation.
-When the subagent launches work in another agent, it verifies that the agent
-started and returns without waiting for the task to finish.
+The OpenCode config loads Agency's hidden instructions in addition to any
+user-owned root `AGENTS.md`, advertises the complete workbase as one portable
+reference, and replaces the built-in Plan agent with `agency-plan`. That
+planning agent can update `TASK.md`, `PHASE.md`, and `EPIC.md`, inspect the
+workbase through read-only Agency commands, and use explicit Agency CLI
+permissions to create or update planning structure. Its normal research tools
+and the complete Agency CLI remain available; managed Agency instructions and
+reported authority govern each operation.
 The TUI-only `/agency-debug` command reports TUI companion initialization and
 whether the server plugin registered writable-checkout skills. It uses a native
 toast and does not submit a prompt to an LLM. When no writable checkout skill

package/cli-main.ts

@@ -618,6 +618,7 @@ const commands: Record<string, Command> = {
 					subcommand: args[0],
 					args: args.slice(1),
 					dryRun: options["dry-run"],
+					force: options.force,
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,

package/package.json

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

package/src/cli-parser.test.ts

@@ -664,11 +664,17 @@ describe("strict CLI parsing", () => {
 				"--phase",
 				"verify",
 				"--dry-run",
+				"--force",
 			]),
 		).toMatchObject({
 			commandName: "worktree",
 			args: ["rebuild", "example", "verify"],
-			values: { task: "example", phase: "verify", "dry-run": true },
+			values: {
+				task: "example",
+				phase: "verify",
+				"dry-run": true,
+				force: true,
+			},
 		})
 		expectUsageError(
 			["worktree", "inspect", "example", "--dry-run"],

package/src/cli-parser.ts

@@ -870,6 +870,7 @@ const commands = {
 			...outputOptions,
 			...entitySelectorOptions,
 			"dry-run": { type: "boolean" },
+			force: { type: "boolean" },
 		},
 		subcommands: {
 			list: {
@@ -886,31 +887,31 @@ const commands = {
 			},
 			prepare: {
 				usage:
-					"agency worktree prepare <task-id> [phase-id] [--dry-run] [--json]",
+					"agency worktree prepare <task-id> [phase-id] [--dry-run] [--force] [--json]",
 				minArgs: 1,
 				maxArgs: 2,
-				options: ["dry-run", "json", "task", "phase"],
+				options: ["dry-run", "force", "json", "task", "phase"],
 			},
 			remove: {
 				usage:
-					"agency worktree remove <task-id> [phase-id] [--dry-run] [--json]",
+					"agency worktree remove <task-id> [phase-id] [--dry-run] [--force] [--json]",
 				minArgs: 1,
 				maxArgs: 2,
-				options: ["dry-run", "json", "task", "phase"],
+				options: ["dry-run", "force", "json", "task", "phase"],
 			},
 			rebuild: {
 				usage:
-					"agency worktree rebuild <task-id> [phase-id] [--dry-run] [--json]",
+					"agency worktree rebuild <task-id> [phase-id] [--dry-run] [--force] [--json]",
 				minArgs: 1,
 				maxArgs: 2,
-				options: ["dry-run", "json", "task", "phase"],
+				options: ["dry-run", "force", "json", "task", "phase"],
 			},
 			repair: {
 				usage:
-					"agency worktree repair <task-id> [phase-id] [--dry-run] [--json]",
+					"agency worktree repair <task-id> [phase-id] [--dry-run] [--force] [--json]",
 				minArgs: 1,
 				maxArgs: 2,
-				options: ["dry-run", "json", "task", "phase"],
+				options: ["dry-run", "force", "json", "task", "phase"],
 			},
 		},
 	},

package/src/cli.test.ts

@@ -1373,12 +1373,7 @@ status: open
 				}
 				if (launch === launches[0]) {
 					expect(effectiveConfig.instructions).toContain(".agency/AGENTS.md")
-					expect(effectiveConfig.agent.agency).toMatchObject({
-						description: expect.stringContaining(
-							"Agency workbase orchestration",
-						),
-						mode: "subagent",
-					})
+					expect(effectiveConfig.agent.agency).toBeUndefined()
 					expect(effectiveConfig.references).toEqual({
 						workbase: {
 							path: "..",
@@ -1386,18 +1381,6 @@ status: open
 								"Complete Agency workbase context; write authority still comes only from agency context",
 						},
 					})
-					const agencyProbe = Bun.spawnSync(
-						["opencode", "debug", "agent", "agency"],
-						{ cwd: contract.cwd, env: environment },
-					)
-					expect(agencyProbe.exitCode).toBe(0)
-					expect(JSON.parse(agencyProbe.stdout.toString())).toMatchObject({
-						name: "agency",
-						description: expect.stringContaining(
-							"Agency workbase orchestration",
-						),
-						mode: "subagent",
-					})
 					for (const document of documents) {
 						const read = Bun.spawnSync(
 							[

package/src/commands/init.test.ts

@@ -45,11 +45,7 @@ describe("init command", () => {
 		).text()
 		const config = JSON.parse(opencode.slice(opencode.indexOf("\n\n") + 2))
 		expect(config.instructions).toEqual([".agency/AGENTS.md"])
-		expect(config.agent.agency).toMatchObject({
-			description: expect.stringContaining("Agency workbase orchestration"),
-			mode: "subagent",
-			prompt: expect.stringContaining("agency context . --json"),
-		})
+		expect(config.agent.agency).toBeUndefined()
 		expect(config.agent.plan).toEqual({ disable: true })
 		expect(config.agent["agency-plan"]).toMatchObject({
 			mode: "primary",

package/src/commands/worktree.ts

@@ -6,6 +6,7 @@ import { WorktreeService } from "../services/WorktreeService"
 interface WorktreeOptions extends BaseCommandOptions {
 	readonly subcommand?: string
 	readonly args?: readonly string[]
+	readonly force?: boolean
 }
 
 const targetLabel = (owner: {
@@ -134,5 +135,6 @@ Options:
   --task <id>          Select a task without positional IDs
   --phase <id>         Select a phase with --task
   --dry-run            Preflight and report changes without applying them
+  --force              Override an existing worktree operation lock
   --json               Print structured output
 `

package/src/services/IntegrationService.test.ts

@@ -186,9 +186,12 @@ describe("IntegrationService", () => {
 		}
 		expect(managedWorkbaseAgents).toContain("agency push --json")
 		expect(managedWorkbaseAgents).toContain("agency-execution-v1")
-		expect(managedWorkbaseAgents).toContain("agency context . --full --json")
+		expect(managedWorkbaseAgents).toContain("agency context . --json")
 		expect(managedWorkbaseAgents).toContain(
-			"Workers use full context here because they need the assigned document prose",
+			"Pass `--full` only when document prose or low-level VCS details are needed",
+		)
+		expect(managedWorkbaseAgents).not.toContain(
+			"agency context . --full --json",
 		)
 		expect(managedWorkbaseAgents).toContain(
 			"Never pass `--work` or `--auto` to `agency task create`",
@@ -681,19 +684,11 @@ describe("IntegrationService", () => {
 		)
 	})
 
-	test("configures Agency agents with complete workbase access", () => {
+	test("configures Agency planning with complete workbase access", () => {
 		const config = JSON.parse(managedBody(managedWorkbaseOpencode))
 
 		expect(config.instructions).toEqual([".agency/AGENTS.md"])
 		expect(config.agent).toEqual({
-			agency: {
-				description:
-					"Handles Agency workbase orchestration and workflow operations with the Agency CLI",
-				mode: "subagent",
-				prompt: expect.stringMatching(
-					/agency context \. --json[\s\S]+agency work prepare[\s\S]+never pass `--work` or `--auto`/,
-				),
-			},
 			plan: {
 				disable: true,
 			},
@@ -716,19 +711,16 @@ describe("IntegrationService", () => {
 				},
 			},
 		})
-		expect(config.agent.agency.model).toBeUndefined()
-		expect(config.agent.agency.permission).toBeUndefined()
 		expect(config.agent["agency-plan"].prompt).toContain(
 			"Explicit-new intent overrides reuse",
 		)
-		expect(config.agent.agency.hidden).toBeUndefined()
-		expect(config.agent.agency.steps).toBeUndefined()
-		expect(config.agent.agency.prompt).toContain(
-			"Return the prepared execution contract to the caller",
-		)
+		expect(config.agent.agency).toBeUndefined()
 		expect(config.agent["agency-plan"].prompt).toContain(
 			"Start with `agency context . --json`",
 		)
+		expect(config.agent["agency-plan"].prompt).toContain(
+			"Pass `--full` only when document prose or low-level VCS details are needed",
+		)
 		expect(config.agent["agency-plan"].prompt).toContain(
 			"decompose it into independently deliverable tasks",
 		)

package/src/services/WorktreeLock.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
-import { mkdtemp, readdir, rm } from "node:fs/promises"
+import { mkdtemp, readdir, rm, utimes } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { withWorktreeLocks } from "./WorktreeLock"
@@ -54,11 +54,90 @@ describe("withWorktreeLocks", () => {
 			_tag: "Left",
 			left: {
 				_tag: "WorktreeLockError",
-				message: `Another worktree operation is in progress for 'alpha'. If no operation is active, remove the stale sentinel with: rm '${lockPath}'`,
+				message: `Another worktree operation is in progress for 'alpha'. Retry with --force or remove the stale sentinel with: rm '${lockPath}'`,
 			},
 		})
 	})
 
+	test("removes stale locks before acquiring them", async () => {
+		const root = await createTempDir()
+		tempDirs.push(root)
+		const lockPath = join(
+			root,
+			`.agency-worktree-${Buffer.from("alpha:task").toString("hex")}.lock`,
+		)
+		await Bun.write(lockPath, "")
+		const staleAt = new Date(Date.now() - 11 * 60 * 1000)
+		await utimes(lockPath, staleAt, staleAt)
+
+		await expect(
+			Effect.runPromise(
+				withWorktreeLocks(root, [{ taskId: "alpha" }], Effect.void),
+			),
+		).resolves.toBeUndefined()
+	})
+
+	test("force overrides an active lock", async () => {
+		const root = await createTempDir()
+		tempDirs.push(root)
+		let firstEntered!: () => void
+		let firstRelease!: () => void
+		const firstEnteredPromise = new Promise<void>((resolve) => {
+			firstEntered = resolve
+		})
+		const firstReleasePromise = new Promise<void>((resolve) => {
+			firstRelease = resolve
+		})
+		const first = Effect.runPromise(
+			withWorktreeLocks(
+				root,
+				[{ taskId: "alpha" }],
+				Effect.promise(async () => {
+					firstEntered()
+					await firstReleasePromise
+				}),
+			),
+		)
+		await firstEnteredPromise
+
+		let forcedEntered!: () => void
+		let forcedRelease!: () => void
+		const forcedEnteredPromise = new Promise<void>((resolve) => {
+			forcedEntered = resolve
+		})
+		const forcedReleasePromise = new Promise<void>((resolve) => {
+			forcedRelease = resolve
+		})
+		const forced = Effect.runPromise(
+			withWorktreeLocks(
+				root,
+				[{ taskId: "alpha" }],
+				Effect.promise(async () => {
+					forcedEntered()
+					await forcedReleasePromise
+				}),
+				{ force: true },
+			),
+		)
+		await forcedEnteredPromise
+
+		firstRelease()
+		await first
+
+		const conflict = await Effect.runPromise(
+			Effect.either(
+				withWorktreeLocks(root, [{ taskId: "alpha" }], Effect.void),
+			),
+		)
+		expect(conflict).toMatchObject({
+			_tag: "Left",
+			left: { _tag: "WorktreeLockError" },
+		})
+
+		forcedRelease()
+		await forced
+	})
+
 	test("releases locks when the protected operation fails", async () => {
 		const root = await createTempDir()
 		tempDirs.push(root)

package/src/services/WorktreeLock.ts

@@ -1,5 +1,5 @@
 import { Data, Effect } from "effect"
-import { open, rm } from "node:fs/promises"
+import { open, rm, stat } from "node:fs/promises"
 import { join } from "node:path"
 
 class WorktreeLockError extends Data.TaggedError("WorktreeLockError")<{
@@ -12,10 +12,23 @@ export interface WorktreeLockTarget {
 	readonly phaseId?: string
 }
 
+export interface WorktreeLockOptions {
+	readonly force?: boolean
+}
+
+const lockTimeoutMs = 10 * 60 * 1000
+
+const isErrorCode = (cause: unknown, code: string) =>
+	typeof cause === "object" &&
+	cause !== null &&
+	"code" in cause &&
+	cause.code === code
+
 const withWorktreeLock = <A, E, R>(
 	root: string,
 	target: WorktreeLockTarget,
 	effect: Effect.Effect<A, E, R>,
+	options: WorktreeLockOptions,
 ): Effect.Effect<A, E | WorktreeLockError, R> => {
 	const key = Buffer.from(
 		`${target.taskId}:${target.phaseId ?? "task"}`,
@@ -24,18 +37,41 @@ const withWorktreeLock = <A, E, R>(
 	const removalCommand = `rm '${lockPath.replaceAll("'", `'\\''`)}'`
 	return Effect.acquireUseRelease(
 		Effect.tryPromise({
-			try: () => open(lockPath, "wx"),
+			try: async () => {
+				try {
+					return await open(lockPath, "wx")
+				} catch (cause) {
+					if (!isErrorCode(cause, "EEXIST")) throw cause
+					let stale = false
+					try {
+						stale = Date.now() - (await stat(lockPath)).mtimeMs >= lockTimeoutMs
+					} catch (statCause) {
+						if (!isErrorCode(statCause, "ENOENT")) throw statCause
+					}
+					if (!options.force && !stale) throw cause
+					await rm(lockPath, { force: true })
+					return open(lockPath, "wx")
+				}
+			},
 			catch: (cause) =>
 				new WorktreeLockError({
-					message: `Another worktree operation is in progress for '${target.taskId}${target.phaseId ? `/${target.phaseId}` : ""}'. If no operation is active, remove the stale sentinel with: ${removalCommand}`,
+					message: `Another worktree operation is in progress for '${target.taskId}${target.phaseId ? `/${target.phaseId}` : ""}'. Retry with --force or remove the stale sentinel with: ${removalCommand}`,
 					cause,
 				}),
 		}),
 		() => effect,
 		(lock) =>
 			Effect.promise(async () => {
+				let ownsLock = false
+				try {
+					const [held, current] = await Promise.all([
+						lock.stat(),
+						stat(lockPath),
+					])
+					ownsLock = held.dev === current.dev && held.ino === current.ino
+				} catch {}
 				await lock.close().catch(() => undefined)
-				await rm(lockPath, { force: true }).catch(() => undefined)
+				if (ownsLock) await rm(lockPath, { force: true }).catch(() => undefined)
 			}),
 	)
 }
@@ -44,6 +80,7 @@ export const withWorktreeLocks = <A, E, R>(
 	root: string,
 	targets: readonly WorktreeLockTarget[],
 	effect: Effect.Effect<A, E, R>,
+	options: WorktreeLockOptions = {},
 ): Effect.Effect<A, E | WorktreeLockError, R> => {
 	const unique = new Map(
 		targets.map((target) => [
@@ -55,7 +92,7 @@ export const withWorktreeLocks = <A, E, R>(
 	for (const [, target] of [...unique.entries()]
 		.sort(([left], [right]) => left.localeCompare(right))
 		.reverse()) {
-		current = withWorktreeLock(root, target, current)
+		current = withWorktreeLock(root, target, current, options)
 	}
 	return current
 }

package/src/services/WorktreeService.ts

@@ -259,6 +259,7 @@ interface MaterializeOptions extends BaseCommandOptions {
 }
 
 interface RemoveOptions extends BaseCommandOptions {
+	readonly force?: boolean
 	readonly snapshots?: WorktreeRemovalSnapshot[]
 	readonly lockHeld?: boolean
 	readonly allowReferenceDrift?: boolean
@@ -267,6 +268,7 @@ interface RemoveOptions extends BaseCommandOptions {
 }
 
 interface LifecycleOptions extends BaseCommandOptions {
+	readonly force?: boolean
 	readonly lockHeld?: boolean
 }
 
@@ -1825,6 +1827,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								root,
 								[{ taskId, ...(phaseId ? { phaseId } : {}) }],
 								materialization,
+								{ force: options.force },
 							)
 				}),
 
@@ -2148,6 +2151,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								root,
 								[{ taskId, ...(phaseId ? { phaseId } : {}) }],
 								removal,
+								{ force: options.force },
 							)
 				}),
 
@@ -2170,6 +2174,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								...options,
 								lockHeld: true,
 							}),
+							{ force: options.force },
 						)
 					}
 					const inspection = yield* inspectExecution(taskId, phaseId, root)
@@ -2316,6 +2321,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								...options,
 								lockHeld: true,
 							}),
+							{ force: options.force },
 						)
 					}
 					const inspection = yield* inspectExecution(taskId, phaseId, root)

package/src/workbase/AGENTS.md

@@ -79,10 +79,10 @@ commands without prescribing an execution environment.
 Start every session with one read-only command:
 
 ```bash
-agency context . --full --json
+agency context . --json
 ```
 
-Workers use full context here because they need the assigned document prose. Use
+Pass `--full` only when document prose or low-level VCS details are needed. Use
 the returned target, document paths and revisions, dependency readiness,
 authority, checkout state, PR state, and validation result. Do not infer these
 from directory names or stale prose.

package/src/workbase/opencode-file.ts

@@ -8,7 +8,7 @@ const checksum = (content: string) =>
 
 const agencyPlanPrompt = `You are in Agency Plan mode. Think, read, search, and delegate exploration to construct a well-formed plan for the user's goal. Keep the plan comprehensive but concise, and ask clarifying questions when important tradeoffs or intent are unclear.
 
-Start with \`agency context . --json\`. Use its document paths and revisions, then inspect the graph, related epics, tasks, phases, linked tickets, and repository declarations needed to understand the work. Use machine-readable Agency output when available instead of inferring structure from directory names.
+Start with \`agency context . --json\`. Pass \`--full\` only when document prose or low-level VCS details are needed. Use its document paths and revisions, then inspect the graph, related epics, tasks, phases, linked tickets, and repository declarations needed to understand the work. Use machine-readable Agency output when available instead of inferring structure from directory names.
 
 When planning an epic, decompose it into independently deliverable tasks with explicit dependencies. Add phases only when one task genuinely requires multiple ordered delivery units. Reuse or update existing work instead of creating duplicate tasks or phases, except when the user explicitly requests a new, separate, or follow-up item. Explicit-new intent overrides reuse of active and archived work even when the subject or suggested ID matches.
 
@@ -20,24 +20,12 @@ const agencyPlanBashPermissions = {
 	"agency *": "allow",
 }
 
-const agencyAgentPrompt = `You are the Agency workflow specialist. Use the Agency CLI to handle delegated workbase orchestration and workflow operations. Always start with \`agency context . --json\` and follow the managed Agency instructions and reported authority.
-
-When the intent and parameters are known, use the matching managed Command Fast Path exactly. The recipes cover creation, preparation, synchronization, phase conversion, archiving, review work, inspection, dropping, continuation, publication, pull requests, non-PR completion, multi-phase setup, investigation handoff, and review refresh. Preparation recipes call \`agency work prepare <task-or-document> --json\`. Do not probe help or list unrelated state, never pass \`--work\` or \`--auto\` to \`agency task create\`, and use \`--dry-run\` only where the recipe or caller requests it. Use CLI discovery only when no fast-path recipe matches or a prescribed command rejects known-current syntax.
-
-Return the prepared execution contract to the caller. Agency owns the target, validation, materialized workspace facts, and native commands; the caller owns presentation and process orchestration.`
-
 const body = () =>
 	`${JSON.stringify(
 		{
 			$schema: "https://opencode.ai/config.json",
 			instructions: [".agency/AGENTS.md"],
 			agent: {
-				agency: {
-					description:
-						"Handles Agency workbase orchestration and workflow operations with the Agency CLI",
-					mode: "subagent",
-					prompt: agencyAgentPrompt,
-				},
 				plan: {
 					disable: true,
 				},