botmux 2.111.0 → 2.112.0

package/dist/adapters/backend/sandbox.d.ts

@@ -9,10 +9,12 @@ export declare function mountOverlay(opts: {
     work: string;
     merged: string;
 }): boolean;
-/** True iff `path` is currently a mountpoint (host-side overlay still mounted). */
+/** True iff `path` is currently a mountpoint (host-side overlay still mounted).
+ *  Read mountinfo instead of stat'ing the path: a broken recursive FUSE mount can
+ *  leave any path-based `mountpoint` probe blocked in uninterruptible I/O. */
 export declare function isMounted(path: string): boolean;
-/** Unmount an overlay merged dir. Best-effort: lazy-umount (`-l`) if a normal
- *  umount fails (busy fd from a still-draining child). No-op if not a mount. */
+/** Unmount an overlay merged dir. Best-effort: lazy detach if a normal unmount
+ *  fails because a still-draining bwrap child holds the FUSE mount busy. */
 export declare function unmountOverlay(merged: string): void;
 export interface SandboxPlan {
     /** In-sandbox path the project is bound at — equals the original workingDir the
@@ -42,6 +44,16 @@ export interface SandboxPlan {
      *  (daemon-produced, e.g. skill plugin dirs) — bound AFTER the privacy masks so
      *  a broad hideDir can't break skill delivery. */
     readonlyRoots?: string[];
+    /** Daemon-generated private roots re-bound writable AFTER credential masks.
+     * Used for the current bot's isolated CLI home only; never accepts user
+     * config. */
+    trustedWritableRoots?: string[];
+    /** Crown-jewel masks emitted after trusted writable carve-outs. */
+    finalHideDirs?: string[];
+    finalHideFiles?: {
+        path: string;
+        empty: string;
+    }[];
     /** User-configured read-only inputs (per-bot sandboxReadonlyPaths). Bound BEFORE
      *  the privacy masks so hidePaths always win over them — an entry overlapping a
      *  masked path must never re-expose the real content. */
@@ -95,6 +107,19 @@ export declare function reexposeRunBinArgs(binPaths: (string | undefined)[]): st
  *  canonical targets so the mount point always exists and $HOME resolves even
  *  when the symlink's parent is masked inside the sandbox. */
 export declare function resolveSandboxMountPath(p: string): string;
+export interface SandboxOverlayPaths {
+    sessionRoot: string;
+    runtimeRoot: string;
+    projectMerged: string;
+    homeMerged: string;
+    legacyProjectMerged: string;
+    legacyHomeMerged: string;
+}
+/** Host-side overlay mountpoints must not live below HOME, because HOME is the
+ *  lower layer of the home overlay. The old layout did exactly that and allowed
+ *  fuse-overlayfs to recursively expose its own mountpoint. Keep the legacy
+ *  paths here only so upgrades can tear down pre-fix sessions safely. */
+export declare function sandboxOverlayPaths(dataDir: string, sessionId: string): SandboxOverlayPaths;
 /**
  * Resolve user-configured sandboxReadonlyPaths: tilde-expand, drop non-existent
  * entries, and REJECT entries that (after resolving symlinks + normalizing) are
@@ -144,6 +169,11 @@ export interface SandboxSpawn {
  *  canonicalized dataDir under a symlink home would escape home-upper via `..` —
  *  fall back to the canonical base so it can't. */
 export declare function sandboxedClaudeDataDir(sessionId: string, realDataDir: string): string;
+/** Credential roots that must never be readable inside the file sandbox.
+ * Relay mode is the only credentialed send path; otherwise an agent could
+ * unset BOTMUX_SEND_RELAY and execute an absolute botmux binary against the
+ * real bots.json/send-cred files exposed by the HOME overlay lowerdir. */
+export declare function sandboxCredentialHidePaths(home: string, botmuxHome?: string): string[];
 /**
  * Whether the LOCAL bwrap file sandbox applies to this spawn at all.
  * - macOS enforces `sandbox: true` via the Seatbelt write-sandbox instead.
@@ -159,9 +189,9 @@ export declare function localSandboxApplies(platform: NodeJS.Platform, backendTy
  * treats null as a hard error and does NOT silently run unsandboxed).
  *
  * Layout under <dataDir>/sandboxes/<sessionId>/: outbox, shimbin, proj-upper
- * (the landable changeset), proj-work, proj-merged, home-merged. The HOME
- * overlay's upper/work live under /var/tmp/botmux-sbx/<sessionId>/ because
- * overlayfs forbids upper/work inside the lower (= the real home).
+ * (the landable changeset), and proj-work. Host-only merged mountpoints plus the
+ * HOME overlay upper/work live under /var/tmp/botmux-sbx/<sessionId>/ so none of
+ * the FUSE mountpoints is nested below the HOME lower layer.
  */
 export declare function prepareSandbox(opts: {
     /** Whether the sandbox is on for THIS session (per-bot BotConfig.sandbox OR
@@ -187,6 +217,10 @@ export declare function prepareSandbox(opts: {
     /** Runtime-generated roots that should be visible read-only inside bwrap.
      *  Trusted (daemon-produced) — bound after the privacy masks. */
     readonlyRoots?: readonly string[];
+    /** Daemon-derived private roots to re-open writable after mandatory masks. */
+    trustedWritablePaths?: readonly string[];
+    /** Credential paths to re-mask after trusted writable carve-outs. */
+    finalHidePaths?: readonly string[];
     /** User-configured extra read-only inputs (per-bot sandboxReadonlyPaths).
      *  Bound before the privacy masks (masks win) and rejected when they would
      *  shadow the home/project overlay roots. */
@@ -243,6 +277,9 @@ export interface RelayRequest {
     videos?: unknown;
     videoCovers?: unknown;
     flags?: unknown;
+    originTurnId?: unknown;
+    originDispatchAttempt?: unknown;
+    originCapability?: unknown;
 }
 export interface ValidatedRelay {
     contentName: string;
@@ -252,6 +289,9 @@ export interface ValidatedRelay {
     videoNames: string[];
     videoCoverNames: string[];
     flags: string[];
+    originTurnId?: string;
+    originDispatchAttempt?: number;
+    originCapability?: string;
 }
 /**
  * PURE validation of an outbox relay request (schema + flag allowlist only — no
@@ -294,6 +334,21 @@ export declare function materializeOutboxFile(outbox: string, name: string, dest
  */
 export declare function buildRelayHostEnv(baseEnv: NodeJS.ProcessEnv, preparedContentFile?: string): NodeJS.ProcessEnv;
 export declare function startOutboxWatcher(outbox: string, baseEnv: NodeJS.ProcessEnv, sessionId: string, opts?: {
+    /** Host-side authorization for a relay's claimed origin capability. When
+     *  absent the relay still runs, but carries NO durable origin — a missing
+     *  hook must never let the sandbox promote its own origin fields. */
+    authorize?: (claim: {
+        capability?: string;
+    }) => {
+        ok: true;
+        origin: {
+            turnId?: string;
+            dispatchAttempt?: number;
+        };
+    } | {
+        ok: false;
+        error: string;
+    };
     cliPath?: string;
 }): () => void;
 //# sourceMappingURL=sandbox.d.ts.map

package/dist/adapters/backend/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/adapters/backend/sandbox.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/adapters/backend/sandbox.ts"],"names":[],"mappings":"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"}

package/dist/adapters/backend/sandbox.js

@@ -14,7 +14,10 @@
  * bwrap 0.8.0 has NO --overlay, so we mount the overlay ON THE HOST then bind the
  * merged dir into bwrap. overlayfs forbids upper/work INSIDE lower, so the HOME
  * overlay (lower=/root) puts upper/work OUTSIDE /root (under /var/tmp/...). The
- * PROJECT overlay upper/work under <dataDir>/sandboxes/<sessionId>/ is fine.
+ * merged mountpoints also live there: putting home-merged below HOME makes the
+ * rootless FUSE overlay recursively contain itself, and bwrap can block forever
+ * while resolving later bind destinations. Project upper/work stay under the
+ * data dir because they are the persistent, landable changeset.
  *
  * Linux-only (overlayfs + bwrap depend on Linux). macOS reuses Anthropic's
  * sandbox-exec approach and is handled elsewhere.
@@ -60,21 +63,41 @@ export function mountOverlay(opts) {
     const f = spawnSync('fuse-overlayfs', ['-o', optStr, opts.merged], { stdio: 'pipe' });
     return f.status === 0;
 }
-/** True iff `path` is currently a mountpoint (host-side overlay still mounted). */
+function decodeMountInfoPath(raw) {
+    return raw.replace(/\\([0-7]{3})/g, (_match, octal) => String.fromCharCode(Number.parseInt(octal, 8)));
+}
+/** True iff `path` is currently a mountpoint (host-side overlay still mounted).
+ *  Read mountinfo instead of stat'ing the path: a broken recursive FUSE mount can
+ *  leave any path-based `mountpoint` probe blocked in uninterruptible I/O. */
 export function isMounted(path) {
-    return spawnSync('mountpoint', ['-q', path], { stdio: 'ignore' }).status === 0;
+    const target = resolve(path);
+    try {
+        const mountInfo = readFileSync('/proc/self/mountinfo', 'utf8');
+        return mountInfo.split('\n').some(line => {
+            const fields = line.split(' ');
+            return fields.length > 4 && decodeMountInfoPath(fields[4]) === target;
+        });
+    }
+    catch {
+        return spawnSync('mountpoint', ['-q', target], {
+            stdio: 'ignore',
+            timeout: 2_000,
+        }).status === 0;
+    }
 }
-/** Unmount an overlay merged dir. Best-effort: lazy-umount (`-l`) if a normal
- *  umount fails (busy fd from a still-draining child). No-op if not a mount. */
+/** Unmount an overlay merged dir. Best-effort: lazy detach if a normal unmount
+ *  fails because a still-draining bwrap child holds the FUSE mount busy. */
 export function unmountOverlay(merged) {
     if (!isMounted(merged))
         return; // not a mountpoint
     // kernel overlay → `umount`; fuse-overlayfs → `fusermount -u` (a non-root
-    // daemon can't `umount` its own fuse mount); lazy `-l` as a last resort for a
-    // busy fd from a still-draining child.
+    // daemon can't `umount` its own fuse mount). `fusermount -uz` is the critical
+    // rootless busy-mount fallback; plain `umount -l` is usually not permitted.
+    if (spawnSync('fusermount', ['-u', merged], { stdio: 'ignore' }).status === 0)
+        return;
     if (spawnSync('umount', [merged], { stdio: 'ignore' }).status === 0)
         return;
-    if (spawnSync('fusermount', ['-u', merged], { stdio: 'ignore' }).status === 0)
+    if (spawnSync('fusermount', ['-uz', merged], { stdio: 'ignore' }).status === 0)
         return;
     spawnSync('umount', ['-l', merged], { stdio: 'ignore' });
 }
@@ -146,6 +169,16 @@ export function buildSandboxArgs(plan) {
         a.push('--tmpfs', dir);
     for (const f of plan.hideFiles)
         a.push('--ro-bind', f.empty, f.path);
+    // Re-open only daemon-derived private roots (for example this bot's own
+    // BOT_HOME) after their parent BOTMUX_HOME was blanked.
+    for (const root of plan.trustedWritableRoots ?? [])
+        a.push('--bind', root, root);
+    // A private root can itself contain a credential that the sandbox must not
+    // recover (notably send-cred.json). Re-deny those after the carve-out.
+    for (const dir of plan.finalHideDirs ?? [])
+        a.push('--tmpfs', dir);
+    for (const f of plan.finalHideFiles ?? [])
+        a.push('--ro-bind', f.empty, f.path);
     // Session-scoped TRUSTED runtime inputs, e.g. generated skill/plugin dirs —
     // after the masks so a broad hideDir can't blank skill delivery.
     for (const root of plan.readonlyRoots ?? [])
@@ -249,6 +282,37 @@ function canonicalize(p) {
 export function resolveSandboxMountPath(p) {
     return canonicalize(p);
 }
+/** Host-side overlay mountpoints must not live below HOME, because HOME is the
+ *  lower layer of the home overlay. The old layout did exactly that and allowed
+ *  fuse-overlayfs to recursively expose its own mountpoint. Keep the legacy
+ *  paths here only so upgrades can tear down pre-fix sessions safely. */
+export function sandboxOverlayPaths(dataDir, sessionId) {
+    const sessionRoot = join(resolveSandboxMountPath(dataDir), 'sandboxes', sessionId);
+    const runtimeRoot = join(VARTMP_ROOT, sessionId);
+    return {
+        sessionRoot,
+        runtimeRoot,
+        projectMerged: join(runtimeRoot, 'proj-merged'),
+        homeMerged: join(runtimeRoot, 'home-merged'),
+        legacyProjectMerged: join(sessionRoot, 'proj-merged'),
+        legacyHomeMerged: join(sessionRoot, 'home-merged'),
+    };
+}
+function overlayMountCandidates(paths) {
+    return [
+        paths.projectMerged,
+        paths.homeMerged,
+        paths.legacyProjectMerged,
+        paths.legacyHomeMerged,
+    ];
+}
+function unmountSandboxOverlays(paths) {
+    for (const merged of overlayMountCandidates(paths))
+        unmountOverlay(merged);
+}
+function hasMountedSandboxOverlay(paths) {
+    return overlayMountCandidates(paths).some(isMounted);
+}
 /**
  * Resolve user-configured sandboxReadonlyPaths: tilde-expand, drop non-existent
  * entries, and REJECT entries that (after resolving symlinks + normalizing) are
@@ -304,6 +368,22 @@ export function sandboxedClaudeDataDir(sessionId, realDataDir) {
     const rel = raw.startsWith('..') ? relative(resolveSandboxMountPath(homedir()), realDataDir) : raw;
     return join(VARTMP_ROOT, sessionId, 'home-upper', rel);
 }
+/** Credential roots that must never be readable inside the file sandbox.
+ * Relay mode is the only credentialed send path; otherwise an agent could
+ * unset BOTMUX_SEND_RELAY and execute an absolute botmux binary against the
+ * real bots.json/send-cred files exposed by the HOME overlay lowerdir. */
+export function sandboxCredentialHidePaths(home, botmuxHome = join(home, '.botmux')) {
+    // Mask the entire botmux state root. Exact-file masks are insufficient:
+    // setup/update creates timestamped bots.json backups, including ones created
+    // after a long-lived sandbox starts. Trusted skill roots and the per-session
+    // outbox are explicitly re-bound after privacy masks by buildSandboxArgs.
+    return [...new Set([
+            join(home, '.botmux'),
+            botmuxHome,
+            join(home, '.lark-cli'),
+            join(home, '.lark-cli-bots'),
+        ])].sort();
+}
 /** Proxy env vars forwarded into the sandbox so the CLI reaches the API even on
  *  the tmux backend (which otherwise only forwards a fixed whitelist). */
 const PROXY_ENV_KEYS = ['http_proxy', 'https_proxy', 'HTTP_PROXY', 'HTTPS_PROXY', 'no_proxy', 'NO_PROXY', 'all_proxy', 'ALL_PROXY'];
@@ -324,9 +404,9 @@ export function localSandboxApplies(platform, backendType) {
  * treats null as a hard error and does NOT silently run unsandboxed).
  *
  * Layout under <dataDir>/sandboxes/<sessionId>/: outbox, shimbin, proj-upper
- * (the landable changeset), proj-work, proj-merged, home-merged. The HOME
- * overlay's upper/work live under /var/tmp/botmux-sbx/<sessionId>/ because
- * overlayfs forbids upper/work inside the lower (= the real home).
+ * (the landable changeset), and proj-work. Host-only merged mountpoints plus the
+ * HOME overlay upper/work live under /var/tmp/botmux-sbx/<sessionId>/ so none of
+ * the FUSE mountpoints is nested below the HOME lower layer.
  */
 export function prepareSandbox(opts) {
     if (!opts.enabled)
@@ -339,28 +419,37 @@ export function prepareSandbox(opts) {
     if (!ensureSandboxDeps(needFuse))
         return null;
     const dataDir = resolveSandboxMountPath(opts.dataDir);
-    const sessionRoot = join(dataDir, 'sandboxes', opts.sessionId);
+    const botmuxHome = dirname(dataDir);
+    const overlayPaths = sandboxOverlayPaths(dataDir, opts.sessionId);
+    const sessionRoot = overlayPaths.sessionRoot;
     const outbox = join(sessionRoot, 'outbox');
     const shimBin = join(sessionRoot, 'shimbin');
     const empties = join(sessionRoot, 'empties');
     const projUpper = join(sessionRoot, 'proj-upper'); // THE LANDABLE CHANGESET
     const projWork = join(sessionRoot, 'proj-work');
-    const projMerged = join(sessionRoot, 'proj-merged');
-    const homeMerged = join(sessionRoot, 'home-merged'); // merged may live under sessionRoot
-    // HOME overlay upper/work MUST be OUTSIDE the home lower (overlayfs constraint).
-    const vartmp = join(VARTMP_ROOT, opts.sessionId);
+    const projMerged = overlayPaths.projectMerged;
+    const homeMerged = overlayPaths.homeMerged;
+    // HOME overlay upper/work and both merged mountpoints MUST be outside HOME.
+    const vartmp = overlayPaths.runtimeRoot;
     const homeUpper = join(vartmp, 'home-upper');
     const homeWork = join(vartmp, 'home-work');
     for (const d of [outbox, shimBin, empties])
         mkdirSync(d, { recursive: true });
     const home = resolveSandboxMountPath(homedir());
+    // Masking BOTMUX_HOME is mandatory for the credential boundary.  A layout
+    // that makes it `/` or the whole user home cannot be masked without erasing
+    // the sandbox runtime itself, so refuse the spawn instead of silently
+    // exposing the custom session/config root.
+    if (botmuxHome === '/' || botmuxHome === home) {
+        console.error(`[sandbox] unsafe SESSION_DATA_DIR layout: BOTMUX_HOME resolves to ${botmuxHome}`);
+        return null;
+    }
     // BOTMUX_SANDBOX_SRC overrides the LOWER project source for spike testing only.
     const projectSource = resolveSandboxMountPath(process.env.BOTMUX_SANDBOX_SRC || opts.sourceWorkingDir);
     const projectMount = resolveSandboxMountPath(opts.sourceWorkingDir);
     // A same-session re-spawn (e.g. in-pane /clear) re-enters here; unmount any
     // stale merged overlays first so we don't stack a second mount on the same dir.
-    unmountOverlay(projMerged);
-    unmountOverlay(homeMerged);
+    unmountSandboxOverlays(overlayPaths);
     // Mount the HOME overlay (lower=real home → reads pass through, writes isolate).
     const homeOk = mountOverlay({ lower: home, upper: homeUpper, work: homeWork, merged: homeMerged });
     if (!homeOk) {
@@ -385,14 +474,25 @@ export function prepareSandbox(opts) {
     const shim = join(shimBin, 'botmux');
     writeFileSync(shim, `#!/bin/sh\nexec node ${JSON.stringify(distCliJs())} "$@"\n`);
     chmodSync(shim, 0o755);
-    // Per-bot privacy masks: existing dirs → tmpfs blank; everything else → empty
-    // read-only placeholder file. No defaults (caller passes hidePaths explicitly).
+    // Credential masks are mandatory; per-bot privacy masks extend them.
+    // Existing dirs → tmpfs blank; everything else → empty read-only placeholder.
     // `~` resolves like the docs' examples (`~/.ssh`) — an unexpanded tilde would
     // fail existsSync and mask a literal `~/...` path, leaving the real one readable.
     const hideDirs = [];
     const hideFiles = [];
+    const finalHideDirs = [];
+    const finalHideFiles = [];
     let emptyIdx = 0;
-    for (const raw of opts.hidePaths ?? []) {
+    const customBotsConfig = process.env.BOTS_CONFIG?.trim();
+    const credentialPaths = [
+        // SESSION_DATA_DIR may live outside ~/.botmux.  Its parent is the
+        // authoritative BOTMUX_HOME everywhere else (send-cred, per-bot homes,
+        // sessions/receipts); mask that exact root so a custom location cannot be
+        // recovered through the sandbox's initial read-only bind of `/`.
+        ...sandboxCredentialHidePaths(home, botmuxHome),
+        ...(customBotsConfig ? [resolve(customBotsConfig)] : []),
+    ];
+    for (const raw of [...credentialPaths, ...(opts.hidePaths ?? [])]) {
         if (!raw || typeof raw !== 'string')
             continue;
         const p = expandTilde(raw, home);
@@ -413,11 +513,33 @@ export function prepareSandbox(opts) {
             hideFiles.push({ path: p, empty });
         }
     }
+    for (const raw of opts.finalHidePaths ?? []) {
+        if (!raw || typeof raw !== 'string')
+            continue;
+        const p = expandTilde(raw, home);
+        let isDir = false;
+        try {
+            isDir = existsSync(p) && statSync(p).isDirectory();
+        }
+        catch { /* */ }
+        if (isDir) {
+            finalHideDirs.push(p);
+        }
+        else {
+            const empty = join(empties, `mask-${emptyIdx++}`);
+            try {
+                writeFileSync(empty, '');
+            }
+            catch { /* */ }
+            finalHideFiles.push({ path: p, empty });
+        }
+    }
     // CLI auth/login paths kept real+writable (token refresh / login must persist,
     // unlike isolated project edits). Resolve `~` and bind only existing paths — a
     // missing auth file isn't a valid mountpoint (the CLI must be logged in on the
     // host; login-from-scratch inside the sandbox isn't supported).
     const authReal = resolveExistingPaths(opts.authPaths, home);
+    const trustedWritableRoots = resolveExistingPaths(opts.trustedWritablePaths, home);
     const readonlyRoots = resolveExistingPaths(opts.readonlyRoots, home);
     const userReadonlyRoots = resolveUserReadonlyRoots(opts.userReadonlyPaths, home, projectMount);
     const plan = {
@@ -429,6 +551,9 @@ export function prepareSandbox(opts) {
         hideDirs,
         hideFiles,
         authReal,
+        trustedWritableRoots,
+        finalHideDirs,
+        finalHideFiles,
         readonlyRoots,
         userReadonlyRoots,
         net: opts.net !== false,
@@ -459,6 +584,18 @@ export function prepareSandbox(opts) {
         BOTMUX_SEND_RELAY: outbox, // routes `botmux send` to the daemon outbox watcher
         PATH: `/run/sbxbin:${process.env.PATH ?? ''}`, // /run/sbxbin first so `botmux` = the relay shim
     };
+    // The daemon discovery dir lives under the masked BOTMUX_HOME, so the only
+    // way an in-sandbox CLI can dial the daemon's loopback IPC (session-scoped,
+    // capability-gated routes like the v3 workflow relay) is this port marker.
+    // Not a credential: every route it reaches authenticates independently.
+    if (process.env.BOTMUX_DAEMON_IPC_PORT) {
+        env.BOTMUX_DAEMON_IPC_PORT = process.env.BOTMUX_DAEMON_IPC_PORT;
+    }
+    // Never inherit a custom credential config path into the sandbox. Its host
+    // path is masked above as defense in depth, while unsetenv prevents an
+    // absolute botmux/lark client from being pointed at it explicitly.
+    args.push('--unsetenv', 'BOTS_CONFIG');
+    args.push('--unsetenv', 'BOTMUX_HOST_RELAY_AUTHORIZED');
     // Forward proxy vars so the CLI reaches the API on the tmux backend too.
     for (const k of PROXY_ENV_KEYS) {
         const v = process.env[k];
@@ -476,8 +613,7 @@ export function prepareSandbox(opts) {
         workDir: projUpper,
         homeUpper,
         cleanup: () => {
-            unmountOverlay(projMerged);
-            unmountOverlay(homeMerged);
+            unmountSandboxOverlays(overlayPaths);
             try {
                 rmSync(sessionRoot, { recursive: true, force: true });
             }
@@ -503,8 +639,8 @@ export function prepareSandbox(opts) {
 export function attachSandboxOutbox(opts) {
     if (process.platform !== 'linux')
         return null;
-    const dataDir = resolveSandboxMountPath(opts.dataDir);
-    const sessionRoot = join(dataDir, 'sandboxes', opts.sessionId);
+    const overlayPaths = sandboxOverlayPaths(opts.dataDir, opts.sessionId);
+    const sessionRoot = overlayPaths.sessionRoot;
     const outbox = join(sessionRoot, 'outbox');
     const projUpper = join(sessionRoot, 'proj-upper');
     if (!existsSync(outbox) && !existsSync(projUpper))
@@ -514,21 +650,17 @@ export function attachSandboxOutbox(opts) {
         mkdirSync(outbox, { recursive: true });
     }
     catch { /* */ }
-    const projMerged = join(sessionRoot, 'proj-merged');
-    const homeMerged = join(sessionRoot, 'home-merged');
-    const vartmp = join(VARTMP_ROOT, opts.sessionId);
     return {
         outbox,
         workDir: projUpper,
         cleanup: () => {
-            unmountOverlay(projMerged);
-            unmountOverlay(homeMerged);
+            unmountSandboxOverlays(overlayPaths);
             try {
                 rmSync(sessionRoot, { recursive: true, force: true });
             }
             catch { /* */ }
             try {
-                rmSync(vartmp, { recursive: true, force: true });
+                rmSync(overlayPaths.runtimeRoot, { recursive: true, force: true });
             }
             catch { /* */ }
         },
@@ -537,15 +669,14 @@ export function attachSandboxOutbox(opts) {
 /** Reclaim one session's overlay residue: unmount both merged overlays + rm the
  *  per-session tree (incl. the /var/tmp home scratch). Idempotent / best-effort. */
 function reclaimSandbox(dataDir, sid) {
-    const sessionRoot = join(resolveSandboxMountPath(dataDir), 'sandboxes', sid);
-    unmountOverlay(join(sessionRoot, 'proj-merged'));
-    unmountOverlay(join(sessionRoot, 'home-merged'));
+    const overlayPaths = sandboxOverlayPaths(dataDir, sid);
+    unmountSandboxOverlays(overlayPaths);
     try {
-        rmSync(sessionRoot, { recursive: true, force: true });
+        rmSync(overlayPaths.sessionRoot, { recursive: true, force: true });
     }
     catch { /* */ }
     try {
-        rmSync(join(VARTMP_ROOT, sid), { recursive: true, force: true });
+        rmSync(overlayPaths.runtimeRoot, { recursive: true, force: true });
     }
     catch { /* */ }
 }
@@ -628,7 +759,8 @@ export function sweepOrphanSandboxes(dataDir, activeSessionIds) {
     // cause of the 2026-06-10 incident — keep it as the FIRST gate.
     const live = liveSandboxSids();
     for (const sid of sids) {
-        const sessionRoot = join(root, sid);
+        const overlayPaths = sandboxOverlayPaths(sandboxDataDir, sid);
+        const sessionRoot = overlayPaths.sessionRoot;
         if (live.has(sid))
             continue; // a running process holds this sandbox — leave it
         if (activeSessionIds.has(sid)) {
@@ -637,7 +769,7 @@ export function sweepOrphanSandboxes(dataDir, activeSessionIds) {
             // AND the tree is older than the spawn grace, the worker/CLI is dead →
             // reclaim the dead residue. We NEVER tear down a live mount, so a genuinely
             // live persistent (tmux/herdr/zellij) session keeps its changeset.
-            if (isMounted(join(sessionRoot, 'proj-merged')) || isMounted(join(sessionRoot, 'home-merged')))
+            if (hasMountedSandboxOverlay(overlayPaths))
                 continue;
             let ageOk = false;
             try {
@@ -731,7 +863,36 @@ export function validateRelayRequest(req) {
         }
         return { ok: false, error: `flag not allowed: ${f}` };
     }
-    return { ok: true, value: {
+    const originTurnId = req.originTurnId === undefined
+        ? undefined
+        : typeof req.originTurnId === 'string' && req.originTurnId.trim() && req.originTurnId.length <= 256
+            ? req.originTurnId
+            : null;
+    if (originTurnId === null)
+        return { ok: false, error: 'originTurnId must be a non-empty bounded string' };
+    const originDispatchAttempt = req.originDispatchAttempt === undefined
+        ? undefined
+        : typeof req.originDispatchAttempt === 'number'
+            && Number.isSafeInteger(req.originDispatchAttempt)
+            && req.originDispatchAttempt > 0
+            ? req.originDispatchAttempt
+            : null;
+    if (originDispatchAttempt === null)
+        return { ok: false, error: 'originDispatchAttempt must be a positive safe integer' };
+    if (originDispatchAttempt !== undefined && originTurnId === undefined) {
+        return { ok: false, error: 'originDispatchAttempt requires originTurnId' };
+    }
+    const originCapability = req.originCapability === undefined
+        ? undefined
+        : typeof req.originCapability === 'string'
+            && /^[a-f0-9]{32,128}$/i.test(req.originCapability)
+            ? req.originCapability
+            : null;
+    if (originCapability === null)
+        return { ok: false, error: 'originCapability must be a bounded hex token' };
+    return {
+        ok: true,
+        value: {
             contentName: req.contentFile,
             preparedContentName,
             cardName,
@@ -739,7 +900,11 @@ export function validateRelayRequest(req) {
             videoNames,
             videoCoverNames,
             flags,
-        } };
+            ...(originTurnId !== undefined ? { originTurnId } : {}),
+            ...(originDispatchAttempt !== undefined ? { originDispatchAttempt } : {}),
+            ...(originCapability !== undefined ? { originCapability } : {}),
+        },
+    };
 }
 /**
  * TOCTOU-safe copy of an outbox file (`outbox/<name>`, name already validated as
@@ -811,6 +976,7 @@ export function buildRelayHostEnv(baseEnv, preparedContentFile) {
 }
 export function startOutboxWatcher(outbox, baseEnv, sessionId, opts = {}) {
     const cli = opts.cliPath ?? distCliJs();
+    const authorize = opts.authorize;
     const inFlight = new Set();
     // Host-private staging — a sibling of the outbox, NOT bound into the sandbox.
     const staging = join(dirname(outbox), 'relay-staging');
@@ -860,6 +1026,11 @@ export function startOutboxWatcher(outbox, baseEnv, sessionId, opts = {}) {
                 finish(id, reqPath, name, staged, 1, '', `relay rejected: ${v.error}`);
                 continue;
             }
+            const authorization = authorize?.({ capability: v.value.originCapability });
+            if (authorization && !authorization.ok) {
+                finish(id, reqPath, name, staged, 2, '', `relay rejected: ${authorization.error}`);
+                continue;
+            }
             try {
                 mkdirSync(staging, { recursive: true });
             }
@@ -948,9 +1119,30 @@ export function startOutboxWatcher(outbox, baseEnv, sessionId, opts = {}) {
                 ...videoCoverPaths.flatMap(a => ['--video-covers', a]),
                 '--session-id', sessionId, // forced — sandbox cannot target another session
             ];
-            const child = spawn(process.execPath, [cli, 'send', ...hostArgs], {
-                env: buildRelayHostEnv(baseEnv, preparedContentPath),
-            });
+            // Fail closed: a durable origin (turnId/dispatchAttempt) may come ONLY
+            // from a host-side authorize decision. The sandbox controls every byte of
+            // the relay request, so its originTurnId/dispatchAttempt are never trusted
+            // — without an authorize hook the relay runs with no durable origin.
+            const trustedOrigin = authorization?.ok ? authorization.origin : undefined;
+            // Master's relay host env (BOTMUX_SEND_RELAY stripped + prepared-content
+            // local-link mode) is the base for the watcher-spawned host re-exec.
+            const requestEnv = {
+                ...buildRelayHostEnv(baseEnv, preparedContentPath),
+                BOTMUX_SESSION_ID: sessionId,
+            };
+            // The host re-exec itself is trusted (the sandbox child has this marker
+            // explicitly unset). Scrub any inherited durable-origin markers first,
+            // then re-apply only what the host authorized; cmdSend still re-validates
+            // the exact receipt/IM origin carried below.
+            requestEnv.BOTMUX_HOST_RELAY_AUTHORIZED = '1';
+            delete requestEnv.BOTMUX_TURN_ID;
+            delete requestEnv.BOTMUX_DISPATCH_ATTEMPT;
+            if (trustedOrigin?.turnId !== undefined)
+                requestEnv.BOTMUX_TURN_ID = trustedOrigin.turnId;
+            if (trustedOrigin?.dispatchAttempt !== undefined) {
+                requestEnv.BOTMUX_DISPATCH_ATTEMPT = String(trustedOrigin.dispatchAttempt);
+            }
+            const child = spawn(process.execPath, [cli, 'send', ...hostArgs], { env: requestEnv });
             let out = '', err = '';
             child.stdout.on('data', d => { out += d; });
             child.stderr.on('data', d => { err += d; });