Feature request: a public API to defer a Sandbox's COW commit/abort decision past process exit

[rotep]

Summary

We're building an MCP (Model Context Protocol) tool-call proxy on top of sandlock-core that wants to run a tool call inside a Sandbox, capture what it would change, hold that off disk pending an external approval decision (e.g. a human or policy approving/denying the effect), and only then commit or discard it. Today there's no supported way to do this once the sandboxed process has exited.

What exists today

• Sandbox::on_exit / Sandbox::on_error (BranchAction::{Commit, Abort, Keep}) are consulted synchronously in Sandbox::drop, based on the child's exit status (crates/sandlock-core/src/sandbox.rs:2443). The decision has to be picked before the sandbox is dropped, and dropping is the only mechanism that fires it.
• BranchAction::Keep doesn't hand back a resumable handle — it calls cow.keep() (sandbox.rs:2456), which is SeccompCowBranch::keep (cow/seccomp.rs:2215, pub(crate)), so the branch's own Drop backstop leaves the upper directory on disk instead of deleting it as an undisposed leak. The SeccompCowBranch itself is then dropped along with the rest of the Sandbox's internal Runtime when Sandbox::drop returns.
• recovery::{list_preserved, read_preserved} can find and read that leftover PreservedBranch later (paths, a deleted list, pid), but the module's own doc comment says it's "report-only today — the supported route to finish an interrupted merge is to re-run commit() on the branch." That commit() is SeccompCowBranch::commit (cow/seccomp.rs:1760, pub fn), but it's unreachable from outside the crate because the containing module is pub(crate) mod cow; (lib.rs:21) and SeccompCowBranch is never re-exported anywhere.

Net effect: once a Sandbox producing a COW branch has exited, there's no public path to hold its change set open and later programmatically commit or abort it based on a decision made after that point — only report on where it landed on disk.

What would help

Something like a way to take the pending branch out of a Sandbox before/instead of letting Drop decide — e.g. a method that hands back a Send-safe handle exposing commit() / abort(), so the decision can be resolved later (after an async wait for external input) instead of being required synchronously at process-exit time. Even a minimal version scoped to the single-sandbox case (independent of the multi-stage transaction work in #65) would unblock our use case.

Happy to sketch a concrete API proposal or take a swing at a PR if there's appetite — wanted to check feasibility/direction first, since this touches Drop semantics and the COW internals directly.

Context

We depend on sandlock-core (pinned by commit) from KYOKAOS, a capability sandbox for MCP agents. The full investigation (including the source references above) is written up in ADR-0012 if useful context.

[congwang-mk]

Thanks for the detailed writeup. Every reference in it checks out against main, and the feature is cheaper than it looks: after wait() the branch is already sitting in the sandbox as an owned value (sandbox.rs:937), and the transaction module already takes a branch out and disposes of it later on a blocking thread. What is missing is only the public surface.

We would rather not add a separate handle type. The branch stays where it is and the sandbox gains the two calls directly. Here is the design we intend to go with.

API

pub enum BranchAction { Commit, Abort, Keep, Defer }

pub struct RunResult {
    // existing fields
    pub changes: Vec<Change>,   // collected in wait() before any disposition
}

impl Sandbox {
    pub fn pending(&self) -> bool;
    pub fn upper_dir(&self) -> Option<&Path>;   // Some while pending
    pub fn commit(&mut self) -> Result<(), BranchError>;
    pub fn abort(&mut self) -> Result<(), BranchError>;
}

Sandbox is already Send, so you can hold it across an async wait for the approval decision and then call commit() or abort() from wherever the answer arrives.

Semantics

• Defer makes wait() leave the branch in place and mark the sandbox pending. on_error keeps its own action, so on_exit = Defer, on_error = Abort sends only successful runs to approval.
• commit() merges with the same 5s lock wait Drop uses today. On lock timeout it returns an error and the branch is preserved on disk, path in the message. abort() discards.
• Dropping a pending sandbox without deciding preserves the branch (same as Keep). You asked to decide and never did, so nothing is published and nothing is lost.
• changes is the same kind-plus-relative-path list dry_run() returns today. The new bytes of every added or modified file live under upper_dir(), laid out like the workdir, so you can diff them against the workdir yourself. Note that Modified means "opened for writing and exists in the workdir"; contents are not compared.
• A deferred commit is last-writer-wins against anything that changed the workdir during the wait, same as Commit today, only later.
• Defer is rejected on a Transaction stage, alongside Abort and Keep.

Consequences

dry_run() is removed. It was run() with both actions forced to Abort plus a read of the change list, and with changes on every result it becomes exactly on_exit = on_error = Abort. The CLI --dry-run flag stays and maps to that. We do not keep backward compatibility before 1.0, so there are no shims.

The FFI and Python bindings get the same surface: BranchAction.DEFER, Result.changes, and sandbox.pending / upper_dir / commit() / abort().

sb = Sandbox(workdir=wd, on_exit=BranchAction.DEFER)
r = sb.run(cmd)
if sb.pending:
    if await approve(r.changes, sb.upper_dir, wd):
        await asyncio.to_thread(sb.commit)
    else:
        sb.abort()

[congwang-mk]

#221 improves the API describing the filesystem changes.