synabun 2.0.10 → 2.2.0

package/neural-interface/lib/worker-resume.js

@@ -0,0 +1,238 @@
+// ═══════════════════════════════════════════
+// SynaBun — dispatched workers across a server restart
+// ═══════════════════════════════════════════
+//
+// A worker's provider process is a child of the Neural Interface, so every
+// restart of the server (`node --watch` on an edit of its code, an in-app
+// restart, an update, Ctrl+C, a crash) used to end the run as interrupted. The
+// dispatcher (assistant-dispatch.js) now suspends such a run at the shutdown and
+// resumes its provider session on the next start, as the same run. This module is
+// what that decision and the resume need besides the dispatcher's own state:
+//
+//   resumeRefusal     why a run may not be resumed, or null
+//   readCostState     what the resumed CLI restores from its transcript (its cost
+//                     counter and per-model usage), so its first turn is charged
+//                     only for itself
+//   endOrphanProcess  a CLI that outlived its server (a crash: no shutdown ended
+//                     it), ended only once its command line shows it is that run's
+//
+// Measured with the SDK and the Claude Code SynaBun runs (0.3.288 / 2.1.310):
+// a session whose CLI was killed in the middle of a tool call resumes, the CLI
+// records that call as interrupted with its outcome unknown, and the next model
+// call goes through; a CLI that gets SIGTERM ends the tool's process tree,
+// records the call's result and its cost state, and exits within a second.
+
+import { execFileSync } from 'node:child_process';
+import { closeSync, existsSync, fstatSync, openSync, readSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+
+/** A run is resumed when the server is back within this long of its last update, and at most this many times. */
+export const RESUME_WINDOW_MS = 15 * 60_000;
+export const MAX_RESUMES = 3;
+
+/** Rebuild OS isolation without dropping an earlier denial or relaxing strict local networking.
+ * The channel is a fresh listener/token each boot; only that listener replaces the old allow-port.
+ */
+export function resumeSandboxPlan(current, previous, channelPort) {
+  if (!current || !previous) throw new Error('the original worker confinement is unavailable');
+  const paths = (a) => [...new Set(a || [])].sort();
+  if (JSON.stringify(paths(current.allowPaths)) !== JSON.stringify(paths(previous.allowPaths))) {
+    throw new Error('the worker confinement folders changed');
+  }
+  const ranges = [current.denyPortRange, previous.denyPortRange].filter(Boolean);
+  return {
+    ...current,
+    denyPorts: [...new Set([...(current.denyPorts || []), ...(previous.denyPorts || [])])],
+    denyLocalPorts: [...new Set([...(current.denyLocalPorts || []), ...(previous.denyLocalPorts || [])])],
+    denyPaths: [...new Set([...(current.denyPaths || []), ...(previous.denyPaths || [])])],
+    denyPortRange: ranges.length ? { from: Math.min(...ranges.map(r => r.from)), to: Math.max(...ranges.map(r => r.to)) } : null,
+    strictLocal: previous.strictLocal || current.strictLocal ? { allowPorts: [channelPort].filter(Boolean) } : null,
+  };
+}
+
+/**
+ * Why `entry` (a dispatcher registry entry) cannot be resumed, or null. `atShutdown`: only what is known while the
+ * server goes down (the rest is checked at the next start: the time it was away, its folder, its account).
+ *
+ * @param {object} entry
+ * @param {object} o
+ * @param {number} [o.now]
+ * @param {number} [o.workLeftMs]  the run's work time left (max_minutes)
+ * @param {boolean} [o.atShutdown]
+ * @param {(path: string) => boolean} [o.isDirectory]
+ * @param {(accountId: string) => string} [o.accountUnusable]  '' when the Claude account can be used
+ */
+export function resumeRefusal(entry, { now = Date.now(), workLeftMs = Infinity, atShutdown = false, isDirectory = () => true, accountUnusable = () => '' } = {}) {
+  if (!entry) return 'the run is not known';
+  if (!['claude-code', 'codex', 'opencode', 'antigravity'].includes(entry.provider)) return 'this provider cannot continue after a restart';
+  if (entry.confinement?.kind === 'skill-eval') return 'a skill evaluation run is a measurement and starts over instead';
+  if (entry.confinement) return 'a skill drafting run is not resumed';
+  if (entry.removedAt) return 'the run was removed';
+  if (!(entry.provider === 'codex' ? entry.providerThreadId : entry.providerSessionId)) return `its ${entry.provider === 'codex' ? 'Codex thread' : entry.provider === 'opencode' ? 'OpenCode session' : entry.provider === 'antigravity' ? 'Antigravity session' : 'Claude session'} had not started yet`;
+  if (entry.provider === 'opencode' && !entry.resumeInfo?.persistentOpenCode) return 'its OpenCode session has no durable run data';
+  // Antigravity keeps the conversation in the run's own home (lib/antigravity/home.js): a run started before homes
+  // existed has its session in the user's own ~/.gemini, which a resume does not use.
+  if (entry.provider === 'antigravity' && !entry.resumeInfo?.antigravityHome) return 'its Antigravity session has no SynaBun home to resume from';
+  const resumes = Number(entry.resumes) || 0;
+  if (resumes >= MAX_RESUMES) return `it was resumed ${resumes} times already`;
+  if (!(workLeftMs > 0)) return entry.maxMinutes ? `its ${entry.maxMinutes} minutes of work time are used up` : 'its work time is used up';
+  if (atShutdown) return null;
+  const since = Date.parse(entry.suspendedAt || '') || Date.parse(entry.updatedAt || '') || 0;
+  if (since && now - since > RESUME_WINDOW_MS) return `the server was back ${Math.round((now - since) / 60_000)} minutes later (more than ${Math.round(RESUME_WINDOW_MS / 60_000)})`;
+  if (!entry.cwd || !isDirectory(entry.cwd)) return `its working directory is gone (${entry.cwd || 'none'})`;
+  let unusable = '';
+  // OpenCode and Antigravity sign in inside their own CLI: SynaBun keeps no account of theirs.
+  try { unusable = entry.provider === 'opencode' || entry.provider === 'antigravity' ? '' : String(accountUnusable((entry.provider === 'codex' ? entry.codexAccountId : entry.claudeAccountId) || 'default', entry.provider, entry) || ''); } catch (error) { unusable = error?.message || 'it could not be read'; }
+  if (unusable) return `its ${entry.provider === 'codex' ? 'Codex' : 'Claude'} account (${entry.codexAccountId || entry.claudeAccountId || 'default'}) cannot be used: ${unusable}`;
+  return null;
+}
+
+/** Whether `path` is `root` or inside it (both resolved; a missing path is compared as written). */
+export function isInside(path, root) {
+  if (!path || !root) return false;
+  const real = (value) => { try { return realpathSync(value); } catch { return resolve(String(value)); } };
+  const rel = relative(real(root), real(path));
+  return rel === '' || (!!rel && !rel.startsWith('..') && !isAbsolute(rel));
+}
+
+/** "14:05": a time of day on this computer's clock, or '' for no time. */
+export function clockTime(value) {
+  const ms = typeof value === 'number' ? value : Date.parse(value || '');
+  if (!Number.isFinite(ms) || ms <= 0) return '';
+  const date = new Date(ms);
+  return `${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}`;
+}
+
+/**
+ * The transcript of a Claude session: <config dir>/projects/<project folder>/<sessionId>.jsonl, the config dir being
+ * the run's account's (CLAUDE_CONFIG_DIR) or ~/.claude. Every project folder is looked in (the CLI names it after
+ * the real path of the working directory). null when there is none.
+ */
+export function findClaudeTranscript({ sessionId, configDir = null, home = homedir() } = {}) {
+  const id = String(sessionId || '');
+  if (!/^[0-9a-f-]{8,64}$/i.test(id)) return null;
+  const projects = join(configDir || join(home, '.claude'), 'projects');
+  let folders = [];
+  try { folders = readdirSync(projects, { withFileTypes: true }).filter((item) => item.isDirectory()).map((item) => item.name); } catch { return null; }
+  for (const folder of folders) {
+    const path = join(projects, folder, `${id}.jsonl`);
+    try { if (statSync(path).isFile()) return path; } catch { /* not here */ }
+  }
+  return null;
+}
+
+/** The last `maxBytes` of a file as text (a partial first line is dropped). */
+function readTail(path, maxBytes = 1024 * 1024) {
+  let fd = null;
+  try {
+    fd = openSync(path, 'r');
+    const size = fstatSync(fd).size;
+    const length = Math.min(size, maxBytes);
+    const buffer = Buffer.alloc(length);
+    readSync(fd, buffer, 0, length, size - length);
+    const text = buffer.toString('utf8');
+    return size > length ? text.slice(text.indexOf('\n') + 1) : text;
+  } catch { return ''; } finally { if (fd !== null) { try { closeSync(fd); } catch { /* closed */ } } }
+}
+
+/**
+ * The cost state a resumed CLI starts from: the last `cost-state` line of the session's transcript, which the CLI
+ * writes when it exits cleanly (a SIGTERM included) and reads back when the session is resumed. →
+ * { totalCostUsd, modelUsage } (modelUsage as result.modelUsage spells it), or null when there is none (a CLI that
+ * was killed outright starts its counters at zero).
+ */
+export function readCostState(path, sessionId = null) {
+  if (!path || !existsSync(path)) return null;
+  const lines = readTail(path).split('\n');
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i];
+    if (!line.includes('"cost-state"')) continue;
+    let row = null;
+    try { row = JSON.parse(line); } catch { continue; }
+    if (row?.type !== 'cost-state') continue;
+    if (sessionId && row.sessionId && row.sessionId !== sessionId) continue;
+    const total = Number(row.totalCostUSD);
+    return {
+      totalCostUsd: Number.isFinite(total) && total > 0 ? total : 0,
+      modelUsage: row.modelUsage && typeof row.modelUsage === 'object' && !Array.isArray(row.modelUsage) ? row.modelUsage : null,
+    };
+  }
+  return null;
+}
+
+/** Whether a process with this pid exists (one of another user's counts as existing). */
+export function processExists(pid) {
+  const id = Number(pid);
+  if (!Number.isInteger(id) || id <= 0) return false;
+  try { process.kill(id, 0); return true; } catch (error) { return error?.code === 'EPERM'; }
+}
+
+/** The command line of a process, or null when it cannot be read (no such process, no `ps`, Windows without CIM). */
+export function processCommandLine(pid, { platform = process.platform, run = execFileSync } = {}) {
+  const id = Number(pid);
+  if (!Number.isInteger(id) || id <= 0) return null;
+  try {
+    if (platform === 'win32') {
+      const out = run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `(Get-CimInstance Win32_Process -Filter "ProcessId=${id}").CommandLine`], { encoding: 'utf8', timeout: 5000, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
+      return String(out || '').trim() || null;
+    }
+    const out = run('ps', ['-o', 'command=', '-p', String(id)], { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] });
+    return String(out || '').trim() || null;
+  } catch { return null; }
+}
+
+/**
+ * A run's own Claude Code CLI: started by the Agent SDK (stream-json both ways) with the run's id in its SynaBun MCP
+ * headers (X-Synabun-Terminal). Anything else with the pid is left alone.
+ */
+export function isRunCliCommand(command, runId) {
+  const text = String(command || '');
+  return !!runId && text.includes(String(runId)) && (
+    (text.includes('--input-format') && text.includes('stream-json'))
+    || (text.includes('app-server') && text.includes('synabun_worker_run='))
+    // Antigravity: `agy acp --gemini-dir <data home>/runtime/antigravity/homes/run-<run id>-…` (lib/antigravity/home.js).
+    || (/\sacp(?:\s|$)/.test(text) && text.includes('--gemini-dir') && /[\\/]antigravity[\\/]homes[\\/]run-/.test(text))
+  );
+}
+
+/** Windows: end a process and every process it started (taskkill /T /F, as the server's own shutdown does). */
+export function endProcessTree(pid, { run = execFileSync } = {}) {
+  run('taskkill', ['/pid', String(pid), '/T', '/F'], { timeout: 5000, windowsHide: true, stdio: 'ignore' });
+}
+
+/**
+ * End the CLI a run had before the server went down, when it is still there (a crash ended no process). It is ended
+ * only when its command line shows it is that run's CLI: SIGTERM, then SIGKILL after `graceMs` once the pid still
+ * shows that command line (it may have gone to another process meanwhile). Windows has no SIGTERM (a signal stops the
+ * CLI alone and leaves its tool's processes, a dev server keeps its port): the tree is ended with taskkill.
+ * → { state: 'gone' | 'ended' | 'killed' | 'still_running' | 'not_ours' | 'unknown' }.
+ * 'unknown': a process has the pid but its command line cannot be read, so it is not touched.
+ */
+export async function endOrphanProcess({ pid, runId, graceMs = 2000, platform = process.platform, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), readCommand = processCommandLine, exists = processExists, kill = (id, signal) => process.kill(id, signal), killTree = endProcessTree } = {}) {
+  const id = Number(pid);
+  if (!Number.isInteger(id) || id <= 0 || id === process.pid || !exists(id)) return { state: 'gone' };
+  const command = readCommand(id);
+  // No command line: a process that exited meanwhile is gone; one still there is not touched.
+  if (command === null) return { state: exists(id) ? 'unknown' : 'gone' };
+  if (!isRunCliCommand(command, runId)) return { state: 'not_ours' };
+  if (platform === 'win32') {
+    try { killTree(id); } catch { /* gone meanwhile, or not allowed: checked below */ }
+    for (let waited = 0; waited < graceMs; waited += 100) {
+      await sleep(100);
+      if (!exists(id)) return { state: 'killed' };
+    }
+    return { state: 'still_running' };
+  }
+  try { kill(id, 'SIGTERM'); } catch { /* gone meanwhile */ }
+  for (let waited = 0; waited < graceMs; waited += 100) {
+    await sleep(100);
+    if (!exists(id)) return { state: 'ended' };
+  }
+  const again = readCommand(id);
+  if (again === null) return { state: exists(id) ? 'still_running' : 'ended' };
+  if (!isRunCliCommand(again, runId)) return { state: 'ended' };
+  try { kill(id, 'SIGKILL'); } catch { /* gone meanwhile */ }
+  await sleep(200);
+  return { state: exists(id) ? 'still_running' : 'killed' };
+}

package/neural-interface/lib/worker-sandbox.js

@@ -0,0 +1,329 @@
+// ═══════════════════════════════════════════
+// SynaBun — macOS Seatbelt isolation for guarded worker trees (pure + small fs)
+// ═══════════════════════════════════════════
+//
+// A dispatched worker (capability read-only / workspace, Protect workers = Enforce) can reach SynaBun's own control
+// listener on localhost:<NEURAL_PORT> from any program it runs — node -e, python, a script, a detached process —
+// fetch the owner's page cookie, and act as the owner (dispatch a full worker, turn Protect workers off, install a
+// skill). The in-code shell guard is only a speed bump: arbitrary code is opaque to it.
+//
+// On macOS the real boundary is the OS: run the worker's whole process tree under sandbox-exec with a profile that
+// blocks outbound connections to SynaBun's control port (and the other local endpoints that can relay commands or
+// owner authority), while leaving everything legitimate working — the internet, reads anywhere, writes per
+// capability, the project's tests, and the worker's own SynaBun MCP tools, which reach SynaBun through a worker-only
+// channel on a port the profile leaves open (see lib/worker-mcp-channel.js).
+//
+// Proven on macOS 26 (scratch probes, 2026-10-23 / 2026-10-24), the facts this module relies on:
+//   • `(deny network-outbound (remote ip "*:<port>"))` blocks that port on EVERY host — 127.0.0.1, localhost, ::1,
+//     [::ffff:127.0.0.1] (the IPv4-mapped IPv6 form a dual-stack app.listen answers on), 0.0.0.0, this Mac's LAN /
+//     interface IPs and its hostname — while a different port and the public internet stay open. The earlier
+//     `localhost:<port>` literal did NOT cover [::ffff:127.0.0.1] (a verified full bypass of the whole layer on the
+//     dual-stack listener): Seatbelt's `localhost` resolves to 127.0.0.1 + ::1 only. The host literal must be `*`
+//     or `localhost` (a numeric IP literal, with or without a CIDR suffix, is rejected by the parser: "host must be
+//     * or localhost in network address"); `*` is the only form that is address-proof.
+//     Seatbelt has no port-range syntax (`*:4120-4400` is rejected), so a reserved range is emitted one port a line.
+//   • `(deny file-read* file-write* (subpath "<canonical>"))` blocks reads AND writes under a path; a later
+//     `(allow file-read* file-write* (subpath "<canonical>"))` wins (Seatbelt is last-match-wins within a filter),
+//     so SynaBun's whole data home can be denied and the run's own scratch / cwd / config folder allowed back after
+//     it. Seatbelt matches the RESOLVED path, so every literal must be canonicalised (/tmp is a symlink to
+//     /private/tmp; an un-resolved literal never matches, and an allow-back must resolve the same way as its deny).
+//   • macOS 27 (27.2 / 26B123, confirmed with scratch sandbox-exec probes outside the repo, 2026-11-01): a
+//     `(deny network-outbound (remote ip …))` rule placed textually AFTER an `(allow network-outbound (remote ip
+//     …))` rule silently defeats that allow — even when the deny's port is completely unrelated to the allow's
+//     (e.g. a later `deny *:4096` broke an earlier `allow localhost:9` for a different, unrelated port 9). This
+//     held on every literal form tried (`localhost` and `*` alike), so it is not about the host literal at all —
+//     it is purely textual position. A deny is never undone by what comes after it, and a later allow for one port
+//     never reopens a different, already-denied port — only "deny AFTER allow, different port" misbehaves. A
+//     same-port pair (a broad `*:<port>` allow immediately followed by a narrower `localhost:<port>` deny, the
+//     INTERNET_PORTS local-redeny below) still narrows correctly on 27.2: last-match-wins for an overlapping
+//     filter is unaffected, confirmed by direct probe. The fix is purely about ORDER, so buildWorkerSandboxProfile
+//     emits every plain port/range deny FIRST, then the strict profile's own allow-then-narrow pair for
+//     INTERNET_PORTS, then the worker-channel allow(s) dead last among network-outbound rules — nothing (deny)
+//     ever follows them, on macOS 26 or 27. This does not widen anything: the channel allow keeps the narrow
+//     `localhost:<port>` literal (still local-only on both macOS versions), and the reorder also fixes a second,
+//     previously-undetected collateral regression — the strict profile's own INTERNET_PORTS allow-back (meant to
+//     keep DNS/SSH/HTTP/HTTPS reachable on real remote hosts) was equally defeated by the later control-port and
+//     reserved-range denies that used to sit between it and nothing; a guarded worker in the strict fallback had
+//     silently lost the public internet too.
+//   • The sandbox is inherited by detached / nohup grandchildren, so a worker cannot escape it by backgrounding.
+//   • A same-user `KERN_PROCARGS2` read (ps -E / a tiny C program) CANNOT be blocked by Seatbelt (it is a same-uid
+//     kernel allowance, not a sandbox-governed operation). So a worker inside the sandbox can still read another
+//     same-user process's argv+env — including a brain's SYNABUN_BRAIN_TOKEN, or a relay's password in env. That
+//     theft is harmless here because the token/password is useless without reaching a port this profile blocks on
+//     every address; a Codex worker (which this module cannot wrap — nested sandbox-exec is refused) is held by
+//     running with its network off instead.
+//
+// This module is macOS-only. On every other platform sandboxSupported() is false; and even on macOS the caller
+// gates on sandboxExecAvailable() (a one-time boot probe that /usr/bin/sandbox-exec exists and runs a trivial
+// allow-default profile), falling back to the in-code guard alone when it does not. Pure but for canonicalising
+// paths, the boot probe, and writing the profile / wrapper into a run's own scratch folder; unit-tested in
+// tests/worker-sandbox.test.mjs.
+//
+// NOT EQUIVALENT OFF macOS (stated plainly; HIGH elsewhere). Where this module does not apply — Linux, Windows, or a
+// macOS host whose sandbox-exec is unavailable — a protected (Enforce, read-only/workspace) worker is held only by the
+// in-code guard (the shell heuristic + the tool hooks), which reads the command line only and so is a lexical
+// speed-bump, not a boundary: a script file (`node /path/x.js`), hidden-address inline code, or any program doing its
+// own networking slips past it. Two things the macOS profile closes that nothing else does there: (a) SynaBun's
+// OpenCode serve band 4096-4400 is unblocked, so a worker's script can connect to a serve; (b) a SHARED (non-protected)
+// serve keeps its OPENCODE_PASSWORD in its process environment (lib/opencode-protocol.js serveSpecFor env mode; only a
+// protected worker's OWN isolated serve hides it via passwordFrom 'stdout'), and a same-uid process can read another
+// process's environment (KERN_PROCARGS2 / /proc/<pid>/environ) — a read no sandbox blocks — so a prompt-injected worker
+// off macOS could read that password and open a full-control session on the shared serve. On macOS under Enforce the
+// 4096-4400 deny (plus the data-home/credential denies below) is the real boundary that stops both. The protected-
+// worker IN-FOLDER confinement off macOS is therefore best-effort, not a guarantee. See docs/assistant.md → Worker
+// confinement → "Protected-worker in-folder confinement off macOS is NOT equivalent to macOS".
+
+import { chmodSync, existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+export const SANDBOX_EXEC = '/usr/bin/sandbox-exec';
+/**
+ * The ports the internet needs (SSH, DNS, HTTP, HTTPS). A relay found listening on one of them is denied on this
+ * computer's own addresses only (`localhost:<port>`: 127.0.0.1, ::1, every interface address and the hostname —
+ * not the IPv4-mapped spelling, which only `*` covers), never with `*:<port>`, which would cut the worker's internet.
+ * The strict profile (detection failed) allows exactly these, plus the worker channel.
+ */
+export const INTERNET_PORTS = Object.freeze([22, 53, 80, 443]);
+/** Local ports no guarded worker has a reason to open: SSH to this computer (Remote Login) is a shell outside the
+ *  sandbox. Denied on this computer's own addresses in every guarded profile; ssh to other hosts is untouched. */
+export const ALWAYS_LOCAL_DENY_PORTS = Object.freeze([22]);
+
+/** macOS only: the platform where the Seatbelt primitives above hold. A cheap pure check for tests and early gates. */
+export function sandboxSupported(platform = process.platform) {
+  return platform === 'darwin';
+}
+
+// Whether /usr/bin/sandbox-exec exists AND runs a trivial allow-default profile: probed once (cheap, ~15 ms) and
+// cached, so a host where Seatbelt is missing or broken falls back to the in-code guard instead of failing every
+// guarded worker. null = not yet probed.
+let _sandboxExecProbe = null;
+/**
+ * macOS AND sandbox-exec works. Cached after the first probe. The caller (server.js) gates OS isolation on this,
+ * never on sandboxSupported() alone, so a missing / broken sandbox-exec is a visible fall-back, not a launch failure.
+ */
+export function sandboxExecAvailable({ platform = process.platform, spawn = spawnSync, force = false } = {}) {
+  if (!sandboxSupported(platform)) return false;
+  if (_sandboxExecProbe !== null && !force) return _sandboxExecProbe;
+  let ok = false;
+  try {
+    if (existsSync(SANDBOX_EXEC)) {
+      const r = spawn(SANDBOX_EXEC, ['-p', '(version 1)(allow default)', '/usr/bin/true'], { timeout: 5000, stdio: 'ignore' });
+      ok = !r.error && r.status === 0 && !r.signal;
+    }
+  } catch { ok = false; }
+  _sandboxExecProbe = ok;
+  return ok;
+}
+/** Tests only: forget the cached probe result. */
+export function _resetSandboxExecProbe() { _sandboxExecProbe = null; }
+
+/** A Seatbelt string literal: double-quoted, with `\` and `"` escaped. */
+function sexpr(text) {
+  return `"${String(text).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+/** Where a path really is (Seatbelt matches the resolved path); the deepest existing ancestor resolved, rest as named. */
+export function canonicalPath(abs) {
+  let probe = isAbsolute(abs) ? abs : resolve(abs);
+  const rest = [];
+  for (let i = 0; i < 256; i++) {
+    try { const real = realpathSync(probe); return rest.length ? join(real, ...rest.reverse()) : real; }
+    catch { const parent = dirname(probe); if (parent === probe) return resolve(abs); rest.push(probe.slice(parent.length).replace(/^[/\\]+/, '')); probe = parent; }
+  }
+  return resolve(abs);
+}
+
+/** Valid, deduped, sorted ports from a list. */
+function cleanPorts(ports) {
+  return [...new Set((ports || []).map(Number).filter((p) => Number.isInteger(p) && p > 0 && p < 65536))].sort((a, b) => a - b);
+}
+
+/**
+ * The ancestor DIRECTORIES of each allow-back that fall inside a denied tree. `(deny file-read* (subpath X))` denies
+ * metadata too, so when a run's scratch folder is allowed back under a denied data home, node cannot even `lstat`
+ * the denied ancestors (/dataHome, /dataHome/data, /dataHome/data/scratch) to resolve a path there — it fails EPERM
+ * before it runs a script. Granting `file-read-metadata` on those exact directory nodes (a literal, not a subpath:
+ * the directory itself, never its contents) lets the lookup through without exposing any file in the denied tree.
+ * Canonical in, canonical out (the allow paths are already canonical, so their dirname chain is too).
+ */
+function metadataAncestors(allowPaths, denyPaths) {
+  const denies = denyPaths.map((p) => (p.endsWith('/') ? p.slice(0, -1) : p)).filter(Boolean);
+  const insideADeny = (dir) => denies.some((d) => dir === d || dir.startsWith(d + '/'));
+  const out = new Set();
+  for (const allow of allowPaths) {
+    let dir = dirname(allow);
+    for (let i = 0; i < 256; i++) {
+      if (insideADeny(dir)) out.add(dir);
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return [...out];
+}
+
+/**
+ * The Seatbelt profile for a guarded worker tree.
+ * @param {object} o
+ * @param {number[]} o.denyPorts individual ports to block OUTBOUND to, on EVERY host (NEURAL_PORT + its WebSockets,
+ *                               the launch beacon, the shared OpenCode serve). The worker-only MCP channel port is
+ *                               NOT here — the profile must leave it open.
+ * @param {{from:number,to:number}} [o.denyPortRange] a reserved range (SynaBun's isolated OpenCode serves) blocked
+ *                               in FULL, so a relay started after this profile is written is already denied. Each
+ *                               port in it is a line (Seatbelt has no range syntax).
+ * @param {string[]} [o.denyPaths] folders / files whose reads AND writes are denied (SynaBun's whole data home, the
+ *                               other runtimes' credential files this run does not use). Each is canonicalised.
+ * @param {string[]} [o.allowPaths] folders allowed back AFTER the denies (the run's own scratch / cwd / config), so
+ *                               a path under a denied tree the run truly needs survives. Canonicalised; placed last
+ *                               (last match wins).
+ * @param {number[]} [o.denyLocalPorts] ports blocked OUTBOUND on this computer's own addresses only (`localhost:<port>`):
+ *                               a relay found on an internet port (22, 53, 80, 443), and local SSH.
+ * @param {{ allowPorts:number[] }} [o.strictLocal] relay detection FAILED for this run: no outbound connection at all
+ *                               but the internet's ports (INTERNET_PORTS, on other hosts) and the worker channel
+ *                               (`allowPorts`, on this computer). `*:*` is the only rule that covers every local
+ *                               spelling (the IPv4-mapped one included); Seatbelt's `localhost` misses [::ffff:…],
+ *                               and mixing `ip6` rules with `localhost` ones silently re-opens IPv4 loopback (verified
+ *                               on macOS 26), so this is written as deny-all-then-allow, never as a loopback deny.
+ *                               On macOS 27 a later deny for an unrelated port defeats an earlier allow (see the
+ *                               module header), so every network-outbound ALLOW rule this emits — the strict
+ *                               profile's INTERNET_PORTS allow-back and the channel allow(s) — is placed after
+ *                               every plain port/range deny, with the channel allow(s) last of all.
+ * @param {string} [o.note] a short comment line (the run id), for readability in a log.
+ * @returns {string} the profile text (ends with a newline).
+ */
+export function buildWorkerSandboxProfile({ denyPorts = [], denyLocalPorts = [], denyPortRange = null, denyPaths = [], allowPaths = [], note = '', strictLocal = null } = {}) {
+  const localOnly = new Set(cleanPorts(denyLocalPorts));
+  // A port the internet needs is never denied on every host: it goes to the local-only list instead.
+  const ports = cleanPorts(denyPorts).filter((p) => { if (INTERNET_PORTS.includes(p)) { localOnly.add(p); return false; } return true; });
+  const range = denyPortRange && Number.isInteger(Number(denyPortRange.from)) && Number.isInteger(Number(denyPortRange.to))
+    ? { from: Math.max(1, Number(denyPortRange.from)), to: Math.min(65535, Number(denyPortRange.to)) } : null;
+  const denies = [...new Set((denyPaths || []).filter((p) => typeof p === 'string' && p).map(canonicalPath))];
+  const allows = [...new Set((allowPaths || []).filter((p) => typeof p === 'string' && p).map(canonicalPath))];
+  const channelPorts = strictLocal ? cleanPorts(strictLocal.allowPorts) : [];
+  const lines = ['(version 1)'];
+  if (note) lines.push(`; ${String(note).replace(/[\r\n]+/g, ' ').slice(0, 200)}`);
+  lines.push('(allow default)');
+  if (strictLocal) {
+    // Detection failed: nothing local is known to be safe, so nothing local is reachable but the worker channel.
+    lines.push('; strict: the relay detection failed for this run, so no local port is reachable but the worker channel');
+    lines.push(`(deny network-outbound (remote ip ${sexpr('*:*')}))`);
+  }
+  // The control ports and the reserved relay range FIRST, before any allow rule below: on macOS 27 a later deny
+  // here would defeat an earlier allow for an unrelated port (module header). A plain deny is never undone by
+  // what follows it, so their own position relative to each other never matters.
+  const seen = new Set();
+  for (const port of ports) { seen.add(port); lines.push(`(deny network-outbound (remote ip ${sexpr(`*:${port}`)}))`); }
+  // The reserved relay range in full: every isolated OpenCode serve, whether it started before or after this profile.
+  if (range) for (let p = range.from; p <= range.to; p++) { if (!seen.has(p)) { seen.add(p); lines.push(`(deny network-outbound (remote ip ${sexpr(`*:${p}`)}))`); } }
+  if (strictLocal) {
+    // Allow the internet's ports back on every host, then narrow them to this computer's own addresses right
+    // after (same port: last-match-wins narrows it locally, unaffected by the macOS 27 ordering issue above,
+    // which is about an unrelated port's deny, not a same-port narrowing pair).
+    for (const port of INTERNET_PORTS) if (port !== 53) localOnly.add(port); // a local DNS resolver stays reachable
+    for (const port of channelPorts) localOnly.delete(port);
+    for (const port of INTERNET_PORTS) lines.push(`(allow network-outbound (remote ip ${sexpr(`*:${port}`)}))`);
+  }
+  // Local-only denies (an internet port a relay holds here, local SSH): this computer's own addresses, never the
+  // internet. In strict mode these sit right after the INTERNET_PORTS allow-back above (the same-port narrowing
+  // pair); otherwise there is no preceding allow to narrow and the position carries no ordering requirement.
+  for (const port of [...new Set([...localOnly, ...ALWAYS_LOCAL_DENY_PORTS])].sort((x, y) => x - y)) {
+    if (channelPorts.includes(port)) continue;
+    lines.push(`(deny network-outbound (remote ip ${sexpr(`localhost:${port}`)}))`);
+  }
+  // The worker channel, allowed dead last among every network-outbound rule above: on macOS 27 any later deny —
+  // even for a wholly unrelated port — would silently defeat this allow (module header). Kept local-only
+  // (`localhost:<port>`, not `*:<port>`): still unreachable from a remote host on this exact port, on macOS 26 and 27.
+  for (const port of channelPorts) lines.push(`(allow network-outbound (remote ip ${sexpr(`localhost:${port}`)}))`);
+  // SynaBun's whole data home (its auth secrets, other runs' task text, the memory DB) and other runtimes' creds:
+  // a worker neither reads nor writes them.
+  for (const path of denies) lines.push(`(deny file-read* file-write* (subpath ${sexpr(path)}))`);
+  // Allowed back LAST (last match wins): the run's own scratch folder, its cwd when that is inside the data home
+  // (skill-drafting workspaces), and its OpenCode config folder — everything the run legitimately needs there.
+  for (const path of allows) lines.push(`(allow file-read* file-write* (subpath ${sexpr(path)}))`);
+  // Metadata-only on the denied ancestors of each allow-back, so `node scratch/probe.mjs` can lstat its way in
+  // (without this, a denied data-home ancestor fails EPERM before the script runs). Directory nodes only (literal),
+  // placed after the file allow-backs so this metadata grant is the last match for those paths.
+  for (const dir of metadataAncestors(allows, denies)) lines.push(`(allow file-read-metadata (literal ${sexpr(dir)}))`);
+  return `${lines.join('\n')}\n`;
+}
+
+/** sandbox-exec argv to run `command args…` under a written profile (OpenCode's serve launch). */
+export function sandboxExecArgv(profilePath, command, args = []) {
+  return [SANDBOX_EXEC, '-f', profilePath, command, ...(Array.isArray(args) ? args : [])];
+}
+
+/**
+ * Write a run's Seatbelt profile and (for a CLI the Agent SDK spawns directly) a wrapper script that execs the real
+ * executable under it. The SDK uses pathToClaudeCodeExecutable verbatim with shell:false, so the wrapper is a plain
+ * shebang script that forwards its arguments; the sandbox is inherited by everything the CLI then starts.
+ *
+ * @param {object} o
+ * @param {string} o.dir      a folder the run owns (its scratch folder): the profile and wrapper live here.
+ * @param {string} o.profile  the profile text (buildWorkerSandboxProfile).
+ * @param {string} [o.realExecutable] the executable the wrapper should exec (for Claude); omit for OpenCode.
+ * @param {string} [o.nodeRunner] the node to run a `.js` entry with (default process.execPath); only used when the
+ *                 real executable is a script the Agent SDK would itself have run via node (.js / .mjs / …).
+ * @param {string} [o.name]   a basename stem (default 'worker').
+ * @returns {{ profilePath: string, wrapperPath: string|null }}
+ *
+ * The wrapper must be named so the Agent SDK spawns it DIRECTLY (not via node): the SDK runs a
+ * pathToClaudeCodeExecutable that ends in .js/.mjs/.ts/.tsx/.jsx through `node`, anything else directly. `.sh`
+ * is spawned directly, so the wrapper execs sandbox-exec itself. If the REAL executable is such a script, the
+ * wrapper runs it under node (what the SDK would have done), so the sandbox still wraps the whole tree.
+ */
+export function writeWorkerSandbox({ dir, profile, realExecutable = null, nodeRunner = process.execPath, name = 'worker' }) {
+  if (!dir) throw new Error('writeWorkerSandbox needs a directory the run owns');
+  mkdirSync(dir, { recursive: true });
+  const stem = String(name).replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 64) || 'worker';
+  const profilePath = join(dir, `${stem}.sb`);
+  writeFileSync(profilePath, profile, { mode: 0o600 });
+  let wrapperPath = null;
+  if (realExecutable) {
+    wrapperPath = join(dir, `${stem}-wrap.sh`);
+    // exec, so the wrapper process is replaced by sandbox-exec (no extra shell in the tree). "$@" forwards argv
+    // verbatim. The real executable (and node, when the entry is a script) and the profile are single-quoted.
+    const sh = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+    const isScript = /\.(?:mjs|cjs|js|ts|tsx|jsx)$/i.test(realExecutable);
+    const runTarget = isScript ? `${sh(nodeRunner)} ${sh(realExecutable)}` : sh(realExecutable);
+    writeFileSync(wrapperPath, `#!/bin/sh\nexec ${sh(SANDBOX_EXEC)} -f ${sh(profilePath)} ${runTarget} "$@"\n`, { mode: 0o700 });
+    chmodSync(wrapperPath, 0o700);
+  }
+  return { profilePath, wrapperPath };
+}
+
+/**
+ * Everything a guarded Claude / OpenCode run needs for OS isolation, or null when it does not apply (not macOS, no
+ * guard, warn / off, or the capability is full). The caller gathers the data-home trees and other-runtime creds to
+ * deny and the run's own folders to allow back; this assembles the port set and gates on an enforced guard. Writing
+ * is left to the caller (writeWorkerSandbox) so a failure to write never throws on the launch path — the caller
+ * falls back to the in-code guard and says so.
+ * @param {{ allowPorts:number[] }} [o.strictLocal] the relay detection failed: the strict profile (see
+ *   buildWorkerSandboxProfile), with `allowPorts` the worker channel.
+ * @returns {{ denyPorts:number[], denyLocalPorts:number[], denyPortRange:{from,to}|null, denyPaths:string[], allowPaths:string[], note:string, strictLocal:object|null } | null}
+ */
+export function workerSandboxPlan({ confinement, serverPort = null, reservedPortRange = null, extraDenyPorts = [], denyPaths = [], allowPaths = [], strictLocal = null, platform = process.platform } = {}) {
+  if (!sandboxSupported(platform)) return null;
+  if (!confinement || !confinement.enforced) return null; // only an enforced guard (read-only / workspace) is wrapped
+  const denyPorts = [];
+  const denyLocalPorts = [];
+  const own = Number(serverPort || confinement.serverPort) || null;
+  if (own) denyPorts.push(own);
+  for (const p of extraDenyPorts || []) {
+    const n = Number(p);
+    if (!(n > 0)) continue;
+    // A relay on an internet port is denied on this computer's addresses only; the internet keeps the port.
+    if (INTERNET_PORTS.includes(n)) denyLocalPorts.push(n); else denyPorts.push(n);
+  }
+  const strictAllow = strictLocal ? cleanPorts(strictLocal.allowPorts) : [];
+  return {
+    denyPorts: [...new Set(denyPorts)],
+    denyLocalPorts: [...new Set(denyLocalPorts)],
+    denyPortRange: reservedPortRange && Number(reservedPortRange.from) > 0 && Number(reservedPortRange.to) > 0
+      ? { from: Number(reservedPortRange.from), to: Number(reservedPortRange.to) } : null,
+    denyPaths: [...new Set((denyPaths || []).filter(Boolean))],
+    allowPaths: [...new Set((allowPaths || []).filter(Boolean))],
+    note: `synabun worker ${confinement.capability} (${confinement.mode})${strictLocal ? ' strict' : ''}`,
+    strictLocal: strictLocal ? { allowPorts: strictAllow } : null,
+  };
+}