@starlove/orbit 1.3.5 → 1.4.1

package/src/cli/orbit.js

@@ -41,8 +41,8 @@ Options (dispatch):
   --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
+  --server-url <url>    Hosted Orbit base URL for remote dispatch
+  --remote              Force hosted/remote dispatch mode
   --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
@@ -186,6 +186,7 @@ function parseArgs(argv) {
     dryRun: false,
     board: null,
     ticket: null,
+    ticketUrl: null,
     profile: "agent",
     policy: "agent-safe",
     serverUrl: null,
@@ -312,6 +313,9 @@ function parseArgs(argv) {
       args.foreground = true;
     } else if (a === "--dry-run") {
       args.dryRun = true;
+    } else if (args.command === "dispatch" && /^https?:\/\//i.test(a) && !args.ticketUrl) {
+      args.ticketUrl = a;
+      args.remote = true;
     } else {
       console.error(`Unknown argument: ${a}`);
       args.command = "help";
@@ -601,8 +605,8 @@ async function runDispatch(options) {
     return;
   }
   process.env.PROJECT_ROOT = resolve(options.cwd);
-  const { dispatchTicket } = await import("../core/dispatch.js");
-  const result = dispatchTicket(options);
+  const { dispatchTicketAsync } = await import("../core/dispatch.js");
+  const result = await dispatchTicketAsync(options);
   if (result.dry_run) {
     console.log(`Dry run: would dispatch ticket #${result.ticket.number} ${result.ticket.title}`);
     console.log(`Board: ${result.board.slug}`);
@@ -620,7 +624,7 @@ async function runDispatch(options) {
   if (result.branch) console.log(`Branch: ${result.branch}`);
   if (result.run_record_path) console.log(`Run record: ${result.run_record_path}`);
   if (result.pid) console.log(`PID: ${result.pid}`);
-  console.log("AI Written-Plan updated with the generated handoff.");
+  console.log("AI Plan updated with a terse summary and linked handoff artifact.");
   console.log("Run record comment added to the ticket.");
   if (result.no_spawn) console.log("No agent spawned; ticket state left unchanged.");
 }

package/src/core/agent.js

@@ -190,12 +190,16 @@ export function completeTicket(body, ctx) {
   const lines = [summary];
   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;
+  const implementationArtifactPath = body.implementation_artifact_path || body.summary_artifact_path || ticket.implementation_artifact_path || "";
   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, time, ticket.id);
+      `UPDATE tickets
+       SET state_id = ?, implementation_summary = ?,
+           implementation_artifact_path = ?, implementation_updates = ?, updated_at = ?
+       WHERE id = ?`
+    ).run(nextState.id, summary, implementationArtifactPath, updates, time, ticket.id);
     recordEvent(db, ticket.board_id, "agent_completed", ticket.id, actor.name, {
       from: ticket.state_name,
       next_state: nextState.name,
@@ -252,7 +256,7 @@ function buildContextPack(ticketId, ctx, depth = 1, options = {}, { includeProje
       ...ticket,
       labels
     }, maxCharsPerField),
-    board: includeProjectContext ? innerBoard : contextBoardIdentity(innerBoard, ctx),
+    board: contextBoardIdentity(innerBoard, ctx),
     parent_ticket: parentTicket ? (includeParentFull ? capTicketFields({ ...parentTicket, labels: labelsForTicket(db, parentTicket.id) }, maxCharsPerField) : compactTicket(parentTicket)) : null,
     child_tickets: childTickets.map((child) => ({
       ...capTicketFields(child, maxCharsPerField),
@@ -295,7 +299,7 @@ export function getAgentDispatchPacket(ticketId, ctx, options = {}) {
   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 ?")
+    .prepare("SELECT id, author, kind, body, created_at FROM comments WHERE ticket_id = ? AND COALESCE(omitted_for_ai, 0) = 0 ORDER BY created_at DESC LIMIT ?")
     .all(ticket.id, commentLimit)
     .reverse()
     .map((comment) => ({ ...comment, body: capString(comment.body, maxCharsPerField) }));
@@ -323,6 +327,10 @@ export function getAgentDispatchPacket(ticketId, ctx, options = {}) {
       description: capString(ticket.description || "", maxCharsPerField),
       acceptance: capString(extractAcceptance(ticket.description || ""), maxCharsPerField),
       ai_plan: capString(ticket.ai_plan || "", maxCharsPerField),
+      plan_artifact_path: ticket.plan_artifact_path || "",
+      implementation_summary: capString(ticket.implementation_summary || "", maxCharsPerField),
+      implementation_artifact_path: ticket.implementation_artifact_path || "",
+      implementation_updates: capString(ticket.implementation_updates || "", maxCharsPerField),
       labels
     },
     blockers: {

package/src/core/agents-md.js

@@ -1,8 +1,8 @@
 import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 
-export const ORBIT_AGENTS_START = "<!-- ORBIT:AGENTS-START -->";
-export const ORBIT_AGENTS_END = "<!-- ORBIT:AGENTS-END -->";
+export const ORBIT_AGENTS_START = "<!--ORBIT-->";
+export const ORBIT_AGENTS_END = "<!--/ORBIT-->";
 export const ORBIT_AGENTS_CANONICAL_LINE =
   "Git is canonical for code. `SKILL-ORBIT.md` is canonical for Orbit/kanban/ticket/card workflow.";
 
@@ -10,7 +10,7 @@ export function orbitAgentsSection() {
   return `${ORBIT_AGENTS_START}
 ${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.
+For Orbit, kanban, board, lane, ticket, card, epic, blocker, claim, AI Ready, implementation fields, planning state, project memory, or handoff work: read \`SKILL-ORBIT.md\` first.
 Use Orbit API/MCP tools for tickets/cards; do not edit .orbit/board.db directly.
 ${ORBIT_AGENTS_END}\n`;
 }

package/src/core/artifacts.js

@@ -0,0 +1,149 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, normalize, relative, sep } from "node:path";
+import { boardById, ticketById } from "./queries.js";
+import { requireBoardAccess } from "./auth.js";
+import { DISPATCH_RUNS_DIR } from "./paths.js";
+import { httpError } from "./util.js";
+
+const MAX_MARKDOWN_ARTIFACT_BYTES = 512 * 1024;
+const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown", ".txt"]);
+
+function cleanPath(value) {
+  const text = String(value || "").trim();
+  if (!text || text.includes("\0")) throw httpError(400, "artifact_path_required");
+  return text.replace(/\\/g, "/");
+}
+
+function ensureInside(path, root) {
+  if (!root) return false;
+  const normalizedRoot = normalize(root + sep);
+  const normalizedPath = normalize(path);
+  return normalizedPath === normalize(root) || normalizedPath.startsWith(normalizedRoot);
+}
+
+function pathAliases(path) {
+  const aliases = new Set([path]);
+  const mntDrive = path.match(/^\/mnt\/([a-z])\/(.+)$/i);
+  if (mntDrive) {
+    const drive = mntDrive[1].toLowerCase();
+    aliases.add(`/${drive}/${mntDrive[2]}`);
+    aliases.add(`${drive.toUpperCase()}:/${mntDrive[2]}`);
+  }
+  const slashDrive = path.match(/^\/([a-z])\/(.+)$/i);
+  if (slashDrive) {
+    const drive = slashDrive[1].toLowerCase();
+    aliases.add(`/mnt/${drive}/${slashDrive[2]}`);
+    aliases.add(`${drive.toUpperCase()}:/${slashDrive[2]}`);
+  }
+  const winDrive = path.match(/^([a-z]):\/(.+)$/i);
+  if (winDrive) {
+    const drive = winDrive[1].toLowerCase();
+    aliases.add(`/mnt/${drive}/${winDrive[2]}`);
+    aliases.add(`/${drive}/${winDrive[2]}`);
+  }
+  return [...aliases];
+}
+
+function isAbsoluteArtifactPath(path) {
+  return isAbsolute(path) || /^[a-z]:\//i.test(path);
+}
+
+function artifactRoots(ctx) {
+  const roots = [];
+  const repoRoot = ctx.board.repo_path || ctx.board.system_path || ctx.board.project_root || "";
+  if (repoRoot) roots.push(normalize(repoRoot));
+  roots.push(normalize(DISPATCH_RUNS_DIR));
+  if (ctx.board.db_path) {
+    roots.push(normalize(join(dirname(ctx.board.db_path), "artifacts")));
+    roots.push(normalize(join(dirname(ctx.board.db_path), "dispatch-runs")));
+  }
+  return [...new Set(roots.filter(Boolean))];
+}
+
+function resolveArtifactPath(ctx, requestedPath) {
+  const raw = cleanPath(requestedPath);
+  const roots = artifactRoots(ctx);
+  if (roots.length === 0) throw httpError(400, "artifact_root_unavailable");
+
+  const variants = pathAliases(raw);
+  const absoluteVariants = variants.filter(isAbsoluteArtifactPath);
+  const candidates = (absoluteVariants.length > 0
+    ? absoluteVariants
+    : roots.flatMap((root) => variants.map((variant) => join(root, variant))))
+    .map((candidate) => normalize(candidate));
+
+  const allowed = candidates.filter((candidate) => roots.some((root) => ensureInside(candidate, root)));
+  const path = allowed.find((candidate) => existsSync(candidate)) || allowed[0];
+  if (!path) throw httpError(400, "artifact_path_outside_allowed_roots");
+  return { path, roots };
+}
+
+function safeArtifactFileName(value, fallback = "artifact.md") {
+  const raw = cleanPath(value || fallback);
+  const name = basename(raw).replace(/[^A-Za-z0-9._-]+/g, "-") || fallback;
+  const ext = extname(name).toLowerCase();
+  if (!MARKDOWN_EXTENSIONS.has(ext)) throw httpError(415, "unsupported_artifact_type");
+  return name;
+}
+
+function boardArtifactRoot(ctx) {
+  if (!ctx.board.db_path) throw httpError(400, "artifact_root_unavailable");
+  return normalize(join(dirname(ctx.board.db_path), "artifacts"));
+}
+
+export function storeTicketMarkdownArtifact(ticketId, body, ctx) {
+  const ticket = ticketById(ctx.db, ticketId);
+  if (!ticket || ticket.board_id !== ctx.board.id) throw httpError(404, "ticket_not_found");
+  requireBoardAccess(ctx.actor, boardById(ctx.db, ticket.board_id));
+
+  const content = String(body?.content || "");
+  const size = Buffer.byteLength(content, "utf8");
+  if (size > MAX_MARKDOWN_ARTIFACT_BYTES) throw httpError(413, "artifact_too_large");
+
+  const fileName = safeArtifactFileName(body?.filename || body?.path || "artifact.md");
+  const root = boardArtifactRoot(ctx);
+  const relativePath = `tickets/${ticket.id}/${fileName}`;
+  const absolutePath = normalize(join(root, relativePath));
+  if (!ensureInside(absolutePath, root)) throw httpError(400, "artifact_path_outside_allowed_roots");
+
+  mkdirSync(dirname(absolutePath), { recursive: true });
+  writeFileSync(absolutePath, content, "utf8");
+
+  return {
+    ticket_id: ticket.id,
+    path: relativePath,
+    absolute_path: absolutePath,
+    size_bytes: size
+  };
+}
+
+function displayPathFor(path, roots) {
+  const root = roots
+    .filter((candidate) => ensureInside(path, candidate))
+    .sort((a, b) => normalize(b).length - normalize(a).length)[0];
+  if (!root) return path;
+  const rel = relative(root, path).replace(/\\/g, "/");
+  return rel || path;
+}
+
+export function getTicketMarkdownArtifact(ticketId, requestedPath, ctx) {
+  const ticket = ticketById(ctx.db, ticketId);
+  if (!ticket || ticket.board_id !== ctx.board.id) throw httpError(404, "ticket_not_found");
+  requireBoardAccess(ctx.actor, boardById(ctx.db, ticket.board_id));
+
+  const { path, roots } = resolveArtifactPath(ctx, requestedPath);
+  const ext = extname(path).toLowerCase();
+  if (!MARKDOWN_EXTENSIONS.has(ext)) throw httpError(415, "unsupported_artifact_type");
+  if (!existsSync(path)) throw httpError(404, "artifact_not_found");
+  const stat = statSync(path);
+  if (!stat.isFile()) throw httpError(400, "artifact_not_file");
+  if (stat.size > MAX_MARKDOWN_ARTIFACT_BYTES) throw httpError(413, "artifact_too_large");
+
+  return {
+    ticket_id: ticket.id,
+    path: displayPathFor(path, roots),
+    absolute_path: path,
+    size_bytes: stat.size,
+    content: readFileSync(path, "utf8")
+  };
+}

package/src/core/board.js

@@ -110,10 +110,10 @@ export const boardRuntime = {
   port: PORT
 };
 
-export function startupSummary(port = PORT) {
+export function startupSummary(port = PORT, host = "localhost") {
   const rows = listBoards();
   return {
-    url: `http://localhost:${port}`,
+    url: `http://${host}:${port}`,
     registryPath: REGISTRY_DB_PATH,
     boardCount: rows.length,
     boardPaths: rows.map((row) => row.db_path)
@@ -140,6 +140,7 @@ export { archivedTicketsForBoard } from "./queries.js";
 export { getTicketBlockers, getTicketRelations } from "./relations.js";
 export { checkpointTicket, claimNext, completeTicket, getAgentDispatchPacket, getContextPack, getContextPackFull, readComments, readTicket } from "./agent.js";
 export { searchTickets } from "./search.js";
+export { getTicketMarkdownArtifact, storeTicketMarkdownArtifact } from "./artifacts.js";
 export { exportBoard } from "./snapshots.js";
 
 // Helpers for ad-hoc id/slug minting in callers (e.g. MCP tools that mint

package/src/core/boards.js

@@ -323,7 +323,6 @@ export function boardManual(boardId, ctx, options = {}) {
       repo_url: innerBoard.repo_url,
       system_path: innerBoard.system_path || ctx.board.repo_path || "",
       default_branch: innerBoard.default_branch,
-      project_notes: innerBoard.project_notes,
       agent_instructions: innerBoard.agent_instructions,
       ai_enabled: innerBoard.ai_enabled,
       manage_helper_files: ctx.board.manage_helper_files,

package/src/core/css-bundle.js

@@ -21,6 +21,7 @@ export async function bundleCss({ entryPoint, outfile, minify = false }) {
     outfile,
     assetNames: "cursors/[name]",
     loader: CURSOR_ASSET_LOADERS,
+    external: ["./fonts/*", "fonts/*"],
     legalComments: "none"
   });
   const cssFile = result.outputFiles.find((file) => file.path.endsWith(".css"));

package/src/core/db.js

@@ -172,7 +172,9 @@ export function createBoardSchema(db) {
       type TEXT NOT NULL DEFAULT 'task',
       parent_ticket_id TEXT,
       ai_plan TEXT NOT NULL DEFAULT '',
+      plan_artifact_path TEXT NOT NULL DEFAULT '',
       implementation_summary TEXT NOT NULL DEFAULT '',
+      implementation_artifact_path TEXT NOT NULL DEFAULT '',
       implementation_updates TEXT NOT NULL DEFAULT '',
       state_id TEXT NOT NULL REFERENCES states(id),
       priority INTEGER NOT NULL DEFAULT 2,
@@ -189,6 +191,7 @@ export function createBoardSchema(db) {
       author TEXT NOT NULL,
       kind TEXT NOT NULL DEFAULT 'comment',
       body TEXT NOT NULL,
+      omitted_for_ai INTEGER NOT NULL DEFAULT 0,
       created_at TEXT NOT NULL
     );
 
@@ -289,6 +292,9 @@ export function createBoardSchema(db) {
     CREATE INDEX IF NOT EXISTS idx_relations_target ON relations(target_ticket_id);
     CREATE INDEX IF NOT EXISTS idx_events_ticket ON events(ticket_id, created_at);
   `);
+  ensureColumn(db, "tickets", "plan_artifact_path", "TEXT NOT NULL DEFAULT ''");
+  ensureColumn(db, "tickets", "implementation_artifact_path", "TEXT NOT NULL DEFAULT ''");
+  ensureColumn(db, "comments", "omitted_for_ai", "INTEGER NOT NULL DEFAULT 0");
 }
 
 export function resetBoard(db) {