@starlove/orbit 1.0.7 → 1.1.0

package/src/core/migrate.js

@@ -0,0 +1,198 @@
+/**
+ * migrate.js — one-time startup migration of per-board SQLite files from
+ * in-repo .orbit/ directories into the central DATA_DIR/boards/<slug>/ store.
+ *
+ * Called during board.js startup, before ensureSchemaForEveryBoard, so that
+ * by the time per-board connections are opened they are already at their
+ * canonical central location.
+ *
+ * If a migration fails the registry row is NOT updated and Orbit continues
+ * to serve from the old in-repo path. A structured warning with agent-actionable
+ * manual instructions is printed to stderr.
+ */
+import { existsSync, mkdirSync, readdirSync, rmSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { closeConnection, getRegistry, openConnection } from "./db.js";
+import { BOARDS_DIR } from "./paths.js";
+import { listBoards } from "./registry.js";
+
+/** Normalize to forward slashes for consistent cross-platform prefix checks. */
+const fwd = (p) => p.replace(/\\/g, "/");
+
+/** True when db_path already lives inside the canonical BOARDS_DIR. */
+function isCentral(dbPath) {
+  return fwd(dbPath).startsWith(fwd(BOARDS_DIR) + "/");
+}
+
+/** Canonical central path for a given slug. */
+function centralPathFor(slug) {
+  return join(BOARDS_DIR, slug, "board.db");
+}
+
+/** Delete a file if it exists; silently ignore errors. */
+function tryUnlink(p) {
+  try { if (existsSync(p)) unlinkSync(p); } catch { /* ignore */ }
+}
+
+/**
+ * Walk upward from startDir, removing each directory that is now empty.
+ * Stops at stopDir (inclusive) or the first non-empty directory.
+ * This cleans up empty .orbit/ trees left behind after moving the db out.
+ */
+function pruneEmptyAncestors(startDir, stopDir) {
+  const stopFwd = fwd(stopDir);
+  let cur = fwd(startDir);
+  while (cur.startsWith(stopFwd)) {
+    try {
+      if (!existsSync(cur)) {
+        /* already gone, climb */
+      } else if (readdirSync(cur).length > 0) {
+        break; // non-empty — stop here
+      } else {
+        // rmSync({recursive:true, force:true}) works correctly for both files and
+        // empty directories across Node versions and platforms.  We've already
+        // confirmed the directory is empty so nothing is over-deleted.
+        rmSync(cur, { recursive: true, force: true });
+      }
+    } catch {
+      break;
+    }
+    if (cur === stopFwd) break; // reached the limit
+    const parent = fwd(dirname(cur));
+    if (parent === cur) break; // filesystem root
+    cur = parent;
+  }
+}
+
+/**
+ * For a db path inside a repo's .orbit directory, return the .orbit parent.
+ *   /repo/.orbit/board.db          → /repo/.orbit
+ *   /repo/.orbit/boards/x/board.db → /repo/.orbit
+ * Returns null if ".orbit" is not found in the path.
+ */
+function orbitParentDir(dbPath) {
+  const parts = fwd(dbPath).split("/");
+  const idx = parts.lastIndexOf(".orbit");
+  if (idx < 0) return null;
+  return parts.slice(0, idx + 1).join("/");
+}
+
+function sqlLiteral(v) {
+  return `'${String(v).replace(/'/g, "''")}'`;
+}
+
+/**
+ * Attempt to migrate one board from in-repo storage to central storage.
+ * Returns a result object with status: 'migrated' | 'failed' | 'missing_source'.
+ */
+function migrateOneBoard(boardRow) {
+  const { id, slug, db_path: oldPath } = boardRow;
+
+  if (!existsSync(oldPath)) {
+    // Source file is gone; ensureSchemaForEveryBoard will prune the stale row.
+    return { status: "missing_source", board: boardRow, oldPath };
+  }
+
+  const newPath = centralPathFor(slug);
+  mkdirSync(dirname(newPath), { recursive: true });
+
+  try {
+    // Safety: if the target path is already registered to a *different* board id,
+    // skip rather than overwrite live data (guards against corrupted registries with
+    // duplicate slugs — cannot happen through normal API use but is defensive).
+    const existingOwner = getRegistry().prepare("SELECT id FROM boards WHERE db_path = ?").get(newPath);
+    if (existingOwner && existingOwner.id !== id) {
+      return {
+        status: "failed",
+        board: boardRow,
+        oldPath,
+        newPath,
+        error: new Error(
+          `central path ${newPath} is already registered to board ${existingOwner.id} — skipping to avoid data loss`
+        )
+      };
+    }
+
+    // Remove any stale central copy left by a previous partial migration.
+    if (existsSync(newPath)) tryUnlink(newPath);
+
+    // VACUUM INTO creates a clean, WAL-flushed copy. It captures only committed
+    // data and produces a single-file database (no -wal/-shm at the destination).
+    const db = openConnection(oldPath);
+    db.exec(`VACUUM INTO ${sqlLiteral(newPath)};`);
+    closeConnection(oldPath);
+
+    // Update the registry before deleting the source so the canonical pointer is
+    // always valid: if the process dies between these two steps the old file still
+    // exists and the next run will redo the migration cleanly.
+    getRegistry()
+      .prepare("UPDATE boards SET db_path = ?, updated_at = ? WHERE id = ?")
+      .run(newPath, new Date().toISOString(), id);
+
+    // Remove source files (main db + WAL + SHM + journal).
+    tryUnlink(oldPath);
+    tryUnlink(oldPath + "-wal");
+    tryUnlink(oldPath + "-shm");
+    tryUnlink(oldPath + "-journal");
+
+    // Prune now-empty .orbit/ directories from the repo tree.
+    const orbitDir = orbitParentDir(oldPath);
+    if (orbitDir) pruneEmptyAncestors(dirname(oldPath), orbitDir);
+
+    return { status: "migrated", board: boardRow, oldPath, newPath };
+  } catch (error) {
+    // Ensure no lingering open connection or partial central file on failure.
+    try { closeConnection(oldPath); } catch { /* ignore */ }
+    tryUnlink(newPath);
+    return { status: "failed", board: boardRow, oldPath, newPath, error };
+  }
+}
+
+/**
+ * Migrate all boards whose db_path lives outside DATA_DIR into central storage.
+ * Called at server/MCP startup before any per-board connections are opened.
+ * Prints a concise summary for migrated boards; prints agent-actionable
+ * instructions for any failures so a human or AI can complete the migration.
+ */
+export function migrateInRepoBoards() {
+  const pending = listBoards().filter((row) => !isCentral(row.db_path));
+  if (pending.length === 0) return;
+
+  const results = pending.map(migrateOneBoard);
+  const migrated = results.filter((r) => r.status === "migrated");
+  const failed = results.filter((r) => r.status === "failed");
+
+  if (migrated.length > 0) {
+    const n = migrated.length;
+    console.log(`[orbit] Migrated ${n} board${n > 1 ? "s" : ""} to central storage (${BOARDS_DIR}):`);
+    for (const r of migrated) {
+      console.log(`  ✓ ${r.board.slug}`);
+      console.log(`    from: ${r.oldPath}`);
+      console.log(`    to:   ${r.newPath}`);
+    }
+  }
+
+  if (failed.length > 0) {
+    const sep = "  │";
+    const n = failed.length;
+    console.error(`\n[orbit] ⚠ Could not auto-migrate ${n} board${n > 1 ? "s" : ""} to central storage.`);
+    console.error(`${sep} These boards continue to work from their current paths.`);
+    console.error(`${sep} To complete the migration manually, run the commands below and`);
+    console.error(`${sep} restart orbit serve:\n`);
+    for (const r of failed) {
+      const slash = process.platform === "win32" ? "\\" : "/";
+      const destDir = dirname(r.newPath).replace(/\//g, slash);
+      const src = r.oldPath.replace(/\//g, slash);
+      const dest = r.newPath.replace(/\//g, slash);
+      console.error(`${sep} Board: ${r.board.slug}  (error: ${r.error?.message ?? r.error})`);
+      if (process.platform === "win32") {
+        console.error(`${sep}   md "${destDir}"`);
+        console.error(`${sep}   copy "${src}" "${dest}"`);
+      } else {
+        console.error(`${sep}   mkdir -p '${destDir}'`);
+        console.error(`${sep}   cp '${src}' '${dest}'`);
+      }
+      console.error(sep);
+    }
+  }
+}

package/src/core/paths.js

@@ -16,10 +16,16 @@ export const PROJECT_ROOT = process.env.PROJECT_ROOT ? resolve(process.env.PROJE
 export const DATA_DIR = process.env.DATA_DIR || join(homedir(), ".orbit");
 /** Central registry of all boards (metadata + paths to per-board SQLite files). */
 export const REGISTRY_DB_PATH = join(DATA_DIR, "registry.db");
+/** Central directory where every board's SQLite file lives: DATA_DIR/boards/<slug>/board.db */
+export const BOARDS_DIR = join(DATA_DIR, "boards");
 export const EXPORT_DIR = join(DATA_DIR, "exports");
 export const BACKUP_DIR = join(DATA_DIR, "backups");
+/** Central directory for dispatch run artifacts: DATA_DIR/dispatch-runs/<board-slug>/<run-id>/ */
+export const DISPATCH_RUNS_DIR = join(DATA_DIR, "dispatch-runs");
 export const PORT = Number(process.env.PORT || 3337);
 
 mkdirSync(DATA_DIR, { recursive: true });
+mkdirSync(BOARDS_DIR, { recursive: true });
 mkdirSync(EXPORT_DIR, { recursive: true });
 mkdirSync(BACKUP_DIR, { recursive: true });
+mkdirSync(DISPATCH_RUNS_DIR, { recursive: true });

package/src/core/registry.js

@@ -4,9 +4,10 @@
 // the board that owns a given ticket / state / entry / relation. Callers
 // receive `{ board, db }` and pass it down via `ctx`.
 
-import { mkdirSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { createBoardSchema, getRegistry, openConnection } from "./db.js";
+import { BOARDS_DIR } from "./paths.js";
 import { now, slugify } from "./util.js";
 
 export function listBoards() {
@@ -92,14 +93,16 @@ export function updateBoardMeta(boardId, patch) {
     .run(...vals);
 }
 
-/** Where a new board.db should live: flat .orbit/board.db for a repo's first
- *  board, or .orbit/boards/<slug>/board.db for additional boards on the same
- *  repo. */
-export function computeNewBoardDbPath(repoPathNorm, slug) {
-  const reg = getRegistry();
-  const count = reg.prepare("SELECT COUNT(*) AS c FROM boards WHERE repo_path = ?").get(repoPathNorm).c;
-  if (count === 0) return join(repoPathNorm, ".orbit", "board.db");
-  return join(repoPathNorm, ".orbit", "boards", slug, "board.db");
+/** Where a new board.db should live: always in the central DATA_DIR/boards/<slug>/ directory.
+ *  Falls back to a numeric suffix if the canonical path already exists on disk (orphaned file). */
+export function computeNewBoardDbPath(_repoPathNorm, slug) {
+  const preferred = join(BOARDS_DIR, slug, "board.db");
+  if (!existsSync(preferred)) return preferred;
+  for (let i = 2; i < 1000; i++) {
+    const alt = join(BOARDS_DIR, `${slug}-${i}`, "board.db");
+    if (!existsSync(alt)) return alt;
+  }
+  return preferred; // callers will handle any existing file
 }
 
 /** Create the directory + file and apply the per-board schema. Returns the

package/src/core/router.js

@@ -5,9 +5,9 @@
 // board, it is rejected with 400 board_id_required rather than silently
 // inheriting some other caller's recent state.
 
-import { localOwnerActor } from "./auth.js";
+import { actorFromHttpRequest } from "./auth.js";
 import { scheduleAutomaticBoardBackup } from "./backups.js";
-import { readJson, sendJson, setCors } from "./http.js";
+import { readJson, readRaw, sendFile, sendJson, setCors } from "./http.js";
 import {
   findBoardForBoardEntry,
   findBoardForRelation,
@@ -54,11 +54,20 @@ import {
   getTicketRelations
 } from "./relations.js";
 import { searchTickets } from "./search.js";
+import {
+  createTicketAttachment,
+  deleteTicketAttachment,
+  getTicketAttachmentContent,
+  listTicketAttachments,
+  MAX_IMAGE_ATTACHMENT_BYTES
+} from "./attachments.js";
 import {
   checkpointTicket,
   claimNext,
   completeTicket,
-  getContextPack
+  getContextPack,
+  readComments,
+  readTicket
 } from "./agent.js";
 
 /** Build a ctx for an already-resolved registry row + actor. */
@@ -103,7 +112,7 @@ export async function handleApi(req, res, url) {
     return;
   }
 
-  const actor = localOwnerActor();
+  const actor = actorFromHttpRequest(req);
 
   // Bootstrap: read-only registry + one chosen board. No global state mutated.
   if (req.method === "GET" && url.pathname === "/api/bootstrap") {
@@ -183,7 +192,9 @@ export async function handleApi(req, res, url) {
       return;
     }
     if (sub === "export" && req.method === "GET") {
-      sendJson(res, 200, exportBoard(row.id, ctx));
+      sendJson(res, 200, exportBoard(row.id, ctx, {
+        includeAttachments: url.searchParams.get("include_attachments") === "true" || url.searchParams.get("include_images") === "true"
+      }));
       return;
     }
     if (sub === "states" && req.method === "POST") {
@@ -212,6 +223,18 @@ export async function handleApi(req, res, url) {
     return;
   }
 
+  // /api/tickets/lookup GET — exact lightweight lookup by number or title.
+  if (req.method === "GET" && url.pathname === "/api/tickets/lookup") {
+    const { boardId, boardSlug } = boardHintsFromQuery(url);
+    const row = resolveBoardFromHint(boardId, boardSlug);
+    if (!row) throw httpError(400, "board_id_required");
+    const lookup = {};
+    if (url.searchParams.has("number")) lookup.number = url.searchParams.get("number");
+    if (url.searchParams.has("title")) lookup.title = url.searchParams.get("title");
+    sendJson(res, 200, readTicket(lookup, ctxFromBoardRow(row, actor)));
+    return;
+  }
+
   // /api/tickets/:id/... — board resolved from query hint or via lookup.
   const ticketPath = url.pathname.match(/^\/api\/tickets\/([^/]+)(?:\/(.*))?$/);
   if (ticketPath) {
@@ -223,6 +246,10 @@ export async function handleApi(req, res, url) {
     if (!found) throw httpError(404, "ticket_not_found");
     const ctx = ctxFromBoardRow(found.board, actor);
 
+    if (sub === "" && req.method === "GET") {
+      sendJson(res, 200, readTicket(ticketId, ctx));
+      return;
+    }
     if (sub === "" && req.method === "PATCH") {
       const body = await readJson(req);
       sendMutationJson(res, 200, updateTicket(ticketId, body, ctx), ctx);
@@ -257,11 +284,40 @@ export async function handleApi(req, res, url) {
       sendJson(res, 200, getTicketBlockers(ticketId, ctx));
       return;
     }
+    if (sub === "comments" && req.method === "GET") {
+      sendJson(res, 200, readComments(ticketId, ctx));
+      return;
+    }
     if (sub === "comments" && req.method === "POST") {
       const body = await readJson(req);
       sendMutationJson(res, 201, createComment(ticketId, body, ctx), ctx);
       return;
     }
+    if (sub === "attachments" && req.method === "GET") {
+      sendJson(res, 200, listTicketAttachments(ticketId, ctx));
+      return;
+    }
+    if (sub === "attachments" && req.method === "POST") {
+      const bytes = await readRaw(req, MAX_IMAGE_ATTACHMENT_BYTES);
+      const attachment = createTicketAttachment(ticketId, {
+        bytes,
+        mime_type: req.headers["content-type"],
+        original_name: req.headers["x-file-name"] || url.searchParams.get("filename") || "image"
+      }, ctx);
+      sendMutationJson(res, 201, attachment, ctx);
+      return;
+    }
+    const attachmentContentPath = sub.match(/^attachments\/([^/]+)\/content$/);
+    if (attachmentContentPath && req.method === "GET") {
+      const result = getTicketAttachmentContent(ticketId, decodeURIComponent(attachmentContentPath[1]), ctx);
+      sendFile(res, result.filePath, result.row.mime_type);
+      return;
+    }
+    const attachmentPath = sub.match(/^attachments\/([^/]+)$/);
+    if (attachmentPath && req.method === "DELETE") {
+      sendMutationJson(res, 200, deleteTicketAttachment(ticketId, decodeURIComponent(attachmentPath[1]), ctx), ctx);
+      return;
+    }
     sendJson(res, 404, { error: "not_found" });
     return;
   }

package/src/core/search.js

@@ -23,7 +23,7 @@ export function searchTickets(args, ctx) {
   if (ticketNumber !== null) {
     rows = db
       .prepare(
-        `SELECT t.*, s.name AS state_name, b.slug AS board_slug, -1 AS rank
+        `SELECT t.*, s.name AS state_name, s.role AS state_role, b.slug AS board_slug, -1 AS rank
          FROM tickets t
          JOIN states s ON s.id = t.state_id
          JOIN boards b ON b.id = t.board_id
@@ -37,7 +37,7 @@ export function searchTickets(args, ctx) {
     rows = rows.concat(
       db
         .prepare(
-          `SELECT t.*, s.name AS state_name, b.slug AS board_slug,
+          `SELECT t.*, s.name AS state_name, s.role AS state_role, b.slug AS board_slug,
                   bm25(ticket_fts) AS rank
            FROM ticket_fts
            JOIN tickets t ON t.id = ticket_fts.ticket_id
@@ -61,7 +61,7 @@ export function searchTickets(args, ctx) {
     rows = rows.concat(
       db
         .prepare(
-          `SELECT DISTINCT t.*, s.name AS state_name, b.slug AS board_slug, ${numberRank} AS rank
+          `SELECT DISTINCT t.*, s.name AS state_name, s.role AS state_role, b.slug AS board_slug, ${numberRank} AS rank
            FROM tickets t
            JOIN states s ON s.id = t.state_id
            JOIN boards b ON b.id = t.board_id

package/src/core/snapshots.js

@@ -13,8 +13,13 @@ import {
   requiredString
 } from "./util.js";
 import { reindexAllTickets } from "./tickets.js";
+import {
+  attachmentRowsForBoard,
+  importAttachmentRows,
+  serializeAttachmentForExport
+} from "./attachments.js";
 
-export function exportBoard(boardId, ctx) {
+export function exportBoard(boardId, ctx, options = {}) {
   const { db, board, actor } = ctx;
   if (boardId !== board.id) throw httpError(404, "board_not_found");
   const innerBoard = boardById(db, boardId);
@@ -56,17 +61,22 @@ export function exportBoard(boardId, ctx) {
        ORDER BY created_at ASC`
     )
     .all(boardId);
+  const attachments = attachmentRowsForBoard(db, boardId).map((row) =>
+    serializeAttachmentForExport(board, row, Boolean(options.includeAttachments))
+  );
 
   return {
     format: "orbit-board-export",
-    version: 5,
+    version: 6,
     exported_at: now(),
+    include_attachments: Boolean(options.includeAttachments),
     board: { ...innerBoard },
     states,
     labels,
     tickets,
     comments,
     relations,
+    attachments,
     board_entries: entries,
     events
   };
@@ -200,6 +210,8 @@ export function importBoardSnapshot(body, ctx) {
       );
     }
 
+    importAttachmentRows(snapshot, ctx, targetBoardId);
+
     for (const entry of snapshot.board_entries || []) {
       db.prepare(
         `INSERT INTO board_entries

package/src/mcp/orbit-client.js

@@ -61,6 +61,7 @@ export function createHttpOrbitClient(env = process.env, fetchImpl = globalThis.
   return {
     mode: "remote",
     sessionLabel: apiUrl,
+    close() {},
     async boardContext(args = {}) {
       return request("GET", `/api/boards/${encodeURIComponent(requireBoard(args))}/context`, { query: { include_struck: args.include_struck ? "true" : undefined } });
     },
@@ -69,11 +70,26 @@ export function createHttpOrbitClient(env = process.env, fetchImpl = globalThis.
     async claimNext(args = {}) { return request("POST", "/api/agent/claim-next", { body: { ...args, board: requireBoard(args) } }); },
     async getTicketContext(args = {}) { return request("GET", `/api/tickets/${encodeURIComponent(args.ticket_id)}/context`, { query: { ...ticketQuery(args), depth: args.depth || 1 } }); },
     async readTicket(args = {}) {
-      if (args.ticket_id) return this.getTicketContext({ ...args, depth: 1 });
-      const found = await this.search({ q: args.title || String(args.number || ""), limit: 10, ...args });
-      return found;
+      if (args.ticket_id) {
+        return request("GET", `/api/tickets/${encodeURIComponent(args.ticket_id)}`, { query: ticketQuery(args) });
+      }
+      if (args.number !== undefined || args.title) {
+        return request("GET", "/api/tickets/lookup", { query: { ...ticketQuery(args), number: args.number, title: args.title } });
+      }
+      throw rpcError(-32602, "ticket_id_or_number_or_title_required");
+    },
+    async readComments(args = {}) {
+      if (args.ticket_id) {
+        return request("GET", `/api/tickets/${encodeURIComponent(args.ticket_id)}/comments`, { query: ticketQuery(args) });
+      }
+      const found = await this.readTicket(args);
+      const ticket = found.ticket || found.results?.find((row) =>
+        (args.number !== undefined && Number(row.number) === Number(args.number)) ||
+        (args.title && String(row.title || "").toLowerCase() === String(args.title).toLowerCase())
+      );
+      if (!ticket?.id) throw rpcError(-32004, "ticket_not_found");
+      return request("GET", `/api/tickets/${encodeURIComponent(ticket.id)}/comments`, { query: ticketQuery(args) });
     },
-    async readComments(args = {}) { const ctx = await this.readTicket(args); return { comments: ctx.comments || ctx.ticket?.comments || [] }; },
     async getTicketRelations(args = {}) { return request("GET", `/api/tickets/${encodeURIComponent(args.ticket_id)}/relations`, { query: ticketQuery(args) }); },
     async getTicketBlockers(args = {}) { return request("GET", `/api/tickets/${encodeURIComponent(args.ticket_id)}/blockers`, { query: ticketQuery(args) }); },
     async search(args = {}) { return request("GET", "/api/search", { query: { q: args.q, limit: args.limit, board_id: args.board_id, board: args.board_slug || args.board || defaultBoard } }); },
@@ -87,7 +103,11 @@ export function createHttpOrbitClient(env = process.env, fetchImpl = globalThis.
     async restoreTicket(args = {}) { return request("POST", `/api/tickets/${encodeURIComponent(args.ticket_id)}/restore`, { query: ticketQuery(args) }); },
     async deleteTicket(args = {}) { return request("DELETE", `/api/tickets/${encodeURIComponent(args.ticket_id)}`, { query: ticketQuery(args) }); },
     async listArchive(args = {}) { return request("GET", `/api/boards/${encodeURIComponent(requireBoard(args))}/archive`); },
-    async exportBoard(args = {}) { return request("GET", `/api/boards/${encodeURIComponent(requireBoard(args))}/export`); },
+    async exportBoard(args = {}) {
+      return request("GET", `/api/boards/${encodeURIComponent(requireBoard(args))}/export`, {
+        query: { include_attachments: args.include_attachments || args.include_images ? "true" : undefined }
+      });
+    },
     async updateSettings(args = {}) { const { board_id, board_slug, board, ...patch } = args; return request("PATCH", `/api/boards/${encodeURIComponent(requireBoard(args))}`, { body: patch }); }
   };
 }
@@ -100,45 +120,59 @@ export async function createLocalOrbitClient(env = process.env) {
   const seed = await import("../core/seed.js");
   const util = await import("../core/util.js");
 
+  const provision = await import("../core/provision-repo-board.js");
   let sessionBoardRow = null;
   const setSessionBoard = (row) => { sessionBoardRow = row; if (row) registry.touchBoardActive(row.id); };
   const getSessionBoard = () => sessionBoardRow;
   const walkUp = (startDir, predicate) => { let dir = startDir; while (true) { if (predicate(dir)) return dir; const parent = dirname(dir); if (parent === dir) return null; dir = parent; } };
-  const createBoardAtRoot = (root) => {
-    const dbPath = join(root, ".orbit", "board.db");
-    mkdirSync(dirname(dbPath), { recursive: true });
-    const db = dbMod.openConnection(dbPath);
-    dbMod.createBoardSchema(db);
-    const seeded = seed.seedIfEmpty(db, root);
-    if (seeded) {
-      const t = util.now();
-      registry.insertBoard({ id: seeded.id, slug: seeded.slug, name: seeded.name, repo_path: root, db_path: dbPath, repo_url: seeded.repo_url || "", default_branch: seeded.default_branch || "main", last_active_at: t, created_at: t, updated_at: t });
-    }
-    const fresh = registry.getBoardByRepoPath(root);
-    if (fresh) { registry.syncRegistryFromBoardDb(fresh, db); setSessionBoard(fresh); }
-  };
 
   const start = util.normalizePath(env.PROJECT_ROOT ? resolve(env.PROJECT_ROOT) : process.cwd());
-  const boardRoot = walkUp(start, (dir) => existsSync(join(dir, ".orbit", "board.db")));
-  if (boardRoot) {
-    const root = util.normalizePath(boardRoot);
-    const existing = registry.getBoardByRepoPath(root);
-    if (existing) setSessionBoard(existing);
-    else {
-      const dbPath = join(boardRoot, ".orbit", "board.db");
-      const db = dbMod.openConnection(dbPath);
-      dbMod.createBoardSchema(db);
-      const seeded = seed.seedIfEmpty(db, root);
-      if (seeded) {
-        const t = util.now();
-        registry.insertBoard({ id: seeded.id, slug: seeded.slug, name: seeded.name, repo_path: root, db_path: dbPath, repo_url: seeded.repo_url || "", default_branch: seeded.default_branch || "main", last_active_at: t, created_at: t, updated_at: t });
+  const displayStart = resolve(env.PROJECT_ROOT ? env.PROJECT_ROOT : process.cwd());
+
+  // Find repo root (walk up for .git, fall back to start).
+  const gitRoot = walkUp(start, (dir) => existsSync(join(dir, ".git")));
+  const repoRoot = util.normalizePath(gitRoot || start);
+
+  // 1. Registry-first lookup: walk upward from start so we find boards regardless
+  //    of whether they were registered at the git root, at PROJECT_ROOT, or at any
+  //    ancestor (handles boards originally created from a subdirectory).
+  let foundByRegistry = false;
+  {
+    let dir = start;
+    while (true) {
+      const row = registry.getBoardByRepoPath(dir);
+      if (row && existsSync(row.db_path)) { setSessionBoard(row); foundByRegistry = true; break; }
+      const parent = util.normalizePath(dirname(dir));
+      if (parent === dir) break; // filesystem root
+      dir = parent;
+    }
+  }
+  if (!foundByRegistry) {
+    // 2. Legacy fallback: walk up for an existing in-repo .orbit/board.db.
+    const boardRoot = walkUp(start, (dir) => existsSync(join(dir, ".orbit", "board.db")));
+    if (boardRoot) {
+      const root = util.normalizePath(boardRoot);
+      const existing = registry.getBoardByRepoPath(root);
+      if (existing) {
+        setSessionBoard(existing);
+      } else {
+        const dbPath = join(boardRoot, ".orbit", "board.db");
+        const db = dbMod.openConnection(dbPath);
+        dbMod.createBoardSchema(db);
+        const seeded = seed.seedIfEmpty(db, root);
+        if (seeded) {
+          const t = util.now();
+          registry.insertBoard({ id: seeded.id, slug: seeded.slug, name: seeded.name, repo_path: root, db_path: dbPath, repo_url: seeded.repo_url || "", default_branch: seeded.default_branch || "main", last_active_at: t, created_at: t, updated_at: t });
+        }
+        const fresh = registry.getBoardByRepoPath(root);
+        if (fresh) { registry.syncRegistryFromBoardDb(fresh, db); setSessionBoard(fresh); }
       }
-      const fresh = registry.getBoardByRepoPath(root);
-      if (fresh) { registry.syncRegistryFromBoardDb(fresh, db); setSessionBoard(fresh); }
+    } else {
+      // 3. No board found — auto-create one (goes to central DATA_DIR/boards/).
+      provision.provisionRepoBoard(repoRoot, { enableAi: true });
+      const fresh = registry.getBoardByRepoPath(repoRoot);
+      if (fresh) setSessionBoard(fresh);
     }
-  } else {
-    const gitRoot = walkUp(start, (dir) => existsSync(join(dir, ".git")));
-    createBoardAtRoot(util.normalizePath(gitRoot || start));
   }
 
   const ctxFor = (row, actor) => {
@@ -153,7 +187,11 @@ export async function createLocalOrbitClient(env = process.env) {
 
   return {
     mode: "local",
-    sessionLabel: () => getSessionBoard()?.db_path || "(none)",
+    sessionLabel: () => {
+      const b = getSessionBoard();
+      return b ? `${displayStart}  target: ${b.repo_path}  db: ${b.db_path}` : "(none)";
+    },
+    close: () => dbMod.closeAllConnections(),
     boardContext: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.getBoardContext(ctx.board.id, ctx, { includeStruck: Boolean(args.include_struck) }); },
     boardList: () => ({ boards: registry.listBoards().map((row) => ({ id: row.id, slug: row.slug, name: row.name, repo_path: row.repo_path })) }),
     boardSetActive: (args = {}) => { const slug = String(args.slug || "").trim(); if (!slug) throw rpcError(-32602, "slug is required."); const row = registry.getBoardBySlug(slug); if (!row) throw rpcError(-32004, `Board slug not found: ${slug}`); setSessionBoard(row); return { ok: true, board_id: row.id, slug: row.slug, name: row.name, db_path: row.db_path }; },
@@ -174,7 +212,12 @@ export async function createLocalOrbitClient(env = process.env) {
     restoreTicket: (args = {}) => { const ctx = sessionCtx(actor()); return backup(ctx, board.restoreTicket(args.ticket_id, ctx)); },
     deleteTicket: (args = {}) => { const ctx = sessionCtx(actor()); return backup(ctx, board.deleteTicket(args.ticket_id, ctx)); },
     listArchive: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return { tickets: board.archivedTicketsForBoard(ctx.db, ctx.board.id) }; },
-    exportBoard: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.exportBoard(ctx.board.id, ctx); },
+    exportBoard: (args = {}) => {
+      const ctx = ctxFor(rowOrSession(args), actor());
+      return board.exportBoard(ctx.board.id, ctx, {
+        includeAttachments: Boolean(args.include_attachments || args.include_images)
+      });
+    },
     updateSettings: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); const { board_id, board_slug, ...patch } = args; return backup(ctx, board.updateBoard(ctx.board.id, patch, ctx)); }
   };
 }