@vitest-agent/cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @vitest-agent/cli
+
+[![npm](https://img.shields.io/npm/v/@vitest-agent/cli?label=npm&color=cb3837)](https://www.npmjs.com/package/@vitest-agent/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+> **Part of the [vitest-agent](https://vitest-agent.dev) ecosystem.** Most users want **[@vitest-agent/plugin](https://www.npmjs.com/package/@vitest-agent/plugin)**, which pulls this package in automatically. Install `@vitest-agent/cli` directly only if you want the `vitest-agent` CLI on its own.
+
+The `vitest-agent` CLI bin. Manages the local SQLite database, runs health diagnostics, and provides the hook-plumbing subcommands used by the Claude Code plugin's session and Bash hooks. Reads cached test data from SQLite — never runs tests or calls AI providers.
+
+## Features
+
+- **`doctor`** — five-point health diagnostic covering manifest assembly, latest-run integrity and staleness
+- **`db`** — `path`, `prune`, `reset` and `query` subcommands for database lifecycle management
+- **`agent`** namespace — `triage`, `wrapup`, `record`, `register-agent`, `end-agent`, `inject-env` and `sidecar-path` for hook-driven plumbing
+
+## Install
+
+```bash
+npm install --save-dev @vitest-agent/cli
+# or
+pnpm add -D @vitest-agent/cli
+```
+
+`@vitest-agent/cli` is a required peer of `@vitest-agent/plugin` and arrives automatically with modern pnpm and npm.
+
+## Quick start
+
+```bash
+npx vitest-agent doctor
+# example output (varies by environment)
+
+npx vitest-agent db path
+# prints the XDG-derived path to data.db
+
+npx vitest-agent db query "SELECT count(*) FROM test_cases"
+# example output (varies by environment)
+```
+
+## Documentation
+
+CLI reference at [vitest-agent.dev/cli](https://vitest-agent.dev/cli).
+
+## License
+
+[MIT](LICENSE)

package/bin/vitest-agent.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { CliLive } from "../layers/CliLive.js";
+import { CURRENT_CLI_VERSION } from "../index.js";
+import { agentCommand } from "../commands/agent.js";
+import { dbCommand } from "../commands/db.js";
+import { doctorCommand } from "../commands/doctor.js";
+import { NodeContext, NodeRuntime } from "@effect/platform-node";
+import { CURRENT_SDK_VERSION, PathResolutionLive, formatFatalError, resolveDataPath, resolveLogFile, resolveLogLevel } from "@vitest-agent/sdk";
+import { Cause, Console, Effect } from "effect";
+import { Command } from "@effect/cli";
+
+//#region src/bin.ts
+/**
+* CLI entry point for vitest-agent.
+*
+* @packageDocumentation
+*/
+const rootCommand = Command.make("vitest-agent").pipe(Command.withSubcommands([
+	dbCommand,
+	doctorCommand,
+	agentCommand
+]));
+const cli = Command.run(rootCommand, {
+	name: "vitest-agent",
+	version: "0.0.0"
+});
+const logLevel = resolveLogLevel();
+const logFile = resolveLogFile();
+// @vitest-agent/sdk and writes a single stderr line on mismatch.
+if ("1.0.0" !== "0.0.0" && CURRENT_SDK_VERSION !== "1.0.0") process.stderr.write(`[@vitest-agent/cli] version drift: @vitest-agent/cli@${CURRENT_CLI_VERSION} with @vitest-agent/sdk@${CURRENT_SDK_VERSION}. Reinstall @vitest-agent/* packages so versions match.\n`);
+const projectDir = process.env.VITEST_AGENT_PROJECT_DIR ?? process.cwd();
+const main = resolveDataPath(projectDir).pipe(Effect.flatMap((dbPath) => Effect.suspend(() => cli(process.argv)).pipe(Effect.provide(CliLive(dbPath, logLevel, logFile)))), Effect.provide(PathResolutionLive(projectDir)), Effect.provide(NodeContext.layer), Effect.catchAllCause((cause) => {
+	if (Cause.defects(cause).length > 0) return Console.error(`vitest-agent: ${formatFatalError(cause)}`).pipe(Effect.andThen(Effect.failCause(cause)));
+	return Effect.failCause(cause);
+}));
+NodeRuntime.runMain(main);
+
+//#endregion
+export {  };

package/commands/agent.js

@@ -0,0 +1,159 @@
+import { SidecarLive } from "../layers/SidecarLive.js";
+import { registerAgentEffect } from "../lib/internal-register-agent.js";
+import { DATA_DB_FILENAME, REGISTRY_DB_FILENAME, resolveProjectDataDir, resolveRegistryDir, resolveSessionMapPath } from "../lib/sidecar-paths.js";
+import { endAgentEffect } from "../lib/internal-end-agent.js";
+import { recordCommand } from "./record.js";
+import { triageCommand } from "./triage.js";
+import { wrapupCommand } from "./wrapup.js";
+import { NodeContext } from "@effect/platform-node";
+import { resolveProjectKeyFromCwd } from "@vitest-agent/sdk";
+import { Cause, Chunk, Effect, Option } from "effect";
+import { join } from "node:path";
+import { Command, Options } from "@effect/cli";
+import { exitCodeForTag, injectEnv } from "@vitest-agent/sdk/dispatch";
+import { resolveSidecarBinaryPath } from "@vitest-agent/sidecar";
+
+//#region src/commands/agent.ts
+/**
+* `agent` subcommand namespace.
+*
+* Commands intended for agents and hook scripts — humans typically do
+* not invoke these directly. The group composes the hook-driven
+* utilities (triage, wrapup, record) with the sidecar invocations
+* called by plugin/hooks/*.sh scripts (register-agent, end-agent,
+* inject-env).
+*
+* The sidecar subcommands return plain text on stdout that the bash
+* hooks parse, and structured error info on stderr in the shape
+* `<exit_code> <error_tag>: <message>`.
+*
+* Exit codes follow the contract documented in the agent-agnostic
+* taxonomy plan:
+*   0 = success
+*   1 = registration conflict
+*   2 = sidecar timeout
+*   3 = database error
+*   4 = project identity not resolvable
+*   5 = other unexpected defect
+*
+* @packageDocumentation
+*/
+const writeStdout = (line) => Effect.sync(() => {
+	process.stdout.write(`${line}\n`);
+});
+const writeStderrAndExit = (exitCode, tag, message) => Effect.sync(() => {
+	process.stderr.write(`${exitCode} ${tag}: ${message}\n`);
+	process.exit(exitCode);
+});
+const mapDefectToExit = (cause) => {
+	const failures = Chunk.toReadonlyArray(Cause.failures(cause));
+	if (failures.length > 0) {
+		const tagged = failures[0];
+		const tag = tagged._tag ?? "UnknownError";
+		const message = tagged.reason ?? tagged.message ?? String(failures[0]);
+		return writeStderrAndExit(exitCodeForTag(tag), tag, message);
+	}
+	const defect = Chunk.toReadonlyArray(Cause.defects(cause))[0];
+	return writeStderrAndExit(5, "Defect", defect instanceof Error ? defect.message : String(defect ?? "unknown defect"));
+};
+const hostKindOpt = Options.text("host-kind").pipe(Options.withDescription("Host vendor identifier; e.g. 'claude-code', 'cursor', 'goose'"));
+const agentTypeOpt = Options.text("agent-type").pipe(Options.withDescription("Agent type, must begin with the host-kind prefix"));
+const hostSessionIdOpt = Options.text("host-session-id").pipe(Options.withDescription("Host's native session id (host chat UUID; `session_id` in the CC hook payload)"));
+const transcriptPathOpt = Options.text("transcript-path").pipe(Options.withDescription("Path to the host's transcript file (basename UUID is the conversation key)"));
+const cwdOpt = Options.text("cwd").pipe(Options.withDescription("Workspace root directory the agent is running in"));
+const parentAgentIdOpt = Options.optional(Options.text("parent-agent-id"));
+const clientNonceOpt = Options.optional(Options.text("client-nonce"));
+const projectKeyOverrideOpt = Options.optional(Options.text("project-key"));
+const registerAgentSubcommand = Command.make("register-agent", {
+	hostKind: hostKindOpt,
+	agentType: agentTypeOpt,
+	hostSessionId: hostSessionIdOpt,
+	transcriptPath: transcriptPathOpt,
+	cwd: cwdOpt,
+	parentAgentId: parentAgentIdOpt,
+	clientNonce: clientNonceOpt,
+	projectKeyOverride: projectKeyOverrideOpt
+}, (opts) => Effect.gen(function* () {
+	const projectKey = Option.isSome(opts.projectKeyOverride) ? opts.projectKeyOverride.value : resolveProjectKeyFromCwd(opts.cwd);
+	const perProjectDbPath = join(resolveProjectDataDir(projectKey), DATA_DB_FILENAME);
+	const registryDbPath = join(resolveRegistryDir(), REGISTRY_DB_FILENAME);
+	const sidecar = SidecarLive({
+		perProjectDbPath,
+		sessionMapDbPath: yield* resolveSessionMapPath().pipe(Effect.catchAllCause(mapDefectToExit)),
+		registryDbPath
+	});
+	const result = yield* registerAgentEffect({
+		hostSessionId: opts.hostSessionId,
+		transcriptPath: opts.transcriptPath,
+		cwd: opts.cwd,
+		hostKind: opts.hostKind,
+		agentType: opts.agentType,
+		projectKey,
+		...Option.isSome(opts.parentAgentId) && { parentAgentId: opts.parentAgentId.value },
+		...Option.isSome(opts.clientNonce) && { clientNonce: opts.clientNonce.value }
+	}).pipe(Effect.provide(sidecar), Effect.catchAllCause(mapDefectToExit));
+	yield* writeStdout(JSON.stringify({
+		agentId: result.agentId,
+		conversationId: result.conversationId,
+		mainAgentId: result.mainAgentId,
+		idempotencyKey: result.idempotencyKey,
+		idempotencyHit: result.idempotencyHit
+	}));
+}).pipe(Effect.provide(NodeContext.layer))).pipe(Command.withDescription("Register an agent invocation in the per-project store and the per-client session map"));
+const agentIdOpt = Options.text("agent-id").pipe(Options.withDescription("The agent_id (UUID) returned by an earlier register-agent call"));
+const endedAtOpt = Options.optional(Options.integer("ended-at"));
+const endHostSessionIdOpt = Options.optional(Options.text("host-session-id"));
+const endCwdOpt = Options.text("cwd").pipe(Options.withDefault(process.cwd()), Options.withDescription("Workspace root, used to locate the per-project data.db"));
+const endProjectKeyOverrideOpt = Options.optional(Options.text("project-key"));
+const endAgentSubcommand = Command.make("end-agent", {
+	agentId: agentIdOpt,
+	endedAt: endedAtOpt,
+	hostSessionId: endHostSessionIdOpt,
+	cwd: endCwdOpt,
+	projectKeyOverride: endProjectKeyOverrideOpt
+}, (opts) => Effect.gen(function* () {
+	const perProjectDbPath = join(resolveProjectDataDir(Option.isSome(opts.projectKeyOverride) ? opts.projectKeyOverride.value : resolveProjectKeyFromCwd(opts.cwd)), DATA_DB_FILENAME);
+	const registryDbPath = join(resolveRegistryDir(), REGISTRY_DB_FILENAME);
+	const sidecar = SidecarLive({
+		perProjectDbPath,
+		sessionMapDbPath: yield* resolveSessionMapPath().pipe(Effect.catchAllCause(mapDefectToExit)),
+		registryDbPath
+	});
+	const endedAt = Option.isSome(opts.endedAt) ? opts.endedAt.value : Math.floor(Date.now() / 1e3);
+	yield* endAgentEffect({
+		agentId: opts.agentId,
+		endedAt,
+		...Option.isSome(opts.hostSessionId) && { hostSessionId: opts.hostSessionId.value }
+	}).pipe(Effect.provide(sidecar), Effect.catchAllCause(mapDefectToExit));
+}).pipe(Effect.provide(NodeContext.layer))).pipe(Command.withDescription("Mark an agent (and optionally its session) as ended"));
+const commandOpt = Options.text("command").pipe(Options.withDescription("The Bash command to (possibly) rewrite with VITEST_AGENT_* env-prefix"));
+const cwdInjectOpt = Options.text("cwd").pipe(Options.withDefault(process.cwd()), Options.withDescription("Working directory; used to find package.json scripts"));
+const injectEnvSubcommand = Command.make("inject-env", {
+	command: commandOpt,
+	cwd: cwdInjectOpt
+}, (opts) => Effect.sync(() => {
+	const out = injectEnv({
+		command: opts.command,
+		cwd: opts.cwd,
+		env: process.env
+	});
+	process.stdout.write(`${out}\n`);
+})).pipe(Command.withDescription("Rewrite a Bash command to prepend VITEST_AGENT_* env vars when it invokes Vitest"));
+const sidecarPathSubcommand = Command.make("sidecar-path", {}, () => Effect.sync(() => {
+	const path = resolveSidecarBinaryPath();
+	if (path === null) process.exit(1);
+	process.stdout.write(`${path}\n`);
+})).pipe(Command.withDescription("Print the absolute path of the platform sidecar binary resolved via require.resolve"));
+const agentParent = Command.make("agent").pipe(Command.withDescription("Commands intended for agents and hook scripts — humans typically don't invoke these directly."));
+const agentCommand = agentParent.pipe(Command.withSubcommands([
+	triageCommand,
+	wrapupCommand,
+	recordCommand,
+	registerAgentSubcommand,
+	endAgentSubcommand,
+	injectEnvSubcommand,
+	sidecarPathSubcommand
+]));
+
+//#endregion
+export { agentCommand };

package/commands/db.js

@@ -0,0 +1,123 @@
+import { formatDbQuery } from "../lib/format-db-query.js";
+import { NodeContext } from "@effect/platform-node";
+import { layer } from "@effect/sql-sqlite-node/SqliteClient";
+import { DataStore, resolveDataPath } from "@vitest-agent/sdk";
+import { Effect } from "effect";
+import { Args, Command, Options } from "@effect/cli";
+import { SqlClient } from "@effect/sql/SqlClient";
+import * as readline from "node:readline";
+import { FileSystem } from "@effect/platform";
+
+//#region src/commands/db.ts
+/**
+* CLI db command -- manage the vitest-agent database.
+*
+* @packageDocumentation
+*/
+const pathCommand = Command.make("path", {}, () => Effect.gen(function* () {
+	const dbPath = yield* resolveDataPath(process.env.VITEST_AGENT_PROJECT_DIR ?? process.cwd());
+	yield* Effect.sync(() => process.stdout.write(`${dbPath}\n`));
+})).pipe(Command.withDescription("Print the resolved database path"));
+const keepRecentOption = Options.withDefault(Options.integer("keep-recent"), 30).pipe(Options.withDescription("Number of most-recent sessions to keep in full"));
+const pruneCommand = Command.make("prune", { keepRecent: keepRecentOption }, ({ keepRecent }) => Effect.gen(function* () {
+	const result = yield* (yield* DataStore).pruneSessions(keepRecent);
+	yield* Effect.sync(() => process.stdout.write(`Pruned ${result.prunedTurns} turn row(s) across ${result.affectedSessions} session(s); session rows retained.\n`));
+})).pipe(Command.withDescription("Drop old sessions' turn history (W1 retention; keeps the last N in full)"));
+const yesOption = Options.boolean("yes").pipe(Options.withDefault(false), Options.withDescription("Skip the interactive confirmation prompt"));
+const resetCommand = Command.make("reset", { yes: yesOption }, ({ yes }) => Effect.gen(function* () {
+	const agentId = process.env.VITEST_AGENT_AGENT_ID;
+	if (agentId !== void 0 && agentId.length > 0) {
+		yield* Effect.sync(() => {
+			process.stderr.write("db reset is human-only; use db prune or run from a human terminal\n");
+			process.exit(4);
+		});
+		return;
+	}
+	const dbPath = yield* resolveDataPath(process.env.VITEST_AGENT_PROJECT_DIR ?? process.cwd());
+	if (!process.stdout.isTTY && !yes) {
+		yield* Effect.sync(() => {
+			process.stderr.write("db reset requires --yes when stdout is not a TTY\n");
+			process.exit(5);
+		});
+		return;
+	}
+	if (process.stdout.isTTY && !yes) {
+		if (!(yield* Effect.promise(() => {
+			return new Promise((resolve) => {
+				const rl = readline.createInterface({
+					input: process.stdin,
+					output: process.stdout
+				});
+				rl.question(`Wipe ${dbPath}? [y/N]: `, (answer) => {
+					rl.close();
+					resolve(answer === "y" || answer === "Y");
+				});
+			});
+		}))) {
+			yield* Effect.sync(() => {
+				process.stdout.write("aborted\n");
+				process.exit(0);
+			});
+			return;
+		}
+	}
+	const fs = yield* FileSystem.FileSystem;
+	yield* fs.remove(dbPath).pipe(Effect.catchAll(() => Effect.void));
+	yield* fs.remove(`${dbPath}-shm`).pipe(Effect.catchAll(() => Effect.void));
+	yield* fs.remove(`${dbPath}-wal`).pipe(Effect.catchAll(() => Effect.void));
+	yield* Effect.sync(() => {
+		process.stdout.write(`Deleted database at ${dbPath}\n`);
+	});
+}).pipe(Effect.provide(NodeContext.layer))).pipe(Command.withDescription("Wipe the database (human-only; blocked in agent contexts)"));
+const queryFormatOption = Options.choice("format", ["table", "json"]).pipe(Options.withDefault("table"), Options.withDescription("Output format for query results"));
+const sqlArg = Args.text({ name: "sql" }).pipe(Args.withDescription("Read-only SQL statement to execute against data.db"));
+/**
+* Flatten an error and its cause chain into a single message so the
+* driver's `attempt to write a readonly database` text surfaces to
+* the user regardless of which layer wrapped it.
+*/
+const describeError = (error) => {
+	if (!(error instanceof Error)) return String(error);
+	const parts = [error.message];
+	let cause = error.cause;
+	while (cause instanceof Error && !parts.includes(cause.message)) {
+		parts.push(cause.message);
+		cause = cause.cause;
+	}
+	return parts.filter((part) => part.length > 0).join(": ");
+};
+const queryCommand = Command.make("query", {
+	sql: sqlArg,
+	format: queryFormatOption
+}, ({ sql, format }) => Effect.gen(function* () {
+	if (sql.trim().length === 0) {
+		yield* Effect.sync(() => {
+			process.stderr.write("db query: missing sql\n");
+			process.exit(2);
+		});
+		return;
+	}
+	const dbPath = yield* resolveDataPath(process.env.VITEST_AGENT_PROJECT_DIR ?? process.cwd());
+	yield* Effect.gen(function* () {
+		const rows = yield* (yield* SqlClient).unsafe(sql);
+		yield* Effect.sync(() => {
+			process.stdout.write(`${formatDbQuery(rows, format)}\n`);
+		});
+	}).pipe(Effect.provide(layer({
+		filename: dbPath,
+		readonly: true
+	})), Effect.catchAll((error) => Effect.sync(() => {
+		process.stderr.write(`db query: ${describeError(error)}\n`);
+		process.exit(3);
+	})));
+})).pipe(Command.withDescription("Run a read-only SQL query against the database"));
+const dbParent = Command.make("db").pipe(Command.withDescription("Manage the vitest-agent database"));
+const dbCommand = dbParent.pipe(Command.withSubcommands([
+	pathCommand,
+	pruneCommand,
+	resetCommand,
+	queryCommand
+]));
+
+//#endregion
+export { dbCommand };

package/commands/doctor.js

@@ -0,0 +1,111 @@
+import { formatDoctor } from "../lib/format-doctor.js";
+import { DataReader, resolveDataPath } from "@vitest-agent/sdk";
+import { Effect, Option } from "effect";
+import { Command, Options } from "@effect/cli";
+
+//#region src/commands/doctor.ts
+/**
+* CLI doctor command -- diagnose database health.
+*
+* @packageDocumentation
+*/
+const formatOption = Options.withDefault(Options.choice("format", ["markdown", "json"]), "markdown");
+const writeOutput = (results, format) => Effect.sync(() => {
+	if (format === "json") process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+	else process.stdout.write(`${formatDoctor(results)}\n`);
+});
+const doctorCommand = Command.make("doctor", { format: formatOption }, ({ format }) => Effect.gen(function* () {
+	const reader = yield* DataReader;
+	const results = [];
+	const dbPath = yield* resolveDataPath(process.cwd());
+	results.push({
+		name: "Database path",
+		passed: true,
+		detail: `\`${dbPath}\``
+	});
+	const manifestOpt = yield* reader.getManifest().pipe(Effect.catchAll(() => Effect.succeed(Option.none())));
+	if (Option.isNone(manifestOpt)) {
+		results.push({
+			name: "Manifest",
+			passed: false,
+			detail: "no test run data found in database"
+		});
+		yield* writeOutput(results, format);
+		yield* Effect.sync(() => process.exit(1));
+		return;
+	}
+	const manifest = manifestOpt.value;
+	results.push({
+		name: "Manifest valid",
+		passed: true,
+		detail: `${manifest.projects.length} project${manifest.projects.length !== 1 ? "s" : ""}`
+	});
+	let validReports = 0;
+	const reportIssues = [];
+	for (const entry of manifest.projects) {
+		const project = entry.project;
+		const reportOpt = yield* reader.getLatestRun(project).pipe(Effect.catchAll(() => Effect.succeed(Option.none())));
+		if (Option.isNone(reportOpt)) reportIssues.push(`\`${entry.project}\` no report data`);
+		else validReports++;
+	}
+	const totalReports = manifest.projects.length;
+	if (reportIssues.length > 0) results.push({
+		name: "Reports",
+		passed: false,
+		detail: `${validReports}/${totalReports} valid -- ${reportIssues.join(", ")}`
+	});
+	else results.push({
+		name: "Reports",
+		passed: true,
+		detail: `${validReports}/${totalReports} valid`
+	});
+	let validHistory = 0;
+	let totalHistory = 0;
+	const historyIssues = [];
+	for (const entry of manifest.projects) {
+		totalHistory++;
+		const project = entry.project;
+		if (!(yield* reader.getHistory(project).pipe(Effect.map((h) => ({
+			ok: true,
+			record: h
+		})), Effect.catchAll(() => Effect.succeed({
+			ok: false,
+			record: null
+		})))).ok) historyIssues.push(`\`${entry.project}\` history read error`);
+		else validHistory++;
+	}
+	if (totalHistory > 0) if (historyIssues.length > 0) results.push({
+		name: "History",
+		passed: false,
+		detail: `${validHistory}/${totalHistory} valid -- ${historyIssues.join(", ")}`
+	});
+	else results.push({
+		name: "History",
+		passed: true,
+		detail: `${validHistory}/${totalHistory} valid`
+	});
+	const timestamps = manifest.projects.map((e) => e.lastRun).filter((t) => t !== null);
+	if (timestamps.length > 0) {
+		const latest = new Date(Math.max(...timestamps.map((t) => new Date(t).getTime())));
+		const ageMs = Date.now() - latest.getTime();
+		const ageMinutes = Math.floor(ageMs / 6e4);
+		const ageHours = Math.floor(ageMs / 36e5);
+		const ageDays = Math.floor(ageMs / 864e5);
+		let ageStr;
+		if (ageMinutes < 1) ageStr = "just now";
+		else if (ageMinutes < 60) ageStr = `${ageMinutes} minute${ageMinutes !== 1 ? "s" : ""} ago`;
+		else if (ageHours < 24) ageStr = `${ageHours} hour${ageHours !== 1 ? "s" : ""} ago`;
+		else ageStr = `${ageDays} day${ageDays !== 1 ? "s" : ""} ago`;
+		const isStale = ageHours >= 24;
+		results.push({
+			name: "Last run",
+			passed: !isStale,
+			detail: isStale ? `${ageStr} (stale)` : ageStr
+		});
+	}
+	yield* writeOutput(results, format);
+	if (results.some((r) => !r.passed)) yield* Effect.sync(() => process.exit(1));
+}));
+
+//#endregion
+export { doctorCommand };