codetrellis 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,324 @@
+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 settings_service_exports = {};
+__export(settings_service_exports, {
+  SettingsError: () => SettingsError,
+  getAuthorKey: () => getAuthorKey,
+  getSettings: () => getSettings,
+  maybeSeedIdentityFromGit: () => maybeSeedIdentityFromGit,
+  mergeWithDefaults: () => mergeWithDefaults,
+  readGitIdentity: () => readGitIdentity,
+  resetSettingsCache: () => resetSettingsCache,
+  settingsPatchProblem: () => settingsPatchProblem,
+  updateSettings: () => updateSettings
+});
+module.exports = __toCommonJS(settings_service_exports);
+var import_node_fs = __toESM(require("node:fs"));
+var import_node_path = __toESM(require("node:path"));
+var import_node_child_process = require("node:child_process");
+var import_types = require("../../shared/types");
+var import_persistence = require("./persistence");
+var import_peer_capabilities = require("./peer-capabilities");
+let cached = null;
+function getSettingsPath() {
+  return import_node_path.default.join((0, import_persistence.getSettingsDir)(), "settings.json");
+}
+function getSettings() {
+  if (cached) return cached;
+  const filePath = getSettingsPath();
+  if (!import_node_fs.default.existsSync(filePath)) {
+    cached = { ...import_types.DEFAULT_SETTINGS };
+    return cached;
+  }
+  try {
+    const raw = JSON.parse(import_node_fs.default.readFileSync(filePath, "utf-8"));
+    cached = mergeWithDefaults(raw);
+    return cached;
+  } catch (err) {
+    console.warn("[Settings] Failed to read settings.json \u2014 using defaults:", err);
+    cached = { ...import_types.DEFAULT_SETTINGS };
+    return cached;
+  }
+}
+function settingsPatchProblem(patch) {
+  if (patch === null || typeof patch !== "object" || Array.isArray(patch)) return "settings must be an object";
+  const p = patch;
+  const section = (name) => {
+    const v = p[name];
+    if (v === void 0) return null;
+    if (v === null || typeof v !== "object" || Array.isArray(v)) return `${name} must be an object`;
+    return v;
+  };
+  const checks = [
+    ["identity.displayName", (v) => typeof v === "string", "text"],
+    ["identity.email", (v) => typeof v === "string", "text"],
+    ["mcp.port", (v) => Number.isInteger(v) && v >= 1024 && v <= 65535, "a port from 1024 to 65535"],
+    ["mcp.autodetectOnCollision", (v) => typeof v === "boolean", "true or false"],
+    [
+      "mcp.capabilities",
+      (v) => Array.isArray(v) && v.every((c) => typeof c === "string" && import_peer_capabilities.ALL_CAPABILITIES.includes(c)),
+      `a list of: ${import_peer_capabilities.ALL_CAPABILITIES.join(", ")}`
+    ],
+    ["mcp.projectScope", (v) => v === "opened" || v === "anywhere", "opened or anywhere"],
+    ["mcp.acceptLocalApiChanges", (v) => typeof v === "boolean", "true or false"],
+    ["plans.defaultVisibility", (v) => v === "shared" || v === "local", "shared or local"],
+    ["plans.attachmentLocation", (v) => v === "project" || v === "user", "project or user"],
+    ["data.dataDirOverride", (v) => typeof v === "string", "text"],
+    ["data.personalSyncPath", (v) => typeof v === "string", "text"],
+    ["data.personalSyncMode", (v) => ["none", "selective", "full"].includes(v), "none, selective or full"],
+    ["device.deviceName", (v) => typeof v === "string", "text"],
+    ["device.advertise", (v) => typeof v === "boolean", "true or false"],
+    ["device.exposeMobileApi", (v) => typeof v === "boolean", "true or false"],
+    ["device.shareAudio", (v) => typeof v === "boolean", "true or false"],
+    ["device.mobileApiPort", (v) => Number.isInteger(v) && v >= 1024 && v <= 65535, "a port from 1024 to 65535"],
+    ["power.preventLidCloseSleep", (v) => typeof v === "boolean", "true or false"],
+    ["power.onlyWhenOnAC", (v) => typeof v === "boolean", "true or false"],
+    ["webhooks.allowedHosts", (v) => Array.isArray(v) && v.every((h) => typeof h === "string"), "a list of host names"],
+    ["webhooks.allowLoopback", (v) => typeof v === "boolean", "true or false"],
+    ["updates.autoCheck", (v) => typeof v === "boolean", "true or false"],
+    ["git.keepRemotesCurrent", (v) => typeof v === "boolean", "true or false"],
+    ["git.everyMinutes", (v) => import_types.FETCH_INTERVAL_CHOICES.includes(v), `${import_types.FETCH_INTERVAL_CHOICES.join(", ")} minutes`],
+    ["data.retentionDays", (v) => import_types.RETENTION_CHOICES.includes(v), "14, 30, 90 or 365 days, or null to keep everything"]
+  ];
+  for (const name of ["identity", "mcp", "plans", "data", "device", "power", "webhooks", "updates", "git"]) {
+    const sec = section(name);
+    if (typeof sec === "string") return sec;
+  }
+  for (const [dotted, ok, want] of checks) {
+    const [sec, key] = dotted.split(".");
+    const v = p[sec]?.[key];
+    if (v !== void 0 && !ok(v)) return `${dotted} must be ${want}`;
+  }
+  const triggers = p.power?.triggers;
+  if (triggers !== void 0) {
+    if (triggers === null || typeof triggers !== "object" || Array.isArray(triggers)) return "power.triggers must be an object";
+    for (const k of ["whileMobileConnected", "whileAgentActive", "always"]) {
+      if (triggers[k] !== void 0 && typeof triggers[k] !== "boolean") return `power.triggers.${k} must be true or false`;
+    }
+  }
+  if (p.firstRunComplete !== void 0 && typeof p.firstRunComplete !== "boolean") return "firstRunComplete must be true or false";
+  return null;
+}
+class SettingsError extends Error {
+}
+function updateSettings(patch) {
+  const problem = settingsPatchProblem(patch);
+  if (problem) throw new SettingsError(problem);
+  const current = getSettings();
+  const next = {
+    identity: { ...current.identity, ...patch.identity ?? {} },
+    mcp: { ...current.mcp, ...patch.mcp ?? {} },
+    plans: { ...current.plans, ...patch.plans ?? {} },
+    data: { ...current.data, ...patch.data ?? {} },
+    device: { ...current.device, ...patch.device ?? {} },
+    power: {
+      ...current.power,
+      ...patch.power ?? {},
+      // triggers is a nested object — preserve unspecified flags
+      // instead of letting a partial { triggers: { always: true } }
+      // patch wipe whileMobileConnected / whileAgentActive.
+      triggers: {
+        ...current.power.triggers,
+        ...patch.power?.triggers ?? {}
+      }
+    },
+    webhooks: {
+      ...current.webhooks,
+      ...patch.webhooks ?? {},
+      // Replace rather than merge: removing a host must actually remove it.
+      allowedHosts: Array.isArray(patch.webhooks?.allowedHosts) ? patch.webhooks.allowedHosts : current.webhooks.allowedHosts
+    },
+    updates: {
+      autoCheck: typeof patch.updates?.autoCheck === "boolean" ? patch.updates.autoCheck : current.updates.autoCheck
+    },
+    git: { ...current.git, ...patch.git ?? {} },
+    firstRunComplete: patch.firstRunComplete ?? current.firstRunComplete,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  if (next.mcp.port < 1024 || next.mcp.port > 65535) {
+    next.mcp.port = import_types.DEFAULT_SETTINGS.mcp.port;
+  }
+  next.webhooks.allowedHosts = [...new Set(
+    (next.webhooks.allowedHosts ?? []).filter((h) => typeof h === "string").map((h) => h.trim().toLowerCase()).filter((h) => h.length > 0 && h.length <= 253 && !h.includes("*") && !h.includes("/"))
+  )];
+  cached = next;
+  saveSettings(next);
+  return next;
+}
+function readGitIdentity(projectPath) {
+  const cwd = projectPath && import_node_fs.default.existsSync(projectPath) ? projectPath : process.cwd();
+  const safeRun = (args) => {
+    try {
+      return (0, import_node_child_process.execSync)(`git config --get ${args}`, {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }).trim();
+    } catch {
+      return "";
+    }
+  };
+  return {
+    name: safeRun("user.name"),
+    email: safeRun("user.email")
+  };
+}
+function getAuthorKey(role = "human") {
+  const { email } = getSettings().identity;
+  return email || role;
+}
+function maybeSeedIdentityFromGit(projectPath) {
+  const current = getSettings();
+  const haveEmail = !!current.identity.email;
+  const haveDisplayName = !!current.identity.displayName;
+  if (haveEmail && haveDisplayName) return false;
+  const gitIdentity = readGitIdentity(projectPath);
+  const patch = {};
+  if (!haveEmail && gitIdentity.email) {
+    patch.identity = { ...patch.identity ?? {}, email: gitIdentity.email };
+  }
+  if (!haveDisplayName && gitIdentity.name) {
+    patch.identity = { ...patch.identity ?? {}, displayName: gitIdentity.name };
+  }
+  if (!patch.identity) return false;
+  updateSettings(patch);
+  return true;
+}
+function resetSettingsCache() {
+  cached = null;
+}
+function saveSettings(settings) {
+  const filePath = getSettingsPath();
+  try {
+    const dir = (0, import_persistence.getSettingsDir)();
+    if (!import_node_fs.default.existsSync(dir)) {
+      import_node_fs.default.mkdirSync(dir, { recursive: true });
+    }
+    const tmpPath = `${filePath}.tmp`;
+    import_node_fs.default.writeFileSync(tmpPath, JSON.stringify(settings, null, 2));
+    import_node_fs.default.renameSync(tmpPath, filePath);
+  } catch (err) {
+    console.error("[Settings] Failed to save settings.json:", err);
+  }
+}
+function mergeWithDefaults(raw) {
+  if (!raw || typeof raw !== "object") return { ...import_types.DEFAULT_SETTINGS };
+  return {
+    identity: {
+      displayName: typeof raw?.identity?.displayName === "string" ? raw.identity.displayName : import_types.DEFAULT_SETTINGS.identity.displayName,
+      email: typeof raw?.identity?.email === "string" ? raw.identity.email : import_types.DEFAULT_SETTINGS.identity.email
+    },
+    mcp: {
+      port: typeof raw?.mcp?.port === "number" ? raw.mcp.port : import_types.DEFAULT_SETTINGS.mcp.port,
+      autodetectOnCollision: typeof raw?.mcp?.autodetectOnCollision === "boolean" ? raw.mcp.autodetectOnCollision : import_types.DEFAULT_SETTINGS.mcp.autodetectOnCollision,
+      // Phase 30. Validated against the real capability names rather than
+      // trusted: this list is what the authorisation gate reads, so a
+      // malformed settings file must not be able to widen it. An absent or
+      // invalid value leaves it undefined, which the gate reads as
+      // DEFAULT_GRANTS — the narrower answer.
+      // Spread rather than assigned, so an absent grant list stays ABSENT
+      // rather than becoming an explicit `undefined`. The gate reads absent
+      // as DEFAULT_GRANTS, and a key that exists with no value is a
+      // different thing from a key that was never written.
+      ...Array.isArray(raw?.mcp?.capabilities) ? {
+        capabilities: raw.mcp.capabilities.filter(
+          (c) => typeof c === "string" && import_peer_capabilities.ALL_CAPABILITIES.includes(c)
+        )
+      } : {},
+      // An existing settings file predates this field, and the secure value
+      // is the default rather than the permissive one — so an upgrade
+      // CONFINES path-taking tools rather than leaving them open because
+      // nobody had an opinion yet.
+      projectScope: raw?.mcp?.projectScope === "anywhere" ? "anywhere" : "opened",
+      // Carried item 2b. Only an explicit false turns local API changes off;
+      // anything else (absent, malformed) leaves them on, as before.
+      ...raw?.mcp?.acceptLocalApiChanges === false ? { acceptLocalApiChanges: false } : {}
+    },
+    plans: {
+      defaultVisibility: raw?.plans?.defaultVisibility === "local" ? "local" : import_types.DEFAULT_SETTINGS.plans.defaultVisibility,
+      attachmentLocation: raw?.plans?.attachmentLocation === "user" ? "user" : import_types.DEFAULT_SETTINGS.plans.attachmentLocation
+    },
+    data: {
+      dataDirOverride: typeof raw?.data?.dataDirOverride === "string" ? raw.data.dataDirOverride : import_types.DEFAULT_SETTINGS.data.dataDirOverride,
+      personalSyncPath: typeof raw?.data?.personalSyncPath === "string" ? raw.data.personalSyncPath : import_types.DEFAULT_SETTINGS.data.personalSyncPath,
+      personalSyncMode: ["none", "selective", "full"].includes(raw?.data?.personalSyncMode) ? raw.data.personalSyncMode : import_types.DEFAULT_SETTINGS.data.personalSyncMode,
+      retentionDays: import_types.RETENTION_CHOICES.includes(raw?.data?.retentionDays) ? raw.data.retentionDays : import_types.DEFAULT_SETTINGS.data.retentionDays
+    },
+    device: {
+      deviceName: typeof raw?.device?.deviceName === "string" ? raw.device.deviceName : import_types.DEFAULT_SETTINGS.device.deviceName,
+      advertise: typeof raw?.device?.advertise === "boolean" ? raw.device.advertise : import_types.DEFAULT_SETTINGS.device.advertise,
+      // Deliberately does NOT inherit from `advertise` for existing profiles.
+      // Someone who turned advertising on before these were separated was
+      // consenting to discovery, not to a 0.0.0.0 listener they were never
+      // shown. Defaulting to false makes them opt in explicitly.
+      exposeMobileApi: typeof raw?.device?.exposeMobileApi === "boolean" ? raw.device.exposeMobileApi : import_types.DEFAULT_SETTINGS.device.exposeMobileApi,
+      shareAudio: typeof raw?.device?.shareAudio === "boolean" ? raw.device.shareAudio : import_types.DEFAULT_SETTINGS.device.shareAudio,
+      mobileApiPort: typeof raw?.device?.mobileApiPort === "number" && raw.device.mobileApiPort > 0 ? raw.device.mobileApiPort : import_types.DEFAULT_SETTINGS.device.mobileApiPort
+    },
+    power: {
+      triggers: {
+        whileMobileConnected: typeof raw?.power?.triggers?.whileMobileConnected === "boolean" ? raw.power.triggers.whileMobileConnected : import_types.DEFAULT_SETTINGS.power.triggers.whileMobileConnected,
+        whileAgentActive: typeof raw?.power?.triggers?.whileAgentActive === "boolean" ? raw.power.triggers.whileAgentActive : import_types.DEFAULT_SETTINGS.power.triggers.whileAgentActive,
+        always: typeof raw?.power?.triggers?.always === "boolean" ? raw.power.triggers.always : import_types.DEFAULT_SETTINGS.power.triggers.always
+      },
+      preventLidCloseSleep: typeof raw?.power?.preventLidCloseSleep === "boolean" ? raw.power.preventLidCloseSleep : import_types.DEFAULT_SETTINGS.power.preventLidCloseSleep,
+      onlyWhenOnAC: typeof raw?.power?.onlyWhenOnAC === "boolean" ? raw.power.onlyWhenOnAC : import_types.DEFAULT_SETTINGS.power.onlyWhenOnAC
+    },
+    webhooks: {
+      // Normalised hard, because this list is what stands between a cloned
+      // repository and an outbound request from inside the user's network
+      // (Phase 19, finding 20). Anything that is not a plain non-empty string
+      // is dropped rather than coerced.
+      allowedHosts: Array.isArray(raw?.webhooks?.allowedHosts) ? [...new Set(
+        raw.webhooks.allowedHosts.filter((h) => typeof h === "string").map((h) => h.trim().toLowerCase()).filter((h) => h.length > 0 && h.length <= 253 && !h.includes("*") && !h.includes("/"))
+      )] : [...import_types.DEFAULT_SETTINGS.webhooks.allowedHosts],
+      allowLoopback: typeof raw?.webhooks?.allowLoopback === "boolean" ? raw.webhooks.allowLoopback : import_types.DEFAULT_SETTINGS.webhooks.allowLoopback
+    },
+    updates: {
+      autoCheck: typeof raw?.updates?.autoCheck === "boolean" ? raw.updates.autoCheck : import_types.DEFAULT_SETTINGS.updates.autoCheck
+    },
+    git: {
+      keepRemotesCurrent: typeof raw?.git?.keepRemotesCurrent === "boolean" ? raw.git.keepRemotesCurrent : import_types.DEFAULT_SETTINGS.git.keepRemotesCurrent,
+      everyMinutes: import_types.FETCH_INTERVAL_CHOICES.includes(raw?.git?.everyMinutes) ? raw.git.everyMinutes : import_types.DEFAULT_SETTINGS.git.everyMinutes
+    },
+    firstRunComplete: typeof raw?.firstRunComplete === "boolean" ? raw.firstRunComplete : import_types.DEFAULT_SETTINGS.firstRunComplete,
+    updatedAt: typeof raw?.updatedAt === "string" ? raw.updatedAt : ""
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SettingsError,
+  getAuthorKey,
+  getSettings,
+  maybeSeedIdentityFromGit,
+  mergeWithDefaults,
+  readGitIdentity,
+  resetSettingsCache,
+  settingsPatchProblem,
+  updateSettings
+});

package/src/backend/services/signal-breakpoints.js

@@ -0,0 +1,172 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var signal_breakpoints_exports = {};
+__export(signal_breakpoints_exports, {
+  SIGNAL_MARKER: () => SIGNAL_MARKER,
+  attemptOf: () => attemptOf,
+  enforceSignals: () => enforceSignals,
+  enforceSignalsForSession: () => enforceSignalsForSession,
+  releaseSettled: () => releaseSettled,
+  signalHeldResult: () => signalHeldResult,
+  signalHeldText: () => signalHeldText,
+  signalRules: () => signalRules,
+  signalSteerText: () => signalSteerText
+});
+module.exports = __toCommonJS(signal_breakpoints_exports);
+var import_node_crypto = require("node:crypto");
+var import_database = require("./database");
+var import_agent_event_log = require("./agent-event-log");
+var import_session_service = require("./session-service");
+var import_awareness_service = require("./awareness-service");
+var import_breakpoint_service = require("./breakpoint-service");
+var import_push_notification_service = require("./push-notification-service");
+function signalRules(projectRoot) {
+  return (0, import_breakpoint_service.rowsOf)(`${import_breakpoint_service.ACTIVE_SELECT} AND b.kind = 'signal' AND b.project_root = ? ORDER BY b.created_at`, [projectRoot]).map(import_breakpoint_service.toBreakpointRow);
+}
+function holding(signals, rule) {
+  return signals.filter((s) => s.kind === rule.target && s.severity === "high" && s.state === "open");
+}
+function releaseSettled(projectRoot, signals = (0, import_awareness_service.listSignals)(projectRoot), now = Date.now()) {
+  const open = new Set(signals.filter((s) => s.severity === "high" && s.state === "open").map((s) => s.id));
+  const waiting = (0, import_breakpoint_service.rowsOf)(
+    `${import_breakpoint_service.HIT_SELECT} WHERE b.kind = 'signal' AND b.project_root = ? AND h.answered_at IS NULL AND h.signal_id IS NOT NULL`,
+    [projectRoot]
+  ).map(import_breakpoint_service.toHitRow);
+  const released = [];
+  for (const hit of waiting) {
+    if (hit.signalId && open.has(hit.signalId)) continue;
+    const r = (0, import_breakpoint_service.answerHit)({ ref: hit.ref, decision: "continue", note: "The signal was answered in Awareness.", by: "CodeTrellis", byType: "system", now });
+    if (r) released.push(r);
+  }
+  return released;
+}
+function enforceSignals(projectRoot, caller, attempt, now = Date.now(), signalsOf = (root, ws) => (0, import_awareness_service.listSignals)(root, { workstream: ws })) {
+  if (!projectRoot || !caller.workstreamRoot) return { kind: "pass" };
+  let continued = null;
+  try {
+    const rules = signalRules(projectRoot);
+    if (!rules.length) return { kind: "pass" };
+    const mine = signalsOf(projectRoot, caller.workstreamRoot);
+    for (const rule of rules) {
+      for (const signal of holding(mine, rule)) {
+        const latest = (0, import_breakpoint_service.rowsOf)(
+          `${import_breakpoint_service.HIT_SELECT} WHERE h.breakpoint_id = ? AND h.signal_id = ? AND h.workstream_root = ? ORDER BY h.hit_at DESC LIMIT 1`,
+          [rule.id, signal.id, caller.workstreamRoot]
+        ).map(import_breakpoint_service.toHitRow)[0];
+        if (!latest) {
+          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, path, breach, signal_id, agent, session_id, workstream_root, hit_at)
+             VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?)`,
+            [
+              ref,
+              rule.id,
+              attempt.tool,
+              attempt.action,
+              attempt.itemUid ?? "",
+              attempt.path ?? null,
+              signal.id,
+              caller.agent,
+              caller.sessionId,
+              caller.workstreamRoot,
+              now
+            ]
+          );
+          const hit = (0, import_breakpoint_service.getHit)(ref);
+          (0, import_agent_event_log.recordBreakpointEvent)("breakpoint_hit", {
+            ...(0, import_breakpoint_service.hitPayload)(hit),
+            breakpointId: rule.id,
+            signalKind: signal.kind,
+            signalSummary: signal.summary.slice(0, 300)
+          }, caller.agent);
+          void (0, import_push_notification_service.pushForBreakpoint)(hit).catch(() => {
+          });
+          return { kind: "paused", hit, signal, fresh: true };
+        }
+        if (latest.answeredAt === null) return { kind: "paused", hit: latest, signal, fresh: false };
+        if (latest.decision === "stop") return { kind: "stop", hit: latest, signal };
+        const untold = (0, import_breakpoint_service.rowsOf)("SELECT consumed_at FROM breakpoint_hits WHERE ref = ?", [latest.ref])[0]?.consumed_at === null;
+        if (untold) (0, import_database.getDb)().run("UPDATE breakpoint_hits SET consumed_at = ? WHERE ref = ?", [now, latest.ref]);
+        continued = { hit: latest, steer: untold ? latest.note : null };
+      }
+    }
+  } catch {
+    return { kind: "pass" };
+  }
+  return continued ? { kind: "continue", ...continued } : { kind: "pass" };
+}
+function attemptOf(tool, args) {
+  const call = (0, import_breakpoint_service.guardedCall)(tool, args);
+  if (!call) return null;
+  return { tool, action: call.actions[0].action, itemUid: call.itemUid };
+}
+function enforceSignalsForSession(projectRoot, sessionId, attempt, now = Date.now()) {
+  if (!projectRoot) return { kind: "pass" };
+  const session = (0, import_session_service.getActiveSessions)().find((s) => s.sessionId === sessionId);
+  if (!session?.workstreamRoot) return { kind: "pass" };
+  try {
+    releaseSettled(projectRoot);
+  } catch {
+  }
+  return enforceSignals(projectRoot, { agent: session.agentType ?? "mcp-agent", sessionId, workstreamRoot: session.workstreamRoot }, attempt, now);
+}
+const SIGNAL_MARKER = "\u2500\u2500 CodeTrellis breakpoint \u2500\u2500";
+function signalHeldText(result) {
+  const h = result.hit;
+  const about = result.signal ? `a serious ${result.signal.kind} signal: ${result.signal.summary}` : "a serious signal";
+  const rule = h.breakpointNote ? ` Their note on the rule: ${h.breakpointNote}` : "";
+  if (result.kind === "stop") {
+    return [
+      SIGNAL_MARKER,
+      `A person answered the breakpoint on ${about} \u2014 stop. Nothing was done.${h.note ? ` Their answer: ${h.note}` : ""}`,
+      "Do not go on with work this signal touches while it is open. Tell the person what you will do instead."
+    ].join("\n");
+  }
+  return [
+    SIGNAL_MARKER,
+    `paused: waiting for a decision. Your workstream is named in ${about}. A person asked to be asked before work goes on while a signal like this is open.${rule} Nothing was done.`,
+    `Call await_decision with ref "${h.ref}", calling it again while it says it is still waiting (this can take a long time; do not work around it). If they answer continue, make the same call again.`
+  ].join("\n");
+}
+function signalHeldResult(result) {
+  const body = {
+    ...result.kind === "paused" ? { paused: true, status: "paused: waiting for a decision" } : { stopped: true },
+    ref: result.hit.ref,
+    signal: result.signal ? { kind: result.signal.kind, summary: result.signal.summary } : null,
+    message: signalHeldText(result)
+  };
+  return {
+    content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
+    _meta: { summary: result.kind === "paused" ? `Paused at a breakpoint on a serious ${result.signal?.kind ?? ""} signal`.replace("  ", " ") : "Stopped at a signal breakpoint" }
+  };
+}
+function signalSteerText(hit) {
+  return hit.note ? `A person answered the signal breakpoint (${hit.ref}): continue, with this steer: ${hit.note}` : null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SIGNAL_MARKER,
+  attemptOf,
+  enforceSignals,
+  enforceSignalsForSession,
+  releaseSettled,
+  signalHeldResult,
+  signalHeldText,
+  signalRules,
+  signalSteerText
+});

package/src/backend/services/signed-approval-record.js

@@ -0,0 +1,86 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var signed_approval_record_exports = {};
+__export(signed_approval_record_exports, {
+  NAMESPACE: () => NAMESPACE,
+  RECORD_KIND: () => RECORD_KIND,
+  canonicalStatement: () => canonicalStatement,
+  parseRecord: () => parseRecord,
+  recordYaml: () => recordYaml,
+  sha256: () => sha256
+});
+module.exports = __toCommonJS(signed_approval_record_exports);
+var import_node_crypto = require("node:crypto");
+var import_yaml = require("yaml");
+const NAMESPACE = "codetrellis-approval";
+const RECORD_KIND = "codetrellis-approval";
+const MAX_RECORD_BYTES = 16 * 1024;
+const UID = /^[A-Za-z0-9-]{8,64}$/;
+const EMAIL = /^[^\s<>@]{1,64}@[^\s<>@]{1,255}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const sha256 = (text) => (0, import_node_crypto.createHash)("sha256").update(text, "utf-8").digest("hex");
+function canonicalStatement(s) {
+  const sort = (v) => {
+    if (Array.isArray(v)) return v.map(sort);
+    if (v && typeof v === "object") {
+      return Object.fromEntries(Object.keys(v).sort().map((k) => [k, sort(v[k])]));
+    }
+    return v;
+  };
+  return JSON.stringify(sort(s));
+}
+function recordYaml(statement, signature) {
+  return (0, import_yaml.stringify)({ kind: RECORD_KIND, version: 1, statement: canonicalStatement(statement), signature: signature.trim() });
+}
+function parseRecord(content) {
+  if (Buffer.byteLength(content, "utf-8") > MAX_RECORD_BYTES) return { ok: false, reason: "the record is too large" };
+  let doc;
+  try {
+    doc = (0, import_yaml.parse)(content);
+  } catch {
+    return { ok: false, reason: "the record is not readable YAML" };
+  }
+  if (!doc || typeof doc !== "object") return { ok: false, reason: "the record is empty" };
+  const d = doc;
+  if (d.kind !== RECORD_KIND || d.version !== 1) return { ok: false, reason: "not an approval record this version reads" };
+  if (typeof d.statement !== "string" || typeof d.signature !== "string") return { ok: false, reason: "the record has no statement or no signature" };
+  if (!/^-----BEGIN SSH SIGNATURE-----\n[A-Za-z0-9+/=\n]+-----END SSH SIGNATURE-----\s*$/.test(d.signature.trim() + "\n")) {
+    return { ok: false, reason: "the signature is not an SSH signature" };
+  }
+  let s;
+  try {
+    s = JSON.parse(d.statement);
+  } catch {
+    return { ok: false, reason: "the statement is not JSON" };
+  }
+  const evidence = s.evidence;
+  const ok = s && typeof s === "object" && typeof s.uid === "string" && UID.test(s.uid) && typeof s.planUid === "string" && UID.test(s.planUid) && typeof s.itemUid === "string" && UID.test(s.itemUid) && typeof s.criterionUid === "string" && UID.test(s.criterionUid) && typeof s.criterionSha256 === "string" && SHA256.test(s.criterionSha256) && s.decision === "approved" && typeof s.signer === "string" && EMAIL.test(s.signer) && typeof s.at === "string" && !Number.isNaN(Date.parse(s.at)) && !!evidence && typeof evidence === "object" && !Array.isArray(evidence) && Object.entries(evidence).every(([k, v]) => UID.test(k) && (v === null || typeof v === "string" && SHA256.test(v)));
+  if (!ok) return { ok: false, reason: "the statement is missing a field or has one it should not" };
+  const statement = s;
+  if (canonicalStatement(statement) !== d.statement) return { ok: false, reason: "the statement is not in its signed form" };
+  return { ok: true, statement, text: d.statement, signature: d.signature.trim() + "\n" };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NAMESPACE,
+  RECORD_KIND,
+  canonicalStatement,
+  parseRecord,
+  recordYaml,
+  sha256
+});