synabun 2.0.10 → 2.1.0

package/lib/client-config-repair.js

@@ -16,11 +16,18 @@ import { dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import {
   mergeGeminiMcpConfig,
-  mergeOpenCodeMcpConfig,
 } from '../neural-interface/lib/mcp-client-config.js';
+import {
+  mcpServersOf,
+  opencodeConfigDir,
+  opencodeConfigFilePath,
+  opencodeMcpServerEntry,
+  setMcpServer,
+} from '../neural-interface/lib/opencode-config.js';
 import {
   inspectCodexConfig,
   upsertCodexMcpConfig,
+  upsertCodexMcpContent,
 } from '../mcp-server/dist/services/codex-config-heal.js';
 import { mcpStdioCommand } from './packaged-runtime.js';
 
@@ -60,11 +67,12 @@ export function auditAndRepairClientConfigs({
 } = {}) {
   if (!dataHome || !packageRoot) throw new Error('dataHome and packageRoot are required');
   const definition = buildCanonicalMcpDefinition({ dataHome, packageRoot });
+  // Codex loads every SynaBun tool (its deferred catalog); a Codex runtime's own list is only its focus.
   const codexDefinition = {
     ...definition,
     env: {
       ...definition.env,
-      SYNABUN_PROFILE: 'full',
+      SYNABUN_TOOLS: 'all',
       SYNABUN_TOOL_CATALOG_MODE: 'deferred',
     },
   };
@@ -105,11 +113,12 @@ export function auditAndRepairClientConfigs({
     results.gemini = { exists: existsSync(geminiPath), connected: false, changed: false, path: geminiPath };
   }
 
-  const xdgConfigHome = process.env.XDG_CONFIG_HOME || join(home, '.config');
-  const openCodePath = join(xdgConfigHome, 'opencode', 'config.json');
+  // OpenCode 2's global opencode.json (it never reads the config.json of OpenCode 1), its mcp.servers.SynaBun:
+  // the folder the rest of SynaBun writes (OPENCODE_CONFIG_DIR, else XDG_CONFIG_HOME's, else ~/.config/opencode).
+  const openCodePath = opencodeConfigFilePath(opencodeConfigDir({ home }));
   const openCode = readJson(openCodePath);
-  if (openCode?.mcp?.SynaBun) {
-    const next = mergeOpenCodeMcpConfig(openCode, 'SynaBun', definition);
+  if (mcpServersOf(openCode).SynaBun) {
+    const next = setMcpServer(structuredClone(openCode), 'SynaBun', opencodeMcpServerEntry(definition));
     const changed = jsonChanged(openCode, next);
     if (apply && changed) writeJsonAtomic(openCodePath, next);
     results.opencode = { exists: true, connected: true, changed, path: openCodePath };
@@ -126,9 +135,9 @@ export function auditAndRepairClientConfigs({
       upsertCodexMcpConfig(codexPath, codexDefinition);
       changed = before !== readFileSync(codexPath, 'utf-8');
     } else {
+      // What the repair would write, compared with what is there: a value like "all" is in most files anyway.
       const content = readFileSync(codexPath, 'utf-8');
-      changed = ![codexDefinition.command, ...codexDefinition.args].every(value => content.includes(value))
-        || !Object.values(codexDefinition.env).every(value => content.includes(value));
+      changed = upsertCodexMcpContent(content, codexDefinition) !== content;
     }
     results.codex = { exists: true, connected: true, changed, path: codexPath, health: codexHealth };
   } else {

package/lib/desktop-app.js

@@ -193,9 +193,15 @@ export async function runAppBackend({
   // 3. Start, through the launcher (lock, supervisor record, background start).
   let launcherPid = null;
   let lastPhase = null;
+  let lastStep = null;
+  // A phase is said when it begins; the snapshot also says how far it is (its step, the bytes done), for the
+  // window's progress bar.
   const reportPhase = (current) => {
-    if (!current?.phase || current.phase === lastPhase) return;
+    if (!current?.phase) return;
+    const step = current.phase === 'snapshot' ? `${current.detail?.step ?? ''}:${current.detail?.done ?? ''}:${current.detail?.state ?? ''}` : null;
+    if (current.phase === lastPhase && step === lastStep) return;
     lastPhase = current.phase;
+    lastStep = step;
     emit({ type: 'supervisor', phase: current.phase, detail: current.detail || null });
   };
   const reporter = () => ({

package/lib/external-tools.js

@@ -66,7 +66,7 @@ export const EXTERNAL_TOOLS = Object.freeze([
     label: 'OpenCode',
     command: 'opencode',
     packages: Object.freeze(['opencode-ai']),
-    // (@opencode-ai/sdk is the JavaScript client and is not matched.)
+    // (No OpenCode client package ships: SynaBun speaks to OpenCode 2's serve itself, neural-interface/lib/opencode2-client.js.)
     patterns: Object.freeze([new RegExp(`^opencode-${PLATFORMS}-`)]),
   }),
   Object.freeze({

package/lib/first-launch-protection.js

@@ -11,6 +11,16 @@
 // The launcher also leaves its stop message in the server's stderr log
 // (recordLauncherFailure), because a detached launch has no terminal: the
 // updater's relaunch reads it back to tell the user why SynaBun did not start.
+//
+// The snapshot is the backup service's upgrade snapshot (createUpgradeSnapshot):
+// a consistent copy of each database (a clone where the file system clones)
+// that passed SQLite's integrity check, stored uncompressed, checksummed as it
+// is written and read back once. The desktop app takes it itself before it
+// replaces its own files (lib/update-snapshot.js) and hands it over; this start
+// uses it only when the data home is still what it was taken from
+// (checkUpgradeSnapshotFreshness), whatever process wrote since: an AI tool's
+// own MCP server may have saved a memory while the app swapped itself. Then it
+// takes a new one, here, before the server and so any migration runs.
 
 import { appendFileSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
@@ -31,19 +41,41 @@ function readJson(path, fallback) {
 /**
  * Why the snapshot an in-app update handed over cannot stand in for a fresh
  * one, or null when it can. It can only when the updater recorded that it
- * installed exactly the version now launching, and the archive still passes
- * verification. A `prepared` update is not enough: its updater may never have
- * run while the old server went on changing data.
+ * installed exactly the version now launching, the archive passes verification
+ * and its database copy passed SQLite's integrity check, and (the desktop app's
+ * snapshot, which records what it was taken from) nothing it protects changed
+ * since it was taken. A `prepared` update is not enough: its updater may never
+ * have run while the old server went on changing data.
  */
-async function handoffSnapshotProblem({ handoff, version, backupService }) {
+async function handoffSnapshotProblem({ handoff, version, backupService, dataHome }) {
   if (handoff.status !== 'installed') return 'that update was prepared but never recorded as installed';
   if (typeof handoff.target !== 'string' || handoff.target !== version) return 'it belongs to an update to another version';
   if (typeof handoff.snapshotPath !== 'string' || !handoff.snapshotPath) return 'it names no snapshot';
   if (!existsSync(handoff.snapshotPath)) return 'its snapshot file is gone';
   try {
     const service = await backupService();
-    const archive = await service.verifyBackupArchive(handoff.snapshotPath);
-    if (archive?.kind !== 'pre-update') return 'its file is not a pre-update snapshot';
+    let manifest;
+    // The desktop app read its snapshot back once, right after writing it, and
+    // recorded which file that was. The very same file, untouched since (device,
+    // inode, size, modification time), is not read a second time: only its
+    // manifest. Any other file is read in full.
+    if (handoff.verifiedStamp && typeof service.sameBackupFile === 'function' && typeof service.readBackupArchiveManifest === 'function'
+      && service.sameBackupFile(handoff.snapshotPath, handoff.verifiedStamp)) {
+      manifest = await service.readBackupArchiveManifest(handoff.snapshotPath);
+      if (manifest?.verified !== true) return 'its file is not a verified snapshot';
+    } else {
+      manifest = await service.verifyBackupArchive(handoff.snapshotPath);
+    }
+    if (manifest?.kind !== 'pre-update') return 'its file is not a pre-update snapshot';
+    // The restore runs SQLite's integrity check on the database it puts back: a copy that never passed it is no copy.
+    if (manifest.database && manifest.database.integrity !== 'ok') return 'its database copy was not checked with SQLite\'s integrity check';
+    // The data as it is now, before anything of this version touches it. The desktop app's snapshot says what it was
+    // taken from; the npm updater's (taken by the old server right before it stopped) does not, and is used as before.
+    if (handoff.source === 'desktop' || manifest.inputs) {
+      if (typeof service.checkUpgradeSnapshotFreshness !== 'function') return 'this version cannot tell whether the data changed since';
+      const freshness = await service.checkUpgradeSnapshotFreshness({ dataHome, manifest, databasePath: resolve(dataHome, 'mcp-data', 'memory.db') });
+      if (!freshness?.fresh) return `the data changed after it was taken (${freshness?.reason || 'unknown'})`;
+    }
   } catch (error) {
     return `its snapshot did not pass verification (${error?.message || error})`;
   }
@@ -94,7 +126,10 @@ export async function protectFirstLaunchAfterUpdate({
   let snapshotPath = null;
   if (pendingHandoff) {
     info('Checking the snapshot taken by the updater...');
-    const problem = await handoffSnapshotProblem({ handoff, version, backupService });
+    // The desktop app's splash says it: the copy made before the update is compared with the data (supervisor phase
+    // `snapshot`, step `check`).
+    progress({ step: 'check' });
+    const problem = await handoffSnapshotProblem({ handoff, version, backupService, dataHome });
     if (problem) info(`The updater's snapshot is not used: ${problem}. Taking a new one.`);
     else {
       snapshotPath = handoff.snapshotPath;
@@ -106,11 +141,16 @@ export async function protectFirstLaunchAfterUpdate({
   if (!snapshotPath) {
     const folderPath = resolve(dataHome, 'backups', 'updates');
     let service;
+    let lastPhase = null;
     try {
       info(`Protecting user state before first launch of v${version}...`);
       progress({});
       service = await backupService();
-      const snapshot = await service.createVerifiedBackup({
+      // The upgrade snapshot where the service has it (every SynaBun since 2026-10-21); the full backup otherwise.
+      const takeSnapshot = typeof service.createUpgradeSnapshot === 'function'
+        ? options => service.createUpgradeSnapshot(options)
+        : options => service.createVerifiedBackup(options);
+      const snapshot = await takeSnapshot({
         dataHome,
         databasePath: resolve(dataHome, 'mcp-data', 'memory.db'),
         folderPath,
@@ -118,17 +158,22 @@ export async function protectFirstLaunchAfterUpdate({
         appVersion: manifest.lastAppVersion || null,
         // Without this the checksum and archive phases run silently for minutes
         // on a large data home, which users read as a hang and kill.
-        onProgress: ({ phase, files, bytes, skippedFiles, skippedBytes }) => {
-          progress({ step: phase, files, bytes, skippedFiles });
+        onProgress: ({ phase, files, bytes, skippedFiles, skippedBytes, done, total, method, state }) => {
+          progress({ step: phase, files, bytes, skippedFiles, done, total, ...(state ? { state } : {}) });
+          // Each phase is said once, when it begins; the steps within it only reach the progress bar.
+          if (phase === lastPhase) return;
+          lastPhase = phase;
           const size = bytes ? ` (${(bytes / 1024 / 1024).toFixed(0)} MB)` : '';
           if (phase === 'collect') {
             info(`  ${files} files to protect${size}`);
             if (skippedFiles) {
               info(`  Skipping ${skippedFiles} generated media files (${(skippedBytes / 1024 / 1024).toFixed(0)} MB) — an upgrade never touches them`);
             }
-          } else if (phase === 'checksum') info(`  Checksumming ${files} files...`);
-          else if (phase === 'archive') info(`  Compressing${size}...`);
+          } else if (phase === 'copy') info(`  Copying the databases${method === 'clone' ? ' (a file system clone)' : ''}...`);
+          else if (phase === 'checksum') info(`  Checksumming ${files} files...`);
+          else if (phase === 'archive') info(total ? `  Writing the archive (${(total / 1024 / 1024).toFixed(0)} MB)...` : `  Compressing${size}...`);
           else if (phase === 'verify') info('  Verifying archive integrity...');
+          else if (phase === 'integrity') info('  Finishing SQLite\'s integrity check of the database copies...');
         },
       });
       snapshotPath = snapshot.path;

package/lib/mcp-dist.js

@@ -0,0 +1,176 @@
+// What "the MCP server is built" means, in one place: mcp-server/dist/index.js and every module it imports by a
+// relative path, transitively, are on disk. mcp-server/dist/ is build output that git ignores, yet a checkout can
+// hold a tracked dist/index.js whose newer imports were never committed (they are ignored too): a server started
+// from it fails to load /mcp. postinstall.js and setup.js build when this says no; the Neural Interface's restore,
+// onboarding status and build route, the install details, the release and the packaged app's checks ask it too.
+//
+// The imports are read from the code itself, never from a comment or a string: a light tokenizer skips comments,
+// strings, template literals and regular expressions, so a word "import" in a text cannot ask for a module that is
+// not loaded (a packaged app has no compiler: a false "missing" there would stop it). Only plain fs and path:
+// postinstall.js and setup.js import this on any Node.
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+const MAX_MODULES = 5000;
+const MAX_MODULE_BYTES = 8 * 1024 * 1024;
+const CODE_EXT = /\.(?:m?js|cjs)$/i;
+// After one of these a `/` starts a regular expression, after anything else it divides.
+const REGEX_AFTER_PUNCT = new Set(['(', ',', '=', ':', '[', '!', '&', '|', '?', '{', '}', ';', '+', '-', '*', '%', '<', '>', '~', '^']);
+const REGEX_AFTER_WORD = new Set(['return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void', 'throw', 'case', 'do', 'else', 'yield', 'await']);
+
+/**
+ * The tokens of a module that matter for its imports: words, punctuation and string literals (their values), with
+ * comments, template literal text and regular expressions left out.
+ * @returns {{ t: 'word'|'punct'|'string', v: string }[]}
+ */
+export function codeTokens(text) {
+  const src = String(text ?? '');
+  const out = [];
+  const frames = [];   // one per open `${` of a template literal: the brace depth that closes it
+  let depth = 0;
+  let i = 0;
+  const last = () => out[out.length - 1];
+  const regexAllowed = () => {
+    const p = last();
+    if (!p) return true;
+    if (p.t === 'punct') return REGEX_AFTER_PUNCT.has(p.v);
+    if (p.t === 'word') return REGEX_AFTER_WORD.has(p.v);
+    return false;
+  };
+  const template = () => {
+    // From just after a backtick (or a closing `}` of a `${`): to the closing backtick or the next `${`.
+    while (i < src.length) {
+      const c = src[i];
+      if (c === '\\') { i += 2; continue; }
+      if (c === '`') { i += 1; out.push({ t: 'string', v: '' }); return; }
+      if (c === '$' && src[i + 1] === '{') { i += 2; frames.push(depth); depth += 1; return; }
+      i += 1;
+    }
+  };
+  while (i < src.length) {
+    const c = src[i];
+    if (c === '/' && src[i + 1] === '/') { const nl = src.indexOf('\n', i); i = nl < 0 ? src.length : nl; continue; }
+    if (c === '/' && src[i + 1] === '*') { const end = src.indexOf('*/', i + 2); i = end < 0 ? src.length : end + 2; continue; }
+    if (c === '\'' || c === '"') {
+      let j = i + 1; let v = '';
+      while (j < src.length && src[j] !== c && src[j] !== '\n') { if (src[j] === '\\') { v += src[j + 1] ?? ''; j += 2; continue; } v += src[j]; j += 1; }
+      out.push({ t: 'string', v });
+      i = j + 1;
+      continue;
+    }
+    if (c === '`') { i += 1; template(); continue; }
+    if (c === '/' && regexAllowed()) {
+      let j = i + 1; let inClass = false;
+      while (j < src.length && src[j] !== '\n') {
+        const d = src[j];
+        if (d === '\\') { j += 2; continue; }
+        if (d === '[') inClass = true;
+        else if (d === ']') inClass = false;
+        else if (d === '/' && !inClass) break;
+        j += 1;
+      }
+      i = j + 1;
+      while (i < src.length && /[a-z]/i.test(src[i])) i += 1;
+      out.push({ t: 'punct', v: ')' });   // a value, as far as a following `/` is concerned
+      continue;
+    }
+    if (/[A-Za-z_$]/.test(c)) {
+      let j = i + 1;
+      while (j < src.length && /[\w$]/.test(src[j])) j += 1;
+      out.push({ t: 'word', v: src.slice(i, j) });
+      i = j;
+      continue;
+    }
+    if (/\s/.test(c)) { i += 1; continue; }
+    if (/[0-9]/.test(c)) { let j = i + 1; while (j < src.length && /[\w.]/.test(src[j])) j += 1; out.push({ t: 'word', v: src.slice(i, j) }); i = j; continue; }
+    if (c === '{') depth += 1;
+    if (c === '}') {
+      if (frames.length && depth - 1 === frames[frames.length - 1]) { depth -= 1; frames.pop(); i += 1; template(); continue; }
+      depth = Math.max(0, depth - 1);
+    }
+    out.push({ t: 'punct', v: c });
+    i += 1;
+  }
+  return out;
+}
+
+/** The module specifiers a module loads: static imports, `export … from`, side-effect imports, `import('…')`. */
+export function importSpecifiers(text) {
+  const tokens = codeTokens(text);
+  const found = [];
+  const at = (k) => tokens[k] || { t: 'end', v: '' };
+  for (let k = 0; k < tokens.length; k++) {
+    const tok = tokens[k];
+    if (tok.t !== 'word' || (tok.v !== 'import' && tok.v !== 'export')) continue;
+    if (k > 0 && at(k - 1).t === 'punct' && at(k - 1).v === '.') continue;   // obj.import
+    const next = at(k + 1);
+    if (tok.v === 'import') {
+      if (next.t === 'punct' && next.v === '.') continue;   // import.meta
+      if (next.t === 'punct' && next.v === '(') { if (at(k + 2).t === 'string' && at(k + 3).v === ')') found.push(at(k + 2).v); continue; }
+      if (next.t === 'string') { found.push(next.v); continue; }
+    }
+    // import a, { b as c } from '…'; import * as d from '…'; export { e } from '…'; export * from '…'
+    let j = k + 1;
+    while (j < tokens.length) {
+      const x = at(j);
+      if (x.t === 'word' && x.v === 'from') break;
+      if (x.t === 'word' || (x.t === 'punct' && (x.v === ',' || x.v === '{' || x.v === '}' || x.v === '*'))) { j += 1; continue; }
+      j = -1;
+      break;
+    }
+    if (j > k + 1 && at(j).v === 'from' && at(j + 1).t === 'string') {
+      if (tok.v === 'export' && !(next.v === '*' || next.v === '{')) continue;
+      found.push(at(j + 1).v);
+    }
+  }
+  return found;
+}
+
+const posix = (p) => p.split(sep).join('/');
+
+/**
+ * Every module dist/index.js needs that is not on disk (or cannot be read), as paths from the package root.
+ * Modules inside mcp-server/dist are followed; one outside it (the package's lib/) is only looked for.
+ * @param {string} packageRoot
+ * @param {{ exists?: (p: string) => boolean, readText?: (p: string) => string, entry?: string }} [o]
+ * @returns {{ complete: boolean, missing: string[], checked: number }}
+ */
+export function mcpDistMissing(packageRoot, { exists = existsSync, readText = null, entry = 'index.js' } = {}) {
+  const root = resolve(packageRoot);
+  const dist = join(root, 'mcp-server', 'dist');
+  const read = readText || ((p) => {
+    const st = statSync(p);
+    if (!st.isFile()) throw new Error('not a regular file');
+    if (st.size > MAX_MODULE_BYTES) return null;
+    return readFileSync(p, 'utf8');
+  });
+  const missing = new Set();
+  const seen = new Set();
+  const queue = [join(dist, entry)];
+  let checked = 0;
+  while (queue.length && checked < MAX_MODULES) {
+    const file = queue.shift();
+    if (seen.has(file)) continue;
+    seen.add(file);
+    if (!exists(file)) { missing.add(posix(relative(root, file))); continue; }
+    const inside = file.startsWith(dist + sep);
+    if (!inside || !CODE_EXT.test(file)) continue;
+    let text;
+    try { text = read(file); } catch { missing.add(posix(relative(root, file))); continue; }
+    checked += 1;
+    if (text === null) continue;   // too large to read here: present, not followed
+    for (const spec of importSpecifiers(text)) {
+      if (!spec.startsWith('./') && !spec.startsWith('../')) continue;
+      const target = resolve(dirname(file), spec.split(/[?#]/)[0]);
+      if (!seen.has(target)) queue.push(target);
+    }
+  }
+  const list = [...missing].sort();
+  return { complete: list.length === 0, missing: list, checked };
+}
+
+/** Whether the MCP server is built: dist/index.js and everything it imports are there. */
+export function mcpDistBuilt(packageRoot, options) {
+  return mcpDistMissing(packageRoot, options).complete;
+}

package/lib/release-npm-ci.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/** Shared CI identity, OIDC-only publication and exact-byte handoff contract. */
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { appendFile, lstat, readFile, readdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { hashFile } from './virustotal.mjs';
+import { publishNpm, runNpm, verifyPacked } from './release-publish.mjs';
+
+export const REPOSITORY = 'danilokhury/Synabun';
+export const WORKFLOW = '.github/workflows/publish.yml';
+export const PUBLISH_NPM = '11.21.0'; // Verified OIDC-compatible CLI; builder stays 10.9.3.
+export const stableVersion = value => typeof value === 'string' && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(value);
+export const exactCommit = value => typeof value === 'string' && /^[a-f0-9]{40}$/.test(value);
+export const requestId = value => typeof value === 'string' && /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(value);
+export const runTitle = ({ version, commit, request }) => `npm ${version} ${commit} ${request}`;
+export const artifactName = (id, attempt) => `npm-publication-${id}-${attempt}`;
+const numberId = value => /^\d+$/.test(String(value)) && Number.isSafeInteger(Number(value)) && Number(value) > 0;
+
+export function validateIdentity({ env, event, pkg, head, main }) {
+  if (env.GITHUB_REPOSITORY !== REPOSITORY || pkg.name !== 'synabun' || !stableVersion(pkg.version)
+      || pkg.repository?.url !== `git+https://github.com/${REPOSITORY}.git`) throw new Error('Unexpected npm package/repository identity');
+  if (!exactCommit(head) || head !== main || !numberId(env.GITHUB_RUN_ID) || !numberId(env.GITHUB_RUN_ATTEMPT)) throw new Error('Release commit must be the current main tip; require exact run identity');
+  let request = null;
+  if (env.GITHUB_EVENT_NAME === 'workflow_dispatch') {
+    if (env.GITHUB_REF !== 'refs/heads/main' || env.GITHUB_SHA !== head || event.inputs?.commit !== head
+        || event.inputs?.version !== pkg.version || !requestId(event.inputs?.request_id)) throw new Error('Invalid dispatch ref/commit/version/request identity');
+    request = event.inputs.request_id;
+  } else if (env.GITHUB_EVENT_NAME === 'release') {
+    const tag = event.release?.tag_name;
+    if (event.action !== 'published' || event.release?.draft !== false || event.release?.prerelease !== false
+        || !new RegExp(`^v?\\.?${pkg.version.replaceAll('.', '\\.')}$`).test(tag || '')
+        || env.GITHUB_REF !== `refs/tags/${tag}` || env.GITHUB_SHA !== head) throw new Error('Invalid stable release event/tag');
+  } else throw new Error('Only main workflow_dispatch or stable release.published can publish');
+  if (env.GITHUB_WORKFLOW_REF !== `${REPOSITORY}/${WORKFLOW}@${env.GITHUB_REF}`) throw new Error('Unexpected publisher workflow identity');
+  return { repository: REPOSITORY, workflow: WORKFLOW, event: env.GITHUB_EVENT_NAME,
+    version: pkg.version, commit: head, request, run_id: Number(env.GITHUB_RUN_ID), run_attempt: Number(env.GITHUB_RUN_ATTEMPT) };
+}
+
+export function oidcEnvironment(env, { cli, userconfig, globalconfig, cache }) {
+  if (env.RUNNER_ENVIRONMENT !== 'github-hosted' || !env.ACTIONS_ID_TOKEN_REQUEST_URL || !env.ACTIONS_ID_TOKEN_REQUEST_TOKEN) throw new Error('GitHub-hosted OIDC runner and id-token: write are required');
+  // Modern npm tries OIDC first. Remove legacy credentials anyway: no silent token fallback.
+  const clean = Object.fromEntries(Object.entries(env).filter(([key]) => !/^(NPM|NPM_TOKEN|NODE_AUTH_TOKEN)$/i.test(key) && !/^npm_config_/i.test(key)));
+  return { ...clean, npm_execpath: cli, NPM_CONFIG_USERCONFIG: userconfig, NPM_CONFIG_GLOBALCONFIG: globalconfig,
+    NPM_CONFIG_CACHE: cache, NPM_CONFIG_REGISTRY: 'https://registry.npmjs.org/', NPM_CONFIG_UPDATE_NOTIFIER: 'false' };
+}
+
+export function verifyToolchain(node, npm) {
+  if (node.replace(/^v/, '') !== '22.19.0' || npm.trim() !== PUBLISH_NPM) throw new Error(`Publication requires Node 22.19.0 and isolated npm ${PUBLISH_NPM}; builder npm is unchanged`);
+}
+
+export async function registryVersion(version, { fetchImpl = fetch, allowMissing = false } = {}) {
+  if (!stableVersion(version)) throw new Error('Invalid registry version');
+  const response = await fetchImpl(`https://registry.npmjs.org/synabun/${version}`, { signal: AbortSignal.timeout(30000) });
+  if (response.status === 404 && allowMissing) return null;
+  if (!response.ok) throw new Error(`npm registry lookup failed (${response.status})`);
+  const pkg = await response.json();
+  if (pkg?.name !== 'synabun' || pkg.version !== version || !/^sha512-[A-Za-z0-9+/]{86}==$/.test(pkg.dist?.integrity || '')) throw new Error('npm registry identity/integrity is unverified');
+  return pkg.dist.integrity;
+}
+
+export async function sha512(path) {
+  const hash = createHash('sha512');
+  for await (const bytes of createReadStream(path)) hash.update(bytes);
+  return `sha512-${hash.digest('base64')}`;
+}
+export const bundleFiles = version => ['npm-virustotal.json', 'npm-virustotal.md', `synabun-${version}.tgz`];
+
+export async function publicationReceipt({ out, identity, registry = registryVersion }) {
+  const packed = await verifyPacked({ out });
+  if (packed.tarball !== join(out, `synabun-${identity.version}.tgz`)) throw new Error('npm receipt version mismatch');
+  const integrity = await sha512(packed.tarball);
+  if (await registry(identity.version) !== integrity) throw new Error('npm registry SHA512 differs from scanned tarball');
+  const files = {};
+  for (const name of bundleFiles(identity.version)) files[name] = { sha256: await hashFile(join(out, name)), size: (await lstat(join(out, name))).size };
+  const receipt = { schema: 1, ...identity, integrity, files };
+  await writeFile(join(out, 'npm-publication.json'), JSON.stringify(receipt, null, 2) + '\n');
+  return receipt;
+}
+
+export async function verifyPublication({ out, expected, registry = registryVersion, strictFiles = true }) {
+  const receipt = JSON.parse(await readFile(join(out, 'npm-publication.json'), 'utf8'));
+  if (receipt.schema !== 1 || receipt.repository !== REPOSITORY || receipt.workflow !== WORKFLOW
+      || !stableVersion(receipt.version) || !exactCommit(receipt.commit) || !numberId(receipt.run_id)
+      || !numberId(receipt.run_attempt) || !['workflow_dispatch', 'release'].includes(receipt.event)
+      || (receipt.event === 'workflow_dispatch' && !requestId(receipt.request))) throw new Error('Unknown or invalid npm publication receipt');
+  for (const [key, value] of Object.entries(expected)) if (receipt[key] !== value) throw new Error(`npm publication identity mismatch: ${key}`);
+  const names = bundleFiles(expected.version);
+  if (JSON.stringify(Object.keys(receipt.files || {}).sort()) !== JSON.stringify([...names].sort())
+      || (strictFiles && JSON.stringify((await readdir(out)).sort()) !== JSON.stringify([...names, 'npm-publication.json'].sort()))) throw new Error('Unexpected npm artifact file set');
+  for (const name of [...names, 'npm-publication.json']) {
+    const info = await lstat(join(out, name));
+    if (!info.isFile() || info.isSymbolicLink()) throw new Error('npm artifact must contain regular files only');
+    if (name !== 'npm-publication.json' && (info.size !== receipt.files[name].size || await hashFile(join(out, name)) !== receipt.files[name].sha256)) throw new Error(`npm artifact integrity mismatch: ${name}`);
+  }
+  const packed = await verifyPacked({ out });
+  if (packed.tarball !== join(out, `synabun-${expected.version}.tgz`) || await sha512(packed.tarball) !== receipt.integrity
+      || await registry(expected.version) !== receipt.integrity) throw new Error('npm publication version/registry integrity mismatch');
+  // Read only the packed manifest; never extract arbitrary paths into the checkout.
+  const tar = spawnSync('tar', ['-xOf', packed.tarball, 'package/package.json'], { encoding: 'utf8', maxBuffer: 1024 * 1024, timeout: 30000 });
+  if (tar.status !== 0) throw new Error('Cannot inspect npm tarball manifest');
+  const pkg = JSON.parse(tar.stdout);
+  if (pkg.name !== 'synabun' || pkg.version !== expected.version || pkg.repository?.url !== `git+https://github.com/${REPOSITORY}.git`) throw new Error('Packed npm manifest identity mismatch');
+  return receipt;
+}
+
+function git(...args) {
+  const result = spawnSync('git', args, { encoding: 'utf8', timeout: 120000 });
+  if (result.status !== 0) throw new Error('Cannot verify current main commit');
+  return result.stdout.trim();
+}
+async function ciIdentity() {
+  git('fetch', '--no-tags', '--depth=1', 'origin', 'main');
+  return validateIdentity({ env: process.env, event: JSON.parse(await readFile(process.env.GITHUB_EVENT_PATH, 'utf8')),
+    pkg: JSON.parse(await readFile('package.json', 'utf8')), head: git('rev-parse', 'HEAD'), main: git('rev-parse', 'FETCH_HEAD') });
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    const stage = process.argv[2], identity = await ciIdentity(), out = join(process.env.RUNNER_TEMP, 'npm-release');
+    if (stage === 'identity') {
+      const published = await registryVersion(identity.version, { allowMissing: true });
+      if (published && identity.event === 'workflow_dispatch') throw new Error('Version already published: recover the original successful run artifacts; never repack an existing version');
+      await appendFile(process.env.GITHUB_OUTPUT, `published=${!!published}\n`);
+    } else if (stage === 'publish') {
+      try { await lstat('.npmrc'); throw new Error('Project .npmrc is forbidden in the publishing checkout'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+      const base = process.env.RUNNER_TEMP;
+      const userconfig = join(base, 'npm-oidc-userconfig'), globalconfig = join(base, 'npm-oidc-globalconfig');
+      await writeFile(userconfig, ''); await writeFile(globalconfig, '');
+      const env = oidcEnvironment(process.env, { cli: join(base, 'npm-oidc-cli/node_modules/npm/bin/npm-cli.js'), userconfig, globalconfig, cache: join(base, 'npm-oidc-cache') });
+      const run = (args, options) => runNpm(args, { ...options, env });
+      verifyToolchain(process.version, run(['--version'], { capture: true }));
+      await publishNpm({ cwd: process.cwd(), out, run, publishPacked: true, provenance: true });
+      await publicationReceipt({ out, identity });
+    } else throw new Error('Use identity or publish');
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/lib/release-publish.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/** The only documented npm publication path: check, pack, scan, publish the same tgz. */
+import { spawnSync } from 'node:child_process';
+import { access, chmod, mkdir, mkdtemp, readFile, copyFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { approved, credentials, evidenceDigest, hashFile } from './virustotal.mjs';
+import { scanRelease } from './release-scan.mjs';
+
+export function runNpm(args, { cwd, env = process.env, capture = false } = {}) {
+  // npm_execpath works with npm.cmd on Windows without shell argument interpolation.
+  const npm = env.npm_execpath;
+  if (!npm && process.platform === 'win32') throw new Error('On Windows run npm run release:publish so npm_execpath is available');
+  const command = npm ? process.execPath : 'npm';
+  const result = spawnSync(command, npm ? [npm, ...args] : args, { cwd, env, encoding: 'utf8', stdio: capture ? 'pipe' : 'inherit', timeout: 1800000, maxBuffer: 8 * 1024 * 1024 });
+  // Never replay npm's captured output (it may contain authentication diagnostics).
+  if (result.error || result.status !== 0) throw new Error(`npm ${args[0]} failed; publication stopped`);
+  return result.stdout;
+}
+export async function verifyPacked({ out, now = Date.now() }) {
+  const report = JSON.parse(await readFile(join(out, 'npm-virustotal.json'), 'utf8'));
+  if (report.schema !== 1 || !report.approved || report.items?.length !== 1 || !approved(report.items)) throw new Error('npm scan report is not approved');
+  const item = report.items[0];
+  if (item.kind !== 'file' || basename(item.name) !== item.name || !/^synabun-.*\.tgz$/.test(item.name)) throw new Error('Invalid npm scan subject');
+  const { evidence_digest, review, ...evidence } = item;
+  if (evidenceDigest(evidence) !== evidence_digest) throw new Error('npm report evidence digest mismatch');
+  const at = Date.parse(item.analysis_date);
+  if (!Number.isFinite(at) || at > now + 300000 || now - at > 7 * 86400000 || item.analysis_status !== 'completed' || item.supported_engines < 10) throw new Error('npm scan report stale, unfinished or inconclusive');
+  if (item.status === 'detections') {
+    const { applyReviews } = await import('./virustotal.mjs');
+    if (!approved(applyReviews([{ ...item, review: null }], [{ ...review, name: item.name, sha256: item.sha256, evidence_digest }], now))) throw new Error('npm detection review required');
+  }
+  const tarball = join(out, item.name);
+  if (await hashFile(tarball) !== item.sha256) throw new Error('npm tarball SHA-256 mismatch; repack and scan');
+  return { tarball, sha256: item.sha256 };
+}
+export async function publishNpm({ cwd, out, reviewFile, provenance = false, packOnly = false, publishPacked = false, run = runNpm, scan = scanRelease }) {
+  credentials(); // Before installs or registry mutations.
+  const rel = relative(resolve(cwd), resolve(out));
+  if (!rel || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith('../') && !rel.startsWith('..\\'))) throw new Error('Release output must be outside the checkout to keep reports/tarballs out of npm packages');
+  const pkg = JSON.parse(await readFile(join(cwd, 'package.json'), 'utf8'));
+  if (pkg.name !== 'synabun' || pkg.scripts?.prepublishOnly?.includes('refuse-publish-from-dev') || !pkg.scripts?.prepublishOnly?.includes('release-publish.mjs guard')) throw new Error('Publish from a fresh prepared Clean clone with npm run release:publish; Dev publication is refused');
+  await mkdir(out, { recursive: true });
+  if (!publishPacked) {
+    run(['run', 'deps:check'], { cwd });
+    run(['ci', '--ignore-scripts'], { cwd });
+    // Preserve Clean's entire install/build/file/pack chain. npm publish TGZ skips it.
+    run(['run', 'prepublishOnly'], { cwd, env: { ...process.env, SYNABUN_RELEASE_PACK: '1' } });
+    run(['run', 'prepack'], { cwd });
+    for (const file of ['mcp-server/dist/index.js', 'NOTICE', 'THIRD-PARTY-LICENSES.md']) await access(join(cwd, file));
+    const staging = await mkdtemp(join(tmpdir(), 'synabun-npm-pack-'));
+    try {
+      const packed = JSON.parse(run(['pack', '--ignore-scripts', '--json', '--pack-destination', staging], { cwd, capture: true }));
+      const name = packed?.[0]?.filename;
+      if (packed.length !== 1 || !name || basename(name) !== name || name !== `synabun-${pkg.version}.tgz`) throw new Error('npm pack returned an unexpected tarball');
+      const tarball = join(out, name);
+      await rm(tarball, { force: true });
+      await copyFile(join(staging, name), tarball);
+      await chmod(tarball, 0o444);
+      await scan({ files: [tarball], out, prefix: 'npm-virustotal', reviewFile });
+    } finally { await rm(staging, { recursive: true, force: true }); }
+  }
+  const packed = await verifyPacked({ out });
+  if (basename(packed.tarball) !== `synabun-${pkg.version}.tgz`) throw new Error('npm tarball version mismatch');
+  if (!packOnly) {
+    run(['publish', packed.tarball, '--ignore-scripts', '--access', 'public', '--tag', 'latest', ...(provenance ? ['--provenance'] : [])], { cwd });
+    if (await hashFile(packed.tarball) !== packed.sha256) throw new Error('npm tarball changed during publication; inspect registry immediately');
+  }
+  return packed;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    if (process.argv[2] === 'guard') {
+      if (process.env.SYNABUN_RELEASE_PACK !== '1') throw new Error('Direct npm publish is disabled: use npm run release:publish -- --out /absolute/release/folder (packs, scans and publishes the exact tgz).');
+    } else {
+      const args = process.argv.slice(2); let out, reviewFile, provenance = false, packOnly = false, publishPacked = false;
+      while (args.length) {
+        const arg = args.shift();
+        if (arg === '--out') out = args.shift();
+        else if (arg === '--review') reviewFile = args.shift();
+        else if (arg === '--provenance') provenance = true;
+        else if (arg === '--pack-only') packOnly = true;
+        else if (arg === '--publish-packed') publishPacked = true;
+        else throw new Error(`Unknown option: ${arg}`);
+      }
+      if (!out || (packOnly && publishPacked)) throw new Error('Use --out DIR; --pack-only and --publish-packed are mutually exclusive');
+      await publishNpm({ cwd: dirname(dirname(fileURLToPath(import.meta.url))), out: resolve(out), reviewFile, provenance, packOnly, publishPacked });
+    }
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}