diff --git a/docs/airlock-v2-design.md b/docs/airlock-v2-design.md
new file mode 100644
index 0000000..07e4f74
--- /dev/null
+++ b/docs/airlock-v2-design.md
@@ -0,0 +1,1653 @@
+# Airlock v2 — design proposal
+
+One daemon per user with sessions, a runtime directory outside the
+project, layered config, and approval of project config.
+
+**Status:** proposal. The blocking items in [Open questions and
+follow-ups](#open-questions-and-follow-ups) are resolved. Nothing here is
+implemented yet. Today's behavior is
+described in [ARCHITECTURE.md](../ARCHITECTURE.md) and
+[SECURITY.md](../SECURITY.md).
+
+This document is the design record: what changes, why, and which
+alternatives were rejected. The user-facing surface (commands and their
+options, messages, harness hooks, and the examples) is in
+[airlock-v2-ux.md](airlock-v2-ux.md). Its changes U1–U16 to this design are
+accepted and incorporated here, except U14, which is
+[planned for v2.1](#planned-for-v21). When it ships, the user-facing reference
+will be [README.md](../README.md) and [SKILL.md](../SKILL.md).
+
+The choice of one daemon per user is re-examined against a future central
+daemon in [airlock-v2-topology.md](airlock-v2-topology.md). Its proposals
+are not folded in yet. The protocol and data model shapes that keep that
+path open while implementing this design are in
+[airlock-v2-technical-guidance.md](airlock-v2-technical-guidance.md).
+
+## Problem
+
+Two separate problems share one fix: the project directory should hold only
+config, and no runtime state or trust decisions.
+
+**Runtime files live in the project.** The daemon writes `airlock.sock`,
+`airlock.pid` and `airlock-ca.pem` next to `airlock.toml`, in the sandbox
+root. That directory is read-write for the agent and for every tool
+([src/policy.rs](../src/policy.rs), `sandbox_root` is always in
+`read_write_paths`). So:
+
+- The agent or any tool can delete or replace the socket, the PID file or
+  the proxy CA certificate while the daemon runs. Replacing the CA only
+  breaks proxy tools. It exposes no credential, because the tool→proxy leg
+  carries none. It is still tampering we should not allow.
+- The files show up in `git status`. Every project needs `.gitignore`
+  entries for them, and they are easy to commit by accident.
+
+**There is one config file, and it is shared.** `airlock.toml` is checked in
+and describes the team's tools. It also has to say where each secret comes
+from, and that is personal: one user reads `GH_TOKEN` from 1Password,
+another from `gh auth token`. A user who wants an extra tool of their own
+has nowhere to put it except the shared file.
+
+Layering personal config over shared config raises a trust question that
+does not exist today: the shared file is written by whoever can land a PR,
+and by the agent itself. Today Airlock simply trusts whatever
+`airlock.toml` says at daemon start.
+
+## Goals
+
+- Socket, PID file and CA certificate live outside the project directory,
+  in a per-user location the agent and tools cannot write.
+- A user can layer personal config over the repo's config: bind secret
+  sources, add personal tools, adjust the agent sandbox.
+- The daemon never acts on a project config file the user has not
+  approved. That includes a file the agent edited. Editing is allowed and
+  sometimes useful, but the user reviews the diff and approves it again.
+- No sandbox, the agent's or a tool's, can write the approval record, the
+  global config or the runtime directory, or redirect Airlock to a copy it
+  wrote.
+
+## Non-goals
+
+- Backwards compatibility. Airlock is pre-1.0. Old in-project runtime files
+  are not migrated; users delete them.
+- Applying config changes to a running session on their own. A running
+  session keeps its config until the user reloads it with
+  [`session reload`](#reloading-a-session).
+- Protecting against an agent that runs outside `airlock run`. Such an agent
+  is the user, as far as the OS is concerned.
+- Protecting against agent-written code that the user runs outside the
+  sandbox: git hooks, `core.fsmonitor`, `.envrc`, mise hooks, build scripts,
+  tests. That code runs as the user and can rewrite any anchor, but it can
+  equally read the user's credentials directly, so it defeats Airlock's core
+  promise before it reaches the trust store. See [B1](#blocking).
+- A network transport. This proposal implements Unix sockets only, but
+  keeps the protocol free of anything that would rule out TCP later (see
+  [Transport](#transport)).
+
+## Overview
+
+- **One daemon per user**, serving every project through
+  [sessions](#sessions). A launcher in the user's terminal (`airlock run`,
+  `airlock session start`) loads and approves a project's config, resolves
+  its secrets, and registers a session. The agent gets a session token, and
+  the daemon serves it only that project.
+- **Runtime dir:** `/run/user/<uid>/airlock/` on Linux, the per-user temp
+  dir from `confstr` on macOS. Neither comes from the environment. The
+  directory is owned by the user and has mode 0700.
+- **Three config layers**, lowest to highest precedence:
+  1. **global:** `$XDG_CONFIG_HOME/airlock/airlock.toml`
+  2. **repo:** `airlock.toml` in the project root
+  3. **local:** `airlock.local.toml` in the project root (gitignored)
+- **Trust:** the repo and local files must each match a byte-for-byte copy
+  the user approved with `airlock trust`. The global file needs no approval.
+- **Anchors:** the trust store, the global config and the runtime dir are
+  refused if they sit where the agent can write.
+
+## Runtime directory
+
+### Location
+
+| Platform | Base | Fallback |
+|---|---|---|
+| Linux | `/run/user/<uid>/airlock`, when `/run/user/<uid>` exists, is owned by the uid and has mode 0700 | `/tmp/airlock-<uid>` |
+| macOS | `confstr(_CS_DARWIN_USER_TEMP_DIR)` + `airlock` | none |
+
+The base ignores `TMPDIR` and `XDG_RUNTIME_DIR`. Both vary between shells of
+the same user: agent harnesses, Nix shells and tmux change `TMPDIR`, and
+`sudo -u`, cron and some ssh and container setups leave `XDG_RUNTIME_DIR`
+unset. A base taken from either would let two shells disagree about where the
+daemon lives (see [B6](#blocking)).
+
+The daemon is per user, so the base holds one set of files:
+
+| File | Purpose |
+|---|---|
+| `airlock.sock` | client socket |
+| `airlock.pid` | PID file |
+| `admin.token` | credential for registering [sessions](#sessions), mode 0600, unreadable from every sandbox |
+| `ca/<session-id>.pem` | a session's proxy CA certificate, when its config has a proxy tool |
+
+Both bases are per-user and cleared on reboot, which suits a socket and a PID
+file. The paths are short enough for `sun_path`: the canonical macOS
+per-user temp dir is about 52 bytes, so the socket path comes to about 75 of
+the 104 allowed bytes.
+
+The Linux fallback sits in shared `/tmp` under a predictable name. Another
+user who creates it first only makes the validation below fail, so the
+daemon refuses to start, and it gains no access. A config that grants write
+access to `/tmp` is refused on a system that uses the fallback, by the
+[anchor check](#protecting-the-anchors).
+
+### Validation
+
+The daemon creates `<base>` and `<base>/ca` with mode 0700. Before using
+either, whether it just created it or found it, it checks with `lstat` that:
+
+- it is a directory, not a symlink,
+- it is owned by the effective uid,
+- `mode & 0o077 == 0`.
+
+If any check fails, the daemon refuses to start and names the directory and
+the failed check. The existing post-bind socket mode check
+([src/daemon.rs](../src/daemon.rs)) stays.
+
+The runtime base is also one of the [anchors](#protecting-the-anchors), so
+it must not fall under any sandbox write grant.
+
+### Sandbox access
+
+| Who | Needs |
+|---|---|
+| Agent (`airlock exec`, `airlock tools list`, `airlock agent check` inside `airlock run`) | connect to `airlock.sock`; never read `admin.token` |
+| Proxy tools | read their own session's `ca/<session-id>.pem`, a new entry in their `read_paths` |
+| Ordinary tools | nothing |
+
+No sandbox gets write access to the runtime dir.
+
+- **macOS:** the Seatbelt baseline grants read-write to all of `$TMPDIR`
+  ([src/sandbox.rs](../src/sandbox.rs), "$TMPDIR (per-session scratch)"),
+  which is normally the same directory as the base. Every profile, agent and
+  tool, therefore ends with `(deny file-write* (subpath "<base>"))` and
+  `(deny file-read* (literal "<base>/admin.token"))`. Tools keep their
+  scratch space but cannot write Airlock's subtree or register sessions. The
+  denies are the **last** rules in the profile: in SBPL the last matching
+  rule wins, so any allow emitted after them would re-allow the path. That
+  includes `agent.filesystem.write`, `extra_write`, `--allow-write` and
+  built-in profile rules.
+- **Linux:** Landlock is allow-only and cannot carve a subtree out of a
+  grant. Neither `/run/user/<uid>` nor `/tmp` is granted by default, and
+  the anchor check refuses any config or `--allow-write` that would grant
+  the base.
+
+### Stale state and migration
+
+Stale-state cleanup works as today (`check_and_cleanup_stale_state`), but in
+the runtime dir. Nothing looks for runtime files in the project directory
+any more. Users delete leftover `airlock.sock`, `airlock.pid` and
+`airlock-ca.pem`, and the matching `.gitignore` lines.
+
+## Config layers
+
+### The three files
+
+| Layer | Path | Approved? | Who writes it |
+|---|---|---|---|
+| global | `$XDG_CONFIG_HOME/airlock/airlock.toml` (default `~/.config/airlock/airlock.toml`, on macOS too) | no | the user |
+| repo | `<root>/airlock.toml` | yes | the team, PR authors, the agent |
+| local | `<root>/airlock.local.toml` | yes | the user, the agent |
+
+The local file sits in the project directory, where the agent can write, so
+it is approved exactly like the repo file.
+
+### Discovery
+
+Discovery walks up from the working directory to `$HOME` (inclusive), as
+today. The first directory holding an `airlock.toml` **or** an
+`airlock.local.toml` owned by the effective uid is the project root. Either
+file marks the project, so Airlock can be used in a repo whose team has not
+adopted it. The project root is the sandbox root, with the same meaning as
+now.
+
+With no project file found, Airlock fails as today, however much global
+config exists.
+
+### `--config <path>`
+
+Exactly that one file: no global layer and no local layer. The project root
+is the file's parent directory, as today. The file still has to be approved.
+
+`--config` is not a global option. It exists only on the commands that
+discover config: `run`, `trust`, `config`, `status`, `session start` and
+`session reload`. `exec` and `tools list` use their session and read no
+files, so a `--config` there would be a silent no-op.
+
+### `--no-project-config`
+
+This replaces `airlock run --no-config` and `AIRLOCK_SANDBOX_ROOT`. The
+empty-config mode those provided is removed.
+
+- Valid wherever discovery runs: `run`, `config`, `status`,
+  `session start` and `session reload`. `exec` and `tools list` do no
+  discovery, since they use their session.
+- Ignores `airlock.toml` and `airlock.local.toml` even if present.
+- The project root is the canonical working directory. The config is the
+  global layer alone, which may be absent (an empty config).
+- With no repo or local file, there is nothing to approve.
+- The agent finds the daemon through its [session](#sessions), as in every
+  other mode, so a working directory that moves does not matter.
+
+### Merge rules
+
+Each layer is parsed on its own, then the layers are merged, then the
+existing validation runs on the merged result. For example, "a proxy tool
+must not hold a secret" is checked against the merged tools.
+
+| Item | Rule |
+|---|---|
+| `[tools.<name>]` | See [Tools across layers](#tools-across-layers). |
+| `[secrets.<label>]` | See [Secret labels across layers](#secret-labels-across-layers). |
+| `filesystem.read`, `filesystem.write` | union |
+| `agent.passthrough_env` | union |
+| `agent.filesystem.read`, `agent.filesystem.write` | union |
+| `agent.env.<VAR>` | per key, highest layer wins |
+| `timeout`, `agent.timeout` | highest layer that sets it |
+| `allow_home_root` | Honored in global or local. In the repo layer it is a config error. |
+
+### Tools across layers
+
+A tool replaces another only where an approved file says so, or where the
+user's own global tool gives way to the project.
+
+- **Global and project.** A project tool (repo or local) replaces a global
+  tool of the same name. The global layer is the user's default for every
+  project, and a project that declares the same tool knows what it needs.
+  The replacement is not silent: `airlock config` shows the global tool as
+  `replaced by repo`, and `run -v` prints it.
+- **Repo and local.** A duplicate is a config error naming both files,
+  unless the local tool says `override = true`. Then the local tool
+  replaces the repo's whole, and the user approves that line with the local
+  file. `override = true` on a tool the repo does not define is a config
+  error, so a stale override cannot linger unnoticed.
+- **Never the reverse.** The global layer cannot replace a project tool,
+  and the repo layer cannot replace a local one. A personal tool must not
+  silently shadow a team tool, and the global file is not approved.
+
+### Secret labels across layers
+
+A secret reference crosses layers only where the user says so in an
+approved file.
+
+- **Repo items** (tools, `agent.env`) may reference only labels the repo
+  layer declares. In the repo layer `source` is optional: a label without
+  one says "this project needs `GH_TOKEN`" and leaves the binding to the
+  user.
+- **Global items** may reference only global labels.
+- **Local items** may reference any label.
+- **The local layer binds repo labels.** A local `[secrets.<label>]` for a
+  label the repo declares replaces the repo's spec whole, either with its
+  own `source` or with `from = "global"`, which uses the global binding of
+  the same name. `from` and `source` are mutually exclusive.
+- **The global layer never serves a repo label on its own.** A global
+  `[secrets.GH_TOKEN]` and a repo `[secrets.GH_TOKEN]` are two separate
+  bindings until the local file links them.
+- A repo label with no source and no local binding is a startup error that
+  lists each such label and points to `airlock init --local`.
+- `[secrets.<label>]` takes an optional `description` in every layer. A
+  repo label without a source is a request to each user, and the
+  description tells them what to supply. The startup error and
+  `init --local` show it.
+
+`airlock init --local` writes `airlock.local.toml` with a stub per repo
+label that has no source. A label the global layer binds gets
+`from = "global"`; any other gets commented `command` and `env` examples
+under its description. In a repo without an `airlock.toml`, whose team has
+not adopted Airlock, it writes a standalone skeleton instead: a commented
+secret and tool, as `init` writes for `airlock.toml`. The stub is an
+ordinary local file: the user approves it like any other.
+
+`init --local` warns if git does not ignore the file. The warning suggests
+adding `airlock.local.toml` to git's global excludes file
+(`~/.config/git/ignore`, or `core.excludesFile`) once, which covers every
+repo, including those whose `.gitignore` the user does not own. This only
+prevents an accidental commit; it is not a control, and the file holds
+references, not secret values.
+
+The opt-in is what the user approves. A PR that adds a tool taking
+`OPENAI_API_KEY` gets the repo's own binding, or none. It gets the user's
+1Password entry only after the user approves a local line that says so.
+
+```toml
+# airlock.local.toml
+[secrets.GH_TOKEN]
+from = "global"
+```
+
+**Relative paths.** Paths in the repo and local layers resolve against the
+project root, as today. A relative path in the global layer is a config
+error: the file applies to every project, so a relative path would mean
+something different in each. `~`, `{sandbox_root}` and `{tool_state}` work
+in all layers.
+
+### Tool state outside the project
+
+Many tools need a writable config directory (`GH_CONFIG_DIR`,
+`CLOUDSDK_CONFIG`, `KUBECONFIG`). Pointing it at `{sandbox_root}/.config/…`
+keeps the user's real config out of the tool sandbox, but puts tool state
+in the project, where the agent can read it and git sees it.
+
+`{tool_state}` in a tool's static `env` resolves to
+`$XDG_CACHE_HOME/airlock/<id>/<tool>` (default
+`~/.cache/airlock/<id>/<tool>`), where `<id>` is the project id from the
+[trust store](#trust-store). The daemon creates it with mode 0700 on first
+use and adds it to that tool's write paths. No other tool and no agent
+sandbox is granted it. Like an anchor, it is refused if it resolves inside
+the project root, so a redirected `XDG_CACHE_HOME` cannot move it there. It
+must not overlap an anchor either.
+
+```toml
+[tools.gh.env]
+GH_TOKEN      = { secret = "GH_TOKEN" }
+GH_CONFIG_DIR = "{tool_state}"
+```
+
+## Trust
+
+### What is approved
+
+- **The repo and local files, each on its own.** A file is approved when its
+  current bytes equal the copy recorded by `airlock trust`. This is the
+  whole file: an edited comment needs approval again too.
+- **The `--config` file.** Same rule.
+- **Not the global file.** It is the user's own file, outside every
+  project. It is protected by the [anchor checks](#protecting-the-anchors)
+  instead.
+
+### Trust store
+
+```
+$XDG_STATE_HOME/airlock/trust/<id>/     (default ~/.local/state/airlock/trust/<id>/, mode 0700)
+    root                  canonical project root
+    airlock.toml          approved copy of the repo file
+    airlock.local.toml    approved copy of the local file
+    <name>.toml           approved copy of a --config file named <name>.toml
+```
+
+Each copy is stored under the approved file's name. Every approved file sits
+in the project root, since `--config` makes the file's parent the root, so
+`<id>` plus the name identify the file's canonical path. A `--config` file
+that is itself named `airlock.toml` in a project root is the repo file and
+shares its slot.
+
+`<id>` is the first 16 hex characters of the SHA-256 of the canonical
+project root. The stored copy is the record: the check compares SHA-256 of the current bytes with SHA-256 of the
+copy. Keeping the copy instead of just a hash is what makes the refusal able
+to show a diff.
+
+A project that moves to a new path gets a new `<id>` and needs approval
+again.
+
+### When approval is checked
+
+Wherever config is loaded for a session, and that is only in a launcher:
+`airlock run`, `session start` and `session reload`. The daemon itself
+never reads project config.
+
+- **In the user's terminal.** The launcher checks approval before it
+  registers the session, so the prompt or refusal and the diff reach the
+  user directly.
+- **No gap between check and use.** Each file is read once with
+  `read_config_securely`. The same bytes are hashed, compared and parsed,
+  and the parsed result is what the launcher registers.
+- **Validation first.** The launcher parses and validates the merged
+  config before it asks about any file, so the user is never asked to
+  approve a file that would fail anyway.
+
+`exec` and `tools list` use a session whose config was approved when it
+started or was last reloaded, so they do not check again.
+
+### Unapproved files at session start
+
+If any layer is unapproved, the launcher shows, for each such file, either a
+unified diff against the approved copy or, for a file never approved, its
+full contents. Then:
+
+- **On a terminal**, it asks `Trust this version and continue? [y/N]`, one
+  file at a time. `y` records the approval exactly as `airlock trust` does
+  and continues. `n` on any file stops the launcher before anything
+  starts, and it exits 125 with `not trusted; nothing started`, as for
+  any other reason Airlock did not start the agent.
+- **On a non-terminal**, it refuses, exits 125 and points to
+  `airlock trust`. Startup stays non-interactive for scripts.
+
+The prompt is exactly as safe as `airlock trust`. The control is that no
+sandbox can write the trust store and no sandbox can run a launcher, not
+the terminal: an agent with a pty can answer a prompt too. Without the
+prompt, refuse, `trust`, run again would be three commands for one
+decision, on the most common path: every edit of the user's own local file
+goes through it.
+
+The printed text is escaped before output: control characters, ANSI escapes,
+bidirectional overrides (U+202A–U+202E, U+2066–U+2069) and zero-width
+characters are shown as `\u{…}`. TOML accepts bidi and zero-width characters
+in strings and comments. Without escaping, an agent could write a diff that
+reads differently from what it does.
+
+A `from = "global"` line approves a link to a binding the prompt does not
+otherwise show. So the prompt annotates each such line with the global
+source it resolves to at that moment:
+
+```
+ [secrets.GH_TOKEN]
+ from = "global"       # → global: command op read op://Private/GitHub/token
+```
+
+The annotation is display only. It is not part of the approved bytes, so a
+later change to the global binding needs no new approval: the global file
+is the user's own.
+
+### `airlock trust`
+
+1. Discovers the same layers a session start would. It honors `--config` and
+   refuses `--no-project-config`, since there would be nothing to approve.
+2. For each repo or local file that differs from its approved copy, prints
+   the escaped diff (or the full file) and asks `Trust <path>? [y/N]`.
+3. On `y`, writes the exact bytes it showed to the trust store: a temp file
+   and `rename` in the same directory.
+4. If sessions for this project are running, names them and says that
+   they keep the previous config until `airlock session reload`.
+
+On a non-terminal, it refuses unless `--yes` or `--expect-sha256` is
+given.
+
+- `--yes` approves every changed file without prompting, for scripted
+  setup.
+- `--expect-sha256 <hash>` (repeatable) approves a changed file only if
+  its SHA-256 equals one of the given hashes, and fails otherwise. This
+  pins the exact content a script or workflow expects.
+
+In CI the trust store is usually empty on every run, so each run is a
+first approval. `trust --yes` there means the review of the commit under
+test is the approval, and it must run before any agent starts in the job,
+so an agent's edit in the same job is never approved. `--expect-sha256`
+removes even that window.
+
+`trust` exists to approve ahead of time and from scripts. Launchers ask the
+same question when they need to.
+
+### After approval
+
+A running session keeps the config it had. The session records the
+SHA-256 of every layer it loaded, including the global file. `airlock status`
+and `session list` compare those with the files on disk and mark a session
+`config changed` when they differ. So does `exec` when it refuses an
+undeclared tool, and `agent check`, so the agent can tell the user. Starting
+a new session picks up the approved config, and so does reloading a running
+one. The daemon does not restart.
+
+### Reloading a session
+
+`airlock session reload [ID…]` applies approved config to running sessions,
+so an agent that added a tool can use it without being restarted and losing
+its context. Without IDs it reloads every session for the project in the
+current directory.
+
+The reload is a launcher: it discovers, validates and approves the config,
+prompting as at session start, and resolves the secrets in the user's
+terminal. It then sends a `Reload` request with the admin credential. The
+daemon builds the new redactor, policy and proxy, and swaps them into the
+session in one step. The session keeps its id and token, so the agent keeps
+working. It prints what changed per session, such as `tools +psql`.
+
+- **Discovery comes from the session, not the current directory.** Each
+  session records its root and mode (default, `--config <path>`,
+  `--no-project-config`), and the reload loads exactly that again. IDs
+  select sessions; the current directory only picks the default set.
+- **The agent's own settings do not change.** The agent's sandbox profile,
+  `agent.env`, `agent.passthrough_env`, `agent.filesystem` and
+  `agent.timeout` were applied when the agent process started, and a
+  running process cannot get a new sandbox. The reload applies everything
+  else (tools, secrets, filesystem grants for tools, proxy routes,
+  timeouts) and prints `agent settings changed; restart the agent to apply
+  them` for a session whose `[agent]` differs.
+- **An `exec` in flight finishes on the config it started with.** Each
+  request takes its own reference to the session's state, so a swap never
+  changes a running tool.
+
+Tools change only when the user asks: the reason running sessions keep
+their config holds.
+
+## Sessions
+
+One daemon per user serves every project. A session binds a client to one
+project: its root, its approved config and the secrets resolved for it. The
+daemon authenticates clients by uid, and the agent runs as the user, so the
+socket alone proves nothing ([B4](#blocking)). `exec`, `tools list` and
+`agent check` are served only with a session token, and only a process
+outside every sandbox can register a session.
+
+### Admin credential
+
+At start, before the readiness signal, the daemon writes 32 random bytes to
+`<base>/admin.token` with mode 0600. A restart replaces it. No sandbox can
+read it: Landlock never grants the runtime dir, and every Seatbelt profile
+denies it (see [Sandbox access](#sandbox-access)). Session registration and
+reload, `session list`, `session revoke`, `tools list --session`, `status`,
+`daemon logs`, `daemon stop` and `daemon restart` need it. `exec`,
+`tools list` without `--session` and `agent check` never read it.
+
+### Registering a session
+
+The launcher (`airlock run` or `session start`) does
+everything that needs the user's terminal or the project's environment, and
+then hands the result to the daemon:
+
+1. Discovers the layers from the current directory, checks approval and
+   merges them, as in [Trust](#trust).
+2. Resolves every secret the config uses. `source = "command"` runs here, so
+   a 1Password or `gcloud` prompt reaches the user. `source = "env"` reads
+   the launcher's own environment. This is what `synchronous_startup` does
+   today.
+3. Builds the [filtered `PATH`](#blocking) (B2) and an environment snapshot
+   of the launcher, without the variables consumed by `source = "env"`.
+4. Starts the daemon if none is running (see [Lifecycle](#lifecycle)).
+5. Sends a `Register` request with the admin credential: the root, the
+   merged config, the layer hashes, the secret values, the snapshot, the
+   filtered `PATH`, a name, and the agent's sandbox kind. The daemon builds
+   the session's redactor, policy and proxy, and answers with a session id
+   and a 32-byte random token.
+
+The name is what `session list`, `trust` and `reload` show. `--name` sets
+it; the default is the harness command's base name, or `shell` for
+`session start`. The sandbox kind is `airlock` for `airlock run` and
+`external` for `session start`. It decides what the
+[harness hook](#agent-integration) tests.
+
+The daemon also records the session's [anchor process](#token-binding):
+the peer PID of the `Register` connection for `run`, and that process's
+parent, the user's shell, for `session start`. It takes the PID from the
+socket, not from the request.
+
+The launcher holds secret values in `Secret<T>` and drops them once
+`Register` succeeds. Refresh commands run later in the daemon, with the
+session's snapshot and filtered `PATH`, never the daemon's own environment.
+
+### Commands
+
+| Command | Does |
+|---|---|
+| `airlock run [-- <harness…>]` | Registers a session, runs the harness in Airlock's agent sandbox with `AIRLOCK_ADDR` and `AIRLOCK_SESSION` set, and holds the session's [lease](#lifetime) until the harness exits. |
+| `airlock run --no-session -- <harness…>` | Airlock's sandbox only. No session and no daemon; `exec` and `tools list` fail inside it as they do anywhere without a session. |
+| `airlock session start` | Registers a session and prints the `export` lines, for a harness that `run` cannot start: an IDE extension, or a harness with its own sandbox. Ends after `--ttl` (default 12h; `0` means until revoked). |
+| `airlock session renew <ID> [--ttl]` | Restarts a `session start` session's TTL. The token stays the same, so the harness keeps working. |
+| `airlock session list` | Lists sessions: id, name, root, start time, number of `exec`s, whether the config changed, and what ends it (`held by airlock run, PID 4821` or `expires in 6h`). |
+| `airlock session reload [ID…]` | Applies approved config to running sessions. See [Reloading a session](#reloading-a-session). |
+| `airlock session revoke <ID…>` / `--here` / `--all` | Ends sessions without restarting the daemon. |
+
+Sessions are addressed by id, unique id prefix or unique name.
+
+`run` always runs the harness in Airlock's sandbox. A harness with its own
+sandbox, such as Claude Code with `--sandbox`, gets its session from
+`session start` like an IDE. Airlock's and Claude Code's Seatbelt profiles
+cannot nest, and a `run` mode without any sandbox would be one flag away
+from `claude --dangerously-skip-permissions` running bare. `run` no longer
+embeds a daemon of its own, so any number of agents can run in one project
+at the same time.
+
+`session start` prints, on stderr, that the harness's own sandbox must meet
+the [external sandbox requirements](#under-another-harness) (`-q` drops
+the note). Everything started from that shell inherits the token: in an
+editor, every extension and integrated terminal. An editor started from
+the Dock or a launcher, not from that shell, gets no session.
+
+### Scope
+
+The directory a session is started in decides what it can reach. Discovery
+runs from there as for every other command, and the session serves only
+that root's approved config. A subdirectory with its own `airlock.toml` is
+a separate project, and a session started there gets that project. The
+daemon takes the root and config from the session, never from the request,
+so an agent that changes directory keeps the scope it started with. The
+request's working directory must still lie under the session's root, as
+today.
+
+Sessions are independent. Two sessions for the same project resolve their
+own secrets and can run different approved configs, for example an old
+session next to a new one started after an approval, or a `--config` file
+next to the default one. The user notices one cost: a second session runs
+the secret commands again, so 1Password or `gcloud` prompts appear again,
+and a minted token is minted and refreshed once per session. Sharing
+secrets between sessions of one project may come later as an
+optimization.
+
+### Lifetime
+
+Sessions live in daemon memory only. A session ends when its owner goes
+away, when it is revoked, or when the daemon stops. A token that the agent
+stashed, or that a leftover background process still holds, stops working
+with it. Its secrets, redactor and proxy are dropped, and its CA file is
+deleted.
+
+Any number of processes use a session at once: every `exec` is its own
+connection, and the harness, its parallel tool calls and its subagents all
+hold the same token. The session is the unit of permission, not of
+identity, so the daemon keeps no list of attached clients. It keeps only
+what ends the session:
+
+| Started by | Ends when |
+|---|---|
+| `airlock run` | its lease closes |
+| `airlock session start` | its TTL runs out |
+
+**The lease.** `airlock run` keeps the connection it sent `Register` on
+open for as long as the harness runs. The daemon holds a task per lease
+that waits for EOF and then revokes the session. The kernel closes a
+process's descriptors however it dies, by exit, panic, SIGKILL or the OOM
+killer, so a launcher cannot die and leave its session behind, and a local
+socket needs no heartbeat.
+
+- The descriptor is close-on-exec, so the harness does not inherit it.
+  Otherwise the lease would last as long as any descendant of the harness,
+  and the agent would hold a connection admitted with `admin.token`.
+- The daemon accepts no further request on a lease connection. Reload and
+  revoke come over their own connections. A second request on a lease is a
+  protocol error and ends the session.
+- The launcher outlives the harness. It forwards SIGHUP, SIGINT and SIGTERM
+  to the harness, waits for it to exit, and only then closes. A closed
+  terminal sends SIGHUP to both, so the order holds.
+- Lease connections have no idle timeout.
+- The launcher sees EOF when the daemon stops, and prints that the
+  agent's session has ended in the user's terminal.
+
+A harness that outlives a SIGKILLed launcher loses its session. That is
+rare, and the harness is then an orphan nobody manages.
+
+**The TTL.** A `session start` launcher exits once it has printed the
+exports, so nothing holds a lease. The TTL is what ends a forgotten
+session; without it, the token would stay valid, and the automatic daemon
+would keep running, indefinitely. The default of 12 hours is one working
+day. `session renew` restarts it without changing the token, so an editor
+started from that shell keeps working. An `exec` on an expired session
+exits 125 with a message saying it expired and that the user can renew it
+with `airlock session renew`.
+
+### Token binding
+
+A session token is in the environment of every process the harness starts.
+A process of the same uid outside Airlock's sandbox can read another
+process's environment: through `KERN_PROCARGS2` (`ps eww`) on macOS, and
+`/proc/<pid>/environ` on Linux. So an agent under an external sandbox that
+allows process inspection, or any unsandboxed process of the user, can
+copy another agent's token. Airlock's agent profile allows `process-info*`
+only for `same-sandbox`, so its own agents cannot read each other's.
+
+The daemon therefore binds each token to a process tree. On every
+connection that presents a token, it takes the peer PID from the socket
+(`LOCAL_PEERPID` on macOS, `SO_PEERCRED` on Linux) and walks the parent
+chain (`proc_pidinfo` on macOS, `/proc/<pid>/stat` on Linux). The request
+is served only if the session's anchor process is an ancestor. The anchor
+is recorded with its start time, so a reused PID does not match.
+
+- For `run`, the anchor is the launcher, which lives exactly as long as the
+  lease.
+- For `session start`, the anchor is the shell that ran it. Everything
+  started from that shell matches.
+- A process that detaches from the tree (a double fork, `setsid` with a
+  reparent to init or launchd) loses access. An agent's tool calls do not
+  do that.
+- The binding is a check on the Unix transport only, like peer uid. A
+  network transport needs tokens bound to the client's TLS identity
+  instead ([F11](#follow-ups)).
+
+A stolen token is then useless outside the tree it was issued to. The
+binding does not help against a process inside the tree, which already
+holds the token legitimately.
+
+### Lifecycle
+
+Two modes, with the same daemon:
+
+- **Automatic (default).** The first launcher that finds no daemon starts
+  one, with the existing double fork and readiness pipe, before the
+  launcher creates any tokio runtime. An automatically started daemon
+  exits after a short grace period with no sessions.
+- **Service.** `airlock daemon install` writes a launchd agent or a systemd
+  user unit that runs `airlock daemon start --foreground`. A service
+  daemon stays up with no sessions. `airlock daemon uninstall` removes it.
+
+The daemon's own environment does not matter in either mode, because
+everything a session needs comes with `Register`. `daemon start`
+(`--foreground` for service managers and debugging), `daemon stop`,
+`daemon restart` and `daemon logs` stay for manual control. `stop` and
+`restart` end every session, so on a terminal they name the sessions and
+ask first; on a non-terminal they refuse while sessions exist unless
+`--yes` is given. `airlock status` reports whether the daemon runs, so
+there is no `daemon status`.
+
+**Versions.** An automatic daemon outlives the binary that started it, so
+every connection starts with a version handshake. A launcher that finds an
+idle daemon of another version restarts it. A busy one keeps serving its
+sessions, with a note to the user, and is replaced once idle, unless the
+protocol is incompatible. Then the launcher refuses and points to
+`airlock daemon restart`.
+
+### Session isolation
+
+All sessions share one process. Inside a session nothing changes from
+today. The new risk is one session's request, tool or output reaching
+another session's secrets. The design rules below keep that a structural
+property rather than a matter of care, and implementation must hold them.
+
+- **The session is the only path to sensitive state.** The token resolves
+  to an `Arc<Session>` holding the config, secret store, redactor, policy,
+  environment snapshot, filtered `PATH` and proxy. Request handlers receive
+  only that handle. No global map holds secrets or config, and nothing
+  looks a secret up by label outside its session.
+- **No process-global state after startup.** Today the request path reads
+  the process environment: `PATH` in `resolve_binary`
+  ([src/exec.rs](../src/exec.rs)), `TMPDIR` in the Seatbelt builder, and
+  `source = "env"` and `clear_secret_env_vars` in
+  [src/secrets.rs](../src/secrets.rs). All of it moves into the session. A
+  clippy `disallowed-methods` rule forbids `std::env::var`, `set_var`,
+  `remove_var` and `current_dir` outside startup code, so a regression fails
+  CI.
+- **A last-pass global redactor.** After a session's own redactor, output
+  also passes an automaton built from every live session's secrets. It
+  masks another session's secret in output even if a bug put it there.
+  Redaction only removes text, so it discloses nothing. It does not cover a
+  secret leaked into another session's tool environment, which the first
+  rule has to prevent.
+- **A per-session cap on concurrent `exec`s**, so one agent cannot starve
+  the others. A panic unwinds and ends only its task.
+
+The proxy is the largest attack surface in the process: hyper and rustls
+parse input from sandboxed tools and from upstream servers. A memory-safety
+bug there would now reach every project's secrets, where today it reaches
+one. Moving each session's proxy to its own process is [F10](#follow-ups).
+
+### Clients
+
+`exec`, `tools list` and `agent check` take the address and token from
+`AIRLOCK_ADDR` and `AIRLOCK_SESSION` and nothing else. They do not fall
+back to `admin.token` or to discovery. A user who wants to run `exec` by
+hand starts a shell with `airlock run -- $SHELL` (sandboxed), or runs
+`eval "$(airlock session start)"` in an unsandboxed one. Every `exec` is
+logged with its session id.
+
+`tools list --session <ID>` is the one exception: run from the user's
+terminal, it reads `admin.token` to show what another session serves.
+
+**Exit status.** `exec` exits with the tool's status, and with 125, 126 or
+127 when Airlock itself fails, as `docker run`, `env` and `chroot` do. Exit
+1 is the most common tool failure, so it cannot also mean "Airlock failed".
+
+| Exit | Meaning |
+|---|---|
+| 125 | Airlock could not run the tool: no session, session ended, daemon unreachable, stale secret, working directory outside the root |
+| 126 | The tool is declared, but its binary cannot be used: not on the session's `PATH`, or inside the root or a write grant. The message names the `PATH` entries that were dropped and why, and suggests installing the tool outside the project (Homebrew, mise, Nix). There is no override: approving the config does not approve a binary the agent can rewrite ([B2](#blocking)). |
+| 127 | No tool by that name in this session |
+
+`run` exits with the agent's status, or 125 when Airlock cannot start it.
+Airlock's own messages start with `airlock:` on stderr, which tells them
+apart from a tool that exits 125–127 itself.
+
+### Transport
+
+`AIRLOCK_ADDR` is a URI. This proposal implements `unix://<path>` only. The
+design keeps a TCP transport open:
+
+- **Authorization starts from the session token, not the uid.** Peer uid,
+  the socket's mode 0700 and the [token binding](#token-binding) to a
+  process tree are extra checks that only the Unix transport can make.
+- **Requests carry no file descriptors.** They carry no other host-local
+  handles either, so any byte stream can carry the protocol.
+- **Registration stays local.** `admin.token` is read from the daemon's
+  filesystem, so only a launcher on the daemon's host can register a
+  session. A remote agent receives a token that was registered there.
+
+A TCP transport needs TLS, and probably tokens bound to the client's TLS
+identity, since a token on the network is a bearer credential. It also meets
+a limit that a socket hides: tools run on the daemon's host, against the
+project root and working directory on that host. See [F11](#follow-ups).
+
+### Under another harness
+
+A harness started from a `session start` shell runs in its own sandbox, or
+in none. Airlock's protections for the agent then depend on that sandbox,
+which must:
+
+| Must | Why |
+|---|---|
+| Deny reads of the runtime base | `admin.token` is protected from Airlock's own sandboxes only. A harness that lets the agent read it lets the agent register sessions for any project. The token reaches the agent through its environment, so denying the whole base breaks nothing. |
+| Deny writes to the runtime base, the trust store and the global config | The agent must not replace the socket or CA, approve its own config, or edit the unapproved global layer. |
+| Deny reads of the user's credential stores (`~/.config/gh`, `~/.config/gcloud`, `~/.aws`, `~/.kube`, the keychain) | Otherwise the agent reads the credentials Airlock brokers, directly. |
+| Deny inspecting other processes | Otherwise the agent can read other processes' environments. [Token binding](#token-binding) makes a copied session token useless, but other secrets in other environments are not covered. |
+
+The harness also inherits the whole environment of the shell it started
+from, unlike under `run`, which passes an allowlist. Start it from a shell
+without secrets in its environment, not from inside `op run`.
+
+SECURITY.md carries this list, with a Claude Code sandbox configuration
+that meets it. `airlock config --paths` prints the exact paths on this
+machine. `session start` points to the list each time (`-q` drops it), and
+[`agent check`](#agent-integration) tests it from the agent's shell.
+
+### Commands refused inside the sandbox
+
+`run`, `trust`, `status`, `session` and `daemon` refuse when
+`AIRLOCK_SANDBOX=1`, with an error that says they need the user's terminal.
+For `status`, the error points to `agent check`, which shows the agent its
+own session. The agent can unset the variable, so this is a convenience
+only. What actually stops the agent is that it cannot write the trust store
+(see below) or read `admin.token`. A daemon the agent starts itself cannot
+create its socket in the runtime base, and anywhere else it runs with the
+agent's own access, so it gains nothing.
+
+With `AIRLOCK_SANDBOX=1`, `airlock --help` lists only the commands that
+work there. The help says so and names the hidden
+commands, so a user in a sandboxed shell sees why one is missing. A hidden
+command's own `--help` still works and starts by saying it needs the
+user's terminal. In a `session start` shell the variable is not set, and
+help is complete.
+
+`init` and `config` work inside the sandbox. `init` writes a project file
+that still needs approval, so an agent can draft a config for the user to
+review. `init --global` is refused there like `trust`, and hidden from
+help: the global file needs no approval, so nothing would review what the
+agent wrote. The sandbox cannot write it anyway, but the refusal says why.
+`config` shows the global layer as unreadable when the sandbox cannot read
+it.
+
+## Protecting the anchors
+
+Three locations decide what the daemon trusts and how clients reach it:
+
+| Anchor | Default |
+|---|---|
+| trust store | `$XDG_STATE_HOME/airlock/trust` → `~/.local/state/airlock/trust` |
+| global config | `$XDG_CONFIG_HOME/airlock/airlock.toml` → `~/.config/airlock/airlock.toml` |
+| runtime base | see [Location](#location); not taken from the environment |
+
+The XDG variables are honored. That makes the environment an attack path. The
+agent cannot set the environment of the user's shell directly, but it can edit
+files that shells load from the repo:
+
+```toml
+# mise.toml in the repo. mise trusts by path by default, so this edit applies
+# the next time the user cd's in, with no prompt.
+[env]
+XDG_STATE_HOME = "{{config_root}}/.cache/state"
+```
+
+A committed `.envrc` does the same once the user has allowed it with direnv.
+The user's next `airlock run` would then read a trust store the agent wrote.
+Redirecting `XDG_CONFIG_HOME` is worse: the global layer is not approved at
+all.
+
+Each anchor is therefore checked before use, after canonicalization:
+
+1. **Ownership and mode.**
+   - Trust store and runtime base: owned by the effective uid, mode 0700,
+     not a symlink.
+   - Global config file and its directory: owned by the effective uid, not
+     group- or world-writable.
+2. **Outside the project root.**
+3. **Outside every sandbox write grant.** That means `filesystem.write`,
+   every tool's `extra_write` and `agent.filesystem.write` from **every
+   layer, including unapproved ones**; `airlock run --allow-write`; and
+   built-in profile write paths. The one exception is macOS `$TMPDIR` for
+   the runtime base, which the Seatbelt deny rule carves out.
+
+The same check runs from the other side at config load: a write grant that
+covers an anchor is a config error. So an agent that edits `airlock.toml` to
+grant itself write access to `~/.local/state/airlock` gets refused twice:
+the edit needs approval, and even once approved the grant is rejected.
+
+With these checks, a redirected XDG variable can only point somewhere the
+agent cannot write. Nothing it controls ends up in the trust store or the
+global layer.
+
+## Inspecting config and sessions
+
+Three layers and several sessions raise two different questions: what do
+the files say, and what does a running agent get. Each has its own command,
+and the agent's view of its own session is a third.
+
+| Command | Answers | Reads |
+|---|---|---|
+| `airlock config` | What the next session start would load: the merged config from the current files, the layer each secret, tool and setting comes from, and each file's approval state. Items from a file that is not approved are marked `(unapproved)`; a global tool a project tool replaces is marked `replaced by repo`. `--paths` prints the layer, trust store, runtime and tool state paths. | The files. No daemon or session. Secret values never appear. Inside the sandbox, a global layer it cannot read shows as `not readable from this sandbox`. |
+| `airlock tools list` | What a session serves. Inside a session, its own tools; from the user's terminal, `--session <ID>` names one. | The daemon, through a `List` request. |
+| `airlock status` | The daemon (running, PID, version, how it started), this project's layers and approval state, and the sessions here and in total. Exits 0 when the daemon runs, 3 when it does not. | Both, with `admin.token`. User's terminal only. |
+
+`tools list` replaces `list`, which stops reading config files. The daemon
+answers from the session's merged, approved config, in today's output
+format.
+
+- The agent sandbox never needs read access to the global config or the
+  trust store.
+- The list matches what `exec` will accept.
+- `tools list` needs a running daemon and a [session](#sessions), and
+  without either it fails with the usual message. [SKILL.md](../SKILL.md)
+  currently says the opposite and changes with this.
+- Under `run --no-session` there is no session, so it fails there with the
+  same message as anywhere else.
+
+The commands are grouped by who runs them. The user's commands sit at the
+top level. What the agent and its harness run sits under `airlock agent`.
+`exec` and `tools list` serve both.
+
+## Agent integration
+
+Whether the agent uses `airlock exec` should not depend on it reading
+SKILL.md. An agent that never loads the skill, or loses it in a
+compaction, runs `gh` directly, gets "not logged in", and works around it.
+Two commands put the facts in the agent's context through its harness:
+
+- **`airlock agent check`** verifies the session and self-tests the
+  sandbox of the process that runs it. Each probe is a single `open` that
+  is expected to fail; nothing is read.
+
+  | Check | Passes when |
+  |---|---|
+  | Session | `AIRLOCK_SESSION` is set and the daemon accepts it |
+  | Daemon | it answers on `AIRLOCK_ADDR`, at a compatible version |
+  | `admin.token` | opening it for reading fails |
+  | Runtime dir, trust store, global config dir | creating a file in each fails |
+  | Environment | no variable named as a secret in any tool's `env` is set; the daemon supplies the names through `List`, never the values |
+  | Credential stores | opening each tool's `extra_read` paths and the well-known stores (`~/.config/gh`, `~/.config/gcloud`, `~/.aws`, `~/.kube`) for reading fails; a warning, not a failure, since `claude-relaxed` opens some on purpose. A path that does not exist is skipped. |
+  | Config | the project files' hashes match the session's; reported, not a failure |
+
+  The client computes none of the paths. The launcher records the runtime
+  base, the trust store and the global config path it validated in the
+  session at `Register`, and the daemon returns them with the session
+  check, so the probes test exactly the paths the launcher used. An agent
+  environment that lacks the XDG variables cannot send the probes to the
+  wrong place. The probes assume the client runs on the daemon's host; a
+  network transport ([F11](#follow-ups)) skips them. Exit 0 if every check
+  passes, 1 if one fails, 125 without a session.
+- **`airlock agent hook <harness>`** adapts `check` and `tools list` to
+  one harness's hook protocol. It reads the hook event from stdin, always
+  exits 0, and prints nothing in a project without Airlock config, so it
+  can sit in a user-wide harness config. `claude-code` answers Claude
+  Code's SessionStart event, which fires on start, resume, `/clear` and
+  compaction. `text` prints the same context as plain text for any harness
+  that shows a start command's output to the agent.
+  `--print-settings` prints the hook configuration, so docs and binary
+  cannot drift. `run --profile claude` passes it to Claude Code with
+  `--settings`.
+
+A pass catches a misconfigured sandbox. It proves nothing against a
+hostile agent, which could fake the output, and the guarantees still come
+from the sandbox. Under `airlock run` the harness and its hooks run inside
+Airlock's sandbox, so the hook's self-test tests the agent's sandbox. For an
+`external` session a hook may run outside the harness's sandbox, so the
+hook skips the probes, lists the tools, and asks the agent to run
+`agent check` once with its own, sandboxed, shell tool.
+
+The agent can remove a hook from a project's `.claude/settings.json`. That
+is acceptable: the hook is guidance, and no security property depends on
+it.
+
+A PreToolUse hook that denies a direct `gh` and suggests the `airlock exec`
+form is left out. It costs a daemon round trip per shell command and needs
+a command parser that is never complete.
+
+## Threat walkthrough
+
+| Attack | Outcome |
+|---|---|
+| Agent edits `airlock.toml` or `airlock.local.toml` | The next session start or reload shows the diff in the user's terminal and asks, or refuses on a non-terminal. The user approves or reverts. Running sessions are unaffected until reloaded. |
+| A PR changes `airlock.toml`, and the user pulls it | Same. |
+| Agent hides a change with ANSI or bidi tricks | The diff is escaped, so the hidden characters are visible. |
+| Agent runs `airlock trust` | Refused by the `AIRLOCK_SANDBOX` check. If the agent unsets the variable, writing the trust store fails because no sandbox has a write grant covering it. |
+| Agent writes the trust store directly | Same: no write grant. |
+| Agent grants itself write access to an anchor through a config edit | The edit needs approval, and the grant is a config error anyway. |
+| Agent redirects `XDG_STATE_HOME` or `XDG_CONFIG_HOME` through repo-level env tooling | The anchor is inside the project or under a write grant, so it is refused. |
+| Agent in project A tries to use project B's tools | Its session is bound to A's root and config. Registering a session for B needs `admin.token`, which no sandbox can read. |
+| A daemon bug lets session A reach session B's state | The session handle is the only path to secrets, and process-env reads are linted out. If B's secret still reaches A's output, the global redactor masks it. |
+| Agent stashes its session token for later | The token stops working when the harness exits, the session's TTL runs out, or the session is revoked. |
+| A process outside the agent's tree copies its token (an agent under a lax external sandbox reads another's environment) | Not served: the [token binding](#token-binding) requires the caller to descend from the session's anchor process. Unix transport only. |
+| The launcher is killed | The lease connection closes and the daemon revokes the session. |
+| Agent replaces the socket, PID file or CA certificate | The runtime dir is not writable: Linux never grants it, and macOS denies it explicitly. |
+| Agent starts its own daemon, session or `airlock run` | Refused (convenience only). If forced, the daemon cannot create its socket in the runtime base, and a session cannot be registered without `admin.token`. |
+| Agent stops the user's daemon, or revokes or reloads sessions | Refused (convenience only), and `daemon stop`, `session revoke` and `session reload` need `admin.token`. |
+| Agent removes the harness hook | Allowed. The hook is guidance; nothing depends on it for security. |
+| Agent plants code the user later runs outside the sandbox (hook, `.envrc`, build script) | Not prevented; a [non-goal](#non-goals). That code can rewrite the anchors, and it can also read the user's credentials directly. |
+
+## Worked examples
+
+### Three layers and the merged result
+
+`~/.config/airlock/airlock.toml` (global):
+
+```toml
+[secrets.GH_TOKEN]
+source  = "command"
+command = ["op", "read", "op://Private/GitHub/token"]
+
+[tools.aws]
+description = "AWS CLI"
+[tools.aws.env]
+AWS_PROFILE = "personal"
+
+[agent]
+passthrough_env = ["COLORTERM"]
+```
+
+`~/src/app/airlock.toml` (repo, approved):
+
+```toml
+timeout = 120
+
+[secrets.GH_TOKEN]
+source = "env"
+
+[tools.gh]
+description = "GitHub CLI"
+[tools.gh.env]
+GH_TOKEN = { secret = "GH_TOKEN" }
+
+[filesystem]
+read = ["/opt/homebrew/share"]
+
+[agent]
+passthrough_env = ["NO_COLOR"]
+[agent.env]
+LOG_LEVEL = "info"
+```
+
+`~/src/app/airlock.local.toml` (local, approved):
+
+```toml
+[secrets.GH_TOKEN]
+source  = "command"
+command = ["gh", "auth", "token"]
+
+[tools.psql]
+description = "Postgres shell"
+[tools.psql.env]
+PGSERVICE = "app-dev"
+
+[agent.env]
+LOG_LEVEL = "debug"
+```
+
+Merged:
+
+| Item | Value | From |
+|---|---|---|
+| `timeout` | `120` | repo |
+| `secrets.GH_TOKEN` | command `gh auth token` | local (replaces repo's `env`; global's `op read` would apply only through `from = "global"`) |
+| tools | `aws`, `gh`, `psql` | global, repo, local |
+| `filesystem.read` | `/opt/homebrew/share` | repo |
+| `agent.passthrough_env` | `COLORTERM`, `NO_COLOR` | union |
+| `agent.env.LOG_LEVEL` | `debug` | local |
+
+This example also shows why the local layer exists. The global 1Password
+binding does not reach the repo's `GH_TOKEN` on its own. The local file binds
+it, here with its own `command`; `from = "global"` would have used the
+1Password entry instead.
+
+### Duplicate tool
+
+A global `gh` gives way to the repo's, and `airlock config` says so:
+
+```
+tools
+  gh    repo    GitHub CLI       (replaces global)
+```
+
+A local `gh` next to the repo's is an error until the local file says it
+means it:
+
+```
+$ airlock run --profile claude
+error: tool "gh" is defined in both ~/src/app/airlock.toml and ~/src/app/airlock.local.toml;
+       add `override = true` to the tool in airlock.local.toml to replace the repo's
+```
+
+### A changed file at session start
+
+```
+$ airlock run --profile claude
+~/src/app/airlock.toml has changed since you last trusted it:
+
+--- trusted
++++ ~/src/app/airlock.toml
+@@ -10,5 +10,6 @@
+ GH_TOKEN = { secret = "GH_TOKEN" }
+
+ [filesystem]
+ read = ["/opt/homebrew/share"]
++write = ["~/.ssh"]
+
+Trust this version and continue? [y/N] n
+not trusted; nothing started
+```
+
+On a non-terminal the launcher prints the same diff, then
+`run \`airlock trust\` in a terminal to approve it`, and exits 125.
+
+### Approving ahead of time, and reloading
+
+```
+$ airlock trust
+~/src/app/airlock.toml has changed since you last trusted it:
+
+--- trusted
++++ ~/src/app/airlock.toml
+@@ -14,3 +14,8 @@
+ ...
+
+Trust this version? [y/N] y
+trusted ~/src/app/airlock.toml
+2 sessions for ~/src/app use the previous config: 7f3a9c "claude", b20e51 "codex"
+run `airlock session reload` to apply it to them
+
+$ airlock session reload
+reloaded 7f3a9c "claude": tools +psql
+reloaded b20e51 "codex": tools +psql
+```
+
+The first approval of a file shows its full contents:
+
+```
+$ airlock trust
+~/src/app/airlock.local.toml is not trusted yet. Contents:
+
+[secrets.GH_TOKEN]
+source  = "command"
+command = ["gh", "auth", "token"]
+...
+
+Trust this file? [y/N]
+```
+
+### A redirected anchor
+
+```
+$ airlock run --profile claude
+error: trust store ~/src/app/.cache/state/airlock/trust is inside the project root ~/src/app
+       (from XDG_STATE_HOME=~/src/app/.cache/state); refusing to use it
+```
+
+### Inside the sandbox
+
+```
+$ airlock trust
+error: `airlock trust` cannot run inside an Airlock sandbox; run it from your own terminal
+```
+
+### A directory with no project config
+
+```
+$ cd ~/scratch/experiment
+$ airlock run --no-project-config --profile claude
+```
+
+This uses `~/scratch/experiment` as the root and the global layer as the
+whole config.
+
+## Decisions
+
+| Question | Chosen | Rejected | Why |
+|---|---|---|---|
+| Why move runtime files | Tamper resistance; keep them out of the repo | Filesystem quirks, sharing across worktrees | The first two are the problems we actually have. |
+| Runtime dir location | Per-user temp root, not from the environment (`/run/user/<uid>`, macOS `confstr`) | `XDG_RUNTIME_DIR` / `TMPDIR`; `~/.local/state`; configurable path | Cleared on reboot, per-user, short enough for `sun_path`, and the same in every shell of the user. |
+| Daemon topology | One daemon per user; sessions bound to a root and its approved config | One daemon per project; a relay router with per-session worker processes | One listener per host, which a network transport needs, and config changes apply to new sessions without a restart. Isolation between sessions is structural (see [Session isolation](#session-isolation)). Compared against a central daemon in [airlock-v2-topology.md](airlock-v2-topology.md). |
+| Session state | Per session, resolved by the launcher in the user's terminal | Shared per root and config; resolved by the daemon | Secret prompts reach the user, `source = "env"` sees the project's shell, and sessions stay independent. |
+| Daemon lifecycle | Automatic start and idle exit by default; optional launchd/systemd service | Only one of them | No setup by default; an always-on service for users who want it and for a future network listener. |
+| Proxy placement | In the daemon for now | Per-session process in the first cut | Keeps the first cut small. The proxy parses untrusted input, so moving it out is tracked as F10. |
+| Trust model for the repo file | Trusted after review | Untrusted (secrets only from personal config); fully trusted | Approved config can do everything it does today, and a change needs review again. |
+| Approval unit | Whole-file bytes | Normalized security-relevant content; per-item approval | Simplest thing to get right, with nothing to normalize or audit. |
+| What approved repo config may do | Everything, as today | No secret sources; suggested sources only | Keeps a single-file setup working. The local layer covers personal bindings. |
+| Personal config location | Global and per-project local | Global only; local only | Global for bindings shared across projects, local for per-project overrides. |
+| Local file location | In the project, approved | Outside the project (`~/.config/airlock/projects/<id>.toml`); in the project with sandbox write denied | Kept next to the repo file where users expect it. Approval handles the agent being able to write it. |
+| Precedence | global < repo < local | repo < global < local | Same order as git config. |
+| Tool collision | A project tool replaces a global one, shown in `config`; repo against local is an error unless the local tool says `override = true` | Always an error; highest layer wins; field merge | A silently shadowed team tool is a security surprise, but an error with no way out breaks every repo that declares the user's global `gh`. Each replacement is either the user's own default giving way, or an approved line. |
+| Secret collision | Local replaces a repo label's spec whole; global reaches a repo label only through local `from = "global"` | Highest layer wins; global rebinds repo labels automatically; approve the cross-layer binding map | A repo label must not resolve to a personal secret without an approved opt-in. Rebinding stays one line per label. |
+| Everything else | Lists union, maps per key, scalars highest | Whole-section replace; additive only | Predictable, and a personal layer can still override a value. |
+| Unapproved file | Show the diff against a stored copy; on a terminal ask and continue, on a non-terminal refuse | Refuse with no diff; always refuse and point to `trust` | The user reviews exactly what changed. Refuse, `trust`, run again is three commands for the most common decision, and the prompt is as safe as `trust`'s. Scripts stay non-interactive. |
+| `airlock trust` UX | Diff, then y/N; `--yes` for scripts | Approve silently; no `--yes` | Review happens where the approval happens. |
+| Protecting approval | Sandbox cannot write the trust store; `trust` refuses in the sandbox | Terminal confirmation as the control | An agent with a pty can answer a prompt, so only the sandbox is a real control. |
+| Global file approval | None, protected by the anchor checks | Approve it like the repo file | It is the user's own file, outside every project. |
+| Anchor paths | Honor XDG, then validate | Ignore the environment and use the passwd home | Conventional, and the validation closes the redirect attack. |
+| Project without config | Requires `airlock.toml` or `airlock.local.toml`; `--no-project-config` opts out | Global-only by default | Using Airlock in an arbitrary directory is explicit. |
+| `--no-config` | Becomes `--no-project-config` (global layer only) | Keep both | An empty config has no real use. |
+| `--config <path>` | That file only, still approved | Replaces only the repo layer; skips approval too | An explicit file means exactly that file. Skipping approval would reopen the hole. |
+| `tools list` | Asks the daemon | Reads the files; daemon with file fallback | Shows what is actually served, and keeps config dirs out of the agent sandbox. |
+| Inspecting the files | `airlock config`, with the layer behind each item | `tools list` only | `tools list` shows what a session serves, not what the files say. Three layers raise "where does this come from?", as `git config --show-origin` answers. |
+| Command grouping | User's commands at the top level; the agent's under `airlock agent`; `exec` and `tools list` for both | Everything at the top level | The agent's plumbing does not sit next to the user's commands. |
+| After approval | New sessions use it; running sessions keep theirs until the user runs `session reload`, and `status` marks them | `trust` reloads running sessions; no reload at all | A running agent's tools change only when the user asks, and an agent that added a tool does not lose its context to a restart. |
+| Commands refused in the sandbox | `run`, `trust`, `status`, `session`, `daemon`; help inside the sandbox hides them and says so | `trust` only; same help everywhere | Clear errors for things an agent has no business doing, and an agent reading the help is not shown commands it cannot use. |
+| Wrapping a harness | `airlock run` always sandboxes; a harness with its own sandbox uses `session start` | A separate `session exec`; `run --no-sandbox` | One verb starts an agent, and no flag runs one with no sandbox at all. `session exec` would give `exec` two meanings. |
+| Exit status | 125 Airlock failed, 126 binary unusable, 127 no such tool | Exit 1 for every Airlock error | 1 is also the most common tool failure. Same convention as `docker run`, `env` and `chroot`. |
+| Session lifetime | `run`: a lease on the `Register` connection; `session start`: `--ttl`, default 12h, with `session renew` | Ends only when `run` sees the harness exit; daemon watches the harness PID; until revoked | The kernel closes a dead launcher's socket, so nothing outlives it, with no platform-specific process watching. A forgotten `session start` would otherwise keep a token valid indefinitely; renew keeps an editor working past a day. |
+| Copied tokens | Bound to the anchor process's tree by peer PID | Acknowledge only | An external sandbox that allows process inspection exposes every token in reach. The binding makes a copy useless outside its tree. |
+| Tool state | `{tool_state}` under `$XDG_CACHE_HOME/airlock` | `{sandbox_root}/.config/…` | Keeps tool state out of the project, the agent's reach and `git status`. |
+| Approving in CI | `trust --yes`, or `--expect-sha256` to pin content | `--yes` only | A pinned hash approves exactly what the workflow expects. |
+| Daemon version skew | Handshake; restart an idle daemon, note on a busy one, refuse if incompatible | Not handled | An automatic daemon outlives the binary that started it. |
+| Agent learns its tools | SessionStart hook through `airlock agent hook`, installed by `--profile claude` | SKILL.md alone; a PreToolUse hook | The hook delivers the facts on every start and compaction. A PreToolUse hook costs a round trip per command and needs a complete command parser. |
+| `--config` scope | Only on commands that discover config | A global option | On `exec` and `tools list` it would be a silent no-op. |
+| Client authentication | Sessions registered with a 0600 `admin.token` no sandbox can read; scoped by the directory they start in; `AIRLOCK_ADDR` is a URI | Uid only; one token per daemon in the agent's environment; per-session tool allowlist | The agent is the same uid. A per-daemon token lives too long and cannot tell agents apart. A subset of one project's tools is rarely needed. |
+| Migration | None | A transition release that checks both locations | Pre-1.0. |
+
+## Prior art: `mise trust`
+
+[mise](https://github.com/jdx/mise) gates project config behind
+`mise trust` (read at `59d5cdb`, `src/config/config_file/mod.rs`):
+
+- **Trust by path by default.** A symlink in
+  `~/.local/state/mise/trusted-configs/` marks a config root as trusted.
+  Later edits are trusted automatically.
+- **Paranoid mode is trust by content.** It stores a SHA-256 of the whole
+  file beside the symlink and checks it on every load. It keeps no copy, so
+  it cannot show a diff.
+- **Implicit trust in several cases.**
+  - `mise run`, `exec`, `install` and `watch` trust their active config
+    automatically.
+  - CI trusts everything.
+  - A linked worktree inherits trust from the main checkout.
+  - `MISE_YES` / `--yes` answers the prompt.
+  - "Safe" configs (only tool versions and plain tasks) need no trust.
+- **The environment can move or bypass trust.** `MISE_STATE_DIR` and
+  `XDG_STATE_HOME` move the store. `MISE_TRUSTED_CONFIG_PATHS` trusts whole
+  path prefixes.
+
+mise's threat is cloning or `cd`-ing into a hostile repo. Airlock's threat is
+a process running as the user that edits files after they were trusted. So
+Airlock takes paranoid mode's content binding and adds the stored copy for
+diffs. It drops trust by path, implicit trust, the worktree and CI shortcuts,
+and exemptions for "safe" files, because each would let an agent's edit take
+effect without review. mise's environment overrides show why Airlock
+validates the anchor locations instead of trusting the variables.
+
+## Open questions and follow-ups
+
+A review of this proposal against the code found the items below. Items
+marked **blocking** must be resolved, in this document, before
+implementation starts: either the design as written does not deliver a
+stated goal, or it does not work. The follow-ups can land after the first
+implementation, or be decided during it.
+
+| # | Item | Status |
+|---|---|---|
+| B1 | The agent can run code outside the sandbox through project files | resolved: goal narrowed |
+| B2 | Approval covers the config, not the code it runs | resolved: filtered `PATH`, binary location check |
+| B3 | The repo layer can reference personal secrets | resolved: local opt-in |
+| B4 | Any daemon of the user is reachable from any sandbox | resolved: sessions |
+| B5 | `exec` inside `airlock run` cannot find the socket on Linux | resolved by B4 |
+| B6 | `$TMPDIR` is not a stable per-user base on macOS | resolved: base ignores the environment |
+| B7 | The Seatbelt deny must be the last rule, in every profile | resolved |
+| B8 | `--config <path>` has no slot in the trust store | resolved: copies keyed by file name |
+| F1 | Ownership checks and XDG handling for the anchors | follow-up |
+| F2 | The global config under home-manager | follow-up |
+| F3 | Review a policy diff, not only a byte diff | follow-up |
+| F4 | Precedence for secret sources | resolved by B3 |
+| F5 | Tool collisions have no way out | resolved: global yields; local `override = true` |
+| F6 | Every worktree needs its own first approval | follow-up |
+| F7 | Runtime dir lifetime | follow-up |
+| F8 | `list` under `airlock run --no-daemon` | resolved: `--no-session` has no session, so `tools list` fails as anywhere else |
+| F9 | Deny agent writes to `.git/hooks/` on macOS | follow-up |
+| F10 | Run each session's proxy in its own process | follow-up |
+| F11 | Network transport | follow-up |
+| Q1 | One daemon per user instead of one per project | resolved: one daemon per user |
+
+### Blocking
+
+**B1. The agent can run code outside the sandbox through project files.**
+The sandbox root is read-write for the agent, and nothing in it is
+protected. The agent can write `.git/hooks/*`, `.git/config`
+(`core.fsmonitor` runs on every `git status`), `.envrc`, `mise.toml`
+(`[hooks] enter` runs on `cd`), `Makefile` or `package.json` scripts. Each
+runs later as the user, unsandboxed. That code can write the trust store
+and the global config directly, or put a fake `airlock` first on `PATH` so
+the user's next `airlock trust` is the agent's.
+
+The mise example in [Protecting the anchors](#protecting-the-anchors) is one
+case of this class. Validating the XDG variables closes that case only.
+Until the class is addressed, the goal "the approval record, the global
+config and the runtime directory cannot be forged or redirected by the
+agent" does not hold.
+
+**Resolved: narrow the goal.** This class predates the proposal. Code the
+user runs outside the sandbox can read `~/.config/gh/hosts.yml` or call
+`op read` itself, which already defeats secret isolation. The trust store
+cannot be held to a higher standard than the secrets it guards. Denying the
+known paths would not close the class either: build scripts, tests and
+source code run as the user whenever the user builds, ordinary git use
+(`git push -u`, `git remote add`) writes `.git/config`, and Landlock cannot
+carve paths out of the root grant.
+
+- The goal now reads: no sandbox can write or redirect the anchors. With
+  the existing approval goal, this means an unreviewed config change does
+  not take effect through Airlock.
+- SECURITY.md gains a "does not protect against" entry for agent-written
+  code the user runs outside the sandbox. It complements the existing
+  "Agent harness escape" entry, which covers the agent itself running
+  outside one.
+- The XDG anchor validation stays. It is cheap, and it covers the one
+  vector that needs no code execution: mise applying a path-trusted `[env]`
+  edit on `cd`.
+- [F9](#follow-ups) adds a macOS-only deny for `.git/hooks/` as defense in
+  depth.
+
+**B2. Approval covers the config, not the code it runs.** Approving the
+bytes of `airlock.toml` does not approve the programs they name.
+
+- `source = "command"` runs unsandboxed with the daemon's environment and
+  working directory ([src/secrets.rs](../src/secrets.rs)). An approved
+  `command = ["./scripts/token.sh"]` runs whatever the agent last wrote to
+  that script. So does a bare `op` when direnv or mise has put a project
+  directory on the daemon's `PATH`. With `refresh`, it runs again long after
+  approval.
+- Tool binaries are resolved on the daemon's `PATH` at request time
+  (`resolve_binary` in [src/exec.rs](../src/exec.rs)). A planted `gh` in an
+  agent-writable `PATH` directory receives `GH_TOKEN`.
+
+Unlike B1, the daemon runs this code itself, with no user action, so it is
+in scope.
+
+**Resolved:**
+
+1. **A filtered `PATH`.** At session start the launcher takes its own
+   `PATH` and drops relative entries and every entry inside the project root or a
+   write grant. Write grants means the same set as the [anchor
+   check](#protecting-the-anchors). The filtered `PATH` is used to resolve
+   tool binaries and secret commands' `argv[0]`, and is the `PATH` handed to
+   tools and secret commands. Without the last part, `gh` could run a
+   planted `git` that inherits `GH_TOKEN`. Entries are dropped, not refused:
+   a direnv or mise setup with `node_modules/.bin` on `PATH` is common, and
+   refusing would break it for no gain. A "binary not found" error lists the
+   entries that were dropped.
+2. **A location check on the resolved binary.** The resolved tool binary
+   and the secret command's resolved `argv[0]` are canonicalized and
+   refused if they land inside the root or a write grant. This catches a
+   symlink on a safe `PATH` entry that points into the project. An
+   `argv[0]` containing `/` goes through the same check, so
+   `command = ["./scripts/token.sh"]` is a config error.
+3. **Interpreter arguments stay open.** In `["bash", "scripts/token.sh"]`
+   the command is approved but the script it reads is not. A scan of the
+   arguments would catch that case and miss `--flagfile=./x`, which gives
+   false confidence. SECURITY.md's Config safety section documents it
+   instead: an argument that names a project file runs whatever is in that
+   file at the time.
+
+**B3. The repo layer can reference personal secrets.** [Merge
+rules](#merge-rules) lets a tool in any layer reference a secret label from
+any layer. A PR can add `[agent.env] X = { secret = "PERSONAL_OPENAI" }` and
+the agent receives the raw value, because `build_agent_env` in
+[src/run.rs](../src/run.rs) resolves secret references. It can equally add
+a networked tool that takes the secret. The reviewer sees a label name, not
+that it resolves to the user's password manager.
+
+Restricting the repo to labels it declares is not enough on its own. A PR
+can declare `[secrets.OPENAI_API_KEY] source = "env"`, and if personal
+layers rebound repo labels automatically, it would get the user's global
+binding anyway. The gap is a binding that crosses layers without approval.
+
+**Resolved: personal bindings need a local opt-in.** See [Secret labels
+across layers](#secret-labels-across-layers). Repo items reference only repo
+labels. A global binding reaches a repo label only through
+`from = "global"` in the approved local file. The user approves that
+crossing explicitly, once per label per project.
+
+**B4. Any daemon of the user is reachable from any sandbox.** The daemon
+authenticates clients by uid alone, and the agent runs as the user.
+
+- macOS: the agent can read all of `$TMPDIR` and has unrestricted outbound
+  network. `$TMPDIR/airlock/` lists every project's daemon, and each `root`
+  file names its project.
+- Linux: Landlock does not mediate `connect` on pathname sockets. The id is
+  a hash of a guessable path.
+
+So the agent in project A can drive project B's daemon and run B's tools
+with B's secrets. `AIRLOCK_ROOT` makes this easier than the
+[`--no-project-config`](#--no-project-config) section says: it skips
+discovery, so it reaches projects the agent cannot even read.
+
+**Resolved: [sessions](#sessions).** A token the daemon hands out over the
+socket is not enough: the agent is the same uid and could ask for one too.
+Registering a session needs `admin.token`, which no Airlock sandbox can
+read. A single per-daemon token in the agent's environment was also considered. It would
+stay valid for the daemon's lifetime, could not tell two agents apart, and
+needed a file fallback for other harnesses that defeated the protection.
+Tools never see a session token, since they get a clean environment.
+
+**B5. `exec` inside `airlock run` cannot find the socket on Linux.** The
+agent's environment is an allowlist (`build_agent_env` in
+[src/run.rs](../src/run.rs)). It carries `TMPDIR` but not
+`XDG_RUNTIME_DIR`. Inside the sandbox the client falls back to
+`${TMPDIR:-/tmp}/airlock-<uid>`, while the daemon listens under
+`/run/user/<uid>`. An `[agent.env]` entry that sets `TMPDIR` breaks it on
+macOS too.
+
+**Resolved by B4.** Every session exports `AIRLOCK_ADDR` with the exact
+address, and the client does no discovery of its own. A nested `airlock.toml`
+under the agent's working directory cannot redirect it either.
+
+**B6. `$TMPDIR` is not a stable per-user base on macOS.** `$TMPDIR` varies
+per shell: agent harnesses set it to `/private/tmp`, and Nix shells and tmux
+change it. As a result:
+
+- A daemon started in one shell is invisible from another, and `daemon
+  start` there starts a second daemon for the same project. Stale-state
+  detection does not catch it, because it looks in a different directory.
+- With `TMPDIR=/private/tmp` the base is `/private/tmp/airlock`, shared by
+  all users. The Linux fallback has a `-<uid>` suffix, the macOS row does
+  not. The first user to create it locks the others out.
+- A long `$TMPDIR` can push the socket path past the 104-byte `sun_path`
+  limit.
+- The daemon's `$TMPDIR` and the one the Seatbelt profile was built from can
+  differ, so the deny rule can target the wrong directory.
+
+**Resolved: the base ignores the environment on both platforms.** See
+[Location](#location). macOS uses `confstr(_CS_DARWIN_USER_TEMP_DIR)`.
+Linux has the same problem with `XDG_RUNTIME_DIR`, so it uses
+`/run/user/<uid>` directly and falls back to `/tmp/airlock-<uid>`. With
+[sessions](#sessions) the agent no longer computes the path, but
+launchers in different shells still have to find the same daemon, and the
+Seatbelt deny has to target the directory the daemon uses.
+
+**B7. The Seatbelt deny must be the last rule, in every profile.** Verified
+with `sandbox-exec`: the last matching rule wins, so a `deny` followed by a
+broader `allow` for the same path is re-allowed. The deny cannot sit right
+after the `$TMPDIR` allow as [Sandbox access](#sandbox-access) says:
+`agent.filesystem.write` or `--allow-write $TMPDIR` is emitted later, and
+the anchor exception for macOS `$TMPDIR` permits exactly those grants. The
+deny must follow every allow, including the profile rules. Tool profiles
+need it too, since a tool's `extra_write` can grant `$TMPDIR` under the same
+exception.
+
+**Resolved.** [Sandbox access](#sandbox-access) now puts the denies last, in
+every agent and tool profile. A test should build each profile with a
+`$TMPDIR` write grant and check that the denies come after it.
+
+**B8. `--config <path>` has no slot in the trust store.** The trust store
+keeps one `airlock.toml` and one `airlock.local.toml` per project id, and
+the id comes from the project root. `--config ./airlock.staging.toml` in the
+project root has the same id as the repo file. Which slot it uses is
+unspecified: either the two approvals overwrite each other, or one of them
+is checked against the wrong copy.
+
+**Resolved: copies are keyed by file name.** See [Trust store](#trust-store).
+`--config ./airlock.staging.toml` is approved as `airlock.staging.toml`, next
+to the repo file's copy. Each session carries its own config, so a session
+on the staging config can run next to one on the default config.
+
+### Follow-ups
+
+**F1. Ownership checks and XDG handling for the anchors.** The agent runs as
+the user, so "owned by the effective uid" proves nothing against it. Only
+"outside every write grant" protects an anchor from the agent; the
+ownership and mode checks protect against other users. The attacks
+that redirect an XDG variable need code running in the user's shell (B1).
+Consider the rejected alternative, taking the anchors from the passwd home
+directory, which removes the redirect class and the validation that comes
+with it.
+
+**F2. The global config under home-manager.** home-manager links
+`~/.config/airlock/airlock.toml` into `/nix/store`, which root owns, so the
+ownership check refuses it. A root-owned, read-only file is safer than a
+user-owned one. Accept root ownership, or check only that no sandbox can
+write the file.
+
+**F3. Review a policy diff, not only a byte diff.** A unified diff often
+hides which TOML table a changed line belongs to, top-level dotted keys can
+set any table, and escaping does not catch confusable characters such as a
+Cyrillic letter in a proxy route host. Show the change in the effective
+merged policy next to the byte diff. That also marks comment-only edits as
+"no effective change", which reduces approval fatigue. Approval stays on
+bytes.
+
+**F4. Precedence for secret sources.** Resolved by B3. Global does not
+override or rebind repo labels. The local file binds them, with
+`from = "global"` as the one-line way to reuse a global binding.
+
+**F5. Tool collisions have no way out.** A personal `gh` in the global file
+breaks startup in the first repo that also defines `gh`, and the user
+can only remove their own. Decide whether the local layer may explicitly
+replace a repo tool, or the global tool yields to the project.
+
+**Resolved: both.** See [Tools across layers](#tools-across-layers). A
+global tool yields to a project tool, visibly; a local tool replaces a repo
+tool only with `override = true`.
+
+**F6. Every worktree needs its own first approval.** Agent workflows create
+worktrees often, and each is a new root and a new id. Consider accepting a
+file whose bytes match a copy already approved for the same git common dir.
+
+**F7. Runtime dir lifetime.** systemd-logind deletes `/run/user/<uid>` at
+logout, which orphans a daemon started over ssh, and a systemd user service
+stops at logout unless lingering is enabled. On macOS, check whether the
+periodic temp cleanup removes a long-running daemon's PID file.
+
+**F8. `list` under `airlock run --no-daemon`.** `list` now needs a daemon,
+and this mode has none. Decide whether `list` fails there or `run` answers it
+another way.
+
+**Resolved.** `--no-daemon` is renamed `--no-session`. There is no session
+under it, so `tools list` fails with the same message as anywhere else
+without one.
+
+**F9. Deny agent writes to `.git/hooks/` on macOS.** Hooks fire on commit
+with no review step, and agents rarely need to write them. Seatbelt can deny
+`<root>/.git/hooks` after the root grant, subject to the ordering rule in
+B7. This is defense in depth, not a guarantee: Linux cannot express it, and
+`core.fsmonitor` in `.git/config` stays open. Worktrees keep hooks in the
+common dir, which may lie outside the root.
+
+**F10. Run each session's proxy in its own process.** The proxy parses HTTP
+and TLS from sandboxed tools and from upstream servers. In the shared daemon,
+a memory-safety bug there reaches every session's secrets. A per-session
+proxy process needs only the credentials for its own routes, which makes it
+a natural cut. The daemon core is then left with NDJSON over serde as its
+only untrusted input.
+
+**F11. Network transport.** [Transport](#transport) keeps it possible. What
+it needs:
+
+- TLS on the listener, and tokens bound to the client's TLS identity.
+- An answer for where tools run. Today they run on the daemon's host, against
+  that host's project root and working directory. Ordinary tools need the
+  checkout there, through a shared filesystem with path mapping. Proxy tools
+  need only HTTP, so they are the natural first remote case.
+
+[airlock-v2-topology.md](airlock-v2-topology.md) describes the central
+daemon this transport serves, and what v2 keeps possible for it.
+
+### Q1. One daemon per user
+
+**Resolved: one daemon per user.** Sessions (B4) made a per-project daemon
+unnecessary for authentication. The single daemon was chosen for the rest:
+
+- One listener per host, which a future network transport needs.
+- An approved config applies to new sessions without restarting anything.
+- `airlock run` stops embedding a daemon, so several agents can run in one
+  project. Today the second one is refused unless a standalone daemon
+  happens to be running.
+
+The costs, and how the design answers them:
+
+- **One process holds every project's secrets.** See [Session
+  isolation](#session-isolation): the session handle as the only path, no
+  process env after startup, a global last-pass redactor, a per-session
+  cap on concurrent `exec`s, and F10 for the proxy. A relay router with per-session worker processes was
+  considered. It keeps process isolation, but adds IPC and process
+  management. The multi-tenant design keeps that isolation only where
+  untrusted parsing happens (F10).
+- **The daemon's environment is not the project's.** The launcher resolves
+  secrets and sends the environment snapshot and filtered `PATH` with
+  `Register`.
+- **Loading has to happen in the user's terminal.** It happens at session
+  registration, in the launcher, and never on an agent's first `exec`.
+- **A crash or restart ends every session.** This is accepted. Sessions are
+  cheap to start again. An upgrade does not force a restart: a busy daemon
+  keeps serving until it is idle, unless the protocol changed (see
+  [Lifecycle](#lifecycle)).
+
+## Planned for v2.1
+
+Designed, but not part of the first implementation. Each item keeps its
+design record and lands in its own PR after v2 ships.
+
+| # | Feature | Design record |
+|---|---|---|
+| V1 | **Dynamic shell completion.** `airlock completions <bash\|zsh>` prints a script that calls back into `airlock` on each TAB, so `exec -- <TAB>` completes the session's tools and `session revoke <TAB>` completes session ids, and hands off to the tool's own completion after `exec -- <tool>`. | [UX: Shell completion](airlock-v2-ux.md#shell-completion) |
+
+V1 is deferred because it pins clap_complete's `unstable-dynamic` feature,
+sends a daemon request on every TAB, and needs hand-written shell
+delegation. Nothing in the daemon, the sessions or the trust model depends
+on it, so it adds no risk to v2 by waiting.
+
+## To verify during implementation
+
+- The agent can connect to `airlock.sock` in a directory it has no file
+  grants for: under Seatbelt with the agent's network rules, and under
+  Landlock, which does not mediate `connect` on pathname sockets.
+- Seatbelt's `process-info*` with `(target same-sandbox)` means the same
+  sandbox instance, not every process with the same profile text. If not,
+  two Airlock-sandboxed agents can read each other's environment; the
+  [token binding](#token-binding) still holds, but other variables do not.
+- Editors started from a `session start` shell descend from it. `code .`
+  may hand off to a running instance or start through launchd, which
+  breaks the [token binding](#token-binding). If so, document which
+  editors work and how to start them.
+
+## Docs to update when this ships
+
+- **SKILL.md:**
+  - `airlock tools list` replaces `airlock list` and needs a session
+  - `exec`, `tools list` and `agent check` need `AIRLOCK_ADDR` and
+    `AIRLOCK_SESSION`; the session section
+  - exit codes 125, 126 and 127 and what to do with each
+  - `airlock agent check`
+  - after editing the config: ask the user to run `airlock trust` and
+    `airlock session reload`; never run the user's commands
+  - the daemon starts on demand; `airlock daemon install/uninstall`
+  - `--no-project-config` replaces `--no-config`
+  - `airlock.local.toml` and the global file
+  - secret labels across layers, `from = "global"`, optional repo `source`,
+    `description`
+- **README.md:** how it works with the launcher, quick start without
+  `daemon start` or runtime `.gitignore` entries, supplying secrets through
+  `airlock run`, team and personal config (`airlock.local.toml`, the global
+  file, `from = "global"`, `init --local`), approving config, harness
+  hooks, the command reference, troubleshooting. `{tool_state}` in the
+  quick start and examples, and the global git excludes line for
+  `airlock.local.toml`.
+- **ARCHITECTURE.md:** one daemon per user and sessions, registration by
+  the launcher (config load, approval, secret resolution), session
+  isolation, lifecycle modes and the version handshake, runtime dir,
+  config layering and merge, `Register`, `Reload` and `List` requests,
+  the session lease and token binding.
+- **SECURITY.md:** the trust model, the anchors and their validation, and
+  the runtime dir replacing sandbox-root runtime files. Config safety: the
+  filtered `PATH`, the binary location check, and interpreter arguments
+  that name project files. Sessions replace uid-only socket authentication;
+  token binding to the anchor process's tree; the external sandbox
+  requirements from [Under another harness](#under-another-harness), with
+  a Claude Code sandbox configuration that meets them, and `agent check`
+  that tests them. A "does not protect against" entry for agent-written
+  code run outside the sandbox.
+- **CLAUDE.md:** the trust boundary invariant (session token, not the
+  socket alone), the session isolation rules, and the socket invariant's
+  file references.
diff --git a/docs/airlock-v2-questions.md b/docs/airlock-v2-questions.md
new file mode 100644
index 0000000..089fed4
--- /dev/null
+++ b/docs/airlock-v2-questions.md
@@ -0,0 +1,468 @@
+# Airlock v2 — developer questions
+
+Questions a developer is likely to ask when they first meet Airlock v2.
+They mix "how do I use this" with "why is it built this way". Answers
+belong in the README, SKILL.md and the
+[design](airlock-v2-design.md) and [UX](airlock-v2-ux.md) docs. This list
+is for checking that those docs cover them.
+
+Each question has a short answer drawn from the v1 [README](../README.md),
+the design doc and the UX doc, with links to where the answer lives, and a
+coverage mark:
+
+- **Covered:** the docs answer it.
+- **Partial:** the docs answer part of it, or answer it only in the design
+  record, not in a user-facing draft.
+- **Gap:** the docs do not answer it, or contradict each other.
+
+The gaps are collected in [Gaps](#gaps) at the end.
+
+## Getting started
+
+1. What is the smallest setup that lets my agent run `gh` without ever
+   seeing my GitHub token?
+
+   An `airlock.toml` with a `GH_TOKEN` secret (`source = "command"`,
+   `command = ["gh", "auth", "token"]`) and a `gh` tool that takes it, then
+   `airlock run --profile claude` and approve the file when asked. No daemon
+   start, no `.gitignore` lines. The `claude` profile keeps `~/.config/gh`
+   and the keychain out of the agent's reach.
+   ([UX: First run](airlock-v2-ux.md#first-run-in-a-personal-project),
+   [README: Security model](../README.md#security-model))
+
+   **Covered.** See gap G13 on `GH_CONFIG_DIR` inside the project.
+
+2. Do I need to start the daemon before `airlock run`, and how do I know
+   whether one is running?
+
+   No. The first launcher that finds no daemon starts one, and it exits
+   after a grace period with no sessions. `airlock status` shows it, and
+   exits 0 when it runs, 3 when it does not. Inside the agent,
+   `airlock agent check` shows whether the daemon answers.
+   ([Design: Lifecycle](airlock-v2-design.md#lifecycle),
+   [UX: Options](airlock-v2-ux.md#options))
+
+   **Covered.**
+
+3. Where do my secrets come from: the environment, a command like `op read`,
+   or somewhere else? Which should I choose?
+
+   Two sources, as in v1: `source = "command"` runs a command in your
+   terminal at session start, and `source = "env"` reads the environment
+   of `airlock run` (not the daemon's any more). A local file can also bind
+   a repo label to your global binding with `from = "global"`.
+   ([README: Supplying secrets](../README.md#supplying-secrets),
+   [Design: Registering a session](airlock-v2-design.md#registering-a-session))
+
+   **Partial.** The docs list the options but do not say why `command` is
+   preferred or when `env` is the better fit (G9).
+
+4. Why does `airlock run` show me my own `airlock.toml` and ask me to trust
+   it, when I just wrote the file myself?
+
+   The agent can write that file too, and Airlock cannot tell who wrote
+   the bytes. Approval binds the exact bytes you saw, so a file nobody
+   approved is shown in full the first time.
+   ([Design: Goals](airlock-v2-design.md#goals),
+   [Design: What is approved](airlock-v2-design.md#what-is-approved))
+
+   **Partial.** The reason is in the design record. The README section
+   that would explain it to a user ("Approving config") is only an outline
+   in the UX doc.
+
+5. How do I use Airlock in a repository whose team has not adopted it?
+
+   Put an `airlock.local.toml` in the project root. Either file marks the
+   project, and the local file may declare its own secrets and tools. For a
+   one-off directory, `--no-project-config` uses the global config alone.
+   ([Design: Discovery](airlock-v2-design.md#discovery),
+   [Design: `--no-project-config`](airlock-v2-design.md#--no-project-config))
+
+   **Partial.** No journey shows it, `airlock init --local` is only
+   described for a repo that has an `airlock.toml`, and the advice to add
+   the file to `.gitignore` edits a file the team owns (G7).
+
+## Sessions
+
+6. What exactly is a session, and how is it different from the daemon?
+
+   The daemon is one process per user that serves every project. A session
+   binds one agent to one project: its root, its approved config, the
+   secrets resolved for it, and a token. `exec` and `tools list` work only
+   with a session token.
+   ([Design: Sessions](airlock-v2-design.md#sessions),
+   [UX: Options](airlock-v2-ux.md#options))
+
+   **Covered.**
+
+7. Why does every agent need its own session instead of just connecting to
+   the daemon's socket?
+
+   The agent runs as your uid, so reaching the socket proves nothing. On
+   Linux, Landlock does not even mediate `connect` on the socket. Without
+   sessions, an agent in project A could run project B's tools with B's
+   secrets. Registering a session needs `admin.token`, which no Airlock
+   sandbox can read, and a token per agent can end with that agent.
+   ([Design: B4](airlock-v2-design.md#blocking),
+   [Design: Decisions, client authentication](airlock-v2-design.md#decisions))
+
+   **Partial.** Only in the design record. It is listed for SECURITY.md
+   and ARCHITECTURE.md but not drafted.
+
+8. How do I run two agents in the same project at the same time, and do they
+   share secrets?
+
+   Run `airlock run` in a second terminal. Each gets its own session. They
+   do not share secrets: each session resolves its own, and sharing is a
+   possible later optimization.
+   ([UX: Every day](airlock-v2-ux.md#every-day),
+   [Design: Scope](airlock-v2-design.md#scope))
+
+   **Partial.** The docs do not say what the user notices: a second
+   1Password or `gcloud` prompt, and two sets of minted tokens refreshing
+   on their own schedules (G10).
+
+9. What happens to a running agent's session when I close the terminal,
+   restart the daemon, or upgrade Airlock?
+
+   - **Closing the terminal:** `airlock run` sees its harness exit and
+     revokes the session. A `session start` session lives on until its
+     TTL, a revoke, or a daemon stop.
+   - **Restarting the daemon:** every session ends. The agent's next
+     `exec` says the session has ended. `daemon stop` and `restart` ask
+     first when sessions exist.
+   - **Upgrading:** a busy daemon keeps serving its sessions on the old
+     version and is replaced when idle. If the protocol is incompatible,
+     the launcher refuses until you run `daemon restart`.
+
+   ([Design: Lifetime](airlock-v2-design.md#lifetime),
+   [UX: Stopping things](airlock-v2-ux.md#stopping-things),
+   [UX: Upgrading Airlock](airlock-v2-ux.md#upgrading-airlock))
+
+   **Partial.** No doc says how `airlock run` handles SIGHUP, or what
+   happens to a session when the launcher dies without seeing the harness
+   exit (G3). After a daemon restart there is no way back into the session
+   except restarting the agent; `--continue` is mentioned only for reload.
+
+10. How do I give a session to an IDE extension that I cannot start through
+    `airlock run`?
+
+    `eval "$(airlock session start --name vscode)"`, then start the editor
+    from that shell. Quit the editor first if it is already running, since
+    a new window inherits the running instance's environment.
+    `--format fish|json` covers other shells.
+    ([UX: A harness with its own sandbox, or an IDE](airlock-v2-ux.md#a-harness-with-its-own-sandbox-or-an-ide))
+
+    **Partial.** `session start` prints no warning that the IDE's sandbox
+    must deny the runtime dir, although `--no-sandbox` does for the same
+    risk. The docs also do not say that every extension and terminal in
+    the editor inherits the token (G6).
+
+11. Why does a session end when the harness exits, and why does a
+    `session start` session expire after 12 hours?
+
+    So a token the agent stashed, or a background process left behind,
+    stops working when the agent is gone. A `session start` session has no
+    harness to watch, so the TTL bounds a forgotten one. Without it the
+    token stays valid, and the automatic daemon keeps running, indefinitely.
+    ([Design: Lifetime](airlock-v2-design.md#lifetime), [Design: Commands](airlock-v2-design.md#commands))
+
+    **Partial.** Why 12 hours is not argued, and the docs do not say what a
+    user does when an IDE session expires mid-work (G11).
+
+## Config layers and trust
+
+12. What goes in `airlock.toml`, what goes in `airlock.local.toml`, and
+    what goes in `~/.config/airlock/airlock.toml`?
+
+    - **Repo (`airlock.toml`):** the team's tools, and the secret labels
+      they need, with a `description` and usually no `source`.
+    - **Local (`airlock.local.toml`, gitignored):** your bindings for the
+      repo's labels (often `from = "global"`), personal tools for this
+      project, and agent overrides.
+    - **Global:** bindings and tools you use in every project, and agent
+      settings such as `passthrough_env`. Relative paths are an error here.
+
+    ([Design: The three files](airlock-v2-design.md#the-three-files),
+    [Design: Worked examples](airlock-v2-design.md#worked-examples),
+    [UX: Joining a team repo](airlock-v2-ux.md#joining-a-team-repo))
+
+    **Covered.**
+
+13. Why can't my global 1Password binding for `GH_TOKEN` serve the repo's
+    `GH_TOKEN` automatically, without a line in `airlock.local.toml`?
+
+    A PR could then declare a label that matches one of your global
+    bindings and get your personal secret, and the reviewer would see only
+    a label name. The local line is the approved opt-in, once per label per
+    project.
+    ([Design: B3](airlock-v2-design.md#blocking),
+    [Design: Secret labels across layers](airlock-v2-design.md#secret-labels-across-layers))
+
+    **Covered** in the design. The README paragraph is only planned. See
+    G12 on `init --local` writing these lines for you.
+
+14. Why is a tool defined in two layers an error instead of the higher layer
+    winning?
+
+    A silently shadowed tool is a security surprise: a personal tool could
+    replace a team tool, or the reverse, without anyone noticing.
+    ([Design: Merge rules](airlock-v2-design.md#merge-rules),
+    [Design: Decisions](airlock-v2-design.md#decisions))
+
+    **Gap.** The reason is covered, but F5 is open: there is no way out of
+    the error. A global `gh` breaks every repo that also declares `gh`, and
+    `gh` is the docs' main example (G4).
+
+15. Why does approval cover the whole file byte for byte, so that even a
+    comment change has to be approved again?
+
+    It is the simplest rule to get right, with nothing to normalize or
+    audit. TOML has dotted keys, and comments and strings can hide bidi or
+    zero-width characters. F3 plans to show the effective policy change next
+    to the byte diff and mark comment-only edits, while approval stays on
+    bytes.
+    ([Design: Decisions, approval unit](airlock-v2-design.md#decisions),
+    [Design: F3](airlock-v2-design.md#follow-ups))
+
+    **Covered.**
+
+16. Why doesn't the global config file need approval when the repo and
+    local files do?
+
+    It is your own file, outside every project. Instead of approval it is
+    protected by the anchor checks: it must lie outside the project and
+    outside every sandbox write grant, so no sandbox can write it.
+    ([Design: Protecting the anchors](airlock-v2-design.md#protecting-the-anchors))
+
+    **Partial.** The docs allow `init` inside the sandbox because it
+    writes a file that still needs approval, which is false for
+    `init --global` (G8). F2 (home-manager) is open.
+
+17. My agent added a tool to `airlock.toml`. How does it get to use that
+    tool without me restarting it and losing its context?
+
+    The agent's `exec` fails with 127 and a note that the config changed.
+    You run `airlock trust`, then `airlock session reload`. The session keeps
+    its token, and the agent's next `tools list` shows the new tool.
+    ([UX: The agent changes the config](airlock-v2-ux.md#the-agent-changes-the-config), [Design: Reloading a session](airlock-v2-design.md#reloading-a-session))
+
+    **Partial.** The docs do not say which settings a reload can change:
+    the agent's own sandbox and environment are fixed when the agent starts
+    (G2).
+
+18. How do I approve config in CI or a setup script where nobody can answer
+    a prompt?
+
+    `airlock trust --yes`. On a non-terminal, `trust` refuses without it,
+    and `run` refuses an unapproved file and points to `trust`.
+    ([Design: `airlock trust`](airlock-v2-design.md#airlock-trust),
+    [UX: Messages](airlock-v2-ux.md#messages))
+
+    **Covered** after G14: `--expect-sha256` pins the content, and the
+    design says `--yes` must run before any agent starts in the job, and
+    why an ephemeral CI trust store makes every run a first approval.
+
+19. How do I see the merged config, and which layer each setting came from?
+
+    `airlock config`. It reads the files, needs no daemon, and shows each
+    layer's approval state and the layer behind every secret, tool and
+    setting. `--paths` prints the layer, trust store and runtime paths.
+    ([UX: Options](airlock-v2-ux.md#options), [Design: Inspecting config and sessions](airlock-v2-design.md#inspecting-config-and-sessions))
+
+    **Partial.** When a file changed since approval, the docs do not say
+    whether `config` merges the current bytes or the approved copy (G15).
+
+## Sandboxing and security
+
+20. Why does the agent get a different sandbox from the tools it runs?
+
+    They do different jobs. The agent needs wide read access to reason
+    about code and no credentials. A tool needs one credential and its own
+    config files. A misbehaving tool can expose at most the secret it was
+    handed, and that is redacted before the agent reads it.
+    ([README: Security model](../README.md#security-model))
+
+    **Covered** (unchanged from v1).
+
+21. Why do the socket, PID file and CA certificate live outside the project
+    directory now?
+
+    The project directory is writable by the agent and every tool, so they
+    could replace the socket, PID file or proxy CA. The files also showed
+    up in `git status`. One daemon per user also needs one place outside
+    any project.
+    ([Design: Problem](airlock-v2-design.md#problem),
+    [Design: Runtime directory](airlock-v2-design.md#runtime-directory))
+
+    **Covered.**
+
+22. What stops the agent from approving its own config change, or from
+    pointing Airlock at a trust store it wrote itself?
+
+    No sandbox can write the trust store, and a write grant that covers it
+    is a config error. `trust` refuses under `AIRLOCK_SANDBOX=1`, but that
+    is only a convenience. XDG variables are honored, but an anchor inside
+    the project or under a write grant is refused. A terminal prompt is not
+    the control: an agent with a pty can answer one.
+    ([Design: Protecting the anchors](airlock-v2-design.md#protecting-the-anchors),
+    [Design: Threat walkthrough](airlock-v2-design.md#threat-walkthrough))
+
+    **Covered.**
+
+23. I already run Claude Code with its own sandbox. What do I give up with
+    `airlock run --no-sandbox`, and what does that sandbox have to deny?
+
+    `--no-sandbox` is removed. A harness with its own sandbox gets its
+    session from `eval "$(airlock session start)"`, like an IDE. Compared
+    with `airlock run`, you give up Airlock's agent sandbox and its denies,
+    `AIRLOCK_SANDBOX=1` with its help and refusals, the filtered agent
+    environment, the automatic hook install, and the session ending with
+    the harness (it lasts until its TTL instead). The harness's sandbox
+    must deny reads of the runtime dir, writes to the runtime dir, trust
+    store and global config, reads of your credential stores, and
+    inspection of other processes.
+    ([Design: Commands](airlock-v2-design.md#commands),
+    [Design: Under another harness](airlock-v2-design.md#under-another-harness),
+    [UX: A harness with its own sandbox, or an IDE](airlock-v2-ux.md#a-harness-with-its-own-sandbox-or-an-ide))
+
+    **Covered** after G5. The question's wording predates the removal.
+
+24. Why does Airlock filter my `PATH` and refuse a tool binary that lives
+    inside the project?
+
+    Approval covers the config, not the programs it names. A `gh` planted
+    in an agent-writable `PATH` entry would receive `GH_TOKEN`, and an
+    approved `command = ["./scripts/token.sh"]` would run whatever the
+    agent last wrote there. Writable entries are dropped from `PATH`, and a
+    binary that resolves into the project or a write grant is refused.
+    ([Design: B2](airlock-v2-design.md#blocking), [UX: Messages, agent](airlock-v2-ux.md#agent-exec-tools-list-agent-check))
+
+    **Partial.** The reason is covered. The docs do not say what to do when
+    a project legitimately ships its tool in the repo, such as
+    `node_modules/.bin` or a pinned `bin/terraform` (G16).
+
+25. Since one daemon now holds every project's secrets, what keeps one
+    project's session from reaching another project's secrets?
+
+    The session handle is the only path to secrets and config, and no
+    global map holds them. Process-environment reads after startup are
+    linted out. A last-pass redactor built from every live session's
+    secrets masks any that leak into another session's output. Each session
+    has its own cap on concurrent `exec`s. The proxy is the remaining shared risk, and F10
+    moves it to its own process.
+    ([Design: Session isolation](airlock-v2-design.md#session-isolation), [Design: Q1](airlock-v2-design.md#q1-one-daemon-per-user))
+
+    **Partial.** Covers the daemon side. Not covered: one agent reading
+    another agent's session token from that agent's process environment
+    (G3b).
+
+26. What does Airlock deliberately *not* protect against, such as git hooks
+    or build scripts that the agent wrote and I later run?
+
+    - Code the agent wrote that you later run outside the sandbox: git
+      hooks, `core.fsmonitor`, `.envrc`, mise hooks, build scripts and
+      tests. F9 adds a macOS-only `.git/hooks` deny as defense in depth.
+    - An agent that runs outside `airlock run`.
+    - Destructive actions through a tool: the token's scope decides those.
+    - Interpreter arguments that name a project file.
+    - From v1: redaction is best-effort, tools have unrestricted network,
+      and local root can read daemon memory.
+
+    ([Design: Non-goals](airlock-v2-design.md#non-goals),
+    [Design: B1, B2](airlock-v2-design.md#blocking),
+    [README: What you get, Known limits](../README.md#what-you-get))
+
+    **Covered**, across three docs. The single SECURITY.md entry is planned.
+
+## Agent integration and day-to-day use
+
+27. How does my agent find out which tools it must run through
+    `airlock exec`, if it never reads SKILL.md?
+
+    A SessionStart hook (`airlock agent hook claude-code`) puts the session
+    state and the tool list in the agent's context on start, resume,
+    `/clear` and compaction. `--profile claude` installs it. Other setups
+    add the `settings.json` block that `--print-settings` prints, and other
+    harnesses can use `airlock agent hook text`.
+    ([UX: Harness hooks](airlock-v2-ux.md#harness-hooks), [Design: Agent integration](airlock-v2-design.md#agent-integration))
+
+    **Partial.** Claude Code only. `airlock run -- codex` appears as an
+    everyday example but gets no hook, and the docs name no other harness
+    that `hook text` fits (G17). Whether `--settings` merges with the
+    user's own hooks is an open question.
+
+28. What does `airlock agent check` actually test, and why can't a passing
+    result prove that the agent is contained?
+
+    It checks the session and daemon, that `admin.token` cannot be opened,
+    that the runtime dir, trust store and global config cannot be written,
+    that no tool secret name is set in its environment, and whether the
+    config changed. It tests only the process that runs it: a hostile agent
+    could fake the output, and under an external sandbox the hook may run
+    outside that sandbox.
+    ([UX: What `airlock agent check` verifies](airlock-v2-ux.md#what-airlock-agent-check-verifies))
+
+    **Covered.** It does not probe the user's credential stores
+    (`~/.config/gh`, `~/.config/gcloud`), which is the core promise (G18).
+
+29. Why does `airlock exec` exit with 125, 126 or 127 for some failures
+    instead of 1?
+
+    Exit 1 is the most common tool failure, so it cannot also mean "Airlock
+    failed". 125 means Airlock could not run the tool (tell the user), 126
+    that the binary cannot be used, and 127 that no such tool is declared.
+    This follows `docker run`, `env` and `chroot`. Airlock's own messages
+    start with `airlock:`.
+    ([Design: Clients](airlock-v2-design.md#clients),
+    [UX: Options](airlock-v2-ux.md#options))
+
+    **Covered.** See G19 on `run` exiting 1 when you decline approval.
+
+30. Why are `airlock status`, `airlock trust` and `airlock session` missing
+    from `airlock --help` when I run it inside the sandbox?
+
+    With `AIRLOCK_SANDBOX=1`, help lists only commands that work there and
+    names the hidden ones. Those need your terminal: they read
+    `admin.token` or write the trust store, which no sandbox can. A hidden
+    command's own `--help` still works.
+    ([Design: Commands refused inside the sandbox](airlock-v2-design.md#commands-refused-inside-the-sandbox),
+    [UX: Options](airlock-v2-ux.md#options))
+
+    **Covered.**
+
+## Gaps
+
+Each gap was reviewed with a proposal, an alternative and "ignore". The
+decisions are written into the [design](airlock-v2-design.md) and
+[UX](airlock-v2-ux.md) docs, except where a gap is ignored.
+
+| # | Gap | Decision | Where |
+|---|---|---|---|
+| G1 | U1–U16 not folded into the design | Folded in; the UX table stays as the record | design throughout |
+| G2 | What `session reload` can change | Applies everything but `[agent]`, and says when the agent needs a restart. Reuses the session's recorded root and mode. An `exec` in flight finishes on the old config. | [Reloading a session](airlock-v2-design.md#reloading-a-session) |
+| G3 | A session outlives a launcher that dies | `airlock run` holds a lease: the `Register` connection stays open, close-on-exec, and the daemon revokes the session on EOF. The launcher forwards signals and closes last. | [Lifetime](airlock-v2-design.md#lifetime) |
+| G3b | Token theft between agents through process inspection | Acknowledged, and tokens are bound to the anchor process's tree by peer PID. Two items to verify: Seatbelt `same-sandbox` semantics, and editors descending from the shell. | [Token binding](airlock-v2-design.md#token-binding) |
+| G4 | Tool collisions have no way out (F5) | A project tool replaces a global one, visibly; repo against local stays an error unless the local tool says `override = true` | [Tools across layers](airlock-v2-design.md#tools-across-layers) |
+| G5 | `--no-sandbox` contract | `--no-sandbox` removed; `session start` serves harnesses with their own sandbox; an external sandbox checklist | [Commands](airlock-v2-design.md#commands), [Under another harness](airlock-v2-design.md#under-another-harness) |
+| G6 | IDE sessions | `session start` warns about the external sandbox; docs say what inherits the token and that a Dock-launched editor gets none | [Commands](airlock-v2-design.md#commands), [UX journey](airlock-v2-ux.md#a-harness-with-its-own-sandbox-or-an-ide) |
+| G7 | Repos without Airlock | `init --local` writes a standalone skeleton; the warning suggests git's global excludes file | [Secret labels across layers](airlock-v2-design.md#secret-labels-across-layers), [UX journey](airlock-v2-ux.md#a-repo-whose-team-has-not-adopted-airlock) |
+| G8 | `init --global` inside the sandbox | Refused, and hidden from help | [Commands refused inside the sandbox](airlock-v2-design.md#commands-refused-inside-the-sandbox) |
+| G9 | Choosing a secret source | Ignored | — |
+| G10 | Two sessions in one project | Documented: secret commands run again per session | [Scope](airlock-v2-design.md#scope), [UX: Every day](airlock-v2-ux.md#every-day) |
+| G11 | Session TTL | 12h is one working day; `session renew` keeps the token; expiry has its own message | [Lifetime](airlock-v2-design.md#lifetime) |
+| G12 | `from = "global"` hides the binding in the prompt | The prompt annotates each line with the global source; display only | [Unapproved files at session start](airlock-v2-design.md#unapproved-files-at-session-start) |
+| G13 | `GH_CONFIG_DIR` inside the project | `{tool_state}` placeholder under `$XDG_CACHE_HOME/airlock/<id>/<tool>` | [Tool state outside the project](airlock-v2-design.md#tool-state-outside-the-project) |
+| G14 | CI approval | `trust --expect-sha256 <hash>`; `--yes` before any agent starts | [`airlock trust`](airlock-v2-design.md#airlock-trust) |
+| G15 | `config` on a changed file | Shows what the next session start would load, marks `(unapproved)`, and says when the global layer is unreadable | [Inspecting config and sessions](airlock-v2-design.md#inspecting-config-and-sessions) |
+| G16 | Project-local tool binaries | No override; the 126 error suggests installing outside the project | [Clients](airlock-v2-design.md#clients) |
+| G17 | Harnesses other than Claude Code | Ignored | — |
+| G18 | `agent check` and credential stores | Warning-level read probes for tools' `extra_read` paths and the well-known stores | [Agent integration](airlock-v2-design.md#agent-integration) |
+| G19 | Exit status on declined approval | 125, `not trusted; nothing started` | [Unapproved files at session start](airlock-v2-design.md#unapproved-files-at-session-start) |
+
+### Answered only in the design record
+
+Q4, Q7, Q13, Q24 and Q25 are answered in the design doc's decisions and
+blocking items, which a user will not read. The design doc's
+[Docs to update when this ships](airlock-v2-design.md#docs-to-update-when-this-ships)
+lists the README and SECURITY.md sections that will carry them.
diff --git a/docs/airlock-v2-technical-guidance.md b/docs/airlock-v2-technical-guidance.md
new file mode 100644
index 0000000..22a2133
--- /dev/null
+++ b/docs/airlock-v2-technical-guidance.md
@@ -0,0 +1,172 @@
+# Airlock v2 — technical guidance
+
+**Status:** proposal, companion to [airlock-v2-design.md](airlock-v2-design.md)
+and [airlock-v2-topology.md](airlock-v2-topology.md). The design doc decides
+what v2 does: one daemon per user with sessions that resolve their own
+secrets. The topology doc records the direction after that: a central
+daemon. This document is for whoever implements v2.
+
+It separates two things:
+
+- **Shapes to use now.** Ways of writing the protocol and the data model
+  that v2 needs anyway, or that cost nothing extra, and that let the
+  central daemon add variants instead of replacing types.
+- **Additions postponed to v2.1 or later.** Things the central daemon will
+  need and v2 would not use. Each has a note on why adding it later is
+  safe. v2 implements nothing it does not use.
+
+Two facts make the first list worth following in v2 rather than later:
+
+- The daemon starts on demand and outlives the binary that started it, so
+  the launcher-to-daemon link is a compatibility boundary from the first
+  release, before any network exists.
+- The design already keeps a network transport possible
+  ([Transport](airlock-v2-design.md#transport)). The shapes below are what
+  that promise costs in concrete types, and the answer is: almost nothing.
+
+## Shapes to use now
+
+### Two message families
+
+Keep admin requests (`Register`, `Reload`, session list, revoke, renew,
+`Logs`, stop) and session requests (`Exec`, `Stdin`, `StdinEof`, `List`,
+`Check`) as two enums on the wire and in code, on top of the existing
+client-versus-daemon split. The local daemon gates the admin family on the
+admin token, and a server would gate it on a different identity. With one
+enum and a token field that gate is a check in every handler; with two it
+is one match at the top of the connection. v2 needs the gate either way.
+
+### A principal on every request
+
+Every request carries `auth`, a tagged value: `{"kind": "session",
+"token": …}` or `{"kind": "admin", "token": …}`. The Unix listener resolves
+it to one `Principal` before any handler runs, applying its own checks
+there: the peer uid, and for a session token the process-tree binding.
+Handlers receive the principal and the session it resolves to, never the
+raw token. v2 needs this lookup anyway; putting the transport checks in the
+listener is what keeps the handlers unchanged when a TLS listener builds a
+principal from a client certificate instead.
+
+### One protocol version, separate from the binary version
+
+The version handshake the design requires (U9) carries a protocol version,
+not the binary version. The protocol version covers the `Register` payload
+too: a change to the config wire types bumps it. Two binaries with the same
+protocol version interoperate; the launcher's "incompatible daemon" error
+compares protocol versions.
+
+### Config on the wire fails closed
+
+`Register` ships the merged config. Reuse the TOML raw types, which already
+deny unknown fields ([src/config.rs](../src/config.rs)), so a daemon that
+receives a field it does not know rejects the request instead of ignoring
+it. An ignored field is usually a policy the launcher expected enforced.
+The protocol version catches the mismatch first; this is the backstop.
+
+### Error kinds as an enum
+
+`Error { kind, message }` with `kind` an enum: `NoSession`, `SessionEnded`,
+`SessionExpired`, `OutsideProcessTree`, `DaemonUnreachable`, `UnknownTool`,
+`BinaryUnusable`, `StaleSecret`, `OutsideRoot`, `Malformed`. The client maps
+kinds to the exit codes 125, 126 and 127 in one table. v2 needs the mapping;
+an enum is the only way to do it that a relay can later pass through
+unchanged.
+
+### The session stores compiled policy
+
+At `Register` the daemon compiles the merged config into a `SessionPolicy`:
+per-tool sandbox policy, environment template with secret references,
+proxy routes, timeouts, and the secret store. Handlers read the compiled
+form only. `Reload` builds a new one and swaps the pointer, which is the
+"one step" the design requires. A server-side layer later compiles into the
+same form.
+
+### Admin frames have their own size limit
+
+The NDJSON line cap of 1 MiB exists to bound memory from an untrusted
+client. `Register` carries a config that may itself be 1 MiB, plus secrets,
+an environment snapshot and a filtered `PATH`, so it needs a larger cap or
+a split into several frames. Admin requests come from a trusted launcher
+and are bounded by the config cap, so a separate limit for that family is
+sound. Decide it in v2; otherwise `Register` fails only on large configs.
+
+### Log entries carry the session id
+
+The design logs every `exec` with its session id, and `daemon logs
+--session` filters on it. Give the entry a session id field rather than
+formatting the id into the message. Nothing more.
+
+### `Exec` stays free of host-specific fields
+
+`Exec { tool, args, cwd }` carries nothing that names the daemon's host
+beyond the working directory. Keep it that way as fields are added. Where a
+reply must name a host path, as the `Check` reply does for the anchor
+paths, make that section optional, so a reply without it is well formed.
+
+## Postponed to v2.1 or later
+
+| Addition | What it would add | Why v2 does not need it | Why later is safe |
+|---|---|---|---|
+| Capability list in the handshake | `capabilities: ["admin", "session", …]` so a launcher can tell what a daemon does | There is one transport and one daemon kind | An added field, with a protocol version bump |
+| Secret origin | `origin: Client \| Daemon` per label, and `secret_refs: [label]` in `Register` | Every v2 secret is resolved by the launcher | Both are added fields; `Register` without them means "all client-side" |
+| `Exec.cwd` relative to the project root | Forwardable working directory | Nothing forwards in v2 | The local daemon is the relay and knows its own root, so it can rewrite an absolute path when forwarding lands |
+| Binding as an enum | `ProcessTree \| TlsIdentity` on the session | One listener, one binding | A struct becomes a one-variant enum in a local refactor |
+| Project `name` in the repo file | A host-independent identity for a central policy | v2 scopes by the root hash and has no policy to key on | An optional field. Approval is byte-based, so files without it are untouched |
+| Structured audit records | Records with principal, tool, decision and exit status | The ring buffer with a session id field serves `daemon logs` | The record replaces a string in one place |
+| Layer `owner` | `User \| Team` on each layer, for an admin-owned layer | The layer kind implies the owner in v2 | An added field on the layer record |
+| Reserved names `run` and `[daemons]` | Placement and named remote daemons | Unknown fields already fail config validation, so a v2 config cannot use them silently | Define them when they land |
+
+Items the design doc already defers, and that this lens would keep
+deferred, are listed in its [Planned for v2.1](airlock-v2-design.md#planned-for-v21)
+section.
+
+## Unix-transport only
+
+These are right for v2 and are replaced, not extended, by a network
+transport. Keep them behind the listener so that nothing else depends on
+them:
+
+- the admin token file and the socket mode,
+- the lease on the `Register` connection,
+- the runtime directory from `confstr` and `/run/user/<uid>`,
+- the trust store keyed by the root hash,
+- the process-tree binding.
+
+Keep the last-pass global redactor as a daemon property rather than a
+session property. It is the per-hop redaction a relay needs: each daemon
+redacts what it knows before output leaves it.
+
+## Sketch
+
+The v2 shapes together. Names are illustrative.
+
+```rust
+enum Principal { Admin, Session(Arc<Session>) }
+
+enum AdminRequest { Register(RegisterRequest), Reload(..), ListSessions, Revoke(..), Renew(..), Logs(..), Stop }
+enum SessionRequest { Exec { tool, args, cwd }, Stdin { data }, StdinEof, List, Check }
+
+struct RegisterRequest {
+    root: PathBuf,
+    layers: Vec<Layer>,                // kind, path, approved, hash
+    config: RawConfig,                 // the TOML raw types; deny_unknown_fields
+    secrets: Vec<(Label, Secret<String>)>,
+    env_snapshot: Vec<(String, String)>,
+    path: Vec<PathBuf>,
+    name: String,
+    sandbox: SandboxKind,
+}
+
+struct Session {
+    id: SessionId,
+    token: Secret<Token>,
+    root: PathBuf,
+    policy: ArcSwap<SessionPolicy>,    // compiled; Reload swaps it
+    binding: ProcessTree,              // anchor pid and start time
+    ends: Ends,                        // Lease | Ttl
+    execs: AtomicU64,
+}
+
+enum ErrorKind { NoSession, SessionEnded, SessionExpired, OutsideProcessTree, DaemonUnreachable,
+                 UnknownTool, BinaryUnusable, StaleSecret, OutsideRoot, Malformed }
+```
diff --git a/docs/airlock-v2-topology.md b/docs/airlock-v2-topology.md
new file mode 100644
index 0000000..cfea812
--- /dev/null
+++ b/docs/airlock-v2-topology.md
@@ -0,0 +1,229 @@
+# Airlock v2 — topology and the central daemon
+
+**Status:** proposal, companion to [airlock-v2-design.md](airlock-v2-design.md).
+The design doc describes one daemon per user whose sessions resolve their
+own secrets (option B below). This document records the longer direction, a
+central Airlock daemon, what that direction requires, compares the local
+topologies against it, and proposes what v2 should change so that it stays
+on the path. Nothing here is folded into the design yet.
+
+## The direction
+
+Airlock should be able to run as a central service, not only as a daemon on
+the developer's machine:
+
+- A daemon reachable over the network, on a central server.
+- Some secrets shared and declared on the daemon's side, resolved by the
+  daemon with its own credentials. Others local, resolved on the developer's
+  machine, as today.
+- Some tools run centrally, next to the shared secrets. Others run locally,
+  against the working tree.
+
+The agent keeps one entry point. The local daemon serves local tools and
+forwards the rest:
+
+```
+developer's machine                             central server
+┌───────────────────────────────┐               ┌────────────────────────────────┐
+│ agent, sandboxed              │               │ airlock server                 │
+│   airlock exec -- gh pr list  │               │   admin-owned config:          │
+│   airlock exec -- kubectl …   │               │     shared secrets, policy,    │
+│              │                │ TLS, identity │     central tools, proxies     │
+│              ▼                │               │                                │
+│ local daemon                  ├──────────────►│ runs kubectl in its sandbox,   │
+│   project config, approval    │ forwarded     │ streams redacted output back   │
+│   local secrets (1Password)   │ exec; secret  │                                │
+│   runs gh in its sandbox      │ fetch         │ vends GH_TOKEN to the local    │
+│                               │◄──────────────┤ daemon for the local gh        │
+└───────────────────────────────┘               └────────────────────────────────┘
+```
+
+## What it requires
+
+Four things. v2 provides none of them, which is fine as long as v2 does not
+build in their way.
+
+### Identity and policy
+
+Today the daemon trusts whoever reaches the socket as the user, because the
+socket is mode 0700 and the agent runs as the same uid. A server has many
+users and cannot trust a socket. It needs:
+
+- **Authentication** of each client: mTLS client certificates, an OIDC
+  token, or an SSH certificate.
+- **Authorization**: which identity may use which tools and which secrets,
+  for which project.
+- **Audit**: every exec attributed to an identity, not to a session id on
+  one machine.
+
+The v2 mechanisms that stand in for this locally are the admin token, the
+socket mode, the peer uid, and the binding of a session token to a process
+tree. All of them are host-local by construction. The server replaces them;
+it does not extend them.
+
+### Two kinds of secrets
+
+| Kind | Declared | Resolved by | Shared |
+|---|---|---|---|
+| daemon-side | in the daemon's own config: the global layer locally, the admin's config centrally | the daemon, with its own credentials, once; refreshed by the daemon | across every session that may reference the label |
+| client-side | in the project layers | the launcher, in the user's terminal, per session | no |
+
+v2 as designed has only client-side secrets. Even a global binding is copied
+into the session by `from = "global"` and resolved by the launcher, so two
+sessions in one project prompt 1Password twice ([Scope](airlock-v2-design.md#scope)),
+and the daemon's own environment is declared irrelevant
+([Lifecycle](airlock-v2-design.md#lifecycle)). A central server is the
+opposite: its secrets are daemon-side by definition, and it has no terminal
+to prompt in. The distinction has to exist in the local daemon first, or the
+server is a different program.
+
+### Tool placement
+
+A tool runs where its working tree and its secret are, and the two pull in
+different directions:
+
+| Tool | Secret | Runs | Does the secret reach the developer's machine? |
+|---|---|---|---|
+| `gh` with a shared token | central | locally: it needs the checkout | yes: the server vends it to the local daemon, which injects it into the sandboxed `gh` and redacts the output, as today |
+| `curl` as a proxy tool against an API | central | locally; the credential is attached on the server | no |
+| `kubectl get pods` with a shared kubeconfig | central | centrally: it needs no checkout | no |
+| `tofu plan` | central or local | locally: it needs the working tree | yes |
+
+So "central secret, local CLI" means vending the secret to the laptop. The
+laptop's daemon holds it in memory, as it holds every secret today. What the
+server adds is policy, rotation and audit, not a secret that never leaves
+the server. Only proxy tools and centrally run tools keep the secret off the
+developer's machine. The first central cases are therefore proxy tools and
+project-less CLIs. Tools that need the working tree stay local; running
+them centrally is a remote development problem and out of scope.
+
+### Transport
+
+[Transport](airlock-v2-design.md#transport) in the design doc already keeps
+a TCP transport possible: `AIRLOCK_ADDR` is a URI, authorization starts
+from a token, and requests carry no file descriptors. A server also needs
+TLS on the listener and tokens bound to the client's TLS identity
+([F11](airlock-v2-design.md#follow-ups)). Forwarding adds one constraint: an
+`Exec` request must be meaningful on another host, so it carries the tool
+name, the arguments, the stdin stream and the working directory relative to
+the project root, and nothing host-specific beyond that.
+
+## Local topologies compared against the direction
+
+| Option | Shared secrets, one prompt | A crash or a bug reaches | Authentication | What transfers to a central daemon | v2 size |
+|---|---|---|---|---|---|
+| **A. One daemon per session.** Today's embedded daemon (`run_embedded` in [src/daemon.rs](../src/daemon.rs)), with its socket in the runtime dir and a token in the agent's environment; `session start` is the same daemon detached with a TTL | no: each session resolves its own | that session | the token; the daemon is the launcher, so a peer must descend from it | the protocol shape | small |
+| **B. One daemon per user, sessions, launcher-resolved secrets.** The design doc as written | no: sessions resolve their own by design | every session on the machine | admin token, socket mode, PID-tree binding; all host-local | the protocol shape and the multi-session skeleton | large |
+| **C. One daemon per user with a daemon-side layer.** As B, but the global layer belongs to the daemon: it resolves and refreshes those secrets once and serves them to every session; sessions carry the project layers and client-side secrets | yes: a global secret is resolved once per daemon | every session on the machine | as B | the protocol, the skeleton, and the daemon-side/client-side split the server needs | B, plus daemon-side config |
+| **D. A central server, with the local daemon as the agent's single entry point and relay** | yes, org-wide | the server: every user | TLS identity, policy, audit | is the target | a design of its own |
+
+A is not a dead end: a central server is a separate role that any local
+daemon can use as a secret source and a remote executor. But A and B are
+equally far from D, since what they share with it is the protocol shape,
+and B pays for a multi-session skeleton whose authentication D throws away.
+C is the one option that builds something D needs and the others do not.
+
+## What v2 should change
+
+If D is the direction, these changes keep v2 on the path. Each names the
+design doc sections it touches.
+
+1. **Choose C over B.** The global config becomes the daemon's: the daemon
+   reads it at start, resolves its secrets once, refreshes them, and serves
+   them to every session that references them. The launcher still resolves
+   project secrets in the user's terminal. `Register` carries client-side
+   secret values and the list of daemon-side labels the session may use;
+   the daemon checks the list against the approved config and records it on
+   the session.
+   - *Touches:* [Registering a session](airlock-v2-design.md#registering-a-session)
+     (steps 2 and 5), [Scope](airlock-v2-design.md#scope) (the second
+     prompt disappears, which answers G10),
+     [Lifecycle](airlock-v2-design.md#lifecycle) ("the daemon's own
+     environment does not matter" no longer holds for daemon-side secrets),
+     [Session isolation](airlock-v2-design.md#session-isolation) (the
+     daemon-side store is shared by design; a session reaches it only
+     through the label list recorded at `Register`), and the Decisions rows
+     "Daemon topology" and "Session state".
+   - *Trade:* the daemon's environment matters again for `op` and `gcloud`,
+     as it did in v1. An automatically started daemon inherits the
+     environment of the launcher that started it. A service daemon has the
+     login environment, not the shell's. Both tools work from per-user
+     sockets and config directories, so this is a documentation item.
+
+2. **Name the host-local authentication for what it is.** Group the admin
+   token, the socket mode, the peer uid and the PID-tree binding under one
+   heading, "Unix transport authentication", and state that a network
+   transport replaces them. Nothing else in the design should depend on
+   them.
+   - *Touches:* [Admin credential](airlock-v2-design.md#admin-credential),
+     [Token binding](airlock-v2-design.md#token-binding),
+     [Transport](airlock-v2-design.md#transport), F11.
+
+3. **Bind labels by the secret's owner, not by a project line.** A
+   daemon-side secret is bound to a project label when its owner allows it:
+   the user, by approving the repo file's label requests, which the prompt
+   annotates with what each would resolve to; the admin, by policy, on a
+   central server. `from = "global"` is a per-project ceremony that a server
+   would never have, and `init --local` already writes it automatically for
+   every label the global layer binds, so it is not the explicit opt-in B3
+   asked for.
+   - *Touches:* [Secret labels across layers](airlock-v2-design.md#secret-labels-across-layers),
+     [Unapproved files at session start](airlock-v2-design.md#unapproved-files-at-session-start)
+     (the annotation), B3, `init --local`.
+
+4. **Decide the first remote case and add placement.** A tool gets an
+   optional placement: `run = "local"` by default, or the name of a daemon
+   the local daemon forwards to. Proxy tools and project-less CLIs are the
+   first central cases. The local daemon is the agent's only address; it
+   forwards an `Exec` and streams the result back. v2 implements no
+   forwarding, but `Exec` is shaped so that a relay can forward it.
+   - *Touches:* [Transport](airlock-v2-design.md#transport), F11, the
+     `[tools.<name>]` schema.
+
+5. **Give the project an identity that is not a path.** The trust store
+   keys a project by the hash of its canonical root, which is host-local. A
+   central policy says "this identity may use this secret for this
+   project", and needs a project identity that two machines agree on: a
+   declared name in `airlock.toml`, or the git remote. v2 can keep the path
+   hash for approval and add the declared name when placement lands, but
+   the schema should leave room for it.
+   - *Touches:* [Trust store](airlock-v2-design.md#trust-store),
+     [Scope](airlock-v2-design.md#scope).
+
+## What v2 must keep possible
+
+The constraints a central daemon puts on v2, in one place:
+
+- `AIRLOCK_ADDR` stays a URI; authorization starts from the session token;
+  requests carry no file descriptors or other host-local handles. (Already
+  in the design.)
+- The protocol distinguishes daemon-side from client-side secrets. `Exec`
+  never carries a secret value. `List` reports where each secret comes
+  from.
+- `Exec` carries the working directory relative to the project root, so it
+  can be forwarded.
+- Session scoping is by project, and the project will need a
+  host-independent identity.
+- The daemon owns a config layer of its own. Locally that is the global
+  file; centrally it is the admin's.
+
+The implementation-level form of these constraints, for the design as it
+stands, is in
+[airlock-v2-technical-guidance.md](airlock-v2-technical-guidance.md).
+
+## Open questions
+
+- **Relay or two sessions.** Either the local daemon forwards central
+  tools, or the agent holds a local and a central session. The relay keeps
+  one address and one token in the agent's environment, and lets the local
+  daemon log every exec. This document assumes the relay.
+- **Daemon-side sources on a server.** `source = "command"` works on a
+  server as it does locally. Vault and cloud secret managers may deserve
+  first-class sources, which is the same question as the multi-value
+  sources in [TODO.md](../TODO.md).
+- **Where the audit log lives.** Locally the ring buffer; centrally
+  something durable, attributed to an identity.
+- **The trust model for central config.** The admin's config is trusted as
+  the user's global file is trusted today: by who can write it. Whether the
+  user also approves what the server offers a project, or only the server's
+  policy decides, is open.
diff --git a/docs/airlock-v2-ux.md b/docs/airlock-v2-ux.md
new file mode 100644
index 0000000..0ee2bc4
--- /dev/null
+++ b/docs/airlock-v2-ux.md
@@ -0,0 +1,1012 @@
+# Airlock v2 — user experience
+
+What the user and the agent see when [Airlock v2](airlock-v2-design.md)
+ships: the commands and their options, their output and errors, the
+harness hooks, and the examples. The README, SKILL.md and SECURITY.md
+changes are listed in the design doc's
+[Docs to update when this ships](airlock-v2-design.md#docs-to-update-when-this-ships).
+
+**Status:** proposal, companion to [airlock-v2-design.md](airlock-v2-design.md).
+The design doc decides the mechanism. This doc decides the surface. Where
+the surface needed the mechanism to change, the change is listed in
+[Changes to the design](#changes-to-the-design) and marked **(U<n>)** where
+it appears. U1–U16 are accepted and incorporated into the design doc,
+except U14, which is [planned for v2.1](airlock-v2-design.md#planned-for-v21).
+
+Paths in transcripts use `~`. The macOS runtime dir is shortened to
+`$RUNTIME`, which is `/var/folders/…/T/airlock`.
+
+## Principles
+
+- **One verb to start an agent.** `airlock run` is the command a user
+  learns first and uses daily. Everything else is setup, inspection or
+  repair.
+- **The terminal is where decisions happen.** Approval, secret prompts and
+  error explanations reach the user in the terminal they typed the command
+  in. Nothing the agent does produces a prompt.
+- **The agent gets messages it can relay.** Every error `exec` and `tools list`
+  print says what happened and what the user has to do, in words the agent
+  can pass on verbatim.
+- **Quiet when it works.** `airlock run` prints nothing before the agent
+  starts unless something needs the user. `-v` shows the steps.
+- **No state in the project.** `git status` shows `airlock.toml` and, if
+  someone forgot `.gitignore`, `airlock.local.toml`. Nothing else.
+- **Agent commands are separate from the user's.** What the agent and its
+  harness run sits under `airlock agent`. `exec` and `tools list` serve
+  both. Inside the sandbox, help hides what only works in the user's
+  terminal, and says that it does.
+- **The agent learns its tools from the harness, not only from the skill.**
+  A harness hook tells the agent at start which tools it must run through
+  Airlock. See [Harness hooks](#harness-hooks).
+
+## Who runs what
+
+| Where | Commands | Needs |
+|---|---|---|
+| User's terminal | `run`, `init`, `trust`, `config`, `status`, `session …`, `daemon …` | nothing; the daemon starts on demand |
+| Both | `exec`, `tools list` | a session; or, for `tools list --session`, the user's terminal |
+| The agent | `agent check` | `AIRLOCK_ADDR` and `AIRLOCK_SESSION`, set by the session |
+| The harness, as a hook | `agent hook claude-code` | same; prints nothing in a project without Airlock |
+| Refused inside the sandbox | `run`, `trust`, `status`, `session`, `daemon`, `init --global` | — |
+
+`init` and `config` are allowed inside the sandbox. `init` writes a
+project file that still needs approval, so an agent can draft a config for
+the user to review. `init --global` is refused: the global file needs no
+approval, so nothing would review it. `config` shows the global layer as
+unreadable if the sandbox cannot read it.
+
+## Command surface
+
+```
+airlock run [--profile NAME] [-- CMD...]     start an agent with a session, sandboxed
+airlock init [--local | --global]            write a starter config
+airlock trust [-y]                           review and approve project config
+airlock config                               merged config, with the layer each part comes from
+airlock status                               daemon, project config and sessions
+airlock exec -- TOOL [ARGS...]               run a declared tool through the session
+airlock tools list [--session ID]            tools a session serves
+airlock agent check                          (agent) verify the session, self-test the sandbox
+airlock agent hook claude-code               (harness) SessionStart hook
+airlock session start | renew | list | reload | revoke
+airlock daemon start [--foreground] | stop | restart | logs | install | uninstall
+```
+
+Changes from today:
+
+| Today | v2 |
+|---|---|
+| `airlock daemon start` before anything works | The daemon starts on demand. `daemon start` is for manual control. |
+| `airlock run` embeds a daemon | `run` registers a session with the per-user daemon. Several agents per project work. |
+| `airlock run --no-daemon` | `airlock run --no-session` (U2) |
+| — | A harness with its own sandbox gets its session from `session start`, like an IDE. `run` always sandboxes. |
+| `airlock run --no-config` + `AIRLOCK_SANDBOX_ROOT` | `--no-project-config` |
+| `--config` on every command | Only on commands that discover config: `run`, `trust`, `config`, `status`, `session start/reload` (U10) |
+| `airlock list` reads `airlock.toml` | `airlock tools list` asks the daemon about the current session, or any session with `--session` (U5). `airlock config` reads the files (U4). |
+| `airlock status`: is a daemon up | `status` shows daemon, project layers, approval state and sessions |
+| `airlock daemon run` | `airlock daemon start --foreground` (U15) |
+| `airlock logs` | `airlock daemon logs` (U15) |
+| — | `trust`, `config`, `session`, `daemon install/uninstall`, `agent check`, `agent hook` |
+| Help is the same everywhere | Inside the sandbox, help lists only the commands that work there, and names the hidden ones (U16) |
+| The agent learns about Airlock from SKILL.md alone | A SessionStart hook puts the session state and tool list in the agent's context (U13) |
+
+## Changes to the design
+
+Each item changed something [airlock-v2-design.md](airlock-v2-design.md)
+had decided or left open. All are accepted, and the design doc now
+describes them. The table stays as the record of what changed and why.
+
+| # | Change | Design before | Why |
+|---|---|---|---|
+| U1 | `airlock run` and `session start` show the diff and ask `Trust this version and continue? [y/N]` on a terminal. On a non-terminal they refuse as the design says. | Refuse, print the diff, point to `airlock trust`; "interactive prompt at start" rejected. | Refuse → `trust` → run again is three commands for one decision, and it is the most common path: every edit of the user's own local file goes through it. The prompt is exactly as safe as `airlock trust`'s: the control is that no sandbox can write the trust store, not the terminal. Startup stays non-interactive for scripts. |
+| U2 | Fold `session exec` into `airlock run --no-sandbox`. Rename `--no-daemon` to `--no-session`. | `session exec -- <harness>` next to `run`. | `airlock exec` runs a tool; `airlock session exec` would run an agent. Two meanings of `exec` in one CLI. `run` with two switches (sandbox, session) covers all four cases with one verb. Resolves F8: under `--no-session` there is no session, so `tools list` fails with the same message as anywhere else. Later revised: `--no-sandbox` is removed, and a harness with its own sandbox uses `session start` (questions G5). |
+| U3 | `airlock init --local` writes `airlock.local.toml` with a binding stub per repo secret label, using `from = "global"` where the global layer binds the label. Validation runs before the approval prompt. | Not covered. | Joining a team repo otherwise means reading the repo file, finding unbound labels, and writing TOML by hand. Validating first means the user is never asked to approve a file that would fail anyway. |
+| U4 | New `airlock config`: the merged config with the layer each item comes from and each file's approval state. Reads the files; no daemon or session. | `list` asks the daemon; nothing for the human side. | Three layers raise "where does this come from?" (as `git config --show-origin` answers). `tools list` shows what a session serves, not what the files say. |
+| U5 | Commands are grouped by audience. `list` becomes `tools list`, which serves the current session, or with `--session <ID or name>` any session from the user's terminal. The agent's own commands go under `airlock agent`: `agent check` and `agent hook`. `status` stays the user's view. | `list` at the top level, session only; `status` for both. | The agent's plumbing should not sit next to the user's commands, and the user should be able to see what a running agent can use. The session's view of itself belongs to `agent check`, so `status` needs no second mode. |
+| U6 | `airlock session reload [ID…]`, run by the user: loads and approves config, resolves secrets, swaps the session's config. The token stays valid. | Non-goal: running sessions keep their config until they end. | An agent that adds a tool to `airlock.toml` otherwise has to be restarted to use it, losing its context. The design's concern, that tools change under a running agent, holds: they change only when the user asks. |
+| U7 | `exec` and `run` exit with 125 when Airlock itself fails, 126 when a declared tool's binary cannot be used, and 127 when no such tool is declared. | Exit 1 for every Airlock error. | 1 is also the most common tool failure. Same convention as `docker run`, `env` and `chroot`. SKILL.md can say "125 means tell the user". |
+| U8 | `session start` takes `--ttl` (default 12h; `0` means until revoked). | Ends on revoke or daemon stop only. | A forgotten `session start` keeps a token valid, and an automatic daemon running, indefinitely. |
+| U9 | Version handshake on connect. A launcher that finds an idle daemon of another version restarts it. A busy one keeps serving, with a note, unless the protocol is incompatible. | Not covered. | An automatic daemon outlives the binary it was started from. |
+| U10 | `--config` is not global; `daemon status` is dropped. | `--config` global; `daemon status` kept. | `exec` and `tools list` ignore files, so a `--config` there is a silent no-op. One status command is enough. |
+| U11 | `--name` on `run` and `session start`. Default: the harness command's base name, or `shell`. | Sessions have only an id. | `session list` and `trust` notes need something a person recognizes. |
+| U12 | Optional `description` on `[secrets.<label>]`. | Not in the schema. | A repo label without a source is a request to each user. The description tells them what to supply. |
+| U13 | `airlock agent check` (session check and sandbox self-test) and `airlock agent hook claude-code` (SessionStart: check, then list tools into the agent's context). The session records whether the agent runs in Airlock's sandbox or an external one. `--profile claude` installs the hook. | Not covered. | Whether the agent uses `airlock exec` depends on it reading SKILL.md. A hook delivers the same facts on every start and after every compaction, and catches a broken sandbox before the agent's first `exec`. |
+| U14 | **Deferred to v2.1.** `airlock completions <bash\|zsh>`: a dynamic completion script that asks the daemon for tool names and session ids, and hands off to the tool's own completion after `exec -- <tool>`. Nix and release tarballs install it. | Not covered. | `exec -- <TAB>` is where completion helps most, and only the session knows the tool names. A static script also goes stale on upgrade. Deferred because it pins an unstable clap_complete feature, calls the daemon on every TAB and needs hand-written shell delegation, and nothing in v2 depends on it. |
+| U15 | `airlock daemon run` becomes `airlock daemon start --foreground`; `airlock logs` becomes `airlock daemon logs`. | `daemon run`; `logs` at the top level. | "run" then always means starting an agent. Logs are daemon administration, rarely needed, and do not belong at the top level. |
+| U16 | With `AIRLOCK_SANDBOX=1`, `airlock --help` lists only the commands that work there. The help says so and names the hidden commands. A hidden command's own `--help` still works, and starts by saying it needs the user's terminal. | Same help everywhere. | An agent that reads the help should not be shown commands it cannot use. A user in a sandboxed shell has to see why a command is missing. |
+
+## Journeys
+
+### First run in a personal project
+
+```
+$ cd ~/src/app
+$ airlock init
+created ~/src/app/airlock.toml
+edit it to declare your tools, then run `airlock run --profile claude`
+```
+
+The user edits the starter into:
+
+```toml
+[secrets.GH_TOKEN]
+source  = "command"
+command = ["gh", "auth", "token"]
+
+[tools.gh]
+description = "GitHub CLI"
+[tools.gh.env]
+GH_TOKEN      = { secret = "GH_TOKEN" }
+GH_CONFIG_DIR = "{tool_state}"
+```
+
+```
+$ airlock run --profile claude
+~/src/app/airlock.toml is not trusted yet. Contents:
+
+    [secrets.GH_TOKEN]
+    source  = "command"
+    command = ["gh", "auth", "token"]
+    …
+
+Trust this file and continue? [y/N] y
+trusted ~/src/app/airlock.toml
+```
+
+Claude Code starts. Behind the prompt, `airlock run` resolved `GH_TOKEN`,
+started the daemon and registered a session. Nothing else was printed.
+With `-v`:
+
+```
+$ airlock run -v --profile claude
+airlock: project ~/src/app (repo: trusted)
+airlock: resolving GH_TOKEN (gh)… done
+airlock: started daemon, PID 48211, exits when idle
+airlock: session 7f3a9c "claude" registered, 1 tool
+airlock: sandbox: claude profile, root ~/src/app
+```
+
+If a secret command takes more than a second, the `resolving` line prints
+without `-v` too, so a 1Password or `gcloud` prompt that appears has
+context.
+
+Claude starts with the SessionStart hook's context already in place: the
+session is active, the self-test passed, and `gh` runs through
+`airlock exec` ([Harness hooks](#harness-hooks)).
+
+Inside the agent:
+
+```
+$ airlock tools list
+gh
+  GitHub CLI
+  GH_TOKEN = <secret "GH_TOKEN">
+  GH_CONFIG_DIR = "/Users/me/.cache/airlock/3f9a1c2b7d4e8a60/gh"
+
+$ airlock exec -- gh auth status
+github.com
+  ✓ Logged in to github.com account me (GH_TOKEN)
+  - Token: [REDACTED:GH_TOKEN]
+```
+
+When Claude exits, the session ends and `airlock run` exits with Claude's
+exit code. Five minutes later the daemon exits too.
+
+### Joining a team repo
+
+The team's `airlock.toml` declares labels and leaves the bindings to each
+user:
+
+```toml
+[secrets.GH_TOKEN]
+description = "GitHub token with read access to acme/app"
+
+[secrets.CLOUDFLARE_API_TOKEN]
+description = "Cloudflare token, Zone:Read on acme.dev"
+
+[tools.gh]
+…
+```
+
+The user's global config already binds `GH_TOKEN` for every project:
+
+```toml
+# ~/.config/airlock/airlock.toml
+[secrets.GH_TOKEN]
+source  = "command"
+command = ["op", "read", "op://Private/GitHub/token"]
+```
+
+```
+$ git clone git@github.com:acme/app ~/src/app && cd ~/src/app
+$ airlock run --profile claude
+error: 2 secrets in ~/src/app/airlock.toml have no source:
+  GH_TOKEN              GitHub token with read access to acme/app
+  CLOUDFLARE_API_TOKEN  Cloudflare token, Zone:Read on acme.dev
+the project leaves these to you. `airlock init --local` creates
+airlock.local.toml with a stub for each.
+
+$ airlock init --local
+created ~/src/app/airlock.local.toml
+  GH_TOKEN              from = "global" (your global config binds it)
+  CLOUDFLARE_API_TOKEN  not bound: edit airlock.local.toml
+airlock.local.toml is ignored by git
+```
+
+The generated file:
+
+```toml
+# Your bindings for this project. Keep it out of git.
+# Run `airlock config` to see the merged result.
+
+# GitHub token with read access to acme/app
+[secrets.GH_TOKEN]
+from = "global"
+
+# Cloudflare token, Zone:Read on acme.dev
+# Uncomment one:
+# [secrets.CLOUDFLARE_API_TOKEN]
+# source  = "command"
+# command = ["op", "read", "op://Private/Cloudflare/token"]
+#
+# [secrets.CLOUDFLARE_API_TOKEN]
+# source = "env"        # read from the environment of `airlock run`
+```
+
+If `airlock.local.toml` is not ignored, the last line instead reads:
+
+```
+warning: airlock.local.toml is not ignored by git. To ignore it in every repo:
+         echo airlock.local.toml >> ~/.config/git/ignore
+```
+
+The global excludes file (or the file `core.excludesFile` names) covers
+repos whose `.gitignore` the user does not own, and every later clone.
+
+After the user fills in the Cloudflare binding:
+
+```
+$ airlock run --profile claude
+~/src/app/airlock.toml is not trusted yet. Contents:
+    …
+Trust this file and continue? [y/N] y
+trusted ~/src/app/airlock.toml
+
+~/src/app/airlock.local.toml is not trusted yet. Contents:
+
+    [secrets.GH_TOKEN]
+    from = "global"       # → global: command op read op://Private/GitHub/token
+    …
+
+Trust this file and continue? [y/N] y
+trusted ~/src/app/airlock.local.toml
+```
+
+The user approves each file on its own. Declining either stops the run,
+with exit status 125. The `# →` note shows what `from = "global"` resolves
+to. It is not part of the file, and not part of what is approved.
+
+### A repo whose team has not adopted Airlock
+
+```
+$ cd ~/src/upstream-lib
+$ airlock init --local
+created ~/src/upstream-lib/airlock.local.toml (no airlock.toml here, so a standalone config)
+warning: airlock.local.toml is not ignored by git. To ignore it in every repo:
+         echo airlock.local.toml >> ~/.config/git/ignore
+```
+
+The file is a skeleton like the one `airlock init` writes: a commented
+secret and tool. The user fills it in and runs `airlock run` as usual. It
+is approved like any local file, and nothing lands in the team's
+`.gitignore`.
+
+### Every day
+
+```
+$ airlock run --profile claude
+```
+
+Nothing to approve, so nothing is printed before Claude starts. A second
+agent in the same project, in another terminal, works the same way and gets
+its own session:
+
+```
+$ airlock run -- codex
+```
+
+The second session resolves its own secrets, so any 1Password or `gcloud`
+prompt appears again, and a minted token is minted and refreshed for each
+session.
+
+```
+$ airlock status
+daemon    running, PID 48211, started on demand 2h ago
+address   unix://$RUNTIME/airlock.sock
+
+project   ~/src/app
+  global  ~/.config/airlock/airlock.toml   user file
+  repo    airlock.toml                     trusted
+  local   airlock.local.toml               trusted
+
+sessions  2 here, 3 in total
+  7f3a9c  claude  10:42  14 execs
+  b20e51  codex   11:30   2 execs
+```
+
+To see what a running agent can use, from the user's terminal:
+
+```
+$ airlock tools list --session codex
+session b20e51 "codex" for ~/src/app
+gh
+  GitHub CLI
+  GH_TOKEN = <secret "GH_TOKEN">
+  ...
+```
+
+`--session` takes an ID, a unique ID prefix, or a unique session name.
+
+### The agent changes the config
+
+The agent adds a `psql` tool to `airlock.toml` and tries it:
+
+```
+$ airlock exec -- psql -c 'select 1'
+airlock: no tool named "psql" in this session
+airlock: airlock.toml changed after this session started. Changes apply
+         once the user approves them (`airlock trust`) and reloads the
+         session (`airlock session reload`).
+$ echo $?
+127
+```
+
+The client can say this because the session carries the hash of each layer
+it loaded, and the agent can read the project files. SKILL.md tells the
+agent to report the change to the user.
+
+In the user's terminal:
+
+```
+$ airlock trust
+~/src/app/airlock.toml has changed since you last trusted it:
+
+--- trusted
++++ ~/src/app/airlock.toml
+@@ -14,3 +14,8 @@
+ GH_TOKEN = { secret = "GH_TOKEN" }
++
++[tools.psql]
++description = "Postgres shell"
++[tools.psql.env]
++PGSERVICE = "app-dev"
+
+Trust this version? [y/N] y
+trusted ~/src/app/airlock.toml
+2 sessions for ~/src/app use the previous config: 7f3a9c "claude", b20e51 "codex"
+run `airlock session reload` to apply it to them
+
+$ airlock session reload
+reloaded 7f3a9c "claude": tools +psql
+reloaded b20e51 "codex": tools +psql
+```
+
+The agent's next `airlock tools list` shows `psql`. Without U6, the user would
+end the agent and start it again. With Claude Code, `airlock run --profile
+claude -- claude --continue` keeps the conversation.
+
+An edit that adds something the user did not expect is the case approval
+exists for:
+
+```
+$ airlock run --profile claude
+~/src/app/airlock.toml has changed since you last trusted it:
+
+--- trusted
++++ ~/src/app/airlock.toml
+@@ -10,5 +10,6 @@
+ [filesystem]
+ read = ["/opt/homebrew/share"]
++write = ["~/.ssh"]
+
+Trust this version and continue? [y/N] n
+not trusted; nothing started
+```
+
+Text that could hide a change is escaped, so it cannot fool the user:
+
+```
++description = "GitHub CLI\u{202E}"
+```
+
+### A harness with its own sandbox, or an IDE
+
+`airlock run` always runs the agent in Airlock's sandbox. A harness that
+brings its own, such as Claude Code with `--sandbox`, or an IDE extension
+that no command can wrap, gets its session from `session start`:
+
+```
+$ eval "$(airlock session start --name claude)"
+session 7f3a9c "claude" for ~/src/app, expires in 12h
+note: this harness runs in its own sandbox, or none. It must deny reads of
+      $RUNTIME and keep the agent away from your credential stores; see
+      https://github.com/ModernPath/airlock/blob/main/SECURITY.md#external-sandboxes
+$ claude --sandbox
+```
+
+`session start` prints the export lines to stdout and the notes to stderr,
+so `eval` sees only the exports:
+
+```
+export AIRLOCK_ADDR='unix://$RUNTIME/airlock.sock'
+export AIRLOCK_SESSION='airlock_7f3a9c_<43 random characters>'
+```
+
+`-q` drops the note once the harness is set up. `--format fish` and
+`--format json` cover other shells and scripts.
+
+The harness inherits this shell's whole environment, unlike under
+`airlock run`. Start it from a plain shell, not from inside `op run`.
+
+For an editor:
+
+```
+$ eval "$(airlock session start --name vscode)"
+$ code .
+```
+
+Everything the editor starts inherits the token: every extension and
+every integrated terminal. If the editor is already running, `code .`
+opens a window in the running instance, which keeps the environment it
+started with, so quit it first. An editor started from the Dock gets no
+session; its agent's hook says so.
+
+The session is bound to this shell's process tree: a process that does not
+descend from the shell cannot use the token, even if it copies it. It ends
+after 12 hours. Before then, `session renew` restarts the clock without
+changing the token, so the editor keeps working:
+
+```
+$ airlock session renew vscode
+renewed 7f3a9c "vscode", expires in 12h
+```
+
+An expired session is gone, with its secrets. The agent's next `exec`
+says so, and the user starts a new session and restarts the editor from
+that shell.
+
+A shell where the user can run `airlock exec` by hand:
+
+```
+$ airlock run -- $SHELL                          # sandboxed, as the agent sees it
+$ eval "$(airlock session start --name shell)"   # in this shell, unsandboxed
+```
+
+### No project config
+
+```
+$ cd ~/scratch/experiment
+$ airlock run --profile claude
+error: no airlock.toml or airlock.local.toml in ~/scratch/experiment or a parent directory up to ~
+`airlock init` creates one here, or `--no-project-config` runs with your global config only
+
+$ airlock run --no-project-config --profile claude
+```
+
+### Upgrading Airlock
+
+The daemon runs until it is idle, so it can outlive an upgrade (U9):
+
+```
+$ brew upgrade airlock
+$ airlock run --profile claude
+note: the daemon runs airlock 0.5.0 and this is 0.6.0. It keeps serving its
+      2 sessions; it is replaced when it is idle, or now with `airlock daemon restart`.
+```
+
+If the daemon has no sessions, the launcher restarts it without a note. If
+the protocols are incompatible, the launcher refuses:
+
+```
+error: the running daemon (airlock 0.5.0) cannot serve this airlock (0.6.0)
+`airlock daemon restart` replaces it and ends its 2 sessions
+```
+
+### An always-on daemon
+
+```
+$ airlock daemon install
+wrote ~/Library/LaunchAgents/ai.modernpath.airlock.plist
+loaded it: the daemon now starts at login and keeps running without sessions
+```
+
+```
+$ airlock daemon install            # Linux
+wrote ~/.config/systemd/user/airlock.service
+enabled and started airlock.service
+note: systemd stops user services at logout. To keep the daemon running,
+      run `loginctl enable-linger`.
+```
+
+`airlock status` then shows `daemon running, PID 811, launchd service`.
+
+### Stopping things
+
+```
+$ airlock session revoke b20e51
+ended b20e51 "codex"
+
+$ airlock daemon stop
+this ends 2 sessions: 7f3a9c "claude" (~/src/app), c3d2e1 "vscode" (~/src/infra)
+Stop the daemon? [y/N] y
+daemon stopped
+```
+
+On a non-terminal, `daemon stop` and `restart` refuse when sessions exist,
+unless `--yes` is given. An agent whose session ended sees:
+
+```
+$ airlock exec -- gh pr list
+airlock: this session has ended (revoked by the user, or the daemon stopped).
+         Ask the user to start a new session.
+```
+
+## Harness hooks
+
+SKILL.md tells the agent to run `airlock tools list` and use `airlock exec`. An
+agent that does not load the skill, or loses it in a compaction, runs `gh`
+directly, gets "not logged in", and works around it. A harness hook puts
+the facts in the agent's context without relying on the agent (U13).
+
+Two commands, both under `airlock agent` because the agent and its
+harness run them, not the user:
+
+- **`airlock agent check`** is the engine, and works anywhere: it verifies
+  the session and self-tests the sandbox of the process that runs it. The
+  agent can run it by hand, and so can the user in a session shell.
+- **`airlock agent hook <harness>`** adapts `check` and `tools list` to
+  one harness's hook protocol. It reads the hook event from stdin and
+  writes what that harness expects. `claude-code` is the first adapter.
+  Others follow the harnesses that have hooks.
+
+### What `airlock agent check` verifies
+
+| Check | Passes when | Why |
+|---|---|---|
+| Session | `AIRLOCK_SESSION` is set and the daemon accepts it | Everything else depends on it. |
+| Daemon | it answers on `AIRLOCK_ADDR`, at a compatible version | Catches a stopped or stale daemon early. |
+| `admin.token` | opening it for reading fails | A readable token lets the agent register sessions for any project ([Under another harness](airlock-v2-design.md#under-another-harness)). The file is opened, never read. |
+| Runtime dir | creating a file in it fails | The agent must not replace the socket or CA. A file that was created is removed at once. |
+| Trust store | creating a file in it fails | The agent must not approve its own config. |
+| Global config dir | creating a file in it fails | The global layer is not approved, so it must not be writable. |
+| Environment | no variable named in any tool's `env` as a secret is set in this process | A tool secret in the agent's environment means it was passed some other way, for example by `--passthrough-env`. The daemon supplies the names through `List`, never the values. |
+| Credential stores | opening each tool's `extra_read` paths and `~/.config/gh`, `~/.config/gcloud`, `~/.aws`, `~/.kube` for reading fails | A warning, not a failure: `claude-relaxed` opens some on purpose. A readable store means the agent can take the credentials Airlock brokers directly. Paths that do not exist are skipped. |
+| Config | the project files' hashes match the session's | Not a failure. Reported so the agent can tell the user the config changed. |
+
+The client computes none of the paths. The daemon returns the runtime
+base, the trust store and the global config path the launcher validated
+for this session, so the probes test the same paths the launcher used.
+Every probe is a single `open` that is expected to fail. Nothing is read.
+
+**What a pass means.** The checks run in the process that runs
+`airlock agent check`, with that process's sandbox. They catch a misconfigured
+sandbox. They do not prove anything against a hostile agent, which could
+fake the output. The guarantees still come from the sandbox itself.
+
+**Which sandbox is tested.** The session records how the agent was started:
+`airlock` for `airlock run`, `external` for `session start`.
+
+- Under `airlock run`, the harness and its hooks run inside Airlock's
+  sandbox, so a hook's self-test tests the agent's sandbox.
+- Under an external sandbox, a hook may run outside that sandbox. Claude
+  Code's own sandbox applies to the commands the agent runs, not
+  necessarily to hooks. The hook then skips the probes, lists the tools,
+  and asks the agent to run `airlock agent check` once with its own shell tool,
+  which is sandboxed.
+
+### `airlock agent check`
+
+```
+$ airlock agent check
+session   7f3a9c "claude" for ~/src/app
+daemon    answers, airlock 0.6.0
+sandbox   Airlock's
+  ok      admin.token cannot be read
+  ok      runtime dir cannot be written
+  ok      trust store cannot be written
+  ok      global config cannot be written
+  ok      no tool secret in this environment
+  ok      credential stores cannot be read
+tools     gh, psql, tofu
+```
+
+A failure names the check and what the user has to fix:
+
+```
+$ airlock agent check
+session   7f3a9c "vscode" for ~/src/app
+daemon    answers, airlock 0.6.0
+sandbox   external
+  FAIL    $RUNTIME/admin.token can be read. The harness's sandbox must deny
+          reads of $RUNTIME, or this agent can start sessions for any project.
+  ok      runtime dir cannot be written
+  ...
+  warn    ~/.config/gcloud can be read. The agent can use your gcloud login
+          directly; deny it in the harness's sandbox.
+$ echo $?
+1
+```
+
+Exit status: 0 if every check passes, 1 if a check fails, 125 if there is
+no session or the daemon does not answer.
+
+### `airlock agent hook claude-code`
+
+Handles Claude Code's SessionStart event. It reads the event JSON from stdin and
+always exits 0, so its output reaches Claude as context, not as a hook
+error.
+
+**SessionStart.** Runs `check`, then `tools list`. Claude Code fires it on
+startup, on resume, after `/clear` and after compaction, so the tool list
+comes back after the context is compacted. When everything passes:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "Airlock is active for this project (session 7f3a9c, sandbox self-test passed).\n\nThese tools hold credentials. Run them only through Airlock, as `airlock exec -- <tool> [args...]`:\n\n  gh    GitHub CLI\n  psql  Postgres shell\n  tofu  OpenTofu\n\nRunning them directly fails: their credentials are not in your environment. Secrets in their output appear as [REDACTED:NAME]; that is expected. `airlock tools list` shows details. Other commands run directly as usual."
+  }
+}
+```
+
+The other outcomes:
+
+| State | Context for Claude | Message for the user (`systemMessage`) |
+|---|---|---|
+| No session, no Airlock config in the project | none, and no output | none |
+| No session, but the project has `airlock.toml` | "This project uses Airlock, but this agent was not started with `airlock run`, so tools that need credentials are unavailable. Tell the user. Do not look for credentials yourself." | "Airlock: this agent has no session. Start it with `airlock run`." |
+| Session ended, or the daemon does not answer | the `exec` error message, and "tell the user" | the same message |
+| A self-test check fails | "Airlock's sandbox self-test failed: <check>. Do not use `airlock exec` until the user fixes it. Tell the user." No tool list. | "Airlock sandbox self-test failed: <check>" |
+| External sandbox | the tool list, plus "Before your first `airlock exec`, run `airlock agent check` with your shell tool and report any FAIL to the user." | none |
+| Config changed since the session started | the tool list, plus the config-changed note from [The agent changes the config](#the-agent-changes-the-config) | none |
+
+Printing nothing outside Airlock projects means the hook can sit in the
+user-wide `~/.claude/settings.json` without effect elsewhere.
+
+Claude Code also offers a PreToolUse hook, which could deny a direct
+`gh pr list` and answer with the `airlock exec` form. It is left out for
+now. The SessionStart context is expected to be enough, and a hook on
+every shell command costs a daemon round trip per call and needs a command
+parser that is never complete.
+
+### Installing the hook
+
+`airlock run --profile claude` installs it. The profile's default command
+becomes:
+
+```
+claude --dangerously-skip-permissions --settings '<hook JSON>'
+```
+
+A user who passes their own command after `--`, or uses another way to
+start Claude Code, adds the hook to `~/.claude/settings.json` (all
+projects) or to the project's `.claude/settings.json` (committed for the
+team):
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      { "hooks": [{ "type": "command", "command": "airlock agent hook claude-code" }] }
+    ]
+  }
+}
+```
+
+`airlock agent hook claude-code --print-settings` prints this block, so the docs
+and the binary cannot drift apart.
+
+The agent can edit a project's `.claude/settings.json` and remove the hook.
+That is acceptable: the hook is guidance, and nothing depends on it for
+security.
+
+### Other harnesses
+
+Without a hook adapter, the generic form works in any harness that runs a
+command at start and shows its output to the agent:
+
+```
+$ airlock agent hook text
+```
+
+It prints the same context as the SessionStart hook, as plain text, and
+exits 0.
+
+## Shell completion
+
+**Status:** deferred to v2.1
+([design](airlock-v2-design.md#planned-for-v21)). The design below is
+complete and lands in its own PR after v2 ships.
+
+`airlock completions <bash|zsh>` prints a completion script for the shell
+(U14). The script is a thin registration: on each TAB it calls back into
+`airlock`, which computes the candidates. So completions know the current
+session's tools and the running sessions, and an installed script does not
+go stale when an upgrade adds a flag.
+
+### Installing
+
+| Shell | Per session (`~/.bashrc`, `~/.zshrc`) | As a file |
+|---|---|---|
+| bash | `source <(airlock completions bash)` | `airlock completions bash > ~/.local/share/bash-completion/completions/airlock` (bash-completion loads it on first use) |
+| zsh | `source <(airlock completions zsh)`, after `compinit` | `airlock completions zsh > ~/.zfunc/_airlock`, with `fpath+=(~/.zfunc)` before `compinit` |
+
+Packages install the file, so most users never run `completions`:
+
+- **Nix:** `postInstall` runs `installShellCompletion --cmd airlock` with
+  the output of `$out/bin/airlock completions bash` and `zsh`.
+- **Release tarballs:** `completions/airlock.bash` and
+  `completions/_airlock` next to the binary, generated by the release
+  build.
+
+### What completes
+
+| Position | Candidates | From |
+|---|---|---|
+| `airlock <TAB>` | subcommands; inside a sandbox (`AIRLOCK_SANDBOX=1`) only the ones that work there: `exec`, `tools`, `agent`, `config`, `init`, `completions` (U16) | static |
+| `airlock exec -- <TAB>` | the session's tools, with descriptions | a `List` request with the session token; nothing without a session |
+| `airlock exec -- gh <TAB>` | `gh`'s own completion, as if the line started with `gh` | delegation: zsh `_normal`, bash `_command_offset` |
+| `airlock run -- <TAB>` | commands, then that command's own completion | delegation |
+| `--profile` | `claude`, `claude-relaxed`, with descriptions | static |
+| `--config` | `*.toml` files | the shell's file completion |
+| `--allow-read`, `--allow-write` | paths | the shell's file completion |
+| `--passthrough-env` | names of exported variables | the shell |
+| `session renew`, `session reload`, `session revoke`, `tools list --session`, `daemon logs --session` | session ids, with name, project and start time | the daemon, with `admin.token`; outside the sandbox only |
+| `agent hook` | `claude-code`, `text` | static |
+| `session start --format` | `sh`, `fish`, `json` | static |
+
+In zsh, descriptions appear next to candidates:
+
+```
+$ airlock exec -- <TAB>
+gh    -- GitHub CLI
+psql  -- Postgres shell
+tofu  -- OpenTofu
+
+$ airlock session revoke <TAB>
+7f3a9c  -- claude  ~/src/app    10:42
+b20e51  -- codex   ~/src/app    11:30
+c3d2e1  -- vscode  ~/src/infra  09:05
+```
+
+bash shows only the candidates themselves, which is a bash limitation.
+
+Tool names complete in any shell with a session: one started with
+`airlock run -- $SHELL`, or after `eval "$(airlock session start)"`. Agents
+do not press TAB, so completion is for the user's own shells.
+
+### Rules for the completer
+
+Completion runs on every TAB, so it has to be fast and have no side
+effects:
+
+- It never starts the daemon, resolves secrets, prompts, or checks
+  approval. It only asks a running daemon.
+- Each daemon request has a 300 ms timeout. On any error it offers no
+  candidates and prints nothing: output on stderr would garble the
+  prompt line.
+- It uses a blocking `std` socket, not a tokio runtime, and runs before
+  anything else in `main()`.
+- A `List` request from completion is not logged as an `exec`.
+
+**Delegated completion runs the tool's own completer directly.** For
+`airlock exec -- gh pr <TAB>`, zsh calls `_gh`, which runs `gh __complete`
+from the shell's `PATH`. That `gh` runs without Airlock's credentials and
+outside the tool sandbox. Subcommands and flags complete; anything that
+needs the API, such as PR numbers, completes to nothing. It runs no more
+than typing `gh` in the same shell would, so it adds no new exposure (the
+design's [B1](airlock-v2-design.md#blocking) non-goal covers a planted
+`gh` on the user's `PATH`).
+
+### Implementation
+
+- `clap_complete`'s `CompleteEnv` provides the call-back protocol
+  (`COMPLETE=zsh airlock -- …`). `ArgValueCandidates` supplies tool names
+  and session ids.
+- Both sit behind clap_complete's `unstable-dynamic` feature, so pin the
+  minor version.
+- The `--` delegation is not part of `CompleteEnv`. `airlock completions`
+  wraps its script in a few lines per shell that hand off to `_normal` or
+  `_command_offset` after `exec -- <tool>` and `run --`.
+- The fallback, if `unstable-dynamic` turns out to be unusable: static
+  `clap_complete::generate` scripts plus a hidden `airlock __complete
+  <tools|sessions>` that hand-written shell functions call.
+- Tests drive the completer with `COMPLETE=bash` and `COMPLETE=zsh` against
+  a mock daemon. They check the candidates with a session, without a
+  session, inside the sandbox, and when the daemon does not answer.
+
+`clap_complete` also supports fish, elvish and PowerShell through the same
+mechanism. They are not tested and not documented until someone needs
+them.
+
+## Options
+
+The help text is written with the code. This section records the options
+each command takes and the decisions behind them, so nothing here needs to
+stay in sync with a verbatim draft.
+
+The top-level help groups commands by who runs them (U5): *Start an
+agent* (`run`, `init`, `trust`, `config`, `status`), *Use tools* (`exec`,
+`tools`), *Manage* (`session`, `daemon`) and *For the agent and its
+harness* (`agent`). clap has no subcommand headings, so this needs a
+custom `help_template`, and a test checks that every subcommand appears in
+it. The footer points to `airlock init`, then `airlock run --profile
+claude`. With `AIRLOCK_SANDBOX=1` the help lists only `exec`, `tools`,
+`agent`, `init` and `config`, says so first, and names the hidden commands
+(U16). A hidden command's own `--help` still works and starts by saying it
+needs the user's terminal. In a `session start` shell the variable is not
+set, and the help is complete.
+
+| Command | Options | Notes |
+|---|---|---|
+| `run [-- CMD...]` | `--profile <claude\|claude-relaxed>`; `--allow-read`, `--allow-write`, `--passthrough-env` (repeatable); `--name`; `--no-session`; `--config PATH`; `--no-project-config`; `-v`; `-q` | `CMD` is optional with `--profile`. Exits with the agent's status, or 125 when Airlock could not start it. `-v` reports each step before the agent starts; `-q` drops notes and warnings. |
+| `exec -- TOOL [ARGS...]` | none | No shell: `$VARS`, globs, pipes and redirects in `ARGS` are passed literally. Reads `AIRLOCK_ADDR` and `AIRLOCK_SESSION`. Exits with the tool's status, or 125, 126 or 127 as in [Messages](#messages). A tool can exit with those too; Airlock's own errors start with `airlock:` on stderr. |
+| `tools list` | `--session <ID>`: an id, a unique id prefix or a unique name; needs the user's terminal | `airlock tools` alone is `tools list`. With `--session`, a first line names the session. |
+| `agent check` | `-q` prints only failures | Exit 0, 1 when a check fails, 125 without a session. |
+| `agent hook <claude-code\|text>` | `--print-settings` prints the hook configuration and exits | Always exits 0. |
+| `trust` | `--config PATH`; `-y`, `--yes`; `--expect-sha256 HASH` (repeatable) | On a non-terminal, refuses without `--yes` or `--expect-sha256`. |
+| `init` | `--local`; `--global` | Fails if the file exists. `--global` is refused inside the sandbox. |
+| `config` | `--config PATH`; `--no-project-config`; `--paths` | Reads the files; no daemon or session. Output below. |
+| `status` | `--config PATH`; `--no-project-config` | Exit 0 when the daemon runs, 3 when it does not: the LSB and `systemctl status` convention, since a stopped daemon is normal in v2. |
+| `session start` | `--name` (default `shell`); `--ttl DURATION` (default `12h`, `0` for never); `--format <sh\|fish\|json>`; `--config PATH`; `--no-project-config`; `-q` | Exports on stdout, notes on stderr. |
+| `session renew <ID>` | `--ttl DURATION` (default: the session's) | Only for `session start` sessions. |
+| `session list` | `--here` | Columns: id, name, project, started, execs, what ends it, note (`config changed`). |
+| `session reload [ID...]` | `--all` | Without ids, every session for the project in the current directory. |
+| `session revoke <ID>...` | `--here`; `--all` | An id prefix is enough when it is unique. |
+| `daemon start` | `--foreground` | `--foreground` stays attached and logs to stderr; it is what the launchd agent and the systemd unit run. |
+| `daemon stop`, `daemon restart` | `-y`, `--yes` | Ask first on a terminal when sessions exist; refuse on a non-terminal without `--yes`. |
+| `daemon logs` | `--session <ID>` | |
+| `daemon install`, `daemon uninstall` | none | |
+
+`daemon --help` says that `run` and `session start` start the daemon when
+it is not running, and that a daemon started that way exits after
+5 minutes with no sessions.
+
+`airlock config` output:
+
+```
+$ airlock config
+layers
+  global  ~/.config/airlock/airlock.toml   user file
+  repo    ~/src/app/airlock.toml           trusted
+  local   ~/src/app/airlock.local.toml     changed since trusted
+
+secrets
+  GH_TOKEN              local → global   command: op read op://Private/GitHub/token     (unapproved)
+  CLOUDFLARE_API_TOKEN  local            command: op read op://Private/Cloudflare/token (unapproved)
+
+tools
+  aws   global  AWS CLI
+  gh    repo    GitHub CLI       GH_TOKEN = <secret "GH_TOKEN">
+  psql  local   Postgres shell                                     (unapproved)
+
+settings
+  timeout                120          repo
+  filesystem.read        /opt/homebrew/share   repo
+  agent.passthrough_env  COLORTERM    global
+                         NO_COLOR     repo
+  agent.env.LOG_LEVEL    "debug"      local (overrides repo)      (unapproved)
+
+airlock.local.toml changed since you trusted it; the next session start asks about it.
+```
+
+## Messages
+
+The user sees the messages for launcher commands, and the agent sees the
+ones for `exec`, `tools list` and `agent check`. Every agent-facing message names the user
+action, so the agent can relay it without interpreting it.
+
+### Launcher (`run`, `session start`, `session reload`)
+
+| Situation | Message | Exit |
+|---|---|---|
+| No project config | `error: no airlock.toml or airlock.local.toml in <dir> or a parent directory up to ~` + hint for `init` / `--no-project-config` | 125 |
+| Invalid TOML or config | `error: <file>:<line>: <problem>`; nothing is approved | 125 |
+| Tool in repo and local | `error: tool "gh" is defined in both <repo> and <local>; add \`override = true\` to the tool in airlock.local.toml to replace the repo's` | 125 |
+| `override = true` on a tool the repo does not define | `error: <local>: tool "gh" sets override, but the repo defines no "gh"` | 125 |
+| Repo label without a binding | lists labels with descriptions + `airlock init --local` hint | 125 |
+| Global item uses a repo label | `error: <global>: tool "x" uses secret "Y", which your global config does not declare` | 125 |
+| Unapproved file, terminal | diff or full file, `Trust this version and continue? [y/N]` (U1); on `n`, `not trusted; nothing started` | 125 on `n` |
+| Unapproved file, no terminal | diff or full file + `run \`airlock trust\` in a terminal to approve it` | 125 |
+| Anchor redirected | `error: trust store <path> is inside the project root <root> (from XDG_STATE_HOME=…); refusing to use it` | 125 |
+| Write grant covers an anchor | `error: <file>: filesystem.write "<path>" covers <anchor>; Airlock's own files cannot be writable from a sandbox` | 125 |
+| Secret command fails | `error: secret GH_TOKEN: \`op read …\` exited with 1:` + its stderr, indented | 125 |
+| Runtime dir check fails | `error: runtime dir <path> is owned by uid 502, not you (501)`, and similar per check | 125 |
+| Daemon version skew | note or error as in [Upgrading Airlock](#upgrading-airlock) | 0 / 125 |
+| Run inside the sandbox | `error: \`airlock run\` cannot run inside an Airlock sandbox; run it from your own terminal` | 125 |
+| `status` inside the sandbox | `error: \`airlock status\` needs your own terminal. Inside a session, \`airlock agent check\` shows this session.` | 125 |
+
+### Agent (`exec`, `tools list`, `agent check`)
+
+| Situation | Message | Exit |
+|---|---|---|
+| No `AIRLOCK_SESSION` | `airlock: no Airlock session. The user starts one with \`airlock run\`; this process was not started that way.` | 125 |
+| Session ended or unknown | `airlock: this session has ended (revoked by the user, or the daemon stopped). Ask the user to start a new session.` | 125 |
+| Session expired | `airlock: this session expired. Ask the user to start a new one, or to renew sessions before they expire with \`airlock session renew\`.` | 125 |
+| Caller outside the session's process tree | `airlock: this process was not started from the session's agent or shell, so it cannot use the session.` | 125 |
+| Daemon unreachable | `airlock: the daemon at <addr> does not answer. Ask the user to check \`airlock status\`.` | 125 |
+| Undeclared tool | `airlock: no tool named "x" in this session` + config-changed hint when a layer's hash differs | 127 |
+| Binary not found | `airlock: tool "tofu" is declared, but no \`tofu\` is on the session's PATH` + the dropped `PATH` entries and why, and: install the tool outside the project (Homebrew, mise, Nix) | 126 |
+| Binary in the project | `airlock: tool "gh" resolves to ~/src/app/bin/gh, inside the project; refusing to run it. Install it outside the project (Homebrew, mise, Nix).` There is no override. | 126 |
+| Stale secret | `airlock: secret "X" is stale (last refresh failed: …). The user needs to fix its source; Airlock retries on its own.` | 125 |
+| Working dir outside root | `airlock: <cwd> is outside this session's project ~/src/app` | 125 |
+| Self-test failure (`agent check`) | `FAIL <what> can be <read/written>.` + the fix, as in [`airlock agent check`](#airlock-agent-check) | 1 |
+
+## Examples
+
+`examples/` today has single-file configs whose headers say to start the
+daemon with `airlock daemon start`, and two shell scripts that wrap
+`daemon start` in `op run` and Vault.
+
+| File | v2 |
+|---|---|
+| `github-only.toml`, `github-and-opentofu.toml`, `kubernetes.toml`, `cloud-providers.toml`, `gcp-*.toml` | Same content. The header says how to run it: copy it to `airlock.toml`, then `airlock run --profile claude`, and approve it when asked. `source = "env"` examples show `op run -- airlock run`. |
+| `1password-startup.sh`, `vault-startup.sh` | Removed. Replaced by `secret-sources.toml`: command sources for 1Password, Vault, `gh auth token` and `gcloud`, plus the `op run -- airlock run` line for `env` sources. |
+| `team/airlock.toml` (new) | A repo file: labels with `description` and no `source`, tools, `[agent]`. |
+| `team/airlock.local.toml` (new) | One user's bindings: `from = "global"` for one label, a `command` for another, a personal tool. |
+| `team/global.toml` (new) | A `~/.config/airlock/airlock.toml`: global bindings, a personal `aws` tool, `agent.passthrough_env`. |
+| `team/README.md` (new) | The three files, the merged result (the table from the design doc's worked example), and the onboarding transcript from [Joining a team repo](#joining-a-team-repo). |
+
+Header comment for a single-file example:
+
+```toml
+# Minimal setup: GitHub CLI only
+#
+# Use it:
+#   cp examples/github-only.toml airlock.toml
+#   airlock run --profile claude        # asks you to trust the file the first time
+#
+# Inside the agent:
+#   airlock exec -- gh repo list
+#   airlock exec -- gh issue list --label bug
+```
+
+## Open UX questions
+
+- **Session id and token format.** The proposal: a 6-hex id, and a token
+  `airlock_<id>_<43 base64url characters>`. The prefix lets secret
+  scanners recognize the token, and logs can name the session without
+  the secret part. Is the prefix worth the length?
+- **Idle grace period.** 5 minutes is a guess. It should be long enough
+  that two quick `airlock run`s share a daemon, and short enough that a
+  forgotten daemon goes away.
+- **Should `airlock trust` offer to reload sessions?** One more prompt
+  (`Reload 2 running sessions now? [y/N]`) against a separate command.
+  This doc keeps it separate.
+- **`daemon install` while an automatic daemon runs.** Either the service
+  waits for the socket to free up, or `install` tells the user to run
+  `daemon restart`. The second is simpler. The first keeps sessions alive.
+- **Worktrees (F6).** When a file is byte-identical to a copy approved for
+  the same git common dir, the prompt could say `identical to the file you
+  trusted in ~/src/app; trust it here too? [Y/n]`. That cuts the cost without
+  implicit trust.
+- **Long diffs.** Page through `$PAGER` when the diff is longer than the
+  terminal? The escaping already happens before output, so the pager
+  cannot interpret anything.
+- **Is `--settings` the right injection point?** Verify that
+  `claude --settings` merges hooks with the user's own settings rather than
+  replacing them. Also decide what happens when the user has also
+  installed the hook in `settings.json`: the tool list would arrive twice.
+  `airlock agent hook` could set a marker variable on its first run and stay
+  silent on the second.
+- **Should a failed self-test block `exec`?** Today the hook only tells
+  the agent and the user. The daemon could refuse `exec` for a session
+  whose self-test failed. But the agent could simply skip the test, and an
+  external harness sandbox cannot be tested from the hook, so it would be a
+  convenience only.
+- **Completion inside the agent sandbox (v2.1).** A sandboxed
+  `airlock run -- $SHELL` loads the user's `.zshrc` only if the sandbox
+  can read it. `claude-relaxed` allows that; `claude` does not. Either
+  document `--allow-read ~/.zshrc`, or accept that completion works only in
+  unsandboxed session shells.
+- **Policy diff (F3).** When it lands, the prompt shows the effective
+  change above the byte diff, and a comment-only edit says so.