@worca/app 0.0.1

package/src/core/fanout.mjs

@@ -0,0 +1,48 @@
+// src/core/fanout.mjs
+// Bounded-concurrency helper for the orchestrator's OWN per-project IO (worktree
+// setup, graph builds, checkpoints, staging) on a workspace run. This is NOT the
+// agent Task fan-out (that is agent-initiated inside a node, gated by node.fanOut);
+// it is the deterministic, capped parallelism the orchestrator uses to apply the
+// existing single-project machinery N times across member projects.
+//
+// The determinism guarantee: results come back in INPUT order, never completion
+// order, so a workspace run over a sorted-projectKey member list always recombines
+// the same way regardless of which project's git finished first.
+
+/**
+ * The hard concurrency cap for orchestrator-owned per-project IO.
+ * WORCA_FANOUT_CAP overrides; a non-positive / non-numeric value falls back to 4.
+ * @returns {number}
+ */
+export function fanoutCap() {
+  const n = Number(process.env.WORCA_FANOUT_CAP);
+  return Number.isFinite(n) && n > 0 ? n : 4;
+}
+
+/**
+ * Map `items` through async `fn` with at most `cap` running concurrently, returning
+ * the results in INPUT order (results[i] === await fn(items[i], i)). A worker pool
+ * pulls the next index off a shared cursor, so the cap is a true ceiling on in-flight
+ * work; the first rejection rejects the whole call (Promise.all semantics).
+ *
+ * @template T, R
+ * @param {T[]} items
+ * @param {number} cap   max concurrent invocations (coerced to >= 1)
+ * @param {(item: T, index: number) => Promise<R>} fn
+ * @returns {Promise<R[]>}  results index-aligned with `items`
+ */
+export async function mapWithCap(items, cap, fn) {
+  const list = Array.isArray(items) ? items : [];
+  const results = new Array(list.length);
+  if (list.length === 0) return results;
+  const limit = Math.max(1, Math.min(Number(cap) || 1, list.length));
+  let cursor = 0;
+  const worker = async () => {
+    while (cursor < list.length) {
+      const i = cursor++;
+      results[i] = await fn(list[i], i);
+    }
+  };
+  await Promise.all(Array.from({ length: limit }, () => worker()));
+  return results;
+}

package/src/core/folder-dialog.mjs

@@ -0,0 +1,138 @@
+// src/core/folder-dialog.mjs
+// Server-side native OS "choose folder" dialog. A browser <input type=file>
+// cannot reveal absolute directory paths, so the add-project Browse button asks
+// the server (which runs on the user's own machine; worca-cc is localhost-only)
+// to open the platform dialog and report the chosen path.
+//
+//   darwin -> osascript `choose folder` (the System Events activate line keeps
+//             the dialog frontmost; on first use macOS may show a one-time
+//             Automation consent prompt — a denial surfaces as a non-cancel
+//             error and degrades to `unsupported`, i.e. the in-app fallback)
+//   win32  -> PowerShell System.Windows.Forms.FolderBrowserDialog (-STA)
+//   linux  -> zenity --file-selection --directory, falling back to kdialog;
+//             requires DISPLAY/WAYLAND_DISPLAY (headless -> unsupported)
+//
+// Any failure that is not a recognized user-cancel degrades to
+// { status: 'unsupported' } so the web UI can fall back to its in-app folder
+// browser. WORCA_NO_NATIVE_DIALOG=1 forces that fallback. Like git-info.mjs,
+// every command goes through an injectable runner (_testing) so tests never
+// open a real dialog. Nothing here ever throws.
+
+import { spawn } from 'node:child_process';
+
+const PROMPT = 'Select a project folder';
+// A dialog waits on a human; give it a long leash, then kill the process so a
+// forgotten dialog cannot pin server resources forever.
+const DIALOG_TIMEOUT_MS = 5 * 60 * 1000;
+
+/** Default runner: spawn cmd, resolve { ok, stdout, stderr, code, timedOut }. */
+function defaultRun(cmd, args, { timeout = DIALOG_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (err) {
+      resolve({ ok: false, stdout: '', stderr: err.message, code: -1, timedOut: false });
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const done = (val) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(val);
+    };
+    const timer = setTimeout(() => {
+      try { child.kill('SIGKILL'); } catch { /* already gone */ }
+      done({ ok: false, stdout, stderr: 'dialog timed out', code: -1, timedOut: true });
+    }, timeout);
+    child.stdout?.on('data', (b) => (stdout += b.toString()));
+    child.stderr?.on('data', (b) => (stderr += b.toString()));
+    child.on('error', (err) => done({ ok: false, stdout, stderr: stderr || err.message, code: -1, timedOut: false }));
+    child.on('close', (code) => done({ ok: code === 0, stdout, stderr, code: code ?? -1, timedOut: false }));
+  });
+}
+
+const _ov = { runner: null, platform: null, env: null };
+let _inFlight = false;
+
+export const _testing = {
+  set({ runner = _ov.runner, platform = _ov.platform, env = _ov.env } = {}) {
+    _ov.runner = runner;
+    _ov.platform = platform;
+    _ov.env = env;
+  },
+  reset() {
+    _ov.runner = null;
+    _ov.platform = null;
+    _ov.env = null;
+    _inFlight = false;
+  },
+};
+
+/**
+ * Open the platform's native folder picker and wait for the user.
+ * Serialized: while one dialog is open, further calls resolve { status:'busy' }.
+ * @returns {Promise<{status:'picked', path:string} | {status:'canceled'}
+ *   | {status:'unsupported'} | {status:'busy'}>}
+ */
+export async function pickFolderNative() {
+  if (_inFlight) return { status: 'busy' };
+  _inFlight = true;
+  try {
+    const platform = _ov.platform || process.platform;
+    const env = _ov.env || process.env;
+    const run = _ov.runner || defaultRun;
+    if ((env.WORCA_NO_NATIVE_DIALOG || '') === '1') return { status: 'unsupported' };
+    if (platform === 'darwin') return await pickMac(run);
+    if (platform === 'win32') return await pickWindows(run);
+    if (platform === 'linux') return await pickLinux(run, env);
+    return { status: 'unsupported' };
+  } finally {
+    _inFlight = false;
+  }
+}
+
+function pickedOrCanceled(stdoutRaw) {
+  const raw = stdoutRaw.trim();
+  const path = raw === '/' ? raw : raw.replace(/\/+$/, '');
+  return path ? { status: 'picked', path } : { status: 'canceled' };
+}
+
+async function pickMac(run) {
+  const r = await run('osascript', [
+    '-e', 'tell application "System Events" to activate',
+    '-e', `POSIX path of (choose folder with prompt "${PROMPT}")`,
+  ]);
+  if (r.ok) return pickedOrCanceled(r.stdout);
+  // `choose folder` cancel: exit 1 + "execution error: User canceled. (-128)"
+  if (/-128|User cancell?ed/i.test(r.stderr || '')) return { status: 'canceled' };
+  return { status: 'unsupported' }; // no GUI session, automation denied, ...
+}
+
+async function pickWindows(run) {
+  const script =
+    'Add-Type -AssemblyName System.Windows.Forms | Out-Null; ' +
+    '$d = New-Object System.Windows.Forms.FolderBrowserDialog; ' +
+    `$d.Description = '${PROMPT}'; $d.ShowNewFolderButton = $true; ` +
+    "if ($d.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) { [Console]::Out.WriteLine($d.SelectedPath) }";
+  const r = await run('powershell.exe', ['-NoProfile', '-STA', '-Command', script]);
+  if (!r.ok) return { status: 'unsupported' };
+  // OK exit either way; empty stdout means the user canceled.
+  const path = r.stdout.trim();
+  return path ? { status: 'picked', path } : { status: 'canceled' };
+}
+
+async function pickLinux(run, env) {
+  if (!env.DISPLAY && !env.WAYLAND_DISPLAY) return { status: 'unsupported' };
+  const zen = await run('zenity', ['--file-selection', '--directory', `--title=${PROMPT}`]);
+  if (zen.ok) return pickedOrCanceled(zen.stdout);
+  if (zen.code === 1 && !zen.timedOut) return { status: 'canceled' }; // user closed it
+  // zenity missing (spawn error -> code -1) or broken: try kdialog.
+  const kd = await run('kdialog', ['--title', PROMPT, '--getexistingdirectory', env.HOME || '/']);
+  if (kd.ok) return pickedOrCanceled(kd.stdout);
+  if (kd.code === 1 && !kd.timedOut) return { status: 'canceled' };
+  return { status: 'unsupported' };
+}

package/src/core/fs-browse.mjs

@@ -0,0 +1,49 @@
+// src/core/fs-browse.mjs
+// Read-only directory listing for the web UI's in-app folder browser (the
+// fallback when the native OS dialog is unavailable). Lists ONLY directories —
+// it is a folder picker, files are never shown — and hides dotfolders. Worca CC
+// is a localhost-only single-user tool (isLocalRequest in ui/server.mjs), so
+// this exposes exactly the same trust level as the manual path field it backs.
+
+import { readdir, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { normalizeProjectPath } from './projects.mjs';
+import { defaultRoot } from './settings.mjs';
+
+function err(message, code) { return Object.assign(new Error(message), { code }); }
+
+/**
+ * List the sub-directories of `input` (tilde-expanded, resolved). Empty input
+ * lists the OS home directory (normalizeProjectPath returns null for blank
+ * input, so this can never fall through to process.cwd()).
+ * @param {string} input
+ * @returns {Promise<{path:string, parent:string|null, home:string,
+ *   dirs:Array<{name:string, path:string}>}>} parent is null at the fs root.
+ * @throws {Error & {code:'BAD_REQUEST'}} when the path does not exist, is not
+ *   a directory, or cannot be read.
+ */
+export async function listFolders(input) {
+  const home = resolve(defaultRoot());
+  const path = normalizeProjectPath(input) || home;
+  let entries;
+  try {
+    entries = await readdir(path, { withFileTypes: true });
+  } catch (e) {
+    if (e.code === 'ENOENT') throw err(`no such directory: ${path}`, 'BAD_REQUEST');
+    if (e.code === 'ENOTDIR') throw err(`not a directory: ${path}`, 'BAD_REQUEST');
+    if (e.code === 'EACCES' || e.code === 'EPERM') throw err(`permission denied: ${path}`, 'BAD_REQUEST');
+    throw err(`cannot read directory: ${e.message}`, 'BAD_REQUEST');
+  }
+  const dirs = [];
+  for (const d of entries) {
+    if (d.name.startsWith('.')) continue;
+    let isDir = d.isDirectory();
+    if (!isDir && d.isSymbolicLink()) {
+      try { isDir = (await stat(join(path, d.name))).isDirectory(); } catch { isDir = false; }
+    }
+    if (isDir) dirs.push({ name: d.name, path: join(path, d.name) });
+  }
+  dirs.sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }));
+  const parent = dirname(path);
+  return { path, parent: parent === path ? null : parent, home, dirs };
+}

package/src/core/git-info.mjs

@@ -0,0 +1,200 @@
+// src/core/git-info.mjs
+// Read-only git facts + gh (GitHub CLI) actions that the History UI needs.
+// Leaf module: depends only on node:child_process so artifacts.mjs and the UI
+// server can both import it without the worktree.mjs <-> artifacts.mjs cycle.
+// Every command goes through an injectable runner (_testing.setRunner) so tests
+// never shell out to real git/gh/GitHub. Nothing here ever throws.
+
+import { spawn } from 'node:child_process';
+
+/** Default runner: spawn `cmd args` in `cwd`, resolve { ok, stdout, stderr, code }. */
+function defaultRun(cmd, args, { cwd } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (err) {
+      resolve({ ok: false, stdout: '', stderr: err.message, code: -1 });
+      return;
+    }
+    let stdout = '', stderr = '';
+    child.stdout?.on('data', (b) => (stdout += b.toString()));
+    child.stderr?.on('data', (b) => (stderr += b.toString()));
+    child.on('error', (err) => resolve({ ok: false, stdout, stderr: stderr || err.message, code: -1 }));
+    child.on('close', (code) => resolve({ ok: code === 0, stdout, stderr, code: code ?? -1 }));
+  });
+}
+
+let _run = defaultRun;
+let _ghCache = null;
+
+/** Parse `git diff --shortstat` output into { added, removed }. */
+export function parseShortstat(out) {
+  const ins = /(\d+)\s+insertion/.exec(String(out || ''));
+  const del = /(\d+)\s+deletion/.exec(String(out || ''));
+  return { added: ins ? Number(ins[1]) : 0, removed: del ? Number(del[1]) : 0 };
+}
+
+/** Added/removed line counts for source...feature (merge-base/3-dot). 0/0 on any failure. */
+export async function diffShortstat(projectDir, source, feature) {
+  if (!projectDir || !source || !feature) return { added: 0, removed: 0 };
+  const r = await _run('git', ['diff', '--shortstat', `${source}...${feature}`], { cwd: projectDir });
+  if (!r.ok) return { added: 0, removed: 0 };
+  return parseShortstat(r.stdout);
+}
+
+/**
+ * Parse `git diff --name-status -M` rows. `head` omitted -> diff base vs working tree.
+ * Rename/copy rows look like `R100\told\tnew`; status letter is the first char.
+ * `pathspecs` (optional) are appended AFTER the bare '--' so callers can restrict
+ * or, more usefully, EXCLUDE paths (`:(exclude)<path>` — exclude-only pathspecs are
+ * valid git). Passing nothing yields the byte-identical argv of before (§8.8).
+ * @returns {Promise<Array<{status:string, path:string, from?:string}>>}
+ */
+export async function diffNameStatus(projectDir, base, head, pathspecs = []) {
+  if (!projectDir || !base) return [];
+  const args = ['diff', '--name-status', '-M', base, ...(head ? [head] : []), '--', ...pathspecs];
+  const r = await _run('git', args, { cwd: projectDir });
+  if (!r.ok) return [];
+  const out = [];
+  for (const line of r.stdout.split('\n')) {
+    if (!line.trim()) continue;
+    const parts = line.split('\t');
+    const status = parts[0][0]; // R100 -> R, C75 -> C
+    if (status === 'R' || status === 'C') {
+      out.push({ status, from: parts[1], path: parts[2] });
+    } else {
+      out.push({ status, path: parts[1] });
+    }
+  }
+  return out;
+}
+
+/**
+ * Parse `git diff --numstat -M` into a Map keyed by path. Binary files report
+ * `-`/`-` and are flagged `binary:true` with zero counts. `pathspecs` (optional)
+ * are appended AFTER the bare '--' — see diffNameStatus.
+ * @returns {Promise<Map<string,{added:number, removed:number, binary:boolean}>>}
+ */
+export async function diffNumstat(projectDir, base, head, pathspecs = []) {
+  const m = new Map();
+  if (!projectDir || !base) return m;
+  const args = ['diff', '--numstat', '-M', base, ...(head ? [head] : []), '--', ...pathspecs];
+  const r = await _run('git', args, { cwd: projectDir });
+  if (!r.ok) return m;
+  for (const line of r.stdout.split('\n')) {
+    if (!line.trim()) continue;
+    const [a, d, ...rest] = line.split('\t');
+    const path = rest[rest.length - 1]; // for renames the last col is the new path
+    const binary = a === '-' || d === '-';
+    m.set(path, { added: binary ? 0 : Number(a) || 0, removed: binary ? 0 : Number(d) || 0, binary });
+  }
+  return m;
+}
+
+/**
+ * Full unified diff (`git diff -M base [head]`). Empty string on failure.
+ * `pathspecs` (optional) are appended AFTER the bare '--' — see diffNameStatus.
+ * @returns {Promise<string>}
+ */
+export async function diffPatch(projectDir, base, head, pathspecs = []) {
+  if (!projectDir || !base) return '';
+  const args = ['diff', '-M', base, ...(head ? [head] : []), '--', ...pathspecs];
+  const r = await _run('git', args, { cwd: projectDir });
+  return r.ok ? r.stdout : '';
+}
+
+/** True iff `branch` exists locally in `projectDir`. False on a missing repo/branch. */
+export async function branchExists(projectDir, branch) {
+  if (!projectDir || !branch) return false;
+  const r = await _run('git', ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], { cwd: projectDir });
+  return r.ok && !!r.stdout.trim();
+}
+
+/** True iff the GitHub CLI is on PATH. Memoized (reset via _testing.reset()). */
+export async function hasGh() {
+  if (_ghCache !== null) return _ghCache;
+  const r = await _run('gh', ['--version']);
+  _ghCache = r.ok;
+  return _ghCache;
+}
+
+/** Push the branch and set upstream. Idempotent; surfaces stderr on failure. */
+export async function pushBranch(projectDir, branch) {
+  const r = await _run('git', ['push', '-u', 'origin', branch], { cwd: projectDir });
+  return { ok: r.ok, stderr: (r.stderr || '').trim() };
+}
+
+/**
+ * Open a PR with `gh pr create`. On "already exists", recover the open PR's URL
+ * via `gh pr view` so the button is still useful. Returns { ok, url, existed } |
+ * { ok:false, error }.
+ */
+export async function createPr({ projectDir, base, head, title, body = '' }) {
+  const args = ['pr', 'create', '--base', base, '--head', head, '--title', title || head, '--body', body || title || head];
+  const r = await _run('gh', args, { cwd: projectDir });
+  if (r.ok) {
+    // gh prints the PR URL as the last stdout line.
+    const url = (r.stdout.trim().split(/\r?\n/).pop() || '').trim();
+    return { ok: true, url, existed: false };
+  }
+  if (/already exists/i.test(r.stderr || '')) {
+    const v = await _run('gh', ['pr', 'view', head, '--json', 'url', '-q', '.url'], { cwd: projectDir });
+    if (v.ok && v.stdout.trim()) return { ok: true, url: v.stdout.trim(), existed: true };
+  }
+  return { ok: false, error: (r.stderr || '').trim() || `gh exited ${r.code}` };
+}
+
+/** Normalize gh's `mergeable` / `mergeStateStatus` to MERGEABLE | CONFLICTING | UNKNOWN. */
+export function normalizeMergeable(raw) {
+  const s = String(raw || '').toUpperCase();
+  if (s === 'MERGEABLE' || s === 'CLEAN') return 'MERGEABLE';
+  if (s === 'CONFLICTING' || s === 'DIRTY') return 'CONFLICTING';
+  return 'UNKNOWN';
+}
+
+/** Read mergeability for the PR whose head is `head`. UNKNOWN on any failure. */
+export async function prMergeable({ projectDir, head }) {
+  const r = await _run('gh', ['pr', 'view', head, '--json', 'mergeable', '-q', '.mergeable'], { cwd: projectDir });
+  if (!r.ok) return 'UNKNOWN';
+  return normalizeMergeable(r.stdout.trim());
+}
+
+/**
+ * Look up an existing PR for `head` via `gh pr list`, so the History UI can hide
+ * the Create-PR button when a PR is already open or merged. Scans the matches and
+ * selects by priority OPEN > MERGED, so a newer closed PR never masks an older
+ * merged one; a closed-but-not-merged PR is ignored (treated as "no active PR").
+ * Returns { state, url, number } with state ∈ { OPEN, MERGED }, or null when there
+ * is no open/merged PR / on any gh failure. Never throws.
+ */
+export async function findPrForBranch({ projectDir, head } = {}) {
+  if (!projectDir || !head) return null;
+  const r = await _run(
+    'gh',
+    ['pr', 'list', '--head', head, '--state', 'all', '--json', 'number,state,url', '--limit', '30'],
+    { cwd: projectDir },
+  );
+  if (!r.ok) return null;
+  let arr;
+  try { arr = JSON.parse(r.stdout || '[]'); } catch { return null; }
+  if (!Array.isArray(arr) || arr.length === 0) return null;
+  // Keep only the states the UI acts on; closed/declined PRs are deliberately dropped.
+  const norm = arr
+    .map((pr) => ({
+      state: String(pr?.state || '').toUpperCase(),
+      url: String(pr?.url || ''),
+      number: Number(pr?.number) || null,
+    }))
+    .filter((pr) => pr.state === 'OPEN' || pr.state === 'MERGED');
+  if (norm.length === 0) return null;
+  // Requirement is binary: hide the button if any OPEN or MERGED PR exists. After
+  // the filter, norm[0] is necessarily a MERGED entry when there is no OPEN one.
+  return norm.find((p) => p.state === 'OPEN') || norm[0];
+}
+
+// Test seam: swap the command runner + clear the gh memo. Mirrors server.mjs#_testing.
+export const _testing = {
+  setRunner(fn) { _run = typeof fn === 'function' ? fn : defaultRun; _ghCache = null; },
+  reset() { _run = defaultRun; _ghCache = null; },
+};

package/src/core/guardrail-store.mjs

@@ -0,0 +1,204 @@
+// src/core/guardrail-store.mjs
+// Global named guardrail-set store (table: guardrail_sets, SCHEMA_V14). The three
+// built-ins — Permissive / Normal / Strict (wire ids permissive/normal/secure; the
+// "Strict" label is display-only) — are VIRTUAL: derived from GUARDRAIL_PRESETS at
+// read time, never persisted, undeletable, prepended by the server (the
+// DEFAULT_WORKFLOW contract). User sets are rows; `settings` is the JSON 5-key
+// blob, sanitized on read. Reads never throw: missing/unsafe-id => null/[];
+// corrupt settings JSON degrades to the empty policy (the row stays a set).
+// deleteGuardrailSet throws ReferencedError while any pipeline resume point pins
+// the set (guardrails are selected PER RUN — resume_point.guardrailsId is the only
+// reference kind; the historical pipelines.guardrails_id column never blocks).
+import { getDb, prepare, tx } from './db.mjs';
+import { slugify } from './artifacts.mjs';
+import { GUARDRAIL_PRESETS, GUARDRAIL_LEVELS, sanitizeGuardrails } from './guardrails.mjs';
+// Shared delete-guard error class (uninstall/delete blocked by live references).
+// Reusing it is safe: plugin-workflows imports only db/artifacts/agent-registry/
+// workflow-validator/plugins-lock (plugin-workflows.mjs:8-15) — a leaf subtree
+// with no cycle back into this module. Its ctor is (message, references); the
+// store stamps code:'REFERENCED' at the throw site, and the server ALSO matches
+// structurally (err.name === 'ReferencedError' || err.code === 'REFERENCED').
+import { ReferencedError } from './plugin-workflows.mjs';
+
+export { ReferencedError };
+
+const EPOCH = '1970-01-01T00:00:00.000Z';
+
+// Wire id -> display name. `secure` renders as "Strict" (display-only rename).
+const BUILTIN_META = Object.freeze({ permissive: 'Permissive', normal: 'Normal', secure: 'Strict' });
+
+export const BUILTIN_GUARDRAIL_SET_IDS = Object.freeze(Object.keys(BUILTIN_META));
+
+export function isBuiltinGuardrailSetId(id) {
+  return Object.prototype.hasOwnProperty.call(BUILTIN_META, id);
+}
+
+/** One virtual built-in, with FRESH settings copies (the frozen preset table never leaks). */
+function builtinSet(id) {
+  return {
+    id,
+    name: BUILTIN_META[id],
+    origin: 'builtin',
+    settings: sanitizeGuardrails(GUARDRAIL_PRESETS[id]),
+    createdAt: EPOCH,
+    updatedAt: EPOCH,
+  };
+}
+
+/** All three virtual built-ins, list order Permissive -> Normal -> Strict. Sync: a pure code-table derivation. */
+export function listBuiltinGuardrailSets() {
+  return BUILTIN_GUARDRAIL_SET_IDS.map(builtinSet);
+}
+
+/** A set id is a stem; reject anything that could escape (same rule as workflows). */
+const SAFE_SET_ID = /^[A-Za-z0-9_-]+$/;
+function isSafeSetId(id) { return typeof id === 'string' && SAFE_SET_ID.test(id); }
+
+/** Map a guardrail_sets row to the set shape. Corrupt settings JSON degrades to the empty policy. */
+function rowToSet(r) {
+  let settings;
+  try { settings = sanitizeGuardrails(JSON.parse(r.settings)); } catch { settings = sanitizeGuardrails(undefined); }
+  return { id: r.id, name: r.name, origin: r.origin || null, settings, createdAt: r.created_at, updatedAt: r.updated_at };
+}
+
+/** Read one stored row. Unsafe id / missing => null. */
+function readRaw(id) {
+  if (!isSafeSetId(id)) return null; // SECURITY: reject path-traversal / unsafe ids
+  getDb();
+  const r = prepare(
+    'SELECT id, name, settings, origin, created_at, updated_at FROM guardrail_sets WHERE id = ?'
+  ).get(id);
+  return r ? rowToSet(r) : null;
+}
+
+/**
+ * Read a set by id. Built-in ids resolve virtually (readGuardrailSet('secure')
+ * returns the Strict built-in); otherwise the stored row, or null.
+ * @param {string} id
+ * @returns {Promise<object|null>}
+ */
+export async function readGuardrailSet(id) {
+  if (isBuiltinGuardrailSetId(id)) return builtinSet(id);
+  return readRaw(id);
+}
+
+/**
+ * List USER sets (NOT the built-ins — callers prepend listBuiltinGuardrailSets()),
+ * newest first by createdAt. Empty store => []. Never throws.
+ * @returns {Promise<object[]>}
+ */
+export async function listGuardrailSets() {
+  getDb();
+  const rows = prepare(
+    'SELECT id, name, settings, origin, created_at, updated_at FROM guardrail_sets ORDER BY created_at DESC, id'
+  ).all();
+  return rows.filter((r) => !isBuiltinGuardrailSetId(r.id)).map(rowToSet);
+}
+
+/**
+ * Persist a set. Mints gr_<slug> from the name when id is missing; sanitizes the
+ * settings blob; preserves created_at on re-save; upsert OMITS origin (a user
+ * re-save of a plugin row keeps its provenance; user rows stay NULL). Reserved
+ * ids (the GUARDRAIL_LEVELS words: the three built-ins + 'custom') and unsafe
+ * explicit ids return null — built-ins are code, not rows.
+ * @param {object} set { id?, name, settings, createdAt? }
+ * @returns {Promise<object|null>}
+ */
+export async function writeGuardrailSet(set) {
+  const now = new Date().toISOString();
+  const name = (set && typeof set.name === 'string' && set.name.trim()) || 'Untitled';
+  const id = (set && typeof set.id === 'string' && set.id.trim()) || `gr_${slugify(name)}`;
+  if (!isSafeSetId(id) || GUARDRAIL_LEVELS.includes(id)) return null; // reserved: builtin ids + 'custom'
+  const settings = sanitizeGuardrails(set?.settings);
+
+  getDb();
+  // Preserve the original createdAt (and report provenance) if this id already exists.
+  const existing = prepare('SELECT created_at, origin FROM guardrail_sets WHERE id = ?').get(id);
+  const createdAt =
+    (set && typeof set.createdAt === 'string' && set.createdAt) ||
+    (existing && existing.created_at) ||
+    now;
+
+  const stored = { id, name, origin: (existing && existing.origin) || null, settings, createdAt, updatedAt: now };
+  tx(() => {
+    prepare(`
+      INSERT INTO guardrail_sets (id, name, settings, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        name = excluded.name, settings = excluded.settings, updated_at = excluded.updated_at
+    `).run(id, name, JSON.stringify(settings), createdAt, now);
+  });
+  return stored;
+}
+
+/**
+ * SYNC reference scan: pipeline resume points whose rp.guardrailsId pins this id
+ * (Phase 2 writes the field; done/stopped runs null their resume point, so only
+ * recoverable runs pin — errored rows retain theirs and legitimately block, the
+ * plugin-workflows scope). The historical pipelines.guardrails_id COLUMN is
+ * deliberately NOT scanned: it records finished runs, and history never blocks.
+ * ARCHIVED rows are excluded for the same reason they are excluded from every
+ * list read: History's Archive soft-deletes (archived_at stamped, resume_point
+ * left in place), and an archived run is invisible, unresumable and un-re-
+ * archivable — so a kept pin would be permanent with no UI escape hatch. The
+ * hard DELETE this replaced released it.
+ * Raw prepare() reads only, so it is callable from inside deleteGuardrailSet's
+ * tx (tx() non-reentrancy bars nested tx() CALLS, not reads).
+ */
+function scanReferences(id) {
+  const referencedBy = [];
+  for (const p of prepare(
+    'SELECT id, resume_point FROM pipelines WHERE resume_point IS NOT NULL AND archived_at IS NULL',
+  ).all()) {
+    try {
+      const rp = JSON.parse(p.resume_point);
+      if (rp && rp.guardrailsId === id) referencedBy.push(`pipeline ${p.id}`);
+    } catch { /* corrupt resume point: not a reference */ }
+  }
+  return referencedBy.length ? [{ id, referencedBy }] : [];
+}
+
+/**
+ * Who still pins this set (the async API wrapper around scanReferences).
+ * @param {string} id
+ * @returns {Promise<Array<{id: string, referencedBy: string[]}>>}
+ */
+export async function guardrailSetReferences(id) {
+  getDb();
+  return scanReferences(id);
+}
+
+/**
+ * Delete a saved set. Refuses built-ins and unsafe ids (false); throws
+ * ReferencedError (with the structured referencing list) while any resume-point
+ * pin exists — nothing deleted; false when no row exists; true on removal.
+ * The reference scan runs INSIDE the same tx as the DELETE (raw prepare()
+ * reads — tx() non-reentrancy bars nested tx() calls, not reads), so a pin
+ * written between scan and DELETE can never slip through and dangle. House
+ * precedent (plugin-workflows removePluginWorkflows) scans outside its tx; we
+ * deviate deliberately: a stranded workflow ref merely falls back to the
+ * default topology, a stranded guardrail pin silently downgrades a paused
+ * run's selected SECURITY policy to Permissive at resume.
+ * @param {string} id
+ * @returns {Promise<boolean>}
+ */
+export async function deleteGuardrailSet(id) {
+  if (isBuiltinGuardrailSetId(id)) return false; // built-ins are undeletable
+  if (!isSafeSetId(id)) return false;            // SECURITY: reject unsafe ids
+  getDb();
+  let changed = 0;
+  tx(() => {
+    const references = scanReferences(id);
+    if (references.length) {
+      const lines = references.map((r) => `  - ${r.id} (referenced by ${r.referencedBy.join(', ')})`);
+      const err = new ReferencedError(
+        `cannot delete guardrail set "${id}" — still referenced:\n${lines.join('\n')}`,
+        references,
+      );
+      err.code = 'REFERENCED'; // structural server match (the 409 mapping)
+      throw err; // tx() rolls back (nothing written) and rethrows
+    }
+    changed = prepare('DELETE FROM guardrail_sets WHERE id = ?').run(id).changes;
+  });
+  return changed > 0;
+}