@markjaquith/agency 2.25.0 → 2.26.0

package/README.md

@@ -379,14 +379,24 @@ conditions remain visible in `warnings` or `unresolved` with a suggested action.
 agency init [path] [--json]
 agency workbase add <path> [--name <name>] [--json]
 agency workbase list [--json]
+agency workbase show <id|name|path> [--json]
+agency workbase name <id|name|path> <name> [--json]
+agency workbase name <id|name|path> --clear [--json]
 agency workbase remove <id|name|path> [--json]
 agency workbase prune [--json]
-agency workbase default [<id|name> | --clear] [--json]
+agency workbase default [<id|name|path> | --clear] [--json]
 agency integration status [--json]
 agency integration sync [--json]
 agency repo add <alias> <remote> [--json]
 agency repo link <alias> <path> [--json]
 agency repo list [--json]
+agency repo show <alias> [--json]
+agency repo fetch <alias> [--json]
+agency repo remove <alias> [--json]
+agency repo unlink <alias> [--json]
+agency repo rename <alias> <new-alias> [--json]
+agency repo remote <alias> [remote] [--json]
+agency repo verify <alias> [--json]
 ```
 
 Registered workbases are stored in
@@ -395,7 +405,9 @@ Each registration has a stable ID and may have a unique name. A default workbase
 is used when the current directory is outside every workbase. `prune` removes
 registrations whose workbase configuration no longer exists.
 `repo add` creates a bare clone. `repo link` creates a symlink to an existing Git
-repository. Alias names are then used by all documents and commands.
+repository. Alias names are then used by all documents and commands. Remove,
+unlink, and rename refuse aliases referenced by active work or backed by linked
+worktrees, and report each blocker.
 
 Commands that print Agency-owned results accept `--json`, including initialization,
 integration inspection/sync, repository mutations, entity creation/list/show,

package/package.json

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

package/skills/agency/SKILL.md

@@ -65,7 +65,9 @@ Register and name known workbases so commands can select one from anywhere:
 ```bash
 agency workbase add <path> [--name <name>]
 agency workbase list
-agency workbase default [<id|name> | --clear]
+agency workbase show <id|name|path>
+agency workbase name <id|name|path> <name> | --clear
+agency workbase default [<id|name|path> | --clear]
 agency workbase remove <id|name|path>
 agency workbase prune
 ```
@@ -85,6 +87,13 @@ Link an existing local Git repository:
 
 ```bash
 agency repo link <alias> <path>
+agency repo show <alias>
+agency repo fetch <alias>
+agency repo remove <alias>
+agency repo unlink <alias>
+agency repo rename <alias> <new-alias>
+agency repo remote <alias> [remote]
+agency repo verify <alias>
 ```
 
 Use aliases, never absolute paths or Git URLs, in epic/task/phase frontmatter.

package/src/cli-parser.test.ts

@@ -121,6 +121,23 @@ describe("strict CLI parsing", () => {
 		expect(parseCli(["status", "--no-pr"]).values["no-pr"]).toBe(true)
 	})
 
+	test("parses addressable resource maintenance commands", () => {
+		for (const args of [
+			["repo", "show", "agency", "--json"],
+			["repo", "fetch", "agency"],
+			["repo", "remove", "agency"],
+			["repo", "unlink", "agency"],
+			["repo", "rename", "agency", "renamed"],
+			["repo", "remote", "agency", "https://example.com/repo.git"],
+			["repo", "verify", "agency"],
+			["workbase", "show", "primary", "--json"],
+			["workbase", "name", "primary", "renamed"],
+			["workbase", "name", "primary", "--clear"],
+		]) {
+			expect(() => parseCli(args)).not.toThrow()
+		}
+	})
+
 	test("validates view filter values and conflicts", () => {
 		expect(() => parseCli(["epic", "list", "--status", "invalid"])).toThrow(
 			"Invalid '--status' value",

package/src/cli-parser.ts

@@ -127,7 +127,7 @@ const commands = {
 		},
 	},
 	workbase: {
-		usage: "agency workbase <add|list|remove|prune|default>",
+		usage: "agency workbase <add|list|show|name|remove|prune|default>",
 		options: {
 			...outputOptions,
 			name: { type: "string" },
@@ -146,6 +146,18 @@ const commands = {
 				maxArgs: 0,
 				options: ["json"],
 			},
+			show: {
+				usage: "agency workbase show <selector> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
+			name: {
+				usage: "agency workbase name <selector> <name> | --clear [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["json", "clear"],
+			},
 			remove: {
 				usage: "agency workbase remove <selector> [--json]",
 				minArgs: 1,
@@ -186,7 +198,8 @@ const commands = {
 		},
 	},
 	repo: {
-		usage: "agency repo <add|link|list>",
+		usage:
+			"agency repo <add|link|list|show|fetch|remove|unlink|rename|remote|verify>",
 		options: outputOptions,
 		subcommands: {
 			add: {
@@ -207,6 +220,48 @@ const commands = {
 				maxArgs: 0,
 				options: ["json"],
 			},
+			show: {
+				usage: "agency repo show <alias> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
+			fetch: {
+				usage: "agency repo fetch <alias> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
+			remove: {
+				usage: "agency repo remove <alias> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
+			unlink: {
+				usage: "agency repo unlink <alias> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
+			rename: {
+				usage: "agency repo rename <alias> <new-alias> [--json]",
+				minArgs: 2,
+				maxArgs: 2,
+				options: ["json"],
+			},
+			remote: {
+				usage: "agency repo remote <alias> [remote] [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["json"],
+			},
+			verify: {
+				usage: "agency repo verify <alias> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
 		},
 	},
 	epic: {

package/src/commands/repo.test.ts

@@ -52,6 +52,21 @@ describe("repo command", () => {
 		])
 	})
 
+	test("shows a repository by alias as JSON", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				repo({
+					subcommand: "show",
+					args: ["agency"],
+					cwd: root,
+					json: true,
+				}),
+			),
+		)
+
+		expect(JSON.parse(logs[0]!).alias).toBe("agency")
+	})
+
 	test("outputs a linked repository as JSON", async () => {
 		const target = join(root, "source")
 		await mkdir(target)
@@ -77,4 +92,33 @@ describe("repo command", () => {
 			path: join(root, "repos/linked"),
 		})
 	})
+
+	test("unlinks a linked repository by alias", async () => {
+		const target = join(root, "unlink-source")
+		await mkdir(target)
+		const git = Bun.spawn(["git", "init", target], {
+			stdout: "ignore",
+			stderr: "ignore",
+		})
+		expect(await git.exited).toBe(0)
+		await runTestEffect(
+			repo({
+				subcommand: "link",
+				args: ["linked", target],
+				cwd: root,
+				silent: true,
+			}),
+		)
+
+		await runTestEffect(
+			repo({
+				subcommand: "unlink",
+				args: ["linked"],
+				cwd: root,
+				silent: true,
+			}),
+		)
+
+		expect(await Bun.file(join(target, ".git/HEAD")).exists()).toBe(true)
+	})
 })

package/src/commands/repo.ts

@@ -9,6 +9,9 @@ interface RepoOptions extends BaseCommandOptions {
 	readonly json?: boolean
 }
 
+const requireArg = (args: readonly string[], index: number, usage: string) =>
+	args[index] ? Effect.succeed(args[index]) : Effect.fail(new Error(usage))
+
 export const repo = (options: RepoOptions) =>
 	Effect.gen(function* () {
 		const repositories = yield* RepositoryService
@@ -61,10 +64,106 @@ export const repo = (options: RepoOptions) =>
 				return
 			}
 
+			case "show": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					"Usage: agency repo show <alias>",
+				)
+				const item = yield* repositories.show(alias, cwd)
+				log(
+					options.json
+						? JSON.stringify(item, null, 2)
+						: `${item.alias}\t${item.kind}\t${item.target ?? item.remote ?? item.path}`,
+				)
+				return
+			}
+
+			case "fetch": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					"Usage: agency repo fetch <alias>",
+				)
+				const item = yield* repositories.fetch(alias, cwd)
+				log(options.json ? JSON.stringify(item, null, 2) : `Fetched '${alias}'`)
+				return
+			}
+
+			case "remove":
+			case "unlink": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					`Usage: agency repo ${options.subcommand} <alias>`,
+				)
+				const item = yield* repositories[options.subcommand](alias, cwd)
+				log(
+					options.json
+						? JSON.stringify(item, null, 2)
+						: `${options.subcommand === "unlink" ? "Unlinked" : "Removed"} '${alias}'`,
+				)
+				return
+			}
+
+			case "rename": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					"Usage: agency repo rename <alias> <new-alias>",
+				)
+				const newAlias = yield* requireArg(
+					options.args,
+					1,
+					"Usage: agency repo rename <alias> <new-alias>",
+				)
+				const item = yield* repositories.rename(alias, newAlias, cwd)
+				log(
+					options.json
+						? JSON.stringify(item, null, 2)
+						: `Renamed '${alias}' to '${newAlias}'`,
+				)
+				return
+			}
+
+			case "remote": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					"Usage: agency repo remote <alias> [remote]",
+				)
+				const item = yield* repositories.remote(alias, options.args[1], cwd)
+				log(
+					options.json
+						? JSON.stringify(item, null, 2)
+						: (item.remote ?? "No origin remote configured"),
+				)
+				return
+			}
+
+			case "verify": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					"Usage: agency repo verify <alias>",
+				)
+				const report = yield* repositories.verify(alias, cwd)
+				if (options.json) log(JSON.stringify(report, null, 2))
+				if (!report.valid) {
+					return yield* Effect.fail(
+						new Error(
+							`Repository '${alias}' verification failed:\n${report.issues.map((issue) => `- ${issue}`).join("\n")}`,
+						),
+					)
+				}
+				if (!options.json) log(`Verified repository '${alias}'`)
+				return
+			}
+
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available subcommands: add, link, list",
+						"Subcommand is required. Available subcommands: add, link, list, show, fetch, remove, unlink, rename, remote, verify",
 					),
 				)
 		}
@@ -77,6 +176,13 @@ Subcommands:
   add <alias> <remote>  Create a bare clone
   link <alias> <path>   Link an existing Git repository
   list                  List repository aliases
+  show <alias>          Show a repository alias
+  fetch <alias>         Fetch and prune a repository
+  remove <alias>        Remove an unused repository alias
+  unlink <alias>        Remove an unused linked alias
+  rename <old> <new>    Rename an unused repository alias
+  remote <alias> [url]  Show or update the origin remote
+  verify <alias>        Verify repository operation
 
 Options:
   --json                Output repository aliases as JSON

package/src/commands/workbase.test.ts

@@ -108,6 +108,53 @@ describe("workbase command", () => {
 		).toEqual({ version: 2, workbases: [] })
 	})
 
+	test("names, shows, and clears a workbase name", async () => {
+		const added = await captureLogs(() =>
+			runTestEffect(
+				workbase({
+					subcommand: "add",
+					args: [root],
+					configDirectory,
+					json: true,
+				}),
+			),
+		)
+		const registration = JSON.parse(added[0]!)
+		await runTestEffect(
+			workbase({
+				subcommand: "name",
+				args: [registration.id, "primary"],
+				configDirectory,
+				silent: true,
+			}),
+		)
+
+		const shown = await captureLogs(() =>
+			runTestEffect(
+				workbase({
+					subcommand: "show",
+					args: ["primary"],
+					configDirectory,
+					json: true,
+				}),
+			),
+		)
+		expect(JSON.parse(shown[0]!).name).toBe("primary")
+
+		await runTestEffect(
+			workbase({
+				subcommand: "name",
+				args: [registration.id],
+				clear: true,
+				configDirectory,
+				silent: true,
+			}),
+		)
+		expect(
+			await Bun.file(join(configDirectory, "agency/workbases.json")).json(),
+		).toEqual({ version: 2, workbases: [registration] })
+	})
+
 	test("requires an add path", async () => {
 		await expect(
 			runTestEffect(

package/src/commands/workbase.ts

@@ -51,6 +51,54 @@ export const workbase = (options: WorkbaseOptions) =>
 				}
 				return
 			}
+			case "show": {
+				const selector = options.args[0]
+				if (!selector) {
+					return yield* Effect.fail(
+						new Error("Usage: agency workbase show <selector>"),
+					)
+				}
+				const entry = yield* service.showRegistered(
+					selector,
+					options.configDirectory,
+					options.cwd,
+				)
+				log(
+					options.json
+						? JSON.stringify(entry, null, 2)
+						: `${entry.name ?? entry.id}\t${entry.path}`,
+				)
+				return
+			}
+			case "name": {
+				const selector = options.args[0]
+				const name = options.clear ? null : options.args[1]
+				if (
+					!selector ||
+					name === undefined ||
+					(options.clear && options.args[1] !== undefined)
+				) {
+					return yield* Effect.fail(
+						new Error(
+							"Usage: agency workbase name <selector> <name> | --clear",
+						),
+					)
+				}
+				const entry = yield* service.nameRegistered(
+					selector,
+					name,
+					options.configDirectory,
+					options.cwd,
+				)
+				log(
+					options.json
+						? JSON.stringify(entry, null, 2)
+						: name === null
+							? `Cleared name for ${entry.id}`
+							: `Named workbase ${name}`,
+				)
+				return
+			}
 			case "remove": {
 				const entry = yield* service.removeRegistered(
 					options.args[0]!,
@@ -89,6 +137,7 @@ export const workbase = (options: WorkbaseOptions) =>
 				const entry = yield* service.setDefault(
 					selector,
 					options.configDirectory,
+					options.cwd,
 				)
 				log(
 					options.json
@@ -102,7 +151,7 @@ export const workbase = (options: WorkbaseOptions) =>
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available: add, list, remove, prune, default",
+						"Subcommand is required. Available: add, list, show, name, remove, prune, default",
 					),
 				)
 		}
@@ -114,6 +163,8 @@ Usage: agency workbase <subcommand>
 Subcommands:
   add <path>        Register an Agency workbase
   list              List registered workbases
+  show <selector>   Show a registered workbase
+  name <selector>   Set or clear a registered workbase name
   remove <selector> Remove a registered workbase
   prune             Remove registrations whose paths no longer exist
   default [selector] Show or set the default workbase

package/src/services/RepositoryService.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
 import { mkdir } from "node:fs/promises"
-import { join } from "node:path"
+import { dirname, join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { RepositoryService } from "./RepositoryService"
 
@@ -16,6 +16,12 @@ const runGit = async (args: string[]) => {
 	}
 }
 
+const write = async (root: string, path: string, content: string) => {
+	const fullPath = join(root, path)
+	await mkdir(dirname(fullPath), { recursive: true })
+	await Bun.write(fullPath, content)
+}
+
 describe("RepositoryService", () => {
 	let root: string
 
@@ -103,4 +109,126 @@ describe("RepositoryService", () => {
 			),
 		).rejects.toThrow("already exists")
 	})
+
+	test("shows, fetches, updates, and verifies a repository", async () => {
+		const source = join(root, "source")
+		const replacement = join(root, "replacement.git")
+		await runGit(["init", "--initial-branch=main", source])
+		await Bun.write(join(source, "README.md"), "# Source\n")
+		await runGit(["-C", source, "add", "README.md"])
+		await runGit([
+			"-C",
+			source,
+			"-c",
+			"user.name=Agency Tests",
+			"-c",
+			"user.email=agency@example.com",
+			"commit",
+			"-m",
+			"Initial commit",
+		])
+		await runGit(["init", "--bare", "--initial-branch=main", replacement])
+		await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) => service.add("agency", source, root)),
+			),
+		)
+
+		const result = await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) =>
+					Effect.gen(function* () {
+						const shown = yield* service.show("agency", root)
+						yield* service.fetch("agency", root)
+						const updated = yield* service.remote("agency", replacement, root)
+						const verified = yield* service.verify("agency", root)
+						return { shown, updated, verified }
+					}),
+				),
+			),
+		)
+
+		expect(result.shown.remote).toBe(source)
+		expect(result.updated.remote).toBe(replacement)
+		expect(result.verified.valid).toBe(true)
+		expect(result.verified.issues).toEqual([])
+	})
+
+	test("renames and removes an unused repository", async () => {
+		const source = join(root, "source.git")
+		await runGit(["init", "--bare", "--initial-branch=main", source])
+		await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) => service.add("old", source, root)),
+			),
+		)
+
+		const removed = await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) =>
+					Effect.gen(function* () {
+						const renamed = yield* service.rename("old", "new", root)
+						expect(renamed.alias).toBe("new")
+						return yield* service.remove("new", root)
+					}),
+				),
+			),
+		)
+
+		expect(removed.alias).toBe("new")
+		expect(await Bun.file(join(root, "repos/new/HEAD")).exists()).toBe(false)
+	})
+
+	test("unlinks a symlink without deleting its target", async () => {
+		const target = join(root, "linked-repository")
+		await mkdir(target, { recursive: true })
+		await runGit(["init", "--initial-branch=main", target])
+		await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) => service.link("linked", target, root)),
+			),
+		)
+
+		await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) => service.unlink("linked", root)),
+			),
+		)
+
+		expect(await Bun.file(join(target, ".git/HEAD")).exists()).toBe(true)
+		expect(await Bun.file(join(root, "repos/linked/.git/HEAD")).exists()).toBe(
+			false,
+		)
+	})
+
+	test("reports active references and refuses unsafe removal", async () => {
+		const source = join(root, "source.git")
+		await runGit(["init", "--bare", "--initial-branch=main", source])
+		await runTestEffect(
+			RepositoryService.pipe(
+				Effect.flatMap((service) => service.add("agency", source, root)),
+			),
+		)
+		await write(
+			root,
+			"tasks/active/TASK.md",
+			`---
+ticketUrl: null
+repo: agency
+branch: task/active
+base: main
+pr: null
+---
+`,
+		)
+
+		await expect(
+			runTestEffect(
+				RepositoryService.pipe(
+					Effect.flatMap((service) => service.remove("agency", root)),
+				),
+			),
+		).rejects.toThrow("active reference execution-unit:task/active")
+		expect(await Bun.file(join(root, "repos/agency/HEAD")).exists()).toBe(true)
+	})
 })

package/src/services/RepositoryService.ts

@@ -2,6 +2,7 @@ import { Schema, TreeFormatter } from "@effect/schema"
 import { Data, Effect, Either } from "effect"
 import { join, resolve } from "node:path"
 import { FileSystemService } from "./FileSystemService"
+import { GraphService } from "./GraphService"
 import { WorkbaseService } from "./WorkbaseService"
 import { RepositoryAlias } from "../workbase/schemas"
 
@@ -18,6 +19,11 @@ interface RepositoryInfo {
 	readonly target: string | null
 }
 
+interface RepositoryVerification extends RepositoryInfo {
+	readonly valid: boolean
+	readonly issues: readonly string[]
+}
+
 const validateAlias = (alias: string) => {
 	const result = Schema.decodeUnknownEither(RepositoryAlias)(alias)
 	return Either.isLeft(result)
@@ -29,6 +35,65 @@ const validateAlias = (alias: string) => {
 		: Effect.succeed(result.right)
 }
 
+const find = (alias: string, startPath: string) =>
+	Effect.gen(function* () {
+		const service = yield* RepositoryService
+		const validAlias = yield* validateAlias(alias)
+		const repositories = yield* service.list(startPath)
+		const repository = repositories.find((item) => item.alias === validAlias)
+		if (!repository) {
+			return yield* new RepositoryError({
+				message: `Unknown repository alias '${validAlias}'`,
+			})
+		}
+		return repository
+	})
+
+const removalBlockers = (repository: RepositoryInfo, startPath: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const graph = yield* GraphService
+		const report = yield* graph.get({ cwd: startPath })
+		const repositoryId = `repository:${repository.alias}`
+		const references = report.edges
+			.filter(
+				(edge) =>
+					edge.to === repositoryId &&
+					(edge.kind === "writes" || edge.kind === "references"),
+			)
+			.map((edge) => edge.from)
+			.sort()
+		const worktrees: string[] = []
+		if (repository.kind !== "symlink") {
+			const result = yield* fs.runCommand(
+				["git", "-C", repository.path, "worktree", "list", "--porcelain"],
+				{ captureOutput: true },
+			)
+			if (result.exitCode === 0) {
+				for (const block of result.stdout.trim().split(/\n\n+/)) {
+					if (!block || /(^|\n)bare(\n|$)/.test(block)) continue
+					const path = block.match(/^worktree (.+)$/m)?.[1]
+					if (path) worktrees.push(path)
+				}
+			}
+		}
+		return { references, worktrees }
+	})
+
+const assertRemovable = (repository: RepositoryInfo, startPath: string) =>
+	Effect.gen(function* () {
+		const blockers = yield* removalBlockers(repository, startPath)
+		const details = [
+			...blockers.references.map((item) => `active reference ${item}`),
+			...blockers.worktrees.map((item) => `linked worktree ${item}`),
+		]
+		if (details.length > 0) {
+			return yield* new RepositoryError({
+				message: `Repository alias '${repository.alias}' is in use and cannot be removed or renamed:\n${details.map((item) => `- ${item}`).join("\n")}`,
+			})
+		}
+	})
+
 export class RepositoryService extends Effect.Service<RepositoryService>()(
 	"RepositoryService",
 	{
@@ -154,6 +219,122 @@ export class RepositoryService extends Effect.Service<RepositoryService>()(
 
 					return repositories
 				}),
+
+			show: (alias: string, startPath: string = process.cwd()) =>
+				find(alias, startPath),
+
+			fetch: (alias: string, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const repository = yield* find(alias, startPath)
+					const result = yield* fs.runCommand(
+						["git", "-C", repository.path, "fetch", "--prune"],
+						{ captureOutput: true },
+					)
+					if (result.exitCode !== 0) {
+						return yield* new RepositoryError({
+							message: `Failed to fetch repository '${alias}': ${result.stderr.trim()}`,
+						})
+					}
+					return repository
+				}),
+
+			remove: (alias: string, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const repository = yield* find(alias, startPath)
+					yield* assertRemovable(repository, startPath)
+					yield* fs.deleteDirectory(repository.path)
+					return repository
+				}),
+
+			unlink: (alias: string, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const service = yield* RepositoryService
+					const repository = yield* find(alias, startPath)
+					if (repository.kind !== "symlink") {
+						return yield* new RepositoryError({
+							message: `Repository alias '${alias}' is not a link; use 'agency repo remove ${alias}'`,
+						})
+					}
+					return yield* service.remove(alias, startPath)
+				}),
+
+			rename: (
+				alias: string,
+				newAlias: string,
+				startPath: string = process.cwd(),
+			) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const workbase = yield* WorkbaseService
+					const repository = yield* find(alias, startPath)
+					const validNewAlias = yield* validateAlias(newAlias)
+					const root = yield* workbase.discover(startPath)
+					const destination = join(root, "repos", validNewAlias)
+					if (yield* fs.exists(destination)) {
+						return yield* new RepositoryError({
+							message: `Repository alias '${validNewAlias}' already exists`,
+						})
+					}
+					yield* assertRemovable(repository, startPath)
+					yield* fs.moveDirectory(repository.path, destination)
+					return yield* find(validNewAlias, startPath)
+				}),
+
+			remote: (
+				alias: string,
+				remote: string | undefined,
+				startPath: string = process.cwd(),
+			) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const repository = yield* find(alias, startPath)
+					if (remote === undefined) return repository
+					if (!remote.trim()) {
+						return yield* new RepositoryError({
+							message: "Repository remote is required",
+						})
+					}
+					const hasOrigin = repository.remote !== null
+					const result = yield* fs.runCommand(
+						[
+							"git",
+							"-C",
+							repository.path,
+							"remote",
+							hasOrigin ? "set-url" : "add",
+							"origin",
+							remote,
+						],
+						{ captureOutput: true },
+					)
+					if (result.exitCode !== 0) {
+						return yield* new RepositoryError({
+							message: `Failed to update remote for repository '${alias}': ${result.stderr.trim()}`,
+						})
+					}
+					return yield* find(alias, startPath)
+				}),
+
+			verify: (alias: string, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const repository = yield* find(alias, startPath)
+					const issues: string[] = []
+					const git = yield* fs.runCommand(
+						["git", "-C", repository.path, "rev-parse", "--git-dir"],
+						{ captureOutput: true },
+					)
+					if (git.exitCode !== 0) issues.push("Path is not a Git repository")
+					if (repository.remote === null)
+						issues.push("Origin remote is not configured")
+					return {
+						...repository,
+						valid: issues.length === 0,
+						issues,
+					} satisfies RepositoryVerification
+				}),
 		}),
 	},
 ) {}

package/src/services/WorkbaseService.test.ts

@@ -111,6 +111,52 @@ describe("WorkbaseService", () => {
 		expect(result.defaultWorkbase).toEqual(registered)
 	})
 
+	test("shows, names, clears names, and defaults by path", async () => {
+		const workbaseRoot = join(root, "workbase")
+		const configDirectory = join(root, "config")
+		await write(workbaseRoot, "agency.json", '{"version":2}\n')
+		const registered = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					service.register(workbaseRoot, configDirectory),
+				),
+			),
+		)
+
+		const result = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					Effect.gen(function* () {
+						const named = yield* service.nameRegistered(
+							workbaseRoot,
+							"primary",
+							configDirectory,
+						)
+						const shown = yield* service.showRegistered(
+							"primary",
+							configDirectory,
+						)
+						const defaultWorkbase = yield* service.setDefault(
+							workbaseRoot,
+							configDirectory,
+						)
+						const unnamed = yield* service.nameRegistered(
+							registered.id,
+							null,
+							configDirectory,
+						)
+						return { named, shown, defaultWorkbase, unnamed }
+					}),
+				),
+			),
+		)
+
+		expect(result.named.name).toBe("primary")
+		expect(result.shown).toEqual(result.named)
+		expect(result.defaultWorkbase?.id).toBe(registered.id)
+		expect(result.unnamed).toEqual({ id: registered.id, path: registered.path })
+	})
+
 	test("rejects names that collide with stable IDs", async () => {
 		const firstRoot = join(root, "first")
 		const secondRoot = join(root, "second")

package/src/services/WorkbaseService.ts

@@ -146,6 +146,31 @@ const writeRegistry = (
 		yield* fs.writeJSON(path, registry)
 	})
 
+const findRegistration = (
+	selector: string,
+	configDirectory?: string,
+	basePath: string = process.cwd(),
+) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const { path, registry } = yield* readRegistry(configDirectory)
+		const candidatePath = resolve(basePath, selector)
+		const canonicalCandidate = (yield* fs.exists(candidatePath))
+			? yield* fs.realPath(candidatePath)
+			: candidatePath
+		const entry =
+			registry.workbases.find((item) => item.id === selector) ??
+			registry.workbases.find((item) => item.name === selector) ??
+			registry.workbases.find((item) => item.path === canonicalCandidate)
+		if (!entry) {
+			return yield* new WorkbaseRegistryError({
+				path,
+				message: `Unknown workbase selector '${selector}'`,
+			})
+		}
+		return { path, registry, entry }
+	})
+
 export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 	"WorkbaseService",
 	{
@@ -401,22 +426,11 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 				basePath: string = process.cwd(),
 			) =>
 				Effect.gen(function* () {
-					const fs = yield* FileSystemService
-					const { path, registry } = yield* readRegistry(configDirectory)
-					const candidatePath = resolve(basePath, selector)
-					const canonicalCandidate = (yield* fs.exists(candidatePath))
-						? yield* fs.realPath(candidatePath)
-						: candidatePath
-					const entry =
-						registry.workbases.find((item) => item.id === selector) ??
-						registry.workbases.find((item) => item.name === selector) ??
-						registry.workbases.find((item) => item.path === canonicalCandidate)
-					if (!entry) {
-						return yield* new WorkbaseRegistryError({
-							path,
-							message: `Unknown workbase selector '${selector}'`,
-						})
-					}
+					const { path, registry, entry } = yield* findRegistration(
+						selector,
+						configDirectory,
+						basePath,
+					)
 					const workbases = registry.workbases.filter(
 						(item) => item.id !== entry.id,
 					)
@@ -431,6 +445,61 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 					return entry
 				}),
 
+			showRegistered: (
+				selector: string,
+				configDirectory?: string,
+				basePath: string = process.cwd(),
+			) =>
+				findRegistration(selector, configDirectory, basePath).pipe(
+					Effect.map(({ entry }) => entry),
+				),
+
+			nameRegistered: (
+				selector: string,
+				name: string | null,
+				configDirectory?: string,
+				basePath: string = process.cwd(),
+			) =>
+				Effect.gen(function* () {
+					const { path, registry, entry } = yield* findRegistration(
+						selector,
+						configDirectory,
+						basePath,
+					)
+					if (name !== null) {
+						const decodedName = decode(EntityId, name)
+						if (!decodedName.success) {
+							return yield* new WorkbaseRegistryError({
+								path,
+								message: `Invalid workbase name '${name}': names must contain only letters, numbers, dots, underscores, and hyphens`,
+							})
+						}
+						const collision = registry.workbases.find(
+							(item) =>
+								item.id !== entry.id &&
+								(item.id === name || item.name === name),
+						)
+						if (collision) {
+							return yield* new WorkbaseRegistryError({
+								path,
+								message: `Workbase name '${name}' is already registered for ${collision.path}`,
+							})
+						}
+					}
+					const updated = {
+						id: entry.id,
+						...(name === null ? {} : { name }),
+						path: entry.path,
+					}
+					yield* writeRegistry(path, {
+						...registry,
+						workbases: registry.workbases.map((item) =>
+							item.id === entry.id ? updated : item,
+						),
+					})
+					return updated
+				}),
+
 			pruneRegistered: (configDirectory?: string) =>
 				Effect.gen(function* () {
 					const fs = yield* FileSystemService
@@ -455,7 +524,11 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 					return removed
 				}),
 
-			setDefault: (selector: string | null, configDirectory?: string) =>
+			setDefault: (
+				selector: string | null,
+				configDirectory?: string,
+				basePath: string = process.cwd(),
+			) =>
 				Effect.gen(function* () {
 					const { path, registry } = yield* readRegistry(configDirectory)
 					if (selector === null) {
@@ -465,15 +538,11 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 						})
 						return null
 					}
-					const entry = registry.workbases.find(
-						(item) => item.id === selector || item.name === selector,
+					const { entry } = yield* findRegistration(
+						selector,
+						configDirectory,
+						basePath,
 					)
-					if (!entry) {
-						return yield* new WorkbaseRegistryError({
-							path,
-							message: `Unknown registered workbase selector '${selector}'`,
-						})
-					}
 					yield* writeRegistry(path, {
 						version: 2,
 						workbases: registry.workbases,