@starlove/orbit 1.3.4 → 1.4.0

package/src/core/snapshots.js

@@ -75,7 +75,7 @@ export function exportBoard(boardId, ctx, options = {}) {
 
   return {
     format: "orbit-board-export",
-    version: 7,
+    version: 9,
     exported_at: now(),
     include_attachments: Boolean(options.includeAttachments),
     board: { ...innerBoard },
@@ -168,9 +168,10 @@ export function importBoardSnapshot(body, ctx) {
       db.prepare(
         `INSERT INTO tickets
          (id, board_id, number, title, description, type, parent_ticket_id, ai_plan,
-          implementation_summary, implementation_updates, state_id, priority,
+          plan_artifact_path, implementation_summary, implementation_artifact_path,
+          implementation_updates, state_id, priority,
           created_by, created_at, updated_at, archived_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
       ).run(
         ticket.id,
         targetBoardId,
@@ -180,7 +181,9 @@ export function importBoardSnapshot(body, ctx) {
         normalizeTicketType(ticket.type || "task"),
         ticket.parent_ticket_id || null,
         ticket.ai_plan || "",
+        ticket.plan_artifact_path || "",
         ticket.implementation_summary || "",
+        ticket.implementation_artifact_path || "",
         ticket.implementation_updates || "",
         ticket.state_id,
         normalizePriority(ticket.priority),
@@ -197,13 +200,14 @@ export function importBoardSnapshot(body, ctx) {
 
     for (const comment of snapshot.comments || []) {
       db.prepare(
-        "INSERT INTO comments (id, ticket_id, author, kind, body, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+        "INSERT INTO comments (id, ticket_id, author, kind, body, omitted_for_ai, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)"
       ).run(
         comment.id,
         comment.ticket_id,
         comment.author || "import",
         comment.kind || "comment",
         comment.body || "",
+        comment.omitted_for_ai ? 1 : 0,
         comment.created_at || now()
       );
     }
@@ -463,6 +467,7 @@ function trelloExportToOrbitSnapshot(trello, ctx) {
         author: trelloMemberName(action.memberCreator),
         kind: "human_comment",
         body: cleanText(action.data?.text) || "",
+        omitted_for_ai: 0,
         created_at: cleanText(action.date) || cardUpdatedAt
       });
     });
@@ -471,7 +476,7 @@ function trelloExportToOrbitSnapshot(trello, ctx) {
   return {
     format: "orbit-board-export",
     source_format: "trello-board-export",
-    version: 7,
+    version: 9,
     exported_at: time,
     include_attachments: false,
     imported_counts: {

package/src/core/tickets.js

@@ -62,8 +62,9 @@ export function createTicket(body, ctx) {
     db.prepare(
       `INSERT INTO tickets
        (id, board_id, number, title, description, type, parent_ticket_id, ai_plan,
-        implementation_summary, implementation_updates, state_id, priority, created_by, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+        plan_artifact_path, implementation_summary, implementation_artifact_path,
+        implementation_updates, state_id, priority, created_by, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
     ).run(
       ticketId,
       boardId,
@@ -73,7 +74,9 @@ export function createTicket(body, ctx) {
       ticketType,
       parentTicketId,
       body.ai_plan || "",
+      body.plan_artifact_path || "",
       body.implementation_summary || "",
+      body.implementation_artifact_path || "",
       body.implementation_updates || "",
       stateId,
       normalizePriority(body.priority),
@@ -113,7 +116,9 @@ export function updateTicket(ticketId, body, ctx) {
     "type",
     "parent_ticket_id",
     "ai_plan",
+    "plan_artifact_path",
     "implementation_summary",
+    "implementation_artifact_path",
     "implementation_updates",
     "state_id",
     "priority"
@@ -295,6 +300,32 @@ export function createComment(ticketId, body, ctx) {
   });
 }
 
+export function updateCommentAiOmission(ticketId, commentId, body, ctx) {
+  const { db, board, actor } = ctx;
+  const ticket = ticketById(db, ticketId);
+  if (!ticket || ticket.board_id !== board.id) throw httpError(404, "ticket_not_found");
+  requireBoardAccess(actor, boardById(db, ticket.board_id));
+  requirePermission(actor, "write");
+
+  const comment = db.prepare("SELECT * FROM comments WHERE id = ? AND ticket_id = ?").get(commentId, ticketId);
+  if (!comment) throw httpError(404, "comment_not_found");
+  const omittedForAi = body.omitted_for_ai ?? body.omittedForAi;
+  if (typeof omittedForAi !== "boolean") throw httpError(400, "omitted_for_ai_required");
+
+  return tx(db, () => {
+    const time = now();
+    db.prepare("UPDATE comments SET omitted_for_ai = ? WHERE id = ?").run(omittedForAi ? 1 : 0, commentId);
+    db.prepare("UPDATE tickets SET updated_at = ? WHERE id = ?").run(time, ticketId);
+    recordEvent(db, ticket.board_id, "comment_ai_omission_changed", ticketId, actor.name, {
+      comment_id: commentId,
+      omitted_for_ai: omittedForAi
+    });
+    reindexTicket(db, ticketId);
+    bumpTicketUpdatedAt(db, ticket.parent_ticket_id, time);
+    return db.prepare("SELECT * FROM comments WHERE id = ?").get(commentId);
+  });
+}
+
 export function getTicketStatusHistory(ticketId, ctx) {
   const { db, board, actor } = ctx;
   const ticket = ticketById(db, ticketId);
@@ -342,7 +373,7 @@ export function reindexTicket(db, ticketId) {
   const ticket = db.prepare("SELECT * FROM tickets WHERE id = ?").get(ticketId);
   if (!ticket) return;
   const comments = db
-    .prepare("SELECT body FROM comments WHERE ticket_id = ? ORDER BY created_at ASC")
+    .prepare("SELECT body FROM comments WHERE ticket_id = ? AND COALESCE(omitted_for_ai, 0) = 0 ORDER BY created_at ASC")
     .all(ticketId)
     .map((comment) => comment.body)
     .join("\n");

package/src/core/util.js

@@ -87,10 +87,11 @@ export function normalizeStateRole(value) {
 }
 
 export function appendFieldNote(existing, note, actorName) {
+  void actorName;
   const text = String(note || "").trim();
   if (!text) return existing || "";
-  const entry = `## ${new Date().toISOString()} - ${actorName}\n\n${text}`;
-  return [existing, entry].filter(Boolean).join("\n\n");
+  const prior = String(existing || "").trim();
+  return [prior, text].filter(Boolean).join("\n\n");
 }
 
 export function toFtsQuery(q) {

package/src/core/version-check.js

@@ -0,0 +1,154 @@
+// Update checking. The server reads its own version from package.json and
+// compares it against the `version` field of package.json on the project's
+// GitHub default branch. We hit the GitHub *contents API* (not the raw CDN):
+// it honours conditional requests / no-cache so the answer is authoritative,
+// and because only the server polls — not every browser — GitHub's 60 req/hr
+// unauthenticated limit is a non-issue. Results are cached in-memory for
+// ORBIT_UPDATE_TTL minutes; `force` bypasses the cache for a "Check now".
+//
+// Env:
+//   ORBIT_UPDATE_CHECK=0    disable the check entirely (returns enabled:false)
+//   ORBIT_UPDATE_TTL=<min>  cache lifetime, default 60
+//   ORBIT_UPDATE_BRANCH     branch to read, default the repo default (master)
+//   ORBIT_GITHUB_TOKEN      optional PAT (private repos / higher rate limit)
+//   ORBIT_SELF_UPDATE=1     enable the gated POST /api/update self-update
+//   ORBIT_DOCKER=1          force "docker" deploy mode
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { ROOT_DIR, DATA_DIR } from "./paths.js";
+
+const DEFAULT_OWNER = "brucestarlove";
+const DEFAULT_REPO = "ss-orbit";
+const CHECK_TIMEOUT_MS = 5000;
+
+let pkgCache = null;
+function readPackage() {
+  if (pkgCache) return pkgCache;
+  try {
+    pkgCache = JSON.parse(readFileSync(join(ROOT_DIR, "package.json"), "utf8"));
+  } catch {
+    pkgCache = {};
+  }
+  return pkgCache;
+}
+
+/** Parse owner/repo out of package.json repository.url, falling back to the
+ *  known Orbit repo so the check still works on odd checkouts. */
+function repoCoordinates() {
+  const url = readPackage()?.repository?.url || "";
+  const match = url.match(/github\.com[/:]([^/]+)\/([^/.]+)/i);
+  return { owner: match?.[1] || DEFAULT_OWNER, repo: match?.[2] || DEFAULT_REPO };
+}
+
+function localVersion() {
+  return readPackage()?.version || "0.0.0";
+}
+
+function updateBranch() {
+  return process.env.ORBIT_UPDATE_BRANCH || "master";
+}
+
+/** How this instance is running, which decides the update instructions the
+ *  client shows. Docker images carry no git tree, so they're rebuild-only. */
+function detectDeployMode() {
+  if (process.env.ORBIT_DOCKER === "1" || existsSync("/.dockerenv")) return "docker";
+  if (existsSync(join(ROOT_DIR, ".git"))) return "source";
+  return "dist";
+}
+
+/** Numeric "a.b.c" comparison (ignores any prerelease suffix). Returns true
+ *  when `latest` is strictly newer than `current`. */
+function isNewer(latest, current) {
+  const parse = (v) => String(v).replace(/^v/, "").split(/[.+-]/).map((n) => Number(n) || 0);
+  const a = parse(latest);
+  const b = parse(current);
+  for (let i = 0; i < 3; i += 1) {
+    if ((a[i] || 0) > (b[i] || 0)) return true;
+    if ((a[i] || 0) < (b[i] || 0)) return false;
+  }
+  return false;
+}
+
+async function fetchLatestVersion() {
+  const { owner, repo } = repoCoordinates();
+  const branch = updateBranch();
+  const headers = {
+    Accept: "application/vnd.github.raw+json",
+    "User-Agent": "orbit-update-check"
+  };
+  if (process.env.ORBIT_GITHUB_TOKEN) headers.Authorization = `Bearer ${process.env.ORBIT_GITHUB_TOKEN}`;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS);
+  try {
+    const res = await fetch(
+      `https://api.github.com/repos/${owner}/${repo}/contents/package.json?ref=${encodeURIComponent(branch)}`,
+      { headers, signal: controller.signal, cache: "no-store" }
+    );
+    if (res.status === 403 || res.status === 429) return { error: "rate_limited" };
+    if (!res.ok) return { error: `http_${res.status}` };
+    const pkg = JSON.parse(await res.text());
+    if (!pkg?.version) return { error: "no_version" };
+    return { latest: String(pkg.version) };
+  } catch (err) {
+    return { error: err?.name === "AbortError" ? "timeout" : "unreachable" };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+let cache = null; // { at: epochMs, payload }
+
+function staticPayload(extra) {
+  const { owner, repo } = repoCoordinates();
+  const branch = updateBranch();
+  return {
+    current: localVersion(),
+    deployMode: detectDeployMode(),
+    selfUpdate: process.env.ORBIT_SELF_UPDATE === "1",
+    repoUrl: `https://github.com/${owner}/${repo}`,
+    changesUrl: `https://github.com/${owner}/${repo}/commits/${branch}`,
+    ...extra
+  };
+}
+
+/** Get current/latest version info, cached for ORBIT_UPDATE_TTL minutes.
+ *  Never throws — network problems surface as `{ error, updateAvailable:false }`. */
+export async function getVersionInfo({ force = false } = {}) {
+  if (process.env.ORBIT_UPDATE_CHECK === "0") {
+    return staticPayload({ enabled: false, latest: null, updateAvailable: false, error: null, checkedAt: null });
+  }
+
+  const ttlMs = (Number(process.env.ORBIT_UPDATE_TTL) || 60) * 60 * 1000;
+  if (!force && cache && Date.now() - cache.at < ttlMs) return cache.payload;
+
+  const result = await fetchLatestVersion();
+  const current = localVersion();
+  const payload = staticPayload({
+    enabled: true,
+    latest: result.latest ?? null,
+    updateAvailable: Boolean(result.latest) && isNewer(result.latest, current),
+    error: result.error ?? null,
+    checkedAt: new Date().toISOString()
+  });
+  cache = { at: Date.now(), payload };
+  return payload;
+}
+
+/** Kick off scripts/update.sh detached and hand back immediately. Only ever
+ *  reached when ORBIT_SELF_UPDATE=1 (the router gates the route). The script
+ *  rebuilds and then signals this process so a supervisor restarts it. */
+export function startSelfUpdate() {
+  const script = join(ROOT_DIR, "scripts", "update.sh");
+  if (!existsSync(script)) return { started: false, error: "script_missing" };
+  const child = spawn("bash", [script], {
+    cwd: ROOT_DIR,
+    detached: true,
+    stdio: "ignore",
+    env: { ...process.env, ORBIT_REPO_DIR: ROOT_DIR, ORBIT_SERVER_PID: String(process.pid), ORBIT_DATA_DIR: DATA_DIR }
+  });
+  child.unref();
+  return { started: true };
+}

package/src/mcp/orbit-client.js

@@ -61,6 +61,13 @@ export function createHttpOrbitClient(env = process.env, fetchImpl = globalThis.
     const { board_id, board_slug, board, ...rest } = args;
     return rest;
   };
+  const settingsPatch = (args = {}) => {
+    const patch = {};
+    for (const field of ["name", "repo_url", "system_path", "default_branch", "agent_instructions"]) {
+      if (args[field] !== undefined) patch[field] = args[field];
+    }
+    return patch;
+  };
   const searchQuery = (args = {}) => ({
     q: args.q,
     limit: args.limit,
@@ -119,6 +126,7 @@ export function createHttpOrbitClient(env = process.env, fetchImpl = globalThis.
     async search(args = {}) { return request("GET", "/api/search", { query: searchQuery(args) }); },
     async createTicket(args = {}) { return request("POST", "/api/tickets", { body: { ...args, board: requireBoard(args) }, ok: [201] }); },
     async updateTicket({ ticket_id, ...patch }) { return request("PATCH", `/api/tickets/${encodeURIComponent(ticket_id)}`, { query: ticketQuery(patch), body: stripBoardSelectors(patch) }); },
+    async uploadMarkdownArtifact({ ticket_id, ...body }) { return request("POST", `/api/tickets/${encodeURIComponent(ticket_id)}/artifacts/markdown`, { query: ticketQuery(body), body: stripBoardSelectors(body), ok: [201] }); },
     async addComment({ ticket_id, ...body }) { return request("POST", `/api/tickets/${encodeURIComponent(ticket_id)}/comments`, { query: ticketQuery(body), body: stripBoardSelectors(body), ok: [201] }); },
     async createReviewVerdict({ ticket_id, ...body }) { return request("POST", `/api/tickets/${encodeURIComponent(ticket_id)}/review-verdicts`, { query: ticketQuery(body), body: stripBoardSelectors(body), ok: [201] }); },
     async listReviewVerdicts(args = {}) { return request("GET", `/api/tickets/${encodeURIComponent(args.ticket_id)}/review-verdicts`, { query: { ...ticketQuery(args), limit: args.limit } }); },
@@ -135,7 +143,7 @@ export function createHttpOrbitClient(env = process.env, fetchImpl = globalThis.
         query: { include_attachments: args.include_attachments || args.include_images ? "true" : undefined }
       });
     },
-    async updateSettings(args = {}) { const { board_id, board_slug, board, ...patch } = args; return request("PATCH", `/api/boards/${encodeURIComponent(requireBoard(args))}`, { body: patch }); }
+    async updateSettings(args = {}) { return request("PATCH", `/api/boards/${encodeURIComponent(requireBoard(args))}`, { body: settingsPatch(args) }); }
   };
 }
 
@@ -226,6 +234,13 @@ export async function createLocalOrbitClient(env = process.env) {
     const { board_id, board_slug, board: _board, ...rest } = args;
     return rest;
   };
+  const settingsPatch = (args = {}) => {
+    const patch = {};
+    for (const field of ["name", "repo_url", "system_path", "default_branch", "agent_instructions"]) {
+      if (args[field] !== undefined) patch[field] = args[field];
+    }
+    return patch;
+  };
   const actor = () => board.localAgentActor();
 
   return {
@@ -249,6 +264,7 @@ export async function createLocalOrbitClient(env = process.env) {
     search: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.searchTickets(args, ctx); },
     createTicket: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); const body = stripBoardSelectors(args); body.board_id = ctx.board.id; return backup(ctx, board.createTicket(body, ctx)); },
     updateTicket: ({ ticket_id, ...patch }) => { const ctx = ctxFor(rowOrSession(patch), actor()); return backup(ctx, board.updateTicket(ticket_id, stripBoardSelectors(patch), ctx)); },
+    uploadMarkdownArtifact: ({ ticket_id, ...body }) => { const ctx = ctxFor(rowOrSession(body), actor()); return board.storeTicketMarkdownArtifact(ticket_id, stripBoardSelectors(body), ctx); },
     addComment: ({ ticket_id, ...body }) => { const ctx = ctxFor(rowOrSession(body), actor()); return backup(ctx, board.createComment(ticket_id, stripBoardSelectors(body), ctx)); },
     createReviewVerdict: ({ ticket_id, ...body }) => { const ctx = ctxFor(rowOrSession(body), actor()); return backup(ctx, board.createReviewVerdict(ticket_id, stripBoardSelectors(body), ctx)); },
     listReviewVerdicts: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return { review_verdicts: board.listReviewVerdicts(args.ticket_id, ctx, args) }; },
@@ -266,6 +282,6 @@ export async function createLocalOrbitClient(env = process.env) {
         includeAttachments: Boolean(args.include_attachments || args.include_images)
       });
     },
-    updateSettings: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); const patch = stripBoardSelectors(args); return backup(ctx, board.updateBoard(ctx.board.id, patch, ctx)); }
+    updateSettings: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return backup(ctx, board.updateBoard(ctx.board.id, settingsPatch(args), ctx)); }
   };
 }

package/src/mcp-server.js

@@ -187,7 +187,7 @@ const TOOL_DEFS = [
   {
     name: "board_context",
     description:
-      "Board/project context pack: board metadata, agent_instructions, journal entries (board_entries), and deployment paths. Complements the lean board_get_ticket_context. Resolves board from board_id / board_slug / board first; the MCP session board is only a fallback convenience. Set include_struck true to include struck journal rows (default false). Same payload as GET /api/boards/:id/context.",
+      "Board/project context pack: agent-safe board metadata, agent_instructions, journal entries (board_entries), and deployment paths. Human-only project_notes are intentionally excluded. Complements the lean board_get_ticket_context. Resolves board from board_id / board_slug / board first; the MCP session board is only a fallback convenience. Set include_struck true to include struck journal rows (default false). Same payload as GET /api/boards/:id/context.",
     inputSchema: {
       type: "object",
       properties: {
@@ -287,7 +287,7 @@ const TOOL_DEFS = [
   {
     name: "board_get_agent_dispatch_packet",
     description:
-      "Return a lean agent dispatch packet for one ticket: board identity/instructions, capped ticket description/acceptance/AI plan, blockers, shallow parent, relevant workflow state IDs, repo path/default branch, recent capped comments, and label names. Resolves board from board_id / board_slug / board first; the MCP session board is only a fallback convenience. Parent/related/implementation bodies are intentionally omitted.",
+      "Return a lean agent dispatch packet for one ticket: board identity/instructions, capped description/acceptance, human-visible card fields and linked artifact paths, blockers, shallow parent, relevant workflow state IDs, repo path/default branch, recent capped comments, and label names. Resolves board from board_id / board_slug / board first; the MCP session board is only a fallback convenience. Full parent/related bodies and full comments are intentionally omitted.",
     inputSchema: {
       type: "object",
       properties: {
@@ -407,9 +407,11 @@ const TOOL_DEFS = [
         description: { type: "string" },
         type: { type: "string", enum: ["epic", "feature", "task", "bug"] },
         parent_ticket_id: { type: ["string", "null"] },
-        ai_plan: { type: "string" },
-        implementation_summary: { type: "string" },
-        implementation_updates: { type: "string" },
+        ai_plan: { type: "string", description: "Existing AI Plan field: terse human-visible plan summary; link full markdown handoffs with plan_artifact_path." },
+        plan_artifact_path: { type: "string", description: "Human-editable link/path to a full markdown/text plan artifact, e.g. docs/plan.md or ./docs/plan.md. Keep AI Plan terse; do not paste full handoffs into ai_plan." },
+        implementation_summary: { type: "string", description: "Existing Work Summary field: terse human-visible result summary; link full reports with implementation_artifact_path." },
+        implementation_artifact_path: { type: "string", description: "Human-editable link/path to a full markdown/text implementation report or evidence artifact, e.g. docs/report.md or ./docs/report.md. Keep Work Summary terse." },
+        implementation_updates: { type: "string", description: "Revisions field: terse later changes/corrections after initial implementation; omit logs, chronology, and normal completion notes." },
         state_id: { type: "string" },
         priority: { type: "integer" },
         labels: { type: "array", items: { type: "string" } }
@@ -422,7 +424,7 @@ const TOOL_DEFS = [
   {
     name: "board_update_ticket",
     description:
-      "Update ticket fields such as AI plan, implementation summary, implementation updates, state, type, priority, or labels (full replace: array of label names). Resolves board from board_id / board_slug / board; the MCP session board is only a fallback convenience.",
+      "Update ticket fields such as terse AI Plan / Work Summary text, linked artifact paths, Revisions, state, type, priority, or labels (full replace: array of label names). Resolves board from board_id / board_slug / board; the MCP session board is only a fallback convenience.",
     inputSchema: {
       type: "object",
       properties: {
@@ -434,9 +436,11 @@ const TOOL_DEFS = [
         description: { type: "string" },
         type: { type: "string" },
         parent_ticket_id: { type: ["string", "null"] },
-        ai_plan: { type: "string" },
-        implementation_summary: { type: "string" },
-        implementation_updates: { type: "string" },
+        ai_plan: { type: "string", description: "Existing AI Plan field: terse human-visible plan summary; link full markdown handoffs with plan_artifact_path." },
+        plan_artifact_path: { type: "string", description: "Human-editable link/path to a full markdown/text plan artifact, e.g. docs/plan.md or ./docs/plan.md. Keep AI Plan terse; do not paste full handoffs into ai_plan." },
+        implementation_summary: { type: "string", description: "Existing Work Summary field: terse human-visible result summary; link full reports with implementation_artifact_path." },
+        implementation_artifact_path: { type: "string", description: "Human-editable link/path to a full markdown/text implementation report or evidence artifact, e.g. docs/report.md or ./docs/report.md. Keep Work Summary terse." },
+        implementation_updates: { type: "string", description: "Revisions field: terse later changes/corrections after initial implementation; omit logs, chronology, and normal completion notes." },
         state_id: { type: "string" },
         priority: { type: "integer" },
         labels: { type: "array", items: { type: "string" }, description: "Replaces all ticket labels when provided." }
@@ -562,7 +566,7 @@ const TOOL_DEFS = [
   {
     name: "board_complete",
     description:
-      "Hand off finished work for human review: moves the ticket to the Review lane (by role or name), writes a completion comment (summary, optional PR URL), and optional implementation_updates. This is the usual 'ready for you to look' path; use board_checkpoint only when blocked mid-flight. Resolves board from board_id / board_slug / board; the MCP session board is only a fallback convenience.",
+      "Hand off finished work for human review: moves the ticket to the Review lane (by role or name), writes a compact completion comment, stores summary as the terse Work Summary (`implementation_summary`), and accepts optional linked implementation_artifact_path. Pass updates only for Revisions: terse later changes/corrections after initial implementation, not normal completion notes. This is the usual 'ready for you to look' path; use board_checkpoint only when blocked mid-flight. Resolves board from board_id / board_slug / board; the MCP session board is only a fallback convenience.",
     inputSchema: {
       type: "object",
       properties: {
@@ -570,8 +574,10 @@ const TOOL_DEFS = [
         board_id: { type: "string" },
         board_slug: { type: "string" },
         board: { type: "string" },
-        summary: { type: "string" },
-        updates: { type: "string" },
+        summary: { type: "string", description: "Terse human-visible Work Summary stored in implementation_summary." },
+        updates: { type: "string", description: "Optional Revisions text only: terse later changes/corrections after initial implementation." },
+        implementation_artifact_path: { type: "string", description: "Human-editable link/path to a markdown/text implementation report artifact; can point at a report generated outside Orbit." },
+        summary_artifact_path: { type: "string", description: "Compatibility alias for implementation_artifact_path." },
         pr_url: { type: "string" },
         next_state: { type: "string" }
       },
@@ -647,7 +653,7 @@ const TOOL_DEFS = [
   {
     name: "board_update_settings",
     description:
-      "PATCH-equivalent for board settings: name (display rename only; slug/canonical URLs stay unchanged), repo_url, system_path, default_branch, agent_instructions (project-level agent context), and project_notes (Notes For You). Resolves board from board_id / board_slug / board; the MCP session board is only a fallback convenience.",
+      "PATCH-equivalent for board settings: name (display rename only; slug/canonical URLs stay unchanged), repo_url, system_path, default_branch, and agent_instructions (project-level agent context). Resolves board from board_id / board_slug / board; the MCP session board is only a fallback convenience.",
     inputSchema: {
       type: "object",
       properties: {
@@ -658,7 +664,6 @@ const TOOL_DEFS = [
         repo_url: { type: "string" },
         system_path: { type: "string" },
         default_branch: { type: "string" },
-        project_notes: { type: "string" },
         agent_instructions: { type: "string" }
       },
       additionalProperties: false

package/src/server.js

@@ -1,4 +1,5 @@
 import { createServer } from "node:http";
+import { networkInterfaces } from "node:os";
 import {
   boardRuntime,
   handleApi,
@@ -41,15 +42,36 @@ const server = createServer(async (req, res) => {
 });
 
 const requestedPort = boardRuntime.port;
+const requestedHost = process.env.HOST || process.env.ORBIT_HOST || "";
 const hasExplicitPort = Boolean(process.env.PORT);
 const maxAutoPort = requestedPort + 99;
 let currentPort = requestedPort;
 
+function listen(port) {
+  if (requestedHost) {
+    server.listen(port, requestedHost);
+    return;
+  }
+  server.listen(port);
+}
+
+function displayHost(host) {
+  if (!host || host === "::" || host === "0.0.0.0") return "localhost";
+  return host;
+}
+
+function networkUrls(port) {
+  return Object.values(networkInterfaces())
+    .flat()
+    .filter((item) => item && item.family === "IPv4" && !item.internal)
+    .map((item) => `http://${item.address}:${port}`);
+}
+
 server.on("error", (error) => {
   if (!hasExplicitPort && error?.code === "EADDRINUSE" && currentPort < maxAutoPort) {
     currentPort += 1;
     console.warn(`[orbit] Port ${currentPort - 1} is in use; trying ${currentPort}.`);
-    server.listen(currentPort);
+    listen(currentPort);
     return;
   }
 
@@ -58,13 +80,16 @@ server.on("error", (error) => {
   process.exit(1);
 });
 
-server.listen(currentPort);
+listen(currentPort);
 
 server.on("listening", () => {
   const address = server.address();
   const port = typeof address === "object" && address ? address.port : currentPort;
-  const summary = startupSummary(port);
+  const host = typeof address === "object" && address ? displayHost(address.address) : displayHost(requestedHost);
+  const summary = startupSummary(port, host);
   console.log(`Starscape Orbit listening on ${summary.url}`);
+  const urls = networkUrls(port).filter((url) => url !== summary.url);
+  if (urls.length) console.log(`Network: ${urls.join(", ")}`);
   console.log(`Registry: ${summary.registryPath}`);
   console.log(`Boards (${summary.boardCount}):`);
   for (const path of summary.boardPaths) console.log(`  - ${path}`);