madarx 2.24.0 → 2.24.1

package/lib/sandbox/index.js

@@ -25,12 +25,24 @@
 //   4. (R4) A real, EXPLICITLY OPT-IN docker execution helper:
 //      `executeSandboxedSpawn` actually spawns `docker run` — but only when
 //      `MADARX_SANDBOX_LIVE_DOCKER` is enabled. Otherwise it refuses clearly and
-//      returns the inspectable plan without spawning. SSH/local backends remain
-//      deferred stubs that refuse rather than run unconfined.
+//      returns the inspectable plan without spawning.
+//   5. (R4) A production-safe, EXPLICITLY OPT-IN SSH execution backend. The plan
+//      builder `buildSshExecSpec` is pure + deterministic: it produces an `ssh`
+//      argv plus a hardened remote shell command (host absolute CLI paths
+//      normalized to a basename, only sanitized env exported on the remote, PATH
+//      dropped so the remote's own PATH applies). A real SSH command is only ever
+//      produced/run when ALL of these hold: `MADARX_SANDBOX_LIVE_SSH` is on AND a
+//      host + user are configured. Missing any of these → a deferred refusal stub
+//      (no unconfined host fallback). The `local` backend is intentionally never
+//      wired — it cannot confine on the host — and stays a refusal stub.
+//   6. (R4) Richer artifact/sync-back metadata via `describeArtifactSync`:
+//      deterministic, backend-aware description of how files written by a run are
+//      recovered (docker bind-mount cache vs. operator-driven scp from the remote
+//      SSH workdir).
 //
 // Spec building stays pure + deterministic so it can be unit-tested without ever
-// invoking docker; `executeSandboxedSpawn` lazy-imports node:child_process and
-// only runs behind the live flag.
+// invoking docker or ssh; `executeSandboxedSpawn` lazy-imports
+// node:child_process and only runs behind the matching live flag.
 
 import path from 'node:path';
 
@@ -41,6 +53,12 @@ export const SANDBOX_BACKENDS = ['docker', 'ssh', 'local'];
 const DEFAULT_IMAGE = 'madarx/sandbox:latest';
 const DEFAULT_WORKDIR = '/sandbox';
 
+// R4 SSH backend defaults. The remote workdir is a dedicated scratch dir, not a
+// home/system path; artifacts land in a fixed subdir under it for sync-back.
+const DEFAULT_SSH_PORT = 22;
+const DEFAULT_SSH_WORKDIR = '/tmp/madarx-sandbox';
+export const SSH_ARTIFACT_SUBDIR = 'artifacts';
+
 // Container-side mount targets. The artifact dir is the agent's only writable
 // host-backed path; the auth dir (if any) is read-only.
 export const ARTIFACT_CONTAINER_DIR = '/sandbox/artifacts';
@@ -71,6 +89,19 @@ function containerCommandName(command) {
   return parts.length ? parts[parts.length - 1] : value;
 }
 
+// POSIX single-quote a string for safe embedding in a remote shell command:
+// wrap in single quotes and escape any embedded single quote as '\''. Prevents
+// argument/command injection through the SSH remote command string.
+/** @param {unknown} s */
+function shellQuote(s) {
+  return `'${String(s ?? '').replace(/'/g, `'\\''`)}'`;
+}
+
+// Only well-formed shell identifier names may be exported via `env NAME=val` on
+// the remote — a defensive guard so a hostile/odd env key can't smuggle shell
+// syntax into the remote command.
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
 // Keys whose NAME signals a credential. Matches the canonical S2 set
 // (KEY / TOKEN / SECRET / PASSWORD) plus the common spellings. Case-insensitive.
 const SECRET_KEY_RE = /(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL)/i;
@@ -93,7 +124,7 @@ function pick(value, allowed, fallback) {
  * env wins over built-in defaults. Unknown / junk values fall back to the safe
  * default (mode "off"), never throw.
  *
- * @param {{ mode?: string, scope?: string, backend?: string, image?: string, network?: string, workdir?: string, agentId?: string, liveDocker?: boolean|string, artifactDir?: string, authDir?: string }} [opts]
+ * @param {{ mode?: string, scope?: string, backend?: string, image?: string, network?: string, workdir?: string, agentId?: string, liveDocker?: boolean|string, artifactDir?: string, authDir?: string, liveSsh?: boolean|string, sshHost?: string, sshUser?: string, sshPort?: string|number, sshWorkdir?: string }} [opts]
  * @param {{ env?: Record<string, string|undefined> }} [ctx]
  */
 export function buildSandboxConfig(opts = {}, ctx = {}) {
@@ -114,7 +145,22 @@ export function buildSandboxConfig(opts = {}, ctx = {}) {
   // (ro). Null when unset → no host FS mount at all (S2 default-deny preserved).
   const artifactDir = String(opts.artifactDir ?? env.MADARX_SANDBOX_ARTIFACT_DIR ?? '').trim() || null;
   const authDir = String(opts.authDir ?? env.MADARX_SANDBOX_AUTH_DIR ?? '').trim() || null;
-  return { mode, scope, backend, image, network, workdir, agentId: opts.agentId || null, liveDocker, artifactDir, authDir };
+  // R4 SSH backend: real SSH execution is a SEPARATE opt-in from confinement
+  // mode, gated by its OWN live flag. Even with backend "ssh" + host/user set,
+  // no SSH command is produced or run unless `liveSsh` is also on. Host/user
+  // null when unset → the backend stays a deferred refusal stub (never an
+  // unconfined host fallback).
+  const liveSsh = truthyFlag(opts.liveSsh ?? env.MADARX_SANDBOX_LIVE_SSH);
+  const sshHost = String(opts.sshHost ?? env.MADARX_SANDBOX_SSH_HOST ?? '').trim() || null;
+  const sshUser = String(opts.sshUser ?? env.MADARX_SANDBOX_SSH_USER ?? '').trim() || null;
+  const sshPortRaw = String(opts.sshPort ?? env.MADARX_SANDBOX_SSH_PORT ?? '').trim();
+  const sshPort = /^\d+$/.test(sshPortRaw) ? Number(sshPortRaw) : DEFAULT_SSH_PORT;
+  const sshWorkdir = String(opts.sshWorkdir ?? env.MADARX_SANDBOX_SSH_WORKDIR ?? '').trim() || DEFAULT_SSH_WORKDIR;
+  return {
+    mode, scope, backend, image, network, workdir, agentId: opts.agentId || null,
+    liveDocker, artifactDir, authDir,
+    liveSsh, sshHost, sshUser, sshPort, sshWorkdir,
+  };
 }
 
 /**
@@ -266,6 +312,140 @@ export function buildDockerExecSpec({ config, command, args = [], env = {}, name
   return { command: 'docker', args: dockerArgs, image: cfg.image, containerEnv, dropped, rejected, mounts };
 }
 
+/**
+ * Whether a config has the minimum SSH connection details (host + user).
+ * @param {ReturnType<typeof buildSandboxConfig>|null|undefined} cfg
+ */
+export function sshConfigPresent(cfg) {
+  return Boolean(cfg && cfg.sshHost && cfg.sshUser);
+}
+
+/**
+ * Build the hardened REMOTE shell command run over SSH. It:
+ *   - `cd`s into the dedicated remote workdir (created defensively with mkdir -p),
+ *   - exports ONLY the sanitized env (secret-bearing + LD_/DYLD_ already stripped;
+ *     PATH dropped so the remote's own PATH is used),
+ *   - execs the command by BASENAME (a host absolute CLI path never reaches the
+ *     remote), with every token POSIX-quoted.
+ * Pure + deterministic.
+ *
+ * @param {{ workdir: string, env: Record<string,string>, command: string, args: string[] }} p
+ */
+function buildRemoteShellCommand({ workdir, env, command, args }) {
+  const artifactDir = `${String(workdir).replace(/\/+$/, '')}/${SSH_ARTIFACT_SUBDIR}`;
+  const parts = [];
+  parts.push('mkdir', '-p', shellQuote(workdir), shellQuote(artifactDir), '&&');
+  parts.push('cd', shellQuote(workdir), '&&');
+  parts.push('exec', 'env');
+  for (const [k, v] of Object.entries(env)) {
+    if (!ENV_NAME_RE.test(k)) continue; // skip non-identifier keys defensively
+    parts.push(`${k}=${shellQuote(v)}`);
+  }
+  parts.push(shellQuote(command), ...args.map(shellQuote));
+  return parts.join(' ');
+}
+
+/**
+ * Build a deterministic `ssh` exec spec that runs `command args` on a remote host
+ * with the same env-hygiene + no-host-path guarantees as the docker backend. The
+ * connection is non-interactive (`BatchMode=yes` → key-based only, never prompts
+ * for a password), with host-key TOFU (`accept-new`) and a bounded connect
+ * timeout. Pure — does NOT spawn ssh (that is `executeSandboxedSpawn`).
+ *
+ * Requires host + user in the config; throws (fail-loud) otherwise. The live
+ * flag is NOT consulted here — gating lives in `buildSandboxedSpawnPlan` /
+ * `executeSandboxedSpawn` so this builder stays purely deterministic + testable.
+ *
+ * @param {{ config?: ReturnType<typeof buildSandboxConfig>, command?: string, args?: string[], env?: Record<string,string|undefined> }} [params]
+ * @returns {{ command: 'ssh', args: string[], target: string, remoteCommand: string, remoteEnv: Record<string,string>, dropped: string[], rejected: string[], workdir: string }}
+ */
+export function buildSshExecSpec({ config, command, args = [], env = {} } = {}) {
+  if (!command) throw new Error('buildSshExecSpec: command is required');
+  const cfg = config || buildSandboxConfig();
+  if (!cfg.sshHost || !cfg.sshUser) {
+    throw new Error('buildSshExecSpec: SSH host and user are required (set MADARX_SANDBOX_SSH_HOST / MADARX_SANDBOX_SSH_USER)');
+  }
+  // dropPath: the remote uses its own PATH; we never forward the host PATH or any
+  // secret-bearing / linker-override var.
+  const { env: remoteEnv, dropped, rejected } = sanitizeChildEnv(env, { dropPath: true });
+  const workdir = cfg.sshWorkdir || DEFAULT_SSH_WORKDIR;
+  const remoteCommand = buildRemoteShellCommand({
+    workdir,
+    env: remoteEnv,
+    command: containerCommandName(command), // basename only — no host absolute path
+    args,
+  });
+  const target = `${cfg.sshUser}@${cfg.sshHost}`;
+  const sshArgs = [
+    '-p', String(cfg.sshPort || DEFAULT_SSH_PORT),
+    '-o', 'BatchMode=yes',
+    '-o', 'StrictHostKeyChecking=accept-new',
+    '-o', 'ConnectTimeout=10',
+    target,
+    remoteCommand,
+  ];
+  return { command: 'ssh', args: sshArgs, target, remoteCommand, remoteEnv, dropped, rejected, workdir };
+}
+
+/**
+ * Deterministic, backend-aware description of how files written during a run are
+ * recovered after teardown. Pure — used both for the live-exec result payload and
+ * for operator inspection of a dry plan.
+ *
+ *  - docker + artifactDir → a rw bind-mount cache that survives teardown (auto).
+ *  - docker, no artifactDir → ephemeral container FS (nothing recoverable).
+ *  - ssh → files stay in the remote workdir; sync-back is an operator-driven scp
+ *    (NOT auto-run in this slice — we surface the exact command instead).
+ *
+ * @param {ReturnType<typeof buildSandboxConfig>} cfg
+ * @param {string} [backend]
+ */
+export function describeArtifactSync(cfg, backend) {
+  const b = backend || cfg?.backend || 'docker';
+  if (b === 'docker') {
+    if (cfg?.artifactDir) {
+      return {
+        backend: 'docker',
+        mechanism: 'bind-mount',
+        hostDir: cfg.artifactDir,
+        containerDir: ARTIFACT_CONTAINER_DIR,
+        mode: 'rw',
+        recoverable: true,
+        authDir: cfg.authDir || null,
+        authContainerDir: cfg.authDir ? AUTH_CONTAINER_DIR : null,
+        note: 'Files written to /sandbox/artifacts persist on the host cache after container teardown (automatic).',
+      };
+    }
+    return {
+      backend: 'docker',
+      mechanism: 'none',
+      recoverable: false,
+      note: 'No MADARX_SANDBOX_ARTIFACT_DIR configured; the container filesystem is ephemeral and nothing is synced back.',
+    };
+  }
+  if (b === 'ssh') {
+    const workdir = cfg?.sshWorkdir || DEFAULT_SSH_WORKDIR;
+    const remoteArtifactDir = `${String(workdir).replace(/\/+$/, '')}/${SSH_ARTIFACT_SUBDIR}`;
+    const target = sshConfigPresent(cfg) ? `${cfg.sshUser}@${cfg.sshHost}` : null;
+    return {
+      backend: 'ssh',
+      mechanism: 'ssh-remote',
+      remoteWorkdir: workdir,
+      remoteArtifactDir,
+      target,
+      port: cfg?.sshPort || DEFAULT_SSH_PORT,
+      recoverable: false,
+      // The exact scp the operator runs to pull artifacts back to a local cache.
+      // Not auto-executed: remote sync-back policy stays an explicit operator step.
+      syncCommand: target
+        ? ['scp', '-P', String(cfg.sshPort || DEFAULT_SSH_PORT), '-r', `${target}:${remoteArtifactDir}/.`, '<local-cache-dir>']
+        : null,
+      note: 'Artifacts remain in the remote workdir; sync-back via scp/rsync is operator-driven (not auto-run in this slice).',
+    };
+  }
+  return { backend: b, mechanism: 'unknown', recoverable: false };
+}
+
 /**
  * The integration seam used by the engine runners. Decides — based on config +
  * whether this is the main agent — whether to confine, and returns a concrete
@@ -273,8 +453,15 @@ export function buildDockerExecSpec({ config, command, args = [], env = {}, name
  *
  *  - sandbox off / main-under-non-main → host pass-through (hardened env only).
  *  - docker backend                    → a `docker run` wrapper (confined).
- *  - ssh / local backends              → deferred stub (NOT silently run
- *                                        unconfined — the caller must decide).
+ *  - ssh backend, fully opted in        → an `ssh` remote-exec wrapper (confined
+ *                                         off-host). "Fully opted in" = live flag
+ *                                         ON + host + user set. This is the SINGLE
+ *                                         chokepoint both the engine runner and
+ *                                         `executeSandboxedSpawn` flow through, so
+ *                                         no real SSH is ever produced without the
+ *                                         explicit opt-in.
+ *  - ssh (not fully opted in) / local   → deferred stub (NOT silently run
+ *                                         unconfined — the caller must decide).
  *
  * @param {{ config?: ReturnType<typeof buildSandboxConfig>, isMain?: boolean, command?: string, args?: string[], env?: Record<string,string|undefined>, name?: string, mountCtx?: { home?: string, repoRoot?: string } }} [params]
  */
@@ -299,35 +486,113 @@ export function buildSandboxedSpawnPlan({ config, isMain = false, command, args
       spec,
     };
   }
-  // ssh / local — backend abstraction exists, execution still deferred. R4's
-  // first slice wires REAL docker execution; SSH/local remain honest stubs that
-  // refuse rather than run unconfined.
+  // SSH — only produce a real, spawnable plan when the operator has FULLY opted
+  // in: the dedicated live flag is on AND a host + user are configured. This
+  // gate lives here (not only in executeSandboxedSpawn) because the engine runner
+  // spawns this plan directly — so this is the one place that guarantees no real
+  // ssh command is built without explicit opt-in. Anything short of that falls
+  // through to the deferred refusal below (never an unconfined host fallback).
+  if (cfg.backend === 'ssh' && cfg.liveSsh && sshConfigPresent(cfg)) {
+    const spec = buildSshExecSpec({ config: cfg, command, args, env });
+    return {
+      sandboxed: true,
+      backend: 'ssh',
+      command: spec.command,
+      args: spec.args,
+      // The local ssh client runs on the host; harden its env. The remote child
+      // receives only `spec.remoteEnv` (baked into the remote command), never the
+      // host secrets/linker overrides.
+      env: hardenChildEnv(env),
+      remoteEnv: spec.remoteEnv,
+      target: spec.target,
+      remoteCommand: spec.remoteCommand,
+      spec,
+    };
+  }
+  // ssh (not fully opted in) / local — honest refusal stubs. R4 wires REAL docker
+  // and SSH execution; the `local` backend cannot confine on the host and is
+  // intentionally never wired, so it always refuses rather than run unconfined.
   return {
     sandboxed: false,
     deferred: true,
     backend: cfg.backend,
-    reason: `Sandbox backend "${cfg.backend}" is not yet implemented (Docker is the only wired backend; SSH/local remain deferred).`,
+    reason: deferredBackendReason(cfg),
     command,
     args: [...args],
     env: hardenChildEnv(env),
   };
 }
 
+/**
+ * Human-readable reason a backend is deferred. SSH explains exactly which opt-in
+ * piece is missing (live flag / host / user); `local` explains it is unconfinable
+ * by design. Always contains "Sandbox backend" so callers can match generically.
+ *
+ * @param {ReturnType<typeof buildSandboxConfig>} cfg
+ */
+function deferredBackendReason(cfg) {
+  if (cfg.backend === 'ssh') {
+    const missing = [];
+    if (!cfg.sshHost) missing.push('MADARX_SANDBOX_SSH_HOST');
+    if (!cfg.sshUser) missing.push('MADARX_SANDBOX_SSH_USER');
+    if (!cfg.liveSsh) missing.push('MADARX_SANDBOX_LIVE_SSH=1');
+    return `Sandbox backend "ssh" is not fully opted in (missing: ${missing.join(', ')}); refusing to run unconfined. Real SSH execution requires the live flag plus host + user config.`;
+  }
+  if (cfg.backend === 'local') {
+    return 'Sandbox backend "local" cannot confine execution on the host machine and is intentionally not wired; refusing to run unconfined (use the docker or ssh backend).';
+  }
+  return `Sandbox backend "${cfg.backend}" is not yet implemented (Docker and SSH are the wired backends).`;
+}
+
+/**
+ * Spawn a child via the (possibly injected) spawn function and resolve with its
+ * exit code + collected stdout/stderr. Pure plumbing — never decides whether a
+ * run is allowed (callers gate before reaching here). `shell: false` always.
+ *
+ * @param {Function} spawnFn
+ * @param {{ command: string, args: string[], env: Record<string,string> }} plan
+ */
+function collectChild(spawnFn, plan) {
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawnFn(plan.command, plan.args, { shell: false, env: plan.env });
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on?.('data', (/** @type {Buffer} */ d) => { stdout += d.toString(); });
+    child.stderr?.on?.('data', (/** @type {Buffer} */ d) => { stderr += d.toString(); });
+    child.on?.('error', reject);
+    child.on?.('close', (/** @type {number} */ code) => {
+      resolve({ code, stdout: stdout.trim(), stderr: stderr.trim() });
+    });
+  });
+}
+
 /**
  * R4 — the EXPLICITLY OPT-IN real execution helper. Resolves a spawn plan via
- * `buildSandboxedSpawnPlan`, then actually spawns `docker run` — but only when
- * `cfg.liveDocker` (MADARX_SANDBOX_LIVE_DOCKER) is enabled. Otherwise it refuses
- * clearly and returns the inspectable plan WITHOUT spawning anything.
+ * `buildSandboxedSpawnPlan`, then actually spawns the confined runner — but only
+ * behind the matching live flag:
+ *   - docker → spawns `docker run` only when `cfg.liveDocker`
+ *     (MADARX_SANDBOX_LIVE_DOCKER); otherwise refuses + returns the plan.
+ *   - ssh    → only reached when the plan is already a real ssh plan, which
+ *     `buildSandboxedSpawnPlan` produces ONLY when `cfg.liveSsh`
+ *     (MADARX_SANDBOX_LIVE_SSH) + host + user are all set. A re-check here is
+ *     belt-and-suspenders.
  *
  * Safety contract:
- *  - Never spawns unless the plan is a confined docker plan AND the live flag is on.
- *  - A deferred (ssh/local) backend throws — never runs unconfined on the host.
- *  - The artifact cache dir is created on the host before the run so files the
- *    container writes to `/sandbox/artifacts` are recoverable after teardown.
- *  - Only the hardened host env reaches the docker CLI; only sanitized env is in
- *    the container argv (built by `buildDockerExecSpec`).
+ *  - Never spawns unless the plan is a confined docker/ssh plan AND its live flag is on.
+ *  - A deferred (ssh-not-opted-in / local) backend throws — never runs unconfined.
+ *  - docker: the artifact cache dir is created on the host before the run so files
+ *    the container writes to `/sandbox/artifacts` survive teardown.
+ *  - Only the hardened host env reaches the docker/ssh CLI; only sanitized env is
+ *    in the inner command (built by `buildDockerExecSpec` / `buildSshExecSpec`).
+ *  - The result carries `syncBack` metadata describing artifact recovery.
  *
- * `spawnFn` / `ensureDir` are injectable for deterministic tests (no real docker).
+ * `spawnFn` / `ensureDir` are injectable for deterministic tests (no real docker/ssh).
  *
  * @param {{ config?: ReturnType<typeof buildSandboxConfig>, isMain?: boolean, command?: string, args?: string[], env?: Record<string,string|undefined>, name?: string, mountCtx?: { home?: string, repoRoot?: string } }} params
  * @param {{ spawnFn?: Function, ensureDir?: (dir: string) => Promise<void> }} [deps]
@@ -341,11 +606,43 @@ export async function executeSandboxedSpawn(params = {}, deps = {}) {
     /** @type {any} */ (e).code = 'sandbox_backend_unavailable';
     throw e;
   }
-  if (!plan.sandboxed || plan.backend !== 'docker') {
-    const e = new Error('executeSandboxedSpawn requires an active, confined docker sandbox plan (sandbox is off or not docker-backed)');
+  if (!plan.sandboxed || (plan.backend !== 'docker' && plan.backend !== 'ssh')) {
+    const e = new Error('executeSandboxedSpawn requires an active, confined docker or ssh sandbox plan (sandbox is off or not a confined backend)');
     /** @type {any} */ (e).code = 'sandbox_not_confined';
     throw e;
   }
+
+  // --- SSH backend ---------------------------------------------------------
+  if (plan.backend === 'ssh') {
+    if (!cfg.liveSsh) {
+      // Defensive: buildSandboxedSpawnPlan would not have produced a real ssh
+      // plan without liveSsh, so this is unreachable in practice — kept as a
+      // hard guarantee that no ssh spawn ever happens without the live flag.
+      return {
+        executed: false,
+        refused: true,
+        backend: 'ssh',
+        reason: 'live SSH execution is disabled; set MADARX_SANDBOX_LIVE_SSH=1 to opt in',
+        plan,
+        syncBack: describeArtifactSync(cfg, 'ssh'),
+      };
+    }
+    const spawnFn = deps.spawnFn || (await import('node:child_process')).spawn;
+    const spawnPlan = /** @type {{ command: string, args: string[], env: Record<string,string> }} */ (plan);
+    const { code, stdout, stderr } = await collectChild(spawnFn, spawnPlan);
+    return {
+      executed: true,
+      code,
+      stdout,
+      stderr,
+      backend: 'ssh',
+      target: plan.target,
+      syncBack: describeArtifactSync(cfg, 'ssh'),
+      plan,
+    };
+  }
+
+  // --- Docker backend ------------------------------------------------------
   if (!cfg.liveDocker) {
     // Off by default: build/inspect the plan but DO NOT spawn docker.
     return {
@@ -354,6 +651,7 @@ export async function executeSandboxedSpawn(params = {}, deps = {}) {
       backend: 'docker',
       reason: 'live docker execution is disabled; set MADARX_SANDBOX_LIVE_DOCKER=1 to opt in',
       plan,
+      syncBack: describeArtifactSync(cfg, 'docker'),
     };
   }
 
@@ -368,29 +666,16 @@ export async function executeSandboxedSpawn(params = {}, deps = {}) {
   }
 
   const spawnFn = deps.spawnFn || (await import('node:child_process')).spawn;
-  return await new Promise((resolve, reject) => {
-    let child;
-    try {
-      child = spawnFn(plan.command, plan.args, { shell: false, env: plan.env });
-    } catch (err) {
-      reject(err);
-      return;
-    }
-    let stdout = '';
-    let stderr = '';
-    child.stdout?.on?.('data', (/** @type {Buffer} */ d) => { stdout += d.toString(); });
-    child.stderr?.on?.('data', (/** @type {Buffer} */ d) => { stderr += d.toString(); });
-    child.on?.('error', reject);
-    child.on?.('close', (/** @type {number} */ code) => {
-      resolve({
-        executed: true,
-        code,
-        stdout: stdout.trim(),
-        stderr: stderr.trim(),
-        backend: 'docker',
-        artifactDir: cfg.artifactDir || null,
-        plan,
-      });
-    });
-  });
+  const spawnPlan = /** @type {{ command: string, args: string[], env: Record<string,string> }} */ (plan);
+  const { code, stdout, stderr } = await collectChild(spawnFn, spawnPlan);
+  return {
+    executed: true,
+    code,
+    stdout,
+    stderr,
+    backend: 'docker',
+    artifactDir: cfg.artifactDir || null,
+    syncBack: describeArtifactSync(cfg, 'docker'),
+    plan,
+  };
 }

package/lib/schema.js

@@ -556,6 +556,17 @@ CREATE TABLE IF NOT EXISTS whatsapp_allowlist (
   UNIQUE(chat_id)
 );
 
+CREATE TABLE IF NOT EXISTS channel_allowlist (
+  id TEXT PRIMARY KEY,
+  channel TEXT NOT NULL,
+  address TEXT NOT NULL,
+  kind TEXT NOT NULL DEFAULT 'dm',
+  label TEXT,
+  created_at TEXT NOT NULL,
+  UNIQUE(channel, address)
+);
+CREATE INDEX IF NOT EXISTS idx_channel_allowlist_channel ON channel_allowlist(channel);
+
 -- Per-chat conversation session boundary. session_started_at is the cutoff for
 -- history reconstruction: buildWhatsAppHistory only replays whatsapp_messages rows
 -- with created_at >= session_started_at. The /new command advances it to now,

package/lib/whatsapp-router.js

@@ -1,5 +1,11 @@
 import { getDb, nowIso, newId } from './db.js';
 import { appendAudit } from './runtime.js';
+import {
+  addChannelAllowlistEntry,
+  isChannelAllowed,
+  listChannelAllowlist,
+  removeChannelAllowlistEntry,
+} from './channel-allowlist.js';
 import { publishLiveEvent } from './live-events.js';
 import { runWhatsAppOrchestrator } from './whatsapp-agent.js';
 import { pollIncomingMessages, sendWhatsAppDocument, sendWhatsAppMessage, setTyping } from './whatsapp.js';
@@ -35,9 +41,7 @@ function startTypingIndicator(chatId, typingFn = setTyping) {
 const recentSenders = new Map();
 
 function listAllowlistChatIds() {
-  return new Set(
-    getDb().prepare('SELECT chat_id FROM whatsapp_allowlist').all().map(row => row.chat_id),
-  );
+  return new Set(listChannelAllowlist('whatsapp').map(row => row.address || row.chat_id));
 }
 
 function alreadySeen(messageId) {
@@ -407,23 +411,29 @@ export async function runRouterLoop({ intervalMs = 1500, signal } = {}) {
 }
 
 export function listInboundAllowlist() {
-  return getDb().prepare('SELECT id, chat_id, kind, label, created_at FROM whatsapp_allowlist ORDER BY created_at DESC').all();
+  return listChannelAllowlist('whatsapp').map(row => ({
+    id: row.id,
+    channel: 'whatsapp',
+    address: row.address || row.chat_id,
+    chat_id: row.address || row.chat_id,
+    kind: row.kind,
+    label: row.label,
+    created_at: row.created_at,
+  }));
 }
 
 export function addAllowlistEntry({ chat_id, kind = 'dm', label = null }) {
   if (!chat_id) throw new Error('chat_id is required');
-  const id = newId('waal');
-  getDb().prepare(`
-    INSERT INTO whatsapp_allowlist (id, chat_id, kind, label, created_at)
-    VALUES (?, ?, ?, ?, ?)
-    ON CONFLICT(chat_id) DO UPDATE SET kind = excluded.kind, label = excluded.label
-  `).run(id, String(chat_id), String(kind), label ? String(label) : null, nowIso());
-  return getDb().prepare('SELECT id, chat_id, kind, label, created_at FROM whatsapp_allowlist WHERE chat_id = ?').get(String(chat_id));
+  return addChannelAllowlistEntry({ channel: 'whatsapp', address: chat_id, kind, label });
 }
 
 export function removeAllowlistEntry(chatId) {
   if (!chatId) return 0;
-  return getDb().prepare('DELETE FROM whatsapp_allowlist WHERE chat_id = ?').run(String(chatId)).changes;
+  return removeChannelAllowlistEntry('whatsapp', chatId);
+}
+
+export function isInboundAllowed(channel, address) {
+  return isChannelAllowed(channel, address);
 }
 
 export function listInboundMessages(limit = 50) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "madarx",
-  "version": "2.24.0",
+  "version": "2.24.1",
   "type": "module",
   "description": "Madarx OS — Next.js product with SQLite-backed runtime, scheduled cron daemon, and approval-gated local runners.",
   "license": "MIT",
@@ -66,6 +66,7 @@
     "whatsapp:reset": "node --no-warnings --env-file-if-exists=.env.local scripts/whatsapp-reset.mjs",
     "smoke:routes": "node --no-warnings scripts/smoke-routes.mjs",
     "mcp:public-interop": "node --no-warnings --env-file-if-exists=.env.local scripts/mcp-public-interop.mjs",
+    "vreach:smoke": "node --no-warnings --env-file-if-exists=.env.local scripts/vreach-channel-smoke.mjs",
     "vecon:proof": "node --no-warnings --env-file-if-exists=.env.local scripts/vecon-prompt-cache-proof.mjs",
     "vendor:open-design": "node --no-warnings scripts/vendor-open-design.mjs",
     "check:disk-enc": "node --no-warnings scripts/check-disk-encryption.mjs",