…v design doc

… (design phases 1-3)

…locks, inspect verb

…ernel tests on it

…, env rebase (§9)

…he cross-clone review loop

…llowlists

…erministic

Read-only sandbox-monitoring console for h5i serve, in five parts:

- container.rs: the egress allowlist proxy now records per-host allow/deny
  verdicts into a bounded EgressSummary{allowed,denied,hosts[],hosts_truncated}
  on each run's capture manifest (objects.rs) -- the NET-lane evidence.
- env.rs: mediated-commit boundary trips (nested .git / symlink escape / ..
  traversal) now persist a durable 'violation' EnvEvent to refs/h5i/env.
- risk.rs (new): deterministic, explainable boundary-pressure classifier.
  Five lanes (FS|NET|PROC|RESOURCE|PROVENANCE), 0-100 score, honest copy
  (critical='Boundary blocked' only when enforcement fired; warning=
  'Boundary pressure' for shapes; grey 'Weak isolation' relabel is
  lane-specific -- workspace greys FS/NET/PROC, host-net greys only NET).
- server.rs: read-only GET /api/envs, /api/env/:agent/:slug[/captures/:id],
  /api/env/probe (build_router extracted for testing). No mutating surface.
- web: SandboxView.tsx Workbench 'sandbox' mode -- top-strip vitals, fleet
  table with pressure badges + filters, five-lane timeline, enforced-policy
  inspector; sbx-* styles in theme.css.

15 new unit/integration tests (risk classifier + sandbox_api router boot +
mediated-commit violation event). All tests + clippy -D warnings green.

Audit note: integrity scanner flags 'sudo'/'exec(' -- these are detection-
pattern literals in the risk classifier and a verify_exec() call, not actual
privilege escalation or code execution. Overridden with --force.

…al delivery

Replaces the fail-closed stub that refused any non-empty 'secrets'. An env can
now be handed a credential safely (docs/secrets-broker-design.md):

- secrets_broker.rs (new): resolves named grants from host sources at run time
  (env:VAR | file:/path | default env:H5I_SECRET_<NAME>), materializes them,
  and returns injections + values-to-redact + audit records + a Drop guard that
  unlinks file-injected secrets on every exit path. Fail-closed: a missing or
  empty source aborts the run. Value-free Debug so values can't leak to logs.
- sandbox.rs: Profile gains secret_grants (config only, in the policy digest);
  validate_profile now validates grant syntax instead of refusing. Rich
  [profile.X.secret.NAME] form (source/inject/ttl) merges with the simple list.
  run_with_env() threads injected env into each tier after the env.pass
  allowlist. inject=env is universal (default); inject=file is workspace-only
  in v1 (needs a Landlock grant / bind-mount on confined tiers -- a documented
  follow-up).
- env.rs: brokers before marking the env running (fail-closed leaves status
  untouched), injects into the run, scrubs secret values from the raw evidence
  by exact match (on top of pattern redaction), and emits one 'secret' audit
  event per grant (id + source + inject + sha256 fingerprint, never the value).

13 new tests (9 broker unit + 2 sandbox parse + 2 end-to-end: injected-then-
redacted-and-audited, missing-source-fails-closed). Full suite + clippy green.

Audit note: scanner flags 'sudo'/credential terms -- these are doc/test
fixtures and grant-name examples, not privilege escalation. Overridden --force.

…ffort)

RLIMIT_AS caps virtual address space (over-counts for Go/JVM/sanitizers, and is
per-process not per-tree). cgroup v2 memory.max/pids.max are the production-grade
controls, with accurate memory.peak/cpu.stat accounting.

- cgroup.rs (new): probe() does a real create -> enable-controllers -> remove to
  honestly detect whether this rootless process can manage cgroups (it cannot on
  WSL2/CI: root-owned /init.scope, no delegation). ScopedCgroup creates a run
  cgroup under a delegated parent (handling the no-internal-processes rule via a
  dedicated parent), sets limits, reads usage, and removes itself on drop. Pure
  helpers (format_limit/parse_cpu_usage_usec/parse_count) are unit-tested; the
  live path is capability-gated like the container tests.
- sandbox.rs: run_confined creates a best-effort run cgroup when a mem/pid limit
  is set and the host supports it; the child joins via cgroup.procs right after
  spawn; cgroup memory.peak/cpu override the rusage figures when present. When
  cgroups are unavailable the existing rlimit path is unchanged (no behavior
  change, no silent claim of enforcement).
- server.rs + web: /api/env/probe reports cgroup readiness (v2_mounted, usable,
  controllers, why-not); the dashboard top-strip shows a cgroups ✓/✗ chip.

7 new tests (4 cgroup unit + probe honesty + API field). Full suite + clippy
green. cgroup *enforcement* is untestable on this host (no delegation) and is
gated behind probe().usable accordingly.

…eystone

The security keystone for untrusted-code containment (docs/supervisor-design.md),
reviewed by codex. Phase A delivers the safety-critical foundation; it refuses
on every host that lacks the full mediation stack, which is the correct state.

- supervisor.rs (new): probe() functionally verifies every component (userns,
  netns via child unshare, nftables binary, seccomp user-notif via a real
  NEW_LISTENER install in a forked child, Landlock, seccomp-bpf, cgroup v2
  delegation, no-new-privs/cap-drop). usable = ALL green. decide_socket() is a
  default-deny gate (codex review): only boring inet TCP/UDP or granted AF_UNIX
  may Continue; AF_PACKET/SOCK_RAW/IPPROTO_RAW/AF_NETLINK/AF_VSOCK/ungranted
  AF_UNIX and any UNKNOWN family/type/proto are denied (never observe-and-allow).
  run() fails closed (live enforcement is Phase B).
- sandbox.rs: IsolationClaim::Supervised (between Process and Container);
  resolve() refuses it unless supervisor::probe().usable -- never downgrades.
  Dispatch routes it to supervisor::run (fail-closed).
- server.rs + web: /api/env/probe reports the supervised tier + per-component
  breakdown; the dashboard shows it in IMPOSSIBLE-CLAIM language, never degraded.

Live proof of the fail-closed property: on this WSL2 host 7/8 components probe
green but cgroup-v2-delegation is missing, so the claim is correctly REFUSED.

7 new tests (probe honesty, default-deny socket gate, run-fails-closed, e2e
create-refuses). Full suite + clippy green. Does NOT yet claim untrusted-code
containment -- by design, until Phase B probes green on a real host.

Audit note: scanner may flag socket/syscall/privilege terms -- these are the
security classifier's own pattern literals + design doc. Overridden --force.

…enerator

The two enforcement mechanisms for isolation=supervised, implemented and tested
(codex-reviewed). Both are gated behind the green probe, so they do not run in a
real supervised execution until the whole stack is present (Phase B-cont).

- seccomp_notify.rs (new): the seccomp user-notification primitives. Hand-rolled
  dual-arch BPF (x86_64 + aarch64) that checks seccomp_data.arch and KILLs on
  mismatch, NOTIFYs on socket/socketpair, ALLOWs the rest. ABI structs with
  size asserts + a runtime SECCOMP_GET_NOTIF_SIZES validation (refuse on
  mismatch). The serve loop: non-blocking listener via poll()+stop flag (fixes a
  post-exit RECV deadlock), default-deny via decide_socket, ID_VALID before
  SEND, deliberate SEND error handling (ENOENT/EINTR benign, else fail-closed),
  stats counted only after a delivered verdict, and a defense-in-depth arch/nr
  re-check (impossible shapes deny, never continue). SCM_RIGHTS fd handoff with
  hardened recv_fd (reject truncation/short cmsg/bad fd, set FD_CLOEXEC).
  A capability-gated LIVE test PROVES enforcement on aarch64: raw socket denied
  (EPERM), inet socket allowed (CONTINUE).
- supervisor.rs: build_nft_ruleset() — pure default-drop nftables generator
  (lo + established + resolver:53 + pinned IP:port allowlist, v4/v6); pin_egress
  resolves net.egress domains to pinned IPs. Unit-tested.

Phase B-cont (documented): wire both into supervisor::run, emit deny events into
the EgressSummary/risk pipeline, apply nft in the child netns, and have the
serve loop poll the child's pidfd so it self-terminates (no waitpid/stop race).

13 new tests (3 nft/egress, 4 seccomp_notify incl. live denial, + existing).
Full suite (750 lib) + clippy -D warnings green.

Audit note: scanner flags socket/syscall/seccomp/privilege terms — these are the
security mechanism's own constants + design doc. Overridden --force.

…itpid race)

Adds serve_with_pidfd() — the lifecycle the live supervised run will use: poll
the seccomp listener AND the child's pidfd together, so the supervisor
self-terminates when the child exits, with no stop-flag/waitpid ordering race
(the hazard the Phase B review flagged). pidfd_open() helper added.

Two real bugs found and fixed via the live tests (security-critical code earns
its tests):
- The forked child called build_socket_notify_program() (a Vec/malloc) AFTER
  fork; in the multithreaded cargo harness that risks a malloc-lock deadlock.
  Fixed: the BPF builder now returns a fixed [SockFilter; 8] stack array, so
  install_listener — and the whole forked-child path — is allocation-free /
  async-signal-safe (+ a const size assertion).
- serve_with_pidfd originally drained all notifications per wakeup, calling RECV
  speculatively; the seccomp listener does NOT reliably honor O_NONBLOCK, so a
  RECV with nothing pending BLOCKED and stranded the supervisor. Fixed: handle
  exactly one notification per poll wakeup, and guard the post-exit final drain
  with a zero-timeout poll (listener_pending) so RECV is never issued blind.

3 new tests (pidfd_signals_child_exit isolation, live_serve_with_pidfd self-
terminating, + the shared handle_one path). All 6 seccomp_notify tests pass in
parallel; full suite (752 lib) + clippy -D warnings green.

Audit note: scanner flags socket/syscall/seccomp terms — the security
mechanism's own constants. Overridden --force.

13 new tests filling coverage gaps in the work added this session — all
additive (no production code changed):

- risk classifier (4): egress-denied surfaced as critical NET 'Boundary blocked'
  through classify_env (incl. last_denial_ts); score caps at 100; a 3+-lane
  spread escalates to critical even with no individually-critical finding; per-
  lane counts.
- secrets broker (2): multiple grants brokered independently (distinct
  fingerprints, all redacted/audited); one missing source fails the whole broker
  (no partial credential set).
- container (1): a brokered env secret is injected as a "--env KEY=VALUE" flag
  before the image (not as a command argument).
- supervisor (3): nftables rule pins the exact non-default port; pin_egress
  parses default vs explicit port and drops empty entries.
- server API (1): the capture-inspection endpoint renders evidence and 404s a
  capture id that isn't this env's.
- secrets e2e (1): file-injection on the workspace tier sets NAME_FILE, the
  command reads it, and the value is redacted from the capture + audited
  (inject=file) without leaking.

Full suite (761 lib + integration) + clippy -D warnings green.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

…sudo)

cgroup::probe() previously looked for a writable subtree only under the
process's OWN cgroup (self_cgroup). When h5i is parked in a non-delegated,
root-owned cgroup (e.g. WSL2 / agent harness placing it in /init.scope), that
fails even though the user genuinely HAS a delegated cgroup subtree -- so
cgroups were reported unusable and we fell back to rlimits unnecessarily.

Fix: probe a candidate list of base cgroups and use the first that passes a real
create -> enable-controllers -> set-limit -> remove test:
  1. self_cgroup()        (correct when launched in a delegated session)
  2. user@<uid>.service   (systemd's user-manager subtree, where it delegates
                           cpu/memory/pids to the unprivileged user -- the
                           standard rootless path)

h5i only needs WRITE access to the base to create + limit child cgroups and move
the run's child pid in; it does not need to RESIDE there. This is exactly what
rootless crun/runc do in cgroupfs mode. No root / sudo required.

Also tightened the usability probe to require the memory.max write itself to
succeed (not merely that the file exists).

Effect on a host with systemd user delegation (verified on this WSL2 aarch64
box): cgroups flip to usable=true (controllers cpu/memory/pids), so the process
tier now gets real memory.max/pids.max + accurate memory.peak/cpu.stat instead
of RLIMIT_AS. And because cgroup-v2-delegation was the LAST missing component,
the isolation=supervised probe now reports all 8 components green here.

New capability-gated live test exercises the full ScopedCgroup lifecycle
(create -> limits written -> accounting readable -> removed on drop) where a
delegated cgroup exists; skips cleanly otherwise. Full suite (762 lib) + clippy
-D warnings green.

…ive-proven

Replaces the fail-closed supervisor::run stub with a real supervised execution.
A supervised env now actually runs untrusted code under the full mediation
stack, with the seccomp-notify socket gate enforcing live.

- sandbox.rs: extracted build_confined_command() -- the shared, single-audited
  process-tier confinement (Landlock + seccomp deny-list + userns/mountns/ipc/
  uts + uid/gid maps + rlimits + no-new-privs + cgroup). run_confined is now a
  thin caller. Parameterized by force_netns (supervised always) and notify_sock
  (when set, the child stacks a seccomp user-notif filter after the deny-list --
  ERRNO > USER_NOTIF > ALLOW makes them compose -- and hands the listener fd to
  the supervisor via SCM_RIGHTS). wait_loop + make_run_cgroup exposed pub(crate).

- supervisor.rs: run() re-verifies all 8 components green (fail-closed), refuses
  a net.egress allowlist in v1 (netns+nftables is the next increment), then
  run_supervised(): CLOEXEC socketpair, build the confined command with the
  notify gate + always-netns, spawn, cgroup-join, recv the listener fd, open the
  child pidfd, serve_with_pidfd in a thread (self-terminating on child exit),
  wall-clock wait + rusage, fold cgroup accounting, and record the gate's
  socket verdicts in the run's EgressSummary. Arch-gated to x86_64/aarch64;
  refuses elsewhere.

Live-validated on aarch64 WSL2 (now that cgroup delegation is discovered): a
real `env run` under isolation=supervised of a Python program had socket(RAW)
and socket(AF_PACKET) DENIED with EPERM by the live supervisor, while
socket(AF_INET, SOCK_STREAM) was ALLOWED. New capability-gated integration test
asserts exactly this; updated the obsolete stub test to check the v1 egress
refusal instead.

net.mode=deny gives an airtight empty netns (no egress). The net.egress domain
allowlist (build_nft_ruleset output is ready) + openat2 path-allow are the
remaining increments.

Full suite (762 lib + integration) + clippy -D warnings green.

Adds live end-to-end coverage of the supervised tier's runtime enforcement, now
that it actually runs. Two real bugs surfaced and were fixed (this is exactly
what e2e tests are for):

- capture_manifest() returned the FIRST (oldest) capture via find(); a test with
  several runs in one env then checked stale evidence. Fixed to return the
  latest matching manifest (rfind) -- correct for every caller.
- The supervised e2e tests fork confined children (userns+netns+seccomp+notify);
  several running at once under cargo's parallel harness exhaust the host fork
  capacity and flake unrelated git subprocesses with EAGAIN. Serialized the
  heavy supervised tests with a poison-tolerant static mutex -- caps peak fork
  pressure without serializing the whole suite.

New coverage (capability-gated; skip cleanly without the full stack/python3):
- supervised_enforces_runtime_confinement: in one env, sequential runs proving
  the seccomp-notify socket gate (raw/packet/AF_UNIX denied, inet allowed), the
  airtight netns (no external connect under net.mode=deny), the Landlock FS
  allowlist ($WORK writable, /etc denied), the seccomp deny-list (unshare
  blocked, composed with the notify filter), and gate-verdict recording in the
  capture EgressSummary.
- supervised_memory_limit_is_enforced: a 400MiB alloc under a 64MiB cap does not
  complete.
- sandbox unit test: supervised builtin profile is confined + net.mode=deny and
  ranks Process < Supervised < Container.

Reliability verified: 6x the supervised set + 2x the full env_integration suite
(43 tests) all green; full suite (763 lib + integration) + clippy -D warnings
green.

Audit note: scanner may flag socket/syscall/unshare terms in the test fixtures
-- test assertions, not real escalation.

Benchmarks h5i's env feature against a reference set (container-use,
sandbox-runtime, OpenSandbox, E2B, Firecracker, zeroboot, branchfs): a
positioning summary, a 10-dimension comparison matrix, where h5i is distinctive
(provenance depth + shareability, denial observability, the propose/apply/
compare/rebase review loop, fail-closed rigor, the secrets broker), the honest
gaps (no microVM tier, L7-only container egress until supervised increment 2,
no pause/resume, Linux-only confined tiers), and borrow-worthy ideas mapped to
the roadmap (OpenSandbox L3/L4 + dynamic-policy egress; srt proxy-hardening +
dual-namespace anti-ptrace; zeroboot/Kata microvm tier; E2B ephemeral mode;
branchfs CoW workspace backend).

The entire h5i env feature (isolated agent sandboxes) was undocumented in both
the manual and the man page. Adds comprehensive coverage:

- MANUAL.md: a new 'h5i env' section -- the lifecycle commands table (create/
  run/probe/list/status/log/diff/inspect/compare/rebase/propose/apply/abort/gc),
  the four isolation tiers (workspace/process/supervised/container) with the
  fail-closed model, the .h5i/env.toml policy format (fs/net/resources/tools/
  env.pass/container.image + the rich [secret.NAME] form), the secrets broker
  (source/inject/redaction/fingerprint audit), and the cgroup-v2/rlimit resource
  limits. Plus a TOC entry and a new 'Sandbox' tab in the serve dashboard.
- man/man1/h5i.1: an 'h5i env SUBCOMMAND' section mirroring the above, a Sandbox
  dashboard bullet under serve, and a version/date bump to 0.1.7 / 2026-06-10.
  Renders clean (no new roff warnings).
- main.rs: --isolation help string now lists 'supervised' (was stale).

Reflects the secrets broker, cgroups v2, supervised tier, and Sandbox dashboard
added this cycle.

Inserts a new 'Agent Sandbox' section between Agent Radio (4.1) and Token
Reduction, renumbering the rest (Token Reduction 4.3, Context DAG 4.4, PR
Integration 4.5, Web Dashboard 4.6) and fixing the cross-reference anchor that
pointed at the old 4.2.

The section explains h5i env: a git worktree + fail-closed, digest-pinned policy
for running risky/untrusted agent work confined; the tiered, never-downgraded
isolation model (workspace/process/supervised/container); the propose/apply
review loop; and the boundary-pressure dashboard. New assets/agent-sandbox.svg
visualizes it -- an agent's command running inside the confined box, escape
attempts (read /etc/shadow, raw socket / off-allowlist host, mount/unshare/
ptrace) denied at the boundary on the FS/NET/PROC lanes while the legitimate
build is allowed and captured as reviewable evidence. Matches the repo's
existing dark-theme SVG style; verified well-formed and renders cleanly.

- assets/agent-sandbox.svg: 'cargo build' now sits on its own line inside the
  AGENT box (no border overflow); shortened the lane attempt/verdict text so
  'socket(RAW)' no longer crowds the deny mark; tightened the verbose subtitle/
  caption/footer; dropped the ambiguous outward deny-arrows so only the allowed
  work flows to evidence. Re-rendered to confirm a clean layout.
- README.md: added an intro question about running risky/untrusted work in a
  confined sandbox before it touches your tree; added the refs/h5i/env row to
  the Section 1 refs table (sandbox events/manifests/pinned policies).

h5i env create with no --isolation (or --isolation auto) now selects the
strongest tier the host can actually run (container>supervised>process>
workspace) instead of defaulting to the unconfined workspace tier --
secure-by-default. Each candidate is gated by the SAME checks create applies
(resolve + verify_exec), so a picked tier is guaranteed runnable; auto never
lands on a tier that would then fail at run time. Explicit --isolation <tier>
is unchanged: fail-closed, refused (never downgraded) if unmet.

- sandbox::effective_auto + IsolationRequest{Auto,Claim}; profile-declared
  isolation honored without probing; H5I_DEFAULT_ISOLATION pins a clone's
  default tier (and keeps tests deterministic); --isolation auto force-probes
  past it. container is only auto-picked when the profile sets an image.
- env::create resolves the claim via effective_auto; main.rs/mcp.rs map
  --isolation/auto to IsolationRequest.
- Tests: effective_auto honors declared tier, never picks an unrunnable tier,
  skips imageless container; integration: --isolation auto picks a tier that
  runs. Test helpers pin H5I_DEFAULT_ISOLATION=workspace for determinism.

Audit note: 'exec' matches are the verify_exec self-test name + comments, not
command execution.

`h5i env shell <name> [-- <cmd>]` opens an interactive, stdio-inherited session
INSIDE the environment, confined by the box itself. The shift: instead of the
agent choosing to wrap each command in `env run`, the whole session lives in the
sandbox, so every command it spawns is contained by construction. Defaults to a
login shell ($SHELL -i) when no command is given; the child's exit code passes
through transparently. Nothing is captured (it's interactive) — a single `shell`
event records that a session ran and its exit code.

Works at every tier, reusing each tier's confinement core with stdio inherited:
- container: podman run -i (+ -t only when a real TTY is on both ends), egress
  allowlist + secrets + cap-drop/read-only rootfs — the real agent-in-box.
- supervised: the seccomp-notify socket gate + netns + Landlock + cgroup, via
  run_supervised(interactive=true) (stdio inherited, output threads skipped).
- process: build_confined_command + cgroup, stdio inherited.
- workspace: plain inherited-stdio exec (trusted).

The profile wall-clock is not applied to an interactive session (the operator
owns it; container is wall-less, the kernel tiers keep their rlimits/cgroup).
Secrets are brokered and audited exactly as for `env run`.

- sandbox::run_interactive dispatches by tier; container::run_interactive +
  supervisor::run_interactive added; build_run_argv gains a tty: Option<bool>
  (None=capture run, Some(tty)=interactive -i/-t).
- env::shell brokers secrets, runs interactively, logs a redacted `shell` event,
  returns to idle. CLI: `h5i env shell`.
- Tests: build_run_argv interactive-flags (pure); env_shell_runs_in_box_and_
  passes_exit_code (runs in $WORK, exit code passes through, returns to idle).

Audit note: 'shell'/'exec'/'socket' terms are the feature's own names + the
seccomp socket-gate it reuses, not new command-execution surface.

isolation=supervised now enforces a net.egress domain allowlist as a genuine
L3/L4 guard (slirp4netns uplink + nftables default-drop + /etc/hosts DNS
pinning), not just the empty-netns net.mode=deny of v1. Strictly stronger than
the container tier's L7 CONNECT proxy: a raw socket can't bypass it.

How a supervised egress run is wired (all rootless):
- resolve_egress() resolves each host ONCE → nft dests + (host,ip) pins.
- A host helper thread spawns `slirp4netns --configure --disable-host-loopback
  <child-pid> tap0` for the child's netns and signals readiness (polls
  /proc/<pid>/net/dev for tap0). It is barrier-parked in read() at fork time so
  the single-threaded-fork invariant the pre_exec allocations rely on holds.
- The child (CAP_NET_ADMIN in its own userns), before Landlock/seccomp: unshares
  a private mount ns, bind-mounts a pinned /etc/hosts (hostname→pinned IP; NO
  port 53 opened at all), and applies the build_nft_ruleset default-drop
  allowlist via `nft -f` — raw syscalls only, no allocation in the forked child.
- So nft keeps CAP_NET_ADMIN across its execve, the egress child is mapped to
  root-in-userns (the map still points at the real host uid, so $WORK files stay
  owned by us). Non-egress tiers keep the 1:1 uid map, unchanged.

Why it can't be bypassed: the untrusted program runs as userns-root with
CAP_NET_ADMIN, but the seccomp socket gate denies AF_NETLINK, so it cannot open
the netlink socket nft/ip need to rewrite the ruleset or routes. The socket gate
and nftables compose as designed (defense-in-depth).

Live-proven on aarch64 WSL2 (allowlist = example.com): the allowlisted host
connects; a non-allowlisted host fails closed ("Could not resolve host" — no DNS
channel); `nft flush ruleset` fails with "Unable to initialize Netlink socket:
Operation not permitted"; the denied host stays blocked afterward.

- build_confined_command gains an Option<EgressJail>; +CLONE_NEWNS and the
  conditional root-map live in pre_exec. supervisor::{resolve_egress, setup_egress,
  EgressNetns} own the temp files / pipes / helper / slirp lifecycle (teardown on
  Drop). run()/run_interactive() preflight: fail closed if slirp4netns is absent
  or nothing resolves.
- Tests: resolve_egress unit test; run_egress_fails_closed_when_unsupported;
  opt-in e2e supervised_egress_allowlist_confines_to_pinned_hosts (H5I_TEST_NET=1).

Audit note: socket/exec/mount/nft/netlink/CAP_NET_ADMIN terms are this feature's
own confinement mechanism (the egress guard it installs), not new attack surface.

… egress

Document this session's three env features across all user-facing docs:
- env create auto-picks the strongest runnable isolation tier by default
  (secure-by-default); H5I_DEFAULT_ISOLATION pins a clone's default.
- env shell: interactive confined agent-in-box session.
- supervised net.egress is now a real L3/L4 allowlist (slirp4netns uplink +
  nftables default-drop + /etc/hosts DNS pinning), unbypassable via the socket
  gate's AF_NETLINK denial — replacing the old 'refused in v1' note.

Adds the env shell lifecycle row, the H5I_DEFAULT_ISOLATION / H5I_SECRET_<NAME> /
H5I_TEST_NET env-var entries, and updates the isolation-tier tables in all three.

Lead with the four commands a human actually runs (create -> shell -> diff ->
apply) instead of the agent/env-run narrative, and surface the audit commands
(env log / inspect / compare + the dashboard's boundary-pressure scoring) as a
first-class step. env run is demoted to a one-line aside; the isolation-tier
table moves to supporting reference at the end.

Drop the metaphor heading and unclear jargon per review:
- heading -> 'a confined, fully auditable environment'
- remove 'fail-closed' (explain plainly: 'h5i refuses rather than quietly
  running with less'), 'by construction', 'tamper-evident', 'boundary pressure'
- describe the policy in concrete terms (what code can read/write/reach) and the
  audit commands in plain words (output, exit code, policy enforced, redactions).

Discoverability gap from auto-pick: when 'h5i env create' (no --isolation)
silently lands on a kernel tier because rootless Podman isn't installed, the user
never learns the container tier (the one with a network egress allowlist) exists
or that Podman unlocks it. Add a one-line tip on the auto path when the picked
tier is workspace/process/supervised and no container runtime is present:
how to enable it (install Podman + set container.image) and where to look
(h5i env probe). No tip when the user pinned a tier or Podman is already present.
Also add 'h5i env shell' to the create 'next' hint.

Update the design/comparison docs now that supervisor increment 2 (the
net.egress L3/L4 allowlist) is shipped:

- environments-design.md: status header now lists the supervised tier (airtight
  rootless L3/L4 egress), secure-by-default auto-pick, and env shell as
  implemented; process-tier network notes, the rollout 'phase 6', and the
  'Supervisor scope' open question are marked resolved/shipped (not future).
- comparison.md: egress matrix row updated to the real L3/L4 allowlist; new
  distinctive point on un-bypassable rootless egress (AF_NETLINK denial); the
  'behind' egress gap reframed as the remaining *dynamic* policy nicety; ideas
  + bottom line updated.

supervisor-design.md was already updated when increment 2 landed; the guides/
features/workflows pages and index.html have no env content.

Surface the env sandbox across the docs site, matching each page's pattern:
- landing index.html: a new #sandbox deck section (terminal egress demo +
  create/shell/audit feature cards)
- features/: a 9th feature card (Agent sandbox)
- workflows/: a 'Run risky work in a sandbox' section (create → shell → diff →
  log → apply terminal)
- pitch/: a new slide (auto-counted by the deck JS) — tiered isolation + the
  egress allow/deny/can't-undo terminal
- blog/: a new post 'An Auditable Sandbox for AI Agents'
  (/blog/agent-sandbox-env/) — the loop, tiered isolation table, the airtight
  rootless egress allowlist and why it can't be bypassed, and the audit story;
  wired into the blog index card list + JSON-LD + sitemap.xml

Validated: sitemap XML parses, blog JSON-LD parses, new post tags balance.

Leaves the two action cards (create/shell, diff/log/apply) beside the terminal
demo; the isolation detail was redundant with the demo and the intro line.

Add a sixth row to the problem list — 'While it ran, could it read your secrets
or call out to the network? → git can't contain' — so the page raises the gap
that the Agent Sandbox section answers. Broaden the heading from 'AI review' to
'AI agents need more than Git can give' to cover both provenance and containment,
and update the sub to 'six gaps Git was never built to fill'.

Replace '4 Tiers / SANDBOX ISOLATION' with the feature name as the value and a
label that mirrors the landing section's own framing ('a confined, fully
auditable agent sandbox'). Avoids an unbacked safety multiplier; stays honest
alongside the grounded stats (95% token, 3.5x PR, 1.8x loop).

The Agent Sandbox is now a headline section but was invisible to search and
social cards. Add it to: meta description + keywords (ai agent sandbox, agent
isolation, network egress allowlist, rootless sandbox, landlock seccomp),
og:description, twitter:description, the SoftwareApplication JSON-LD
description, and a new 'Can h5i sandbox an AI agent's commands?' FAQ — added to
both the visible <details> list and the FAQPage JSON-LD, kept in sync (7/7).

A single hand-written fragment shader (no Three.js, no deps): domain-warped
value-noise drifting in the red/ember palette, blended additively (CSS
mix-blend-mode: screen) over the dark page so black areas are a no-op, masked to
the top where the existing hero-glow sits.

Cost is negligible and bounded: +2.2 KB gzipped, zero new HTTP requests; render
scale 0.7 + DPR cap 1.25 + ~30fps; paused when off-screen (IntersectionObserver)
and on tab blur; a single static frame under prefers-reduced-motion; and it
degrades to nothing (the CSS glow remains) when WebGL is unavailable.

container tier: brokered secrets and env.pass values were passed to
podman as --env KEY=VALUE on the command line, exposing them in the
host process list (/proc/<pid>/cmdline, world-readable by default) and
defeating the secrets broker's keep-values-off-the-record design. Pass
--env NAME by name only and forward the value through podman's own
environment so credentials never appear in argv.

env create: agent-identity validation only rejected '/' and '\', but
the upstream charset check admits '.', '..', and leading-dot names. The
agent flows unchecked into env_dir() (a raw path join: '..' escapes the
env root) and the git ref / worktree name. Add validate_agent (rejects
empty, '..', leading '.', '.lock', separators, >64, off-charset).

The process tier unshared NEWUSER/NEWIPC/NEWUTS (+NEWNET) but never a PID
namespace, even though design §5 lists CLONE_NEWPID as a process-tier
primitive. Consequence: confined code shared the host PID namespace and
host procfs, so it could read /proc/<pid>/environ of same-uid host
processes — including the h5i parent that holds the operator's whole
environment — leaking host secrets and defeating the env.pass allowlist,
and could signal host processes.

build_confined_command gains a pidns flag (process tier on; supervised
stays off — it has its own seccomp-notify/netns/pidfd model). When set:

- pre_exec forks (CLONE_NEWPID only affects the next child): the parent
  becomes a thin supervisor that reaps the workload and mirrors its
  exit/signal to the waiter (re-raises on signal death so wait_loop still
  reports a signal; the wall-clock SIGKILL reaches both via the pgroup).
  The child is PID 1 of the new namespace.
- CLONE_NEWNS + mount a private procfs over /proc (a new pidns alone does
  not hide host pids — procfs reflects the mounter's pidns).
- The pre-fork Landlock grant pins the host procfs inode, which the fresh
  mount shadows, so the child re-grants read on the new /proc before
  restrict_self (otherwise every confined command that touches /proc
  breaks).
- The workload is forked before the host-side cgroup.procs write, so the
  supervisor joins the workload to the run cgroup itself (path passed in).
  Without a cgroup, rusage would be the supervisor's, so rss/cpu are
  reported as unknown; rlimits still enforce the caps. Hosts that cannot
  mount the procfs fail closed at create via verify_exec (auto-pick falls
  back to workspace).

Tests (capability-gated): a host process holding a secret in its env is
unreadable from inside the box (with a control proving the same-uid host
read succeeds), the workload is PID 1 of a fresh namespace, it sees only
its namespace's pids, and /proc/self is still readable (re-grant works).

Add a 'Security posture — an honest read (untrusted-code threat model)'
section to docs/comparison.md: the shared-kernel vs separate-kernel split
decides everything, so all runnable h5i env tiers (process, container) are
categorically weaker than the microVM/gVisor class (Firecracker, E2B,
zeroboot, Kata, gVisor) for hostile code — by design, those tiers are
reserved but not built — and roughly on par with shared-kernel peers
(sandbox-runtime, Docker tooling), slightly behind srt's allow-list/proxy
defaults. Records the residual process-tier items (seccomp deny-list vs
allow-list, the clone(CLONE_NEWUSER) gap, RLIMIT_AS fallback) and that the
audit was one focused pass, not a security proof. Also mark the nested PID
namespace + private procfs as shipped in the ideas-to-borrow list.