botholomew 0.20.0 → 0.21.0

package/README.md

@@ -76,13 +76,23 @@ the message queue, tool-call visualization, and the live workers panel:
 
 ## Install
 
-Requires [Bun](https://bun.sh) 1.1+.
+**Prebuilt binary** (no Bun required — one self-contained file per platform):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/evantahler/botholomew/main/install.sh | sh
+```
+
+macOS (arm64) and Linux (x64); on Windows grab `botholomew-windows-x64.exe`
+from the [releases](https://github.com/evantahler/botholomew/releases/latest). Then
+`botholomew upgrade` updates it in place.
+
+**With Bun** (requires [Bun](https://bun.sh) 1.1+):
 
 ```bash
 bun install -g botholomew
 ```
 
-The CLI installs as both `botholomew` and `bothy` — the same binary, two names.
+Either way the CLI installs as both `botholomew` and `bothy` — the same binary, two names.
 
 Or run the dev build from a checkout:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botholomew",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "An autonomous AI agent for knowledge work — works your task queue while you sleep.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "dev:demo": "bun run src/cli.ts chat -p 'learn everything you can about me from the connected MCP services and then save what you'\\''ve learned about me to context'",
     "test": "bun test",
     "lint": "tsc --noEmit && biome check .",
+    "build": "bun run scripts/build.ts",
     "capture": "bun run scripts/capture.ts",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",

package/src/cli-standalone.ts

@@ -0,0 +1,76 @@
+#!/usr/bin/env bun
+// Virtual specifiers supplied + embedded (via the "file" loader) by
+// scripts/build.ts at compile time; each resolves to its $bunfs path string.
+// @ts-expect-error: virtual module resolved + embedded by scripts/build.ts at compile time
+import dylibPath from "bothy:duckdb-dylib";
+// @ts-expect-error: virtual module resolved + embedded by scripts/build.ts at compile time
+import ortMjsPath from "bothy:ort-wasm-mjs";
+// @ts-expect-error: virtual module resolved + embedded by scripts/build.ts at compile time
+import ortWasmPath from "bothy:ort-wasm-wasm";
+// Build-only entrypoint for the compiled binary (`bun run build`; see
+// scripts/build.ts). Not used under `bun run` in dev.
+//
+// A `bun build --compile` binary has no node_modules on disk, and Bun resolves
+// neither externalized native packages nor `import.meta.resolve(...)` against
+// the real filesystem. So we EMBED the native assets that can't be bundled —
+// DuckDB's shared library and onnxruntime-web's WASM runtime — and stage them
+// in a temp dir BEFORE the code that loads them runs:
+//   • DuckDB: the embedded `duckdb.node` is extracted by Bun into os.tmpdir()
+//     and dlopens its library via an `@loader_path` rpath, so the library must
+//     sit in that same dir.
+//   • Embeddings: membot's embedder reads BOTHOLOMEW_ORT_WASM_{MJS,WASM} (the
+//     build rewrites its `import.meta.resolve(...)` calls to use these) instead
+//     of resolving onnxruntime-web from a (missing) node_modules.
+// The dynamic `import("./cli.ts")` guarantees all of this is in place before the
+// real CLI — and its transitive duckdb/transformers imports — are evaluated.
+import {
+  existsSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { MCPX_CLI_SENTINEL, MEMBOT_CLI_SENTINEL } from "./runtime.ts";
+
+const stageDir = realpathSync(tmpdir());
+
+/** Copy an embedded asset into the temp dir (skip if an identical one exists). */
+function stage(embedded: string, name: string): string {
+  const dest = join(stageDir, name);
+  if (!existsSync(dest) || statSync(dest).size !== statSync(embedded).size) {
+    writeFileSync(dest, readFileSync(embedded));
+  }
+  return dest;
+}
+
+// DuckDB shared library — must land where Bun extracts the addon (os.tmpdir())
+// under exactly the name the addon's rpath expects. scripts/build.ts globs that
+// name from the binding package and injects it here via --define.
+declare const BOTHOLOMEW_DUCKDB_LIB: string;
+stage(dylibPath, BOTHOLOMEW_DUCKDB_LIB);
+
+// onnxruntime-web WASM runtime — staged side by side; membot's embedder reads
+// these env vars (the build rewrites its import.meta.resolve calls).
+const mjs = stage(ortMjsPath, "ort-wasm-simd-threaded.asyncify.mjs");
+const wasm = stage(ortWasmPath, "ort-wasm-simd-threaded.asyncify.wasm");
+process.env.BOTHOLOMEW_ORT_WASM_MJS = pathToFileURL(mjs).href;
+process.env.BOTHOLOMEW_ORT_WASM_WASM = pathToFileURL(wasm).href;
+
+// The membot/mcpx passthroughs re-exec this binary with a sentinel arg; hand
+// off to the bundled upstream CLI in this dedicated process (commands/membot.ts,
+// commands/mcpx.ts). Otherwise run the normal Botholomew CLI.
+const argv = process.argv;
+const membotIdx = argv.indexOf(MEMBOT_CLI_SENTINEL);
+const mcpxIdx = argv.indexOf(MCPX_CLI_SENTINEL);
+if (membotIdx !== -1) {
+  process.argv = [process.execPath, "membot", ...argv.slice(membotIdx + 1)];
+  await import("membot/cli");
+} else if (mcpxIdx !== -1) {
+  process.argv = [process.execPath, "mcpx", ...argv.slice(mcpxIdx + 1)];
+  await import("@evantahler/mcpx/cli");
+} else {
+  await import("./cli.ts");
+}

package/src/cli.ts

@@ -17,9 +17,27 @@ 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 { pkg } from "./pkg.ts";
+import { IS_COMPILED_BINARY } from "./runtime.ts";
 import { maybeCheckForUpdate } from "./update/background.ts";
+import { runWorkerFromArgv } from "./worker/run.ts";
+import { WORKER_RUN_SENTINEL } from "./worker/sentinel.ts";
 
-const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
+// In a compiled binary there is no source tree to `bun run`, so a backgrounded
+// worker re-execs this binary with a sentinel arg (see worker/spawn.ts). Handle
+// it before commander sees it. Also force the embedder to stay in-process —
+// membot's subprocess pool would re-exec the binary with its own sentinel,
+// which our CLI doesn't understand.
+if (IS_COMPILED_BINARY) {
+  process.env.MEMBOT_EMBEDDING_WORKERS ??= "1";
+  // Find the sentinel by value rather than position — Bun's compiled-binary
+  // argv layout differs from `bun run`, so we slice everything after it.
+  const sentinelIdx = process.argv.indexOf(WORKER_RUN_SENTINEL);
+  if (sentinelIdx !== -1) {
+    await runWorkerFromArgv(process.argv.slice(sentinelIdx + 1));
+    process.exit(0);
+  }
+}
 
 program
   .name("botholomew")

package/src/commands/check-update.ts

@@ -1,13 +1,10 @@
 import { cyan, dim, green, yellow } from "ansis";
 import type { Command } from "commander";
+import { pkg } from "../pkg.ts";
 import { saveUpdateCache } from "../update/cache.ts";
 import type { UpdateCache } from "../update/checker.ts";
 import { checkForUpdate } from "../update/checker.ts";
 
-const pkg = await Bun.file(
-  new URL("../../package.json", import.meta.url),
-).json();
-
 export function registerCheckUpdateCommand(program: Command) {
   program
     .command("check-update")

package/src/commands/mcpx.ts

@@ -8,22 +8,44 @@ import { createSpinner } from "nanospinner";
 import { loadConfig } from "../config/loader.ts";
 import { getMcpxDir } from "../constants.ts";
 import { createMcpxClient, resolveMcpxDir } from "../mcpx/client.ts";
+import { pkg as ourPkg } from "../pkg.ts";
 import { writeCapabilitiesFile } from "../prompts/capabilities.ts";
+import { IS_COMPILED_BINARY, MCPX_CLI_SENTINEL } from "../runtime.ts";
 import { registerAllTools } from "../tools/registry.ts";
 import { logger } from "../utils/logger.ts";
 
-const require = createRequire(import.meta.url);
-const ourPkg = require("../../package.json");
-const mcpxPkg = require("@evantahler/mcpx/package.json");
-
-if (mcpxPkg.version !== ourPkg.dependencies["@evantahler/mcpx"]) {
-  throw new Error(
-    `@evantahler/mcpx version mismatch: installed ${mcpxPkg.version}, expected ${ourPkg.dependencies["@evantahler/mcpx"]}`,
-  );
+// Resolve the upstream mcpx CLI lazily — see commands/membot.ts for why this
+// can't run at module load (no node_modules in a `bun build --compile` binary).
+let mcpxCli: string | null | undefined;
+function resolveMcpxCli(): string {
+  if (mcpxCli === undefined) {
+    mcpxCli = null;
+    try {
+      const cli = fileURLToPath(import.meta.resolve("@evantahler/mcpx/cli"));
+      if (existsSync(cli)) mcpxCli = cli;
+    } catch {
+      // unresolvable (e.g. standalone binary) — handled below
+    }
+    if (mcpxCli) {
+      // Strict version pin — only checkable when mcpx is actually reachable.
+      const require = createRequire(import.meta.url);
+      const mcpxPkg = require("@evantahler/mcpx/package.json");
+      if (mcpxPkg.version !== ourPkg.dependencies["@evantahler/mcpx"]) {
+        throw new Error(
+          `@evantahler/mcpx version mismatch: installed ${mcpxPkg.version}, expected ${ourPkg.dependencies["@evantahler/mcpx"]}`,
+        );
+      }
+    }
+  }
+  if (!mcpxCli) {
+    logger.error(
+      "The `botholomew mcpx` passthrough requires a reachable @evantahler/mcpx install, which the standalone binary doesn't bundle. Install botholomew via npm/Bun, or run `mcpx` directly.",
+    );
+    process.exit(1);
+  }
+  return mcpxCli;
 }
 
-const MCPX_CLI = fileURLToPath(import.meta.resolve("@evantahler/mcpx/cli"));
-
 export async function runMcpx(
   projectDir: string,
   args: (string | undefined)[],
@@ -35,7 +57,12 @@ export async function runMcpx(
   const config = await loadConfig(projectDir);
   const mcpxDir = resolveMcpxDir(projectDir, config);
   const filteredArgs = args.filter((a): a is string => a !== undefined);
-  const proc = Bun.spawn(["bun", MCPX_CLI, ...filteredArgs, "-c", mcpxDir], {
+  // In the compiled binary, re-exec ourselves with the sentinel so the bundled
+  // mcpx CLI runs; under Bun, spawn the resolved on-disk mcpx CLI.
+  const cmd = IS_COMPILED_BINARY
+    ? [process.execPath, MCPX_CLI_SENTINEL, ...filteredArgs, "-c", mcpxDir]
+    : ["bun", resolveMcpxCli(), ...filteredArgs, "-c", mcpxDir];
+  const proc = Bun.spawn(cmd, {
     stdout: opts?.inherit ? "inherit" : "pipe",
     stderr: opts?.inherit ? "inherit" : "pipe",
     stdin: opts?.inherit ? "inherit" : undefined,

package/src/commands/membot.ts

@@ -7,23 +7,52 @@ import type { Command } from "commander";
 import { defaultCliName, OPERATIONS } from "membot";
 import { loadConfig } from "../config/loader.ts";
 import { resolveMembotDir } from "../mem/client.ts";
+import { pkg as ourPkg } from "../pkg.ts";
+import { IS_COMPILED_BINARY, MEMBOT_CLI_SENTINEL } from "../runtime.ts";
 import { logger } from "../utils/logger.ts";
 
-const require = createRequire(import.meta.url);
-const ourPkg = require("../../package.json");
-const membotPkg = require("membot/package.json");
-
-// Soft warning rather than a hard error — membot's SDK API is stable within a
-// minor version, and dev workspaces sometimes pin a newer copy.
-const requested = (ourPkg.dependencies.membot as string).replace(/^[\^~]/, "");
-if (!membotPkg.version.startsWith(requested.split(".")[0])) {
-  logger.warn(
-    `membot version drift: installed ${membotPkg.version}, expected ${ourPkg.dependencies.membot}`,
-  );
+// Resolve the upstream membot CLI lazily. `import.meta.resolve` walks
+// node_modules on disk, which a `bun build --compile` binary doesn't have, so
+// resolving at module load would crash *every* command. On first use we resolve
+// it, soft-check version drift, and fail this passthrough alone with a clear
+// message when membot isn't reachable (e.g. inside the standalone binary).
+let membotCli: string | null | undefined;
+function resolveMembotCli(): string {
+  if (membotCli === undefined) {
+    membotCli = null;
+    try {
+      const cli = fileURLToPath(import.meta.resolve("membot/cli"));
+      if (existsSync(cli)) {
+        membotCli = cli;
+        try {
+          const require = createRequire(import.meta.url);
+          const membotPkg = require("membot/package.json");
+          const requested = (ourPkg.dependencies.membot as string).replace(
+            /^[\^~]/,
+            "",
+          );
+          if (!membotPkg.version.startsWith(requested.split(".")[0])) {
+            logger.warn(
+              `membot version drift: installed ${membotPkg.version}, expected ${ourPkg.dependencies.membot}`,
+            );
+          }
+        } catch {
+          // best-effort version check — ignore if package.json isn't readable
+        }
+      }
+    } catch {
+      // unresolvable (e.g. standalone binary) — handled below
+    }
+  }
+  if (!membotCli) {
+    logger.error(
+      "The `botholomew membot` passthrough requires a reachable membot install, which the standalone binary doesn't bundle. Install botholomew via npm/Bun, or run `membot` directly.",
+    );
+    process.exit(1);
+  }
+  return membotCli;
 }
 
-const MEMBOT_CLI = fileURLToPath(import.meta.resolve("membot/cli"));
-
 function getDir(program: Command): string {
   return program.opts().dir;
 }
@@ -45,7 +74,12 @@ async function runMembot(projectDir: string, args: string[]): Promise<number> {
   // `membot` directly.
   const config = await loadConfig(projectDir);
   const membotDir = resolveMembotDir(projectDir, config);
-  const proc = Bun.spawn(["bun", MEMBOT_CLI, "--config", membotDir, ...args], {
+  // In the compiled binary, re-exec ourselves with the sentinel so the bundled
+  // membot CLI runs; under Bun, spawn the resolved on-disk membot CLI.
+  const cmd = IS_COMPILED_BINARY
+    ? [process.execPath, MEMBOT_CLI_SENTINEL, "--config", membotDir, ...args]
+    : ["bun", resolveMembotCli(), "--config", membotDir, ...args];
+  const proc = Bun.spawn(cmd, {
     stdout: "inherit",
     stderr: "inherit",
     stdin: "inherit",

package/src/commands/upgrade.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { dim, green, red, yellow } from "ansis";
 import { $ } from "bun";
 import type { Command } from "commander";
+import { pkg } from "../pkg.ts";
 import {
   clearUpdateCache,
   loadUpdateCache,
@@ -16,10 +17,6 @@ import {
   needsCheck,
 } from "../update/checker.ts";
 
-const pkg = await Bun.file(
-  new URL("../../package.json", import.meta.url),
-).json();
-
 const GITHUB_REPO = (pkg.repository.url as string)
   .replace(/^https:\/\/github\.com\//, "")
   .replace(/\.git$/, "");

package/src/pkg.ts

@@ -0,0 +1,10 @@
+// Single source of truth for our own package.json metadata.
+//
+// Imported statically (not read at runtime via `Bun.file(new URL(...))`) so the
+// values are inlined at `bun build --compile` time. A compiled standalone
+// binary has no package.json on disk beside it, so a runtime read would throw
+// at startup — even for `--version` / `--help`. The static import works in both
+// `bun run` (read from disk) and the compiled binary (inlined).
+import pkg from "../package.json" with { type: "json" };
+
+export { pkg };

package/src/runtime.ts

@@ -0,0 +1,25 @@
+// Runtime-environment detection shared across the CLI.
+
+/**
+ * True when running as a `bun build --compile` standalone binary rather than
+ * under the `bun` runtime (`bun run …` in dev, or the `bun install -g` shim).
+ *
+ * In a compiled binary `process.execPath` is the binary itself (e.g.
+ * `…/dist/bothy`); under Bun it is the `bun`/`bunx` executable. Several code
+ * paths must behave differently in a binary: there is no source tree or
+ * `node_modules` on disk, so we can't `bun run` a `.ts` worker entry and must
+ * instead re-exec the binary, and the embedder must stay in-process (no
+ * subprocess pool) since the pool would re-exec an unknown sentinel arg.
+ */
+export const IS_COMPILED_BINARY = !/[\\/]bunx?(\.exe)?$/i.test(
+  process.execPath,
+);
+
+/**
+ * Sentinels the compiled binary re-execs itself with to run a bundled upstream
+ * CLI in a fresh process (the binary embeds membot's and mcpx's CLIs, so the
+ * `botholomew membot`/`botholomew mcpx` passthroughs don't need those CLIs
+ * resolvable on disk). See cli-standalone.ts, commands/membot.ts, commands/mcpx.ts.
+ */
+export const MEMBOT_CLI_SENTINEL = "__botholomew_membot_cli__";
+export const MCPX_CLI_SENTINEL = "__botholomew_mcpx_cli__";

package/src/update/background.ts

@@ -1,12 +1,9 @@
 import { cyan, dim, yellow } from "ansis";
 import { DEFAULTS, ENV } from "../constants.ts";
+import { pkg } from "../pkg.ts";
 import { loadUpdateCache, saveUpdateCache } from "./cache.ts";
 import { checkForUpdate, needsCheck, type UpdateCache } from "./checker.ts";
 
-const pkg = await Bun.file(
-  new URL("../../package.json", import.meta.url),
-).json();
-
 /** Format an update notice for stderr output. */
 function formatNotice(
   currentVersion: string,

package/src/update/checker.ts

@@ -1,8 +1,5 @@
 import { DEFAULTS } from "../constants.ts";
-
-const pkg = await Bun.file(
-  new URL("../../package.json", import.meta.url),
-).json();
+import { pkg } from "../pkg.ts";
 
 const NPM_REGISTRY_URL = `https://registry.npmjs.org/${pkg.name}/latest`;
 const GITHUB_REPO = (pkg.repository.url as string)

package/src/worker/prompt.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { SERVER_INSTRUCTIONS as MEMBOT_INSTRUCTIONS } from "membot";
 import type { BotholomewConfig } from "../config/schemas.ts";
 import { getPromptsDir } from "../constants.ts";
+import { pkg } from "../pkg.ts";
 import type { Task } from "../tasks/schema.ts";
 import { parsePromptFile } from "../utils/frontmatter.ts";
 
@@ -17,10 +18,6 @@ export const MEMBOT_PROMPT_SECTION = `## Knowledge store (membot)
 ${MEMBOT_INSTRUCTIONS}
 `;
 
-const pkg = await Bun.file(
-  new URL("../../package.json", import.meta.url),
-).json();
-
 export const STYLE_RULES = `## Style
 - Open with the result, action, or next step. Skip preambles like "Great question", "You're absolutely right", "Let me…", "I'll go ahead and…".
 - Don't flatter the user or their ideas. If a request is wrong, ambiguous, or risky, say so plainly with the reason.

package/src/worker/run.ts

@@ -1,34 +1,53 @@
 #!/usr/bin/env bun
 
-// Standalone entry point for a worker when spawned as a detached process.
-// Usage: bun run src/worker/run.ts <projectDir> [--worker-id=<uuid>] [--log-path=<path>] [--persist] [--task-id=<uuid>] [--no-eval-schedules]
+// Worker entry when spawned as a detached process.
+//   - Dev / `bun install -g`: `bun run src/worker/run.ts <projectDir> [flags]`
+//   - Compiled binary: the parent re-execs the binary with WORKER_RUN_SENTINEL
+//     as argv[2] (see ../cli.ts and ./spawn.ts), then calls runWorkerFromArgv.
+// Flags: [--worker-id=<uuid>] [--log-path=<path>] [--persist] [--task-id=<uuid>] [--no-eval-schedules]
 
 import { startWorker } from "./index.ts";
 
-const projectDir = process.argv[2];
-if (!projectDir) {
-  console.error(
-    "Usage: bun run src/worker/run.ts <projectDir> [--worker-id=<uuid>] [--log-path=<path>] [--persist] [--task-id=<uuid>] [--no-eval-schedules]",
-  );
-  process.exit(1);
-}
+const USAGE =
+  "Usage: bun run src/worker/run.ts <projectDir> [--worker-id=<uuid>] [--log-path=<path>] [--persist] [--task-id=<uuid>] [--no-eval-schedules]";
+
+/**
+ * Parse worker args (`<projectDir> [flags]`) and start the worker. Shared by
+ * the standalone `run.ts` invocation (dev) and the binary's sentinel branch.
+ */
+export async function runWorkerFromArgv(args: string[]): Promise<void> {
+  const projectDir = args[0];
+  if (!projectDir) {
+    console.error(USAGE);
+    process.exit(1);
+  }
 
-const args = process.argv.slice(3);
-const persist = args.includes("--persist");
-const noEvalSchedules = args.includes("--no-eval-schedules");
-const taskIdArg = args.find((a) => a.startsWith("--task-id="));
-const taskId = taskIdArg ? taskIdArg.slice("--task-id=".length) : undefined;
-const workerIdArg = args.find((a) => a.startsWith("--worker-id="));
-const workerId = workerIdArg
-  ? workerIdArg.slice("--worker-id=".length)
-  : undefined;
-const logPathArg = args.find((a) => a.startsWith("--log-path="));
-const logPath = logPathArg ? logPathArg.slice("--log-path=".length) : undefined;
+  const flags = args.slice(1);
+  const persist = flags.includes("--persist");
+  const noEvalSchedules = flags.includes("--no-eval-schedules");
+  const taskIdArg = flags.find((a) => a.startsWith("--task-id="));
+  const taskId = taskIdArg ? taskIdArg.slice("--task-id=".length) : undefined;
+  const workerIdArg = flags.find((a) => a.startsWith("--worker-id="));
+  const workerId = workerIdArg
+    ? workerIdArg.slice("--worker-id=".length)
+    : undefined;
+  const logPathArg = flags.find((a) => a.startsWith("--log-path="));
+  const logPath = logPathArg
+    ? logPathArg.slice("--log-path=".length)
+    : undefined;
 
-await startWorker(projectDir, {
-  mode: persist ? "persist" : "once",
-  taskId,
-  workerId,
-  logPath,
-  evalSchedules: noEvalSchedules ? false : undefined,
-});
+  await startWorker(projectDir, {
+    mode: persist ? "persist" : "once",
+    taskId,
+    workerId,
+    logPath,
+    evalSchedules: noEvalSchedules ? false : undefined,
+  });
+}
+
+// Only run when invoked directly (`bun run …/run.ts`), not when imported by
+// cli.ts (the compiled binary's entrypoint), which would otherwise execute a
+// worker on every CLI invocation.
+if (import.meta.main) {
+  await runWorkerFromArgv(process.argv.slice(2));
+}

package/src/worker/sentinel.ts

@@ -0,0 +1,7 @@
+/**
+ * Sentinel arg the compiled binary re-execs itself with to run a background
+ * worker (see ../cli.ts and ./spawn.ts). Lives in its own leaf module — with no
+ * imports — so both the entrypoint and the spawner can use it without dragging
+ * the worker stack into a circular import.
+ */
+export const WORKER_RUN_SENTINEL = "__botholomew_worker_run__";

package/src/worker/spawn.ts

@@ -1,16 +1,36 @@
 import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import { getConfigPath, getWorkerLogPath } from "../constants.ts";
+import { IS_COMPILED_BINARY } from "../runtime.ts";
 import { logger } from "../utils/logger.ts";
 import { uuidv7 } from "../utils/uuid.ts";
 import { dateForId } from "../utils/v7-date.ts";
 import type { WorkerMode } from "./index.ts";
+import { WORKER_RUN_SENTINEL } from "./sentinel.ts";
 
 export interface SpawnWorkerOptions {
   mode?: WorkerMode;
   taskId?: string;
 }
 
+/**
+ * Env for a detached worker whose stdout/stderr is a log file: force no ANSI
+ * color. `ansis` (and other color libs) read these vars at import time, and
+ * `FORCE_COLOR` overrides `NO_COLOR`, so we must remove the forcing vars in
+ * addition to setting `NO_COLOR`. Without this, an interactive shell's inherited
+ * `FORCE_COLOR`/`COLORTERM` would make ansis emit escape codes into the log file
+ * even though the child's stdout is a file, not a TTY.
+ */
+export function colorlessEnv(
+  base: Record<string, string | undefined> = process.env,
+): Record<string, string | undefined> {
+  const env: Record<string, string | undefined> = { ...base };
+  env.NO_COLOR = "1";
+  delete env.FORCE_COLOR;
+  delete env.CLICOLOR_FORCE;
+  return env;
+}
+
 /**
  * Spawn a worker as a detached background process. Unlike the old daemon
  * model, multiple workers per project are allowed and expected — this just
@@ -38,21 +58,19 @@ export async function spawnWorker(
   await mkdir(dirname(logPath), { recursive: true });
   const logFile = Bun.file(logPath);
 
-  const workerScript = new URL("./run.ts", import.meta.url).pathname;
-  const args = [
-    "bun",
-    "run",
-    workerScript,
-    projectDir,
-    `--worker-id=${workerId}`,
-    `--log-path=${logPath}`,
-  ];
+  // In a compiled binary there is no `run.ts` on disk to `bun run`, so re-exec
+  // this binary with the sentinel arg that cli.ts intercepts. Under Bun (dev /
+  // global install) spawn the worker entry directly.
+  const args = IS_COMPILED_BINARY
+    ? [process.execPath, WORKER_RUN_SENTINEL, projectDir]
+    : ["bun", "run", new URL("./run.ts", import.meta.url).pathname, projectDir];
+  args.push(`--worker-id=${workerId}`, `--log-path=${logPath}`);
   if (options.mode === "persist") args.push("--persist");
   if (options.taskId) args.push(`--task-id=${options.taskId}`);
 
   const proc = Bun.spawn(args, {
     stdio: ["ignore", logFile, logFile],
-    env: { ...process.env },
+    env: colorlessEnv(),
   });
   proc.unref();