botholomew 0.7.12 → 0.8.0

package/README.md

@@ -8,10 +8,10 @@
 
 ![Botholomew chat TUI](docs/assets/chat-happy-path.gif)
 
-**A local-first AI agent for knowledge work.** Botholomew is a long-running
-autonomous agent that works its way through a task queue — reading email,
-summarizing documents, researching topics, organizing notes, and maintaining
-context over time — while you sleep, work, or chat with it.
+**A local AI agent for knowledge work.** Botholomew is an autonomous agent
+that works its way through a task queue — reading email, summarizing
+documents, researching topics, organizing notes, and maintaining context
+over time — while you sleep, work, or chat with it.
 
 Unlike coding agents, Botholomew has **no shell, no filesystem, and no network
 tools** by default. Everything it touches lives inside a single DuckDB database
@@ -22,12 +22,12 @@ is granted deliberately, per project, through MCP servers.
 
 ## Why Botholomew?
 
-- **Autonomous.** A background daemon ticks on a schedule, claims tasks,
-  works them with Claude, and logs every interaction. You can close the
-  terminal and come back later.
+- **Autonomous.** Background **workers** claim tasks, work them with Claude,
+  and log every interaction. You can spawn one-shot workers on demand, a
+  long-running `--persist` worker, or point cron at `botholomew worker run`.
 - **Portable.** Each project is a `.botholomew/` directory — markdown +
   DuckDB. Copy it, share it, check it in (or `.gitignore` it).
-- **Local-first.** All data stays on your machine. Embeddings are indexed in
+- **Local.** All data stays on your machine. Embeddings are indexed in
   DuckDB's native vector store with HNSW. Model calls go direct to Anthropic
   and OpenAI.
 - **Extensible.** External tools come from MCP servers via
@@ -40,8 +40,9 @@ is granted deliberately, per project, through MCP servers.
   filesystem access of its own. Everything it can touch lives in
   `.botholomew/` — and every external capability is something you
   explicitly add.
-- **Self-healing.** An OS-level watchdog (launchd on macOS, systemd on Linux)
-  restarts the daemon if it dies, rotates logs, and runs on boot.
+- **Concurrent.** Many workers can run at once. Each registers itself in
+  the DB and heartbeats; crashed workers get reaped and their tasks go
+  back into the queue automatically.
 - **Self-modifying.** The agent maintains its own `beliefs.md` and
   `goals.md` — it learns, updates its priors, and revises its goals as it
   works.
@@ -80,13 +81,17 @@ export OPENAI_API_KEY=sk-...     # used for embeddings
 # 3. Queue some work
 botholomew task add "Summarize every markdown file in ~/notes"
 
-# 4. Start the daemon (foreground — watch it work)
-botholomew daemon start --foreground
+# 4. Run a worker to process the queue
+botholomew worker run                  # one-shot: claim and run one task
+botholomew worker run --persist        # long-running: loop until you stop it
 
 # 5. Or chat with the agent interactively
 botholomew chat
 ```
 
+See [docs/automation.md](docs/automation.md) for cron-based setups if you
+want Botholomew to advance on its own.
+
 ---
 
 ## What a project looks like
@@ -103,8 +108,7 @@ my-project/
     skills/               # user-defined slash commands
       summarize.md
       standup.md
-    daemon.pid            # PID file for the running daemon
-    daemon.log            # rotating daemon logs
+    worker.log            # stdout/stderr from spawned workers
 ```
 
 Everything the agent can touch is here. No surprises.
@@ -118,9 +122,8 @@ Everything the agent can touch is here. No surprises.
 | Command | Purpose |
 |---|---|
 | `botholomew init` | Create `.botholomew/` with templates and a fresh database |
-| `botholomew daemon start\|stop\|status` | Run, stop, or inspect the daemon |
-| `botholomew daemon install\|uninstall` | Register/remove the OS watchdog |
-| `botholomew daemon list` | List all Botholomew projects on this machine |
+| `botholomew worker run\|start` | Run a worker (foreground or background); `--persist` for long-running, `--task-id <id>` to target one task |
+| `botholomew worker list\|status\|stop\|kill\|reap` | Inspect and manage running workers |
 | `botholomew chat` | Interactive Ink/React TUI |
 | `botholomew task list\|add\|view\|update\|reset\|delete` | Manage the task queue |
 | `botholomew schedule list\|add\|enable\|trigger\|delete` | Recurring work |
@@ -140,16 +143,16 @@ All `list` subcommands support `-l, --limit <n>` and `-o, --offset <n>` for pagi
 
 ```
  ┌──────────────┐         ┌──────────────┐         ┌──────────────┐
- │    Chat      │         │   Daemon     │         │  Watchdog    │
- │   (Ink TUI)  │         │  (tick loop) │         │ launchd/     │
- │              │         │              │         │ systemd      │
+ │    Chat      │         │  Worker(s)   │         │    cron /    │
+ │   (Ink TUI)  │         │  (tick loop) │         │    tmux      │
+ │              │         │              │         │    (optional)│
  └──────┬───────┘         └──────┬───────┘         └──────┬───────┘
         │                        │                        │
-        │ enqueue tasks          │ claims tasks           │ every 60s:
-        │ browse history         │ runs LLM tool loops    │ check PID
-        │ invoke skills          │ updates status         │ restart if
-        │                        │ logs to threads        │ dead
-        │                        │                        │
+        │ enqueue tasks          │ register + heartbeat   │ fire
+        │ browse history         │ claim tasks            │ `worker run`
+        │ spawn_worker tool      │ run LLM tool loops     │ on a
+        │ invoke skills          │ reap dead peers        │ schedule
+        │                        │ log to threads         │
         └────────────┬───────────┴────────────┬───────────┘
                      │                        │
                ┌─────▼────────────────────────▼─────┐
@@ -157,7 +160,8 @@ All `list` subcommands support `-l, --limit <n>` and `-o, --offset <n>` for pagi
                │  ┌───────────┐ ┌──────────────┐    │
                │  │  tasks    │ │ context_items│    │
                │  │ schedules │ │  embeddings  │    │
-               │  │  threads  │ │   (HNSW)     │    │
+               │  │  workers  │ │   (HNSW)     │    │
+               │  │  threads  │ │              │    │
                │  └───────────┘ └──────────────┘    │
                └─────┬───────────────────────────────┘
                      │
@@ -173,11 +177,14 @@ See [docs/architecture.md](docs/architecture.md) for a deeper tour.
 
 Topics worth understanding in detail:
 
-- **[Architecture](docs/architecture.md)** — daemon, chat, watchdog, and how
-  they share a database.
+- **[Architecture](docs/architecture.md)** — workers, chat, and how
+  they share a database. Registration, heartbeat, and reaping.
+- **[Automation](docs/automation.md)** — cron recipes and optional
+  launchd/systemd samples for running workers on a schedule without a
+  shipped watchdog.
 - **[The TUI](docs/tui.md)** — the `botholomew chat` Ink/React terminal UI:
-  seven tabs, slash-command autocomplete, message queue, and tool-call
-  visualization.
+  eight tabs, slash-command autocomplete, message queue, tool-call
+  visualization, and a live workers panel.
 - **[The virtual filesystem](docs/virtual-filesystem.md)** — why the agent's
   "files" are actually DuckDB rows, and how `context_read`/`context_write` work.
 - **[Context & hybrid search](docs/context-and-search.md)** — LLM-driven
@@ -193,8 +200,6 @@ Topics worth understanding in detail:
   with positional arguments and tab completion.
 - **[MCPX integration](docs/mcpx.md)** — configuring external servers and
   how MCP tools are merged into the agent's toolset.
-- **[The watchdog](docs/watchdog.md)** — launchd plists, systemd units, and
-  multi-project service naming.
 - **[Configuration](docs/configuration.md)** — every key in `config.json`
   and its default.
 - **[Doc captures](docs/captures.md)** — how the screenshots and GIFs in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botholomew",
-  "version": "0.7.12",
+  "version": "0.8.0",
   "description": "Local, autonomous AI agent for knowledge work — works your task queue while you sleep.",
   "type": "module",
   "bin": {

package/src/chat/agent.ts

@@ -6,14 +6,6 @@ import type {
 import type { McpxClient } from "@evantahler/mcpx";
 import type { BotholomewConfig } from "../config/schemas.ts";
 import { embedSingle } from "../context/embedder.ts";
-import { fitToContextWindow, getMaxInputTokens } from "../daemon/context.ts";
-import { maybeStoreResult } from "../daemon/large-results.ts";
-import { createLlmClient } from "../daemon/llm-client.ts";
-import {
-  buildMetaHeader,
-  extractKeywords,
-  loadPersistentContext,
-} from "../daemon/prompt.ts";
 import { withDb } from "../db/connection.ts";
 import { hybridSearch } from "../db/embeddings.ts";
 import { logInteraction } from "../db/threads.ts";
@@ -25,10 +17,18 @@ import {
   toAnthropicTool,
 } from "../tools/tool.ts";
 import { logger } from "../utils/logger.ts";
+import { fitToContextWindow, getMaxInputTokens } from "../worker/context.ts";
+import { maybeStoreResult } from "../worker/large-results.ts";
+import { createLlmClient } from "../worker/llm-client.ts";
+import {
+  buildMetaHeader,
+  extractKeywords,
+  loadPersistentContext,
+} from "../worker/prompt.ts";
 
 registerAllTools();
 
-/** Tools available in chat mode — no daemon terminal tools, no destructive file tools */
+/** Tools available in chat mode — no worker terminal tools, no destructive file tools */
 const CHAT_TOOL_NAMES = new Set([
   "create_task",
   "list_tasks",
@@ -36,6 +36,7 @@ const CHAT_TOOL_NAMES = new Set([
   "context_search",
   "context_info",
   "context_refresh",
+  "context_tree",
   "search_grep",
   "search_semantic",
   "list_threads",
@@ -49,6 +50,7 @@ const CHAT_TOOL_NAMES = new Set([
   "mcp_info",
   "mcp_exec",
   "read_large_result",
+  "spawn_worker",
 ]);
 
 export function getChatTools() {
@@ -102,10 +104,10 @@ export async function buildChatSystemPrompt(
 
   parts.push("## Instructions");
   parts.push(
-    "You are Botholomew, an AI agent personified by a wise owl. This is your interactive chat interface. Help the user manage tasks, review results from daemon activity, search context, and answer questions.",
+    "You are Botholomew, an AI agent personified by a wise owl. This is your interactive chat interface. Help the user manage tasks, review results from background worker activity, search context, and answer questions.",
   );
   parts.push(
-    "You do NOT execute long-running work directly — enqueue tasks for the daemon instead using create_task.",
+    "You do NOT execute long-running work directly — enqueue tasks for a background worker instead using create_task, and spawn a worker via spawn_worker when the user wants the task run now.",
   );
   parts.push(
     "Use the available tools to look up tasks, threads, schedules, and context when the user asks about them. Context items can be looked up by virtual path or by UUID via `context_info` and refreshed via `context_refresh`.",

package/src/cli.ts

@@ -5,7 +5,6 @@ import { program } from "commander";
 import { registerChatCommand } from "./commands/chat.ts";
 import { registerCheckUpdateCommand } from "./commands/check-update.ts";
 import { registerContextCommand } from "./commands/context.ts";
-import { registerDaemonCommand } from "./commands/daemon.ts";
 import { registerInitCommand } from "./commands/init.ts";
 import { registerMcpxCommand } from "./commands/mcpx.ts";
 import { registerNukeCommand } from "./commands/nuke.ts";
@@ -15,6 +14,7 @@ import { registerSkillCommand } from "./commands/skill.ts";
 import { registerTaskCommand } from "./commands/task.ts";
 import { registerThreadCommand } from "./commands/thread.ts";
 import { registerUpgradeCommand } from "./commands/upgrade.ts";
+import { registerWorkerCommand } from "./commands/worker.ts";
 import { maybeCheckForUpdate } from "./update/background.ts";
 
 const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
@@ -33,7 +33,7 @@ program
   });
 
 registerInitCommand(program);
-registerDaemonCommand(program);
+registerWorkerCommand(program);
 registerTaskCommand(program);
 registerThreadCommand(program);
 registerScheduleCommand(program);

package/src/commands/chat.ts

@@ -16,49 +16,34 @@ export function registerChatCommand(program: Command) {
     )
     .option("--thread-id <id>", "Resume an existing chat thread")
     .option("-p, --prompt <text>", "Start chat with an initial prompt")
-    .option("--no-daemon", "don't auto-start the daemon")
-    .action(
-      async (opts: {
-        threadId?: string;
-        prompt?: string;
-        daemon?: boolean;
-      }) => {
-        const { render } = await import("ink");
-        const React = await import("react");
-        const { App } = await import("../tui/App.tsx");
-        const dir = program.opts().dir;
+    .action(async (opts: { threadId?: string; prompt?: string }) => {
+      const { render } = await import("ink");
+      const React = await import("react");
+      const { App } = await import("../tui/App.tsx");
+      const dir = program.opts().dir;
 
-        // Auto-spawn daemon if not running (attached mode)
-        if (opts.daemon !== false) {
-          const { ensureDaemonRunning } = await import(
-            "../daemon/ensure-running.ts"
-          );
-          await ensureDaemonRunning(dir);
-        }
-
-        // VHS/ttyd doesn't fully negotiate the Kitty Keyboard protocol, so
-        // Ink's "enabled" mode drops non-text keystrokes (Tab, Escape) under
-        // capture. Use "disabled" mode in capture to keep text input working;
-        // captures that need Tab/Escape should use the `-p` prompt flag or
-        // a /slash command typed as text instead.
-        const isCapture = process.env.BOTHOLOMEW_FAKE_LLM === "1";
-        const instance = render(
-          React.createElement(App, {
-            projectDir: dir,
-            threadId: opts.threadId,
-            initialPrompt: opts.prompt,
-          }),
-          {
-            exitOnCtrlC: false,
-            kittyKeyboard: isCapture
-              ? { mode: "disabled" }
-              : {
-                  mode: "enabled",
-                  flags: ["disambiguateEscapeCodes"],
-                },
-          },
-        );
-        await instance.waitUntilExit();
-      },
-    );
+      // VHS/ttyd doesn't fully negotiate the Kitty Keyboard protocol, so
+      // Ink's "enabled" mode drops non-text keystrokes (Tab, Escape) under
+      // capture. Use "disabled" mode in capture to keep text input working;
+      // captures that need Tab/Escape should use the `-p` prompt flag or
+      // a /slash command typed as text instead.
+      const isCapture = process.env.BOTHOLOMEW_FAKE_LLM === "1";
+      const instance = render(
+        React.createElement(App, {
+          projectDir: dir,
+          threadId: opts.threadId,
+          initialPrompt: opts.prompt,
+        }),
+        {
+          exitOnCtrlC: false,
+          kittyKeyboard: isCapture
+            ? { mode: "disabled" }
+            : {
+                mode: "enabled",
+                flags: ["disambiguateEscapeCodes"],
+              },
+        },
+      );
+      await instance.waitUntilExit();
+    });
 }

package/src/commands/nuke.ts

@@ -6,8 +6,8 @@ import { deleteAllDaemonState } from "../db/daemon-state.ts";
 import { deleteAllSchedules } from "../db/schedules.ts";
 import { deleteAllTasks } from "../db/tasks.ts";
 import { deleteAllThreads } from "../db/threads.ts";
+import { listWorkers } from "../db/workers.ts";
 import { logger } from "../utils/logger.ts";
-import { getDaemonStatus } from "../utils/pid.ts";
 import { withDb } from "./with-db.ts";
 
 type NukeScope = "context" | "tasks" | "schedules" | "threads" | "all";
@@ -49,12 +49,15 @@ function printDryRun(scope: NukeScope, counts: Record<string, number>) {
   );
 }
 
-async function ensureDaemonStopped(dir: string): Promise<boolean> {
-  const status = await getDaemonStatus(dir);
-  if (status) {
+async function ensureNoRunningWorkers(conn: DbConnection): Promise<boolean> {
+  const running = await listWorkers(conn, { status: "running" });
+  if (running.length > 0) {
     logger.error(
-      `Daemon is running (PID ${status.pid}). Stop it first: botholomew daemon stop`,
+      `${running.length} worker(s) running. Stop them first: botholomew worker stop <id>`,
     );
+    for (const w of running) {
+      logger.dim(`  ${w.id} (pid ${w.pid}, mode=${w.mode})`);
+    }
     return false;
   }
   return true;
@@ -101,8 +104,8 @@ function registerScope(
     .description(description)
     .option("-y, --yes", "confirm the deletion (required)")
     .action((opts) =>
-      withDb(program, async (conn, dir) => {
-        if (!(await ensureDaemonStopped(dir))) {
+      withDb(program, async (conn) => {
+        if (!(await ensureNoRunningWorkers(conn))) {
           process.exit(1);
         }
         const tables = TABLES_BY_SCOPE[scope];
@@ -138,7 +141,7 @@ export function registerNukeCommand(program: Command) {
     program,
     nuke,
     "threads",
-    "Erase all threads and interactions (daemon + chat history)",
+    "Erase all threads and interactions (worker + chat history)",
   );
   registerScope(
     program,

package/src/commands/schedule.ts

@@ -134,7 +134,7 @@ export function registerScheduleCommand(program: Command) {
         }
 
         // Lazy import to avoid loading LLM deps for non-trigger commands
-        const { evaluateSchedule } = await import("../daemon/schedules.ts");
+        const { evaluateSchedule } = await import("../worker/schedules.ts");
         const { loadConfig } = await import("../config/loader.ts");
         const { createTask } = await import("../db/tasks.ts");
         const { markScheduleRun } = await import("../db/schedules.ts");

package/src/commands/thread.ts

@@ -18,7 +18,7 @@ export function registerThreadCommand(program: Command) {
   thread
     .command("list")
     .description("List threads")
-    .option("-t, --type <type>", "filter by type (daemon_tick, chat_session)")
+    .option("-t, --type <type>", "filter by type (worker_tick, chat_session)")
     .option("-l, --limit <n>", "max number of threads", Number.parseInt)
     .option("-o, --offset <n>", "skip first N threads", Number.parseInt)
     .action((opts) =>
@@ -156,7 +156,7 @@ export function registerThreadCommand(program: Command) {
 
 function typeColor(type: Thread["type"]): string {
   switch (type) {
-    case "daemon_tick":
+    case "worker_tick":
       return ansis.magenta(type);
     case "chat_session":
       return ansis.cyan(type);

package/src/commands/with-db.ts

@@ -7,7 +7,7 @@ import { migrate } from "../db/schema.ts";
 /**
  * Open a migrated DB connection from the CLI --dir flag, run the callback,
  * and guarantee the connection is closed afterward. Retries on lock
- * conflicts so CLI invocations cooperate with a running daemon/chat.
+ * conflicts so CLI invocations cooperate with running workers or chat.
  */
 export async function withDb<T>(
   program: Command,

package/src/commands/worker.ts

@@ -0,0 +1,231 @@
+import ansis from "ansis";
+import type { Command } from "commander";
+import { loadConfig } from "../config/loader.ts";
+import {
+  getWorker,
+  listWorkers,
+  markWorkerDead,
+  markWorkerStopped,
+  pruneStoppedWorkers,
+  reapDeadWorkers,
+  WORKER_STATUSES,
+  type Worker,
+} from "../db/workers.ts";
+import { logger } from "../utils/logger.ts";
+import { withDb } from "./with-db.ts";
+
+function formatAge(from: Date, to = new Date()): string {
+  const secs = Math.max(0, Math.floor((to.getTime() - from.getTime()) / 1000));
+  if (secs < 60) return `${secs}s ago`;
+  const mins = Math.floor(secs / 60);
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+function statusColor(status: Worker["status"]): string {
+  switch (status) {
+    case "running":
+      return ansis.green(status);
+    case "stopped":
+      return ansis.dim(status);
+    case "dead":
+      return ansis.red(status);
+  }
+}
+
+function printWorker(w: Worker) {
+  const short = w.id.slice(0, 8);
+  const lines = [
+    `${ansis.bold(short)}  pid=${w.pid}  mode=${w.mode}  ${statusColor(w.status)}  host=${w.hostname}`,
+    `  started: ${w.started_at.toISOString()} (${formatAge(w.started_at)})`,
+    `  heartbeat: ${w.last_heartbeat_at.toISOString()} (${formatAge(w.last_heartbeat_at)})`,
+  ];
+  if (w.task_id) lines.push(`  task: ${w.task_id}`);
+  if (w.stopped_at) lines.push(`  stopped: ${w.stopped_at.toISOString()}`);
+  console.log(lines.join("\n"));
+}
+
+export function registerWorkerCommand(program: Command) {
+  const worker = program
+    .command("worker")
+    .description("Manage background workers that claim and run tasks");
+
+  worker
+    .command("run")
+    .description(
+      "Run a worker in the foreground. One-shot by default: claims one task and exits. Use --persist for a long-running tick loop.",
+    )
+    .option("--persist", "keep running, looping over the tick cycle", false)
+    .option(
+      "--task-id <id>",
+      "run exactly this task (implies one-shot; incompatible with --persist)",
+    )
+    .option("--no-eval-schedules", "skip schedule evaluation this run")
+    .action(
+      async (opts: {
+        persist?: boolean;
+        taskId?: string;
+        evalSchedules?: boolean;
+      }) => {
+        if (opts.persist && opts.taskId) {
+          logger.error("--persist and --task-id are mutually exclusive.");
+          process.exit(1);
+        }
+        const dir = program.opts().dir;
+        const { startWorker } = await import("../worker/index.ts");
+        await startWorker(dir, {
+          foreground: true,
+          mode: opts.persist ? "persist" : "once",
+          taskId: opts.taskId,
+          evalSchedules: opts.evalSchedules,
+        });
+      },
+    );
+
+  worker
+    .command("start")
+    .description("Spawn a worker as a detached background process")
+    .option("--persist", "keep running, looping over the tick cycle", false)
+    .option("--task-id <id>", "run exactly this task (implies one-shot)")
+    .action(async (opts: { persist?: boolean; taskId?: string }) => {
+      if (opts.persist && opts.taskId) {
+        logger.error("--persist and --task-id are mutually exclusive.");
+        process.exit(1);
+      }
+      const dir = program.opts().dir;
+      const { spawnWorker } = await import("../worker/spawn.ts");
+      await spawnWorker(dir, {
+        mode: opts.persist ? "persist" : "once",
+        taskId: opts.taskId,
+      });
+    });
+
+  worker
+    .command("list")
+    .description("List workers registered in this project's database")
+    .option(
+      "-s, --status <status>",
+      `filter by status (${WORKER_STATUSES.join("|")})`,
+    )
+    .option("-l, --limit <n>", "max number of workers", Number.parseInt)
+    .option("-o, --offset <n>", "skip first N workers", Number.parseInt)
+    .action(
+      (opts: { status?: Worker["status"]; limit?: number; offset?: number }) =>
+        withDb(program, async (conn) => {
+          if (opts.status && !WORKER_STATUSES.includes(opts.status)) {
+            logger.error(
+              `Unknown status: ${opts.status}. Use one of: ${WORKER_STATUSES.join(", ")}`,
+            );
+            process.exit(1);
+          }
+          const workers = await listWorkers(conn, {
+            status: opts.status,
+            limit: opts.limit,
+            offset: opts.offset,
+          });
+          if (workers.length === 0) {
+            logger.dim("No workers found.");
+            return;
+          }
+          for (const w of workers) {
+            printWorker(w);
+            console.log("");
+          }
+        }),
+    );
+
+  worker
+    .command("status <id>")
+    .description("Show details for a single worker")
+    .action((id: string) =>
+      withDb(program, async (conn) => {
+        const w = await getWorker(conn, id);
+        if (!w) {
+          logger.error(`No worker found with id ${id}.`);
+          process.exit(1);
+        }
+        printWorker(w);
+      }),
+    );
+
+  worker
+    .command("stop <id>")
+    .description("SIGTERM the worker's process (graceful) and mark stopped")
+    .action((id: string) =>
+      withDb(program, async (conn) => {
+        const w = await getWorker(conn, id);
+        if (!w) {
+          logger.error(`No worker found with id ${id}.`);
+          process.exit(1);
+        }
+        signalWorker(w, "SIGTERM");
+        await markWorkerStopped(conn, id);
+        logger.success(`Worker ${id} signaled (SIGTERM) and marked stopped.`);
+      }),
+    );
+
+  worker
+    .command("kill <id>")
+    .description("SIGKILL the worker's process and mark dead")
+    .action((id: string) =>
+      withDb(program, async (conn) => {
+        const w = await getWorker(conn, id);
+        if (!w) {
+          logger.error(`No worker found with id ${id}.`);
+          process.exit(1);
+        }
+        signalWorker(w, "SIGKILL");
+        await markWorkerDead(conn, id);
+        logger.success(`Worker ${id} killed (SIGKILL) and marked dead.`);
+      }),
+    );
+
+  worker
+    .command("reap")
+    .description(
+      "Mark stale workers dead (releasing their tasks/schedule claims) and prune cleanly-stopped workers older than the retention window",
+    )
+    .action(() =>
+      withDb(program, async (conn, dir) => {
+        const config = await loadConfig(dir);
+        const reaped = await reapDeadWorkers(
+          conn,
+          config.worker_dead_after_seconds,
+        );
+        if (reaped.length === 0) {
+          logger.dim("No stale workers to reap.");
+        } else {
+          logger.success(
+            `Reaped ${reaped.length} worker(s): ${reaped.join(", ")}`,
+          );
+        }
+        const pruned = await pruneStoppedWorkers(
+          conn,
+          config.worker_stopped_retention_seconds,
+        );
+        if (pruned.length > 0) {
+          logger.success(
+            `Pruned ${pruned.length} stopped worker(s) older than retention window.`,
+          );
+        }
+      }),
+    );
+}
+
+function signalWorker(w: Worker, signal: "SIGTERM" | "SIGKILL"): void {
+  if (w.status !== "running") {
+    logger.warn(
+      `Worker ${w.id} already ${w.status}; signaling PID ${w.pid} anyway.`,
+    );
+  }
+  try {
+    process.kill(w.pid, signal);
+  } catch (err) {
+    logger.warn(
+      `Could not send ${signal} to PID ${w.pid}: ${err instanceof Error ? err.message : err}. Marking DB state only.`,
+    );
+  }
+}