@starlove/orbit 1.0.5 → 1.0.7

package/src/core/agent.js

@@ -24,7 +24,7 @@ import {
   requiredString
 } from "./util.js";
 import { boardManual } from "./boards.js";
-import { reindexTicket } from "./tickets.js";
+import { bumpTicketUpdatedAt, reindexTicket } from "./tickets.js";
 
 /**
  * Claim the next AI-ready ticket on the resolved board. The router/MCP layer
@@ -71,14 +71,16 @@ export function claimNext(body, ctx) {
     if (!inProgress) throw httpError(400, "missing_in_progress_state");
 
     tx(db, () => {
+      const time = now();
       db.prepare("UPDATE tickets SET state_id = ?, updated_at = ? WHERE id = ?").run(
         inProgress.id,
-        now(),
+        time,
         candidate.id
       );
       addComment(db, candidate.id, actor.name, "agent_note", "Agent claimed this ticket and is starting work.");
       recordEvent(db, candidate.board_id, "agent_claimed", candidate.id, actor.name, { agent_id: actor.id });
       reindexTicket(db, candidate.id);
+      bumpTicketUpdatedAt(db, candidate.parent_ticket_id, time);
     });
 
     return {
@@ -157,7 +159,8 @@ export function checkpointTicket(body, ctx) {
   if (!review) throw httpError(400, "missing_review_state");
   const message = requiredString(body.message, "message");
   tx(db, () => {
-    db.prepare("UPDATE tickets SET state_id = ?, updated_at = ? WHERE id = ?").run(review.id, now(), ticket.id);
+    const time = now();
+    db.prepare("UPDATE tickets SET state_id = ?, updated_at = ? WHERE id = ?").run(review.id, time, ticket.id);
     addComment(db, ticket.id, actor.name, "checkpoint", message);
     recordEvent(db, ticket.board_id, "checkpoint_requested", ticket.id, actor.name, {
       from: ticket.state_name,
@@ -167,6 +170,7 @@ export function checkpointTicket(body, ctx) {
       actor_id: actor.id
     });
     reindexTicket(db, ticket.id);
+    bumpTicketUpdatedAt(db, ticket.parent_ticket_id, time);
   });
   return getContextPack(ticket.id, ctx, 1);
 }
@@ -190,10 +194,11 @@ export function completeTicket(body, ctx) {
   if (body.pr_url) lines.push(`PR: ${body.pr_url}`);
   const updates = body.updates ? appendFieldNote(ticket.implementation_updates, body.updates, actor.name) : ticket.implementation_updates;
   tx(db, () => {
+    const time = now();
     addComment(db, ticket.id, actor.name, "completion", lines.join("\n\n"));
     db.prepare(
       "UPDATE tickets SET state_id = ?, implementation_summary = ?, implementation_updates = ?, updated_at = ? WHERE id = ?"
-    ).run(nextState.id, summary, updates, now(), ticket.id);
+    ).run(nextState.id, summary, updates, time, ticket.id);
     recordEvent(db, ticket.board_id, "agent_completed", ticket.id, actor.name, {
       from: ticket.state_name,
       next_state: nextState.name,
@@ -203,6 +208,7 @@ export function completeTicket(body, ctx) {
       actor_id: actor.id
     });
     reindexTicket(db, ticket.id);
+    bumpTicketUpdatedAt(db, ticket.parent_ticket_id, time);
   });
   return getContextPack(ticket.id, ctx, 1);
 }

package/src/core/agents-md.js

@@ -11,6 +11,7 @@ export function orbitAgentsSection() {
 ${ORBIT_AGENTS_CANONICAL_LINE}
 
 When work mentions Orbit, kanban, board, lane, ticket, card, epic, blocker, claim, AI Ready, implementation fields, planning state, project memory, or handoff: read \`SKILL-ORBIT.md\` first and follow it.
+Use Orbit API/MCP tools for tickets/cards; do not edit .orbit/board.db directly.
 ${ORBIT_AGENTS_END}\n`;
 }
 

package/src/core/board.js

@@ -100,7 +100,7 @@ export {
   updateBoardEntry,
   boardManual
 } from "./boards.js";
-export { archiveTicket, createComment, deleteTicket, restoreTicket, updateTicket } from "./tickets.js";
+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";

package/src/core/bootstrap.js

@@ -33,8 +33,9 @@ function boardSummaryFromRegistry(r) {
  *
  * @param actor authenticated actor
  * @param requestedBoardId optional board id from `?board_id=` (or null)
+ * @param requestedBoardSlug optional board slug from `?board=` (or null)
  */
-export function getBootstrap(actor, requestedBoardId = null) {
+export function getBootstrap(actor, requestedBoardId = null, requestedBoardSlug = null) {
   const registryRows = listBoards();
   const accessible = registryRows.filter((row) => canAccessBoard(actor, { slug: row.slug }));
 
@@ -57,6 +58,9 @@ export function getBootstrap(actor, requestedBoardId = null) {
   if (requestedBoardId) {
     chosen = accessible.find((row) => row.id === requestedBoardId) || null;
   }
+  if (!chosen && requestedBoardSlug) {
+    chosen = accessible.find((row) => row.slug === requestedBoardSlug) || null;
+  }
   if (!chosen) {
     const defaultRow = pickDefaultBoard();
     if (defaultRow && accessible.some((row) => row.id === defaultRow.id)) {
@@ -105,7 +109,7 @@ export function getBootstrap(actor, requestedBoardId = null) {
        JOIN states s ON s.id = t.state_id
        JOIN boards b ON b.id = t.board_id
        WHERE t.archived_at IS NULL
-       ORDER BY t.updated_at DESC`
+       ORDER BY t.updated_at DESC, t.id ASC`
     )
     .all()
     .filter((ticket) => boardIds.has(ticket.board_id));
@@ -143,6 +147,10 @@ export function getBootstrap(actor, requestedBoardId = null) {
 
   return {
     actor: publicActor(actor),
+    // The server may choose a default board that is not first in the registry's
+    // alphabetic board list. Expose that choice explicitly so first-page load
+    // selects the same board whose lanes/tickets are included below.
+    active_board_id: chosenRow.id,
     meta: {
       db_path: chosenRow.db_path,
       export_dir: EXPORT_DIR

package/src/core/router.js

@@ -107,7 +107,7 @@ export async function handleApi(req, res, url) {
 
   // Bootstrap: read-only registry + one chosen board. No global state mutated.
   if (req.method === "GET" && url.pathname === "/api/bootstrap") {
-    sendJson(res, 200, getBootstrap(actor, url.searchParams.get("board_id")));
+    sendJson(res, 200, getBootstrap(actor, url.searchParams.get("board_id"), url.searchParams.get("board")));
     return;
   }
 

package/src/core/search.js

@@ -16,41 +16,73 @@ export function searchTickets(args, ctx) {
   if (!q) return { query: q, results: [] };
   if (!canAccessBoard(actor, board)) return { query: q, results: [] };
 
+  const ticketNumber = ticketNumberQuery(q);
   const fts = toFtsQuery(q);
   let rows = [];
-  try {
+
+  if (ticketNumber !== null) {
     rows = db
       .prepare(
-        `SELECT t.*, s.name AS state_name, b.slug AS board_slug,
-                bm25(ticket_fts) AS rank
-         FROM ticket_fts
-         JOIN tickets t ON t.id = ticket_fts.ticket_id
+        `SELECT t.*, s.name AS state_name, 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
-         WHERE ticket_fts MATCH ? AND t.archived_at IS NULL
-         ORDER BY rank
+         WHERE t.board_id = ? AND t.number = ? AND t.archived_at IS NULL
          LIMIT ?`
       )
-      .all(fts, limit);
+      .all(board.id, ticketNumber, limit);
+  }
+
+  try {
+    rows = rows.concat(
+      db
+        .prepare(
+          `SELECT t.*, s.name AS state_name, b.slug AS board_slug,
+                  bm25(ticket_fts) AS rank
+           FROM ticket_fts
+           JOIN tickets t ON t.id = ticket_fts.ticket_id
+           JOIN states s ON s.id = t.state_id
+           JOIN boards b ON b.id = t.board_id
+           WHERE ticket_fts MATCH ? AND t.board_id = ? AND t.archived_at IS NULL
+           ORDER BY rank
+           LIMIT ?`
+        )
+        .all(fts, board.id, limit)
+    );
   } catch {
     const like = `%${q}%`;
-    rows = db
-      .prepare(
-        `SELECT DISTINCT t.*, s.name AS state_name, b.slug AS board_slug, 0 AS rank
-         FROM tickets t
-         JOIN states s ON s.id = t.state_id
-         JOIN boards b ON b.id = t.board_id
-         LEFT JOIN comments c ON c.ticket_id = t.id
-         WHERE t.archived_at IS NULL
-           AND (t.title LIKE ? OR t.description LIKE ? OR t.ai_plan LIKE ?
-            OR t.implementation_summary LIKE ? OR t.implementation_updates LIKE ? OR c.body LIKE ?)
-         ORDER BY t.updated_at DESC
-         LIMIT ?`
-      )
-      .all(like, like, like, like, like, like, limit);
+    const numberRank = ticketNumber !== null ? "CASE WHEN t.number = ? THEN -1 ELSE 0 END" : "0";
+    const numberPredicate = ticketNumber !== null ? "OR t.number = ?" : "";
+    const fallbackArgs = ticketNumber !== null ? [ticketNumber, board.id] : [board.id];
+    fallbackArgs.push(like, like, like, like, like, like);
+    if (ticketNumber !== null) fallbackArgs.push(ticketNumber);
+    fallbackArgs.push(limit);
+
+    rows = rows.concat(
+      db
+        .prepare(
+          `SELECT DISTINCT t.*, s.name AS state_name, 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
+           LEFT JOIN comments c ON c.ticket_id = t.id
+           WHERE t.board_id = ? AND t.archived_at IS NULL
+             AND (t.title LIKE ? OR t.description LIKE ? OR t.ai_plan LIKE ?
+              OR t.implementation_summary LIKE ? OR t.implementation_updates LIKE ? OR c.body LIKE ?
+              ${numberPredicate})
+           ORDER BY t.updated_at DESC, t.id ASC
+           LIMIT ?`
+        )
+        .all(...fallbackArgs)
+    );
   }
 
-  rows.sort((a, b) => (a.rank !== b.rank ? a.rank - b.rank : String(b.updated_at).localeCompare(String(a.updated_at))));
+  rows.sort((a, b) => {
+    if (a.rank !== b.rank) return a.rank - b.rank;
+    const byTime = String(b.updated_at).localeCompare(String(a.updated_at));
+    if (byTime !== 0) return byTime;
+    return String(a.id).localeCompare(String(b.id));
+  });
 
   const seen = new Set();
   const deduped = [];
@@ -68,3 +100,10 @@ export function searchTickets(args, ctx) {
 
   return { query: q, results };
 }
+
+function ticketNumberQuery(q) {
+  const match = String(q).trim().match(/^#?(\d+)$/);
+  if (!match) return null;
+  const number = Number(match[1]);
+  return Number.isSafeInteger(number) ? number : null;
+}

package/src/core/tickets.js

@@ -17,6 +17,17 @@ import {
   requiredString
 } from "./util.js";
 
+/**
+ * Bump a ticket's `updated_at` without recording an event or touching other
+ * fields. Used to roll child activity up to the parent epic so the column sort
+ * (ORDER BY updated_at DESC) keeps the epic group near recent activity even
+ * when only its children changed. Pass `null`/undefined to no-op.
+ */
+export function bumpTicketUpdatedAt(db, ticketId, time) {
+  if (!ticketId) return;
+  db.prepare("UPDATE tickets SET updated_at = ? WHERE id = ?").run(time, ticketId);
+}
+
 export function createTicket(body, ctx) {
   const { db, board, actor } = ctx;
   // The router resolves `ctx.board` from path/body/query before we get here.
@@ -82,6 +93,7 @@ export function createTicket(body, ctx) {
       parent_ticket_id: parentTicketId
     });
     reindexTicket(db, ticketId);
+    bumpTicketUpdatedAt(db, parentTicketId, time);
     return ticketById(db, ticketId);
   });
 }
@@ -139,11 +151,12 @@ export function updateTicket(ticketId, body, ctx) {
   }
 
   return tx(db, () => {
+    const time = now();
     if (fields.length > 0) {
       const sets = fields.map((field) => `${field} = ?`);
       const values = fields.map((field) => applied[field]);
       sets.push("updated_at = ?");
-      values.push(now(), ticketId);
+      values.push(time, ticketId);
       db.prepare(`UPDATE tickets SET ${sets.join(", ")} WHERE id = ?`).run(...values);
     }
 
@@ -160,7 +173,7 @@ export function updateTicket(ticketId, body, ctx) {
         db.prepare("INSERT OR IGNORE INTO ticket_labels (ticket_id, label_id) VALUES (?, ?)").run(ticketId, label.id);
       }
       if (fields.length === 0) {
-        db.prepare("UPDATE tickets SET updated_at = ? WHERE id = ?").run(now(), ticketId);
+        db.prepare("UPDATE tickets SET updated_at = ? WHERE id = ?").run(time, ticketId);
       }
     }
 
@@ -191,6 +204,13 @@ export function updateTicket(ticketId, body, ctx) {
       }
     }
     reindexTicket(db, ticketId);
+    // Roll activity up to the parent epic so the column sort keeps the epic
+    // group near recent child activity. On reparent, bump both old and new
+    // parent — both views changed (one lost a child, the other gained one).
+    bumpTicketUpdatedAt(db, before.parent_ticket_id, time);
+    if (after.parent_ticket_id && after.parent_ticket_id !== before.parent_ticket_id) {
+      bumpTicketUpdatedAt(db, after.parent_ticket_id, time);
+    }
     return after;
   });
 }
@@ -208,6 +228,7 @@ export function archiveTicket(ticketId, ctx) {
     const time = now();
     db.prepare("UPDATE tickets SET archived_at = ?, updated_at = ? WHERE id = ?").run(time, time, ticketId);
     recordEvent(db, ticket.board_id, "ticket_archived", ticketId, actor.name, { title: ticket.title });
+    bumpTicketUpdatedAt(db, ticket.parent_ticket_id, time);
     return ticketById(db, ticketId);
   });
 }
@@ -225,6 +246,7 @@ export function restoreTicket(ticketId, ctx) {
     const time = now();
     db.prepare("UPDATE tickets SET archived_at = NULL, updated_at = ? WHERE id = ?").run(time, ticketId);
     recordEvent(db, ticket.board_id, "ticket_restored", ticketId, actor.name, { title: ticket.title });
+    bumpTicketUpdatedAt(db, ticket.parent_ticket_id, time);
     return ticketById(db, ticketId);
   });
 }
@@ -246,6 +268,7 @@ export function deleteTicket(ticketId, ctx) {
     });
     db.prepare("DELETE FROM ticket_fts WHERE ticket_id = ?").run(ticketId);
     db.prepare("DELETE FROM tickets WHERE id = ?").run(ticketId);
+    bumpTicketUpdatedAt(db, ticket.parent_ticket_id, now());
     return { ok: true, deleted_id: ticketId };
   });
 }
@@ -262,10 +285,12 @@ export function createComment(ticketId, body, ctx) {
   const kind = body.kind || (actor.type === "agent" ? "agent_note" : "human_comment");
 
   return tx(db, () => {
+    const time = now();
     const comment = addComment(db, ticketId, author, kind, commentBody);
-    db.prepare("UPDATE tickets SET updated_at = ? WHERE id = ?").run(now(), ticketId);
+    db.prepare("UPDATE tickets SET updated_at = ? WHERE id = ?").run(time, ticketId);
     recordEvent(db, ticket.board_id, "comment_created", ticketId, actor.name, { kind: comment.kind });
     reindexTicket(db, ticketId);
+    bumpTicketUpdatedAt(db, ticket.parent_ticket_id, time);
     return comment;
   });
 }

package/src/mcp/orbit-client.js

@@ -0,0 +1,180 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+function rpcError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+export function orbitMode(env = process.env) {
+  const mode = String(env.ORBIT_MODE || "local").trim().toLowerCase();
+  if (mode === "remote" || mode === "http") return "remote";
+  if (mode === "local" || mode === "") return "local";
+  throw rpcError(-32602, `Unsupported ORBIT_MODE: ${env.ORBIT_MODE}`);
+}
+
+export async function createOrbitClient(env = process.env) {
+  return orbitMode(env) === "remote" ? createHttpOrbitClient(env) : createLocalOrbitClient(env);
+}
+
+export function createHttpOrbitClient(env = process.env, fetchImpl = globalThis.fetch) {
+  const apiUrl = String(env.ORBIT_API_URL || "").trim().replace(/\/+$/, "");
+  const defaultBoard = String(env.ORBIT_DEFAULT_BOARD || "").trim();
+  if (!apiUrl) throw rpcError(-32602, "ORBIT_MODE=remote requires ORBIT_API_URL.");
+  if (typeof fetchImpl !== "function") throw rpcError(-32603, "ORBIT_MODE=remote requires global fetch support.");
+
+  async function request(method, path, { query = {}, body, ok = [200] } = {}) {
+    const url = new URL(`${apiUrl}${path}`);
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, String(value));
+    }
+    const response = await fetchImpl(url, {
+      method,
+      headers: body === undefined ? undefined : { "Content-Type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body)
+    });
+    let payload = null;
+    const text = await response.text();
+    if (text) {
+      try { payload = JSON.parse(text); } catch { payload = { message: text }; }
+    }
+    if (!ok.includes(response.status)) {
+      const message = payload?.message || payload?.error || `Orbit API ${method} ${url.pathname} failed with HTTP ${response.status}`;
+      throw rpcError(-32000, message);
+    }
+    return payload ?? {};
+  }
+
+  function boardArg(args = {}) {
+    return args.board_id || args.board_slug || args.board || defaultBoard;
+  }
+
+  function requireBoard(args = {}) {
+    const board = boardArg(args);
+    if (!board) throw rpcError(-32602, "Remote Orbit MCP requires board_id/board_slug/board or ORBIT_DEFAULT_BOARD.");
+    return board;
+  }
+
+  const ticketQuery = (args = {}) => ({ board_id: args.board_id, board: args.board_slug || args.board || defaultBoard });
+
+  return {
+    mode: "remote",
+    sessionLabel: apiUrl,
+    async boardContext(args = {}) {
+      return request("GET", `/api/boards/${encodeURIComponent(requireBoard(args))}/context`, { query: { include_struck: args.include_struck ? "true" : undefined } });
+    },
+    async boardList() { return request("GET", "/api/boards"); },
+    async boardSetActive(args = {}) { if (!args.slug) throw rpcError(-32602, "slug is required."); env.ORBIT_DEFAULT_BOARD = String(args.slug); return { ok: true, slug: String(args.slug), mode: "remote" }; },
+    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;
+    },
+    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 } }); },
+    async createTicket(args = {}) { return request("POST", "/api/tickets", { body: { ...args, board: requireBoard(args) }, ok: [201] }); },
+    async updateTicket({ ticket_id, ...patch }) { return request("PATCH", `/api/tickets/${encodeURIComponent(ticket_id)}`, { query: ticketQuery(patch), body: patch }); },
+    async addComment({ ticket_id, ...body }) { return request("POST", `/api/tickets/${encodeURIComponent(ticket_id)}/comments`, { body, ok: [201] }); },
+    async addBoardEntry(args = {}) { return request("POST", `/api/boards/${encodeURIComponent(requireBoard(args))}/entries`, { body: args, ok: [201] }); },
+    async checkpoint(args = {}) { return request("POST", "/api/agent/checkpoint", { body: args }); },
+    async complete(args = {}) { return request("POST", "/api/agent/complete", { body: args }); },
+    async archiveTicket(args = {}) { return request("POST", `/api/tickets/${encodeURIComponent(args.ticket_id)}/archive`, { query: ticketQuery(args) }); },
+    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 updateSettings(args = {}) { const { board_id, board_slug, board, ...patch } = args; return request("PATCH", `/api/boards/${encodeURIComponent(requireBoard(args))}`, { body: patch }); }
+  };
+}
+
+export async function createLocalOrbitClient(env = process.env) {
+  const board = await import("../core/board.js");
+  const dbMod = await import("../core/db.js");
+  const registry = await import("../core/registry.js");
+  const backups = await import("../core/backups.js");
+  const seed = await import("../core/seed.js");
+  const util = await import("../core/util.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 fresh = registry.getBoardByRepoPath(root);
+      if (fresh) { registry.syncRegistryFromBoardDb(fresh, db); setSessionBoard(fresh); }
+    }
+  } else {
+    const gitRoot = walkUp(start, (dir) => existsSync(join(dir, ".git")));
+    createBoardAtRoot(util.normalizePath(gitRoot || start));
+  }
+
+  const ctxFor = (row, actor) => {
+    if (!row) throw rpcError(-32602, "No board in session; pass board_id or board_slug, or call board_set_active first.");
+    return { actor, board: row, db: registry.openBoardDb(row) };
+  };
+  const sessionCtx = (actor) => ctxFor(getSessionBoard(), actor);
+  const backup = (ctx, result) => { backups.scheduleAutomaticBoardBackup(ctx.board, ctx.db); return result; };
+  const explicit = (args = {}) => args.board_id ? registry.getBoardByRegistryId(args.board_id) : (args.board_slug || args.board ? registry.getBoardBySlug(args.board_slug || args.board) : null);
+  const rowOrSession = (args = {}) => explicit(args) || getSessionBoard();
+  const actor = () => board.localAgentActor();
+
+  return {
+    mode: "local",
+    sessionLabel: () => getSessionBoard()?.db_path || "(none)",
+    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 }; },
+    claimNext: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return backup(ctx, board.claimNext(args, ctx)); },
+    getTicketContext: (args = {}) => board.getContextPack(args.ticket_id, sessionCtx(actor()), Number(args.depth || 1)),
+    readTicket: (args = {}) => board.readTicket(args, sessionCtx(actor())),
+    readComments: (args = {}) => board.readComments(args, sessionCtx(actor())),
+    getTicketRelations: (args = {}) => board.getTicketRelations(args.ticket_id, sessionCtx(actor())),
+    getTicketBlockers: (args = {}) => board.getTicketBlockers(args.ticket_id, sessionCtx(actor())),
+    search: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.searchTickets({ q: args.q, limit: args.limit }, ctx); },
+    createTicket: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); const { board_slug, board: _b, ...body } = args; body.board_id = ctx.board.id; return backup(ctx, board.createTicket(body, ctx)); },
+    updateTicket: ({ ticket_id, ...patch }) => { const ctx = sessionCtx(actor()); return backup(ctx, board.updateTicket(ticket_id, patch, ctx)); },
+    addComment: ({ ticket_id, ...body }) => { const ctx = sessionCtx(actor()); return backup(ctx, board.createComment(ticket_id, body, ctx)); },
+    addBoardEntry: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return backup(ctx, board.createBoardEntry(ctx.board.id, args, ctx)); },
+    checkpoint: (args = {}) => { const ctx = sessionCtx(actor()); return backup(ctx, board.checkpointTicket(args, ctx)); },
+    complete: (args = {}) => { const ctx = sessionCtx(actor()); return backup(ctx, board.completeTicket(args, ctx)); },
+    archiveTicket: (args = {}) => { const ctx = sessionCtx(actor()); return backup(ctx, board.archiveTicket(args.ticket_id, ctx)); },
+    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); },
+    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)); }
+  };
+}