Name the binding that was actually doing it, and how to find yours

The section said stock tmux, which scrolls five lines. The configuration
that prompted this bound halfpage-up instead - half the pane, so twenty
lines in a forty-line one, which is what "more than half the screen" was.

Both are worth naming, and neither is worth guessing at from here: the
first line of the section is now the list-keys that answers it. The
example scrolls four rather than one, which is what the reported fix
settled on and reads better on a desktop sharing the same server.

.dejima.md

@@ -24,45 +24,75 @@ relaunch so the derived image is rebuilt), not installing it in-session.
 If it is missing and you cannot get a rebuild, say the suites were not run
 rather than reporting a change as tested.
 
-## Run the suite for what you changed, not all of them
+**`parallel` is declared for the same reason**, because CI runs every suite
+with `--jobs $(nproc) --no-parallelize-across-files` and `bats --jobs` needs
+GNU parallel to do it. Without it bats exits with `Cannot execute N jobs
+without GNU parallel` and prints no test output at all.
 
-The suites are independent and cover different areas. Running all of them for
-every edit is the single biggest drag on iteration here — reach for the whole
-set before opening a PR, not between edits.
+That failure is quiet in the worst way, so **check the exit status, not the
+output**. A suite that never ran emits no `not ok` line, so the obvious
+`| grep '^not ok'` check reports it as passing — which is how a change here
+was once reported green against a suite that had not executed. Requiring both
+a zero exit status and a non-zero count of `ok` lines catches it:
 
-| You changed | Run |
-| --- | --- |
-| `bin/dejima-audit` | `test/audit.bats` |
-| `bin/dejima-config-lib.sh`, `install.sh` | `test/config.bats` |
-| `bin/dejima-provider-lib.sh`, `forges/`, `workflows/`, `harnesses/` | `test/providers.bats` |
-| `bin/dejima-attach`, `-ttyd`, `-notify-watch`, `web/`, `systemd/` | `test/remote.bats` |
-| `bin/dejima-project-lib.sh`, `-dep`, `-project`, `-allow` | `test/project.bats` |
-| `bin/dejima-update-check` | `test/config.bats` |
-| `bin/dejima-tui-lib.sh` | `test/remote.bats` and `test/project.bats` (both tools use it) |
-| `bin/dejima-tty-suspend` | `test/static.bats` |
-| `tools/` | `test/providers.bats` |
-| `bin/dejima-anthropic-proxy`, `docker/anthropic-proxy-forwarder.js` | `test/proxy.bats` |
-| `docker/`, `hooks/`, `README.md`, `docs/` | `test/static.bats` |
-| anything under `docker/` that has to actually boot | `test/runtime.bats` (needs Docker) |
+```sh
+out="$(bats --jobs "$(nproc)" --no-parallelize-across-files test/config.bats 2>&1)"
+rc=$?
+n="$(grep -cE '^ok ' <<< "$out")"
+[ "$rc" -eq 0 ] && [ "$n" -gt 0 ] || { echo "$out"; exit 1; }
+```
 
-When the whole set genuinely is wanted, run it concurrently rather than one
-file after another:
+## Two lanes: one for iterating, one for the pull request
+
+Between edits:
+
+```sh
+bash test/run-confined.sh --changed
+```
+
+It reads `git diff` — committed, uncommitted and untracked — maps each path to
+the suites that cover it, and runs only those. `--list` prints the selection
+without running anything, and a path given as an argument stands in for one git
+would have reported, so `--changed --list docker/Dockerfile` answers "what would
+this change run?" directly.
+
+Before opening a pull request, and for any claim that a change is tested:
 
 ```sh
 bash test/run-confined.sh
 ```
 
-The suites share no state, so they run together safely: about seven minutes
-instead of about twenty-five. It reports what each suite ran as well as what
-failed, because a suite that cannot start - a syntax error, or duplicate test
-names, which bats refuses outright - exits nonzero having run nothing, and
-that reads as "no failures" to anything counting only failures.
+That is the gate: every confined suite, no selection. Each run prints which lane
+it was, and `--changed` says in as many words that it is not the gate. **A green
+`--changed` run is not a tested change** — it is evidence about the suites it
+names and nothing about the ones it skipped.
 
-Two things that are not in that table because they defeat it: `bin/dejima`
-itself and `bin/dejima-config-lib.sh` are read by nearly every other suite, so a
-change to either is one of the cases where the whole set genuinely applies. And
-a change to a shipped doc or a `docker/` file usually needs `static.bats` *as
-well as* whatever else it touched — that suite asserts on files it does not own.
+The map lives in `suites_for()` in `test/run-confined.sh` rather than in a table
+here, so that it runs instead of being remembered, and so an agent cannot map a
+change to the wrong suite by hand. A path matching no rule selects every suite:
+a path nobody has mapped is a path nobody has decided about. When you add a
+file that a specific suite covers, add the rule — `static.bats` checks the map
+names only suites that exist, but nothing can tell that a rule is too narrow.
+
+Both lanes run the tests within each file concurrently as well as the files
+themselves, which is most of where the wall clock went. It is bats' own
+`--jobs`, and it needs `flock` rather than GNU parallel; without `flock` the
+script falls back to one at a time and says so.
+
+**The concurrency is budgeted for the whole run, not per suite.** Every
+selected suite runs at once, so what lands on the machine is suites × jobs;
+asking each for `nproc` made that ten times the cores on a ten-core box. The
+script targets roughly twice the cores in total and divides, and prints both
+numbers. That is #295: several tests wait on a bounded deadline — a pty
+reaching raw mode, a shipper polling, an audit finishing — and a saturated
+machine blows through it, so they failed for the load rather than for the
+thing they check. If you add a test that waits for something, assume the
+machine is busy.
+
+Each run reports what every suite ran as well as what failed, because a suite
+that cannot start — a syntax error, or duplicate test names, which bats refuses
+outright — exits nonzero having run nothing, and that reads as "no failures" to
+anything counting only failures.
 
 **CI runs `test/runtime.bats` on every pull request**, as a separate
 `privileged` job in `.gitea/workflows/tests.yml`. So being unable to run it

.dejima/dependencies

@@ -29,6 +29,17 @@ npm:cline
 
 apt:tmux
 apt:bats
+
+# What `bats --jobs` needs. CI runs every suite with
+# `--jobs $(nproc) --no-parallelize-across-files`, so without this a sandbox
+# cannot run the suites the way they are actually run - and the failure is
+# quiet in the worst way: bats exits with "Cannot execute N jobs without GNU
+# parallel" and produces no test output at all, so a check that greps for
+# `not ok` reads a suite that never ran as a suite that passed.
+#
+# Debian's `parallel` IS GNU parallel. moreutils ships a different binary of
+# the same name and conflicts with it; bats needs this one.
+apt:parallel
 # The other half of what CI runs. The CI job installs it itself, so without
 # this line a sandbox is the one place the gate cannot be run at all - and a
 # base image that happens to carry it is not a guarantee, as one that stopped

.gitea/workflows/tests.yml

@@ -87,6 +87,7 @@ jobs:
           - config
           - providers
           - conversation
+          - share
     name: confined (${{ matrix.suite }})
     container:
       # Debian bookworm plus a node binary - node is what actions/checkout
@@ -163,9 +164,16 @@ jobs:
       # they fail on the terminal rather than on anything they mean to check.
       # xterm-256color ships in ncurses-base, which is Essential - nothing to
       # install. Set on the command rather than in env: so it survives su.
+      #
+      # --jobs runs the tests within the file concurrently. bats needs GNU
+      # parallel only to parallelize ACROSS files; within one file it uses its
+      # own flock-based semaphore, and flock is in util-linux, which Debian
+      # marks Essential - so nothing here has to install anything for it.
+      # --no-parallelize-across-files is what tells bats that, since it
+      # otherwise refuses --jobs outright when GNU parallel is absent.
       - run: |
           chown -R node:node .
-          su node -c "TERM=xterm-256color bats test/${{ matrix.suite }}.bats"
+          su node -c "TERM=xterm-256color bats --jobs $(nproc) --no-parallelize-across-files test/${{ matrix.suite }}.bats"
 
   shellcheck:
     # Its own job rather than a matrix entry: it installs a different package,
@@ -425,8 +433,18 @@ jobs:
       # SKIP_BUILD below then reuses this image rather than skipping a build.
       # The image is still built fresh from this commit, so the property the
       # test file defaults to - never assert against a stale image - holds.
+      # Named under localhost/ so a stray push cannot resolve to Docker Hub,
+      # like every other image this repo builds (#53).
+      #
+      # This step and runtime.bats must agree on that name, and they come from
+      # different commits: this file is read from the BASE branch (see the
+      # pull_request_target note at the top) while the checkout above is the
+      # branch under test. So a rename here lands in two steps - the base
+      # tagging both names first, then this - and a future one has to do the
+      # same. A single pull request that changes both sides fails, because the
+      # half that runs is the half it did not change.
       - name: Build the sandbox image
-        run: docker build -t dejima:latest -f docker/Dockerfile .
+        run: docker build -t localhost/dejima:latest -f docker/Dockerfile .
 
       - run: bats test/runtime.bats
         env:

.gitignore

@@ -1,7 +1,7 @@
 .claude
 web/node_modules
 
-# Python bytecode. bin/dejima-anthropic-proxy is a python program, so anything
+# Python bytecode. bin/dejima-credential-proxy is a python program, so anything
 # that imports or compiles it leaves these beside it.
 __pycache__/
 *.pyc

README.md

@@ -45,18 +45,18 @@ starts.
 
 - **An egress allowlist.** DNS and IP, IPv4 and IPv6. Anything not on the
   list does not connect, and the agent is told so.
-- **Credentials that stay on the host.** Your Anthropic OAuth credential
-  never enters the container: a host-side proxy holds it and the container
-  gets a placeholder. Your SSH key doesn't either; the container sees an
-  agent socket, never the key.
+- **Credentials that stay on the host.** Your model credential never enters
+  the container, whichever backend you selected: a host-side proxy holds it
+  and injects it per request, and the container gets a placeholder. Your SSH
+  key doesn't either; the container sees an agent socket, never the key.
 - **Per-project declaration and approval.** A project declares the domains
   and dependencies it needs in `.dejima/`. Declaring is not granting: the
   approval is a separate decision you make on the host, and the approval
   store is never mounted where a session could reach it.
-- **One project's session cannot reach another's.** `~/.claude` is not
-  mounted whole. A session gets its own project's transcripts, memory and edit
-  history and nothing else, so it cannot read what you did elsewhere or write
-  into another project's memory.
+- **One project's session cannot reach another's.** Your harness's state
+  directory is not mounted whole. A session gets its own project's
+  transcripts, memory and edit history and nothing else, so it cannot read
+  what you did elsewhere or write into another project's memory.
 - **CI hardening, because push access is code execution elsewhere.** A session
   opens a pull request, the workflow fires, and your runner executes that
   commit before you've read a line of it. The container bounds what a session
@@ -64,12 +64,17 @@ starts.
   [docs/ci.md](docs/ci.md) for what hardening a runner takes, and
   [dejima-ci-hardener](https://gitbox.branderson.io/dejima/dejima-ci-hardener)
   for a tool that does it.
-- **Guard rails inside the session.** Hooks refuse obviously destructive
-  commands, pushes to anywhere but the allowed remote, and merging a PR from
-  inside the sandbox. These are fast-fail guards against an overeager agent,
-  not a boundary against a hostile one: the container is the boundary.
+- **Guard rails inside the session.** Pushes to anywhere but the allowed
+  remote, and merging a PR from inside the sandbox, are refused whichever
+  harness is selected - they shadow `git` and the forge CLI on `PATH`. Refusing
+  an obviously destructive command needs a hook the harness can host, so a
+  harness without one goes without it, and the launch says so rather than
+  leaving you to assume. All of these are fast-fail guards against an
+  overeager agent, not a boundary against a hostile one: the container is the
+  boundary.
 - **An exit-time audit** of the host surfaces a session could have written to,
-  so a change to your git config or `~/.claude` does not go unnoticed.
+  so a change to your git config, to the workspace's own agent configuration,
+  or to a file your harness runs on the host does not go unnoticed.
 
 **What it gives an agent to work with:**
 
@@ -83,9 +88,10 @@ starts.
   name - and dejima loads it alongside a briefing on where the session is and
   why the limits are there. An agent that knows it is in a sandbox asks for a
   domain rather than working around the firewall.
-- **Config parity with your host.** `CLAUDE.md`, settings, hooks, plugins and
-  git identity carry over; uid, home directory and project path match on both
-  sides, so a session's transcript is readable from the host afterward.
+- **Config parity with your host.** Your harness's own global instructions,
+  settings, hooks, skills, rules and plugins carry over, and so does your git
+  identity; uid, home directory and project path match on both sides, so a
+  session's transcript is readable from the host afterward.
 - **Remote access, opt-in and off by default.** Attach to a live session from
   a terminal or a browser, with a push notification when it wants you.
 - **What a long session worked out, kept.** Each time the agent compacts, the
@@ -123,6 +129,32 @@ A note from the developer about the voice in this repository:
 
 [![Developed in dejima](assets/dejima-badge.svg)](https://gitbox.branderson.io/dejima/dejima)
 
+## The dejima stack
+
+dejima runs inside the machine it is protecting the rest of, so it cannot bound
+its own host, a runner it never touches, or notice anything after a session
+ends. These are what cover the rest. **Only the first row is required.** The
+last two are categories rather than products; the named ones are what this
+deployment happens to use.
+
+| Piece | Runs on | What it adds |
+| --- | --- | --- |
+| **dejima** | a devbox | The container boundary: what a session reaches on disk, and deny-by-default egress. |
+| **[dejima-devbox-hardener](https://gitbox.branderson.io/dejima/dejima-devbox-hardener)** | the same devbox | Cuts LAN reach to what is declared, enforced from outside the guest so root in the VM cannot flush it. |
+| **[dejima-guard](https://gitbox.branderson.io/dejima/dejima-guard)** | a different machine | Notices the devbox changed, against a baseline held off the box. Detection, not enforcement. |
+| **[dejima-ci-hardener](https://gitbox.branderson.io/dejima/dejima-ci-hardener)** | your CI runner | A runner that executes a session's pull request without that being LAN access. Hosted CI is the alternative, on someone else's network rather than yours. |
+| **ntfy**, or any push service | anywhere both can reach | Where "session needs input" and the guard's alerts arrive. |
+| **Uptime Kuma**, or any uptime monitor | off the devbox | The dead man's switch: what notices the guard itself stopped reporting. |
+
+**→ [docs/threat-model.md](docs/threat-model.md#the-stack-and-what-each-piece-buys)** -
+what each one buys, what goes wrong without it, and where each one's boundary
+ends. None of them is required to run dejima; what they change is what the
+layer below the container costs, and whether anyone finds out.
+
+**→ [Why a container, and not a microVM?](docs/threat-model.md#why-a-container-and-not-a-microvm)** -
+the most common question about this design, and why the effort went into the
+layers below the container rather than into a harder one.
+
 ## Setup
 
 This repo only holds the tooling; no project lives here. Point it at a project
@@ -143,10 +175,13 @@ ones you want.
    [Sign in on the host first](#sign-in-on-the-host-first) - and skip it
    entirely for a harness pointed at a model you serve yourself, which needs
    no credential.
-2. **`./install.sh`**, which symlinks the CLIs into `~/.local/bin`, writes a
-   starter `~/.config/dejima/config` if none exists, and registers whatever
-   guard hooks the harness you selected can host. Idempotent, so re-run it
-   after pulling; it never overwrites an existing config.
+2. **`./install.sh`**, which symlinks the CLIs into `~/.local/bin` and writes
+   a starter `~/.config/dejima/config` if none exists. It writes nothing to
+   your harness's own config: the sandbox's guards are baked into the image and
+   registered per launch into a settings layer of dejima's own, so installing
+   dejima does not change how your harness behaves outside a sandbox.
+   Idempotent, so re-run it after pulling; it never overwrites an existing
+   config.
 3. **Put `~/.local/bin` on your `PATH`** if it isn't already.
 4. **Set `[core] harness`.** It has no default and a launch is refused without
    it, which is what stops a later release changing your selection for you.
@@ -271,8 +306,8 @@ works if the host has a credential to hold. Authenticating from inside is not
 the fix: the container is where the credential deliberately never goes, and the
 egress allowlist is not built around completing a sign-in flow there. The same
 applies to the account state your harness keeps alongside the credential, read
-fresh from the host at every launch (see "Throwaway ~/.claude.json" in
-[docs/security.md](docs/security.md)).
+fresh from the host at every launch (Claude Code's is "Throwaway
+~/.claude.json" in [docs/security.md](docs/security.md)).
 
 So: run your harness once on the host, sign in, confirm it answers, and then
 point dejima at a project. When a credential expires, refresh it the same way,
@@ -283,19 +318,33 @@ There is no credential to hold or expire; what that setup needs instead is for
 the endpoint to be reachable from inside the container, which is an allowlist
 question rather than a sign-in one.
 
-## Provider axes: forge, workflow, harness
+## Provider axes: forge, workflow, harness, model backend
 
-The forge integration, the push/PR workflow, and the agent harness aren't
-hardcoded into dejima: each is a directory under `forges/`, `workflows/` or
-`harnesses/`, selected independently by `[core] forge`, `[core] workflow` and
-`[core] harness`.
+The forge integration, the push/PR workflow, the agent harness and the model
+API aren't hardcoded into dejima: each is a directory under `forges/`,
+`workflows/`, `harnesses/` or `backends/`, selected independently by
+`[core] forge`, `[core] workflow`, `[core] harness` and
+`[harness.<name>] backend`.
 
 - **Forges:** `none`, `gitea`, `github`
 - **Workflows:** `local-only`, `branch-push`, `worktree-pr`
 - **Harnesses:** `claude-code`, `cline`
+- **Model backends:** `anthropic`, `anthropic-api-key`, `openrouter`, `self-hosted`
+
+Which of those last two pair up is the backend's API dialect against the
+harness's, checked at launch rather than maintained as a list:
+
+| Backend | `claude-code` | `cline` | Credential |
+| --- | --- | --- | --- |
+| `anthropic` | yes | yes | OAuth, held on the host |
+| `anthropic-api-key` | yes | yes | a static key, held on the host |
+| `openrouter` | no | yes | a static key, held on the host |
+| `self-hosted` | no | yes | none, and so no proxy at all |
 
 **→ [docs/providers.md](docs/providers.md)** - the manifest contract, key by
-key, and the shipped providers as worked examples.
+key, what each pairing needs configured, and the shipped providers as worked
+examples. The model API is called a *backend* throughout, to keep it apart
+from the axes themselves.
 
 ## Using this responsibly
 
@@ -351,9 +400,11 @@ equivalent for it.
 
 The allowlist covers what the sandbox needs to function - DNS, the Docker host,
 GitHub on port 443 for read access whichever forge is selected, whatever the
-selected forge needs, the harness's own update and model endpoints, and
-`api.anthropic.com` when the credential proxy is off - plus whatever a project
-has declared and had approved.
+selected forge needs, the harness's own update endpoints, and the selected
+backend's API endpoint when the credential proxy is off - plus whatever a
+project has declared and had approved. With the proxy on that last name is
+deliberately absent: the session reaches the API through the in-container
+terminator rather than by resolving it.
 
 DNS is allowlisted as well as IPs: a local resolver only forwards lookups for
 names already on that same allowlist, so an unapproved domain does not resolve
@@ -402,25 +453,35 @@ exact command to hand you.
 tarball dependencies, the symlink refusal that protects the approval store,
 and the complete `dejima-allow`/`dejima-dep`/`dejima-project` reference.
 
-## Config parity with your host Claude Code setup
+## Config parity with your host harness setup
 
-Global `CLAUDE.md`, settings, hooks, skills, plugins and git identity all carry
-over, and your existing login stays effective, with the credential itself never
-entering the container. `~/.claude` is not shared as a whole - only an
-enumerated subset does, so a session transcript is readable from the host
-afterward but a credential or cache isn't. The container's own user matches
-yours exactly, so `$HOME`-relative paths resolve the same on both sides.
+Your harness's own global instructions, settings, hooks, skills, rules and
+plugins carry over, along with your git identity, and your existing login stays
+effective with the credential itself never entering the container. The
+harness's config directory is not shared as a whole - only an enumerated subset
+is, so a session transcript is readable from the host afterward but a
+credential or cache isn't. The container's own user matches yours exactly, so
+`$HOME`-relative paths resolve the same on both sides.
+
+Which files those are is each harness's own question, answered in its plugin:
+`~/.claude` for Claude Code, `~/.agents` and `~/.cline` for Cline.
 
 **→ [docs/configuration.md](docs/configuration.md)** - exactly what carries
-over and what doesn't, and why single-file mounts couldn't be trusted here.
+over and what doesn't, per harness, and why single-file mounts couldn't be
+trusted here.
 
 ## Shared scratch space
 
-`~/shared` is a read-write bind mount of `[core] share_dir`, separate from the
-project mount, for passing files in and out of a session without touching the
-checkout. It persists across sessions since it's a real directory, not a
-container volume. **Clear it out between sessions:** anything left there is
-readable by the next session, and by every session after that.
+`~/shared` is a read-write bind mount of this project's directory under
+`[core] share_dir`, separate from the project mount, for passing files in and
+out of a session without touching the checkout. One directory per project, so a
+session sees its own project's handoff files and no other project's.
+`dejima-share path` prints the host directory to drop a file into before a
+launch; `dejima-share list` shows what every project is holding.
+
+It persists across sessions since it's a real directory, not a container
+volume. **Clear it out between sessions:** anything left there is readable by
+the next session against that project, and by every session after that.
 
 `~/shared`, the project mount, and anything in `[mounts] read_write` are the
 only writable host paths in the container. Everything else a session writes
@@ -484,9 +545,9 @@ what a forwarded personal agent changes, and the persistent alternative.
 
 Before each run, dejima snapshots the host surfaces a session could write to
 and persist through: `.git/config` keys that run a command on the next `git`,
-`.git/hooks/`, the workspace's `.claude/`, `.mcp.json`, `.envrc`, and writes
-under `~/.claude/projects`. After the container exits it diffs them and tells
-you what changed.
+`.git/hooks/`, the workspace's `.claude/` and `.vscode/`, `.mcp.json`, `.envrc`,
+and any host-side file the selected harness declares as one it runs by itself.
+After the container exits it diffs them and tells you what changed.
 
 It is **advisory, not a block**, firing after the session has ended, so a
 finding is something to clean up before your next `git` command or session in
@@ -625,7 +686,7 @@ and how to run them.
 | [research-review.md](docs/research-review.md) | Checking the threat model against the field's, and the standing questions that are the agenda |
 | [configuration.md](docs/configuration.md) | Per-project declaration, dependencies, config parity |
 | [tools.md](docs/tools.md) | The optional tools a session can be given, and what hardening each one carries |
-| [providers.md](docs/providers.md) | Forge, workflow and harness axes, and writing your own |
+| [providers.md](docs/providers.md) | Forge, workflow, harness and model-backend axes, and writing your own |
 | [ci.md](docs/ci.md) | What push access grants on your CI host, and how to bound it |
 | [remote-access.md](docs/remote-access.md) | Picking and verifying a bind address, and the SSH and web front doors |
 | [development.md](docs/development.md) | The file map, the test suites, running them |

backends/anthropic-api-key/backend.conf

@@ -0,0 +1,41 @@
+# Anthropic on API billing: a key rather than a subscription login. This is
+# what most organisations put their people on.
+#
+# One backend for both places the key can live, because they are one
+# arrangement. Claude Code's own console login creates a key and stores it as
+# primaryApiKey in ~/.claude.json - the defaults below - and a key you hold in
+# a file of your own is the same static credential read from somewhere else:
+#
+#     [backend.anthropic-api-key]
+#     credential_file  = /path/to/your/key
+#     credential_field =
+#
+# An empty credential_field means the whole file is the key.
+#
+# For a subscription login, see anthropic. That one is a genuinely different
+# arrangement rather than a different location - a Bearer token that expires
+# and is refreshed, against the same endpoint.
+
+upstream        = https://api.anthropic.com
+proxied_domain  = api.anthropic.com
+api_style       = anthropic
+
+credential      = static
+
+# Anthropic's own header, and the key goes in bare - no scheme prefix. This is
+# the pair the subscription backend does NOT use, which is the whole
+# difference between the two: an OAuth token is a Bearer, an API key is
+# x-api-key.
+auth_header     = x-api-key
+auth_format     = {token}
+
+# The other slot, stripped so a placeholder cannot travel beside the injected
+# key. Two answers to the same question and which one the API prefers is not
+# dejima's to guess - and here the wrong answer is the placeholder.
+strip_headers   = authorization
+
+# Defaulted to where Claude Code puts it, so the common case needs no
+# configuration. dejima strips this field from the copy of ~/.claude.json it
+# stages, so the container gets the surrounding config and none of the key.
+keys            = credential_file:path=~/.claude.json credential_field:?jsonfield=primaryApiKey
+requires        = credential_file

backends/anthropic/backend.conf

@@ -0,0 +1,45 @@
+# Anthropic, on a subscription login: the OAuth credential Claude Code writes
+# on the host.
+#
+# The refreshing kind. The token expires, so the proxy renews it against the
+# endpoint below and writes the rotated one back to the host file - which is
+# what keeps a host-side login working rather than being signed out by a
+# sandbox run. For a console key on API billing, see anthropic-api-key.
+
+upstream        = https://api.anthropic.com
+
+# What the in-container TLS terminator answers for, and what /etc/hosts pins to
+# loopback. On the backend rather than the harness, because it is a property
+# of the endpoint: the same harness reaches a different one when a different
+# backend is selected, and the terminator has to follow the endpoint.
+proxied_domain  = api.anthropic.com
+
+# The Messages API, which is not OpenAI-compatible. A harness pointed here has
+# to speak it; one that cannot is refused at launch rather than sending
+# well-formed requests in the wrong shape.
+api_style       = anthropic
+
+credential      = anthropic-oauth
+oauth_endpoint  = https://platform.claude.com/v1/oauth/token
+oauth_client_id = 9d1c250a-e61b-44d9-88ed-5944d1962f5e
+
+auth_header     = Authorization
+auth_format     = Bearer {token}
+
+# x-api-key must not travel beside the injected Authorization: two answers to
+# the same question, and which one the API prefers is not dejima's to guess.
+# The container only ever holds a placeholder, so what this prevents is a
+# placeholder being the one that gets read.
+strip_headers   = x-api-key
+
+# The API rejects an OAuth token without it. Merged into whatever the client
+# already sent rather than replacing it, and left completely alone when the
+# value is already there - see the proxy's comment on why re-joining a list
+# that needs no change is itself a fingerprint.
+ensure_headers  = anthropic-beta=oauth-2025-04-20
+
+# Claude Code's own credential file, which is where the OAuth blob lives. A
+# path, never a secret: the file is read host-side per request and is not
+# mounted into the container.
+keys            = credential_file:path=~/.claude/.credentials.json
+requires        = credential_file

backends/openrouter/backend.conf

@@ -0,0 +1,34 @@
+# OpenRouter, an OpenAI-compatible gateway in front of many models.
+#
+# A hosted endpoint behind a static API key. The key stays on the host and is
+# read per request, exactly as the Anthropic OAuth token is.
+
+upstream        = https://openrouter.ai/api/v1
+
+# The name the in-container terminator answers for, and what /etc/hosts pins to
+# loopback. The host alone: the path above is where requests are FORWARDED, and
+# a hostname is what a certificate and a DNS pin are about.
+proxied_domain  = openrouter.ai
+
+api_style       = openai
+
+# A key, not a login. Nothing to refresh and nothing to write back, so a 401
+# here means the key is wrong rather than stale - which is why the proxy does
+# not retry it.
+credential      = static
+
+auth_header     = Authorization
+auth_format     = Bearer {token}
+
+# Both spellings an OpenAI-compatible client might reach for, so a placeholder
+# cannot travel beside the injected Authorization. The container only ever
+# holds a placeholder; what this prevents is the placeholder being the one the
+# endpoint reads.
+strip_headers   = x-api-key api-key
+
+# No default, and no assumed value: a key file's location is the operator's,
+# and guessing at one would be dejima pointing at a file it has no reason to
+# think exists. `requires` makes an unset one a refusal at launch rather than
+# an authentication failure several layers down.
+keys            = credential_file:?path
+requires        = credential_file

backends/self-hosted/backend.conf

@@ -0,0 +1,27 @@
+# A model the operator serves: on the host, or somewhere on the sandbox's own
+# network.
+#
+# The third arrangement, and the only one with no credential anywhere in it.
+# Nothing to withhold means no proxy, no terminator and nothing to steal, which
+# makes this the strongest posture dejima offers - see docs/security.md.
+#
+# WHERE it is belongs to the operator rather than to this file, which is why
+# base_url is a config key and not a manifest constant. A local endpoint is
+# also the one an operator is most likely to keep configured while using
+# something else: it lives in [backend.self-hosted] and stays there when the
+# selected backend changes.
+
+credential      = none
+
+# No upstream and no proxied_domain: both describe an endpoint dejima stands in
+# front of, and it stands in front of nothing here.
+
+# OpenAI-compatible, which is what a self-served model almost always speaks -
+# llama.cpp, vLLM, Ollama and LM Studio all expose that shape.
+api_style       = openai
+
+# No default. Refusing an unset one at launch beats a session starting against
+# an endpoint dejima picked, and there is no address worth guessing: whatever
+# is at 127.0.0.1:8080 on somebody else's machine is not this operator's model.
+keys            = base_url:?url
+requires        = base_url

bin/dejima-audit

@@ -970,7 +970,11 @@ tcb_snapshot() {
         # missed when that layer landed: a tool.conf names a tarball URL and
         # the sha256 checked against it, and the host's image build installs
         # what it points at as root.
-        for dir in bin hooks docker test forges workflows harnesses tools; do
+        #
+        # backends/ likewise: a backend.conf names the upstream every request
+        # is forwarded to and the host path the credential is read from, so an
+        # edit here redirects where a real credential is sent.
+        for dir in bin hooks docker test forges workflows harnesses tools backends; do
             if [ -d "$ws/$dir" ]; then
                 while IFS= read -r -d '' f; do
                     stage_entry "tcb:${f#"$ws"/}" "$f"

bin/dejima-config-lib.sh

@@ -165,6 +165,30 @@ _config_keys() {
     _config_extra_keys
 }
 
+# A key that used to exist and now lives somewhere else.
+#
+# "unknown key" is true and useless on its own: an operator who wrote a key
+# dejima once accepted has no way to tell a typo from a move, and the answer
+# is in a document they have no reason to think they need. A rename that
+# ships without this costs every operator who had the old key the same search.
+#
+# Keep this to keys that dejima ITSELF moved. A key nobody ever accepted is a
+# typo, and guessing at what it was meant to be is worse than saying nothing.
+_config_moved_hint() {  # <section> <key>
+    local section="$1" key="$2"
+    case "$section.$key" in
+        harness.*.base_url|harness.*base_url)
+            printf '  Where the model is belongs to the backend now, not the harness.\n' >&2
+            printf '  For one you serve yourself:\n\n' >&2
+            printf '      [harness.%s]\n      backend = self-hosted\n\n' \
+                "${section#harness.}" >&2
+            printf '      [backend.self-hosted]\n      base_url = ...\n\n' >&2
+            printf '  A hosted API is a backend of its own instead, which carries its own\n' >&2
+            printf '  address - see docs/providers.md, "Model backends".\n' >&2
+            ;;
+    esac
+}
+
 config_root() {
     printf '%s' "${DEJIMA_CONFIG_DIR:-$HOME/.config/dejima}"
 }
@@ -371,6 +395,29 @@ _config_valid_value() {
         identifier)
             [[ "$value" =~ ^[A-Za-z0-9._-]+$ ]]
             ;;
+        modelid)
+            # A model's name at whatever endpoint serves it, which is not an
+            # identifier: every hosted catalogue namespaces by vendor with a
+            # slash (`z-ai/glm-5.3`) and several qualify a variant with a colon
+            # (`deepseek/deepseek-r1:free`, `llama3:8b`). Typed `identifier`,
+            # not one OpenRouter id could be configured at all, so the backend
+            # this harness exists to reach was unusable.
+            #
+            # Still narrow, and for the same reason `path` is: this reaches an
+            # agent's configuration file. It is written there with jq --arg, so
+            # the JSON escaping is not what this is protecting - what it
+            # protects is that a value carrying a newline or a tab would split
+            # a record every reader of this config expects to be one line.
+            [[ "$value" =~ ^[A-Za-z0-9][A-Za-z0-9._:/-]*$ ]]
+            ;;
+        jsonfield)
+            # Which value inside a credentials file is the key: dot-separated
+            # object names, nothing else. No array indices and no jq syntax,
+            # because the credential proxy walks these segments itself and a
+            # value that could name an expression would be one that could name
+            # a computation.
+            [[ "$value" =~ ^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$ ]]
+            ;;
         text)
             # A sentence rather than a token - a person's name, an email
             # address, a one-line description. An identifier has no room for a
@@ -524,10 +571,23 @@ _config_parse() {
         _config_trim_into value "${line#*=}"
         if ! _config_type_into type "$section.$key"; then
             echo "unknown key in $conf: [$section] $key" >&2
+            _config_moved_hint "$section" "$key"
             return 1
         fi
         if ! _config_valid_value "$type" "$value"; then
-            echo "invalid value for [$section] $key in $conf: $value" >&2
+            # The value is echoed so the operator can see what was wrong with
+            # it, except for the userinfo of a URL. A url-typed value is the
+            # one kind here that carries a credential - ntfy takes its
+            # authentication as https://<user>:<token>@<host>/<topic> - and a
+            # value only reaches this line by being malformed, so the mistake
+            # would be what wrote the token into a terminal or a journal.
+            # Everything after the @ is kept: the host and path are what make
+            # the message useful.
+            local shown="$value"
+            case "$type:$value" in
+                *url:*://*@*) shown="${value%%://*}://<redacted>@${value#*@}" ;;
+            esac
+            echo "invalid value for [$section] $key in $conf: $shown" >&2
             return 1
         fi
         # Last assignment wins, which is why this overwrites rather than

bin/dejima-credential-proxy

@@ -1,12 +1,24 @@
 #!/usr/bin/env python3
-# Host-side credential-injecting proxy for sandboxed Claude Code sessions.
+# Host-side credential-injecting proxy for sandboxed sessions.
+#
 # The container only ever holds a placeholder token; this proxy (launched on
-# the host by bin/dejima, reached via a bind-mounted unix socket and
-# an in-container loopback forwarder) strips the placeholder and injects the
-# real OAuth access token from ~/.claude/.credentials.json, so the credential
-# itself never enters the container. It also owns token refresh: rotated
-# tokens are written back to the real host file atomically, keeping
-# host-side sessions logged in. See docs/security.md.
+# the host by bin/dejima, reached via a bind-mounted unix socket and an
+# in-container loopback forwarder) strips the placeholder and injects the real
+# credential, so the credential itself never enters the container. See
+# docs/security.md.
+#
+# NOTHING HERE NAMES A BACKEND. Which upstream, which credential, how it is
+# read, which header carries it and what shape that header takes are all
+# arguments (#171). The Anthropic arrangement this started as is one set of
+# those arguments and no longer a special case in the code, because the moment
+# a second backend exists, a proxy that knows one backend's name has to grow
+# a branch for every other.
+#
+# Two credential kinds, and the difference is refresh. A static key is read and
+# sent. An OAuth credential expires, so it is refreshed against an endpoint and
+# the rotated token written back to the host file atomically - which is what
+# keeps a host-side session logged in rather than being signed out by a sandbox
+# run. A backend says which kind it has; this decides nothing on its own.
 import argparse
 import http.client
 import json
@@ -19,8 +31,6 @@ import time
 from http.server import BaseHTTPRequestHandler
 from urllib.parse import urlsplit
 
-OAUTH_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
-OAUTH_BETA = "oauth-2025-04-20"
 # Hop-by-hop headers describe the connection to this proxy rather than the
 # request, so they stop here (RFC 9110 7.6.1). Host is deliberately not in
 # this set: it has to be rewritten for the upstream, and is replaced in place
@@ -30,28 +40,106 @@ HOP_BY_HOP = {
     "connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
     "te", "trailer", "trailers", "transfer-encoding", "upgrade",
 }
-# Casing for the few headers this proxy has to supply when the client sent
-# none of its own. Everything the client did send keeps the client's casing.
+# Casing for the headers this proxy has to supply when the client sent none of
+# its own. Everything the client did send keeps the client's casing; these are
+# only consulted for a header being added rather than replaced. The auth and
+# ensure-header names are added to this at startup, in the spelling the
+# backend declared, for the same reason.
 SUPPLIED_NAMES = {
     "host": "Host",
-    "authorization": "Authorization",
-    "anthropic-beta": "anthropic-beta",
     "content-length": "Content-Length",
 }
 
 
-class Credentials:
-    def __init__(self, path, oauth_endpoint, margin):
+class StaticCredential:
+    """A key in a file, sent as-is. No expiry, so nothing to refresh."""
+
+    # Trailing newline stripped, because a key file is written by an editor or
+    # a `>` redirection as often as by a tool, and a newline inside a header
+    # value is not a cosmetic difference: it would either be rejected or split
+    # the header block. Refused rather than trimmed if anything is left that
+    # cannot appear in a header, since a key that needs sanitising is a key
+    # that was pasted wrong, and guessing at it would send a mangled
+    # credential upstream and report the backend's rejection as the fault.
+    # A field, when the key is one value inside a document rather than the
+    # whole file. Claude Code signed in with a console API token keeps its key
+    # as primaryApiKey in ~/.claude.json, beside unrelated app state, so a
+    # backend has to be able to say which value is the credential.
+    def __init__(self, path, field=None):
+        self.path = path
+        self.field = field
+
+    def token(self):
+        with open(self.path) as f:
+            raw = f.read()
+        if self.field is None:
+            value = raw.strip()
+        else:
+            try:
+                doc = json.loads(raw)
+            except ValueError as e:
+                raise RuntimeError("%s is not JSON: %s" % (self.path, e))
+            cur = doc
+            for seg in self.field.split("."):
+                if not isinstance(cur, dict) or seg not in cur:
+                    raise RuntimeError(
+                        "%s has no %s" % (self.path, self.field))
+                cur = cur[seg]
+            if not isinstance(cur, str):
+                raise RuntimeError(
+                    "%s: %s is not a string" % (self.path, self.field))
+            value = cur.strip()
+        if not value:
+            raise RuntimeError("%s is empty" % self.path)
+        bad = [c for c in value if ord(c) < 0x20 or ord(c) == 0x7F]
+        if bad:
+            raise RuntimeError("%s contains a control character" % self.path)
+        return value
+
+    def refresh(self, stale_token):
+        # Nothing to refresh. A 401 from a static key means the key is wrong,
+        # and retrying with the same bytes would turn one rejection into two.
+        raise RuntimeError("this credential cannot be refreshed")
+
+    @property
+    def refreshable(self):
+        return False
+
+    def startup_check(self):
+        self.token()
+
+
+class OAuthCredential:
+    def __init__(self, path, oauth_endpoint, client_id, margin):
         self.path = path
         self.oauth_endpoint = oauth_endpoint
+        self.client_id = client_id
         self.margin = margin
         self.lock = threading.Lock()
 
+    @property
+    def refreshable(self):
+        return True
+
+    def startup_check(self):
+        # A plain read, not token(): this is a startup sanity check and must
+        # not trigger a refresh (that belongs to the first real request, so an
+        # external refresher gets a chance to win first).
+        self._read()["claudeAiOauth"]["accessToken"]
+        expires = self._read()["claudeAiOauth"].get("refreshTokenExpiresAt")
+        if expires is not None and expires / 1000 < time.time():
+            # Concrete, not generic. This class reads Claude Code's own
+            # credential shape, so the remedy is a command the operator can
+            # run rather than an instruction to work out.
+            raise RuntimeError(
+                "the refresh token has expired - run `claude` on the host "
+                "and log in again first")
+
     def _read(self):
         with open(self.path) as f:
             return json.load(f)
 
-    def access_token(self):
+    def token(self):
         oauth = self._read()["claudeAiOauth"]
         if oauth["expiresAt"] / 1000 - time.time() < self.margin:
             self.refresh(stale_token=oauth["accessToken"])
@@ -75,7 +163,7 @@ class Credentials:
             req = json.dumps({
                 "grant_type": "refresh_token",
                 "refresh_token": oauth["refreshToken"],
-                "client_id": OAUTH_CLIENT_ID,
+                "client_id": self.client_id,
             })
             conn.request("POST", u.path, body=req,
                          headers={"Content-Type": "application/json"})
@@ -121,6 +209,24 @@ class Credentials:
             raise
 
 
+class AuthShape:
+    """How a backend wants its credential presented.
+
+    header/format are the injection; strip is what must not travel beside it;
+    ensure is a comma-list header that has to contain a value, used for the
+    Anthropic OAuth beta and general enough to need no name of its own here.
+    """
+
+    def __init__(self, header, fmt, strip, ensure):
+        self.header = header
+        self.format = fmt
+        # The auth header is never also stripped: it is replaced, and listing
+        # it in both places would drop the injected value instead of sending
+        # it.
+        self.strip = frozenset(n.lower() for n in strip) - {header.lower()}
+        self.ensure = ensure
+
+
 class BodyTooLarge(Exception):
     """A request body over the cap. Its own type, not ValueError: _read_body
     raises ValueError for a genuinely malformed request (a chunk length that
@@ -135,7 +241,7 @@ class Handler(BaseHTTPRequestHandler):
         pass  # per-request lines would interleave with the session's own UI
 
     def log_error(self, fmt, *args):
-        sys.stderr.write("dejima-anthropic-proxy: " + fmt % args + "\n")
+        sys.stderr.write("dejima-credential-proxy: " + fmt % args + "\n")
 
     # Capped, because the client is the sandboxed session and this runs on the
     # host as the operator's user. Every other session-controlled size in this
@@ -207,25 +313,34 @@ class Handler(BaseHTTPRequestHandler):
         # which is re-emitted in the client's own position instead.
         conn.putrequest(self.command, self.path,
                         skip_host=True, skip_accept_encoding=True)
+        auth = self.server.auth
         supplied = {
             "host": u.netloc,
-            "authorization": "Bearer " + token,
+            auth.header.lower(): auth.format.replace("{token}", token),
             "content-length": str(len(body)),
         }
-        # anthropic-beta is left completely alone when the OAuth value is
-        # already among the client's own - which it is in the tls transport,
-        # where Claude Code believes it holds an OAuth credential. Re-joining
-        # a list that needs no change would normalize the client's spacing,
-        # which is the same class of tell as the casing.
-        betas = [b.strip() for v in self.headers.get_all("anthropic-beta", [])
-                 for b in v.split(",")]
-        if OAUTH_BETA not in betas:
-            first = self.headers.get("anthropic-beta")
-            supplied["anthropic-beta"] = first + "," + OAUTH_BETA if first else OAUTH_BETA
+        # An ensure-header is left completely alone when its value is already
+        # among the client's own - as anthropic-beta's is in the tls transport,
+        # where the harness believes it holds an OAuth credential. Re-joining a
+        # list that needs no change would normalize the client's spacing, which
+        # is the same class of tell as the casing.
+        for name, wanted in auth.ensure:
+            low = name.lower()
+            present = [v.strip() for header in self.headers.get_all(low, [])
+                       for v in header.split(",")]
+            if wanted in present:
+                continue
+            first = self.headers.get(low)
+            supplied[low] = first + "," + wanted if first else wanted
         seen = set()
         for name, value in self.headers.items():
             low = name.lower()
-            if low in HOP_BY_HOP or low == "x-api-key":
+            # The strip set is the backend's, not a fixed list. It exists so a
+            # header the client used for a credential cannot travel alongside
+            # the one this proxy injects: x-api-key beside an Authorization is
+            # two answers to the same question, and which one an API prefers is
+            # not this program's to guess.
+            if low in HOP_BY_HOP or low in auth.strip:
                 continue
             if low in supplied:
                 # One replacement even for a repeated header, or the injected
@@ -236,6 +351,13 @@ class Handler(BaseHTTPRequestHandler):
                 value = supplied[low]
             seen.add(low)
             conn.putheader(name, value)
+        # Only names registered above are emitted, so a value put in `supplied`
+        # whose name is not in SUPPLIED_NAMES is computed and then silently
+        # dropped. That is deliberate - it is what keeps this pass from
+        # inventing a header the backend never declared - but it means the two
+        # have to be populated from the same place, which is why main() derives
+        # SUPPLIED_NAMES from the auth header and the ensure list rather than
+        # listing them.
         for low, name in SUPPLIED_NAMES.items():
             if low in supplied and low not in seen:
                 # Content-Length only when there is a body: a bodyless GET
@@ -257,19 +379,22 @@ class Handler(BaseHTTPRequestHandler):
             return self._fail(413, "credential proxy: request body too large",
                               log_message="refused a request body: %s" % e)
         try:
-            token = self.server.creds.access_token()
+            token = self.server.creds.token()
         except Exception as e:
             return self._fail(502, "credential proxy: could not load or refresh the "
                                     "credential - see host terminal",
                                log_message="cannot load credentials: %s" % e)
         try:
             conn, resp = self._upstream(token, body)
-            if resp.status == 401:
+            if resp.status == 401 and self.server.creds.refreshable:
                 # Upstream disagrees with expiresAt - refresh once and retry.
+                # Only for a credential that can be refreshed: retrying a
+                # static key sends the same bytes and turns one rejection into
+                # two, with the second one looking like a flapping upstream.
                 resp.read()
                 conn.close()
                 self.server.creds.refresh(stale_token=token)
-                token = self.server.creds.access_token()
+                token = self.server.creds.token()
                 conn, resp = self._upstream(token, body)
         except Exception as e:
             return self._fail(502, "credential proxy: upstream request failed - "
@@ -315,9 +440,10 @@ class Handler(BaseHTTPRequestHandler):
 class ProxyServer(socketserver.ThreadingMixIn, socketserver.UnixStreamServer):
     daemon_threads = True
 
-    def __init__(self, socket_path, upstream, creds):
+    def __init__(self, socket_path, upstream, creds, auth):
         self.upstream = upstream
         self.creds = creds
+        self.auth = auth
         super().__init__(socket_path, Handler)
 
     def get_request(self):
@@ -345,34 +471,79 @@ def main():
     p = argparse.ArgumentParser()
     p.add_argument("--socket", required=True)
     p.add_argument("--credentials", required=True)
-    p.add_argument("--upstream", default="https://api.anthropic.com")
-    p.add_argument("--oauth-endpoint", default="https://platform.claude.com/v1/oauth/token")
+    # No default for any of these, deliberately. A default upstream or a
+    # default credential kind would be one backend's arrangement wearing the
+    # name of every backend's, which is the shape #171 was filed about: the
+    # caller says which backend this is, and this program has no opinion.
+    p.add_argument("--upstream", required=True)
+    p.add_argument("--credential-kind", required=True,
+                   choices=("static", "anthropic-oauth"))
+    # Which value in the credentials file is the key, for the static kind.
+    # Absent means the whole file is the key.
+    p.add_argument("--credential-field", default=None)
+    p.add_argument("--auth-header", default="Authorization")
+    # "{token}" rather than a scheme name, so a backend that wants something
+    # other than "Bearer x" - a bare key, a prefix of its own - needs no code
+    # here.
+    p.add_argument("--auth-format", default="Bearer {token}")
+    # Repeatable, and replacing rather than adding to a default: a backend
+    # states what must not travel beside its credential, and inheriting
+    # another backend's list would be a guess.
+    p.add_argument("--strip-header", action="append", default=[],
+                   metavar="NAME")
+    p.add_argument("--ensure-header", action="append", default=[],
+                   metavar="NAME=VALUE")
+    p.add_argument("--oauth-endpoint")
+    p.add_argument("--oauth-client-id")
     p.add_argument("--refresh-margin", type=int, default=300)
     args = p.parse_args()
 
-    creds = Credentials(args.credentials, args.oauth_endpoint, args.refresh_margin)
+    if "{token}" not in args.auth_format:
+        sys.stderr.write("dejima-credential-proxy: --auth-format must contain "
+                         "{token}, or the credential is never sent\n")
+        return 2
+    ensure = []
+    for item in args.ensure_header:
+        if "=" not in item:
+            sys.stderr.write("dejima-credential-proxy: --ensure-header wants "
+                             "NAME=VALUE, got %r\n" % item)
+            return 2
+        name, _, value = item.partition("=")
+        if not name or not value:
+            sys.stderr.write("dejima-credential-proxy: --ensure-header wants "
+                             "NAME=VALUE, got %r\n" % item)
+            return 2
+        ensure.append((name, value))
+
+    if args.credential_kind == "anthropic-oauth":
+        if not args.oauth_endpoint or not args.oauth_client_id:
+            sys.stderr.write("dejima-credential-proxy: anthropic-oauth needs "
+                             "--oauth-endpoint and --oauth-client-id\n")
+            return 2
+        creds = OAuthCredential(args.credentials, args.oauth_endpoint,
+                                args.oauth_client_id, args.refresh_margin)
+    else:
+        creds = StaticCredential(args.credentials, args.credential_field)
+
     try:
-        # A plain read, not access_token(): this is just a startup sanity
-        # check and must not trigger a refresh (that belongs to the first
-        # real request, so an external refresher gets a chance to win first).
-        creds._read()["claudeAiOauth"]["accessToken"]
+        creds.startup_check()
     except Exception as e:
         sys.stderr.write(
-            "dejima-anthropic-proxy: unusable credentials file %s: %s\n"
+            "dejima-credential-proxy: unusable credential %s: %s\n"
             % (args.credentials, e))
         return 1
 
-    expires = creds._read()["claudeAiOauth"].get("refreshTokenExpiresAt")
-    if expires is not None and expires / 1000 < time.time():
-        sys.stderr.write(
-            "dejima-anthropic-proxy: the refresh token in %s has "
-            "expired - run `claude` on the host and log in again first\n"
-            % args.credentials)
-        return 1
+    auth = AuthShape(args.auth_header, args.auth_format,
+                     args.strip_header, ensure)
+    # In the spelling the backend declared, for headers this has to add
+    # rather than replace. A client that sent its own keeps its own casing.
+    SUPPLIED_NAMES[auth.header.lower()] = auth.header
+    for name, _ in ensure:
+        SUPPLIED_NAMES.setdefault(name.lower(), name)
 
     if os.path.exists(args.socket):
         os.unlink(args.socket)
-    server = ProxyServer(args.socket, urlsplit(args.upstream), creds)
+    server = ProxyServer(args.socket, urlsplit(args.upstream), creds, auth)
     try:
         server.serve_forever()
     except KeyboardInterrupt:

bin/dejima-credential-scan

@@ -0,0 +1,367 @@
+#!/usr/bin/env python3
+# Finds credential-shaped values in the host files dejima copies into a
+# container, and prints what it found WITHOUT printing any value.
+#
+# This exists because the alternative does not scale. Two leaks were found by
+# hand in one week - a console API key in ~/.claude.json, credential helpers
+# in ~/.gitconfig - and both fixes were denylists: they encode exactly the
+# knowledge dejima did not have the week before. A harness's authentication is
+# not a stable interface, so the next field added leaks silently unless
+# something is looking (#291).
+#
+# NOTHING HERE DECIDES ANYTHING. It classifies and reports; bin/dejima asks
+# the operator and applies the answer. Keeping the judgement out of here is
+# what lets the same classifier run in a test without a terminal.
+#
+# THE ONE INVARIANT: a credential value never leaves this program. Not in a
+# finding, not in an error, not in a traceback. What a caller gets is a
+# redacted path and a shape name - enough to report a bug to whoever ships the
+# harness, and useless to anyone who intercepts it.
+#
+# Which is why the caller never sees a real path either. In a gitconfig the
+# userinfo sits in the SECTION HEADER, so `url.https://me:PAT@github.com/` is
+# a path that IS a credential. Findings carry a redacted path for a human and
+# an opaque id for matching, and --scrub takes ids back - so real paths stay
+# inside this program, which is the only place that has to hold them.
+
+import argparse
+import hashlib
+import json
+import math
+import re
+import sys
+
+# Anything that looks like credentials in a URL, wherever it appears.
+USERINFO = re.compile(r"(?P<scheme>[a-z][a-z0-9+.-]*://)(?P<user>[^/@\s:]*):"
+                      r"[^/@\s]+@")
+
+
+def redact(text):
+    """A path an operator can recognise, with any embedded secret removed."""
+    return USERINFO.sub(lambda m: "%s%s:***@" % (m.group("scheme"),
+                                                 m.group("user")), text)
+
+
+def finding_id(label, path):
+    """Stable across runs, and reveals nothing about what it identifies.
+
+    Keyed on the real path, so a decision survives the credential itself
+    rotating - the operator answered about a field, not about a value."""
+    h = hashlib.sha256(("%s\t%s" % (label, path)).encode("utf-8"))
+    return h.hexdigest()[:16]
+
+# Vendor prefixes, which are worth naming separately from the heuristics: a
+# match here is not a guess, and the shape name tells an operator exactly what
+# they are looking at without showing it to them.
+KNOWN_SHAPES = (
+    ("anthropic-api-key", re.compile(r"sk-ant-")),
+    ("openrouter-key", re.compile(r"sk-or-")),
+    ("openai-key", re.compile(r"^sk-[A-Za-z0-9]{20,}$")),
+    ("github-token", re.compile(r"(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{8,}|github_pat_")),
+    ("slack-token", re.compile(r"xox[baprs]-")),
+    ("aws-access-key-id", re.compile(r"^AKIA[0-9A-Z]{16}$")),
+    ("google-api-key", re.compile(r"^AIza[0-9A-Za-z_-]{35}$")),
+    ("jwt", re.compile(r"^eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.")),
+    ("private-key-pem", re.compile(r"^-----BEGIN [A-Z ]*PRIVATE KEY-----")),
+    ("auth-header-value", re.compile(r"(?i)(^|:\s*)(basic|bearer)\s+\S{8,}")),
+    ("url-userinfo", re.compile(r"^[a-z][a-z0-9+.-]*://[^/@\s]+:[^/@\s]+@")),
+)
+
+# Names that say "this is a secret", matched as WHOLE WORDS rather than as
+# substrings. Substring matching put `auth` inside `oauthAccount` and flagged
+# every field of the signed-in account's description, and `tengu_mcp_local_
+# oauth_blocked_hosts` along with them.
+SUSPECT_WORDS = frozenset((
+    "key", "apikey", "token", "secret", "secrets", "credential", "credentials",
+    "password", "passwd", "auth", "authorization", "bearer", "cookie",
+    "signature", "privatekey",
+))
+
+# Secrets are drawn from a restricted alphabet and contain no whitespace:
+# base64, hex, base58, or a vendor's own. Prose is not, which is the whole
+# discriminator - English text scores 4.0-4.5 bits per character by this
+# measure, so entropy ALONE flags every sentence in a config file.
+SECRETISH = re.compile(r"^[A-Za-z0-9+/=_.~-]+$")
+
+
+def words(name):
+    """Splits an identifier into lowercase words: camelCase, snake_case and
+    kebab-case all reduce to the same thing."""
+    name = re.sub(r"\[\d+\]$", "", name)
+    parts = re.split(r"[^A-Za-z0-9]+", name)
+    out = []
+    for part in parts:
+        out.extend(w.lower() for w in
+                   re.findall(r"[A-Z]+(?![a-z])|[A-Z][a-z0-9]*|[a-z0-9]+", part))
+    return out
+
+
+def suspect_name(path):
+    """The leaf, plus its immediate parent.
+
+    The parent matters for a gitconfig, where `credential.helper` is a
+    credential because of the section it sits in. Anything further up is too
+    broad: a whole subtree named after a feature flag about oauth is not a
+    subtree of credentials."""
+    segments = path.split(".")
+    for seg in segments[-2:]:
+        if SUSPECT_WORDS & set(words(seg)):
+            return True
+    return False
+
+# Shapes that look like secrets to an entropy test and are not. Checked before
+# entropy, so a UUID machine id does not cost an operator a prompt.
+NOT_SECRET = (
+    re.compile(r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-"
+               r"[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"),          # uuid
+    re.compile(r"^[a-z]+://"),                                # url
+    re.compile(r"^/"),                                        # absolute path
+    re.compile(r"^~?/"),                                      # home path
+    re.compile(r"^\d{4}-\d{2}-\d{2}"),                        # timestamp
+    re.compile(r"^[0-9.]+$"),                                 # version/number
+)
+
+MIN_ENTROPY_LEN = 32
+MIN_ENTROPY_BITS = 4.0
+
+
+def shannon(value):
+    if not value:
+        return 0.0
+    counts = {}
+    for ch in value:
+        counts[ch] = counts.get(ch, 0) + 1
+    n = float(len(value))
+    return -sum((c / n) * math.log(c / n, 2) for c in counts.values())
+
+
+def classify(path, value):
+    """Returns (verdict, shape) with verdict in credential|suspect|None.
+
+    Never returns any part of `value`.
+    """
+    if not isinstance(value, str) or not value.strip():
+        return (None, None)
+    v = value.strip()
+    for shape, pattern in KNOWN_SHAPES:
+        if pattern.search(v):
+            return ("credential", shape)
+    if any(p.match(v) for p in NOT_SECRET):
+        return (None, None)
+    # Both remaining rules require a value that could BE a secret: one token,
+    # restricted alphabet, no whitespace. Without that, a field called
+    # "authDescription" holding a sentence is a finding.
+    if not SECRETISH.match(v):
+        return (None, None)
+    if suspect_name(path) and len(v) >= 8:
+        return ("suspect", "named-field")
+    if len(v) >= MIN_ENTROPY_LEN and shannon(v) >= MIN_ENTROPY_BITS:
+        return ("suspect", "high-entropy")
+    return (None, None)
+
+
+def walk_json(doc, prefix=""):
+    if isinstance(doc, dict):
+        for k, v in doc.items():
+            yield from walk_json(v, "%s.%s" % (prefix, k) if prefix else str(k))
+    elif isinstance(doc, list):
+        # Indexed, so a decision recorded against one element does not silently
+        # cover a different one later.
+        for i, v in enumerate(doc):
+            yield from walk_json(v, "%s[%d]" % (prefix, i))
+    else:
+        yield (prefix, doc)
+
+
+def ini_logical_lines(text):
+    """Yields (raw_lines, logical_text) with backslash continuations joined.
+
+    A gitconfig value may run across lines, and both reading and removing have
+    to treat the whole run as one thing. Reading it line by line finds a
+    credential under a key that does not exist - `password=...` on a
+    continuation of `helper = !echo \\` parses as its own key - and removing
+    one line of it leaves the rest behind."""
+    lines = text.splitlines(True)
+    i = 0
+    while i < len(lines):
+        raws = [lines[i]]
+        logical = lines[i].rstrip("\n")
+        while logical.rstrip().endswith("\\") and i + 1 < len(lines):
+            i += 1
+            raws.append(lines[i])
+            logical = logical.rstrip()[:-1] + lines[i].rstrip("\n")
+        yield (raws, logical.strip())
+        i += 1
+
+
+def ini_entries(text):
+    """Yields (raw_lines, kind, key, value) where kind is section|pair|other."""
+    section = ""
+    for raws, line in ini_logical_lines(text):
+        if not line or line.startswith("#") or line.startswith(";"):
+            yield (raws, "other", None, None)
+            continue
+        if line.startswith("[") and line.endswith("]"):
+            inner = line[1:-1].strip()
+            m = re.match(r'^(\S+)\s+"(.*)"$', inner)
+            if m:
+                section = "%s.%s" % (m.group(1), m.group(2))
+                # The subsection text is part of the key, and a URL with
+                # userinfo in it is a credential sitting in a section header.
+                yield (raws, "section", section, m.group(2))
+            else:
+                section = inner
+                yield (raws, "section", section, None)
+            continue
+        if "=" not in line:
+            yield (raws, "other", None, None)
+            continue
+        k, _, v = line.partition("=")
+        key = "%s.%s" % (section, k.strip()) if section else k.strip()
+        yield (raws, "pair", key, v.strip())
+
+
+def walk_ini(text):
+    for _raws, kind, key, value in ini_entries(text):
+        if kind in ("section", "pair") and value is not None:
+            yield (key, value)
+
+
+def delete_json_path(doc, path):
+    # Mirrors walk_json's construction exactly, including list indices.
+    parts = re.findall(r"[^.\[\]]+|\[\d+\]", path)
+    cur = doc
+    for part in parts[:-1]:
+        cur = cur[int(part[1:-1])] if part.startswith("[") else cur[part]
+    last = parts[-1]
+    if last.startswith("["):
+        del cur[int(last[1:-1])]
+    else:
+        del cur[last]
+
+
+def drop_ini_paths(text, paths):
+    """Removes whole sections for a section-header finding, whole logical
+    lines otherwise. Line-based rather than via a parser, so a file this
+    cannot fully model is changed only where it matched - but a match takes
+    every line of the value with it."""
+    drop = set(paths)
+    out = []
+    in_dropped_section = False
+    for raws, kind, key, _value in ini_entries(text):
+        if kind == "section":
+            # A finding on the header itself takes the section with it: the
+            # secret is the header, and the keys under it belong to it.
+            in_dropped_section = key in drop
+            if in_dropped_section:
+                continue
+            out.extend(raws)
+            continue
+        if in_dropped_section:
+            continue
+        if kind == "pair" and key in drop:
+            continue
+        out.extend(raws)
+    return "".join(out)
+
+
+def load_list(path):
+    if not path:
+        return []
+    out = []
+    try:
+        with open(path) as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith("#"):
+                    out.append(line)
+    except OSError:
+        pass
+    return out
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--file", required=True)
+    p.add_argument("--format", required=True, choices=("json", "ini"))
+    # What this file is called where an operator would recognise it, rather
+    # than the temp path of the copy being scanned.
+    p.add_argument("--label", required=True)
+    # Paths judged safe, and paths already decided. Both are plain lists of
+    # "<label>\t<path>" so bin/dejima can build them without a parser.
+    p.add_argument("--known-safe", default=None)
+    p.add_argument("--decided", default=None)
+    # Ids to remove from the file, in place. The caller never had the real
+    # paths, so this is the only way it can ask for one to go.
+    p.add_argument("--scrub", default=None)
+    args = p.parse_args()
+
+    try:
+        with open(args.file) as f:
+            text = f.read()
+    except OSError as e:
+        # The filename, never the contents.
+        print("cannot read %s: %s" % (args.label, e.strerror), file=sys.stderr)
+        return 2
+
+    if args.format == "json":
+        try:
+            pairs = list(walk_json(json.loads(text)))
+        except ValueError:
+            print("%s is not readable as JSON" % args.label, file=sys.stderr)
+            return 2
+    else:
+        pairs = list(walk_ini(text))
+
+    if args.scrub:
+        wanted = set(load_list(args.scrub))
+        drop = [path for path, value in pairs
+                if finding_id(args.label, path) in wanted]
+        if not drop:
+            return 0
+        if args.format == "json":
+            doc = json.loads(text)
+            for path in drop:
+                delete_json_path(doc, path)
+            out = json.dumps(doc, indent=2) + "\n"
+        else:
+            out = drop_ini_paths(text, drop)
+        with open(args.file, "w") as f:
+            f.write(out)
+        return 0
+
+    # Two different keys, deliberately.
+    #
+    # A judged-safe entry is a "<label>\t<path>" written by hand, and it
+    # covers the subtree beneath it - `customApiKeyResponses.approved` has to
+    # answer for `...approved[0]` and every sibling, or an array of the same
+    # judged-safe thing asks once per element.
+    #
+    # A decision is an opaque id and matches ONE path exactly. Broadening
+    # those the same way would let one answer about one field quietly cover
+    # fields the operator never saw.
+    safe = [e for e in load_list(args.known_safe) if "\t" in e]
+    decided = set(load_list(args.decided))
+
+    def judged_safe(entry):
+        for s_entry in safe:
+            if entry == s_entry or entry.startswith(s_entry + ".") \
+                    or entry.startswith(s_entry + "["):
+                return True
+        return False
+
+    for path, value in pairs:
+        fid = finding_id(args.label, path)
+        if fid in decided or judged_safe("%s\t%s" % (args.label, path)):
+            continue
+        verdict, shape = classify(path, value)
+        if verdict:
+            # verdict, id, label, redacted path, shape. No value, and no
+            # length either - a length is a hint about a secret.
+            print("%s\t%s\t%s\t%s\t%s"
+                  % (verdict, fid, args.label, redact(path), shape))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bin/dejima-credential-scan-known-safe

@@ -0,0 +1,37 @@
+# Findings judged safe, so the scanner does not ask about them.
+#
+# Every line is "<label>\t<path>", and every line needs a reason. This file is
+# the allowlist half of #291: the scanner refuses to be quiet by default, and
+# adding a line here is the deliberate act that makes it quiet about one
+# thing. A line with no reason is a line nobody reviewed.
+#
+# Judge on what the value IS, not on whether leaking it would matter. "It is
+# only an email address" is a decision about consequence; this file is for
+# decisions about identity.
+#
+# An entry covers the subtree beneath it, so `a.b` answers for `a.b[0]` and
+# `a.b.c`. That is what makes an array of the same judged-safe thing one line
+# rather than one per element - and it is why a broad entry is a broad grant.
+# Name the narrowest path that covers what you meant.
+
+# Hashes of API keys the operator approved on the host, not the keys. Claude
+# Code stores the last 20 characters, so it is a fragment rather than a
+# credential - and dropping it re-prompts inside the sandbox for a decision
+# already made outside it.
+~/.claude.json	customApiKeyResponses.approved
+~/.claude.json	customApiKeyResponses.rejected
+
+# Installation identifiers. Not credentials: they authenticate nothing, and
+# they are why a session's own telemetry and cache lookups match the host's.
+~/.claude.json	userID
+~/.claude.json	machineID
+
+# The signed-in account's own description - address, organisation, roles.
+# Identifying, and deliberately kept: a session's UI reflects the real account,
+# which is what makes it recognisable as yours. It grants nothing on its own.
+~/.claude.json	oauthAccount.emailAddress
+~/.claude.json	oauthAccount.accountUuid
+~/.claude.json	oauthAccount.organizationUuid
+~/.claude.json	oauthAccount.organizationName
+~/.claude.json	oauthAccount.organizationRole
+~/.claude.json	oauthAccount.workspaceRole

bin/dejima-harness-lib.sh

@@ -128,6 +128,30 @@ harness_plugin_load() {
     fi
     # shellcheck disable=SC1090
     source "$plugin"
+
+    # Resolve this harness's key schema now, in the caller's own shell.
+    #
+    # A plugin reads its settings through harness_config_get, and its callers
+    # reach it from inside subshells - a process substitution, a pipeline. A
+    # subshell inherits this shell's variables, so warming the cache here means
+    # those never re-derive it; without this they each start cold, because a
+    # cache filled in a subshell dies with it.
+    #
+    # That is a correctness fix and not only a speed one (#284).
+    # dejima-conversation-ship re-resolves its transcript paths from a SIGTERM
+    # handler, and bash reports 128+n for commands completing while it is
+    # delivering a signal - measured, _config_valid_value returned 0 and its
+    # caller read 143. So a perfectly valid manifest was rejected inside the
+    # trap, "unknown config key" was printed, and the tail of the session's
+    # transcript went unshipped. Resolved before any signal is possible, the
+    # handler answers from cache and has nothing left to fail at.
+    #
+    # Failure is ignored on purpose: an unreadable manifest is the caller's to
+    # report when it asks for a value, in its own words, not this function's to
+    # turn into a plugin-load error.
+    if declare -F _provider_keys_field >/dev/null 2>&1; then
+        _provider_keys_field harness "$name" >/dev/null 2>&1 || true
+    fi
 }
 
 # Calls one hook of the loaded plugin, if it defines it. Absence is normal:
@@ -368,9 +392,26 @@ harness_config_dirs_load() {
 DEJIMA_STAGED_CONFIG=()
 
 # host path, and the path under $HOME it is installed at.
+# `ensure` asks for a placeholder at that path in the container when the host
+# has none, so a harness that needs a file to exist gets one without dejima
+# creating it on the operator's machine.
+#
+# Two kinds, because empty is not always a valid file. `ensure` writes nothing;
+# `ensure-json` writes `{}`, and settings.json needs that one - an empty file
+# is not valid JSON, and Claude Code discards a settings.json it cannot parse
+# wholesale, taking every permission, hook and plugin the operator configured
+# with it.
+#
+# Opt-in per file rather than implied: an empty statusline.sh would be
+# installed executable and run as the status line, so that one stays absent.
 emit_staged_config() {
-    local src="$1" rel="$2"
+    local src="$1" rel="$2" ensure="${3:-}"
     [ -n "$src" ] && [ -n "$rel" ] || return 0
+    case "$ensure" in
+        ''|ensure|ensure-json) ;;
+        *) echo "Harness plugin emitted an invalid staged-config flag: $ensure" >&2
+           exit 1 ;;
+    esac
     # The relative path becomes a location under $HOME inside the container.
     # Anything that could climb out of it, or that is not relative at all, is
     # a plugin bug rather than something to normalise quietly.
@@ -379,7 +420,7 @@ emit_staged_config() {
             echo "Harness plugin emitted an invalid staged-config path: $rel" >&2
             exit 1 ;;
     esac
-    DEJIMA_STAGED_CONFIG+=("$src"$'\t'"$rel")
+    DEJIMA_STAGED_CONFIG+=("$src"$'\t'"$rel"$'\t'"$ensure")
 }
 
 harness_staged_config_load() {

bin/dejima-notify-watch

@@ -83,11 +83,36 @@ fi
 # Refusing rather than sanitizing, because the config is operator-written:
 # a value that can't be used as intended means they got something wrong, and
 # this is the one place they say where their phone notifications go.
+#
+# The value is not echoed back whole. An ntfy server that wants credentials
+# takes them in the URL - https://<user>:<token>@<host>/<topic>, which
+# docs/remote-access.md documents - and a misconfiguration should not be the
+# thing that writes that token into the journal, where it stays.
+redacted_url() {
+    case "$1" in
+        *://*@*) printf '%s://<redacted>@%s' "${1%%://*}" "${1#*@}" ;;
+        *) printf '%s' "$1" ;;
+    esac
+}
+
 require_url() {
     case "$2" in
         http://*|https://*) ;;
         *)
-            echo "$1 in $(config_path) must be an http:// or https:// URL: $2" >&2
+            echo "$1 in $(config_path) must be an http:// or https:// URL: $(redacted_url "$2")" >&2
+            exit 1
+            ;;
+    esac
+    # The URL is handed to curl through a config file on stdin rather than as
+    # an argument (see the push below), and that format is line-oriented with
+    # its own quoting: a newline in the value would start a second directive,
+    # and a quote or a backslash would end or escape the string. The `url`
+    # config type's own character set already excludes all three, so this
+    # refuses a value that arrived some other way rather than sanitizing one
+    # that did - the same reading as the scheme check above.
+    case "$2" in
+        *[!A-Za-z0-9:/._~?=%@+-]*)
+            echo "$1 in $(config_path) has a character dejima will not send: $(redacted_url "$2")" >&2
             exit 1
             ;;
     esac
@@ -168,12 +193,31 @@ push() {
     # stdout is discarded (ntfy answers with a JSON receipt); stderr is not.
     # -sS exists precisely to keep transport errors on stderr, and under a
     # systemd user unit that is the journal, which is where they belong.
+    #
+    # The URL goes in on stdin, not in argv. It is the one value here that can
+    # carry a credential, and every argument of every process on this host is
+    # readable by any local account through /proc/<pid>/cmdline - so a token in
+    # argv is a token published to the machine for as long as the request runs,
+    # and `ps` is enough to read it. Nothing else on this line is secret: the
+    # title, the body and the click URL are all composed from host data.
+    #
+    # This also retires the `-K/path` hazard the scheme check above was half
+    # of: a URL that is not a URL can no longer be read as an option, because
+    # it is no longer in the option list at all. Both checks stay anyway, and
+    # the second one is now what keeps this format from gaining a directive.
+    # Redirected from a process substitution rather than piped into. `printf |
+    # curl` is a pipeline under `set -o pipefail`, so a curl that exits before
+    # draining stdin leaves printf holding a closed pipe and the pipeline
+    # reports 141 - a "push failed" line for a push that succeeded. A
+    # redirection is not a pipeline and has no such status to inherit. It also
+    # keeps `--config -` in argv rather than a /dev/fd path, which is a fixed
+    # string a test can compare.
     curl -fsS --max-time 10 --retry 2 \
         -H "Title: $title" \
         -H "Priority: default" \
         "${click[@]}" \
         -d "$body" \
-        -- "$NTFY_URL" >/dev/null \
+        --config - >/dev/null < <(printf 'url = "%s"\n' "$NTFY_URL") \
         || echo "dejima-notify-watch: push failed for $run_id/$event" >&2
 }
 

bin/dejima-provider-lib.sh

@@ -28,36 +28,65 @@ MAX_MANIFEST_LINES=200
 # filling this on first use meant filling it again in every `$(...)` that
 # reached it, which was a fork apiece and hundreds of them per launch.
 _PROVIDER_ROOT_CACHE="$(cd "${BASH_SOURCE[0]%/*}/.." && pwd)"
-provider_root() {
+# Assigns rather than prints, so a caller reaching it in a loop does not pay a
+# `$( )` fork per call. provider_root below is the printing form for everyone
+# who wants a value in a substitution anyway.
+_provider_root_into() {
     if [ -n "${DEJIMA_PROVIDER_ROOT:-}" ]; then
-        printf '%s' "$DEJIMA_PROVIDER_ROOT"
+        printf -v "$1" '%s' "$DEJIMA_PROVIDER_ROOT"
         return 0
     fi
     # Only the repo path is cached. The test hook is re-read every call, so a
     # test that repoints it mid-process still gets the directory it just set.
     [ -n "$_PROVIDER_ROOT_CACHE" ] || _PROVIDER_ROOT_CACHE="$(cd "${BASH_SOURCE[0]%/*}/.." && pwd)"
-    printf '%s' "$_PROVIDER_ROOT_CACHE"
+    printf -v "$1" '%s' "$_PROVIDER_ROOT_CACHE"
 }
 
-_provider_axis_dir() {
-    case "$1" in
-        forge)    printf 'forges' ;;
-        workflow) printf 'workflows' ;;
-        harness)  printf 'harnesses' ;;
+provider_root() {
+    local _root
+    _provider_root_into _root
+    printf '%s' "$_root"
+}
+
+# Same assign-instead-of-print split as _provider_root_into, for the same
+# reason: provider_dir is reached once per manifest read.
+_provider_axis_dir_into() {
+    case "$2" in
+        forge)    printf -v "$1" 'forges' ;;
+        workflow) printf -v "$1" 'workflows' ;;
+        harness)  printf -v "$1" 'harnesses' ;;
+        # The model API a session talks to, and how its credential is
+        # presented. Selected per harness rather than in [core], because what
+        # it configures is the credential proxy rather than the shape of the
+        # work (#171).
+        #
+        # "backend" and not "provider", which is what the industry calls a
+        # model API: this repo already calls the axes themselves providers, and
+        # one word for both reads as one thing. A harness's own config keeps
+        # its own vocabulary - cline writes providers.json with a
+        # lastUsedProvider key, and bin/harness/cline.sh translates.
+        backend) printf -v "$1" 'backends' ;;
         # Not an axis in the select-one sense the other three are: a launch
         # enables zero or more tools, and none is the default. It is here
         # because everything else about it is the same - a manifest that is
         # data, validated by the same schema machinery, never sourced.
-        tool)     printf 'tools' ;;
-        *) echo "unknown provider axis: $1" >&2; return 1 ;;
+        tool)     printf -v "$1" 'tools' ;;
+        *) echo "unknown provider axis: $2" >&2; return 1 ;;
     esac
 }
 
+_provider_axis_dir() {
+    local _sub
+    _provider_axis_dir_into _sub "$1" || return 1
+    printf '%s' "$_sub"
+}
+
 _provider_manifest_name() {
     case "$1" in
         forge)    printf 'forge.conf' ;;
         workflow) printf 'workflow.conf' ;;
         harness)  printf 'harness.conf' ;;
+        backend) printf 'backend.conf' ;;
         tool)     printf 'tool.conf' ;;
         *) return 1 ;;
     esac
@@ -72,6 +101,18 @@ valid_provider_name() {
     [[ "$1" =~ ^[a-z0-9][a-z0-9-]*$ ]]
 }
 
+# `readlink -m` answers memoized per path, because the containment check below
+# resolves the same axis directory once per provider and provider_dir is
+# reached from inside each `$( manifest_get ... )`. What is cached is one
+# path's resolution, not a verdict: every caller still runs the containment
+# comparison and the -d check itself.
+declare -gA _PROVIDER_REAL_CACHE=()
+_provider_resolve_into() {
+    [ -n "${_PROVIDER_REAL_CACHE[$2]+set}" ] \
+        || _PROVIDER_REAL_CACHE["$2"]="$(readlink -m "$2")"
+    printf -v "$1" '%s' "${_PROVIDER_REAL_CACHE[$2]}"
+}
+
 # Resolved once per root+axis+name. The two readlinks are the containment
 # check, and it is called on every manifest read; keying the cache on the
 # resolved root rather than just the name is what keeps a test that repoints
@@ -79,19 +120,19 @@ valid_provider_name() {
 declare -gA _PROVIDER_DIR_CACHE=()
 provider_dir() {
     local axis="$1" name="$2" sub root axis_root dir_real id
-    sub="$(_provider_axis_dir "$axis")" || return 1
+    _provider_axis_dir_into sub "$axis" || return 1
     if ! valid_provider_name "$name"; then
         echo "invalid $axis name: $name" >&2
         return 1
     fi
-    root="$(provider_root)"
+    _provider_root_into root
     id="$root:$axis:$name"
     if [ -n "${_PROVIDER_DIR_CACHE[$id]+set}" ]; then
         printf '%s' "${_PROVIDER_DIR_CACHE[$id]}"
         return 0
     fi
-    axis_root="$(readlink -m "$root/$sub")"
-    dir_real="$(readlink -m "$root/$sub/$name")"
+    _provider_resolve_into axis_root "$root/$sub"
+    _provider_resolve_into dir_real "$root/$sub/$name"
     case "$dir_real/" in
         "$axis_root"/*) ;;
         *)  echo "refusing $axis '$name': it resolves outside $axis_root" >&2
@@ -122,17 +163,28 @@ _config_extra_type_valid() {
     esac
 }
 
-provider_list() {
-    local axis="$1" sub entry name
-    sub="$(_provider_axis_dir "$axis")" || return 1
-    for entry in "$(provider_root)/$sub"/*/; do
+# Fills _PROVIDER_LIST_OUT rather than printing, so the warm-up at the bottom
+# of this file can walk all three axes without a `$( )` fork apiece.
+declare -ga _PROVIDER_LIST_OUT=()
+_provider_list_into() {
+    local axis="$1" sub root entry name
+    _PROVIDER_LIST_OUT=()
+    _provider_axis_dir_into sub "$axis" || return 1
+    _provider_root_into root
+    for entry in "$root/$sub"/*/; do
         [ -d "$entry" ] || continue
-        name="$(basename "$entry")"
+        name="${entry%/}"
+        name="${name##*/}"
         valid_provider_name "$name" || continue
-        printf '%s\n' "$name"
+        _PROVIDER_LIST_OUT+=("$name")
     done
 }
 
+provider_list() {
+    _provider_list_into "$1" || return 1
+    [ "${#_PROVIDER_LIST_OUT[@]}" -eq 0 ] || printf '%s\n' "${_PROVIDER_LIST_OUT[@]}"
+}
+
 # Manifest schema. Same three-column shape as the config table: key, type,
 # default. Types are the config file's own, so one validator set covers both.
 _manifest_table() {
@@ -151,6 +203,7 @@ issue_command	?command
 merge_block	?command
 repo_flags	?list:flag
 repo_env	?identifier
+repo_paths	?list:repopath
 identity_keys	?list:identifier
 disclose	?disclosures
 keys	?list:keyspec
@@ -189,6 +242,54 @@ autonomy	enum:commit|push-branch|open-pr	commit
 briefing	?relpath
 EOF
             ;;
+        # credential = none is an endpoint that needs no credential - a model
+        # the operator serves. There is nothing to withhold, so no proxy runs
+        # and neither upstream nor proxied_domain applies: the session reaches
+        # it directly, and where it is comes from the operator's own
+        # [backend.<name>] base_url rather than from the manifest. Both are
+        # optional for that reason and bin/dejima requires them where they do
+        # apply.
+        #
+        # api_style is which dialect the endpoint speaks, and it is a property
+        # of the API rather than of any harness: Anthropic's Messages API and
+        # an OpenAI-compatible one are different wire formats, so a harness
+        # that can only speak one has to know which it is being pointed at
+        # before it writes its own configuration.
+        #
+        # A model API and how its credential is presented. Every field here
+        # is an argument bin/dejima-credential-proxy already takes (#171):
+        # this axis is what turns "the caller states the arrangement" into
+        # "a file states it", so adding a backend is adding a directory.
+        #
+        # Nothing here is a secret. A backend declares WHERE its credential
+        # is read from, never what it is - the file it names is read
+        # host-side per request and never mounted.
+        #
+        # WHERE a credential sits is the operator's, so credential_field is
+        # a `keys` entry rather than a manifest key. A key is not always the
+        # whole file - Claude Code's console login keeps its key as
+        # primaryApiKey in ~/.claude.json, beside unrelated app state - and
+        # the same static arrangement serves a bare key file with the field
+        # cleared. Two placements of one credential, not two backends.
+        backend) cat <<'EOF'
+upstream	?url
+proxied_domain	?hostname
+api_style	enum:anthropic|openai
+credential	enum:static|anthropic-oauth|none
+auth_header	identifier	Authorization
+auth_format	authformat	Bearer {token}
+strip_headers	?list:identifier
+ensure_headers	?list:headerpair
+oauth_endpoint	?url
+oauth_client_id	?identifier
+keys	?list:keyspec
+requires	?list:identifier
+EOF
+            ;;
+        # api_styles is which of those dialects this harness can speak. A
+        # launch pairing it with a backend it has no client for is refused at
+        # launch rather than failing later with well-formed requests in the
+        # wrong shape.
         harness) cat <<'EOF'
 install	?depspec
 image_dirs	?list:homepath
@@ -197,8 +298,8 @@ image_env	?list:envpair
 command	identifier	claude
 command_path	?path
 api_domains	?list:hostname
-proxied_api_domain	?hostname
 guards	?list:identifier
+api_styles	?list:identifier
 briefing_args	?args
 briefing_path	?homepath
 no_confirm_args	?args
@@ -207,6 +308,7 @@ keys	?list:keyspec
 resume_command	?template
 transcript_update	enum:append|rewrite	append
 briefing	?relpath
+assumed_backend	?provider:backend
 EOF
             ;;
         *) return 1 ;;
@@ -303,6 +405,42 @@ _provider_valid_value() {
             # subcommand or a value.
             [[ "$value" =~ ^--?[A-Za-z0-9][A-Za-z0-9-]*$ ]]
             ;;
+        repopath)
+            # A repository named in a path rather than in a flag:
+            # `<subcommand>:<first path segment>`, as in `api:repos` for
+            # `gh api repos/<owner>/<name>/...`.
+            #
+            # Scoped to a subcommand because the alternative is comparing every
+            # positional argument that happens to contain two slashes, and a
+            # false refusal on an issue title is worse than the miss - this is
+            # a fast-fail, so a wrong yes costs an honest agent a working
+            # command. The guard applies it only when the subcommand is argv's
+            # first word.
+            case "$value" in *:*) ;; *) return 1 ;; esac
+            local sub="${value%%:*}" seg="${value#*:}"
+            [[ "$sub" =~ ^[A-Za-z0-9][A-Za-z0-9_-]*$ ]] || return 1
+            [[ "$seg" =~ ^[A-Za-z0-9][A-Za-z0-9_-]*$ ]]
+            ;;
+        authformat)
+            # How the credential is written into its header. "{token}" rather
+            # than a scheme name, so a provider wanting a bare key or a prefix
+            # of its own needs no code - and required, because a format
+            # without it produces a proxy that starts, answers, and sends
+            # every request unauthenticated. The proxy checks this too; a
+            # manifest that cannot be loaded is the better place to find out.
+            case "$value" in *"{token}"*) ;; *) return 1 ;; esac
+            _provider_valid_value text "$value"
+            ;;
+        headerpair)
+            # NAME=VALUE for ensure_headers, where NAME is a header rather
+            # than an environment variable - lower case and dashes are the
+            # norm (anthropic-beta), which is exactly what envpair refuses.
+            case "$value" in *=*) ;; *) return 1 ;; esac
+            local hname="${value%%=*}" hvalue="${value#*=}"
+            [ -n "$hname" ] && [ -n "$hvalue" ] || return 1
+            _provider_valid_value identifier "$hname" || return 1
+            _provider_valid_value identifier "$hvalue"
+            ;;
         relpath)
             # Joined to a provider directory, so no absolute paths and no
             # traversal - a manifest may only name a file it ships.
@@ -496,12 +634,45 @@ manifest_validate() {
 #
 # Failures are ignored: a missing or unreadable directory is not this loop's
 # to report, and provider_dir refuses it again when something asks.
-for _axis in forge workflow harness; do
-    for _name in $(provider_list "$_axis" 2>/dev/null); do
-        provider_dir "$_axis" "$_name" >/dev/null 2>&1 || true
+#
+# One `readlink -m` for every path rather than two per provider. It takes
+# several operands and prints one resolved path per line, so the warm-up costs
+# a single process instead of one per directory - which is most of what
+# sourcing this file costs, and is paid by every `bin/dejima` invocation and
+# every test that drives the library in a fresh shell. The batch only fills
+# the resolution cache; provider_dir still does its own containment check
+# against what it finds there.
+_provider_warm_dirs() {
+    local axis sub root name path i=0
+    local -a axes=() names=() paths=() lines=()
+    _provider_root_into root
+    for axis in forge workflow harness backend; do
+        _provider_axis_dir_into sub "$axis" || continue
+        paths+=("$root/$sub")
+        _provider_list_into "$axis" || continue
+        for name in "${_PROVIDER_LIST_OUT[@]}"; do
+            axes+=("$axis")
+            names+=("$name")
+            paths+=("$root/$sub/$name")
+        done
     done
-done
-unset _axis _name
+    mapfile -t lines < <(readlink -m -- "${paths[@]}" 2>/dev/null)
+    # A path containing a newline would desync the one-line-per-operand
+    # pairing. Nothing shipped can produce one - names are validated and the
+    # root comes from `pwd` - but a mismatched count means the pairing cannot
+    # be trusted, so the batch is dropped rather than cached wrong. provider_dir
+    # then resolves each path itself, exactly as it would have.
+    if [ "${#lines[@]}" -eq "${#paths[@]}" ]; then
+        for path in "${paths[@]}"; do
+            _PROVIDER_REAL_CACHE["$path"]="${lines[$i]}"
+            i=$((i + 1))
+        done
+    fi
+    for i in "${!names[@]}"; do
+        provider_dir "${axes[$i]}" "${names[$i]}" >/dev/null 2>&1 || true
+    done
+}
+_provider_warm_dirs
 
 _manifest_parse() {
     local axis="$1" name="$2" dir="$3" id="$4" file line key value type line_count
@@ -596,13 +767,44 @@ manifest_get() {
 # `wc -l`, both to avoid a subshell/external-process fork per manifest line:
 # this runs once per key in a [forge.<name>]/[harness.<name>] section, on
 # every config_validate pass that has not already been answered from cache.
+# Cached, and that is a correctness fix as well as a speed one (#284).
+#
+# Speed: this is reached once per key of a [forge.<name>]/[harness.<name>]
+# section on every config_validate pass, and each miss re-reads the manifest
+# and revalidates the whole keys list - a fork per element for the keyspec
+# parse.
+#
+# Correctness: dejima-conversation-ship re-resolves its transcript paths from
+# a SIGTERM handler, and bash clobbers $? with 128+n when it delivers a pending
+# signal at a command boundary. Measured: _config_valid_value returned 0 and
+# its caller read 143, so the `|| return 1` chain below failed for a manifest
+# that is perfectly valid, the shipper reported "unknown config key" and the
+# last lines of the session's transcript went unshipped. Anything that has
+# already been resolved once is answered from here instead, so the signal
+# handler does no work that a spurious status can fail.
+#
+# Keyed on the resolved directory rather than the name, like every other cache
+# here, so two roots cannot answer for each other.
+#
+# SUCCESSES ONLY. A remembered refusal was the first shape of this and it is
+# the wrong one: it turns one transient failure into a permanent one, and the
+# symptom is indistinguishable from the bug this exists to fix - a lookup that
+# worked at startup failing for the rest of the process. Nothing here is
+# expensive enough to be worth remembering a "no" for.
+declare -gA _PROVIDER_KEYS_CACHE=() _PROVIDER_KEYS_SEEN=()
+
 _provider_keys_field() {
-    local axis="$1" name="$2" dir file line key value="" seen=0 type n=0
+    local axis="$1" name="$2" dir file line key value="" seen=0 type n=0 id
     # An unselected axis contributes no keys - a different question from
     # whether a selection is valid. Without this, --print-config prints
     # "invalid harness name:" and fails at the thing it is for.
     [ -n "$name" ] || return 1
     dir="$(provider_dir "$axis" "$name")" || return 1
+    id="$axis:$dir"
+    if [ -n "${_PROVIDER_KEYS_SEEN[$id]+set}" ]; then
+        printf '%s' "${_PROVIDER_KEYS_CACHE[$id]}"
+        return 0
+    fi
     file="$dir/$(_provider_manifest_name "$axis")"
     [ -f "$file" ] || return 1
     type="$(_manifest_type "$axis" keys)" || return 1
@@ -620,10 +822,41 @@ _provider_keys_field() {
         seen=1
     done < "$file"
     [ "$seen" = 1 ] || value="$(_manifest_default "$axis" keys)"
+    # Core's own key on every backend section, appended rather than declared
+    # by each manifest. Whether to withhold a credential is dejima's question,
+    # not the backend author's, and a backend that forgot to declare it would
+    # silently lose the setting.
+    #
+    # No default, deliberately: unset means "whatever [credentials] proxy
+    # says", which is a third state that on/off cannot carry. See
+    # backend_proxy_enabled.
+    [ "$axis" != backend ] || value="${value:+$value }proxy:?bool"
     _provider_valid_value "$type" "$value" || return 1
+    _PROVIDER_KEYS_CACHE[$id]="$value"
+    _PROVIDER_KEYS_SEEN[$id]=ok
     printf '%s' "$value"
 }
 
+# Is the credential proxy on for this backend?
+#
+# [backend.<name>] proxy, falling back to [credentials] proxy. Per backend
+# because the global switch has the wrong blast radius: an operator with one
+# backend the proxy cannot serve had to disable withholding for every backend,
+# including the ones it serves perfectly.
+#
+# Deliberately not config_get_bool, which reports an UNSET optional key as
+# off. Unset here means "inherit", and reading it as "disabled" would turn the
+# credential proxy off for every backend the moment this key existed.
+backend_proxy_enabled() {  # <backend-name>
+    local v=""
+    [ -n "${1:-}" ] || return 1
+    if config_type "backend.$1.proxy" >/dev/null 2>&1; then
+        v="$(config_get "backend.$1" proxy)"
+    fi
+    [ -n "$v" ] || v="$(config_get credentials proxy)"
+    [ "$v" = on ]
+}
+
 # A section is known only when a provider directory for its name actually
 # exists - provider_dir carries the same name/containment checks
 # _config_extra_type_valid already relies on for the provider: config types.
@@ -632,6 +865,7 @@ _config_extra_section_known() {
     case "$section" in
         forge.*)   axis=forge;   name="${section#forge.}" ;;
         harness.*) axis=harness; name="${section#harness.}" ;;
+        backend.*) axis=backend; name="${section#backend.}" ;;
         # An identity is the operator's own name for a set of credentials, so
         # there is no directory to check it against - only that it is a name
         # at all. Unlike a provider, an unused one is not a misconfiguration:
@@ -687,6 +921,7 @@ _config_extra_spec() {
     case "$want" in
         forge.*)   axis=forge ;;
         harness.*) axis=harness ;;
+        backend.*) axis=backend ;;
         identity.*)
             rest="${want#identity.}"
             key="${rest#*.}"
@@ -872,7 +1107,7 @@ identity_validate() {
     # "once" that a session could not reach, and a deprecation nobody sees
     # until removal is not a deprecation.
     if config_is_set core ssh_key; then
-        printf '  %s[core] ssh_key is deprecated%s - it is [identity.default] ssh_key\n' \
+        printf '\n  %s[core] ssh_key is deprecated%s - it is [identity.default] ssh_key\n' \
             "${C_WARN:-}" "${C_RESET:-}" >&2
         printf '  under its old name.\n' >&2
         if [ -n "$name" ]; then
@@ -888,8 +1123,10 @@ identity_validate() {
         # force it answers with THAT identity's key - and printing it as the
         # thing to move would name a key the operator is not being asked to
         # touch.
-        printf '      [identity.default]\n      ssh_key = %s\n\n' \
+        printf '      [identity.default]\n      ssh_key = %s\n' \
             "$(_config_get_from_file core ssh_key)" >&2
+        # Worth a pause before the build scrolls it away - see bin/dejima.
+        DEJIMA_STARTUP_NOTICE=1
     fi
 
     [ -n "$name" ] || return 0
@@ -1274,10 +1511,12 @@ the user's machine, with
 
 What this means:
 - The workspace directory is bind-mounted read-write and is the real
-  project. ~/shared is also a real, persistent host directory (not part of
-  the project) - use it to hand the user a file (a screenshot, a temp
-  script) without touching the project checkout, or to pick up something
-  they left there for you. Your harness keeps its own state on the host too,
+  project. ~/shared is also a real, persistent host directory (this
+  project's own, and not part of its checkout) - use it to hand the user a
+  file (a screenshot, a temp script) without touching the project checkout,
+  or to pick up something they left there for you. It outlives this session
+  and every session against this project shares it, so treat what is in it
+  as readable by all of them. Your harness keeps its own state on the host too,
   so this session's transcript outlives the container - the work is
   recoverable on the host with the command at the end of this
   briefing.{{writable_mounts}} Everything else is disposable: installed system
@@ -1433,8 +1672,6 @@ If a task genuinely needs something else the sandbox can't provide -
 broader network access than a domain or two, host-level or system changes,
 GUI/hardware access - stop and explain clearly to the user what you need
 and why, instead of trying to work around the firewall or sandbox yourself.
-They can continue this exact session outside the container by running on
-the host:
 BRIEFING_EOF
 }
 
@@ -1788,9 +2025,11 @@ briefing_compose() {
     # The harness fragment closes the briefing: it supplies both the resume
     # command closing_a has just promised and the sentence about where the
     # session history it resumes from actually lives. Both are the harness's
-    # own facts - Claude Code resumes from a bind-mounted ~/.claude, Cline
-    # from a per-project state directory named in the command itself - and
-    # core stating either one meant stating Claude Code's.
+    # own facts, INCLUDING whether there is anything to say. Claude Code
+    # resumes from a bind-mounted ~/.claude and says so; Cline cannot be
+    # resumed outside dejima at all, and a core sentence promising it could
+    # was Claude Code's fact stated as everyone's - which left a Cline session
+    # able to send its operator somewhere that does not work.
     #
     # $requirements and $project_doc (the missing-dependency report and
     # .dejima.md) stay hook-computed and hook-appended after this - they read

bin/dejima-share

@@ -0,0 +1,186 @@
+#!/bin/bash
+# Where a project's ~/shared lives on the host, and what is in it.
+#
+# `[core] share_dir` holds one directory per project, and a launch mounts only
+# that project's at ~/shared. This is the host side of that: where to put a
+# file so the next session against a project finds it, what every project is
+# holding, and how to move files left over from when share_dir was mounted
+# whole.
+#
+# Nothing here is a security control. The boundary is the mount bin/dejima
+# sets up; this is the operator's view of what is on the other side of it.
+#
+# Usage: dejima-share <path|list|adopt> [<path>]
+set -euo pipefail
+
+case "${1:-}" in
+    -h|--help)
+        cat <<'DEJIMA_SHARE_HELP'
+dejima-share - the host side of a project's ~/shared
+
+Usage: dejima-share <path|list|adopt> [path]
+
+  path [path]    print the host directory a launch against `path` mounts at
+                 ~/shared, creating it if it does not exist yet - so a file
+                 copied there is waiting for the next session
+  list           every project's share directory, with its size and when it
+                 was last written, plus anything left loose in share_dir
+  adopt [path]   move whatever is loose in share_dir's top level into `path`'s
+                 share directory, after showing it and asking
+
+  path defaults to the current directory.
+
+A launch mounts <share_dir>/projects/<slug> at ~/shared, where slug is the
+project's absolute path with every non-alphanumeric character replaced by a
+dash - the same key the audit and epitaph stores use. Only that directory
+crosses into the container, so one project's session cannot read another's
+handoff files.
+
+Files that were in share_dir's top level before this split are still there and
+are no longer mounted anywhere. `adopt` is for moving them somewhere a session
+will see them; it never overwrites.
+
+Nothing here deletes anything by itself, and dejima never prunes share_dir. It
+grows until you clear it out - `list` is what tells you what has gone stale.
+
+See docs/configuration.md.
+DEJIMA_SHARE_HELP
+        exit 0 ;;
+esac
+
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+# The provider library rather than the config one directly: [core] harness and
+# the other provider-typed keys resolve against the manifests, so config
+# validation refuses an ordinary config without it.
+# shellcheck source=dejima-provider-lib.sh
+source "$SCRIPT_DIR/dejima-provider-lib.sh"
+# shellcheck source=dejima-slug-lib.sh
+source "$SCRIPT_DIR/dejima-slug-lib.sh"
+config_validate || exit 1
+
+action="${1:-}"
+[ -n "$action" ] || { echo "Usage: dejima-share <path|list|adopt> [<path>]" >&2; exit 1; }
+
+SHARE_ROOT="$(config_get core share_dir)"
+PROJECTS_ROOT="$(share_projects_root "$SHARE_ROOT")"
+
+# A workspace argument becomes a mount path, so it is resolved the way
+# bin/dejima resolves the one it is about to mount rather than used as typed.
+# A path that does not exist is a typo, and answering it with a share
+# directory nothing will ever mount is worse than refusing.
+resolve_workspace() {
+    local given="${1:-$PWD}"
+    [ -d "$given" ] || { echo "no such directory: $given" >&2; exit 1; }
+    (cd "$given" && pwd)
+}
+
+# Whatever is in share_dir's top level that is not the per-project root. Every
+# one of these was visible to every session before the split and is visible to
+# none now.
+loose_entries() {
+    find "$SHARE_ROOT" -mindepth 1 -maxdepth 1 ! -name projects -printf '%f\n' \
+        2>/dev/null | sort
+}
+
+case "$action" in
+    path)
+        ws="$(resolve_workspace "${2:-}")"
+        dir="$(share_dir_for "$SHARE_ROOT" "$ws")"
+        # Created here rather than only at launch, because the point of asking
+        # is usually to put something in it before the launch happens.
+        mkdir -p "$dir"
+        printf '%s\n' "$dir"
+        ;;
+
+    list)
+        if [ ! -d "$PROJECTS_ROOT" ]; then
+            echo "No project has a share directory yet ($PROJECTS_ROOT does not exist)."
+        else
+            found=0
+            while IFS= read -r d; do
+                [ -n "$d" ] || continue
+                found=1
+                # du and date rather than a stat of the directory itself: the
+                # directory's own mtime changes when an entry is added or
+                # removed and not when one is written, which would report a
+                # share nobody has touched in months as fresh.
+                size="$(du -sh "$PROJECTS_ROOT/$d" 2>/dev/null | cut -f1)"
+                newest="$(find "$PROJECTS_ROOT/$d" -type f -printf '%T@\n' 2>/dev/null \
+                    | sort -rn | head -1)"
+                if [ -n "$newest" ]; then
+                    when="$(date -d "@${newest%.*}" '+%Y-%m-%d' 2>/dev/null || echo '?')"
+                else
+                    when="empty"
+                fi
+                printf '%-10s %-12s %s\n' "${size:-?}" "$when" "$d"
+            done < <(find "$PROJECTS_ROOT" -mindepth 1 -maxdepth 1 -type d -printf '%f\n' \
+                2>/dev/null | sort)
+            [ "$found" = 1 ] || echo "No project has a share directory yet."
+        fi
+
+        loose="$(loose_entries)" || true
+        if [ -n "$loose" ]; then
+            echo
+            echo "Loose in $SHARE_ROOT, mounted into no session:"
+            while IFS= read -r e; do
+                [ -n "$e" ] || continue
+                printf '  %s\n' "$e"
+            done <<< "$loose"
+            echo
+            echo "Move them with 'dejima-share adopt <project path>', or delete them."
+        fi
+        echo
+        echo "Nothing prunes this. Clear out what you no longer need: everything"
+        echo "in a project's share is readable by every future session against it."
+        ;;
+
+    adopt)
+        ws="$(resolve_workspace "${2:-}")"
+        dest="$(share_dir_for "$SHARE_ROOT" "$ws")"
+        loose="$(loose_entries)" || true
+        if [ -z "$loose" ]; then
+            echo "Nothing loose in $SHARE_ROOT - every entry is already under projects/."
+            exit 0
+        fi
+        echo "Moving into $ws's share ($dest):"
+        while IFS= read -r e; do
+            [ -n "$e" ] || continue
+            if [ -e "$dest/$e" ]; then
+                printf '  %-30s SKIP - %s already has one\n' "$e" "$dest"
+            else
+                printf '  %s\n' "$e"
+            fi
+        done <<< "$loose"
+        echo
+        # One question, after showing everything, the way dejima-project
+        # approve asks - and read from stdin for the same reason it does, so a
+        # non-interactive caller answering no is the default rather than an
+        # error about /dev/tty. A move is not undoable by this tool, and the
+        # files are the operator's.
+        printf 'Move them? [y/N] '
+        read -r reply || reply=n
+        case "$reply" in
+            y|Y) ;;
+            *) echo "Nothing moved."; exit 0 ;;
+        esac
+        mkdir -p "$dest"
+        moved=0
+        while IFS= read -r e; do
+            [ -n "$e" ] || continue
+            # Never overwrites: a name that already exists in the destination
+            # is left where it is and reported, because the two files are both
+            # the operator's and this cannot know which one they meant.
+            if [ -e "$dest/$e" ]; then
+                echo "Skipped $e - $dest already has one" >&2
+                continue
+            fi
+            mv -n "$SHARE_ROOT/$e" "$dest/$e"
+            moved=$((moved + 1))
+        done <<< "$loose"
+        echo "Moved $moved entr$([ "$moved" = 1 ] && echo y || echo ies) into $dest"
+        ;;
+
+    *)
+        echo "Usage: dejima-share <path|list|adopt> [<path>]" >&2
+        exit 1 ;;
+esac

bin/dejima-slug-lib.sh

@@ -1,12 +1,15 @@
-# Shared library: the ~/.claude/projects slug scheme, and which slugs belong
-# to a given workspace. Sourced by bin/dejima (to decide what to mount) and
-# bin/dejima-epitaph (to decide whose transcripts to keep). Not on PATH and
-# not executable.
+# Shared library: the ~/.claude/projects slug scheme, which slugs belong to a
+# given workspace, and the share_dir layout keyed by that slug. Sourced by
+# bin/dejima (to decide what to mount), bin/dejima-epitaph (to decide whose
+# transcripts to keep) and bin/dejima-share. Not on PATH and not executable.
 #
 # One definition, because the callers must not disagree. A slug the mount
 # exposes but a caller treats as foreign is a session whose work is silently
 # left behind; a slug a caller treats as the workspace's own but the mount
-# does not expose is a hole that nothing reports.
+# does not expose is a hole that nothing reports. The share layout is here for
+# the same reason: bin/dejima mounts a directory and dejima-share tells an
+# operator where to put files in it, and those two naming different places
+# would be an operator dropping a file where nothing will ever read it.
 
 # Claude Code's own project key: the absolute cwd with every non-alphanumeric
 # replaced by a dash. Matches docker/log-shipper.sh's Loki key and
@@ -14,6 +17,17 @@
 # runs inside the container, the other is a separate library).
 ws_slug() { printf '%s' "$1" | sed 's/[^a-zA-Z0-9]/-/g'; }
 
+# Every per-project share directory lives under this one subdirectory of
+# `[core] share_dir` rather than directly in it, which is what makes "left
+# over from before the split" a decidable question: anything at share_dir's
+# top level other than this directory predates the layout, because nothing
+# writes there any more. It is also the directory to mount over sshfs - one
+# entry per project, with no loose files mixed in.
+share_projects_root() { printf '%s/projects' "${1%/}"; }
+
+# The host directory mounted at ~/shared for a launch against $2.
+share_dir_for() { printf '%s/%s' "$(share_projects_root "$1")" "$(ws_slug "$2")"; }
+
 # The slugs belonging to $1: its own, plus one per live git worktree nested
 # underneath it. One per line, sorted, no duplicates.
 #

bin/dejima-ttyd

@@ -178,10 +178,35 @@ focus_opt=()
 colors_opt=()
 [ -z "$button_colors" ] || colors_opt=(-t "buttonColors=$button_colors")
 
+# The sixteen ANSI slots xterm.js draws with, which without this are its own
+# defaults - white on black, a bright red, a magenta. dejima's own output
+# reaches a terminal in indexed colour precisely so the terminal's theme fills
+# those slots (see dejima-color-lib.sh), and here dejima IS the terminal: the
+# browser has no gruvbox to inherit, so the front door showed the stock
+# palette while the same session over SSH showed the operator's.
+#
+# So the exact hexes belong here, by the same rule as web/src/page.css: they
+# are the two surfaces where dejima owns the background. A static test keeps
+# the values they share in step.
+#
+# Upstream gruvbox dark, by its own names. `background` and `foreground` are
+# bg0/light1, which is what a gruvbox terminal is set to.
+theme_opt=(-t 'theme={
+  "background":"#282828","foreground":"#ebdbb2",
+  "cursor":"#ebdbb2","cursorAccent":"#282828",
+  "selectionBackground":"#504945",
+  "black":"#282828","red":"#cc241d","green":"#98971a","yellow":"#d79921",
+  "blue":"#458588","magenta":"#b16286","cyan":"#689d6a","white":"#a89984",
+  "brightBlack":"#928374","brightRed":"#fb4934","brightGreen":"#b8bb26",
+  "brightYellow":"#fabd2f","brightBlue":"#83a598","brightMagenta":"#d3869b",
+  "brightCyan":"#8ec07c","brightWhite":"#ebdbb2"
+}')
+
 exec ttyd --interface 127.0.0.1 --port "$port" --check-origin --url-arg --writable \
     --index "$index_html" \
     ${font_opt[@]+"${font_opt[@]}"} \
     ${prefix_opt[@]+"${prefix_opt[@]}"} \
     ${focus_opt[@]+"${focus_opt[@]}"} \
     ${colors_opt[@]+"${colors_opt[@]}"} \
+    "${theme_opt[@]}" \
     "$SCRIPT_DIR/dejima-attach"

bin/harness/claude-code.sh

@@ -31,10 +31,16 @@
 # Written through a temp file and renamed: the destination is the settings
 # layer bin/dejima is about to mount, and a jq that failed partway would
 # otherwise leave the session with a truncated one.
+# Where dejima's own hooks live inside the container. Baked into the image
+# (see docker/Dockerfile) rather than reached through the ~/.claude/hooks
+# mount, because that mount is the operator's configuration and dejima should
+# not have to write to it to make its own sandbox work.
+DEJIMA_HOOK_DIR=/usr/local/lib/dejima/hooks
+
 harness_register_notify() {
     local settings="$1" tmp
     tmp="$(mktemp "${TMPDIR:-/tmp}/dejima-settings-remote.XXXXXX.json")"
-    if jq '.hooks.Stop = ((.hooks.Stop // []) + [{"matcher": "", "hooks": [{"type": "command", "command": "$HOME/.claude/hooks/dejima-notify.sh done"}]}])' \
+    if jq '.hooks.Stop = ((.hooks.Stop // []) + [{"matcher": "", "hooks": [{"type": "command", "command": "'"$DEJIMA_HOOK_DIR"'/dejima-notify.sh done"}]}])' \
         "$settings" > "$tmp"; then
         mv "$tmp" "$settings"
     else
@@ -107,30 +113,16 @@ harness_state_mounts() {
 # what it can host (see `guards` in its manifest), and registering something
 # it did not declare would contradict the launch message that says so.
 harness_register_guards() {
-    local repo="$1" backup="$2" settings="$HOME/.claude/settings.json"
+    local repo="$1" settings="$HOME/.claude/settings.json"
 
-    mkdir -p "$HOME/.claude/hooks"
-
-    _link_hook() {
-        local name="$1" src="$repo/hooks/$1" dest="$HOME/.claude/hooks/$1"
-        if [ -L "$dest" ] && [ "$(readlink -f "$dest")" = "$(readlink -f "$src")" ]; then
-            echo "Skipping: $name already linked to this repo's copy"
-            return
-        fi
-        if [ -e "$dest" ] || [ -L "$dest" ]; then
-            mkdir -p "$backup"
-            echo "Moving: existing ~/.claude/hooks/$name to $backup/$name"
-            mv "$dest" "$backup/$name"
-        fi
-        echo "Linking: $name ($src -> $dest)"
-        ln -s "$src" "$dest"
-    }
-
-    # Not a guard: this is R3, the briefing's delivery mechanism, and a
-    # session without it does not know it is in a sandbox.
-    _link_hook sandbox-context.sh
-    harness_has_guard push-guard  && _link_hook git-push-guard.sh
-    harness_has_guard merge-guard && _link_hook merge-guard.sh
+    # Registers nothing. Every hook dejima uses is baked into the image and
+    # registered per launch into the sandbox's own --settings overlay, so
+    # installing dejima writes nothing to the operator's Claude Code config.
+    #
+    # What is left is taking back what older versions of this function put
+    # there. The hook is kept rather than deleted because "what a harness
+    # needs on the host" is a real question a future one may answer
+    # differently; for Claude Code the answer is now nothing.
 
     # Symlink from before the gitea-merge-guard.sh -> merge-guard.sh rename
     # points at a hooks/ path that no longer exists. Only remove it if it is
@@ -141,42 +133,18 @@ harness_register_guards() {
         rm -f "$old_merge_guard"
     fi
 
-    # Linked so it exists at a stable path for the read-only ~/.claude/hooks
-    # mount, but deliberately NOT registered below: bin/dejima registers it
-    # per session, into a throwaway settings copy, and only when remote
-    # access is configured. Registering it here would fire it for every
-    # unsandboxed host session too, where it has no marker directory to
-    # write to.
-    harness_has_guard notify && _link_hook dejima-notify.sh
 
-    # deny-dangerous-bash.sh is the one hook that is NOT sandbox-gated: it
-    # has no DEJIMA check, so it applies to the operator's own host sessions
-    # as well. That is deliberate, and it is why it may already be owned by
-    # another install (dotfiles, say) - only claim it if nothing else
-    # provides it, so this repo works standalone without clobbering an
-    # existing setup.
-    if harness_has_guard bash-deny; then
-        local deny_dest="$HOME/.claude/hooks/deny-dangerous-bash.sh"
-        if [ -e "$deny_dest" ] || [ -L "$deny_dest" ]; then
-            echo "Skipping: deny-dangerous-bash.sh already present at $deny_dest (leaving it as-is)"
-        else
-            echo "Linking: deny-dangerous-bash.sh ($repo/hooks/deny-dangerous-bash.sh -> $deny_dest)"
-            ln -s "$repo/hooks/deny-dangerous-bash.sh" "$deny_dest"
-        fi
-    fi
-    echo
 
-    if [ ! -f "$settings" ]; then
-        echo "Creating $settings"
-        echo '{}' > "$settings"
-    fi
+    # No settings.json is created here either: a file dejima writes nothing
+    # into is a file it has no business bringing into existence.
+    [ -f "$settings" ] || return 0
 
     # The registration that went with the symlink removed above. Two things
     # depend on it going: Claude Code reports a missing hook command on every
     # session start while it points at a path that no longer exists, and -
     # until the dedupe below stopped matching it - it also stood in for the
-    # registration it was renamed from, so `_register merge-guard.sh` skipped
-    # and the merge guard was registered nowhere at all. Dropped only when
+    # registration it was renamed from, so the merge guard's own registration
+    # was skipped and it was registered nowhere at all. Dropped only when
     # the path it names is gone, so an operator's own file at that name keeps
     # its registration, matching the symlink check above.
     if [ ! -e "$old_merge_guard" ] && jq -e --arg s "/gitea-merge-guard.sh" \
@@ -191,34 +159,34 @@ harness_register_guards() {
             "$settings" > "$stale_tmp" && mv "$stale_tmp" "$settings"
     fi
 
-    _register() {
-        local event="$1" matcher="$2" script_name="$3" description="$4"
-        # endswith on the leading slash, not test(): test() is an unanchored
-        # regex, so a hook whose name merely ends in another's - which is what
-        # a rename like gitea-merge-guard.sh -> merge-guard.sh produces - read
-        # as already registered, and the new hook was silently never added.
-        if jq -e --arg s "/$script_name" \
-            "[.hooks.${event}[]?.hooks[]?.command // empty] | any(endswith(\$s))" \
-            "$settings" >/dev/null 2>&1; then
-            echo "Skipping: $script_name already registered as a $event hook"
-            return
+    # An upgrade has to take back what an older install.sh put here, or the
+    # claim above is only true of a fresh one. Removed by name and only when
+    # the symlink points into THIS repo: an operator's own file at one of
+    # these names is theirs.
+    local moved dest
+    for moved in sandbox-context.sh git-push-guard.sh merge-guard.sh dejima-notify.sh \
+                 deny-dangerous-bash.sh; do
+        dest="$HOME/.claude/hooks/$moved"
+        if [ -L "$dest" ] && [ "$(readlink -f "$dest")" = "$(readlink -f "$repo/hooks/$moved")" ]; then
+            echo "Removing: $moved from ~/.claude/hooks (the sandbox registers its own now)"
+            rm -f "$dest"
         fi
-        echo "Registering $script_name as a $event hook in $settings ($description)"
-        local tmp
-        tmp=$(mktemp)
-        jq --arg matcher "$matcher" --arg cmd "\$HOME/.claude/hooks/$script_name" \
-            ".hooks.${event} = ((.hooks.${event} // []) + [{\"matcher\": \$matcher, \"hooks\": [{\"type\": \"command\", \"command\": \$cmd}]}])" \
-            "$settings" > "$tmp" && mv "$tmp" "$settings"
-    }
-
-    _register SessionStart "startup|resume|clear|compact" sandbox-context.sh \
-        "injects sandbox context on session start"
-    harness_has_guard push-guard && _register PreToolUse Bash git-push-guard.sh \
-        "blocks pushes outside the allowed host(s)/branches"
-    harness_has_guard merge-guard && _register PreToolUse Bash merge-guard.sh \
-        "blocks the configured forge's merge command inside the sandbox"
-    harness_has_guard bash-deny && _register PreToolUse Bash deny-dangerous-bash.sh \
-        "blocks obviously destructive Bash commands"
+        # And its registration, matched the same endswith way _register does.
+        local ev
+        for ev in SessionStart PreToolUse Stop; do
+            if jq -e --arg s "/$moved" \
+                "[.hooks.${ev}[]?.hooks[]?.command // empty] | any(endswith(\$s))" \
+                "$settings" >/dev/null 2>&1; then
+                echo "Removing: $moved's $ev registration from $settings"
+                local mv_tmp; mv_tmp=$(mktemp)
+                jq --arg s "/$moved" \
+                    ".hooks.${ev} = ((.hooks.${ev} // [])
+                        | map(.hooks = ((.hooks // []) | map(select((.command // \"\") | endswith(\$s) | not))))
+                        | map(select((.hooks | length) > 0)))" \
+                    "$settings" > "$mv_tmp" && mv "$mv_tmp" "$settings"
+            fi
+        done
+    done
     echo
     return 0
 }
@@ -379,14 +347,11 @@ _plugin_version_mounts() {
 harness_prepare_config() {
     local overlay="$1" settings="$HOME/.claude/settings.json" settings_error
 
-    # install.sh normally creates settings.json, and many hosts have no
-    # CLAUDE.md at all. Created empty rather than left absent because
-    # harness_staged_config below emits both unconditionally and core skips
-    # staging a file that does not exist - so without this the session would
-    # silently start without them. statusline.sh is deliberately NOT created:
-    # an empty one would be staged executable and run as the status line.
-    [ -f "$settings" ] || echo '{}' > "$settings"
-    [ -f "$HOME/.claude/CLAUDE.md" ] || : > "$HOME/.claude/CLAUDE.md"
+
+    # Nothing is created on the host. A settings.json or CLAUDE.md the
+    # operator does not have is not one dejima should make on their machine so
+    # that it has something to copy - harness_staged_config asks for an empty
+    # one in the CONTAINER instead, which is where it is needed.
 
     # Claude Code ignores a settings.json it cannot parse, wholesale and with
     # only a startup warning, so a stray edit on the host costs the sandbox
@@ -395,7 +360,8 @@ harness_prepare_config() {
     # symptom is an unexpected bypass-mode warning rather than anything
     # mentioning settings. The file is staged verbatim, so nothing else parses
     # it before the session reads it - check here, where the fix is at hand.
-    if ! settings_error="$(jq . "$settings" 2>&1 >/dev/null)"; then
+    # Absent is not unparseable: there is simply nothing to stage.
+    if [ -f "$settings" ] && ! settings_error="$(jq . "$settings" 2>&1 >/dev/null)"; then
         echo "$settings is not valid JSON:" >&2
         echo "  $settings_error" >&2
         echo "Claude Code would ignore it entirely and the sandbox would start with" >&2
@@ -410,7 +376,38 @@ harness_prepare_config() {
     # --settings layer (the manifest's settings_args) above
     # ~/.claude/settings.json, which holds only what the sandbox overrides;
     # the operator's hooks, permissions and plugins still apply from there.
+    #
+    # And dejima's own hooks, registered HERE rather than in the operator's
+    # ~/.claude/settings.json. Claude Code merges this layer with theirs, so
+    # their hooks still run - proven by the one dejima deliberately leaves on
+    # the host, deny-dangerous-bash.sh, which fires inside a container while
+    # being registered only there.
+    #
+    # Registering them here is what lets install.sh stop writing to a config
+    # that is not dejima's. The scripts are baked into the image, so a session
+    # cannot unlink a guard the way it could one staged into a directory it
+    # owns.
     jq -n '{sandbox: {enabled: false}}' > "$overlay"
+    _register_overlay_hook() {  # <event> <matcher> <script>
+        local event="$1" matcher="$2" script="$3" tmp
+        tmp="$(mktemp "${TMPDIR:-/tmp}/dejima-overlay.XXXXXX.json")" || return 1
+        if jq --arg m "$matcher" --arg c "$DEJIMA_HOOK_DIR/$script" \
+            ".hooks.${event} = ((.hooks.${event} // []) +
+                [{\"matcher\": \$m, \"hooks\": [{\"type\": \"command\", \"command\": \$c}]}])" \
+            "$overlay" > "$tmp"; then
+            mv "$tmp" "$overlay"
+        else
+            rm -f "$tmp"
+            echo "warning: could not register $script; it will not run this session." >&2
+        fi
+    }
+    # R3: without this a session is not told it is in a sandbox at all, which
+    # is why it is registered whether or not any guard is declared.
+    _register_overlay_hook SessionStart "startup|resume|clear|compact" sandbox-context.sh
+    harness_has_guard push-guard  && _register_overlay_hook PreToolUse Bash git-push-guard.sh
+    harness_has_guard merge-guard && _register_overlay_hook PreToolUse Bash merge-guard.sh
+    harness_has_guard bash-deny   && _register_overlay_hook PreToolUse Bash deny-dangerous-bash.sh
+    return 0
 }
 
 harness_staged_config() {
@@ -418,10 +415,13 @@ harness_staged_config() {
     # and what a dangling symlink means, are core's to decide - filtering
     # here would skip a dangling one silently, which is the case that must
     # refuse rather than quietly leave the session without the file.
-    local f
-    for f in settings.json CLAUDE.md statusline.sh; do
-        emit_staged_config "$HOME/.claude/$f" ".claude/$f"
-    done
+    # settings.json and CLAUDE.md are asked to exist even when the host has
+    # none: Claude Code reads both, and an empty one reads the same as a file
+    # the operator never made. statusline.sh is not - an empty one would be
+    # installed executable and run as the status line.
+    emit_staged_config "$HOME/.claude/settings.json" ".claude/settings.json" ensure-json
+    emit_staged_config "$HOME/.claude/CLAUDE.md" ".claude/CLAUDE.md" ensure
+    emit_staged_config "$HOME/.claude/statusline.sh" ".claude/statusline.sh"
 }
 
 # Where this workspace's transcripts are, and which store key each belongs
@@ -601,35 +601,25 @@ harness_transform_transcript() {
     ' 2>/dev/null
 }
 
-# Which of the hooks install.sh registers are actually in the operator's
-# settings, and which are not. Prints the missing ones, one per line, and
-# returns 1 if there are any - so the launch can name what is not in force
-# rather than assert that nothing is.
+# harness_guards_registered is deliberately not defined.
 #
-# Every hook this harness would install is checked, not just the briefing:
-# the realistic failure (install.sh never run with a harness set) is
-# all-or-nothing, but a hand-edited settings.json missing one guard is a
-# session quietly running without it, which is the case worth catching.
+# It read the operator's own ~/.claude/settings.json and named any of dejima's
+# hooks missing from it, because that is where install.sh used to put them and
+# "install.sh never run with a harness set" was a real way to get a session
+# with no briefing and no guards.
 #
-# dejima-notify.sh is deliberately absent: bin/dejima registers it per
-# session into a throwaway layer, and it is never in the operator's file.
+# Nothing is written there now: the hooks are baked into the image and
+# registered per launch into dejima's own --settings overlay, so an absent
+# registration in the operator's file is the correct state rather than a
+# broken one. Left defined, it named all four as not in force on every launch
+# of a host that had never run the old installer - and told the operator to
+# run ./install.sh, which strips exactly those registrations, making the
+# message permanent.
 #
-# Reads the operator's real settings rather than dejima's own layer, which
-# is composed fresh each launch and always looks right.
-harness_guards_registered() {
-    local settings="$HOME/.claude/settings.json" missing=0
-    _registered() {
-        [ -f "$settings" ] || return 1
-        jq -e --arg s "/$2" "[.hooks.$1[]?.hooks[]?.command // empty]
-               | any(endswith(\$s))" "$settings" >/dev/null 2>&1
-    }
-    _registered SessionStart sandbox-context.sh \
-        || { printf 'the session briefing\n'; missing=1; }
-    harness_has_guard push-guard && { _registered PreToolUse git-push-guard.sh \
-        || { printf 'push-guard\n'; missing=1; }; }
-    harness_has_guard merge-guard && { _registered PreToolUse merge-guard.sh \
-        || { printf 'merge-guard\n'; missing=1; }; }
-    harness_has_guard bash-deny && { _registered PreToolUse deny-dangerous-bash.sh \
-        || { printf 'bash-deny\n'; missing=1; }; }
-    return "$missing"
-}
+# There is nothing to put in its place. What the overlay carries is composed
+# fresh each launch from the manifest, so reading it back would be asking
+# dejima whether it did what it just did; which guards the harness cannot host
+# at all is the manifest's, and harness_report_guards already says it.
+#
+# The hook itself stays in the plugin interface. What a harness needs wired on
+# the host is a real question, and a future one may answer it differently.

bin/harness/cline.sh

@@ -40,18 +40,17 @@ harness_briefing_state_dir() {
 
 # Which endpoints a session may be pointed at, and why the answer is not "any".
 #
-# Absent base_url means Anthropic: Cline is configured with the real hostname
-# and a placeholder key, and dejima's in-container terminator and host-side
-# proxy supply the real credential, exactly as they do for Claude Code. The
-# credential never enters the container.
+# The selected backend says where the model is. A proxied one carries its own
+# upstream and dejima's terminator stands in front of it, so the credential
+# never enters the container. A backend with `credential = none` is a model
+# the operator serves, carrying its own [backend.<name>] base_url, and it is
+# reached directly because there is nothing to withhold.
 #
-# A base_url means a self-hosted endpoint, and it has to be one reachable
-# without a credential - the Docker host, or something on the sandbox's own
-# network. That restriction is R5 and not a network one: a hosted provider
-# would need an API key inside the container, and dejima has no proxy that
-# could hold one back on its behalf. An endpoint that needs no key has nothing
-# to withhold, which is why an open-weight model served locally is supported
-# today and api.openai.com is not.
+# That second kind has to be an endpoint that genuinely needs no credential.
+# The restriction is R5 and not a network one: a hosted API pointed at this way
+# would need a key inside the container, and dejima has no proxy holding one
+# for it. An endpoint that needs no key has nothing to withhold, which is why a
+# model served locally is supported and api.openai.com reached this way is not.
 #
 # Two ways an endpoint qualifies, and neither is about the URL's syntax.
 #
@@ -66,17 +65,15 @@ harness_briefing_state_dir() {
 # what the container can reach at all, so an endpoint failing this check is
 # one the session could not have connected to anyway. Requiring a literal
 # address instead was too strict by half: a model server on someone's own
-# network normally has a name, and refusing it made the local-endpoint path -
-# the reason this harness is provider-agnostic at all - unusable for the
-# ordinary case.
+# network normally has a name, and refusing it made this path - the reason
+# this harness is backend-agnostic at all - unusable for the ordinary case.
 #
-# What neither branch is doing is protecting the model credential. dejima
-# writes a placeholder into providers.json on this path whatever the endpoint
+# What this is not doing is protecting the model credential. dejima writes a
+# placeholder into providers.json on every proxied path whatever the endpoint
 # is, so no real credential enters the container either way. What this decides
-# is whether the configuration can WORK: an endpoint that needs a key would
-# get the placeholder and fail, and saying so at launch beats an auth error
-# three layers down. Pointing it somewhere is the operator's call, bounded by
-# an allowlist entry they made deliberately.
+# is whether the configuration can WORK: an endpoint that needs a key would get
+# a no-credential marker and fail, and saying so at launch beats an auth error
+# three layers down.
 _cline_host_local() {
     local url="$1" host a b
     host="${url#*://}"
@@ -130,7 +127,7 @@ _cline_host_allowlisted() {
     return 1
 }
 
-# The provider configuration the session runs with, and the three conditions
+# The backend configuration the session runs with, and the three conditions
 # that make a launch wrong: no model, a credential mode with no path through,
 # and an endpoint whose key dejima would have to put in the container.
 #
@@ -146,7 +143,7 @@ _cline_host_allowlisted() {
 # bounds where a repointed endpoint could reach. What rewriting buys is that a
 # repointing cannot persist into the next session.
 harness_prepare_config() {
-    local state model base_url settings
+    local state model settings
     state="$(_cline_state_dir "$WORKSPACE_DIR")" || {
         echo "harness.cline: state_dir is not set, so there is nowhere to keep" >&2
         echo "this project's Cline state. Set it in [harness.cline]." >&2
@@ -162,61 +159,98 @@ harness_prepare_config() {
         echo "  [harness.cline]" >&2
         echo "  model = claude-haiku-4-5-20251001" >&2
         echo "" >&2
-        echo "\`cline auth\` outside the sandbox lists what your provider offers." >&2
+        echo "\`cline auth\` outside the sandbox lists what your backend offers." >&2
         return 1
     fi
 
-    base_url="$(harness_config_get base_url)"
     local ctx
     ctx="$(harness_config_get context_window)"
 
-    # The Anthropic path is the credential proxy's path, and it only works in
-    # the shape that was actually tested: the proxy on, terminating TLS for
-    # api.anthropic.com in-container, with Cline configured for the real
-    # hostname and a placeholder key.
+    # WHERE THE MODEL IS is the backend's, and only the backend's. One
+    # setting, so there is nothing for a second one to disagree with.
     #
-    # With the proxy off, Claude Code mounts the operator's real credential -
-    # a downgrade this repository documents and accepts. There is no
-    # equivalent here: the credential Cline would need is in the operator's
-    # own providers.json, which is exactly the file dejima declines to mount,
-    # and writing a placeholder anyway would produce an auth failure whose
-    # cause is three layers away. The loopback transport is the same story
-    # from the other end - it hands the harness a base URL and a token through
-    # the environment, which Cline does not read for provider selection
+    # A self-served endpoint is `backend = self-hosted`, carrying its own
+    # [backend.self-hosted] base_url. That placement is what lets an operator
+    # keep a local model configured while using a hosted API, and switch
+    # between them by changing one word.
+    local backend
+    backend="$(harness_config_get backend)"
+    if [ -z "$backend" ]; then
+        echo "harness.cline: no [harness.cline] backend is set, so nothing says" >&2
+        echo "where the model is." >&2
+        echo "" >&2
+        echo "  [harness.cline]" >&2
+        echo "  backend = openrouter      a hosted API, key held on the host" >&2
+        echo "  backend = self-hosted     a model you serve, with no key at all" >&2
+        echo "" >&2
+        echo "There is deliberately no default: one dejima could change later would" >&2
+        echo "move your session to another endpoint without your config changing." >&2
+        return 1
+    fi
+
+    local kind base_url=""
+    kind="$(manifest_get backend "$backend" credential)" || return 1
+    if [ "$kind" = none ]; then
+        base_url="$(config_get "backend.$backend" base_url)" || return 1
+    fi
+
+    # The proxy is what keeps a credential out of the container, and it only
+    # works in the shape that was actually tested: the proxy on, terminating
+    # TLS in-container, with Cline configured for the endpoint's real hostname
+    # and a placeholder key.
+    #
+    # With the proxy off, claude-code mounts the operator's real credential - a
+    # downgrade this repository documents and accepts. There is no equivalent
+    # here: the credential Cline would need is in the operator's own
+    # providers.json, which is exactly the file dejima declines to mount, and
+    # writing a placeholder anyway would produce an auth failure whose cause is
+    # three layers away. The loopback transport is the same story from the
+    # other end - it hands the harness a base URL and a token through the
+    # environment, which Cline does not read for provider selection
     # (CLINE_PROVIDER and CLINE_MODEL were tried and ignored).
     #
-    # Both refuse rather than start something that will fail confusingly, and
-    # both have the same way out: point base_url at a model you serve.
-    if [ -z "$base_url" ]; then
+    # A backend with no credential is unaffected: there is nothing to withhold
+    # and no proxy in the path.
+    if [ "$kind" != none ]; then
         local why=""
-        [ "$(config_get_bool credentials proxy)" = "1" ] \
-            || why="[credentials] proxy is off"
+        backend_proxy_enabled "$backend" \
+            || why="the proxy is off for this backend"
         [ -n "$why" ] || [ "$(config_get credentials transport)" = "tls" ] \
             || why="[credentials] transport is loopback"
         if [ -n "$why" ]; then
-            echo "harness.cline: $why, and cline has no way to reach Anthropic" >&2
-            echo "without the TLS terminator the proxy puts in front of it." >&2
+            echo "harness.cline: $why, and cline has no way to reach a proxied" >&2
+            echo "backend without the TLS terminator the proxy puts in front of it." >&2
             echo "Its credential lives in the providers.json dejima declines to" >&2
             echo "mount, so there is nothing to fall back to - unlike claude-code," >&2
             echo "which mounts the real credential in that mode." >&2
             echo "" >&2
             echo "Either turn the proxy back on with the default tls transport," >&2
-            echo "or set [harness.cline] base_url to a model you serve yourself." >&2
+            echo "or select a backend you serve yourself." >&2
             return 1
         fi
     fi
 
-    if [ -n "$base_url" ] && ! _cline_host_local "$base_url"; then
-        echo "harness.cline: refusing base_url $base_url." >&2
-        echo "It is not a host-local endpoint, so it would need an API key" >&2
-        echo "inside the container, and dejima has no proxy that can hold one" >&2
-        echo "back for that provider - the model credential would stop being" >&2
-        echo "something the sandbox never sees." >&2
+    # An endpoint reached with no credential has to be one that needs none, and
+    # that is an R5 check rather than a network rule: a hosted API pointed at
+    # this way would want a key inside the container, and the model credential
+    # would stop being something the sandbox never sees.
+    #
+    # Still here rather than in core because cline is the only harness with a
+    # direct path today. It belongs in core the moment a second one has one.
+    if [ "$kind" = none ] && ! _cline_host_local "$base_url"; then
+        echo "harness.cline: refusing [backend.$backend] base_url $base_url." >&2
+        echo "That backend needs no credential, so the endpoint has to be one" >&2
+        echo "that needs none: a model you serve. This is not host-local, so it" >&2
+        echo "would want a key inside the container." >&2
         echo "" >&2
-        echo "Supported today: leave base_url unset for Anthropic through" >&2
-        echo "dejima's own credential proxy, or point it at a model you serve" >&2
-        echo "yourself, which needs no key. That means a loopback or RFC 1918" >&2
-        echo "address, or a host you have allowlisted:" >&2
+        echo "For a hosted API, select a backend for it instead - the key is then" >&2
+        echo "held on the host and injected per request:" >&2
+        echo "" >&2
+        echo "  [harness.cline]" >&2
+        echo "  backend = openrouter" >&2
+        echo "" >&2
+        echo "For one you serve, that means a loopback or RFC 1918 address, or a" >&2
+        echo "host you have allowlisted:" >&2
         echo "" >&2
         echo "  dejima-allow --project <path> <host>" >&2
         echo "" >&2
@@ -246,25 +280,45 @@ harness_prepare_config() {
 
     local tmp
     tmp="$(mktemp "$settings/.providers.XXXXXX")" || return 1
-    if [ -n "$base_url" ]; then
-        jq -n --arg m "$model" --arg u "$base_url" \
+    # Which of Cline's own provider types to write, from the selected
+    # backend's api_style rather than from a second setting an operator has
+    # to keep in step. Anthropic's Messages API and an OpenAI-compatible one
+    # are different wire formats, and Cline has a client for each.
+    local style endpoint key
+    style="$(manifest_get backend "$backend" api_style)" || return 1
+    if [ "$kind" = none ]; then
+        endpoint="$base_url"
+        key="dejima-no-credential-needed"
+    else
+        # The endpoint's REAL hostname, not a loopback one. The terminator
+        # answers for it inside the container and the host-side proxy holds the
+        # credential, which is what keeps the session indistinguishable from
+        # one talking to the API directly.
+        endpoint="$(manifest_get backend "$backend" upstream)" || return 1
+        # The placeholder is what Cline sends; the host-side proxy replaces it
+        # with the real credential on the way out. Same arrangement as Claude
+        # Code's faked .credentials.json, confirmed end to end against the API.
+        key="sandbox-credential-proxy-placeholder"
+    fi
+
+    if [ "$style" = anthropic ]; then
+        # Cline's native Anthropic client, which addresses the API by name and
+        # so needs no baseUrl: entrypoint.sh has already pointed that name at
+        # the terminator.
+        jq -n --arg m "$model" --arg k "$key" \
+            --arg t "$now" --arg c "$ctx" \
+            '{version: 1, lastUsedProvider: "anthropic", modes: {},
+              providers: {anthropic: {
+                settings: ({provider: "anthropic", model: $m, apiKey: $k}
+                           + (if $c == "" then {} else {contextWindow: ($c|tonumber)} end)),
+                updatedAt: $t, tokenSource: "manual"}}}' > "$tmp"
+    else
+        jq -n --arg m "$model" --arg u "$endpoint" --arg k "$key" \
             --arg t "$now" --arg c "$ctx" \
             '{version: 1, lastUsedProvider: "openai-compatible", modes: {},
               providers: {"openai-compatible": {
                 settings: ({provider: "openai-compatible", model: $m,
-                            baseUrl: $u, apiKey: "dejima-no-credential-needed"}
-                           + (if $c == "" then {} else {contextWindow: ($c|tonumber)} end)),
-                updatedAt: $t, tokenSource: "manual"}}}' > "$tmp"
-    else
-        # The placeholder is what Cline sends; the host-side proxy replaces it
-        # with the real credential on the way out. Same arrangement as Claude
-        # Code's faked .credentials.json, confirmed end to end against the API.
-        jq -n --arg m "$model" \
-            --arg t "$now" --arg c "$ctx" \
-            '{version: 1, lastUsedProvider: "anthropic", modes: {},
-              providers: {anthropic: {
-                settings: ({provider: "anthropic", model: $m,
-                            apiKey: "sandbox-credential-proxy-placeholder"}
+                            baseUrl: $u, apiKey: $k}
                            + (if $c == "" then {} else {contextWindow: ($c|tonumber)} end)),
                 updatedAt: $t, tokenSource: "manual"}}}' > "$tmp"
     fi || { rm -f "$tmp"; return 1; }
@@ -278,6 +332,91 @@ harness_prepare_config() {
 # nothing inside the container has to be told where its state is - the source
 # is keyed by dejima's workspace slug and only the target follows the harness,
 # which is what emit_mount_at is for.
+# The operator's own configuration, brought in from the host.
+#
+# Read-only, and that is the whole point rather than caution: everything here
+# is either an instruction the agent follows or a program cline runs. A
+# session that could rewrite them would be choosing what happens on the HOST
+# the next time cline starts outside a container - persistence for a prompt
+# injection, in files nobody re-reads before the next run.
+#
+# `scan` for the same reason claude-code's directories are scanned: on a Linux
+# host these are routinely symlinks into a dotfiles checkout, and the target
+# has to be mounted for the link to resolve inside the container. Core refuses
+# a target that overlaps a guarded store.
+#
+# ~/.agents/rules is deliberately absent. It reads like the obvious companion
+# to ~/.agents/skills and cline does not load it - checked by planting a file
+# in it and one in ~/Documents/Cline/Rules and asking `cline config` which it
+# had: only the second appeared. Mounting a directory the harness never reads
+# would be a promise dejima cannot keep.
+harness_config_dirs() {
+    emit_config_dir "$HOME/.agents/skills" ro scan
+    # Not confirmed loaded by that same probe, unlike skills. Mounted because
+    # it is the documented default for --hooks-dir and because the cost of
+    # being wrong is an empty directory, where the cost of leaving it out is a
+    # hook that silently does not run.
+    emit_config_dir "$HOME/.agents/hooks" ro scan
+    emit_config_dir "$HOME/.cline/hooks" ro scan
+}
+
+# AGENTS.md is instructions the agent follows, so a session that could write
+# the host's copy would be choosing what the next session is told. Staged
+# rather than mounted: the copy lands root-owned and read-only, and a file
+# that is a symlink into a dotfiles checkout arrives as its real content
+# rather than as a link the host can still swap.
+harness_staged_config() {
+    emit_staged_config "$HOME/.agents/AGENTS.md" ".agents/AGENTS.md"
+
+    # Global rules, from both host locations into the one directory cline
+    # actually reads.
+    #
+    # cline loads global rules from Documents/Cline/Rules and nowhere else -
+    # ~/.agents/rules reads like its companion and is not read, checked by
+    # planting a file in each and asking `cline config` which it had. So
+    # ~/.agents/rules is supported by staging its files INTO the directory
+    # that is read, rather than by mounting it where it sits and having
+    # nothing load it.
+    #
+    # File by file rather than as a directory mount, because dejima writes its
+    # own briefing into that same directory: a read-only mount over it would
+    # leave nowhere to put the briefing.
+    local d f base briefing seen=" "
+    # The briefing's own name, from the manifest rather than repeated here.
+    # dejima wins that collision, and entrypoint.sh already delivers it after
+    # the staged files - so staging a host file it is about to overwrite would
+    # only add a mount nobody reads.
+    briefing="$(basename "$(manifest_get harness cline briefing_path)")"
+    # Documents first, so a name present in both wins there: it is cline's own
+    # location for this, and where an operator editing rules through cline is
+    # writing. Two sources staged to one destination would otherwise be two
+    # bind mounts at the same container path.
+    for d in "$HOME/Documents/Cline/Rules" "$HOME/.agents/rules"; do
+        [ -d "$d" ] || continue
+        # .md and .txt are what cline reads out of a rules directory.
+        for f in "$d"/*.md "$d"/*.txt; do
+            [ -f "$f" ] || continue
+            base="$(basename "$f")"
+            [ "$base" = "$briefing" ] && continue
+            case "$seen" in *" $base "*) continue ;; esac
+            seen="$seen$base "
+            emit_staged_config "$f" "Documents/Cline/Rules/$base"
+        done
+    done
+}
+
+# Writable copies, discarded with the container.
+#
+# cline rewrites both of these as it runs - its settings TUI toggles them - so
+# a read-only copy would fail the write rather than the persistence, and the
+# persistence is the part that matters. cline_mcp_settings.json names MCP
+# servers, which are commands cline executes: a session that could write the
+# host's copy would be choosing what runs there next time.
+harness_seed() {
+    emit_seed_from "$HOME/.cline/settings.json" ".cline/settings.json"
+    emit_seed_from "$HOME/.cline/cline_mcp_settings.json" ".cline/cline_mcp_settings.json"
+}
+
 harness_state_mounts() {
     local dir
     dir="$(_cline_state_dir "$1")" || return 0

docker/Dockerfile

@@ -273,7 +273,7 @@ COPY docker/ulogd.conf /etc/ulogd-sandbox.conf
 # Into $VIMRUNTIME/plugin, not /etc/xdg/nvim - see the file's own comment.
 COPY docker/sandbox-clipboard.lua /usr/local/share/nvim/runtime/plugin/sandbox-clipboard.lua
 COPY docker/entrypoint.sh /usr/local/bin/
-COPY docker/anthropic-proxy-forwarder.js /usr/local/bin/anthropic-proxy-forwarder.js
+COPY docker/credential-proxy-forwarder.js /usr/local/bin/credential-proxy-forwarder.js
 COPY docker/harness-wrapper.sh /usr/local/bin/dejima-harness-wrapper
 # The two guards that do not need the harness's help. git-guard shadows git on
 # PATH; forge-guard is linked over a forge CLI by entrypoint.sh when a workflow
@@ -287,6 +287,17 @@ COPY docker/forge-guard.sh /usr/local/lib/dejima/forge-guard.sh
 # entrypoint.sh, which renders the briefing before the session starts - to
 # hand to the harness as an argument, or to write to a file it reads.
 COPY hooks/dejima-briefing-render.sh /usr/local/lib/dejima/dejima-briefing-render.sh
+# dejima's own hooks, for the same reason and one more: they are registered
+# into the sandbox's --settings overlay rather than into the operator's
+# ~/.claude/settings.json, so nothing has to be written to a host config to
+# make the sandbox work. Baked rather than mounted from the checkout because a
+# guard whose script can change under a running session is not one.
+#
+COPY hooks/deny-dangerous-bash.sh /usr/local/lib/dejima/hooks/deny-dangerous-bash.sh
+COPY hooks/sandbox-context.sh /usr/local/lib/dejima/hooks/sandbox-context.sh
+COPY hooks/git-push-guard.sh /usr/local/lib/dejima/hooks/git-push-guard.sh
+COPY hooks/merge-guard.sh /usr/local/lib/dejima/hooks/merge-guard.sh
+COPY hooks/dejima-notify.sh /usr/local/lib/dejima/hooks/dejima-notify.sh
 # Back to root before the first RUN that writes outside /home/node. The npm
 # installs above run as node deliberately; COPY writes as root regardless of
 # USER, so the copies above are unaffected, but the install(1) below is a RUN
@@ -312,7 +323,7 @@ RUN bash /tmp/install-forge-bins.sh /tmp/forges /usr/local/lib/dejima/forge /usr
 # and describes what a page should look like instead of going and seeing.
 RUN ln -s /usr/local/share/npm-global/lib/node_modules /node_modules
 
-RUN chmod +x /usr/local/bin/dns-proxy.sh /usr/local/bin/init-firewall.sh /usr/local/bin/log-shipper.sh /usr/local/bin/entrypoint.sh /usr/local/bin/dejima-harness-wrapper /usr/local/lib/dejima/git-guard.sh /usr/local/lib/dejima/forge-guard.sh /usr/local/lib/dejima/dejima-briefing-render.sh && \
+RUN chmod +x /usr/local/bin/dns-proxy.sh /usr/local/bin/init-firewall.sh /usr/local/bin/log-shipper.sh /usr/local/bin/entrypoint.sh /usr/local/bin/dejima-harness-wrapper /usr/local/lib/dejima/git-guard.sh /usr/local/lib/dejima/forge-guard.sh /usr/local/lib/dejima/dejima-briefing-render.sh /usr/local/lib/dejima/hooks/*.sh && \
   echo 'export PATH="$PATH:/usr/local/share/npm-global/bin"' > /etc/profile.d/npm-global-path.sh
 
 # Entrypoint runs as root (no USER node here) so it can set up the firewall

docker/credential-proxy-forwarder.js

@@ -1,6 +1,6 @@
 // TCP front door for the host-side credential proxy, which listens on a
 // bind-mounted unix socket (no host TCP exposure - see
-// bin/dejima-anthropic-proxy). Deliberately no HTTP awareness in either
+// bin/dejima-credential-proxy). Deliberately no HTTP awareness in either
 // mode: bytes in, bytes out.
 //
 // tls (default): terminates TLS for api.anthropic.com on :443, which
@@ -29,7 +29,7 @@ const port = parseInt(
   10,
 );
 if (!socketPath) {
-  console.error("anthropic-proxy-forwarder: SANDBOX_ANTHROPIC_PROXY_SOCKET not set");
+  console.error("credential-proxy-forwarder: SANDBOX_ANTHROPIC_PROXY_SOCKET not set");
   process.exit(1);
 }
 
@@ -47,7 +47,7 @@ if (transport === "tls") {
   const keyPath = process.env.SANDBOX_ANTHROPIC_TLS_KEY;
   if (!certPath || !keyPath) {
     console.error(
-      "anthropic-proxy-forwarder: SANDBOX_ANTHROPIC_TLS_CERT/SANDBOX_ANTHROPIC_TLS_KEY not set",
+      "credential-proxy-forwarder: SANDBOX_ANTHROPIC_TLS_CERT/SANDBOX_ANTHROPIC_TLS_KEY not set",
     );
     process.exit(1);
   }

docker/docker-compose.yml

@@ -34,7 +34,13 @@ services:
     # $SANDBOX_IMAGE lets bin/dejima point a run at a derived,
     # per-project image instead, without this build ever producing one
     # under that name itself - see bin/dejima.
-    image: ${SANDBOX_IMAGE:-dejima:${SANDBOX_USER:-node}}
+    # localhost/ so this can never resolve to Docker Hub: Docker reads a first
+    # component containing a dot or colon, or exactly "localhost", as a
+    # registry host, and a bare `dejima:node` is `docker.io/library/dejima:node`
+    # to anything that pushes (#53). bin/dejima holds the same prefix in
+    # SANDBOX_IMAGE_REPO and passes it in; this default is for a compose
+    # invocation by hand.
+    image: ${SANDBOX_IMAGE:-localhost/dejima:${SANDBOX_USER:-node}}
     # Run tini as PID 1 so orphaned processes get reaped. Without it PID 1 is
     # the session's own command (claude, or nvim under SANDBOX_NVIM_CONFIG),
     # which never reaps: every process-substitution child the test suite and
@@ -131,10 +137,11 @@ services:
       # The names this harness needs reachable, and the one its credential
       # proxy stands in front of - see docker/fixed-domains.sh.
       SANDBOX_HARNESS_DOMAINS: ${SANDBOX_HARNESS_DOMAINS:-}
-      SANDBOX_HARNESS_PROXIED_DOMAIN: ${SANDBOX_HARNESS_PROXIED_DOMAIN:-}
+      SANDBOX_BACKEND_PROXIED_DOMAIN: ${SANDBOX_BACKEND_PROXIED_DOMAIN:-}
       SANDBOX_HARNESS_BRIEFING_ARGS: ${SANDBOX_HARNESS_BRIEFING_ARGS:-}
       SANDBOX_HARNESS_BRIEFING_PATH: ${SANDBOX_HARNESS_BRIEFING_PATH:-}
       SANDBOX_HARNESS_SEED: ${SANDBOX_HARNESS_SEED:-}
+      SANDBOX_HARNESS_STAGED_EMPTY: ${SANDBOX_HARNESS_STAGED_EMPTY:-}
       # Opt-in escape hatch from the default hard GitHub-push block - see
       # init-firewall.sh and git-push-guard.sh. Off unless explicitly set.
       ALLOW_GITHUB_PUSH: ${ALLOW_GITHUB_PUSH:-0}
@@ -162,6 +169,10 @@ services:
       # empty - and unset by entrypoint.sh - otherwise.
       ANTHROPIC_BASE_URL: ${SANDBOX_ANTHROPIC_BASE_URL:-}
       ANTHROPIC_AUTH_TOKEN: ${SANDBOX_ANTHROPIC_AUTH_TOKEN:-}
+      # The placeholder an API-billing session authenticates with. The real key
+      # never enters the container; the host-side proxy swaps this for it per
+      # request, exactly as it does for a subscription login's token.
+      ANTHROPIC_API_KEY: ${SANDBOX_ANTHROPIC_API_KEY:-}
       SANDBOX_ANTHROPIC_PROXY_SOCKET: ${SANDBOX_ANTHROPIC_PROXY_SOCKET:-}
       SANDBOX_ANTHROPIC_TRANSPORT: ${SANDBOX_ANTHROPIC_TRANSPORT:-}
     volumes:

docker/entrypoint.sh

@@ -235,6 +235,36 @@ if [ -d /etc/dejima-harness ]; then
     done < <(find /etc/dejima-harness -type f -print0)
 fi
 
+# Files the harness needs to exist whether or not the operator has one.
+#
+# Created HERE rather than on the host. A harness that reads a settings file
+# still reads one when it is empty, and dejima creating that file on the
+# operator's machine - so there is something to copy - is a write to their
+# configuration for dejima's own convenience. Root-owned and read-only, the
+# same as anything else staged, so the container's copy is not a channel back.
+for _spec in ${SANDBOX_HARNESS_STAGED_EMPTY:-}; do
+    _kind="${_spec%%:*}"
+    _rel="${_spec#*:}"
+    case "$_rel" in
+        /*|*..*)
+            echo "entrypoint: refusing staged-config path '$_rel': it must be" >&2
+            echo "relative to the sandbox user's home and must not contain '..'." >&2
+            exit 1 ;;
+    esac
+    _dest="$SANDBOX_HOME/$_rel"
+    [ -e "$_dest" ] && continue
+    mkdir -p "$(dirname "$_dest")"
+    # An empty file is not valid JSON, and a harness that discards a config it
+    # cannot parse would lose everything in it rather than nothing.
+    if [ "$_kind" = ensure-json ]; then
+        printf '{}\n' > "$_dest"
+    else
+        : > "$_dest"
+    fi
+    chown root:root "$_dest"
+    chmod 444 "$_dest"
+done
+
 # The harness's own writable state. Unlike the staged config above, these are
 # owned by the sandbox user and stay writable: they are what the harness
 # rewrites as it runs - a plugin registry, a catalogue, an install marker -
@@ -348,11 +378,11 @@ if [ -n "${SANDBOX_HARNESS_BRIEFING_ARGS:-}" ]; then
 fi
 
 # TCP front door for the host-side credential proxy (see bin/dejima and
-# bin/dejima-anthropic-proxy): the proxy listens on a bind-mounted unix
-# socket, and anthropic-proxy-forwarder.js pipes bytes into it. Only started
+# bin/dejima-credential-proxy): the proxy listens on a bind-mounted unix
+# socket, and credential-proxy-forwarder.js pipes bytes into it. Only started
 # when this session actually has a proxy socket.
 #
-# In the default tls transport the harness's proxied_api_domain is pointed at
+# In the default tls transport the backend's proxied_domain is pointed at
 # loopback here and the forwarder terminates TLS for it, so the harness runs
 # with no base-URL override and no placeholder token - it is indistinguishable
 # from a stock install, which is the whole point (see docs/security.md). The hosts
@@ -381,15 +411,15 @@ esac
 if [ -n "${SANDBOX_ANTHROPIC_PROXY_SOCKET:-}" ]; then
     forwarder_port=18300
     # Which name the terminator answers for is the selected harness's, from
-    # `proxied_api_domain` in its manifest - this image is shared by every
-    # harness and must name none of them. Empty here means a harness declared
-    # a credential proxy it gave no endpoint for: the terminator would come up
-    # answering for nothing, the session would reach the real API directly,
-    # and the credential the proxy exists to withhold would be the one in use.
-    proxied_domain="${SANDBOX_HARNESS_PROXIED_DOMAIN:-}"
+    # `proxied_domain` in its manifest - this image is shared by every
+    # backend and must name none of them. Empty here means a proxy socket was
+    # mounted with no endpoint declared for it: the terminator would come up
+    # answering for nothing, the session would reach the real API directly, and
+    # the credential the proxy exists to withhold would be the one in use.
+    proxied_domain="${SANDBOX_BACKEND_PROXIED_DOMAIN:-}"
     if [ -z "$proxied_domain" ]; then
-        echo "FATAL: a credential proxy socket is mounted, but the selected harness" >&2
-        echo "declares no proxied_api_domain for the terminator to stand in front of." >&2
+        echo "FATAL: a credential proxy socket is mounted, but the selected" >&2
+        echo "backend declares no proxied_domain for the terminator." >&2
         echo "Not starting the session - traffic would reach the API unintercepted." >&2
         exit 1
     fi
@@ -438,7 +468,7 @@ if [ -n "${SANDBOX_ANTHROPIC_PROXY_SOCKET:-}" ]; then
         # the single most ordinary variable a corporate environment sets.
         export NODE_EXTRA_CA_CERTS="$tls_dir/cert.pem"
     fi
-    gosu "$SANDBOX_USER" node /usr/local/bin/anthropic-proxy-forwarder.js &
+    gosu "$SANDBOX_USER" node /usr/local/bin/credential-proxy-forwarder.js &
     # Node's own startup (V8 init, module load, then finally binding the
     # listen socket) isn't instant - without this wait, a request that
     # arrives right after this script proceeds (an automated test's
@@ -473,6 +503,7 @@ fi
 # behavior byte-for-byte.
 [ -n "${ANTHROPIC_BASE_URL:-}" ] || unset ANTHROPIC_BASE_URL
 [ -n "${ANTHROPIC_AUTH_TOKEN:-}" ] || unset ANTHROPIC_AUTH_TOKEN
+[ -n "${ANTHROPIC_API_KEY:-}" ] || unset ANTHROPIC_API_KEY
 
 # Unset is the ordinary case (remote access is opt-in) and says nothing.
 # Set-but-unusable is worth a startup line because of how it presents: the

docker/fixed-domains.sh

@@ -51,11 +51,11 @@ fi
 # SaaS name: dns-proxy.sh exempts the extra list from stop-dns-rebind, and
 # init-firewall.sh downgrades a failed lookup there to a warning.
 #
-# Which name this is comes from the harness (proxied_api_domain); the rule
+# Which name this is comes from the provider (proxied_domain); the rule
 # about when to allowlist it is dejima's, and stays here.
 if [ -z "${SANDBOX_ANTHROPIC_PROXY_SOCKET:-}" ] \
-    && [ -n "${SANDBOX_HARNESS_PROXIED_DOMAIN:-}" ]; then
-    FIXED_DOMAINS+=("$SANDBOX_HARNESS_PROXIED_DOMAIN")
+    && [ -n "${SANDBOX_BACKEND_PROXIED_DOMAIN:-}" ]; then
+    FIXED_DOMAINS+=("$SANDBOX_BACKEND_PROXIED_DOMAIN")
 fi
 
 # GitHub itself is allowlisted by IP range (see github-domains ipset,

docker/forge-guard.sh

@@ -28,8 +28,10 @@
 #                        to a forge here.
 #   DEJIMA_FORGE_REPO    the "<owner>/<name>" of the repository the session
 #                        was launched against, and DEJIMA_FORGE_REPO_FLAGS /
-#                        DEJIMA_FORGE_REPO_ENV the spellings this forge's CLI
-#                        accepts for naming a different one.
+#                        DEJIMA_FORGE_REPO_ENV / DEJIMA_FORGE_REPO_PATHS the
+#                        spellings this forge's CLI accepts for naming a
+#                        different one: a flag, an environment variable, and a
+#                        path segment under a named subcommand.
 #   DEJIMA_FORGE_REAL_DIR  where the real CLIs live, behind the shadow.
 set -u
 
@@ -44,7 +46,8 @@ fi
 # Outside a dejima container, or with nothing to do, this is a pass-through.
 if [ -z "${DEJIMA:-}" ] ||
    { [ -z "${DEJIMA_MERGE_BLOCK:-}" ] && [ -z "${DEJIMA_DISCLOSE:-}" ] &&
-     [ -z "${DEJIMA_FORGE_REPO_FLAGS:-}" ] && [ -z "${DEJIMA_FORGE_REPO_ENV:-}" ]; }; then
+     [ -z "${DEJIMA_FORGE_REPO_FLAGS:-}" ] && [ -z "${DEJIMA_FORGE_REPO_ENV:-}" ] &&
+     [ -z "${DEJIMA_FORGE_REPO_PATHS:-}" ]; }; then
     exec "$real" "$@"
 fi
 
@@ -120,7 +123,8 @@ fi
 # Refused rather than skipped when the launch resolved no repository at all: a
 # workspace with no origin has nothing for --repo to legitimately name, and
 # "cannot confirm" is not a reason to let it through.
-if [ -n "${DEJIMA_FORGE_REPO_FLAGS:-}" ] || [ -n "${DEJIMA_FORGE_REPO_ENV:-}" ]; then
+if [ -n "${DEJIMA_FORGE_REPO_FLAGS:-}" ] || [ -n "${DEJIMA_FORGE_REPO_ENV:-}" ] ||
+   [ -n "${DEJIMA_FORGE_REPO_PATHS:-}" ]; then
     refuse_repo() {
         echo "Blocked by dejima's forge guard: this session was launched against ${DEJIMA_FORGE_REPO:-no repository}, and $1 names '$2'. Act on the repository the sandbox mounts." >&2
         exit 1
@@ -154,15 +158,33 @@ if [ -n "${DEJIMA_FORGE_REPO_FLAGS:-}" ] || [ -n "${DEJIMA_FORGE_REPO_ENV:-}" ];
                         ;;
                     "$flag"=*) value="${arg#*=}" ;;
                     *)
-                        # A one-dash flag may carry its value with no
-                        # separator - `-Rowner/name` - which two-dash flags do
-                        # not do.
+                        # One-dash flags only; a two-dash flag carries its
+                        # value with `=` or as the next argument, both above.
                         case "$flag" in
-                            --*) continue ;;
                             -?) ;;
                             *) continue ;;
                         esac
-                        case "$arg" in "$flag"?*) value="${arg#"$flag"}" ;; *) continue ;; esac
+                        # Short flags cluster, so the letter can sit anywhere
+                        # in one: `-Rowner/name`, `-wR owner/name` and
+                        # `-wRowner/name` all name a repository and none of
+                        # them is `-R` as its own argument (#243). Split at the
+                        # letter the way getopt does - what follows it in the
+                        # same argument is the value, and nothing following it
+                        # means the next argument is.
+                        letter="${flag#-}"
+                        # A cluster, not a value that happens to start with a
+                        # dash: one dash, then the letter somewhere in a run of
+                        # letters. Without the second check, `--search foo-R/x`
+                        # style arguments would be mined for flag letters.
+                        case "$arg" in -[!-]*) ;; *) continue ;; esac
+                        rest="${arg#-}"
+                        case "$rest" in *"$letter"*) ;; *) continue ;; esac
+                        case "${rest%%"$letter"*}" in *[!A-Za-z]*) continue ;; esac
+                        value="${rest#*"$letter"}"
+                        if [ -z "$value" ]; then
+                            [ "${#args_left[@]}" -gt 0 ] || continue
+                            value="${args_left[0]}"
+                        fi
                         ;;
                 esac
                 [ -n "$value" ] || continue
@@ -170,6 +192,39 @@ if [ -n "${DEJIMA_FORGE_REPO_FLAGS:-}" ] || [ -n "${DEJIMA_FORGE_REPO_ENV:-}" ];
             done
         done
     fi
+
+    # A repository named in a path rather than in a flag - `gh api
+    # repos/<owner>/<name>/issues` reaches any repository the token does,
+    # without a --repo anywhere in it (#243).
+    #
+    # Only when the declared subcommand is argv's first word. The alternative
+    # is inspecting every positional that contains two slashes, which would
+    # refuse `gh issue create --title repos/a/b` - and a false refusal costs an
+    # honest agent a working command, which is the wrong way for a fast-fail to
+    # be wrong.
+    if [ -n "${DEJIMA_FORGE_REPO_PATHS:-}" ] && [ "$#" -gt 0 ]; then
+        read -ra repo_paths <<< "$DEJIMA_FORGE_REPO_PATHS"
+        for spec in "${repo_paths[@]}"; do
+            [ "$1" = "${spec%%:*}" ] || continue
+            segment="${spec#*:}"
+            for arg in "$@"; do
+                case "$arg" in -*) continue ;; esac
+                # gh substitutes {owner} and {repo} from the checkout, so a
+                # path carrying them names this repository by construction and
+                # comparing the literal braces would refuse it.
+                case "$arg" in *'{'*) continue ;; esac
+                path="${arg#/}"
+                case "$path" in "$segment"/*/*) ;; *) continue ;; esac
+                path="${path#"$segment"/}"
+                owner="${path%%/*}"
+                path="${path#*/}"
+                name="${path%%/*}"
+                [ -n "$owner" ] && [ -n "$name" ] || continue
+                same_repo "$owner/$name" \
+                    || refuse_repo "the path '$arg'" "$owner/$name"
+            done
+        done
+    fi
 fi
 
 # --- the authorship disclosure ---------------------------------------------

docs/configuration.md

@@ -31,14 +31,21 @@ config file behind them.
 | `[core] update_check` | `on` | at startup, say when this checkout is behind the branch it tracks. One `ls-remote` to your own remote, at most hourly, never fetching; `off` makes dejima contact nothing of its own accord. The answer is cached in `~/.local/share/dejima/update-check`, which is safe to delete |
 | `[ui] banner` | `on` | the three-line summary at the top of a launch - project and branch, the selection, and the switches whose state changes what a session can do. `off` prints nothing. Never drawn when output is redirected |
 | `[core] firewall` | `on` | egress firewall; `off` disables it (debugging only), also settable per launch with `--no-firewall` |
-| `[core] share_dir` | `~/.local/share/dejima/shared` | host-visible read/write scratch dir, mounted at `~/shared` |
+| `[core] share_dir` | `~/.local/share/dejima/shared` | host-visible read/write scratch dir. One directory per project underneath it, and only that project's is mounted at `~/shared`. `dejima-share` is the host side of it |
 | `[core] ssh_key` | unset | **deprecated** - the pre-identity spelling of `[identity.default] ssh_key`. Still read when the config has no `[identity.default]`; refused when it has one, since the two say the same thing |
 | `[core] known_hosts` | `~/.ssh/known_hosts` | known-hosts file used for git-over-ssh |
+| `[harness.claude-code] backend` | *(none - must be set)* | which model API this harness talks to, and so which credential the proxy injects. A directory under `backends/`, each shipping its own `[backend.<name>]` keys. Per harness rather than global, because running Claude Code against Anthropic and Cline against something else is the ordinary case. No default, for the reason `[core] harness` has none: one that could change later would move a session to another endpoint without its config changing. Unset, dejima writes `anthropic` into your config once and says so - a migration rather than a default, so nothing it decides later can move you. Also settable per launch with `--backend`. See [providers.md](providers.md#model-backends) |
 | `[harness.claude-code] projects_dir` | `~/.claude/projects` | where Claude Code session transcripts live |
 | `[harness.claude-code] file_history_dir` | `~/.claude/file-history` | Claude Code's edit-undo record, mounted per session rather than whole |
 | `[harness.claude-code] statusline_path` | `~/.claude/statusline.sh` | statusline script path |
-| `[harness.cline] model` | *(none - must be set)* | model id the endpoint serves; no default, because any shipped one goes stale with the next Cline release. Also settable per launch with `--model` |
-| `[harness.cline] base_url` | unset | OpenAI-compatible endpoint. Unset means Anthropic through dejima's credential proxy. Accepts a loopback or RFC 1918 address, or a host you have allowlisted. Also settable per launch with `--base-url` |
+| `[harness.cline] backend` | *(none - must be set)* | as above, and the risk is concrete here: Cline supports many backends and has one of its own. Nothing is written into your config for you either, unlike Claude Code: there is no one endpoint every existing Cline session was already using, so any value dejima recorded would be a guess. Also settable per launch with `--backend` |
+| `[backend.anthropic] credential_file` | `~/.claude/.credentials.json` | the host file this backend's credential is read from, per request. A path, never a secret, and never mounted into the container |
+| `[backend.self-hosted] base_url` | *(none - must be set)* | where you serve the model. A loopback or RFC 1918 address, or a host you have allowlisted - it has to be an endpoint needing no credential, since there is none to withhold. On the backend rather than the harness, so a local endpoint stays configured while a hosted API is selected |
+| `[backend.anthropic-api-key] credential_file` | `~/.claude.json` | where your Anthropic API key is. Defaulted to where Claude Code's console login puts it, so the common case needs nothing set; point it at a file of your own if you hold the key yourself. Read host-side per request and never mounted, and the key is stripped from the copy of `~/.claude.json` dejima stages |
+| `[backend.anthropic-api-key] credential_field` | `primaryApiKey` | which value inside that file is the key, as dot-separated object names. Clear it (`credential_field =`) when the file is nothing but the key |
+| `[backend.<name>] proxy` | *(inherits `[credentials] proxy`)* | whether the credential proxy runs for this backend. Per backend so that one backend the proxy cannot serve is not a reason to stop withholding credentials from the ones it can. Off means this backend's real credential is given to the session, and dejima says so at launch |
+| `[backend.openrouter] credential_file` | *(none - must be set)* | your OpenRouter API key, in a file. Read host-side per request and never mounted; the container only ever holds a placeholder. No default, because a key's location is yours and guessing at one would point dejima at a file it has no reason to think exists |
+| `[harness.cline] model` | *(none - must be set)* | model id the endpoint serves, exactly as that endpoint spells it - a hosted catalogue namespaces by vendor (`z-ai/glm-5.3`) and may qualify a variant (`deepseek/deepseek-r1:free`). No default, because any shipped one goes stale with the next Cline release. Also settable per launch with `--model` |
 | `[harness.cline] context_window` | unset | tokens Cline may use before compacting. Needed for a model it has no catalogue entry for, which is every self-served one. Also settable per launch with `--context-window` |
 | `[harness.cline] state_dir` | `~/.local/share/dejima/cline` | per-project Cline state; one directory per workspace |
 | `[forge.gitea] ssh_host` | unset | Gitea/Forgejo SSH hostname: skip if you only push to GitHub |
@@ -333,7 +340,9 @@ you don't have one.
 
 ### Cline
 
-Almost nothing carries over, and that is the design rather than a gap.
+Your own configuration carries over the same way Claude Code's does - the
+table under [What comes in from your host](#what-comes-in-from-your-host) is
+the list. Your *sessions* do not, and that is the design rather than a gap.
 
 Cline keeps one `sessions.db` indexing every session it has ever run, with
 the project a session belonged to as a field inside the record rather than a
@@ -344,21 +353,33 @@ under `[harness.cline] state_dir` (default `~/.local/share/dejima/cline`),
 mounted at `~/.cline/data` in the container. Sessions persist across runs of
 the same project and are invisible to every other project.
 
-Because that directory is dejima's rather than yours, resuming on the host
-needs `CLINE_DATA_DIR` set to it. The exact command is at the end of every
-session's briefing.
+Because that directory is dejima's rather than yours, resuming on the host is
+not a supported path - see
+[Sessions, and where they live](#sessions-and-where-they-live) below. Relaunch
+dejima on the same project instead, which is what the briefing tells the
+session to offer.
 
-The provider configuration is written fresh by dejima at each launch and is
-not yours either. Two shapes are supported:
+The model configuration is written fresh by dejima at each launch and is not
+yours either. Where the model is comes from `[harness.cline] backend` and
+nowhere else, so there is no second setting for it to disagree with, and two
+shapes are supported:
 
-- **`base_url` unset** - Anthropic, reached through dejima's own credential
-  proxy exactly as Claude Code is. What is written into the container is the
-  placeholder `sandbox-credential-proxy-placeholder`; the real credential
-  stays on the host.
-- **`base_url` set to a model you serve yourself** - either a loopback or
-  RFC 1918 address, or a host you have allowlisted with `dejima-allow`.
+- **A backend the proxy serves** (`anthropic`, `anthropic-api-key`,
+  `openrouter`) - reached through dejima's own credential proxy exactly as
+  Claude Code is. What is written into the container is the placeholder
+  `sandbox-credential-proxy-placeholder` and the endpoint's real hostname; the
+  credential stays on the host. Which of Cline's own provider types dejima
+  writes comes from the backend's `api_style`: its native Anthropic client for
+  one, its OpenAI-compatible client for the other.
+- **A backend with no credential** (`self-hosted`, carrying its own
+  `[backend.self-hosted] base_url`) - a model you serve, at either a loopback
+  or RFC 1918 address or a host you have allowlisted with `dejima-allow`.
   Nothing needs a credential, so there is nothing to withhold.
 
+Keeping the address on the backend rather than on the harness is what lets you
+have a local model and a hosted API both configured and switch between them by
+changing one word.
+
 A name qualifies through the allowlist rather than through how it is spelled,
 because that is the same store deciding whether the container can reach the
 endpoint at all: one that fails the check is one the session could not have
@@ -366,13 +387,13 @@ connected to anyway. A model server on your own network normally has a name,
 so requiring a literal address would have made this path unusable for the
 ordinary case.
 
-Anything else is refused at launch - a hosted provider's API key would have to
-go inside the container, and dejima has no proxy that could hold one back on
-its behalf. Note what the check is *not* doing: dejima writes a placeholder
-into the container on this path whatever the endpoint is, so no real
-credential enters it either way. What the check decides is whether the
-configuration can work at all, which is worth saying at launch rather than as
-an auth error three layers down. See
+Anything else is refused at launch - a hosted API pointed at through a
+no-credential backend would want its key inside the container, and dejima has
+no proxy that could hold one back on its behalf. Note what the check is *not*
+doing: dejima writes a placeholder into the container on the proxied path
+whatever the endpoint is, so no real credential enters it either way. What the
+check decides is whether the configuration can work at all, which is worth
+saying at launch rather than as an auth error three layers down. See
 [development.md](development.md#worked-example-cline).
 
 If the endpoint serves a model Cline has no catalogue entry for - which is every
@@ -408,6 +429,96 @@ editing the base `Dockerfile`: a dependency added that way is declared,
 approved and layered like any other, and it survives a rebuild. Editing the
 Dockerfile directly puts it outside that record.
 
+
+#### Sessions, and where they live
+
+This project's Cline state - sessions, transcripts, tasks - is kept on the host
+in `~/.local/share/dejima/cline/<project>` and mounted at `~/.cline/data`. It
+survives the container being replaced, so **launching dejima again on the same
+project picks up where the last session left off.**
+
+A directory per project rather than one shared: Cline indexes every session it
+has ever run in a single database, so sharing one would put every project's
+history in every project's context - the same boundary `~/.claude/projects`
+gets, for the same reason.
+
+**Cline sessions are not importable or exportable.** A session started by
+running `cline` on your own machine is in `~/.cline/data` and is not visible
+inside dejima; a session started inside dejima is in the per-project directory
+and is not offered back to a host-side Cline. There is no import, no export,
+and no merge - see
+[#301](https://gitbox.branderson.io/dejima/dejima/issues/301) for why that was
+looked at and not built.
+
+The session briefing tells a Cline agent this, so it will not offer to hand
+you a session to resume outside the sandbox. Claude Code can be resumed on the
+host and its briefing says so; the claim lives in each harness's own briefing
+fragment rather than in the shared preamble, because only one of them can make
+it.
+
+#### What comes in from your host
+
+The same shape as Claude Code's, and for the same reason: your own
+configuration should reach a session, and nothing the session writes should
+reach your machine.
+
+| Host path | How it arrives | Why |
+| --- | --- | --- |
+| `~/.agents/skills/` | read-only mount | skills are instructions the agent follows |
+| `~/.agents/hooks/`, `~/.cline/hooks/` | read-only mount | hooks are programs cline runs |
+| `~/.agents/AGENTS.md` | read-only copy | instructions; a copy also survives it being a symlink into a dotfiles checkout |
+| `~/.agents/rules/*.md`, `*.txt` | read-only copy, into `Documents/Cline/Rules/` | see below |
+| `~/Documents/Cline/Rules/*.md`, `*.txt` | read-only copy | the location cline actually reads |
+| `~/.cline/settings.json`, `~/.cline/cline_mcp_settings.json` | writable copy, discarded | cline rewrites both as it runs |
+| `~/.cline/data/` | this project's own state directory | see above |
+
+Read-only is the point rather than caution. A session that could rewrite a
+hook, a skill or an MCP server definition would be choosing what happens on
+**your** machine the next time you start cline outside a container - which is
+persistence for a prompt injection, in files nobody re-reads before the next
+run. The two settings files are copies rather than read-only mounts because
+cline rewrites them itself; the copy is discarded with the container.
+
+The read-only directories are scanned for symlinks, so a `skills/` that is a
+link into a dotfiles checkout brings its target too. dejima refuses a target
+that overlaps one of its own guarded stores.
+
+**Global rules come from two places and land in one.** cline loads them from
+`~/Documents/Cline/Rules` and nowhere else - `~/.agents/rules` reads like the
+obvious companion to `~/.agents/skills` and is not loaded, which you can see
+by planting a file in each and opening `cline config`. So dejima copies the
+files from *both* host locations into the one directory cline reads, rather
+than mounting `~/.agents/rules` where nothing would look at it.
+
+They are copied file by file rather than mounted as a directory, because
+dejima writes its own briefing into that same directory and a read-only mount
+over it would leave nowhere to put it.
+
+Two collisions have fixed answers. A name present in **both** host locations
+is taken from `Documents/Cline/Rules`, since that is cline's own location for
+rules and where it writes when you edit them through cline. A host file named
+`00-dejima.md` is skipped: that is the briefing's name, and dejima's wins.
+## What dejima says before it starts
+
+Some launches print a notice first: an environment variable that is no longer
+read, a deprecated key, a guard that is not registered, a line dejima wrote
+into your config. Everything after that is the image build, which on a cold
+cache is thousands of lines - so when a notice was printed, dejima waits for
+Enter before starting it.
+
+The wait happens only when there was something to read, and only when a
+terminal is attached. An unattended launch never blocks on it.
+
+`--no-pause` skips the wait and still prints the notice. It is for starting
+several sessions at once - a tmuxinator layout, a script - where every one of
+them has a terminal and none of them wants a keypress. It is a flag rather
+than a config key on purpose: it describes the terminal in front of one
+launch, not a standing preference.
+
+A long list of entries left in the shared directory is sampled rather than
+printed whole, for the same reason: it is a standing condition you clear once,
+and it should not push the things about this run off the screen.
+
 ## Identities
 
 **Several accounts on one machine, and none of them yours.** An
@@ -662,11 +773,32 @@ pick up from somewhere else, run dejima inside tmux and use
 
 ## Shared scratch space
 
-`~/shared` is a read-write bind mount of `[core] share_dir` (default
-`~/.local/share/dejima/shared`, created automatically) - separate
-from the project mount, for passing files (screenshots, temp scripts) in and
-out of a session without touching the actual checkout. Persists across
-sessions since it's a real directory, not a container volume.
+`~/shared` is a read-write bind mount of one project's directory under
+`[core] share_dir` (default `~/.local/share/dejima/shared`, created
+automatically) - separate from the project mount, for passing files
+(screenshots, temp scripts) in and out of a session without touching the actual
+checkout. Persists across sessions since it's a real directory, not a container
+volume.
+
+**One directory per project, not one for the host.** A launch mounts
+`<share_dir>/projects/<slug>` at `~/shared`, where the slug is the project's
+absolute path with every non-alphanumeric character replaced by a dash - the
+same key the audit and epitaph stores use. So a session sees its own project's
+handoff files and no other project's, and nothing an agent has been told
+changes, because inside the container the path is still `~/shared`.
+
+`dejima-share` is the host side of that:
+
+```sh
+dejima-share path            # the host directory for this project, created if new
+dejima-share path ~/code/x   # …for another project
+dejima-share list            # every project's share, with size and last write
+dejima-share adopt           # move files left loose in share_dir into this project's
+```
+
+**To hand a file *to* a session,** put it in `dejima-share path` before
+launching. That is what makes the inbound direction work without a mount that
+every project can read.
 
 Treat it as a handoff point, not as general-purpose storage. If your own
 project instructions tell agents to write somewhere at a fixed host path -
@@ -680,10 +812,20 @@ being rewritten to point at `~/shared`.
 only writable host paths in the container. Everything else a session writes
 goes away with it.
 
-**Clear it out periodically.** It persists across sessions by design, which
-means anything you left in it is readable by every session after the one you
-left it for. A credential dropped in there to get one job done, and then
-forgotten, is a credential you have handed to every session since.
+**Clear it out periodically.** The per-project split bounds which sessions can
+read what you left, and bounds nothing about how long. A project's share
+persists by design, so anything in it is readable by every future session
+against that project: a credential dropped in there to get one job done, and
+then forgotten, is a credential you have handed to every session against that
+project since. Nothing prunes `share_dir` - `dejima-share list` prints each
+project's size and the date of its last write, and deleting is yours.
+
+**Files from before the split.** `share_dir` used to be mounted whole, so
+anything at its top level was visible to every session. Those files are still
+there and are now mounted into nothing; dejima says so at every launch while
+that is true, rather than moving an operator's files on its own.
+`dejima-share adopt <project>` moves them into one project's share after
+showing what it will move and asking, and it never overwrites.
 
 ## Reading what a session left behind
 
@@ -782,14 +924,21 @@ session can run.
 
 ### The session briefing
 
-A `SessionStart` hook (`~/.claude/hooks/sandbox-context.sh`) injects a
-reminder when `DEJIMA` is set: the session is running in a
-disposable, firewalled container and should stay within the task at hand -
-if something genuinely needs to break out (broader network, host changes,
-GUI/hardware), stop and ask rather than trying to work around the firewall,
-since the same session can be resumed unrestricted on the host via
-`claude --resume`. No-op outside the container. `deny-dangerous-bash.sh`
-(`PreToolUse`) also applies here, since `~/.claude/hooks` is mounted in.
+Every session is told where it is running: a disposable, firewalled container
+it should stay within, and if something genuinely needs to break out - broader
+network, host changes, GUI/hardware - it should stop and ask rather than work
+around the firewall. Whether the session can be resumed unrestricted on the
+host afterwards is the harness's own answer, and each harness's briefing
+fragment gives it: Claude Code's names `claude --resume`, Cline's says plainly
+that its sessions do not leave the sandbox.
+
+*How* the briefing reaches a session is per harness too, because they do not
+agree on a mechanism. Claude Code takes it as a system prompt through the flag
+its manifest names; Cline takes no such flag and registers no hook, so
+`entrypoint.sh` renders it into a file the harness reads, root-owned and
+read-only. A harness doing neither gets it through a `SessionStart` hook. What
+the briefing *says* is none of theirs - one script composes it for all three
+routes. See [development.md](development.md).
 
 When GitHub is a push destination this session - `--allow-github-push`, or
 `forge = github` under a pushing workflow - the briefing also tells the

docs/development.md

@@ -64,8 +64,10 @@ top-level entries like `statusline.sh`) to resolve, and runs
 `docker compose run`. `bin/dejima-allow`
 adds a domain to a running session's firewall from the host - see
 [Adding a domain to a running session](security.md#adding-a-domain-to-a-running-session).
-`install.sh` installs the hooks into
-`~/.claude/hooks` and registers them in `~/.claude/settings.json`.
+`install.sh` writes nothing to `~/.claude`. Every hook dejima uses is baked
+into the image at `/usr/local/lib/dejima/hooks` and registered per launch into
+the `--settings` overlay, which Claude Code merges with your
+`~/.claude/settings.json` rather than replacing it.
 
 ## Tests
 
@@ -151,11 +153,23 @@ attached: read what `gitea-pr` printed.
 ### Running the tests
 
 ```sh
-bats test/               # everything
-bats test/audit.bats     # one suite - the suites are independent, see .dejima.md
+bash test/run-confined.sh             # every confined suite - the pull-request gate
+bash test/run-confined.sh --changed   # only the suites your diff calls for
+bats test/audit.bats                  # one suite - the suites are independent
 SKIP_BUILD=1 bats test/runtime.bats   # the one suite needing Docker; reuse the current image
 ```
 
+`test/run-confined.sh` runs the files concurrently and, within each file, the
+tests too, via bats' own `--jobs`. Adding `--jobs $(nproc)
+--no-parallelize-across-files` to a bare `bats` invocation gets the same effect
+for a single suite; both halves of that are needed, because bats otherwise
+requires GNU parallel for `--jobs` and only the across-files half actually does.
+
+`--changed` is for iterating. It maps the diff to suites through `suites_for()`
+in that script, prints which lane it ran, and says plainly that it is not the
+gate - a change is tested when the whole set has run, not when the selected
+subset has.
+
 `runtime.bats` is the only suite that needs a Docker daemon: it is the one
 that builds the image and boots real containers to assert against.
 Everything else, `audit.bats`, `ci-runner.bats`, `config.bats`,
@@ -189,10 +203,12 @@ it has to argue about.
 
 ### What a harness must be able to do
 
-Support is per harness and deliberate. A supported harness gets the same
-depth of integration Claude Code has - the same mounts, the same guards, the
-same audit surfaces - so a harness is not a manifest someone drops in. That
-is only possible if the harness can host what those protections need.
+Support is per harness and deliberate. A supported harness gets everything
+dejima has to give: its state scoped per project, its config carried in
+read-only, its audit surfaces watched, and its guards installed wherever it
+can host one. So a harness is not a manifest someone drops in - and where it
+cannot host a protection, the launch says so rather than leaving the gap
+unnamed.
 
 These are the requirements. A harness that fails one of the first four cannot
 be supported, and that is a decision about the harness rather than a gap in
@@ -342,20 +358,22 @@ that command lives in the harness's briefing fragment rather than in
 `resume_command`: briefing substitution is one pass, so a placeholder inside
 a substituted value is never resolved.
 
-*Provider-agnostic is not the same as endpoint-agnostic.* Cline can be pointed
-anywhere; dejima cannot follow it everywhere. With `base_url` unset it runs
-against Anthropic through dejima's own credential proxy and the key never
-enters the container. Pointed at someone else's hosted API there is no proxy
-that could hold a key back, so the key would have to go in - which is R5
-failing, not a network restriction. The plugin therefore accepts `base_url`
-only for a model the operator serves themselves - a loopback or RFC 1918
-address, or a host they have allowlisted - where an open-weight model needs no
-credential at all and R5 has nothing to protect. The allowlist is what
-qualifies a name, because it is the same store deciding what the container can
-reach: an endpoint failing the check is one the session could not have
-connected to anyway, and a model server on someone's own network normally has
-a name rather than a literal address. A provider-generic proxy would widen
-this to hosted providers; nobody has written one (#171).
+*Backend-agnostic is not the same as endpoint-agnostic.* Cline can be pointed
+anywhere; dejima cannot follow it everywhere. A backend the proxy serves is
+fine whatever its dialect - the proxy takes the credential's kind and header
+names as arguments, so `openrouter` works the way `anthropic` does and the key
+never enters the container either way. What dejima cannot follow is a hosted
+API reached *without* a backend: there is no proxy holding a key back on its
+behalf, so the key would have to go in, which is R5 failing rather than a
+network restriction.
+
+So the `credential = none` path is only accepted for a model the operator
+serves themselves - a loopback or RFC 1918 address, or a host they have
+allowlisted - where the endpoint needs no credential at all and R5 has nothing
+to protect. The allowlist is what qualifies a name, because it is the same
+store deciding what the container can reach: an endpoint failing the check is
+one the session could not have connected to anyway, and a model server on
+someone's own network normally has a name rather than a literal address.
 
 *Conversation logging works; epitaphs do not, and only one of those is
 Cline's fault.* Cline's transcripts are
@@ -487,9 +505,9 @@ harness-specific path resolving to nothing is the honest answer.
 | Seeded files | that a harness reading a credential from a fixed path needs something at it, since an absent file and an empty one are not reliably the same to it. The manifest's `image_files`, created empty and 0600 in that harness's layer, where a mounted credential shadows it - rather than by `entrypoint.sh`, which runs in every image including the base one alone | `harnesses/<name>/harness.conf` |
 | Image environment | anything the harness wants set for every session of its own - for Claude Code, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`. The manifest's `image_env`, in the same layer | `harnesses/<name>/harness.conf` |
 | Command | there is no default anywhere shared. `SANDBOX_CMD` comes from the manifest's `command` via `bin/dejima`, and `entrypoint.sh` refuses an empty one rather than naming a harness a given image may not contain | `harnesses/<name>/harness.conf`, `docker/entrypoint.sh` |
-| Proxied endpoint | which name the in-container TLS terminator answers for, and what `/etc/hosts` pins to loopback. The manifest's `proxied_api_domain`; a credential proxy with no domain declared is refused rather than started answering for nothing | `harnesses/<name>/harness.conf`, `docker/entrypoint.sh` |
-| Egress allowlist | `platform.claude.com` always, `api.anthropic.com` only when no credential proxy is in front of it. `api_domains` and `proxied_api_domain` in the manifest | `harnesses/<name>/harness.conf` |
-| Credentials | the whole proxy exists because Claude Code authenticates from `~/.claude/.credentials.json` rather than an env var; the entrypoint seeds a well-formed fake so it has something to read | `bin/dejima-anthropic-proxy`, `docker/anthropic-proxy-forwarder.js`, `docker/entrypoint.sh` |
+| Proxied endpoint | which name the in-container TLS terminator answers for, and what `/etc/hosts` pins to loopback. The BACKEND's `proxied_domain`, not the harness's: a harness reaches whichever endpoint it is configured for, so the name belongs to the endpoint. A proxied backend with no domain declared is refused rather than started answering for nothing | `backends/<name>/backend.conf`, `docker/entrypoint.sh` |
+| Egress allowlist | `platform.claude.com` always, `api.anthropic.com` only when no credential proxy is in front of it. `api_domains` on the harness, `proxied_domain` on the backend | `harnesses/<name>/harness.conf`, `backends/<name>/backend.conf` |
+| Credentials | which substitute the harness accepts, and where it reads it from: a well-formed fake `~/.claude/.credentials.json` the entrypoint seeds for Claude Code, a placeholder key in `settings/providers.json` for Cline, a placeholder in an environment variable on the API-key path. The proxy itself is neither harness's - what the credential is, which header carries it and whether it refreshes are the backend's, passed as arguments | `bin/dejima-credential-proxy`, `docker/credential-proxy-forwarder.js`, `docker/entrypoint.sh` |
 | Hook protocol | the event payload arrives on stdin; `SessionStart` returns `hookSpecificOutput.hookEventName`/`additionalContext` as JSON, while a `PreToolUse` hook blocks by exiting 2 with its reason on stderr | `hooks/*.sh` |
 | Hook registration | four hooks written into `~/.claude/settings.json` in Claude Code's schema, one `SessionStart` with a `startup\|resume\|clear\|compact` matcher and three `PreToolUse` matching `Bash`. In the plugin, gated per declared guard | `bin/harness/claude-code.sh` |
 | Briefing delivery | **by which of three routes**, not whether. Claude Code takes the briefing as a system prompt, through the flag its manifest names in `briefing_args`, because a `SessionStart` payload past roughly nine kilobytes is persisted and replaced with a preview - so the hook route silently under-delivered a briefing carrying a project's `.dejima.md`. Cline takes no such flag and registers no hook, so it declares a `briefing_path` and reads a file `entrypoint.sh` writes root-owned and read-only. A harness doing neither still gets it through the hook. What the briefing *says* is none of theirs: composing it host-side is core's, and the container-side part - this container's id, the declared-versus-installed gap, the project's `.dejima.md` - is one script every route calls | `hooks/dejima-briefing-render.sh`, `hooks/sandbox-context.sh`, `docker/entrypoint.sh` |
@@ -539,13 +557,19 @@ because absent is visible to the operator and broken is not.
 `claude-code` is no exception to that: it is declared by its own manifest and
 built into its own layer like any other. The base image carries nothing of any
 harness's - not its package, not the directories it keeps state in, not its
-environment, and not its name as a default command. What is left on the
-harness axis is the credential proxy, which is Claude Code's shape throughout
-and is the R5 row above.
+environment, and not its name as a default command.
+
+The credential proxy is no longer on that list either. Which header carries
+the credential, what shape it takes, what must not travel beside it and
+whether it can be refreshed are all arguments the selected backend supplies,
+so a second harness reaches a proxied backend without a branch of its own -
+which is the R5 row above, and is confirmed rather than argued: Cline runs a
+real completion through the same terminator and the same host-side proxy.
 
 `providers.bats` covers the manifest contract itself and is where a new
-`harness.conf` gets its parsing and validation tests. The suites that assert
-on Claude Code paths by name - `config.bats`, `audit.bats`, `static.bats`,
-`runtime.bats` - are the ones that will need a second set, and a green run
-against the existing harness proves nothing about a new one. Nothing in
-`test/` currently runs a second harness end to end.
+`harness.conf` gets its parsing and validation tests. `config.bats`,
+`static.bats`, `project.bats` and `conversation.bats` each carry a second
+harness's cases beside Claude Code's, which is the shape a third one should
+follow. What is still missing is the end of the ladder: `runtime.bats` boots
+only `claude-code`, so nothing in `test/` runs a second harness end to end in
+a real container, and a green confined run says nothing about that.

docs/nginx-dejima.conf.example

@@ -25,9 +25,15 @@
 #   2. Authentication. ttyd is started with no credential of its own (see
 #      bin/dejima-ttyd), because it is bound to 127.0.0.1 where only this
 #      host can reach it - this proxy is the only gate in front of it. A
-#      vhost without auth_basic (or something stronger in its place) is an
-#      unauthenticated host shell on your LAN. Put every listen behind it:
-#      a second server block without auth is the same open door.
+#      vhost that authenticates nothing is an unauthenticated host shell on
+#      your LAN. Put every listen behind it: a second server block without
+#      auth is the same open door.
+#
+#      This file uses HTTP Basic because it is the shortest thing to show.
+#      One shared credential, no per-operator identity, no second factor,
+#      revocation by editing htpasswd. docs/remote-access.md, under
+#      "Authenticating the front door", is what that costs and what else
+#      meets the requirement.
 #
 #      Authentication alone does not stop a page in your browser from
 #      opening a WebSocket to this vhost and having the browser attach your

docs/providers.md

@@ -3,16 +3,20 @@
 [← dejima README](../README.md)
 
 dejima's forge (Gitea/Forgejo/...), workflow (worktree-and-PR, or something
-else) and harness (Claude Code, or another agent CLI) behaviour are not
-hardcoded into core. Each is a directory under `forges/`, `workflows/` or
-`harnesses/`, selected by `[core] forge`, `[core] workflow` and
-`[core] harness` in `~/.config/dejima/config`. Shipped today:
+else), harness (Claude Code, or another agent CLI) and model backend
+(Anthropic, OpenRouter, something you serve) behaviour are not hardcoded into
+core. Each is a directory under `forges/`, `workflows/`, `harnesses/` or
+`backends/`. Shipped today:
 
 | Axis | Directory | Selector | Ships |
 | --- | --- | --- | --- |
 | forge | `forges/` | `[core] forge` | `forges/gitea`, `forges/github`, `forges/none` |
 | workflow | `workflows/` | `[core] workflow` | `workflows/worktree-pr`, `workflows/branch-push`, `workflows/local-only` |
-| harness | `harnesses/` | `[core] harness` | `harnesses/claude-code` |
+| harness | `harnesses/` | `[core] harness` | `harnesses/claude-code`, `harnesses/cline` |
+| backend | `backends/` | `[harness.<name>] backend` | `backends/anthropic`, `backends/anthropic-api-key`, `backends/openrouter`, `backends/self-hosted` |
+
+The backend is selected per harness rather than in `[core]`, because it is the
+harness that talks to a model API - see [Model backends](#model-backends).
 
 See [Shipped providers](#shipped-providers) below for what each one is for.
 
@@ -44,7 +48,7 @@ elsewhere needs to change.
 ## The manifest file
 
 Each provider directory has exactly one manifest file, named for its axis:
-`forge.conf`, `workflow.conf`, `harness.conf`. Format is the same
+`forge.conf`, `workflow.conf`, `harness.conf`, `backend.conf`. Format is the same
 `key = value` shape as the main config file:
 
 - One `key = value` pair per line; surrounding whitespace is trimmed.
@@ -76,6 +80,7 @@ value never does:
 | `export` | `NAME=key` or `NAME=@key` for the `env_export` forge key - see [Forge](#forge) below. |
 | `template` | Prose that may contain `{{placeholder}}` markers; the placeholder names are checked against the briefing whitelist at composition time, not here. |
 | `keyspec` | One element of a `keys` list - see [The `keys` field](#the-keys-field-a-providers-own-config-schema) below. |
+| `repopath` | `<subcommand>:<first path segment>` for the `repo_paths` forge key - where a repository appears in a path rather than behind a flag. |
 | `list:TYPE` | Space-separated (not colon-separated, unlike a config-file list) elements, each checked against `TYPE`. |
 
 A leading `?` on any type (`?hostname`, `?list:identifier`, ...) makes the
@@ -123,9 +128,10 @@ operator can set, resolved the same way as any other config key
 | `pr_command` | `?command` | (empty) | The PR-management command name the forge's briefing prose and `env_export`/`merge_block` refer to. |
 | `issue_command` | `?command` | (empty) | The issue-management command name, same idea. |
 | `merge_block` | `?command` | (empty) | The command prefix refused inside the sandbox - only when the workflow's `block_merge = on`. Enforced by `docker/forge-guard.sh`, which shadows the named CLI on PATH and compares argv, so it holds for a harness that cannot intercept a tool call; `hooks/merge-guard.sh` applies the same rule to a command string, for the harnesses that can. Matched as a run of consecutive non-flag arguments, so a flag before the subcommand does not slip past it. |
-| `repo_flags` | `?list:flag` | (empty) | The option names this forge's CLI accepts for naming a repository other than the one the session was launched against - `--repo -R` for `gh`. `docker/forge-guard.sh` refuses a value that is not that repository, in every spelling (`--repo x`, `--repo=x`, and a one-dash flag with its value attached). Fast-fail, not a boundary, for the same reason `merge_block` is not one: the session holds the token. Leave it empty for a CLI that resolves the repo itself and refuses another host, as the gitea ones do - a forge is not required to be aimable. |
+| `repo_flags` | `?list:flag` | (empty) | The option names this forge's CLI accepts for naming a repository other than the one the session was launched against - `--repo -R` for `gh`. `docker/forge-guard.sh` refuses a value that is not that repository, in every spelling of the flag itself: `--repo x`, `--repo=x`, `-R x`, `-Rx`, and the letter inside a short-flag cluster (`-wR x`, `-wRx`). Fast-fail, not a boundary, for the same reason `merge_block` is not one: the session holds the token. Leave it empty for a CLI that resolves the repo itself and refuses another host, as the gitea ones do - a forge is not required to be aimable. |
 | `identity_keys` | `?list:identifier` | (empty) | Which of this forge's own `keys` name an **account** rather than the forge itself - the credential paths, which differ per session, where an API URL does not. One declaration, two rules: a key named here is one an `[identity.<name>]` section may set, and one a project may not declare in its own `.dejima/`. Core keeps no list of its own, so a forge whose credential is spelled differently needs no change here. The identity inherits the type from this forge's `keys` entry, not a second copy of it. |
 | `repo_env` | `?identifier` | (empty) | The environment variable this forge's CLI reads for the same thing - `GH_REPO`. Declared separately because it takes no argument and would otherwise be the way around every flag above. |
+| `repo_paths` | `?list:repopath` | (empty) | A repository this forge's CLI names in a path rather than in a flag, as `<subcommand>:<first segment>` - `api:repos` for `gh api repos/<owner>/<name>/...`. Scoped to a subcommand on purpose: comparing every positional argument that contains two slashes would refuse an issue title that happens to look like one, and a false refusal costs an honest agent a working command. Paths carrying `gh`'s own `{owner}`/`{repo}` placeholders are left alone, since those resolve to this repository by construction. |
 | `disclose` | `?disclosures` | (empty) | Which of this forge's commands send a body the session authored, as comma-separated `kind:command prefix` entries - `pr:gh pr create, issue:gh issue create, ...`. `docker/forge-guard.sh` prepends a marker to the body of a matching command, so a PR, issue or comment an agent wrote says so. The three kinds are `pr`, `issue` and `comment`; the wording of each marker is core's, not the manifest's, so that dejima says one thing about agent authorship whichever forge is selected. Unlike `merge_block` this does not depend on the workflow: what a workflow permits is a policy, who wrote the text is a fact. |
 | `keys` | `?list:keyspec` | (empty) | This forge's own `[forge.<name>]` config schema - see above. |
 | `requires` | `?list:identifier` | (empty) | Which of this forge's own config keys an operator is expected to set for it to actually work - checked at launch by two refusal rules (partly-configured, and none-configured-with-a-fixed-host) when the workflow pushes; see [Validation](#validation). A key with a non-empty schema default never counts as missing for either check. |
@@ -226,10 +232,10 @@ A workflow's `briefing.md` is plain Markdown plus two marker forms that
 | `command` | `identifier` | `claude` | The container's main process for this harness, and the name the wrapper shadows on `PATH`. `[core] command` defaults to it. |
 | `command_path` | `?path` | (empty) | Where the real binary lives, behind the shadow. |
 | `api_domains` | `?list:hostname` | (empty) | Hostnames this harness's own machinery must reach - its update host, its telemetry endpoint. They join the *fixed* allowlist rather than the extra one, which `dns-proxy.sh` exempts from stop-dns-rebind and `init-firewall.sh` treats as non-fatal when it fails to resolve. |
-| `proxied_api_domain` | `?hostname` | (empty) | The model API endpoint the credential proxy stands in front of. Allowlisted **only when the proxy is off**: with it on, the session reaches the API through the forwarder, so leaving the name unresolvable defeats a bypass that looks it up by DNS. Which name it is comes from here; when to allowlist it is dejima's rule. |
+| `api_styles` | `?list:identifier` | (empty) | Which backend `api_style`s this harness has a client for. `claude-code` speaks `anthropic`; `cline` speaks both, which is what makes it the backend-agnostic one. Empty means unchecked. |
 | `guards` | `?list:identifier` | (empty) | Which of dejima's guard rails this harness can host: `bash-deny`, `push-guard`, `merge-guard`, `notify`. A name outside that set is refused rather than treated as an unknown guard, since a typo would otherwise turn a guard off silently. The ones a harness does not declare are named at launch - see "What a harness must be able to do" in [development.md](development.md). |
 | `briefing_args` | `?args` | (empty) | The flag that carries the briefing to a harness taking it on the command line - for Claude Code, `--append-system-prompt`. `dejima-harness-wrapper` reads the rendered briefing and passes it as a single value, so every invocation carries it and not only the entrypoint's. Set, the session-start hook stops carrying the briefing and reduces to the session id, which is the one thing that does not exist until the harness starts. |
-| `briefing_path` | `?homepath` | (empty) | Where this harness reads its briefing from, relative to `$HOME`, for a harness that has no session-start hook to be handed it through. Set, `entrypoint.sh` renders the briefing into that path root-owned and read-only before the session starts, and refuses to start it at all if that fails. Empty for a harness that registers a hook instead, which is how Claude Code gets it. |
+| `briefing_path` | `?homepath` | (empty) | Where this harness reads its briefing from, relative to `$HOME`, for a harness that has no session-start hook to be handed it through. Set, `entrypoint.sh` renders the briefing into that path root-owned and read-only before the session starts, and refuses to start it at all if that fails. Empty for a harness that takes the briefing on the command line (`briefing_args`, which is how Claude Code gets it) or that can be handed it through a session-start hook. |
 | `no_confirm_args` | `?template` | (empty) | The flags that make the harness run without confirming each tool call. Required in practice: dejima refuses to launch a harness that names none, because unattended operation is the premise the container is built on (R1 in [development.md](development.md)). |
 | `settings_args` | `?template` | (empty) | How this harness is told to read dejima's own settings layer, mounted at `/etc/dejima-settings.json`. Empty for a harness that takes its overrides some other way. |
 | `keys` | `?list:keyspec` | (empty) | This harness's own `[harness.<name>]` config schema - same grammar as a forge's `keys`. |
@@ -260,6 +266,74 @@ resuming the session on the host is `claude --resume <session id>`, with
 `{{session_id}}` filled in at composition time; and its briefing fragment is
 `briefing.md`.
 
+## Model backends
+
+`backends/<name>/backend.conf`. Which model API a session talks to, and how the
+credential proxy presents the credential to it.
+
+**"Backend" and not "provider",** which is what the industry usually calls a
+model API. This document already calls forge, workflow and harness "provider
+axes", and one word for both reads as one thing. A harness keeps its own
+vocabulary: `cline` writes a `providers.json` with a `lastUsedProvider` key,
+and `bin/harness/cline.sh` translates.
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `upstream` | `?url` | (empty) | Where the proxy forwards to. Required unless `credential` is `none`, which runs no proxy. |
+| `api_style` | `enum:anthropic\|openai` | (required) | Which dialect the endpoint speaks. A property of the API rather than of any harness: Anthropic's Messages API and an OpenAI-compatible one are different wire formats. A harness declares which it can speak in `api_styles`, and a launch pairing the two wrongly is refused rather than sending well-formed requests in a shape the endpoint cannot parse. |
+| `proxied_domain` | `?hostname` | (empty) | The name the in-container TLS terminator answers for, and what `/etc/hosts` pins to loopback. Required unless `credential` is `none`. On this axis rather than the harness's: a harness reaches whichever endpoint it is configured for, so the name belongs to the endpoint. Declared on the harness, the terminator would answer for one API while the session talked to another, and the credential the proxy exists to withhold would be the one in use. |
+| `credential` | `enum:static\|anthropic-oauth\|none` | (required) | Whether there is a credential, and whether it expires. `static` is read and sent; `anthropic-oauth` is refreshed against `oauth_endpoint` and the rotated token written back to the host file, which is what keeps a host-side login working rather than being signed out by a sandbox run; `none` is a model you serve, with nothing to withhold and so no proxy at all. |
+| `auth_header` | `identifier` | `Authorization` | Which header carries it. |
+| `auth_format` | `authformat` | `Bearer {token}` | How it is written. Must contain `{token}`, so a backend wanting a bare key or a prefix of its own needs no code; a format without it produces a proxy that starts, answers, and sends every request unauthenticated. |
+| `strip_headers` | `?list:identifier` | (empty) | Headers that must not travel beside the injected one. `x-api-key` next to an `Authorization` is two answers to the same question, and which one an API prefers is not dejima's to guess. The auth header is never stripped from under itself. |
+| `ensure_headers` | `?list:headerpair` | (empty) | `NAME=VALUE` that has to appear in a comma-list header, merged into whatever the client sent and left alone when already present. Anthropic's OAuth beta is the one shipped example. |
+| `oauth_endpoint` | `?url` | (empty) | Required by the `anthropic-oauth` kind, meaningless to `static`. |
+| `oauth_client_id` | `?identifier` | (empty) | Same. |
+| `keys` | `?list:keyspec` | (empty) | This backend's own `[backend.<name>]` config schema, exactly as a forge's works. A backend with a credential is expected to declare `credential_file`. |
+| `requires` | `?list:identifier` | (empty) | Which of those must be set for a launch to proceed. |
+
+### What pairs with what
+
+Compatibility is not a list anyone maintains: it is the backend's `api_style`
+against the harness's `api_styles`, checked at launch. This table is what those
+declarations currently work out to.
+
+| Backend | `claude-code` | `cline` | Credential | You configure |
+| --- | --- | --- | --- | --- |
+| `anthropic` | yes | yes | OAuth, refreshed and written back | nothing, once you have logged in on the host |
+| `anthropic-api-key` | yes | yes | a static key, held on the host | nothing, if Claude Code signed you in; otherwise `[backend.anthropic-api-key] credential_file` |
+| `openrouter` | no | yes | a static key, held on the host | `[backend.openrouter] credential_file` |
+| `self-hosted` | no | yes | none, and so no proxy at all | `[backend.self-hosted] base_url` |
+
+`claude-code` speaks Anthropic's Messages API and nothing else, so the two
+OpenAI-compatible backends are refused with it - at launch, naming both sides,
+rather than by sending well-formed requests in a shape the endpoint cannot
+parse. `cline` has a client for each dialect, which is what makes it the
+backend-agnostic one.
+
+Adding a backend does not change this table by hand: a new directory whose
+`api_style` is one a harness already declares works with that harness the day
+it lands.
+
+**Which backend a launch uses is the harness's setting**, `[harness.<name>]
+backend`, overridable for one launch with `--backend`. Per harness because
+that is how it is used: one harness against Anthropic and another against
+something else, on the same machine.
+
+No harness ships a default for it, for the reason `[core] harness` has none. A
+harness may instead declare `assumed_backend`: what it was talking to before
+the key existed, which dejima writes into the operator's config the first time
+it finds the key unset, and says so. That is a migration rather than a default
+- recorded once in the operator's own file, so a later change to dejima cannot
+move a session whose config never changed. A harness only states it where the
+value is not a guess; one whose past endpoint depended on other settings
+declares nothing, and an unset backend is then a refusal.
+
+**Nothing here is a secret.** A backend declares *where* its credential is
+read from - `credential_file` is a path - never what it is. The file it names
+is read host-side per request and is never mounted into the container, which
+is the property the whole arrangement exists for.
+
 ## Tool
 
 Not an axis: a launch selects one forge, one workflow and one harness, and
@@ -440,7 +514,11 @@ every launch:
 | workflow | `branch-push` | worktree → push, stops at the branch |
 | workflow | `local-only` | **default** - commits locally, pushes nothing |
 | harness | `claude-code` | hosts every guard; **not a default** - `[core] harness` must be set |
-| harness | `cline` | provider-agnostic, so it can be pointed at an open-weight model served locally; hosts no guards, and needs `[harness.cline] model` set and a CPU with AVX2 |
+| harness | `cline` | backend-agnostic, so it can be pointed at an open-weight model served locally; hosts no guards, and needs `[harness.cline] model` set and a CPU with AVX2 |
+| backend | `anthropic` | Anthropic on a subscription login; the OAuth token is refreshed and written back to the host |
+| backend | `anthropic-api-key` | Anthropic on API billing, whether the key came from Claude Code's console login (`primaryApiKey` in `~/.claude.json`, the default) or a file you hold yourself |
+| backend | `openrouter` | a hosted OpenAI-compatible API; a static key, held on the host |
+| backend | `self-hosted` | a model you serve; no credential and so no proxy, and the endpoint must be host-local |
 
 ### Harness integration maturity
 
@@ -459,7 +537,7 @@ over, which is a kind of coverage no test suite substitutes for.
 **Cline is new, and has barely been used.** Its integration was built
 deliberately and is tested, but a test only covers what someone thought to
 check. The first run against a live model immediately turned up a bug no test
-had: Cline silently discards a provider entry with no `updatedAt` and falls back
+had: Cline silently discards a `providers.json` entry with no `updatedAt` and falls back
 to its own hosted endpoint, which presents as a connection failure to a host
 nobody configured. The first real session turned up a second, in a component
 Cline does not own at all - the conversation shipper passed its payload as a
@@ -475,6 +553,41 @@ can be pointed at any endpoint, including a model you serve yourself - and
 expect to be the person who finds the next crack.
 
 
+### Model backend maturity
+
+The same caveat the harnesses and forges get, and for the same reason: four
+backends in one table invites the reading that each got the same amount of
+use, and they did not.
+
+**`anthropic` is the one dejima was built around.** The credential proxy, the
+in-container terminator, the refresh-and-write-back - all of it was designed
+against a subscription login and generalised afterwards. It has been used for
+real work continuously, which is the coverage no test substitutes for.
+
+**`anthropic-api-key` works and has not been leaned on.** It was verified end
+to end on a real machine: the model answers, billing shows as API usage, the
+key stays on the host and the container holds only a placeholder. That is one
+confirmed launch rather than months of use, and the difference matters for the
+same reason it does above.
+
+**`openrouter` is at the same level.** Built from the same manifest shape,
+exercised against a fake upstream and through a full launch, and confirmed
+against the real endpoint. What has not happened yet is a long tail of
+sessions through it, so expect the rough edges that only volume finds.
+
+**`self-hosted` runs no proxy at all**, which makes it the simplest of the
+four and the one with least to go wrong in dejima: there is no credential to
+withhold, so the session reaches the endpoint directly and dejima's only job
+is refusing an address that is not host-local. It has been run against a local
+model. What it does not get is any of the credential machinery's protection,
+because there is nothing to protect.
+
+If you are choosing with no other reason to prefer one, and you have a
+subscription, `anthropic` is the path with the most miles on it. The other
+three are supported in the same sense the second harness is: built
+deliberately, tested, and newer than the thing they sit beside.
+
+
 ### Forge integration maturity
 
 The same caveat the harnesses get, for the same reason: two forges listed in
@@ -509,13 +622,33 @@ knowing about because they are what a second forge costs:
 - **`gh` can be aimed past the sandboxed repository, and is stopped.** The
   gitea CLIs refuse an origin that is not on the configured host, so they can
   only act on the repo the sandbox was launched against. `gh` takes `--repo`
-  on nearly every subcommand and reads `GH_REPO`, so this forge declares both
-  (`repo_flags`, `repo_env`) and `docker/forge-guard.sh` refuses a value that
-  is not the launched-against repository. Fast-fail, not a boundary, exactly
-  as `merge_block` is: the session holds the token and could call the API
+  on nearly every subcommand, reads `GH_REPO`, and names repositories in `gh
+  api` paths, so this forge declares all three (`repo_flags`, `repo_env`,
+  `repo_paths`) and `docker/forge-guard.sh` refuses a value that is not the
+  launched-against repository. Fast-fail, not a boundary, exactly as
+  `merge_block` is: the session holds the token and could call the API
   directly. What actually bounds it is the token's scope, so a per-repository
   fine-grained PAT is the expected shape of `push_token_file`.
 
+  **What it sees, and what it does not.** Worth stating both, because a guard
+  described only by what it catches reads like a boundary. It compares, case
+  -insensitively: `--repo x` and `--repo=x`; `-R x` and `-Rx`; the same letter
+  inside a short-flag cluster, `-wR x` and `-wRx`; `GH_REPO`; and
+  `gh api repos/<owner>/<name>/...`, with or without a leading slash. A launch
+  that resolved no repository at all refuses every one of those rather than
+  waving them through.
+
+  It does not see a GraphQL `mutation` sent through `gh api graphql`, a
+  repository named in an `--jq` expression or a `-F`/`-f` field, an API path
+  under a segment other than `repos/`, or `gh` invoked through something else
+  that passes the repository along. Nor can it know that the workspace's
+  `origin` is the repository you meant: it compares against whatever origin
+  the checkout has, so a workspace pointing somewhere unexpected shifts what
+  counts as "this repository" rather than being caught by this. That list is
+  not exhaustive either, and it is not meant to be - widening it further would
+  mean parsing each subcommand's flags, which is the coupling this guard
+  exists to avoid. The token's scope is what bounds the ones it misses.
+
 So: if you have a choice, `gitea` is the better-worn path. Choose `github`
 because that is where your repositories are, which is a good reason - and
 expect to be the person who finds the next crack.

docs/remote-access.md

@@ -36,9 +36,9 @@ attached. The two things holding that line are:
 - **[The bind address](#the-bind-address-is-the-one-thing-to-get-right).**
   `ttyd` binds `127.0.0.1` and your proxy must bind one specific LAN
   address - never the wildcard, never a Docker bridge.
-- **Authentication on the proxy.** `ttyd` carries no credential of its own,
-  so a `server` block without `auth_basic` is an unauthenticated host shell
-  for everyone on that network.
+- **[Authentication on the proxy](#authenticating-the-front-door).** `ttyd`
+  carries no credential of its own, so a `server` block that authenticates
+  nothing is an unauthenticated host shell for everyone on that network.
 
 What it does **not** add is a way *out* of a sandbox. Configured as
 described below, a compromised session cannot reach `ttyd`, cannot reach
@@ -321,8 +321,10 @@ and forgotten. What matters in it:
 
 - **Authentication on every server block.** `ttyd` is started with no
   credential of its own, because the loopback bind means only this host can
-  reach it - the proxy is the entire gate. A block without `auth_basic` is
-  an unauthenticated host shell on your network.
+  reach it - the proxy is the entire gate. A block that authenticates nothing
+  is an unauthenticated host shell on your network. The example uses HTTP
+  Basic; [Authenticating the front door](#authenticating-the-front-door) is
+  what that costs and what else meets the requirement.
 - **A `default_server` that refuses.** nginx picks a server block by
   SNI/`Host`, and when nothing matches it serves the **default** for that
   listen address - which, if the front door is the only block on it, is the
@@ -345,6 +347,60 @@ and forgotten. What matters in it:
 - **A long `proxy_read_timeout`.** An attached terminal sits idle for hours;
   nginx's default is 60 seconds.
 
+**The page carries its own colours.** dejima's terminal output uses indexed
+colour so your terminal's theme fills the slots - but a browser has no theme
+to inherit, so the front door is handed gruvbox explicitly: all sixteen ANSI
+slots plus background, foreground and cursor. Without it xterm.js draws with
+its own defaults, and the same session looks one way over SSH and another in
+the browser. `bin/dejima-ttyd` sets it, and `web/src/page.css` carries the
+same values for the chrome around it.
+
+## Authenticating the front door
+
+`ttyd` binds loopback and carries no credential, so whatever sits in front of
+it is the entire gate. The requirement is that it authenticates **every
+request to every server block, the default one included** - not that it is any
+particular software. These are the shapes that meet it, roughly in order of
+how much they change.
+
+**A network the public internet cannot reach.** Tailscale, WireGuard, or any
+VPN that puts the listener on an interface nothing outside can route to.
+First because it removes the exposure rather than authenticating it, because
+it composes with everything below, and because for a lot of readers it is both
+the simplest answer and the strongest. It does not replace [the bind
+address](#the-bind-address-is-the-one-thing-to-get-right): a VPN interface is
+still one specific address to bind, and the wildcard is still wrong.
+
+**HTTP Basic**, which is what the example config shows. One shared credential,
+no per-operator identity, no second factor, revocation that means editing
+`htpasswd`, and an access log that cannot tell two people apart. For a solo
+operator that is a reasonable trade, and worth saying that it is one; for
+anyone else it is the first thing to replace. It also sends the password on
+every request, which is why TLS is not optional here.
+
+**Client certificates.** `ssl_client_certificate` and `ssl_verify_client on`
+in the same block. Per-device identity, revocable through a CRL, and nothing
+worth stealing sent on every request. The cost is distribution and renewal,
+and a phone that has to have the certificate installed - the part that will
+bite, and the part that differs per platform.
+
+**A forward-auth proxy.** oauth2-proxy or Authelia via nginx `auth_request`:
+OIDC, per-user identity, and a session cookie rather than a credential on
+every request. Also where passkeys realistically arrive, since the proxy
+handles WebAuthn and `ttyd` never learns about it. The cost is another moving
+piece in the path to a host shell, which is worth naming given what is on the
+other side of it.
+
+**Something you already run.** An identity-aware gateway, or an
+authenticating proxy already in the path. The requirement above is the whole
+of what this document asks of it.
+
+**None of these stops a browser that has already authenticated.** Whatever is
+in front, a page loaded in a session that has passed it can act - which is the
+same property that makes the front door usable from a phone you unlocked an
+hour ago. Authentication decides who gets a shell, not what an already-open
+tab does with one.
+
 ## How it works
 
 Almost none of this is in the sandbox. The container writes one empty file
@@ -397,7 +453,7 @@ guarantee actually lives.
  ════════╪══════════════════ your LAN ══════════════════╪══════════════
  ┌─ your machine, as your user ───────────────────────────────────────┐
  │  nginx, listening on ONE LAN address        sshd                   │
- │   TLS + auth_basic, plus a default_server    authorized_keys with  │
+ │   TLS + auth, plus a default_server          authorized_keys with  │
  │   that refuses every other name              a forced command      │
  │       │                                              │             │
  │       │  proxy_pass http://127.0.0.1:7681            │             │
@@ -486,6 +542,46 @@ nvim split separator resizes the split. Neither needs any server-side
 configuration - they are stock tmux and nvim behaviour; the page's only
 contribution is delivering the drag.
 
+### A scroll gesture jumps too far, and the amount is tmux's
+
+A scroll gesture is sent as wheel notches, one per row of finger travel. What a
+notch is then worth belongs to whoever receives it, and this page is not it:
+when the pane is scrolling its own history, tmux is.
+
+**Find out what yours does before changing anything:**
+
+```sh
+tmux list-keys -T copy-mode-vi | grep WheelUpPane
+```
+
+Stock tmux scrolls five lines (`send-keys -X -N 5 scroll-up`), which is a fifth
+of a desktop terminal and better than half a phone one. A configuration that
+binds `halfpage-up` instead - a common enough idiom that it is worth naming -
+scrolls half the pane, so twenty lines in a forty-line one. That is the case
+this section exists for: on a phone it throws the screen on the smallest
+movement of a thumb, and placing a particular line takes several tries.
+
+Set it to a few lines, in your own `~/.tmux.conf`:
+
+```tmux
+bind -T copy-mode-vi WheelUpPane   select-pane \; send -X -N 4 scroll-up
+bind -T copy-mode-vi WheelDownPane select-pane \; send -X -N 4 scroll-down
+bind -T copy-mode    WheelUpPane   select-pane \; send -X -N 4 scroll-up
+bind -T copy-mode    WheelDownPane select-pane \; send -X -N 4 scroll-down
+```
+
+Both tables, because which one is active follows `mode-keys`. `scroll-up` takes
+no amount of its own, so the `-N` repeat count is the amount. It applies to
+every client of that tmux server, phone and desktop alike - which is the reason
+it is not something dejima sets for you: `dejima-attach` joins the tmux session
+you launched from, and its configuration is yours.
+
+Nothing in dejima can make the step smaller from this side. The page can only
+choose how many notches to send, and sending fewer means dragging further for
+each one - which trades a jumpy scroll for a stiff one rather than fixing
+either. An application reading the mouse directly, rather than through tmux,
+picks its own figure and there is no binding for that at all.
+
 ### Toolbar
 
 ```
@@ -689,8 +785,8 @@ cost of losing the correction everywhere else.
 Terminating TLS somewhere else and forwarding here is a supported shape, but
 read this first: it moves the front door out of the LAN threat model
 everything above is written against. If the outer proxy is internet-facing,
-`auth_basic` over TLS is now the only thing between the public internet and
-a host shell. Put something stronger in front of it, and take the
+whatever authenticates it is now the only thing between the public internet
+and a host shell, and HTTP Basic is a thin thing for that to be. Put something stronger in front of it, and take the
 [security notes](security.md) as the floor rather than the ceiling.
 
 The mechanical part has four requirements at the outer hop, and each one
@@ -742,13 +838,20 @@ what the outer proxy sends.
 
 ## Notifications
 
-`dejima` registers `hooks/dejima-notify.sh` as a `Stop` hook for a
-remote-enabled session, into the throwaway settings override layer it already
-generates - never into your real `~/.claude/settings.json`. Your own hooks
-keep running alongside it, since Claude Code merges hooks across layers rather
-than replacing. The layer is mounted read-only, so a session cannot
-unregister its own hook. The hook writes one empty file named `done` into
-this run's marker directory: no content, no stdin, no network.
+**Only for a harness that declares the `notify` guard**, because a
+notification needs a session-lifecycle signal to hang off and not every
+harness has one. Claude Code does; Cline does not, and a remote-enabled Cline
+session gets attach and the web terminal but no push. The launch says which
+guards a harness is going without, so that is visible rather than a
+notification that silently never arrives.
+
+Where it is declared, `dejima` registers `hooks/dejima-notify.sh` as a `Stop`
+hook for a remote-enabled session, into the throwaway settings override layer
+it already generates - never into your real `~/.claude/settings.json`. Your
+own hooks keep running alongside it, since Claude Code merges hooks across
+layers rather than replacing. The layer is mounted read-only, so a session
+cannot unregister its own hook. The hook writes one empty file named `done`
+into this run's marker directory: no content, no stdin, no network.
 
 **One push per stop, and not a second one a minute later.** The hook and the
 watcher both understand a `waiting` event as well, and Claude Code's
@@ -878,7 +981,12 @@ the next one is worth checking.
    with a 404 usually means `ntfy_url` names the server but no topic; a 401
    or 403 means the instance wants credentials, which the URL can carry as
    `https://<user>:<token>@<host>/<topic>` - nothing here sends an auth
-   header of its own.
+   header of its own. That URL is handed to `curl` on stdin rather than as an
+   argument, because every argument of every process on a host is readable by
+   any local account through `/proc/<pid>/cmdline`, and a token in a URL is a
+   token in `ps` output for as long as the request runs. Worth knowing if you
+   reach for `curl -sv "$ntfy_url"` yourself in the next step: that one does
+   put it there, briefly, on a machine you are already logged into.
 5. **Can this host reach the ntfy server at all?** `curl -sv "$ntfy_url"`
    from the host, not from a session. A host-level egress filter this machine
    does not control drops the push with nothing in any log here, and every
@@ -949,3 +1057,180 @@ from shrinking the desktop's view, and the option's only scopes are the
 window - which a grouped session *shares* with yours, so setting it there
 would permanently overwrite your choice with nothing to restore afterwards -
 and global. An operator who deliberately set `smallest` keeps it.
+
+## Mounting the box's files
+
+The front doors above get you a terminal. The other half of working from
+another machine is the files - the screenshots, specs and scratch output a
+session leaves behind - and `sshfs` puts those directories in your own file
+manager and editor over the SSH access you already have.
+
+Read the next section before setting it up. What it costs is not obvious from
+the fact that it is only a filesystem mount, and it is not a cost dejima can
+carry for you: nothing dejima runs is in the path.
+
+### What mounting it costs you
+
+**Every byte and every name in those directories was written by a sandboxed
+session.** That is what they are for - a handoff directory a session cannot
+write to is not a handoff directory - so this is not a defect to fix but the
+surface to know about. dejima sanitises session-authored bytes before
+printing them to your terminal, in `dejima-audit` and `dejima-epitaph`,
+because that is the one surface it controls. A file manager on another
+machine is not that surface, and nothing carries the sanitising there.
+
+**Mounting removes the deciding.** Copying a file off the box when you want
+it is a decision per file. A mount, and especially one a login unit brings up
+for you, means the directory is simply present whenever you are logged in -
+and a desktop does not wait to be asked. A file indexer walks new directories and
+opens what it finds to extract text from PDFs, archives and office documents.
+A thumbnailer decodes images and video frames. A previewer parses on
+selection. Those are image and document parsers, running as you, unsandboxed,
+reached with no click. dejima's whole premise is that the session may be
+hostile; none of that software was written with that assumption about a
+directory on your own disk. This is the [threat
+model](threat-model.md#ranked-by-what-is-actually-likely)'s fifth-ranked item
+with its one bound removed - it is still the operator's side of the handoff,
+but no person decides per file any more.
+
+**Names are session-chosen too, and a desktop renders names.** Control
+characters, bidi overrides, and a long name whose visible tail is not its real
+extension all survive into a file listing. The rule for a terminal applies
+unchanged to a file manager: what is displayed is not evidence of what it is.
+
+**Opening the directory as a project is code execution.** Editors act on
+configuration they find beside the files - `.envrc` for direnv, a `.vscode`
+directory, a project-local `exrc`, a `.git/config` that any later `git`
+command run in that directory honours. A session that can write the directory
+chooses those files as freely as it chooses the screenshots. Pull files out of
+the mount; do not point a project-opening tool at it.
+
+**The mount is read-write, and your desktop uses that.** Thumbnail caches,
+trash directories, editor swap and undo files land in the share, where every
+later session reads them. An editor swap file can hold buffer content from
+the file you had open, and deleting something in a file manager usually moves
+it to a trash directory inside the same mount rather than removing it.
+
+**Symlinks resolve on your machine.** `sshfs` passes a symlink through as a
+symlink, so one a session planted resolves against *your* filesystem: a
+backup job, an indexer, `cp -r` or `rsync -L` pointed at the mount can be led
+out of it and into your own files. `-o follow_symlinks` inverts that by
+resolving them on the box instead, which hands you the box's files rather
+than yours. Neither is what you want, so do not add that option and do not
+point recursive tools at the mount.
+
+**What it does not add is a route inward.** A session cannot see the mount,
+cannot cause one, and gains nothing from the fact that one exists. The ssh
+credential involved already gets you a shell on that box, so it is not a new
+grant either. Everything above is about where session-authored bytes end up,
+which is a machine that appears nowhere in dejima's blast-radius table.
+
+**Keeping it small** is most of the answer, and unmounting is the biggest
+lever: none of the above happens to a directory that is not currently there.
+Then mount the handoff directories rather than the box's home, add `-o ro` for
+one you only ever pull from, exclude the mount point from your indexer's and
+your backup tool's scope, and [clear `share_dir` out
+periodically](configuration.md#shared-scratch-space) - which now means stale
+files on two machines rather than one.
+
+### Setting it up
+
+**Use your ordinary key, not the front-door one.** A `command=` in
+`authorized_keys` replaces whatever the client asked to run, and a
+`subsystem sftp` request is not an exception, so a client offering the phone
+key gets `dejima-attach` where it expected the SFTP protocol and fails
+without explaining itself. Do not relax that key to make this work: the
+forced command is the whole of what makes it safe to leave on a phone. The
+key that already gets you a normal shell on the box is the right one, and it
+grants nothing new here - you had the shell.
+
+**Find the host path first.** `~/shared` is where the *container* sees it; on
+the host it is one project's directory under `[core] share_dir`, which defaults
+to `~/.local/share/dejima/shared` and is not named `shared` at all.
+`dejima --print-config | grep share_dir` on the box prints the resolved root,
+and `dejima-share list` prints what is under it. Mount `<share_dir>/projects`
+to get one directory per project with no loose files mixed in, or a single
+project's directory - `dejima-share path <project>` - to keep the mount to the
+one you actually pull from.
+Anything in `[mounts] read_write` needs no lookup, because those mount at the
+host path they name: `~/specs` in the container is `~/specs` on the box.
+
+```sh
+sshfs box:.local/share/dejima/shared/projects ~/mnt/dejima-shared \
+    -o IdentityFile=/home/<you>/.ssh/id_ed25519,IdentitiesOnly=yes \
+    -o PasswordAuthentication=no \
+    -o reconnect,ServerAliveInterval=15,ServerAliveCountMax=3 \
+    -o Compression=no
+```
+
+`IdentitiesOnly=yes` stops ssh offering every key your agent holds ahead of
+the one you named, which can exhaust the server's `MaxAuthTries` and fail as
+though the key were wrong. `PasswordAuthentication=no` makes an unattended
+mount fail immediately rather than block on a prompt nobody is there to
+answer. The keepalives are what make `reconnect` worth having: they give up
+after about 45 seconds, where a laptop that slept or changed network
+otherwise leaves every `ls` hanging on the kernel's TCP timeout.
+`Compression=no` because screenshots and PDFs are already compressed.
+
+Two additions worth knowing rather than copying. `-o
+Ciphers=aes128-gcm@openssh.com` is faster when both ends have AES-NI, and
+slower when they do not - ssh's default puts `chacha20-poly1305` first
+precisely because it wins on hardware without it. And `-o idmap=user` if your
+account has a different UID on the two machines, or every file arrives owned
+by whoever holds that number locally.
+
+A `Host box` block in `~/.ssh/config` carrying the identity and keepalive
+options keeps all of this to `sshfs box:... ~/mnt/...`, which is worth doing
+once rather than pasting the long form wherever you need it.
+
+**Mount it when you want it, and `fusermount3 -u` when you are done.** Two
+commands is not much friction, and it buys back the thing the section above
+says a mount costs: while it is unmounted there is no directory for an
+indexer to walk or a previewer to open, so the window in which your machine
+acts on session output is one you opened on purpose. Every automatic form
+below trades that away. There is deliberately no `/etc/fstab` line here -
+those run as root, which means a key root can read, root's `~/.ssh/config`
+instead of yours, and `allow_other` before your own account can see inside
+the mount, at which point every account on the machine can too. That is a
+worse deal in every direction than typing `sshfs`.
+
+### On login
+
+**Prefer mounting on demand.** This is here because a mount you have to
+remember is a mount you stop using, not because it is the better answer: an
+always-present directory is exactly the case the cost section is about. Worth
+it for a directory you genuinely work out of, like `~/specs`; not worth it
+for one you look at twice a week.
+
+A **user** service runs as you, so the key in your home directory works
+without being made readable by anyone else. In
+`~/.config/systemd/user/dejima-shared.service`:
+
+```ini
+[Unit]
+Description=dejima shared directory
+Wants=network-online.target
+After=network-online.target
+
+[Service]
+ExecStart=/usr/bin/sshfs -f box:.local/share/dejima/shared %h/mnt/dejima-shared \
+    -o IdentityFile=%h/.ssh/id_ed25519,IdentitiesOnly=yes \
+    -o PasswordAuthentication=no \
+    -o reconnect,ServerAliveInterval=15,ServerAliveCountMax=3
+ExecStop=/bin/fusermount3 -u %h/mnt/dejima-shared
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+```
+
+`-f` is the load-bearing flag: without it `sshfs` daemonises, systemd watches
+the parent exit and calls the mount a failure. `fusermount3` is the libfuse3
+name, `fusermount` the libfuse2 one. Then
+`systemctl --user enable --now dejima-shared`, and one unit per directory -
+`%h` expands to your home, so the same file with two paths changed covers
+`~/specs`.
+
+`systemctl --user` needs `loginctl enable-linger <you>` if you want the mount
+to survive you logging out, the same requirement `dejima-notify-watch` has.

docs/research-review.md

@@ -57,7 +57,11 @@ doing any work.
    hostile?** The field says no for untrusted code, and tiers gVisor and
    per-workload VM kernels above it. dejima's answer is that escape moves a
    layer - true where the layer exists. See
-   [Which deployment this describes](threat-model.md#which-deployment-this-describes).
+   [Which deployment this describes](threat-model.md#which-deployment-this-describes)
+   and [Why a container, and not a microVM](threat-model.md#why-a-container-and-not-a-microvm),
+   which is where the reasoning is written down so a sweep can contradict it.
+   The live half of this question is question 5: whether a current escape
+   clears this configuration's floor.
 2. **Does a name-based egress allowlist hold?** It holds against an agent that
    must resolve a name. It does not hold against exfiltration through an
    allowed domain or against DNS query-name channels, both of which are listed

docs/security.md

@@ -277,6 +277,9 @@ a line added to a manifest widens the egress boundary on the next run.
 container: it names a tarball URL, the sha256 checked against it and the
 layout it is unpacked with, all consumed by the image build - so a session
 that edits one chooses what the next launch downloads and installs as root.
+`backends/*/backend.conf` names the upstream every request is forwarded to and
+the host path the credential is read from, so an edit there redirects where a
+real credential is sent.
 
 An ordinary edit is a diff you are about to read and is not reported; one git
 cannot see - hidden by `.gitignore`, `.git/info/exclude`, `assume-unchanged`
@@ -288,29 +291,31 @@ can make; it is one the audit reports. See
 
 - Running the harness with its permission prompts off removes your chance to
   review tool calls before they run. Only point this at trusted repositories.
-- The mounted project itself has **no write protection**. `deny-dangerous-
-  bash.sh`, `git-push-guard.sh` and `merge-guard.sh` are regex
-  pattern-matching on the literal Bash command string - a fast-fail guard
-  against an overeager agent doing something obviously destructive, not a
-  boundary against one that's actively trying to get around them (a
-  different scripting language, an encoded command, editing `.git/config`
-  directly all sail right through).
-  Nothing here stops a compromised or badly-instructed session from
-  modifying or deleting the real working copy it's mounted against.
+- The mounted project itself has **no write protection**. The guards are
+  fast-fail checks against an overeager agent doing something obviously
+  destructive, not a boundary against one actively trying to get around them.
+  `deny-dangerous-bash.sh` is regex pattern-matching on the literal Bash
+  command string, so a different scripting language, an encoded command or
+  editing `.git/config` directly all sail right through. The push and merge
+  guards shadow `git` and the forge CLI on `PATH` and read argv, so quoting
+  and pipelines stop mattering - but a session that means to get round one can
+  call `/usr/bin/git` directly. Nothing here stops a compromised or
+  badly-instructed session from modifying or deleting the real working copy
+  it's mounted against.
 - That same read-write access to the mounted project is also a
   host-code-execution vector, not just a data-destruction one: a
   compromised session could plant `.git/hooks/post-commit` (or
   `pre-push`), set `core.hooksPath`, or write a
   `.claude/settings.local.json` with a malicious hook command, into the
   project. Any of those run unsandboxed on the host the next time you run
-  `git` or open Claude Code in that repo - no network egress required, so
+  `git` or open your harness in that repo - no network egress required, so
   the firewall doesn't see it either. Same underlying persistence pattern
-  as the `~/.claude/hooks` and `~/.claude.json` risks above, just through
+  as the harness config risks above, just through
   the project mount instead of the config mount. "Only point this at
   trusted repositories" (above) covers input trust; this is about the
   sandbox writing a persistence payload into an otherwise-trusted repo.
   The workspace's own `.git/hooks` directory is mounted read-only
-  (same pattern as the `~/.claude` code directories below), so planting a hook
+  (same pattern as the harness's own code directories below), so planting a hook
   file directly is closed - accepted breakage: installing hooks
   *in-session* (`husky`, `pre-commit install`) fails, which is the
   point. `core.hooksPath` and `.claude/settings.local.json` aren't
@@ -495,6 +500,16 @@ approximation of its name.
 
 ## One project's session cannot reach another's
 
+The property is the same for every harness; the mechanism is not, because it
+depends on how the harness keys its own state. Claude Code stores a directory
+per project and dejima mounts a slice of it. Cline stores one flat database
+indexing every session it has ever run, with the project as a field inside the
+record, so there is no slice to take - dejima gives each workspace a data
+directory of its own instead. Both reach the same place: a session sees its
+own project's history and no other's.
+
+### Claude Code: a slice of your own tree
+
 - `~/.claude/projects` (session transcripts and per-project memory) is
   **not** mounted as a tree. A session gets the workspace's own slug
   directory plus one for each live git worktree nested under it,
@@ -548,6 +563,31 @@ approximation of its name.
   That costs undo history for that session if it is later resumed on the
   host, and it is the reason this cannot be scoped as completely as
   `projects/`, where the workspace's own slug is known at launch.
+
+### Cline: a directory dejima owns, one per workspace
+
+- `~/.cline/data` is **not** mounted. Cline indexes every session it has ever
+  run in one `sessions.db`, with the project a session belonged to as a field
+  inside the record rather than a directory above it, so there is no
+  per-project subtree to slice: mounting your data directory would put every
+  project's transcripts in every session, which is this section's whole
+  subject.
+
+  A launch instead creates `<[harness.cline] state_dir>/<workspace slug>` on
+  the host and mounts *that* at `~/.cline/data`. Every session under it belongs
+  to this project by construction rather than by a filter that could be wrong,
+  which is why Cline clears this requirement more cleanly than Claude Code
+  rather than less.
+
+  The cost is that the directory is dejima's rather than yours: a session
+  started inside the sandbox is not offered back to a host-side Cline, and one
+  you started on the host is not visible inside. There is no import or export
+  ([#301](https://gitbox.branderson.io/dejima/dejima/issues/301)), and the
+  briefing tells the session so, so it will not offer you a resume command that
+  cannot work.
+
+### Whichever harness is selected
+
 - Epitaphs - the summary a session leaves when its context is compacted away -
   are kept host-side in `[epitaph] dir`, and that directory is never mounted. A session can neither read what earlier
   sessions concluded nor edit what this one is about to record, which is the
@@ -555,8 +595,177 @@ approximation of its name.
   they are extracted from *is* session-writable, so a summary records what was
   there rather than vouching for it - and nothing loads one back into a later
   session, deliberately: that would be the channel #104 closed, rebuilt.
+- `[core] share_dir` is **not** mounted whole. A launch mounts
+  `<share_dir>/projects/<slug>` at `~/shared`, so a session sees its own
+  project's handoff files and no other project's - the same slicing as
+  `projects/` above, applied to the directory that was the remaining way
+  around it. A handoff file is session-authored by design, and one project's
+  session writing a plausible-looking note that a session in another project
+  then picks up is #104's channel by a different route.
+
+  The per-project split bounds *which* sessions, not *how long*: a project's
+  share persists, so everything in it is readable by every later session
+  against that project. Nothing prunes it, which is why
+  [docs/configuration.md](configuration.md#shared-scratch-space) says to clear
+  it out and `dejima-share list` prints what each project is holding.
+
+  `<share_dir>/projects` is in the guarded list, so an operator cannot hand
+  the whole of it back through `[mounts] readonly` or `[mounts] read_write`.
+  The session's own share arrives at `~/shared` without going through either.
 ## The model API credential never enters the container
 
+### Four arrangements, and what a session can take from each
+
+Which one a launch is in comes from the selected backend's `credential` kind
+and from whether the proxy is on. The differences are worth stating together,
+because only the last one puts a durable credential where a session can read
+it.
+
+| Arrangement | In the container | What a compromised session can take | What it can still do |
+| --- | --- | --- | --- |
+| **Proxied, refreshing** (`credential = anthropic-oauth`) | A fake credential file whose secrets are placeholders. The real one is read host-side per request. | The placeholder. | Use the API as you, through the proxy, while the session runs. |
+| **Proxied, static key** (`credential = static`) | A placeholder key in the harness's own model configuration, and the endpoint's real hostname. | The placeholder. | The same. |
+| **A backend with no credential** (`credential = none`, a model you serve) | Nothing but the endpoint's address. It needs no credential, so there is none to withhold. | Nothing. | Reach that endpoint, which is why it has to be one you allowlisted. |
+| **No proxy** (`[credentials] proxy = off`, or a Claude Code login the selected backend cannot serve) | The real credential file, mounted. | **The credential itself**, durable and usable offline. | Everything the credential allows, for as long as it is valid. |
+
+**The first three keep the credential out; the fourth does not.** That is the
+whole of the difference, and it is why `proxy = off` is described here as a
+kill switch rather than as an option.
+
+**Both Anthropic billing models are in the first three.** A subscription login
+is `backends/anthropic`, whose OAuth token the proxy refreshes and writes back;
+a console key is `backends/anthropic-api-key`, a static credential against the
+same endpoint presented as `x-api-key` - one backend whether the key came from
+Claude Code's own login or a file you hold. Either way the credential is held on
+the host and injected per request. On the API-key path the container gets
+`ANTHROPIC_API_KEY=sandbox-credential-proxy-placeholder` and no credential file
+at all.
+
+What lands in the fourth row is `proxy = off`, and a login whose shape no
+selected backend serves.
+
+**The proxy is switched per backend, not globally.** `[backend.<name>] proxy`
+falls back to `[credentials] proxy` when unset. One backend whose credential
+the proxy cannot serve is then an opt-out for that backend, rather than a
+reason to stop withholding credentials from the ones it serves. Turning it off
+for a backend prints what the session is being given, because it is a
+downgrade the operator chose rather than a setting that happens to be off.
+
+**Everything dejima copies in is scanned for credential-shaped values it does
+not recognise, and an unknown one is a question rather than a surprise.** The
+scanner reports a redacted path, a shape name, the harness and the backend -
+never the value, and never a real path, since a gitconfig can carry userinfo
+in a section header. **Finding it is best effort**: this recognises common
+credential shapes and can miss an unusual one. Removing one it has found is
+not - a value it names is removed whole, including one split across
+continuation lines.
+
+The choice is yours: keep it out for this launch, let it in for this launch,
+let it in every launch, or stop. Only the third persists, in
+`credential-scan.decisions` beside your config, keyed by field rather than by
+value so rotating a credential does not re-ask a question you already
+answered. A standing *scrub* is available there too but is not offered at the
+prompt: removing something the harness turns out to need would break every
+launch after, with the cause several layers from the symptom. With nothing
+attached to answer, the launch stops rather than carrying it in.
+
+This is the general form of the two fixes below, which are denylists and so
+only know what was already found. See
+[#291](https://gitbox.branderson.io/dejima/dejima/issues/291).
+
+#### What the scan does not catch
+
+It recognises the *shape* of a credential, not its meaning, so it is a
+backstop against the class of leak that has actually happened here twice -
+not a guarantee that nothing crosses. Specifically:
+
+- **Values containing whitespace.** Both heuristic rules require one token
+  from a restricted alphabet, because the alternative flags every sentence in
+  a config file: English prose scores 4.0-4.5 bits per character by the same
+  entropy measure a random key does. People do put spaces in passphrases they
+  chose themselves, and one of those would go straight through. It is a
+  deliberate trade and it fits these files, which hold credentials issued to a
+  machine rather than typed by a person.
+- **Short or low-entropy secrets in fields not named like one.** A token that
+  is eight lowercase letters in a field called `nickname` is indistinguishable
+  from a nickname.
+- **Anything in a format it cannot parse.** JSON and INI only. An unparseable
+  file is copied unchecked, and says so at launch rather than being silently
+  trusted or silently blocked.
+- **Anything dejima does not copy.** This covers the files dejima *stages* -
+  `~/.claude.json` and `~/.gitconfig`. It does not read your read-write
+  mounts, the workspace, or anything else you have pointed a session at, and a
+  credential you leave in one of those is not something dejima is looking for.
+
+The value of it is not that it is exhaustive. It is that a credential shape
+dejima has never seen becomes a question at launch instead of a copy nobody
+noticed for a year.
+
+**Two host files are copied into a container, and both are filtered.**
+`~/.gitconfig` can hold a `credential.helper` that prints a token, an
+`http.<url>.extraHeader` carrying an Authorization line, or userinfo inside a
+`url.<...>.insteadOf` key; none of that is part of what the sandbox is
+granted, so the copy drops it and says so. The general problem - that these
+filters are denylists, and a harness's authentication is not a stable
+interface - is [#291](https://gitbox.branderson.io/dejima/dejima/issues/291).
+
+**`~/.claude.json` is staged, not mounted, and the staging strips a
+credential.** That file mixes app state with configuration the copy exists to
+carry, and a Claude Code signed in with a console API token keeps its key
+there as a top-level `primaryApiKey` - not in `.credentials.json`, which stays
+`{}` for that login. The copy drops that key, and `backends/anthropic-api-key`
+reads it host-side per request instead. Without it the proxy would
+withhold one file while dejima copied another, on every launch and whatever
+backend was selected.
+
+**The residual the first two share is use-while-running.** A session that has
+been turned can spend your quota, ask the model anything, and read the answers
+- through the proxy, without ever holding the credential. That is inherent to
+the sandbox working at all: the session has to be able to reach the model, and
+anything it can reach it can misuse. What the proxy buys is that the misuse
+stops when the session does, and nothing durable leaves.
+
+**Refreshing and static differ in what a leak elsewhere costs, not in what the
+container sees.** Neither enters it. But an OAuth access token is short-lived
+and the proxy rotates it, while an API key is typically long-lived and
+account-wide - so the host-side file is worth more in the static case, and a
+compromise of the *host* is correspondingly worse. Scope the key at the
+backend where you can, the same argument
+[docs/providers.md](providers.md) makes for a repository-scoped forge token.
+
+**The proxied domain is not in the egress allowlist while the proxy is on.**
+`docker/fixed-domains.sh` adds it only when there is no proxy, so a session
+that tries to reach the API by name finds it unresolvable and goes through the
+terminator instead. Worth being precise about the limit: this defeats a lookup,
+not a route. The API's address stays reachable as an IP literal for as long as
+any other allowlisted name resolves to it.
+
+**A hosted OpenAI-compatible backend is the second arrangement, and it is
+what `backends/openrouter` is.** The key sits in a file on the host, named by
+`[backend.openrouter] credential_file` and read per request; the container
+gets `sandbox-credential-proxy-placeholder` and the endpoint's real hostname,
+which the in-container terminator answers for. Nothing about the arrangement
+is visible to the session, which is the same property the Anthropic path has
+and the reason both are worth having rather than one.
+
+Worth naming what a *hosted* backend adds over Anthropic's OAuth, since it is
+not the container that changes: an API key is typically long-lived and
+account-wide where an access token is short-lived and rotated, so the host-side
+file is worth more. Scope the key at the backend where it offers that, the
+same argument this repository makes for a repository-scoped forge token.
+
+**A backend you serve yourself is the strongest posture available**, and it is
+worth saying so plainly rather than treating it as the degraded one. A session
+pointed at a model on your own network has no credential anywhere in the
+picture, so there is nothing to place, nothing to withhold and nothing to
+steal. What it costs is that the model is yours to run.
+
+It is a backend like any other - `backends/self-hosted`, with
+`credential = none` and its address in `[backend.self-hosted] base_url`. That
+placement is deliberate: an operator who serves a model locally and also uses a
+hosted API keeps both configured and switches by changing one word, rather than
+having to unset one setting to stop it overriding another.
+
 **This assumes the host has one.** dejima authenticates nothing: the proxy
 holds a credential the harness wrote on the host, so a machine where the
 harness has never signed in has nothing for it to hold. The proxy then does
@@ -567,11 +776,19 @@ prerequisite. Sign in on the host first; see the README's
 Refreshing an expired credential is the same: on the host, not from inside a
 session, where the credential deliberately never goes.
 
+### The refreshing OAuth path, in detail
+
+The `backends/anthropic` arrangement, at the level of what the proxy actually
+does. The machinery is not Anthropic's - the credential's kind, which header
+carries it, what must not travel beside it are all arguments a backend
+supplies - but it is worth reading through one backend rather than in the
+abstract, and this is the one with the most miles on it.
+
 - The Anthropic OAuth credential (`~/.claude/.credentials.json`) never
   enters the container. It isn't mounted: `~/.claude` is not shared as a
   whole (see the mount inventory below), so there is no path from
   inside the container to that file. `dejima` starts a host-side proxy
-  (`bin/dejima-anthropic-proxy`) on a per-session unix socket and mounts a
+  (`bin/dejima-credential-proxy`) on a per-session unix socket and mounts a
   fake credential in place of the real one - the secrets are placeholders,
   while `scopes`/`subscriptionType`/`rateLimitTier`/`clientId` are copied so
   the session's UI stays accurate. Its expiry is a year out rather than
@@ -579,7 +796,7 @@ session, where the credential deliberately never goes.
   refresh token that isn't real, logging the session out. Inside the
   container,
   `entrypoint.sh` points `api.anthropic.com` at a loopback TLS terminator
-  (`anthropic-proxy-forwarder.js`) whose certificate is generated at startup
+  (`credential-proxy-forwarder.js`) whose certificate is generated at startup
   and trusted only there, and which pipes raw bytes into the proxy's socket.
   The proxy injects the real access token per request and owns OAuth refresh
   - rotated tokens are written back to the real host file atomically, so
@@ -588,7 +805,13 @@ session, where the credential deliberately never goes.
   `ANTHROPIC_AUTH_TOKEN`, nothing marking the session as unusual. The proxy
   forwards the client's header block verbatim - same names, casing, order and
   repeats, and no `Accept-Encoding` it didn't send - changing only
-  `Authorization`, and `anthropic-beta` if the OAuth value isn't there. Left
+  `Authorization`, and `anthropic-beta` if the OAuth value isn't there.
+  Neither of those is a name the proxy holds: which header carries the
+  credential, what shape it takes, what must not travel beside it and which
+  comma-list value has to be present are all arguments, and `bin/dejima`
+  supplies the Anthropic ones (#171). The credential kind is an argument too -
+  a refreshing OAuth file, or a static key that is read and sent - so a
+  backend that cannot be refreshed is not a branch here. Left
   alone, Python's `http.client` would rewrite all of that into its own style
   and move the fingerprint from the client to the wire. It cannot disguise
   that the connection is CPython's `ssl` rather than Node: the TLS handshake
@@ -646,7 +869,13 @@ session, where the credential deliberately never goes.
   real credential into the container. Rung one is a supported, tested mode,
   not an improvised workaround; if you reach the third, treat it as a
   temporary state rather than a new baseline.
-## What the container sees of `~/.claude`
+## What the container sees of Claude Code's `~/.claude`
+
+One harness's inventory, because there is no shared one to give: what a
+harness keeps where, and which of it is safe to mount, is the harness's own
+answer and each plugin gives it. Cline's is the table in
+[configuration.md](configuration.md#what-comes-in-from-your-host); the
+reasoning below is what both are built on.
 
 - `~/.claude` is **not** shared with the container as a whole. Its contents
   are enumerated in `docker-compose.yml`, in three classes, and anything not
@@ -669,10 +898,10 @@ session, where the credential deliberately never goes.
     approval step, skills can ship executable scripts, and
     commands/agents/output-styles are prompt text loaded into a later host
     session, so without this a compromised session could plant a backdoored
-    hook - including by unlinking one of `install.sh`'s hook symlinks and
-    dropping a plain file in its place, since the dynamic per-target mounts
-    only protect symlink targets that resolve *outside* `~/.claude`, never
-    this directory itself - tamper with plugin code, or drop a malicious
+    hook - including by unlinking one of your own hook symlinks and dropping a
+    plain file in its place, since the dynamic per-target mounts only protect
+    symlink targets that resolve *outside* `~/.claude`, never this directory
+    itself - tamper with plugin code, or drop a malicious
     skill/command/agent/output-style file. Any of those would then run or
     load **unsandboxed on the host** the next time Claude Code starts
     there, turning a single compromised sandbox session into persistent
@@ -917,11 +1146,13 @@ default:
 - DNS resolution via a local proxy (see "DNS is allowlisted too")
 - the Docker host itself (not its whole subnet)
 - GitHub's published IP ranges, port 443 only (see "GitHub push" below)
-- `registry.npmjs.org` and `platform.claude.com` (the harness and its
-  updates), `release-assets.githubusercontent.com` (GitHub release assets, a
-  separate CDN from github.com's own IPs, and where a good deal of tooling
-  fetches its binaries); `api.anthropic.com` when the credential proxy is off
-  (kill switch or API-key auth)
+- `registry.npmjs.org`, plus whatever the selected harness declares as its own
+  (`platform.claude.com` for Claude Code; Cline declares none, so a session
+  falling back to Cline's hosted endpoints fails to connect, which is the
+  right outcome); `release-assets.githubusercontent.com` (GitHub release
+  assets, a separate CDN from github.com's own IPs, and where a good deal of
+  tooling fetches its binaries); and the selected backend's API endpoint when
+  the credential proxy is off for it
 
   That is the whole built-in list, and it is meant to stay that way: it covers
   what the sandbox itself cannot run without, not what a project might want.
@@ -1035,9 +1266,9 @@ Internal hosts named before the container starts (`[forge.gitea] ssh_host`,
 `api`, `[logging] loki_url`, and any globally or per-project approved domain)
 are already exempted and unaffected by this.
 
-The sandbox-context.sh `SessionStart` hook tells the agent to ask for this
-by name when a task is blocked on a single missing domain, rather than
-stopping the whole session over it.
+The session briefing tells the agent to ask for this by name when a task is
+blocked on a single missing domain, rather than stopping the whole session
+over it.
 
 ### The firewall bounds the container, not the harness
 

docs/threat-model.md

@@ -79,8 +79,29 @@ The ordering is the point. Nothing above the last item requires an exploit.
 Item 5 is not an argument for making the handoff harder; a session that cannot
 ask is a session that works around you instead. It is an argument for being
 able to answer, afterwards, what that actually did to the machine - which is
-the layer below this repository's, and the reason the sister project is
-looking at detection rather than at more enforcement.
+the layer below this repository's, and the reason `dejima-guard` exists and
+looks at detection rather than at more enforcement.
+
+**The handoff directories are item 5 with the person taken out.** `[core]
+share_dir` and everything in `[mounts] read_write` exist so that session
+output survives the container, so every byte and every filename in them is
+session-authored by design. On the box that is bounded by how rarely anyone
+looks. Mount one on a workstation - over sshfs, or by any sync that runs on
+its own - and the directory is simply present, at which point a desktop opens
+what appears in it without being asked: an indexer parsing documents and
+archives to extract text, a thumbnailer decoding images, a previewer, an
+editor honouring project configuration it finds beside the files. Each is a
+parser running as the operator, outside the container, reached with no
+decision per file. Item 5's last sentence is that a person decides; here
+nobody does.
+
+It stays item 5 rather than becoming a row of its own, because the shape is
+the same: the session initiates none of it. It cannot see the mount, cannot
+cause one, and the ssh credential involved already gave that operator a shell
+on the box. What changes is where session-authored bytes get opened, and the
+machine they get opened on is not a row in the table below.
+[remote-access.md](remote-access.md#what-mounting-it-costs-you) has the
+specifics and what shrinks them.
 
 ## Blast radius by layer
 
@@ -122,8 +143,31 @@ can see.
 ## Where dejima's boundary ends
 
 dejima runs inside the machine it is protecting the rest of, which is the
-whole reason there are two other repositories. It cannot bound its own host's
-network position, and it cannot bound a runner it never touches.
+whole reason there are three other repositories. It cannot bound its own host's
+network position, it cannot bound a runner it never touches, and it cannot tell
+anyone that something changed after the session ended.
+
+### The stack, and what each piece buys
+
+**Only the first row is required.** Everything under it is what the layer
+below the container costs, and every one of them can be substituted or left
+out - the last two are categories rather than products.
+
+| Piece | Runs on | What it buys | Without it |
+| --- | --- | --- | --- |
+| **dejima** | the devbox | The container boundary: what a session reaches on disk, and deny-by-default egress. | An agent with your home directory and the open internet. |
+| **dejima-devbox-hardener** | the same devbox, enforced from outside the guest | Bounds where an escape *spreads*: LAN reach cut to what is declared, and root in the VM cannot flush the rule set. | An escape reaches the LAN, and the row below the container is unbounded. |
+| **dejima-guard** | a different machine | Notices the devbox changed: file hashes, enabled units and listening ports, diffed against a baseline held off the box. Detection, not enforcement. | Anything a session leaves behind survives unremarked, because nobody is looking at the devbox between sessions. |
+| **self-hosted CI + dejima-ci-hardener** | a runner VM | A runner that executes a session's pull request without that being LAN access, and a rollback that expires what an escape gained. | CI runs attacker-controlled code with the network position of whatever host it sits on. |
+| **or third-party hosted CI** | someone else's machine | The same isolation, bought rather than run - and on their network rather than yours. | - |
+| **ntfy, or any push service** | anywhere both can reach | The channel dejima's "session needs input" and the guard's alerts both arrive on. | A session that stopped to ask, and an alert that fired, both wait for someone to think to look. |
+| **Uptime Kuma, or any uptime monitor** | off the devbox | The dead man's switch: it is what notices the *guard* has stopped reporting. | Silence is indistinguishable from health, which is the failure mode every watcher has. |
+
+The last row is the one most easily skipped and the one that decides whether
+the rest is real. A watcher that has died looks exactly like a watcher with
+nothing to report.
+
+### Each project's own boundary
 
 **[dejima-devbox-hardener](https://gitbox.branderson.io/dejima/dejima-devbox-hardener)**
 covers the two VM rows: what an escape spreads to, rather than whether it can
@@ -138,14 +182,40 @@ Nothing there tries to stop the code running. Its
 [threat model](https://gitbox.branderson.io/dejima/dejima-ci-hardener/src/branch/main/docs/threat-model.md#blast-radius-by-layer)
 has the two tiers and where each one's boundary sits.
 
-Neither is required to run dejima, and the container row holds without them.
-What they change is what the row below it costs.
+**[dejima-guard](https://gitbox.branderson.io/dejima/dejima-guard)** watches a
+devbox from a machine that is not the devbox and alerts on what changed. It
+enforces nothing: everything it reports has already happened. It collects over
+SSH, diffs against a baseline held on the watching machine, and alerts from
+there. That placement is the point, since a baseline stored on the box being
+watched is a baseline the thing you are watching for can edit, and it
+complements devbox-hardener rather than overlapping it - one bounds where a
+compromise spreads, the other notices that one happened.
+
+**It is the only piece here that adds a machine holding credentials rather than
+taking capability away.** Every other row removes something: what a session
+reaches, where an escape spreads, what a runner can talk to. This one
+introduces a host holding an SSH key to the devbox and a token for the alert
+channel, and its exposure is bounded by the hardening of a machine this stack
+does not describe or require anything of. That is the thing to weigh before
+running it.
+
+**Its detection ceiling is root on the watched box.** The collector runs on the
+devbox, so root there can return whatever it likes, including the baseline
+unchanged. What the guard catches is accidents, non-root compromise, and
+payloads that did not think to look, which is most of them. The heartbeat
+proves the guard ran, not that it saw the truth.
+[Its own `SECURITY.md`](https://gitbox.branderson.io/dejima/dejima-guard/src/branch/main/SECURITY.md)
+has the rest, including the ways it is deliberately narrower than dejima.
+
+None of the three is required to run dejima, and the container row holds
+without them. What they change is what the row below it costs, and whether
+anyone finds out.
 
 **A survey of comparable projects found none with rows below the container at
 all** - their boundary is between the agent and the host, and what is under
 the host is outside their threat models. The same survey found nothing
 treating a forge or a CI runner as part of an agent's blast radius, which is
-what the second sister project exists for: a session that can open a pull
+what dejima-ci-hardener exists for: a session that can open a pull
 request can execute code on a machine dejima never touches.
 
 Recorded as an observation from one day of secondary sources rather than as a
@@ -193,6 +263,80 @@ repository's behalf.
 **What this repository can do about that is say so**, which is the whole of
 this section. Nothing in dejima can bound its own host.
 
+## Why a container, and not a microVM
+
+The most frequent question about this project.
+
+The short answer is that a microVM is the stronger boundary and nothing here
+disputes it. Container escape is the least likely of the six threats above and
+the only one that needs an exploit at all, and the layer it lands on is already
+bounded by a control enforced from outside the guest. The effort went there
+rather than into a harder container.
+
+**There is already a VM here**, which is what the usual framing misses. It is
+put as container versus microVM, as though the alternative were a container
+with nothing underneath. On the deployment this document describes, dejima runs
+inside a devbox VM whose rule set is enforced from the hypervisor. So the choice
+is not one boundary against two. It is an outer VM enforced from outside the
+guest, against that plus an inner one managed by software running on the box it
+is protecting - inside the blast radius of the row it is meant to bound. A
+boundary enforced from outside is worth more than one enforced by the thing
+inside it, and that is most of the answer.
+
+**The field's ordering is not in dispute.** gVisor's syscall interposition and
+a per-workload VM kernel are both stronger than a namespaced container.
+Firecracker is what AWS runs Lambda on, for the reason that applies here too:
+untrusted code, multi-tenant, on shared hardware. The disagreement is about
+where marginal effort goes, not about which primitive is stronger.
+
+### What a stronger runtime would and would not change
+
+It would not touch the five threats ranked above escape. Two of them would get
+*harder*, because both are enforced by how the container is configured rather
+than by what isolates it:
+
+- **One project's session cannot reach another's**, because each path crossing
+  the boundary is named individually rather than mounting a tree
+  ([#104](https://gitbox.branderson.io/dejima/dejima/issues/104)). Under a VM
+  each becomes a filesystem daemon.
+- **The container sees an agent socket, never your key.** That is a live host
+  socket, and a VM has no equivalent to hand it one.
+
+One would get easier: egress rules on a tap device sit where the guest holds no
+capability to touch them. That is available without changing the runtime, which
+is what [#305](https://gitbox.branderson.io/dejima/dejima/issues/305) does.
+
+**And "swap the runtime" understates the work**, because several controls are
+implemented *in* Docker rather than merely hosted by it. The dependency
+approval is a derived image build; the tooling reaches live sessions through
+it; the capability floor is an argument about Docker's model. Porting them is a
+rewrite of the parts that *are* the security argument, in a project that says
+at the top that none of it has been reviewed by anyone else.
+
+### What would change the answer
+
+The decision is a judgement about effort, not a door held shut, and these are
+the things that would reopen it:
+
+- **Kata Containers is the cheap path if this reasoning is wrong.** It is an
+  OCI runtime, so the compose file, the mounts and the tooling survive, and it
+  can use Firecracker underneath. A per-launch switch rather than a fork.
+- **Pointing dejima at projects chosen by someone else.** That contradicts an
+  assumption stated at the top of this document, and reorders the ranked list.
+- **A container escape in the wild that clears this configuration's floor**:
+  non-root session user, `no-new-privileges`, `cap_drop: ALL` and a short list
+  added back. The class recurs, and whether a live one clears that floor is
+  asked on a schedule in
+  [research-review.md](research-review.md#the-standing-questions) rather than
+  assumed either way.
+
+What is done instead is depth below the container, which is
+[the stack](#the-stack-and-what-each-piece-buys): two of the three layers under
+dejima are enforced where the guest cannot reach them, and the third bounds a
+compromise in time. A sandbox that reaches for a microVM and stops there has
+nothing underneath it, so an escape from the VM ends its argument. Here it is a
+row with controls of its own.
+
 ## What this repository does not claim
 
 - **That the egress allowlist bounds what reaches the model.** It bounds what
@@ -206,12 +350,24 @@ this section. Nothing in dejima can bound its own host.
   belongs in that harness's assessment.
   [security.md](security.md#the-firewall-bounds-the-container-not-the-harness)
   has the evidence.
+- **That a session cannot use the model API as you while it runs.** It can.
+  The credential proxy keeps the credential on the host, so nothing durable
+  leaves and the misuse stops when the session does - but a session that has
+  been turned can spend your quota and read whatever it asks for, through the
+  proxy, without ever holding the credential. That is inherent to the sandbox
+  working at all. [security.md](security.md#four-arrangements-and-what-a-session-can-take-from-each)
+  has the four arrangements and what each one puts in the container, including
+  the one that puts the credential itself there.
 - **That escape is impossible.** It is a row in the table with controls of its
   own, not an outcome that has been designed away.
 - **That the hooks stop a hostile agent.** They stop an unlucky one.
 - **That a finding from the exit-time audit was caused by the session.** It
   reports that a surface changed while the session ran. A concurrent session
   or the operator's own editing lands in the same diff.
+- **That what a session leaves in a handoff directory is safe for another
+  machine to open.** `share_dir` and `[mounts] read_write` carry
+  session-authored bytes and session-chosen filenames out of the container on
+  purpose. Sanitising happens where dejima does the printing, and stops there.
 - **That the allowlist bounds exfiltration once a session has push access.**
   A commit is an outbound channel to a host that is on the list by definition.
   See [ci.md](ci.md).

forges/github/forge.conf

@@ -38,6 +38,11 @@ merge_block   = gh pr merge
 # repository-scoped fine-grained PAT is the expected shape.
 repo_flags    = --repo -R
 repo_env      = GH_REPO
+# `gh api repos/<owner>/<name>/...` names a repository with no --repo anywhere
+# in it, and is the ordinary way to reach an endpoint the subcommands do not
+# cover. Scoped to `api` so the guard is not comparing every positional
+# argument that contains two slashes (#243).
+repo_paths    = api:repos
 disclose      = pr:gh pr create, pr:gh pr edit, issue:gh issue create, issue:gh issue edit, comment:gh issue comment
 # See the gitea manifest's note: this is the key an identity supplies and a
 # project may not. The read-only [github] token_file is core's rather than

harnesses/claude-code/briefing.md

@@ -1,3 +1,6 @@
+They can continue this exact session outside the container by running on
+the host:
+
   {{resume_command}}
 
 (session history is shared via the bind-mounted ~/.claude, so it will pick

harnesses/claude-code/harness.conf

@@ -5,11 +5,38 @@ image_env          = CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
 command            = claude
 command_path       = /usr/local/share/npm-global/bin/claude
 api_domains        = platform.claude.com
-proxied_api_domain = api.anthropic.com
 guards             = bash-deny push-guard merge-guard notify
+
+# Anthropic's Messages API and nothing else. Claude Code speaks one dialect, so
+# pairing it with an OpenAI-compatible backend is refused at launch rather
+# than producing well-formed requests in the wrong shape.
+api_styles         = anthropic
 no_confirm_args    = --dangerously-skip-permissions
 briefing_args      = --append-system-prompt
 settings_args      = --settings /etc/dejima-settings.json
-keys               = projects_dir:path=~/.claude/projects file_history_dir:path=~/.claude/file-history statusline_path:path=~/.claude/statusline.sh
+# Which model API this harness talks to, and so which credential the host-side
+# proxy injects. Per harness rather than global (#171): an operator running
+# Claude Code against Anthropic and Cline against something else is the
+# ordinary case, and one setting cannot say both.
+#
+# NO DEFAULT, for the reason [core] harness has none. A default that could ever
+# change is a config file that is not the source of truth: a session whose
+# config did not change must not start talking to a different endpoint because
+# dejima's idea of a sensible one moved.
+keys               = backend:?provider:backend projects_dir:path=~/.claude/projects file_history_dir:path=~/.claude/file-history statusline_path:path=~/.claude/statusline.sh
+
+# What this harness was talking to before the key existed, WRITTEN INTO the
+# operator's config the first time a launch finds it unset - not resolved as a
+# default on every read.
+#
+# The difference is the whole point. A default is dejima's answer, re-decided
+# every launch, and changing it later moves a session whose config never
+# changed. A migration is the operator's answer, recorded once: after it runs,
+# nothing dejima decides later can move them.
+#
+# Safe to state here because it is not a guess. Claude Code against Anthropic
+# is what every existing session already was, so writing it down changes
+# nothing about the launch it runs in.
+assumed_backend   = anthropic
 resume_command     = claude --resume {{session_id}}
 briefing           = briefing.md

harnesses/cline/briefing.md

@@ -1,10 +1,10 @@
-  export CLINE_DATA_DIR={{harness_state_dir}}
-  cline history          # find this session's id
-  cline --id <session-id>
+This session cannot be continued outside dejima, so do not offer that or ask
+the operator to try it. It CAN be continued by launching dejima again on this
+project: this project's Cline state - sessions, transcripts, tasks - is kept
+on the host in a directory of its own and survives the container being
+replaced, so the next launch picks up where this one left off.
 
-(the session id is deliberately absent from this briefing: Cline mints one when
-a run starts, which is after this text was written, so `cline history` is where
-to read it. CLINE_DATA_DIR has to be set because this project's Cline state is
-kept in that directory on the host rather than in ~/.cline/data - Cline indexes
-every session it has ever run in a single database, so dejima gives each
-project its own and one project's history is never another's context.)
+(Cline indexes every session it has ever run in a single database, so dejima
+gives each project its own rather than sharing one. That directory is
+dejima's, not Cline's own, and pointing a host-side Cline at it is not a
+supported path - which is why resuming outside is not on offer.)

harnesses/cline/harness.conf

@@ -14,7 +14,9 @@ install            = npm:cline
 # Documents/Cline/Rules is where the briefing is staged. That path is not a
 # guess and not what Cline's documentation says: ~/Documents/Cline/Rules
 # reaches the model on Linux and ~/Cline/Rules does not.
-image_dirs         = .cline .cline/data Documents Documents/Cline Documents/Cline/Rules
+# .agents and .cline/hooks are the operator's own config, mounted from the
+# host by the plugin; they need a mount point in the image to land on.
+image_dirs         = .cline .cline/data .cline/hooks .agents .agents/skills .agents/hooks Documents Documents/Cline Documents/Cline/Rules
 
 # DO_NOT_TRACK and DISABLE_TELEMETRY are both honoured; CLINE_NO_AUTO_UPDATE
 # stops a session upgrading its own harness mid-run, which would replace a
@@ -28,15 +30,9 @@ command_path       = /usr/local/share/npm-global/bin/cline
 # endpoint with the firewall up, so there is no catalogue or feature-flag host
 # to allowlist. Cline's own endpoints (api.cline.bot and friends) are
 # deliberately absent - a session that falls back to them has lost its
-# provider configuration, and failing to connect is the right outcome.
+# backend configuration, and failing to connect is the right outcome.
 api_domains        =
 
-# Only meaningful on the Anthropic path, where Cline is pointed at the real
-# hostname with a placeholder key and dejima's terminator and host-side proxy
-# supply the credential. Confirmed end to end. On the local-endpoint path
-# nothing connects here and pinning it costs nothing.
-proxied_api_domain = api.anthropic.com
-
 # None. Cline registers no hook that can refuse a tool call, so bash-deny has
 # nowhere to live, and it has no session lifecycle signal dejima can turn into
 # a notification. push-guard and merge-guard are not listed because no harness
@@ -44,6 +40,12 @@ proxied_api_domain = api.anthropic.com
 # names what this costs; see harness_report_guards.
 guards             =
 
+# Both, which is what makes this harness the backend-agnostic one: it has a
+# native Anthropic client and an openai-compatible one, and dejima picks
+# between them from the selected backend's api_style rather than from a
+# setting an operator has to keep in step by hand.
+api_styles         = anthropic openai
+
 # R3. Cline registers no session-start hook, so the briefing is a file, and
 # this is the path that reaches the model - established by running it, not by
 # reading the documentation, which says ~/Cline/Rules. On Linux that directory
@@ -63,9 +65,10 @@ no_confirm_args    = --auto-approve true
 # goes stale with the next Cline release, and choosing the model an unattended
 # agent runs on is the operator's call. Absent, the launch refuses and says so.
 #
-# base_url absent means the Anthropic path through dejima's credential proxy.
-# Set, it means a self-hosted endpoint, and the plugin refuses one that is not
-# host-local - see bin/harness/cline.sh for why that is an R5 check.
+# base_url is NOT here. Where the model is belongs to the backend: a
+# self-served one carries its own [backend.<name>] base_url, which is what
+# lets an operator keep a local endpoint configured while using a hosted API
+# and switch between them by changing one word.
 # context_window is the one Cline cannot work out for itself. It budgets
 # against its own catalogue, and for a model it does not recognise - which is
 # every self-served one - it has no budget at all, so it grows the conversation
@@ -77,7 +80,18 @@ no_confirm_args    = --auto-approve true
 # compacts constantly. Set it a little under whatever the server allows -
 # Cline's accounting is approximate and a compaction does not always land
 # under target when a single tool result is large.
-keys               = state_dir:path=~/.local/share/dejima/cline model:?identifier base_url:?url context_window:?int:512:100000000
+# See claude-code's manifest for why this is per harness and why it has no
+# default. The risk is concrete here rather than theoretical: Cline supports
+# many backends and has one of its own, so any value dejima shipped
+# would be dejima choosing an endpoint on the operator's behalf, and changing
+# it later would move a running setup without touching its config.
+#
+# And no assumed_backend either, deliberately. What this harness was talking
+# to before the key existed depends on base_url - unset meant Anthropic, set
+# meant a model the operator serves - so there is no single value to record,
+# and recording the wrong one would write a proxied endpoint into the config
+# of a session that never used one. Making the two coherent is its own change.
+keys               = backend:?provider:backend state_dir:path=~/.local/share/dejima/cline model:?modelid context_window:?int:512:100000000
 
 # Deliberately empty: resuming needs the state directory's path as well as the
 # session id, briefing placeholders do not nest, and `template` forbids the

hooks/sandbox-context.sh

@@ -41,11 +41,11 @@ if [ "${DEJIMA_BRIEFING_VIA_ARGS:-0}" = "1" ]; then
 fi
 
 # The image's copy first, because that is the one that exists in a real
-# session: this file reaches the container through the ~/.claude/hooks mount,
-# and install.sh links it there one file at a time, so its sibling in the repo
-# is not alongside it. The sibling is the fallback so the hook can be run
+# session: this file is baked in beside it and registered by absolute path
+# into the sandbox's --settings overlay, so nothing about it depends on the
+# operator's ~/.claude. The sibling is the fallback so the hook can be run
 # against a checkout - which is what the test suite does - and readlink -f is
-# what turns the linked path back into the repo one.
+# what turns a linked path back into the repo one.
 #
 # Missing or unreadable degrades to no briefing rather than failing the hook:
 # a SessionStart hook that exits non-zero drops the whole session's context,

install.sh

@@ -1,10 +1,13 @@
 #!/bin/bash
-# Idempotent installer for dejima. Registers the selected harness's guard
-# hooks wherever that harness reads them from, and puts
+# Idempotent installer for dejima. Writes NOTHING to the harness's own
+# configuration: every hook dejima uses is baked into the image and registered
+# per launch into a settings layer of dejima's own, so installing this does not
+# change how the harness behaves outside a sandbox. What it still does is take
+# back what older versions put there. It puts
 # bin/dejima, bin/dejima-allow, bin/dejima-dep, bin/dejima-project,
-# bin/dejima-audit and the opt-in remote-access scripts on PATH. Safe to
-# re-run - every step is a no-op if already done, and every change is
-# printed as it happens.
+# bin/dejima-audit, bin/dejima-share and the opt-in remote-access scripts on
+# PATH. Safe to re-run - every step is a no-op if already done, and every
+# change is printed as it happens.
 #
 # It never enables anything: the remote-access scripts do nothing without
 # [remote-access] enabled = on in ~/.config/dejima/config, and the user units
@@ -76,6 +79,10 @@ link_bin dejima-project
 # operator to run `dejima-audit ack`, which is only true once it is on PATH.
 link_bin dejima-audit
 link_bin dejima-epitaph
+# ~/shared is one directory per project now, so "where do I put a file for the
+# next session" has an answer only this can give - and the launch notice about
+# files left over from the old layout tells the operator to run it.
+link_bin dejima-share
 link_bin dejima-update-check
 
 # Remote access (opt-in, see docs/remote-access.md). All three are inert
@@ -195,8 +202,11 @@ fi
 # Registering before reading it would mean writing one harness's config for
 # an operator who has chosen another.
 #
-# Delegated to the harness's plugin, which is also what gates each guard on
-# the harness having declared it (see `guards` in its manifest).
+# Nothing to register: the sandbox's hooks are baked into the image and
+# registered per launch into its own settings overlay. What is delegated to
+# the plugin is the host-side cleanup an upgrade needs - taking back what
+# older versions wrote into the harness's config - which still has to know
+# which harness is selected.
 echo
 source "$SCRIPT_DIR/bin/dejima-harness-lib.sh"
 # A config that does not parse leaves config_get empty for EVERY key, so
@@ -205,20 +215,20 @@ source "$SCRIPT_DIR/bin/dejima-harness-lib.sh"
 # fault, on stderr, which is the answer to a question this cannot answer.
 _harness=""
 if config_exists && ! config_validate; then
-    echo "$CONFIG_FILE could not be read, so no guard hooks were registered."
+    echo "$CONFIG_FILE could not be read, so no harness host-side setup was checked."
     echo "Fix what is reported above and re-run ./install.sh."
 elif ! _harness="$(config_get core harness 2>/dev/null)" || [ -z "$_harness" ]; then
     _harness=""
-    echo "No [core] harness is set in $CONFIG_FILE, so no guard hooks were"
-    echo "registered. Set one and re-run ./install.sh."
+    echo "No [core] harness is set in $CONFIG_FILE, so no harness host-side"
+    echo "setup was checked. Set one and re-run ./install.sh."
 else
     DEJIMA_HARNESS_NAME="$_harness"
     harness_plugin_load "$_harness"
     if declare -F harness_register_guards >/dev/null 2>&1; then
-        echo "Registering $_harness's guard hooks"
+        echo "Checking $_harness's host-side setup"
         harness_register_guards "$SCRIPT_DIR" "$BACKUP_DIR"
     else
-        echo "Harness '$_harness' installs no guard hooks."
+        echo "Harness '$_harness' needs nothing on the host."
         echo
     fi
 fi

test/audit.bats

@@ -629,10 +629,21 @@ EOF
     printf 'keep = 10\n' >> "$CONFIG_DIR/config"
     snap; git -C "$WS" config user.name changed
     chmod 500 "$AUDITDIR/$slug"
-    run timeout 5 "$AUDIT" compare "$WS" "$STATE"
+    # The subject is FOREVER, not fast. Rotation trims oldest-first and breaks
+    # when the unlink fails; without that break the loop's condition never
+    # changes and it spins. Any finite bound catches that, so the bound is
+    # generous on purpose: a five-second one was timing the machine, and on a
+    # loaded one a correct run exceeded it and reported a spin that had not
+    # happened (#295).
+    run timeout 120 "$AUDIT" compare "$WS" "$STATE"
     result="$status"
     chmod 700 "$AUDITDIR/$slug"
-    [ "$result" -ne 124 ]
+    [ "$result" -ne 124 ] || { echo "rotation did not terminate"; return 1; }
+    # And it gave up rather than evicting: an unwritable directory means every
+    # planted report is still there. Without this the test says only that the
+    # command exited, which a rotation that silently did nothing also satisfies.
+    [ "$(find "$AUDITDIR/$slug" -maxdepth 1 -name '2026-01-01-*.txt' | wc -l)" -eq 12 ] \
+        || { echo "reports were evicted from a directory that cannot be written"; return 1; }
 }
 
 # One `ack` run used to walk one report and exit, saying nothing about the

test/conversation.bats

@@ -29,17 +29,25 @@ teardown() {
 # A real HTTP server standing in for Loki, appending each pushed body to a
 # file. Real because the shipper reaches it with curl: a stub that replaced
 # curl would stop testing the thing that formats and sends the payload.
+# The server binds port 0 itself and reports what it got, rather than a helper
+# picking a free port and handing the number over.
+#
+# That handover was a race, and `bats --jobs` is what makes it fire: the helper
+# bound port 0, read the number, CLOSED the socket, and only then did the
+# server bind it. Another test starting in that window takes the same port, and
+# the loser dies with "Address already in use" - but the readiness probe below
+# still succeeds, because something IS listening on that port. The test then
+# ships to the other test's Loki, finds its own log empty, and reports the
+# failure as a lost transcript. Seen in CI, not locally: it needs enough cores
+# for two tests to be in that window at once.
 start_loki() {
-    LOKI_PORT="$(python3 - <<'EOF'
-import socket
-s = socket.socket(); s.bind(("127.0.0.1", 0)); print(s.getsockname()[1]); s.close()
-EOF
-)"
-    python3 - "$LOKI_PORT" "$LOKI_LOG" <<'EOF' &
-import sys
+    local portfile="$BATS_TEST_TMPDIR/loki-port"
+    rm -f "$portfile"
+    python3 - "$portfile" "$LOKI_LOG" <<'EOF' &
+import sys, os
 from http.server import BaseHTTPRequestHandler, HTTPServer
 
-port, path = int(sys.argv[1]), sys.argv[2]
+portfile, path = sys.argv[1], sys.argv[2]
 
 class H(BaseHTTPRequestHandler):
     def do_POST(self):
@@ -51,12 +59,26 @@ class H(BaseHTTPRequestHandler):
     def log_message(self, *a):
         pass
 
-HTTPServer(("127.0.0.1", port), H).serve_forever()
+srv = HTTPServer(("127.0.0.1", 0), H)
+# Written only once the socket is bound and listening, and atomically, so the
+# shell can never read a half-written number or one for a socket that is gone.
+tmp = portfile + ".tmp"
+with open(tmp, "w") as f:
+    f.write(str(srv.server_address[1]))
+os.replace(tmp, portfile)
+srv.serve_forever()
 EOF
     LOKI_PID=$!
     local i
-    for i in $(seq 1 50); do
-        (exec 3<>/dev/tcp/127.0.0.1/"$LOKI_PORT") 2>/dev/null && return 0
+    for i in $(seq 1 100); do
+        if [ -s "$portfile" ]; then
+            LOKI_PORT="$(cat "$portfile")"
+            return 0
+        fi
+        # A server that died on startup will never write the file, and waiting
+        # the full timeout for a process that is already gone only delays the
+        # real message.
+        kill -0 "$LOKI_PID" 2>/dev/null || break
         sleep 0.1
     done
     echo "the fake Loki never came up" >&2
@@ -106,6 +128,23 @@ await_shipped() {
     return 1
 }
 
+# Blocks until the shipper has finished a poll and is asleep between polls.
+# The two SIGTERM tests below need exactly that state - the trap installed, one
+# scan done - and both used to state it by sleeping for a second. That is a
+# statement about the machine rather than about the shipper: under load the
+# startup that precedes the trap takes longer than the sleep, the TERM lands
+# before there is a trap to catch it, and the process dies flushing nothing.
+# The nap is a child `sleep` of the shipper, which makes the state observable.
+await_napping() {
+    local i
+    for i in $(seq 1 200); do
+        pgrep -P "$SHIP_PID" -x sleep >/dev/null 2>&1 && return 0
+        sleep 0.05
+    done
+    echo "the shipper never reached its first nap" >&2
+    return 1
+}
+
 @test "a line is shipped to Loki while the session runs" {
     start_loki
     write_config
@@ -156,10 +195,11 @@ await_shipped() {
     write_config
     mkdir -p "$(slug_dir)"
     start_ship
-    # Long enough for one poll to read the line into the batch, short enough
-    # that the 2s batch interval has not flushed it on its own.
+    # Written before the first poll, so the poll reads it into the batch; the
+    # kill then lands while the shipper is asleep with it still in there,
+    # because the batch interval has not elapsed since it started.
     say "already batched" >> "$(slug_dir)/s1.jsonl"
-    sleep 1
+    await_napping
     kill -TERM "$SHIP_PID"
     wait "$SHIP_PID" 2>/dev/null || true
     SHIP_PID=""
@@ -172,10 +212,11 @@ await_shipped() {
     write_config
     mkdir -p "$(slug_dir)"
     start_ship
-    # Written and killed inside one poll interval, so nothing has read it yet:
-    # only the trap's own rescan can find it. A final_flush that flushed the
-    # batch without rescanning would pass the test above and fail this one.
-    sleep 1
+    # Written after a poll has already run and killed before the next one, so
+    # nothing has read it yet: only the trap's own rescan can find it. A
+    # final_flush that flushed the batch without rescanning would pass the test
+    # above and fail this one.
+    await_napping
     say "the final answer" >> "$(slug_dir)/s1.jsonl"
     kill -TERM "$SHIP_PID"
     wait "$SHIP_PID" 2>/dev/null || true
@@ -352,3 +393,64 @@ EOF
     run grep -c "should not ship" "$LOKI_LOG"
     [ "$output" -eq 0 ] || { echo "shipped without a resolvable layout: $(shipped)"; return 1; }
 }
+
+@test "the tail survives a kill even when the harness declares an optional key with no default" {
+    # #284, and it is worth pinning by SHAPE rather than by the key that
+    # exposed it. Any optional keyspec with an empty default in the selected
+    # harness's `keys` used to make final_flush's config lookup fail: it
+    # re-resolves the transcript paths from the SIGTERM handler, and bash
+    # reports 128+n for commands completing while it delivers a signal, so a
+    # perfectly valid manifest was rejected and the tail - usually the agent's
+    # final answer, which is the whole reason final_flush exists - was dropped
+    # with no error the operator would ever see.
+    #
+    # Nothing shipped for claude-code had that shape until #171 added one, so
+    # this adds one of its own rather than depending on a real key keeping it.
+    # A provider root of its own, so the shipped manifests are not edited and
+    # a concurrent run is unaffected.
+    local proot="$BATS_TEST_TMPDIR/proot"
+    mkdir -p "$proot"
+    # Loudly: a partial copy here produces exactly the symptom this test is
+    # about - a lookup that fails - and swallowing the error would report the
+    # fixture's fault as the code's.
+    cp -a "$REPO_ROOT/forges" "$REPO_ROOT/workflows" "$REPO_ROOT/harnesses" \
+          "$REPO_ROOT/backends" "$proot/" \
+        || { echo "could not build the probe provider root"; return 1; }
+    local axis
+    for axis in forges workflows harnesses backends; do
+        [ -d "$proot/$axis" ] || { echo "the probe provider root has no $axis/"; return 1; }
+    done
+    sed -i 's/^keys \( *\)=/keys \1= probe_only_key:?identifier/' \
+        "$proot/harnesses/claude-code/harness.conf"
+    grep -q 'probe_only_key:?identifier' "$proot/harnesses/claude-code/harness.conf" \
+        || { echo "the probe key was not injected"; return 1; }
+    export DEJIMA_PROVIDER_ROOT="$proot"
+
+    start_loki
+    write_config
+    mkdir -p "$(slug_dir)"
+    start_ship
+
+    # Wait for the shipper to be demonstrably running rather than sleeping at
+    # it. A fixed sleep is a second race on a loaded machine: if the process
+    # is still starting when the signal arrives, the handler runs before the
+    # key schema has been resolved, which fails for the ORIGINAL #284 reason
+    # and would read as this fix not working.
+    say "a first line" >> "$(slug_dir)/s1.jsonl"
+    await_shipped "a first line" || { echo "the shipper never started"; return 1; }
+
+    say "the final answer" >> "$(slug_dir)/s1.jsonl"
+    kill -TERM "$SHIP_PID"
+    wait "$SHIP_PID" 2>/dev/null || true
+    SHIP_PID=""
+    # Wait for the line rather than reading the log the instant the shipper
+    # exits. `wait` returns when the SHIPPER is gone, which says nothing about
+    # the collector on the other end having written what it was sent - so
+    # reading immediately is a race the loaded machine loses, and it fails as
+    # "the tail was lost", which is precisely this test's bug signature (#295).
+    await_shipped "the final answer" \
+        || { echo "the unread tail was lost: $(shipped)"; return 1; }
+    # And the lookup did not merely survive - it never failed. That message
+    # reaching an operator's terminal is the visible half of this bug.
+    [[ "$(shipped)" != *"unknown config key"* ]] || { echo "$(shipped)"; return 1; }
+}

test/fixtures/answer-prompt.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Runs a command on a real pty and answers its prompts.
+
+The credential scan only asks when stdin is a terminal, which is the whole
+point - an unattended launch must not block on a question nobody will see. So
+a test that drives the interactive path needs a pty rather than a pipe, or it
+exercises the non-interactive branch while claiming to test the other one.
+
+Usage: answer-prompt.py [--marker TEXT] <answer-per-prompt>... -- <command> [args...]
+
+Each answer is sent when the child writes a line ending in the prompt marker.
+Everything the child wrote is printed on exit, and the child's exit status is
+this program's.
+"""
+
+import os
+import pty
+import signal
+import re
+import select
+import sys
+import time
+
+# The default is the credential scan's prompt. --marker takes another, so a
+# test for a different prompt does not need a second copy of this.
+MARKER = "[s/a/o/r]"
+
+# dejima pauses before the image build when it printed a notice worth reading.
+# That is not the prompt any test here is about - it is ambient, and every
+# launch fixture that sets [core] ssh_key raises it - so it is answered
+# automatically rather than costing every caller an extra argument.
+AMBIENT = "Press Enter to continue"
+# An IDLE timeout: how long to wait with no output before giving up. Generous
+# because the thing it guards against is a command that never finishes, and
+# any finite bound catches that - while a tight one just times the machine.
+# Sixty seconds was enough on an idle box and not enough under the full gate,
+# where every suite runs at once (#295).
+TIMEOUT = 240.0
+
+
+def main():
+    if "--" not in sys.argv:
+        print("usage: answer-prompt.py <answer>... -- <command>...", file=sys.stderr)
+        return 2
+    split = sys.argv.index("--")
+    args = list(sys.argv[1:split])
+    global MARKER
+    if "--marker" in args:
+        i = args.index("--marker")
+        MARKER = args[i + 1]
+        del args[i:i + 2]
+    answers = args
+    command = sys.argv[split + 1:]
+    if not command:
+        print("no command given", file=sys.stderr)
+        return 2
+
+    pid, fd = pty.fork()
+    if pid == 0:
+        # The child: a session leader with this pty as its controlling
+        # terminal, which is what makes `[ -t 0 ]` true inside dejima.
+        try:
+            os.execvp(command[0], command)
+        except OSError as e:
+            print("exec failed: %s" % e, file=sys.stderr)
+            os._exit(127)
+
+    out = []
+    pending = list(answers)
+    deadline = TIMEOUT
+    while True:
+        r, _, _ = select.select([fd], [], [], deadline)
+        if not r:
+            out.append("\n[answer-prompt: timed out waiting for output]\n")
+            break
+        try:
+            chunk = os.read(fd, 4096)
+        except OSError:
+            break
+        if not chunk:
+            break
+        text = chunk.decode("utf-8", "replace")
+        out.append(text)
+        # Answer only when the prompt is the most recent thing written, so a
+        # marker appearing inside prose does not consume an answer.
+        if pending and MARKER in text:
+            os.write(fd, (pending.pop(0) + "\n").encode())
+        elif AMBIENT in text and AMBIENT != MARKER:
+            os.write(fd, b"\n")
+
+    # The read loop ends when the child stops WRITING, which is not when it
+    # stops running: dejima does its exit audit and stops its shipper after
+    # the last thing it prints. So give it a grace period to finish before
+    # concluding anything - killing it there reported a child that was merely
+    # busy as a hang, and left it taking SIGPIPE on a pty nobody was reading.
+    #
+    # Only then kill, because an unanswered prompt is the other way this ends
+    # and waiting on that turns a failing test into a hung suite. The caller
+    # is told which it was.
+    stuck = False
+    status = 0
+    grace = time.time() + 60.0
+    try:
+        while True:
+            done, status = os.waitpid(pid, os.WNOHANG)
+            if done != 0:
+                break
+            if time.time() >= grace:
+                stuck = True
+                os.kill(pid, signal.SIGKILL)
+                _, status = os.waitpid(pid, 0)
+                break
+            time.sleep(0.1)
+    except OSError:
+        status = 0
+    sys.stdout.write("".join(out))
+    if pending:
+        sys.stdout.write("\n[answer-prompt: %d answer(s) never used]\n" % len(pending))
+    if stuck:
+        sys.stdout.write("\n[answer-prompt: the command never exited - killed. "
+                         "It was probably waiting at a prompt nothing answered.]\n")
+    return os.waitstatus_to_exitcode(status) if hasattr(os, "waitstatus_to_exitcode") \
+        else (status >> 8)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

test/fixtures/tty-suspend-harness.py

@@ -118,8 +118,8 @@ finally:
 # TTY_SUSPEND_NO_HELPER leaves the helper out, which is dejima before this
 # existed. It is the control: a harness that cannot see the bug cannot be
 # trusted to see the fix either.
-start_helper = "" if os.environ.get("TTY_SUSPEND_NO_HELPER") else \
-    '"%s" &\nhelper=$!' % HELPER
+HELPER_EXPECTED = not os.environ.get("TTY_SUSPEND_NO_HELPER")
+start_helper = '"%s" &\nhelper=$!' % HELPER if HELPER_EXPECTED else ""
 # bin/dejima's shape: the client inherits SIGTSTP ignored and is started with
 # the terminal, and the keystroke is converted into an explicit SIGSTOP for it
 # before the launcher stops itself. Without the conversion the client is the
@@ -221,6 +221,53 @@ def lflag():
     return termios.tcgetattr(master)[3]
 
 
+def reclaimed():
+    """True once dejima-tty-suspend has taken ^Z back from the container's raw mode.
+
+    Read off the pty rather than inferred from output, and specific enough to
+    mean only the helper. Raw mode has ISIG off; a plain shell has ISIG on with
+    intr at ^C. Only the helper leaves ISIG on, susp at ^Z, and intr undefined
+    - which is the whole of what it does, so this is the feature's precondition
+    stated exactly.
+    """
+    attrs = termios.tcgetattr(master)
+    cc = attrs[6]
+    return bool(attrs[3] & termios.ISIG) \
+        and cc[termios.VSUSP] == b"\x1a" \
+        and cc[termios.VINTR] == b"\x00"
+
+
+def await_reclaim(timeout=10.0):
+    end = time.time() + timeout
+    while time.time() < end:
+        if reclaimed():
+            return True
+        pump(0.05)
+    return reclaimed()
+
+
+def raw_restored():
+    """True once the resumed client has put the terminal back into raw mode."""
+    flags = lflag()
+    return not (flags & termios.ICANON) and not (flags & termios.ECHO)
+
+
+def await_raw(timeout=15.0):
+    """Wait for that, rather than reading the flags at a fixed moment after fg.
+
+    `fg` returns as soon as the job is continued; the client sets raw mode some
+    scheduling later. Sampling the flags right after fg was timing the machine,
+    and on a loaded one it read the shell's own canonical mode and reported it
+    as a failure to restore - the same shape as the reclaim wait above.
+    """
+    end = time.time() + timeout
+    while time.time() < end:
+        if raw_restored():
+            return True
+        pump(0.05)
+    return raw_restored()
+
+
 def received():
     try:
         with open(RECEIVED, "rb") as fh:
@@ -242,6 +289,27 @@ try:
     check("the container run attached", expect("CONTAINER-ATTACHED"))
 
     for cycle in (1, 2):
+        # Wait for the helper to hold the terminal before typing at it (#262).
+        #
+        # CONTAINER-ATTACHED is printed by the stand-in immediately after it
+        # sets raw mode, so it marks the START of the window this feature
+        # exists to close, not the end. The helper only acts once it has POLLED
+        # the terminal and seen -isig, so between those two moments ^Z is still
+        # the byte 0x1a. Sending into that window put the byte in the container
+        # and failed `nothing-reached-the-container` - the security assertion -
+        # on a machine where nothing was wrong but the scheduling.
+        #
+        # Waiting for the precondition rather than lengthening the deadline
+        # after it: with the terminal provably converting ^Z to a signal before
+        # anything is typed, that check can no longer fail for timing reasons
+        # at all, which is the point. A longer timeout would only have narrowed
+        # the window.
+        #
+        # Skipped without the helper, where the byte reaching the container is
+        # the expected result and this would never come true.
+        if HELPER_EXPECTED:
+            check("cycle%d-suspend-char-reclaimed" % cycle, await_reclaim(),
+                  "dejima-tty-suspend never took ^Z back from raw mode")
         before = received()
         forget()
         send("\x1a")
@@ -255,12 +323,11 @@ try:
               expect("SHELL-ALIVE-%d" % cycle, 5.0))
         forget()
         send("fg\n")
-        expect("CONTAINER-REDRAW", 5.0)
+        restored = await_raw()
         flags = lflag()
-        check("cycle%d-raw-mode-restored" % cycle,
-              not (flags & termios.ICANON) and not (flags & termios.ECHO),
+        check("cycle%d-raw-mode-restored" % cycle, restored,
               "ICANON=%s ECHO=%s" % (bool(flags & termios.ICANON), bool(flags & termios.ECHO)))
-        check("cycle%d-redraw-poked" % cycle, "CONTAINER-REDRAW" in "".join(seen))
+        check("cycle%d-redraw-poked" % cycle, expect("CONTAINER-REDRAW", 15.0))
         check("cycle%d-session-alive" % cycle, "LAUNCHER-DONE" not in "".join(seen))
 
     before = received()

test/project.bats

@@ -98,7 +98,8 @@ launch() {
     # launch is what triggers it. Its cache needs nothing further: it lands
     # under $HOME, which every launch fixture already points somewhere of its
     # own.
-    printf '[core]\nharness = claude-code\nupdate_check = off\nssh_key = %s\n' \
+    # backend is stated, not defaulted: it has none and never will (#171).
+    printf '[core]\nharness = claude-code\nupdate_check = off\nssh_key = %s\n[harness.claude-code]\nbackend = anthropic\n' \
         "$LAUNCH_DIR/sandbox-key" >> "$conf"
     HOME="$LAUNCH_DIR/home" PATH="$LAUNCH_DIR:$PATH" \
         SANDBOX_TEST_RUN_ENV="$LAUNCH_ENV" \
@@ -981,7 +982,7 @@ ENTRYPOINT [\"/usr/local/bin/entrypoint.sh\"]" ]]
     # no domains at all, or by the env prefix below never reaching the child.
     printf 'good.example.com\n' > "$CONFIG_DIR/allowed-domains"
     launch_setup
-    printf '[core]\nharness = claude-code\nssh_key = %s\n' "$LAUNCH_DIR/sandbox-key" >> "$CONFIG_DIR/config"
+    printf '[core]\nharness = claude-code\nssh_key = %s\n[harness.claude-code]\nbackend = anthropic\n' "$LAUNCH_DIR/sandbox-key" >> "$CONFIG_DIR/config"
     HOME="$LAUNCH_DIR/home" PATH="$LAUNCH_DIR:$PATH" \
         SANDBOX_TEST_RUN_ENV="$LAUNCH_ENV" \
         SSH_AUTH_SOCK= ALLOWED_DOMAINS=evil.example \
@@ -1066,13 +1067,13 @@ ENTRYPOINT [\"/usr/local/bin/entrypoint.sh\"]" ]]
     launch_setup
     run launch "$PROJ"
     [ "$status" -eq 0 ]
-    [ "$(launched_env SANDBOX_IMAGE)" = "dejima:$(id -un)-harness-claude-code" ]
+    [ "$(launched_env SANDBOX_IMAGE)" = "localhost/dejima:$(id -un)-harness-claude-code" ]
 
     "$REPO_ROOT/bin/dejima-dep" add --project "$PROJ" apt:libpq-dev >/dev/null
     run launch "$PROJ"
     [ "$status" -eq 0 ]
     slug="$(bash -c 'source "$1"; project_slug "$2"' _ "$LIB" "$PROJ")"
-    [ "$(launched_env SANDBOX_IMAGE)" = "dejima:$(id -un)-$slug" ]
+    [ "$(launched_env SANDBOX_IMAGE)" = "localhost/dejima:$(id -un)-$slug" ]
 }
 
 # nvim's data/state/cache are Docker volumes, not host paths, so nothing a
@@ -1116,8 +1117,8 @@ ENTRYPOINT [\"/usr/local/bin/entrypoint.sh\"]" ]]
     launch_setup
     run launch "$PROJ"
     [ "$status" -eq 0 ]
-    grep -q -- "-t dejima:$(id -un)-global -f" <(docker_log)
-    [ "$(launched_env SANDBOX_IMAGE)" = "dejima:$(id -un)-global" ]
+    grep -q -- "-t localhost/dejima:$(id -un)-global -f" <(docker_log)
+    [ "$(launched_env SANDBOX_IMAGE)" = "localhost/dejima:$(id -un)-global" ]
 }
 
 @test "the launcher builds the global layer then the project layer on top of it" {
@@ -1127,12 +1128,12 @@ ENTRYPOINT [\"/usr/local/bin/entrypoint.sh\"]" ]]
     run launch "$PROJ"
     [ "$status" -eq 0 ]
     slug="$(bash -c 'source "$1"; project_slug "$2"' _ "$LIB" "$PROJ")"
-    global_line=$(grep -n -- "-t dejima:$(id -un)-global -f" <(docker_log) | cut -d: -f1)
-    project_line=$(grep -n -- "-t dejima:$(id -un)-$slug -f" <(docker_log) | cut -d: -f1)
+    global_line=$(grep -n -- "-t localhost/dejima:$(id -un)-global -f" <(docker_log) | cut -d: -f1)
+    project_line=$(grep -n -- "-t localhost/dejima:$(id -un)-$slug -f" <(docker_log) | cut -d: -f1)
     [ -n "$global_line" ]
     [ -n "$project_line" ]
     [ "$global_line" -lt "$project_line" ]
-    [ "$(launched_env SANDBOX_IMAGE)" = "dejima:$(id -un)-$slug" ]
+    [ "$(launched_env SANDBOX_IMAGE)" = "localhost/dejima:$(id -un)-$slug" ]
 }
 
 @test "the project layer's Dockerfile is generated FROM the global layer, not the base image" {
@@ -1148,11 +1149,11 @@ ENTRYPOINT [\"/usr/local/bin/entrypoint.sh\"]" ]]
     [ "$status" -eq 0 ]
     slug="$(bash -c 'source "$1"; project_slug "$2"' _ "$LIB" "$PROJ")"
     # base -> harness -> global -> project, each FROM the one before it.
-    dockerfile_for "dejima:$(id -un)-harness-claude-code" \
-        | grep -qxF "FROM dejima:$(id -un)"
-    dockerfile_for "dejima:$(id -un)-global" \
-        | grep -qxF "FROM dejima:$(id -un)-harness-claude-code"
-    dockerfile_for "dejima:$(id -un)-$slug" | grep -qxF "FROM dejima:$(id -un)-global"
+    dockerfile_for "localhost/dejima:$(id -un)-harness-claude-code" \
+        | grep -qxF "FROM localhost/dejima:$(id -un)"
+    dockerfile_for "localhost/dejima:$(id -un)-global" \
+        | grep -qxF "FROM localhost/dejima:$(id -un)-harness-claude-code"
+    dockerfile_for "localhost/dejima:$(id -un)-$slug" | grep -qxF "FROM localhost/dejima:$(id -un)-global"
 }
 
 @test "the launcher builds no dependency layer when neither global nor project deps are approved" {
@@ -1163,10 +1164,10 @@ ENTRYPOINT [\"/usr/local/bin/entrypoint.sh\"]" ]]
     # harness in the image - so this is about the DEPENDENCY layers, which is
     # what "no approved dependencies" is a statement about.
     local tagged
-    tagged="$(grep -oE -- '-t dejima:[^ ]+' <(docker_log) | sed 's/^-t //' | sort -u)"
-    [ "$tagged" = "dejima:$(id -un)-harness-claude-code" ] \
+    tagged="$(grep -oE -- '-t localhost/dejima:[^ ]+' <(docker_log) | sed 's/^-t //' | sort -u)"
+    [ "$tagged" = "localhost/dejima:$(id -un)-harness-claude-code" ] \
         || { echo "expected only the harness layer to be built, got:"; echo "$tagged"; return 1; }
-    [ "$(launched_env SANDBOX_IMAGE)" = "dejima:$(id -un)-harness-claude-code" ]
+    [ "$(launched_env SANDBOX_IMAGE)" = "localhost/dejima:$(id -un)-harness-claude-code" ]
 }
 
 @test "the launcher warns when the approval store sits inside the mounted workspace" {

test/providers.bats

@@ -1045,11 +1045,34 @@ assert_remedy_forges_exist() {
     # with (#187). The guard is generic; the manifest is what makes it fire.
     [ "$(lib manifest_get forge github repo_flags)" = "--repo -R" ]
     [ "$(lib manifest_get forge github repo_env)" = "GH_REPO" ]
+    # And in a path rather than a flag: `gh api repos/<owner>/<name>/...`
+    # names a repository with no --repo in it at all (#243).
+    [ "$(lib manifest_get forge github repo_paths)" = "api:repos" ]
     # The gitea CLIs resolve the repo from origin and refuse another host, so
     # there is nothing to declare and nothing for the guard to compare. A
     # forge is not required to be aimable.
     [ -z "$(lib manifest_get forge gitea repo_flags)" ]
     [ -z "$(lib manifest_get forge gitea repo_env)" ]
+    [ -z "$(lib manifest_get forge gitea repo_paths)" ]
+}
+
+@test "a repo path has to name a subcommand and a segment" {
+    # `<subcommand>:<first segment>`. The subcommand half is what keeps the
+    # guard from comparing every positional argument that contains two
+    # slashes, so a spelling that omits it is not a narrower declaration - it
+    # is one that would refuse an issue title.
+    local d bad; d="$(mktemp -d "$BATS_TEST_TMPDIR/pathtype.XXXXXX")"
+    mkdir -p "$d/forges/probe"
+    for bad in "repos" "api:" ":repos" "api:repos/more" "api:/repos" "-api:repos"; do
+        printf 'repo_paths = %s\n' "$bad" > "$d/forges/probe/forge.conf"
+        run env DEJIMA_PROVIDER_ROOT="$d" \
+            bash -c 'source "$1"; manifest_validate forge probe' _ "$LIB"
+        [ "$status" -ne 0 ] || { echo "accepted repo_paths = $bad"; return 1; }
+    done
+    printf 'repo_paths = api:repos\n' > "$d/forges/probe/forge.conf"
+    run env DEJIMA_PROVIDER_ROOT="$d" \
+        bash -c 'source "$1"; manifest_validate forge probe' _ "$LIB"
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
 }
 
 @test "a repo flag has to look like a flag" {
@@ -1322,3 +1345,312 @@ assert_remedy_forges_exist() {
         done
     done
 }
+
+# --- the model provider axis (#171) ------------------------------------------
+
+@test "the anthropic backend manifest validates and answers for every field" {
+    lib manifest_validate backend anthropic
+    [ "$(lib manifest_get backend anthropic upstream)" = "https://api.anthropic.com" ]
+    [ "$(lib manifest_get backend anthropic proxied_domain)" = "api.anthropic.com" ]
+    [ "$(lib manifest_get backend anthropic credential)" = "anthropic-oauth" ]
+    [ "$(lib manifest_get backend anthropic auth_format)" = "Bearer {token}" ]
+    [ "$(lib manifest_get backend anthropic strip_headers)" = "x-api-key" ]
+    [ "$(lib manifest_get backend anthropic ensure_headers)" = "anthropic-beta=oauth-2025-04-20" ]
+}
+
+@test "a backend's own keys become [backend.<name>] config keys" {
+    # The same machinery a forge's keys go through, so a backend declaring
+    # where its credential lives needs no row hardcoded in core's schema.
+    [ "$(lib config_type backend.anthropic.credential_file)" = "path" ]
+    run lib config_type backend.anthropic.not_a_key
+    [ "$status" -ne 0 ]
+}
+
+@test "an auth_format with no token placeholder is refused by the schema" {
+    # The proxy refuses it too. Refusing it here as well is the difference
+    # between finding out at launch and finding out from a provider's 401:
+    # a format without {token} produces a proxy that starts, answers, and
+    # sends every request unauthenticated.
+    local d; d="$(mktemp -d "$BATS_TEST_TMPDIR/authfmt.XXXXXX")"
+    mkdir -p "$d/backends/probe"
+    _probe() {
+        printf 'upstream = https://x.example\nproxied_domain = x.example\ncredential = static\nauth_format = %s\n' "$1" \
+            > "$d/backends/probe/backend.conf"
+        run env DEJIMA_PROVIDER_ROOT="$d" \
+            bash -c 'source "$1"; manifest_validate backend probe' _ "$LIB"
+    }
+    _probe 'Bearer'
+    [ "$status" -ne 0 ] || { echo "a format with no {token} was accepted"; return 1; }
+    _probe 'Bearer {token}'
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
+    _probe '{token}'
+    [ "$status" -eq 0 ] || { echo "a bare-key format was refused: $output"; return 1; }
+}
+
+@test "an ensure_headers entry has to be NAME=VALUE with a header-shaped name" {
+    # envpair would refuse anthropic-beta outright: it wants an upper-case
+    # environment variable, and a header name is lower case with dashes.
+    local d; d="$(mktemp -d "$BATS_TEST_TMPDIR/ensure.XXXXXX")"
+    mkdir -p "$d/backends/probe"
+    _ensure() {
+        printf 'upstream = https://x.example\nproxied_domain = x.example\ncredential = static\nensure_headers = %s\n' "$1" \
+            > "$d/backends/probe/backend.conf"
+        run env DEJIMA_PROVIDER_ROOT="$d" \
+            bash -c 'source "$1"; manifest_validate backend probe' _ "$LIB"
+    }
+    local bad
+    for bad in 'anthropic-beta' '=value' 'name=' 'has space=v'; do
+        _ensure "$bad"
+        [ "$status" -ne 0 ] || { echo "accepted ensure_headers = $bad"; return 1; }
+    done
+    _ensure 'anthropic-beta=oauth-2025-04-20'
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
+}
+
+@test "a backend name that is not a directory is refused by the config type" {
+    # The same provider:<axis> check core.forge and core.harness go through,
+    # so a typo names nothing rather than resolving somewhere.
+    run lib _config_valid_value provider:backend anthropic
+    [ "$status" -eq 0 ] || { echo "the shipped provider was refused: $output"; return 1; }
+    run lib _config_valid_value provider:backend no-such-provider
+    [ "$status" -ne 0 ] || { echo "a provider with no directory was accepted"; return 1; }
+    run lib _config_valid_value provider:backend ../etc
+    [ "$status" -ne 0 ] || { echo "a traversal was accepted"; return 1; }
+}
+
+@test "the backend is selected per harness, not globally" {
+    # An operator running Claude Code against Anthropic and Cline against
+    # something else is the ordinary case, and it is why this is not one
+    # [credentials] key. Each harness declares its own, with its own default.
+    [ "$(lib config_type harness.claude-code.backend)" = "?provider:backend" ]
+    [ "$(lib config_type harness.cline.backend)" = "?provider:backend" ]
+    # And NO default, on either. One that could change later would move a
+    # session to another endpoint without its config changing, which is the
+    # reason [core] harness has none either.
+    [ -z "$(lib config_default harness.claude-code.backend)" ] \
+        || { echo "claude-code ships a default backend"; return 1; }
+    [ -z "$(lib config_default harness.cline.backend)" ] \
+        || { echo "cline ships a default backend"; return 1; }
+    # And there is no global one to disagree with them.
+    run lib config_type credentials.backend
+    [ "$status" -ne 0 ] || { echo "a global backend key is back"; return 1; }
+}
+
+@test "a harness that declares no backend names no endpoint to proxy" {
+    # The self-served case: a model on the operator's own network needs no
+    # credential withheld because there is none, so a harness may decline to
+    # name a provider and the launch runs without a proxy.
+    local d; d="$(mktemp -d "$BATS_TEST_TMPDIR/noprov.XXXXXX")"
+    mkdir -p "$d/harnesses/bare"
+    printf 'command = true\n' > "$d/harnesses/bare/harness.conf"
+    run env DEJIMA_PROVIDER_ROOT="$d" \
+        bash -c 'source "$1"; config_type harness.bare.backend' _ "$LIB"
+    [ "$status" -ne 0 ] || { echo "a harness that declares nothing got a provider key"; return 1; }
+}
+
+@test "openrouter is declared as a static-key, openai-style backend" {
+    # The second shipped provider, and the case #171 was filed about: a hosted
+    # endpoint behind a static API key, which dejima previously had no answer
+    # for other than refusing it.
+    lib manifest_validate backend openrouter
+    [ "$(lib manifest_get backend openrouter upstream)" = "https://openrouter.ai/api/v1" ]
+    [ "$(lib manifest_get backend openrouter proxied_domain)" = "openrouter.ai" ]
+    [ "$(lib manifest_get backend openrouter api_style)" = "openai" ]
+    [ "$(lib manifest_get backend openrouter credential)" = "static" ]
+    # Both spellings an OpenAI-compatible client might use for a key, so a
+    # placeholder cannot travel beside the injected Authorization.
+    [ "$(lib manifest_get backend openrouter strip_headers)" = "x-api-key api-key" ]
+    # No default for the key's location and no assumed value: an unset one is
+    # a refusal at launch, not a guess at a path.
+    [ "$(lib manifest_get backend openrouter requires)" = "credential_file" ]
+    [ -z "$(lib config_default backend.openrouter.credential_file)" ]
+    # proxied_domain is the HOST alone. upstream carries the path; a
+    # certificate and a DNS pin are about a name.
+    [[ "$(lib manifest_get backend openrouter proxied_domain)" != */* ]]
+}
+
+@test "a self-served endpoint is a backend like any other" {
+    # Where the model is belongs to the provider, including when the operator
+    # serves it. That is what lets a local endpoint stay configured while a
+    # hosted API is selected: it is [backend.self-hosted] base_url, not a
+    # setting on the harness that has to be unset to get out of the way.
+    lib manifest_validate backend self-hosted
+    [ "$(lib manifest_get backend self-hosted credential)" = "none" ]
+    [ "$(lib manifest_get backend self-hosted api_style)" = "openai" ]
+    [ "$(lib manifest_get backend self-hosted requires)" = "base_url" ]
+    [ "$(lib config_type backend.self-hosted.base_url)" = "?url" ]
+    [ -z "$(lib config_default backend.self-hosted.base_url)" ] \
+        || { echo "self-hosted ships a default endpoint"; return 1; }
+    # upstream and proxied_domain describe an endpoint dejima stands in front
+    # of, and it stands in front of nothing here.
+    [ -z "$(lib manifest_get backend self-hosted upstream)" ]
+    [ -z "$(lib manifest_get backend self-hosted proxied_domain)" ]
+    # And the harness no longer carries one of its own to disagree with it.
+    run lib config_type harness.cline.base_url
+    [ "$status" -ne 0 ] || { echo "cline still declares base_url"; return 1; }
+}
+
+@test "a harness and a backend have to speak the same API" {
+    # Anthropic's Messages API is not OpenAI-compatible. Pairing a harness
+    # with a provider it has no client for is knowable at launch and produces
+    # nothing but confusion later, so both sides declare what they speak.
+    [ "$(lib manifest_get backend anthropic api_style)" = "anthropic" ]
+    [ "$(lib manifest_get harness claude-code api_styles)" = "anthropic" ]
+    # cline is the provider-agnostic one and says so.
+    [ "$(lib manifest_get harness cline api_styles)" = "anthropic openai" ]
+
+    # A dialect outside the two is refused by the schema. An ABSENT one is not
+    # - manifest_validate only type-checks the keys a file actually has, which
+    # is true of every axis and not something this one changed - so bin/dejima
+    # names the four a provider cannot work without where it reads them. That
+    # refusal is covered in config.bats, at the launch.
+    local d; d="$(mktemp -d "$BATS_TEST_TMPDIR/style.XXXXXX")"
+    mkdir -p "$d/backends/probe"
+    printf 'upstream = https://x.example\nproxied_domain = x.example\ncredential = static\napi_style = sideways\n' \
+        > "$d/backends/probe/backend.conf"
+    run env DEJIMA_PROVIDER_ROOT="$d" \
+        bash -c 'source "$1"; manifest_validate backend probe' _ "$LIB"
+    [ "$status" -ne 0 ] || { echo "an unknown api_style validated"; return 1; }
+}
+
+@test "the backend/harness matrix in the docs agrees with the manifests" {
+    # A compatibility table is derived data: every cell is the provider's
+    # api_style against the harness's api_styles. Written by hand it goes stale
+    # the first time a provider is added, and a stale one is worse than none -
+    # a reader trusts it and dejima refuses the launch.
+    #
+    # So it is recomputed here and compared cell by cell, rather than spot
+    # -checked. A new backend or harness that nobody adds a row for fails
+    # this, which is the point.
+    # Both copies, because the README carries a shorter one and two copies of
+    # derived data is two things to drift. Checked against the manifests
+    # rather than against each other, so neither can be right by agreeing with
+    # a wrong one.
+    local doc rows
+    for doc in "$REPO_ROOT/docs/providers.md" "$REPO_ROOT/README.md"; do
+    rows="$(sed -n '/^| Backend | `claude-code` | `cline` |/,/^$/p' "$doc")"
+    [ -n "$rows" ] || { echo "the matrix is gone from $doc, or its header changed"; return 1; }
+
+    local p h styles want got row
+    for p in $(lib provider_list backend); do
+        row="$(grep -E "^\| \`$p\` \|" <<< "$rows")" \
+            || { echo "no row for backend '$p'"; return 1; }
+        # Column count first. A row with a doubled separator still answers
+        # the cells this asks for by index, so without this a malformed row
+        # passes - which is how one got in.
+        local want_cols cols
+        want_cols="$(awk -F'|' 'NR==1 {print NF}' <<< "$rows")"
+        cols="$(awk -F'|' '{print NF}' <<< "$row")"
+        [ "$cols" = "$want_cols" ] \
+            || { echo "$p's row has $cols columns, the header has $want_cols"; return 1; }
+        local i=0
+        for h in claude-code cline; do
+            i=$((i + 1))
+            styles="$(lib manifest_get harness "$h" api_styles)"
+            if [[ " $styles " == *" $(lib manifest_get backend "$p" api_style) "* ]]; then
+                want=yes
+            else
+                want=no
+            fi
+            got="$(awk -F'|' -v n=$((i + 2)) '{gsub(/^ +| +$/,"",$n); print $n}' <<< "$row")"
+            [ "$got" = "$want" ] \
+                || { echo "$p x $h: the table says '$got', the manifests say '$want'"; return 1; }
+        done
+    done
+
+    # And every shipped harness has a column, or the table is answering for
+    # fewer pairs than exist.
+    for h in $(lib provider_list harness); do
+        grep -q "\`$h\`" <<< "$rows" || { echo "no column for harness '$h' in $doc"; return 1; }
+    done
+    done
+}
+
+@test "an Anthropic API key is a backend, so it stays on the host too" {
+    # The setup most organisations use: a console key on API billing, rather
+    # than a subscription login. Without a backend to declare it, dejima has
+    # no claudeAiOauth block to protect, skips the proxy, and mounts the
+    # operator's real key into the container - so the common arrangement
+    # would be the one where a long-lived, account-wide credential sits where
+    # a compromised session can read it.
+    lib manifest_validate backend anthropic-api-key
+    [ "$(lib manifest_get backend anthropic-api-key credential)" = "static" ]
+    [ "$(lib manifest_get backend anthropic-api-key upstream)" = "https://api.anthropic.com" ]
+    [ "$(lib manifest_get backend anthropic-api-key api_style)" = "anthropic" ]
+    # Anthropic's own header, bare - no scheme prefix. That pair is the whole
+    # difference from the subscription backend: a token is a Bearer, a key is
+    # x-api-key.
+    [ "$(lib manifest_get backend anthropic-api-key auth_header)" = "x-api-key" ]
+    [ "$(lib manifest_get backend anthropic-api-key auth_format)" = "{token}" ]
+    [ "$(lib manifest_get backend anthropic auth_header)" = "Authorization" ]
+    # And the other slot stripped, so a placeholder cannot travel beside the
+    # injected key and be the one the API reads.
+    [ "$(lib manifest_get backend anthropic-api-key strip_headers)" = "authorization" ]
+    [ "$(lib manifest_get backend anthropic-api-key requires)" = "credential_file" ]
+}
+
+@test "one API-billing backend serves both places the key can live" {
+    # Claude Code's console login keeps its key as primaryApiKey in
+    # ~/.claude.json; a key you hold yourself is a file that is nothing but
+    # the key. Same endpoint, same header, same static credential - one
+    # backend, with WHERE the key sits left to the operator.
+    lib manifest_validate backend anthropic-api-key
+    [ "$(lib manifest_get backend anthropic-api-key credential)" = "static" ]
+    [ "$(lib manifest_get backend anthropic-api-key auth_header)" = "x-api-key" ]
+    [ "$(lib manifest_get backend anthropic-api-key auth_format)" = "{token}" ]
+    [ "$(lib manifest_get backend anthropic-api-key strip_headers)" = "authorization" ]
+    # Defaulted to the console login, so the common case needs no config.
+    [ "$(lib config_default backend.anthropic-api-key.credential_file)" = "~/.claude.json" ]
+    [ "$(lib config_default backend.anthropic-api-key.credential_field)" = "primaryApiKey" ]
+    # And clearable, which is what serves a bare key file.
+    [ "$(lib config_type backend.anthropic-api-key.credential_field)" = "?jsonfield" ]
+    # Two backends for Anthropic, not three: the split is the wire
+    # arrangement, not where a file happens to be.
+    run lib provider_dir backend anthropic-console
+    [ "$status" -ne 0 ] || { echo "anthropic-console is back"; return 1; }
+    [ "$(lib manifest_get backend anthropic credential)" = "anthropic-oauth" ]
+}
+
+@test "the endpoint is identical across the anthropic backends" {
+    # Three values describe Anthropic's API rather than any credential, so
+    # they must not drift between the two backends that reach it. This is what
+    # the duplication costs, and it is cheaper to test than to deduplicate.
+    local field a b
+    for field in upstream proxied_domain api_style; do
+        a="$(lib manifest_get backend anthropic "$field")"
+        b="$(lib manifest_get backend anthropic-api-key "$field")"
+        [ -n "$a" ] || { echo "anthropic declares no $field"; return 1; }
+        [ "$a" = "$b" ] \
+            || { echo "$field differs: anthropic=$a anthropic-api-key=$b"; return 1; }
+    done
+}
+
+@test "a credential_field is dot-separated names, not an expression" {
+    # The proxy walks these segments itself, so a value that could name an
+    # expression would be one that could name a computation. It is a config
+    # type now, because where a key sits in a file is the operator's.
+    local good bad
+    for good in primaryApiKey a.b.c _x1; do
+        lib _config_valid_value jsonfield "$good" \
+            || { echo "refused '$good'"; return 1; }
+    done
+    for bad in '.leading' 'trailing.' 'a..b' 'a[0]' 'a|keys' '$env' 'a b' '1abc'; do
+        run lib _config_valid_value jsonfield "$bad"
+        [ "$status" -ne 0 ] || { echo "accepted '$bad'"; return 1; }
+    done
+}
+
+@test "every backend section takes a proxy key, whatever its manifest says" {
+    # Whether to withhold a credential is dejima's question, not the backend
+    # author's, so core appends it rather than each manifest declaring it - a
+    # backend that forgot would silently lose the setting.
+    local b
+    for b in $(lib provider_list backend); do
+        [ "$(lib config_type "backend.$b.proxy")" = "?bool" ] \
+            || { echo "backend '$b' has no proxy key"; return 1; }
+    done
+    # No default, because unset is a third state: inherit [credentials] proxy.
+    # A default of either value would decide for every backend at once.
+    [ -z "$(lib config_default backend.anthropic.proxy)" ] \
+        || { echo "the per-backend proxy key ships a default"; return 1; }
+}

test/proxy.bats

@@ -7,7 +7,7 @@ PLACEHOLDER="sandbox-credential-proxy-placeholder"
 
 setup() {
     REPO_ROOT="$BATS_TEST_DIRNAME/.."
-    PROXY="$REPO_ROOT/bin/dejima-anthropic-proxy"
+    PROXY="$REPO_ROOT/bin/dejima-credential-proxy"
     TD="$(mktemp -d)"
     SOCK="$TD/proxy.sock"
     CREDS="$TD/credentials.json"
@@ -27,10 +27,21 @@ EOF
     chmod 600 "$CREDS"
 }
 
+# The Anthropic arrangement, spelled the way bin/dejima spells it. The proxy
+# itself now defaults none of this (#171), so a test that omitted a flag would
+# be exercising a configuration no launch produces - which is why these are
+# here in full rather than left to defaults, and why static.bats pins that
+# bin/dejima still passes the same set.
 start_proxy() {
     "$PROXY" --socket "$SOCK" --credentials "$CREDS" \
         --upstream "http://127.0.0.1:$PORT" \
-        --oauth-endpoint "http://127.0.0.1:$PORT/v1/oauth/token" "$@" 2>"$TD/stderr" &
+        --credential-kind anthropic-oauth \
+        --oauth-endpoint "http://127.0.0.1:$PORT/v1/oauth/token" \
+        --oauth-client-id "9d1c250a-e61b-44d9-88ed-5944d1962f5e" \
+        --auth-header Authorization \
+        --auth-format "Bearer {token}" \
+        --strip-header x-api-key \
+        --ensure-header "anthropic-beta=oauth-2025-04-20" "$@" 2>"$TD/stderr" &
     PROXY_PID=$!
     for _ in $(seq 1 50); do [ -S "$SOCK" ] && break; sleep 0.1; done
     [ -S "$SOCK" ]
@@ -268,8 +279,13 @@ teardown() {
 @test "an already-expired refresh token is fatal at startup, before the socket exists" {
     write_creds 7200
     sed -i 's/"refreshTokenExpiresAt":[0-9]*/"refreshTokenExpiresAt":1000/' "$CREDS"
-    run "$PROXY" --socket "$SOCK" --credentials "$CREDS" --upstream "http://127.0.0.1:$PORT"
-    [ "$status" -ne 0 ]
+    run timeout 5 "$PROXY" --socket "$SOCK" --credentials "$CREDS" \
+        --upstream "http://127.0.0.1:$PORT" --credential-kind anthropic-oauth \
+        --oauth-endpoint "http://127.0.0.1:$PORT/v1/oauth/token" \
+        --oauth-client-id probe
+    # 1, not just nonzero: an argument mistake exits 2, and this test would
+    # otherwise pass on one while proving nothing about the expiry check.
+    [ "$status" -eq 1 ]
     [[ "$output" == *"log in"* ]]
     [ ! -S "$SOCK" ]
 }
@@ -278,7 +294,7 @@ teardown() {
     start_proxy
     SANDBOX_ANTHROPIC_PROXY_SOCKET="$SOCK" SANDBOX_ANTHROPIC_PROXY_PORT=18399 \
         SANDBOX_ANTHROPIC_TRANSPORT=loopback \
-        node "$REPO_ROOT/docker/anthropic-proxy-forwarder.js" &
+        node "$REPO_ROOT/docker/credential-proxy-forwarder.js" &
     FWD_PID=$!
     ok=""
     for _ in $(seq 1 50); do
@@ -347,7 +363,7 @@ start_forwarder() {  # start_forwarder <transport> <port>; extra env passes thro
     SANDBOX_ANTHROPIC_PROXY_PORT="$2" \
     SANDBOX_ANTHROPIC_TLS_CERT="$TD/cert.pem" \
     SANDBOX_ANTHROPIC_TLS_KEY="$TD/key.pem" \
-        node "$REPO_ROOT/docker/anthropic-proxy-forwarder.js" 2>"$TD/fwd-stderr" &
+        node "$REPO_ROOT/docker/credential-proxy-forwarder.js" 2>"$TD/fwd-stderr" &
     FWD_PID=$!
     for _ in $(seq 1 50); do
         (exec 3<>"/dev/tcp/127.0.0.1/$2") 2>/dev/null && return 0
@@ -422,7 +438,7 @@ make_cert() {
     run env -u SANDBOX_ANTHROPIC_TLS_CERT -u SANDBOX_ANTHROPIC_TLS_KEY \
         SANDBOX_ANTHROPIC_PROXY_SOCKET="$SOCK" SANDBOX_ANTHROPIC_TRANSPORT=tls \
         SANDBOX_ANTHROPIC_PROXY_PORT=18398 \
-        node "$REPO_ROOT/docker/anthropic-proxy-forwarder.js"
+        node "$REPO_ROOT/docker/credential-proxy-forwarder.js"
     [ "$status" -ne 0 ]
     [[ "$output" == *"SANDBOX_ANTHROPIC_TLS_CERT"* ]]
 }
@@ -464,3 +480,153 @@ make_cert() {
     [ "$status" -eq 0 ] || { echo "$output"; return 1; }
     [ "$output" = "200" ] || { echo "a 2MiB body was refused with $output"; return 1; }
 }
+
+# --- backend-generic behaviour (#171) ----------------------------------------
+#
+# The proxy knows no backend's name: upstream, credential kind, auth
+# header and shape, what to strip and what to ensure are all arguments. These
+# exercise the second kind - a static key, which is what an OpenAI-compatible
+# hosted backend has - and the parts of the shape a backend can move.
+
+# A static-key proxy against the same fake upstream. $1.. are extra flags.
+# Startup refusals run the proxy in the FOREGROUND and expect it to exit, so
+# every one of them is bounded by `timeout`. Without it, a check that stopped
+# refusing does not fail the test - the proxy starts, serves forever, and the
+# test hangs until the whole suite is killed, which reports as no result rather
+# than as a wrong one. Found by mutating two of these and watching them time
+# out instead of going red.
+start_static() {
+    printf 'sk-test-static-key\n' > "$TD/key"
+    chmod 600 "$TD/key"
+    "$PROXY" --socket "$SOCK" --credentials "$TD/key" \
+        --upstream "http://127.0.0.1:$PORT" \
+        --credential-kind static "$@" 2>"$TD/stderr" &
+    PROXY_PID=$!
+    for _ in $(seq 1 50); do [ -S "$SOCK" ] && break; sleep 0.1; done
+    [ -S "$SOCK" ]
+}
+
+@test "a static key is injected, and the placeholder never reaches upstream" {
+    start_static
+    run pcurl -d '{"hello":1}' http://proxy/v1/chat/completions
+    [ "$status" -eq 0 ]
+    [ "$(jq -r '.headers.authorization' <<<"$output")" = "Bearer sk-test-static-key" ]
+    [[ "$output" != *"$PLACEHOLDER"* ]]
+    [ "$(jq -r '.body' <<<"$output")" = '{"hello":1}' ]
+}
+
+@test "a static key file's trailing newline does not reach the header" {
+    # Written by an editor or a shell redirection as often as by a tool. A
+    # newline in a header value is not cosmetic: it would be rejected or split
+    # the block.
+    start_static
+    run pcurl -d '{}' http://proxy/v1/chat/completions
+    [ "$(jq -r '.headers.authorization' <<<"$output")" = "Bearer sk-test-static-key" ]
+}
+
+@test "a static credential is never refreshed, so a 401 is reported once" {
+    # Refreshing needs somewhere to refresh against, and a static key has
+    # none. Retrying would send the same bytes and turn one rejection into
+    # two, which reads as a flapping upstream rather than a wrong key.
+    # The same route the OAuth retry test uses: 401 on the first call, echo
+    # after. An OAuth credential refreshes and the second call succeeds; a
+    # static one has nowhere to refresh against, so the 401 is what the
+    # session sees.
+    start_static
+    run pcurl -o /dev/null -w '%{http_code}' -d '{}' http://proxy/echo-401-once
+    [ "$output" = "401" ]
+    # And no refresh was attempted anywhere, which the fake counts for us.
+    [ "$(curl -s "http://127.0.0.1:$PORT/oauth-hits")" = "0" ]
+}
+
+@test "the auth header and its format are the backend's, not Bearer by fiat" {
+    # A backend that wants its key in a header of its own, unprefixed, needs
+    # no code here. Asserted together because the pair is the shape.
+    start_static --auth-header x-goog-api-key --auth-format '{token}'
+    run pcurl -d '{}' http://proxy/v1/chat/completions
+    [ "$(jq -r '.headers["x-goog-api-key"]' <<<"$output")" = "sk-test-static-key" ]
+    # And the client's own Authorization placeholder is left alone rather than
+    # silently rewritten: it is not this backend's auth header. Stripping it
+    # is a separate declaration, which the next test covers.
+    [ "$(jq -r '.headers.authorization' <<<"$output")" = "Bearer $PLACEHOLDER" ]
+}
+
+@test "a header named in strip-header does not travel beside the injected one" {
+    start_static --auth-header x-goog-api-key --auth-format '{token}' \
+        --strip-header authorization
+    run pcurl -d '{}' http://proxy/v1/chat/completions
+    [ "$(jq -r '.headers.authorization // "absent"' <<<"$output")" = "absent" ]
+    [ "$(jq -r '.headers["x-goog-api-key"]' <<<"$output")" = "sk-test-static-key" ]
+}
+
+@test "the auth header cannot be stripped out from under itself" {
+    # Naming it in both places is a backend's mistake, and the safe reading
+    # is that the credential still goes: dropping it would send an
+    # unauthenticated request and report the backend's 401 as the fault.
+    #
+    # Position as well as presence, because presence alone does not
+    # distinguish the two paths. A stripped-then-re-added header arrives at
+    # the END of the block from the supplied-names pass; a replaced one keeps
+    # the slot the client gave it. Both send the credential, and only one of
+    # them leaves the request looking like the client wrote it - which is the
+    # property the whole header-emission dance exists for.
+    start_static --strip-header authorization
+    run pcurl -H "Content-Type: application/json" -H "X-Stainless-Lang: js" \
+        -d '{}' http://proxy/v1/chat/completions
+    [ "$(jq -r '.headers.authorization' <<<"$output")" = "Bearer sk-test-static-key" ]
+    local auth_at type_at
+    auth_at="$(jq -r '[.header_lines[][0] | ascii_downcase] | index("authorization")' <<<"$output")"
+    type_at="$(jq -r '[.header_lines[][0] | ascii_downcase] | index("content-type")' <<<"$output")"
+    [ "$auth_at" -lt "$type_at" ] \
+        || { echo "Authorization moved to position $auth_at, after Content-Type at $type_at"; return 1; }
+}
+
+@test "no ensure-header means none is invented" {
+    # anthropic-beta is one backend's requirement. A proxy that added it
+    # anyway would put an Anthropic tell on every other backend's wire.
+    start_static
+    run pcurl -d '{}' http://proxy/v1/chat/completions
+    [ "$(jq -r '.headers["anthropic-beta"] // "absent"' <<<"$output")" = "absent" ]
+}
+
+@test "an unusable static key is fatal at startup, before the socket exists" {
+    : > "$TD/key"
+    run timeout 5 "$PROXY" --socket "$SOCK" --credentials "$TD/key" \
+        --upstream "http://127.0.0.1:$PORT" --credential-kind static
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"empty"* ]]
+    [ ! -S "$SOCK" ]
+}
+
+@test "a key carrying a control character is refused rather than sanitised" {
+    # A key that needs sanitising was pasted wrong. Trimming it would send
+    # mangled bytes and report the backend's rejection as the fault.
+    printf 'sk-good\x1bbad\n' > "$TD/key"
+    run timeout 5 "$PROXY" --socket "$SOCK" --credentials "$TD/key" \
+        --upstream "http://127.0.0.1:$PORT" --credential-kind static
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"control character"* ]]
+    [ ! -S "$SOCK" ]
+}
+
+@test "an auth-format with no token placeholder is refused" {
+    # It would start, answer requests, and send every one of them without a
+    # credential. Refusing at parse time is the difference between a
+    # configuration error and a silently unauthenticated session.
+    printf 'k\n' > "$TD/key"
+    run timeout 5 "$PROXY" --socket "$SOCK" --credentials "$TD/key" \
+        --upstream "http://127.0.0.1:$PORT" --credential-kind static \
+        --auth-format 'Bearer'
+    [ "$status" -eq 2 ]
+    [[ "$output" == *"{token}"* ]]
+    [ ! -S "$SOCK" ]
+}
+
+@test "anthropic-oauth without its endpoint or client id is refused" {
+    write_creds 7200
+    run timeout 5 "$PROXY" --socket "$SOCK" --credentials "$CREDS" \
+        --upstream "http://127.0.0.1:$PORT" --credential-kind anthropic-oauth
+    [ "$status" -eq 2 ]
+    [[ "$output" == *"oauth-endpoint"* ]]
+    [ ! -S "$SOCK" ]
+}

test/release-pass.sh

@@ -132,8 +132,11 @@ added="$(comm -13 \
 # itself the thing that makes the rollback refuse.
 # The singular is spelled out rather than derived: "harnesses" does not lose
 # an s to become "harness", and a manifest is named for the singular.
+#
+# Every axis, including backends: the newest one is exactly the one a stale
+# list would miss, because a list is only ever updated by whoever remembers.
 new_providers=""
-for pair in harnesses:harness forges:forge workflows:workflow; do
+for pair in harnesses:harness forges:forge workflows:workflow backends:backend; do
     axis="${pair%%:*}"
     one="${pair#*:}"
     [ -d "$axis" ] || continue
@@ -144,9 +147,35 @@ for pair in harnesses:harness forges:forge workflows:workflow; do
     done < <(find "$axis" -mindepth 1 -maxdepth 1 -type d -printf '%f\n' | sort)
 done
 
-if [ -n "$added" ] || [ -n "$new_providers" ]; then
+# And the keys a provider DECLARES, which are config keys an operator writes
+# and an older dejima refuses - but which live in a manifest rather than in
+# core's schema, so the diff above cannot see them. `[harness.claude-code]
+# backend` is one: adopting it is what makes the rollback refuse, and nothing
+# said so.
+new_keys=""
+for pair in harnesses:harness forges:forge workflows:workflow backends:backend; do
+    axis="${pair%%:*}"
+    one="${pair#*:}"
+    [ -d "$axis" ] || continue
+    while IFS= read -r name; do
+        [ -n "$name" ] || continue
+        now="$(sed -n 's/^keys *= *//p' "$axis/$name/$one.conf" 2>/dev/null \
+               | tr ' ' '\n' | sed 's/:.*//' | sort -u)"
+        was="$(git show "$base:$axis/$name/$one.conf" 2>/dev/null \
+               | sed -n 's/^keys *= *//p' | tr ' ' '\n' | sed 's/:.*//' | sort -u)"
+        while IFS= read -r k; do
+            [ -n "$k" ] || continue
+            new_keys="$new_keys [$one.$name]|$k"
+        done < <(comm -13 <(printf '%s\n' "$was") <(printf '%s\n' "$now"))
+    done < <(find "$axis" -mindepth 1 -maxdepth 1 -type d -printf '%f\n' | sort)
+done
+
+if [ -n "$added" ] || [ -n "$new_providers" ] || [ -n "$new_keys" ]; then
     [ -z "$added" ] || printf '   %s\n' $added
     [ -z "$new_providers" ] || printf '   [%s] as a config section\n' $new_providers
+    for entry in $new_keys; do
+        printf '   %s %s\n' "${entry%%|*}" "${entry#*|}"
+    done
 else
     echo "   (none - a rollback accepts any config this release accepts)"
 fi

test/remote.bats

@@ -1353,15 +1353,29 @@ EOF
 # the whitelist below is what makes the log sufficient.
 stub_curl() {
     STUB_DIR="${STUB_DIR:-$(mktemp -d)}"
+    # stdin as well as argv, because the request URL now arrives that way and
+    # a stub that only saw argv would report the push as carrying no
+    # destination at all - which reads like the value being dropped.
+    #
+    # Drained only when `--config -` asked for it, exactly as the real curl
+    # does. A stub that reads stdin unconditionally HANGS when the caller
+    # sends none, so a change that stopped redirecting would fail this suite
+    # by timing out rather than by failing an assertion.
     cat > "$STUB_DIR/curl" <<EOF
 #!/bin/bash
 printf '%s\n' "\$@" >> "$STUB_DIR/curl-argv"
+_want_stdin=
+for _a in "\$@"; do
+    [ "\$_a" = --config ] && _want_stdin=1
+done
+[ -z "\$_want_stdin" ] || cat >> "$STUB_DIR/curl-stdin"
 exit 0
 EOF
     chmod +x "$STUB_DIR/curl"
     PATH="$STUB_DIR:$PATH"
 }
 curl_log() { cat "$STUB_DIR/curl-argv" 2>/dev/null; }
+curl_stdin() { cat "$STUB_DIR/curl-stdin" 2>/dev/null; }
 
 # The EXACT argument vector of one push, one argument per line - a whitelist,
 # not a search. Absence assertions cannot do this job: an argument that leaks
@@ -1375,7 +1389,7 @@ expect_argv() {
         -H "Title: dejima: $1" \
         -H "Priority: default"
     [ -z "${3:-}" ] || printf '%s\n' -H "Click: $3"
-    printf '%s\n' -d "$2" -- https://ntfy.example.invalid/dejima
+    printf '%s\n' -d "$2" --config -
 }
 # Compared as a whole file, so a SECOND push would fail this too. The
 # sentinel is what makes "whole" true: both sides are command substitutions,
@@ -1569,6 +1583,49 @@ EOF
     [ -z "$(curl_log)" ]
 }
 
+@test "the ntfy URL never reaches curl's argv, because it can carry a token" {
+    # An ntfy server that wants credentials takes them in the URL, and
+    # docs/remote-access.md documents that form. Every argument of every
+    # process on this host is readable by any local account through
+    # /proc/<pid>/cmdline, so a URL in argv is a token published to the
+    # machine for as long as the request runs - `ps` is enough.
+    #
+    # Both halves are asserted. Absent from argv is the fix; present on stdin
+    # is what stops the fix from being "the push lost its destination", which
+    # would pass an absence check just as well.
+    stub_curl
+    conf_with_ntfy
+    write_entry 0123456789abcdef '%1' 'work:2'
+    marker 0123456789abcdef waiting
+    run "$REPO_ROOT/bin/dejima-notify-watch" --once
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
+
+    [[ "$(curl_log)" != *ntfy.example.invalid* ]] \
+        || { echo "the URL is in argv:"; curl_log; return 1; }
+    [[ "$(curl_stdin)" == *'url = "https://ntfy.example.invalid/dejima"'* ]] \
+        || { echo "the URL did not reach curl at all:"; curl_stdin; return 1; }
+
+    # The click URL is not secret and stays where it is: it is composed from
+    # base_url, which is the address of the operator's own front door.
+    [[ "$(curl_log)" == *"Click: https://dejima.example.invalid/?arg=0123456789abcdef"* ]] \
+        || { echo "the click target moved:"; curl_log; return 1; }
+}
+
+@test "a misconfigured ntfy URL is not echoed back with its credentials" {
+    # The refusal path prints the offending value, and the journal is where
+    # that lands under a systemd user unit. A token that survives a
+    # misconfiguration by being written to the journal is a token that
+    # outlives the mistake.
+    stub_curl
+    write_remote_config 'ntfy_url = https://someone:hunter2@ntfy.example.invalid/t{}'
+    run "$REPO_ROOT/bin/dejima-notify-watch" --once
+    [ "$status" -ne 0 ] || { echo "a bad URL was accepted: $output"; return 1; }
+    [[ "$output" != *hunter2* ]] \
+        || { echo "the credential was echoed back: $output"; return 1; }
+    [[ "$output" == *"ntfy_url"* ]] || { echo "$output"; return 1; }
+    [ -z "$(curl_log)" ]
+}
+
 @test "a config value curl would read as an option is refused, not passed on" {
     # The url schema type requires an http(s) scheme, which "-K/path" is not -
     # verified against the real curl, which would otherwise read "-K/path" as
@@ -1951,6 +2008,12 @@ expect_ttyd_argv() {
     [ -z "${3:-}" ] || printf '%s\n' -t "tmuxPrefix=$3"
     [ -z "${4:-}" ] || printf '%s\n' -t "focusOnTap=$4"
     [ -z "${5:-}" ] || printf '%s\n' -t "buttonColors=$5"
+    # Always sent, unlike the four above: a browser has no theme to inherit,
+    # so this is not an option an operator turns on. Read out of the script
+    # rather than transcribed - this file asserts that ttyd is given a theme
+    # and that its values match the page (static.bats), not what they are.
+    printf '%s\n' -t "$(sed -n "/^theme_opt=(-t '/,/^}')$/p" \
+        "$REPO_ROOT/bin/dejima-ttyd" | sed "1s/^theme_opt=(-t '//; \$s/')$//")"
     printf '%s\n' "$(readlink -f "$REPO_ROOT/bin")/dejima-attach"
 }
 # Sentinel on both sides: both are command substitutions, which strip trailing
@@ -2176,7 +2239,10 @@ PY
     run "$REPO_ROOT/bin/dejima-ttyd"
     [ "$status" -eq 0 ]
     assert_ttyd_argv 12345
-    run grep -cx -- '-t' "$STUB_DIR/ttyd-argv"
+    # No fontSize reaches ttyd, rather than no -t at all: the theme is sent on
+    # every launch (a browser has no palette to inherit), so counting -t stopped
+    # measuring what this is about, which is that an unset option sends nothing.
+    run grep -c 'fontSize' "$STUB_DIR/ttyd-argv"
     [ "$output" = "0" ]
 
     # Set. Checked through the exact vector, not a substring: "fontSize=20
@@ -2668,10 +2734,14 @@ nginx_blocks() {
 }
 
 @test "install.sh links the remote scripts and the notify hook, registers neither, and enables nothing" {
-    # The hook is linked by the harness plugin now - which file it is, and
-    # where the harness reads it from, is the harness's business - while the
-    # CLIs stay install.sh's, being dejima's own.
-    grep -q '_link_hook dejima-notify.sh' "$REPO_ROOT/bin/harness/claude-code.sh"
+    # The hook is baked into the image and registered by absolute path, so
+    # install.sh puts nothing of it on the host - which file it is, and where
+    # a session reads it from, is the harness plugin's business. The CLIs stay
+    # install.sh's, being dejima's own.
+    grep -q 'COPY hooks/dejima-notify.sh /usr/local/lib/dejima/hooks/dejima-notify.sh' \
+        "$REPO_ROOT/docker/Dockerfile"
+    grep -q '_link_hook' "$REPO_ROOT/bin/harness/claude-code.sh" \
+        && { echo "install.sh still links hooks into ~/.claude/hooks"; return 1; }
     grep -q '^link_bin dejima-attach$' "$REPO_ROOT/install.sh"
     grep -q '^link_bin dejima-ttyd$' "$REPO_ROOT/install.sh"
     grep -q '^link_bin dejima-notify-watch$' "$REPO_ROOT/install.sh"
@@ -2703,13 +2773,25 @@ nginx_blocks() {
     # $output, and this is a statement about what THIS run printed.
     [[ "$output" == *"nothing is listening"* ]]
 
-    # bin/dejima registers $HOME/.claude/hooks/dejima-notify.sh per session,
-    # and ~/.claude/hooks is what gets mounted read-only into the container.
-    # Without this link every notification hook is an exit-127.
-    [ -L "$FAKE_HOME/.claude/hooks/dejima-notify.sh" ]
-    [ "$(readlink -f "$FAKE_HOME/.claude/hooks/dejima-notify.sh")" \
-      = "$(readlink -f "$REPO_ROOT/hooks/dejima-notify.sh")" ]
-    [ -x "$FAKE_HOME/.claude/hooks/dejima-notify.sh" ]
+    # The notify hook is baked into the image and registered per session by
+    # its absolute path there, so nothing about it lands on the host. Without
+    # the baked copy every notification hook would be an exit-127.
+    [ ! -e "$FAKE_HOME/.claude/hooks/dejima-notify.sh" ] \
+        || { echo "install.sh still puts the notify hook on the host"; return 1; }
+    # Asserted on what the registration PRODUCES rather than on the source
+    # text: the path is a variable there, and a grep for the literal passes or
+    # fails on how it happens to be spelled rather than on where it points.
+    local st; st="$(mktemp)"; echo '{}' > "$st"
+    bash -c '
+        source "'"$REPO_ROOT"'/bin/dejima-provider-lib.sh"
+        source "'"$REPO_ROOT"'/bin/dejima-harness-lib.sh"
+        harness_plugin_load claude-code
+        harness_hook harness_register_notify "$1"
+    ' _ "$st" >/dev/null 2>&1
+    [ "$(jq -r '.hooks.Stop[0].hooks[0].command' "$st")" \
+        = "/usr/local/lib/dejima/hooks/dejima-notify.sh done" ] \
+        || { echo "notify is not registered at its baked path: $(cat "$st")"; rm -f "$st"; return 1; }
+    rm -f "$st"
     local b
     for b in dejima-attach dejima-ttyd dejima-notify-watch; do
         [ -L "$FAKE_HOME/.local/bin/$b" ]
@@ -2717,14 +2799,15 @@ nginx_blocks() {
         [ -x "$FAKE_HOME/.local/bin/$b" ]
     done
 
-    # Positive first: an absence assertion against a settings.json that did
-    # not get written would pass on its own.
-    run jq -e '[.hooks[]?[]?.hooks[]?.command] | any(test("sandbox-context.sh"))' \
-        "$FAKE_HOME/.claude/settings.json"
-    [ "$status" -eq 0 ]
-    run jq -e '[.hooks[]?[]?.hooks[]?.command] | any(test("dejima-notify"))' \
-        "$FAKE_HOME/.claude/settings.json"
-    [ "$status" -ne 0 ]
+    # install.sh registers nothing in the harness's config now, so there is
+    # nothing positive to check there - the settings file may not exist at
+    # all. The positive assertion that matters moved above: the notify hook IS
+    # registered, at its baked path, in the sandbox's own overlay.
+    if [ -f "$FAKE_HOME/.claude/settings.json" ]; then
+        run jq -e '[.hooks[]?[]?.hooks[]?.command] | any(test("dejima-notify"))' \
+            "$FAKE_HOME/.claude/settings.json"
+        [ "$status" -ne 0 ]
+    fi
 
     # Nothing was enabled, and nothing under the runtime dir was created: the
     # feature stays off until the operator sets [remote-access] enabled = on.
@@ -2735,7 +2818,7 @@ nginx_blocks() {
     run env HOME="$FAKE_HOME" PATH="$STUB_DIR:$PATH" "$REPO_ROOT/install.sh"
     [ "$status" -eq 0 ]
     [ ! -e "$FAKE_HOME/.dejima-backup" ]
-    [ -L "$FAKE_HOME/.claude/hooks/dejima-notify.sh" ]
+    [ ! -e "$FAKE_HOME/.claude/hooks/dejima-notify.sh" ]
 
     # And with one, it may not: re-running the installer after a git pull is
     # exactly what an operator with a front door already up does, and telling

test/run-confined.sh

@@ -1,13 +1,16 @@
 #!/bin/bash
-# Every confined suite at once, for the case where the whole set is genuinely
-# wanted - before opening a pull request, or after touching bin/dejima, which
-# nearly every suite reads.
+# The confined suites, in one of two lanes.
 #
-# The suites are separate files that share no state, which is what makes this
-# safe: each writes into its own BATS_*_TMPDIR, and the two that bind a socket
-# ask the kernel for a free port rather than naming one. Run sequentially they
-# take about twenty-five minutes on ten cores; run together, about seven, which
-# is the difference between checking the whole set and not bothering.
+#   test/run-confined.sh              every confined suite - the pull-request gate
+#   test/run-confined.sh --changed    only the suites the working diff calls for
+#
+# The suites are separate files that share no state, which is what makes running
+# them together safe: each writes into its own BATS_*_TMPDIR, and the two that
+# bind a socket ask the kernel for a free port rather than naming one. Within a
+# file, bats' own --jobs parallelism is used too; it needs flock rather than GNU
+# parallel, which is why --no-parallelize-across-files is passed alongside it
+# (bats refuses --jobs without GNU parallel unless across-files is off, and this
+# script is already doing the across-files half itself).
 #
 # CI does not use this. It runs the same suites as a matrix, one job each, so
 # that a failure names the suite it came from without anyone reading a log -
@@ -26,22 +29,216 @@ cd "$root" || exit 1
 # this repo is usually worked on.
 PRIVILEGED=" runtime ci-runner "
 
-suites=()
+# Which suites a changed path calls for. This is the table .dejima.md used to
+# carry as prose; it is here so that it runs, and so that an agent iterating
+# cannot map a change to the wrong suite by hand.
+#
+# Anything that matches no rule selects every suite. A path nobody has mapped
+# is a path nobody has decided about, and guessing "none" there is how a change
+# ships having been checked by nothing.
+suites_for() {
+    case "$1" in
+        # Read by nearly every other suite, so a change to one is the whole set.
+        bin/dejima|bin/dejima-config-lib.sh) echo ALL ;;
+
+        bin/dejima-audit)                    echo audit ;;
+        bin/dejima-update-check)             echo config ;;
+        bin/dejima-epitaph)                  echo config ;;
+        bin/dejima-tty-suspend)              echo static ;;
+        bin/dejima-color-lib.sh)             echo 'remote project' ;;
+        bin/dejima-tui-lib.sh)               echo 'remote project' ;;
+        bin/dejima-conversation-ship)        echo conversation ;;
+        bin/dejima-share)                    echo share ;;
+        # The slug scheme keys the transcript mounts, the epitaph and audit
+        # stores, and the share layout, so a change to it is not one area's.
+        bin/dejima-slug-lib.sh)              echo 'share conversation audit static' ;;
+        bin/dejima-credential-proxy|docker/credential-proxy-forwarder.js) echo proxy ;;
+        bin/dejima-project-lib.sh|bin/dejima-project|bin/dejima-dep|bin/dejima-allow) echo project ;;
+        bin/dejima-attach|bin/dejima-ttyd|bin/dejima-notify-watch) echo remote ;;
+        web/*|systemd/*)                     echo remote ;;
+        bin/dejima-provider-lib.sh|bin/dejima-harness-lib.sh) echo providers ;;
+        bin/harness/*)                       echo providers ;;
+        forges/*|workflows/*|harnesses/*|tools/*) echo providers ;;
+        install.sh)                          echo config ;;
+
+        # static.bats asserts on files it does not own, so a shipped doc or a
+        # docker/ file needs it as well as whatever else the change touched -
+        # which for docker/ is most things, since the entrypoint and compose
+        # file are read by nearly every suite that builds a launch.
+        docker/*)                            echo ALL ;;
+        hooks/*)                             echo 'static config providers project' ;;
+        docs/*|README.md|*.md)               echo static ;;
+        .gitea/*|.shellcheckrc)              echo static ;;
+        .dejima/*)                           echo 'static config project providers' ;;
+
+        test/*.bats) local n="${1##*/}"; echo "${n%.bats}" ;;
+        test/*)                              echo static ;;
+
+        *) echo ALL ;;
+    esac
+}
+
+lane=all
+jobs=""
+base=""
+list_only=0
+given_paths=()
+while [ "$#" -gt 0 ]; do
+    case "$1" in
+        --changed) lane=changed ;;
+        --base) shift; base="${1:-}" ;;
+        --list) list_only=1 ;;
+        -j|--jobs) shift; jobs="${1:-}" ;;
+        -h|--help)
+            sed -n '2,5p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+            printf '  --list        print the selection and stop\n'
+            printf '  --jobs N      tests to run at once within each suite\n'
+            printf '  --base REF    what --changed diffs against\n'
+            exit 0 ;;
+        -*) echo "unknown argument: $1" >&2; exit 2 ;;
+        # A path given here stands in for one git would have reported, so the
+        # map can be asked what it does with a path without the answer
+        # depending on what happens to be uncommitted.
+        *) given_paths+=("$1") ;;
+    esac
+    shift
+done
+
+if [ "$lane" != changed ] && [ "${#given_paths[@]}" -gt 0 ]; then
+    echo "paths only mean something with --changed: ${given_paths[*]}" >&2
+    exit 2
+fi
+
+all_suites=()
 for f in test/*.bats; do
     [ -f "$f" ] || continue
     name="$(basename "$f" .bats)"
     case "$PRIVILEGED" in *" $name "*) continue ;; esac
-    suites+=("$name")
+    all_suites+=("$name")
 done
-[ "${#suites[@]}" -gt 0 ] || { echo "found no confined suites under test/" >&2; exit 1; }
+[ "${#all_suites[@]}" -gt 0 ] || { echo "found no confined suites under test/" >&2; exit 1; }
+
+# Within-file parallelism is bats' own, and it needs flock. Without it bats
+# exits before running anything, so the fallback is stated rather than left to
+# look like a broken suite. The size of it is decided after the selection,
+# below, because it depends on how many suites there are.
+if command -v flock >/dev/null 2>&1; then
+    can_parallelize=1
+else
+    can_parallelize=0
+fi
+
+selected=()
+changed_paths=()
+if [ "$lane" = changed ]; then
+    if [ "${#given_paths[@]}" -gt 0 ]; then
+        changed_paths=("${given_paths[@]}")
+    else
+        if [ -z "$base" ]; then
+            for candidate in origin/development development origin/main main; do
+                if git rev-parse --verify --quiet "$candidate" >/dev/null; then
+                    base="$candidate"
+                    break
+                fi
+            done
+        fi
+        # Committed work plus what is still in the working tree, including
+        # files git has never seen: iteration happens before a commit, and a
+        # lane that only saw committed changes would report on the wrong thing.
+        mapfile -t changed_paths < <(
+            {
+                [ -z "$base" ] || git diff --name-only \
+                    "$(git merge-base "$base" HEAD 2>/dev/null || echo "$base")" 2>/dev/null
+                git diff --name-only HEAD 2>/dev/null
+                git ls-files --others --exclude-standard 2>/dev/null
+            } | sort -u
+        )
+    fi
+
+    wanted=" "
+    for p in "${changed_paths[@]}"; do
+        [ -n "$p" ] || continue
+        for s in $(suites_for "$p"); do
+            [ "$s" != ALL ] || { wanted=ALL; break 2; }
+            case "$wanted" in *" $s "*) ;; *) wanted="$wanted$s " ;; esac
+        done
+    done
+    if [ "$wanted" = ALL ]; then
+        selected=("${all_suites[@]}")
+    else
+        for s in "${all_suites[@]}"; do
+            case "$wanted" in *" $s "*) selected+=("$s") ;; esac
+        done
+    fi
+else
+    selected=("${all_suites[@]}")
+fi
+
+skipped=()
+for s in "${all_suites[@]}"; do
+    for t in ${selected[@]+"${selected[@]}"}; do [ "$t" = "$s" ] && continue 2; done
+    skipped+=("$s")
+done
+
+# Which lane ran, before anything else, because the whole point of having two
+# is that a run can be read back later without guessing which one it was. To
+# stderr, so --list's stdout is the suite names and nothing else.
+# How much concurrency to actually ask for.
+#
+# Every selected suite runs at once, so what lands on the machine is
+# suites x jobs. Asking each suite for `nproc` made that ten times the cores
+# on a ten-core box, and #295 is what that cost: the tests that wait on a
+# bounded deadline - a pty reaching raw mode, a shipper polling, an audit
+# finishing - blow through it on a machine that oversubscribed, and fail for
+# the load rather than for the thing they check.
+#
+# Oversubscription still helps, because these tests fork more than they
+# compute. It is a property of the whole run rather than of each suite, so it
+# is budgeted once and divided: roughly twice the cores, in total.
+if [ -z "$jobs" ]; then
+    if [ "$can_parallelize" = 1 ] && [ "${#selected[@]}" -gt 0 ]; then
+        cores="$(nproc 2>/dev/null || echo 4)"
+        budget=$(( cores * 2 ))
+        jobs=$(( (budget + ${#selected[@]} - 1) / ${#selected[@]} ))
+        [ "$jobs" -ge 1 ] || jobs=1
+    else
+        jobs=1
+    fi
+fi
+bats_flags=()
+[ "$jobs" -gt 1 ] && bats_flags=(--jobs "$jobs" --no-parallelize-across-files)
+
+{
+    if [ "$lane" = changed ]; then
+        printf 'lane: CHANGED - %d of %d confined suites, from %d changed path(s)\n' \
+            "${#selected[@]}" "${#all_suites[@]}" "${#changed_paths[@]}"
+        [ "${#skipped[@]}" -eq 0 ] || printf '      not run: %s\n' "${skipped[*]}"
+        printf '      An iteration check. NOT the pull-request gate - for that run\n'
+        printf '      test/run-confined.sh with no arguments.\n'
+    else
+        printf 'lane: ALL - every confined suite (the pull-request gate)\n'
+        printf '      not run: runtime, ci-runner - they need Docker and a real runner.\n'
+    fi
+    [ "$list_only" = 1 ] || printf '      %d test(s) at a time within each suite, %d suites at once\n' \
+        "$jobs" "${#selected[@]}"
+    printf '\n'
+} >&2
+
+if [ "$list_only" = 1 ]; then
+    [ "${#selected[@]}" -eq 0 ] || printf '%s\n' "${selected[@]}"
+    exit 0
+fi
+
+if [ "${#selected[@]}" -eq 0 ]; then
+    echo "nothing to run: no changed path maps to a confined suite"
+    exit 0
+fi
 
-# One process per suite. There are fewer suites than cores on anything this
-# repo is developed on, and they are shell rather than CPU-bound, so a job
-# limit would cost wall clock for no benefit.
 out="$(mktemp -d)"
 trap 'rm -rf "$out"' EXIT
-for s in "${suites[@]}"; do
-    ( bats "test/$s.bats" > "$out/$s" 2>&1; printf '%s' "$?" > "$out/$s.status" ) &
+for s in "${selected[@]}"; do
+    ( bats ${bats_flags[@]+"${bats_flags[@]}"} "test/$s.bats" > "$out/$s" 2>&1
+      printf '%s' "$?" > "$out/$s.status" ) &
 done
 wait
 
@@ -51,7 +248,7 @@ wait
 # that as "0 failures" is how a green board comes to mean nothing.
 failed=0
 printf '%-16s %6s %8s\n' suite ran failed
-for s in "${suites[@]}"; do
+for s in "${selected[@]}"; do
     ran="$(grep -cE '^(ok|not ok)' "$out/$s")"
     bad="$(grep -cE '^not ok' "$out/$s")"
     status="$(cat "$out/$s.status" 2>/dev/null || echo 1)"
@@ -69,7 +266,7 @@ done
 
 if [ "$failed" -ne 0 ]; then
     echo
-    for s in "${suites[@]}"; do
+    for s in "${selected[@]}"; do
         ran="$(grep -cE '^(ok|not ok)' "$out/$s")"
         bad="$(grep -cE '^not ok' "$out/$s")"
         { [ "$bad" -gt 0 ] || [ "$ran" -eq 0 ]; } || continue
@@ -77,7 +274,7 @@ if [ "$failed" -ne 0 ]; then
         if [ "$ran" -eq 0 ]; then
             head -20 "$out/$s"
         else
-            grep -E '^not ok' -A 6 "$out/$s"
+            grep -E '^not ok' -A 20 "$out/$s"
         fi
         echo
     done

test/runtime.bats

@@ -49,7 +49,10 @@ compose_cap_add() {
     ' "$BATS_TEST_DIRNAME/../docker/docker-compose.yml"
 }
 
-IMAGE=dejima:latest
+# localhost/ for the same reason bin/dejima uses it: a bare name is a Docker
+# Hub name to anything that pushes, and nothing built here is meant to leave
+# the host (#53).
+IMAGE=localhost/dejima:latest
 
 # What a session actually runs: the base image plus the selected harness's own
 # layer, built in setup_file. Exported there because bats re-runs this file's
@@ -75,6 +78,29 @@ network_name() { echo "dejima-test-net-$(basename "$BATS_RUN_TMPDIR")"; }
 # long-lived runner, until someone clears it by hand.
 test_container_name() { echo "dejima-test-$1-$(basename "$BATS_RUN_TMPDIR")"; }
 
+# The Anthropic arrangement, in one place.
+#
+# dejima-credential-proxy defaults none of this any more (#171): which upstream,
+# which credential kind, which header and what shape are all the caller's to
+# state, because a default is one backend's arrangement wearing every
+# backend's name. Three copies of the same eight flags in this file would be
+# three places for them to drift from what bin/dejima actually launches, so
+# there is one - and static.bats pins that bin/dejima still passes the same set.
+#
+# Sets PROXY_PID, which every caller's teardown already kills.
+start_credential_proxy() {  # <socket> <credentials> <upstream> <oauth-endpoint>
+    "$BATS_TEST_DIRNAME/../bin/dejima-credential-proxy" \
+        --socket "$1" --credentials "$2" --upstream "$3" \
+        --credential-kind anthropic-oauth \
+        --oauth-endpoint "$4" \
+        --oauth-client-id "9d1c250a-e61b-44d9-88ed-5944d1962f5e" \
+        --auth-header Authorization \
+        --auth-format "Bearer {token}" \
+        --strip-header x-api-key \
+        --ensure-header "anthropic-beta=oauth-2025-04-20" &
+    PROXY_PID=$!
+}
+
 # Every container here must go on network_name(), never the default bridge:
 # dns-proxy.sh forwards to Docker's embedded resolver at 127.0.0.11, which
 # only exists on a user-defined network. On the default bridge dnsmasq has
@@ -165,11 +191,19 @@ harness_manifest_value() {
     sed -n "s/^$1 *= *//p" "$BATS_TEST_DIRNAME/../harnesses/claude-code/harness.conf"
 }
 
+# The same, for the selected model backend. proxied_domain lives off the
+# harness manifest onto this one (#171): a harness reaches whichever endpoint
+# it is configured for, so the name the terminator answers for belongs to the
+# endpoint rather than to the program talking to it.
+backend_manifest_value() {
+    sed -n "s/^$1 *= *//p" "$BATS_TEST_DIRNAME/../backends/anthropic/backend.conf"
+}
+
 # The selected harness's image layer, on top of $1, tagged for this run so
 # teardown_file's sweep finds it. Prints the new tag.
 build_harness_layer() {
     local base="$1" tag df ctx
-    tag="dejima-test-harness:$(basename "$BATS_RUN_TMPDIR")"
+    tag="localhost/dejima-test-harness:$(basename "$BATS_RUN_TMPDIR")"
     df="$(mktemp)"
     # An empty build context, for the reason bin/dejima uses one: a build
     # whose context is a directory anything else can write is a way into the
@@ -321,6 +355,37 @@ setup_file() {
     done < <(docker ps -a --filter name=^dejima-test- --filter status=exited \
                  --filter status=created --format '{{.Names}}' 2>/dev/null)
 
+    # And the images this suite builds - harness, override, derived - which
+    # nothing reaps across runs (#26). The per-test teardown removes only the
+    # CURRENT run's suffix, so an abandoned run's images have no reaper at all.
+    # They hold no subnet, so this is disk rather than the network's kind of
+    # harm; it is also the largest thing here by disk, since each is built
+    # FROM the session image.
+    #
+    # Same age guard as above, for the same reason: a concurrent run's images
+    # are minutes old. The prefix is checked again on the name rather than
+    # trusted to the CLI filter, so the reap can only ever reach this suite's
+    # own namespace.
+    local _img _born _suffix
+    _suffix="$(basename "$BATS_RUN_TMPDIR")"
+    while IFS= read -r _img; do
+        [ -n "$_img" ] || continue
+        # Both spellings, because the images this suite builds were renamed to
+        # localhost/ (#53) after this reap was written against the bare form,
+        # and for two releases it therefore matched nothing. A reap whose
+        # pattern stops matching is not a reap that fails - it is one that
+        # silently does nothing, which is indistinguishable from having
+        # nothing to do, so nothing anywhere reported it.
+        #
+        # Matching both is also what stops the next rename doing it again.
+        case "$_img" in dejima-test-*|localhost/dejima-test-*) ;; *) continue ;; esac
+        case "$_img" in *":$_suffix") continue ;; esac
+        _born="$(docker image inspect -f '{{.Created}}' "$_img" 2>/dev/null)" || continue
+        _born="$(date -d "$_born" +%s 2>/dev/null)" || continue
+        [ "$(( $(date +%s) - _born ))" -gt "$REAP_AFTER" ] || continue
+        docker rmi -f "$_img" >/dev/null 2>&1 || true
+    done < <(docker images --format '{{.Repository}}:{{.Tag}}' 2>/dev/null)
+
     docker network create "$network" >/dev/null
 
     # No DEJIMA_FORGE_HOSTS/LOKI_URL: this suite only asserts the default
@@ -360,7 +425,7 @@ setup_file() {
         -e ANTHROPIC_BASE_URL= \
         -e ANTHROPIC_AUTH_TOKEN= \
         -e SANDBOX_HARNESS_DOMAINS="$(harness_manifest_value api_domains)" \
-        -e SANDBOX_HARNESS_PROXIED_DOMAIN="$(harness_manifest_value proxied_api_domain)" \
+        -e SANDBOX_BACKEND_PROXIED_DOMAIN="$(backend_manifest_value proxied_domain)" \
         --entrypoint /usr/local/bin/entrypoint.sh \
         "$SESSION_IMAGE" >/dev/null
 
@@ -407,7 +472,7 @@ teardown() {
         docker rm -f "$c" >/dev/null 2>&1 || true
     done < <(docker ps -a --filter "name=^dejima-test-.*$suffix\$" \
                  --format '{{.Names}}' 2>/dev/null)
-    docker images -q "dejima-test-*:$suffix" 2>/dev/null \
+    docker images -q "localhost/dejima-test-*:$suffix" 2>/dev/null \
         | xargs -r docker rmi -f >/dev/null 2>&1 || true
 }
 
@@ -420,7 +485,7 @@ dexec_node() {
 }
 
 @test "the container's user actually matches overridden SANDBOX_USER/UID/GID/HOME build args, not just the defaults" {
-    local test_image="dejima-test-override:$(basename "$BATS_RUN_TMPDIR")"
+    local test_image="localhost/dejima-test-override:$(basename "$BATS_RUN_TMPDIR")"
     local test_container="$(test_container_name override)"
     local sandbox_dir="$BATS_TEST_DIRNAME/../docker"
     local repo_root="$BATS_TEST_DIRNAME/.."
@@ -1256,17 +1321,16 @@ EOF'
     cat > "$TD/credentials.json" <<EOF
 {"claudeAiOauth":{"accessToken":"real-access-token","refreshToken":"r","expiresAt":$((($(date +%s) + 7200) * 1000)),"refreshTokenExpiresAt":$((($(date +%s) + 86400) * 1000)),"scopes":[],"subscriptionType":"max","rateLimitTier":"default"}}
 EOF
-    "$BATS_TEST_DIRNAME/../bin/dejima-anthropic-proxy" \
-        --socket "$TD/proxy.sock" --credentials "$TD/credentials.json" \
-        --upstream "http://127.0.0.1:$(cat "$TD/port")" &
-    PROXY_PID=$!
+    start_credential_proxy "$TD/proxy.sock" "$TD/credentials.json" \
+        "http://127.0.0.1:$(cat "$TD/port")" \
+        "http://127.0.0.1:$(cat "$TD/port")/v1/oauth/token"
     for _ in $(seq 1 50); do [ -S "$TD/proxy.sock" ] && break; sleep 0.1; done
     # UnixStreamServer binds at umask default, so the socket lands 755, and
     # connecting to a unix socket needs *write* permission on it. In the real
     # flow the connecting uid is the one that bound it, so that is fine;
     # under CI it is root binding and node connecting, and the whole chain
     # this test follows fails at its first hop. Widened rather than left to
-    # dejima-anthropic-proxy, which has no such problem in production.
+    # dejima-credential-proxy, which has no such problem in production.
     # Unconditional: if the loop above timed out, "No such file" here says so
     # more clearly than a test that fails on a bare false condition.
     chmod 666 "$TD/proxy.sock"
@@ -1278,7 +1342,7 @@ EOF
         -e SANDBOX_TEST_MODE=1 \
         -e GH_TOKEN="${GH_TOKEN:-}" \
         -e SANDBOX_ANTHROPIC_PROXY_SOCKET="$TD/proxy.sock" \
-        -e SANDBOX_HARNESS_PROXIED_DOMAIN="$(harness_manifest_value proxied_api_domain)" \
+        -e SANDBOX_BACKEND_PROXIED_DOMAIN="$(backend_manifest_value proxied_domain)" \
         -e SANDBOX_ANTHROPIC_TRANSPORT=loopback \
         -e ANTHROPIC_AUTH_TOKEN=sandbox-credential-proxy-placeholder \
         -v "$TD:$TD" \
@@ -1478,7 +1542,7 @@ EOF
 }
 
 @test "a derived project image gets the package and keeps the base privilege posture" {
-    local derived="dejima-test-derived:$(basename "$BATS_RUN_TMPDIR")"
+    local derived="localhost/dejima-test-derived:$(basename "$BATS_RUN_TMPDIR")"
     local test_container="$(test_container_name derived)"
     local ctx; ctx="$(mktemp -d)"
     local store; store="$(mktemp -d)"
@@ -1535,13 +1599,13 @@ EOF
 @test "live end-to-end: claude -p through the real proxy (RUN_LIVE_API=1 only)" {
     [ "${RUN_LIVE_API:-0}" = "1" ] || skip "set RUN_LIVE_API=1 to hit the real API"
     TD="$BATS_TEST_TMPDIR"
-    "$BATS_TEST_DIRNAME/../bin/dejima-anthropic-proxy" \
-        --socket "$TD/proxy.sock" --credentials "$HOME/.claude/.credentials.json" &
-    PROXY_PID=$!
+    start_credential_proxy "$TD/proxy.sock" "$HOME/.claude/.credentials.json" \
+        "https://api.anthropic.com" \
+        "https://platform.claude.com/v1/oauth/token"
     for _ in $(seq 1 50); do [ -S "$TD/proxy.sock" ] && break; sleep 0.1; done
     SANDBOX_ANTHROPIC_PROXY_SOCKET="$TD/proxy.sock" SANDBOX_ANTHROPIC_PROXY_PORT=18399 \
         SANDBOX_ANTHROPIC_TRANSPORT=loopback \
-        node "$BATS_TEST_DIRNAME/../docker/anthropic-proxy-forwarder.js" &
+        node "$BATS_TEST_DIRNAME/../docker/credential-proxy-forwarder.js" &
     FWD_PID=$!
     sleep 0.5
     run env ANTHROPIC_BASE_URL=http://127.0.0.1:18399 \
@@ -1630,10 +1694,9 @@ s.serve_forever()' "$bind_addr" > "$port_file" 2>/dev/null &
     cat > "$TD/credentials.json" <<EOF
 {"claudeAiOauth":{"accessToken":"real-access-token","refreshToken":"r","expiresAt":$((($(date +%s) + 7200) * 1000)),"refreshTokenExpiresAt":$((($(date +%s) + 86400) * 1000)),"scopes":[],"subscriptionType":"max","rateLimitTier":"default"}}
 EOF
-    "$BATS_TEST_DIRNAME/../bin/dejima-anthropic-proxy" \
-        --socket "$TD/proxy.sock" --credentials "$TD/credentials.json" \
-        --upstream "http://127.0.0.1:$(cat "$TD/port")" &
-    PROXY_PID=$!
+    start_credential_proxy "$TD/proxy.sock" "$TD/credentials.json" \
+        "http://127.0.0.1:$(cat "$TD/port")" \
+        "http://127.0.0.1:$(cat "$TD/port")/v1/oauth/token"
     for _ in $(seq 1 50); do [ -S "$TD/proxy.sock" ] && break; sleep 0.1; done
     # See the loopback test above for why this chmod is here.
     chmod 666 "$TD/proxy.sock"
@@ -1646,7 +1709,7 @@ EOF
         -e SANDBOX_TEST_MODE=1 \
         -e GH_TOKEN="${GH_TOKEN:-}" \
         -e SANDBOX_ANTHROPIC_PROXY_SOCKET="$TD/proxy.sock" \
-        -e SANDBOX_HARNESS_PROXIED_DOMAIN="$(harness_manifest_value proxied_api_domain)" \
+        -e SANDBOX_BACKEND_PROXIED_DOMAIN="$(backend_manifest_value proxied_domain)" \
         -v "$TD:$TD" \
         --entrypoint /usr/local/bin/entrypoint.sh \
         "$SESSION_IMAGE" >/dev/null

test/share.bats

@@ -0,0 +1,255 @@
+#!/usr/bin/env bats
+# The per-project share directory: what a launch mounts at ~/shared, and the
+# host-side CLI that says where it is.
+#
+# `[core] share_dir` used to be mounted whole, so every session saw every other
+# session's handoff files, across projects. What is asserted here is that the
+# mount is now one project's subdirectory, that an operator can still find it,
+# and that the files left over from the old layout are neither hidden silently
+# nor moved without being asked about.
+
+setup() {
+    REPO_ROOT="$BATS_TEST_DIRNAME/.."
+    LIB="$REPO_ROOT/bin/dejima-provider-lib.sh"
+    SLUG_LIB="$REPO_ROOT/bin/dejima-slug-lib.sh"
+    HOST="$(mktemp -d)"
+    CONFIG_DIR="$HOST/config"
+    SHARE="$HOST/share"
+    WS="$HOST/ws"
+    mkdir -p "$CONFIG_DIR" "$SHARE" "$WS" "$HOST/home/.claude"
+    echo '{}' > "$HOST/home/.claude/settings.json"
+    KEY="$HOST/sandbox-key"
+    : > "$KEY"
+    chmod 600 "$KEY"
+    export DEJIMA_CONFIG_DIR="$CONFIG_DIR"
+    # A dejima session exports several of these into every shell it starts, so
+    # a test that meant "unset" by not setting them would be reading the
+    # invoking environment rather than stating its own precondition.
+    unset SANDBOX_SHARE_DIR SANDBOX_CMD SANDBOX_EXTRA_MOUNTS LOKI_URL \
+        ENABLE_FIREWALL ALLOWED_DOMAINS
+}
+
+teardown() {
+    rm -rf "$HOST" ${STUB_DIR:+"$STUB_DIR"}
+}
+
+write_config() {
+    {
+        printf '[core]\nharness = claude-code\nforge = none\nworkflow = local-only\n'
+        printf 'update_check = off\nssh_key = %s\nshare_dir = %s\n' "$KEY" "$SHARE"
+        [ "$#" -eq 0 ] || printf '%s\n' "$@"
+    } > "$CONFIG_DIR/config"
+}
+
+slug() { bash -c 'source "$1"; ws_slug "$2"' _ "$SLUG_LIB" "$1"; }
+
+share() { "$REPO_ROOT/bin/dejima-share" "$@"; }
+
+# Drives the real launch with a stubbed docker, and records what
+# SANDBOX_SHARE_DIR was when compose was invoked. Reading --print-config
+# instead would pass against a version that resolved the path correctly and
+# then mounted something else.
+launch() {
+    STUB_DIR="$(mktemp -d)"
+    cat > "$STUB_DIR/docker" <<'EOF'
+#!/bin/sh
+printf '%s\n' "${SANDBOX_SHARE_DIR-}" >> "$SANDBOX_TEST_SHARE_LOG"
+exit 0
+EOF
+    chmod +x "$STUB_DIR/docker"
+    SHARE_LOG="$HOST/share-log"
+    : > "$SHARE_LOG"
+    HOME="$HOST/home" PATH="$STUB_DIR:$PATH" SSH_AUTH_SOCK= \
+        SANDBOX_TEST_SHARE_LOG="$SHARE_LOG" \
+        run "$REPO_ROOT/bin/dejima" "${1:-$WS}"
+}
+
+# What the launch actually handed compose, deduplicated - compose is invoked
+# more than once per launch and every call must agree.
+mounted_share() { sort -u "$SHARE_LOG" | grep -v '^$' | head -1; }
+
+@test "a launch mounts one project's subdirectory, not share_dir itself" {
+    write_config
+    launch
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
+    [ "$(mounted_share)" = "$SHARE/projects/$(slug "$WS")" ] \
+        || { echo "mounted '$(mounted_share)'"; return 1; }
+    [ -d "$SHARE/projects/$(slug "$WS")" ] \
+        || { echo "the launch did not create the directory it mounts"; return 1; }
+}
+
+@test "two projects get two directories" {
+    local other="$HOST/other"
+    mkdir -p "$other"
+    write_config
+    launch "$WS"
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
+    local first="$(mounted_share)"
+    launch "$other"
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
+    [ "$first" != "$(mounted_share)" ] \
+        || { echo "both projects mounted $first"; return 1; }
+}
+
+@test "dejima-share path prints the directory a launch mounts, and creates it" {
+    write_config
+    run share path "$WS"
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
+    [ -d "$output" ] || { echo "path did not create $output"; return 1; }
+    local printed="$output"
+    launch
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
+    # The point of the shared layout helpers: an operator dropping a file where
+    # `path` says would otherwise be dropping it where nothing reads it.
+    [ "$printed" = "$(mounted_share)" ] \
+        || { echo "path said $printed, the launch mounted $(mounted_share)"; return 1; }
+}
+
+@test "dejima-share path defaults to the current directory" {
+    write_config
+    cd "$WS"
+    run share path
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
+    [ "$output" = "$SHARE/projects/$(slug "$WS")" ] || { echo "$output"; return 1; }
+}
+
+@test "dejima-share path refuses a directory that does not exist" {
+    # It would otherwise answer a typo with a share directory nothing will
+    # ever mount, which is worse than refusing: the file goes somewhere real
+    # and no session sees it.
+    write_config
+    run share path "$HOST/no-such-project"
+    [ "$status" -ne 0 ]
+    [[ "$output" == *"no such directory"* ]] || { echo "$output"; return 1; }
+}
+
+@test "a launch says which files the split left behind, every time until they are gone" {
+    write_config
+    echo secret > "$SHARE/left-over.txt"
+    launch
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
+    [[ "$output" == *"left-over.txt"* ]] \
+        || { echo "the launch hid a file it stopped mounting: $output"; return 1; }
+    [[ "$output" == *"dejima-share adopt"* ]] \
+        || { echo "it does not say what to do about it: $output"; return 1; }
+    # Said again rather than once: a file handed to a session yesterday and
+    # silently not arriving today is the failure this exists against.
+    launch
+    [[ "$output" == *"left-over.txt"* ]] || { echo "$output"; return 1; }
+    rm "$SHARE/left-over.txt"
+    launch
+    [[ "$output" != *"no session can see"* ]] \
+        || { echo "still warning with nothing left over: $output"; return 1; }
+}
+
+@test "the per-project root is not itself reported as left behind" {
+    write_config
+    launch
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
+    [[ "$output" != *"no session can see"* ]] \
+        || { echo "a clean share_dir warned about its own projects dir: $output"; return 1; }
+}
+
+@test "dejima-share list names each project and flags what is loose" {
+    write_config
+    share path "$WS" > /dev/null
+    echo x > "$SHARE/loose-file"
+    run share list
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
+    [[ "$output" == *"$(slug "$WS")"* ]] || { echo "$output"; return 1; }
+    [[ "$output" == *"loose-file"* ]] || { echo "$output"; return 1; }
+    # The retention story is the only one there is: nothing prunes this.
+    [[ "$output" == *"Nothing prunes this"* ]] || { echo "$output"; return 1; }
+}
+
+@test "adopt moves nothing without a yes" {
+    write_config
+    echo keep > "$SHARE/left-over.txt"
+    run bash -c 'printf "n\n" | "$1" adopt "$2"' _ "$REPO_ROOT/bin/dejima-share" "$WS"
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
+    [ -f "$SHARE/left-over.txt" ] || { echo "declining still moved it"; return 1; }
+    # And an empty answer is a no, not a prompt loop or a yes.
+    run bash -c 'printf "\n" | "$1" adopt "$2"' _ "$REPO_ROOT/bin/dejima-share" "$WS"
+    [ -f "$SHARE/left-over.txt" ] || { echo "an empty answer moved it"; return 1; }
+}
+
+@test "adopt moves what is loose into one project's share" {
+    write_config
+    echo one > "$SHARE/a.txt"
+    mkdir -p "$SHARE/adir"
+    echo two > "$SHARE/adir/b.txt"
+    run bash -c 'printf "y\n" | "$1" adopt "$2"' _ "$REPO_ROOT/bin/dejima-share" "$WS"
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
+    local dest="$SHARE/projects/$(slug "$WS")"
+    [ -f "$dest/a.txt" ] || { echo "a.txt did not arrive"; return 1; }
+    [ -f "$dest/adir/b.txt" ] || { echo "the directory did not arrive whole"; return 1; }
+    [ ! -e "$SHARE/a.txt" ] || { echo "a.txt is still loose"; return 1; }
+    [ "$(cat "$dest/a.txt")" = one ] || { echo "contents changed"; return 1; }
+}
+
+@test "adopt never overwrites" {
+    # Both files are the operator's and this cannot know which one they meant,
+    # so the loose one stays loose and says so.
+    write_config
+    local dest="$SHARE/projects/$(slug "$WS")"
+    mkdir -p "$dest"
+    echo kept > "$dest/a.txt"
+    echo incoming > "$SHARE/a.txt"
+    run bash -c 'printf "y\n" | "$1" adopt "$2"' _ "$REPO_ROOT/bin/dejima-share" "$WS"
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
+    [ "$(cat "$dest/a.txt")" = kept ] || { echo "it overwrote the destination"; return 1; }
+    [ -f "$SHARE/a.txt" ] || { echo "it removed the source it refused to move"; return 1; }
+    [[ "$output" == *"already has one"* ]] || { echo "$output"; return 1; }
+}
+
+@test "adopt says so when there is nothing loose" {
+    write_config
+    share path "$WS" > /dev/null
+    run share adopt "$WS"
+    [ "$status" -eq 0 ] || { echo "$output"; return 1; }
+    [[ "$output" == *"Nothing loose"* ]] || { echo "$output"; return 1; }
+}
+
+@test "a writable mount naming the share root is refused" {
+    # The ~/shared mount is per project only while nothing else hands the whole
+    # of it over. A session's own share arrives without going through
+    # [mounts] read_write at all, so refusing costs nothing here.
+    write_config '[mounts]' "read_write = $SHARE/projects"
+    mkdir -p "$SHARE/projects"
+    launch
+    [ "$status" -ne 0 ] || { echo "mounted every project's handoff files"; return 1; }
+    [[ "$output" == *"Refusing"* ]] || { echo "$output"; return 1; }
+    [[ "$output" == *"handoff"* ]] || { echo "the refusal does not say why: $output"; return 1; }
+}
+
+@test "a read-only mount naming the share root is refused too" {
+    write_config
+    mkdir -p "$SHARE/projects"
+    launch_ro() {
+        STUB_DIR="$(mktemp -d)"
+        printf '#!/bin/sh\nexit 0\n' > "$STUB_DIR/docker"
+        chmod +x "$STUB_DIR/docker"
+        HOME="$HOST/home" PATH="$STUB_DIR:$PATH" SSH_AUTH_SOCK= \
+            run "$REPO_ROOT/bin/dejima" --extra-readonly "$SHARE/projects" "$WS"
+    }
+    launch_ro
+    [ "$status" -ne 0 ] || { echo "read-only was enough to hand it over"; return 1; }
+    [[ "$output" == *"Refusing"* ]] || { echo "$output"; return 1; }
+}
+
+@test "the briefing tells the session the share directory is this project's" {
+    # The agent is told to leave things in ~/shared and to pick things up
+    # there. The path inside the container did not change, so what has to
+    # change is what it is told about who else can read it.
+    local out flat
+    out="$(bash -c 'source "$1"; briefing_compose none local-only claude-code' _ "$LIB")" \
+        || { echo "$out"; return 1; }
+    [[ "$out" == *"~/shared"* ]] || { echo "the briefing lost ~/shared"; return 1; }
+    # Flattened, because the sentence wraps: a phrase spanning a line break
+    # matches nothing and the test fails on a reflow that changed no words.
+    flat="$(tr '\n' ' ' <<< "$out" | tr -s ' ')"
+    [[ "$flat" == *"this project's own"* ]] \
+        || { echo "the briefing still reads as one directory for the host"; return 1; }
+    [[ "$flat" == *"every session against this project shares it"* ]] \
+        || { echo "the briefing does not say who else can read it"; return 1; }
+}

web/test/gestures.test.js

@@ -0,0 +1,96 @@
+'use strict';
+const { test } = require('node:test');
+const assert = require('node:assert');
+require('../src/gestures.js');
+const { createGestures } = globalThis.DEJIMA.gestures;
+
+const CELL = 20; // rows are 20px tall in every world below
+
+// An element that records the listeners createGestures attaches, so a test can
+// fire a touch sequence at it without a DOM.
+function makeElement() {
+  const listeners = {};
+  return {
+    addEventListener: (type, fn) => { (listeners[type] = listeners[type] || []).push(fn); },
+    fire: (type, event) => { (listeners[type] || []).forEach((fn) => fn(event)); }
+  };
+}
+
+function touchEvent(points) {
+  return {
+    touches: points.map((p) => ({ clientX: p.x, clientY: p.y })),
+    preventDefault: function () { this.defaultPrevented = true; },
+    defaultPrevented: false
+  };
+}
+
+// reporting: whether the application has asked for mouse reports, which is
+// what decides who receives a notch and so what one is worth.
+function makeWorld(reporting) {
+  const element = makeElement();
+  const scrolled = [];   // this page's own scrollback, one row per entry
+  const wheeled = [];    // notches sent to the application
+  const gestures = createGestures({
+    element: element,
+    term: {
+      scrollLines: (n) => scrolled.push(n),
+      getSelection: () => ''
+    },
+    mouse: {
+      cellHeight: () => CELL,
+      enabled: () => !!reporting,
+      cellAt: () => ({ col: 1, row: 1 }),
+      wheel: (cell, up) => wheeled.push(up ? 'up' : 'down'),
+      altScreen: () => false,
+      press: () => {}, motion: () => {}, release: () => {}
+    },
+    dragMode: () => false,
+    onCopy: () => {}
+  });
+  gestures.attach();
+  return {
+    element, scrolled, wheeled,
+    // A one-finger drag of `rows` rows, downward, which pulls earlier output
+    // into view. Delivered as one touchmove: scrollBy accumulates travel, so
+    // the split into events is not what the count under test depends on.
+    dragDown: function (rows) {
+      element.fire('touchstart', touchEvent([{ x: 100, y: 100 }]));
+      element.fire('touchmove', touchEvent([{ x: 100, y: 100 + rows * CELL }]));
+      element.fire('touchend', touchEvent([]));
+    }
+  };
+}
+
+// One notch per row of finger travel, whichever side receives the notch.
+// What a notch is then WORTH belongs to the receiver: this page moves one row,
+// and tmux's copy mode moves five until its binding says otherwise.
+
+test('scrollback moves one row per row of finger travel', () => {
+  const w = makeWorld(false);
+  w.dragDown(10);
+  assert.equal(w.scrolled.length, 10);
+  assert.ok(w.scrolled.every((n) => n === -1), 'dragging down goes back in history');
+  assert.equal(w.wheeled.length, 0, 'no application is listening');
+});
+
+test('an application gets one notch per row of finger travel', () => {
+  const w = makeWorld(true);
+  w.dragDown(10);
+  assert.equal(w.wheeled.length, 10);
+  assert.ok(w.wheeled.every((d) => d === 'up'), 'dragging down scrolls up');
+  assert.equal(w.scrolled.length, 0, 'the page did not also scroll itself');
+});
+
+test('travel shorter than a row sends nothing rather than rounding up', () => {
+  const w = makeWorld(true);
+  w.element.fire('touchstart', touchEvent([{ x: 100, y: 200 }]));
+  w.element.fire('touchmove', touchEvent([{ x: 100, y: 200 + CELL / 2 }]));
+  assert.equal(w.wheeled.length, 0);
+});
+
+test('dragging up scrolls forward again', () => {
+  const w = makeWorld(true);
+  w.element.fire('touchstart', touchEvent([{ x: 100, y: 300 }]));
+  w.element.fire('touchmove', touchEvent([{ x: 100, y: 300 - 3 * CELL }]));
+  assert.deepEqual(w.wheeled, ['down', 'down', 'down']);
+});