@starlove/orbit 1.0.7 → 1.1.1

package/src/cli/orbit.js

@@ -1,36 +1,55 @@
 #!/usr/bin/env node
 /**
  * Orbit CLI — `orbit init` provisions `.orbit/board.db`, registry row, and
- * copies SKILL-ORBIT.md into the target repo. Does not import board.js.
+ * copies managed SKILL-ORBIT.md into the target repo. Does not import board.js.
  */
 
 import { spawnSync } from "node:child_process";
-import { copyFileSync, existsSync, mkdirSync, rmSync, unlinkSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, rmSync, unlinkSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { removeOrbitAgentsSection, syncAgentsMd } from "../core/agents-md.js";
+import { removeOrbitAgentsSection, syncAgentsMd, syncSkillOrbitMd } from "../core/agents-md.js";
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 
 function printUsage() {
   console.log(`Usage:
+  orbit -v, --version      Print the Orbit CLI version
   orbit init  [options]    Provision .orbit/board.db + SKILL-ORBIT.md + AGENTS.md
   orbit reset [options]    Delete .orbit/ + SKILL-ORBIT.md + registry row
   orbit serve [options]    Start the Orbit web app + HTTP API
   orbit docker [options]   Build/run Orbit's web app in Docker
   orbit mcp   [options]    Start the stdio MCP server (for agent clients)
+  orbit dispatch [options] Dispatch a Hermes profile on a ticket
 
-Options (init / reset / serve / docker / mcp):
+Options (init / reset / serve / docker / mcp / dispatch):
   --cwd <dir>           Project root (default: process.cwd())
 
 Options (init only):
   --no-ai               Create the board with AI collaboration disabled
   --example             Create example onboarding tickets
-  --refresh-agents-md   Overwrite SKILL-ORBIT.md and refresh Orbit section in AGENTS.md
 
 Options (serve / docker):
   --port <n>            HTTP port (default: 3337, or $PORT)
 
+Options (dispatch):
+  --board <slug-or-id>  Local board to dispatch against (default: board for --cwd)
+  --ticket <number-id>  Ticket number or id to dispatch
+  --profile <name>      Hermes profile to run (default: agent)
+  --policy <name>       Autonomous policy wrappers to apply (default: agent-safe; use none to disable)
+  --server-url <url>    Refused for now; dispatch is local-board only
+  --remote              Refused for now; use remote MCP/manual orchestration for hosted boards
+  --worktree            Create and preserve a git worktree for review/testing
+  --worktree-path <dir> Worktree path when --worktree is used
+  --branch <name>       Branch name for the preserved worktree
+  --hermes-bin <cmd>    Hermes executable (default: hermes)
+  --no-spawn            Prepare card/worktree/run record but do not start Hermes or move In Progress
+  --no-yolo             Do not pass --yolo to Hermes (default dispatch passes --yolo)
+  --foreground          Attach spawned Hermes process to this terminal
+  --keep-handoff-file   Keep duplicate handoff file under DATA_DIR/dispatch-runs/<board>
+  --force               Dispatch even when blockers exist
+  --dry-run             Preview only; no files, worktrees, ticket fields, comments, or agents change
+
 Options (docker only):
   --image <name>        Docker image tag (default: starscape-orbit:local)
   --data-dir <dir>      Docker registry/export data dir (default: <cwd>/.orbit/docker-data)
@@ -41,6 +60,11 @@ Options (docker only):
   --dry-run             Print docker commands without running them`);
 }
 
+function printVersion() {
+  const packageJson = JSON.parse(readFileSync(resolve(PACKAGE_ROOT, "package.json"), "utf8"));
+  console.log(packageJson.version);
+}
+
 function shellQuote(value) {
   return `"${String(value || "").replace(/"/g, '\\"')}"`;
 }
@@ -59,7 +83,7 @@ async function loadCliCore() {
   const [
     { disableAiCollaboration, enableAiCollaboration },
     { backupBoardDatabase, backupRegistry },
-    { createRegistrySchema, openConnection },
+    { closeConnection, createRegistrySchema, openConnection },
     { DATA_DIR, ROOT_DIR },
     { provisionRepoBoard },
     { deleteBoard, getBoardByRepoPath },
@@ -79,6 +103,7 @@ async function loadCliCore() {
     ROOT_DIR,
     backupBoardDatabase,
     backupRegistry,
+    closeConnection,
     createRegistrySchema,
     deleteBoard,
     disableAiCollaboration,
@@ -107,12 +132,36 @@ function disableAiIfRequested(options, registryRow, core) {
   console.log("AI collaboration disabled for this board.");
 }
 
+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 resetBusyError(error, projectRoot) {
+  if (!isBusyFilesystemError(error)) return error;
+  const message = [
+    `Orbit could not remove local board files under ${projectRoot}.`,
+    "",
+    "On Windows this usually means an Orbit web server, MCP helper, editor, or terminal still has .orbit/board.db open.",
+    "Close Orbit server terminals and restart any AI client with Orbit MCP enabled, then rerun:",
+    `  orbit reset --cwd ${shellQuote(projectRoot)}`,
+    "",
+    `Original error: ${error.message}`
+  ].join("\n");
+  const wrapped = new Error(message);
+  wrapped.code = error.code;
+  wrapped.cause = error;
+  return wrapped;
+}
+
 function parseArgs(argv) {
   const args = {
     command: null,
     cwd: process.env.PROJECT_ROOT ? resolve(process.env.PROJECT_ROOT) : process.cwd(),
     cwdProvided: false,
-    refreshAgentsMd: false,
     ai: true,
     example: false,
     port: null,
@@ -121,18 +170,43 @@ function parseArgs(argv) {
     containerName: null,
     buildImage: true,
     detach: true,
-    dryRun: false
+    dryRun: false,
+    board: null,
+    ticket: null,
+    profile: "agent",
+    policy: "agent-safe",
+    serverUrl: null,
+    worktree: false,
+    worktreePath: null,
+    branch: null,
+    hermesBin: "hermes",
+    noSpawn: false,
+    yolo: true,
+    keepHandoffFile: false,
+    force: false,
+    foreground: false,
+    remote: false,
+    help: false,
+    invalid: false
   };
   const rest = argv.slice(2);
   if (rest.length === 0 || rest[0] === "-h" || rest[0] === "--help") {
     args.command = "help";
     return args;
   }
+  if (rest[0] === "-v" || rest[0] === "--version") {
+    args.command = "version";
+    return args;
+  }
+  if (rest[0] === "dispatch" && (rest[1] === "-h" || rest[1] === "--help")) {
+    args.command = "dispatch";
+    args.help = true;
+    return args;
+  }
   args.command = rest[0];
   for (let i = 1; i < rest.length; i++) {
     const a = rest[i];
-    if (a === "--refresh-agents-md") args.refreshAgentsMd = true;
-    else if (a === "--no-ai") args.ai = false;
+    if (a === "--no-ai") args.ai = false;
     else if (a === "--example") args.example = true;
     else if (a === "--cwd" && rest[i + 1]) {
       args.cwdProvided = true;
@@ -144,6 +218,52 @@ function parseArgs(argv) {
       args.port = rest[++i];
     } else if (a.startsWith("--port=")) {
       args.port = a.slice("--port=".length);
+    } else if (a === "--board" && rest[i + 1]) {
+      args.board = rest[++i];
+    } else if (a.startsWith("--board=")) {
+      args.board = a.slice("--board=".length);
+    } else if (a === "--ticket" && rest[i + 1]) {
+      args.ticket = rest[++i];
+    } else if (a.startsWith("--ticket=")) {
+      args.ticket = a.slice("--ticket=".length);
+    } else if (a === "--profile" && rest[i + 1]) {
+      args.profile = rest[++i];
+    } else if (a.startsWith("--profile=")) {
+      args.profile = a.slice("--profile=".length);
+    } else if (a === "--policy" && rest[i + 1]) {
+      args.policy = rest[++i];
+    } else if (a.startsWith("--policy=")) {
+      args.policy = a.slice("--policy=".length);
+    } else if (a === "--server-url" && rest[i + 1]) {
+      args.serverUrl = rest[++i];
+    } else if (a.startsWith("--server-url=")) {
+      args.serverUrl = a.slice("--server-url=".length);
+    } else if (a === "--remote") {
+      args.remote = true;
+    } else if (a === "--worktree") {
+      args.worktree = true;
+    } else if (a === "--worktree-path" && rest[i + 1]) {
+      args.worktreePath = resolve(rest[++i]);
+    } else if (a.startsWith("--worktree-path=")) {
+      args.worktreePath = resolve(a.slice("--worktree-path=".length));
+    } else if (a === "--branch" && rest[i + 1]) {
+      args.branch = rest[++i];
+    } else if (a.startsWith("--branch=")) {
+      args.branch = a.slice("--branch=".length);
+    } else if (a === "--hermes-bin" && rest[i + 1]) {
+      args.hermesBin = rest[++i];
+    } else if (a.startsWith("--hermes-bin=")) {
+      args.hermesBin = a.slice("--hermes-bin=".length);
+    } else if (a === "--no-spawn") {
+      args.noSpawn = true;
+    } else if (a === "--no-yolo") {
+      args.yolo = false;
+    } else if (a === "--yolo") {
+      args.yolo = true;
+    } else if (a === "--keep-handoff-file") {
+      args.keepHandoffFile = true;
+    } else if (a === "--force") {
+      args.force = true;
     } else if (a === "--image" && rest[i + 1]) {
       args.image = rest[++i];
     } else if (a.startsWith("--image=")) {
@@ -162,11 +282,13 @@ function parseArgs(argv) {
       args.detach = true;
     } else if (a === "--foreground") {
       args.detach = false;
+      args.foreground = true;
     } else if (a === "--dry-run") {
       args.dryRun = true;
     } else {
       console.error(`Unknown argument: ${a}`);
       args.command = "help";
+      args.invalid = true;
       return args;
     }
   }
@@ -187,15 +309,13 @@ async function runInit(options) {
   if (!existsSync(skillSrc)) {
     console.warn(`Warning: missing ${skillSrc} — skipped copying SKILL-ORBIT.md and AGENTS.md Orbit section.`);
   } else {
-    if (skillSrc === skillDest) {
+    const skillSync = syncSkillOrbitMd(projectRoot, skillSrc);
+    if (skillSync.status === "same_file") {
       console.log("SKILL-ORBIT.md source is already the project copy — left unchanged.");
-    } else if (existsSync(skillDest) && !options.refreshAgentsMd) {
-      console.log(`SKILL-ORBIT.md already exists — left unchanged (use --refresh-agents-md to replace).`);
     } else {
-      copyFileSync(skillSrc, skillDest);
       console.log(`Wrote ${skillDest}`);
     }
-    syncAgentsMd(projectRoot, options);
+    syncAgentsMd(projectRoot);
   }
 
   enableAiIfEnabled(options, result.registryRow, core);
@@ -204,7 +324,7 @@ async function runInit(options) {
   if (result.message && result.status === "skipped") {
     console.log(result.message);
   } else if (result.status === "created") {
-    console.log(`Initialized Orbit board at ${resolve(projectRoot, ".orbit", "board.db")}`);
+    console.log(`Initialized Orbit board at ${result.registryRow?.db_path ?? "(unknown path)"}`);
   } else if (result.status === "repaired") {
     console.log(result.message || "Linked existing board database to the registry.");
   }
@@ -231,6 +351,7 @@ async function runReset(options) {
     DATA_DIR,
     backupBoardDatabase,
     backupRegistry,
+    closeConnection,
     createRegistrySchema,
     deleteBoard,
     getBoardByRepoPath,
@@ -247,23 +368,53 @@ async function runReset(options) {
   const registryRow = getBoardByRepoPath(projectRoot);
 
   if (registryRow && existsSync(registryRow.db_path)) {
-    backupBoardDatabase(registryRow, openConnection(registryRow.db_path), "pre-cli-reset");
+    const db = openConnection(registryRow.db_path);
+    try {
+      backupBoardDatabase(registryRow, db, "pre-cli-reset");
+    } catch (error) {
+      throw resetBusyError(error, projectRoot);
+    } finally {
+      closeConnection(registryRow.db_path);
+    }
   }
   if (registryRow) backupRegistry("pre-cli-reset");
 
-  if (existsSync(orbitDir)) {
-    rmSync(orbitDir, { recursive: true, force: true });
-    removed.push(orbitDir);
-  }
-  if (existsSync(skillMd)) {
-    unlinkSync(skillMd);
-    removed.push(skillMd);
-  }
-  const agentsCleanup = removeOrbitAgentsSection(projectRoot);
-  if (agentsCleanup.removed) {
-    removed.push(`${agentsCleanup.path} Orbit section`);
-  } else if (!agentsCleanup.ok) {
-    console.warn(`Warning: skipped AGENTS.md cleanup (${agentsCleanup.reason}) in ${agentsCleanup.path}`);
+  try {
+    // Remove the board database. With central storage the db lives outside the
+    // project directory; with legacy in-repo storage it is inside orbitDir below.
+    const isCentralDb = registryRow && !registryRow.db_path.startsWith(projectRoot + "/");
+    if (isCentralDb && existsSync(registryRow.db_path)) {
+      const boardDir = dirname(registryRow.db_path);
+      rmSync(boardDir, { recursive: true, force: true });
+      removed.push(boardDir);
+    }
+
+    // Remove central dispatch-runs for this board.
+    if (registryRow) {
+      const dispatchRunsDir = join(DATA_DIR, "dispatch-runs", registryRow.slug);
+      if (existsSync(dispatchRunsDir)) {
+        rmSync(dispatchRunsDir, { recursive: true, force: true });
+        removed.push(dispatchRunsDir);
+      }
+    }
+
+    // Remove the in-repo .orbit/ directory (covers legacy db, residual dispatch-runs, etc.).
+    if (existsSync(orbitDir)) {
+      rmSync(orbitDir, { recursive: true, force: true });
+      removed.push(orbitDir);
+    }
+    if (existsSync(skillMd)) {
+      unlinkSync(skillMd);
+      removed.push(skillMd);
+    }
+    const agentsCleanup = removeOrbitAgentsSection(projectRoot);
+    if (agentsCleanup.removed) {
+      removed.push(`${agentsCleanup.path} Orbit section`);
+    } else if (!agentsCleanup.ok) {
+      console.warn(`Warning: skipped AGENTS.md cleanup (${agentsCleanup.reason}) in ${agentsCleanup.path}`);
+    }
+  } catch (error) {
+    throw resetBusyError(error, projectRoot);
   }
 
   if (registryRow) {
@@ -284,6 +435,7 @@ async function runServe(options) {
   // captures it at module load. cwd defaults are equivalent for most users, but
   // an explicit --cwd lets a global install target a board outside cwd.
   process.env.PROJECT_ROOT = resolve(options.cwd);
+  process.env.ORBIT_SYNC_MANAGED_SKILL_ORBIT = "1";
   if (options.port) process.env.PORT = String(options.port);
   await import("../server.js");
 }
@@ -385,6 +537,35 @@ async function runMcp(options) {
   await import("../mcp-server.js");
 }
 
+async function runDispatch(options) {
+  if (options.help) {
+    printUsage();
+    return;
+  }
+  process.env.PROJECT_ROOT = resolve(options.cwd);
+  const { dispatchTicket } = await import("../core/dispatch.js");
+  const result = dispatchTicket(options);
+  if (result.dry_run) {
+    console.log(`Dry run: would dispatch ticket #${result.ticket.number} ${result.ticket.title}`);
+    console.log(`Board: ${result.board.slug}`);
+    console.log(`Profile: ${result.profile}`);
+    console.log(`Mode: ${result.no_spawn ? "prepare-only" : "spawn"}`);
+    console.log("No files, worktrees, ticket fields, comments, or agents were changed.");
+    return;
+  }
+  console.log(`Dispatch ${result.spawned ? "started" : "prepared"}: ${result.run_id}`);
+  console.log(`Board: ${result.board.slug}`);
+  console.log(`Ticket: #${result.ticket.number} ${result.ticket.title}`);
+  console.log(`Profile: ${result.profile}`);
+  console.log(`Policy: ${result.policy}`);
+  console.log(`Worktree: ${result.worktree_path}`);
+  if (result.branch) console.log(`Branch: ${result.branch}`);
+  if (result.pid) console.log(`PID: ${result.pid}`);
+  console.log("AI Written-Plan updated with the generated handoff.");
+  console.log("Run record comment added to the ticket.");
+  if (result.no_spawn) console.log("No agent spawned; ticket state left unchanged.");
+}
+
 async function main() {
   const args = parseArgs(process.argv);
   try {
@@ -398,9 +579,13 @@ async function main() {
       await runDocker(args);
     } else if (args.command === "mcp") {
       await runMcp(args);
+    } else if (args.command === "dispatch") {
+      await runDispatch(args);
+    } else if (args.command === "version") {
+      printVersion();
     } else {
       printUsage();
-      process.exitCode = args.command === "help" ? 0 : 1;
+      process.exitCode = args.command === "help" && !args.invalid ? 0 : 1;
     }
   } catch (err) {
     console.error(err?.message || err);

package/src/core/agent.js

@@ -7,6 +7,7 @@ import {
   relationRows,
   stateByName,
   stateByRole,
+  stateById,
   ticketById,
   ticketByNumber,
   ticketByTitle,
@@ -112,9 +113,6 @@ export function readTicket(lookup, ctx) {
   const innerBoard = boardById(db, ticket.board_id);
   requireBoardAccess(actor, innerBoard);
 
-  const comments = db
-    .prepare("SELECT * FROM comments WHERE ticket_id = ? ORDER BY created_at ASC")
-    .all(ticket.id);
   const labels = labelsForTicket(db, ticket.id);
 
   return {
@@ -128,7 +126,6 @@ export function readTicket(lookup, ctx) {
       priority: ticket.priority,
       labels
     },
-    comments,
     board_manual: boardManual(innerBoard.id, ctx)
   };
 }
@@ -213,14 +210,16 @@ export function completeTicket(body, ctx) {
   return getContextPack(ticket.id, ctx, 1);
 }
 
-export function getContextPack(ticketId, ctx, depth = 1) {
+export function getContextPack(ticketId, ctx, depth = 1, options = {}) {
   const { db, board, actor } = ctx;
+  const maxCharsPerField = positiveInt(options.max_chars_per_field ?? options.maxCharsPerField, 0);
+  const includeParentFull = Boolean(options.include_parent_full ?? options.includeParentFull);
+  const includeRelatedFull = Boolean(options.include_related_full ?? options.includeRelatedFull);
   const ticket = ticketById(db, ticketId);
   if (!ticket || ticket.board_id !== board.id) throw httpError(404, "ticket_not_found");
   const innerBoard = boardById(db, ticket.board_id);
   requireBoardAccess(actor, innerBoard);
 
-  const comments = db.prepare("SELECT * FROM comments WHERE ticket_id = ? ORDER BY created_at ASC").all(ticketId);
   const labels = labelsForTicket(db, ticketId);
   const relations = relationRows(db, ticketId);
   const blockers = unresolvedBlockers(db, ticketId);
@@ -236,33 +235,124 @@ export function getContextPack(ticketId, ctx, depth = 1) {
     ...childTickets,
     ...(parentTicket ? [parentTicket] : [])
   ]);
-  const relatedCommentRows =
-    depth > 0
-      ? relatedTickets.flatMap((related) =>
-          db
-            .prepare("SELECT * FROM comments WHERE ticket_id = ? ORDER BY created_at DESC LIMIT 5")
-            .all(related.id)
-            .reverse()
-            .map((comment) => ({ ...comment, ticket_id: related.id, ticket_title: related.title }))
-        )
-      : [];
 
   return {
-    ticket: {
+    ticket: capTicketFields({
       ...ticket,
       labels
-    },
+    }, maxCharsPerField),
     board: innerBoard,
     board_manual: boardManual(innerBoard.id, ctx),
-    comments,
-    parent_ticket: parentTicket ? compactTicket(parentTicket) : null,
+    parent_ticket: parentTicket ? (includeParentFull ? capTicketFields({ ...parentTicket, labels: labelsForTicket(db, parentTicket.id) }, maxCharsPerField) : compactTicket(parentTicket)) : null,
     child_tickets: childTickets.map((child) => ({
-      ...child,
+      ...capTicketFields(child, maxCharsPerField),
       child_count: childTicketsFor(db, child.id).length
     })),
-    relations,
+    relations: relations.map((relation) => ({
+      ...relation,
+      other_ticket: includeRelatedFull
+        ? capTicketFields({ ...relation.other_ticket, labels: labelsForTicket(db, relation.other_ticket.id) }, maxCharsPerField)
+        : compactTicket(relation.other_ticket)
+    })),
     blockers,
-    related_tickets: relatedTickets,
-    related_comments: relatedCommentRows
+    related_tickets: relatedTickets.map((related) =>
+      includeRelatedFull ? capTicketFields({ ...related, labels: labelsForTicket(db, related.id) }, maxCharsPerField) : compactTicket(related)
+    )
+  };
+}
+
+export function getAgentDispatchPacket(ticketId, ctx, options = {}) {
+  const { db, board, actor } = ctx;
+  const maxCharsPerField = positiveInt(options.max_chars_per_field ?? options.maxCharsPerField, 4000);
+  const commentLimit = Math.min(nonNegativeInt(options.comment_limit ?? options.commentLimit, 5), 20);
+  const ticket = ticketById(db, ticketId);
+  if (!ticket || ticket.board_id !== board.id) throw httpError(404, "ticket_not_found");
+  const innerBoard = boardById(db, ticket.board_id);
+  requireBoardAccess(actor, innerBoard);
+
+  const labels = labelsForTicket(db, ticket.id).map((label) => label.name);
+  const parentTicket = ticket.parent_ticket_id ? ticketById(db, ticket.parent_ticket_id) : null;
+  const blockers = unresolvedBlockers(db, ticket.id).map(compactTicket);
+  const comments = db
+    .prepare("SELECT id, author, kind, body, created_at FROM comments WHERE ticket_id = ? ORDER BY created_at DESC LIMIT ?")
+    .all(ticket.id, commentLimit)
+    .reverse()
+    .map((comment) => ({ ...comment, body: capString(comment.body, maxCharsPerField) }));
+
+  return {
+    board: {
+      id: innerBoard.id,
+      slug: innerBoard.slug,
+      name: innerBoard.name,
+      repo_path: innerBoard.repo_path || innerBoard.system_path || "",
+      system_path: innerBoard.system_path || innerBoard.repo_path || "",
+      default_branch: innerBoard.default_branch || "main",
+      agent_instructions: capString(innerBoard.agent_instructions || "", maxCharsPerField)
+    },
+    ticket: {
+      id: ticket.id,
+      ticket_id: ticket.id,
+      number: ticket.number,
+      title: ticket.title,
+      type: ticket.type,
+      priority: ticket.priority,
+      state_id: ticket.state_id,
+      state_name: ticket.state_name,
+      state_role: ticket.state_role,
+      description: capString(ticket.description || "", maxCharsPerField),
+      acceptance: capString(extractAcceptance(ticket.description || ""), maxCharsPerField),
+      ai_plan: capString(ticket.ai_plan || "", maxCharsPerField),
+      labels
+    },
+    blockers: {
+      can_start: blockers.length === 0,
+      blockers
+    },
+    parent_ticket: parentTicket ? compactTicket(parentTicket) : null,
+    relevant_state_ids: relevantStateIds(db, innerBoard.id, ticket.state_id),
+    recent_comments: comments
+  };
+}
+
+function positiveInt(value, fallback) {
+  const n = Number(value);
+  return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+
+function nonNegativeInt(value, fallback) {
+  const n = Number(value);
+  return Number.isInteger(n) && n >= 0 ? n : fallback;
+}
+
+function capString(value, maxChars) {
+  const text = String(value || "");
+  return maxChars && text.length > maxChars ? text.slice(0, maxChars) : text;
+}
+
+function capTicketFields(ticket, maxChars) {
+  if (!maxChars) return ticket;
+  const copy = { ...ticket };
+  for (const field of ["description", "ai_plan", "implementation_summary", "implementation_updates"]) {
+    if (Object.hasOwn(copy, field)) copy[field] = capString(copy[field], maxChars);
+  }
+  return copy;
+}
+
+function extractAcceptance(description) {
+  const match = String(description || "").match(/(?:^|\n)\s*(?:acceptance criteria|acceptance)\s*:?\s*\n([\s\S]*)/i);
+  return match ? match[1].trim() : "";
+}
+
+function relevantStateIds(db, boardId, currentStateId) {
+  const byRole = (role) => stateByRole(db, boardId, role)?.id || null;
+  const byName = (name) => stateByName(db, boardId, name)?.id || null;
+  return {
+    current: currentStateId,
+    current_role: stateById(db, currentStateId)?.role || null,
+    ai_ready: byRole("ai_ready") || byName("AI Ready"),
+    in_progress: byRole("in_progress") || byName("In Progress"),
+    review: byRole("review") || byName("Review"),
+    done: byRole("done") || byName("Done"),
+    todo: byRole("todo") || byName("Todo")
   };
 }

package/src/core/agents-md.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 
 export const ORBIT_AGENTS_START = "<!-- ORBIT:AGENTS-START -->";
@@ -21,7 +21,19 @@ export function buildAgentsMd() {
 ${orbitAgentsSection()}`;
 }
 
-export function syncAgentsMd(projectRoot, options = {}, logger = console.log) {
+export function syncSkillOrbitMd(projectRoot, skillSrc) {
+  const skillDest = resolve(projectRoot, "SKILL-ORBIT.md");
+  if (!existsSync(skillSrc)) {
+    return { ok: false, status: "missing_source", source: skillSrc, path: skillDest };
+  }
+  if (resolve(skillSrc) === skillDest) {
+    return { ok: true, status: "same_file", source: skillSrc, path: skillDest };
+  }
+  copyFileSync(skillSrc, skillDest);
+  return { ok: true, status: "written", source: skillSrc, path: skillDest };
+}
+
+export function syncAgentsMd(projectRoot, _options = {}, logger = console.log) {
   const agentsPath = resolve(projectRoot, "AGENTS.md");
   const section = orbitAgentsSection();
 
@@ -36,14 +48,7 @@ export function syncAgentsMd(projectRoot, options = {}, logger = console.log) {
   const endIndex = current.indexOf(ORBIT_AGENTS_END);
 
   if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
-    if (!options.refreshAgentsMd) {
-      logger("AGENTS.md already includes Orbit instructions — left unchanged (use --refresh-agents-md to replace).");
-      return;
-    }
-    const before = current.slice(0, startIndex).replace(/\s*$/, "\n\n");
-    const after = current.slice(endIndex + ORBIT_AGENTS_END.length).replace(/^\s*/, "");
-    writeFileSync(agentsPath, `${before}${section}${after}`, "utf8");
-    logger(`Refreshed Orbit instructions inside ${agentsPath}`);
+    logger("AGENTS.md already includes Orbit instructions — left unchanged.");
     return;
   }