@markjaquith/agency 3.0.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
@@ -995,12 +992,17 @@ agency archive epic <epic-id> [--dry-run] [--json]
 agency archive task <task-id> [--dry-run] [--json]
 agency archive tasks [--dry-run] [--json]
 agency archive phase <task-id> <phase-id> [--dry-run] [--json]
+agency archive <path> [--dry-run] [--json]
 agency restore epic <epic-id> [--dry-run] [--json]
 agency restore task <task-id> [--dry-run] [--json]
 agency restore phase <task-id> <phase-id> [--dry-run] [--json]
 ```
 
-Archived work keeps its hierarchy under `archive/`. Epic archiving includes its
+An existing path within an active epic or task infers that work item, so
+`agency archive .` works from its directory. Collection roots are ambiguous,
+phase paths require the explicit `archive phase` form, and paths outside active
+epic or task trees are rejected. Archived work keeps its hierarchy under
+`archive/`. Epic archiving includes its
 listed tasks. A task can be archived only when its effective status is terminal
 (`done` or `dropped`). Multi-phase task status is derived from its phases, every
 phase must be terminal, and a task with no phases is not eligible.

package/cli-main.ts

@@ -396,10 +396,18 @@ const commands: Record<string, Command> = {
 				console.log(archiveHelp)
 				return
 			}
+			const explicitType = [
+				"list",
+				"show",
+				"epic",
+				"task",
+				"tasks",
+				"phase",
+			].includes(args[0] ?? "")
 			await runCommand(
 				archive({
-					type: args[0],
-					args: args.slice(1),
+					type: explicitType ? args[0] : undefined,
+					args: explicitType ? args.slice(1) : args,
 					json: options.json,
 					dryRun: options["dry-run"],
 					kinds: options.kind,
@@ -610,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.0.0",
+  "version": "3.1.1",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

package/src/cli-parser.test.ts

@@ -478,6 +478,11 @@ describe("strict CLI parsing", () => {
 	})
 
 	test("accepts archive dry-run", () => {
+		expect(parseCli(["archive", ".", "--dry-run"])).toMatchObject({
+			commandName: "archive",
+			args: ["."],
+			values: { "dry-run": true },
+		})
 		expect(parseCli(["archive", "task", "example", "--dry-run"])).toMatchObject(
 			{
 				commandName: "archive",
@@ -659,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

@@ -763,7 +763,7 @@ const commands = {
 		},
 	},
 	archive: {
-		usage: "agency archive <list|show|epic|task|tasks|phase>",
+		usage: "agency archive <path|list|show|epic|task|tasks|phase>",
 		options: {
 			...outputOptions,
 			...entitySelectorOptions,
@@ -772,6 +772,12 @@ const commands = {
 			status: { type: "string", multiple: true },
 			repository: { type: "string", multiple: true },
 		},
+		command: {
+			usage: "agency archive <path> [--dry-run] [--json]",
+			minArgs: 1,
+			maxArgs: 1,
+			options: ["dry-run", "json"],
+		},
 		subcommands: {
 			list: {
 				usage:
@@ -864,6 +870,7 @@ const commands = {
 			...outputOptions,
 			...entitySelectorOptions,
 			"dry-run": { type: "boolean" },
+			force: { type: "boolean" },
 		},
 		subcommands: {
 			list: {
@@ -880,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"],
 			},
 		},
 	},
@@ -1474,9 +1481,8 @@ export function parseCli(args: readonly string[]): ParsedCli {
 			values: parsed.values,
 		}
 	}
-	const spec = definition.subcommands
-		? definition.subcommands[subcommand ?? ""]
-		: definition.command
+	const selectedSubcommand = definition.subcommands?.[subcommand ?? ""]
+	const spec = selectedSubcommand ?? definition.command
 	if (!spec) {
 		const message = subcommand
 			? `Unknown subcommand '${subcommand}' for 'agency ${commandName}'.`
@@ -1484,7 +1490,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 		throw usageError(message, definition.usage)
 	}
 
-	let commandPositionals = definition.subcommands
+	let commandPositionals = selectedSubcommand
 		? parsed.positionals.slice(1)
 		: parsed.positionals
 	const allowed = new Set([...commonOptionNames, ...(spec.options ?? [])])
@@ -1535,7 +1541,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 
 	commandPositionals = applyEntitySelectors(
 		commandName,
-		subcommand,
+		selectedSubcommand ? subcommand : undefined,
 		commandPositionals,
 		parsed.values,
 		spec,
@@ -1708,7 +1714,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 
 	return {
 		commandName: commandName as keyof typeof commands,
-		args: definition.subcommands
+		args: selectedSubcommand
 			? [subcommand!, ...commandPositionals]
 			: commandPositionals,
 		values: parsed.values,

package/src/cli.test.ts

@@ -531,9 +531,9 @@ status: dropped
 `,
 		)
 
-		expect((await runCli(["archive", "task", "example"], root)).exitCode).toBe(
-			0,
-		)
+		expect(
+			(await runCli(["archive", "."], join(root, "tasks/example"))).exitCode,
+		).toBe(0)
 		const result = await runCli(["archive", "task", "example", "--json"], root)
 
 		expect(result.exitCode).toBe(1)
@@ -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/archive.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdir } from "node:fs/promises"
 import { join } from "node:path"
 import {
 	captureLogs,
@@ -93,6 +94,75 @@ describe("archive command", () => {
 		)
 	})
 
+	test("infers a task from a filesystem path", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				archive({
+					args: ["."],
+					cwd: join(root, "tasks/example"),
+					dryRun: true,
+					json: true,
+				}),
+			),
+		)
+
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			operation: "archive",
+			kind: "task",
+			id: "example",
+			dryRun: true,
+		})
+	})
+
+	test("infers an epic from a filesystem path", async () => {
+		const directory = join(root, "epics/delivery")
+		await mkdir(directory, { recursive: true })
+		await Bun.write(
+			join(directory, "EPIC.md"),
+			`---
+ticketUrl: https://example.com/epic
+repos:
+  - repo: agency
+    ref: main
+tasks: []
+---
+
+# Delivery
+`,
+		)
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				archive({ args: ["."], cwd: directory, dryRun: true, json: true }),
+			),
+		)
+
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			operation: "archive",
+			kind: "epic",
+			id: "delivery",
+			dryRun: true,
+		})
+	})
+
+	test("rejects ambiguous and unsupported archive paths", async () => {
+		await expect(
+			runTestEffect(archive({ args: ["."], cwd: root, silent: true })),
+		).rejects.toThrow("Archive path is ambiguous")
+		await expect(
+			runTestEffect(
+				archive({ args: ["repos/agency"], cwd: root, silent: true }),
+			),
+		).rejects.toThrow("Archive path must be within an active epic or task")
+
+		const phaseDirectory = join(root, "tasks/example/phases/build")
+		await mkdir(phaseDirectory, { recursive: true })
+		await expect(
+			runTestEffect(
+				archive({ args: ["."], cwd: phaseDirectory, silent: true }),
+			),
+		).rejects.toThrow("Archive path identifies a phase")
+	})
+
 	test("reports an already archived task", async () => {
 		await runTestEffect(
 			archive({ type: "task", args: ["example"], cwd: root, silent: true }),
@@ -143,7 +213,9 @@ describe("archive command", () => {
 	test("requires a supported work item type", async () => {
 		await expect(
 			runTestEffect(archive({ args: [], cwd: root, silent: true })),
-		).rejects.toThrow("Available: list, show, epic, task, tasks, phase")
+		).rejects.toThrow(
+			"Provide a path or use: list, show, epic, task, tasks, phase",
+		)
 	})
 
 	test("rejects an extra archive show identifier", async () => {

package/src/commands/archive.ts

@@ -24,6 +24,14 @@ export const archive = (options: ArchiveOptions) =>
 		const { log } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
 		const [id, phaseId] = options.args
+		let archiveType = options.type
+		let archiveId = id
+
+		if (!archiveType && id) {
+			const target = yield* archives.resolvePathTarget(id, cwd)
+			archiveType = target.kind
+			archiveId = target.id
+		}
 
 		if (options.type === "list") {
 			const records = yield* archives.list(
@@ -73,22 +81,22 @@ export const archive = (options: ArchiveOptions) =>
 		}
 
 		let result
-		switch (options.type) {
+		switch (archiveType) {
 			case "epic":
-				if (!id)
+				if (!archiveId)
 					return yield* Effect.fail(
 						new Error("Usage: agency archive epic <epic-id>"),
 					)
-				result = yield* archives.archiveEpic(id, cwd, {
+				result = yield* archives.archiveEpic(archiveId, cwd, {
 					dryRun: options.dryRun,
 				})
 				break
 			case "task":
-				if (!id)
+				if (!archiveId)
 					return yield* Effect.fail(
 						new Error("Usage: agency archive task <task-id>"),
 					)
-				result = yield* archives.archiveTask(id, cwd, {
+				result = yield* archives.archiveTask(archiveId, cwd, {
 					dryRun: options.dryRun,
 				})
 				break
@@ -109,7 +117,7 @@ export const archive = (options: ArchiveOptions) =>
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Archive operation is required. Available: list, show, epic, task, tasks, phase",
+						"Archive target is required. Provide a path or use: list, show, epic, task, tasks, phase",
 					),
 				)
 		}
@@ -141,11 +149,14 @@ export const archive = (options: ArchiveOptions) =>
 	})
 
 export const help = `
-Usage: agency archive <list|show|epic|task|tasks|phase>
+Usage: agency archive <path|list|show|epic|task|tasks|phase>
 
 Browse or archive work items after preflighting worktrees and graph references.
 
+An existing path within an active epic or task infers that work item.
+
 Commands:
+  <path>                                 Archive the containing epic or task
   list [filters]                         List archived work
   show <type> <id>                       Show an archived epic or task
   show phase <task-id> <phase-id>        Show an archived phase

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/ArchiveService.ts

@@ -1,7 +1,7 @@
 import { Schema, TreeFormatter } from "@effect/schema"
 import { Data, Effect, Either, Layer } from "effect"
 import { lstat, mkdir, open, rename, rm } from "node:fs/promises"
-import { dirname, join, relative } from "node:path"
+import { dirname, join, relative, resolve, sep } from "node:path"
 import { EpicService, type EpicRecord } from "./EpicService"
 import { FileSystemService } from "./FileSystemService"
 import { PhaseService, type PhaseRecord } from "./PhaseService"
@@ -52,6 +52,11 @@ class ArchiveError extends Data.TaggedError("ArchiveError")<{
 
 export type ArchiveKind = "epic" | "task" | "phase"
 
+interface ArchivePathTarget {
+	readonly kind: "epic" | "task"
+	readonly id: string
+}
+
 const LifecycleEventSchema = Schema.Struct({
 	operation: Schema.Literal("archive", "restore"),
 	at: Schema.String,
@@ -478,6 +483,59 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 	"ArchiveService",
 	{
 		sync: () => ({
+			resolvePathTarget: (path: string, cwd: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const workbase = yield* WorkbaseService
+					const candidate = resolve(cwd, path)
+					if (!(yield* fs.exists(candidate))) {
+						return yield* new ArchiveError({
+							message: `Archive path does not exist: ${candidate}`,
+						})
+					}
+
+					const canonicalPath = yield* fs.realPath(candidate)
+					const root = yield* workbase.discover(canonicalPath)
+					const child = relative(root, canonicalPath)
+					const parts = child.split(sep)
+					if (child === "" || parts.length === 1) {
+						return yield* new ArchiveError({
+							message: `Archive path is ambiguous; it does not identify a single epic or task: ${canonicalPath}`,
+						})
+					}
+
+					const [collection, id] = parts
+					const kind =
+						collection === "epics"
+							? "epic"
+							: collection === "tasks"
+								? "task"
+								: undefined
+					if (!kind || !id) {
+						return yield* new ArchiveError({
+							message: `Archive path must be within an active epic or task: ${canonicalPath}`,
+						})
+					}
+					if (kind === "task" && parts[2] === "phases") {
+						return yield* new ArchiveError({
+							message: `Archive path identifies a phase; use 'agency archive phase <task-id> <phase-id>': ${canonicalPath}`,
+						})
+					}
+
+					const document = join(
+						root,
+						kind === "epic" ? "epics" : "tasks",
+						id,
+						kind === "epic" ? "EPIC.md" : "TASK.md",
+					)
+					if (!(yield* fs.exists(document))) {
+						return yield* new ArchiveError({
+							message: `Archive path does not identify an active ${kind}: ${canonicalPath}`,
+						})
+					}
+					return { kind, id } satisfies ArchivePathTarget
+				}),
+
 			list: (filters: ArchiveFilters = {}, startPath: string = process.cwd()) =>
 				Effect.gen(function* () {
 					const fs = yield* FileSystemService

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,
 				},