botholomew 0.15.4 → 0.15.6

package/package.json

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

package/src/chat/agent.ts

@@ -52,9 +52,11 @@ const CHAT_TOOL_NAMES = new Set([
   "view_thread",
   "search_threads",
   "create_schedule",
+  "schedule_edit",
   "list_schedules",
-  "update_beliefs",
-  "update_goals",
+  "prompt_read",
+  "prompt_edit",
+  "task_edit",
   "capabilities_refresh",
   "mcp_list_tools",
   "mcp_search",
@@ -100,7 +102,7 @@ You do NOT execute long-running work directly — enqueue tasks for a background
 Use the available tools to look up tasks, threads, schedules, and context when the user asks about them. Files the agent can read and write live under \`context/\` as project-relative paths (e.g. \`notes/foo.md\`). Use \`context_tree\` to see what's there, \`search\` (hybrid regexp + semantic) to find content, then \`context_read\` / \`context_info\` to drill in.
 Past conversations live in CSV files under \`threads/\`; use \`list_threads\`, \`search_threads\`, and \`view_thread\` to find and page through them.
 When multiple tool calls are independent of each other (i.e., one does not depend on the result of another), call them all in a single response. They will be executed in parallel, which is faster than calling them one at a time.
-You can update the agent's beliefs and goals files when the user asks you to.
+You can read and edit the agent's prompt files (beliefs, goals, capabilities, soul) under \`prompts/\` via \`prompt_read\` and \`prompt_edit\` (line-range patches). Files marked \`agent-modification: false\` (e.g. soul.md) are read-only.
 You can author and refine slash-command skills (reusable prompt templates stored in \`skills/\`) via \`skill_list\`, \`skill_search\`, \`skill_read\`, \`skill_write\`, \`skill_edit\`, and \`skill_delete\`. New or edited skills are usable as \`/<name>\` on the user's next message.
 Format your responses using Markdown. Use headings, bold, italic, lists, and code blocks to make your responses clear and well-structured.
 `;
@@ -252,7 +254,7 @@ export async function runChatTurn(input: {
     // Rebuild the system prompt every iteration so that:
     //   (1) `loading: contextual` files get matched against the latest user
     //       message, and
-    //   (2) any update_beliefs / update_goals tool call in the previous
+    //   (2) any prompt_edit tool call in the previous
     //       iteration is reflected in the next LLM call.
     const keywordSource = findLastUserText(messages);
     const systemPrompt = await buildChatSystemPrompt(projectDir, {

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,13 +12,24 @@ 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,
   PathEscapeError,
   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
@@ -59,11 +70,7 @@ export class PathConflictError extends Error {
   }
 }
 
-export interface Patch {
-  start_line: number;
-  end_line: number;
-  content: string;
-}
+export type Patch = LinePatch;
 
 export interface ContextEntry {
   /** Project-relative path under context/, e.g. "notes/foo.md". Forward-slashes. */
@@ -313,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);
@@ -324,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,
@@ -354,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(
@@ -773,30 +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 lines = content.split("\n");
-
-  const sorted = [...patches].sort((a, b) => b.start_line - a.start_line);
-
-  for (const patch of sorted) {
-    if (patch.end_line === 0) {
-      const insertLines = patch.content === "" ? [] : patch.content.split("\n");
-      lines.splice(patch.start_line - 1, 0, ...insertLines);
-    } else {
-      const deleteCount = patch.end_line - patch.start_line + 1;
-      const insertLines = patch.content === "" ? [] : patch.content.split("\n");
-      lines.splice(patch.start_line - 1, deleteCount, ...insertLines);
-    }
-  }
-
-  const newContent = lines.join("\n");
-  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: lines.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/fs/patches.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+export interface LinePatch {
+  start_line: number;
+  end_line: number;
+  content: string;
+}
+
+export const LinePatchSchema = z.object({
+  start_line: z.number().describe("1-based inclusive start line"),
+  end_line: z
+    .number()
+    .describe("1-based inclusive end line (0 to insert without replacing)"),
+  content: z
+    .string()
+    .describe("Replacement text (empty string to delete lines)"),
+});
+
+/**
+ * Apply git-style line-range patches to a string. Patches are applied
+ * bottom-up so earlier line numbers stay stable. `end_line === 0` is an
+ * insert that doesn't replace; an empty `content` deletes.
+ */
+export function applyLinePatches(raw: string, patches: LinePatch[]): string {
+  const lines = raw.split("\n");
+  const sorted = [...patches].sort((a, b) => b.start_line - a.start_line);
+
+  for (const patch of sorted) {
+    const insertLines = patch.content === "" ? [] : patch.content.split("\n");
+    if (patch.end_line === 0) {
+      lines.splice(patch.start_line - 1, 0, ...insertLines);
+    } else {
+      const deleteCount = patch.end_line - patch.start_line + 1;
+      lines.splice(patch.start_line - 1, deleteCount, ...insertLines);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/schedules/store.ts

@@ -19,7 +19,7 @@ import {
   ScheduleFrontmatterSchema,
 } from "./schema.ts";
 
-function scheduleFilePath(projectDir: string, id: string): string {
+export function scheduleFilePath(projectDir: string, id: string): string {
   return join(getSchedulesDir(projectDir), `${id}.md`);
 }
 
@@ -27,20 +27,26 @@ function scheduleLockPath(projectDir: string, id: string): string {
   return join(getSchedulesLockDir(projectDir), `${id}.lock`);
 }
 
-function serializeSchedule(fm: ScheduleFrontmatter, body: string): string {
+export function serializeSchedule(
+  fm: ScheduleFrontmatter,
+  body: string,
+): string {
   return matter.stringify(`\n${body.trim()}\n`, fm as Record<string, unknown>);
 }
 
-interface ParseOk {
+export interface ScheduleParseOk {
   ok: true;
   schedule: Schedule;
 }
-interface ParseFail {
+export interface ScheduleParseFail {
   ok: false;
   reason: string;
 }
 
-function parseScheduleFile(raw: string, mtimeMs: number): ParseOk | ParseFail {
+export function parseScheduleFile(
+  raw: string,
+  mtimeMs: number,
+): ScheduleParseOk | ScheduleParseFail {
   let parsed: matter.GrayMatterFile<string>;
   try {
     parsed = matter(raw);

package/src/tasks/store.ts

@@ -21,7 +21,7 @@ import {
   type TaskStatus,
 } from "./schema.ts";
 
-function taskFilePath(projectDir: string, id: string): string {
+export function taskFilePath(projectDir: string, id: string): string {
   return join(getTasksDir(projectDir), `${id}.md`);
 }
 
@@ -33,23 +33,23 @@ function taskLockPath(projectDir: string, id: string): string {
  * Render a Task to its on-disk markdown form. Frontmatter contains every
  * field; the body is preserved as-is. Trailing newline keeps line count sane.
  */
-function serializeTask(fm: TaskFrontmatter, body: string): string {
+export function serializeTask(fm: TaskFrontmatter, body: string): string {
   return matter.stringify(`\n${body.trim()}\n`, fm as Record<string, unknown>);
 }
 
-interface ParseResult {
+export interface TaskParseOk {
   ok: true;
   task: Task;
 }
-interface ParseFailure {
+export interface TaskParseFail {
   ok: false;
   reason: string;
 }
 
-function parseTaskFile(
+export function parseTaskFile(
   raw: string,
   mtimeMs: number,
-): ParseResult | ParseFailure {
+): TaskParseOk | TaskParseFail {
   let parsed: matter.GrayMatterFile<string>;
   try {
     parsed = matter(raw);