@semalt-ai/code 1.8.5 → 1.20.0

package/lib/background.js

@@ -0,0 +1,584 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Background tasks — detached agent processes (Task 5.3)
+// ---------------------------------------------------------------------------
+//
+// Run an agent task as a DETACHED background process that survives the terminal
+// closing, plus a task registry to list / inspect / collect / terminate it.
+// Each background task is its OWN process (its own `process.cwd()`, its own
+// dynamic tool registry, its own everything) — which sidesteps the documented
+// in-process multi-instance global-state limitations of the embedding SDK
+// (Task 5.2): isolation comes for free from the process boundary.
+//
+// LIFECYCLE
+//   launchBackground()      (parent / terminal-attached)
+//     1. VALIDATE everything checkable SYNCHRONOUSLY, surfacing errors to the
+//        terminal — config validity, a resolvable model, permission-policy
+//        shape, sandbox availability. After detach there is no terminal to
+//        reach, so a misconfiguration must fail HERE, before any process forks.
+//     2. Write the launch spec + an initial registry record under the task dir.
+//     3. spawnDetached() the child (`semalt-code __bg-exec <taskDir>`), record
+//        its PID, and `unref()` so the parent can exit.
+//   runBackgroundChild()    (detached)
+//     Reads the spec, builds an agent via the STABLE SDK facade (createAgent)
+//     with the LAUNCH-FIXED permission policy, runs the prompt to completion,
+//     and writes progress/result/status to the task dir. After detach: pure
+//     execution — no path back to the terminal.
+//
+// SECURITY (the 5.2 embedded perimeter, applied to the background context)
+//   * Permission posture is FIXED AT LAUNCH and refuse-by-default. A background
+//     task has no TTY, so its policy (preset allow/deny rules + coarse tiers, or
+//     the refuse-on-mutation default) is set when it starts and can NEVER fall
+//     through to an interactive prompt — createAgent installs a refuse approver
+//     when none is supplied (see lib/sdk.js).
+//   * The OS sandbox + destructive-command deny-list stay ON in the child unless
+//     an opt-out (`sandbox.mode: 'off'`, `dangerouslySkipPermissions`) is passed
+//     EXPLICITLY at launch. There is no human to ask, so an unavailable sandbox
+//     in `auto` mode REFUSES the command (createAgent's onUnsandboxed default).
+//   * Background-launch is NOT exposed as an agent tool — it is a CLI/SDK,
+//     human-initiated surface only. See TOOL-EXPOSURE DECISION at the bottom.
+//
+// IPC IS VIA FILES, not a live channel — the detached child writes NDJSON
+// progress + a result envelope to its task dir; the parent reads them on
+// `collect`. This survives the terminal closing and needs no live IPC.
+//
+// TASK STORE LAYOUT — ~/.semalt-ai/tasks/<id>/
+//   spec.json      launch spec the child reads (prompt, model, policy, sandbox,
+//                  cwd). NOT secrets — the API key is passed via the child's env
+//                  (SEMALT_API_KEY), never written to disk here.
+//   meta.json      the registry record / current status snapshot
+//                  { id, pid, status, started_at, finished_at, prompt_summary,
+//                    model, policy_summary, stopReason?, error? }
+//   events.ndjson  append-only progress log (one JSON object per line, like the
+//                  audit log): status / tool / warning / error / result events.
+//   result.json    the final headless envelope on completion
+//                  { result, toolCalls, usage, cost, stopReason, verifyStatus }
+//
+// Everything is injectable (fs / now / spawn / createAgent / detection) so the
+// whole module is deterministic and unit-testable offline.
+
+const fsReal = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const { normalizeSandbox, detectSandbox } = require('./sandbox');
+const { spawnDetached, killTreeByPid, isProcessAlive } = require('./proc');
+
+const DEFAULT_TASKS_DIR = path.join(os.homedir(), '.semalt-ai', 'tasks');
+
+// Lifecycle states. `stale` is NOT persisted — it is COMPUTED for a task marked
+// running/starting whose PID is no longer alive (the process died without
+// writing a terminal status, e.g. a SIGKILL or a crash). It surfaces in `tasks`
+// so zombies never accumulate invisibly and can be pruned.
+const TERMINAL_STATUSES = new Set(['completed', 'failed', 'terminated']);
+const ACTIVE_STATUSES = new Set(['starting', 'running']);
+
+const VALID_ACTIONS = new Set(['allow', 'deny', 'ask']);
+const MATCHER_KEYS = ['pattern', 'path', 'url', 'match'];
+
+function summarize(text, max = 80) {
+  const s = String(text == null ? '' : text).replace(/\s+/g, ' ').trim();
+  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+
+// --------------------------------------------------------------------------
+// Task store — registry CRUD over the on-disk layout above.
+// --------------------------------------------------------------------------
+function createTaskStore({ rootDir = DEFAULT_TASKS_DIR, fs = fsReal, now = () => Date.now() } = {}) {
+  function dir(id) { return path.join(rootDir, id); }
+  function paths(id) {
+    const d = dir(id);
+    return {
+      dir: d,
+      spec: path.join(d, 'spec.json'),
+      meta: path.join(d, 'meta.json'),
+      events: path.join(d, 'events.ndjson'),
+      result: path.join(d, 'result.json'),
+    };
+  }
+
+  // crypto.randomBytes is fine to call directly — this is a process, not a
+  // resumable workflow script.
+  function genId() { return crypto.randomBytes(5).toString('hex'); }
+
+  function readJson(p) {
+    try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+    catch { return null; }
+  }
+
+  // Atomic write: write a temp sibling then rename, so a concurrent reader never
+  // sees a half-written meta.json.
+  function writeJsonAtomic(p, obj) {
+    const tmp = `${p}.tmp-${process.pid}-${Math.floor(now())}`;
+    fs.writeFileSync(tmp, JSON.stringify(obj, null, 2));
+    fs.renameSync(tmp, p);
+  }
+
+  function create({ id, spec, prompt, model, policySummary }) {
+    const d = dir(id);
+    fs.mkdirSync(d, { recursive: true });
+    const p = paths(id);
+    fs.writeFileSync(p.spec, JSON.stringify(spec, null, 2));
+    const meta = {
+      id,
+      pid: null,
+      status: 'starting',
+      started_at: now(),
+      finished_at: null,
+      prompt_summary: summarize(prompt),
+      model: model || null,
+      policy_summary: policySummary || 'refuse-by-default',
+    };
+    writeJsonAtomic(p.meta, meta);
+    // Touch the events log so `tasks status` on a just-launched task doesn't error.
+    fs.writeFileSync(p.events, '');
+    return meta;
+  }
+
+  function readMeta(id) { return readJson(paths(id).meta); }
+  function readSpec(id) { return readJson(paths(id).spec); }
+  function readResult(id) { return readJson(paths(id).result); }
+
+  function patchMeta(id, patch) {
+    const cur = readMeta(id) || { id };
+    const next = { ...cur, ...patch };
+    writeJsonAtomic(paths(id).meta, next);
+    return next;
+  }
+
+  function appendEvent(id, event) {
+    const line = JSON.stringify({ ts: new Date(now()).toISOString(), ...event }) + '\n';
+    fs.appendFileSync(paths(id).events, line);
+  }
+
+  function readEvents(id) {
+    let raw;
+    try { raw = fs.readFileSync(paths(id).events, 'utf8'); }
+    catch { return []; }
+    const out = [];
+    for (const line of raw.split('\n')) {
+      const t = line.trim();
+      if (!t) continue;
+      try { out.push(JSON.parse(t)); } catch { /* skip corrupt line */ }
+    }
+    return out;
+  }
+
+  function writeResult(id, envelope) {
+    writeJsonAtomic(paths(id).result, envelope);
+  }
+
+  function list() {
+    let ids;
+    try { ids = fs.readdirSync(rootDir); }
+    catch { return []; }
+    const metas = [];
+    for (const id of ids) {
+      const meta = readMeta(id);
+      if (meta) metas.push(meta);
+    }
+    // Newest first.
+    return metas.sort((a, b) => (b.started_at || 0) - (a.started_at || 0));
+  }
+
+  function remove(id) {
+    try { fs.rmSync(dir(id), { recursive: true, force: true }); return true; }
+    catch { return false; }
+  }
+
+  return {
+    rootDir, dir, paths, genId,
+    create, readMeta, readSpec, readResult, patchMeta,
+    appendEvent, readEvents, writeResult,
+    list, remove,
+  };
+}
+
+// --------------------------------------------------------------------------
+// Status reconciliation — surface dead "running" tasks as stale.
+// --------------------------------------------------------------------------
+
+// The effective status for display: a task marked active whose PID is no longer
+// alive is reported as 'stale' (it died without writing a terminal status).
+function effectiveStatus(meta, alive = isProcessAlive) {
+  if (!meta) return 'unknown';
+  if (ACTIVE_STATUSES.has(meta.status) && !alive(meta.pid)) return 'stale';
+  return meta.status;
+}
+
+function isStale(meta, alive = isProcessAlive) {
+  return effectiveStatus(meta, alive) === 'stale';
+}
+
+// Which tasks are safe to prune: terminal (completed/failed/terminated) or stale
+// (dead but never finalized). Genuinely-running tasks are kept.
+function prunableIds(metas, alive = isProcessAlive) {
+  const out = [];
+  for (const m of metas) {
+    const eff = effectiveStatus(m, alive);
+    if (TERMINAL_STATUSES.has(eff) || eff === 'stale') out.push(m.id);
+  }
+  return out;
+}
+
+// Mark a stale task's meta as terminated so a later read is honest even without
+// a prune (idempotent: only rewrites genuinely-stale active tasks).
+function reconcile(store, { alive = isProcessAlive, now = () => Date.now() } = {}) {
+  const changed = [];
+  for (const m of store.list()) {
+    if (isStale(m, alive)) {
+      store.patchMeta(m.id, { status: 'terminated', finished_at: m.finished_at || now(), error: m.error || 'process died without reporting (stale)' });
+      changed.push(m.id);
+    }
+  }
+  return changed;
+}
+
+// --------------------------------------------------------------------------
+// Launch-time validation (constraint 4) — runs in the parent, before detach.
+// --------------------------------------------------------------------------
+
+function validatePolicy(policy) {
+  const errors = [];
+  if (!policy || typeof policy !== 'object') return errors;
+  const rules = policy.rules;
+  if (rules != null) {
+    if (!Array.isArray(rules)) { errors.push('policy.rules must be an array'); return errors; }
+    rules.forEach((r, i) => {
+      if (!r || typeof r !== 'object') { errors.push(`policy.rules[${i}] is not an object`); return; }
+      if (!r.tool || typeof r.tool !== 'string') errors.push(`policy.rules[${i}] missing a string "tool"`);
+      if (!VALID_ACTIONS.has(r.action)) errors.push(`policy.rules[${i}] action must be one of allow|deny|ask`);
+      const present = MATCHER_KEYS.filter((k) => r[k] != null);
+      if (present.length > 1) errors.push(`policy.rules[${i}] has more than one matcher key (${present.join(', ')})`);
+    });
+  }
+  if (policy.allow != null && !Array.isArray(policy.allow)) errors.push('policy.allow must be an array of tiers');
+  return errors;
+}
+
+// Validate everything checkable BEFORE detaching. Synchronous as far as the JS
+// goes except the optional model probe; the launcher awaits it before forking.
+// Returns an array of human-readable error strings ([] = OK).
+async function validateLaunch({
+  prompt,
+  config = {},
+  policy = {},
+  sandboxConfig,
+  model,
+  detection,
+  probeModel,
+} = {}) {
+  const errors = [];
+
+  if (!prompt || !String(prompt).trim()) errors.push('prompt is empty');
+
+  if (!config.api_base) errors.push('no api_base configured (run `semalt-code init` or pass --api-base)');
+
+  const resolvedModel = model || config.default_model;
+  if (!resolvedModel) errors.push('no model configured (pass -m <model> or set a default_model)');
+
+  errors.push(...validatePolicy(policy));
+
+  // Sandbox availability. Only a HARD requirement when the launch asks for it
+  // (failIfUnavailable) — otherwise an unavailable sandbox refuses commands at
+  // runtime (fail-safe), which is not a launch error.
+  const sb = normalizeSandbox(sandboxConfig);
+  if (sb.mode !== 'off' && sb.failIfUnavailable) {
+    const det = detection || detectSandbox();
+    if (!det.available) {
+      errors.push(`sandbox unavailable and failIfUnavailable is set: ${det.reason || 'no OS sandbox primitive'}`);
+    }
+  }
+
+  // Optional model-reachability probe (injected; default skipped to stay
+  // offline-deterministic). A background task that can't reach its model would
+  // fail silently after detach, so the caller can wire a light probe here.
+  if (typeof probeModel === 'function') {
+    let ok = false;
+    try { ok = await probeModel(resolvedModel); }
+    catch (e) { errors.push(`model endpoint unreachable: ${e && e.message ? e.message : e}`); ok = true; /* already recorded */ }
+    if (ok === false) errors.push('model endpoint did not respond');
+  }
+
+  return errors;
+}
+
+// Build the launch-fixed policy object from coarse flags + rules. Pure.
+function buildPolicy({ allowedTiers = [], readonly = false, rules = [], dangerouslySkipPermissions = false } = {}) {
+  return {
+    allow: Array.isArray(allowedTiers) ? allowedTiers.slice() : [],
+    readonly: !!readonly,
+    rules: Array.isArray(rules) ? rules.slice() : [],
+    dangerouslySkipPermissions: !!dangerouslySkipPermissions,
+  };
+}
+
+function policySummary(policy) {
+  if (policy.dangerouslySkipPermissions) return 'DANGER: skip-permissions';
+  const parts = [];
+  if (policy.allow && policy.allow.length) parts.push('allow:' + policy.allow.join('+'));
+  if (policy.readonly) parts.push('readonly');
+  if (policy.rules && policy.rules.length) parts.push(`${policy.rules.length} rule(s)`);
+  return parts.length ? parts.join(', ') : 'refuse-by-default';
+}
+
+// --------------------------------------------------------------------------
+// Launcher (parent) — validate, persist, detach.
+// --------------------------------------------------------------------------
+async function launchBackground({
+  prompt,
+  config = {},
+  policy = {},
+  sandboxConfig,
+  model,
+  cwd = process.cwd(),
+  maxIterations,
+  store,
+  // Injectables for tests / wiring.
+  spawn = require('child_process').spawn,
+  execPath = process.execPath,
+  indexJs = path.resolve(__dirname, '..', 'index.js'),
+  resolveKey,
+  env = process.env,
+  detection,
+  probeModel,
+  now = () => Date.now(),
+} = {}) {
+  const resolvedModel = model || config.default_model;
+  const effectiveSandboxConfig = sandboxConfig != null ? sandboxConfig : config.sandbox;
+
+  // 1. VALIDATE before any side effect (constraint 4).
+  const errors = await validateLaunch({ prompt, config, policy, sandboxConfig: effectiveSandboxConfig, model: resolvedModel, detection, probeModel });
+  if (errors.length) {
+    const err = new Error('Cannot launch background task:\n  - ' + errors.join('\n  - '));
+    err.validationErrors = errors;
+    throw err;
+  }
+
+  const taskStore = store || createTaskStore({ now });
+  const id = taskStore.genId();
+  const sandbox = normalizeSandbox(effectiveSandboxConfig);
+
+  // The spec the child reads. NO secrets on disk — the API key goes via env.
+  const spec = {
+    version: 1,
+    prompt: String(prompt),
+    apiBase: config.api_base,
+    model: resolvedModel,
+    contextLength: config.context_length || null,
+    maxIterations: maxIterations != null ? maxIterations : config.max_iterations,
+    cwd,
+    policy: buildPolicy(policy),
+    sandbox,
+  };
+  taskStore.create({ id, spec, prompt, model: resolvedModel, policySummary: policySummary(spec.policy) });
+
+  // 2. DETACH. Pass --dangerously-skip-permissions through to the child's argv
+  // so lib/tools.js (which reads argv at module load) honors the launch-fixed
+  // opt-out for the deny-list / secret-read / config-write guards — those are
+  // NOT reachable through createAgent options.
+  const childArgs = [indexJs, '__bg-exec', taskStore.dir(id)];
+  if (spec.policy.dangerouslySkipPermissions) childArgs.push('--dangerously-skip-permissions');
+
+  // Carry the resolved API key via env so it is never persisted to the task dir.
+  const childEnv = { ...env };
+  if (typeof resolveKey === 'function') {
+    try { const k = resolveKey(config); if (k) childEnv.SEMALT_API_KEY = k; } catch { /* fall through */ }
+  }
+
+  const child = spawnDetached(spawn, execPath, childArgs, { cwd, env: childEnv });
+  taskStore.patchMeta(id, { pid: child.pid != null ? child.pid : null, status: 'running' });
+  if (typeof child.unref === 'function') child.unref();
+
+  return { id, pid: child.pid, dir: taskStore.dir(id) };
+}
+
+// --------------------------------------------------------------------------
+// Child runner (detached) — read spec, run agent, write result/status.
+// --------------------------------------------------------------------------
+async function runBackgroundChild({
+  taskDir,
+  store,
+  createAgent = require('./sdk').createAgent,
+  now = () => Date.now(),
+} = {}) {
+  const id = path.basename(taskDir);
+  const taskStore = store || createTaskStore({ rootDir: path.dirname(taskDir), now });
+  const spec = taskStore.readSpec(id);
+  if (!spec) {
+    taskStore.patchMeta(id, { status: 'failed', finished_at: now(), error: 'spec.json missing or unreadable' });
+    return { status: 'failed' };
+  }
+
+  taskStore.appendEvent(id, { type: 'status', status: 'running' });
+
+  const policy = spec.policy || {};
+  const agent = createAgent({
+    apiBase: spec.apiBase,
+    model: spec.model,
+    contextLength: spec.contextLength,
+    cwd: spec.cwd,
+    // LAUNCH-FIXED permission posture. NO `approve` is ever wired (no TTY); with
+    // no rules/tiers createAgent refuses every mutation — the safe default.
+    rules: policy.rules || [],
+    allow: policy.allow || [],
+    readonly: !!policy.readonly,
+    dangerouslySkipPermissions: !!policy.dangerouslySkipPermissions,
+    // Sandbox + deny-list stay on unless the launch opted out (sandbox.mode off).
+    sandbox: spec.sandbox,
+    maxIterations: spec.maxIterations,
+  });
+
+  // Stream advisory progress to the events log (bounded — tool/warning/error,
+  // never raw tokens, so the file stays small).
+  agent.on('tool', (e) => {
+    try {
+      const ok = !(e && e.meta && e.meta.error);
+      const ev = { type: 'tool', tag: e && e.tag, ms: e && e.ms, ok };
+      // On a failed/blocked tool, record a short excerpt (e.g. a deny-list
+      // refusal) so `tasks status` is honest about what the agent couldn't do.
+      if (!ok && e && e.result) ev.detail = String(e.result).slice(0, 200);
+      taskStore.appendEvent(id, ev);
+    } catch { /* best-effort */ }
+  });
+  agent.on('warning', (m) => {
+    try { taskStore.appendEvent(id, { type: 'warning', message: typeof m === 'string' ? m : (m && m.message) }); } catch { /* best-effort */ }
+  });
+  agent.on('error', (e) => {
+    if (e && e.isWarning) return;
+    try { taskStore.appendEvent(id, { type: 'warning', message: e && e.message }); } catch { /* best-effort */ }
+  });
+
+  try {
+    const res = await agent.run(spec.prompt);
+    const envelope = {
+      result: res.result,
+      toolCalls: res.toolCalls,
+      usage: res.usage,
+      cost: res.cost,
+      stopReason: res.stopReason,
+      verifyStatus: res.verifyStatus,
+    };
+    taskStore.writeResult(id, envelope);
+    taskStore.appendEvent(id, { type: 'result', stopReason: envelope.stopReason, verifyStatus: envelope.verifyStatus });
+    taskStore.patchMeta(id, { status: 'completed', finished_at: now(), stopReason: envelope.stopReason, verifyStatus: envelope.verifyStatus });
+    return { status: 'completed', envelope };
+  } catch (err) {
+    const message = err && err.message ? err.message : String(err);
+    taskStore.appendEvent(id, { type: 'error', message });
+    taskStore.patchMeta(id, { status: 'failed', finished_at: now(), error: message });
+    return { status: 'failed', error: message };
+  } finally {
+    try { await agent.close(); } catch { /* best-effort */ }
+  }
+}
+
+// --------------------------------------------------------------------------
+// Kill (terminate) — tree-kill the recorded PID + mark terminated.
+// --------------------------------------------------------------------------
+async function killTask(store, id, {
+  alive = isProcessAlive,
+  kill = killTreeByPid,
+  delay = (ms) => new Promise((r) => setTimeout(r, ms)),
+  graceMs = 2000,
+  now = () => Date.now(),
+} = {}) {
+  const meta = store.readMeta(id);
+  if (!meta) return { ok: false, reason: 'no such task' };
+  if (TERMINAL_STATUSES.has(meta.status)) return { ok: false, reason: `already ${meta.status}` };
+  if (!meta.pid || !alive(meta.pid)) {
+    // Already dead — just finalize the record (no orphan to kill).
+    store.patchMeta(id, { status: 'terminated', finished_at: now(), error: meta.error || 'process was not running' });
+    return { ok: true, reason: 'process was not running; marked terminated' };
+  }
+  kill(meta.pid, 'SIGTERM');
+  await delay(graceMs);
+  if (alive(meta.pid)) kill(meta.pid, 'SIGKILL');
+  store.patchMeta(id, { status: 'terminated', finished_at: now() });
+  return { ok: true, reason: 'terminated' };
+}
+
+// --------------------------------------------------------------------------
+// Formatters (pure) — for the `tasks` CLI surface.
+// --------------------------------------------------------------------------
+function formatTaskList(metas, { alive = isProcessAlive } = {}) {
+  if (!metas || !metas.length) return 'No background tasks.';
+  const lines = ['Background tasks:'];
+  for (const m of metas) {
+    const eff = effectiveStatus(m, alive);
+    const when = m.started_at ? new Date(m.started_at).toISOString() : '?';
+    lines.push(`  ${m.id}  [${eff}]  ${when}  ${m.model || '?'}  ${m.prompt_summary || ''}`);
+  }
+  const stale = metas.filter((m) => isStale(m, alive)).length;
+  if (stale) lines.push(`\n  ${stale} stale task(s) — run \`semalt-code tasks prune\` to clean up.`);
+  return lines.join('\n');
+}
+
+function formatTaskStatus(meta, events, { alive = isProcessAlive } = {}) {
+  if (!meta) return 'No such task.';
+  const eff = effectiveStatus(meta, alive);
+  const lines = [
+    `Task ${meta.id}`,
+    `  status:   ${eff}${eff !== meta.status ? ` (recorded: ${meta.status})` : ''}`,
+    `  pid:      ${meta.pid == null ? '?' : meta.pid}`,
+    `  model:    ${meta.model || '?'}`,
+    `  policy:   ${meta.policy_summary || '?'}`,
+    `  started:  ${meta.started_at ? new Date(meta.started_at).toISOString() : '?'}`,
+    `  finished: ${meta.finished_at ? new Date(meta.finished_at).toISOString() : '—'}`,
+    `  prompt:   ${meta.prompt_summary || ''}`,
+  ];
+  if (meta.stopReason) lines.push(`  stopReason: ${meta.stopReason}`);
+  if (meta.error) lines.push(`  error:    ${meta.error}`);
+  const recent = (events || []).slice(-8);
+  if (recent.length) {
+    lines.push('  recent events:');
+    for (const e of recent) lines.push(`    ${e.ts || ''} ${e.type}${e.tag ? ' ' + e.tag : ''}${e.message ? ' ' + e.message : ''}`);
+  }
+  return lines.join('\n');
+}
+
+module.exports = {
+  DEFAULT_TASKS_DIR,
+  TERMINAL_STATUSES,
+  ACTIVE_STATUSES,
+  createTaskStore,
+  effectiveStatus,
+  isStale,
+  prunableIds,
+  reconcile,
+  validatePolicy,
+  validateLaunch,
+  buildPolicy,
+  policySummary,
+  launchBackground,
+  runBackgroundChild,
+  killTask,
+  formatTaskList,
+  formatTaskStatus,
+};
+
+// ---------------------------------------------------------------------------
+// TOOL-EXPOSURE DECISION (constraint 5) — documented, deliberate.
+// ---------------------------------------------------------------------------
+//
+// Background-launch is NOT exposed as an agent tool. There is no
+// `run_background` / `spawn_background` tag, no TOOL_SPECS entry, and nothing
+// registered into the (static OR dynamic) tool registry. It is reachable ONLY
+// from the human-initiated CLI/SDK surface (`semalt-code run --background`,
+// `launchBackground()`).
+//
+// WHY: a model-reachable background launcher is a privilege-escalation surface —
+// the agent could fork a fresh process to escape its own permission perimeter
+// (the very thing the subagent no-escalation rule, 4.5, forbids). Subagents
+// already give the model in-process parallelism while SHARING the parent
+// permission manager (no escalation possible). Background tasks exist for a
+// different need — a human-owned, terminal-surviving job — so keeping the
+// launcher off the tool surface removes the escalation question entirely rather
+// than trying to police it.
+//
+// If a future task DOES expose a background-launch tool, it MUST inherit (and be
+// unable to exceed) the launching agent's posture: pass the parent's resolved
+// policy as the child's launch-fixed policy and reject any widening, exactly as
+// subagents reuse the parent permissionManager.