@bo-agent/sandbox-local

Local implementation of the @bo-agent/sandbox seam. Selects and caches one platform runner: Linux prefers a working bwrap then Landlock; macOS uses Seatbelt (sandbox-exec); Windows uses the ACL restricted-token runner. Multiple candidates are probed in order; a sole candidate is selected directly.

The package root exports the default and named LocalSandboxProvider plugin and Config; platform profile builders stay internal.

Fail-closed

Unsupported platforms and unusable runners fail closed with SANDBOX_UNAVAILABLE; execution never silently falls through unconfined. Each wrap carries structured runner-failure rules so consumers can distinguish a broken sandbox from a command failure.

Policy is per call; the provider stores only the mechanism and cached runner verdict. Each wrap reports enforcement completeness plus backend-specific denial signatures and runner-failure rules.

Backend specifics

• Bubblewrap / Seatbelt: signature-only — neither public contract reserves a launcher-failure status, so the runner's child exit remains ordinary.
• Landlock: requires exit 125 and a landlock-run: fatal line after excluding only the exact partial-enforcement notice; a notice with child exit 1, 2, or 125 remains a child outcome.
• Windows ACL: keeps one deterministic write SID and standing ACE per workspace, but gives every live session/workspace pair a random private temp directory with a distinct SID and revocable ACE. A workspace equal to or containing the platform temp root fails before any ACL mutation because its inheritable workspace ACE would otherwise reach every private temp child.

Consumers spawn the returned argv directly, so a missing or unexecutable runner is an out-of-band spawn failure while a successfully launched child exit 126 or 127 remains ordinary.

Vendored launcher

@bo-agent/node-addon-landlock-run supplies the Landlock platform launcher, functional probe, and CLI argument vocabulary. This provider owns only mode-to-grant mapping and runner selection. Keeping path resolution and probe parsing with the versioned binary prevents contract drift.

Known limitations

• Windows ACL enforcement is partial — the restricted token must retain Everyone for process initialization, so external objects granting Everyone write access remain writable; NTFS hard links also alias one file object across workspace and external paths. Reported as enforcement: 'partial' rather than overstating that boundary as full.
• Landlock may be partial — older supported kernel ABIs confine only the access classes they expose, reported as enforcement: 'partial'.
• Seatbelt depends on deprecated sandbox-exec — macOS still ships it, but this provider cannot replace or probe that private policy engine if Apple removes it.
• Runner selection is cached for the provider lifetime — installing, removing, or repairing a runner requires reloading the plugin before selection changes.