@markjaquith/agency 2.3.0 → 2.5.0

package/src/services/WorktreeService.ts

@@ -1,5 +1,5 @@
 import { Data, Effect } from "effect"
-import { dirname, join, resolve } from "node:path"
+import { basename, dirname, join, resolve } from "node:path"
 import { FileSystemService } from "./FileSystemService"
 import { WorkbaseService } from "./WorkbaseService"
 import { TaskService } from "./TaskService"
@@ -9,6 +9,8 @@ import {
 	worktreeCommandEnvironment,
 } from "../workbase/worktree-command"
 import type { RepositoryReference } from "../workbase/schemas"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
 
 class WorktreeError extends Data.TaggedError("WorktreeError")<{
 	readonly message: string
@@ -49,6 +51,15 @@ const parseWorktreeList = (output: string): readonly GitWorktree[] => {
 	return worktrees
 }
 
+const formatCommand = (args: readonly string[]) =>
+	args
+		.map((argument) =>
+			/^[A-Za-z0-9_./:=+@%-]+$/.test(argument)
+				? argument
+				: `'${argument.replaceAll("'", `'\\''`)}'`,
+		)
+		.join(" ")
+
 export class WorktreeService extends Effect.Service<WorktreeService>()(
 	"WorktreeService",
 	{
@@ -57,12 +68,16 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 				taskId: string,
 				phaseId?: string,
 				startPath: string = process.cwd(),
+				options: BaseCommandOptions = {},
 			) =>
 				Effect.gen(function* () {
 					const fs = yield* FileSystemService
 					const workbase = yield* WorkbaseService
 					const tasks = yield* TaskService
 					const phases = yield* PhaseService
+					const { verboseLog } = createLoggers(options)
+					const forwardCommandOutput =
+						options.verbose === true && !options.silent && !options.json
 					const { root, config } = yield* workbase.loadConfig(startPath)
 					const report = yield* workbase.validate(root)
 					const ownershipIssue = report.issues.find((issue) =>
@@ -258,9 +273,14 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								]
 							}
 
+							if (config.worktreeCreateCommand) {
+								verboseLog(`Running worktree command: ${formatCommand(args)}`)
+							}
 							const result = yield* fs.runCommand(args, {
 								cwd: repositoryPath,
 								captureOutput: true,
+								forwardOutput:
+									config.worktreeCreateCommand && forwardCommandOutput,
 								env,
 							})
 							if (result.exitCode !== 0) {
@@ -352,6 +372,128 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						repos: execution.repos ?? [],
 					} satisfies ExecutionWorkspace
 				}),
+
+			remove: (
+				taskId: string,
+				phaseId?: string,
+				startPath: string = process.cwd(),
+			) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const workbase = yield* WorkbaseService
+					const tasks = yield* TaskService
+					const phases = yield* PhaseService
+					const root = yield* workbase.discover(startPath)
+					const task = yield* tasks.show(taskId, root)
+
+					let execution: {
+						repo: string
+						repos?: readonly RepositoryReference[]
+					}
+					let codePath: string
+					if ("phases" in task.data) {
+						if (!phaseId) {
+							return yield* new WorktreeError({
+								message: `Task '${taskId}' has multiple phases; phase ID is required`,
+							})
+						}
+						const phase = yield* phases.show(taskId, phaseId, root)
+						execution = phase.data
+						codePath = join(dirname(phase.path), "code")
+					} else {
+						if (phaseId) {
+							return yield* new WorktreeError({
+								message: `Task '${taskId}' is single-phase and does not accept a phase ID`,
+							})
+						}
+						execution = task.data
+						codePath = join(dirname(task.path), "code")
+					}
+
+					const codeDirectoryExists = yield* fs.isDirectory(codePath)
+					const removed: string[] = []
+					for (const alias of [
+						execution.repo,
+						...(execution.repos ?? []).map((reference) => reference.repo),
+					]) {
+						const repositoryPath = join(root, "repos", alias)
+						const checkoutPath = join(codePath, alias)
+						const listed = yield* fs.runCommand(
+							[
+								"git",
+								"-C",
+								repositoryPath,
+								"worktree",
+								"list",
+								"--porcelain",
+								"-z",
+							],
+							{ captureOutput: true },
+						)
+						if (listed.exitCode !== 0) {
+							return yield* new WorktreeError({
+								message: `Failed to inspect worktrees for '${alias}': ${listed.stderr}`,
+							})
+						}
+
+						const checkoutExists = yield* fs.isDirectory(checkoutPath)
+						const canonicalCheckoutPath = checkoutExists
+							? yield* fs.realPath(checkoutPath)
+							: join(
+									yield* fs.realPath(dirname(codePath)),
+									basename(codePath),
+									alias,
+								)
+						let registeredPath: string | undefined
+						for (const worktree of parseWorktreeList(listed.stdout)) {
+							const worktreePath = (yield* fs.exists(worktree.path))
+								? yield* fs.realPath(worktree.path)
+								: resolve(worktree.path)
+							if (worktreePath === canonicalCheckoutPath) {
+								registeredPath = worktreePath
+								break
+							}
+						}
+						if (!registeredPath) {
+							if (checkoutExists) {
+								return yield* new WorktreeError({
+									message: `Existing checkout ${checkoutPath} is not registered as a Git worktree`,
+								})
+							}
+							continue
+						}
+
+						const result = yield* fs.runCommand(
+							[
+								"git",
+								"-C",
+								repositoryPath,
+								"worktree",
+								"remove",
+								...(!checkoutExists ? ["--force"] : []),
+								checkoutExists ? checkoutPath : registeredPath,
+							],
+							{ captureOutput: true },
+						)
+						if (result.exitCode !== 0) {
+							return yield* new WorktreeError({
+								message: `Failed to remove worktree for '${alias}': ${result.stderr}`,
+							})
+						}
+						if (checkoutExists) removed.push(checkoutPath)
+					}
+
+					if (codeDirectoryExists && (yield* fs.isDirectory(codePath))) {
+						const remaining = yield* fs.readDirectory(codePath)
+						if (remaining.length > 0) {
+							return yield* new WorktreeError({
+								message: `Cannot remove ${codePath}; it contains unmanaged entries: ${remaining.map((entry) => entry.name).join(", ")}`,
+							})
+						}
+						yield* fs.deleteDirectory(codePath)
+					}
+					return removed
+				}),
 		}),
 	},
 ) {}

package/src/test-utils.ts

@@ -11,6 +11,7 @@ import { TaskService } from "./services/TaskService"
 import { PhaseService } from "./services/PhaseService"
 import { WorktreeService } from "./services/WorktreeService"
 import { PullRequestService } from "./services/PullRequestService"
+import { ArchiveService } from "./services/ArchiveService"
 
 export const createTempDir = () => mkdtemp(join(tmpdir(), "agency-test-"))
 
@@ -26,6 +27,7 @@ const TestLayer = Layer.mergeAll(
 	PhaseService.Default,
 	WorktreeService.Default,
 	PullRequestService.Default,
+	ArchiveService.Default,
 )
 
 export async function runTestEffect<A, E>(

package/src/utils/process.test.ts

@@ -1,8 +1,45 @@
-import { describe, expect, test } from "bun:test"
+import { describe, expect, spyOn, test } from "bun:test"
 import { Effect } from "effect"
 import { spawnProcess } from "./process"
 
 describe("spawnProcess", () => {
+	test("forwards and captures output in tee mode", async () => {
+		const forwardedStdout: Uint8Array[] = []
+		const forwardedStderr: Uint8Array[] = []
+		const stdout = spyOn(process.stdout, "write").mockImplementation(((
+			chunk: Uint8Array,
+		) => {
+			forwardedStdout.push(chunk)
+			return true
+		}) as never)
+		const stderr = spyOn(process.stderr, "write").mockImplementation(((
+			chunk: Uint8Array,
+		) => {
+			forwardedStderr.push(chunk)
+			return true
+		}) as never)
+
+		try {
+			const result = await Effect.runPromise(
+				spawnProcess(
+					["sh", "-c", "printf 'standard output'; printf 'standard error' >&2"],
+					{ stdout: "tee", stderr: "tee" },
+				),
+			)
+
+			expect(result).toEqual({
+				stdout: "standard output",
+				stderr: "standard error",
+				exitCode: 0,
+			})
+			expect(Buffer.concat(forwardedStdout).toString()).toBe("standard output")
+			expect(Buffer.concat(forwardedStderr).toString()).toBe("standard error")
+		} finally {
+			stdout.mockRestore()
+			stderr.mockRestore()
+		}
+	})
+
 	test("captures large stdout and stderr without hanging", async () => {
 		const line = "x".repeat(4096)
 		const script = [

package/src/utils/process.ts

@@ -15,11 +15,29 @@ interface ProcessResult {
 interface SpawnOptions {
 	readonly cwd?: string
 	readonly stdin?: "pipe" | "inherit"
-	readonly stdout?: "pipe" | "inherit"
-	readonly stderr?: "pipe" | "inherit"
+	readonly stdout?: "pipe" | "inherit" | "tee"
+	readonly stderr?: "pipe" | "inherit" | "tee"
 	readonly env?: Record<string, string>
 }
 
+const readOutput = async (
+	stream: ReadableStream<Uint8Array> | null | undefined,
+	target?: { write(chunk: Uint8Array): unknown },
+) => {
+	if (!stream) return ""
+
+	const reader = stream.getReader()
+	const decoder = new TextDecoder()
+	let output = ""
+	while (true) {
+		const { done, value } = await reader.read()
+		if (done) break
+		target?.write(value)
+		output += decoder.decode(value, { stream: true })
+	}
+	return output + decoder.decode()
+}
+
 /**
  * Generic error for process execution failures
  */
@@ -50,8 +68,8 @@ export const spawnProcess = (
 			const proc = Bun.spawn([...args], {
 				cwd: options?.cwd ?? process.cwd(),
 				stdin: options?.stdin ?? "pipe",
-				stdout: options?.stdout ?? "pipe",
-				stderr: options?.stderr ?? "pipe",
+				stdout: options?.stdout === "inherit" ? "inherit" : "pipe",
+				stderr: options?.stderr === "inherit" ? "inherit" : "pipe",
 				env: options?.env ? { ...process.env, ...options.env } : process.env,
 			})
 			// Start draining stdout/stderr immediately so verbose subprocesses
@@ -59,11 +77,17 @@ export const spawnProcess = (
 			const stdoutPromise =
 				options?.stdout === "inherit"
 					? Promise.resolve("")
-					: new Response(proc.stdout ?? "").text()
+					: readOutput(
+							proc.stdout,
+							options?.stdout === "tee" ? process.stdout : undefined,
+						)
 			const stderrPromise =
 				options?.stderr === "inherit"
 					? Promise.resolve("")
-					: new Response(proc.stderr ?? "").text()
+					: readOutput(
+							proc.stderr,
+							options?.stderr === "tee" ? process.stderr : undefined,
+						)
 
 			const [exitCode, stdout, stderr] = await Promise.all([
 				proc.exited,

package/src/utils/progress.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test"
+import { createProgress } from "./progress"
+
+describe("progress", () => {
+	test("replaces an active TTY line with its completed state", () => {
+		const output: string[] = []
+		const progress = createProgress(
+			{},
+			{ isTTY: true, write: (text) => output.push(text) },
+		)
+
+		progress.start("Preparing workspace...")
+		progress.succeed("Workspace ready")
+
+		expect(output).toEqual([
+			"\r\x1b[2K\x1b[2m○\x1b[0m Preparing workspace...",
+			"\r\x1b[2K\x1b[32m✓\x1b[0m Workspace ready\n",
+		])
+	})
+
+	test("stays quiet for silent or non-TTY output", () => {
+		const output: string[] = []
+		for (const [silent, isTTY] of [
+			[true, true],
+			[false, false],
+		] as const) {
+			const progress = createProgress(
+				{ silent },
+				{ isTTY, write: (text) => output.push(text) },
+			)
+			progress.start("Preparing workspace...")
+			progress.fail("Workspace preparation failed")
+		}
+
+		expect(output).toEqual([])
+	})
+})

package/src/utils/progress.ts

@@ -0,0 +1,36 @@
+interface ProgressOptions {
+	readonly silent?: boolean
+}
+
+interface ProgressOutput {
+	readonly isTTY: boolean
+	readonly write: (text: string) => void
+}
+
+export interface Progress {
+	readonly start: (message: string) => void
+	readonly succeed: (message: string) => void
+	readonly fail: (message: string) => void
+}
+
+const terminalOutput: ProgressOutput = {
+	isTTY: Boolean(process.stderr.isTTY),
+	write: (text) => process.stderr.write(text),
+}
+
+export const createProgress = (
+	options: ProgressOptions,
+	output: ProgressOutput = terminalOutput,
+): Progress => {
+	const enabled = !options.silent && output.isTTY
+	const write = (symbol: string, message: string, complete: boolean) => {
+		if (!enabled) return
+		output.write(`\r\x1b[2K${symbol} ${message}${complete ? "\n" : ""}`)
+	}
+
+	return {
+		start: (message) => write("\x1b[2m○\x1b[0m", message, false),
+		succeed: (message) => write("\x1b[32m✓\x1b[0m", message, true),
+		fail: (message) => write("\x1b[31m✗\x1b[0m", message, true),
+	}
+}

package/src/workbase/AGENTS.md

@@ -24,7 +24,10 @@ field. Repositories listed in plural `repos` are read-only references.
 
 - Keep task-level decisions in `TASK.md` and phase-specific delivery context in
   `PHASE.md`.
+- Keep execution-unit `status` current with `agency task status` or
+  `agency phase status`; `agency work` marks launched work as `working`.
 - Do not manually create, move, or remove worktrees under `code/`.
+- Use `agency archive`, rather than moving work item folders manually.
 - Do not edit bare repositories or repository symlinks under `repos/`.
 - Do not run `agency work` from an active agent session unless the user
   explicitly asks to launch another agent.

package/src/workbase/opencode-file.ts

@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto"
+
+const managedHeaderPattern =
+	/^\/\/ agency-managed: sha256=([a-f0-9]{64})\r?\n\r?\n/
+
+const checksum = (content: string) =>
+	createHash("sha256").update(content).digest("hex")
+
+const body = `${JSON.stringify(
+	{
+		$schema: "https://opencode.ai/config.json",
+		references: {
+			tasks: {
+				path: "../tasks",
+				description: "Agency task definitions and execution context",
+			},
+			epics: {
+				path: "../epics",
+				description: "Agency epic definitions and orchestration context",
+			},
+		},
+	},
+	null,
+	2,
+)}\n`
+
+const renderManagedWorkbaseOpencode = (content: string = body) =>
+	`// agency-managed: sha256=${checksum(content)}\n\n${content}`
+
+export const managedWorkbaseOpencode = renderManagedWorkbaseOpencode()
+
+export const canUpdateManagedWorkbaseOpencode = (content: string) => {
+	const match = content.match(managedHeaderPattern)
+	if (!match?.[1]) return false
+
+	return checksum(content.slice(match[0].length)) === match[1]
+}

package/src/workbase/schemas.test.ts

@@ -53,6 +53,15 @@ describe("body-of-work descriptions", () => {
 		expect(epic.description).toBeUndefined()
 	})
 
+	test("allows tasks without an external ticket", () => {
+		const task = Schema.decodeUnknownSync(TaskFrontmatter)({
+			ticketUrl: null,
+			phases: [],
+		})
+
+		expect(task.ticketUrl).toBeNull()
+	})
+
 	test("rejects an empty description when present", () => {
 		expect(() =>
 			Schema.decodeUnknownSync(PhaseFrontmatter)({
@@ -66,6 +75,47 @@ describe("body-of-work descriptions", () => {
 	})
 })
 
+describe("work status", () => {
+	test("defaults execution units to open", () => {
+		const task = Schema.decodeUnknownSync(TaskFrontmatter)({
+			ticketUrl: "https://example.com/task",
+			repo: "agency",
+			branch: "task/default-status",
+			base: "main",
+			pr: null,
+		})
+		const phase = Schema.decodeUnknownSync(PhaseFrontmatter)({
+			repo: "agency",
+			branch: "task/default-phase-status",
+			base: "main",
+			pr: null,
+		})
+
+		expect("status" in task && task.status).toBe("open")
+		expect(phase.status).toBe("open")
+	})
+
+	test("accepts supported statuses and rejects other values", () => {
+		const phase = Schema.decodeUnknownSync(PhaseFrontmatter)({
+			repo: "agency",
+			branch: "task/done",
+			base: "main",
+			pr: null,
+			status: "done",
+		})
+		expect(phase.status).toBe("done")
+		expect(() =>
+			Schema.decodeUnknownSync(PhaseFrontmatter)({
+				repo: "agency",
+				branch: "task/invalid",
+				base: "main",
+				pr: null,
+				status: "blocked",
+			}),
+		).toThrow()
+	})
+})
+
 describe("schema boundaries", () => {
 	const rejects = <S extends Schema.Schema.AnyNoContext>(
 		schema: S,

package/src/workbase/schemas.ts

@@ -15,6 +15,8 @@ export const RepositoryReference = Schema.Struct({
 	ref: NonEmptyString,
 })
 
+export const WorkStatus = Schema.Literal("open", "working", "done", "dropped")
+
 const Url = NonEmptyString.pipe(Schema.pattern(/^[a-zA-Z][a-zA-Z0-9+.-]*:/))
 
 const GitHubPullRequestUrl = NonEmptyString.pipe(
@@ -37,6 +39,7 @@ const ExecutionUnit = {
 	branch: NonEmptyString,
 	base: NonEmptyString,
 	pr: Schema.NullOr(GitHubPullRequestUrl),
+	status: Schema.optionalWith(WorkStatus, { default: () => "open" as const }),
 }
 
 export const EpicFrontmatter = Schema.Struct({
@@ -47,14 +50,14 @@ export const EpicFrontmatter = Schema.Struct({
 })
 
 const SinglePhaseTaskFrontmatter = Schema.Struct({
-	ticketUrl: Url,
+	ticketUrl: Schema.NullOr(Url),
 	description: Description,
 	epic: Schema.optional(EntityId),
 	...ExecutionUnit,
 })
 
 const MultiPhaseTaskFrontmatter = Schema.Struct({
-	ticketUrl: Url,
+	ticketUrl: Schema.NullOr(Url),
 	description: Description,
 	epic: Schema.optional(EntityId),
 	phases: Schema.Array(Dependency),
@@ -73,6 +76,7 @@ export const PhaseFrontmatter = Schema.Struct({
 export type WorkbaseConfig = Schema.Schema.Type<typeof WorkbaseConfig>
 export type Dependency = Schema.Schema.Type<typeof Dependency>
 export type RepositoryReference = Schema.Schema.Type<typeof RepositoryReference>
+export type WorkStatus = Schema.Schema.Type<typeof WorkStatus>
 export type EpicFrontmatter = Schema.Schema.Type<typeof EpicFrontmatter>
 export type TaskFrontmatter = Schema.Schema.Type<typeof TaskFrontmatter>
 export type PhaseFrontmatter = Schema.Schema.Type<typeof PhaseFrontmatter>

package/src/workbase/work-target.test.ts

@@ -25,7 +25,7 @@ describe("work target choices", () => {
 				{
 					id: "single",
 					path: "/workbase/tasks/single/TASK.md",
-					data: {},
+					data: { status: "done" },
 				},
 				{
 					id: "standalone",
@@ -38,19 +38,19 @@ describe("work target choices", () => {
 					taskId: "multi",
 					id: "verify",
 					path: "/workbase/tasks/multi/phases/verify/PHASE.md",
-					data: {},
+					data: { status: "done" },
 				},
 				{
 					taskId: "multi",
 					id: "build",
 					path: "/workbase/tasks/multi/phases/build/PHASE.md",
-					data: {},
+					data: { status: "working" },
 				},
 				{
 					taskId: "multi",
 					id: "unlisted",
 					path: "/workbase/tasks/multi/phases/unlisted/PHASE.md",
-					data: {},
+					data: { status: "dropped" },
 				},
 			],
 		)
@@ -58,11 +58,11 @@ describe("work target choices", () => {
 		expect(choices.map((choice) => choice.label)).toEqual([
 			"\x1b[35m\x1b[0m delivery\x1b[2m - Ship the release\x1b[0m",
 			"  \x1b[36m󰗡\x1b[0m multi",
-			"    \x1b[33m󰔚\x1b[0m build",
-			"    \x1b[33m󰔚\x1b[0m verify",
-			"    \x1b[33m󰔚\x1b[0m unlisted",
-			"  \x1b[36m󰗡\x1b[0m single",
-			"\x1b[36m󰗡\x1b[0m standalone\x1b[2m - Independent work\x1b[0m",
+			"    \x1b[34m◐\x1b[0m \x1b[33m󰔚\x1b[0m build",
+			"    \x1b[32m✓\x1b[0m \x1b[33m󰔚\x1b[0m verify",
+			"    \x1b[31m⊘\x1b[0m \x1b[33m󰔚\x1b[0m unlisted",
+			"  \x1b[32m✓\x1b[0m \x1b[36m󰗡\x1b[0m single",
+			"\x1b[2m○\x1b[0m \x1b[36m󰗡\x1b[0m standalone\x1b[2m - Independent work\x1b[0m",
 		])
 		expect(choices.map((choice) => choice.target.kind)).toEqual([
 			"epic",

package/src/workbase/work-target.ts

@@ -1,4 +1,5 @@
 import { Effect } from "effect"
+import type { WorkStatus } from "./schemas"
 
 export type WorkTarget =
 	| {
@@ -36,14 +37,17 @@ interface TaskRecord {
 				readonly description?: string
 				readonly phases: readonly { readonly id: string }[]
 		  }
-		| { readonly description?: string }
+		| { readonly description?: string; readonly status?: WorkStatus }
 }
 
 interface PhaseRecord {
 	readonly taskId: string
 	readonly id: string
 	readonly path: string
-	readonly data: { readonly description?: string }
+	readonly data: {
+		readonly description?: string
+		readonly status?: WorkStatus
+	}
 }
 
 export interface WorkTargetChoice {
@@ -51,13 +55,21 @@ export interface WorkTargetChoice {
 	readonly target: WorkTarget
 }
 
+const statusIcons: Record<WorkStatus, string> = {
+	open: "\x1b[2m○\x1b[0m",
+	working: "\x1b[34m◐\x1b[0m",
+	done: "\x1b[32m✓\x1b[0m",
+	dropped: "\x1b[31m⊘\x1b[0m",
+}
+
 const label = (
 	indent: string,
 	kind: WorkTarget["kind"],
 	id: string,
 	description?: string,
+	status?: WorkStatus,
 ) =>
-	`${indent}${
+	`${indent}${status === undefined ? "" : `${statusIcons[status]} `}${
 		{
 			epic: "\x1b[35m\x1b[0m",
 			task: "\x1b[36m󰗡\x1b[0m",
@@ -73,7 +85,13 @@ const taskChoices = (
 	const multiPhase = "phases" in task.data
 	const choices: WorkTargetChoice[] = [
 		{
-			label: label(indent, "task", task.id, task.data.description),
+			label: label(
+				indent,
+				"task",
+				task.id,
+				task.data.description,
+				multiPhase ? undefined : (task.data.status ?? "open"),
+			),
 			target: {
 				kind: "task",
 				taskId: task.id,
@@ -91,7 +109,13 @@ const taskChoices = (
 		if (!record) continue
 		renderedPhases.add(record.id)
 		choices.push({
-			label: label(`${indent}  `, "phase", record.id, record.data.description),
+			label: label(
+				`${indent}  `,
+				"phase",
+				record.id,
+				record.data.description,
+				record.data.status ?? "open",
+			),
 			target: {
 				kind: "phase",
 				taskId: task.id,
@@ -103,7 +127,13 @@ const taskChoices = (
 	for (const record of phaseRecords) {
 		if (renderedPhases.has(record.id)) continue
 		choices.push({
-			label: label(`${indent}  `, "phase", record.id, record.data.description),
+			label: label(
+				`${indent}  `,
+				"phase",
+				record.id,
+				record.data.description,
+				record.data.status ?? "open",
+			),
 			target: {
 				kind: "phase",
 				taskId: task.id,