synabun 2.0.9 → 2.1.0

package/neural-interface/lib/codex-settings-schema.js

@@ -1,12 +1,66 @@
-import { spawnSync } from 'node:child_process';
-import { mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 // The probes run no command: always the Windows sandbox that needs no administrator (lib/agent-sandbox-elevation.js).
 import { CODEX_PROBE_SANDBOX_ARGS } from './agent-sandbox-elevation.js';
 
+// The probes start Codex itself (a 300 MB binary on Windows) once per setting value: asynchronous, never
+// more than two at a time, one run per binary for every caller, and kept per binary identity (path, mtime,
+// size: an update is another binary) in memory and, through setCodexSettingsStore(), across restarts.
 const cache = new Map();
 const featureCache = new Map();
+const inflight = new Map();
+const latestSchema = new Map(); // codexBin → the schema of the binary as it was last read
+let store = null;
+const MAX_PROBES = 2;
+let running = 0;
+const waiting = [];
+
+/** Where answers are kept across restarts: `{ get(key) → value | undefined, set(key, value) }` (lib/launch-cache.js). */
+export function setCodexSettingsStore(next) {
+  store = next && typeof next.get === 'function' && typeof next.set === 'function' ? next : null;
+}
+
+function limited(job) {
+  return new Promise((resolve, reject) => {
+    waiting.push({ job, resolve, reject });
+    const pump = () => {
+      while (running < MAX_PROBES && waiting.length) {
+        const next = waiting.shift();
+        running += 1;
+        Promise.resolve().then(next.job).then(next.resolve, next.reject).finally(() => { running -= 1; pump(); });
+      }
+    };
+    pump();
+  });
+}
+
+// One Codex run: { status, stdout } (status null when it could not start or ran out of time).
+function probe(codexBin, args, { env, timeout }) {
+  return limited(() => new Promise((resolve) => {
+    execFile(codexBin, args, { env, encoding: 'utf8', timeout, windowsHide: true, maxBuffer: 16 * 1024 * 1024 }, (error, stdout) => {
+      resolve({ status: error ? (typeof error.code === 'number' ? error.code : null) : 0, stdout: String(stdout || '') });
+    });
+  }));
+}
+
+// What was found for `key` before (this run, or the last one through the store), or undefined.
+function known(memo, key) {
+  if (memo.has(key)) return memo.get(key);
+  try {
+    const kept = store?.get(key);
+    if (kept && typeof kept === 'object') { memo.set(key, kept); return kept; }
+  } catch { /* nothing kept */ }
+  return undefined;
+}
+
+function once(key, run) {
+  if (inflight.has(key)) return inflight.get(key);
+  const job = Promise.resolve().then(run).finally(() => inflight.delete(key));
+  inflight.set(key, job);
+  return job;
+}
 export const CODEX_SETTINGS_KEYS = Object.freeze([
   'model', 'review_model', 'model_provider', 'approval_policy', 'sandbox_mode', 'personality',
   'service_tier', 'model_reasoning_effort', 'model_reasoning_summary', 'model_verbosity',
@@ -40,33 +94,38 @@ export function settingsSchemaFromProtocol(configSchema, threadSchema) {
 }
 
 /** Generate from the executable we actually launch; never use the global home. */
-export function readCodexSettingsSchema(codexBin) {
-  const stamp = statSync(codexBin);
-  const key = `${codexBin}:${stamp.mtimeMs}:${stamp.size}`;
-  if (cache.has(key)) return cache.get(key);
-  const home = mkdtempSync(join(tmpdir(), 'synabun-codex-schema-'));
-  try {
-    const out = join(home, 'schema');
-    const run = spawnSync(codexBin, ['app-server', 'generate-json-schema', '--experimental', '--out', out, ...CODEX_PROBE_SANDBOX_ARGS], {
-      env: { ...process.env, CODEX_HOME: home }, encoding: 'utf8', timeout: 15000, windowsHide: true,
-    });
-    if (run.error || run.status !== 0) throw new Error('Codex could not report its settings schema');
-    const read = name => JSON.parse(readFileSync(join(out, 'v2', `${name}.json`), 'utf8'));
-    const schema = settingsSchemaFromProtocol(read('ConfigReadResponse'), read('ThreadStartParams'));
-    // Protocol enums can retain deprecated variants that the config loader
-    // already rejects (0.162 still exports `untrusted`). Ask the loader too.
-    // `features list` validates config locally and never runs a model or tool.
-    for (const [fieldKey, field] of Object.entries(schema.fields)) {
-      field.values = field.values.filter(value => {
-        const check = spawnSync(codexBin, [...CODEX_PROBE_SANDBOX_ARGS, '-c', `${fieldKey}=${JSON.stringify(value)}`, 'features', 'list'], {
-          env: { ...process.env, CODEX_HOME: home }, encoding: 'utf8', timeout: 5000, windowsHide: true,
-        });
-        return !check.error && check.status === 0;
-      });
-    }
-    cache.set(key, schema);
-    return schema;
-  } finally { rmSync(home, { recursive: true, force: true }); }
+export async function readCodexSettingsSchema(codexBin) {
+  const stamp = await stat(codexBin);
+  const key = `schema:${codexBin}:${stamp.mtimeMs}:${stamp.size}`;
+  const found = known(cache, key);
+  if (found) { latestSchema.set(codexBin, found); return found; }
+  return once(key, async () => {
+    const home = await mkdtemp(join(tmpdir(), 'synabun-codex-schema-'));
+    try {
+      const env = { ...process.env, CODEX_HOME: home };
+      const out = join(home, 'schema');
+      const run = await probe(codexBin, ['app-server', 'generate-json-schema', '--experimental', '--out', out, ...CODEX_PROBE_SANDBOX_ARGS], { env, timeout: 15000 });
+      if (run.status !== 0) throw new Error('Codex could not report its settings schema');
+      const read = async name => JSON.parse(await readFile(join(out, 'v2', `${name}.json`), 'utf8'));
+      const schema = settingsSchemaFromProtocol(await read('ConfigReadResponse'), await read('ThreadStartParams'));
+      // Protocol enums can retain deprecated variants that the config loader
+      // already rejects (0.162 still exports `untrusted`). Ask the loader too.
+      // `features list` validates config locally and never runs a model or tool.
+      for (const [fieldKey, field] of Object.entries(schema.fields)) {
+        const checks = await Promise.all(field.values.map(value => probe(codexBin, [...CODEX_PROBE_SANDBOX_ARGS, '-c', `${fieldKey}=${JSON.stringify(value)}`, 'features', 'list'], { env, timeout: 5000 })));
+        field.values = field.values.filter((_, index) => checks[index].status === 0);
+      }
+      cache.set(key, schema);
+      latestSchema.set(codexBin, schema);
+      try { store?.set(key, schema); } catch { /* kept in memory */ }
+      return schema;
+    } finally { await rm(home, { recursive: true, force: true }).catch(() => {}); }
+  });
+}
+
+/** The schema readCodexSettingsSchema() last gave for this binary, or null: never starts Codex. */
+export function cachedCodexSettingsSchema(codexBin) {
+  return latestSchema.get(codexBin) || null;
 }
 
 export function validateCodexSettings(config, schema, features = []) {
@@ -99,24 +158,27 @@ export function validateCodexSettings(config, schema, features = []) {
 
 /** Some stable flags are now mandatory and ignore false (e.g. unified_exec).
  * Check both states with the local loader instead of offering a no-op switch. */
-export function readCodexFeatureSupport(codexBin, features) {
+export async function readCodexFeatureSupport(codexBin, features) {
   const names = features.filter(f => ['stable', 'beta'].includes(f.stage) && /^[A-Za-z0-9_-]+$/.test(f.name)).map(f => f.name).sort();
-  const stat = statSync(codexBin);
-  const key = `${codexBin}:${stat.mtimeMs}:${stat.size}:${names.join(',')}`;
-  if (featureCache.has(key)) return featureCache.get(key);
-  const home = mkdtempSync(join(tmpdir(), 'synabun-feature-support-'));
-  try {
-    const states = [false, true].map(value => {
-      const check = spawnSync(codexBin, [...CODEX_PROBE_SANDBOX_ARGS, '-c', `features={${names.map(name => `${name}=${value}`).join(',')}}`, 'features', 'list'], {
-        env: { ...process.env, CODEX_HOME: home }, encoding: 'utf8', timeout: 10000, windowsHide: true,
-      });
-      if (check.error || check.status !== 0) throw new Error('Codex could not validate feature switches');
-      return new Map(check.stdout.split('\n').map(line => {
-        const parts = line.trim().split(/\s+/); return [parts[0], parts.at(-1)];
+  const stamp = await stat(codexBin);
+  const key = `features:${codexBin}:${stamp.mtimeMs}:${stamp.size}:${names.join(',')}`;
+  const found = known(featureCache, key);
+  if (found) return found;
+  return once(key, async () => {
+    const home = await mkdtemp(join(tmpdir(), 'synabun-feature-support-'));
+    try {
+      const env = { ...process.env, CODEX_HOME: home };
+      const states = await Promise.all([false, true].map(async value => {
+        const check = await probe(codexBin, [...CODEX_PROBE_SANDBOX_ARGS, '-c', `features={${names.map(name => `${name}=${value}`).join(',')}}`, 'features', 'list'], { env, timeout: 10000 });
+        if (check.status !== 0) throw new Error('Codex could not validate feature switches');
+        return new Map(check.stdout.split('\n').map(line => {
+          const parts = line.trim().split(/\s+/); return [parts[0], parts.at(-1)];
+        }));
       }));
-    });
-    const supported = Object.fromEntries(names.map(name => [name, states[0].get(name) === 'false' && states[1].get(name) === 'true']));
-    featureCache.set(key, supported);
-    return supported;
-  } finally { rmSync(home, { recursive: true, force: true }); }
+      const supported = Object.fromEntries(names.map(name => [name, states[0].get(name) === 'false' && states[1].get(name) === 'true']));
+      featureCache.set(key, supported);
+      try { store?.set(key, supported); } catch { /* kept in memory */ }
+      return supported;
+    } finally { await rm(home, { recursive: true, force: true }).catch(() => {}); }
+  });
 }

package/neural-interface/lib/codex-worker-app-server.js

@@ -0,0 +1,172 @@
+// One app-server per dispatched worker. The SDK-shaped surface keeps the native
+// worker's event/usage contract while thread/resume reopens its durable thread.
+import { spawn, execFileSync } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
+
+const toml = (v) => Array.isArray(v) ? `[${v.map(toml).join(',')}]`
+  : v && typeof v === 'object' ? `{${Object.entries(v).filter(([, x]) => x != null).map(([k, x]) => `${JSON.stringify(k)}=${toml(x)}`).join(',')}}`
+    : JSON.stringify(v);
+
+// Match the SDK's leaf overrides: pins/switches address only their intended
+// fields and leave native command/url/env definitions in the native config.
+// Codex splits override paths literally on dots (it does not parse TOML keys).
+// Top-level keys may already be override paths; nested keys are literal segments.
+export function codexWorkerConfigOverrides(config) {
+  const overrides = [];
+  const visit = (value, path) => {
+    if (value == null) return;
+    if (typeof value === 'object' && !Array.isArray(value)) {
+      for (const [key, child] of Object.entries(value)) {
+        if (path && /[.=\x00-\x1f\x7f]/.test(key)) throw new Error('Codex override paths cannot address this config key');
+        visit(child, path ? `${path}.${key}` : key);
+      }
+    } else overrides.push(`${path}=${toml(value)}`);
+  };
+  visit(config, '');
+  return overrides;
+}
+
+export class CodexWorkerAppServer {
+  constructor({ codexPathOverride, env, config = {}, configArgs = [], apiKey, signal, onProcess = () => {} }) {
+    this.pending = new Map();
+    this.seq = 0;
+    this.listener = null;
+    this.failure = null;
+    const args = [...configArgs];
+    for (const override of codexWorkerConfigOverrides(config)) args.push('-c', override);
+    // Run identity in the command line permits conservative orphan identification.
+    args.push('-c', `synabun_worker_run=${JSON.stringify(env.SYNABUN_TERMINAL_SESSION || '')}`, 'app-server');
+    this.proc = spawn(codexPathOverride, args, { env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+    this.exited = new Promise((r) => this.proc.once('close', r));
+    onProcess({ pid: this.proc.pid, startedAt: new Date().toISOString() });
+    let buffer = '';
+    const decoder = new StringDecoder('utf8');
+    this.proc.stdout.on('data', (chunk) => {
+      buffer += decoder.write(chunk);
+      let end;
+      while ((end = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, end); buffer = buffer.slice(end + 1);
+        let msg; try { msg = JSON.parse(line); } catch { continue; }
+        if (msg.id != null && !msg.method) {
+          const p = this.pending.get(msg.id); if (!p) continue;
+          this.pending.delete(msg.id); clearTimeout(p.timer);
+          msg.error ? p.reject(new Error(msg.error.message || 'Codex RPC failed')) : p.resolve(msg.result);
+        } else if (msg.id != null) {
+          // Workers have approvalPolicy never. Never grant an unexpected request.
+          this.write({ id: msg.id, error: { code: -32601, message: 'Unattended worker does not accept interactive requests' } });
+        } else this.listener?.(msg);
+      }
+    });
+    // Drain stderr without exposing credentials/config to the worker transcript.
+    this.proc.stderr.resume();
+    this.proc.on('error', (error) => this.fail(error));
+    this.proc.stdin.on('error', (error) => this.fail(error));
+    this.proc.on('close', (code, signal) => this.fail(new Error(`Codex app-server exited (${signal || code})`)));
+    this.ready = (async () => {
+      await this.rpc('initialize', { clientInfo: { name: 'synabun-worker', version: '1.0.0' }, capabilities: { experimentalApi: true } });
+      this.write({ method: 'initialized', params: {} });
+      if (apiKey) await this.rpc('account/login/start', { type: 'apiKey', apiKey });
+    })();
+    this.ready.catch(() => {});
+    this.startupSignal = signal;
+    this.cancelStartup = () => { this.dispose().catch(() => {}); };
+    signal?.addEventListener('abort', this.cancelStartup, { once: true });
+    if (signal?.aborted) this.cancelStartup();
+  }
+  write(value) { if (!this.proc.stdin.destroyed) this.proc.stdin.write(JSON.stringify(value) + '\n'); }
+  fail(error) {
+    this.failure = error;
+    for (const p of this.pending.values()) { clearTimeout(p.timer); p.reject(error); }
+    this.pending.clear();
+    this.listener?.({ method: 'synabun/exit', error });
+  }
+  rpc(method, params) {
+    if (this.failure) return Promise.reject(this.failure);
+    return new Promise((resolve, reject) => {
+      const id = ++this.seq;
+      const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`Codex ${method} timed out`)); }, 30_000);
+      this.pending.set(id, { resolve, reject, timer });
+      this.write({ id, method, params });
+    });
+  }
+  startThread(options) { return this.thread(null, options); }
+  resumeThread(id, options) { return this.thread(id, options); }
+  thread(id, options) {
+    const owner = this;
+    const sandboxPolicy = options.sandboxMode === 'read-only' ? { type: 'readOnly', networkAccess: !!options.networkAccessEnabled }
+      : options.sandboxMode === 'workspace-write' ? { type: 'workspaceWrite', writableRoots: [options.workingDirectory, ...(options.additionalDirectories || [])], networkAccess: !!options.networkAccessEnabled }
+        : { type: 'dangerFullAccess' };
+    const ready = this.ready.then(async () => {
+      const reply = await this.rpc(id ? 'thread/resume' : 'thread/start', {
+        ...(id ? { threadId: id } : {}), cwd: options.workingDirectory,
+        model: options.model || null, approvalPolicy: 'never', sandbox: options.sandboxMode,
+        config: { web_search: options.webSearchMode || 'disabled', sandbox_workspace_write: { network_access: !!options.networkAccessEnabled, writable_roots: options.additionalDirectories || [] } },
+      });
+      const actual = reply?.thread?.id;
+      if (!actual || (id && actual !== id)) throw new Error('Codex did not resume the requested thread');
+      id = actual;
+    });
+    ready.catch(() => {});
+    return {
+      get id() { return id; }, ready: () => ready,
+      async runStreamed(prompt, { signal, outputSchema } = {}) {
+        await ready;
+        const queue = []; const text = new Map(); let wake; let done = false; let failure; let turnId;
+        const push = (event) => { queue.push(event); wake?.(); };
+        const abort = () => {
+          failure = Object.assign(new Error('Codex turn aborted'), { name: 'AbortError' }); done = true; wake?.();
+          if (turnId) owner.rpc('turn/interrupt', { threadId: id, turnId }).catch(() => {});
+        };
+        owner.listener = (msg) => {
+          const p = msg.params || {};
+          if (p.threadId && p.threadId !== id) return;
+          if (msg.method === 'synabun/exit') { failure = msg.error; done = true; wake?.(); }
+          if (msg.method === 'item/agentMessage/delta') {
+            const value = (text.get(p.itemId) || '') + (p.delta || '');
+            text.set(p.itemId, value);
+            push({ type: 'item.updated', item: { id: p.itemId, type: 'agent_message', text: value } });
+          }
+          if (msg.method === 'item/started' || msg.method === 'item/completed') {
+            const item = p.item || {};
+            const types = { agentMessage: 'agent_message', commandExecution: 'command_execution', fileChange: 'file_change', mcpToolCall: 'mcp_tool_call', webSearch: 'web_search', reasoning: 'reasoning' };
+            push({ type: msg.method === 'item/started' ? 'item.started' : 'item.completed', item: { ...item, type: types[item.type] || item.type, aggregated_output: item.aggregatedOutput, exit_code: item.exitCode } });
+          }
+          if (msg.method === 'turn/completed') {
+            if (p.turn?.status === 'failed') push({ type: 'turn.failed', error: p.turn.error || { message: 'Codex turn failed' } });
+            else if (p.turn?.status === 'interrupted') failure = Object.assign(new Error('Codex turn interrupted'), { name: 'AbortError' });
+            else push({ type: 'turn.completed' }); // rollout meter is authoritative across resumes
+            done = true; wake?.();
+          }
+        };
+        signal?.addEventListener('abort', abort, { once: true });
+        try {
+          if (signal?.aborted) throw Object.assign(new Error('Codex turn aborted'), { name: 'AbortError' });
+          const reply = await owner.rpc('turn/start', { threadId: id, input: [{ type: 'text', text: String(prompt), text_elements: [] }], approvalPolicy: 'never', sandboxPolicy, effort: options.modelReasoningEffort || null, ...(outputSchema ? { outputSchema } : {}) });
+          turnId = reply?.turn?.id;
+          if (signal?.aborted) abort();
+        } catch (error) { owner.listener = null; signal?.removeEventListener('abort', abort); throw error; }
+        return { events: (async function* () {
+          try {
+            yield { type: 'thread.started', thread_id: id };
+            while (!done || queue.length) {
+              if (queue.length) yield queue.shift();
+              else await new Promise((r) => { wake = r; });
+            }
+            if (failure) throw failure;
+          } finally { owner.listener = null; signal?.removeEventListener('abort', abort); }
+        })() };
+      },
+    };
+  }
+  async dispose() {
+    this.startupSignal?.removeEventListener('abort', this.cancelStartup);
+    if (this.proc.exitCode !== null || this.proc.signalCode) return;
+    if (process.platform === 'win32') {
+      try { execFileSync('taskkill', ['/pid', String(this.proc.pid), '/T', '/F'], { timeout: 5000, stdio: 'ignore', windowsHide: true }); } catch {}
+    } else this.proc.kill('SIGTERM');
+    let timer;
+    await Promise.race([this.exited, new Promise((r) => { timer = setTimeout(r, 1500); })]);
+    clearTimeout(timer);
+    if (this.proc.exitCode === null && !this.proc.signalCode) this.proc.kill('SIGKILL');
+  }
+}

package/neural-interface/lib/confined-fs.js

@@ -19,7 +19,7 @@
 // sequence; it does not remove it.
 
 import {
-  openSync, closeSync, fstatSync, lstatSync, readSync, writeSync, ftruncateSync, fsyncSync,
+  openSync, closeSync, fstatSync, fchmodSync, lstatSync, readSync, writeSync, ftruncateSync, fsyncSync,
   mkdirSync, readdirSync, rmSync, unlinkSync, renameSync, realpathSync, createReadStream, constants,
 } from 'node:fs';
 import { randomBytes } from 'node:crypto';
@@ -142,6 +142,17 @@ export function writeConfinedFile(base, path, data, { exclusive = false, mode =
     if (!st.isFile()) throw new PathConfineError(400, 'Not a regular file.');
     if (!created) ftruncateSync(fd, 0);
     writeAll(fd, data);
+  } catch (err) {
+    // A file this call created and could not fill (the disk filled, the data could not be had) is not left
+    // half written: it is removed while it is still the file that was opened.
+    if (created) {
+      try {
+        const mine = fstatSync(fd);
+        const now = lstatSync(real);
+        if (now.dev === mine.dev && now.ino === mine.ino) unlinkSync(real);
+      } catch { /* gone already, or no longer ours */ }
+    }
+    throw err;
   } finally { try { closeSync(fd); } catch {} }
   return real;
 }
@@ -173,14 +184,29 @@ export function removeConfinedEntry(base, path) {
   return true;
 }
 
+/**
+ * What is at `path` itself, a link not followed: 'absent', 'file', 'dir', 'link' or 'other' (a FIFO, a
+ * socket, a device). Nothing is opened.
+ */
+export function entryKind(path) {
+  let st;
+  try { st = lstatSync(String(path)); } catch { return 'absent'; }
+  if (st.isSymbolicLink()) return 'link';
+  if (st.isFile()) return 'file';
+  if (st.isDirectory()) return 'dir';
+  return 'other';
+}
+
 /**
  * Replace `path` with `data` through a temporary file in the same folder:
  * created exclusively under an unpredictable name, never through a link, then
  * renamed over `path` (a rename replaces a link, it does not follow it).
  * `expect` is the file's state when it was read ({ dev, ino, mtimeMs, size }):
- * a file that changed since is not overwritten (409).
+ * a file that changed since is not overwritten (409). `exactMode`: the new
+ * file gets `mode` as it is, not narrowed by the process umask (a file that
+ * replaces another keeps the permissions that one had).
  */
-export function replaceFileAtomic(path, data, { mode = 0o600, expect = null } = {}) {
+export function replaceFileAtomic(path, data, { mode = 0o600, expect = null, exactMode = false } = {}) {
   const dir = realPathOf(dirname(String(path)));
   const target = join(dir, basename(String(path)));
   const tmp = join(dir, `.${basename(target)}.${randomBytes(12).toString('hex')}.tmp`);
@@ -190,6 +216,7 @@ export function replaceFileAtomic(path, data, { mode = 0o600, expect = null } =
     try {
       const st = verifyOpened(fd, tmp);
       if (!st.isFile()) throw moved();
+      if (exactMode) fchmodSync(fd, mode & 0o7777);
       writeAll(fd, data);
       try { fsyncSync(fd); } catch {}
     } finally { try { closeSync(fd); } catch {} }

package/neural-interface/lib/crash-notice-api.js

@@ -0,0 +1,98 @@
+// ═══════════════════════════════════════════
+// SynaBun — /api/system/crash-notice: the notice after an automatic restart
+// ═══════════════════════════════════════════
+//
+//   GET  /api/system/crash-notice           { ok, notice }   null, or the crash the supervisor recovered from
+//   POST /api/system/crash-notice/dismiss   { id }           { ok, notice }: what is left (a newer crash's, or null)
+//
+// When the server crashes after it was up, its supervisor (lib/server-supervisor.js at the package root) starts
+// it again and leaves DATA_HOME/data/server-crash.json (lib/server-crash-record.js) for it. The owner's pages ask
+// for it when they load and every time their sync socket connects (a page that was open through the crash
+// reconnects, it is not reloaded: public/shared/ui-crash-notice.js), and show it until the owner dismisses it. A
+// dismissal removes the record, and every open tab and window drops the notice at once (`crash-notice:changed`
+// on the sync socket); none shows it again after a reload. The next crash writes a new record, with a new id,
+// which shows again. A record that cannot be removed (a read-only data folder) is kept dismissed in memory for
+// the life of this server.
+//
+// The owner's only: /api/system is admin-only (lib/request-gate.js), and every route takes the owner's guard by
+// itself (lib/http-guards.js ownerRouteGuard: this server's Host, its Origin on the write, no guest, no cross-site
+// write) and refuses an agent's request (uiOnly: X-SynaBun-Terminal, -Role, -Assistant, -Desktop-Grant, as
+// /api/system/app does). The dismissal is the owner's write from SynaBun's own page: X-SynaBun-UI: 1, a JSON body,
+// and this boot's page secret (lib/page-session.js, as Skills Studio's owner writes), which a local process that
+// merely leaves the agent headers out lacks; a tab that stayed open through the restart carries the previous boot's
+// cookie, and the page's own recovery (public/shared/page-session.js) gets this boot's and sends the dismissal once
+// more. A request names an id, never a path.
+
+import { Router } from 'express';
+import { clearCrashRecord, readCrashRecord } from '../../lib/server-crash-record.js';
+import { sendGuardError, uiOnly } from './http-guards.js';
+
+const ID = /^[0-9a-f]{16}$/;
+
+/** What a page is shown of a record (already checked field by field when it was read), or null. */
+export function crashNoticeOf(record) {
+  if (!record || typeof record !== 'object') return null;
+  const { v, ...notice } = record;
+  return notice;
+}
+
+/**
+ * @param {object} deps
+ * @param {string} deps.dataHome
+ * @param {import('express').RequestHandler} deps.guard   the owner's guard (lib/http-guards.js ownerRouteGuard)
+ * @param {{ verify(req): boolean, require: import('express').RequestHandler }} [deps.pageSession]  lib/page-session.js:
+ *   the page secret a dismissal carries (server.js hands it in; without one, as in a unit test, none is asked)
+ * @param {(message: object) => void} [deps.broadcast]     the owner's open pages (server.js broadcastSync keeps
+ *   `crash-notice:` from invite guests)
+ * @param {() => Promise<{ tunnel?: 'unknown' }>} [deps.leftovers]  what the crashed server may have left running that
+ *   this one could not end (server.js: its cloudflared, sweepLeftoverTunnels): added to the notice
+ */
+export function createCrashNoticeApi({
+  dataHome, guard, pageSession = null, broadcast = () => {}, log = () => {}, read = readCrashRecord, clear = clearCrashRecord,
+  leftovers = async () => ({}),
+} = {}) {
+  if (!dataHome || typeof guard !== 'function') throw new Error('createCrashNoticeApi needs the data home and the owner\'s guard');
+  const router = Router();
+  // Dismissed while the record could not be removed: never shown again by this server.
+  const dismissed = new Set();
+  const current = () => {
+    const notice = crashNoticeOf(read(dataHome));
+    return notice && !dismissed.has(notice.id) ? notice : null;
+  };
+  // The notice as a page is shown it: the record, and what the crashed server may have left open.
+  const shown = async (notice) => {
+    if (!notice) return null;
+    let left = {};
+    try { left = await leftovers(); } catch { left = {}; }
+    return { ...notice, ...(left?.tunnel === 'unknown' ? { tunnel: 'unknown' } : {}) };
+  };
+
+  router.use(guard, uiOnly, (req, res, next) => { res.set('Cache-Control', 'no-store'); next(); });
+
+  router.get('/', async (req, res) => { res.json({ ok: true, notice: await shown(current()) }); });
+
+  router.post('/dismiss', (req, res, next) => {
+    if (req.get('x-synabun-ui') !== '1') return sendGuardError(res, 403, 'UI_HEADER_REQUIRED', 'A notice is dismissed from SynaBun\'s own page.');
+    // The page secret: what a local process that merely sends the page's headers lacks.
+    if (pageSession && !pageSession.verify(req)) return pageSession.require(req, res, next);
+    next();
+  }, async (req, res) => {
+    if (!req.is('application/json')) return res.status(415).json({ ok: false, code: 'JSON_REQUIRED', error: 'Send JSON.' });
+    const id = req.body?.id;
+    if (typeof id !== 'string' || !ID.test(id)) return res.status(400).json({ ok: false, code: 'BAD_REQUEST', error: 'Send { id } of the notice.' });
+    if (!clear(dataHome, { id })) {
+      const still = crashNoticeOf(read(dataHome));
+      if (still?.id === id) {
+        dismissed.add(id);
+        log(`[crash-notice] the record could not be removed; ${id} stays dismissed until the server restarts`);
+      }
+    } else {
+      log(`[crash-notice] dismissed ${id}`);
+    }
+    const notice = await shown(current());
+    try { broadcast({ type: 'crash-notice:changed', notice }); } catch {}
+    res.json({ ok: true, notice });
+  });
+
+  return router;
+}