@starlove/orbit 1.0.7 → 1.1.1

package/src/core/attachments.js

@@ -0,0 +1,238 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, extname, join, normalize, sep } from "node:path";
+import { boardById, ticketById } from "./queries.js";
+import { requireBoardAccess, requirePermission } from "./auth.js";
+import { tx } from "./db.js";
+import { recordEvent } from "./events.js";
+import { bumpTicketUpdatedAt } from "./tickets.js";
+import { httpError, id, now } from "./util.js";
+
+export const MAX_IMAGE_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+
+const IMAGE_EXTENSIONS = new Map([
+  ["image/png", ".png"],
+  ["image/jpeg", ".jpg"],
+  ["image/gif", ".gif"],
+  ["image/webp", ".webp"],
+  ["image/svg+xml", ".svg"],
+  ["image/bmp", ".bmp"],
+  ["image/avif", ".avif"]
+]);
+
+export function attachmentStorageRoot(boardRow) {
+  return join(dirname(boardRow.db_path), "attachments");
+}
+
+function ticketAttachmentDir(boardRow, ticketId) {
+  return join(attachmentStorageRoot(boardRow), "tickets", ticketId);
+}
+
+function safeOriginalName(value) {
+  const name = String(value || "image").replace(/[\0\r\n]/g, "").trim();
+  return name.slice(0, 240) || "image";
+}
+
+function normalizeImageMime(value) {
+  const mime = String(value || "").split(";")[0].trim().toLowerCase();
+  if (!IMAGE_EXTENSIONS.has(mime)) throw httpError(415, "unsupported_attachment_type");
+  return mime;
+}
+
+function extensionFor(mime, originalName = "") {
+  const originalExt = extname(originalName).toLowerCase();
+  if ([...IMAGE_EXTENSIONS.values()].includes(originalExt)) return originalExt;
+  return IMAGE_EXTENSIONS.get(mime) || ".img";
+}
+
+function relativeStoredPath(ticketId, attachmentId, mime, originalName) {
+  return normalize(join("tickets", ticketId, `${attachmentId}${extensionFor(mime, originalName)}`)).replace(/\\/g, "/");
+}
+
+function resolveStoredPath(boardRow, storedPath) {
+  const root = attachmentStorageRoot(boardRow);
+  const abs = join(root, storedPath);
+  const normalizedRoot = normalize(root + sep);
+  const normalizedAbs = normalize(abs);
+  if (!normalizedAbs.startsWith(normalizedRoot)) throw httpError(400, "invalid_attachment_path");
+  return normalizedAbs;
+}
+
+function assertTicket(ctx, ticketId, write = false) {
+  const { db, board, actor } = ctx;
+  const ticket = ticketById(db, ticketId);
+  if (!ticket || ticket.board_id !== board.id) throw httpError(404, "ticket_not_found");
+  requireBoardAccess(actor, boardById(db, ticket.board_id));
+  if (write) requirePermission(actor, "write");
+  return ticket;
+}
+
+function rowToAttachment(boardRow, row) {
+  const path = resolveStoredPath(boardRow, row.stored_path);
+  let missing = true;
+  let size = row.size_bytes;
+  try {
+    const stat = statSync(path);
+    missing = !stat.isFile();
+    if (!missing) size = stat.size;
+  } catch {
+    missing = true;
+  }
+  return {
+    id: row.id,
+    ticket_id: row.ticket_id,
+    board_id: row.board_id,
+    original_name: row.original_name,
+    mime_type: row.mime_type,
+    size_bytes: row.size_bytes,
+    sha256: row.sha256,
+    stored_path: row.stored_path,
+    created_by: row.created_by,
+    created_at: row.created_at,
+    missing,
+    content_url: missing ? null : `/api/tickets/${encodeURIComponent(row.ticket_id)}/attachments/${encodeURIComponent(row.id)}/content`,
+    filesystem_size_bytes: missing ? null : size
+  };
+}
+
+export function listTicketAttachments(ticketId, ctx) {
+  assertTicket(ctx, ticketId);
+  const rows = ctx.db
+    .prepare("SELECT * FROM ticket_attachments WHERE ticket_id = ? ORDER BY created_at ASC")
+    .all(ticketId);
+  return { attachments: rows.map((row) => rowToAttachment(ctx.board, row)) };
+}
+
+export function getTicketAttachmentContent(ticketId, attachmentId, ctx) {
+  assertTicket(ctx, ticketId);
+  const row = ctx.db
+    .prepare("SELECT * FROM ticket_attachments WHERE id = ? AND ticket_id = ?")
+    .get(attachmentId, ticketId);
+  if (!row) throw httpError(404, "attachment_not_found");
+  const filePath = resolveStoredPath(ctx.board, row.stored_path);
+  if (!existsSync(filePath)) throw httpError(404, "attachment_file_missing");
+  return { row, filePath };
+}
+
+export function createTicketAttachment(ticketId, input, ctx) {
+  const ticket = assertTicket(ctx, ticketId, true);
+  const mime = normalizeImageMime(input.mime_type);
+  const bytes = Buffer.isBuffer(input.bytes) ? input.bytes : Buffer.from(input.bytes || []);
+  if (bytes.length === 0) throw httpError(400, "empty_attachment");
+  if (bytes.length > MAX_IMAGE_ATTACHMENT_BYTES) throw httpError(413, "attachment_too_large");
+  const originalName = safeOriginalName(input.original_name);
+  const attachmentId = id();
+  const storedPath = relativeStoredPath(ticketId, attachmentId, mime, originalName);
+  const filePath = resolveStoredPath(ctx.board, storedPath);
+  const hash = createHash("sha256").update(bytes).digest("hex");
+  const time = now();
+
+  mkdirSync(ticketAttachmentDir(ctx.board, ticketId), { recursive: true });
+  writeFileSync(filePath, bytes, { flag: "wx" });
+
+  try {
+    return tx(ctx.db, () => {
+      ctx.db.prepare(
+        `INSERT INTO ticket_attachments
+         (id, ticket_id, board_id, original_name, stored_path, mime_type, size_bytes, sha256, created_by, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+      ).run(attachmentId, ticketId, ticket.board_id, originalName, storedPath, mime, bytes.length, hash, ctx.actor.name, time);
+      ctx.db.prepare("UPDATE tickets SET updated_at = ? WHERE id = ?").run(time, ticketId);
+      recordEvent(ctx.db, ticket.board_id, "attachment_created", ticketId, ctx.actor.name, {
+        attachment_id: attachmentId,
+        original_name: originalName,
+        mime_type: mime,
+        size_bytes: bytes.length,
+        sha256: hash
+      });
+      bumpTicketUpdatedAt(ctx.db, ticket.parent_ticket_id, time);
+      return rowToAttachment(ctx.board, ctx.db.prepare("SELECT * FROM ticket_attachments WHERE id = ?").get(attachmentId));
+    });
+  } catch (error) {
+    try { unlinkSync(filePath); } catch {}
+    throw error;
+  }
+}
+
+export function deleteTicketAttachment(ticketId, attachmentId, ctx) {
+  const ticket = assertTicket(ctx, ticketId, true);
+  const row = ctx.db
+    .prepare("SELECT * FROM ticket_attachments WHERE id = ? AND ticket_id = ?")
+    .get(attachmentId, ticketId);
+  if (!row) throw httpError(404, "attachment_not_found");
+  const filePath = resolveStoredPath(ctx.board, row.stored_path);
+  return tx(ctx.db, () => {
+    ctx.db.prepare("DELETE FROM ticket_attachments WHERE id = ?").run(attachmentId);
+    const time = now();
+    ctx.db.prepare("UPDATE tickets SET updated_at = ? WHERE id = ?").run(time, ticketId);
+    recordEvent(ctx.db, ticket.board_id, "attachment_deleted", ticketId, ctx.actor.name, {
+      attachment_id: attachmentId,
+      original_name: row.original_name
+    });
+    bumpTicketUpdatedAt(ctx.db, ticket.parent_ticket_id, time);
+    try { unlinkSync(filePath); } catch {}
+    return { ok: true, deleted_id: attachmentId };
+  });
+}
+
+export function attachmentRowsForBoard(db, boardId) {
+  return db
+    .prepare("SELECT * FROM ticket_attachments WHERE board_id = ? ORDER BY created_at ASC")
+    .all(boardId);
+}
+
+export function serializeAttachmentForExport(boardRow, row, includeBytes = false) {
+  const attachment = rowToAttachment(boardRow, row);
+  if (!includeBytes || attachment.missing) {
+    return { ...attachment, data_base64: null, included: false };
+  }
+  const filePath = resolveStoredPath(boardRow, row.stored_path);
+  const data = readFileSync(filePath);
+  return {
+    ...attachment,
+    data_base64: data.toString("base64"),
+    included: true,
+    missing: false
+  };
+}
+
+export function importAttachmentRows(snapshot, ctx, targetBoardId) {
+  const rows = Array.isArray(snapshot.attachments) ? snapshot.attachments : [];
+  for (const attachment of rows) {
+    const attachmentId = attachment.id || id();
+    const ticketId = attachment.ticket_id;
+    if (!ticketId || !ctx.db.prepare("SELECT 1 FROM tickets WHERE id = ?").get(ticketId)) continue;
+    const mime = normalizeImageMime(attachment.mime_type || "image/png");
+    const originalName = safeOriginalName(attachment.original_name);
+    const storedPath = relativeStoredPath(ticketId, attachmentId, mime, originalName);
+    let size = Number(attachment.size_bytes || 0);
+    let sha = String(attachment.sha256 || "");
+
+    if (attachment.data_base64) {
+      const bytes = Buffer.from(String(attachment.data_base64), "base64");
+      if (bytes.length > MAX_IMAGE_ATTACHMENT_BYTES) throw httpError(413, "attachment_too_large");
+      size = bytes.length;
+      sha = createHash("sha256").update(bytes).digest("hex");
+      const filePath = resolveStoredPath(ctx.board, storedPath);
+      mkdirSync(dirname(filePath), { recursive: true });
+      writeFileSync(filePath, bytes);
+    }
+
+    ctx.db.prepare(
+      `INSERT OR IGNORE INTO ticket_attachments
+       (id, ticket_id, board_id, original_name, stored_path, mime_type, size_bytes, sha256, created_by, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(
+      attachmentId,
+      ticketId,
+      targetBoardId,
+      originalName,
+      storedPath,
+      mime,
+      size,
+      sha,
+      attachment.created_by || "import",
+      attachment.created_at || now()
+    );
+  }
+}

package/src/core/auth.js

@@ -20,6 +20,42 @@ export function localAgentActor() {
   };
 }
 
+function headerValue(req, name) {
+  const value = req?.headers?.[name.toLowerCase()];
+  if (Array.isArray(value)) return value[0] || "";
+  return String(value || "");
+}
+
+function cleanActorField(value, fallback) {
+  const clean = String(value || "")
+    .trim()
+    .replace(/\s+/g, " ")
+    .slice(0, 80);
+  return clean || fallback;
+}
+
+function actorIdFromName(name) {
+  return String(name || "agent")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80) || "agent";
+}
+
+export function actorFromHttpRequest(req) {
+  const actorType = headerValue(req, "x-orbit-actor-type").trim().toLowerCase();
+  const agentName = headerValue(req, "x-orbit-agent-name");
+  if (actorType !== "agent" && !agentName.trim()) return localOwnerActor();
+
+  const name = cleanActorField(headerValue(req, "x-orbit-actor-name") || agentName, "agent");
+  const id = cleanActorField(headerValue(req, "x-orbit-actor-id"), actorIdFromName(name));
+  return {
+    ...localAgentActor(),
+    id,
+    name
+  };
+}
+
 export function authenticate() {
   return localOwnerActor();
 }

package/src/core/backups.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { getRegistry } from "./db.js";
-import { BACKUP_DIR } from "./paths.js";
+import { closeConnection, getRegistry, hasConnection, openConnection } from "./db.js";
+import { BACKUP_DIR, REGISTRY_DB_PATH } from "./paths.js";
 import { now } from "./util.js";
 
 const DEFAULT_RETENTION = 30;
@@ -100,11 +100,17 @@ export function scheduleAutomaticBoardBackup(boardRow, db) {
 
   const timer = setTimeout(() => {
     scheduledBoardBackups.delete(boardRow.id);
+    const hadBoardConnection = hasConnection(boardRow.db_path);
+    const hadRegistryConnection = hasConnection(REGISTRY_DB_PATH);
+    const backupDb = openConnection(boardRow.db_path);
     try {
-      backupBoardDatabase(boardRow, db, "auto-write");
+      backupBoardDatabase(boardRow, backupDb, "auto-write");
       backupRegistry("auto-write");
     } catch (error) {
       console.warn(`[orbit] Automatic write backup failed for "${boardRow.slug}": ${error.message}`);
+    } finally {
+      if (!hadBoardConnection) closeConnection(boardRow.db_path);
+      if (!hadRegistryConnection) closeConnection(REGISTRY_DB_PATH);
     }
   }, automaticDelayMs());
   timer.unref?.();

package/src/core/board.js

@@ -8,16 +8,21 @@
 //   3. Iterate every registry board, ensuring the per-board schema exists
 //      and reindexing FTS for that board's DB. No "active board" singleton:
 //      each iteration opens its own connection.
+//   4. When launched through `orbit serve`, refresh Orbit-managed
+//      SKILL-ORBIT.md copies for registered repo paths.
 //
 // Beyond startup this module just re-exports per-domain functions for
 // `src/server.js` and `src/mcp-server.js` to consume.
 
 import { existsSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
 import "./paths.js";
+import { syncSkillOrbitMd } from "./agents-md.js";
 import { createBoardSchema, createRegistrySchema } from "./db.js";
 import { reindexAllTickets } from "./tickets.js";
 import { deleteBoard, listBoards, openBoardDb, syncRegistryFromBoardDb } from "./registry.js";
 import { provisionRepoBoard } from "./provision-repo-board.js";
+import { migrateInRepoBoards } from "./migrate.js";
 import { id, slugify } from "./util.js";
 import {
   DATA_DIR,
@@ -58,12 +63,38 @@ function ensureSchemaForEveryBoard() {
   }
 }
 
+function syncManagedSkillOrbitFiles() {
+  const skillSrc = resolve(ROOT_DIR, "SKILL-ORBIT.md");
+  for (const row of listBoards()) {
+    if (!row.repo_path) continue;
+    try {
+      const result = syncSkillOrbitMd(row.repo_path, skillSrc);
+      if (result.status === "missing_source") {
+        console.warn(`[orbit] Missing managed SKILL-ORBIT.md source at ${skillSrc}; skipped repo guidance refresh.`);
+        return;
+      }
+      if (result.status === "written") {
+        console.log(`[orbit] Refreshed managed SKILL-ORBIT.md in ${row.repo_path}`);
+      }
+    } catch (error) {
+      console.warn(`[orbit] Could not refresh SKILL-ORBIT.md in ${row.repo_path}: ${error.message}`);
+    }
+  }
+}
+
 ensureWorkspace();
+// Move any per-board SQLite files that still live in in-repo .orbit/ directories
+// into the central DATA_DIR/boards/<slug>/ store. Must run before
+// ensureSchemaForEveryBoard so all connections open against the canonical paths.
+migrateInRepoBoards();
 // Reconcile the registry against disk *before* deciding whether to bootstrap a
 // first board — otherwise a stale row from a deleted .orbit/ folder makes
 // listBoards() non-empty and we never re-seed.
 ensureSchemaForEveryBoard();
 ensureFirstBoard();
+if (process.env.ORBIT_SYNC_MANAGED_SKILL_ORBIT === "1") {
+  syncManagedSkillOrbitFiles();
+}
 
 export const boardRuntime = {
   rootDir: ROOT_DIR,
@@ -103,7 +134,7 @@ export {
 export { archiveTicket, createComment, createTicket, deleteTicket, restoreTicket, updateTicket } from "./tickets.js";
 export { archivedTicketsForBoard } from "./queries.js";
 export { getTicketBlockers, getTicketRelations } from "./relations.js";
-export { checkpointTicket, claimNext, completeTicket, getContextPack, readComments, readTicket } from "./agent.js";
+export { checkpointTicket, claimNext, completeTicket, getAgentDispatchPacket, getContextPack, readComments, readTicket } from "./agent.js";
 export { searchTickets } from "./search.js";
 export { exportBoard } from "./snapshots.js";
 

package/src/core/boards.js

@@ -222,7 +222,7 @@ export function updateBoard(boardId, body, ctx) {
   for (const field of allowed) {
     if (body[field] !== undefined) {
       sets.push(`${field} = ?`);
-      values.push(String(body[field] ?? ""));
+      values.push(field === "name" ? requiredString(body[field], "name") : String(body[field] ?? ""));
     }
   }
 

package/src/core/db.js

@@ -30,8 +30,32 @@ export function openConnection(dbPath) {
 export function closeConnection(dbPath) {
   const conn = connections.get(dbPath);
   if (!conn) return;
-  conn.close();
-  connections.delete(dbPath);
+  try {
+    conn.exec("PRAGMA wal_checkpoint(TRUNCATE);");
+  } catch {
+    // Another process may still be attached; closing this connection is enough
+    // to release our file handle.
+  }
+  try {
+    conn.close();
+  } finally {
+    connections.delete(dbPath);
+  }
+}
+
+export function hasConnection(dbPath) {
+  return connections.has(dbPath);
+}
+
+export function closeAllConnections() {
+  for (const dbPath of [...connections.keys()]) {
+    try {
+      closeConnection(dbPath);
+    } catch {
+      // Shutdown cleanup should release every handle it can without masking
+      // the original exit path.
+    }
+  }
 }
 
 // Reentrancy depth per connection. Only the outermost tx() issues
@@ -155,6 +179,19 @@ export function createBoardSchema(db) {
       created_at TEXT NOT NULL
     );
 
+    CREATE TABLE IF NOT EXISTS ticket_attachments (
+      id TEXT PRIMARY KEY,
+      ticket_id TEXT NOT NULL REFERENCES tickets(id) ON DELETE CASCADE,
+      board_id TEXT NOT NULL REFERENCES boards(id) ON DELETE CASCADE,
+      original_name TEXT NOT NULL,
+      stored_path TEXT NOT NULL,
+      mime_type TEXT NOT NULL,
+      size_bytes INTEGER NOT NULL,
+      sha256 TEXT NOT NULL,
+      created_by TEXT NOT NULL DEFAULT 'human',
+      created_at TEXT NOT NULL
+    );
+
     CREATE TABLE IF NOT EXISTS board_entries (
       id TEXT PRIMARY KEY,
       board_id TEXT NOT NULL REFERENCES boards(id) ON DELETE CASCADE,
@@ -214,6 +251,8 @@ export function createBoardSchema(db) {
     CREATE INDEX IF NOT EXISTS idx_tickets_archived ON tickets(board_id, archived_at);
     CREATE INDEX IF NOT EXISTS idx_tickets_parent ON tickets(parent_ticket_id);
     CREATE INDEX IF NOT EXISTS idx_comments_ticket ON comments(ticket_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_ticket_attachments_ticket ON ticket_attachments(ticket_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_ticket_attachments_board ON ticket_attachments(board_id, created_at);
     CREATE INDEX IF NOT EXISTS idx_board_entries_board ON board_entries(board_id, type, created_at);
     CREATE INDEX IF NOT EXISTS idx_relations_source ON relations(source_ticket_id);
     CREATE INDEX IF NOT EXISTS idx_relations_target ON relations(target_ticket_id);
@@ -227,6 +266,7 @@ export function resetBoard(db) {
     DELETE FROM ticket_labels;
     DELETE FROM relations;
     DELETE FROM comments;
+    DELETE FROM ticket_attachments;
     DELETE FROM board_entries;
     DELETE FROM events;
     DELETE FROM tickets;

package/src/core/delete-board.js

@@ -1,9 +1,10 @@
-import { existsSync, rmSync, unlinkSync } from "node:fs";
+import { existsSync, rmSync } from "node:fs";
 import { basename, dirname, join, relative } from "node:path";
 import { removeOrbitAgentsSection } from "./agents-md.js";
 import { requireBoardAccess } from "./auth.js";
 import { backupBoardDatabase, backupRegistry, cancelAutomaticBoardBackup } from "./backups.js";
 import { closeConnection } from "./db.js";
+import { BOARDS_DIR, DATA_DIR, DISPATCH_RUNS_DIR } from "./paths.js";
 import { deleteBoard, listBoards, openBoardDb } from "./registry.js";
 import { httpError, normalizePath } from "./util.js";
 
@@ -13,17 +14,31 @@ function isInside(parent, child) {
 }
 
 function boardDbDeleteTargets(boardRow) {
-  const repoRoot = normalizePath(boardRow.repo_path || "");
   const dbPath = normalizePath(boardRow.db_path || "");
-  const orbitRoot = normalizePath(join(repoRoot, ".orbit"));
-  if (!repoRoot || !dbPath || !isInside(orbitRoot, dbPath) || basename(dbPath) !== "board.db") {
+  if (!dbPath || basename(dbPath) !== "board.db") {
     throw httpError(409, "unsafe_board_db_path");
   }
 
+  // Central storage: db lives inside DATA_DIR/boards/<slug>/board.db
+  const boardsDirNorm = normalizePath(BOARDS_DIR);
+  if (dbPath.startsWith(boardsDirNorm + "/")) {
+    const boardDir = dirname(dbPath);
+    // Safety: boardDir must be exactly one level below BOARDS_DIR
+    if (normalizePath(dirname(boardDir)) !== boardsDirNorm) {
+      throw httpError(409, "unsafe_board_db_path");
+    }
+    return [boardDir];
+  }
+
+  // Legacy in-repo storage: db lives inside <repo>/.orbit/
+  const repoRoot = normalizePath(boardRow.repo_path || "");
+  const orbitRoot = normalizePath(join(repoRoot, ".orbit"));
+  if (!repoRoot || !isInside(orbitRoot, dbPath)) {
+    throw httpError(409, "unsafe_board_db_path");
+  }
   const boardDir = dirname(dbPath);
   const boardsRoot = normalizePath(join(orbitRoot, "boards"));
-  const removeBoardDir = isInside(boardsRoot, boardDir);
-  if (removeBoardDir) return [boardDir];
+  if (isInside(boardsRoot, boardDir)) return [boardDir];
   return [dbPath, `${dbPath}-wal`, `${dbPath}-shm`, `${dbPath}-journal`];
 }
 
@@ -35,16 +50,49 @@ function isLastBoardForRepo(boardRow) {
 function repoArtifactTargets(boardRow) {
   const repoRoot = normalizePath(boardRow.repo_path || "");
   const dbPath = normalizePath(boardRow.db_path || "");
-  const orbitRoot = normalizePath(join(repoRoot, ".orbit"));
-  if (!repoRoot || !dbPath || !isInside(orbitRoot, dbPath) || basename(dbPath) !== "board.db") {
+  if (!repoRoot || !dbPath || basename(dbPath) !== "board.db") {
     throw httpError(409, "unsafe_board_db_path");
   }
   return {
-    orbitRoot,
+    orbitRoot: normalizePath(join(repoRoot, ".orbit")),
     skillMd: join(repoRoot, "SKILL-ORBIT.md")
   };
 }
 
+function removeOptions(recursive = false) {
+  const options = { force: true };
+  if (recursive) options.recursive = true;
+  if (process.platform === "win32") {
+    options.maxRetries = 10;
+    options.retryDelay = 100;
+  }
+  return options;
+}
+
+function isBusyFilesystemError(error) {
+  const message = String(error?.message || "").toLowerCase();
+  return (
+    ["EBUSY", "EPERM", "ENOTEMPTY"].includes(error?.code) ||
+    (error?.code === "ERR_SQLITE_ERROR" && (message.includes("locked") || message.includes("busy")))
+  );
+}
+
+function boardFilesBusyError(error, boardRow) {
+  if (!isBusyFilesystemError(error)) return error;
+  const wrapped = new Error(
+    [
+      `Orbit could not remove local board files for "${boardRow.slug}".`,
+      "On Windows this usually means an Orbit web server, MCP helper, AI client, editor, or terminal still has .orbit/board.db open.",
+      "Close those processes, then retry the delete from Settings or run orbit reset --cwd <repo>.",
+      `Original error: ${error.message}`
+    ].join("\n")
+  );
+  wrapped.status = 409;
+  wrapped.code = "board_files_busy";
+  wrapped.cause = error;
+  return wrapped;
+}
+
 export function deleteRegisteredBoard(boardRow, body, actor) {
   requireBoardAccess(actor, { slug: boardRow.slug });
 
@@ -54,26 +102,44 @@ export function deleteRegisteredBoard(boardRow, body, actor) {
   const deleteFiles = body?.delete_files !== false;
   const removeRepoArtifacts = deleteFiles && isLastBoardForRepo(boardRow);
   const repoArtifacts = removeRepoArtifacts ? repoArtifactTargets(boardRow) : null;
+  // Always delete the board's own db files/directory; when it is the last board
+  // for a repo also sweep in-repo artifacts (.orbit/, SKILL-ORBIT.md, AGENTS.md).
+  // Also remove the board's central dispatch-runs directory.
+  const dispatchRunsDir = join(DISPATCH_RUNS_DIR, boardRow.slug);
   const targets = deleteFiles
-    ? removeRepoArtifacts
-      ? [repoArtifacts.orbitRoot]
-      : boardDbDeleteTargets(boardRow)
+    ? [
+        ...boardDbDeleteTargets(boardRow),
+        ...(repoArtifacts ? [repoArtifacts.orbitRoot] : []),
+        ...(existsSync(dispatchRunsDir) ? [dispatchRunsDir] : [])
+      ]
     : [];
   const artifactResults = [];
   cancelAutomaticBoardBackup(boardRow.id);
-  if (deleteFiles) backupBoardDatabase(boardRow, openBoardDb(boardRow), "pre-board-delete");
+  if (deleteFiles) {
+    try {
+      backupBoardDatabase(boardRow, openBoardDb(boardRow), "pre-board-delete");
+    } catch (error) {
+      throw boardFilesBusyError(error, boardRow);
+    } finally {
+      closeConnection(boardRow.db_path);
+    }
+  }
   backupRegistry("pre-board-delete");
   closeConnection(boardRow.db_path);
 
-  for (const target of targets) {
-    if (existsSync(target)) {
-      rmSync(target, { recursive: true, force: true });
-      artifactResults.push({ path: target, removed: true });
+  try {
+    for (const target of targets) {
+      if (existsSync(target)) {
+        rmSync(target, removeOptions(true));
+        artifactResults.push({ path: target, removed: true });
+      }
     }
-  }
-  if (repoArtifacts?.skillMd && existsSync(repoArtifacts.skillMd)) {
-    unlinkSync(repoArtifacts.skillMd);
-    artifactResults.push({ path: repoArtifacts.skillMd, removed: true });
+    if (repoArtifacts?.skillMd && existsSync(repoArtifacts.skillMd)) {
+      rmSync(repoArtifacts.skillMd, removeOptions(false));
+      artifactResults.push({ path: repoArtifacts.skillMd, removed: true });
+    }
+  } catch (error) {
+    throw boardFilesBusyError(error, boardRow);
   }
   if (removeRepoArtifacts) {
     const agentsCleanup = removeOrbitAgentsSection(boardRow.repo_path);