@os-eco/overstory-cli 0.9.4 → 0.11.0

package/src/commands/log.ts

@@ -12,12 +12,14 @@
 
 import { join } from "node:path";
 import { Command } from "commander";
+import { isStopHookPersistentCapability } from "../agents/capabilities.ts";
 import { updateIdentity } from "../agents/identity.ts";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
 import { filterToolArgs } from "../events/tool-filter.ts";
 import { analyzeSessionInsights } from "../insights/analyzer.ts";
+import { hasWorkToVerify, runQualityGates } from "../insights/quality-gates.ts";
 import { createLogger } from "../logging/logger.ts";
 import { createMailClient } from "../mail/client.ts";
 import { createMailStore } from "../mail/store.ts";
@@ -66,8 +68,12 @@ function updateLastActivity(projectRoot: string, agentName: string): void {
 			const session = store.getByName(agentName);
 			if (session) {
 				store.updateLastActivity(agentName);
-				if (session.state === "booting" || session.state === "zombie") {
-					store.updateState(agentName, "working");
+				// Tool-use observed: try booting → working. Matrix-guarded so a
+				// zombie classification (set by watchdog) is NOT silently revived
+				// here — that revival was a contributor to the schizophrenic
+				// state=zombie + tool-use-active symptom in overstory-a993.
+				if (session.state === "booting") {
+					store.tryTransitionState(agentName, "working");
 				}
 			}
 		} finally {
@@ -79,63 +85,144 @@ function updateLastActivity(projectRoot: string, agentName: string): void {
 }
 
 /**
- * Agent capabilities that run as persistent interactive sessions.
- * The Stop hook fires every turn for these agents (not just at session end),
- * so they must NOT auto-transition to 'completed' on session-end events.
+ * Maximum retry attempts for the session-end transition.
+ *
+ * The Stop hook is the only signal that turns sessions.db state from
+ * "working" to "completed" for headless legacy paths and tmux sessions.
+ * If it loses that signal due to a transient SQLite contention error
+ * (e.g. "database is locked" while the watchdog ticks against the same
+ * file), the row stays in "working" forever and the watchdog later
+ * promotes it to "zombie". Retrying with exponential backoff lets brief
+ * lock contention resolve before we give up. (overstory-e74b)
  */
-const PERSISTENT_CAPABILITIES = new Set(["coordinator", "orchestrator", "monitor"]);
+const TRANSITION_MAX_ATTEMPTS = 5;
+const TRANSITION_BACKOFF_BASE_MS = 50;
 
 /**
- * Transition agent state to 'completed' in the SessionStore.
- * Called when session-end event fires.
- *
- * Skips the transition for persistent agent types (coordinator, orchestrator, monitor)
- * whose Stop hook fires every turn, not just at true session end.
+ * One attempt at the session-end state transition.
  *
- * Non-fatal: silently ignores errors to avoid breaking hook execution.
+ * Throws on transient failures (e.g. SQLite "database is locked") so the
+ * caller can retry. The body is the original logic from
+ * `transitionToCompleted`.
  */
-function transitionToCompleted(projectRoot: string, agentName: string): void {
+function transitionToCompletedOnce(projectRoot: string, agentName: string): void {
+	const overstoryDir = join(projectRoot, ".overstory");
+	const { store } = openSessionStore(overstoryDir);
 	try {
-		const overstoryDir = join(projectRoot, ".overstory");
-		const { store } = openSessionStore(overstoryDir);
-		try {
-			const session = store.getByName(agentName);
-			if (session && PERSISTENT_CAPABILITIES.has(session.capability)) {
-				// Check if a persistent top-level agent self-exited by verifying the run
-				// is already completed.
-				// If `ov run complete` was called before session-end, the run status is 'completed'
-				// and we should transition the persistent session to completed too.
-				if (
-					(session.capability === "coordinator" || session.capability === "orchestrator") &&
-					session.runId
-				) {
-					const runStore = createRunStore(join(overstoryDir, "sessions.db"));
-					try {
-						const run = runStore.getRun(session.runId);
-						if (run && run.status === "completed") {
-							// Self-exit: the persistent agent called ov run complete before session ended
-							store.updateState(agentName, "completed");
-							store.updateLastActivity(agentName);
-							return;
-						}
-					} finally {
-						runStore.close();
+		const session = store.getByName(agentName);
+		if (session && isStopHookPersistentCapability(session.capability)) {
+			// Check if a persistent top-level agent self-exited by verifying the run
+			// is already completed.
+			// If `ov run complete` was called before session-end, the run status is 'completed'
+			// and we should transition the persistent session to completed too.
+			if (
+				(session.capability === "coordinator" || session.capability === "orchestrator") &&
+				session.runId
+			) {
+				const runStore = createRunStore(join(overstoryDir, "sessions.db"));
+				try {
+					const run = runStore.getRun(session.runId);
+					if (run && run.status === "completed") {
+						// Self-exit: the persistent agent called ov run complete before session ended
+						store.updateState(agentName, "completed");
+						store.updateLastActivity(agentName);
+						return;
 					}
+				} finally {
+					runStore.close();
 				}
-				// Normal persistent agent: only update activity, don't mark completed
-				store.updateLastActivity(agentName);
-				return;
 			}
-			store.updateState(agentName, "completed");
+			// Normal persistent agent: only update activity, don't mark completed
 			store.updateLastActivity(agentName);
+			return;
+		}
+		store.updateState(agentName, "completed");
+		store.updateLastActivity(agentName);
+	} finally {
+		store.close();
+	}
+}
+
+/**
+ * Best-effort: log a session-end hook failure to events.db so it surfaces in
+ * `ov errors` and trace timelines. Swallows secondary errors (events.db may
+ * also be locked when the primary write failed).
+ */
+async function logHookFailure(
+	projectRoot: string,
+	agentName: string,
+	hookName: string,
+	error: unknown,
+	attempts: number,
+): Promise<void> {
+	try {
+		const eventsDbPath = join(projectRoot, ".overstory", "events.db");
+		const eventStore = createEventStore(eventsDbPath);
+		try {
+			eventStore.insert({
+				runId: null,
+				agentName,
+				sessionId: null,
+				eventType: "error",
+				toolName: null,
+				toolArgs: null,
+				toolDurationMs: null,
+				level: "error",
+				data: JSON.stringify({
+					hook: hookName,
+					attempts,
+					message: error instanceof Error ? error.message : String(error),
+				}),
+			});
 		} finally {
-			store.close();
+			eventStore.close();
 		}
 	} catch {
-		// Non-fatal: don't break logging if session update fails
+		// Non-fatal: events.db may also be unavailable when the primary write failed.
 	}
 }
 
+/**
+ * Transition agent state to 'completed' in the SessionStore.
+ * Called when session-end event fires.
+ *
+ * Retries on transient SQLite contention with exponential backoff
+ * (50/100/200/400/800ms). On persistent failure, records an `error` event
+ * to events.db so the missed signal shows up in observability tooling and
+ * the watchdog's stale-but-tmux-dead fallback can recognize it.
+ * (overstory-e74b)
+ *
+ * Skips the transition for capabilities in `STOP_HOOK_PERSISTENT_CAPABILITIES`
+ * (coordinator, orchestrator, monitor, lead) whose Stop hook fires every model
+ * turn rather than once at true session end. See
+ * `src/agents/capabilities.ts` for the full rationale and consumer list.
+ *
+ * Non-fatal: silently ignores errors to avoid breaking hook execution.
+ */
+async function transitionToCompleted(projectRoot: string, agentName: string): Promise<void> {
+	let lastError: unknown;
+	for (let attempt = 0; attempt < TRANSITION_MAX_ATTEMPTS; attempt++) {
+		try {
+			transitionToCompletedOnce(projectRoot, agentName);
+			return;
+		} catch (err) {
+			lastError = err;
+			if (attempt < TRANSITION_MAX_ATTEMPTS - 1) {
+				await Bun.sleep(TRANSITION_BACKOFF_BASE_MS * 2 ** attempt);
+			}
+		}
+	}
+
+	// All retries failed — surface the missed signal via events.db.
+	await logHookFailure(
+		projectRoot,
+		agentName,
+		"session-end:transitionToCompleted",
+		lastError,
+		TRANSITION_MAX_ATTEMPTS,
+	);
+}
+
 /**
  * Look up an agent's session record.
  * Returns null if not found.
@@ -293,6 +380,7 @@ export async function autoRecordExpertise(params: {
 	parentAgent: string | null;
 	projectRoot: string;
 	sessionStartedAt: string;
+	outcomeStatus?: "success" | "partial" | "failure";
 }): Promise<string[]> {
 	const learnResult = await params.mulchClient.learn({ since: "HEAD~1" });
 	if (learnResult.suggestedDomains.length === 0) {
@@ -309,6 +397,8 @@ export async function autoRecordExpertise(params: {
 				description: `${params.capability} agent ${params.agentName} completed work in this domain. Files: ${filesList}`,
 				tags: ["auto-session-end", params.capability],
 				evidenceBead: params.taskId ?? undefined,
+				outcomeStatus: params.outcomeStatus,
+				outcomeAgent: params.agentName,
 			});
 			recordedDomains.push(domain);
 		} catch {
@@ -348,6 +438,8 @@ export async function autoRecordExpertise(params: {
 					description: insight.description,
 					tags: insight.tags,
 					evidenceBead: params.taskId ?? undefined,
+					outcomeStatus: params.outcomeStatus,
+					outcomeAgent: params.agentName,
 				});
 				if (!recordedDomains.includes(insight.domain)) {
 					recordedDomains.push(insight.domain);
@@ -414,6 +506,7 @@ export async function appendOutcomeToAppliedRecords(params: {
 	capability: string;
 	taskId: string | null;
 	projectRoot: string;
+	outcomeStatus?: "success" | "partial" | "failure";
 }): Promise<number> {
 	const appliedRecordsPath = join(
 		params.projectRoot,
@@ -436,10 +529,12 @@ export async function appendOutcomeToAppliedRecords(params: {
 	if (!records || records.length === 0) return 0;
 
 	const taskSuffix = params.taskId ? ` for task ${params.taskId}` : "";
+	const status: "success" | "partial" | "failure" = params.outcomeStatus ?? "success";
+	const gateNote = params.outcomeStatus ? ` Quality gates: ${params.outcomeStatus}.` : "";
 	const outcome = {
-		status: "success" as const,
+		status,
 		agent: params.agentName,
-		notes: `Applied by ${params.capability} agent ${params.agentName}${taskSuffix}. Session completed.`,
+		notes: `Applied by ${params.capability} agent ${params.agentName}${taskSuffix}. Session completed.${gateNote}`,
 	};
 
 	let appended = 0;
@@ -629,8 +724,9 @@ async function runLog(opts: {
 		}
 		case "session-end":
 			logger.info("session.end", { agentName: opts.agent });
-			// Transition agent state to completed
-			transitionToCompleted(config.project.root, opts.agent);
+			// Transition agent state to completed (with retry/backoff and
+			// events.db fallback on persistent failure — overstory-e74b).
+			await transitionToCompleted(config.project.root, opts.agent);
 			// Look up agent session for identity update and metrics recording
 			{
 				const agentSession = getAgentSession(config.project.root, opts.agent);
@@ -647,28 +743,6 @@ async function runLog(opts: {
 					// Non-fatal: identity may not exist for this agent
 				}
 
-				// Auto-nudge coordinator when a lead completes so it wakes up
-				// to process merge_ready / worker_done messages without waiting
-				// for user input (see decision mx-728f8d).
-				if (agentSession?.capability === "lead") {
-					try {
-						const nudgesDir = join(config.project.root, ".overstory", "pending-nudges");
-						const { mkdir } = await import("node:fs/promises");
-						await mkdir(nudgesDir, { recursive: true });
-						const markerPath = join(nudgesDir, "coordinator.json");
-						const marker = {
-							from: opts.agent,
-							reason: "lead_completed",
-							subject: `Lead ${opts.agent} completed — check mail for merge_ready/worker_done`,
-							messageId: `auto-nudge-${opts.agent}-${Date.now()}`,
-							createdAt: new Date().toISOString(),
-						};
-						await Bun.write(markerPath, `${JSON.stringify(marker, null, "\t")}\n`);
-					} catch {
-						// Non-fatal: nudge failure should not break session-end
-					}
-				}
-
 				// Record session metrics (with optional token data from transcript)
 				if (agentSession) {
 					// NOTE: We intentionally do NOT auto-complete the run here for coordinator agents.
@@ -728,9 +802,33 @@ async function runLog(opts: {
 						// Non-fatal: metrics recording should not break session-end handling
 					}
 
+					// Resolve outcome status from quality-gate results, threaded into
+					// every session-end mulch record write so confirmation scoring
+					// reflects whether tests/lint/typecheck actually passed.
+					let outcomeStatus: "success" | "partial" | "failure" | undefined;
+					if (!isStopHookPersistentCapability(agentSession.capability)) {
+						try {
+							let baseRef = "main";
+							const baseBranchPath = join(config.project.root, ".overstory", "session-branch.txt");
+							const baseFile = Bun.file(baseBranchPath);
+							if (await baseFile.exists()) {
+								const txt = (await baseFile.text()).trim();
+								if (txt.length > 0) baseRef = txt;
+							}
+							const hasWork = await hasWorkToVerify(agentSession.worktreePath, baseRef);
+							if (hasWork) {
+								const gates = config.project.qualityGates ?? [];
+								const outcome = await runQualityGates(gates, agentSession.worktreePath);
+								if (outcome) outcomeStatus = outcome.status;
+							}
+						} catch {
+							// Non-fatal: outcome status is optional
+						}
+					}
+
 					// Auto-record expertise via mulch learn + record (post-session).
 					// Skip persistent agents whose Stop hook fires every turn.
-					if (!PERSISTENT_CAPABILITIES.has(agentSession.capability)) {
+					if (!isStopHookPersistentCapability(agentSession.capability)) {
 						try {
 							const mulchClient = createMulchClient(config.project.root);
 							const mailDbPath = join(config.project.root, ".overstory", "mail.db");
@@ -743,6 +841,7 @@ async function runLog(opts: {
 								parentAgent: agentSession.parentAgent,
 								projectRoot: config.project.root,
 								sessionStartedAt: agentSession.startedAt,
+								outcomeStatus,
 							});
 						} catch {
 							// Non-fatal: mulch learn/record should not break session-end handling
@@ -751,7 +850,7 @@ async function runLog(opts: {
 
 					// Append outcomes to applied mulch records (outcome feedback loop).
 					// Reads applied-records.json written by sling.ts at spawn time.
-					if (!PERSISTENT_CAPABILITIES.has(agentSession.capability)) {
+					if (!isStopHookPersistentCapability(agentSession.capability)) {
 						try {
 							const mulchClient = createMulchClient(config.project.root);
 							await appendOutcomeToAppliedRecords({
@@ -760,6 +859,7 @@ async function runLog(opts: {
 								capability: agentSession.capability,
 								taskId,
 								projectRoot: config.project.root,
+								outcomeStatus,
 							});
 						} catch {
 							// Non-fatal

package/src/commands/mail.test.ts

@@ -118,6 +118,54 @@ describe("mailCommand", () => {
 			expect(output).toContain("Explore API");
 			expect(output).toContain("Total: 2 messages");
 		});
+
+		test("--type filters by message type", async () => {
+			// Add a typed message to the seeded inbox
+			const store = createMailStore(join(tempDir, ".overstory", "mail.db"));
+			const client = createMailClient(store);
+			client.send({
+				from: "lead-x",
+				to: "coordinator",
+				subject: "merge_ready: t1",
+				body: "ready to merge",
+				type: "merge_ready",
+			});
+			client.close();
+
+			await mailCommand(["list", "--type", "merge_ready"]);
+			expect(output).toContain("merge_ready: t1");
+			expect(output).not.toContain("Build task");
+			expect(output).not.toContain("Explore API");
+			expect(output).toContain("Total: 1 message");
+		});
+
+		test("--type combined with --from filters by both", async () => {
+			const store = createMailStore(join(tempDir, ".overstory", "mail.db"));
+			const client = createMailClient(store);
+			client.send({
+				from: "lead-x",
+				to: "coordinator",
+				subject: "merge_ready: t1",
+				body: "ready",
+				type: "merge_ready",
+			});
+			client.send({
+				from: "lead-y",
+				to: "coordinator",
+				subject: "merge_ready: t2",
+				body: "ready",
+				type: "merge_ready",
+			});
+			client.close();
+
+			await mailCommand(["list", "--from", "lead-x", "--type", "merge_ready"]);
+			expect(output).toContain("merge_ready: t1");
+			expect(output).not.toContain("merge_ready: t2");
+		});
+
+		test("--type rejects invalid type with ValidationError", async () => {
+			await expect(mailCommand(["list", "--type", "bogus"])).rejects.toThrow(/Invalid --type/);
+		});
 	});
 
 	describe("reply", () => {
@@ -1274,6 +1322,120 @@ describe("mailCommand", () => {
 			expect(stderrOutput).toBe("");
 		});
 	});
+
+	describe("terminal-state recipient rejection (overstory-f5be)", () => {
+		async function seedRecipient(name: string, state: "working" | "completed" | "zombie") {
+			const { createSessionStore } = await import("../sessions/store.ts");
+			const sessionsDbPath = join(tempDir, ".overstory", "sessions.db");
+			const sessionStore = createSessionStore(sessionsDbPath);
+			sessionStore.upsert({
+				id: `session-${name}`,
+				agentName: name,
+				capability: "builder",
+				worktreePath: `/worktrees/${name}`,
+				branchName: name,
+				taskId: "bead-x",
+				tmuxSession: `overstory-test-${name}`,
+				state,
+				pid: 99999,
+				parentAgent: "orchestrator",
+				depth: 1,
+				runId: "run-001",
+				startedAt: new Date().toISOString(),
+				lastActivity: new Date().toISOString(),
+				escalationLevel: 0,
+				stalledSince: null,
+				transcriptPath: null,
+			});
+			sessionStore.close();
+		}
+
+		test("rejects send to recipient in completed state", async () => {
+			await seedRecipient("dead-builder", "completed");
+
+			let caught: unknown;
+			try {
+				await mailCommand([
+					"send",
+					"--to",
+					"dead-builder",
+					"--subject",
+					"Hello",
+					"--body",
+					"Are you there?",
+				]);
+			} catch (err) {
+				caught = err;
+			}
+
+			expect(caught).toBeDefined();
+			expect((caught as Error).name).toBe("MailError");
+			expect((caught as Error).message).toContain("dead-builder");
+			expect((caught as Error).message).toContain("completed");
+
+			// Confirm no message was inserted
+			const store = createMailStore(join(tempDir, ".overstory", "mail.db"));
+			const client = createMailClient(store);
+			const messages = client.list({ to: "dead-builder" });
+			expect(messages.length).toBe(0);
+			client.close();
+		});
+
+		test("rejects send to recipient in zombie state", async () => {
+			await seedRecipient("crashed-builder", "zombie");
+
+			let caught: unknown;
+			try {
+				await mailCommand([
+					"send",
+					"--to",
+					"crashed-builder",
+					"--subject",
+					"Status?",
+					"--body",
+					"Ping",
+				]);
+			} catch (err) {
+				caught = err;
+			}
+
+			expect(caught).toBeDefined();
+			expect((caught as Error).name).toBe("MailError");
+			expect((caught as Error).message).toContain("zombie");
+		});
+
+		test("allows send when recipient has no session row (e.g. orchestrator)", async () => {
+			// No session seeded for "orchestrator" — the existing beforeEach
+			// only inserts mail rows, not session rows.
+			await mailCommand([
+				"send",
+				"--to",
+				"orchestrator",
+				"--subject",
+				"Hello",
+				"--body",
+				"Top-level role",
+			]);
+
+			const store = createMailStore(join(tempDir, ".overstory", "mail.db"));
+			const client = createMailClient(store);
+			const messages = client.list({ to: "orchestrator" });
+			expect(messages.length).toBeGreaterThanOrEqual(1);
+			client.close();
+		});
+
+		test("allows send to active (working) recipient", async () => {
+			await seedRecipient("live-builder", "working");
+
+			await mailCommand(["send", "--to", "live-builder", "--subject", "Hello", "--body", "Active"]);
+
+			const store = createMailStore(join(tempDir, ".overstory", "mail.db"));
+			const client = createMailClient(store);
+			const messages = client.list({ to: "live-builder" });
+			expect(messages.length).toBe(1);
+			client.close();
+		});
+	});
 });
 
 describe("shouldAutoNudge", () => {

package/src/commands/mail.ts

@@ -7,9 +7,9 @@
  */
 
 import { join } from "node:path";
-import { Command } from "commander";
+import { Command, CommanderError } from "commander";
 import { resolveProjectRoot } from "../config.ts";
-import { ValidationError } from "../errors.ts";
+import { MailError, ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
 import { jsonOutput } from "../json.ts";
 import { accent, printHint, printSuccess } from "../logging/color.ts";
@@ -253,6 +253,7 @@ interface ListOpts {
 	to?: string;
 	agent?: string;
 	unread?: boolean;
+	type?: string;
 	json?: boolean;
 }
 
@@ -405,6 +406,30 @@ async function handleSend(opts: SendOpts, cwd: string): Promise<void> {
 		}
 	}
 
+	// Reject sends to agents in a terminal state (completed/zombie).
+	// `installMailInjectors` reaps the per-agent dispatch loop the moment a
+	// session lands in a terminal state (serve.ts:378), so any mail addressed
+	// after that point would sit unread forever with no way to surface it.
+	// Sessions with no row at all (orchestrator, coordinator, operator roles)
+	// fall through — we only know about agents tracked in SessionStore.
+	// Group addresses already skip terminal agents via `getActive()`.
+	{
+		const overstoryDir = join(cwd, ".overstory");
+		const { store: sessionStore } = openSessionStore(overstoryDir);
+		try {
+			const recipient = sessionStore.getByName(to);
+			if (recipient && (recipient.state === "completed" || recipient.state === "zombie")) {
+				throw new MailError(
+					`Recipient "${to}" is in terminal state (${recipient.state}); message not sent. ` +
+						`The agent is no longer running, so this message would never be delivered.`,
+					{ agentName: to },
+				);
+			}
+		} finally {
+			sessionStore.close();
+		}
+	}
+
 	// Single-recipient message (existing logic)
 	const client = openClient(cwd);
 	try {
@@ -603,9 +628,20 @@ function handleList(opts: ListOpts, cwd: string): void {
 	const unread = opts.unread ? true : undefined;
 	const json = opts.json ?? false;
 
+	let type: MailMessageType | undefined;
+	if (opts.type !== undefined) {
+		if (!MAIL_MESSAGE_TYPES.includes(opts.type as MailMessageType)) {
+			throw new ValidationError(
+				`Invalid --type "${opts.type}". Must be one of: ${MAIL_MESSAGE_TYPES.join(", ")}`,
+				{ field: "type", value: opts.type },
+			);
+		}
+		type = opts.type as MailMessageType;
+	}
+
 	const client = openClient(cwd);
 	try {
-		const messages = client.list({ from, to, unread });
+		const messages = client.list({ from, to, unread, type });
 
 		if (json) {
 			jsonOutput("mail list", { messages });
@@ -732,8 +768,8 @@ export async function mailCommand(args: string[]): Promise<void> {
 
 	program
 		.command("check")
-		.description("Check inbox (unread messages)")
-		.option("--agent <name>", "Agent name")
+		.description("Check inbox for one agent and mark unread as read (per-agent scope)")
+		.option("--agent <name>", "Agent name (default: orchestrator)")
 		.option("--inject", "Inject format for hook context")
 		.option("--json", "Output as JSON")
 		.option("--debounce <ms>", "Debounce interval in milliseconds")
@@ -744,11 +780,12 @@ export async function mailCommand(args: string[]): Promise<void> {
 
 	program
 		.command("list")
-		.description("List messages with filters")
+		.description("List messages with filters (system-wide unless --to/--agent given)")
 		.option("--from <name>", "Filter by sender")
-		.option("--to <name>", "Filter by recipient")
+		.option("--to <name>", "Filter by recipient (scopes to one agent)")
 		.option("--agent <name>", "Alias for --to (filter by recipient)")
-		.option("--unread", "Show only unread messages")
+		.option("--unread", "Show only unread messages (does NOT mark them read)")
+		.option("--type <type>", "Filter by message type")
 		.option("--json", "Output as JSON")
 		.exitOverride()
 		.action((opts: ListOpts) => {
@@ -789,5 +826,23 @@ export async function mailCommand(args: string[]): Promise<void> {
 			handlePurge(opts, root);
 		});
 
-	await program.parseAsync(["node", "overstory-mail", ...args]);
+	try {
+		await program.parseAsync(["node", "overstory-mail", ...args]);
+	} catch (err) {
+		// `exitOverride()` turns Commander's help paths into thrown
+		// CommanderErrors after the help text was already written to stdout.
+		// Swallow both the explicit `--help` path (commander.helpDisplayed,
+		// exitCode 0) and the missing-subcommand path (commander.help,
+		// exitCode 1) — the user got what they asked for.
+		if (
+			err instanceof CommanderError &&
+			(err.code === "commander.helpDisplayed" || err.code === "commander.help")
+		) {
+			if (err.exitCode !== 0) {
+				process.exitCode = err.exitCode;
+			}
+			return;
+		}
+		throw err;
+	}
 }