@markjaquith/agency 3.2.3 → 3.2.5

package/README.md

@@ -26,14 +26,20 @@ Agency records privacy-safe CLI usage events locally so command journeys,
 failures, and flag adoption can be analyzed. Events are stored in SQLite at
 `$XDG_STATE_HOME/agency/usage.sqlite3` (or
 `~/.local/state/agency/usage.sqlite3`) and retained for 90 days by default.
-Each event contains the normalized command path, flag names, timing, outcome,
-Agency version, and ordered `AGENCY_SESSION_ID` correlation. Raw arguments,
+Each event contains the parser-derived command and subcommand path, flag names,
+timing, a bounded outcome code, Agency version, invocation source, explicit test
+attribution, and ordered journey correlation. Journey IDs are one-way hashes of
+`AGENCY_SESSION_ID`; raw session IDs, positional arguments, entity IDs, paths,
 flag values, free-form input, and the current directory are never recorded.
 
 Export events as JSON Lines with `agency usage export`. Set
 `AGENCY_NO_USAGE_LOG=1` to opt out, `AGENCY_USAGE_RETENTION_DAYS` to change
-retention, or `AGENCY_USAGE_DB` to select a different database path. Logging is
-best effort and never changes command output or exit behavior.
+retention, or `AGENCY_USAGE_DB` to select a different database path. Expired
+events are pruned on every read and write. Set `AGENCY_INVOCATION_SOURCE` to one
+of `human`, `agent`, or `automation`, and set `AGENCY_USAGE_TEST=1` for explicit
+test attribution. Logging is best effort and never changes command output or
+exit behavior. Databases created by versions before this privacy boundary are
+cleared because their command paths may contain positional values.
 
 ## Core Model
 

package/cli-main.ts

@@ -57,7 +57,11 @@ import {
 	successEnvelope,
 	writeEnvelope,
 } from "./src/protocol"
-import { exportUsageEvents, recordUsageEvent } from "./src/usage-log"
+import {
+	exportUsageEvents,
+	recordUsageEvent,
+	usageOutcomeCode,
+} from "./src/usage-log"
 
 // Create CLI layer with all services
 const CliLayer = Layer.mergeAll(
@@ -752,9 +756,7 @@ const machineMode = process.argv
 const invocationStartedAt = performance.now()
 const rawArguments = process.argv.slice(2)
 let usageCommandPath = "invalid"
-let usageFlagNames = rawArguments
-	.filter((argument) => argument.startsWith("--"))
-	.map((argument) => argument.slice(2).split("=", 1)[0]!)
+let usageFlagNames: string[] = []
 
 const pushUsageDetails = (error?: unknown) => {
 	if (usageCommandPath !== "push") return {}
@@ -795,17 +797,12 @@ const pushUsageDetails = (error?: unknown) => {
 try {
 	const {
 		commandName,
+		commandPath,
 		args: commandArgs,
 		passthrough,
 		values,
 	} = parseCli(rawArguments)
-	usageCommandPath =
-		[commandName, commandArgs[0]]
-			.filter(
-				(part): part is string =>
-					typeof part === "string" && part.length > 0 && !part.startsWith("-"),
-			)
-			.join("/") || "root"
+	usageCommandPath = commandPath
 	usageFlagNames = Object.entries(values)
 		.filter(([, value]) => value !== undefined && value !== false)
 		.map(([name]) => name)
@@ -823,6 +820,7 @@ try {
 				flagNames: usageFlagNames,
 				durationMs: performance.now() - invocationStartedAt,
 				outcome: "success",
+				outcomeCode: "SUCCESS",
 				exitStatus: 0,
 			},
 			VERSION,
@@ -841,6 +839,7 @@ try {
 				flagNames: usageFlagNames,
 				durationMs: performance.now() - invocationStartedAt,
 				outcome: exitStatus === 0 ? "success" : "failure",
+				outcomeCode: exitStatus === 0 ? "SUCCESS" : "NONZERO_EXIT",
 				exitStatus,
 			},
 			VERSION,
@@ -884,18 +883,28 @@ try {
 			flagNames: usageFlagNames,
 			durationMs: performance.now() - invocationStartedAt,
 			outcome: exitStatus === 0 ? "success" : "failure",
+			outcomeCode: exitStatus === 0 ? "SUCCESS" : "NONZERO_EXIT",
 			exitStatus,
 			...pushUsageDetails(),
 		},
 		VERSION,
 	)
 } catch (error) {
+	if (
+		typeof error === "object" &&
+		error !== null &&
+		"commandPath" in error &&
+		typeof error.commandPath === "string"
+	) {
+		usageCommandPath = error.commandPath
+	}
 	await recordUsageEvent(
 		{
 			commandPath: usageCommandPath,
 			flagNames: usageFlagNames,
 			durationMs: performance.now() - invocationStartedAt,
 			outcome: "failure",
+			outcomeCode: usageOutcomeCode(error),
 			exitStatus: 1,
 			...pushUsageDetails(error),
 		},

package/package.json

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

package/src/cli-parser.test.ts

@@ -7,6 +7,25 @@ const expectUsageError = (args: string[], usage: string) => {
 }
 
 describe("strict CLI parsing", () => {
+	test("returns canonical paths without positional values", () => {
+		expect(parseCli(["task", "show", "private-task-id"]).commandPath).toBe(
+			"task/show",
+		)
+		expect(parseCli(["validate", "/private/customer/path"]).commandPath).toBe(
+			"validate",
+		)
+		expect(parseCli(["work", "prepare", "private-task-id"]).commandPath).toBe(
+			"work/prepare",
+		)
+		expect(parseCli(["pr", "view", "private-task-id"]).commandPath).toBe("pr")
+		try {
+			parseCli(["task", "create", "private-task-id"])
+			expect.unreachable()
+		} catch (error) {
+			expect(error).toMatchObject({ commandPath: "task/create" })
+		}
+	})
+
 	test("parses act selectors, dry-run, and JSON options", () => {
 		expect(
 			parseCli([
@@ -363,6 +382,7 @@ describe("strict CLI parsing", () => {
 		const args = ["create", "--title", "two words", "--", "--literal"]
 		expect(parseCli(["--cwd", "/workbase", "pr", ...args])).toEqual({
 			commandName: "pr",
+			commandPath: "pr",
 			args,
 			passthrough: true,
 			values: { cwd: "/workbase" },
@@ -382,6 +402,7 @@ describe("strict CLI parsing", () => {
 			]),
 		).toEqual({
 			commandName: "pr",
+			commandPath: "pr/create",
 			args: ["create", "ship", "release"],
 			values: { draft: true, force: true, json: true },
 		})

package/src/cli-parser.ts

@@ -1032,6 +1032,7 @@ const preCommandValueOptions = new Set(["--workbase", "--cwd"])
 
 export interface ParsedCli {
 	readonly commandName?: keyof typeof commands
+	readonly commandPath: string
 	readonly args: string[]
 	readonly passthrough?: boolean
 	readonly values: Record<
@@ -1040,8 +1041,14 @@ export interface ParsedCli {
 	>
 }
 
+const canonicalCommandPath = (
+	commandName: string,
+	subcommand: string | undefined,
+) => (subcommand ? `${commandName}/${subcommand}` : commandName)
+
 class CliUsageError extends Error {
 	readonly _tag = "CliUsageError"
+	readonly commandPath: string
 
 	constructor(
 		readonly detail: string,
@@ -1049,6 +1056,15 @@ class CliUsageError extends Error {
 	) {
 		super(`${detail}\n\nUsage: ${usage}`)
 		this.name = "CliUsageError"
+		const [, commandName, subcommand] = usage.split(/\s+/)
+		const definition: CommandDefinition | undefined =
+			commands[commandName as keyof typeof commands]
+		this.commandPath = !definition
+			? "invalid"
+			: subcommand && definition.subcommands?.[subcommand]
+				? `${commandName}/${subcommand}`
+				: commandName!
+		Object.defineProperty(this, "commandPath", { enumerable: false })
 	}
 }
 
@@ -1323,7 +1339,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 				"agency <command> [options]",
 			)
 		}
-		return { args: [], values: parsed.values }
+		return { commandPath: "root", args: [], values: parsed.values }
 	}
 
 	const commandName = args[commandIndex]!
@@ -1368,6 +1384,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 		}
 		return {
 			commandName,
+			commandPath: "pr",
 			args: prArgs,
 			passthrough: true,
 			values: parsed.values,
@@ -1391,6 +1408,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 		assertNoDuplicateOptions(parsed.tokens, new Set(), definition.usage)
 		return {
 			commandName: commandName as keyof typeof commands,
+			commandPath: commandName,
 			args: parsed.positionals,
 			values: parsed.values,
 		}
@@ -1441,6 +1459,10 @@ export function parseCli(args: readonly string[]): ParsedCli {
 	if (parsed.values.version) {
 		return {
 			commandName: commandName as keyof typeof commands,
+			commandPath: canonicalCommandPath(
+				commandName,
+				selectedSubcommand ? subcommand : undefined,
+			),
 			args: parsed.positionals,
 			values: parsed.values,
 		}
@@ -1448,6 +1470,10 @@ export function parseCli(args: readonly string[]): ParsedCli {
 	if (parsed.values.help) {
 		return {
 			commandName: commandName as keyof typeof commands,
+			commandPath: canonicalCommandPath(
+				commandName,
+				selectedSubcommand ? subcommand : undefined,
+			),
 			args: parsed.positionals,
 			values: parsed.values,
 		}
@@ -1622,6 +1648,14 @@ export function parseCli(args: readonly string[]): ParsedCli {
 
 	return {
 		commandName: commandName as keyof typeof commands,
+		commandPath: canonicalCommandPath(
+			commandName,
+			selectedSubcommand
+				? subcommand
+				: commandName === "work" && commandPositionals[0] === "prepare"
+					? "prepare"
+					: undefined,
+		),
 		args: selectedSubcommand
 			? [subcommand!, ...commandPositionals]
 			: commandPositionals,

package/src/cli.test.ts

@@ -179,10 +179,31 @@ describe("CLI", () => {
 			XDG_STATE_HOME: state,
 			AGENCY_SESSION_ID: "cli-session",
 			AGENCY_NO_USAGE_LOG: "0",
+			AGENCY_INVOCATION_SOURCE: "automation",
+			AGENCY_USAGE_TEST: "1",
 		}
 		expect((await runCli(["--version"], projectRoot, env)).exitCode).toBe(0)
 		expect(
-			(await runCli(["unknown", "--cwd", "/private/value"], projectRoot, env))
+			(
+				await runCli(
+					[
+						"task",
+						"create",
+						"private-customer-id",
+						"--repo",
+						"private-repository",
+						"--description",
+						"private free-form input",
+						"--cwd",
+						"/private/customer/path",
+					],
+					projectRoot,
+					env,
+				)
+			).exitCode,
+		).toBe(1)
+		expect(
+			(await runCli(["unknown", "--private-flag=value"], projectRoot, env))
 				.exitCode,
 		).toBe(1)
 
@@ -194,20 +215,41 @@ describe("CLI", () => {
 			.map((line) => JSON.parse(line))
 		expect(events).toEqual([
 			expect.objectContaining({
-				sessionId: "cli-session",
-				sessionSequence: 1,
+				journeyId: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+				journeySequence: 1,
+				invocationSource: "automation",
+				isTest: true,
 				commandPath: "version",
 				flagNames: ["version"],
 				outcome: "success",
+				outcomeCode: "SUCCESS",
 			}),
 			expect.objectContaining({
-				sessionSequence: 2,
+				journeySequence: 2,
+				commandPath: "task/create",
+				flagNames: ["cwd", "description", "repo"],
+				outcome: "failure",
+				outcomeCode: "WORKBASE_NOT_FOUND",
+			}),
+			expect.objectContaining({
+				journeySequence: 3,
 				commandPath: "invalid",
-				flagNames: ["cwd"],
+				flagNames: [],
 				outcome: "failure",
+				outcomeCode: "CLI_USAGE",
 			}),
 		])
-		expect(exported.stdout).not.toContain("/private/value")
+		for (const value of [
+			"cli-session",
+			"private-customer-id",
+			"private-repository",
+			"private free-form input",
+			"/private/customer/path",
+			"private-flag",
+			"value",
+		]) {
+			expect(exported.stdout).not.toContain(value)
+		}
 	})
 
 	test("records status-based non-PR completion", async () => {

package/src/services/IntegrationService.test.ts

@@ -260,6 +260,9 @@ describe("IntegrationService", () => {
 			"!result.authority?.writable?.checkoutPath",
 		)
 		expect(managedWorkbaseOpencodePlugin).toContain('status !== "working"')
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			'output.env.AGENCY_INVOCATION_SOURCE = "agent"',
+		)
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			"output.env.AGENCY_SESSION_ID = sessionID",
 		)

package/src/services/RepositoryService.test.ts

@@ -1,6 +1,6 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test"
 import { Effect } from "effect"
-import { mkdir, realpath } from "node:fs/promises"
+import { mkdir, realpath, stat } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { RepositoryService } from "./RepositoryService"
@@ -136,6 +136,30 @@ describe("RepositoryService", () => {
 		})
 	})
 
+	test("inspects only the requested repository alias", async () => {
+		const requested = join(root, "repos/requested")
+		const unrelated = join(root, "repos/unrelated")
+		await mkdir(requested, { recursive: true })
+		await mkdir(unrelated, { recursive: true })
+		await runGit(["init", "--initial-branch=main", requested])
+		await runGit(["init", "--initial-branch=main", unrelated])
+
+		const spawn = spyOn(Bun, "spawn")
+		try {
+			const repository = await runTestEffect(
+				RepositoryService.pipe(
+					Effect.flatMap((service) => service.show("requested", root)),
+				),
+			)
+			expect(repository.alias).toBe("requested")
+			expect(spawn.mock.calls).toHaveLength(1)
+			expect(spawn.mock.calls[0]?.[0]).toContain(requested)
+			expect(spawn.mock.calls[0]?.[0]).not.toContain(unrelated)
+		} finally {
+			spawn.mockRestore()
+		}
+	})
+
 	test("materializes a linked alias without invalidating active worktrees", async () => {
 		const target = join(root, "linked-repository")
 		const checkout = join(root, "tasks/active/code/linked")
@@ -146,6 +170,13 @@ describe("RepositoryService", () => {
 		await Bun.write(join(target, "README.md"), "linked\n")
 		await runGit(["-C", target, "add", "README.md"])
 		await runGit(["-C", target, "commit", "-m", "initial"])
+		const commit = await gitOutput(["-C", target, "rev-parse", "HEAD"])
+		const sourceObject = join(
+			target,
+			".git/objects",
+			commit.slice(0, 2),
+			commit.slice(2),
+		)
 		await setPortableOrigin(target, "materialized")
 		await runTestEffect(
 			RepositoryService.pipe(
@@ -218,6 +249,15 @@ status: working
 				"refs/agency/reviews/active",
 			]),
 		).toBe(await gitOutput(["-C", target, "rev-parse", "main"]))
+		const materializedObject = join(
+			root,
+			"repos/linked/objects",
+			commit.slice(0, 2),
+			commit.slice(2),
+		)
+		expect((await stat(materializedObject)).ino).not.toBe(
+			(await stat(sourceObject)).ino,
+		)
 	})
 
 	test("preserves detached registered worktree commits from a shallow linked repository", async () => {

package/src/services/RepositoryService.ts

@@ -186,18 +186,71 @@ const portableRemote = (path: string, backend?: VersionControlBackend) =>
 		return yield* validateRemote(remote)
 	})
 
-const find = (alias: string, startPath: string) =>
+const inspectRepository = (
+	alias: string,
+	state: Effect.Effect.Success<ReturnType<typeof configState>>,
+	backend: VersionControlBackend,
+) =>
 	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) {
+		const fs = yield* FileSystemService
+		const path = join(state.root, "repos", alias)
+		const declaredRemote = state.config.repositories?.[alias]?.remote ?? null
+		const entry = yield* fs.inspectFile(path)
+		if (entry.kind === "missing") {
+			if (declaredRemote) {
+				return {
+					alias,
+					path,
+					kind: null,
+					remote: null,
+					declaredRemote,
+					target: null,
+					states: ["declared", "missing"],
+				} as RepositoryInfo
+			}
 			return yield* new RepositoryError({
-				message: `Unknown repository alias '${validAlias}'`,
+				message: `Unknown repository alias '${alias}'`,
 			})
 		}
-		return repository
+		const isSymlink = entry.kind === "symlink"
+		if (!isSymlink && !(yield* fs.isDirectory(path))) {
+			return {
+				alias,
+				path,
+				kind: null,
+				remote: null,
+				declaredRemote,
+				target: null,
+				states: [...(declaredRemote ? (["declared"] as const) : []), "invalid"],
+			} as RepositoryInfo
+		}
+		const target = isSymlink ? yield* fs.readSymlinkTarget(path) : null
+		const inspection = yield* backend.inspectRepository(path)
+		const remote = inspection?.remote ?? null
+		const states: RepositoryState[] = []
+		if (declaredRemote) states.push("declared")
+		states.push(isSymlink ? "linked" : "materialized")
+		if (!inspection) states.push("invalid")
+		if (declaredRemote && remote !== declaredRemote)
+			states.push("remote-drifted")
+		return {
+			alias,
+			path,
+			kind: isSymlink ? "symlink" : (inspection?.kind ?? "repository"),
+			remote,
+			declaredRemote,
+			target,
+			states,
+		} as RepositoryInfo
+	})
+
+const find = (alias: string, startPath: string) =>
+	Effect.gen(function* () {
+		const versionControl = yield* VersionControlService
+		const validAlias = yield* validateAlias(alias)
+		const state = yield* configState(startPath)
+		const backend = yield* versionControl.forWorkbase(state.root)
+		return yield* inspectRepository(validAlias, state, backend)
 	})
 
 const requireMaterialized = (repository: RepositoryInfo) =>
@@ -450,14 +503,11 @@ export class RepositoryService extends Effect.Service<RepositoryService>()(
 					const backend = yield* versionControl.forWorkbase(state.root)
 					const destination = join(state.root, "repos", validAlias)
 					const resolvedTarget = resolve(startPath, target)
-					const existing = (yield* RepositoryService)
-						.list(state.root)
-						.pipe(
-							Effect.map((items) =>
-								items.find((item) => item.alias === validAlias),
-							),
-						)
-					const current = yield* existing
+					const current =
+						state.config.repositories?.[validAlias] ||
+						(yield* fs.exists(destination))
+							? yield* inspectRepository(validAlias, state, backend)
+							: undefined
 					const localCurrent =
 						current && !current.states.includes("missing") ? current : undefined
 					if (localCurrent?.kind === "symlink") {
@@ -521,10 +571,17 @@ export class RepositoryService extends Effect.Service<RepositoryService>()(
 				Effect.gen(function* () {
 					const fs = yield* FileSystemService
 					const versionControl = yield* VersionControlService
-					const repository = yield* find(alias, startPath)
+					const validAlias = yield* validateAlias(alias)
+					const state = yield* configState(startPath)
+					const backend = yield* versionControl.forWorkbase(state.root)
+					const repository = yield* inspectRepository(
+						validAlias,
+						state,
+						backend,
+					)
 					if (repository.kind !== "symlink" || !repository.target) {
 						return yield* new RepositoryError({
-							message: `Repository alias '${alias}' is not linked`,
+							message: `Repository alias '${validAlias}' is not linked`,
 						})
 					}
 					if (repository.states.includes("invalid")) {
@@ -543,9 +600,6 @@ export class RepositoryService extends Effect.Service<RepositoryService>()(
 						})
 					}
 
-					const state = yield* configState(startPath)
-					const backend = yield* versionControl.forWorkbase(state.root)
-
 					const source = yield* fs.realPath(repository.path)
 					const registered = yield* backend.listWorkspaces(repository.path)
 					const registeredState = registered
@@ -854,78 +908,22 @@ export class RepositoryService extends Effect.Service<RepositoryService>()(
 			list: (startPath: string = process.cwd()) =>
 				Effect.gen(function* () {
 					const fs = yield* FileSystemService
-					const { root, config } = yield* WorkbaseService.pipe(
-						Effect.flatMap((service) => service.loadConfig(startPath)),
-					)
 					const versionControl = yield* VersionControlService
-					const backend = yield* versionControl.forWorkbase(root)
-					const reposPath = join(root, "repos")
+					const state = yield* configState(startPath)
+					const backend = yield* versionControl.forWorkbase(state.root)
+					const reposPath = join(state.root, "repos")
 					const entries = (yield* fs.isDirectory(reposPath))
 						? (yield* fs.readDirectory(reposPath)).filter(
 								(entry) => !entry.name.startsWith(".agency-"),
 							)
 						: []
-					const local = new Map(entries.map((entry) => [entry.name, entry]))
 					const aliases = new Set([
-						...Object.keys(config.repositories ?? {}),
-						...local.keys(),
+						...Object.keys(state.config.repositories ?? {}),
+						...entries.map((entry) => entry.name),
 					])
 					return yield* Effect.forEach(
 						[...aliases].sort(),
-						(alias) =>
-							Effect.gen(function* () {
-								const path = join(reposPath, alias)
-								const entry = local.get(alias)
-								const declaredRemote =
-									config.repositories?.[alias]?.remote ?? null
-								if (!entry) {
-									return {
-										alias,
-										path,
-										kind: null,
-										remote: null,
-										declaredRemote,
-										target: null,
-										states: ["declared", "missing"] as RepositoryState[],
-									} satisfies RepositoryInfo
-								}
-								if (!entry.isDirectory && !entry.isSymlink) {
-									return {
-										alias,
-										path,
-										kind: null,
-										remote: null,
-										declaredRemote,
-										target: null,
-										states: [
-											...(declaredRemote ? (["declared"] as const) : []),
-											"invalid",
-										] as RepositoryState[],
-									} satisfies RepositoryInfo
-								}
-								const target = entry.isSymlink
-									? yield* fs.readSymlinkTarget(path)
-									: null
-								const inspection = yield* backend.inspectRepository(path)
-								const remote = inspection?.remote ?? null
-								const states: RepositoryState[] = []
-								if (declaredRemote) states.push("declared")
-								states.push(entry.isSymlink ? "linked" : "materialized")
-								if (!inspection) states.push("invalid")
-								if (declaredRemote && remote !== declaredRemote)
-									states.push("remote-drifted")
-								return {
-									alias,
-									path,
-									kind: entry.isSymlink
-										? "symlink"
-										: (inspection?.kind ?? "repository"),
-									remote,
-									declaredRemote,
-									target,
-									states,
-								} satisfies RepositoryInfo
-							}),
+						(alias) => inspectRepository(alias, state, backend),
 						{ concurrency: 8 },
 					)
 				}),

package/src/services/VersionControlService.ts

@@ -171,7 +171,15 @@ export class GitVersionControlService extends Effect.Service<GitVersionControlSe
 						yield* requireSuccess(
 							"Failed to clone Git repository",
 							fs.runCommand(
-								["git", "clone", "--bare", "--", source, destination],
+								[
+									"git",
+									"clone",
+									"--bare",
+									"--no-hardlinks",
+									"--",
+									source,
+									destination,
+								],
 								{
 									captureOutput: true,
 								},

package/src/usage-log.test.ts

@@ -1,20 +1,36 @@
 import { afterEach, describe, expect, test } from "bun:test"
+import { Database } from "bun:sqlite"
 import { rm } from "node:fs/promises"
 import { join } from "node:path"
 import { cleanupTempDir, createTempDir } from "./test-utils"
-import { exportUsageEvents, recordUsageEvent } from "./usage-log"
+import {
+	exportUsageEvents,
+	recordUsageEvent,
+	usageOutcomeCode,
+} from "./usage-log"
 
 describe("usage logging", () => {
 	const tempDirs: string[] = []
 
 	afterEach(() => Promise.all(tempDirs.splice(0).map(cleanupTempDir)))
 
+	test("maps only reviewed failure categories", () => {
+		expect(usageOutcomeCode({ _tag: "WorkbaseNotFoundError" })).toBe(
+			"WORKBASE_NOT_FOUND",
+		)
+		expect(usageOutcomeCode({ _tag: "private-customer-id" })).toBe(
+			"COMMAND_FAILED",
+		)
+	})
+
 	test("stores versioned privacy-safe events in session order", async () => {
 		const state = await createTempDir()
 		tempDirs.push(state)
 		const env = {
 			XDG_STATE_HOME: state,
 			AGENCY_SESSION_ID: "session-1",
+			AGENCY_INVOCATION_SOURCE: "automation",
+			AGENCY_USAGE_TEST: "1",
 		} as NodeJS.ProcessEnv
 		for (const commandPath of ["worktree/prepare", "context"]) {
 			await recordUsageEvent(
@@ -23,6 +39,7 @@ describe("usage logging", () => {
 					flagNames: ["json", "task", "json"],
 					durationMs: 12.4,
 					outcome: "success",
+					outcomeCode: "SUCCESS",
 					exitStatus: 0,
 					...(commandPath === "context"
 						? {
@@ -40,26 +57,31 @@ describe("usage logging", () => {
 		expect(await Bun.file(join(state, "agency/usage.sqlite3")).exists()).toBe(
 			true,
 		)
-		expect(await exportUsageEvents(env)).toEqual([
+		const events = await exportUsageEvents(env)
+		expect(events).toEqual([
 			expect.objectContaining({
 				version: 2,
-				sessionId: "session-1",
-				sessionSequence: 1,
+				journeyId: expect.stringMatching(/^sha256:[a-f0-9]{64}$/),
+				journeySequence: 1,
+				invocationSource: "automation",
+				isTest: true,
 				agencyVersion: "1.2.3",
 				commandPath: "worktree/prepare",
 				flagNames: ["json", "task"],
 				durationMs: 12,
 				outcome: "success",
+				outcomeCode: "SUCCESS",
 				exitStatus: 0,
 			}),
 			expect.objectContaining({
-				sessionSequence: 2,
+				journeySequence: 2,
 				commandPath: "context",
 				vcs: "git",
 				terminalStage: "publish",
 				category: "success",
 			}),
 		])
+		expect(JSON.stringify(events)).not.toContain("session-1")
 	})
 
 	test("supports opt-out and ignores unavailable storage", async () => {
@@ -75,6 +97,7 @@ describe("usage logging", () => {
 				flagNames: [],
 				durationMs: 1,
 				outcome: "failure",
+				outcomeCode: "COMMAND_FAILED",
 				exitStatus: 1,
 			},
 			"1.2.3",
@@ -93,6 +116,7 @@ describe("usage logging", () => {
 					flagNames: [],
 					durationMs: 1,
 					outcome: "failure",
+					outcomeCode: "COMMAND_FAILED",
 					exitStatus: 1,
 				},
 				"1.2.3",
@@ -101,4 +125,64 @@ describe("usage logging", () => {
 		).resolves.toBeUndefined()
 		await rm(blocked)
 	})
+
+	test("prunes expired events on every database access", async () => {
+		const state = await createTempDir()
+		tempDirs.push(state)
+		const env = {
+			XDG_STATE_HOME: state,
+			AGENCY_USAGE_RETENTION_DAYS: "30",
+		} as NodeJS.ProcessEnv
+		await recordUsageEvent(
+			{
+				commandPath: "status",
+				flagNames: [],
+				durationMs: 1,
+				outcome: "success",
+				outcomeCode: "SUCCESS",
+				exitStatus: 0,
+			},
+			"1.2.3",
+			env,
+		)
+		const database = new Database(join(state, "agency/usage.sqlite3"))
+		database.run(
+			"UPDATE usage_events SET occurred_at = datetime('now', '-31 days')",
+		)
+		database.close()
+
+		expect(await exportUsageEvents(env)).toEqual([])
+	})
+
+	test("removes legacy events that may contain positional values", async () => {
+		const state = await createTempDir()
+		tempDirs.push(state)
+		const path = join(state, "usage.sqlite3")
+		const database = new Database(path, { create: true })
+		database.run(
+			"CREATE TABLE usage_events (id INTEGER PRIMARY KEY, command_path TEXT NOT NULL)",
+		)
+		database.run("INSERT INTO usage_events (command_path) VALUES (?)", [
+			"task/private-customer-id",
+		])
+		database.close()
+		const env = { AGENCY_USAGE_DB: path } as NodeJS.ProcessEnv
+
+		await recordUsageEvent(
+			{
+				commandPath: "task/show",
+				flagNames: [],
+				durationMs: 1,
+				outcome: "success",
+				outcomeCode: "SUCCESS",
+				exitStatus: 0,
+			},
+			"1.2.3",
+			env,
+		)
+
+		expect(await exportUsageEvents(env)).toEqual([
+			expect.objectContaining({ commandPath: "task/show", version: 2 }),
+		])
+	})
 })

package/src/usage-log.ts

@@ -1,21 +1,92 @@
 import { Database } from "bun:sqlite"
+import { createHash } from "node:crypto"
 import { mkdir } from "node:fs/promises"
 import { dirname, join } from "node:path"
 
 const USAGE_EVENT_VERSION = 2 as const
 const DEFAULT_RETENTION_DAYS = 90
 
+const INVOCATION_SOURCES = new Set(["human", "agent", "automation"])
+const USAGE_EVENT_COLUMNS = new Set([
+	"id",
+	"event_version",
+	"journey_id",
+	"journey_sequence",
+	"invocation_source",
+	"is_test",
+	"occurred_at",
+	"agency_version",
+	"command_path",
+	"flag_names",
+	"duration_ms",
+	"outcome",
+	"outcome_code",
+	"exit_status",
+	"vcs",
+	"terminal_stage",
+	"category",
+])
+
+export type UsageOutcomeCode =
+	| "SUCCESS"
+	| "NONZERO_EXIT"
+	| "CLI_USAGE"
+	| "WORKBASE_NOT_FOUND"
+	| "WORKBASE_INVALID"
+	| "VALIDATION_FAILED"
+	| "CONFLICT"
+	| "FILESYSTEM_ERROR"
+	| "PROCESS_ERROR"
+	| "COMMAND_FAILED"
+
 export interface UsageEvent {
 	readonly commandPath: string
 	readonly flagNames: readonly string[]
 	readonly durationMs: number
 	readonly exitStatus: number
 	readonly outcome: "success" | "failure"
+	readonly outcomeCode: UsageOutcomeCode
 	readonly vcs?: "git"
 	readonly terminalStage?: string
 	readonly category?: string
 }
 
+export const usageOutcomeCode = (error: unknown): UsageOutcomeCode => {
+	const tag =
+		typeof error === "object" &&
+		error !== null &&
+		"_tag" in error &&
+		typeof error._tag === "string"
+			? error._tag
+			: error instanceof Error
+				? error.name
+				: undefined
+	switch (tag) {
+		case "CliUsageError":
+			return "CLI_USAGE"
+		case "WorkbaseNotFoundError":
+			return "WORKBASE_NOT_FOUND"
+		case "WorkbaseConfigError":
+		case "WorkbaseRegistryError":
+		case "FrontmatterParseError":
+			return "WORKBASE_INVALID"
+		case "ValidationFailedError":
+			return "VALIDATION_FAILED"
+		case "ClaimConflictError":
+		case "ClaimOwnershipError":
+		case "RevisionConflictError":
+		case "ExecutionGuardError":
+			return "CONFLICT"
+		case "FileNotFoundError":
+		case "FileSystemError":
+			return "FILESYSTEM_ERROR"
+		case "ProcessError":
+			return "PROCESS_ERROR"
+		default:
+			return "COMMAND_FAILED"
+	}
+}
+
 const stateDirectory = (env: NodeJS.ProcessEnv) =>
 	env.XDG_STATE_HOME ?? join(env.HOME ?? ".", ".local", "state")
 
@@ -32,36 +103,68 @@ const retentionDays = (env: NodeJS.ProcessEnv) => {
 		: DEFAULT_RETENTION_DAYS
 }
 
+const invocationSource = (env: NodeJS.ProcessEnv) => {
+	const source = env.AGENCY_INVOCATION_SOURCE?.toLowerCase()
+	if (source && INVOCATION_SOURCES.has(source)) return source
+	return env.AGENCY_SESSION_ID ? "agent" : "human"
+}
+
+const isTestInvocation = (env: NodeJS.ProcessEnv) =>
+	["1", "true", "yes"].includes((env.AGENCY_USAGE_TEST ?? "").toLowerCase())
+
+const journeyId = (env: NodeJS.ProcessEnv) => {
+	if (!env.AGENCY_SESSION_ID) return null
+	return `sha256:${createHash("sha256").update(env.AGENCY_SESSION_ID).digest("hex")}`
+}
+
+const pruneExpiredEvents = (database: Database, env: NodeJS.ProcessEnv) => {
+	database
+		.query(
+			"DELETE FROM usage_events WHERE datetime(occurred_at) < datetime('now', ?)",
+		)
+		.run(`-${retentionDays(env)} days`)
+}
+
 const openDatabase = async (env: NodeJS.ProcessEnv) => {
 	const path = usageDatabasePath(env)
 	await mkdir(dirname(path), { recursive: true, mode: 0o700 })
 	const database = new Database(path, { create: true, strict: true })
 	database.run("PRAGMA journal_mode = WAL")
 	database.run("PRAGMA busy_timeout = 1000")
+	const existingColumns = database
+		.query("PRAGMA table_info(usage_events)")
+		.all() as { name: string }[]
+	if (
+		existingColumns.length > 0 &&
+		(existingColumns.length !== USAGE_EVENT_COLUMNS.size ||
+			existingColumns.some(({ name }) => !USAGE_EVENT_COLUMNS.has(name)))
+	) {
+		// Version 1 could contain positional values. Do not preserve unsafe telemetry.
+		database.run("DROP TABLE usage_events")
+	}
 	database.run(`
 		CREATE TABLE IF NOT EXISTS usage_events (
 			id INTEGER PRIMARY KEY AUTOINCREMENT,
 			event_version INTEGER NOT NULL,
-			session_id TEXT NOT NULL,
-			session_sequence INTEGER NOT NULL,
+			journey_id TEXT,
+			journey_sequence INTEGER,
+			invocation_source TEXT NOT NULL,
+			is_test INTEGER NOT NULL,
 			occurred_at TEXT NOT NULL,
 			agency_version TEXT NOT NULL,
 			command_path TEXT NOT NULL,
 			flag_names TEXT NOT NULL,
 			duration_ms INTEGER NOT NULL,
 			outcome TEXT NOT NULL,
-			exit_status INTEGER NOT NULL
+			outcome_code TEXT NOT NULL,
+			exit_status INTEGER NOT NULL,
+			vcs TEXT,
+			terminal_stage TEXT,
+			category TEXT
 		)
 	`)
-	for (const column of ["vcs", "terminal_stage", "category"]) {
-		try {
-			database.run(`ALTER TABLE usage_events ADD COLUMN ${column} TEXT`)
-		} catch {
-			// Existing databases already have migrated columns.
-		}
-	}
 	database.run(
-		"CREATE INDEX IF NOT EXISTS usage_events_session ON usage_events(session_id, session_sequence)",
+		"CREATE INDEX IF NOT EXISTS usage_events_journey ON usage_events(journey_id, journey_sequence)",
 	)
 	database.run(
 		"CREATE INDEX IF NOT EXISTS usage_events_command ON usage_events(command_path, occurred_at)",
@@ -78,42 +181,42 @@ export async function recordUsageEvent(
 	let database: Database | undefined
 	try {
 		database = await openDatabase(env)
-		const sessionId = env.AGENCY_SESSION_ID || `process-${process.pid}`
+		pruneExpiredEvents(database, env)
+		const eventJourneyId = journeyId(env)
 		database
 			.query(`
 					INSERT INTO usage_events (
-						event_version, session_id, session_sequence, occurred_at,
+						event_version, journey_id, journey_sequence,
+						invocation_source, is_test, occurred_at,
 						agency_version, command_path, flag_names, duration_ms,
-						outcome, exit_status, vcs, terminal_stage, category
+						outcome, outcome_code, exit_status, vcs, terminal_stage, category
 					) VALUES (
 						?, ?,
-						(SELECT COALESCE(MAX(session_sequence), 0) + 1 FROM usage_events WHERE session_id = ?),
-						?, ?, ?, ?, ?, ?, ?, ?, ?, ?
+						CASE WHEN ? IS NULL THEN NULL ELSE
+							(SELECT COALESCE(MAX(journey_sequence), 0) + 1 FROM usage_events WHERE journey_id = ?)
+						END,
+						?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
 					)
 				`)
 			.run(
 				USAGE_EVENT_VERSION,
-				sessionId,
-				sessionId,
+				eventJourneyId,
+				eventJourneyId,
+				eventJourneyId,
+				invocationSource(env),
+				isTestInvocation(env) ? 1 : 0,
 				new Date().toISOString(),
 				agencyVersion,
 				event.commandPath,
 				JSON.stringify([...new Set(event.flagNames)].sort()),
 				Math.max(0, Math.round(event.durationMs)),
 				event.outcome,
+				event.outcomeCode,
 				event.exitStatus,
 				event.vcs ?? null,
 				event.terminalStage ?? null,
 				event.category ?? null,
 			)
-		if (Math.random() < 0.01) {
-			const days = retentionDays(env)
-			database
-				.query(
-					"DELETE FROM usage_events WHERE occurred_at < datetime('now', ?)",
-				)
-				.run(`-${days} days`)
-		}
 	} catch {
 		// Usage logging must never affect command behavior.
 	} finally {
@@ -128,24 +231,29 @@ export async function exportUsageEvents(
 	let database: Database | undefined
 	try {
 		database = await openDatabase(env)
+		pruneExpiredEvents(database, env)
 		const rows = database
 			.query(`
-				SELECT event_version, session_id, session_sequence, occurred_at,
+				SELECT event_version, journey_id, journey_sequence,
+					invocation_source, is_test, occurred_at,
 					agency_version, command_path, flag_names, duration_ms,
-					outcome, exit_status, vcs, terminal_stage, category
+					outcome, outcome_code, exit_status, vcs, terminal_stage, category
 				FROM usage_events ORDER BY occurred_at, id
 			`)
-			.all() as Record<string, string | number>[]
+			.all() as Record<string, string | number | null>[]
 		return rows.map((row) => ({
 			version: row.event_version,
-			sessionId: row.session_id,
-			sessionSequence: row.session_sequence,
+			journeyId: row.journey_id,
+			journeySequence: row.journey_sequence,
+			invocationSource: row.invocation_source,
+			isTest: row.is_test === 1,
 			occurredAt: row.occurred_at,
 			agencyVersion: row.agency_version,
 			commandPath: row.command_path,
 			flagNames: JSON.parse(String(row.flag_names)),
 			durationMs: row.duration_ms,
 			outcome: row.outcome,
+			outcomeCode: row.outcome_code,
 			exitStatus: row.exit_status,
 			...(row.vcs == null ? {} : { vcs: row.vcs }),
 			...(row.terminal_stage == null

package/src/workbase/agent-command.test.ts

@@ -114,6 +114,7 @@ describe("agent commands", () => {
 
 		expect(environment).toMatchObject({
 			AGENCY_AGENT: "custom",
+			AGENCY_INVOCATION_SOURCE: "agent",
 			AGENCY_SESSION_ID: "session-1",
 			AGENCY_WORKBASE: "/workbase",
 			AGENCY_TARGET: "execution-unit:phase/task/build",

package/src/workbase/agent-command.ts

@@ -118,6 +118,7 @@ export const agentEnvironment = (
 	variables: AgentCommandVariables,
 ): Record<string, string> => ({
 	AGENCY_AGENT: agent,
+	AGENCY_INVOCATION_SOURCE: "agent",
 	AGENCY_SESSION_ID: variables.sessionId,
 	AGENCY_WORKBASE: variables.workbase,
 	AGENCY_TARGET: variables.target,

package/src/workbase/opencode-plugin-file.ts

@@ -195,6 +195,7 @@ const plugin: Plugin = async ({ directory }) => {
       if (!sessionID) return
       const context = workerSessions.get(sessionID)
       if (!context?.target) return
+      output.env.AGENCY_INVOCATION_SOURCE = "agent"
       output.env.AGENCY_SESSION_ID = sessionID
       output.env.AGENCY_TARGET = context.target
       if (context.root) output.env.AGENCY_WORKBASE = context.root