codetrellis 0.0.0-stage → 0.2.0

package/src/backend/services/breakpoint-service.js

@@ -0,0 +1,584 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var breakpoint_service_exports = {};
+__export(breakpoint_service_exports, {
+  ACTIVE_SELECT: () => ACTIVE_SELECT,
+  BREAKPOINT_KINDS: () => import_types.BREAKPOINT_KINDS,
+  BreakpointError: () => BreakpointError,
+  DECISIONS: () => import_types.BREAKPOINT_DECISIONS,
+  HIT_SELECT: () => HIT_SELECT,
+  MAX_NOTE: () => MAX_NOTE,
+  SIGNAL_BREAK_KINDS: () => import_types.SIGNAL_BREAK_KINDS,
+  answerHit: () => answerHit,
+  cleanNote: () => cleanNote,
+  clearBreakpoint: () => clearBreakpoint,
+  codeCovers: () => codeCovers,
+  codeScope: () => codeScope,
+  codeTarget: () => codeTarget,
+  countWaitingHits: () => countWaitingHits,
+  decisionView: () => decisionView,
+  docBreakpoint: () => docBreakpoint,
+  enforce: () => enforce,
+  getBreakpoint: () => getBreakpoint,
+  getHit: () => getHit,
+  guardedCall: () => guardedCall,
+  hitPayload: () => hitPayload,
+  listBreakpoints: () => listBreakpoints,
+  listHits: () => listHits,
+  onHitAnswered: () => onHitAnswered,
+  pausedResult: () => pausedResult,
+  rowsOf: () => rowsOf,
+  setBreakpoint: () => setBreakpoint,
+  specBreakpointOn: () => specBreakpointOn,
+  steerText: () => steerText,
+  stoppedResult: () => stoppedResult,
+  subjectOf: () => subjectOf,
+  toBreakpointRow: () => toBreakpointRow,
+  toHitRow: () => toHitRow
+});
+module.exports = __toCommonJS(breakpoint_service_exports);
+var import_node_crypto = require("node:crypto");
+var import_node_fs = __toESM(require("node:fs"));
+var import_node_path = __toESM(require("node:path"));
+var import_database = require("./database");
+var import_agent_event_log = require("./agent-event-log");
+var import_types = require("../../shared/types");
+var import_push_notification_service = require("./push-notification-service");
+var import_spec_links_service = require("./spec-links-service");
+const MAX_NOTE = 1e3;
+const MAX_DEPTH = 50;
+function rowsOf(sql, params = []) {
+  const res = (0, import_database.getDb)().exec(sql, params);
+  if (!res.length) return [];
+  const { columns, values } = res[0];
+  return values.map((v) => Object.fromEntries(columns.map((c, i) => [c, v[i]])));
+}
+function cleanNote(raw) {
+  if (typeof raw !== "string") return null;
+  const s = raw.replace(/\r\n?/g, "\n").replace(/[\u0000-\u0009\u000b-\u001f\u007f]+/g, " ").trim();
+  return s ? s.slice(0, MAX_NOTE) : null;
+}
+function guardedCall(tool, args) {
+  const a = args ?? {};
+  const uid = typeof a.uid === "string" && a.uid ? a.uid : null;
+  if (!uid) return null;
+  const actions = [];
+  switch (tool) {
+    case "claim_item":
+      actions.push({ action: "claim", kind: "task" });
+      break;
+    case "update_item":
+      if (a.status === "in_progress") actions.push({ action: "claim", kind: "task" });
+      if (a.status === "done") actions.push({ action: "done", kind: "task" });
+      if (a.title !== void 0 || a.body !== void 0 || a.template !== void 0) actions.push({ action: "edit", kind: "spec" });
+      break;
+    case "restore_item_version":
+      actions.push({ action: "edit", kind: "spec" });
+      break;
+    case "delete_item":
+      actions.push({ action: "delete", kind: "task" }, { action: "delete", kind: "spec" });
+      break;
+    default:
+      return null;
+  }
+  return actions.length ? { itemUid: uid, actions } : null;
+}
+function itemRow(uid) {
+  return rowsOf("SELECT uid, parent_uid, plan_uid, title FROM plan_items WHERE uid = ?", [uid])[0] ?? null;
+}
+function lineage(uid) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  let at = uid;
+  while (at && !seen.has(at) && out.length < MAX_DEPTH) {
+    seen.add(at);
+    const row = itemRow(at);
+    if (!row) break;
+    out.push(row);
+    at = row.parent_uid;
+  }
+  return out;
+}
+function toBreakpoint(r) {
+  return {
+    id: r.id,
+    kind: r.kind,
+    target: r.target,
+    targetTitle: r.title ?? null,
+    planUid: r.plan_uid,
+    projectRoot: r.project_root ?? null,
+    note: r.note,
+    createdAt: Number(r.created_at),
+    createdBy: r.created_by,
+    createdByType: r.created_by_type
+  };
+}
+const ACTIVE_SELECT = `SELECT b.id, b.kind, b.target, b.plan_uid, b.project_root, b.note, b.created_at, b.created_by, b.created_by_type,
+  COALESCE(i.title, d.title) AS title
+  FROM breakpoints b LEFT JOIN plan_items i ON i.uid = b.target LEFT JOIN plan_documents d ON d.uid = b.target WHERE b.cleared_at IS NULL`;
+function toBreakpointRow(r) {
+  return toBreakpoint(r);
+}
+function listBreakpoints(planUid) {
+  const rows = planUid ? rowsOf(`${ACTIVE_SELECT} AND b.plan_uid = ? ORDER BY b.created_at`, [planUid]) : rowsOf(`${ACTIVE_SELECT} ORDER BY b.created_at`);
+  return rows.map(toBreakpoint);
+}
+function getBreakpoint(id) {
+  const r = rowsOf(`${ACTIVE_SELECT} AND b.id = ?`, [id])[0];
+  return r ? toBreakpoint(r) : null;
+}
+class BreakpointError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+  status;
+}
+function setBreakpoint(input) {
+  if (!import_types.BREAKPOINT_KINDS.includes(input.kind)) throw new BreakpointError(`kind must be one of ${import_types.BREAKPOINT_KINDS.join(", ")}`, 400);
+  if (input.kind === "proposal") throw new BreakpointError("A proposal breakpoint is raised by a spec change being proposed, not set", 400);
+  if (input.kind === "code") return setCodeBreakpoint(input);
+  if (input.kind === "signal") return setSignalBreakpoint(input);
+  if (input.docUid !== void 0) return setDocBreakpoint(input);
+  const item = typeof input.itemUid === "string" ? itemRow(input.itemUid) : null;
+  if (!item) throw new BreakpointError("Item not found", 404);
+  const kind = input.kind;
+  const existing = rowsOf(`${ACTIVE_SELECT} AND b.kind = ? AND b.target = ?`, [kind, item.uid])[0];
+  if (existing) return { breakpoint: toBreakpoint(existing), created: false };
+  const id = `bp_${(0, import_node_crypto.randomBytes)(6).toString("hex")}`;
+  (0, import_database.getDb)().run(
+    "INSERT INTO breakpoints (id, kind, target, plan_uid, note, created_at, created_by, created_by_type) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+    [id, kind, item.uid, item.plan_uid, cleanNote(input.note), input.now ?? Date.now(), input.by, input.byType]
+  );
+  return { breakpoint: getBreakpoint(id), created: true };
+}
+function setDocBreakpoint(input) {
+  if (input.kind !== "spec") throw new BreakpointError("A plan document takes a spec breakpoint", 400);
+  const doc = typeof input.docUid === "string" ? rowsOf("SELECT uid, plan_uid FROM plan_documents WHERE uid = ?", [input.docUid])[0] : void 0;
+  if (!doc) throw new BreakpointError("Document not found", 404);
+  const existing = rowsOf(`${ACTIVE_SELECT} AND b.kind = 'spec' AND b.target = ?`, [doc.uid])[0];
+  if (existing) return { breakpoint: toBreakpoint(existing), created: false };
+  const id = `bp_${(0, import_node_crypto.randomBytes)(6).toString("hex")}`;
+  (0, import_database.getDb)().run(
+    "INSERT INTO breakpoints (id, kind, target, plan_uid, note, created_at, created_by, created_by_type) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+    [id, "spec", doc.uid, doc.plan_uid, cleanNote(input.note), input.now ?? Date.now(), input.by, input.byType]
+  );
+  return { breakpoint: getBreakpoint(id), created: true };
+}
+function docBreakpoint(docUid) {
+  const r = rowsOf(`${ACTIVE_SELECT} AND b.kind = 'spec' AND b.target = ?`, [docUid])[0];
+  return r ? toBreakpoint(r) : null;
+}
+const SYMBOL_RE = /^[A-Za-z_$][\w$.#()]{0,99}$/;
+function codeTarget(projectRoot, rawPath, rawSymbol) {
+  if (typeof rawPath !== "string") throw new BreakpointError("A code breakpoint needs a path in the project", 400);
+  let p = rawPath.trim().replace(/^\.\/+/, "");
+  const folderHint = p.endsWith("/");
+  p = p.replace(/\/+$/, "").replace(/\/{2,}/g, "/");
+  if (!p || p.length > 300 || p.includes("\0") || p.includes("\\") || p.startsWith("/") || /^[A-Za-z]:/.test(p) || p.startsWith("~") || p.split("/").some((x) => x === ".." || x === "." || x === "")) {
+    throw new BreakpointError("A code breakpoint's path must be relative to the project, with no ..", 400);
+  }
+  let stat;
+  try {
+    stat = import_node_fs.default.statSync(import_node_path.default.join(projectRoot, p));
+  } catch {
+    throw new BreakpointError(`No ${p} in the opened project`, 404);
+  }
+  const folder = stat.isDirectory();
+  if (folderHint && !folder) throw new BreakpointError(`${p} is a file, not a folder`, 400);
+  if (rawSymbol !== void 0 && rawSymbol !== null && rawSymbol !== "") {
+    if (folder) throw new BreakpointError("A function breakpoint is on a file, not a folder", 400);
+    if (typeof rawSymbol !== "string" || !SYMBOL_RE.test(rawSymbol)) throw new BreakpointError("symbol must be a name from the file", 400);
+    return `${p}#${rawSymbol}`;
+  }
+  return folder ? `${p}/` : p;
+}
+function codeScope(target) {
+  const i = target.indexOf("#");
+  return i === -1 ? target : target.slice(0, i);
+}
+function codeCovers(target, file) {
+  const scope = codeScope(target);
+  return scope.endsWith("/") ? file.startsWith(scope) : file === scope;
+}
+function setCodeBreakpoint(input) {
+  if (!input.projectRoot) throw new BreakpointError("No project is open", 409);
+  const target = codeTarget(input.projectRoot, input.path, input.symbol);
+  const existing = rowsOf(`${ACTIVE_SELECT} AND b.kind = 'code' AND b.target = ? AND b.project_root = ?`, [target, input.projectRoot])[0];
+  if (existing) return { breakpoint: toBreakpoint(existing), created: false };
+  const id = `bp_${(0, import_node_crypto.randomBytes)(6).toString("hex")}`;
+  (0, import_database.getDb)().run(
+    "INSERT INTO breakpoints (id, kind, target, project_root, note, created_at, created_by, created_by_type) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+    [id, "code", target, input.projectRoot, cleanNote(input.note), input.now ?? Date.now(), input.by, input.byType]
+  );
+  return { breakpoint: getBreakpoint(id), created: true };
+}
+function setSignalBreakpoint(input) {
+  if (!input.projectRoot) throw new BreakpointError("No project is open", 409);
+  if (!import_types.SIGNAL_BREAK_KINDS.includes(input.signal)) {
+    throw new BreakpointError(`signal must be one of ${import_types.SIGNAL_BREAK_KINDS.join(", ")}`, 400);
+  }
+  const target = input.signal;
+  const existing = rowsOf(`${ACTIVE_SELECT} AND b.kind = 'signal' AND b.target = ? AND b.project_root = ?`, [target, input.projectRoot])[0];
+  if (existing) return { breakpoint: toBreakpoint(existing), created: false };
+  const id = `bp_${(0, import_node_crypto.randomBytes)(6).toString("hex")}`;
+  (0, import_database.getDb)().run(
+    "INSERT INTO breakpoints (id, kind, target, project_root, note, created_at, created_by, created_by_type) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+    [id, "signal", target, input.projectRoot, cleanNote(input.note), input.now ?? Date.now(), input.by, input.byType]
+  );
+  return { breakpoint: getBreakpoint(id), created: true };
+}
+function clearBreakpoint(input) {
+  const bp = getBreakpoint(input.id);
+  if (!bp) return { cleared: false, released: [] };
+  if (bp.kind === "proposal") throw new BreakpointError("A spec proposal is decided on the proposal: accept, amend or reject", 400);
+  const now = input.now ?? Date.now();
+  (0, import_database.getDb)().run("UPDATE breakpoints SET cleared_at = ?, cleared_by = ?, cleared_by_type = ? WHERE id = ?", [now, input.by, input.byType, bp.id]);
+  const released = [];
+  for (const hit of listHits({ state: "waiting" }).filter((h) => h.breakpointId === bp.id)) {
+    const answered = answerHit({ ref: hit.ref, decision: "continue", note: "The breakpoint was cleared.", by: input.by, byType: input.byType, now });
+    if (answered) released.push(answered);
+  }
+  return { cleared: true, released };
+}
+function breakpointFor(kind, action, chain) {
+  const set = rowsOf(`${ACTIVE_SELECT} AND b.kind = ? AND b.plan_uid = ? ORDER BY b.created_at`, [kind, chain[0].plan_uid]).map(toBreakpoint);
+  if (!set.length) return null;
+  for (const row of chain) {
+    const bp = set.find((b) => b.target === row.uid);
+    if (bp) return bp;
+  }
+  if (action === "delete") {
+    const deleted = chain[0].uid;
+    return set.find((b) => lineage(b.target).some((r) => r.uid === deleted)) ?? null;
+  }
+  return null;
+}
+function specBreakpointOn(itemUid) {
+  try {
+    const chain = lineage(itemUid);
+    return chain.length ? breakpointFor("spec", "edit", chain) : null;
+  } catch {
+    return null;
+  }
+}
+const HIT_SELECT = `SELECT h.*, b.kind, b.note AS bp_note, b.target AS bp_target, COALESCE(i.title, d.title) AS title
+  FROM breakpoint_hits h LEFT JOIN breakpoints b ON b.id = h.breakpoint_id LEFT JOIN plan_items i ON i.uid = h.item_uid
+  LEFT JOIN plan_documents d ON d.uid = h.item_uid`;
+function toHitRow(r) {
+  return toHit(r);
+}
+function relianceOf(r) {
+  if (r.kind !== "spec" || r.action !== "edit" || Number(r.breach) === 1) return null;
+  const rel = (0, import_spec_links_service.reliedOnBy)(r.item_uid);
+  if (rel.length === 0) return null;
+  return { tasks: new Set(rel.map((x) => x.itemUid)).size, plans: new Set(rel.map((x) => x.planUid)).size };
+}
+function diskChangeOf(r) {
+  if (r.action !== "disk") return null;
+  const held = rowsOf("SELECT title, body FROM plan_doc_disk_holds WHERE ref = ?", [r.ref])[0];
+  const doc = rowsOf("SELECT title, body FROM plan_documents WHERE uid = ?", [r.item_uid])[0];
+  if (!held || !doc) return null;
+  return { beforeTitle: doc.title, afterTitle: held.title, before: doc.body, after: held.body };
+}
+function toHit(r) {
+  const reliedOn = relianceOf(r);
+  const diskChange = diskChangeOf(r);
+  return {
+    ref: r.ref,
+    breakpointId: r.breakpoint_id,
+    kind: r.kind ?? null,
+    breakpointNote: r.bp_note ?? null,
+    breakpointTarget: r.bp_target ?? null,
+    tool: r.tool,
+    action: r.action,
+    itemUid: r.item_uid,
+    itemTitle: r.title ?? null,
+    path: r.path ?? null,
+    breach: Number(r.breach) === 1,
+    signalId: r.signal_id ?? null,
+    planUid: r.plan_uid,
+    agent: r.agent,
+    sessionId: r.session_id,
+    workstreamRoot: r.workstream_root,
+    hitAt: Number(r.hit_at),
+    decision: r.decision ?? null,
+    note: r.note,
+    answeredAt: r.answered_at === null ? null : Number(r.answered_at),
+    answeredBy: r.answered_by,
+    answeredByType: r.answered_by_type,
+    ...reliedOn ? { reliedOn } : {},
+    ...diskChange ? { diskChange } : {}
+  };
+}
+function getHit(ref) {
+  const r = rowsOf(`${HIT_SELECT} WHERE h.ref = ?`, [ref])[0];
+  return r ? toHit(r) : null;
+}
+function countWaitingHits() {
+  return Number(rowsOf("SELECT COUNT(*) AS n FROM breakpoint_hits h WHERE h.answered_at IS NULL")[0]?.n ?? 0);
+}
+function listHits(q = {}) {
+  const where = [];
+  const params = [];
+  if ((q.state ?? "waiting") === "waiting") where.push("h.answered_at IS NULL");
+  if (q.planUid) {
+    where.push("h.plan_uid = ?");
+    params.push(q.planUid);
+  }
+  const sql = `${HIT_SELECT}${where.length ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY h.hit_at DESC LIMIT 200`;
+  return rowsOf(sql, params).map(toHit).reverse();
+}
+function hitPayload(hit) {
+  return {
+    ref: hit.ref,
+    kind: hit.kind,
+    action: hit.action,
+    tool: hit.tool,
+    itemUid: hit.itemUid,
+    itemTitle: hit.itemTitle,
+    ...hit.path ? { path: hit.path } : {},
+    ...hit.breach ? { breach: true } : {},
+    ...hit.signalId ? { signalId: hit.signalId } : {},
+    planUid: hit.planUid,
+    agent: hit.agent,
+    ...hit.workstreamRoot ? { workstreamRoot: hit.workstreamRoot } : {},
+    ...hit.reliedOn ? { reliedOn: hit.reliedOn } : {}
+  };
+}
+const answeredListeners = [];
+function onHitAnswered(fn) {
+  answeredListeners.push(fn);
+}
+function answerHit(input) {
+  const hit = getHit(input.ref);
+  if (!hit || hit.answeredAt !== null) return null;
+  const note = cleanNote(input.note);
+  (0, import_database.getDb)().run(
+    "UPDATE breakpoint_hits SET decision = ?, note = ?, answered_at = ?, answered_by = ?, answered_by_type = ? WHERE ref = ? AND answered_at IS NULL",
+    [input.decision, note, input.now ?? Date.now(), input.by, input.byType, input.ref]
+  );
+  const answered = getHit(input.ref);
+  (0, import_agent_event_log.recordBreakpointEvent)("breakpoint_answered", {
+    ...hitPayload(answered),
+    decision: answered.decision,
+    note: answered.note,
+    waitedMs: (answered.answeredAt ?? 0) - answered.hitAt,
+    by: input.by,
+    byType: input.byType
+  }, input.byType);
+  for (const fn of answeredListeners) {
+    try {
+      fn(answered);
+    } catch (err) {
+      console.warn("[Breakpoints] answer listener failed:", err);
+    }
+  }
+  return answered;
+}
+function workstreamOf(sessionId) {
+  if (!sessionId) return null;
+  try {
+    return rowsOf("SELECT workstream_root AS root FROM agent_sessions WHERE session_id = ?", [sessionId])[0]?.root ?? null;
+  } catch {
+    return null;
+  }
+}
+function enforce(tool, args, caller, now = Date.now()) {
+  let call;
+  let chain;
+  try {
+    call = guardedCall(tool, args);
+    if (!call) return { kind: "pass" };
+    chain = lineage(call.itemUid);
+    if (!chain.length) return { kind: "pass" };
+  } catch {
+    return { kind: "pass" };
+  }
+  for (const { action, kind } of call.actions) {
+    let bp;
+    try {
+      bp = breakpointFor(kind, action, chain);
+    } catch {
+      bp = null;
+    }
+    if (!bp) continue;
+    const open = rowsOf(
+      `${HIT_SELECT} WHERE h.breakpoint_id = ? AND h.item_uid = ? AND h.action = ? AND h.agent = ? AND h.consumed_at IS NULL ORDER BY h.hit_at`,
+      [bp.id, call.itemUid, action, caller.agent]
+    ).map(toHit);
+    const answered = open.find((h) => h.answeredAt !== null);
+    if (answered) {
+      (0, import_database.getDb)().run("UPDATE breakpoint_hits SET consumed_at = ? WHERE ref = ?", [now, answered.ref]);
+      if (answered.decision === "stop") return { kind: "stop", hit: answered };
+      continue;
+    }
+    const waiting = open.find((h) => h.answeredAt === null);
+    if (waiting) return { kind: "paused", hit: waiting, fresh: false };
+    const ref = `bp-${(0, import_node_crypto.randomBytes)(5).toString("hex")}`;
+    (0, import_database.getDb)().run(
+      `INSERT INTO breakpoint_hits (ref, breakpoint_id, tool, action, item_uid, plan_uid, agent, session_id, workstream_root, hit_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [ref, bp.id, tool, action, call.itemUid, chain[0].plan_uid, caller.agent, caller.sessionId, workstreamOf(caller.sessionId), now]
+    );
+    const hit = getHit(ref);
+    (0, import_agent_event_log.recordBreakpointEvent)("breakpoint_hit", { ...hitPayload(hit), breakpointId: bp.id, on: bp.target, onTitle: bp.targetTitle }, caller.agent);
+    void (0, import_push_notification_service.pushForBreakpoint)(hit).catch(() => {
+    });
+    return { kind: "paused", hit, fresh: true };
+  }
+  const spent = rowsOf(
+    `${HIT_SELECT} WHERE h.item_uid = ? AND h.agent = ? AND h.consumed_at = ? ORDER BY h.answered_at DESC`,
+    [call.itemUid, caller.agent, now]
+  ).map(toHit)[0];
+  return spent ? { kind: "continue", hit: spent } : { kind: "pass" };
+}
+const DOING = {
+  claim: "claiming",
+  done: "marking done",
+  edit: "changing the description of",
+  delete: "deleting",
+  edit_code: "changing",
+  breach: "changing",
+  propose: "changing the spec",
+  disk: "changing"
+};
+function subjectOf(hit) {
+  return hit.path ?? hit.itemTitle ?? hit.itemUid;
+}
+function said(hit) {
+  return hit.answeredByType === "human" ? "A person" : `Someone (${hit.answeredByType ?? "unknown"})`;
+}
+function reliance(hit) {
+  if (!hit.reliedOn) return null;
+  const rel = (0, import_spec_links_service.reliedOnBy)(hit.itemUid);
+  if (rel.length === 0) return null;
+  const names = rel.slice(0, 4).map((a) => `"${a.title}" (${a.planTitle})`).join(", ");
+  const more = rel.length > 4 ? ` and ${rel.length - 4} more` : "";
+  const tasks = new Set(rel.map((x) => x.itemUid)).size;
+  const plans = new Set(rel.map((x) => x.planUid)).size;
+  return {
+    reliedOnBy: rel.map((a) => ({ uid: a.itemUid, title: a.title, plan: a.planTitle })),
+    line: ` ${tasks} ${tasks === 1 ? "task" : "tasks"} in ${plans} ${plans === 1 ? "plan" : "plans"} ${tasks === 1 ? "relies" : "rely"} on this page: ${names}${more}. To change a spec others rely on, propose it instead: propose_spec_change(page_uid, section, text, why) is not held, tells their agents so they can say what it means for their work, and a person decides it. If you propose instead, await the proposal's decision rather than this one: this pause stays in the person's inbox for them to answer.`
+  };
+}
+function pausedResult(hit) {
+  const what = `${DOING[hit.action]} \u201C${subjectOf(hit)}\u201D`;
+  const rel = reliance(hit);
+  const body = {
+    paused: true,
+    status: "paused: waiting for a decision",
+    ref: hit.ref,
+    breakpoint: { kind: hit.kind, note: hit.breakpointNote },
+    ...rel ? { reliedOnBy: rel.reliedOnBy } : {},
+    message: `paused: waiting for a decision. A person set a breakpoint and wants to be asked before ${what}. Nothing was done. Call await_decision with this ref and wait for their answer, calling it again while it says it is still waiting (this can take a long time; do not work around it). If they say continue, make the same call again.${rel ? rel.line : ""}`
+  };
+  return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }], _meta: { summary: `Paused at a breakpoint before ${what}` } };
+}
+function stoppedResult(hit) {
+  const body = {
+    stopped: true,
+    ref: hit.ref,
+    note: hit.note,
+    message: `${said(hit)} answered your breakpoint: stop. Nothing was done.${hit.note ? ` Their note: ${hit.note}` : ""} Do not make this call again unless they ask you to.`
+  };
+  return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }], _meta: { summary: "Stopped at a breakpoint" } };
+}
+function steerText(hit) {
+  if (!hit.note) return null;
+  return `${said(hit)} answered your breakpoint (${hit.ref}): continue, with this steer: ${hit.note}`;
+}
+function decisionView(hit) {
+  if (hit.answeredAt === null) {
+    return {
+      status: "waiting",
+      ref: hit.ref,
+      waitingSince: new Date(hit.hitAt).toISOString(),
+      message: "Still waiting for a person. Call await_decision again with the same ref. Do not make the paused call again until they answer."
+    };
+  }
+  if (hit.action === "propose") {
+    return {
+      status: "answered",
+      ref: hit.ref,
+      decision: hit.decision === "stop" ? "rejected" : "accepted",
+      note: hit.note,
+      by: hit.answeredByType,
+      at: new Date(hit.answeredAt).toISOString(),
+      message: hit.decision === "stop" ? "The spec change was not accepted. Carry on with the spec as it is; the note says why." : "The spec change was accepted and the page has its new version. Work to it."
+    };
+  }
+  const fnAt = hit.breakpointTarget ? hit.breakpointTarget.indexOf("#") : -1;
+  const code = fnAt > 0 && hit.breakpointTarget ? `${hit.breakpointTarget.slice(fnAt + 1)} in ${hit.path}` : hit.path;
+  const next = hit.breach ? hit.decision === "stop" ? `Stop changing ${code}. Tell the person what you changed there, so they can review or revert it.` : "Carry on; the person has seen the change." : hit.action === "edit_code" ? hit.decision === "stop" ? `Do not change ${code}. Tell the person what you will do instead.` : `Make the edit again; ${code} is open to you now.` : hit.decision === "stop" ? "Do not make the paused call. Stop that work, and tell the person what you will do instead." : "Make the paused call again; it will go through once.";
+  return {
+    status: "answered",
+    ref: hit.ref,
+    decision: hit.decision,
+    note: hit.note,
+    by: hit.answeredByType,
+    at: new Date(hit.answeredAt).toISOString(),
+    message: next
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ACTIVE_SELECT,
+  BREAKPOINT_KINDS,
+  BreakpointError,
+  DECISIONS,
+  HIT_SELECT,
+  MAX_NOTE,
+  SIGNAL_BREAK_KINDS,
+  answerHit,
+  cleanNote,
+  clearBreakpoint,
+  codeCovers,
+  codeScope,
+  codeTarget,
+  countWaitingHits,
+  decisionView,
+  docBreakpoint,
+  enforce,
+  getBreakpoint,
+  getHit,
+  guardedCall,
+  hitPayload,
+  listBreakpoints,
+  listHits,
+  onHitAnswered,
+  pausedResult,
+  rowsOf,
+  setBreakpoint,
+  specBreakpointOn,
+  steerText,
+  stoppedResult,
+  subjectOf,
+  toBreakpointRow,
+  toHitRow
+});