[paveq]

Implements the Airlock v2 design from #14 and is stacked on it. The design, UX and technical-guidance docs there are the spec. Where this PR made a choice the docs left open, it is recorded in the design doc's new Implementation notes section.

What changes

• One daemon per user, with sessions (src/daemon.rs, src/session.rs, src/protocol.rs).

  • The daemon starts on demand, or as a launchd/systemd service (airlock daemon install).
  • It reads no config and no process environment after startup. Everything a session needs arrives with Register.
  • Connections open with a protocol-version handshake. Requests come in two families, admin and session, each gated on its own credential (admin.token or a session token), with an ErrorKind per failure mapped to exit codes 125/126/127.
  • Sessions end when the airlock run lease closes, when their TTL runs out (session start, 12h), on revoke, or when the daemon stops.
  • Each token is bound to its anchor process's tree, checked by peer PID plus start time.
  • Every response passes the session's redactor and then a daemon-wide last-pass redactor; error messages included.
  • Each session may run at most 16 execs at once.
  • An automatic daemon exits 5 minutes after its last session ends.
  • A startup lock serializes concurrent auto-starts.

• Runtime dir outside the project (src/runtime_dir.rs): confstr per-user temp dir on macOS, /run/user/<uid> or /tmp/airlock-<uid> on Linux. It is never taken from the environment and is validated with lstat. Every Seatbelt profile ends with denies for writes to it and for reading admin.token, plus F9's .git/hooks write deny.

• Layered config (src/layers.rs, src/config.rs):

  • Layers, lowest to highest: global < repo airlock.toml < local airlock.local.toml.
  • Tool collisions follow the design (global yields; local needs override = true).
  • Repo items use only repo labels. The local file binds them, and from = "global" reuses a global binding.
  • {tool_state} keeps tool state outside the project.
  • deny_unknown_fields applies at every level, so the wire config fails closed.

• Trust (src/trust.rs):

  • The trust store keeps byte-exact approved copies, written by temp file and rename.
  • Reviews show unified diffs with ANSI, bidi and zero-width characters escaped, and from = "global" lines are annotated with the global source.
  • Launchers prompt on a terminal and refuse elsewhere. airlock trust takes --yes and --expect-sha256.

• Anchors and B2 (src/anchors.rs, src/exec.rs, src/secrets.rs):

  • XDG-derived anchors are checked for ownership and mode, refused inside the project root, and checked against every write grant from every layer (approved or not) plus --allow-write.
  • The filtered PATH is used both to resolve tools and to resolve secret commands' argv[0].
  • Binaries are refused if they resolve into the project or a write grant.

• Launcher and CLI (src/launcher.rs, src/run.rs, src/main.rs, src/admin.rs, src/client.rs, src/inspect.rs, src/service.rs, src/agent.rs):

  • The full command surface from the UX doc: run, init [--local|--global], trust, config [--paths], status, exec, tools list [--session], session start|renew|list|reload|revoke, daemon start|stop|restart|logs|install|uninstall, agent check, agent hook claude-code|text.
  • --help is grouped by audience; inside the sandbox it shows only the commands that work there and names the hidden ones.
  • User-terminal commands refuse inside the sandbox.

• Tool access levels (src/sandbox.rs, src/policy.rs). Each tool's built-in filesystem baseline is set by access, per tool or once at the top level:

  • none: the tool's binary plus what any program needs to start (dyld and the shared cache on macOS; the loader and libc on Linux);
  • system: the previous baseline;
  • default (the default): system plus read-only Nix store, Homebrew, /usr/local, MacPorts and Linuxbrew, so dynamically linked Nix and Homebrew tools work without extra_read.

  On Linux a tool now gets its own binary at every level; before, a tool installed outside the baseline directories could not execute.

• Kits for the agent (src/kits.rs). Under airlock run, [agent] kits = [...] or --kit adds what a kind of work needs, separately from the harness --profile. Built in: rust, node, python, go, elixir; you can define your own in the global or local config.

  • isolated (the default) points the language's cache variables (CARGO_HOME, npm_config_cache, GOPATH, MIX_HOME, …) at a per-project directory under ~/.cache/airlock/kits/.
  • shared writes the real caches and reads the user's toolchain config and registry credentials, so private registries and publishing work.
  • Neither mode ever writes binaries or config (~/.cargo/bin, ~/.cargo/config.toml, ~/.npmrc, ~/.mix).
  • [kits.*] is accepted only in the global or local layer, so a repo can't switch you to shared mode. SECURITY.md covers shared mode's cache-poisoning risk.

• Session isolation is enforced by a lint. clippy.toml disallows std::env::var*, set_var, remove_var and current_dir. Launcher-side functions carry narrowly scoped allows; no daemon-side request path reads the environment.

• Docs and examples: README, SKILL, ARCHITECTURE, SECURITY, CLAUDE.md and TODO are rewritten for v2. The examples carry v2 headers, examples/team/ holds a three-layer walkthrough, and examples/secret-sources.toml replaces the startup scripts. All examples are parse-tested.

• Demo: examples/demo/demo.sh walks through the whole flow in throwaway XDG dirs and does not touch your real config or trust store.

Try it

cargo build
examples/demo/demo.sh

Run it from a normal terminal, not inside airlock run. It shows:

1. The unbound-label error, then init --local.
2. The merged config with each item's layer.
3. trust and session start.
4. A redacted exec, and exit codes 127/125/3.
5. A config edit by the agent, then trust and session reload.
6. agent check and the SessionStart hook output.
7. airlock run with a sandboxed agent.
8. Revoke, then daemon stop.

Testing

• macOS, outside Airlock: cargo test passes all 945 tests, none skipped, including every test that applies a real Seatbelt sandbox. examples/demo/demo.sh runs end to end with exit 0.
• That first unsandboxed macOS run found three bugs that the skipped tests and Linux CI had missed. They are fixed here, each with a regression test:
  • exec with stdin at EOF (/dev/null, an empty pipe) failed: the client half-closed the socket, which the daemon reads as a disconnect.
  • Every airlock run session ended as soon as it was registered: the daemon half-closed the lease after Registered.
  • The launcher's lease kept the 10-second admin request timeout, which would have ended every airlock run session 10 seconds in.
• Kits were checked with real cargo fetch/build runs under airlock run:
  • isolated mode leaves the real ~/.cargo untouched;
  • shared mode writes the registry cache and applies the user's config.toml;
  • shared mode can't write config.toml, credentials.toml or ~/.cargo/bin.
• The test split is a build-time cfg. build.rs sets no_nested_sandbox when AIRLOCK_SANDBOX=1 or AIRLOCK_NO_NESTED_SANDBOX=1 (the Nix package build sets the latter). A plain cargo test anywhere else runs everything.
• Linux: the real-sandbox suites passed in CI under Landlock up to 947f148. CI runs only for PRs into main, so this PR's later commits were checked with the cross-checked clippy below, not run on Linux.
• cargo clippy --all-targets -D warnings is clean on macOS and on Linux (cross-checked).

Beyond the design

• Linux sandboxes can now write to /dev/null. The Landlock baseline used to grant it read-only, which broke 2>/dev/null in tools and agents.
• The home-root guard compares canonical paths. A home reached through a symlink no longer lets a project at $HOME through without allow_home_root.
• Pre-trust error output and airlock config escape config text.
• Tool names are restricted to [A-Za-z0-9._+-].
• Tools run with their own name as argv[0], not the canonical binary path, so multicall binaries (Nix coreutils, busybox) work.
• A Linux tool gets read and execute access to its own binary at every access level.

Known limitations

• eval "$(airlock session start)" must run directly in the shell that will use the session (verified in bash and zsh). Piping its output through another command anchors the session to a short-lived subshell, which makes it unusable. This is documented.
• Follow-ups F1–F3, F6, F7, F10, F11 and shell completion (V1) remain, as the design says.

🤖 Generated with Claude Code

[paveq]

Code review findings

I reviewed the local feat/airlock-v2 at 141213a, which is 26 commits ahead of the pushed head (1d26f63), so the line numbers below refer to that local state. These findings come from reading the code; I didn't build or run tests. The stray build.log in the pushed head is already removed locally.

Security and isolation (fix before merging)

1. A global tool can be given the repo's secret (src/layers.rs:1200). If the global layer and airlock.toml both declare the same label, final_secrets keeps only the repo/local binding, because final_secrets.contains_key skips the global spec. A global gh tool that references GH_TOKEN then gets whatever value the repo bound to that label (for example source="env", from="AWS_SECRET_ACCESS_KEY") and sends it to GitHub. The trust review never shows that the global tool was rebound. This contradicts the design rule that the two layers are "separate bindings until the local file links them".
2. Refreshed secret commands run unsandboxed with cwd = project root (src/session.rs:231). argv[0] is location-checked, but anything the command loads relative to its cwd is not. Example: with command = ["python3", "-m", "keyring", "get", …] and refresh = 3600, the sandboxed agent writes <root>/keyring.py. The next background refresh runs it as the user, outside every sandbox. The same applies to npx, uv run and mise shims that read project config from cwd.
3. Pre-auth connections can buffer 16 MiB each (src/daemon.rs:1255). Every connection is framed with MAX_ADMIN_LINE_BYTES. MAX_SESSION_LINE_BYTES is only checked after the full line is buffered, and never for later stdin frames. Any process of the uid, including an agent sandboxed for another project with no token, can open many connections and grow daemon memory without bound. Session clients can also send 16 MiB stdin frames. v1 capped every line at 1 MiB via ClientLineOverflow.
4. handle_reload doesn't check that payload.root == session.root (src/daemon.rs:1625). The agent deletes <proj>/airlock.toml, then airlock session reload runs discovery, which walks up to an already-trusted parent (e.g. ~/src/airlock.toml). Every tool then gets read-write on ~/src as its sandbox root, while the cwd check and resolve_binary_in still use <proj>.
5. Secret values pass through buffers that are never zeroized (src/daemon.rs:1295). Register/Reload carry plaintext secret values, but the daemon reads them into a plain String (plus LinesCodec's BytesMut), and the launcher's encode_line writes them into a plain Vec<u8>. Only WireSecret.value is Zeroizing. Every registration leaves copies of every resolved secret in freed heap, in both the launcher and the long-lived daemon.

Reliability

6. A reused PID blocks daemon auto-start (src/daemon.rs:493). The stale-state check still treats a live PID in airlock.pid as a running daemon. It runs while holding the exclusive startup lock, and a real daemon holds that lock for its whole life, so a live PID here can only belong to an unrelated process that reused it. After a SIGKILL, crash or OOM, airlock run and session start return AlreadyRunning until that process exits or the user deletes the PID file.
7. The listener stays bound during graceful_shutdown (src/daemon.rs:997). Shutdown can take 5s or more (child grace period plus 2s per session). New connections queue in the backlog and are never answered. airlock run connects, waits for the 10s Hello timeout and fails as a hard error rather than Unreachable, so it never starts a fresh daemon. airlock exec has no read timeout and hangs until the old daemon exits. Fix: drop the listener before graceful_shutdown.
8. daemon restart always starts a Manual daemon (src/main.rs:1213). With a launchd/systemd service installed, the service manager respawns the daemon first and takes the startup lock, so restart's own start fails with StartInProgress (exit 75). Restarting an automatic daemon turns it into a Manual one that never exits when idle.
9. parse_ttl can panic (src/launcher.rs:953). split_at(len-1) panics on a non-ASCII last character (--ttl 5é), and n * multiplier is unchecked. A large value that doesn't overflow still panics in the daemon's Ends::ttl_from_now (SystemTime overflow in handle_register/handle_renew), and the launcher sees the connection drop with no error message.

Error message

10. run_trust discards the refusal message (src/launcher.rs:865). It matches Decision::Refuse { .. } and drops the message from trust::decide. On an --expect-sha256 mismatch the user never sees which file failed or its current hash. The CLI prints a generic hint instead, which on an interactive terminal wrongly suggests a non-terminal is needed.

[paveq]

Known issue: secret labels share one namespace across layers

This predates parent configs (4ac91ff). That change extends it to parent-level tools, so I'm recording it here.

On the wire, a merged config's [secrets] table is one flat map keyed by label. A tool from a lower layer that references label L gets whatever binding the final table holds for L. If a higher layer also declares L, that is the higher layer's binding, not the one from the layer that declared the tool.

• Global tool, repo label. The global file declares [secrets.GH_TOKEN] and a global gh tool that uses it. The repo also declares [secrets.GH_TOKEN], with its own source or bound in the local file. The global gh then runs with the repo's GH_TOKEN, not the user's global one.
• Parent tool, repo label. The same happens to a tool from a cascade = true parent config when the project declares a label of the same name.

merge_level in src/layers.rs inserts the repo and local labels into the final secrets table first. When it then adds the base labels that base tools reference, it skips any label the table already has.

Impact. It doesn't leak a personal secret into a repo tool. The direction is the reverse: an approved repo file decides which credential a user's own global or parent tool receives. That needs an approved file, and usually a project that declares a label for its own tool of the same name, so it's mostly a correctness surprise rather than a hole. It's still a case where a lower layer's tool silently runs with a binding its own file never declared.

Possible fixes (not done in this PR):

• Make the collision a config error that names both files when a base tool references a label a higher layer also declares.
• Namespace labels per layer on the wire, so each tool's env refers to the binding of the layer that declared the tool.

Left alone for now; I'll address it separately if wanted.