@starlove/orbit 1.0.7 → 1.1.0

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

@@ -112,9 +112,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 +125,6 @@ export function readTicket(lookup, ctx) {
       priority: ticket.priority,
       labels
     },
-    comments,
     board_manual: boardManual(innerBoard.id, ctx)
   };
 }
@@ -220,7 +216,6 @@ export function getContextPack(ticketId, ctx, depth = 1) {
   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,16 +231,6 @@ 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: {
@@ -254,7 +239,6 @@ export function getContextPack(ticketId, ctx, depth = 1) {
     },
     board: innerBoard,
     board_manual: boardManual(innerBoard.id, ctx),
-    comments,
     parent_ticket: parentTicket ? compactTicket(parentTicket) : null,
     child_tickets: childTickets.map((child) => ({
       ...child,
@@ -262,7 +246,6 @@ export function getContextPack(ticketId, ctx, depth = 1) {
     })),
     relations,
     blockers,
-    related_tickets: relatedTickets,
-    related_comments: relatedCommentRows
+    related_tickets: relatedTickets
   };
 }

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;
   }