botmux 2.66.0-canary.1 → 2.66.0

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

@@ -1,21 +1,39 @@
+/**
+ * Mount an overlayfs: reads fall through to `lower` (real, zero copy); writes
+ * copy-up into `upper` (the landable changeset). `work` is overlayfs scratch on
+ * the same fs as `upper`. Returns true iff `mount` exited 0.
+ */
+export declare function mountOverlay(opts: {
+    lower: string;
+    upper: string;
+    work: string;
+    merged: string;
+}): boolean;
+/** True iff `path` is currently a mountpoint (host-side overlay still mounted). */
+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. */
+export declare function unmountOverlay(merged: string): void;
 export interface SandboxPlan {
-    /** Host path of the per-session writable project copy (a `git clone` of the
-     *  source). Mounted INSIDE the sandbox at `projectMount`, not at this path. */
-    workDir: string;
-    /** In-sandbox path the clone is mounted at — MUST equal the original
-     *  workingDir the CLI was given (e.g. codex `-C <dir>`), so the CLI's existing
-     *  args resolve to the clone. Also the child's chdir. */
+    /** In-sandbox path the project is bound at — equals the original workingDir the
+     *  CLI was given, so the CLI's existing path args resolve. Also the child's chdir. */
     projectMount: string;
-    /** Per-session scoped HOME — bound over the real home path so every CLI's
-     *  hardcoded `~/.<cli>` resolves into this de-identified area. */
-    scopedHome: string;
-    /** Daemon-mediated `botmux send` outbox — the ONLY IPC surface bound in, so
-     *  bots.json / Lark creds never enter the sandbox. */
+    /** Host path of the merged project overlay (reads=real lower, writes=upper). */
+    projectMerged: string;
+    /** In-sandbox path the home overlay is bound at — equals the real home path so
+     *  every CLI's hardcoded `~/.<cli>` resolves there. */
+    home: string;
+    /** Host path of the merged home overlay. */
+    homeMerged: string;
+    /** Daemon-mediated `botmux send` outbox — bound LAST so it wins over any mask. */
     outbox: string;
-    /** Extra read-only paths the toolchain lives under (node/CLI binaries via
-     *  fnm, the botmux dist) — re-exposed AFTER the scoped-home mask because on
-     *  this host they sit under $HOME (e.g. ~/.local/share/fnm, ~/iserver/botmux). */
-    toolchainRo: string[];
+    /** Per-bot privacy masks: directories blanked with an empty tmpfs. */
+    hideDirs: string[];
+    /** Per-bot privacy masks: files blanked with a read-only empty placeholder. */
+    hideFiles: {
+        path: string;
+        empty: string;
+    }[];
     /** Keep network egress. File-only scope ⇒ default true (npm/pip/git work). */
     net?: boolean;
 }
@@ -23,42 +41,49 @@ export interface SandboxPlan {
  * Build the bwrap argv prefix. Final spawn becomes:
  *   bwrap <these args> -- <cliBin> <cliArgs...>
  *
- * Mount order matters: the scoped HOME is bound over the real home FIRST, then
- * toolchain/work/outbox paths (some under home) are re-bound on top — bwrap
- * applies binds in order, so the later, more specific mounts win.
+ * Mount order matters (later mounts win): the whole real fs read-only first, then
+ * the home + project merged overlays bind over it (so writes there are isolated),
+ * then privacy masks blank specific paths, then the outbox binds LAST so it stays
+ * writable even if a mask covers a parent dir.
  */
 export declare function buildSandboxArgs(plan: SandboxPlan): string[];
-/**
- * Materialise a de-identified config dir inside `scopedHome`: copy ONLY the
- * auth/config files from the host's real config, never history/sessions.
- * `dereference` resolves symlinks (codex's config.toml → config.toml.old) into
- * real files, since the symlink target won't exist inside the masked home.
- *
- * Returns false if this CLI has no persistent config to scope (hermes/aiden/…).
- */
-export declare function seedScopedConfig(cliId: string, scopedHome: string, projectMount?: string): boolean;
 /** Is file-sandbox enabled for this session? Spike gate = env; the real
- *  per-bot BotConfig.sandbox flag is a follow-up. */
+ *  per-bot BotConfig.sandbox flag is decided by the caller. */
 export declare function sandboxEnabled(): boolean;
 export interface SandboxSpawn {
     /** Replace the CLI binary with this (always 'bwrap'). */
     bin: string;
     /** bwrap args + '--' + original (bin, ...args). */
     args: string[];
-    /** Env overrides to merge into childEnv (HOME, PATH, BOTMUX_SEND_RELAY). */
+    /** Env overrides to merge into childEnv (HOME, PATH, BOTMUX_SEND_RELAY, proxies). */
     env: Record<string, string>;
     /** Outbox dir the daemon watcher must service. */
     outbox: string;
-    /** Per-session project copy (for logging / landing). */
+    /** Project overlay UPPER dir — THE LANDABLE CHANGESET (used by sandbox-land). */
     workDir: string;
-    /** Remove the per-session sandbox tree. */
+    /** HOME overlay UPPER dir (/var/tmp/botmux-sbx/<sid>/home-upper). The sandboxed
+     *  CLI's $HOME writes — INCLUDING its session jsonl under CLAUDE_CONFIG_DIR —
+     *  land here (invisible at the real path). The worker redirects its bridge/idle
+     *  watch into this via sandboxedClaudeDataDir() so it sees the CLI's turns. */
+    homeUpper: string;
+    /** Unmount the overlays + remove the per-session sandbox tree. */
     cleanup: () => void;
 }
+/** The path where a sandboxed session's CLI actually writes a $HOME-relative
+ *  data dir (e.g. CLAUDE_CONFIG_DIR / `.claude-runtime`): the HOME overlay's
+ *  ephemeral UPPER copy. The worker redirects its jsonl/bridge watch here so it
+ *  sees the sandboxed CLI's writes (which are invisible at the real host path).
+ *  Mirrors prepareSandbox's homeUpper layout — keep in sync. */
+export declare function sandboxedClaudeDataDir(sessionId: string, realDataDir: string): string;
 /**
  * Build the sandboxed spawn for a CLI session, or return null when sandboxing
- * is off / unsupported. Creates per-session dirs under
- * <dataDir>/sandboxes/<sessionId>/, clones the source project, seeds a
- * de-identified config dir, and installs a `botmux` shim on PATH.
+ * is off / unsupported / a required overlay mount fails (fail-safe = the worker
+ * 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).
  */
 export declare function prepareSandbox(opts: {
     /** Whether the sandbox is on for THIS session (per-bot BotConfig.sandbox OR
@@ -71,7 +96,51 @@ export declare function prepareSandbox(opts: {
     dataDir: string;
     cliBin: string;
     cliArgs: string[];
+    /** Per-bot privacy masks (opt-in, no defaults). Paths existing as dirs are
+     *  blanked with a tmpfs; files with an empty read-only placeholder. */
+    hidePaths?: string[];
 }): SandboxSpawn | null;
+/**
+ * Re-attach the daemon/worker side to an ALREADY-spawned sandbox session WITHOUT
+ * touching the overlays. Used on daemon-restart reattach to a persistent
+ * (tmux/herdr/zellij) pane whose bwrap'd CLI is still alive: the CLI is bound to
+ * its own namespace-pinned overlay, so we must NOT unmount/remount (that would
+ * leave a duplicate host-side mount the CLI isn't using). We only need the outbox
+ * path back so the watcher can keep servicing the live CLI's `botmux send`, plus
+ * the workDir (upper changeset for landing) and a cleanup that tears the residue
+ * down at close/exit. Returns null if the session has no sandbox tree on disk
+ * (never sandboxed). Linux-only, mirrors prepareSandbox's layout.
+ */
+export declare function attachSandboxOutbox(opts: {
+    sessionId: string;
+    dataDir: string;
+}): {
+    outbox: string;
+    workDir: string;
+    cleanup: () => void;
+} | null;
+/**
+ * Reclaim leaked sandbox residue.
+ *
+ * Two classes of leak are reclaimed:
+ *  1. NON-ACTIVE orphans — sid not in `activeSessionIds`: the session is gone, so
+ *     any leftover mount/dir is pure residue (the original startup-sweep case,
+ *     guarding against a daemon crash/kill that skipped killCli()).
+ *  2. ACTIVE-but-DEAD — sid IS in `activeSessionIds`, yet NEITHER of its merged
+ *     overlays is still mounted. This closes the blind spot where a sandboxed
+ *     worker was SIGKILL'd (straggler reaper) or crashed: the session stays
+ *     status='active' on disk, so the old "skip if active" rule would let the
+ *     leaked upper/work dirs survive across restarts indefinitely. We only GC an
+ *     active sid when its mounts are ALREADY gone — we NEVER tear down a live
+ *     mount (a CLI persisting in a tmux/herdr/zellij pane is still bound to it),
+ *     so a genuinely-live persistent session keeps its changeset.
+ *
+ * Safe to call repeatedly: wire once at daemon bootstrap AND on a periodic timer
+ * (the SIGKILL/straggler path can't run worker-side killCli(), so a startup-only
+ * sweep would let a crashed-active session's mount survive for the whole next
+ * daemon lifetime — one daemon per bot can run for days).
+ */
+export declare function sweepOrphanSandboxes(dataDir: string, activeSessionIds: Set<string>): void;
 export interface RelayRequest {
     contentFile?: unknown;
     attachments?: unknown;
@@ -101,9 +170,14 @@ export declare function validateRelayRequest(req: RelayRequest): {
 /**
  * TOCTOU-safe copy of an outbox file (`outbox/<name>`, name already validated as
  * a plain basename) into a host-private `dest`. Opens with O_NOFOLLOW so a
- * symlink swapped in by the sandbox AFTER validation is rejected at open time;
- * reads from the fd (not the path), so the inode can't be swapped under us.
- * Returns false (reject) on symlink / non-regular / any error.
+ * symlink swapped in by the sandbox AFTER validation is rejected at open time,
+ * and O_NONBLOCK so opening a FIFO/special the sandbox dropped into the (rw-bound)
+ * outbox returns IMMEDIATELY instead of blocking the synchronous watcher tick
+ * forever (a FIFO with no writer would otherwise hang the whole worker event
+ * loop — an agent-triggerable DoS). After open we fstat-reject anything that
+ * isn't a regular file (a FIFO opened O_NONBLOCK|O_RDONLY succeeds but isFile()
+ * is false → rejected here). Reads from the fd (not the path), so the inode can't
+ * be swapped under us. Returns false (reject) on symlink / non-regular / any error.
  */
 export declare function materializeOutboxFile(outbox: string, name: string, dest: string): boolean;
 /**

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":"AAsBA,MAAM,WAAW,WAAW;IAC1B;mFAC+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB;;6DAEyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB;sEACkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB;0DACsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf;;sFAEkF;IAClF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAMD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,EAAE,CAmB5D;AA2CD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CA0BlG;AA4ED;qDACqD;AACrD,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAoDD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC;;sFAEkF;IAClF,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,GAAG,YAAY,GAAG,IAAI,CA2FtB;AAOD,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAQD,MAAM,WAAW,cAAc;IAAG,WAAW,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;CAAE;AAEpG;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAwB1H;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAiBzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,IAAI,CAkE5G"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/adapters/backend/sandbox.ts"],"names":[],"mappings":"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"}