@starlove/orbit 1.0.7 → 1.1.1

package/src/mcp/orbit-client.js

@@ -57,26 +57,61 @@ export function createHttpOrbitClient(env = process.env, fetchImpl = globalThis.
   }
 
   const ticketQuery = (args = {}) => ({ board_id: args.board_id, board: args.board_slug || args.board || defaultBoard });
+  const searchQuery = (args = {}) => ({
+    q: args.q,
+    limit: args.limit,
+    board_id: args.board_id,
+    board: args.board_slug || args.board || defaultBoard,
+    mode: args.mode,
+    include_full: args.include_full || args.includeFull ? "true" : undefined,
+    fields: Array.isArray(args.fields) ? args.fields.join(",") : args.fields,
+    max_chars_per_field: args.max_chars_per_field ?? args.maxCharsPerField
+  });
+  const contextQuery = (args = {}) => ({
+    ...ticketQuery(args),
+    depth: args.depth,
+    max_chars_per_field: args.max_chars_per_field ?? args.maxCharsPerField,
+    comment_limit: args.comment_limit ?? args.commentLimit,
+    include_parent_full: args.include_parent_full || args.includeParentFull ? "true" : undefined,
+    include_related_full: args.include_related_full || args.includeRelatedFull ? "true" : undefined
+  });
 
   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 } });
     },
     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 getTicketContext(args = {}) { return request("GET", `/api/tickets/${encodeURIComponent(args.ticket_id)}/context`, { query: { ...contextQuery(args), depth: args.depth || 1 } }); },
+    async getAgentDispatchPacket(args = {}) { return request("GET", `/api/tickets/${encodeURIComponent(args.ticket_id)}/dispatch-packet`, { query: contextQuery(args) }); },
     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 } }); },
+    async search(args = {}) { return request("GET", "/api/search", { query: searchQuery(args) }); },
     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] }); },
@@ -87,7 +122,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 +139,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,17 +206,22 @@ 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 }; },
     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); },
+    getTicketContext: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.getContextPack(args.ticket_id, ctx, Number(args.depth || 1), args); },
+    getAgentDispatchPacket: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.getAgentDispatchPacket(args.ticket_id, ctx, args); },
+    readTicket: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.readTicket(args, ctx); },
+    readComments: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.readComments(args, ctx); },
+    getTicketRelations: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.getTicketRelations(args.ticket_id, ctx); },
+    getTicketBlockers: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.getTicketBlockers(args.ticket_id, ctx); },
+    search: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.searchTickets(args, 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)); },
@@ -174,7 +232,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)); }
   };
 }

package/src/mcp-server.js

@@ -5,6 +5,47 @@
 // "active board" state.
 
 import { createOrbitClient } from "./mcp/orbit-client.js";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import {
+  archivedTicketsForBoard,
+  archiveTicket,
+  checkpointTicket,
+  claimNext,
+  completeTicket,
+  createBoardEntry,
+  createComment,
+  createTicket,
+  deleteTicket,
+  exportBoard,
+  getBoardContext,
+  getAgentDispatchPacket,
+  getContextPack,
+  readComments,
+  readTicket,
+  getTicketBlockers,
+  getTicketRelations,
+  localAgentActor,
+  restoreTicket,
+  searchTickets,
+  updateBoard,
+  updateTicket
+} from "./core/board.js";
+import { closeAllConnections, createBoardSchema, openConnection } from "./core/db.js";
+import {
+  getBoardByRegistryId,
+  getBoardBySlug,
+  getBoardByRepoPath,
+  insertBoard,
+  listBoards,
+  openBoardDb,
+  syncRegistryFromBoardDb,
+  touchBoardActive
+} from "./core/registry.js";
+import { scheduleAutomaticBoardBackup } from "./core/backups.js";
+import { provisionRepoBoard } from "./core/provision-repo-board.js";
+import { seedIfEmpty } from "./core/seed.js";
+import { now, normalizePath } from "./core/util.js";
 
 const SERVER_INFO = {
   name: "minimal-agent-board",
@@ -12,6 +53,133 @@ const SERVER_INFO = {
 };
 
 const orbitClient = await createOrbitClient();
+// Per-process session board. Set on init by walking up from cwd, mutable via
+// `board_set_active`. NEVER read by anything outside this file — every
+// downstream call receives an explicit ctx.
+let sessionBoardRow = null;
+
+function setSessionBoard(row) {
+  sessionBoardRow = row;
+  if (row) touchBoardActive(row.id);
+}
+
+function getSessionBoard() {
+  return sessionBoardRow;
+}
+
+/**
+ * Walk up from `startDir` toward the filesystem root, returning the first
+ * directory that satisfies `predicate`. Returns null if none found.
+ */
+function walkUp(startDir, predicate) {
+  let dir = startDir;
+  while (true) {
+    if (predicate(dir)) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Initialise the MCP session board. Resolution order:
+ *   1. Walk up from PROJECT_ROOT (cwd unless `orbit mcp --cwd` or env overrides it)
+ *      for an existing `.orbit/board.db` — finds the board even when the agent
+ *      is launched from a subdirectory or MCP config uses an absolute command.
+ *   2. Walk up from PROJECT_ROOT for a `.git/` directory — auto-creates a board at
+ *      the git root on first launch.
+ *   3. Fall back to PROJECT_ROOT itself — supports non-git projects and global installs.
+ */
+function initMcpSessionBoard() {
+  const start = normalizePath(process.env.PROJECT_ROOT ? resolve(process.env.PROJECT_ROOT) : process.cwd());
+
+  // 1. Prefer the registry row for PROJECT_ROOT (or one of its ancestors). New
+  // Orbit boards live in central DATA_DIR storage, so there may be no in-repo
+  // .orbit/board.db to discover.
+  const registeredRoot = walkUp(start, (dir) => Boolean(getBoardByRepoPath(normalizePath(dir))));
+  if (registeredRoot) {
+    setSessionBoard(getBoardByRepoPath(normalizePath(registeredRoot)));
+    return;
+  }
+
+  // 2. Walk up for an existing legacy board db.
+  const boardRoot = walkUp(start, (dir) => existsSync(join(dir, ".orbit", "board.db")));
+  if (boardRoot) {
+    const root = normalizePath(boardRoot);
+    const existing = getBoardByRepoPath(root);
+    if (existing) { setSessionBoard(existing); return; }
+    // db exists on disk but isn't in the registry yet — register it.
+    const dbPath = join(boardRoot, ".orbit", "board.db");
+    const db = openConnection(dbPath);
+    createBoardSchema(db);
+    const seeded = seedIfEmpty(db, root);
+    if (seeded) {
+      const t = now();
+      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 = getBoardByRepoPath(root);
+    if (fresh) { syncRegistryFromBoardDb(fresh, db); setSessionBoard(fresh); }
+    return;
+  }
+
+  // 3. Walk up for a git root; fall back to cwd for non-git projects.
+  const gitRoot = walkUp(start, (dir) => existsSync(join(dir, ".git")));
+  const result = provisionRepoBoard(normalizePath(gitRoot || start));
+  if (result.registryRow) setSessionBoard(result.registryRow);
+}
+
+function createBoardAtRoot(root) {
+  const dbPath = join(root, ".orbit", "board.db");
+  mkdirSync(dirname(dbPath), { recursive: true });
+  const db = openConnection(dbPath);
+  createBoardSchema(db);
+  const seeded = seedIfEmpty(db, root);
+  if (seeded) {
+    const t = now();
+    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 = getBoardByRepoPath(root);
+  if (fresh) { syncRegistryFromBoardDb(fresh, db); setSessionBoard(fresh); }
+}
+
+initMcpSessionBoard();
+closeAllConnections();
+
+/** Build a ctx for the session board (or a board the tool argument selected). */
+function ctxFor(boardRow, actor) {
+  if (!boardRow) throw rpcError(-32602, "No board in session; pass board_id or board_slug, or call board_set_active first.");
+  return { actor, board: boardRow, db: openBoardDb(boardRow) };
+}
+
+function sessionCtx(actor) {
+  return ctxFor(getSessionBoard(), actor);
+}
+
+function withAutomaticBackup(ctx, result) {
+  scheduleAutomaticBoardBackup(ctx.board, ctx.db);
+  return result;
+}
+
+/** Resolve a registry row from explicit args (no session fallback). */
+function resolveExplicitBoard(args) {
+  if (args.board_id) {
+    const row = getBoardByRegistryId(args.board_id);
+    if (!row) throw rpcError(-32004, "Board id not found.");
+    return row;
+  }
+  if (args.board_slug || args.board) {
+    const row = getBoardBySlug(args.board_slug || args.board);
+    if (!row) throw rpcError(-32004, "Board slug not found.");
+    return row;
+  }
+  return null;
+}
+
+/** Resolve a board for a tool that accepts board_id/board_slug AND can fall
+ *  back to the session board. */
+function resolveBoardOrSession(args) {
+  return resolveExplicitBoard(args) || getSessionBoard();
+}
 
 const TOOL_DEFS = [
   {
@@ -75,28 +243,56 @@ const TOOL_DEFS = [
   {
     name: "board_get_ticket_context",
     description:
-      "Read the full context pack for a ticket, including board agent_instructions (project-level agent context), relations, blockers, comments, and child cards. Heavy — prefer board_read_ticket when you only need title/description/comments.",
+      "Read the default agent context pack for a ticket, including board agent_instructions (project-level agent context), relations, blockers, implementation fields, and child cards. Ticket comments are intentionally omitted; use board_read_comments for explicit comment retrieval.",
     inputSchema: {
       type: "object",
       properties: {
         ticket_id: { type: "string" },
-        depth: { type: "integer", minimum: 1, maximum: 3 }
+        board_id: { type: "string" },
+        board_slug: { type: "string" },
+        board: { type: "string" },
+        depth: { type: "integer", minimum: 1, maximum: 3 },
+        max_chars_per_field: { type: "integer", minimum: 1 },
+        include_parent_full: { type: "boolean" },
+        include_related_full: { type: "boolean" }
       },
       required: ["ticket_id"],
       additionalProperties: false
     },
     handler: (args) => orbitClient.getTicketContext(args)
   },
+  {
+    name: "board_get_agent_dispatch_packet",
+    description:
+      "Return a lean agent dispatch packet for one ticket: board identity/instructions, capped ticket description/acceptance/AI plan, blockers, shallow parent, relevant workflow state IDs, repo path/default branch, recent capped comments, and label names. Parent/related/implementation bodies are intentionally omitted.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ticket_id: { type: "string" },
+        board_id: { type: "string" },
+        board_slug: { type: "string" },
+        board: { type: "string" },
+        max_chars_per_field: { type: "integer", minimum: 1 },
+        comment_limit: { type: "integer", minimum: 0, maximum: 20 }
+      },
+      required: ["ticket_id"],
+      additionalProperties: false
+    },
+    handler: (args) => orbitClient.getAgentDispatchPacket(args)
+  },
   {
     name: "board_read_ticket",
     description:
-      "Look up a ticket by ticket_id, number, or exact title (case-insensitive) on the session's active board, and return its title, description, labels, state, and full comment thread plus the board manual (agent_instructions + journal + deployment paths).",
+      "Look up a ticket by ticket_id, number, or exact title (case-insensitive) on the session's active board, and return its title, description, labels, state, and the board manual (agent_instructions + journal + deployment paths). Ticket comments are intentionally omitted; use board_read_comments for explicit comment retrieval.",
     inputSchema: {
       type: "object",
       properties: {
         ticket_id: { type: "string" },
         number: { type: "integer" },
-        title: { type: "string" }
+        title: { type: "string" },
+        board_id: { type: "string" },
+        board_slug: { type: "string" },
+        board: { type: "string" }
       },
       additionalProperties: false
     },
@@ -111,7 +307,10 @@ const TOOL_DEFS = [
       properties: {
         ticket_id: { type: "string" },
         number: { type: "integer" },
-        title: { type: "string" }
+        title: { type: "string" },
+        board_id: { type: "string" },
+        board_slug: { type: "string" },
+        board: { type: "string" }
       },
       additionalProperties: false
     },
@@ -123,7 +322,10 @@ const TOOL_DEFS = [
     inputSchema: {
       type: "object",
       properties: {
-        ticket_id: { type: "string" }
+        ticket_id: { type: "string" },
+        board_id: { type: "string" },
+        board_slug: { type: "string" },
+        board: { type: "string" }
       },
       required: ["ticket_id"],
       additionalProperties: false
@@ -136,7 +338,10 @@ const TOOL_DEFS = [
     inputSchema: {
       type: "object",
       properties: {
-        ticket_id: { type: "string" }
+        ticket_id: { type: "string" },
+        board_id: { type: "string" },
+        board_slug: { type: "string" },
+        board: { type: "string" }
       },
       required: ["ticket_id"],
       additionalProperties: false
@@ -154,7 +359,11 @@ const TOOL_DEFS = [
         board: { type: "string" },
         board_slug: { type: "string" },
         board_id: { type: "string" },
-        limit: { type: "integer", minimum: 1, maximum: 50 }
+        limit: { type: "integer", minimum: 1, maximum: 50 },
+        mode: { type: "string", enum: ["ids", "summary", "full"] },
+        include_full: { type: "boolean" },
+        fields: { type: "array", items: { type: "string" } },
+        max_chars_per_field: { type: "integer", minimum: 1 }
       },
       required: ["q"],
       additionalProperties: false
@@ -332,7 +541,9 @@ const TOOL_DEFS = [
       type: "object",
       properties: {
         board_id: { type: "string" },
-        board_slug: { type: "string" }
+        board_slug: { type: "string" },
+        include_attachments: { type: "boolean", description: "Embed attached image bytes in the JSON snapshot." },
+        include_images: { type: "boolean", description: "Alias for include_attachments." }
       },
       additionalProperties: false
     },
@@ -341,7 +552,7 @@ const TOOL_DEFS = [
   {
     name: "board_update_settings",
     description:
-      "PATCH-equivalent for board settings: name, repo_url, system_path, default_branch, agent_instructions (project-level agent context), and project_notes (Notes For You). Same fields as PATCH /api/boards/:id.",
+      "PATCH-equivalent for board settings: name (display rename only; slug/canonical URLs stay unchanged), repo_url, system_path, default_branch, agent_instructions (project-level agent context), and project_notes (Notes For You).",
     inputSchema: {
       type: "object",
       properties: {
@@ -364,13 +575,21 @@ const tools = new Map(TOOL_DEFS.map((tool) => [tool.name, tool]));
 
 let inputBuffer = Buffer.alloc(0);
 let expectedBodyLength = -1;
+let shuttingDown = false;
+
+function shutdown(code = 0) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  orbitClient.close?.();
+  process.exit(code);
+}
 
 process.stdin.on("data", (chunk) => {
   inputBuffer = Buffer.concat([inputBuffer, chunk]);
   drainInput();
 });
 
-process.stdin.on("end", () => process.exit(0));
+process.stdin.on("end", () => shutdown(0));
 process.stdin.resume();
 
 function drainInput() {
@@ -449,6 +668,8 @@ async function handleMessage(body, transport = "content-length") {
     }, transport);
   } catch (error) {
     writeMessage(errorResponse(message.id, error.code || -32000, error.message || "Internal error."), transport);
+  } finally {
+    orbitClient.close?.();
   }
 }
 
@@ -544,6 +765,11 @@ process.on("unhandledRejection", (error) => {
   writeMessage(errorResponse(null, -32000, error?.message || "Unhandled rejection."));
 });
 
+process.once("SIGINT", () => shutdown(0));
+process.once("SIGTERM", () => shutdown(0));
+process.once("exit", () => orbitClient.close?.());
+
 if (process.env.MAB_MCP_STDERR_LOG === "1") {
-  console.error(`Starscape Orbit MCP ready. Mode: ${orbitClient.mode}. Target: ${typeof orbitClient.sessionLabel === "function" ? orbitClient.sessionLabel() : orbitClient.sessionLabel}`);
+  const target = typeof orbitClient.sessionLabel === "function" ? orbitClient.sessionLabel() : orbitClient.sessionLabel;
+  console.error(`Starscape Orbit MCP ready. Mode: ${orbitClient.mode}. Target: ${target}`);
 }

package/src/server.js

@@ -8,6 +8,7 @@ import {
   startSSEStream,
   startupSummary
 } from "./core/board.js";
+import { closeAllConnections } from "./core/db.js";
 
 const server = createServer(async (req, res) => {
   try {
@@ -46,3 +47,22 @@ server.listen(boardRuntime.port, () => {
   console.log(`Boards (${summary.boardCount}):`);
   for (const path of summary.boardPaths) console.log(`  - ${path}`);
 });
+
+let shuttingDown = false;
+
+function shutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  server.close(() => {
+    closeAllConnections();
+    process.exit(0);
+  });
+  setTimeout(() => {
+    closeAllConnections();
+    process.exit(0);
+  }, 1500).unref();
+}
+
+process.once("SIGINT", shutdown);
+process.once("SIGTERM", shutdown);
+process.once("exit", () => closeAllConnections());