synabun 2.0.10 → 2.2.0

package/neural-interface/lib/skills/reviews.js

@@ -0,0 +1,212 @@
+// ── The Review queue ──
+// What the SynaBun Assistant (or any agent) makes goes here, never straight into a runtime (owner decision,
+// 2026-10-22): a submission is one immutable revision of a library skill, with its digest, the targets it is meant
+// for, the checks of exactly those bytes, what it can do compared with the revision approved before it (the scan's
+// authority inventory, side by side), release notes, the author's assumptions, and who made it. The owner
+// approves, asks for changes or rejects; only an approval moves the skill's `approved` pointer, and only an
+// approved revision of an agent's is installed (lib/skills/deploy.js refuses the rest). New bytes need a new
+// submission: an approval belongs to the digest it was given for.
+//
+//   pending ──► approved ──► publishing ──► published | partial | publish_failed
+//      │  └──► changes_requested ──► (a new submission links back to it)
+//      ├──► rejected
+//      └──► withdrawn (the author, or the owner)
+//
+// DATA_HOME/data/skills/reviews.json (schema 2), written whole and atomically.
+
+import { randomBytes } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { PathConfineError } from '../path-confine.js';
+import { readConfinedFile, replaceFileAtomic } from '../confined-fs.js';
+import { normalizeAuthor } from './library.js';
+
+export const REVIEWS_SCHEMA = 2;
+export const REVIEW_POLICY = 'review-policy-1';
+export const REVIEW_STATES = Object.freeze(['pending', 'changes_requested', 'approved', 'publishing', 'published', 'partial', 'publish_failed', 'rejected', 'withdrawn']);
+const OPEN = new Set(['pending', 'changes_requested']);
+const MAX_REVIEWS = 2000;
+const MAX_COMMENTS = 200;
+const REVIEW_RE = /^rvw_[0-9a-f]{20}$/;
+
+export class ReviewError extends PathConfineError {
+  constructor(status, message, code, extra = {}) {
+    super(status, message);
+    this.code = code;
+    Object.assign(this, extra);
+  }
+}
+
+const text = (v, n) => (typeof v === 'string' ? v.slice(0, n) : '');
+
+/** What one revision can do that the other cannot (the scans' authority inventories compared). */
+export function authorityDelta(before, after) {
+  const keys = ['scripts', 'binaries', 'dynamicContext', 'hooks', 'toolGrants', 'domains', 'sensitive', 'persistentWrites', 'installers'];
+  const label = (k, v) => {
+    if (k === 'scripts' || k === 'binaries') return v.path;
+    if (k === 'hooks') return `${v.event}`;
+    if (k === 'toolGrants') return `${v.key}: ${v.tool}`;
+    if (k === 'domains') return v;
+    if (k === 'dynamicContext') return `${v.file}: ${v.command}`;
+    return `${v.file}:${v.line}`;
+  };
+  const out = {};
+  for (const k of keys) {
+    const a = new Set((before?.[k] || []).map((v) => label(k, v)));
+    const b = new Set((after?.[k] || []).map((v) => label(k, v)));
+    const added = [...b].filter((x) => !a.has(x));
+    const removed = [...a].filter((x) => !b.has(x));
+    if (added.length || removed.length) out[k] = { added: added.slice(0, 100), removed: removed.slice(0, 100) };
+  }
+  return { changed: Object.keys(out).length > 0, byKind: out };
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.dataDir DATA_HOME/data/skills
+ * @param {object} o.library lib/skills/library.js
+ */
+export function createReviewQueue({ dataDir, library, emit = () => {}, now = () => new Date().toISOString(), newId = () => `rvw_${randomBytes(10).toString('hex')}` }) {
+  const storePath = join(dataDir, 'reviews.json');
+
+  function read() {
+    try {
+      const parsed = JSON.parse(readConfinedFile(dataDir, storePath, { maxBytes: 32 * 1024 * 1024, encoding: 'utf-8' }));
+      if (parsed?.schemaVersion === REVIEWS_SCHEMA && Array.isArray(parsed.records)) return parsed;
+    } catch { /* none yet */ }
+    return { schemaVersion: REVIEWS_SCHEMA, records: [] };
+  }
+  function write(store) {
+    mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+    const records = store.records.length > MAX_REVIEWS ? store.records.slice(-MAX_REVIEWS) : store.records;
+    replaceFileAtomic(storePath, `${JSON.stringify({ schemaVersion: REVIEWS_SCHEMA, records }, null, 2)}\n`, { mode: 0o600 });
+  }
+  function get(reviewId) {
+    if (typeof reviewId !== 'string' || !REVIEW_RE.test(reviewId)) throw new ReviewError(400, 'Not a review id.', 'invalid_review');
+    const rec = read().records.find((r) => r.reviewId === reviewId);
+    if (!rec) throw new ReviewError(404, 'There is no such review.', 'review_not_found');
+    return rec;
+  }
+  function update(reviewId, change) {
+    const store = read();
+    const rec = store.records.find((r) => r.reviewId === reviewId);
+    if (!rec) throw new ReviewError(404, 'There is no such review.', 'review_not_found');
+    change(rec);
+    rec.updatedAt = now();
+    write(store);
+    emit({ type: 'review.changed', reviewId, skillId: rec.skillId, state: rec.state });
+    return rec;
+  }
+
+  function list({ state = null, skillId = null, open = null } = {}) {
+    return read().records.filter((r) => (!state || r.state === state) && (!skillId || r.skillId === skillId) && (open === null || OPEN.has(r.state) === open))
+      .sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+  }
+
+  /**
+   * Submit a revision for review.
+   * @param {object} o
+   * @param {string} o.revisionId
+   * @param {object[]} [o.targets] where it is meant to go ({ runtime, scope, accountId?, projectPath? })
+   * @param {object} o.evidence { lint, scan, authority } of exactly that revision
+   */
+  function submit({ revisionId, targets = [], releaseNotes = '', assumptions = [], author, evidence = {}, previousReviewId = null }) {
+    const revision = library.getRevision(revisionId);
+    const skill = library.getSkill(revision.skillId);
+    const store = read();
+    const dup = store.records.find((r) => r.submittedRevisionId === revisionId && OPEN.has(r.state));
+    if (dup) return { review: dup, existing: true };
+    if (previousReviewId !== null) {
+      const prev = store.records.find((r) => r.reviewId === previousReviewId);
+      if (!prev || prev.skillId !== skill.skillId) throw new ReviewError(400, 'previousReviewId is not a review of this skill.', 'invalid_review');
+    }
+    const rec = {
+      schemaVersion: REVIEWS_SCHEMA, reviewId: newId(), skillId: skill.skillId, skillName: skill.name,
+      submittedRevisionId: revisionId, submittedDigest: revision.contentDigest, baseApprovedRevisionId: skill.pointers.approved || null,
+      state: 'pending',
+      targets: (Array.isArray(targets) ? targets : []).slice(0, 12).map((t) => ({ runtime: text(t?.runtime, 20), scope: text(t?.scope, 20) || 'user', accountId: text(t?.accountId, 64) || 'default', projectPath: text(t?.projectPath, 2000) || null })),
+      evidence, releaseNotes: text(releaseNotes, 8000), assumptions: (Array.isArray(assumptions) ? assumptions : []).filter((a) => typeof a === 'string').slice(0, 50).map((a) => a.slice(0, 1000)),
+      author: normalizeAuthor(author), reviewer: null, policyVersion: REVIEW_POLICY, decisionReason: null, exceptions: [],
+      comments: [], publication: { jobId: null, targetResults: [] }, previousReviewId, createdAt: now(), updatedAt: now(),
+    };
+    if (!REVIEW_RE.test(rec.reviewId)) throw new ReviewError(500, 'Bad review id.', 'bad_id');
+    store.records.push(rec);
+    if (previousReviewId) { const prev = store.records.find((r) => r.reviewId === previousReviewId); if (prev) prev.supersededBy = rec.reviewId; }
+    write(store);
+    try { library.setPointer(skill.skillId, 'candidate', revisionId, { by: rec.author.kind, reason: `submitted for review (${rec.reviewId})` }); } catch { /* the pointer is a convenience: the review stands */ }
+    emit({ type: 'review.changed', reviewId: rec.reviewId, skillId: rec.skillId, state: rec.state });
+    return { review: rec, existing: false };
+  }
+
+  function comment(reviewId, { by, body }) {
+    const t = text(body, 4000).trim();
+    if (!t) throw new ReviewError(400, 'A comment has text.', 'invalid_comment');
+    return update(reviewId, (rec) => {
+      if (rec.comments.length >= MAX_COMMENTS) throw new ReviewError(413, 'This review has as many comments as it can hold.', 'too_many_comments');
+      rec.comments.push({ at: now(), by: normalizeAuthor(by), body: t });
+    });
+  }
+
+  /** The author takes a submission back (or the owner closes it). */
+  function withdraw(reviewId, { by }) {
+    return update(reviewId, (rec) => {
+      if (!OPEN.has(rec.state)) throw new ReviewError(409, `A review that is ${rec.state} cannot be withdrawn.`, 'review_state');
+      rec.state = 'withdrawn';
+      rec.decisionReason = 'withdrawn';
+      rec.reviewer = normalizeAuthor(by);
+    });
+  }
+
+  /**
+   * The owner's decision. `approve` binds the approval to the submitted digest (the revision must still read as
+   * it was submitted, and its scan must not block) and moves the skill's `approved` pointer.
+   * @param {'approve'|'reject'|'request_changes'} decision
+   */
+  /**
+   * @param {object} o
+   * @param {string|null} [o.installName] the name the revision installs under (deploy.js effectiveInstallName): an
+   *   approval covers that name only, and an install under another name goes back to review
+   */
+  function decide(reviewId, { decision, reason = '', by, scan = null, installName = null }) {
+    if (!['approve', 'reject', 'request_changes'].includes(decision)) throw new ReviewError(400, 'A decision is approve, reject or request_changes.', 'invalid_decision');
+    const rec = get(reviewId);
+    if (!OPEN.has(rec.state) || (decision === 'approve' && rec.state !== 'pending')) throw new ReviewError(409, `A review that is ${rec.state} cannot be ${decision === 'request_changes' ? 'sent back' : `${decision}d`}.`, 'review_state');
+    if (decision === 'approve') {
+      const revision = library.getRevision(rec.submittedRevisionId);
+      if (revision.contentDigest !== rec.submittedDigest) throw new ReviewError(409, 'The revision does not read as it was submitted.', 'digest_mismatch');
+      library.readRevisionFiles(rec.submittedRevisionId);   // every blob there and intact
+      if (scan && scan.digest === rec.submittedDigest && (scan.gate === 'blocked' || scan.status === 'error')) {
+        throw new ReviewError(409, 'The scan of these files blocks them: they cannot be approved.', 'scan_blocked');
+      }
+      library.setPointer(rec.skillId, 'approved', rec.submittedRevisionId, { by: 'owner', reason: `review ${reviewId} approved`, allowProtected: 'review' });
+    }
+    return update(reviewId, (r) => {
+      r.state = decision === 'approve' ? 'approved' : decision === 'reject' ? 'rejected' : 'changes_requested';
+      r.reviewer = normalizeAuthor(by);
+      r.decisionReason = text(reason, 4000) || null;
+      r.decidedAt = now();
+      if (decision === 'approve') r.approvedInstallName = typeof installName === 'string' && installName ? installName : null;
+    });
+  }
+
+  /** The approval a revision has: the newest approved review of it, with the name it was approved to install as. */
+  function approvalOf(revisionId) {
+    const approved = new Set(['approved', 'publishing', 'published', 'partial', 'publish_failed']);
+    const found = read().records.filter((r) => r.submittedRevisionId === revisionId && approved.has(r.state))
+      .sort((a, b) => String(b.decidedAt || '').localeCompare(String(a.decidedAt || '')))[0];
+    return found ? { reviewId: found.reviewId, installName: found.approvedInstallName || null } : null;
+  }
+
+  /** A publication of an approved review: its per-target outcomes, never one success for all. */
+  function recordPublication(reviewId, { results, jobId = null }) {
+    return update(reviewId, (rec) => {
+      if (!['approved', 'publishing', 'published', 'partial', 'publish_failed'].includes(rec.state)) throw new ReviewError(409, 'Only an approved review is published.', 'review_state');
+      const list = Array.isArray(results) ? results : [];
+      rec.publication = { jobId, targetResults: [...(rec.publication?.targetResults || []), ...list.map((r) => ({ at: now(), targetKey: r.targetKey, status: r.status, installationId: r.installationId || null, error: r.error || null }))].slice(-200) };
+      const committed = list.filter((r) => r.status === 'committed').length;
+      rec.state = committed === list.length && list.length ? 'published' : committed ? 'partial' : 'publish_failed';
+    });
+  }
+
+  return { list, get, submit, comment, withdraw, decide, approvalOf, recordPublication, paths: { storePath } };
+}

package/neural-interface/lib/skills/revision.js

@@ -0,0 +1,80 @@
+// ── Saving over the version that was opened ──
+// A Skills Studio save names the revision the editor opened (lib/skills/digest.js revisionOf): when the file on
+// disk is not that revision any more (another editor, a pull, an agent changed it), nothing is written and the
+// answer says so (409, `revision_conflict`, with the revision that is there now). Otherwise the new bytes go to
+// a temporary file in the same folder and are renamed over the old one, so an interrupted save leaves the old
+// file whole; the file keeps its permissions, and a link to it inside the skill stays a link.
+
+import { lstatSync } from 'node:fs';
+import { PathConfineError } from '../path-confine.js';
+import { canonicalInside, readConfinedFile, replaceFileAtomic, writeConfinedFile, MAX_FILE_BYTES } from '../confined-fs.js';
+import { revisionOf } from './digest.js';
+import { isEditableText } from '../../public/shared/skills/ss-doc.js';
+
+export class RevisionConflictError extends PathConfineError {
+  constructor(currentRevision) {
+    super(409, currentRevision
+      ? 'This file was changed since it was opened. Nothing was written.'
+      : 'This file was removed since it was opened. Nothing was written.');
+    this.code = 'revision_conflict';
+    this.currentRevision = currentRevision;
+  }
+}
+
+/** A revision as a request may carry it: `sha256:<64 hex>`, or `absent` (the file must not exist yet). */
+export const isRevision = (value) => value === 'absent' || (typeof value === 'string' && /^sha256:[0-9a-f]{64}$/.test(value));
+
+/**
+ * Read one regular file inside `base`, with its revision.
+ * @returns {{ bytes: Buffer, binary: boolean, text: string | null, revision: string, size: number }}
+ */
+export function readRevisioned(base, path, { maxBytes = MAX_FILE_BYTES } = {}) {
+  const bytes = readConfinedFile(base, path, { maxBytes });
+  const binary = !isEditableText(bytes);
+  return { bytes, binary, text: binary ? null : bytes.toString('utf-8'), revision: revisionOf(bytes), size: bytes.length };
+}
+
+/**
+ * Write one file inside `base` over the revision it was opened at.
+ * @param {string} base the folder the file must really be in
+ * @param {string} path
+ * @param {Buffer|string} data
+ * @param {object} [o]
+ * @param {string|null} [o.expectedRevision] what the file must hold now (`absent`: it must not exist). Without one
+ *   (a page from before revisions) the file is written as before, but atomically.
+ * @param {number} [o.maxBytes] the most the new content may be (413 over it)
+ * @param {boolean} [o.refuseBinary] a file that is not text is not replaced (415)
+ * @param {boolean} [o.create] a file that does not exist may be created (exclusively)
+ * @returns {{ revision: string, created: boolean, path: string }}
+ */
+export function writeRevisioned(base, path, data, { expectedRevision = null, maxBytes = MAX_FILE_BYTES, refuseBinary = false, create = true } = {}) {
+  if (expectedRevision !== null && expectedRevision !== undefined && !isRevision(expectedRevision)) throw new PathConfineError(400, 'Not a revision.');
+  const buf = Buffer.isBuffer(data) ? data : Buffer.from(String(data ?? ''), 'utf-8');
+  if (buf.length > maxBytes) throw new PathConfineError(413, `That is larger than ${Math.max(1, Math.round(maxBytes / (1024 * 1024)))} MB; it was not written.`);
+  const real = canonicalInside(base, path);
+  let st = null;
+  try { st = lstatSync(real); } catch { st = null; }
+  if (!st) {
+    if (expectedRevision && expectedRevision !== 'absent') throw new RevisionConflictError(null);
+    if (!create) throw new PathConfineError(404, 'File not found.');
+    writeConfinedFile(base, real, buf, { exclusive: true });
+    return { revision: revisionOf(buf), created: true, path: real };
+  }
+  if (!st.isFile()) throw new PathConfineError(400, 'Not a regular file.');
+  const current = readConfinedFile(base, real, { maxBytes: Math.max(maxBytes, MAX_FILE_BYTES) });
+  const currentRevision = revisionOf(current);
+  // "Create it again" while something made the file meanwhile: what is there is named, never replaced.
+  if (expectedRevision === 'absent') throw new RevisionConflictError(currentRevision);
+  if (expectedRevision && expectedRevision !== currentRevision) throw new RevisionConflictError(currentRevision);
+  if (refuseBinary && !isEditableText(current)) {
+    const err = new PathConfineError(415, 'This file is not text: it is not replaced by text. Nothing was written.');
+    err.code = 'binary_file';
+    throw err;
+  }
+  replaceFileAtomic(real, buf, {
+    mode: st.mode & 0o7777,
+    exactMode: true,
+    expect: { dev: st.dev, ino: st.ino, mtimeMs: st.mtimeMs, size: st.size },
+  });
+  return { revision: revisionOf(buf), created: false, path: real };
+}

package/neural-interface/lib/skills/roots.js

@@ -0,0 +1,269 @@
+// ── Every folder a runtime reads skills, commands, agents or prompts from ──
+// One list, for the catalog (lib/skills/catalog.js), the installs (lib/skills/deploy.js), the bridge migration
+// (lib/skills/migration.js) and the staging check (an import is never staged inside one of these). Each root says
+// which runtimes read it, for whom (a Claude or Codex account, a project), what lives there (skill folders, or
+// command / agent / prompt files), whether SynaBun may write there and why, and how its discovery was verified.
+//
+// Where they are (profiles in public/shared/skills/ss-profiles.js; Codex and OpenCode verified on 2026-10-22 by
+// starting codex-cli 0.163.0 and opencode 2.0.32 in a temporary home):
+//   Claude Code   <config dir>/skills, /commands, /agents for each account (CLAUDE_CONFIG_DIR, ~/.claude by
+//                 default; an added account's own folder); <config dir>/skills/synced (account skills,
+//                 read-only); plugin skills and commands under <config dir>/plugins/cache (read-only); the managed
+//                 settings folder's .claude/skills (read-only); each registered project's .claude/skills,
+//                 /commands, /agents.
+//   Codex         $CODEX_HOME/skills for each account (~/.codex by default; the installer's default and where
+//                 SynaBun installs), $CODEX_HOME/skills/.system (Codex's own, read-only), $CODEX_HOME/prompts (the
+//                 old bridges), /etc/codex/skills (admin, read-only), a project's .agents/skills (Codex and
+//                 OpenCode) and .codex/skills (read by Codex, not documented: read-only here).
+//   OpenCode      <config>/opencode/skills (XDG_CONFIG_HOME or ~/.config; where SynaBun installs), the singular
+//                 <config>/opencode/skill (read), <config>/opencode/command and ~/.opencode/command (the old
+//                 bridges), <config>/opencode/commands, a project's .opencode/skills. With OPENCODE_CONFIG_DIR set,
+//                 OpenCode (2.0.32, checked) reads <dir>/skills and <dir>/skill instead of the <config>/opencode
+//                 ones: <dir>/skills is then where SynaBun installs (and <dir> holds the settings it reads), and the
+//                 <config>/opencode skill folders stay listed as read by no runtime.
+//                 OpenCode also reads ~/.claude/skills and both .agents roots (not in SynaBun's own OpenCode panel,
+//                 which turns the Claude ones off).
+//   Antigravity   ~/.gemini/config/skills (Google Antigravity's `agy`; where SynaBun installs) and a project's
+//                 .agents/skills (the Codex project folder, which Antigravity reads too). Not fixture-tested.
+//   Shared        ~/.agents/skills: Codex and OpenCode (and other agents) read it. SynaBun writes there only when
+//                 the owner turned that on (`sharedAgentsRoot`).
+//   SynaBun       PACKAGE_ROOT/skills, the bundled skills: read-only.
+//
+// Nothing here reads a skill; `status` is only what the folder is (there, missing, not a folder, unreadable).
+
+import { createHash } from 'node:crypto';
+import { lstatSync, readdirSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+export const RUNTIMES = Object.freeze(['claude', 'codex', 'opencode', 'antigravity']);
+
+const realFs = { lstat: lstatSync, realpath: realpathSync, readdir: readdirSync };
+
+/** A root's id: stable for the same kind of root at the same place. */
+export function rootIdOf({ family, kind, scope, accountId = '', path }) {
+  return `root_${createHash('sha256').update([family, kind, scope, accountId || '', resolve(String(path))].join('\0')).digest('hex').slice(0, 20)}`;
+}
+
+/** The managed-settings folder of Claude Code on this platform (enterprise skills live in its .claude/skills). */
+export function claudeManagedDir(platform = process.platform) {
+  if (platform === 'darwin') return '/Library/Application Support/ClaudeCode';
+  if (platform === 'win32') return 'C:\\Program Files\\ClaudeCode';
+  return '/etc/claude-code';
+}
+
+/**
+ * @param {object} o
+ * @param {Record<string,string|undefined>} [o.env]
+ * @param {string} [o.homeDir]
+ * @param {string} [o.platform]
+ * @param {() => {path: string, label?: string}[]} [o.projects] registered projects
+ * @param {() => {id: string, label?: string, home: string}[]} [o.claudeAccounts] every Claude account with its config dir
+ * @param {() => {id: string, label?: string, home: string}[]} [o.codexAccounts] every Codex account with its CODEX_HOME
+ * @param {string} [o.bundledDir] PACKAGE_ROOT/skills
+ * @param {() => { sharedAgentsRoot?: boolean }} [o.config]
+ * @param {object} [o.fs] lstat / realpath / readdir (tests)
+ */
+export function createRootResolver({
+  env = process.env, homeDir = homedir(), platform = process.platform,
+  projects = () => [], claudeAccounts = null, codexAccounts = null,
+  bundledDir = null, config = () => ({}), fs = realFs, managedDir = null, codexAdminDir = '/etc/codex/skills',
+} = {}) {
+  const home = resolve(homeDir);
+  const configHome = () => resolve(env.XDG_CONFIG_HOME || join(home, '.config'));
+
+  function statusOf(path) {
+    let st;
+    try { st = fs.lstat(path); } catch (err) { return { status: err?.code === 'EACCES' ? 'unreadable' : 'absent', resolvedPath: null, linked: false }; }
+    let real = null;
+    try { real = fs.realpath(path); } catch { return { status: 'unreadable', resolvedPath: null, linked: st.isSymbolicLink(), note: 'a link that leads nowhere' }; }
+    let target = st;
+    if (st.isSymbolicLink()) { try { target = fs.lstat(real); } catch { return { status: 'unreadable', resolvedPath: real, linked: true }; } }
+    if (!target.isDirectory()) return { status: 'not-a-folder', resolvedPath: real, linked: st.isSymbolicLink() };
+    try { fs.readdir(real); } catch { return { status: 'unreadable', resolvedPath: real, linked: st.isSymbolicLink() }; }
+    return { status: 'ok', resolvedPath: real, linked: st.isSymbolicLink() };
+  }
+
+  function claudeHomes() {
+    const rows = typeof claudeAccounts === 'function' ? (claudeAccounts() || []) : [];
+    const list = rows.filter((r) => r && typeof r.home === 'string' && r.home).map((r) => ({ id: r.id || 'default', label: r.label || r.id || 'Default', home: resolve(r.home) }));
+    if (!list.some((r) => r.id === 'default')) list.unshift({ id: 'default', label: 'Default', home: resolve(env.CLAUDE_CONFIG_DIR || join(home, '.claude')) });
+    return list;
+  }
+  function codexHomes() {
+    const rows = typeof codexAccounts === 'function' ? (codexAccounts() || []) : [];
+    const list = rows.filter((r) => r && typeof r.home === 'string' && r.home).map((r) => ({ id: r.id || 'default', label: r.label || r.id || 'Default', home: resolve(r.home) }));
+    if (!list.some((r) => r.id === 'default')) list.unshift({ id: 'default', label: 'Default', home: resolve(env.CODEX_HOME || join(home, '.codex')) });
+    return list;
+  }
+
+  /** Every root, with what it is now. */
+  function listRoots() {
+    const out = [];
+    const seenIds = new Set();
+    const add = (spec) => {
+      const rootId = rootIdOf(spec);
+      if (seenIds.has(rootId)) return;
+      seenIds.add(rootId);
+      const state = statusOf(spec.path);
+      out.push({
+        rootId, family: spec.family, kind: spec.kind, layout: spec.kind === 'skills' ? 'skill-folders' : 'md-files',
+        runtimes: spec.runtimes, scope: spec.scope, sourceKind: spec.sourceKind,
+        accountId: spec.accountId || null, accountLabel: spec.accountLabel || null, pluginId: spec.pluginId || null,
+        projectPath: spec.projectPath || null, projectLabel: spec.projectLabel || null,
+        path: resolve(spec.path), resolvedPath: state.resolvedPath, linked: state.linked, status: state.status,
+        policy: spec.policy, discovery: spec.discovery, anchor: spec.anchor || null, note: spec.note || state.note || '',
+        installTarget: spec.installTarget || null,
+      });
+    };
+    const owner = (reason) => ({ write: 'owner', reason });
+    const never = (reason) => ({ write: 'never', reason });
+    const sharedOn = !!config()?.sharedAgentsRoot;
+
+    // Claude Code, per account.
+    const claudeDefault = resolve(join(home, '.claude'));
+    for (const acct of claudeHomes()) {
+      const a = { accountId: acct.id, accountLabel: acct.label };
+      // OpenCode reads ~/.claude/skills itself (not another config dir, and not in SynaBun's own OpenCode panel).
+      const opencodeCompat = acct.home === claudeDefault;
+      add({ family: 'claude', kind: 'skills', scope: 'user', sourceKind: 'native', path: join(acct.home, 'skills'), runtimes: opencodeCompat ? ['claude', 'opencode'] : ['claude'], ...a,
+        policy: owner('The account\'s own skills folder.'), discovery: { contract: 'skills/<name>/SKILL.md', verified: 'docs' },
+        installTarget: { runtime: 'claude', scope: 'user' },
+        note: opencodeCompat ? 'A terminal OpenCode reads it too (Claude compatibility); SynaBun\'s own OpenCode serves (the panel, an Assistant brain) start with OPENCODE_DISABLE_CLAUDE_CODE=1 and do not.' : '' });
+      add({ family: 'claude', kind: 'skills', scope: 'synced', sourceKind: 'synced', path: join(acct.home, 'skills', 'synced'), runtimes: ['claude'], ...a,
+        policy: never('Skills the Claude account syncs down; a local change would be overwritten. Customize a copy instead.'), discovery: { contract: 'skills/synced/<name>/SKILL.md, /anthropic-skills:<name>', verified: 'docs' } });
+      add({ family: 'claude', kind: 'commands', scope: 'user', sourceKind: 'native', path: join(acct.home, 'commands'), runtimes: ['claude'], ...a,
+        policy: owner('The account\'s own commands.'), discovery: { contract: 'commands/<ns>/<name>.md → /ns:name', verified: 'docs' } });
+      add({ family: 'claude', kind: 'agents', scope: 'user', sourceKind: 'native', path: join(acct.home, 'agents'), runtimes: ['claude'], ...a,
+        policy: owner('The account\'s own agents.'), discovery: { contract: 'agents/<name>.md', verified: 'docs' } });
+      // Plugins: every installed plugin's skills and commands, read-only (they belong to the plugin).
+      const cache = join(acct.home, 'plugins', 'cache');
+      for (const plugin of pluginFolders(cache)) {
+        const p = { ...a, pluginId: `${plugin.plugin}@${plugin.marketplace}` };
+        add({ family: 'claude', kind: 'skills', scope: 'plugin', sourceKind: 'plugin', path: join(plugin.path, 'skills'), runtimes: ['claude'], ...p,
+          policy: never('Part of an installed plugin: updated through the plugin.'), discovery: { contract: `/${plugin.plugin}:<name>`, verified: 'docs' }, note: `Plugin ${plugin.plugin} (${plugin.marketplace}, ${plugin.version})` });
+        add({ family: 'claude', kind: 'commands', scope: 'plugin', sourceKind: 'plugin', path: join(plugin.path, 'commands'), runtimes: ['claude'], ...p,
+          policy: never('Part of an installed plugin.'), discovery: { contract: `/${plugin.plugin}:<name>`, verified: 'docs' }, note: `Plugin ${plugin.plugin} (${plugin.marketplace}, ${plugin.version})` });
+      }
+    }
+    add({ family: 'claude', kind: 'skills', scope: 'managed', sourceKind: 'managed', path: join(managedDir || claudeManagedDir(platform), '.claude', 'skills'), runtimes: ['claude'],
+      policy: never('Set by an administrator (managed settings).'), discovery: { contract: '<managed>/.claude/skills/<name>/SKILL.md', verified: 'docs' } });
+
+    // Codex, per account.
+    for (const acct of codexHomes()) {
+      const a = { accountId: acct.id, accountLabel: acct.label };
+      add({ family: 'codex', kind: 'skills', scope: 'user', sourceKind: 'native', path: join(acct.home, 'skills'), runtimes: ['codex'], ...a,
+        policy: owner('The Codex home\'s skills folder (the installer\'s default).'), discovery: { contract: '$CODEX_HOME/skills/<name>/SKILL.md', verified: 'fixture codex-cli 0.163.0' },
+        installTarget: { runtime: 'codex', scope: 'user' } });
+      add({ family: 'codex', kind: 'skills', scope: 'system', sourceKind: 'system', path: join(acct.home, 'skills', '.system'), runtimes: ['codex'], ...a,
+        policy: never('Codex\'s own skills.'), discovery: { contract: '$CODEX_HOME/skills/.system/<name>/SKILL.md', verified: 'fixture codex-cli 0.163.0' } });
+      add({ family: 'codex', kind: 'prompts', scope: 'user', sourceKind: 'legacy-bridge', path: join(acct.home, 'prompts'), runtimes: ['codex'], ...a,
+        policy: { write: 'migration', reason: 'Custom prompts are deprecated: SynaBun\'s old bridges move from here to native skill folders.' }, discovery: { contract: '/prompts:<name>', verified: 'docs' } });
+    }
+    add({ family: 'codex', kind: 'skills', scope: 'admin', sourceKind: 'admin', path: codexAdminDir, runtimes: ['codex'],
+      policy: never('Set by an administrator.'), discovery: { contract: '/etc/codex/skills/<name>/SKILL.md', verified: 'docs' } });
+
+    // OpenCode: its configuration folder is OPENCODE_CONFIG_DIR when that is set (2.0.32 then reads skills there,
+    // and not in <config>/opencode), else <config>/opencode.
+    const oc = join(configHome(), 'opencode');
+    const ocDir = opencodeConfigDir();
+    const overridden = ocDir !== oc;
+    add({ family: 'opencode', kind: 'skills', scope: 'user', sourceKind: 'native', path: join(ocDir, 'skills'), runtimes: ['opencode'],
+      policy: owner(overridden ? 'OpenCode\'s skills folder (OPENCODE_CONFIG_DIR).' : 'OpenCode\'s own skills folder.'),
+      discovery: { contract: overridden ? '$OPENCODE_CONFIG_DIR/skills/<name>/SKILL.md' : '<config>/opencode/skills/<name>/SKILL.md', verified: 'fixture opencode 2.0.32' },
+      installTarget: { runtime: 'opencode', scope: 'user' } });
+    add({ family: 'opencode', kind: 'skills', scope: 'user', sourceKind: 'compat', path: join(ocDir, 'skill'), runtimes: ['opencode'],
+      policy: never('The singular folder OpenCode still reads; new skills go to skills/.'),
+      discovery: { contract: overridden ? '$OPENCODE_CONFIG_DIR/skill/<name>/SKILL.md' : '<config>/opencode/skill/<name>/SKILL.md', verified: 'fixture opencode 2.0.32' } });
+    if (overridden) {
+      for (const folder of ['skills', 'skill']) {
+        add({ family: 'opencode', kind: 'skills', scope: 'user', sourceKind: 'inactive', path: join(oc, folder), runtimes: [],
+          policy: never('OpenCode does not read this folder while OPENCODE_CONFIG_DIR is set.'), discovery: { contract: 'not read while OPENCODE_CONFIG_DIR is set', verified: 'fixture opencode 2.0.32' } });
+      }
+    }
+    add({ family: 'opencode', kind: 'commands', scope: 'user', sourceKind: 'legacy-bridge', path: join(oc, 'command'), runtimes: ['opencode'],
+      policy: { write: 'migration', reason: 'Where SynaBun\'s old bridges were written.' }, discovery: { contract: '<config>/opencode/command/<name>.md', verified: 'fixture opencode 2.0.32' } });
+    add({ family: 'opencode', kind: 'commands', scope: 'user', sourceKind: 'native', path: join(oc, 'commands'), runtimes: ['opencode'],
+      policy: never('OpenCode commands: not managed by Skills Studio yet.'), discovery: { contract: '<config>/opencode/commands/<name>.md', verified: 'fixture opencode 2.0.32' } });
+    add({ family: 'opencode', kind: 'commands', scope: 'user', sourceKind: 'legacy-bridge', path: join(home, '.opencode', 'command'), runtimes: ['opencode'],
+      policy: { write: 'migration', reason: 'An old place SynaBun wrote bridges to.' }, discovery: { contract: '~/.opencode/command/<name>.md', verified: 'unverified' } });
+
+    // Antigravity (Google's `agy`): its own skills folder under ~/.gemini/config. It needs no refresh: it reads the folder again by itself.
+    add({ family: 'antigravity', kind: 'skills', scope: 'user', sourceKind: 'native', path: join(home, '.gemini', 'config', 'skills'), runtimes: ['antigravity'],
+      policy: owner('Antigravity\'s own skills folder.'), discovery: { contract: '~/.gemini/config/skills/<name>/SKILL.md', verified: 'docs' },
+      installTarget: { runtime: 'antigravity', scope: 'user' } });
+
+    // Shared.
+    add({ family: 'shared', kind: 'skills', scope: 'shared', sourceKind: 'shared', path: join(home, '.agents', 'skills'), runtimes: ['codex', 'opencode'],
+      policy: sharedOn ? owner('Shared by Codex, OpenCode and other agents; turned on by the owner.') : { write: 'owner-opt-in', reason: 'Shared by Codex, OpenCode and other agents: SynaBun writes here only when you turn it on.' },
+      discovery: { contract: '~/.agents/skills/<name>/SKILL.md', verified: 'fixture codex-cli 0.163.0, opencode 2.0.32' },
+      installTarget: { runtime: 'agents', scope: 'user' } });
+
+    // Projects.
+    let list = [];
+    try { list = projects() || []; } catch { list = []; }
+    for (const proj of list) {
+      if (!proj?.path) continue;
+      const p = { projectPath: resolve(proj.path), projectLabel: proj.label || proj.path, anchor: resolve(proj.path) };
+      const at = (...parts) => join(proj.path, ...parts);
+      add({ family: 'claude', kind: 'skills', scope: 'project', sourceKind: 'native', path: at('.claude', 'skills'), runtimes: ['claude', 'opencode'], ...p,
+        policy: owner('The project\'s Claude skills (shared with the repository).'), discovery: { contract: '.claude/skills/<name>/SKILL.md', verified: 'docs; OpenCode fixture' },
+        installTarget: { runtime: 'claude', scope: 'project' } });
+      add({ family: 'claude', kind: 'commands', scope: 'project', sourceKind: 'native', path: at('.claude', 'commands'), runtimes: ['claude'], ...p,
+        policy: owner('The project\'s commands.'), discovery: { contract: '.claude/commands/<ns>/<name>.md → /ns:name', verified: 'docs' } });
+      add({ family: 'claude', kind: 'agents', scope: 'project', sourceKind: 'native', path: at('.claude', 'agents'), runtimes: ['claude'], ...p,
+        policy: owner('The project\'s agents.'), discovery: { contract: '.claude/agents/<name>.md', verified: 'docs' } });
+      add({ family: 'codex', kind: 'skills', scope: 'project', sourceKind: 'native', path: at('.agents', 'skills'), runtimes: ['codex', 'opencode', 'antigravity'], ...p,
+        policy: owner('The project\'s shared skills (Codex\'s repository folder; OpenCode and Antigravity read it too).'), discovery: { contract: '.agents/skills/<name>/SKILL.md', verified: 'fixture codex-cli 0.163.0, opencode 2.0.32; Antigravity: docs' },
+        installTarget: { runtime: 'codex', scope: 'project' } });
+      add({ family: 'codex', kind: 'skills', scope: 'project', sourceKind: 'compat', path: at('.codex', 'skills'), runtimes: ['codex'], ...p,
+        policy: never('Read by Codex 0.163.0 but not in its guide: new skills go to .agents/skills.'), discovery: { contract: '.codex/skills/<name>/SKILL.md', verified: 'fixture codex-cli 0.163.0' } });
+      add({ family: 'opencode', kind: 'skills', scope: 'project', sourceKind: 'native', path: at('.opencode', 'skills'), runtimes: ['opencode'], ...p,
+        policy: owner('The project\'s OpenCode skills.'), discovery: { contract: '.opencode/skills/<name>/SKILL.md', verified: 'fixture opencode 2.0.32' },
+        installTarget: { runtime: 'opencode', scope: 'project' } });
+    }
+
+    // Bundled.
+    if (bundledDir) {
+      add({ family: 'synabun', kind: 'skills', scope: 'bundled', sourceKind: 'bundled', path: bundledDir, runtimes: [],
+        policy: never('Ships with SynaBun: install it, or customize a copy.'), discovery: { contract: 'not read by a runtime directly', verified: 'n/a' } });
+    }
+    return out;
+  }
+
+  /** Installed plugins under a plugin cache: <marketplace>/<plugin>/<version>, bounded. */
+  function pluginFolders(cache) {
+    const out = [];
+    const list = (dir) => { try { return fs.readdir(dir).filter((n) => !n.startsWith('.')).sort(); } catch { return []; } };
+    for (const marketplace of list(cache).slice(0, 50)) {
+      for (const plugin of list(join(cache, marketplace)).slice(0, 200)) {
+        for (const version of list(join(cache, marketplace, plugin)).slice(0, 20)) {
+          out.push({ marketplace, plugin, version, path: join(cache, marketplace, plugin, version) });
+          if (out.length >= 500) return out;
+        }
+      }
+    }
+    return out;
+  }
+
+  /** OpenCode's configuration folder: OPENCODE_CONFIG_DIR when set, else <config>/opencode (its settings and skills). */
+  function opencodeConfigDir() {
+    return env.OPENCODE_CONFIG_DIR ? resolve(String(env.OPENCODE_CONFIG_DIR)) : join(configHome(), 'opencode');
+  }
+
+  /** The roots that receive installs, by runtime and scope (and account / project). */
+  function installRoot({ runtime, scope = 'user', accountId = 'default', projectPath = null }) {
+    const roots = listRoots();
+    const wanted = roots.filter((r) => r.installTarget && r.installTarget.runtime === runtime && r.installTarget.scope === scope);
+    if (scope === 'project') return wanted.find((r) => projectPath && r.projectPath === resolve(projectPath)) || null;
+    if (runtime === 'claude' || runtime === 'codex') return wanted.find((r) => (r.accountId || 'default') === (accountId || 'default')) || null;
+    return wanted[0] || null;
+  }
+
+  /** Every folder a runtime reads skills from (the import staging is refused inside any of them). */
+  function liveRootPaths() {
+    return listRoots().filter((r) => r.family !== 'synabun').map((r) => r.path);
+  }
+
+  return { listRoots, installRoot, liveRootPaths, claudeHomes, codexHomes, opencodeConfigDir };
+}