@os-eco/overstory-cli 0.9.4 → 0.11.0

package/src/commands/group.test.ts

@@ -20,6 +20,7 @@ import {
 	loadGroups,
 	printGroupProgress,
 	removeFromGroup,
+	resolveGroup,
 } from "./group.ts";
 
 let tempDir: string;
@@ -379,3 +380,96 @@ describe("printGroupProgress", () => {
 		expect(output).toContain("2026-01-15T10:00:00.000Z");
 	});
 });
+
+// -- resolveGroup --
+
+describe("resolveGroup", () => {
+	test("resolves by exact UUID", () => {
+		const a = makeGroup({ id: "group-aaaaaaaa", name: "alpha" });
+		const b = makeGroup({ id: "group-bbbbbbbb", name: "beta" });
+		expect(resolveGroup([a, b], "group-aaaaaaaa")).toBe(a);
+	});
+
+	test("resolves by unique name", () => {
+		const a = makeGroup({ id: "group-aaaaaaaa", name: "alpha" });
+		const b = makeGroup({ id: "group-bbbbbbbb", name: "beta" });
+		expect(resolveGroup([a, b], "beta")).toBe(b);
+	});
+
+	test("ID match wins when name === some-other-group's-id", () => {
+		const a = makeGroup({ id: "group-aaaaaaaa", name: "group-bbbbbbbb" });
+		const b = makeGroup({ id: "group-bbbbbbbb", name: "beta" });
+		expect(resolveGroup([a, b], "group-bbbbbbbb")).toBe(b);
+	});
+
+	test("name match prefers the active group when others are completed", () => {
+		const old = makeGroup({ id: "group-aaaaaaaa", name: "dup", status: "completed" });
+		const live = makeGroup({ id: "group-bbbbbbbb", name: "dup", status: "active" });
+		expect(resolveGroup([old, live], "dup")).toBe(live);
+	});
+
+	test("ambiguous when multiple active groups share a name", () => {
+		const x = makeGroup({ id: "group-aaaaaaaa", name: "dup", status: "active" });
+		const y = makeGroup({ id: "group-bbbbbbbb", name: "dup", status: "active" });
+		expect(() => resolveGroup([x, y], "dup")).toThrow(GroupError);
+		try {
+			resolveGroup([x, y], "dup");
+		} catch (err) {
+			expect(err).toBeInstanceOf(GroupError);
+			const message = (err as GroupError).message;
+			expect(message).toContain("ambiguous");
+			expect(message).toContain("group-aaaaaaaa");
+			expect(message).toContain("group-bbbbbbbb");
+		}
+	});
+
+	test("ambiguous when zero active groups share the name", () => {
+		const x = makeGroup({ id: "group-aaaaaaaa", name: "dup", status: "completed" });
+		const y = makeGroup({ id: "group-bbbbbbbb", name: "dup", status: "completed" });
+		expect(() => resolveGroup([x, y], "dup")).toThrow(GroupError);
+	});
+
+	test("throws not-found for unknown identifier", () => {
+		const a = makeGroup({ id: "group-aaaaaaaa", name: "alpha" });
+		expect(() => resolveGroup([a], "nope")).toThrow(/not found/);
+	});
+});
+
+// -- name-or-id lookup in addToGroup / removeFromGroup --
+
+describe("name-or-id lookup", () => {
+	test("addToGroup resolves by name", async () => {
+		const group = makeGroup({ id: "group-aaaaaaaa", name: "alpha", memberIssueIds: ["i1"] });
+		await writeGroups([group]);
+		const tracker = stubTrackerOk();
+		const updated = await addToGroup(tempDir, "alpha", ["i2"], false, tracker);
+		expect(updated.id).toBe("group-aaaaaaaa");
+		expect(updated.memberIssueIds).toEqual(["i1", "i2"]);
+	});
+
+	test("removeFromGroup resolves by name", async () => {
+		const group = makeGroup({ id: "group-aaaaaaaa", name: "alpha", memberIssueIds: ["i1", "i2"] });
+		await writeGroups([group]);
+		const updated = await removeFromGroup(tempDir, "alpha", ["i2"]);
+		expect(updated.id).toBe("group-aaaaaaaa");
+		expect(updated.memberIssueIds).toEqual(["i1"]);
+	});
+});
+
+function stubTrackerOk(): import("../tracker/types.ts").TrackerClient {
+	return {
+		ready: async () => [],
+		show: async (id: string): Promise<TrackerIssue> => ({
+			id,
+			title: id,
+			status: "open",
+			priority: 2,
+			type: "task",
+		}),
+		create: async () => "stub-id",
+		claim: async () => undefined,
+		close: async () => undefined,
+		list: async () => [],
+		sync: async () => undefined,
+	};
+}

package/src/commands/group.ts

@@ -79,6 +79,44 @@ function generateGroupId(): string {
 	return `group-${crypto.randomUUID().slice(0, 8)}`;
 }
 
+/**
+ * Resolve a group by ID or name.
+ *
+ * Names are not enforced unique by `createGroup`, so live `groups.json` files
+ * contain duplicate names — a naive name lookup would silently pick the wrong
+ * group. Resolution precedence:
+ *   1. Exact ID match wins (UUIDs are unambiguous).
+ *   2. Otherwise filter by name. If exactly one match, return it.
+ *   3. If multiple name matches, prefer a single `active` one. If still
+ *      ambiguous, throw with the matching IDs so the caller can disambiguate
+ *      by passing the UUID.
+ *
+ * @internal Exported for testing.
+ */
+export function resolveGroup(groups: TaskGroup[], identifier: string): TaskGroup {
+	const byId = groups.find((g) => g.id === identifier);
+	if (byId) return byId;
+
+	const byName = groups.filter((g) => g.name === identifier);
+	if (byName.length === 1) {
+		const only = byName[0];
+		if (only) return only;
+	}
+	if (byName.length > 1) {
+		const active = byName.filter((g) => g.status === "active");
+		if (active.length === 1) {
+			const only = active[0];
+			if (only) return only;
+		}
+		const ids = byName.map((g) => g.id).join(", ");
+		throw new GroupError(
+			`Group name "${identifier}" is ambiguous (matches: ${ids}). Use the group ID.`,
+			{ groupId: identifier },
+		);
+	}
+	throw new GroupError(`Group "${identifier}" not found`, { groupId: identifier });
+}
+
 /**
  * Create a new task group.
  * @internal Exported for testing.
@@ -140,16 +178,13 @@ export async function addToGroup(
 	}
 
 	const groups = await loadGroups(projectRoot);
-	const group = groups.find((g) => g.id === groupId);
-	if (!group) {
-		throw new GroupError(`Group "${groupId}" not found`, { groupId });
-	}
+	const group = resolveGroup(groups, groupId);
 
 	// Check for duplicates against existing members
 	for (const id of issueIds) {
 		if (group.memberIssueIds.includes(id)) {
-			throw new GroupError(`Issue "${id}" is already a member of group "${groupId}"`, {
-				groupId,
+			throw new GroupError(`Issue "${id}" is already a member of group "${group.id}"`, {
+				groupId: group.id,
 			});
 		}
 	}
@@ -187,16 +222,13 @@ export async function removeFromGroup(
 	}
 
 	const groups = await loadGroups(projectRoot);
-	const group = groups.find((g) => g.id === groupId);
-	if (!group) {
-		throw new GroupError(`Group "${groupId}" not found`, { groupId });
-	}
+	const group = resolveGroup(groups, groupId);
 
 	// Validate all issues are members
 	for (const id of issueIds) {
 		if (!group.memberIssueIds.includes(id)) {
-			throw new GroupError(`Issue "${id}" is not a member of group "${groupId}"`, {
-				groupId,
+			throw new GroupError(`Issue "${id}" is not a member of group "${group.id}"`, {
+				groupId: group.id,
 			});
 		}
 	}
@@ -204,7 +236,7 @@ export async function removeFromGroup(
 	// Check that removal won't empty the group
 	const remaining = group.memberIssueIds.filter((id) => !issueIds.includes(id));
 	if (remaining.length === 0) {
-		throw new GroupError("Cannot remove all issues from a group", { groupId });
+		throw new GroupError("Cannot remove all issues from a group", { groupId: group.id });
 	}
 
 	group.memberIssueIds = remaining;
@@ -347,7 +379,7 @@ export function createGroupCommand(): Command {
 	cmd
 		.command("status")
 		.description("Show progress for one or all groups")
-		.argument("[group-id]", "Group ID (optional, shows all if omitted)")
+		.argument("[group-id-or-name]", "Group ID or name (optional, shows all if omitted)")
 		.option("--json", "Output as JSON")
 		.option("--skip-validation", "Skip task validation (for offline use)")
 		.action(
@@ -361,10 +393,7 @@ export function createGroupCommand(): Command {
 				const groups = await loadGroups(projectRoot);
 
 				if (groupId) {
-					const group = groups.find((g) => g.id === groupId);
-					if (!group) {
-						throw new GroupError(`Group "${groupId}" not found`, { groupId });
-					}
+					const group = resolveGroup(groups, groupId);
 					const progress = await getGroupProgress(projectRoot, group, groups, tracker);
 					if (json) {
 						jsonOutput("group status", { ...progress });
@@ -401,7 +430,7 @@ export function createGroupCommand(): Command {
 	cmd
 		.command("add")
 		.description("Add issues to a group")
-		.argument("<group-id>", "Group ID")
+		.argument("<group-id-or-name>", "Group ID or name")
 		.argument("<ids...>", "Issue IDs to add")
 		.option("--json", "Output as JSON")
 		.option("--skip-validation", "Skip task validation (for offline use)")
@@ -437,7 +466,7 @@ export function createGroupCommand(): Command {
 	cmd
 		.command("remove")
 		.description("Remove issues from a group")
-		.argument("<group-id>", "Group ID")
+		.argument("<group-id-or-name>", "Group ID or name")
 		.argument("<ids...>", "Issue IDs to remove")
 		.option("--json", "Output as JSON")
 		.action(async (groupId: string, ids: string[], opts: { json?: boolean }) => {

package/src/commands/init.test.ts

@@ -353,6 +353,14 @@ describe("initCommand: canonical branch detection", () => {
 		const content = await Bun.file(configPath).text();
 		expect(content).toContain("canonicalBranch: main");
 	});
+
+	test("generated config opts into headless Claude by default (overstory-caec)", async () => {
+		await initCommand({ _spawner: noopSpawner });
+
+		const configPath = join(tempDir, ".overstory", "config.yaml");
+		const content = await Bun.file(configPath).text();
+		expect(content).toContain("claudeHeadlessByDefault: true");
+	});
 });
 
 describe("initCommand: --yes flag", () => {

package/src/commands/init.ts

@@ -816,6 +816,10 @@ export async function initCommand(opts: InitOptions): Promise<void> {
 	config.project.canonicalBranch = canonicalBranch;
 	if (config.runtime) {
 		config.runtime.default = defaultRuntime;
+		// New projects default to headless Claude spawns; the UI (`ov serve`) is the
+		// primary operator surface and tmux is opt-in via `--no-headless`. Existing
+		// projects keep tmux until they edit their config (overstory-caec).
+		config.runtime.claudeHeadlessByDefault = true;
 	}
 
 	const configYaml = serializeConfigToYaml(config);
@@ -956,5 +960,8 @@ export async function initCommand(opts: InitOptions): Promise<void> {
 
 	printSuccess("Initialized");
 	printHint("Next: run `ov hooks install` to enable Claude Code hooks.");
-	printHint("Then: run `ov status` to see the current state.");
+	printHint("Then: `ov coordinator start` and `ov serve` — open http://localhost:7321");
+	printHint(
+		"       (UI is the primary operator surface; pass `--no-headless` to ov sling for tmux attach)",
+	);
 }

package/src/commands/log.test.ts

@@ -633,8 +633,55 @@ describe("logCommand", () => {
 		});
 	});
 
-	test("session-end writes pending-nudge marker for coordinator when lead completes", async () => {
-		// Create sessions.db with a lead agent
+	test("session-end does NOT transition lead to completed (persistent agent)", async () => {
+		// Regression test for overstory-49a7:
+		// The lead's Stop hook fires every turn (interactive Claude Code), not just at
+		// true session end. session-end must NOT mark leads completed, or they vanish
+		// from getActive() after their first turn while their tmux is still alive.
+		const dbPath = join(tempDir, ".overstory", "sessions.db");
+		const session: AgentSession = {
+			id: "session-lead",
+			agentName: "lead-alpha",
+			capability: "lead",
+			worktreePath: tempDir,
+			branchName: "lead-alpha-branch",
+			taskId: "bead-lead-001",
+			tmuxSession: "overstory-lead-alpha",
+			state: "working",
+			pid: 33333,
+			parentAgent: null,
+			depth: 0,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date(Date.now() - 60_000).toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		};
+		const store = createSessionStore(dbPath);
+		store.upsert(session);
+		store.close();
+
+		await logCommand(["session-end", "--agent", "lead-alpha"]);
+
+		// Lead should remain 'working', not transition to 'completed'
+		const readStore = createSessionStore(dbPath);
+		const updatedSession = readStore.getByName("lead-alpha");
+		readStore.close();
+
+		expect(updatedSession).toBeDefined();
+		expect(updatedSession?.state).toBe("working");
+		// But lastActivity should be updated
+		expect(new Date(updatedSession?.lastActivity ?? "").getTime()).toBeGreaterThan(
+			new Date(session.lastActivity).getTime(),
+		);
+	});
+
+	test("session-end does NOT write pending-nudge marker for leads (moved to ov stop)", async () => {
+		// Regression test for overstory-49a7:
+		// The lead_completed nudge used to fire from the per-turn Stop hook, spamming
+		// the coordinator with false completion signals every turn. It is now emitted
+		// only by `ov stop <lead>` (the real completion signal).
 		const dbPath = join(tempDir, ".overstory", "sessions.db");
 		const session: AgentSession = {
 			id: "session-lead",
@@ -661,17 +708,10 @@ describe("logCommand", () => {
 
 		await logCommand(["session-end", "--agent", "lead-alpha"]);
 
-		// Verify the pending-nudge marker was written for the coordinator
+		// No pending-nudge marker should be written from session-end
 		const markerPath = join(tempDir, ".overstory", "pending-nudges", "coordinator.json");
 		const markerFile = Bun.file(markerPath);
-		expect(await markerFile.exists()).toBe(true);
-
-		const marker = JSON.parse(await markerFile.text());
-		expect(marker.from).toBe("lead-alpha");
-		expect(marker.reason).toBe("lead_completed");
-		expect(marker.subject).toContain("lead-alpha");
-		expect(marker.messageId).toContain("auto-nudge-lead-alpha-");
-		expect(marker.createdAt).toBeDefined();
+		expect(await markerFile.exists()).toBe(false);
 	});
 
 	test("session-end does NOT write pending-nudge marker for non-lead agents", async () => {
@@ -1259,6 +1299,81 @@ describe("logCommand", () => {
 		expect(mail?.body).toContain("10 tool calls");
 		expect(mail?.body).toContain("pattern"); // At least 1 pattern insight
 	});
+
+	test("threads outcomeStatus into per-domain reference and per-insight records", async () => {
+		const learnResult: MulchLearnResult = {
+			success: true,
+			command: "mulch learn",
+			changedFiles: ["src/foo.ts"],
+			suggestedDomains: ["typescript"],
+			unmatchedFiles: [],
+		};
+		const { client, recordCalls } = createFakeMulchClient(learnResult);
+		const mailDbPath = join(tempDir, ".overstory", "auto-record-outcome.db");
+
+		// Seed events so analyzer emits at least one insight (10+ tool calls).
+		const eventsDbPath = join(tempDir, ".overstory", "events.db");
+		const eventStore = createEventStore(eventsDbPath);
+		const sessionStartedAt = new Date(Date.now() - 60_000).toISOString();
+		for (let i = 0; i < 10; i++) {
+			eventStore.insert({
+				runId: null,
+				agentName: "outcome-agent",
+				sessionId: "sess-outcome",
+				eventType: "tool_start",
+				toolName: "Read",
+				toolArgs: JSON.stringify({ file_path: `/src/file${i}.ts` }),
+				toolDurationMs: null,
+				level: "info",
+				data: JSON.stringify({ summary: `read: /src/file${i}.ts` }),
+			});
+		}
+		eventStore.close();
+
+		await autoRecordExpertise({
+			mulchClient: client,
+			agentName: "outcome-agent",
+			capability: "builder",
+			taskId: "bead-outcome",
+			mailDbPath,
+			parentAgent: "parent-agent",
+			projectRoot: tempDir,
+			sessionStartedAt,
+			outcomeStatus: "partial",
+		});
+
+		expect(recordCalls.length).toBeGreaterThanOrEqual(2);
+		for (const call of recordCalls) {
+			expect(call.options.outcomeStatus).toBe("partial");
+			expect(call.options.outcomeAgent).toBe("outcome-agent");
+		}
+	});
+
+	test("omits outcomeStatus when caller does not supply one", async () => {
+		const learnResult: MulchLearnResult = {
+			success: true,
+			command: "mulch learn",
+			changedFiles: ["src/foo.ts"],
+			suggestedDomains: ["typescript"],
+			unmatchedFiles: [],
+		};
+		const { client, recordCalls } = createFakeMulchClient(learnResult);
+		const mailDbPath = join(tempDir, ".overstory", "auto-record-no-outcome.db");
+
+		await autoRecordExpertise({
+			mulchClient: client,
+			agentName: "no-outcome-agent",
+			capability: "builder",
+			taskId: null,
+			mailDbPath,
+			parentAgent: null,
+			projectRoot: tempDir,
+			sessionStartedAt: new Date().toISOString(),
+		});
+
+		expect(recordCalls).toHaveLength(1);
+		expect(recordCalls[0]?.options.outcomeStatus).toBeUndefined();
+	});
 });
 
 /**
@@ -1312,6 +1427,10 @@ try {
 			stdin: "pipe",
 			stdout: "pipe",
 			stderr: "pipe",
+			// Pin project root to tempDir. Without this, a subprocess started from
+			// inside an `ov sling`-spawned worktree inherits OVERSTORY_PROJECT_ROOT
+			// pointing at the parent project, and writes events to prod's events.db.
+			env: { ...process.env, OVERSTORY_PROJECT_ROOT: tempDir },
 		});
 
 		// Write the JSON payload to stdin and close
@@ -1501,6 +1620,7 @@ try {
 			stdin: "pipe",
 			stdout: "pipe",
 			stderr: "pipe",
+			env: { ...process.env, OVERSTORY_PROJECT_ROOT: tempDir },
 		});
 
 		// Write empty string and close immediately
@@ -1734,4 +1854,60 @@ describe("appendOutcomeToAppliedRecords", () => {
 		});
 		expect(count).toBe(0);
 	});
+
+	test("uses supplied outcomeStatus when provided", async () => {
+		const agentDir = join(tempDir, ".overstory", "agents", "test-agent");
+		await mkdir(agentDir, { recursive: true });
+		await Bun.write(
+			join(agentDir, "applied-records.json"),
+			JSON.stringify({
+				taskId: "bead-outcome",
+				agentName: "test-agent",
+				capability: "builder",
+				records: [{ id: "mx-aaa111", domain: "agents" }],
+			}),
+		);
+
+		const { client, appendOutcomeCalls } = makeOutcomeClient();
+		await appendOutcomeToAppliedRecords({
+			mulchClient: client,
+			agentName: "test-agent",
+			capability: "builder",
+			taskId: "bead-outcome",
+			projectRoot: tempDir,
+			outcomeStatus: "failure",
+		});
+
+		expect(appendOutcomeCalls).toHaveLength(1);
+		expect(appendOutcomeCalls[0]?.outcome).toMatchObject({ status: "failure" });
+		expect(appendOutcomeCalls[0]?.outcome.notes).toContain("Quality gates: failure");
+	});
+
+	test("falls back to 'success' when outcomeStatus is undefined (backward compat)", async () => {
+		const agentDir = join(tempDir, ".overstory", "agents", "test-agent");
+		await mkdir(agentDir, { recursive: true });
+		await Bun.write(
+			join(agentDir, "applied-records.json"),
+			JSON.stringify({
+				taskId: "bead-default",
+				agentName: "test-agent",
+				capability: "builder",
+				records: [{ id: "mx-bbb222", domain: "agents" }],
+			}),
+		);
+
+		const { client, appendOutcomeCalls } = makeOutcomeClient();
+		await appendOutcomeToAppliedRecords({
+			mulchClient: client,
+			agentName: "test-agent",
+			capability: "builder",
+			taskId: "bead-default",
+			projectRoot: tempDir,
+		});
+
+		expect(appendOutcomeCalls).toHaveLength(1);
+		expect(appendOutcomeCalls[0]?.outcome.status).toBe("success");
+		// No "Quality gates:" annotation when caller didn't provide outcomeStatus
+		expect(appendOutcomeCalls[0]?.outcome.notes).not.toContain("Quality gates:");
+	});
 });