@starlove/orbit 1.3.4 → 1.4.0

package/src/core/dispatch.js

@@ -1,6 +1,6 @@
 import { spawn, spawnSync } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { extname, join, resolve } from "node:path";
+import { basename, dirname, extname, join, resolve } from "node:path";
 import { localOwnerActor } from "./auth.js";
 import { DISPATCH_RUNS_DIR } from "./paths.js";
 import { getContextPackFull } from "./agent.js";
@@ -52,14 +52,34 @@ function resolveTicket(db, boardId, ticketRef) {
   return ticket;
 }
 
-function remoteDispatchError(options) {
-  if (!options.remote && !options.serverUrl) return null;
-  const target = options.serverUrl ? ` (${options.serverUrl})` : "";
-  return [
-    `Remote dispatch is not supported by the local CLI path yet${target}.`,
-    "`orbit dispatch` currently mutates a board through the local registry and SQLite board file only.",
-    "Run it on the board host without --server-url/--remote, or use remote MCP/manual orchestration for hosted boards."
-  ].join("\n");
+function parseTicketUrl(value) {
+  if (!value) return null;
+  let url;
+  try {
+    url = new URL(String(value));
+  } catch {
+    return null;
+  }
+  const hash = String(url.hash || "").replace(/^#/, "");
+  const match = hash.match(/(?:^|\/)b\/([^/]+)\/t\/([^/?#]+)/);
+  if (!match) return null;
+  url.hash = "";
+  url.search = "";
+  url.pathname = url.pathname.replace(/\/+$/, "");
+  return {
+    serverUrl: url.toString().replace(/\/+$/, ""),
+    board: decodeURIComponent(match[1]),
+    ticket: decodeURIComponent(match[2])
+  };
+}
+
+function remoteTarget(options) {
+  const parsed = parseTicketUrl(options.ticketUrl || options.ticket);
+  return {
+    serverUrl: options.serverUrl || parsed?.serverUrl || process.env.ORBIT_SERVER_URL || process.env.ORBIT_API_URL || "",
+    board: options.board || parsed?.board || process.env.ORBIT_DEFAULT_BOARD || "",
+    ticket: parsed?.ticket || options.ticket || ""
+  };
 }
 
 function resolveExecutable(command) {
@@ -210,6 +230,7 @@ function buildRunRecordJson({
     commit_shas: [],
     residual_risks: [],
     server_url: sanitizeUrlBearingValue(serverUrl),
+    transport: options.remote || options.serverUrl || options.ticketUrl ? "remote" : "local",
     mode: options.noSpawn ? "prepare-only" : "spawn",
     command: `${options.hermesBin || "hermes"} ${hermesArgs.map((arg) => (arg.includes(" ") ? q(arg) : arg)).join(" ")}`,
     created_at: new Date().toISOString(),
@@ -377,6 +398,10 @@ function buildHandoff({ boardRow, context, profile, repoRoot, worktreePath, bran
   const childText = children.length
     ? children.map((child) => `- #${child.number} ${child.title} (${child.state_name})`).join("\n")
     : "None.";
+  const recentComments = (context.recent_comments || [])
+    .slice(-5)
+    .map((comment) => `- ${comment.author || "unknown"} (${comment.kind || "comment"}): ${comment.body || ""}`)
+    .join("\n");
   const verificationText = verificationCommands.map((command) => `- ${command}`).join("\n");
 
   return `# Orbit Agent Handoff
@@ -400,29 +425,30 @@ Implement the ticket faithfully. Treat this ticket as the source of truth for co
 ## Read first
 1. AGENTS.md in the repository.
 2. SKILL-ORBIT.md in the repository.
-3. This AI Written-Plan handoff.
-4. The ticket description, implementation fields, blockers, parent/child cards, and board journal entries below.
+3. This linked markdown handoff.
+4. The ticket description, terse visible AI Plan / Work Summary, Revisions, blockers, parent/child cards, and board Journal entries below.
 
 ## Ticket description
 ${ticket.description || "(No description.)"}
 
-## Implementation records
-AI Written-Plan: ${ticket.ai_plan || "(Empty.)"}
+## Human-visible card fields
+AI Plan: ${ticket.ai_plan || "(Empty.)"}
+
+Linked plan artifact: ${ticket.plan_artifact_path || "(None.)"}
 
-AI Implementation Summary: ${ticket.implementation_summary || "(Empty.)"}
+Work Summary: ${ticket.implementation_summary || "(Empty.)"}
 
-Implementation Updates/Lessons: ${ticket.implementation_updates || "(Empty.)"}
+Linked implementation artifact: ${ticket.implementation_artifact_path || "(None.)"}
+
+Revisions: ${ticket.implementation_updates || "(Empty.)"}
 
 ## Board agent instructions
 ${board.agent_instructions || "(No board-level agent instructions.)"}
 
-## Board notes
-${board.project_notes || "(No board notes.)"}
-
 ## Board journal: lessons and decisions
-Board journal entries are project constraints and lessons, not persona or roleplay instructions. Apply them only when they clarify architecture, workflow, product boundaries, or reusable pitfalls.
+Board Journal entries are the most important code, pattern, project, and workflow context loaded for every agent working with this board. Treat decisions and lessons as project constraints, not persona or roleplay instructions.
 
-${boardEntries || "(No active board journal entries.)"}
+${boardEntries || "(No active board Journal entries.)"}
 
 ## Parent ticket
 ${parent ? `#${parent.number} ${parent.title} (${parent.state_name})` : "None."}
@@ -433,6 +459,7 @@ ${childText}
 ## Unresolved blockers
 ${blockerText}
 
+${recentComments ? `## Recent ticket comments\n${recentComments}\n` : ""}
 ## Scope boundaries
 - Keep changes local to this repository/worktree.
 - Do not push, deploy, publish, or open/merge PRs.
@@ -445,7 +472,7 @@ Allowed without asking: read/search files, inspect git status/diff/log, edit fil
 Blocked or requires explicit human approval: Docker, git push, deploy/publish/release commands, destructive git operations (reset/clean/rebase/force checkout/worktree removal), package install/publish/version commands, recursive/force filesystem deletion, SSH/SCP/rsync, cloud CLIs, GitHub CLI, direct curl/wget network calls, sudo, and secret exfiltration.
 
 ## Declared verification commands
-Run the commands that apply before handoff. If a conditional command does not apply, say why in Implementation Updates.
+Run the commands that apply before handoff. If a conditional command does not apply, say why in the completion comment or Work Summary.
 
 ${verificationText}
 
@@ -460,10 +487,11 @@ ${verificationText}
 When done:
 1. Run the relevant automated tests and any focused manual/API sanity checks.
 2. Commit the work locally on the dispatch branch.
-3. Update the ticket's AI Implementation Summary with what changed, commit SHA, branch/worktree, verification, and manual checks still needed.
-4. Add Implementation Updates/Lessons for pitfalls, remediation, or future-agent guidance.
-5. Add a completion comment/run record on the ticket.
-6. Move the ticket to Review, not Done, unless the human operator explicitly requested auto-completion.
+3. Put a terse, human-readable result summary in Work Summary (implementation_summary).
+4. If full detail matters, write a markdown report artifact and link it with implementation_artifact_path.
+5. Leave Revisions alone unless this run revises earlier implementation; promote important code/pattern/project lessons and decisions to board Journal entries.
+6. Add a compact completion comment/run receipt on the ticket.
+7. Move the ticket to Review, not Done, unless the human operator explicitly requested auto-completion.
 `;
 }
 
@@ -472,10 +500,19 @@ function buildShortPrompt({ boardRow, ticket, profile, serverUrl }) {
     `You are ${profile}, dispatched by Orbit.`,
     `Work board ${boardRow.slug}, ticket #${ticket.number}: ${ticket.title}.`,
     "Read AGENTS.md and SKILL-ORBIT.md in this repository first.",
-    "The full generated handoff is stored on the ticket in AI Written-Plan; treat the Orbit ticket as source of truth.",
+    "The full generated handoff is linked from the ticket as a markdown artifact; treat the Orbit ticket plus linked artifact as source of truth.",
     serverUrl ? `Orbit server URL: ${serverUrl}` : "Use local Orbit/MCP/API access available from this repo.",
     "Follow the autonomous policy in the handoff. Do not push, deploy, publish, run Docker, or expose secrets.",
-    "When complete, commit locally, update AI Implementation Summary/Implementation Updates on the ticket, comment the run record, and move the ticket to Review."
+    "When complete, commit locally, update a terse Work Summary plus any linked markdown report on the ticket, use Revisions only for post-initial corrections, comment the run receipt, and move the ticket to Review."
+  ].join("\n");
+}
+
+function buildPlanExcerpt({ ticket, profile, handoffPath }) {
+  return [
+    `- ${profile} dispatched to work #${ticket.number}: ${ticket.title}.`,
+    `- Full generated handoff is linked as markdown: ${handoffPath}`,
+    "- Follow blockers, scope boundaries, autonomous policy, and declared verification in that artifact.",
+    "- Keep AI Plan and Work Summary terse; put full detail in linked markdown/report artifacts."
   ].join("\n");
 }
 
@@ -490,10 +527,281 @@ function ensureWorktree({ repoRoot, boardSlug, ticketNumber, profile, branchName
   return { branchName: runBranch, worktreePath: runWorktree };
 }
 
-export function dispatchTicket(options) {
-  const remoteError = remoteDispatchError(options);
-  if (remoteError) throw new Error(remoteError);
+function remoteRunId(ticket, profile) {
+  return `orbit-${ticket.number}-${profile}-${shortId()}`;
+}
+
+function remoteRunDir(repoRoot, runId) {
+  return join(repoRoot, ".orbit", "dispatch-runs", runId);
+}
+
+function remoteWorktreePath(repoRoot, runId) {
+  return join(dirname(repoRoot), ".worktrees", basename(repoRoot), runId);
+}
+
+function contextFromDispatchPacket(packet, blockers) {
+  const blockerList = Array.isArray(blockers?.blockers) ? blockers.blockers : packet.blockers?.blockers || [];
+  return {
+    ticket: packet.ticket,
+    board: packet.board,
+    board_manual: { entries: [] },
+    parent_ticket: packet.parent_ticket || null,
+    child_tickets: [],
+    blockers: blockerList,
+    recent_comments: packet.recent_comments || []
+  };
+}
+
+async function createRemoteClient(options, target) {
+  if (options.remoteClient) return options.remoteClient;
+  const { createHttpOrbitClient } = await import("../mcp/orbit-client.js");
+  return createHttpOrbitClient({
+    ...process.env,
+    ORBIT_MODE: "remote",
+    ORBIT_API_URL: target.serverUrl,
+    ORBIT_DEFAULT_BOARD: target.board
+  });
+}
+
+async function dispatchTicketRemote(options) {
+  const target = remoteTarget(options);
+  if (!target.serverUrl) throw new Error("Remote dispatch requires --server-url or a hosted Orbit ticket URL.");
+  if (!target.board) throw new Error("Remote dispatch requires --board or a hosted Orbit ticket URL containing /b/<slug>.");
+  if (!target.ticket) throw new Error("Remote dispatch requires --ticket or a hosted Orbit ticket URL containing /t/<ticket>.");
+
+  const profile = options.profile || "agent";
+  const policyName = options.policy === undefined ? DEFAULT_POLICY : options.policy;
+  const verificationCommands = normalizeVerificationCommands(options.verifyCommands);
+  const remoteClient = await createRemoteClient(options, target);
+  await remoteClient.boardSetActive?.({ slug: target.board });
+
+  let packet;
+  if (/^\d+$/.test(String(target.ticket))) {
+    const found = await remoteClient.readTicket({ board_slug: target.board, number: Number(target.ticket) });
+    const ticketId = found.ticket?.id || found.results?.[0]?.id || found.id;
+    if (!ticketId) throw new Error(`Ticket not found on remote board: ${target.ticket}`);
+    packet = await remoteClient.getAgentDispatchPacket({ board_slug: target.board, ticket_id: ticketId, comment_limit: 5 });
+  } else {
+    packet = await remoteClient.getAgentDispatchPacket({ board_slug: target.board, ticket_id: target.ticket, comment_limit: 5 });
+  }
+  const blockers = await remoteClient.getTicketBlockers({ board_slug: target.board, ticket_id: packet.ticket.id });
+  const blockerList = Array.isArray(blockers?.blockers) ? blockers.blockers : [];
+  if (blockerList.length && !options.force) {
+    throw new Error(`Ticket #${packet.ticket.number} is blocked: ${blockerList.map((b) => `#${b.number} ${b.title}`).join(", ")}`);
+  }
+
+  const boardRow = {
+    id: packet.board.id,
+    slug: packet.board.slug,
+    name: packet.board.name,
+    repo_path: packet.board.repo_path || packet.board.system_path || "",
+    default_branch: packet.board.default_branch || "main"
+  };
+  const ticket = packet.ticket;
+  const repoRoot = resolveRepoRoot(options, boardRow);
+
+  if (options.dryRun) {
+    return {
+      dry_run: true,
+      no_spawn: Boolean(options.noSpawn),
+      run_id: null,
+      board: { id: boardRow.id, slug: boardRow.slug, name: boardRow.name },
+      ticket: { id: ticket.id, number: ticket.number, title: ticket.title },
+      profile,
+      policy: policyName || "none",
+      repo_root: repoRoot,
+      worktree_path: repoRoot,
+      branch: options.branch || "",
+      handoff_path: null,
+      policy_bin: null,
+      pid: null,
+      spawned: false,
+      prompt: "",
+      run_record: "",
+      run_record_path: null,
+      verification_commands: verificationCommands,
+      remote: true
+    };
+  }
+
+  const inProgressId = packet.relevant_state_ids?.in_progress;
+  if (!options.noSpawn && !inProgressId) throw new Error("Remote board is missing an In Progress state id in the dispatch packet.");
+  const hermesExecutable = options.noSpawn ? null : preflightHermes(options, profile);
+  const runId = remoteRunId(ticket, profile);
+  const runDir = remoteRunDir(repoRoot, runId);
+  const baseCommit = optionalCommandOutput("git", ["-C", repoRoot, "rev-parse", "HEAD"]);
+  const environmentVariance = collectEnvironmentVariance();
+  let branchName = options.branch || "";
+  let worktreePath = "";
+
+  if (options.worktree) {
+    const worktree = ensureWorktree({
+      repoRoot,
+      boardSlug: boardRow.slug,
+      ticketNumber: ticket.number,
+      profile,
+      branchName: options.branch || `orbit/${ticket.number}-${cleanName(profile)}-remote-${shortId()}`,
+      worktreePath: options.worktreePath || remoteWorktreePath(repoRoot, runId)
+    });
+    branchName = worktree.branchName;
+    worktreePath = worktree.worktreePath;
+  }
+
+  mkdirSync(runDir, { recursive: true });
+  const policyBin = createPolicyBin(runDir, policyName);
+  const context = contextFromDispatchPacket(packet, blockers);
+  const displayServerUrl = sanitizeUrlBearingValue(target.serverUrl);
+  const handoff = `${buildHandoff({
+    boardRow,
+    context,
+    profile,
+    repoRoot,
+    worktreePath,
+    branchName,
+    baseCommit,
+    policyName,
+    runId,
+    serverUrl: displayServerUrl,
+    verificationCommands
+  })}\n## Remote Orbit environment for spawned agents\n- ORBIT_MODE=remote\n- ORBIT_DEFAULT_BOARD=${boardRow.slug}\n- ORBIT_API_URL is provided by dispatch when spawning; URL-bearing values are redacted from run records.\n`;
+  const handoffPath = join(runDir, "handoff.md");
+  writeFileSync(handoffPath, handoff, "utf8");
+
+  const prompt = buildShortPrompt({ boardRow, ticket, profile, serverUrl: displayServerUrl });
+  const hermesArgs = [];
+  if (profile) hermesArgs.push("-p", profile);
+  if (options.yolo) hermesArgs.push("--yolo");
+  hermesArgs.push("chat", "-q", prompt);
+  const runRecordPath = join(runDir, "run-record.json");
+  const writeRunRecordFile = options.writeRunRecordFile || ((path, runRecordJson) => {
+    writeFileSync(path, `${JSON.stringify(runRecordJson, null, 2)}\n`, "utf8");
+  });
+  const writeRunRecordJson = (status, childProcess = null) => {
+    const runRecordJson = buildRunRecordJson({
+      runId,
+      status,
+      boardRow,
+      ticket,
+      profile,
+      policyName,
+      repoRoot,
+      worktreePath,
+      branchName,
+      baseCommit,
+      handoffPath,
+      policyBin,
+      child: childProcess,
+      hermesArgs,
+      verificationCommands,
+      options: { ...options, remote: true },
+      serverUrl: target.serverUrl,
+      environmentVariance
+    });
+    writeRunRecordFile(runRecordPath, runRecordJson);
+    return runRecordJson;
+  };
+
+  let status = "prepared";
+  writeRunRecordJson(status, null);
+  const planSummary = buildPlanExcerpt({ ticket, profile, handoffPath });
+  let linkedHandoffPath = handoffPath;
+  if (typeof remoteClient.uploadMarkdownArtifact === "function") {
+    const uploaded = await remoteClient.uploadMarkdownArtifact({
+      ticket_id: ticket.id,
+      board_slug: boardRow.slug,
+      filename: `${runId}-handoff.md`,
+      source_path: handoffPath,
+      content: readFileSync(handoffPath, "utf8")
+    });
+    if (uploaded?.path) linkedHandoffPath = uploaded.path;
+  }
+  const ticketPatch = { ticket_id: ticket.id, board_slug: boardRow.slug, ai_plan: planSummary, plan_artifact_path: linkedHandoffPath };
+  if (!options.noSpawn) ticketPatch.state_id = inProgressId;
+  await remoteClient.updateTicket(ticketPatch);
+
+  const cwd = worktreePath || repoRoot;
+  const env = {
+    ...process.env,
+    ORBIT_MODE: "remote",
+    ORBIT_API_URL: target.serverUrl,
+    ORBIT_DEFAULT_BOARD: boardRow.slug,
+    ORBIT_DISPATCH_RUN_ID: runId,
+    ORBIT_BOARD: boardRow.slug,
+    ORBIT_TICKET: String(ticket.number),
+    ORBIT_TICKET_ID: ticket.id,
+    ORBIT_HANDOFF_PATH: handoffPath,
+    ORBIT_AUTONOMOUS_POLICY: policyName || "none",
+    ...(policyBin ? { PATH: `${policyBin}:${process.env.PATH || ""}` } : {})
+  };
+
+  let child = null;
+  if (!options.noSpawn) {
+    child = spawn(hermesExecutable.command, [...hermesExecutable.argsPrefix, ...hermesArgs], {
+      cwd,
+      env,
+      detached: !options.foreground,
+      stdio: options.foreground ? "inherit" : "ignore"
+    });
+    if (!options.foreground) child.unref();
+    status = "launched";
+    writeRunRecordJson(status, child);
+  }
+
+  const runRecord = [
+    `Orbit remote dispatch run ${options.noSpawn ? "prepared" : "started"}.`,
+    `- run_id: ${runId}`,
+    `- profile: ${profile}`,
+    `- status: ${status}`,
+    `- transport: remote hosted board`,
+    `- policy: ${policyName || "none"}`,
+    `- ticket: #${ticket.number} ${ticket.title}`,
+    `- branch: ${branchName || "current branch"}`,
+    `- base_commit: ${baseCommit || "unknown"}`,
+    `- worktree: ${worktreePath || repoRoot}`,
+    `- handoff: ${handoffPath}`,
+    linkedHandoffPath !== handoffPath ? `- hosted_handoff: ${linkedHandoffPath}` : null,
+    `- run_record_json: ${runRecordPath}`,
+    `- policy_bin: ${policyBin || "none"}`,
+    `- pid: ${child?.pid || "not spawned"}`,
+    `- verification_commands: ${verificationCommands.join("; ")}`,
+    `- command: ${options.hermesBin || "hermes"} ${hermesArgs.map((arg) => (arg.includes(" ") ? q(arg) : arg)).join(" ")}`,
+    options.noSpawn ? "- mode: prepare-only; no agent spawned and ticket state left unchanged" : "- mode: spawned; ticket moved to In Progress"
+  ].filter(Boolean).join("\n");
+
+  await remoteClient.addComment({ ticket_id: ticket.id, board_slug: boardRow.slug, author: "orbit dispatch", kind: "agent_note", body: runRecord });
 
+  return {
+    dry_run: false,
+    no_spawn: Boolean(options.noSpawn),
+    run_id: runId,
+    board: { id: boardRow.id, slug: boardRow.slug, name: boardRow.name },
+    ticket: { id: ticket.id, number: ticket.number, title: ticket.title },
+    profile,
+    policy: policyName || "none",
+    repo_root: repoRoot,
+    worktree_path: worktreePath || repoRoot,
+    branch: branchName || "",
+    handoff_path: handoffPath,
+    linked_handoff_path: linkedHandoffPath,
+    policy_bin: policyBin,
+    pid: child?.pid || null,
+    spawned: Boolean(child),
+    prompt,
+    run_record: runRecord,
+    run_record_path: runRecordPath,
+    verification_commands: verificationCommands,
+    remote: true
+  };
+}
+
+export async function dispatchTicketAsync(options) {
+  if (options.remote || options.serverUrl || options.ticketUrl || parseTicketUrl(options.ticket)) {
+    return dispatchTicketRemote({ ...options, remote: true });
+  }
+  return dispatchTicket(options);
+}
+
+export function dispatchTicket(options) {
   const profile = options.profile || "agent";
   const policyName = options.policy === undefined ? DEFAULT_POLICY : options.policy;
   const verificationCommands = normalizeVerificationCommands(options.verifyCommands);
@@ -616,10 +924,11 @@ export function dispatchTicket(options) {
   writeRunRecordJson(status, null);
 
   touchBoardActive(boardRow.id);
+  const planSummary = buildPlanExcerpt({ ticket, profile, handoffPath });
   if (options.noSpawn) {
-    updateTicket(ticket.id, { ai_plan: handoff }, ctx);
+    updateTicket(ticket.id, { ai_plan: planSummary, plan_artifact_path: handoffPath }, ctx);
   } else {
-    updateTicket(ticket.id, { ai_plan: handoff, state_id: inProgress.id }, ctx);
+    updateTicket(ticket.id, { ai_plan: planSummary, plan_artifact_path: handoffPath, state_id: inProgress.id }, ctx);
   }
 
   const cwd = worktreePath || repoRoot;
@@ -657,7 +966,7 @@ export function dispatchTicket(options) {
     `- branch: ${branchName || "current branch"}`,
     `- base_commit: ${baseCommit || "unknown"}`,
     `- worktree: ${worktreePath || repoRoot}`,
-    `- handoff: AI Written-Plan field${options.keepHandoffFile ? ` and ${handoffPath}` : ""}`,
+    `- handoff: linked markdown artifact${options.keepHandoffFile ? ` and ${handoffPath}` : ""}`,
     `- run_record_json: ${runRecordPath}`,
     `- policy_bin: ${policyBin || "none"}`,
     `- pid: ${child?.pid || "not spawned"}`,
@@ -669,7 +978,7 @@ export function dispatchTicket(options) {
   createComment(ticket.id, { author: "orbit dispatch", kind: "agent_note", body: runRecord }, ctx);
 
   if (!options.keepHandoffFile) {
-    // The canonical copy is the ticket's AI Written-Plan. Keep run metadata and
+    // The canonical copy is the linked markdown artifact. Keep run metadata and
     // policy wrappers. Local-only agents may still use ORBIT_HANDOFF_PATH as a
     // bootstrap hint before they read the card, so leave the file in place.
   }
@@ -686,6 +995,7 @@ export function dispatchTicket(options) {
     worktree_path: worktreePath || repoRoot,
     branch: branchName || "",
     handoff_path: handoffPath,
+    linked_handoff_path: handoffPath,
     policy_bin: policyBin,
     pid: child?.pid || null,
     spawned: Boolean(child),

package/src/core/http.js

@@ -75,13 +75,20 @@ function shouldBundleSourceStyles(pathname, filePath) {
   return pathname === "/styles.css" && filePath === join(ROOT_DIR, "public", "styles.css");
 }
 
+export function staticAssetPathname(pathname) {
+  return pathname === "/app" || pathname.startsWith("/app/")
+    ? pathname.slice(4) || "/"
+    : pathname;
+}
+
 export async function serveStatic(req, res, pathname) {
   if (req.method !== "GET" && req.method !== "HEAD") {
     sendEmpty(res, 405);
     return;
   }
 
-  const requested = pathname === "/" ? "/index.html" : pathname;
+  const staticPathname = staticAssetPathname(pathname);
+  const requested = staticPathname === "/" ? "/index.html" : staticPathname;
   const filePath = resolvePath(PUBLIC_DIR, `.${decodeURIComponent(requested)}`);
   if (!filePath.startsWith(PUBLIC_DIR)) {
     sendEmpty(res, 403);
@@ -89,7 +96,7 @@ export async function serveStatic(req, res, pathname) {
   }
 
   try {
-    const data = shouldBundleSourceStyles(pathname, filePath)
+    const data = shouldBundleSourceStyles(staticPathname, filePath)
       ? Buffer.from((await bundleCss({ entryPoint: filePath, outfile: filePath })).cssFile.contents)
       : await readFile(filePath);
     res.writeHead(200, {

package/src/core/paths.js

@@ -6,9 +6,33 @@ import { fileURLToPath } from "node:url";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 export const ROOT_DIR = resolve(__dirname, "..", "..");
-// Prefer the pre-built bundle (present in published package); fall back to raw source for dev.
+
 const _distFull = join(ROOT_DIR, "dist", "full");
-export const PUBLIC_DIR = existsSync(_distFull) ? _distFull : join(ROOT_DIR, "public");
+const _publicDir = join(ROOT_DIR, "public");
+
+/** Where static assets (HTML/JS/CSS) are served from.
+ *
+ *  public/  — editable source; `pnpm dev` bundles @starlove/ui imports on the fly.
+ *  dist/full — prebuilt, hashed bundles from `pnpm build`; what Docker/npm ship.
+ *
+ *  Auto (default): public/ when it exists, else dist/full. Repo dev therefore
+ *  always sees live CSS/JS edits. Docker and other dist-only installs fall back
+ *  to the bundle without needing an env var.
+ *
+ *  Override: ORBIT_USE_DIST=1 force dist/full, ORBIT_USE_DIST=0 force public/. */
+function resolvePublicDir() {
+    const distExists = existsSync(_distFull);
+    const publicExists = existsSync(_publicDir);
+    const pref = process.env.ORBIT_USE_DIST;
+
+    if (pref === "1" && distExists) return _distFull;
+    if (pref === "0" && publicExists) return _publicDir;
+    if (publicExists) return _publicDir;
+    if (distExists) return _distFull;
+    return _publicDir;
+}
+
+export const PUBLIC_DIR = resolvePublicDir();
 export const MCP_SERVER_PATH = join(ROOT_DIR, "src", "mcp-server.js");
 /** Repo root for default board placement; cwd unless PROJECT_ROOT is set. */
 export const PROJECT_ROOT = process.env.PROJECT_ROOT ? resolve(process.env.PROJECT_ROOT) : resolve(process.cwd());

package/src/core/router.js

@@ -42,10 +42,12 @@ import {
   deleteTicket,
   getTicketStatusHistory,
   restoreTicket,
+  updateCommentAiOmission,
   updateTicket
 } from "./tickets.js";
 import { archivedTicketsForBoard } from "./queries.js";
 import { httpError } from "./util.js";
+import { getVersionInfo, startSelfUpdate } from "./version-check.js";
 import { pickFolder } from "./system-picker.js";
 import {
   createRelation,
@@ -72,6 +74,7 @@ import {
   readTicket
 } from "./agent.js";
 import { createReviewVerdict, getReviewVerdict, listReviewVerdicts } from "./review-verdicts.js";
+import { getTicketMarkdownArtifact, storeTicketMarkdownArtifact } from "./artifacts.js";
 
 /** Build a ctx for an already-resolved registry row + actor. */
 function ctxFromBoardRow(boardRow, actor) {
@@ -124,6 +127,21 @@ export async function handleApi(req, res, url) {
     return;
   }
 
+  // Update check (no actor needed). The client polls this on load and on a
+  // manual "Check now" (?refresh=1 bypasses the server's cached result).
+  if (req.method === "GET" && url.pathname === "/api/version") {
+    sendJson(res, 200, await getVersionInfo({ force: url.searchParams.get("refresh") === "1" }));
+    return;
+  }
+
+  // Opt-in self-update. Hidden (404) unless the operator set ORBIT_SELF_UPDATE=1,
+  // since it pulls + rebuilds + restarts the running server.
+  if (req.method === "POST" && url.pathname === "/api/update") {
+    if (process.env.ORBIT_SELF_UPDATE !== "1") throw httpError(404, "not_found");
+    sendJson(res, 202, startSelfUpdate());
+    return;
+  }
+
   const actor = actorFromHttpRequest(req);
 
   // Bootstrap: read-only registry + one chosen board. No global state mutated.
@@ -309,11 +327,26 @@ export async function handleApi(req, res, url) {
       sendJson(res, 200, readComments(ticketId, ctx));
       return;
     }
+    if (sub === "artifacts/markdown" && req.method === "GET") {
+      sendJson(res, 200, getTicketMarkdownArtifact(ticketId, url.searchParams.get("path"), ctx));
+      return;
+    }
+    if (sub === "artifacts/markdown" && req.method === "POST") {
+      const body = await readJson(req);
+      sendJson(res, 201, storeTicketMarkdownArtifact(ticketId, body, ctx));
+      return;
+    }
     if (sub === "comments" && req.method === "POST") {
       const body = await readJson(req);
       sendMutationJson(res, 201, createComment(ticketId, body, ctx), ctx);
       return;
     }
+    const commentPath = sub.match(/^comments\/([^/]+)$/);
+    if (commentPath && req.method === "PATCH") {
+      const body = await readJson(req);
+      sendMutationJson(res, 200, updateCommentAiOmission(ticketId, decodeURIComponent(commentPath[1]), body, ctx), ctx);
+      return;
+    }
     if (sub === "review-verdicts" && req.method === "GET") {
       sendJson(res, 200, { review_verdicts: listReviewVerdicts(ticketId, ctx, { limit: url.searchParams.get("limit") }) });
       return;

package/src/core/search.js

@@ -57,7 +57,7 @@ export function searchTickets(args, ctx) {
     const numberRank = ticketNumber !== null ? "CASE WHEN t.number = ? THEN -1 ELSE 0 END" : "0";
     const numberPredicate = ticketNumber !== null ? "OR t.number = ?" : "";
     const fallbackArgs = ticketNumber !== null ? [ticketNumber, board.id] : [board.id];
-    fallbackArgs.push(like, like, like, like, like, like);
+    fallbackArgs.push(like, like, like, like, like, like, like, like);
     if (ticketNumber !== null) fallbackArgs.push(ticketNumber);
     fallbackArgs.push(limit);
 
@@ -71,7 +71,8 @@ export function searchTickets(args, ctx) {
            LEFT JOIN comments c ON c.ticket_id = t.id
            WHERE t.board_id = ? AND t.archived_at IS NULL
              AND (t.title LIKE ? OR t.description LIKE ? OR t.ai_plan LIKE ?
-              OR t.implementation_summary LIKE ? OR t.implementation_updates LIKE ? OR c.body LIKE ?
+              OR t.implementation_summary LIKE ? OR t.implementation_updates LIKE ?
+              OR t.plan_artifact_path LIKE ? OR t.implementation_artifact_path LIKE ? OR c.body LIKE ?
               ${numberPredicate})
            ORDER BY t.updated_at DESC, t.id ASC
            LIMIT ?`