@inceptionstack/roundhouse 0.2.2 → 0.3.1

package/src/cli/cron.ts

@@ -0,0 +1,296 @@
+/**
+ * cli/cron.ts — roundhouse cron CLI subcommands
+ */
+
+import { CronStore, validateJobId } from "../cron/store";
+import { isBuiltinJob } from "../cron/helpers";
+import { CronRunner } from "../cron/runner";
+import { validateSchedule } from "../cron/schedule";
+import { validateTemplate } from "../cron/template";
+import { parseDuration } from "../cron/durations";
+import type { CronJobConfig, CronSchedule } from "../cron/types";
+import { DEFAULT_TIMEOUT_MS, DEFAULT_TIMEZONE, VALID_NOTIFY_ON, DEFAULT_RUNS_LIMIT } from "../cron/constants";
+import { formatSchedule, formatRunCounts, formatJobSummary, formatJobDetail, formatRunLine, runStatusIcon, jobEnabledIcon } from "../cron/format";
+
+function rejectBuiltin(id: string): void {
+  if (isBuiltinJob(id)) {
+    console.error(`Job ID "${id}" is reserved for built-in jobs.`);
+    process.exit(1);
+  }
+}
+
+function validateNotifyOn(value?: string): "always" | "success" | "failure" {
+  const v = value ?? "always";
+  if (!(VALID_NOTIFY_ON as readonly string[]).includes(v)) {
+    console.error(`Invalid --notify-on: "${v}". Use ${VALID_NOTIFY_ON.join(", ")}.`);
+    process.exit(1);
+  }
+  return v as "always" | "success" | "failure";
+}
+
+function parseArgs(args: string[]): { positional: string[]; flags: Record<string, string> } {
+  const positional: string[] = [];
+  const flags: Record<string, string> = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith("--") && i + 1 < args.length && !args[i + 1].startsWith("--")) {
+      flags[args[i].slice(2)] = args[i + 1];
+      i++;
+    } else if (args[i].startsWith("--")) {
+      flags[args[i].slice(2)] = "true";
+    } else {
+      positional.push(args[i]);
+    }
+  }
+  return { positional, flags };
+}
+
+export async function cmdCron(args: string[]): Promise<void> {
+  const { positional, flags } = parseArgs(args);
+  const sub = positional[0];
+
+  const store = new CronStore();
+  await store.ensureDirs();
+
+  switch (sub) {
+    case "add": {
+      const id = positional[1];
+      if (!id) { console.error("Usage: roundhouse cron add <id> --prompt '...' --cron '...' --tz '...'"); process.exit(1); }
+      validateJobId(id);
+      rejectBuiltin(id);
+
+      const existing = await store.getJob(id);
+      if (existing && !flags.replace) {
+        console.error(`Job "${id}" already exists. Use --replace to overwrite.`);
+        process.exit(1);
+      }
+
+      const prompt = flags.prompt;
+      if (!prompt) { console.error("--prompt is required"); process.exit(1); }
+
+      // Parse schedule — only one allowed
+      const schedCount = [flags.cron, flags.every, flags.at].filter(Boolean).length;
+      if (schedCount > 1) { console.error("Specify only one of --cron, --every, or --at"); process.exit(1); }
+      let schedule: CronSchedule;
+      if (flags.cron) {
+        schedule = { type: "cron", cron: flags.cron, tz: flags.tz ?? DEFAULT_TIMEZONE };
+      } else if (flags.every) {
+        schedule = { type: "interval", every: flags.every };
+      } else if (flags.at) {
+        schedule = { type: "once", at: flags.at, tz: flags.tz };
+      } else {
+        console.error("Schedule required: --cron '...', --every '...', or --at '...'");
+        process.exit(1);
+      }
+
+      validateSchedule(schedule);
+
+      // Parse vars
+      const vars: Record<string, string> = {};
+      if (flags.var) {
+        for (const v of flags.var.split(",")) {
+          const [k, ...rest] = v.split("=");
+          if (k && rest.length) vars[k.trim()] = rest.join("=").trim();
+        }
+      }
+
+      // Validate template
+      const templateErrors = validateTemplate(prompt, new Set(Object.keys(vars)));
+      if (templateErrors.length) {
+        console.error("Template errors:");
+        templateErrors.forEach((e) => console.error(`  ${e}`));
+        process.exit(1);
+      }
+
+      // Parse notify
+      const notify: CronJobConfig["notify"] = {};
+      if (flags.telegram) {
+        notify.telegram = {
+          chatIds: flags.telegram.split(",").map((s) => s.trim()),
+          onlyOn: validateNotifyOn(flags["notify-on"]),
+        };
+      }
+
+      const now = new Date().toISOString();
+      const job: CronJobConfig = {
+        id,
+        enabled: true,
+        description: flags.description,
+        createdAt: existing?.createdAt ?? now,
+        updatedAt: now,
+        schedule,
+        prompt,
+        vars: Object.keys(vars).length ? vars : undefined,
+        timeoutMs: flags.timeout ? parseDuration(flags.timeout) : undefined,
+        notify: Object.keys(notify).length ? notify : undefined,
+      };
+
+      await store.writeJob(job);
+      console.log(`✅ Cron job "${id}" ${existing ? "updated" : "created"}.`);
+      if (flags.json) console.log(JSON.stringify(job, null, 2));
+      break;
+    }
+
+    case "list": {
+      const jobs = await store.listJobs();
+      if (jobs.length === 0) {
+        console.log("No cron jobs configured.");
+        break;
+      }
+      if (flags.json) {
+        console.log(JSON.stringify(jobs, null, 2));
+      } else {
+        for (const j of jobs) {
+          const state = await store.getState(j.id);
+          console.log(`  ${formatJobSummary(j, state)}`);
+        }
+      }
+      break;
+    }
+
+    case "show": {
+      const id = positional[1];
+      if (!id) { console.error("Usage: roundhouse cron show <id>"); process.exit(1); }
+      const job = await store.getJob(id);
+      if (!job) { console.error(`Job not found: ${id}`); process.exit(1); }
+      const state = await store.getState(id);
+      const runs = await store.listRuns(id, 5);
+      if (flags.json) {
+        console.log(JSON.stringify({ job, state, recentRuns: runs }, null, 2));
+      } else {
+        console.log(`\n${formatJobDetail(job, state, runs)}`);
+      }
+      break;
+    }
+
+    case "trigger":
+    case "run": {
+      const id = positional[1];
+      if (!id) { console.error("Usage: roundhouse cron trigger <id>"); process.exit(1); }
+      rejectBuiltin(id);
+      const job = await store.getJob(id);
+      if (!job) { console.error(`Job not found: ${id}`); process.exit(1); }
+      console.log(`Triggering ${id}...`);
+      const runner = new CronRunner(store);
+      const record = await runner.runJob(job, new Date(), "manual");
+      console.log(`\nResult: ${record.status} (${record.durationMs}ms)`);
+      if (record.responseText) console.log(`\n${record.responseText.slice(0, 2000)}`);
+      if (record.error) console.log(`\nError: ${record.error}`);
+      process.exit(record.status === "completed" ? 0 : 1);
+      break;
+    }
+
+    case "runs": {
+      const id = positional[1];
+      if (!id) { console.error("Usage: roundhouse cron runs <id>"); process.exit(1); }
+      const runs = await store.listRuns(id, parseInt(flags.limit ?? String(DEFAULT_RUNS_LIMIT), 10));
+      if (runs.length === 0) {
+        console.log(`No runs for ${id}.`);
+      } else if (flags.json) {
+        console.log(JSON.stringify(runs, null, 2));
+      } else {
+        for (const r of runs) {
+          console.log(`  ${formatRunLine(r)} (${r.kind})`);
+        }
+      }
+      break;
+    }
+
+    case "pause": {
+      const id = positional[1];
+      if (!id) { console.error("Usage: roundhouse cron pause <id>"); process.exit(1); }
+      rejectBuiltin(id);
+      const job = await store.getJob(id);
+      if (!job) { console.error(`Job not found: ${id}`); process.exit(1); }
+      job.enabled = false;
+      job.updatedAt = new Date().toISOString();
+      await store.writeJob(job);
+      console.log(`⏸️ Job "${id}" paused.`);
+      break;
+    }
+
+    case "resume": {
+      const id = positional[1];
+      if (!id) { console.error("Usage: roundhouse cron resume <id>"); process.exit(1); }
+      rejectBuiltin(id);
+      const job = await store.getJob(id);
+      if (!job) { console.error(`Job not found: ${id}`); process.exit(1); }
+      job.enabled = true;
+      job.updatedAt = new Date().toISOString();
+      await store.writeJob(job);
+      console.log(`▶️ Job "${id}" resumed.`);
+      break;
+    }
+
+    case "edit": {
+      const id = positional[1];
+      if (!id) { console.error("Usage: roundhouse cron edit <id> [--prompt '...'] [--cron '...'] ..."); process.exit(1); }
+      rejectBuiltin(id);
+      const job = await store.getJob(id);
+      if (!job) { console.error(`Job not found: ${id}`); process.exit(1); }
+
+      if (flags.prompt) job.prompt = flags.prompt;
+      if (flags.description) job.description = flags.description;
+      if (flags.timeout) job.timeoutMs = parseDuration(flags.timeout);
+      // Reject multiple schedule flags
+      const editSchedCount = [flags.cron, flags.every, flags.at].filter(Boolean).length;
+      if (editSchedCount > 1) { console.error("Specify only one of --cron, --every, or --at"); process.exit(1); }
+      if (flags.cron) job.schedule = { type: "cron", cron: flags.cron, tz: flags.tz ?? (job.schedule.type === "cron" ? job.schedule.tz : DEFAULT_TIMEZONE) };
+      if (flags.every) job.schedule = { type: "interval", every: flags.every };
+      if (flags.at) job.schedule = { type: "once", at: flags.at, tz: flags.tz };
+      if (flags.telegram) {
+        job.notify = { ...job.notify, telegram: { chatIds: flags.telegram.split(",").map((s) => s.trim()), onlyOn: validateNotifyOn(flags["notify-on"]) } };
+      }
+
+      validateSchedule(job.schedule);
+      // Validate template after edit
+      const editVars = new Set(Object.keys(job.vars ?? {}));
+      const editErrors = validateTemplate(job.prompt, editVars);
+      if (editErrors.length) {
+        console.error("Template errors:");
+        editErrors.forEach((e) => console.error(`  ${e}`));
+        process.exit(1);
+      }
+      job.updatedAt = new Date().toISOString();
+      await store.writeJob(job);
+      console.log(`✅ Job "${id}" updated.`);
+      break;
+    }
+
+    case "delete": {
+      const id = positional[1];
+      if (!id) { console.error("Usage: roundhouse cron delete <id>"); process.exit(1); }
+      rejectBuiltin(id);
+      const job = await store.getJob(id);
+      if (!job) { console.error(`Job not found: ${id}`); process.exit(1); }
+      await store.deleteJob(id);
+      console.log(`🗑️ Job "${id}" deleted.`);
+      break;
+    }
+
+    default:
+      console.log(`roundhouse cron <command>
+
+Commands:
+  add <id> [flags]    Create a cron job
+  list                List all jobs
+  show <id>           Show job details
+  trigger <id>        Run job now
+  runs <id>           Show run history
+  edit <id> [flags]   Edit a job
+  pause <id>          Disable a job
+  resume <id>         Enable a job
+  delete <id>         Delete a job
+
+Flags for add/edit:
+  --prompt "..."      Prompt template (required for add)
+  --cron "..."        Cron expression (e.g. "0 8 * * *")
+  --every "..."       Interval (e.g. "6h")
+  --at "..."          One-shot time (e.g. "30m" or ISO date)
+  --tz "..."          Timezone (e.g. "Asia/Jerusalem")
+  --telegram "..."    Telegram chat IDs (comma-separated)
+  --var "k=v,..."      Template variables (comma-separated)
+  --timeout "..."     Timeout (e.g. "30m")
+  --description "..." Job description
+  --json              JSON output`);
+  }
+}

package/src/cli/doctor/checks/agent.ts

@@ -0,0 +1,68 @@
+/**
+ * Agent checks (pi-specific)
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { DoctorCheck } from "../types";
+import { which } from "../shell";
+
+export const agentChecks: DoctorCheck[] = [
+  {
+    id: "pi-sdk", category: "agent", name: "Pi SDK",
+    async run() {
+      try {
+        const pkgPath = join(process.cwd(), "node_modules", "@mariozechner", "pi-coding-agent", "package.json");
+        const raw = await readFile(pkgPath, "utf8");
+        const ver = JSON.parse(raw).version;
+        return { id: "pi-sdk", category: "agent", name: "Pi SDK", status: "pass", summary: `v${ver}` };
+      } catch {
+        return {
+          id: "pi-sdk", category: "agent", name: "Pi SDK", status: "fail", summary: "not found",
+          details: ["@mariozechner/pi-coding-agent not installed"],
+          fix: { description: "Install pi SDK", command: "npm install @mariozechner/pi-coding-agent" },
+        };
+      }
+    },
+  },
+
+  {
+    id: "pi-cli", category: "agent", name: "Pi CLI",
+    async run() {
+      const path = await which("pi");
+      return {
+        id: "pi-cli", category: "agent", name: "Pi CLI",
+        status: path ? "pass" : "warn", summary: path ?? "not found",
+        details: !path ? ["pi CLI needed for roundhouse tui"] : undefined,
+      };
+    },
+  },
+
+  {
+    id: "pi-settings", category: "agent", name: "Pi settings",
+    async run() {
+      const settingsPath = join(homedir(), ".pi", "agent", "settings.json");
+      try {
+        const raw = await readFile(settingsPath, "utf8");
+        const settings = JSON.parse(raw);
+        const model = settings.defaultModel ? `${settings.defaultProvider}/${settings.defaultModel}` : "not configured";
+        const issues: string[] = [];
+        if (!settings.defaultProvider) issues.push("No defaultProvider set");
+        if (!settings.defaultModel) issues.push("No defaultModel set");
+        return {
+          id: "pi-settings", category: "agent", name: "Pi settings",
+          status: issues.length ? "warn" : "pass",
+          summary: issues.length ? `${issues.length} issue(s)` : `model: ${model}`,
+          details: issues.length ? issues : undefined,
+        };
+      } catch {
+        return {
+          id: "pi-settings", category: "agent", name: "Pi settings",
+          status: "warn", summary: "not found",
+          details: [`${settingsPath} does not exist`],
+        };
+      }
+    },
+  },
+];

package/src/cli/doctor/checks/config.ts

@@ -0,0 +1,88 @@
+/**
+ * Configuration checks
+ */
+
+import { readFile, access, mkdir } from "node:fs/promises";
+import { writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { DoctorCheck, DoctorContext, DoctorCheckResult } from "../types";
+import { DEFAULT_CONFIG } from "../../../config";
+
+export const configChecks: DoctorCheck[] = [
+  {
+    id: "config-dir", category: "config", name: "Config directory",
+    async run(ctx) {
+      const configDir = dirname(ctx.configPath);
+      try {
+        await access(configDir);
+        return { id: "config-dir", category: "config", name: "Config directory", status: "pass", summary: configDir };
+      } catch {
+        return {
+          id: "config-dir", category: "config", name: "Config directory", status: "warn", summary: "missing",
+          details: [`${configDir} does not exist`],
+          fix: {
+            description: "Create config directory",
+            command: `mkdir -p ${configDir}`,
+            run: async () => { await mkdir(configDir, { recursive: true }); return true; },
+          },
+        };
+      }
+    },
+  },
+
+  {
+    id: "config-file", category: "config", name: "Config file",
+    async run(ctx) {
+      try {
+        const raw = await readFile(ctx.configPath, "utf8");
+        try {
+          JSON.parse(raw);
+          return { id: "config-file", category: "config", name: "Config file", status: "pass", summary: ctx.configPath };
+        } catch {
+          return { id: "config-file", category: "config", name: "Config file", status: "fail", summary: "invalid JSON", details: [`${ctx.configPath} is not valid JSON`] };
+        }
+      } catch {
+        return {
+          id: "config-file", category: "config", name: "Config file", status: "warn", summary: "not found (defaults will be used)",
+          details: [`${ctx.configPath} does not exist`],
+          fix: {
+            description: "Create default config",
+            command: `roundhouse install`,
+            run: async () => {
+              const configDir = dirname(ctx.configPath);
+              await mkdir(configDir, { recursive: true });
+              await writeFile(ctx.configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n");
+              return true;
+            },
+          },
+        };
+      }
+    },
+  },
+
+  {
+    id: "config-schema", category: "config", name: "Config schema",
+    async run(ctx) {
+      try {
+        const raw = await readFile(ctx.configPath, "utf8");
+        const cfg = JSON.parse(raw);
+        const issues: string[] = [];
+        if (!cfg.agent?.type) issues.push("Missing agent.type");
+        if (!cfg.chat?.botUsername) issues.push("Missing chat.botUsername");
+        if (!cfg.chat?.adapters || Object.keys(cfg.chat.adapters).length === 0) issues.push("No chat adapters configured");
+        if (!cfg.chat?.allowedUsers?.length) issues.push("allowedUsers is empty (anyone can message the bot)");
+
+        if (issues.length === 0) {
+          return { id: "config-schema", category: "config", name: "Config schema", status: "pass", summary: "valid" };
+        }
+        const hasError = issues.some((i) => i.startsWith("Missing"));
+        return {
+          id: "config-schema", category: "config", name: "Config schema",
+          status: hasError ? "fail" : "warn", summary: `${issues.length} issue(s)`, details: issues,
+        };
+      } catch {
+        return { id: "config-schema", category: "config", name: "Config schema", status: "info", summary: "skipped (no config file)" };
+      }
+    },
+  },
+];

package/src/cli/doctor/checks/credentials.ts

@@ -0,0 +1,62 @@
+/**
+ * Credential checks
+ */
+
+import type { DoctorCheck } from "../types";
+
+export const credentialChecks: DoctorCheck[] = [
+  {
+    id: "telegram-token", category: "credentials", name: "Telegram bot token",
+    async run(ctx) {
+      // Check both process env and the systemd env file
+      let token = ctx.env.TELEGRAM_BOT_TOKEN;
+      if (!token) {
+        try {
+          const { readFile } = await import("node:fs/promises");
+          const envContent = await readFile(ctx.envFilePath, "utf8");
+          const match = envContent.match(/^TELEGRAM_BOT_TOKEN=(.+)$/m);
+          if (match) token = match[1].trim().replace(/^["']|["']$/g, "");
+        } catch {}
+      }
+      if (!token) {
+        return {
+          id: "telegram-token", category: "credentials", name: "Telegram bot token",
+          status: "fail", summary: "TELEGRAM_BOT_TOKEN not set",
+          details: ["Set TELEGRAM_BOT_TOKEN in your environment or ~/.roundhouse/env"],
+        };
+      }
+      if (!/^\d+:[A-Za-z0-9_-]+$/.test(token)) {
+        return {
+          id: "telegram-token", category: "credentials", name: "Telegram bot token",
+          status: "fail", summary: "invalid format",
+          details: ["Token should match pattern: digits:alphanumeric"],
+        };
+      }
+      // Try getMe
+      try {
+        const res = await fetch(`https://api.telegram.org/bot${token}/getMe`, {
+          signal: AbortSignal.timeout(10000),
+        });
+        if (res.ok) {
+          const data = await res.json() as any;
+          const username = data.result?.username ?? "unknown";
+          return {
+            id: "telegram-token", category: "credentials", name: "Telegram bot token",
+            status: "pass", summary: `@${username}`,
+          };
+        }
+        return {
+          id: "telegram-token", category: "credentials", name: "Telegram bot token",
+          status: "fail", summary: `API returned ${res.status}`,
+          details: ["Token may be invalid or revoked"],
+        };
+      } catch (err) {
+        return {
+          id: "telegram-token", category: "credentials", name: "Telegram bot token",
+          status: "warn", summary: "cannot reach Telegram API",
+          details: [(err as Error).message],
+        };
+      }
+    },
+  },
+];

package/src/cli/doctor/checks/disk.ts

@@ -0,0 +1,69 @@
+/**
+ * Disk and directory checks
+ */
+
+import { access, stat, readdir, constants } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { mkdirSync } from "node:fs";
+import type { DoctorCheck } from "../types";
+import { run } from "../shell";
+
+const INCOMING_DIR = process.env.ROUNDHOUSE_INCOMING_DIR ?? join(homedir(), ".roundhouse", "incoming");
+const SESSIONS_DIR = join(homedir(), ".pi", "agent", "gateway-sessions");
+
+export const diskChecks: DoctorCheck[] = [
+  {
+    id: "incoming-dir", category: "disk", name: "Incoming directory",
+    async run(ctx) {
+      try {
+        await access(INCOMING_DIR, constants.W_OK);
+        return { id: "incoming-dir", category: "disk", name: "Incoming directory", status: "pass", summary: INCOMING_DIR };
+      } catch {
+        return {
+          id: "incoming-dir", category: "disk", name: "Incoming directory",
+          status: "warn", summary: "missing or not writable",
+          details: [INCOMING_DIR],
+          fix: {
+            description: "Create incoming directory",
+            run: async () => { mkdirSync(INCOMING_DIR, { recursive: true }); return true; },
+          },
+        };
+      }
+    },
+  },
+
+  {
+    id: "sessions-dir", category: "disk", name: "Sessions directory",
+    async run() {
+      try {
+        await access(SESSIONS_DIR);
+        const threads = await readdir(SESSIONS_DIR);
+        return {
+          id: "sessions-dir", category: "disk", name: "Sessions directory",
+          status: "pass", summary: `${threads.length} thread(s)`,
+        };
+      } catch {
+        return {
+          id: "sessions-dir", category: "disk", name: "Sessions directory",
+          status: "info", summary: "not created yet (first message will create it)",
+        };
+      }
+    },
+  },
+
+  {
+    id: "disk-space", category: "disk", name: "Free disk space",
+    async run() {
+      const df = await run("df", ["-BM", "--output=avail", homedir()]);
+      if (!df) return { id: "disk-space", category: "disk", name: "Free disk space", status: "info", summary: "cannot check" };
+      const lines = df.split("\n").filter(Boolean);
+      const avail = parseInt(lines[lines.length - 1]);
+      if (isNaN(avail)) return { id: "disk-space", category: "disk", name: "Free disk space", status: "info", summary: "cannot parse" };
+      const gb = (avail / 1024).toFixed(1);
+      if (avail < 100) return { id: "disk-space", category: "disk", name: "Free disk space", status: "fail", summary: `${gb} GB`, details: ["Less than 100 MB free"] };
+      if (avail < 1024) return { id: "disk-space", category: "disk", name: "Free disk space", status: "warn", summary: `${gb} GB`, details: ["Less than 1 GB free"] };
+      return { id: "disk-space", category: "disk", name: "Free disk space", status: "pass", summary: `${gb} GB` };
+    },
+  },
+];

package/src/cli/doctor/checks/stt.ts

@@ -0,0 +1,76 @@
+/**
+ * STT / Voice checks
+ */
+
+import { access, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { DoctorCheck } from "../types";
+
+export const sttChecks: DoctorCheck[] = [
+  {
+    id: "whisper-model", category: "stt", name: "Whisper model cache",
+    async run() {
+      const modelDir = join(homedir(), ".cache", "whisper");
+      try {
+        const files = await readdir(modelDir);
+        const models = files.filter((f) => f.endsWith(".pt"));
+        if (models.length === 0) {
+          return {
+            id: "whisper-model", category: "stt", name: "Whisper model cache",
+            status: "warn", summary: "no models downloaded",
+            details: ["Model will download on first voice message (~461MB for small)"],
+          };
+        }
+        return {
+          id: "whisper-model", category: "stt", name: "Whisper model cache",
+          status: "pass", summary: models.join(", "),
+        };
+      } catch {
+        return {
+          id: "whisper-model", category: "stt", name: "Whisper model cache",
+          status: "info", summary: "cache dir not found",
+          details: [`${modelDir} does not exist yet`],
+        };
+      }
+    },
+  },
+
+  {
+    id: "whisper-tmp", category: "stt", name: "Whisper temp dirs",
+    async run() {
+      const tmpDir = join(homedir(), ".roundhouse", "whisper-tmp");
+      try {
+        const entries = await readdir(tmpDir);
+        if (entries.length === 0) {
+          return { id: "whisper-tmp", category: "stt", name: "Whisper temp dirs", status: "pass", summary: "clean" };
+        }
+        return {
+          id: "whisper-tmp", category: "stt", name: "Whisper temp dirs",
+          status: "warn", summary: `${entries.length} orphaned dir(s)`,
+          details: [`Leftover temp directories in ${tmpDir}`],
+          fix: {
+            description: "Clean orphaned temp dirs older than 1 hour",
+            run: async () => {
+              const { rm, stat: fsStat } = await import("node:fs/promises");
+              const cutoff = Date.now() - 60 * 60 * 1000;
+              let cleaned = 0;
+              for (const entry of entries) {
+                try {
+                  const s = await fsStat(join(tmpDir, entry));
+                  if (s.mtimeMs < cutoff) {
+                    await rm(join(tmpDir, entry), { recursive: true });
+                    cleaned++;
+                  }
+                } catch {}
+              }
+              return cleaned > 0;
+            },
+          },
+        };
+      } catch {
+        return { id: "whisper-tmp", category: "stt", name: "Whisper temp dirs", status: "pass", summary: "no temp dir" };
+      }
+    },
+  },
+];