synabun 2.0.10 → 2.1.0

package/neural-interface/lib/skills/runtime-checks.js

@@ -0,0 +1,355 @@
+// ── What a runtime says about an installed skill ──
+// An install writes bytes; whether a runtime offers the skill is another question, asked two ways:
+//
+//   eligibility  read from the runtime's own settings, without starting it: Codex's config.toml
+//                ([[skills.config]] path = …, enabled = false), Claude Code's settings.json (skillOverrides
+//                "off", a deny rule on Skill(name)), OpenCode's opencode.json and opencode.jsonc (the last rule of
+//                action `skill` whose resource matches the name: OpenCode 2's `permissions`, an OpenCode 1
+//                `permission.skill` read as OpenCode reads it). 'enabled', 'disabled', or 'unknown' when the
+//                settings cannot be read.
+//   probe        asked of the runtime itself, only when the owner asks (Verify in the Studio): Codex lists its
+//                skills through `codex app-server` (skills/list, forceReload); OpenCode through SynaBun's own
+//                running serve. Claude Code has no listing to ask: it says null with the reason. A probe reads; it
+//                changes no setting.
+//   enable       the one write here, on the owner's click only (POST /api/skills-studio/v2/eligibility/enable):
+//                the setting that turns the skill off is changed to let it through, the file is backed up first
+//                (DATA_HOME/data/skills/backups/settings/), and the answer names the file, the backup and the lines
+//                that changed. Codex: that [[skills.config]] table's `enabled = false` line becomes `enabled = true`
+//                (the rest of config.toml byte for byte). OpenCode: `{ "action": "skill", "resource": "<name>",
+//                "effect": "allow" }` is added as the last rule of opencode.json's `permissions` (a deny in a .jsonc
+//                file is left to the owner, with the rule to add; a deny of every skill is refused unless the owner
+//                confirmed loosening it, `confirmDenyAll`).
+//                Claude Code: the skillOverrides entry or the Skill(name) deny rule is removed (a deny of every skill
+//                is never loosened). A JSON file is changed in one value only, byte for byte otherwise
+//                (lib/skills/json-edit.js): never reformatted. Nothing is changed silently.
+
+import { spawn } from 'node:child_process';
+import { closeSync, constants, copyFileSync, fstatSync, mkdirSync, openSync, readSync, statSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { replaceFileAtomic } from '../confined-fs.js';
+import { parseJsonWithOffsets, nodeAt, appendMember, appendElement, removeMember, removeElement } from './json-edit.js';
+import { OPENCODE_CONFIG_FILES, parseJsonc, permissionRulesOf } from '../opencode-config.js';
+
+const MAX_SETTINGS_BYTES = 1024 * 1024;
+
+/**
+ * A settings file, read bounded: `{ state: 'absent' }` when there is none, `{ state: 'ok', text }`, or
+ * `{ state: 'unreadable' }` when it is there but cannot be read whole (over the bound, not a regular file, no
+ * permission). The size is known before a byte is read; a FIFO or a device is never opened for reading
+ * (O_NONBLOCK, and the open file is checked again before the read).
+ */
+export function readSettingsFile(path, { maxBytes = MAX_SETTINGS_BYTES } = {}) {
+  let st;
+  try { st = statSync(path); } catch (err) { return err?.code === 'ENOENT' || err?.code === 'ENOTDIR' ? { state: 'absent' } : { state: 'unreadable' }; }
+  if (!st.isFile() || st.size > maxBytes) return { state: 'unreadable' };
+  let fd = null;
+  try {
+    fd = openSync(path, constants.O_RDONLY | (constants.O_NONBLOCK || 0));
+    const open = fstatSync(fd);
+    if (!open.isFile() || open.size > maxBytes) return { state: 'unreadable' };
+    const buf = Buffer.alloc(open.size);
+    let got = 0;
+    while (got < buf.length) {
+      const n = readSync(fd, buf, got, buf.length - got, got);
+      if (n <= 0) break;
+      got += n;
+    }
+    return { state: 'ok', text: buf.subarray(0, got).toString('utf-8') };
+  } catch { return { state: 'unreadable' }; }
+  finally { if (fd !== null) { try { closeSync(fd); } catch { /* closed */ } } }
+}
+
+/** The [[skills.config]] tables of a Codex config.toml: `{ path, name, enabled }` each (a reading of those lines only). */
+export function codexSkillConfigs(toml) {
+  const out = [];
+  let current = null;
+  for (const raw of String(toml || '').split(/\r?\n/)) {
+    const line = raw.replace(/\s+#.*$/, '').trim();
+    if (!line) continue;
+    if (/^\[\[\s*skills\.config\s*\]\]$/.test(line)) { current = { path: null, name: null, enabled: null }; out.push(current); continue; }
+    if (/^\[/.test(line)) { current = null; continue; }
+    if (!current) continue;
+    const kv = /^([A-Za-z_]+)\s*=\s*(.+)$/.exec(line);
+    if (!kv) continue;
+    const [, key, value] = kv;
+    const str = /^"((?:[^"\\]|\\.)*)"$/.exec(value)?.[1]?.replace(/\\(["\\])/g, '$1') ?? /^'([^']*)'$/.exec(value)?.[1] ?? null;
+    if (key === 'path' && str !== null) current.path = str;
+    else if (key === 'name' && str !== null) current.name = str;
+    else if (key === 'enabled' && /^(true|false)$/.test(value)) current.enabled = value === 'true';
+  }
+  return out;
+}
+
+const skillPatternMatches = (pattern, name) => new RegExp(`^${String(pattern).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.')}$`).test(name);
+
+/**
+ * The last rule of a config that decides skill `name`: `{ effect: 'allow' | 'ask' | 'deny', resource }` of the last
+ * rule of action `skill` whose resource matches it (OpenCode 2's `permissions`, after an OpenCode 1
+ * `permission.skill` converted), or null when none does.
+ */
+export function opencodeSkillRule(config, name) {
+  let found = null;
+  for (const rule of permissionRulesOf(config)) {
+    if (rule.action === 'skill' && skillPatternMatches(rule.resource, name)) found = { effect: rule.effect, resource: rule.resource };
+  }
+  return found;
+}
+
+/** What a config decides for skill `name` ('allow' | 'ask' | 'deny' | null): opencodeSkillRule's effect. */
+export function opencodeSkillPermission(config, name) {
+  return opencodeSkillRule(config, name)?.effect ?? null;
+}
+
+/**
+ * @param {object} o
+ * @param {(accountId: string) => string} o.codexHome
+ * @param {(accountId: string) => string} o.claudeHome
+ * @param {() => string} o.opencodeConfigDir <config>/opencode
+ * @param {() => string|null} [o.codexBin]
+ * @param {(accountId: string) => object} [o.codexEnv] the environment Codex runs under for that account
+ * @param {() => object|null} [o.opencodeClient] SynaBun's running OpenCode serve client, when there is one
+ */
+export function createSkillsRuntimeChecks({ codexHome, claudeHome, opencodeConfigDir, codexBin = () => null, codexEnv = () => process.env, opencodeClient = () => null, spawnImpl = spawn, timeoutMs = 20000, backupDir = null } = {}) {
+  /**
+   * Whether the runtime's settings let the skill through, with the setting that does not: `{ state, reason }`.
+   * `state` is 'enabled', 'disabled' or 'unknown'; `reason` names the file and the rule only when it is 'disabled'
+   * (`kind`: codex-config, claude-override, claude-deny, opencode-permission), or why nothing could be read.
+   */
+  function eligibilityDetail({ runtime, name, skillMd, accountId = 'default', projectPath = null }) {
+    if (runtime === 'codex') {
+      const file = join(codexHome(accountId), 'config.toml');
+      const read = readSettingsFile(file);
+      if (read.state === 'absent') return { state: 'enabled', reason: null };   // no config.toml: nothing turns a skill off
+      if (read.state !== 'ok') return { state: 'unknown', reason: { kind: 'unreadable', file } };       // there, but not read whole: it may turn it off
+      const tables = codexSkillConfigs(read.text);
+      const hit = tables.filter((t) => (t.path && resolve(t.path) === resolve(skillMd)) || (t.name && t.name === name));
+      if (!hit.length) return { state: 'enabled', reason: null };
+      const last = hit[hit.length - 1];
+      return last.enabled === false ? { state: 'disabled', reason: { kind: 'codex-config', file, table: { path: last.path, name: last.name } } } : { state: 'enabled', reason: null };
+    }
+    if (runtime === 'claude') {
+      const files = [join(claudeHome(accountId), 'settings.json')];
+      if (projectPath) files.push(join(projectPath, '.claude', 'settings.json'), join(projectPath, '.claude', 'settings.local.json'));
+      let unknown = null;
+      for (const file of files) {
+        const read = readSettingsFile(file);
+        if (read.state === 'absent') continue;
+        if (read.state !== 'ok') { unknown = { kind: 'unreadable', file }; continue; }
+        let data;
+        try { data = JSON.parse(read.text); } catch { unknown = { kind: 'invalid-json', file }; continue; }
+        if (data?.skillOverrides && data.skillOverrides[name] === 'off') return { state: 'disabled', reason: { kind: 'claude-override', file, key: name } };
+        const deny = Array.isArray(data?.permissions?.deny) ? data.permissions.deny : [];
+        const rule = deny.find((r) => r === 'Skill' || r === `Skill(${name})` || r === `Skill(${name} *)`);
+        if (rule) return { state: 'disabled', reason: { kind: 'claude-deny', file, rule } };
+      }
+      return unknown ? { state: 'unknown', reason: unknown } : { state: 'enabled', reason: null };
+    }
+    if (runtime === 'opencode') {
+      // OpenCode 2 reads opencode.json, then opencode.jsonc over it: the last matching rule of both decides.
+      let decided = null;
+      for (const file of OPENCODE_CONFIG_FILES) {
+        const full = join(opencodeConfigDir(), file);
+        const read = readSettingsFile(full);
+        if (read.state === 'absent') continue;
+        if (read.state !== 'ok') return { state: 'unknown', reason: { kind: 'unreadable', file: full } };
+        let data;
+        try { data = file.endsWith('.jsonc') ? parseJsonc(read.text) : JSON.parse(read.text); } catch { return { state: 'unknown', reason: { kind: 'invalid-json', file: full } }; }
+        const rule = opencodeSkillRule(data, name);
+        if (rule) decided = { ...rule, file: full };
+      }
+      if (decided?.effect !== 'deny') return { state: 'enabled', reason: null };
+      return { state: 'disabled', reason: { kind: 'opencode-permission', file: decided.file, pattern: decided.resource, action: 'deny' } };
+    }
+    return { state: 'unknown', reason: { kind: 'unknown-runtime' } };
+  }
+
+  /** 'enabled' | 'disabled' | 'unknown' (eligibilityDetail's state). */
+  function eligibility(o) { return eligibilityDetail(o).state; }
+
+  /**
+   * Let the skill through the setting that turns it off (the owner pressed "Enable for …"). Reads the detail
+   * again first; a skill that is not turned off changes nothing (`changed: false`). The file is copied into
+   * `backupDir` before it is written; the answer carries the file, the backup and the lines that changed, so the
+   * page can show exactly what was done. Throws an EnableError (status, code) when the file cannot be changed
+   * safely: then the answer says what to change by hand.
+   */
+  function enable({ runtime, name, skillMd, accountId = 'default', projectPath = null, confirmDenyAll = false }) {
+    const detail = eligibilityDetail({ runtime, name, skillMd, accountId, projectPath });
+    if (detail.state !== 'disabled') return { ok: true, changed: false, state: detail.state, file: detail.reason?.file || null };
+    const { file } = detail.reason;
+    const read = readSettingsFile(file);
+    if (read.state !== 'ok') throw new EnableError(409, `${file} could not be read whole: change it yourself.`, 'settings_unreadable', { file });
+    let next;
+    let changed = [];
+    if (detail.reason.kind === 'codex-config') {
+      const out = enableCodexTable(read.text, { skillMd, name });
+      if (!out) throw new EnableError(409, `The [[skills.config]] table that turns /${name} off in ${file} could not be changed in place: set its "enabled = true" yourself.`, 'settings_unchanged', { file });
+      next = out.text; changed = out.changed;
+    } else if (detail.reason.kind === 'opencode-permission') {
+      const allowRule = { action: 'skill', resource: name, effect: 'allow' };
+      if (/\.jsonc$/i.test(file)) throw new EnableError(409, `${file} has comments, which SynaBun does not rewrite: add ${JSON.stringify(allowRule)} as the last rule of its "permissions" yourself.`, 'jsonc_unsupported', { file, rule: allowRule });
+      const out = enableOpencodeRule(read.text, { name, confirmDenyAll, everySkill: detail.reason.pattern === '*' });
+      if (out.error) throw new EnableError(409, out.error.message, out.error.code, { file, rule: allowRule });
+      next = out.text; changed = out.changed;
+    } else if (detail.reason.kind === 'claude-override') {
+      const root = parseJsonWithOffsets(read.text);
+      const overrides = nodeAt(root, ['skillOverrides']);
+      next = overrides?.members?.length === 1 ? removeMember(read.text, root, 'skillOverrides') : removeMember(read.text, overrides, name);
+      changed = [`skillOverrides["${name}"] removed`];
+    } else if (detail.reason.kind === 'claude-deny') {
+      if (detail.reason.rule === 'Skill') throw new EnableError(409, `${file} denies every skill ("Skill" in permissions.deny): SynaBun does not loosen that rule; change it yourself.`, 'deny_all', { file, rule: 'Skill' });
+      const root = parseJsonWithOffsets(read.text);
+      const deny = nodeAt(root, ['permissions', 'deny']);
+      const at = deny?.elements?.findIndex((e) => e.value === detail.reason.rule) ?? -1;
+      if (at < 0) throw new EnableError(409, 'The rule moved while it was being changed: nothing was written.', 'settings_unchanged', { file });
+      next = removeElement(read.text, deny, at);
+      changed = [`permissions.deny: "${detail.reason.rule}" removed`];
+    } else throw new EnableError(409, 'Nothing SynaBun can change.', 'settings_unchanged', { file });
+    JSON.parse(/\.toml$/i.test(file) ? '{}' : next);   // a JSON edit that does not parse is never written
+    const backup = backupSettings(file);
+    const mode = (() => { try { return statSync(file).mode & 0o777; } catch { return 0o600; } })();
+    replaceFileAtomic(file, next, { mode });
+    const after = eligibilityDetail({ runtime, name, skillMd, accountId, projectPath });
+    return { ok: after.state === 'enabled', changed: true, state: after.state, file, backup, lines: changed };
+  }
+
+  function backupSettings(file) {
+    if (!backupDir) return null;
+    mkdirSync(backupDir, { recursive: true, mode: 0o700 });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const target = join(backupDir, `${stamp}-${basename(file)}`);
+    copyFileSync(file, target, constants.COPYFILE_EXCL);
+    return target;
+  }
+
+  /** Ask Codex itself: `codex app-server`, initialize, skills/list. */
+  function probeCodex({ skillMd, accountId, projectPath }) {
+    const bin = codexBin();
+    if (!bin) return Promise.resolve({ discovered: null, code: 'not-installed', method: 'codex app-server', reason: 'Codex is not installed.' });
+    return new Promise((resolveProbe) => {
+      let done = false;
+      const env = { ...codexEnv(accountId) };
+      const child = spawnImpl(bin, ['app-server'], { cwd: projectPath || codexHome(accountId), env, stdio: ['pipe', 'pipe', 'pipe'] });
+      const finish = (result) => { if (done) return; done = true; clearTimeout(timer); try { child.stdin?.end?.(); } catch {} try { child.kill(); } catch {} resolveProbe({ method: 'codex app-server skills/list', ...result }); };
+      const timer = setTimeout(() => finish({ discovered: null, code: 'no-answer', reason: 'Codex did not answer in time.' }), timeoutMs);
+      // Nothing is written once the probe is settled: Codex exited, could not be started, answered or ran out of time.
+      const send = (message) => { if (done || !child.stdin?.writable) return; try { child.stdin.write(`${JSON.stringify(message)}\n`); } catch {} };
+      // A Codex that exits or fails to start as a request is written fails the pipe after write() returned (EPIPE, a
+      // write after end): unhandled, that error would end the server. A probe whose Codex died early has failed.
+      child.stdin?.on?.('error', () => finish({ discovered: null, code: 'no-answer', reason: 'Codex stopped before it answered.' }));
+      let buf = '';
+      child.on?.('error', (err) => finish({ discovered: null, code: err?.code === 'ENOENT' ? 'not-installed' : 'no-answer', reason: `Codex could not be started (${err?.code || err?.message}).` }));
+      child.on?.('exit', () => finish({ discovered: null, code: 'no-answer', reason: 'Codex stopped before it answered.' }));
+      child.stdout.on('data', (d) => {
+        buf += d;
+        let i;
+        while ((i = buf.indexOf('\n')) >= 0) {
+          const line = buf.slice(0, i); buf = buf.slice(i + 1);
+          let m; try { m = JSON.parse(line); } catch { continue; }
+          if (m.id === 1) {
+            send({ jsonrpc: '2.0', method: 'initialized', params: {} });
+            send({ jsonrpc: '2.0', id: 2, method: 'skills/list', params: { cwds: [projectPath || codexHome(accountId)], forceReload: true } });
+          } else if (m.id === 2) {
+            const skills = (m.result?.data || []).flatMap((e) => e.skills || []);
+            const hit = skills.find((s) => typeof s.path === 'string' && resolve(s.path) === resolve(skillMd));
+            finish(hit ? { discovered: true, enabled: hit.enabled !== false, scope: hit.scope || null } : { discovered: false, listed: skills.length });
+          }
+        }
+      });
+      send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { clientInfo: { name: 'synabun-skills-verify', version: '1' }, capabilities: { experimentalApi: true } } });
+    });
+  }
+
+  async function probe({ runtime, name, skillMd, accountId = 'default', projectPath = null }) {
+    if (runtime === 'codex') return probeCodex({ skillMd, accountId, projectPath });
+    if (runtime === 'opencode') {
+      const client = opencodeClient();
+      if (!client?.app?.skills) return { discovered: null, code: 'not-running', method: 'opencode serve', reason: 'SynaBun\'s OpenCode is not running: start a new OpenCode session to check.' };
+      try {
+        const res = await client.app.skills(projectPath ? { directory: projectPath } : {});
+        const list = Array.isArray(res?.data) ? res.data : [];
+        const hit = list.find((s) => (s.location && resolve(s.location) === resolve(skillMd)) || s.name === name);
+        return { method: 'opencode serve /api/skill', discovered: !!hit, ...(hit ? {} : { listed: list.length }) };
+      } catch (err) { return { discovered: null, code: 'no-answer', method: 'opencode serve', reason: err?.message || String(err) }; }
+    }
+    if (runtime === 'claude') return { discovered: null, code: 'no-list', method: 'none', reason: 'Claude Code has no list to ask; its folder rules were checked instead.' };
+    return { discovered: null, method: 'none', reason: 'Unknown runtime.' };
+  }
+
+  return { eligibility, eligibilityDetail, enable, probe };
+}
+
+/**
+ * opencode.json with `{ "action": "skill", "resource": "<name>", "effect": "allow" }` as the last rule of its
+ * `permissions` (the list made when there is none), the rest of the text byte for byte: OpenCode 2 applies the last
+ * rule that matches, after the rules of an OpenCode 1 `permission` object, which stays as it was. `everySkill`: the
+ * rule that turns the skill off denies every skill, which SynaBun loosens only when the owner confirmed it
+ * (`confirmDenyAll`).
+ * @returns {{ text?: string, changed?: string[], error?: { code: string, message: string } }}
+ */
+export function enableOpencodeRule(text, { name, confirmDenyAll = false, everySkill = false }) {
+  const root = parseJsonWithOffsets(text);
+  if (root.type !== 'object') return { error: { code: 'settings_unchanged', message: 'The settings file is not a JSON object.' } };
+  if (everySkill && !confirmDenyAll) {
+    return { error: { code: 'deny_all', message: `The OpenCode configuration denies every skill: SynaBun does not loosen that rule by itself. Allow "${name}" yourself, or confirm loosening it.` } };
+  }
+  const rule = `{ "action": "skill", "resource": ${JSON.stringify(name)}, "effect": "allow" }`;
+  const changed = [`permissions: ${rule} added`];
+  const permissions = nodeAt(root, ['permissions']);
+  if (!permissions) return { text: appendMember(text, root, 'permissions', `[${rule}]`), changed };
+  if (permissions.type !== 'array') return { error: { code: 'settings_unchanged', message: '"permissions" is not a list: change it yourself.' } };
+  return { text: appendElement(text, permissions, rule), changed };
+}
+
+export class EnableError extends Error {
+  constructor(status, message, code, extra = {}) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    Object.assign(this, extra);
+  }
+}
+
+/**
+ * The text of a Codex config.toml with the `enabled = false` line of the [[skills.config]] table(s) that name this
+ * skill turned to `enabled = true`; every other byte stays (comments and spacing included). Null when no such
+ * line is there to change.
+ */
+export function enableCodexTable(toml, { skillMd, name }) {
+  const lines = String(toml || '').split(/(\r?\n)/);   // text and its separators, kept
+  const out = [];
+  const changed = [];
+  let current = null;   // the table being read: { path, name, enabledAt }
+  const flush = () => {
+    if (!current) return;
+    const hit = (current.path && resolve(current.path) === resolve(skillMd)) || (current.name && current.name === name);
+    if (hit && current.enabledAt !== null) {
+      const raw = out[current.enabledAt];
+      out[current.enabledAt] = raw.replace(/^(\s*enabled\s*=\s*)false(\s*(#.*)?)$/, '$1true$2');
+      changed.push({ line: current.lineNo, before: raw, after: out[current.enabledAt] });
+    }
+    current = null;
+  };
+  let lineNo = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    out.push(raw);
+    if (i % 2 === 1) continue;   // a separator
+    lineNo++;
+    const line = raw.replace(/\s+#.*$/, '').trim();
+    if (!line) continue;
+    if (/^\[\[\s*skills\.config\s*\]\]$/.test(line)) { flush(); current = { path: null, name: null, enabledAt: null, lineNo: null }; continue; }
+    if (/^\[/.test(line)) { flush(); continue; }
+    if (!current) continue;
+    const kv = /^([A-Za-z_]+)\s*=\s*(.+)$/.exec(line);
+    if (!kv) continue;
+    const [, key, value] = kv;
+    const str = /^"((?:[^"\\]|\\.)*)"$/.exec(value)?.[1]?.replace(/\\(["\\])/g, '$1') ?? /^'([^']*)'$/.exec(value)?.[1] ?? null;
+    if (key === 'path' && str !== null) current.path = str;
+    else if (key === 'name' && str !== null) current.name = str;
+    else if (key === 'enabled' && value === 'false') { current.enabledAt = out.length - 1; current.lineNo = lineNo; }
+    else if (key === 'enabled' && value === 'true') { current.enabledAt = null; current.lineNo = null; }
+  }
+  flush();
+  return changed.length ? { text: out.join(''), changed } : null;
+}

package/neural-interface/lib/skills/scan-assets.js

@@ -0,0 +1,252 @@
+import { inflateSync, brotliDecompressSync } from 'node:zlib';
+
+export const ASSET_EXT = /\.(?:png|jpe?g|gif|webp|ico|woff2?|ttf|otf)$/i;
+const MAX = 16 * 1024 * 1024;
+export const ASSET_LIMITS = Object.freeze({ assetInflated: 8 * 1024 * 1024, scanInflated: 32 * 1024 * 1024, ratio: 100, ratioSlack: 64 * 1024 });
+export const assetBudget = () => ({ inflated: 0, exhausted: false });
+export const scriptMarkers = (s) => /(?:^|\n)[\t ]*#!|<\?php\b|<\?=|<%|<script\b/i.test(s);
+// Long, language-specific markers are evidence even among non-printable bytes.
+// Short markers stay restricted to printable/decoded text to avoid random pixel/glyph hits.
+const rawMarkers = (s) => /<\?php\b|<script\b/i.test(s);
+const printableLines = (s) => s.matchAll(/(?:^|\n)([\t\x20-\x7e]{4,})(?=\r?\n|$)/g);
+const crc32 = (b) => { let crc = -1; for (const x of b) { crc ^= x; for (let n = 0; n < 8; n++) crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0); } return (crc ^ -1) >>> 0; };
+
+// Validate framing, offsets and the exact end, without rendering or executing the asset.
+// Bounded decompression is only for metadata/font tables, never archive extraction.
+export function inspectAsset(path, b, suspicious, { budget = assetBudget(), local = { inflated: 0 }, heuristic = () => {} } = {}) {
+  let script = false;
+  const raw = (data) => {
+    const text = data.toString('latin1');
+    if (rawMarkers(text)) script = true;
+    // Random printable substrings of compressed pixels/glyphs are not commands.
+    for (const [, line] of printableLines(text)) { const hit = suspicious(line); if (scriptMarkers(line) || hit === 'strong') script = true; else if (hit) heuristic(line); }
+  };
+  const text = (data, encoding = 'utf8') => {
+    const value = typeof data === 'string' ? data : encoding === 'utf8' ? new TextDecoder('utf8', { fatal: true }).decode(data) : data.toString(encoding);
+    if (scriptMarkers(value)) script = true;
+    let start = 0;
+    while (start < value.length && !script) {
+      const newline = value.indexOf('\n', start), end = newline < 0 ? value.length : newline;
+      const line = value.slice(start, end), hit = suspicious(line);
+      if (hit === 'strong') script = true;
+      else if (hit) heuristic(line);
+      start = end + 1;
+    }
+  };
+  const range = (at, n) => Number.isSafeInteger(at) && Number.isSafeInteger(n) && at >= 0 && n >= 0 && at + n <= b.length;
+  const ascii = (at, n) => b.subarray(at, at + n).toString('latin1');
+  const unpack = (data, brotli, visit, expected) => {
+    const cap = Math.min(ASSET_LIMITS.assetInflated - local.inflated, ASSET_LIMITS.scanInflated - budget.inflated, data.length * ASSET_LIMITS.ratio + ASSET_LIMITS.ratioSlack);
+    const exceeded = () => { budget.exhausted = true; return Object.assign(new Error('asset-decompression-budget'), { budget: true }); };
+    if (budget.exhausted || cap <= 0 || expected > cap) throw exceeded();
+    let out;
+    try {
+      const decoded = (brotli ? brotliDecompressSync : inflateSync)(data, { maxOutputLength: cap, info: true });
+      if (decoded.engine.bytesWritten !== data.length) throw new Error('trailing compressed bytes');
+      out = decoded.buffer;
+    }
+    catch (err) { if (err.code === 'ERR_BUFFER_TOO_LARGE') throw exceeded(); throw err; }
+    local.inflated += out.length; budget.inflated += out.length;
+    if (expected != null && out.length !== expected) throw new Error('invalid inflated length');
+    visit(out); // Scan now; never retain decompressed outputs across chunks/tables/assets.
+  };
+  const fontTable = (tag, data) => {
+    raw(data);
+    if (tag !== 'name') {
+      // A table made entirely of text is decoded metadata, not a random glyph byte run.
+      if (/^[\t\r\n\x20-\x7e]+$/.test(data.toString('latin1'))) text(data, 'latin1');
+      return;
+    }
+    if (data.length < 6) throw new Error('invalid name table');
+    const count = data.readUInt16BE(2), start = data.readUInt16BE(4);
+    if (6 + count * 12 > data.length || start > data.length) throw new Error('invalid names');
+    for (let i = 0; i < count; i++) {
+      const at = 6 + i * 12, platform = data.readUInt16BE(at), length = data.readUInt16BE(at + 8), offset = start + data.readUInt16BE(at + 10);
+      if (offset + length > data.length) throw new Error('invalid name');
+      const value = data.subarray(offset, offset + length);
+      if (platform === 0 || platform === 3) { if (length % 2) throw new Error('invalid unicode name'); text(Buffer.from(value).swap16(), 'utf16le'); }
+      else text(value, 'latin1');
+    }
+  };
+  function png() {
+    if (b.subarray(0, 8).toString('hex') !== '89504e470d0a1a0a') return false;
+    let at = 8, image = false, header = false;
+    while (range(at, 12)) {
+      const n = b.readUInt32BE(at), tag = ascii(at + 4, 4);
+      if (!range(at, n + 12) || !/^[A-Za-z]{4}$/.test(tag) || crc32(b.subarray(at + 4, at + 8 + n)) !== b.readUInt32BE(at + 8 + n)) return false;
+      if (!header && (tag !== 'IHDR' || n !== 13 || !b.readUInt32BE(at + 8) || !b.readUInt32BE(at + 12))) return false;
+      if (header && tag === 'IHDR') return false;
+      header = true;
+      const data = b.subarray(at + 8, at + 8 + n);
+      if (tag === 'IDAT') image = true;
+      if (tag === 'tEXt') { const zero = data.indexOf(0); if (zero < 1) return false; text(data.subarray(zero + 1), 'latin1'); }
+      if (tag === 'zTXt' || tag === 'iCCP') { const zero = data.indexOf(0); if (zero < 1 || data[zero + 1] !== 0) return false; unpack(data.subarray(zero + 2), false, tag === 'zTXt' ? (out) => text(out, 'latin1') : raw); }
+      if (tag === 'iTXt') {
+        const zero = data.indexOf(0); if (zero < 1 || ![0, 1].includes(data[zero + 1]) || data[zero + 2] !== 0) return false;
+        const lang = data.indexOf(0, zero + 3), translated = data.indexOf(0, lang + 1);
+        if (lang < 0 || translated < 0) return false;
+        if (data[zero + 1]) unpack(data.subarray(translated + 1), false, text);
+        else text(data.subarray(translated + 1));
+      }
+      at += n + 12;
+      if (tag === 'IEND') return n === 0 && image && at === b.length;
+    }
+    return false;
+  }
+  function jpeg() {
+    if (b[0] !== 255 || b[1] !== 216) return false;
+    let at = 2, frame = false, scan = false;
+    while (at < b.length) {
+      if (b[at++] !== 255) return false;
+      while (b[at] === 255) at++;
+      const marker = b[at++];
+      if (marker === 0xd9) return frame && scan && at === b.length;
+      if (!range(at, 2) || marker === 0 || marker === 0xd8) return false;
+      const n = b.readUInt16BE(at); if (n < 2 || !range(at, n)) return false;
+      if (marker === 0xfe) text(b.subarray(at + 2, at + n), 'latin1');
+      if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) frame = true;
+      at += n;
+      if (marker === 0xda) {
+        scan = true;
+        while (at < b.length) {
+          if (b[at] !== 255) { at++; continue; }
+          if (b[at + 1] === 0 || b[at + 1] >= 0xd0 && b[at + 1] <= 0xd7) { at += 2; continue; }
+          break;
+        }
+      }
+    }
+    return false;
+  }
+  function gif() {
+    if (!['GIF87a', 'GIF89a'].includes(ascii(0, 6)) || !range(0, 13) || !b.readUInt16LE(6) || !b.readUInt16LE(8)) return false;
+    let at = 13 + (b[10] & 128 ? 3 * 2 ** ((b[10] & 7) + 1) : 0), image = false;
+    const blocks = (comment = false) => { const parts = []; while (range(at, 1)) { const n = b[at++]; if (!n) { if (comment) text(Buffer.concat(parts), 'latin1'); return true; } if (!range(at, n)) return false; if (comment) parts.push(b.subarray(at, at + n)); at += n; } return false; };
+    while (range(at, 1)) {
+      const tag = b[at++];
+      if (tag === 0x3b) return image && at === b.length;
+      if (tag === 0x21) { if (!range(at, 1) || !blocks(b[at++] === 0xfe)) return false; }
+      else if (tag === 0x2c) {
+        if (!range(at, 9)) return false;
+        const flags = b[at + 8]; at += 9 + (flags & 128 ? 3 * 2 ** ((flags & 7) + 1) : 0);
+        if (!range(at, 1) || b[at] < 2 || b[at++] > 8 || !blocks()) return false;
+        image = true;
+      } else return false;
+    }
+    return false;
+  }
+  function webp() {
+    if (!range(0, 12) || ascii(0, 4) !== 'RIFF' || ascii(8, 4) !== 'WEBP' || b.readUInt32LE(4) + 8 !== b.length) return false;
+    let at = 12, image = false;
+    while (range(at, 8)) {
+      const tag = ascii(at, 4), n = b.readUInt32LE(at + 4);
+      if (!range(at + 8, n + (n & 1))) return false;
+      if (['VP8 ', 'VP8L', 'ANMF'].includes(tag)) image = true;
+      at += 8 + n + (n & 1);
+    }
+    return image && at === b.length;
+  }
+  function ico() {
+    if (!range(0, 6) || b.readUInt32LE(0) !== 0x10000) return false;
+    const count = b.readUInt16LE(4); if (!count || !range(6, count * 16)) return false;
+    let end = 6 + count * 16;
+    for (let i = 0; i < count; i++) {
+      const n = b.readUInt32LE(6 + i * 16 + 8), at = b.readUInt32LE(6 + i * 16 + 12);
+      if (at !== end || !range(at, n) || n < 8) return false;
+      const image = b.subarray(at, at + n);
+      if (image.subarray(0, 8).toString('hex') === '89504e470d0a1a0a') { const reason = inspectAsset('icon.png', image, suspicious, { budget, local, heuristic }); if (reason) throw Object.assign(new Error(reason), { reason }); }
+      else {
+        if (n < 40 || image.readUInt32LE(0) !== 40 || image.readUInt32LE(16) !== 0) return false;
+        const w = image.readInt32LE(4), h = Math.abs(image.readInt32LE(8)) / 2, depth = image.readUInt16LE(14);
+        if (w <= 0 || !Number.isInteger(h) || !h || ![1, 4, 8, 16, 24, 32].includes(depth)) return false;
+        const colors = image.readUInt32LE(32) || (depth <= 8 ? 2 ** depth : 0);
+        if (40 + colors * 4 + (Math.ceil(w * depth / 32) * 4 + Math.ceil(w / 32) * 4) * h !== n) return false;
+      }
+      end = at + n;
+    }
+    return end === b.length;
+  }
+  function font() {
+    const tag = ascii(0, 4), woff = /\.woff$/i.test(path), woff2 = /\.woff2$/i.test(path);
+    if (woff || woff2) {
+      if (tag !== (woff2 ? 'wOF2' : 'wOFF') || !range(0, woff2 ? 48 : 44) || b.readUInt32BE(8) !== b.length || !b.readUInt16BE(12) || b.readUInt16BE(14)) return false;
+      const metaAt = b.readUInt32BE(woff2 ? 28 : 24), metaSize = b.readUInt32BE(woff2 ? 32 : 28);
+      const metaOriginal = b.readUInt32BE(woff2 ? 36 : 32);
+      const privateAt = b.readUInt32BE(woff2 ? 40 : 36), privateSize = b.readUInt32BE(woff2 ? 44 : 40);
+      if (!range(metaAt, metaSize) || !range(privateAt, privateSize) || (!metaSize && (metaAt || metaOriginal)) || (!privateSize && privateAt)) return false;
+      const count = b.readUInt16BE(12), blocks = [];
+      let directoryEnd;
+      if (woff2) {
+        const tags = 'cmap head hhea hmtx maxp name OS/2 post cvt_ fpgm glyf loca prep CFF_ VORG EBDT EBLC gasp hdmx kern LTSH PCLT VDMX vhea vmtx BASE GDEF GPOS GSUB EBSC JSTF MATH CBDT CBLC COLR CPAL SVG_ sbix acnt avar bdat bloc bsln cvar fdsc feat fmtx fvar gvar hsty just lcar mort morx opbd prop trak Zapf Silf Glat Gloc Feat Sill'.split(' ').map((s) => s.replace('_', ' '));
+        let pos = 48, total = 0;
+        const byte = () => { if (!range(pos, 1)) throw new Error('short directory'); return b[pos++]; };
+        const u32 = () => { if (!range(pos, 4)) throw new Error('short directory'); const n = b.readUInt32BE(pos); pos += 4; return n; };
+        const base128 = () => {
+          let n = 0;
+          for (let i = 0; i < 5; i++) { const v = byte(); if ((!i && v === 128) || n > 0x1ffffff) throw new Error('invalid base128'); n = n * 128 + (v & 127); if (!(v & 128)) return n; }
+          throw new Error('invalid base128');
+        };
+        const u255 = () => { const v = byte(); return v === 253 ? byte() * 256 + byte() : v === 254 ? byte() + 506 : v === 255 ? byte() + 253 : v; };
+        const tables = [];
+        for (let i = 0; i < count; i++) {
+          const flags = byte(), tag = (flags & 63) === 63 ? String.fromCharCode(byte(), byte(), byte(), byte()) : tags[flags & 63];
+          const version = flags >>> 6, original = base128(), transformed = ['glyf', 'loca'].includes(tag) ? version !== 3 : version !== 0;
+          if (['glyf', 'loca'].includes(tag) ? ![0, 3].includes(version) : version && !(tag === 'hmtx' && version === 1)) return false;
+          const size = transformed ? base128() : original;
+          if (tag === 'loca' && transformed && size !== 0) return false;
+          tables.push({ tag, offset: total, size, transformed }); total += size;
+        }
+        if (ascii(4, 4) === 'ttcf') {
+          if (![0x10000, 0x20000].includes(u32())) return false;
+          const fonts = u255(); if (!fonts || fonts > b.length) return false;
+          for (let i = 0; i < fonts; i++) {
+            const n = u255(), flavor = u32(), used = new Set(), names = new Set();
+            if (!n || n > count || ![0x10000, 0x4f54544f].includes(flavor)) return false;
+            for (let j = 0; j < n; j++) { const index = u255(); if (index >= count || used.has(index) || names.has(tables[index].tag)) return false; used.add(index); names.add(tables[index].tag); }
+            if (names.has('glyf') !== names.has('loca')) return false;
+          }
+        } else if (new Set(tables.map((t) => t.tag)).size !== count) return false;
+        directoryEnd = pos;
+        const size = b.readUInt32BE(20); if (!size || !range(pos, size)) return false;
+        blocks.push({ offset: pos, size, visit: () => unpack(b.subarray(pos, pos + size), true, (out) => {
+          for (const t of tables) fontTable(t.tag, out.subarray(t.offset, t.offset + t.size));
+        }, total) });
+      } else {
+        directoryEnd = 44 + count * 20; if (!range(44, count * 20)) return false;
+        for (let i = 0; i < count; i++) {
+          const at = 44 + i * 20, offset = b.readUInt32BE(at + 4), size = b.readUInt32BE(at + 8), original = b.readUInt32BE(at + 12), tableTag = ascii(at, 4);
+          if (!range(offset, size) || size > original || offset % 4) return false;
+          blocks.push({ offset, size, visit: () => size < original ? unpack(b.subarray(offset, offset + size), false, (out) => fontTable(tableTag, out), original) : fontTable(tableTag, b.subarray(offset, offset + size)) });
+        }
+      }
+      blocks.sort((a, b) => a.offset - b.offset);
+      if (metaSize) blocks.push({ offset: metaAt, size: metaSize, visit: () => unpack(b.subarray(metaAt, metaAt + metaSize), woff2, text, metaOriginal) });
+      if (privateSize) blocks.push({ offset: privateAt, size: privateSize, visit: () => raw(b.subarray(privateAt, privateAt + privateSize)) });
+      let end = directoryEnd;
+      for (const block of blocks) {
+        if (block.offset !== end && block.offset !== Math.ceil(end / 4) * 4 || block.offset < end || !b.subarray(end, block.offset).every((v) => v === 0)) return false;
+        end = block.offset + block.size;
+      }
+      if (end !== b.length && !(Math.ceil(end / 4) * 4 === b.length && b.subarray(end).every((v) => v === 0))) return false;
+      for (const block of blocks) block.visit();
+      return true;
+    }
+    if (!range(0, 12) || (/\.ttf$/i.test(path) ? b.readUInt32BE(0) !== 0x10000 : tag !== 'OTTO')) return false;
+    const count = b.readUInt16BE(4); if (!count || !range(12, count * 16)) return false;
+    let end = 12 + count * 16;
+    for (let i = 0; i < count; i++) {
+      const at = 12 + i * 16, offset = b.readUInt32BE(at + 8), size = b.readUInt32BE(at + 12);
+      if (offset < 12 + count * 16 || !range(offset, size)) return false;
+      fontTable(ascii(at, 4), b.subarray(offset, offset + size));
+      end = Math.max(end, offset + size);
+    }
+    return end === b.length || Math.ceil(end / 4) * 4 === b.length && b.subarray(end).every((x) => x === 0);
+  }
+  try {
+    if (b.length > MAX) return 'asset-too-large';
+    const valid = /\.png$/i.test(path) ? png() : /\.jpe?g$/i.test(path) ? jpeg() : /\.gif$/i.test(path) ? gif() : /\.webp$/i.test(path) ? webp() : /\.ico$/i.test(path) ? ico() : font();
+    if (!valid) return 'asset-invalid-structure';
+    raw(b);
+    if (script) return 'asset-script-content';
+    return null;
+  } catch (err) { return err.reason || (err.budget ? 'asset-decompression-budget' : 'asset-invalid-structure'); }
+}

package/neural-interface/lib/skills/scan-context.js

@@ -0,0 +1,26 @@
+import { readHeadOf } from './export.js';
+import { bundleNameProblem } from './bundle.js';
+class NameError extends Error { constructor(status, message, code) { super(message); Object.assign(this, { status, code }); } }
+
+/**
+ * The name a revision is installed under (its folder's name): its SKILL.md name when that can be a folder name,
+ * else the library's. The plan, the review's evidence and an approval all use this one name.
+ */
+export function effectiveInstallName(skill, files) {
+  const { parsed } = readHeadOf(files);
+  const fmName = typeof parsed.data?.name === 'string' ? parsed.data.name.trim() : '';
+  const candidate = fmName && !bundleNameProblem(fmName) ? fmName : skill?.name;
+  if (!candidate || bundleNameProblem(candidate)) throw new NameError(422, 'This skill has no name that can be a folder\'s name: give its SKILL.md a "name".', 'invalid_name');
+  return candidate;
+}
+
+/**
+ * The names a scan checks a skill's install name against: every name SynaBun ships (look-alikes), and those it
+ * must not take (all of them but the skill's own when it is that shipped skill, in the library as bundled).
+ */
+export function nameChecks(skill, name, shipped = []) {
+  const all = [...new Set((shipped || []).filter((n) => typeof n === 'string' && n))];
+  const own = skill?.origin?.kind === 'bundled' ? String(skill.origin.name || skill.name || '').toLowerCase() : '';
+  const notOwn = all.filter((n) => n.toLowerCase() !== own || own !== String(name || '').toLowerCase());
+  return { knownNames: notOwn, reservedNames: notOwn };
+}