@starlove/orbit 1.4.0 → 2.0.0

package/src/core/agent.js

@@ -1,387 +0,0 @@
-import {
-  addComment,
-  boardById,
-  childTicketsFor,
-  compactTicket,
-  labelsForTicket,
-  relationRows,
-  stateByName,
-  stateByRole,
-  stateById,
-  ticketById,
-  ticketByNumber,
-  ticketByTitle,
-  uniqueTickets,
-  unresolvedBlockers
-} from "./queries.js";
-import { canAccessBoard, requireBoardAccess } from "./auth.js";
-import { tx } from "./db.js";
-import { recordEvent } from "./events.js";
-import {
-  appendFieldNote,
-  httpError,
-  now,
-  normalizeTicketType,
-  requiredString
-} from "./util.js";
-import { boardManual } from "./boards.js";
-import { bumpTicketUpdatedAt, reindexTicket } from "./tickets.js";
-
-/**
- * Claim the next AI-ready ticket on the resolved board. The router/MCP layer
- * is responsible for picking which board this runs against (via path slug,
- * body field, or session board); this function never scans other boards or
- * mutates global state. If you want to claim from another board, the caller
- * resolves a different ctx and calls again.
- */
-export function claimNext(body, ctx) {
-  const { db, board, actor } = ctx;
-  const filters = {
-    type: body.type ? normalizeTicketType(body.type) : "",
-    includeEpics: Boolean(body.include_epics)
-  };
-
-  const inner = boardById(db, board.id);
-  if (!inner || !canAccessBoard(actor, inner)) {
-    throw httpError(403, "forbidden");
-  }
-
-  const candidates = db
-    .prepare(
-      `SELECT t.*, b.slug AS board_slug
-       FROM tickets t
-       JOIN states s ON s.id = t.state_id
-       JOIN boards b ON b.id = t.board_id
-       WHERE (s.role = 'ai_ready' OR (s.role IS NULL AND s.name = 'AI Ready'))
-         AND t.archived_at IS NULL
-       ORDER BY t.priority DESC, t.created_at ASC`
-    )
-    .all();
-
-  const filtered = candidates.filter((ticket) =>
-    !filters.type ? filters.includeEpics || ticket.type !== "epic" : ticket.type === filters.type
-  );
-
-  for (const candidate of filtered) {
-    const blockedBy = unresolvedBlockers(db, candidate.id);
-    if (blockedBy.length > 0) continue;
-
-    const inProgress =
-      stateByRole(db, candidate.board_id, "in_progress") ||
-      stateByName(db, candidate.board_id, "In Progress");
-    if (!inProgress) throw httpError(400, "missing_in_progress_state");
-
-    tx(db, () => {
-      const time = now();
-      db.prepare("UPDATE tickets SET state_id = ?, updated_at = ? WHERE id = ?").run(
-        inProgress.id,
-        time,
-        candidate.id
-      );
-      addComment(db, candidate.id, actor.name, "agent_note", "Agent claimed this ticket and is starting work.");
-      recordEvent(db, candidate.board_id, "agent_claimed", candidate.id, actor.name, { agent_id: actor.id });
-      reindexTicket(db, candidate.id);
-      bumpTicketUpdatedAt(db, candidate.parent_ticket_id, time);
-    });
-
-    return {
-      claimed: true,
-      ticket_id: candidate.id,
-      context: readTicket(candidate.id, ctx)
-    };
-  }
-
-  return { claimed: false, reason: "no_schedulable_ticket" };
-}
-
-function resolveTicketLookup(db, boardId, { ticket_id, number, title }) {
-  if (ticket_id) return ticketById(db, ticket_id);
-  if (number !== undefined && number !== null && number !== "") {
-    const n = Number(number);
-    if (!Number.isInteger(n)) throw httpError(400, "invalid_number");
-    return ticketByNumber(db, boardId, n);
-  }
-  if (title) return ticketByTitle(db, boardId, String(title));
-  throw httpError(400, "ticket_id_or_number_or_title_required");
-}
-
-export function readTicket(lookup, ctx) {
-  const { db, board, actor } = ctx;
-  const args = typeof lookup === "string" ? { ticket_id: lookup } : lookup || {};
-  const ticket = resolveTicketLookup(db, board.id, args);
-  if (!ticket || ticket.board_id !== board.id) throw httpError(404, "ticket_not_found");
-  const innerBoard = boardById(db, ticket.board_id);
-  requireBoardAccess(actor, innerBoard);
-
-  const labels = labelsForTicket(db, ticket.id);
-
-  return {
-    ticket: {
-      id: ticket.id,
-      number: ticket.number,
-      title: ticket.title,
-      description: ticket.description,
-      state_name: ticket.state_name,
-      type: ticket.type,
-      priority: ticket.priority,
-      labels
-    },
-    board_manual: boardManual(innerBoard.id, ctx)
-  };
-}
-
-export function readComments(lookup, ctx) {
-  const { db, board, actor } = ctx;
-  const args = typeof lookup === "string" ? { ticket_id: lookup } : lookup || {};
-  const ticket = resolveTicketLookup(db, board.id, args);
-  if (!ticket || ticket.board_id !== board.id) throw httpError(404, "ticket_not_found");
-  requireBoardAccess(actor, boardById(db, ticket.board_id));
-  const comments = db
-    .prepare("SELECT * FROM comments WHERE ticket_id = ? ORDER BY created_at ASC")
-    .all(ticket.id);
-  return { ticket_id: ticket.id, comments };
-}
-
-export function checkpointTicket(body, ctx) {
-  const { db, board, actor } = ctx;
-  const tid = requiredString(body.ticket_id, "ticket_id");
-  const ticket = ticketById(db, tid);
-  if (!ticket || ticket.board_id !== board.id) throw httpError(404, "ticket_not_found");
-  requireBoardAccess(actor, boardById(db, ticket.board_id));
-
-  // Same review lane as `complete`; distinguish mid-flight pause via checkpoint comment + event kind.
-  const review =
-    stateByRole(db, ticket.board_id, "review") ||
-    stateByName(db, ticket.board_id, "Review");
-  if (!review) throw httpError(400, "missing_review_state");
-  const message = requiredString(body.message, "message");
-  tx(db, () => {
-    const time = now();
-    db.prepare("UPDATE tickets SET state_id = ?, updated_at = ? WHERE id = ?").run(review.id, time, ticket.id);
-    addComment(db, ticket.id, actor.name, "checkpoint", message);
-    recordEvent(db, ticket.board_id, "checkpoint_requested", ticket.id, actor.name, {
-      from: ticket.state_name,
-      state: review.name,
-      to: review.name,
-      actor_type: actor.type,
-      actor_id: actor.id
-    });
-    reindexTicket(db, ticket.id);
-    bumpTicketUpdatedAt(db, ticket.parent_ticket_id, time);
-  });
-  return getContextPack(ticket.id, ctx, 1);
-}
-
-export function completeTicket(body, ctx) {
-  const { db, board, actor } = ctx;
-  const tid = requiredString(body.ticket_id, "ticket_id");
-  const ticket = ticketById(db, tid);
-  if (!ticket || ticket.board_id !== board.id) throw httpError(404, "ticket_not_found");
-  requireBoardAccess(actor, boardById(db, ticket.board_id));
-
-  // If the caller specified a next_state, honor that name verbatim. Otherwise
-  // resolve the review lane by role so renaming the lane does not break this.
-  const nextState = body.next_state
-    ? stateByName(db, ticket.board_id, body.next_state)
-    : stateByRole(db, ticket.board_id, "review") || stateByName(db, ticket.board_id, "Review");
-  if (!nextState) throw httpError(400, "missing_next_state");
-
-  const summary = requiredString(body.summary, "summary");
-  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_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,
-      to: nextState.name,
-      pr_url: body.pr_url || "",
-      actor_type: actor.type,
-      actor_id: actor.id
-    });
-    reindexTicket(db, ticket.id);
-    bumpTicketUpdatedAt(db, ticket.parent_ticket_id, time);
-  });
-  return getContextPack(ticket.id, ctx, 1);
-}
-
-function contextBoardIdentity(innerBoard, ctx) {
-  return {
-    id: innerBoard.id,
-    slug: innerBoard.slug,
-    name: innerBoard.name,
-    repo_path: innerBoard.system_path || ctx.board.repo_path || "",
-    system_path: innerBoard.system_path || ctx.board.repo_path || "",
-    default_branch: innerBoard.default_branch || "main"
-  };
-}
-
-function buildContextPack(ticketId, ctx, depth = 1, options = {}, { includeProjectContext = false } = {}) {
-  const { db, board, actor } = ctx;
-  const maxCharsPerField = positiveInt(options.max_chars_per_field ?? options.maxCharsPerField, 0);
-  const includeParentFull = Boolean(options.include_parent_full ?? options.includeParentFull);
-  const includeRelatedFull = Boolean(options.include_related_full ?? options.includeRelatedFull);
-  const ticket = ticketById(db, ticketId);
-  if (!ticket || ticket.board_id !== board.id) throw httpError(404, "ticket_not_found");
-  const innerBoard = boardById(db, ticket.board_id);
-  requireBoardAccess(actor, innerBoard);
-
-  const labels = labelsForTicket(db, ticketId);
-  const relations = relationRows(db, ticketId);
-  const blockers = unresolvedBlockers(db, ticketId);
-  const parentTicket = ticket.parent_ticket_id ? ticketById(db, ticket.parent_ticket_id) : null;
-  const childTickets = childTicketsFor(db, ticketId).map((child) => ({
-    ...child,
-    labels: labelsForTicket(db, child.id),
-    blockers: unresolvedBlockers(db, child.id)
-  }));
-
-  const relatedTickets = uniqueTickets([
-    ...relations.map((relation) => relation.other_ticket),
-    ...childTickets,
-    ...(parentTicket ? [parentTicket] : [])
-  ]);
-
-  const pack = {
-    ticket: capTicketFields({
-      ...ticket,
-      labels
-    }, maxCharsPerField),
-    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),
-      child_count: childTicketsFor(db, child.id).length
-    })),
-    relations: relations.map((relation) => ({
-      ...relation,
-      other_ticket: includeRelatedFull
-        ? capTicketFields({ ...relation.other_ticket, labels: labelsForTicket(db, relation.other_ticket.id) }, maxCharsPerField)
-        : compactTicket(relation.other_ticket)
-    })),
-    blockers,
-    related_tickets: relatedTickets.map((related) =>
-      includeRelatedFull ? capTicketFields({ ...related, labels: labelsForTicket(db, related.id) }, maxCharsPerField) : compactTicket(related)
-    )
-  };
-
-  if (includeProjectContext) pack.board_manual = boardManual(innerBoard.id, ctx);
-  return pack;
-}
-
-export function getContextPack(ticketId, ctx, depth = 1, options = {}) {
-  return buildContextPack(ticketId, ctx, depth, options, { includeProjectContext: false });
-}
-
-export function getContextPackFull(ticketId, ctx, depth = 1, options = {}) {
-  return buildContextPack(ticketId, ctx, depth, options, { includeProjectContext: true });
-}
-
-export function getAgentDispatchPacket(ticketId, ctx, options = {}) {
-  const { db, board, actor } = ctx;
-  const maxCharsPerField = positiveInt(options.max_chars_per_field ?? options.maxCharsPerField, 4000);
-  const commentLimit = Math.min(nonNegativeInt(options.comment_limit ?? options.commentLimit, 5), 20);
-  const ticket = ticketById(db, ticketId);
-  if (!ticket || ticket.board_id !== board.id) throw httpError(404, "ticket_not_found");
-  const innerBoard = boardById(db, ticket.board_id);
-  requireBoardAccess(actor, innerBoard);
-
-  const labels = labelsForTicket(db, ticket.id).map((label) => label.name);
-  const parentTicket = ticket.parent_ticket_id ? ticketById(db, ticket.parent_ticket_id) : null;
-  const blockers = unresolvedBlockers(db, ticket.id).map(compactTicket);
-  const comments = db
-    .prepare("SELECT id, author, kind, body, created_at FROM comments WHERE ticket_id = ? 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) }));
-
-  return {
-    board: {
-      id: innerBoard.id,
-      slug: innerBoard.slug,
-      name: innerBoard.name,
-      repo_path: innerBoard.repo_path || innerBoard.system_path || "",
-      system_path: innerBoard.system_path || innerBoard.repo_path || "",
-      default_branch: innerBoard.default_branch || "main",
-      agent_instructions: capString(innerBoard.agent_instructions || "", maxCharsPerField)
-    },
-    ticket: {
-      id: ticket.id,
-      ticket_id: ticket.id,
-      number: ticket.number,
-      title: ticket.title,
-      type: ticket.type,
-      priority: ticket.priority,
-      state_id: ticket.state_id,
-      state_name: ticket.state_name,
-      state_role: ticket.state_role,
-      description: capString(ticket.description || "", maxCharsPerField),
-      acceptance: capString(extractAcceptance(ticket.description || ""), maxCharsPerField),
-      ai_plan: capString(ticket.ai_plan || "", maxCharsPerField),
-      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: {
-      can_start: blockers.length === 0,
-      blockers
-    },
-    parent_ticket: parentTicket ? compactTicket(parentTicket) : null,
-    relevant_state_ids: relevantStateIds(db, innerBoard.id, ticket.state_id),
-    recent_comments: comments
-  };
-}
-
-function positiveInt(value, fallback) {
-  const n = Number(value);
-  return Number.isInteger(n) && n > 0 ? n : fallback;
-}
-
-function nonNegativeInt(value, fallback) {
-  const n = Number(value);
-  return Number.isInteger(n) && n >= 0 ? n : fallback;
-}
-
-function capString(value, maxChars) {
-  const text = String(value || "");
-  return maxChars && text.length > maxChars ? text.slice(0, maxChars) : text;
-}
-
-function capTicketFields(ticket, maxChars) {
-  if (!maxChars) return ticket;
-  const copy = { ...ticket };
-  for (const field of ["description", "ai_plan", "implementation_summary", "implementation_updates"]) {
-    if (Object.hasOwn(copy, field)) copy[field] = capString(copy[field], maxChars);
-  }
-  return copy;
-}
-
-function extractAcceptance(description) {
-  const match = String(description || "").match(/(?:^|\n)\s*(?:acceptance criteria|acceptance)\s*:?\s*\n([\s\S]*)/i);
-  return match ? match[1].trim() : "";
-}
-
-function relevantStateIds(db, boardId, currentStateId) {
-  const byRole = (role) => stateByRole(db, boardId, role)?.id || null;
-  const byName = (name) => stateByName(db, boardId, name)?.id || null;
-  return {
-    current: currentStateId,
-    current_role: stateById(db, currentStateId)?.role || null,
-    ai_ready: byRole("ai_ready") || byName("AI Ready"),
-    in_progress: byRole("in_progress") || byName("In Progress"),
-    review: byRole("review") || byName("Review"),
-    done: byRole("done") || byName("Done"),
-    todo: byRole("todo") || byName("Todo")
-  };
-}

package/src/core/agents-md.js

@@ -1,109 +0,0 @@
-import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-
-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.";
-
-export function orbitAgentsSection() {
-  return `${ORBIT_AGENTS_START}
-${ORBIT_AGENTS_CANONICAL_LINE}
-
-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`;
-}
-
-export function buildAgentsMd() {
-  return `# AGENTS.md
-
-${orbitAgentsSection()}`;
-}
-
-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 };
-}
-
-/**
- * Write both Orbit helper files (SKILL-ORBIT.md + the AGENTS.md Orbit section)
- * into a project root. This is the shared core behind `orbit init` and the
- * web-UI "Generate AI helper files" checkbox, so the two flows stay identical.
- * Never throws — returns a result the caller can log or ignore.
- */
-export function generateHelperFiles(projectRoot, skillSrc, logger = console.log) {
-  if (!existsSync(skillSrc)) {
-    return { ok: false, status: "missing_source", source: skillSrc };
-  }
-  const skill = syncSkillOrbitMd(projectRoot, skillSrc);
-  syncAgentsMd(projectRoot, {}, logger);
-  return { ok: true, status: skill.status, skill };
-}
-
-export function syncAgentsMd(projectRoot, _options = {}, logger = console.log) {
-  const agentsPath = resolve(projectRoot, "AGENTS.md");
-  const section = orbitAgentsSection();
-
-  if (!existsSync(agentsPath)) {
-    writeFileSync(agentsPath, buildAgentsMd(), "utf8");
-    logger(`Wrote ${agentsPath}`);
-    return;
-  }
-
-  const current = readFileSync(agentsPath, "utf8");
-  const startIndex = current.indexOf(ORBIT_AGENTS_START);
-  const endIndex = current.indexOf(ORBIT_AGENTS_END);
-
-  if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
-    logger("AGENTS.md already includes Orbit instructions — left unchanged.");
-    return;
-  }
-
-  writeFileSync(agentsPath, `${current.replace(/\s*$/, "\n\n")}${section}`, "utf8");
-  logger(`Appended Orbit instructions to ${agentsPath}`);
-}
-
-function removeExactLegacyIntro(before) {
-  const escaped = ORBIT_AGENTS_CANONICAL_LINE.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const legacyIntro = new RegExp(`(?:^|\\n)[ \\t]*${escaped}[ \\t]*(?:\\r?\\n)?[ \\t]*$`);
-  return before.replace(legacyIntro, (match) => (match.startsWith("\n") ? "\n" : ""));
-}
-
-function joinAfterAgentsRemoval(beforeRaw, afterRaw) {
-  const before = removeExactLegacyIntro(beforeRaw).replace(/\s*$/, "");
-  const after = afterRaw.replace(/^\s*/, "");
-  if (before && after) return `${before}\n\n${after}`;
-  if (before) return `${before}\n`;
-  return after;
-}
-
-export function removeOrbitAgentsSection(projectRoot) {
-  const agentsPath = resolve(projectRoot, "AGENTS.md");
-  if (!existsSync(agentsPath)) {
-    return { ok: true, removed: false, path: agentsPath, reason: "agents_md_missing" };
-  }
-
-  const current = readFileSync(agentsPath, "utf8");
-  const startMatches = [...current.matchAll(new RegExp(ORBIT_AGENTS_START, "g"))];
-  const endMatches = [...current.matchAll(new RegExp(ORBIT_AGENTS_END, "g"))];
-  if (startMatches.length === 0 && endMatches.length === 0) {
-    return { ok: true, removed: false, path: agentsPath, reason: "orbit_section_missing" };
-  }
-  if (startMatches.length !== 1 || endMatches.length !== 1 || endMatches[0].index <= startMatches[0].index) {
-    return { ok: false, removed: false, path: agentsPath, reason: "ambiguous_orbit_section" };
-  }
-
-  const startIndex = startMatches[0].index;
-  const endIndex = endMatches[0].index + ORBIT_AGENTS_END.length;
-  const next = joinAfterAgentsRemoval(current.slice(0, startIndex), current.slice(endIndex));
-  if (next !== current) writeFileSync(agentsPath, next, "utf8");
-  return { ok: true, removed: next !== current, path: agentsPath };
-}

package/src/core/artifacts.js

@@ -1,149 +0,0 @@
-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")
-  };
-}