botholomew 0.15.5 → 0.15.6

package/package.json

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

package/src/context/locks.ts

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { CONTEXT_DIR, LOCKS_SUBDIR } from "../constants.ts";
+import {
+  acquireLock,
+  LockHeldError,
+  readLockHolder,
+  releaseLock,
+} from "../fs/atomic.ts";
+
+/**
+ * Per-path mutex for `context/` mutations. Tasks/schedules already serialize
+ * their own writes via O_EXCL lockfiles; this gives the same guarantee for
+ * `context_write` / `context_edit` / `context_delete` / `context_mv` so two
+ * tools (worker + chat, or two workers on the same path) can't race on
+ * read-modify-write or rename ordering.
+ *
+ * Lockfiles live at `<projectDir>/context/.locks/<sha1(path)>.lock`. We hash
+ * the path so the lock filename is bounded-length and slash-free, and so a
+ * leading-dot path doesn't accidentally collide with `walk()`'s dotfile skip
+ * in `src/context/store.ts`. The `.locks/` dir itself is invisible to
+ * `context_list` (walk skips dot-prefixed names at every depth).
+ */
+
+// Retries are exponential-ish with jitter. Total worst-case wait is
+// ~5 seconds — comfortable for a small herd of concurrent writers (the
+// per-path critical section is just a stat + tmp write + rename, on the
+// order of 1-10 ms each), and short enough that a stuck holder surfaces
+// to the caller instead of hanging an LLM tool call indefinitely.
+const ACQUIRE_RETRIES = 32;
+const ACQUIRE_BASE_BACKOFF_MS = 10;
+const ACQUIRE_MAX_BACKOFF_MS = 200;
+
+export function getContextLocksDir(projectDir: string): string {
+  return join(projectDir, CONTEXT_DIR, LOCKS_SUBDIR);
+}
+
+export function contextLockPath(
+  projectDir: string,
+  normalizedPath: string,
+): string {
+  const hash = createHash("sha1").update(normalizedPath).digest("hex");
+  return join(getContextLocksDir(projectDir), `${hash}.lock`);
+}
+
+/**
+ * Run `fn` while holding the per-path context lock. Retries a few times with
+ * a small backoff if another caller has the lock — concurrent context tools
+ * are expected to converge, not surface "try again" errors to the LLM.
+ *
+ * `holderId` is stored in the lockfile body so the reaper (and humans
+ * inspecting `context/.locks/`) can identify the owner. Pass the worker id
+ * when called from a worker; chat sessions pass `"chat:<sessionId>"` or
+ * just `"chat"` — anything stable for the duration of the operation.
+ */
+export async function withContextLock<T>(
+  projectDir: string,
+  normalizedPath: string,
+  holderId: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const lockPath = contextLockPath(projectDir, normalizedPath);
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await acquireLock(lockPath, holderId);
+      try {
+        return await fn();
+      } finally {
+        await releaseLock(lockPath);
+      }
+    } catch (err) {
+      if (err instanceof LockHeldError && attempt < ACQUIRE_RETRIES) {
+        const exp = Math.min(
+          ACQUIRE_MAX_BACKOFF_MS,
+          ACQUIRE_BASE_BACKOFF_MS * 2 ** attempt,
+        );
+        const jittered = exp * (0.5 + Math.random());
+        await new Promise((res) => setTimeout(res, jittered));
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+
+/**
+ * True if `<projectDir>/context/.locks/<sha1(path)>.lock` currently exists.
+ * Used by the reindex orphan-prune to skip paths that a worker is mid-write
+ * on — without this guard the prune can drop the search-index rows of a
+ * file that's about to land on disk.
+ */
+export async function isContextPathLocked(
+  projectDir: string,
+  normalizedPath: string,
+): Promise<boolean> {
+  try {
+    await stat(contextLockPath(projectDir, normalizedPath));
+    return true;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw err;
+  }
+}
+
+/**
+ * Reaper: walk `context/.locks/`, drop any lockfile whose holder is no
+ * longer running per `isHolderAlive`. Mirrors `reapOrphanLocks` in
+ * `src/tasks/store.ts` so the worker reaper can clean stale context locks
+ * left behind by a crashed worker.
+ *
+ * `isHolderAlive` receives the raw holder id — the caller decides what
+ * counts as alive (typically: workers/<id>.json status === "running").
+ * Holders that don't match the worker convention (e.g. `"chat"` from a
+ * chat session) are conservatively treated as alive — not our business
+ * to expire those.
+ */
+export async function reapOrphanContextLocks(
+  projectDir: string,
+  isHolderAlive: (holderId: string) => Promise<boolean>,
+): Promise<string[]> {
+  const dir = getContextLocksDir(projectDir);
+  let names: string[];
+  try {
+    names = await readdir(dir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw err;
+  }
+  const released: string[] = [];
+  for (const name of names) {
+    if (!name.endsWith(".lock")) continue;
+    const lockPath = join(dir, name);
+    const holder = await readLockHolder(lockPath);
+    if (!holder) {
+      await releaseLock(lockPath);
+      released.push(name);
+      continue;
+    }
+    if (!(await isHolderAlive(holder))) {
+      await releaseLock(lockPath);
+      released.push(name);
+    }
+  }
+  return released;
+}

package/src/context/reindex.ts

@@ -15,6 +15,7 @@ import {
 import { logger } from "../utils/logger.ts";
 import { chunkByTextSplit } from "./chunker.ts";
 import { embed as defaultEmbed } from "./embedder.ts";
+import { isContextPathLocked } from "./locks.ts";
 import { listContextDir } from "./store.ts";
 
 /** Embed function shape — exported for tests that want to inject a fake. */
@@ -110,8 +111,16 @@ export async function reindexContext(
   }
 
   // 4. Anything left in indexedByPath is in the index but not on disk →
-  //    delete its rows so search results don't surface ghost files.
+  //    delete its rows so search results don't surface ghost files. Skip
+  //    paths with an active per-path write lock: a worker may have just
+  //    written the file *after* our `collectDiskFiles` walk snapshot, and
+  //    pruning now would drop the index row for a real file. Best-effort —
+  //    the next reindex will reconcile.
   for (const orphan of indexedByPath.keys()) {
+    if (await isContextPathLocked(projectDir, orphan)) {
+      logger.debug(`reindex: skipping orphan-prune for in-flight ${orphan}`);
+      continue;
+    }
     await withDb(dbPath, (conn) => deleteIndexedPath(conn, orphan));
     removed++;
   }

package/src/context/store.ts

@@ -12,7 +12,12 @@ import {
 } from "node:fs/promises";
 import { dirname, join, posix, relative, sep } from "node:path";
 import { CONTEXT_DIR, PROTECTED_AREAS } from "../constants.ts";
-import { atomicWrite } from "../fs/atomic.ts";
+import {
+  atomicWrite,
+  atomicWriteIfUnchanged,
+  MtimeConflictError,
+  readWithMtime,
+} from "../fs/atomic.ts";
 import { applyLinePatches, type LinePatch } from "../fs/patches.ts";
 import {
   getCanonicalRoot,
@@ -20,6 +25,11 @@ import {
   resolveInRoot,
   toRelativePath,
 } from "../fs/sandbox.ts";
+import { withContextLock } from "./locks.ts";
+
+function defaultHolderId(): string {
+  return `pid:${process.pid}`;
+}
 
 /**
  * Disk-backed replacement for the old DuckDB context_items CRUD layer. All
@@ -310,7 +320,10 @@ export async function writeContextFile(
   projectDir: string,
   path: string,
   content: string,
-  opts: { onConflict?: "error" | "overwrite" } = {},
+  opts: {
+    onConflict?: "error" | "overwrite";
+    holderId?: string;
+  } = {},
 ): Promise<ContextEntry> {
   const abs = await resolveContext(projectDir, path);
   const normalized = normalizeContextPath(path);
@@ -321,28 +334,35 @@ export async function writeContextFile(
     );
   }
   const conflict = opts.onConflict ?? "overwrite";
-  let exists = false;
-  try {
-    const st = await stat(abs);
-    if (st.isDirectory()) throw new IsDirectoryError(normalized);
-    exists = true;
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
-  }
-  if (exists && conflict === "error") {
-    throw new PathConflictError(normalized);
-  }
-  await mkdir(dirname(abs), { recursive: true });
-  await atomicWrite(abs, content);
-  const entry = await getInfo(projectDir, normalized);
-  if (!entry) throw new Error(`Wrote ${normalized} but could not stat`);
-  return entry;
+  return withContextLock(
+    projectDir,
+    normalized,
+    opts.holderId ?? defaultHolderId(),
+    async () => {
+      let exists = false;
+      try {
+        const st = await stat(abs);
+        if (st.isDirectory()) throw new IsDirectoryError(normalized);
+        exists = true;
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+      }
+      if (exists && conflict === "error") {
+        throw new PathConflictError(normalized);
+      }
+      await mkdir(dirname(abs), { recursive: true });
+      await atomicWrite(abs, content);
+      const entry = await getInfo(projectDir, normalized);
+      if (!entry) throw new Error(`Wrote ${normalized} but could not stat`);
+      return entry;
+    },
+  );
 }
 
 export async function deleteContextPath(
   projectDir: string,
   path: string,
-  opts: { recursive?: boolean } = {},
+  opts: { recursive?: boolean; holderId?: string } = {},
 ): Promise<{ removed: number; was_directory: boolean; was_symlink: boolean }> {
   const abs = await resolveContext(projectDir, path, {
     allowSymlinkLeaf: true,
@@ -351,61 +371,80 @@ export async function deleteContextPath(
   if (normalized === "") {
     throw new PathEscapeError("refusing to delete the context root", path);
   }
-  let lst: Awaited<ReturnType<typeof lstat>>;
-  try {
-    lst = await lstat(abs);
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
-      throw new NotFoundError(normalized);
-    }
-    throw err;
-  }
-  // A symlink (to a file or a directory, broken or not) is removed with a
-  // plain unlink — never follow into the target. This is what enforces
-  // "the symlink can be deleted, but not the original content".
-  if (lst.isSymbolicLink()) {
-    await unlink(abs);
-    return { removed: 1, was_directory: false, was_symlink: true };
-  }
-  if (lst.isDirectory()) {
-    if (!opts.recursive) {
-      throw new IsDirectoryError(normalized);
-    }
-    const removedPaths = await collectFiles(abs);
-    await rm(abs, { recursive: true, force: false });
-    return {
-      removed: removedPaths.length,
-      was_directory: true,
-      was_symlink: false,
-    };
-  }
-  await unlink(abs);
-  return { removed: 1, was_directory: false, was_symlink: false };
+  return withContextLock(
+    projectDir,
+    normalized,
+    opts.holderId ?? defaultHolderId(),
+    async () => {
+      let lst: Awaited<ReturnType<typeof lstat>>;
+      try {
+        lst = await lstat(abs);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+          throw new NotFoundError(normalized);
+        }
+        throw err;
+      }
+      // A symlink (to a file or a directory, broken or not) is removed with
+      // a plain unlink — never follow into the target. This is what enforces
+      // "the symlink can be deleted, but not the original content".
+      if (lst.isSymbolicLink()) {
+        await unlink(abs);
+        return { removed: 1, was_directory: false, was_symlink: true };
+      }
+      if (lst.isDirectory()) {
+        if (!opts.recursive) {
+          throw new IsDirectoryError(normalized);
+        }
+        const removedPaths = await collectFiles(abs);
+        await rm(abs, { recursive: true, force: false });
+        return {
+          removed: removedPaths.length,
+          was_directory: true,
+          was_symlink: false,
+        };
+      }
+      await unlink(abs);
+      return { removed: 1, was_directory: false, was_symlink: false };
+    },
+  );
 }
 
 export async function moveContextPath(
   projectDir: string,
   src: string,
   dst: string,
+  opts: { holderId?: string } = {},
 ): Promise<void> {
   const srcAbs = await resolveContext(projectDir, src);
   const dstAbs = await resolveContext(projectDir, dst);
-  try {
-    await stat(srcAbs);
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
-      throw new NotFoundError(normalizeContextPath(src));
-    }
-    throw err;
-  }
-  try {
-    await stat(dstAbs);
-    throw new PathConflictError(normalizeContextPath(dst));
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
-  }
-  await mkdir(dirname(dstAbs), { recursive: true });
-  await fsRename(srcAbs, dstAbs);
+  const srcNorm = normalizeContextPath(src);
+  const dstNorm = normalizeContextPath(dst);
+  // Acquire both locks in a stable order to avoid AB/BA deadlocks between
+  // concurrent moves that swap two paths. Sorted lexicographically.
+  const [firstNorm, secondNorm] =
+    srcNorm < dstNorm ? [srcNorm, dstNorm] : [dstNorm, srcNorm];
+  const holder = opts.holderId ?? defaultHolderId();
+  return withContextLock(projectDir, firstNorm, holder, () =>
+    withContextLock(projectDir, secondNorm, holder, async () => {
+      try {
+        await stat(srcAbs);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+          throw new NotFoundError(srcNorm);
+        }
+        throw err;
+      }
+      try {
+        await stat(dstAbs);
+        throw new PathConflictError(dstNorm);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+      }
+      await mkdir(dirname(dstAbs), { recursive: true });
+      await fsRename(srcAbs, dstAbs);
+    }),
+  );
 }
 
 export async function copyContextPath(
@@ -770,15 +809,26 @@ export async function applyPatches(
   projectDir: string,
   path: string,
   patches: Patch[],
+  opts: { holderId?: string } = {},
 ): Promise<{ applied: number; lines: number }> {
-  const content = await readContextFile(projectDir, path);
-  const newContent = applyLinePatches(content, patches);
-  await writeContextFile(projectDir, path, newContent, {
-    onConflict: "overwrite",
+  const abs = await resolveContext(projectDir, path);
+  const normalized = normalizeContextPath(path);
+  const holder = opts.holderId ?? defaultHolderId();
+  return withContextLock(projectDir, normalized, holder, async () => {
+    const read = await readWithMtime(abs);
+    if (!read) throw new NotFoundError(normalized);
+    const newContent = applyLinePatches(read.content, patches);
+    // The lock keeps other context tools out of this critical section, but
+    // an external editor (vim, IDE) can still mutate the file in parallel.
+    // The mtime guard catches that — agents and humans don't silently lose
+    // edits to each other.
+    await atomicWriteIfUnchanged(abs, newContent, read.mtimeMs);
+    return { applied: patches.length, lines: newContent.split("\n").length };
   });
-  return { applied: patches.length, lines: newContent.split("\n").length };
 }
 
+export { MtimeConflictError };
+
 /**
  * Convert an absolute filesystem path back to a context-relative path. Used
  * when rendering search hits or worker output that originated in store.ts.

package/src/fs/atomic.ts

@@ -1,3 +1,4 @@
+import { randomBytes } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import {
   mkdir,
@@ -10,6 +11,17 @@ import {
 } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
+/**
+ * Build a temp suffix that is unique even when two callers in the same
+ * process race on the same target in the same millisecond. The 8 random
+ * bytes drown out any chance of `pid + Date.now()` collision and let the
+ * O_EXCL temp open in atomicWrite act as a real safety net rather than a
+ * suggestion.
+ */
+function defaultTempSuffix(): string {
+  return `${process.pid}.${Date.now()}.${randomBytes(8).toString("hex")}`;
+}
+
 /**
  * Write `content` to `targetPath` atomically: write to a sibling temp file,
  * fsync, then rename. The rename is atomic on POSIX same-filesystem; the
@@ -24,9 +36,17 @@ export async function atomicWrite(
   opts: { tempSuffix?: string } = {},
 ): Promise<void> {
   await mkdir(dirname(targetPath), { recursive: true });
-  const suffix = opts.tempSuffix ?? `${process.pid}.${Date.now()}`;
+  const suffix = opts.tempSuffix ?? defaultTempSuffix();
   const tmp = `${targetPath}.tmp.${suffix}`;
-  const fh = await open(tmp, "w", 0o644);
+  // O_EXCL surfaces a temp-file collision rather than letting two writers
+  // truncate each other's bytes. With the random default suffix this is the
+  // belt-and-suspenders guarantee that concurrent writes to the same target
+  // never silently lose data on the way to rename().
+  const fh = await open(
+    tmp,
+    fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY,
+    0o644,
+  );
   try {
     if (typeof content === "string") {
       await fh.writeFile(content, "utf-8");
@@ -89,9 +109,13 @@ export async function atomicWriteIfUnchanged(
   opts: { tempSuffix?: string } = {},
 ): Promise<void> {
   await mkdir(dirname(targetPath), { recursive: true });
-  const suffix = opts.tempSuffix ?? `${process.pid}.${Date.now()}`;
+  const suffix = opts.tempSuffix ?? defaultTempSuffix();
   const tmp = `${targetPath}.tmp.${suffix}`;
-  const fh = await open(tmp, "w", 0o644);
+  const fh = await open(
+    tmp,
+    fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY,
+    0o644,
+  );
   try {
     await fh.writeFile(content, "utf-8");
     await fh.sync();

package/src/tools/file/copy.ts

@@ -33,7 +33,9 @@ export const contextCopyTool = {
   execute: async (input, ctx) => {
     try {
       if (input.overwrite && (await fileExists(ctx.projectDir, input.dst))) {
-        await deleteContextPath(ctx.projectDir, input.dst);
+        await deleteContextPath(ctx.projectDir, input.dst, {
+          holderId: ctx.workerId,
+        });
       }
       await copyContextPath(ctx.projectDir, input.src, input.dst);
       return { src: input.src, dst: input.dst, is_error: false };

package/src/tools/file/delete.ts

@@ -39,6 +39,7 @@ export const contextDeleteTool = {
     try {
       const result = await deleteContextPath(ctx.projectDir, input.path, {
         recursive: input.recursive,
+        holderId: ctx.workerId,
       });
       return {
         deleted: result.removed,

package/src/tools/file/edit.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import {
   applyPatches,
   IsDirectoryError,
+  MtimeConflictError,
   NotFoundError,
   readContextFile,
 } from "../../context/store.ts";
@@ -19,6 +20,7 @@ const outputSchema = z.object({
   is_error: z.boolean(),
   error_type: z.string().optional(),
   message: z.string().optional(),
+  next_action_hint: z.string().optional(),
 });
 
 export const contextEditTool = {
@@ -34,6 +36,7 @@ export const contextEditTool = {
         ctx.projectDir,
         input.path,
         input.patches,
+        { holderId: ctx.workerId },
       );
       const content = await readContextFile(ctx.projectDir, input.path);
       return { applied, content, is_error: false };
@@ -56,6 +59,17 @@ export const contextEditTool = {
           message: `context/${err.path} is a directory`,
         };
       }
+      if (err instanceof MtimeConflictError) {
+        return {
+          applied: 0,
+          content: "",
+          is_error: true,
+          error_type: "mtime_conflict",
+          message: `context/${input.path} was modified concurrently — another writer (or an external editor) changed it between read and write.`,
+          next_action_hint:
+            "Call context_read to fetch the current content, recompute your patches against the new line numbers, and retry.",
+        };
+      }
       throw err;
     }
   },

package/src/tools/file/move.ts

@@ -32,9 +32,14 @@ export const contextMoveTool = {
   execute: async (input, ctx) => {
     try {
       if (input.overwrite && (await fileExists(ctx.projectDir, input.dst))) {
-        await deleteContextPath(ctx.projectDir, input.dst, { recursive: true });
+        await deleteContextPath(ctx.projectDir, input.dst, {
+          recursive: true,
+          holderId: ctx.workerId,
+        });
       }
-      await moveContextPath(ctx.projectDir, input.src, input.dst);
+      await moveContextPath(ctx.projectDir, input.src, input.dst, {
+        holderId: ctx.workerId,
+      });
       return { src: input.src, dst: input.dst, is_error: false };
     } catch (err) {
       if (err instanceof NotFoundError) {

package/src/tools/file/write.ts

@@ -38,7 +38,7 @@ export const contextWriteTool = {
         ctx.projectDir,
         input.path,
         input.content,
-        { onConflict: input.on_conflict ?? "error" },
+        { onConflict: input.on_conflict ?? "error", holderId: ctx.workerId },
       );
       return { path: entry.path, is_error: false };
     } catch (err) {

package/src/tools/tool.ts

@@ -17,6 +17,15 @@ export interface ToolContext {
   projectDir: string;
   config: Required<BotholomewConfig>;
   mcpxClient: McpxClient | null;
+  /**
+   * Identifier of the agent process running this tool, used as the holder
+   * id for per-path context locks (`src/context/locks.ts`) so the worker
+   * reaper can identify and release locks abandoned by a crashed worker.
+   * Workers pass their `workerId`; chat sessions pass a `chat:` prefixed
+   * id; tests and one-off CLI calls leave it `undefined` (the store falls
+   * back to `pid:<n>`).
+   */
+  workerId?: string;
   /**
    * Chat-mode only. Lets long-running tools (e.g. `sleep`) poll for
    * Esc-to-abort by reading `session.aborted`. Workers leave this `undefined`.

package/src/tui/App.tsx

@@ -216,6 +216,7 @@ function AppInner({
   const [splashDone, setSplashDone] = useState(skipSplash);
   const [error, setError] = useState<string | null>(null);
   const sessionRef = useRef<ChatSession | null>(null);
+  const shuttingDownRef = useRef(false);
   const [activeTab, setActiveTab] = useState<TabId>(1);
   const [workerRunning, setWorkerRunning] = useState(false);
   const [chatTitle, setChatTitle] = useState<string | undefined>(undefined);
@@ -275,16 +276,52 @@ function AppInner({
 
     return () => {
       cancelled = true;
+      // Fire-and-forget safety net: only triggers when unmount happens via a
+      // path that didn't go through performShutdown (which nulls sessionRef
+      // first). React doesn't await unmount cleanups, so the goodbye lands
+      // before mcpx finishes closing — that's fine for non-Ctrl-C paths.
       if (sessionRef.current) {
-        const threadId = sessionRef.current.threadId;
-        endChatSession(sessionRef.current);
+        const session = sessionRef.current;
+        const threadId = session.threadId;
+        abortActiveStream(session);
+        void endChatSession(session);
         process.stderr.write(
-          `\nThread: ${threadId}\nResume with: ${ansi.success}botholomew chat --thread-id ${threadId}${ansi.reset}\n`,
+          `\nThread: ${threadId}\nResume with: ${ansi.success}botholomew chat --thread-id ${threadId}${ansi.reset}\nBye!\n`,
         );
       }
     };
   }, [projectDir, resumeThreadId]);
 
+  const performShutdown = useCallback(async () => {
+    if (shuttingDownRef.current) {
+      // Second Ctrl-C while cleanup is in flight — give the user an escape
+      // hatch. 130 = standard SIGINT exit code.
+      process.exit(130);
+    }
+    shuttingDownRef.current = true;
+
+    const session = sessionRef.current;
+    // Null the ref so the useEffect cleanup that runs on Ink unmount becomes
+    // a no-op — otherwise it would double-print the goodbye and double-close
+    // the mcpx client.
+    sessionRef.current = null;
+
+    if (session) {
+      const threadId = session.threadId;
+      abortActiveStream(session);
+      try {
+        await endChatSession(session);
+      } catch {
+        // Best-effort: the user pressed Ctrl-C, surfacing a stack trace here
+        // would just hide the goodbye line.
+      }
+      process.stderr.write(
+        `\nThread: ${threadId}\nResume with: ${ansi.success}botholomew chat --thread-id ${threadId}${ansi.reset}\nBye!\n`,
+      );
+    }
+    exit();
+  }, [exit]);
+
   // Minimum splash screen duration
   useEffect(() => {
     const timer = setTimeout(() => setSplashDone(true), 2000);
@@ -333,9 +370,12 @@ function AppInner({
     (input: string, key: any) => {
       markActivityRef.current();
 
-      // Ctrl+C exits
+      // Ctrl+C exits. Routed through performShutdown so the in-flight LLM
+      // stream is aborted and mcpx is closed before we unmount Ink — without
+      // that, one Ctrl-C prints the goodbye but the process stays pinned by
+      // the open HTTPS socket and a second Ctrl-C is needed.
       if (input === "c" && key.ctrl) {
-        exit();
+        void performShutdown();
         return;
       }
 
@@ -417,7 +457,7 @@ function AppInner({
         }
       }
     },
-    [exit, syncQueue],
+    [performShutdown, syncQueue],
   );
 
   useInput(stableAppHandler);
@@ -669,7 +709,7 @@ function AppInner({
             syncQueue();
             processQueue();
           },
-          exit,
+          exit: () => void performShutdown(),
           clearChat: () => {
             const session = sessionRef.current;
             if (!session) return;
@@ -743,7 +783,7 @@ function AppInner({
       syncQueue();
       processQueue();
     },
-    [exit, processQueue, syncQueue],
+    [performShutdown, processQueue, syncQueue],
   );
 
   const sessionDbPath = sessionRef.current?.dbPath;

package/src/worker/heartbeat.ts

@@ -1,3 +1,4 @@
+import { reapOrphanContextLocks } from "../context/locks.ts";
 import { reapOrphanScheduleLocks } from "../schedules/store.ts";
 import { reapOrphanLocks as reapOrphanTaskLocks } from "../tasks/store.ts";
 import { logger } from "../utils/logger.ts";
@@ -81,6 +82,25 @@ export function startReaper(
       logger.warn(`schedule lock reap failed: ${err}`);
     }
 
+    try {
+      // Context locks store either a `workerId` (worker holders) or a
+      // free-form id like `chat` / `pid:<n>` (chat sessions, CLI). Only
+      // expire holders that look like worker ids; conservatively treat
+      // any other holder as alive — we don't manage the chat session's
+      // lifecycle here.
+      const released = await reapOrphanContextLocks(projectDir, async (id) => {
+        if (id.startsWith("pid:") || id.startsWith("chat")) return true;
+        return await isAlive(id);
+      });
+      if (released.length > 0) {
+        logger.warn(
+          `released ${released.length} orphan context lock(s): ${released.join(", ")}`,
+        );
+      }
+    } catch (err) {
+      logger.warn(`context lock reap failed: ${err}`);
+    }
+
     try {
       const pruned = await pruneStoppedWorkers(
         projectDir,

package/src/worker/llm.ts

@@ -53,6 +53,7 @@ export async function runAgentLoop(input: {
   dbPath: string;
   threadId: string;
   projectDir: string;
+  workerId?: string;
   mcpxClient?: McpxClient | null;
   callbacks?: WorkerStreamCallbacks;
 }): Promise<AgentLoopResult> {
@@ -63,6 +64,7 @@ export async function runAgentLoop(input: {
     dbPath,
     threadId,
     projectDir,
+    workerId,
     callbacks,
   } = input;
 
@@ -207,6 +209,7 @@ export async function runAgentLoop(input: {
           projectDir,
           config,
           mcpxClient: input.mcpxClient ?? null,
+          workerId,
         });
         const elapsed = Date.now() - start;
         callbacks?.onToolEnd(
@@ -265,6 +268,7 @@ interface ToolCallCtx {
   projectDir: string;
   config: Required<BotholomewConfig>;
   mcpxClient: McpxClient | null;
+  workerId?: string;
 }
 
 async function executeToolCall(

package/src/worker/tick.ts

@@ -77,6 +77,7 @@ export async function tick(opts: TickOptions): Promise<boolean> {
     projectDir,
     dbPath,
     config,
+    workerId,
     mcpxClient,
     callbacks,
     task,
@@ -115,6 +116,7 @@ export async function runSpecificTask(opts: {
     projectDir: opts.projectDir,
     dbPath: opts.dbPath,
     config: opts.config,
+    workerId: opts.workerId,
     mcpxClient: opts.mcpxClient,
     callbacks: opts.callbacks,
     task,
@@ -126,11 +128,13 @@ async function runClaimedTask(opts: {
   projectDir: string;
   dbPath: string;
   config: Required<BotholomewConfig>;
+  workerId: string;
   mcpxClient?: McpxClient | null;
   callbacks?: WorkerStreamCallbacks;
   task: Task;
 }): Promise<void> {
-  const { projectDir, dbPath, config, mcpxClient, callbacks, task } = opts;
+  const { projectDir, dbPath, config, workerId, mcpxClient, callbacks, task } =
+    opts;
 
   logger.info(`Claimed task: ${task.name} (${task.id})`);
   if (!callbacks && task.description) {
@@ -161,6 +165,7 @@ async function runClaimedTask(opts: {
       dbPath,
       threadId,
       projectDir,
+      workerId,
       mcpxClient,
       callbacks,
     });