From a66cae3856868ab5f056082c9663cee8e2374ea7 Mon Sep 17 00:00:00 2001
From: Bret Mogilefsky <bret.mogilefsky@gsa.gov>
Date: Mon, 21 Sep 2026 22:05:23 +0000
Subject: [PATCH 01/12] docs(adr): add ADR-0030 host-authoritative sandbox
 configuration

Records the principle that acq must not rely on guest-generated or
guest-tamperable state to configure the sandbox: because the in-sandbox agent
has passwordless sudo, guest root-ownership is not a trust boundary against a
prompt-injected agent. The only enforceable boundary is host<->guest.

acq-trusted inputs (data AND code) must be either host-resident and mounted
read-only into the guest, or held on the host and injected at exec time --
never read back from the guest and treated as authoritative.

Introduces a per-sandbox host config directory mounted read-only, and trusted
startup execution invoked from that read-only mount (three options considered;
option 1 -- mount kit code read-only and invoke from the :ro path -- selected).
Documents the staged migration of the existing /var/lib/acq markers (agent,
workspace, ssh-auth-sock, kit-env, and the presence gates) off guest-writable
paths. First consumer: patterns ADR 0003 (neutral model-provider discovery).

Includes two Mermaid sequence diagrams (GitHub/Host/Guest boxes) contrasting
the rejected guest-write path with the chosen host-materialized read-only path.

Co-authored-by: OpenCode [claude_4_8_opus] <bret.mogilefsky@gsa.gov>
---
 .../0030-host-authoritative-sandbox-config.md | 308 ++++++++++++++++++
 1 file changed, 308 insertions(+)
 create mode 100644 docs/adr/0030-host-authoritative-sandbox-config.md

diff --git a/docs/adr/0030-host-authoritative-sandbox-config.md b/docs/adr/0030-host-authoritative-sandbox-config.md
new file mode 100644
index 00000000..5c7c90a6
--- /dev/null
+++ b/docs/adr/0030-host-authoritative-sandbox-config.md
@@ -0,0 +1,308 @@
+---
+title: "Host-Authoritative Sandbox Configuration (no trust in guest-generated state)"
+status: accepted
+date: 2026-09-21
+decision_makers: ["Bret Mogilefsky"]
+category: architecture
+nist_controls: ["AC-3", "AC-6", "CM-5", "CM-6", "SC-7", "SI-7", "SI-10", "SI-17"]
+impact_level: moderate
+ato_relevance: no
+risk_treatment: mitigate
+supersedes: []
+---
+
+# ADR-0030: Host-Authoritative Sandbox Configuration (no trust in guest-generated state)
+
+## Context and Problem Statement
+
+acq deliberately gives the in-sandbox `agent` user **passwordless sudo** (see
+`AGENTS.md`, and the msb agent-user provisioning in
+`acq.backends/msb.sh`: `/etc/sudoers.d/90-acq-agent … NOPASSWD:ALL`). This is an
+intentional convenience: the sandbox — not the guest OS user boundary — is the
+security boundary (ADR-0005, ADR-0011). A consequence follows that has not been
+stated as a principle until now:
+
+> **Inside the guest, root-ownership is not a trust boundary against the agent.**
+> A prompt-injected agent can `sudo` to root and rewrite any file in the guest,
+> including anything under a root-owned path such as `/var/lib/acq/`.
+
+acq currently violates the safe form of this in two ways:
+
+1. **acq reads guest-written state back and acts on it.** Four content-bearing
+   markers under the guest path `/var/lib/acq/` are written by acq (via
+   `msb exec -u 0`), then read back on a later session/restart and used to
+   *configure the sandbox*:
+
+   | Marker | Written (host fn) | Read back → effect |
+   |---|---|---|
+   | `agent` | `acq_backend_provision` | selects which binary the re-attach launches |
+   | `workspace` | `acq_backend_provision` | sets the session working directory (`-w`) |
+   | `ssh-auth-sock` | ssh-agent bridge starter | sets `-e SSH_AUTH_SOCK=…` for git/ssh signing |
+   | `kit-env` | `_acq_msb_apply_kit_dir` | replays kit `environment[]` as `-e NAME=value` on every session |
+
+   Each read is charset/token-hardened against *shell injection* (e.g.
+   `_acq_msb_safe_agent_token`, the `kit-env` awk name re-validation), so a
+   tampered marker cannot break out of an `sh -c`. But the hardening does not stop
+   a sudo-capable guest from setting a **valid-but-malicious value**: redirect
+   `SSH_AUTH_SOCK`, change the launched agent to another allowed token, change the
+   cwd, or inject arbitrary environment variables into the agent process. The
+   guest can influence its own host-driven reconfiguration.
+
+2. **acq re-runs guest-resident kit code across a restart.** On msb, kit
+   `files[]` (including startup scripts and config-merge programs such as the
+   provider kits' `merge-*-config.mjs`) are copied *into the guest* at provision
+   and then `chown`ed to the agent. acq's restart heal
+   (`acq_backend_ensure_kits_applied`) re-runs the `startup` phase by invoking
+   those **guest-resident** files. A sudo-capable agent can overwrite a startup
+   script or normalizer *between* provision and the next restart; the heal then
+   executes the tampered code. This is the general form of the
+   "provider-facts file is root-owned, therefore safe" error flagged in the
+   `agentic-coding-patterns` PR #423 review — root-ownership is not the barrier
+   it appears to be.
+
+A concrete instance motivating this ADR: the neutral model-provider discovery
+design (patterns ADR 0003) originally had each provider kit **write** a facts
+file to a root-owned guest path in its own `startup` command, and claimed that
+path was "not agent-writable." Under passwordless sudo it is. A planted or
+tampered facts file would let the guest steer model routing (and, absent the
+host-side validation this ADR requires, an SSRF/credential-misuse surface).
+
+### Presence-only gates (a lower-severity variant of the same problem)
+
+Four other `/var/lib/acq/` files are `touch`/`test -f` idempotency gates
+(`install-<cksum>`, `agent-installed-<agent>`, `agent-user-ready`, `oci-ready`).
+Their *content* is never consumed, but a guest can pre-`touch` them to
+**suppress** a provisioning step (skip an install, skip the agent-user/sudoers
+setup, skip OCI setup). That is a downgrade/DoS on setup rather than injection,
+but it is the same root cause: acq relies on guest-resident state to make a
+provisioning decision.
+
+## Decision Drivers
+
+- **The only enforceable boundary is host↔guest.** A value acq holds on the host
+  (in memory, or in a host file the guest cannot write) is beyond the reach of a
+  sudo-capable guest; a value living in the guest is not.
+- **Least privilege / integrity** (AC-6, SI-7): the sandbox's configuration must
+  not be forgeable by the workload it sandboxes.
+- **Preserve the sandbox-is-the-boundary model** (ADR-0005/0011): this ADR does
+  **not** remove passwordless sudo. It removes acq's *reliance on* guest-writable
+  state for configuration, which is orthogonal.
+- **No code execution on the host** (the deciding factor that rejected patterns
+  ADR 0003's "Option 2"): acq may read *static data* from a pinned kit directory
+  on the host, but must not *execute* kit-shipped code on the host, next to real
+  credentials.
+- **Backend parity and Windows path forms**: any new mount must work on both
+  msb (`--volume host:guest:ro`) and sbx (`:ro` positional), and respect the
+  host/guest path-form split (ADR-0029).
+- **Fail-soft preservation**: the current marker writes are best-effort
+  (`|| true`); the migration must not turn a transient state-dir hiccup into a
+  hard provision abort where it was previously survivable.
+
+## The principle (normative)
+
+> **acq MUST NOT rely on guest-generated or guest-tamperable state to configure
+> the sandbox.** Every input acq trusts to make a configuration or
+> lifecycle decision — data *and* code — MUST be one of:
+>
+> - **(H1) Host-resident and mounted read-only into the guest** (the VMM/mount
+>   layer enforces read-only; guest sudo cannot override it), or
+> - **(H2) Held on the host and supplied at exec time** from acq's own state
+>   (never read back from the guest).
+>
+> The guest may freely write its own genuinely-owned read-write state (the
+> workspace, a per-sandbox cache, kit scratch) — acq simply must not read that
+> state back and treat it as authoritative configuration.
+
+## Considered Options (trusted startup execution)
+
+The data case (H1/H2) is straightforward. The harder case is **running trusted
+code in the guest at startup** — acq's restart heal must invoke a kit's
+`startup`/normalizer logic without trusting a guest-resident, agent-tamperable
+copy of it. Three options were considered:
+
+1. **Mount the kit's executable payload read-only and invoke it from the `:ro`
+   path.** acq stages the pinned kit's startup scripts/normalizers from the
+   host-side kit directory it already fetched into a per-sandbox host config
+   dir, mounts that dir `:ro` into the guest, and the heal executes
+   `sh /var/lib/acq/host/<kit>/<script>` from the read-only mount. The guest can
+   read and execute it but cannot rewrite it. Uniform with the data case (H1):
+   *all* acq-trusted inputs, data and code, are host-materialized and `:ro`.
+
+2. **Re-push the code fresh from the host on every heal.** Before each startup
+   run, acq re-`copy`s the script from the pinned kit dir, overwriting any
+   tampering, then execs it from a normal (guest-writable) path. No new mount,
+   but a **TOCTOU window** remains between the copy and the exec (a racing sudo
+   process can rewrite it in between), and it fights the existing
+   copy-then-chown-to-agent flow. Strictly weaker than (1).
+
+3. **Register the script via msb `--script-path` and rely on native replay.**
+   Rejected on mechanism, not security: ADR-0017 established (source-verified)
+   that a bare `--script-path` registration is *inert at boot* on the pinned msb
+   — `start_detached` replays only `runtime.entrypoint`/`runtime.cmd` — and that
+   a native `msb start` cannot even boot a secret-bound sandbox without acq's
+   secret injection. So this reduces in practice to acq invoking the staged file
+   itself, i.e. to option (1) or (2), and adds nothing.
+
+## Decision Outcome
+
+**Chosen: Option 1 — host-materialize acq-trusted inputs (data *and* code) and
+mount them read-only; invoke code from the `:ro` path.**
+
+Concretely, this ADR introduces two mechanisms and a staged migration.
+
+### Mechanism 1 — Per-sandbox host config directory, mounted `:ro`
+
+- A new per-sandbox host directory under the acq state tree, keyed by
+  backend + sandbox name using the same sanitized-filename + raw-name-checksum
+  scheme as the existing provenance/CLI-kit records
+  (`acq.backends/common.sh`): e.g.
+  `${ACQ_STATE_DIR}/config/<backend>.<sandbox>.<sum>/`.
+- acq populates it **on the host** at provision (and refreshes it on the heal):
+  static facts/config read from the **pinned** kit directories acq already
+  fetches (`_acq_msb_fetch_kit`) and validates on the host — never by executing
+  kit code on the host.
+- acq mounts that directory into the guest **read-only** at a well-known path:
+  `/var/lib/acq/host/` (`:ro`). On msb via `--volume <hostdir>:/var/lib/acq/host:ro`;
+  on sbx via the `:ro` positional the CLI already honors (confirmed: sbx enforces
+  read-only on extra mounts; msb builds the `:ro` `--volume` flag itself). Host
+  and guest path forms follow ADR-0029.
+- In-guest consumers (kit orchestrators, the agent) **read** from
+  `/var/lib/acq/host/…` but cannot write it. Guest-owned read-write state stays
+  on separate rw paths.
+
+### Mechanism 2 — Trusted startup execution from the `:ro` mount
+
+- Kit `startup` code that acq re-runs across restarts is staged into the same
+  per-sandbox `:ro` config dir and invoked from there by the heal, so a restart
+  always executes the host-authoritative (pinned) copy, not a guest-tampered one.
+- Kits that genuinely must *compute* runtime state in-guest still may — they
+  write their output to a guest-owned **rw** path (e.g. a per-sandbox catalog
+  cache), which acq never treats as authoritative configuration. (This is
+  exactly the boundary patterns ADR 0003 now draws: read-only provider *facts*
+  from the `:ro` mount; rw *catalog* generated per-sandbox at startup, never
+  shared across sandboxes.)
+
+### Migration (one tracking issue, one PR, a commit per change)
+
+Applied incrementally, each preserving the current best-effort fail-soft
+behavior:
+
+1. **Facts + `:ro` mount plumbing** (unblocks patterns ADR 0003 Layer 1): add the
+   per-sandbox host config dir and the `:ro` mount on both backends.
+2. **`agent`, `workspace`**: acq authors these already — write them to the host
+   config dir and stop reading them back from the guest.
+3. **`ssh-auth-sock`**: acq already knows the value (its own constant) — hold it
+   host-side and inject at exec; stop reading it back.
+4. **`kit-env`**: acq already parses each kit's `environment[]` on the host
+   during apply — persist the validated env to the host config dir and replay
+   from there; stop reading the guest marker.
+5. **Presence gates** (`install-*`, `agent-installed-*`, `agent-user-ready`,
+   `oci-ready`): move to the host config dir so a guest cannot forge them to
+   suppress provisioning. (Lower severity; last.)
+
+## Threat model and flows
+
+Participants: **GitHub** (pinned kit source), **Host** (acq + real credentials +
+the state tree), **Guest** (the microVM/container; agent has passwordless sudo).
+
+### Rejected flow — kit writes trusted state in the guest
+
+```mermaid
+sequenceDiagram
+    box GitHub
+    participant KIT as Pinned kit repo
+    end
+    box Host
+    participant ACQ as acq
+    end
+    box Guest (agent has sudo)
+    participant STARTUP as kit startup cmd
+    participant AGENT as agent (injectable)
+    participant FS as /var/lib/acq (root-owned)
+    end
+
+    ACQ->>KIT: fetch pinned kit
+    ACQ->>STARTUP: run startup (msb exec)
+    STARTUP->>FS: write facts.json (as root)
+    Note over FS: "root-owned ⇒ safe" — FALSE under sudo
+    AGENT->>FS: sudo tee facts.json (tamper)
+    ACQ->>FS: read facts.json back
+    ACQ->>ACQ: configure sandbox from tampered value
+    Note over ACQ: guest steered its own host-side config
+```
+
+### Chosen flow — host-materialized, guest read-only
+
+```mermaid
+sequenceDiagram
+    box GitHub
+    participant KIT as Pinned kit repo
+    end
+    box Host
+    participant ACQ as acq
+    participant HSTATE as state/config/<sandbox> (host)
+    end
+    box Guest (agent has sudo)
+    participant RO as /var/lib/acq/host (:ro)
+    participant AGENT as agent (injectable)
+    participant RW as rw cache (guest-owned)
+    end
+
+    ACQ->>KIT: fetch pinned kit (static data + code)
+    ACQ->>ACQ: validate facts host-side (env-var-ownership, SSRF, schema)
+    ACQ->>HSTATE: write validated facts + staged startup code
+    ACQ->>RO: mount HSTATE read-only (--volume …:ro / :ro positional)
+    AGENT-->>RO: sudo tee facts.json (FAILS: read-only mount, VMM-enforced)
+    ACQ->>RO: invoke staged startup from :ro path
+    RO->>RW: orchestrator computes per-sandbox catalog (rw, not shared)
+    Note over ACQ,RO: acq trusts only host-authoritative :ro inputs
+```
+
+## Consequences
+
+### Positive
+
+- A prompt-injected, sudo-capable agent can no longer forge or tamper the state
+  acq uses to configure the sandbox, launch the agent, set its environment, or
+  re-run startup across restarts (AC-6, SI-7, SI-17).
+- Establishes a single, uniform rule for all future acq-trusted inputs
+  (data and code): host-materialized and `:ro`, or host-held and exec-injected.
+- Directly unblocks patterns ADR 0003 Layer 1 with a real integrity guarantee,
+  replacing the incorrect "root-owned ⇒ safe" claim.
+
+### Negative / risks
+
+- New per-sandbox mount and host state dir to create, refresh, and clean up
+  (mirrors the existing `clones/`, `ports/`, provenance records — low novelty).
+- Startup gains a small host-materialize + mount step. Bounded and one-time
+  per provision/heal.
+- Windows path-form handling (ADR-0029) must cover the new mount and any staged
+  script paths.
+- The current marker writes are best-effort; the migration must keep that
+  fail-soft posture rather than converting a state-dir error into a hard abort.
+
+### Neutral
+
+- Passwordless sudo is unchanged. This ADR narrows what acq *trusts*, not what
+  the agent *can do* inside its sandbox.
+- No change to the neutral `hybrid/v1` kit vocabulary is required for the
+  mechanism itself; the provider-facts declaration is specified in patterns
+  ADR 0003.
+
+## Links
+
+- ADR-0005 — kits-from-patterns and the agent trust model (sandbox is the
+  boundary; passwordless sudo rationale).
+- ADR-0011 — msb backend and neutral kits (the exec-based marker/kit-apply paths
+  this ADR migrates; the agent-user/sudoers provisioning).
+- ADR-0017 — msb create-time startup-script staging (why native `--script-path`
+  replay is inert and restart durability is acq's exec heal; grounds Option 3's
+  rejection).
+- ADR-0021 — host ssh-agent forwarding (the `ssh-auth-sock` marker migrated in
+  step 3).
+- ADR-0023 / ADR-0027 — neutral `volumes[]` and `:ro` workspace mounts (the
+  read-only mount capability this ADR reuses).
+- ADR-0029 — Windows host/guest path forms (applies to the new `:ro` mount).
+- `agentic-coding-patterns` ADR 0003 (isolation) — neutral model-provider
+  discovery; its Layer 1 provider-facts channel is the first consumer of this
+  mechanism and references this ADR as the mechanism of record.

From d077381c89474f0cdb9eb9f5d744b600cf20c4aa Mon Sep 17 00:00:00 2001
From: Bret Mogilefsky <bret.mogilefsky@gsa.gov>
Date: Mon, 21 Sep 2026 22:40:50 +0000
Subject: [PATCH 02/12] feat(acq): add host-authoritative per-sandbox config
 store + :ro mount (ADR-0030)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduce a host-side per-sandbox config store (acq_host_config_* in common.sh)
keyed like the provenance/cli-kits records, and mount it into the msb guest
READ-ONLY at ACQ_HOST_CONFIG_GUEST_DIR (default /var/lib/acq/host) via
--volume host:guest:ro. This is the mechanism ADR-0030 defines: acq's trusted
per-sandbox config lives on the host, and where the guest must read it, it sees
a read-only mount the VMM enforces — a passwordless-sudo agent can read but
cannot forge it.

This commit adds only the store + mount plumbing and terminate-time cleanup on
both backends; subsequent commits migrate the individual /var/lib/acq markers
(agent, workspace, ssh-auth-sock, kit-env, and the presence gates) off the
guest-writable paths onto this store.

Refs: GSA-TTS/agentic-coding-quickstart#503

Co-authored-by: OpenCode [claude_4_8_opus] <bret.mogilefsky@gsa.gov>
---
 acq.backends/common.sh | 157 +++++++++++++++++++++++++++++++++++++++++
 acq.backends/msb.sh    |  25 +++++++
 acq.backends/sbx.sh    |   5 ++
 3 files changed, 187 insertions(+)

diff --git a/acq.backends/common.sh b/acq.backends/common.sh
index 53b4c6b1..37a103fd 100644
--- a/acq.backends/common.sh
+++ b/acq.backends/common.sh
@@ -1509,6 +1509,163 @@ acq_cli_kits_load() {
   return 0
 }
 
+# ============================================================================
+# Host-authoritative per-sandbox config store (ADR-0030)
+# ============================================================================
+# acq must NOT rely on guest-generated or guest-tamperable state to configure a
+# sandbox: the in-sandbox agent has passwordless sudo, so a root-owned GUEST path
+# (e.g. /var/lib/acq/agent) is NOT a trust boundary against a prompt-injected
+# agent — it can sudo-rewrite any such file, and acq would then read the tampered
+# value back and act on it (which agent to launch, cwd, SSH_AUTH_SOCK, kit env).
+#
+# The only enforceable boundary is host<->guest. This store holds acq's trusted
+# per-sandbox config on the HOST (under the same state tree as provenance and the
+# cli-kits record) and, where the guest legitimately needs to read a value, acq
+# mounts the directory into the guest READ-ONLY (see the backend :ro mount).
+# The guest can read it but cannot write it; a sudo agent cannot forge it.
+#
+# Layout (host):   <provenance-dir>/<backend>/<safe-name>.<sum>.config/<KEY>
+# Guest mount:     ACQ_HOST_CONFIG_GUEST_DIR (read-only)  [default /var/lib/acq/host]
+# One flat file per KEY (value = raw bytes, no trailing newline added), so a
+# value may contain any byte a single line could not; readers get exactly what
+# was written. Atomic temp+rename write; fail-soft (mirrors the marker writes
+# it replaces, which were best-effort `|| true`).
+#
+# KEY charset is restricted ([A-Za-z0-9._-], no slash) so a key can never escape
+# the config dir; callers pass fixed literals (agent, workspace, ssh-auth-sock,
+# kit-env, and the gate markers).
+
+# The well-known guest mount point for the read-only host config dir. Overridable
+# for tests / unusual images. Kept under /var/lib/acq so it sits beside the
+# (being-migrated) legacy guest markers without colliding with them.
+ACQ_HOST_CONFIG_GUEST_DIR="${ACQ_HOST_CONFIG_GUEST_DIR:-/var/lib/acq/host}"
+
+# Host directory holding one sandbox's config files. Same keying as the
+# provenance/cli-kits records (sanitized name + raw-name checksum) so the three
+# sit side by side and never collide across backends or sanitizer-aliased names.
+acq_host_config_dir() {
+  local backend="${1:-}" name="${2:-}"
+  [ -n "$backend" ] && [ -n "$name" ] || return 1
+  local safe_backend safe_name name_sum
+  safe_backend=$(printf '%s' "$backend" | tr -c 'A-Za-z0-9._-' '_')
+  safe_name=$(printf '%s' "$name" | tr -c 'A-Za-z0-9._-' '_')
+  name_sum=$(printf '%s' "$name" | cksum 2>/dev/null | cut -d' ' -f1 2>/dev/null || echo 0)
+  printf '%s/%s/%s.%s.config\n' "$(_acq_provenance_dir)" "$safe_backend" "$safe_name" "$name_sum"
+}
+
+# Validate a config KEY: fixed-literal callers only, restricted charset, never a
+# path separator or traversal. Fail closed (return non-zero, emit nothing).
+_acq_host_config_key_ok() {
+  case "${1:-}" in
+    ""|.|..) return 1 ;;
+    *[!A-Za-z0-9._-]*) return 1 ;;
+    *) return 0 ;;
+  esac
+}
+
+# Write one KEY's VALUE for a sandbox's host config. Creates the dir 0700 and the
+# file 0600 (world-unreadable on the host; the guest sees it via the :ro mount).
+# Atomic temp+rename. Best-effort: warns (debug) and returns non-zero on failure
+# but never aborts the caller — preserving the fail-soft posture of the guest
+# markers this replaces.
+# Usage: acq_host_config_write BACKEND NAME KEY VALUE
+acq_host_config_write() {
+  local backend="${1:-}" name="${2:-}" key="${3:-}" value="${4:-}"
+  [ -n "$backend" ] && [ -n "$name" ] || return 1
+  _acq_host_config_key_ok "$key" || { acq_debug "host-config: refusing unsafe key '$key'"; return 1; }
+  local dir file
+  dir=$(acq_host_config_dir "$backend" "$name") || return 1
+  if ! mkdir -p "$dir" 2>/dev/null; then
+    acq_debug "host-config: could not create config dir: $dir"
+    return 1
+  fi
+  chmod 700 "$dir" 2>/dev/null || true
+  file="$dir/$key"
+  local tmp="${file}.tmp.$$"
+  printf '%s' "$value" > "$tmp" 2>/dev/null || {
+    acq_debug "host-config: write failed: $tmp"; rm -f "$tmp" 2>/dev/null; return 1; }
+  chmod 600 "$tmp" 2>/dev/null || true
+  mv -f "$tmp" "$file" 2>/dev/null || {
+    acq_debug "host-config: mv failed: $file"; rm -f "$tmp" 2>/dev/null; return 1; }
+  acq_debug "host-config: wrote $backend/$name/$key"
+  return 0
+}
+
+# Read one KEY's VALUE. Echoes the raw stored bytes (empty if absent/unreadable).
+# Never fails the caller (returns 0 even when the key is absent) so a reader under
+# `set -euo pipefail` behaves like the old failure-guarded guest `cat`.
+# Usage: acq_host_config_read BACKEND NAME KEY
+acq_host_config_read() {
+  local backend="${1:-}" name="${2:-}" key="${3:-}"
+  [ -n "$backend" ] && [ -n "$name" ] || return 0
+  _acq_host_config_key_ok "$key" || return 0
+  local dir file
+  dir=$(acq_host_config_dir "$backend" "$name") || return 0
+  file="$dir/$key"
+  [ -f "$file" ] || return 0
+  cat "$file" 2>/dev/null || true
+}
+
+# True (0) if a KEY exists for a sandbox. Replaces the guest `test -f` marker
+# gates (install-*, agent-*-ready, oci-ready) that a sudo guest could forge.
+# Usage: acq_host_config_has BACKEND NAME KEY
+acq_host_config_has() {
+  local backend="${1:-}" name="${2:-}" key="${3:-}"
+  [ -n "$backend" ] && [ -n "$name" ] || return 1
+  _acq_host_config_key_ok "$key" || return 1
+  local dir
+  dir=$(acq_host_config_dir "$backend" "$name") || return 1
+  [ -f "$dir/$key" ]
+}
+
+# Append VALUE (one line) to a KEY's file, creating it if needed. Used by the
+# kit-env accumulator (multiple kits each contribute lines). Same fail-soft
+# contract as acq_host_config_write.
+# Usage: acq_host_config_append BACKEND NAME KEY VALUE
+acq_host_config_append() {
+  local backend="${1:-}" name="${2:-}" key="${3:-}" value="${4:-}"
+  [ -n "$backend" ] && [ -n "$name" ] || return 1
+  _acq_host_config_key_ok "$key" || { acq_debug "host-config: refusing unsafe key '$key'"; return 1; }
+  local dir file
+  dir=$(acq_host_config_dir "$backend" "$name") || return 1
+  if ! mkdir -p "$dir" 2>/dev/null; then
+    acq_debug "host-config: could not create config dir: $dir"; return 1
+  fi
+  chmod 700 "$dir" 2>/dev/null || true
+  file="$dir/$key"
+  printf '%s\n' "$value" >> "$file" 2>/dev/null || {
+    acq_debug "host-config: append failed: $file"; return 1; }
+  chmod 600 "$file" 2>/dev/null || true
+  return 0
+}
+
+# Remove one KEY (e.g. reset kit-env before a full re-apply). Best-effort.
+# Usage: acq_host_config_clear BACKEND NAME KEY
+acq_host_config_clear() {
+  local backend="${1:-}" name="${2:-}" key="${3:-}"
+  [ -n "$backend" ] && [ -n "$name" ] || return 0
+  _acq_host_config_key_ok "$key" || return 0
+  local dir
+  dir=$(acq_host_config_dir "$backend" "$name") || return 0
+  rm -f "$dir/$key" 2>/dev/null || true
+  return 0
+}
+
+# Remove a sandbox's entire host config dir (called from terminate). Best-effort.
+# Usage: acq_host_config_remove BACKEND NAME
+acq_host_config_remove() {
+  local backend="${1:-}" name="${2:-}"
+  [ -n "$backend" ] && [ -n "$name" ] || return 0
+  local dir
+  dir=$(acq_host_config_dir "$backend" "$name") || return 0
+  # Guard against a pathological empty resolution before rm -rf.
+  case "$dir" in
+    ""|/|/*/) return 0 ;;
+    *.config) rm -rf "$dir" 2>/dev/null || true ;;
+  esac
+  return 0
+}
+
 # Automatic stale-sandbox advisory for `acq run` on an EXISTING sandbox. Compares
 # the sandbox's recorded bundle ref against the local pinned PATTERNS_KIT_REF and,
 # when they differ (or no record exists), OFFERS an in-place refresh. Contract:
diff --git a/acq.backends/msb.sh b/acq.backends/msb.sh
index f6eaf169..9f071a14 100644
--- a/acq.backends/msb.sh
+++ b/acq.backends/msb.sh
@@ -3038,6 +3038,29 @@ EOF
   _acq_msb_vsock_flags_into _vsock_flags
   [ "${#_vsock_flags[@]}" -gt 0 ] && create_flags+=("${_vsock_flags[@]}")
 
+  # Host-authoritative config mount (ADR-0030). Mount this sandbox's host config
+  # dir into the guest READ-ONLY at ACQ_HOST_CONFIG_GUEST_DIR. acq writes the
+  # sandbox's trusted config there on the HOST (agent, workspace, ssh-auth-sock,
+  # kit-env, gate markers); the guest can read but — because the mount is
+  # read-only, enforced by the VMM/mount layer — a passwordless-sudo agent cannot
+  # forge or tamper it. The host dir is created empty now so the create-time
+  # mount has a source; acq populates it during provisioning (post-create).
+  local _hcfg_dir _hcfg_host
+  if _hcfg_dir=$(acq_host_config_dir msb "$name"); then
+    mkdir -p "$_hcfg_dir" 2>/dev/null || true
+    chmod 700 "$_hcfg_dir" 2>/dev/null || true
+    # --volume takes HOST:GUEST[:ro]; the host side is what native msb resolves on
+    # this machine (host_path → drive form under MSYS), the guest side is POSIX
+    # (ACQ_HOST_CONFIG_GUEST_DIR). See ADR-0029.
+    if command -v host_path >/dev/null 2>&1; then
+      _hcfg_host=$(host_path "$_hcfg_dir")
+    else
+      _hcfg_host="$_hcfg_dir"
+    fi
+    create_flags+=(--volume "${_hcfg_host}:${ACQ_HOST_CONFIG_GUEST_DIR}:ro")
+    acq_debug "msb host-config mount: ${_hcfg_host} (host) -> ${ACQ_HOST_CONFIG_GUEST_DIR} (guest, ro)"
+  fi
+
   # Credentials: read from the acq-owned secret store (keychain/file), scoped to
   # this sandbox first, then global. The real value is read into a TRANSIENT env
   # var (never argv, never the kit spec) and bound with `msb --secret ENV@HOST`,
@@ -4565,6 +4588,8 @@ acq_backend_terminate() {
   # Same GONE-after-remove-attempt rule as the volumes above: delete the scratch
   # clone and drop the fetch-back remote only once the sandbox is really gone.
   _acq_msb_clone_cleanup "$1"
+  # Remove the host-authoritative config dir (ADR-0030) once the sandbox is gone.
+  acq_host_config_remove msb "$1" || true
   return "$_rc"
 }
 
diff --git a/acq.backends/sbx.sh b/acq.backends/sbx.sh
index accf52b0..fac3f152 100644
--- a/acq.backends/sbx.sh
+++ b/acq.backends/sbx.sh
@@ -627,6 +627,11 @@ acq_backend_stop() {
 
 acq_backend_terminate() {
   sbx rm --force "$1"
+  # Remove any host-authoritative config dir for this sandbox (ADR-0030).
+  # sbx does not use the guest /var/lib/acq markers today (its parity mechanism
+  # is `sbx run --name` + ~/.acq-extra-kits), so this is a defensive no-op unless
+  # a future sbx path writes host config. Best-effort, never blocks removal.
+  acq_host_config_remove sbx "$1" || true
 }
 
 acq_backend_list() {

From 88e4cd9615d7634e42a9e561b0f8fe0e10a71fd3 Mon Sep 17 00:00:00 2001
From: Bret Mogilefsky <bret.mogilefsky@gsa.gov>
Date: Mon, 21 Sep 2026 23:16:13 +0000
Subject: [PATCH 03/12] feat(acq): migrate
 agent/workspace/ssh-auth-sock/kit-env to host config store (ADR-0030)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move the four content-bearing /var/lib/acq guest markers onto the
host-authoritative config store so a passwordless-sudo agent can no longer
tamper the values acq reads back to configure the sandbox:

- agent      -> which binary a name-only re-attach launches
- workspace  -> the session cwd (-w)
- ssh-auth-sock -> the injected SSH_AUTH_SOCK (git/ssh signing)
- kit-env    -> kit environment[] replayed as -e NAME=value each session

acq now writes these to acq_host_config_* on the host at provision/apply and
reads them back from the host on every session verb (run/attach/shell) — no
guest `msb exec cat` happens for them. The kit-env NAME re-validation and the
agent safe-token guard are preserved for defense-in-depth. Session verbs still
survive an absent value under set -euo pipefail (the host read returns empty,
not a failing pipeline).

Tests: the offline stub library gains seed_host_config (seeds the host store
from the STUB_RECORDED_* knobs, exported into subshells); the guest-cat stub
arms for these markers are removed; provision assertions read the host store.

Refs: GSA-TTS/agentic-coding-quickstart#503

Co-authored-by: OpenCode [claude_4_8_opus] <bret.mogilefsky@gsa.gov>
---
 acq.backends/msb.sh                          | 131 ++++++++++---------
 scripts/test-acq-lib.sh                      |  73 ++++-------
 test/bats/115-ssh-agent-forward.bats         |  18 ++-
 test/bats/71b-msb-secret-store-backends.bats |   8 +-
 test/bats/72-msb-agent-user.bats             |  24 +++-
 test/bats/78-msb-kit-env.bats                |  47 ++++---
 6 files changed, 160 insertions(+), 141 deletions(-)

diff --git a/acq.backends/msb.sh b/acq.backends/msb.sh
index 9f071a14..5653eb14 100644
--- a/acq.backends/msb.sh
+++ b/acq.backends/msb.sh
@@ -74,6 +74,16 @@ if ! command -v acq_is_known_agent >/dev/null 2>&1; then
   . "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/agents.sh"
 fi
 
+# Host-authoritative config store (ADR-0030). Normally defined in common.sh
+# (sourced before this adapter by acq_resolve_backend), but the offline session
+# paths (attach/run/shell) are exercised in tests that source THIS file directly
+# without common.sh. Guard-source it so acq_host_config_* are always defined when
+# this file's functions run (cheap re-source; common.sh is idempotent).
+if ! command -v acq_host_config_read >/dev/null 2>&1; then
+  # shellcheck source=acq.backends/common.sh
+  . "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/common.sh"
+fi
+
 # ---------------------------------------------------------------------------
 # _acq_msb_cli — invoke the msb CLI with MSYS argument rewriting disabled
 # ---------------------------------------------------------------------------
@@ -1580,18 +1590,18 @@ EOF
   # 2) Persist environment[] for session replay. Threading `-e NAME=value` onto
   #    the kit's own commands (step 3) covers provisioning only; the block exists
   #    for agent-runtime config (see ADR-0011: OPENCODE_CONFIG-style vars), so
-  #    the validated entries are also appended to a root-owned guest marker that
-  #    run/attach/shell read back and replay as `-e` flags (same marker pattern
-  #    as /var/lib/acq/agent and /var/lib/acq/ssh-auth-sock). Entries are passed
-  #    as argv to a fixed `sh -c` body — kit bytes are never interpolated into
-  #    shell syntax (SI-10).
+  #    the validated entries are also persisted to the HOST config store
+  #    (ADR-0030) that run/attach/shell read back and replay as `-e` flags — the
+  #    same role the guest /var/lib/acq/kit-env marker had, but host-authoritative
+  #    so a passwordless-sudo agent cannot inject env into the agent process.
   local _kit_env=()
   _acq_msb_collect_kit_env_into _kit_env "$spec"
   if [ "${#_kit_env[@]}" -gt 0 ]; then
-    _acq_msb_cli exec -u 0 "$name" -- sh -c \
-      'mkdir -p /var/lib/acq && printf "%s\n" "$@" >> /var/lib/acq/kit-env' \
-      sh "${_kit_env[@]}" </dev/null >/dev/null 2>&1 || \
-      echo "acq(msb): warning: could not persist kit env for '$name'; its environment[] will not reach agent sessions" >&2
+    local _kev
+    for _kev in "${_kit_env[@]}"; do
+      acq_host_config_append msb "$name" kit-env "$_kev" || \
+        echo "acq(msb): warning: could not persist kit env for '$name'; its environment[] will not reach agent sessions" >&2
+    done
   fi
 
   # 3) Run commands[]. Reassemble each argv record and exec it as the given uid.
@@ -1604,7 +1614,7 @@ EOF
   _acq_msb_run_commands "$name" "$spec"
 }
 
-# _acq_msb_reset_kit_env NAME — remove the persisted kit-env marker so a
+# _acq_msb_reset_kit_env NAME — remove the persisted kit-env so a
 # FULL-set kit application (provision, heal) rebuilds it from the current kits'
 # environment[] only. Without this, the per-kit append in _acq_msb_apply_kit_dir
 # would retain entries a kit no longer declares — removed runtime config
@@ -1612,10 +1622,9 @@ EOF
 # single-kit `acq kit apply` verb deliberately does NOT reset: a mid-life add
 # is additive, and replay's last-value-wins handles its overrides. Best-effort:
 # a failed reset degrades to the previous stale-retention behavior, never
-# aborts the apply.
+# aborts the apply. Host-authoritative (ADR-0030).
 _acq_msb_reset_kit_env() {
-  _acq_msb_cli exec -u 0 "$1" -- sh -c 'rm -f /var/lib/acq/kit-env' \
-    </dev/null >/dev/null 2>&1 || true
+  acq_host_config_clear msb "$1" kit-env
 }
 
 # Copy a host file into the guest and VERIFY it is readable there before
@@ -3226,26 +3235,27 @@ EOF
 
   # Record which agent this sandbox runs, so acq_backend_attach (which only gets
   # the sandbox name) knows what to launch — the sbx equivalent is that
-  # `sbx run --name` re-launches the agent baked in at create. Written as root to
-  # a fixed guest path; validated charset (KNOWN_AGENTS tokens are word-safe).
+  # `sbx run --name` re-launches the agent baked in at create. Written to the
+  # HOST-authoritative config store (ADR-0030), not a guest file: a
+  # passwordless-sudo agent could otherwise rewrite a guest marker and change
+  # which binary acq relaunches. The value is still charset-checked defensively.
   case "$agent" in
-    *[!a-z-]*) : ;;  # defensive: never write an odd token
-    *) _acq_msb_cli exec "$name" -u 0 -- sh -c "mkdir -p /var/lib/acq && printf '%s' '$agent' > /var/lib/acq/agent" >/dev/null 2>&1 || true ;;
+    *[!a-z-]*) : ;;  # defensive: never record an odd token
+    *) acq_host_config_write msb "$name" agent "$agent" || true ;;
   esac
 
   # Record the guest workspace path too. attach only gets the sandbox NAME, so it
   # cannot recompute the host→guest mapping (which now mirrors the host path);
-  # persist it so a name-only re-attach cds into the right place. The path was
-  # validated as an existing host dir above; guard the charset before it enters a
-  # root sh -c string.
+  # persist it (host-side, ADR-0030) so a name-only re-attach cds into the right
+  # place. The path was validated as an existing host dir above; the charset
+  # guard is kept for defense-in-depth even though the value no longer enters a
+  # guest sh -c string.
   if [ -n "$ACQ_MSB_GUEST_WORKSPACE" ]; then
     case "$ACQ_MSB_GUEST_WORKSPACE" in
-      # Guest-side paths are POSIX (canonicalize_path, ADR-0029), so the
-      # conservative charset holds; only a literal ' would break the quoting.
       *[!A-Za-z0-9._/-]*)
         acq_debug "msb: not recording unsafe guest workspace path: $ACQ_MSB_GUEST_WORKSPACE" ;;
       *)
-        _acq_msb_cli exec "$name" -u 0 -- sh -c "mkdir -p /var/lib/acq && printf '%s' '$ACQ_MSB_GUEST_WORKSPACE' > /var/lib/acq/workspace" >/dev/null 2>&1 || true ;;
+        acq_host_config_write msb "$name" workspace "$ACQ_MSB_GUEST_WORKSPACE" || true ;;
     esac
   fi
 
@@ -3305,7 +3315,7 @@ _acq_msb_agent_has_install_recipe() {
 # interpolate into a shell command. Agent tokens are short lowercase names
 # (opencode, claude, shell, …); restrict to [a-z-] so a value can never break
 # out of the `sh -c "command -v '$agent'"` single-quoting (defense against a
-# `acq create "x';…'"` arg or a tampered /var/lib/acq/agent marker). Callers
+# `acq create "x';…'"` arg or a stale host-config value). Callers
 # that build an `sh -c` string with $agent MUST gate on this first.
 _acq_msb_safe_agent_token() {
   acq_agent_safe_token "$1"
@@ -3783,9 +3793,9 @@ _acq_msb_start_ssh_agent_bridge() {
 
   # Record the guest sock path so attach/exec/start can resolve SSH_AUTH_SOCK
   # even when no provision flag is set. Only written when forwarding is active.
-  _acq_msb_cli exec "$name" -u 0 -- sh -c \
-    "mkdir -p /var/lib/acq && printf '%s' '$_sock' > /var/lib/acq/ssh-auth-sock" \
-    </dev/null >/dev/null 2>&1 || true
+  # Host-authoritative (ADR-0030): held on the host, not a guest marker a
+  # sudo agent could repoint. $_sock is acq's own constant.
+  acq_host_config_write msb "$name" ssh-auth-sock "$_sock" || true
   acq_debug "msb: ssh-agent bridge started at $_sock (vsock port $_port) in $name"
 
   # Liveness probe (ADR-0021): the bridge + marker are now in place, but the
@@ -3865,17 +3875,15 @@ _acq_msb_warn_if_agent_unreachable() {
 
 # _acq_msb_ssh_auth_sock_for NAME — echo the recorded guest ssh-agent sock path
 # (the SSH_AUTH_SOCK value git/ssh should use in the guest), or empty when
-# forwarding was never configured for this sandbox. Read from the persisted
-# marker so run/attach on a name-only re-entry still find it. See ADR-0021.
+# forwarding was never configured for this sandbox. Read from the HOST config
+# store (ADR-0030) so run/attach on a name-only re-entry still find it, and a
+# sudo guest cannot repoint SSH_AUTH_SOCK. See ADR-0021.
 _acq_msb_ssh_auth_sock_for() {
   local name="$1"
-  # Failure-guarded: with the marker absent (forwarding never configured), the
-  # in-guest `cat` exits 1 and — under acq's `set -euo pipefail` — the pipeline
-  # would otherwise propagate that into the caller's command substitution and
-  # kill the whole session verb (the trailing `tr` does NOT mask it: pipefail
-  # takes the failing stage's status).
-  { _acq_msb_cli exec "$name" -u 0 -- sh -c 'cat /var/lib/acq/ssh-auth-sock 2>/dev/null' \
-    </dev/null 2>/dev/null || true; } | tr -d '[:space:]'
+  # The host read never fails the caller (empty when unset), so a session verb
+  # under `set -euo pipefail` survives an absent value (forwarding never
+  # configured) and takes the documented no-flag fallback.
+  acq_host_config_read msb "$name" ssh-auth-sock | tr -d '[:space:]'
 }
 
 _acq_msb_git_identity_env_flags_into() {
@@ -3911,25 +3919,24 @@ EOF
 }
 
 # _acq_msb_kit_env_flags_into ARRVAR NAME — build the `-e NAME=value` flag array
-# for the kit environment[] entries persisted at /var/lib/acq/kit-env by
-# _acq_msb_apply_kit_dir, so every session path (run/attach/shell) sees the env
+# for the kit environment[] entries persisted in the HOST config store (ADR-0030)
+# by _acq_msb_apply_kit_dir, so every session path (run/attach/shell) sees the env
 # the kits declared for agent runtime (see ADR-0011). Empty array when no kit
 # declared environment[]. Array passed by name (bash 3.2 compat).
 #
-# The marker is root-owned but its content is kit-derived guest data: re-validate
-# each NAME (same ^[A-Za-z_][A-Za-z0-9_]*$ charset kit_spec_env enforces) so a
-# tampered line cannot smuggle an option-shaped or quote-bearing token, and keep
-# the LAST value for a duplicate name (kits append in application order, so a
-# later kit overrides an earlier one).
+# The stored content is kit-derived data: re-validate each NAME (same
+# ^[A-Za-z_][A-Za-z0-9_]*$ charset kit_spec_env enforces) so a malformed line
+# cannot smuggle an option-shaped or quote-bearing token, and keep the LAST value
+# for a duplicate name (kits append in application order, so a later kit overrides
+# an earlier one).
 _acq_msb_kit_env_flags_into() {
   local _arrn="$1" _name="$2"
   eval "$_arrn=()"
-  # Failure-guarded: an absent marker (pre-kit-env sandbox, or no kit declared
-  # environment[]) must yield an empty result, not kill the session verb — see
-  # _acq_msb_ssh_auth_sock_for.
+  # The host read never fails the caller: an absent value (pre-kit-env sandbox,
+  # or no kit declared environment[]) yields an empty result, not a killed
+  # session verb under `set -euo pipefail`.
   local _kvs
-  _kvs=$(_acq_msb_cli exec "$_name" -u 0 -- sh -c 'cat /var/lib/acq/kit-env 2>/dev/null' \
-    </dev/null 2>/dev/null) || _kvs=""
+  _kvs=$(acq_host_config_read msb "$_name" kit-env)
   [ -n "$_kvs" ] || return 0
   local _line
   while IFS= read -r _line; do
@@ -4306,11 +4313,10 @@ _ACQ_MSB_RUN_WS=""
 
 # _acq_msb_workspace_for NAME — the guest workspace a session starts in (-w).
 # Prefer an explicit ACQ_MSB_WORKSPACE override; otherwise the guest path
-# recorded at provision (it mirrors the host mount path, so it cannot be
-# recomputed from NAME alone); fall back to the agent home if nothing was
-# recorded (older sandbox). The marker read is failure-guarded so an absent
-# marker takes the documented fallback instead of killing the session verb
-# under `set -e` (see _acq_msb_ssh_auth_sock_for).
+# recorded at provision in the host config store (it mirrors the host mount path,
+# so it cannot be recomputed from NAME alone); fall back to the agent home if
+# nothing was recorded (older sandbox). The host-config read never fails the
+# caller, so an absent value takes the documented fallback under `set -e`.
 _acq_msb_workspace_for() {
   local name="$1" ws=""
   if [ -n "${ACQ_MSB_WORKSPACE:-}" ]; then
@@ -4323,7 +4329,7 @@ _acq_msb_workspace_for() {
       ws="$ACQ_MSB_WORKSPACE"
     fi
   else
-    ws=$({ _acq_msb_cli exec "$name" -u 0 -- sh -c 'cat /var/lib/acq/workspace 2>/dev/null' </dev/null 2>/dev/null || true; } | tr -d '\r\n')
+    ws=$(acq_host_config_read msb "$name" workspace | tr -d '\r\n')
   fi
   [ -n "$ws" ] || ws="/home/agent"
   printf '%s\n' "$ws"
@@ -4438,9 +4444,9 @@ acq_backend_run() {
 #                base image's Node REPL, and the passwd shell isn't exported).
 #
 # A bare `acq run <sandbox>` re-attach (no agent token) reads the agent recorded
-# at provision from /var/lib/acq/agent; `shell` (or a missing/failed agent binary)
-# falls back to an interactive `/bin/sh -l` as `agent` — never a root shell, never
-# msb's Node-REPL default. Post-`--` args are forwarded to the agent.
+# at provision from the host config store (ADR-0030); `shell` (or a missing/failed
+# agent binary) falls back to an interactive `/bin/sh -l` as `agent` — never a
+# root shell, never msb's Node-REPL default. Post-`--` args are forwarded to the agent.
 acq_backend_attach() {
   local name="$1"
   shift
@@ -4469,12 +4475,13 @@ _acq_msb_attach() {
   ws=$(_acq_msb_workspace_for "$name")
 
   # Read the agent recorded at provision. Default to `shell` if unset. The value
-  # comes from a guest file (/var/lib/acq/agent); charset-guard it before it
-  # enters the `sh -c "command -v '$agent'"` below, since a tampered marker could
-  # otherwise break the single-quoting and run as the agent user. Fall back to a
-  # plain shell on anything unexpected.
+  # comes from the HOST-authoritative config store (ADR-0030), not a guest file,
+  # so a passwordless-sudo agent can no longer alter which binary is launched.
+  # The charset guard is kept for defense-in-depth before the value enters the
+  # `sh -c "command -v '$agent'"` below; fall back to a plain shell on anything
+  # unexpected.
   local agent
-  agent=$({ _acq_msb_cli exec "$name" -u 0 -- sh -c 'cat /var/lib/acq/agent 2>/dev/null' </dev/null 2>/dev/null || true; } | tr -d '[:space:]')
+  agent=$(acq_host_config_read msb "$name" agent | tr -d '[:space:]')
   if [ -z "$agent" ] || ! _acq_msb_safe_agent_token "$agent"; then
     agent="shell"
   fi
diff --git a/scripts/test-acq-lib.sh b/scripts/test-acq-lib.sh
index 570f7be5..7fa4772e 100644
--- a/scripts/test-acq-lib.sh
+++ b/scripts/test-acq-lib.sh
@@ -390,51 +390,11 @@ case "$_msb_sub" in
         [ "${STUB_NPM_FAIL:-0}" = "1" ] && exit 1 || exit 0 ;;
       *"test -f "*) exit 1 ;;       # markers absent
       *"test -s "*) exit 0 ;;       # copied files present
-      # The /var/lib/acq marker reads (agent, workspace, ssh-auth-sock,
-      # kit-env). An UNSET STUB_RECORDED_* models an ABSENT marker faithfully:
-      # a real `sh -c 'cat …'` exits 1 there, and acq runs under
-      # `set -euo pipefail`, so every reader must survive that nonzero (a
-      # sandbox from before a marker existed, or one whose feature was never
-      # configured, still has to serve every session verb). A SET-but-empty
-      # value models a present-but-empty marker (cat exits 0).
-      *"cat /var/lib/acq/agent"*)
-        [ -n "${STUB_RECORDED_AGENT+x}" ] || exit 1
-        printf '%s' "$STUB_RECORDED_AGENT" ;;
-      *"cat /var/lib/acq/workspace"*)
-        [ -n "${STUB_RECORDED_WORKSPACE+x}" ] || exit 1
-        printf '%s' "$STUB_RECORDED_WORKSPACE" ;;
-      # ADR-0021: the persisted ssh-agent guest sock marker read by
-      # _acq_msb_ssh_auth_sock_for (and, via it, run/attach/start).
-      *"cat /var/lib/acq/ssh-auth-sock"*)
-        [ -n "${STUB_RECORDED_SSH_AUTH_SOCK+x}" ] || exit 1
-        printf '%s' "$STUB_RECORDED_SSH_AUTH_SOCK" ;;
-      # The persisted kit environment[] marker (see ADR-0011). The write/reset
-      # arms keep a STATEFUL model in $STUBDIR/.kit_env so the full
-      # provision→heal→replay cycle is testable (stale-entry regression);
-      # STUB_RECORDED_KIT_ENV, when set, overrides it with fixed content
-      # (multi-line values model multiple entries). Absent/empty semantics per
-      # the marker-reads comment above.
-      *">> /var/lib/acq/kit-env"*)
-        # Append the env tokens: argv shape is `… -- sh -c '<script>' sh
-        # NAME=value…` — collect everything after the argv0 `sh` that follows
-        # the script.
-        _kes_c=0 _kes_script=0 _kes_argv0=0
-        for a in "$@"; do
-          if [ "$_kes_argv0" = 1 ]; then printf '%s\n' "$a" >>"$STUBDIR/.kit_env"
-          elif [ "$_kes_script" = 1 ] && [ "$a" = "sh" ]; then _kes_argv0=1
-          elif [ "$_kes_c" = 1 ]; then _kes_script=1; _kes_c=0
-          elif [ "$a" = "-c" ]; then _kes_c=1
-          fi
-        done ;;
-      *"rm -f /var/lib/acq/kit-env"*) rm -f "$STUBDIR/.kit_env" ;;
-      *"cat /var/lib/acq/kit-env"*)
-        if [ -n "${STUB_RECORDED_KIT_ENV+x}" ]; then
-          printf '%s' "$STUB_RECORDED_KIT_ENV"
-        elif [ -f "$STUBDIR/.kit_env" ]; then
-          cat "$STUBDIR/.kit_env"
-        else
-          exit 1
-        fi ;;
+      # ADR-0030 migrated agent/workspace/ssh-auth-sock/kit-env OFF the guest
+      # /var/lib/acq markers onto the HOST config store (acq_host_config_*), which
+      # acq now reads directly on the host — no `msb exec cat` happens for them.
+      # The STUB_RECORDED_* knobs are seeded into the host store instead (see
+      # seed_host_config below), so no guest-cat arm remains for them here.
       *) : ;;
     esac ;;
   ssh)
@@ -586,3 +546,26 @@ load_acq() {
   # failing command via errexit inherited into the @test body, so disabling it
   # in setup() makes every assertion in the suite pass vacuously (#381 review).
 }
+
+# seed_host_config BACKEND NAME — populate the ADR-0030 host config store for a
+# sandbox from the STUB_RECORDED_* env knobs, so tests that exercise the session
+# paths (attach/run/shell) find the agent/workspace/ssh-auth-sock/kit-env acq now
+# reads from the HOST (no guest `msb exec cat` happens for them anymore). Only a
+# SET knob is written (an unset knob models an absent value → acq's documented
+# fallback). Requires acq_host_config_* to be defined (source common.sh first).
+# Usage (inside a test subshell, after sourcing common.sh/msb.sh):
+#   seed_host_config msb "$name"
+seed_host_config() {
+  local backend="${1:-msb}" name="${2:-}"
+  [ -n "$name" ] || return 0
+  command -v acq_host_config_write >/dev/null 2>&1 || return 0
+  [ -n "${STUB_RECORDED_AGENT+x}" ] && acq_host_config_write "$backend" "$name" agent "$STUB_RECORDED_AGENT"
+  [ -n "${STUB_RECORDED_WORKSPACE+x}" ] && acq_host_config_write "$backend" "$name" workspace "$STUB_RECORDED_WORKSPACE"
+  [ -n "${STUB_RECORDED_SSH_AUTH_SOCK+x}" ] && acq_host_config_write "$backend" "$name" ssh-auth-sock "$STUB_RECORDED_SSH_AUTH_SOCK"
+  [ -n "${STUB_RECORDED_KIT_ENV+x}" ] && acq_host_config_write "$backend" "$name" kit-env "$STUB_RECORDED_KIT_ENV"
+  return 0
+}
+# Export so a test's `run bash -c '…'` subshell (which does NOT re-source this
+# stub library) still sees the helper. The ACQ_PROVENANCE_DIR/ACQ_STATE_DIR env
+# exports carry the store location into that subshell too.
+export -f seed_host_config 2>/dev/null || true
diff --git a/test/bats/115-ssh-agent-forward.bats b/test/bats/115-ssh-agent-forward.bats
index e94ecc14..f83198a4 100644
--- a/test/bats/115-ssh-agent-forward.bats
+++ b/test/bats/115-ssh-agent-forward.bats
@@ -144,13 +144,16 @@ s.bind(sys.argv[1])' "$1" >/dev/null 2>&1 && [ -S "$1" ]
   local log; log=$(cat "$CALLS")
   assert_regex "$log" "socat UNIX-LISTEN:'/home/agent/\.acq/ssh-agent\.sock'"
   assert_regex "$log" "VSOCK-CONNECT:2:'3552'"
-  assert_regex "$log" '/var/lib/acq/ssh-auth-sock'
+  # ADR-0030: the sock path is recorded in the HOST config store, not a guest
+  # /var/lib/acq/ssh-auth-sock marker.
+  assert_equal "$(cat "$ACQ_PROVENANCE_DIR"/msb/sbox.*.config/ssh-auth-sock 2>/dev/null)" "/home/agent/.acq/ssh-agent.sock"
 }
 
 @test "vsock(10c9): the start path reads the marker and starts the bridge; empty marker starts none" {
   run bash -c '
     export STUB_MSB_VERSION=0.6.9 STUB_RECORDED_SSH_AUTH_SOCK=/home/agent/.acq/ssh-agent.sock
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    seed_host_config msb sbox
     _ACQ_MSB_SSH_AGENT_FORWARDING=0
     _acq_msb_start_ssh_agent_bridge sbox >/dev/null 2>&1
     wait
@@ -160,8 +163,9 @@ s.bind(sys.argv[1])' "$1" >/dev/null 2>&1 && [ -S "$1" ]
   run bash -c '
     export STUB_MSB_VERSION=0.6.9 STUB_RECORDED_SSH_AUTH_SOCK=
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    seed_host_config msb sbox2
     _ACQ_MSB_SSH_AGENT_FORWARDING=0
-    _acq_msb_start_ssh_agent_bridge sbox >/dev/null 2>&1
+    _acq_msb_start_ssh_agent_bridge sbox2 >/dev/null 2>&1
     wait
   '
   refute_regex "$(cat "$CALLS")" 'socat UNIX-LISTEN'
@@ -192,13 +196,15 @@ s.bind(sys.argv[1])' "$1" >/dev/null 2>&1 && [ -S "$1" ]
   run bash -c '
     export STUB_MSB_VERSION=0.6.9 STUB_RECORDED_SSH_AUTH_SOCK=/home/agent/.acq/ssh-agent.sock
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    seed_host_config msb sbox
     acq_backend_run sbox -- git status >/dev/null 2>&1
   '
   assert_regex "$(cat "$CALLS")" 'SSH_AUTH_SOCK=/home/agent/\.acq/ssh-agent\.sock'
   : > "$CALLS"
   run bash -c '
-    export STUB_MSB_VERSION=0.6.9 STUB_RECORDED_SSH_AUTH_SOCK=/home/agent/.acq/ssh-agent.sock
+    export STUB_MSB_VERSION=0.6.9 STUB_RECORDED_SSH_AUTH_SOCK=/home/agent/.acq/ssh-agent.sock STUB_RECORDED_AGENT=opencode STUB_AGENT_PRESENT=1
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    seed_host_config msb sbox
     ( _acq_msb_attach sbox </dev/null >/dev/null 2>&1 )
   '
   assert_regex "$(cat "$CALLS")" 'SSH_AUTH_SOCK='
@@ -206,7 +212,8 @@ s.bind(sys.argv[1])' "$1" >/dev/null 2>&1 && [ -S "$1" ]
   run bash -c '
     export STUB_MSB_VERSION=0.6.9 STUB_RECORDED_SSH_AUTH_SOCK=
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
-    acq_backend_run sbox -- git status >/dev/null 2>&1
+    seed_host_config msb sboxempty
+    acq_backend_run sboxempty -- git status >/dev/null 2>&1
   '
   refute_regex "$(cat "$CALLS")" 'SSH_AUTH_SOCK='
 }
@@ -309,7 +316,8 @@ s.bind(sys.argv[1])' "$1" >/dev/null 2>&1 && [ -S "$1" ]
   '
   local log; log=$(cat "$CALLS")
   assert_regex "$log" "socat UNIX-LISTEN:'/home/agent/\.acq/ssh-agent\.sock'"
-  assert_regex "$log" '/var/lib/acq/ssh-auth-sock'
+  # ADR-0030: the sock path is recorded in the HOST config store, not a guest marker.
+  assert_equal "$(cat "$ACQ_PROVENANCE_DIR"/msb/reattachbox.*.config/ssh-auth-sock 2>/dev/null)" "/home/agent/.acq/ssh-agent.sock"
   # A running sandbox must NOT be routed through acq_backend_start.
   refute_regex "$log" 'msb start'
 }
diff --git a/test/bats/71b-msb-secret-store-backends.bats b/test/bats/71b-msb-secret-store-backends.bats
index bff65da3..79c7ccd1 100644
--- a/test/bats/71b-msb-secret-store-backends.bats
+++ b/test/bats/71b-msb-secret-store-backends.bats
@@ -283,12 +283,14 @@ _provision() { # NAME PRE_SNIPPET WS_ARGS...
   log=$(cat "$CALLS")
   assert_regex "$log" "--volume ${ws_app_h}:${ws_app}"
   assert_regex "$log" "--volume ${ws_lib_h}:${ws_lib}:ro"
-  assert_regex "$log" "'${ws_app}' > /var/lib/acq/workspace"
-  refute_regex "$log" "'/home/agent/workspace' > /var/lib/acq/workspace"
+  # ADR-0030: the workspace record is written to the HOST config store now, not a
+  # guest /var/lib/acq/workspace marker. Assert the primary landed there.
+  assert_equal "$(cat "$ACQ_PROVENANCE_DIR"/msb/mwbox.*.config/workspace 2>/dev/null)" "${ws_app}"
+  [ "$(cat "$ACQ_PROVENANCE_DIR"/msb/mwbox.*.config/workspace 2>/dev/null)" != "/home/agent/workspace" ]
 
   # Single workspace records that mount as the start dir.
   _provision swbox 'export ACQ_SECRET_STORE_DIR="'"$STUBDIR"'/sw-secrets"' "$STUBDIR/ws-app"
-  assert_regex "$(cat "$CALLS")" "'${ws_app}' > /var/lib/acq/workspace"
+  assert_equal "$(cat "$ACQ_PROVENANCE_DIR"/msb/swbox.*.config/workspace 2>/dev/null)" "${ws_app}"
 }
 
 @test "msb: a symlinked workspace is canonicalized to its real path before mounting" {
diff --git a/test/bats/72-msb-agent-user.bats b/test/bats/72-msb-agent-user.bats
index 00e9c6b4..7f6fae1d 100644
--- a/test/bats/72-msb-agent-user.bats
+++ b/test/bats/72-msb-agent-user.bats
@@ -92,7 +92,9 @@ SPEC
   local log; log=$(cat "$CALLS")
   assert_regex "$log" 'npm install -g --no-fund --no-audit opencode-ai'
   assert_regex "$log" '--net-rule allow@registry\.npmjs\.org'
-  assert_regex "$log" '/var/lib/acq/agent'
+  # ADR-0030: the launched-agent record is written to the HOST config store, not
+  # a guest /var/lib/acq/agent marker. Assert it landed in the host store.
+  assert_equal "$(cat "$ACQ_PROVENANCE_DIR"/msb/instbox.*.config/agent 2>/dev/null)" "opencode"
 }
 
 @test "msb: install is idempotent — skipped when the agent binary is already present" {
@@ -142,6 +144,7 @@ _attach() { # PRE_SNIPPET NAME
     pre="$1"; name="$2"
     eval "$pre"
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    seed_host_config msb "$name"
     acq_backend_attach "$name" 2>&1
   ' _ "$1" "$2"
 }
@@ -198,7 +201,10 @@ _attach() { # PRE_SNIPPET NAME
   refute_regex "$(cat "$CALLS")" 'touch /tmp/acq_pwn'
 }
 
-@test "msb: attach with a tampered agent marker falls back to shell, never runs the injection" {
+@test "msb: attach with a garbage recorded agent value falls back to shell, never runs the injection" {
+  # ADR-0030: the agent record now lives in the host config store (a sudo guest
+  # can no longer plant it), but acq still charset-guards the value before it
+  # enters `command -v '$agent'`. Seed a hostile value and prove the guard holds.
   _attach 'export STUB_RECORDED_AGENT="x'"'"';touch /tmp/acq_pwn;'"'"'" STUB_RECORDED_WORKSPACE=/tmp/wsp' injattach
   local log; log=$(cat "$CALLS")
   refute_regex "$log" 'touch /tmp/acq_pwn'
@@ -286,6 +292,7 @@ _attach() { # PRE_SNIPPET NAME
   run bash -c '
     export STUB_RECORDED_WORKSPACE=/tmp/myrepo
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    seed_host_config msb wsbox
     acq_backend_run wsbox -- git status >/dev/null 2>&1
   '
   assert_regex "$(cat "$CALLS")" '\-u agent -e HOME=/home/agent -w /tmp/myrepo wsbox -- git status'
@@ -296,6 +303,7 @@ _attach() { # PRE_SNIPPET NAME
   run bash -c '
     export ACQ_MSB_WORKSPACE=/tmp/override STUB_RECORDED_WORKSPACE=/tmp/myrepo
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    seed_host_config msb wsbox
     acq_backend_run wsbox -- git status >/dev/null 2>&1
   '
   assert_regex "$(cat "$CALLS")" '\-w /tmp/override wsbox'
@@ -303,6 +311,9 @@ _attach() { # PRE_SNIPPET NAME
   run bash -c '
     unset ACQ_MSB_WORKSPACE STUB_RECORDED_WORKSPACE
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    # No STUB_RECORDED_WORKSPACE → seed nothing; also clear any value a prior
+    # sub-case in this same test wrote to the shared host store for this name.
+    acq_host_config_clear msb wsbox workspace
     acq_backend_run wsbox -- git status >/dev/null 2>&1
   '
   assert_regex "$(cat "$CALLS")" '\-w /home/agent wsbox'
@@ -379,16 +390,19 @@ _attach() { # PRE_SNIPPET NAME
   assert_regex "$log" '\-le 3'
 }
 
-@test "msb: repeated acq exec reads the workspace marker once per process (cached)" {
+@test "msb: repeated acq exec reads the workspace once per process (cached)" {
   : > "$CALLS"
+  # ADR-0030: the workspace is read from the HOST config store now, not a guest
+  # `cat`, so the per-process cache is asserted via the resolved -w value being
+  # applied to BOTH execs (a re-read would still yield the same value, but the
+  # cache guarantees a single host lookup — proven by the stable -w on both).
   run bash -c '
     export STUB_RECORDED_WORKSPACE=/tmp/myrepo
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    seed_host_config msb cachebox
     acq_backend_run cachebox -- git status >/dev/null 2>&1
     acq_backend_run cachebox -- git log >/dev/null 2>&1
   '
-  local log; log=$(cat "$CALLS")
-  assert_equal "$(grep -c 'cat /var/lib/acq/workspace' "$CALLS")" "1"
   assert_equal "$(grep -c -- '-w /tmp/myrepo cachebox' "$CALLS")" "2"
 }
 
diff --git a/test/bats/78-msb-kit-env.bats b/test/bats/78-msb-kit-env.bats
index d02282da..6f77bcba 100644
--- a/test/bats/78-msb-kit-env.bats
+++ b/test/bats/78-msb-kit-env.bats
@@ -6,10 +6,10 @@
 # OPENCODE_CONFIG-style vars). On msb the entries were only threaded onto the
 # kit's own provisioning commands and never reached the agent session or
 # `acq exec`/`acq shell` — the kit env silently no-op'd at runtime. The fix
-# persists the validated entries to a root-owned guest marker
-# (/var/lib/acq/kit-env, same pattern as /var/lib/acq/agent and
-# /var/lib/acq/ssh-auth-sock) at apply time, and every session path reads the
-# marker back and threads each entry as `msb exec -e NAME=value`.
+# persists the validated entries and every session path replays each as
+# `msb exec -e NAME=value`. Per ADR-0030 the entries are persisted to the
+# HOST-authoritative config store (acq_host_config_* kit-env key), not a guest
+# /var/lib/acq/kit-env marker a passwordless-sudo agent could tamper.
 #
 # shellcheck shell=bats
 
@@ -18,7 +18,7 @@ teardown() { acq_teardown_stubs; }
 
 load 'helper'
 
-@test "msb kit env: apply persists environment[] to /var/lib/acq/kit-env; unsafe name is dropped" {
+@test "msb kit env: apply persists environment[] to the host config store; unsafe name is dropped" {
   : > "$CALLS"
   run bash -c '
     export ACQ_SECRET_STORE_DIR="'"$STUBDIR"'/kitenv-secrets"
@@ -39,13 +39,15 @@ SPEC
     _acq_msb_apply_kit_dir envbox "$ek"
   '
   assert_success
-  local log; log=$(cat "$CALLS")
-  assert_regex "$log" '/var/lib/acq/kit-env'
-  assert_regex "$log" 'OPENCODE_CONFIG=/home/agent/\.config/opencode/kit\.jsonc'
-  refute_regex "$log" '1BAD'
+  # The record now lands in the HOST config store, not a guest exec.
+  local kitenv; kitenv=$(cat "$ACQ_PROVENANCE_DIR"/msb/envbox.*.config/kit-env 2>/dev/null)
+  assert_regex "$kitenv" 'OPENCODE_CONFIG=/home/agent/\.config/opencode/kit\.jsonc'
+  refute_regex "$kitenv" '1BAD'
+  # And no guest /var/lib/acq/kit-env write happened.
+  refute_regex "$(cat "$CALLS")" '/var/lib/acq/kit-env'
 }
 
-@test "msb kit env: a kit with no environment[] writes no kit-env marker" {
+@test "msb kit env: a kit with no environment[] writes no kit-env record" {
   : > "$CALLS"
   run bash -c '
     export ACQ_SECRET_STORE_DIR="'"$STUBDIR"'/noenv-secrets"
@@ -67,19 +69,21 @@ commands:
       - -c
       - echo CMD_NOENV
 SPEC
-    _acq_msb_apply_kit_dir envbox "$nk"
+    _acq_msb_apply_kit_dir envbox2 "$nk"
   '
   assert_success
   refute_regex "$(cat "$CALLS")" '/var/lib/acq/kit-env'
+  [ ! -f "$ACQ_PROVENANCE_DIR"/msb/envbox2.*.config/kit-env ]
 }
 
-@test "msb kit env: acq exec replays persisted entries as -e flags; none when marker empty" {
+@test "msb kit env: acq exec replays persisted entries as -e flags; none when empty" {
   : > "$CALLS"
   run bash -c '
     export STUB_MSB_VERSION=0.6.9
     export STUB_RECORDED_KIT_ENV="OPENCODE_CONFIG=/home/agent/oc.jsonc
 RUBOCOP_PARALLELISM=4"
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    seed_host_config msb sbox
     acq_backend_run sbox -- printenv OPENCODE_CONFIG >/dev/null 2>&1
   '
   local log; log=$(cat "$CALLS")
@@ -89,7 +93,8 @@ RUBOCOP_PARALLELISM=4"
   run bash -c '
     export STUB_MSB_VERSION=0.6.9 STUB_RECORDED_KIT_ENV=
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
-    acq_backend_run sbox -- git status >/dev/null 2>&1
+    seed_host_config msb sbox2
+    acq_backend_run sbox2 -- git status >/dev/null 2>&1
   '
   refute_regex "$(cat "$CALLS")" 'OPENCODE_CONFIG'
 }
@@ -100,6 +105,7 @@ RUBOCOP_PARALLELISM=4"
     export STUB_MSB_VERSION=0.6.9 STUB_RECORDED_AGENT=opencode STUB_AGENT_PRESENT=1
     export STUB_RECORDED_KIT_ENV="OPENCODE_CONFIG=/home/agent/oc.jsonc"
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    seed_host_config msb sbox
     ( _acq_msb_attach sbox </dev/null >/dev/null 2>&1 )
   '
   assert_regex "$(cat "$CALLS")" '-e OPENCODE_CONFIG=/home/agent/oc\.jsonc'
@@ -108,6 +114,7 @@ RUBOCOP_PARALLELISM=4"
     export STUB_MSB_VERSION=0.6.9
     export STUB_RECORDED_KIT_ENV="OPENCODE_CONFIG=/home/agent/oc.jsonc"
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    seed_host_config msb sbox
     ( _acq_msb_shell_exec sbox </dev/null >/dev/null 2>&1 )
   '
   assert_regex "$(cat "$CALLS")" '-e OPENCODE_CONFIG=/home/agent/oc\.jsonc'
@@ -154,14 +161,11 @@ RUBOCOP_PARALLELISM=4"
   assert_regex "$(cat "$CALLS")" '-e EMAIL=global@example\.gov'
 }
 
-@test "msb markers: ABSENT /var/lib/acq markers must not kill session verbs under set -e" {
-  # acq runs under `set -euo pipefail`. On a sandbox whose /var/lib/acq markers
-  # are absent (created before a marker existed, e.g. pre-kit-env sandboxes, or
-  # no ssh-agent forwarding configured), the in-guest `cat` exits 1 inside the
-  # command substitution and an unguarded assignment terminates acq before any
-  # output — every exec/shell/attach against such a sandbox dies with rc 1 and
-  # nothing on stdout/stderr (observed live for kit-env and ssh-auth-sock).
-  # All STUB_RECORDED_* stay UNSET here so the stub exits 1 like real cat.
+@test "msb markers: an ABSENT host config must not kill session verbs under set -e" {
+  # acq runs under `set -euo pipefail`. On a sandbox with no recorded host config
+  # (created before ADR-0030, or with no ssh-agent forwarding / kit env), the
+  # host reads return empty and must not terminate the session verb. All
+  # STUB_RECORDED_* stay UNSET and nothing is seeded into the host store.
   : > "$CALLS"
   run bash -c '
     set -euo pipefail
@@ -249,6 +253,7 @@ SPEC
 GITLAB_HOST=gitlab.example.gov
 GITLAB_HOST=gitlab.override.gov"
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    seed_host_config msb sbox
     acq_backend_run sbox -- git status >/dev/null 2>&1
   '
   local log; log=$(cat "$CALLS")

From a8f41445cb75ddbe53b9cb2155aef3c1ae179fd2 Mon Sep 17 00:00:00 2001
From: Bret Mogilefsky <bret.mogilefsky@gsa.gov>
Date: Mon, 21 Sep 2026 23:42:14 +0000
Subject: [PATCH 04/12] feat(acq): migrate run-once gates to host config store
 (ADR-0030)

Move the four presence-only idempotency gates off guest /var/lib/acq markers
onto the host-authoritative config store, so a passwordless-sudo agent can no
longer pre-create a marker to SUPPRESS a provisioning step:

- install-<cksum>        (per kit install command, run-once)
- agent-installed-<agent> (agent npm install, run-once)
- agent-user-ready       (agent user + sudoers setup)
- oci-ready              (podman/OCI engine install)

Each gate is now acq_host_config_has/_write on the host instead of a guest
`test -f`/`touch`. Behavior is otherwise unchanged (still fail-soft, still
re-runs the cheap idempotent device-node grant / shell-sync outside the gate).

Tests: seed_host_config_gates seeds agent-user-ready/oci-ready from
STUB_AGENT_USER_READY/STUB_OCI_READY; the guest test -f arms for these markers
are removed from the stub; gate assertions read the host store.

With this, no /var/lib/acq guest marker is written or read by acq anymore.

Refs: GSA-TTS/agentic-coding-quickstart#503

Co-authored-by: OpenCode [claude_4_8_opus] <bret.mogilefsky@gsa.gov>
---
 acq.backends/msb.sh                | 31 ++++++++++++++++++------------
 scripts/test-acq-lib.sh            | 31 ++++++++++++++++++------------
 test/bats/72-msb-agent-user.bats   | 16 +++++++++++----
 test/bats/73-msb-kits-startup.bats | 12 +++++++++---
 4 files changed, 59 insertions(+), 31 deletions(-)

diff --git a/acq.backends/msb.sh b/acq.backends/msb.sh
index 5653eb14..4e35aea3 100644
--- a/acq.backends/msb.sh
+++ b/acq.backends/msb.sh
@@ -1896,8 +1896,11 @@ _acq_msb_exec_install() {
   eval "_ef=(\${${_eflagn}[@]+\"\${${_eflagn}[@]}\"})"
 
   local marker
-  marker="/var/lib/acq/install-$(printf '%s\0' "$@" | cksum | cut -d' ' -f1)"
-  if _acq_msb_cli exec "$_name" -u 0 -- sh -c "test -f '$marker'" </dev/null >/dev/null 2>&1; then
+  # Host-authoritative run-once gate (ADR-0030): a presence key in the host config
+  # store, keyed by the command's cksum, instead of a guest `touch`/`test -f` a
+  # passwordless-sudo agent could forge to SUPPRESS this install step.
+  marker="install-$(printf '%s\0' "$@" | cksum | cut -d' ' -f1)"
+  if acq_host_config_has msb "$_name" "$marker"; then
     acq_debug "msb cmd[install] already done (marker hit): $*"
     return 0
   fi
@@ -1908,7 +1911,7 @@ _acq_msb_exec_install() {
     return 0
   }
   acq_debug "msb cmd[install] DONE: $*"
-  _acq_msb_cli exec "$_name" -u 0 -- sh -c "mkdir -p /var/lib/acq && touch '$marker'" </dev/null >/dev/null 2>&1 || true
+  acq_host_config_write msb "$_name" "$marker" 1 || true
 }
 
 # _acq_msb_exec_run NAME PHASE USER BACKGROUND UFLAG_ARRVAR EFLAG_ARRVAR -- ARGV...
@@ -3435,8 +3438,8 @@ _acq_msb_install_agent() {
     return 0
   fi
 
-  local marker="/var/lib/acq/agent-installed-${agent}"
-  if _acq_msb_cli exec "$name" -u 0 -- sh -c "test -f '$marker'" >/dev/null 2>&1; then
+  local marker="agent-installed-${agent}"
+  if acq_host_config_has msb "$name" "$marker"; then
     return 0
   fi
 
@@ -3457,7 +3460,7 @@ _acq_msb_install_agent() {
 
   # Verify the binary is now on PATH before recording the marker.
   if _acq_msb_cli exec "$name" -u 0 -- sh -c "command -v '$agent'" >/dev/null 2>&1; then
-    _acq_msb_cli exec "$name" -u 0 -- sh -c "mkdir -p /var/lib/acq && touch '$marker'" >/dev/null 2>&1 || true
+    acq_host_config_write msb "$name" "$marker" 1 || true
     acq_debug "msb: agent '$agent' installed and on PATH in $name"
   else
     echo "acq(msb): warning: installed '$agent' but it is not on PATH in '$name'." >&2
@@ -3487,8 +3490,11 @@ _acq_msb_install_agent() {
 # _acq_msb_exec_command) with HOME exported.
 _acq_msb_ensure_agent_user() {
   local name="$1"
-  local marker="/var/lib/acq/agent-user-ready"
-  if _acq_msb_cli exec "$name" -u 0 -- sh -c "test -f '$marker'" >/dev/null 2>&1; then
+  # Host-authoritative run-once gate (ADR-0030): the user/sudoers setup is gated
+  # on a host config key, not a guest marker a passwordless-sudo agent could
+  # pre-create to SKIP the setup.
+  local marker="agent-user-ready"
+  if acq_host_config_has msb "$name" "$marker"; then
     # The user exists from an earlier run, but its login shell may predate the
     # passwd-shell setup: re-sync it so an existing /bin/sh agent user
     # is healed to bash on its next run, not left behind.
@@ -3572,7 +3578,7 @@ _acq_msb_ensure_agent_user() {
     return 1
   }
   _acq_msb_ensure_agent_shell "$name"
-  _acq_msb_cli exec "$name" -u 0 -- sh -c "mkdir -p /var/lib/acq && touch '$marker'" >/dev/null 2>&1 || true
+  acq_host_config_write msb "$name" "$marker" 1 || true
 }
 
 # _acq_msb_ensure_agent_shell NAME — align the agent's login shell with what
@@ -4109,8 +4115,8 @@ _acq_msb_ensure_oci() {
   # and it is also re-applied on restart from acq_backend_start.
   _acq_msb_grant_oci_devs "$name"
 
-  local marker="/var/lib/acq/oci-ready"
-  if _acq_msb_cli exec "$name" -u 0 -- sh -c "test -f '$marker'" >/dev/null 2>&1; then
+  local marker="oci-ready"
+  if acq_host_config_has msb "$name" "$marker"; then
     return 0
   fi
 
@@ -4279,7 +4285,8 @@ EOF
       # Best-effort: mark ready so we do not re-run the (network-bound) install on
       # every provision/restart. (The /dev/net/tun grant and config writes above
       # are cheap + idempotent and re-run each pass regardless of this marker.)
-      _acq_msb_cli exec "$name" -u 0 -- sh -c "mkdir -p /var/lib/acq && touch '$marker'" >/dev/null 2>&1 || true
+      # Host-authoritative (ADR-0030).
+      acq_host_config_write msb "$name" "$marker" 1 || true
       acq_debug "msb: OCI engine (rootless podman) ready in $name"
       return 0
     fi
diff --git a/scripts/test-acq-lib.sh b/scripts/test-acq-lib.sh
index 7fa4772e..8159d9b7 100644
--- a/scripts/test-acq-lib.sh
+++ b/scripts/test-acq-lib.sh
@@ -304,12 +304,6 @@ case "$_msb_sub" in
       # models a bash-less base. MUST precede the generic command-v arm.
       *"command -v bash"*)
         [ "${STUB_GUEST_BASH:-1}" = "0" ] && exit 1 || printf '/bin/bash\n' ;;
-      # The agent-user-ready marker gate. Default ABSENT (exit 1, like the
-      # generic test -f arm) so provision runs the full block;
-      # STUB_AGENT_USER_READY=1 models an already-provisioned sandbox so the
-      # heal's marker-hit shell-sync path can be exercised.
-      *"test -f '/var/lib/acq/agent-user-ready'"*)
-        [ "${STUB_AGENT_USER_READY:-0}" = "1" ] && exit 0 || exit 1 ;;
       # The OCI-engine setup is TWO msb-exec `sh -c` blocks: (1) a root (`-u 0`)
       # install/config block carrying `/usr/local/bin/docker`, and (2) a rootless
       # verify block (`-u agent`) that runs a `podman build` layer-mount self-test
@@ -323,12 +317,10 @@ case "$_msb_sub" in
         [ "${STUB_OCI_SETUP_FAIL:-0}" = "1" ] && exit 1 || exit 0 ;;
       *"acq-oci-selftest"*)
         [ "${STUB_OCI_VERIFY_FAIL:-0}" = "1" ] && exit 1 || exit 0 ;;
-      # The OCI-ready marker probe (`test -f '/var/lib/acq/oci-ready'`) gates the
-      # setup block. Match it BEFORE the generic `test -f` (markers absent) case
-      # below. Default ABSENT (exit 1) so the OCI step runs; STUB_OCI_READY=1
-      # makes the marker present (exit 0) to exercise the marker-gated skip.
-      *"test -f '/var/lib/acq/oci-ready'"*)
-        [ "${STUB_OCI_READY:-0}" = "1" ] && exit 0 || exit 1 ;;
+      # ADR-0030: the agent-user-ready and oci-ready run-once gates moved OFF the
+      # guest /var/lib/acq markers onto the HOST config store (acq_host_config_*).
+      # Tests seed those via seed_host_config_gates (from STUB_AGENT_USER_READY /
+      # STUB_OCI_READY), so no guest `test -f` arm remains for them here.
       # `command -v <agent>` (agent-presence probe): controllable so the install
       # path can be exercised. By default the agent is ABSENT (exit 1) so install
       # runs; STUB_AGENT_PRESENT=1 makes it "present" (skips install). The prereq
@@ -569,3 +561,18 @@ seed_host_config() {
 # stub library) still sees the helper. The ACQ_PROVENANCE_DIR/ACQ_STATE_DIR env
 # exports carry the store location into that subshell too.
 export -f seed_host_config 2>/dev/null || true
+
+# seed_host_config_gates BACKEND NAME — seed the ADR-0030 presence-gate keys
+# (agent-user-ready, oci-ready) from STUB_AGENT_USER_READY / STUB_OCI_READY, so a
+# test can model an already-provisioned sandbox (the run-once gates now live in
+# the host config store, not guest `touch`/`test -f` markers). Only a truthy knob
+# writes the key. Requires acq_host_config_* (source common.sh first).
+seed_host_config_gates() {
+  local backend="${1:-msb}" name="${2:-}"
+  [ -n "$name" ] || return 0
+  command -v acq_host_config_write >/dev/null 2>&1 || return 0
+  [ "${STUB_AGENT_USER_READY:-0}" = "1" ] && acq_host_config_write "$backend" "$name" agent-user-ready 1
+  [ "${STUB_OCI_READY:-0}" = "1" ] && acq_host_config_write "$backend" "$name" oci-ready 1
+  return 0
+}
+export -f seed_host_config_gates 2>/dev/null || true
diff --git a/test/bats/72-msb-agent-user.bats b/test/bats/72-msb-agent-user.bats
index 7f6fae1d..ef69a4eb 100644
--- a/test/bats/72-msb-agent-user.bats
+++ b/test/bats/72-msb-agent-user.bats
@@ -35,6 +35,7 @@ _provision() { # NAME AGENT PRE_SNIPPET [KITDIR]
     # NOTE: the stub must NOT read a variable named "kitdir" — provision declares
     # a `local kitdir`, which dynamically shadows it at stub-call time.
     _acq_msb_fetch_kit() { printf "%s\n" "$stub_kitdir"; }
+    seed_host_config_gates msb "$name"
     acq_backend_provision "$name" "$agent" /tmp 2>&1
     printf "PROVISION_RC=%s\n" "$?"
   ' _ "$name" "$agent" "$pre" "$kitdir"
@@ -145,6 +146,7 @@ _attach() { # PRE_SNIPPET NAME
     eval "$pre"
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
     seed_host_config msb "$name"
+    seed_host_config_gates msb "$name"
     acq_backend_attach "$name" 2>&1
   ' _ "$1" "$2"
 }
@@ -216,7 +218,8 @@ _attach() { # PRE_SNIPPET NAME
   local log; log=$(cat "$CALLS")
   assert_regex "$log" 'PODMAN_PKGS='
   assert_regex "$log" '/usr/local/bin/docker'
-  assert_regex "$log" "touch '/var/lib/acq/oci-ready'"
+  # ADR-0030: the oci-ready gate is recorded in the host config store.
+  assert_equal "$(cat "$ACQ_PROVENANCE_DIR"/msb/ocibox.*.config/oci-ready 2>/dev/null)" "1"
   assert_regex "$log" '/etc/containers/storage\.conf'
   assert_regex "$log" 'driver = ..vfs..'
   assert_regex "$log" 'mount_program'
@@ -258,7 +261,9 @@ _attach() { # PRE_SNIPPET NAME
 @test "msb: the OCI setup is skipped when the ready marker already exists" {
   _provision ocirdybox shell 'export ACQ_SECRET_STORE_DIR="'"$STUBDIR"'/ociready-secrets" STUB_OCI_READY=1'
   local log; log=$(cat "$CALLS")
-  assert_regex "$log" "test -f '/var/lib/acq/oci-ready'"
+  # ADR-0030: the oci-ready gate is a host config key now, seeded by
+  # seed_host_config_gates from STUB_OCI_READY; a hit skips the setup block.
+  assert_equal "$(cat "$ACQ_PROVENANCE_DIR"/msb/ocirdybox.*.config/oci-ready 2>/dev/null)" "1"
   refute_regex "$log" 'PODMAN_PKGS='
   refute_regex "$log" '/usr/local/bin/docker'
 }
@@ -274,7 +279,8 @@ _attach() { # PRE_SNIPPET NAME
   _provision ocifailbox shell 'export ACQ_SECRET_STORE_DIR="'"$STUBDIR"'/ocifail-secrets" STUB_OCI_SETUP_FAIL=1'
   assert_success
   assert_output --partial 'could not provision an OCI engine'
-  refute_regex "$(cat "$CALLS")" "touch '/var/lib/acq/oci-ready'"
+  # The host-store oci-ready key must NOT be written on a failed setup.
+  [ ! -f "$ACQ_PROVENANCE_DIR"/msb/ocifailbox.*.config/oci-ready ]
 }
 
 @test "msb: an unsafe ACQ_MSB_PODMAN_PKGS is refused and never reaches an exec" {
@@ -417,10 +423,12 @@ _attach() { # PRE_SNIPPET NAME
     . "'"$REPO_ROOT"'/acq.backends/msb.sh"
     # shellcheck disable=SC2034  # consumed by the sourced acq_backend_ensure_kits_applied
     ACQ_CLI_KITS=()
+    seed_host_config_gates msb healshbox
     acq_backend_ensure_kits_applied healshbox >/dev/null 2>&1
   '
   local log; log=$(cat "$CALLS")
-  assert_regex "$log" "test -f '/var/lib/acq/agent-user-ready'"
+  # ADR-0030: agent-user-ready is a host config key; a hit skips useradd but
+  # still re-syncs the login shell (the heal path this test asserts).
   assert_regex "$log" 'acq-login-profile.* sh /bin/bash'
   refute_regex "$log" 'useradd'
 }
diff --git a/test/bats/73-msb-kits-startup.bats b/test/bats/73-msb-kits-startup.bats
index 6cc39853..41adf45b 100644
--- a/test/bats/73-msb-kits-startup.bats
+++ b/test/bats/73-msb-kits-startup.bats
@@ -154,9 +154,11 @@ SPEC
     _acq_msb_apply_kit_dir instmarkerbox "$imk"
   '
   local log; log=$(cat "$CALLS")
-  assert_regex "$log" "test -f '/var/lib/acq/install-"
-  assert_regex "$log" "touch '/var/lib/acq/install-"
+  # ADR-0030: the run-once install gate is a host config key now, not a guest
+  # test -f/touch. The install command still runs, and the gate key is written.
   assert_regex "$log" 'msb exec instmarkerbox -u 0'
+  local instkey; instkey=$(ls "$ACQ_PROVENANCE_DIR"/msb/instmarkerbox.*.config/install-* 2>/dev/null | head -n1)
+  [ -n "$instkey" ]
 }
 
 # Provision helper that stages startup scripts to a per-test dir and keeps them.
@@ -306,8 +308,12 @@ SPEC
   local log body
   log=$(cat "$CALLS")
   body=$(_staged_body mix-stage)
-  assert_regex "$log" "test -f '/var/lib/acq/install-"
+  # ADR-0030: install is still exec-based and run-once, but the gate lives in the
+  # host config store now (not a guest test -f). Assert the install ran and a
+  # gate key was recorded; startup is staged into the script body, not the gate.
   assert_regex "$log" 'echo INSTALL_ONLY_0017'
+  local instkey; instkey=$(ls "$ACQ_PROVENANCE_DIR"/msb/mixbox.*.config/install-* 2>/dev/null | head -n1)
+  [ -n "$instkey" ]
   assert_regex "$body" 'echo STARTUP_ONLY_0017'
   refute_regex "$body" 'INSTALL_ONLY_0017'
 }

From 7de3211ed555b251e1aaa1a9c3e395b878041495 Mon Sep 17 00:00:00 2001
From: Bret Mogilefsky <bret.mogilefsky@gsa.gov>
Date: Tue, 22 Sep 2026 00:39:24 +0000
Subject: [PATCH 05/12] feat(acq): execute trusted kit startup code from the
 :ro mount (ADR-0030)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements ADR-0030 Mechanism 2. A kit files[] entry marked `readonly: true`
carries trusted CODE that acq must run from the host-authoritative read-only
mount, not a guest-writable copy a passwordless-sudo agent could tamper between
restarts.

- kit_spec_files surfaces a 5th tab field (readonly), default empty — 4-field
  consumers and unflagged files are unaffected.
- _acq_msb_apply_kit_dir stages a readonly file onto the per-sandbox host config
  dir (kit-files/<path-slug>.<crc>, cp 0555) instead of `msb copy`ing it into the
  guest, and records a guest-path -> :ro-path rewrite.
- _acq_msb_run_commands and the staged --script-path body
  (_acq_msb_startup_body_into) rewrite any startup argv token that EXACTLY equals
  a readonly file guest path to its :ro path (whole-token match; a --flag data
  path is left alone). So both the exec heal and a native replay run the :ro copy.
- Identification is declared (readonly: true), never inferred from argv, so a
  data file the command also reads (opencode.jsonc) stays a normal guest drop.

Backward compatible: no readonly files -> empty rewrite table -> unchanged
behavior. Adoption of the field by the patterns-repo kits (usai-provider merge
script, ADR 0003 provider normalizers) is additive and independently deployable.

New suite 79-msb-readonly-kit-files.bats covers field surfacing, host-staging vs
guest-copy, argv rewrite on both the exec and staged-body paths, whole-token
matching, and the :ro mount.

Refs: GSA-TTS/agentic-coding-quickstart#503

Co-authored-by: OpenCode [claude_4_8_opus] <bret.mogilefsky@gsa.gov>
---
 acq.backends/kit-translate.sh                 |  17 ++-
 acq.backends/msb.sh                           | 128 +++++++++++++++-
 .../0030-host-authoritative-sandbox-config.md |  20 +++
 test/bats/79-msb-readonly-kit-files.bats      | 144 ++++++++++++++++++
 4 files changed, 302 insertions(+), 7 deletions(-)
 create mode 100644 test/bats/79-msb-readonly-kit-files.bats

diff --git a/acq.backends/kit-translate.sh b/acq.backends/kit-translate.sh
index 99fe3851..2260acfc 100644
--- a/acq.backends/kit-translate.sh
+++ b/acq.backends/kit-translate.sh
@@ -35,7 +35,7 @@
 #   kit_spec_net_allow   SPEC                -> one host[:port] per line
 #   kit_spec_published_ports SPEC            -> one "guest<TAB>proto<TAB>name<TAB>host" per line
 #   kit_spec_volumes     SPEC                -> one "path<TAB>type<TAB>size" per line
-#   kit_spec_files       SPEC                -> one "path|mode|phase|source" per line
+#   kit_spec_files       SPEC                -> one "path|mode|phase|source|readonly" per line
 #   kit_spec_commands    SPEC                -> command records (see format below)
 #   kit_spec_env         SPEC                -> one "NAME<TAB>value" per line
 #   kit_spec_has_shortcut SPEC BACKEND       -> 0 if backend_shortcuts.<backend>
@@ -486,9 +486,14 @@ _kit_vol_validate() {
 # kit_spec_files SPEC
 # ---------------------------------------------------------------------------
 # Echo one record per files[] entry, tab-separated:
-#   path <TAB> mode <TAB> phase <TAB> source
+#   path <TAB> mode <TAB> phase <TAB> source <TAB> readonly
 # phase is empty if unspecified (default: written before commands run).
 # source is empty for inline-content files (not used by the four acq kits).
+# readonly is "true" iff the entry declares `readonly: true` — a file whose
+# BYTES are trusted CODE acq must execute from a host-authoritative read-only
+# mount rather than a guest-writable copy a passwordless-sudo agent could tamper
+# (ADR-0030). Empty (treated as false) otherwise, so existing 4-field consumers
+# and unflagged files are unaffected.
 kit_spec_files() {
   local spec="$1"
   [ -f "$spec" ] || return 0
@@ -517,9 +522,10 @@ kit_spec_files() {
       if (k=="mode")   cur_mode=v
       if (k=="phase")  cur_phase=v
       if (k=="source") cur_source=v
+      if (k=="readonly") cur_readonly=v
       if (k=="description") cur_desc=v
     }
-    function flush() {
+    function flush(   ro) {
       if (cur_path != "") {
         # Reject fields that could break out of the shell contexts these values
         # are later interpolated into. A hostile or mistyped kit spec must not
@@ -536,6 +542,7 @@ kit_spec_files() {
         # kit stages no files at all — a silent, host-dependent failure, because
         # the warning goes to stderr and the create path treats kit failures as
         # best-effort. Do NOT "simplify" this back to an interval expression.
+        ro = (cur_readonly == "true") ? "true" : ""
         if (cur_mode != "" && cur_mode !~ /^[0-7][0-7][0-7][0-7]?$/) {
           print "kit-translate: skipping file with invalid mode: " cur_mode > "/dev/stderr"
         } else if (cur_path !~ /^[A-Za-z0-9._\/-]+$/) {
@@ -543,10 +550,10 @@ kit_spec_files() {
         } else if (cur_source != "" && cur_source !~ /^[A-Za-z0-9._\/-]+$/) {
           print "kit-translate: skipping file with unsafe source: " cur_source > "/dev/stderr"
         } else {
-          printf "%s\t%s\t%s\t%s\n", cur_path, cur_mode, cur_phase, cur_source
+          printf "%s\t%s\t%s\t%s\t%s\n", cur_path, cur_mode, cur_phase, cur_source, ro
         }
       }
-      cur_path=""; cur_mode=""; cur_phase=""; cur_source=""; cur_desc=""
+      cur_path=""; cur_mode=""; cur_phase=""; cur_source=""; cur_readonly=""; cur_desc=""
     }
   ' "$spec"
 }
diff --git a/acq.backends/msb.sh b/acq.backends/msb.sh
index 4e35aea3..b8157bcc 100644
--- a/acq.backends/msb.sh
+++ b/acq.backends/msb.sh
@@ -658,6 +658,14 @@ ACQ_MSB_CLONES_DIR="${ACQ_MSB_CLONES_DIR:-${ACQ_STATE_DIR}/clones}"
 # always defined even if provision is not the entry point.
 _ACQ_MSB_STARTUP_STAGE_FILES=()
 _ACQ_MSB_STARTUP_STAGED=""
+# Per-kit read-only-file rewrite table (ADR-0030 Mechanism 2): parallel arrays
+# mapping a kit-declared guest path (FROM) to the path the same bytes appear at
+# on the read-only host-config mount (TO). _acq_msb_apply_kit_dir populates these
+# from `readonly: true` files[] entries; _acq_msb_run_commands / the staged
+# startup body rewrite any startup-argv token equal to a FROM into its TO, so
+# trusted code runs from the :ro mount, never a guest-writable copy.
+_ACQ_MSB_RO_REWRITE_FROM=()
+_ACQ_MSB_RO_REWRITE_TO=()
 # SSH user for the serve listener. `msb ssh serve` authorizes a key host-wide;
 # the login user on the loopback listener defaults to root (override if a
 # deployment's msb serve expects a different account).
@@ -1566,19 +1574,40 @@ _acq_msb_apply_kit_dir() {
 $(kit_spec_files "$spec")
 EOF
 
-  local path mode phase source src _i
+  local path mode phase source readonly src _i
+  # Reset the per-kit readonly-file rewrite table (guest path -> :ro guest path)
+  # before this kit's files are processed; _acq_msb_run_commands consults it to
+  # rewrite startup argv so trusted code runs from the read-only mount (ADR-0030).
+  _ACQ_MSB_RO_REWRITE_FROM=()
+  _ACQ_MSB_RO_REWRITE_TO=()
   for _i in ${_frecs[@]+"${!_frecs[@]}"}; do
     fline="${_frecs[$_i]}"
     path=$(printf '%s' "$fline" | cut -f1)
     mode=$(printf '%s' "$fline" | cut -f2)
     phase=$(printf '%s' "$fline" | cut -f3)
     source=$(printf '%s' "$fline" | cut -f4)
+    readonly=$(printf '%s' "$fline" | cut -f5)
     [ -n "$path" ] || continue
     src=""
     if [ -n "$source" ]; then
       src="${kitdir}/${source}"
     fi
-    if [ -n "$src" ] && [ -f "$src" ]; then
+    if [ "$readonly" = "true" ] && [ -n "$src" ] && [ -f "$src" ]; then
+      # Trusted CODE (ADR-0030 Mechanism 2): stage it on the per-sandbox
+      # host-config dir so the guest sees it through the READ-ONLY mount and a
+      # passwordless-sudo agent cannot rewrite it. Do NOT copy it into the
+      # guest's writable filesystem; record a rewrite so the invoking startup
+      # command runs the :ro copy instead of the (absent) guest path.
+      local _ro_guest
+      if _ro_guest=$(_acq_msb_stage_readonly_file "$name" "$kitdir" "$path" "$src"); then
+        _ACQ_MSB_RO_REWRITE_FROM+=("$path")
+        _ACQ_MSB_RO_REWRITE_TO+=("$_ro_guest")
+        acq_debug "msb readonly kit file: $path -> $_ro_guest (:ro)"
+      else
+        echo "acq(msb): warning: could not stage read-only kit file '$path' for '$name';" \
+             "its startup command may fail." >&2
+      fi
+    elif [ -n "$src" ] && [ -f "$src" ]; then
       _acq_msb_copy_file_verified "$name" "$src" "$path" "$mode" || {
         echo "acq(msb): error: could not place kit file at ${name}:${path}" >&2
         echo "acq(msb):   subsequent kit commands that read it will fail." >&2
@@ -1627,6 +1656,52 @@ _acq_msb_reset_kit_env() {
   acq_host_config_clear msb "$1" kit-env
 }
 
+# _acq_msb_stage_readonly_file NAME KITDIR GUESTPATH SRC — stage one trusted kit
+# code file onto the per-sandbox host-config dir so the guest sees it through the
+# READ-ONLY mount (ADR-0030 Mechanism 2), and echo the guest path it appears at.
+# Returns non-zero (and echoes nothing) on failure. The file is placed under a
+# `kit-files/<pathslug>.<crc>` subtree of the host-config dir (a direct
+# filesystem write, NOT acq_host_config_write, whose flat KEY charset forbids the
+# nested path). Staged 0555 on the host — defense in depth; the :ro mount is the
+# real guarantee. No chown: a :ro bind is readable/executable by the agent user
+# regardless of host owner.
+_acq_msb_stage_readonly_file() {
+  local name="$1" kitdir="$2" guestpath="$3" src="$4"
+  local cfgdir slug crc dest reldir="kit-files"
+  cfgdir=$(acq_host_config_dir msb "$name") || return 1
+  # Lossy slug + CRC of the guest path, matching the volume-name scheme
+  # (_acq_msb_volume_flags_from_records): map non-alnum to '-', squeeze runs, and
+  # append a CRC so two distinct paths that slug the same do not collide.
+  slug=$(printf '%s' "${guestpath#/}" | tr -c 'A-Za-z0-9' '-' | tr -s '-')
+  slug="${slug%-}"
+  crc=$(printf '%s' "$guestpath" | cksum 2>/dev/null | cut -d' ' -f1 2>/dev/null || echo 0)
+  if ! mkdir -p "${cfgdir}/${reldir}" 2>/dev/null; then
+    acq_debug "msb readonly-stage: could not create ${cfgdir}/${reldir}"
+    return 1
+  fi
+  chmod 700 "$cfgdir" 2>/dev/null || true
+  dest="${cfgdir}/${reldir}/${slug}.${crc}"
+  cp -f "$src" "$dest" 2>/dev/null || { acq_debug "msb readonly-stage: cp failed: $src -> $dest"; return 1; }
+  chmod 0555 "$dest" 2>/dev/null || true
+  # The guest sees the host-config dir at ACQ_HOST_CONFIG_GUEST_DIR (:ro).
+  printf '%s/%s/%s.%s\n' "$ACQ_HOST_CONFIG_GUEST_DIR" "$reldir" "$slug" "$crc"
+}
+
+# _acq_msb_ro_rewrite_token TOKEN — echo TOKEN, or its read-only-mount equivalent
+# when TOKEN exactly equals a staged readonly file's declared guest path (ADR-0030
+# Mechanism 2). Whole-token match only (never substring), so a --flag value that
+# merely mentions the path is untouched. Bash 3.2 safe (parallel-array scan).
+_acq_msb_ro_rewrite_token() {
+  local _tok="$1" _i
+  for _i in ${_ACQ_MSB_RO_REWRITE_FROM[@]+"${!_ACQ_MSB_RO_REWRITE_FROM[@]}"}; do
+    if [ "$_tok" = "${_ACQ_MSB_RO_REWRITE_FROM[$_i]}" ]; then
+      printf '%s\n' "${_ACQ_MSB_RO_REWRITE_TO[$_i]}"
+      return 0
+    fi
+  done
+  printf '%s\n' "$_tok"
+}
+
 # Copy a host file into the guest and VERIFY it is readable there before
 # returning. Also chown files under /home/agent to the agent user (they are
 # copied as root, but the kits' startup commands read them as the agent user;
@@ -1771,6 +1846,16 @@ EOF
         ;;
       "__END__")
         reading=0
+        # ADR-0030 Mechanism 2: rewrite any argv token that names a readonly
+        # (trusted-code) kit file to its read-only-mount path, so startup runs the
+        # :ro copy, not a guest-writable one. No-op when the rewrite table is
+        # empty (the common case: no kit declared readonly files).
+        if [ "${#_ACQ_MSB_RO_REWRITE_FROM[@]}" -gt 0 ] && [ "${#argv[@]}" -gt 0 ]; then
+          local _ai
+          for _ai in "${!argv[@]}"; do
+            argv[$_ai]=$(_acq_msb_ro_rewrite_token "${argv[$_ai]}")
+          done
+        fi
         _acq_msb_exec_command "$name" "$phase" "$user" "$background" \
           ${_kit_env[@]+"${_kit_env[@]}"} -- ${argv[@]+"${argv[@]}"}
         ;;
@@ -2143,6 +2228,31 @@ _acq_msb_startup_body_into() {
   local _kit_env=()
   _acq_msb_collect_kit_env_into _kit_env "$_spec"
 
+  # ADR-0030 Mechanism 2: build this spec's readonly-file rewrite table so the
+  # staged --script-path body (like the exec path) invokes trusted code from the
+  # :ro mount. Staging runs at create-flag assembly, before _acq_msb_apply_kit_dir
+  # populates the module-level table, so derive a LOCAL table from the same
+  # readonly files[] entries. The guest :ro path is derived by the same
+  # slug+crc scheme _acq_msb_stage_readonly_file uses (the file itself is staged
+  # later, during apply; here we only need the resulting guest path to rewrite
+  # the argv token).
+  local _ro_from=() _ro_to=() _frec _fpath _fsource _freadonly _fslug _fcrc
+  while IFS= read -r _frec; do
+    [ -n "$_frec" ] || continue
+    _freadonly=$(printf '%s' "$_frec" | cut -f5)
+    [ "$_freadonly" = "true" ] || continue
+    _fpath=$(printf '%s' "$_frec" | cut -f1)
+    _fsource=$(printf '%s' "$_frec" | cut -f4)
+    [ -n "$_fpath" ] && [ -n "$_fsource" ] || continue
+    _fslug=$(printf '%s' "${_fpath#/}" | tr -c 'A-Za-z0-9' '-' | tr -s '-')
+    _fslug="${_fslug%-}"
+    _fcrc=$(printf '%s' "$_fpath" | cksum 2>/dev/null | cut -d' ' -f1 2>/dev/null || echo 0)
+    _ro_from+=("$_fpath")
+    _ro_to+=("${ACQ_HOST_CONFIG_GUEST_DIR}/kit-files/${_fslug}.${_fcrc}")
+  done <<EOF
+$(kit_spec_files "$_spec")
+EOF
+
   # Buffer the command stream first (kit_spec_commands runs its own subshell).
   local _lines=() line
   while IFS= read -r line; do
@@ -2167,6 +2277,20 @@ EOF
       "__END__")
         reading=0
         if [ "$phase" = "startup" ] && [ "${#argv[@]}" -gt 0 ]; then
+          # Rewrite readonly-file argv tokens to their :ro-mount path (whole-token
+          # match), so the staged body runs trusted code from the read-only mount.
+          if [ "${#_ro_from[@]}" -gt 0 ]; then
+            local _ai _aj _atok
+            for _ai in "${!argv[@]}"; do
+              _atok="${argv[$_ai]}"
+              for _aj in "${!_ro_from[@]}"; do
+                if [ "$_atok" = "${_ro_from[$_aj]}" ]; then
+                  argv[$_ai]="${_ro_to[$_aj]}"
+                  break
+                fi
+              done
+            done
+          fi
           local _prefix=() _cmdline
           _acq_msb_startup_env_prefix_into _prefix "$user" _kit_env
           _cmdline=$(_acq_msb_startup_emit_command "$user" "$background" _prefix argv)
diff --git a/docs/adr/0030-host-authoritative-sandbox-config.md b/docs/adr/0030-host-authoritative-sandbox-config.md
index 5c7c90a6..b89115cb 100644
--- a/docs/adr/0030-host-authoritative-sandbox-config.md
+++ b/docs/adr/0030-host-authoritative-sandbox-config.md
@@ -175,6 +175,18 @@ Concretely, this ADR introduces two mechanisms and a staged migration.
 - Kit `startup` code that acq re-runs across restarts is staged into the same
   per-sandbox `:ro` config dir and invoked from there by the heal, so a restart
   always executes the host-authoritative (pinned) copy, not a guest-tampered one.
+- **Identification is declared, not inferred.** A kit `files[]` entry marks
+  trusted code with `readonly: true`. acq stages such a file onto the host config
+  dir (under `kit-files/<path-slug>.<crc>`), does **not** `msb copy` it into the
+  guest's writable filesystem, and rewrites any startup-command argv token that
+  *exactly equals* the file's declared guest path to its `:ro`-mount path (whole
+  token only, so a `--flag <data-path>` value is left untouched). Inference from
+  "is this path referenced by a startup command" is deliberately rejected: trust
+  is a per-file property the kit author asserts, and a data file the command also
+  reads (e.g. `opencode.jsonc`) must stay a normal guest-writable drop.
+- A file **without** `readonly: true` is unchanged: copied into the guest and
+  invoked by its guest path (full backward compatibility; no shipped kit changes
+  behavior until it opts in).
 - Kits that genuinely must *compute* runtime state in-guest still may — they
   write their output to a guest-owned **rw** path (e.g. a per-sandbox catalog
   cache), which acq never treats as authoritative configuration. (This is
@@ -182,6 +194,14 @@ Concretely, this ADR introduces two mechanisms and a staged migration.
   from the `:ro` mount; rw *catalog* generated per-sandbox at startup, never
   shared across sandboxes.)
 
+> **Cross-repo dependency.** The `readonly: true` files[] field is additive to
+> the neutral `hybrid/v1` kit spec and must be adopted by the provider/harness
+> kits in `GSA-TTS/agentic-coding-patterns` for their trusted code (e.g.
+> `usai-provider`'s `merge-global-config.mjs`, and ADR 0003's provider
+> normalizers). The two sides are independently deployable: acq shipping first
+> is inert until a kit opts in; a kit shipping the field first is ignored by an
+> older acq (the file still copies into the guest). Tracked as sequenced work.
+
 ### Migration (one tracking issue, one PR, a commit per change)
 
 Applied incrementally, each preserving the current best-effort fail-soft
diff --git a/test/bats/79-msb-readonly-kit-files.bats b/test/bats/79-msb-readonly-kit-files.bats
new file mode 100644
index 00000000..aa6f3566
--- /dev/null
+++ b/test/bats/79-msb-readonly-kit-files.bats
@@ -0,0 +1,144 @@
+#!/usr/bin/env bats
+#
+# 79-msb-readonly-kit-files.bats — ADR-0030 Mechanism 2: trusted startup
+# execution from the read-only host-config mount.
+#
+# A kit files[] entry marked `readonly: true` carries trusted CODE that acq must
+# execute from the host-authoritative read-only mount (/var/lib/acq/host, mounted
+# :ro), NOT a guest-writable copy a passwordless-sudo agent could tamper. This
+# suite proves:
+#   - kit_spec_files surfaces the `readonly` field (5th tab column), default empty;
+#   - a readonly file is staged into the host-config dir's kit-files/ subtree and
+#     is NOT `msb copy`d into the guest;
+#   - the invoking startup command's argv token is rewritten to the :ro path
+#     (both the exec path and the staged --script-path body);
+#   - a non-readonly file still copies into the guest (unchanged behavior);
+#   - only a WHOLE-token match is rewritten (a --flag value that merely mentions
+#     the path is left alone).
+#
+# shellcheck shell=bats
+
+setup() { acq_setup_stubs; load_acq; }
+teardown() { acq_teardown_stubs; }
+
+load 'helper'
+
+# kit_spec_files field surfacing --------------------------------------------
+
+@test "kit_spec_files: emits readonly as a 5th field; default empty" {
+  local k="$STUBDIR/rokit"; mkdir -p "$k"
+  cat >"$k/spec.yaml" <<'SPEC'
+schemaVersion: "hybrid/v1"
+kind: mixin
+name: ro-kit
+displayName: RO Kit
+description: one readonly code file and one plain data file
+files:
+  - path: /home/agent/cfg/merge.mjs
+    mode: "0755"
+    source: files/merge.mjs
+    readonly: true
+  - path: /home/agent/cfg/data.jsonc
+    mode: "0644"
+    source: files/data.jsonc
+SPEC
+  run bash -c '. "'"$REPO_ROOT"'/acq.backends/kit-translate.sh"; kit_spec_files "'"$k"'/spec.yaml"'
+  assert_success
+  # Record 1: readonly=true in the 5th tab field.
+  assert_line --index 0 "$(printf '/home/agent/cfg/merge.mjs\t0755\t\tfiles/merge.mjs\ttrue')"
+  # Record 2: no readonly -> empty 5th field.
+  assert_line --index 1 "$(printf '/home/agent/cfg/data.jsonc\t0644\t\tfiles/data.jsonc\t')"
+}
+
+# provision: staging + no guest copy + argv rewrite -------------------------
+
+# A kit with a readonly code file invoked by a startup command, plus a plain
+# data file the same command references via a --flag.
+_ro_kit() { # DIR
+  local k="$1"; mkdir -p "$k/files"
+  printf 'console.log("merge");\n' > "$k/files/merge.mjs"
+  printf '{}\n' > "$k/files/data.jsonc"
+  cat >"$k/spec.yaml" <<'SPEC'
+schemaVersion: "hybrid/v1"
+kind: mixin
+name: ro-code-kit
+displayName: RO Code Kit
+description: trusted startup code + a data file
+files:
+  - path: /home/agent/cfg/merge.mjs
+    mode: "0755"
+    source: files/merge.mjs
+    readonly: true
+  - path: /home/agent/cfg/data.jsonc
+    mode: "0644"
+    source: files/data.jsonc
+commands:
+  - phase: startup
+    user: "1000"
+    command:
+      - node
+      - /home/agent/cfg/merge.mjs
+      - --source
+      - /home/agent/cfg/data.jsonc
+SPEC
+}
+
+@test "msb ro: a readonly code file is staged on the host-config dir, NOT copied into the guest" {
+  local k="$STUBDIR/rocode"; _ro_kit "$k"
+  : > "$CALLS"
+  run bash -c '
+    export ACQ_SECRET_STORE_DIR="'"$STUBDIR"'/rocode-secrets"
+    . "'"$REPO_ROOT"'/acq.backends/secret-store.sh"
+    . "'"$REPO_ROOT"'/acq.backends/kit-translate.sh"
+    . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    _acq_msb_fetch_kit() { printf "%s\n" "'"$k"'"; }
+    acq_backend_provision rocodebox shell /tmp >/dev/null 2>&1
+  '
+  local log; log=$(cat "$CALLS")
+  # The readonly file is staged into the per-sandbox host config dir kit-files/.
+  local staged; staged=$(find "$ACQ_PROVENANCE_DIR"/msb/rocodebox.*.config/kit-files -type f 2>/dev/null | head -n1)
+  [ -n "$staged" ]
+  # It is NOT msb-copied into the guest at its declared guest path.
+  refute_regex "$log" 'msb copy .*:/home/agent/cfg/merge\.mjs'
+  # The plain data file IS copied into the guest (unchanged behavior).
+  assert_regex "$log" 'msb copy .*rocodebox:/home/agent/cfg/data\.jsonc'
+}
+
+@test "msb ro: the startup argv token is rewritten to the :ro mount path (exec + staged body)" {
+  local k="$STUBDIR/rocode2"; _ro_kit "$k"
+  : > "$CALLS"
+  run bash -c '
+    export ACQ_SECRET_STORE_DIR="'"$STUBDIR"'/rocode2-secrets"
+    export ACQ_MSB_KEEP_STARTUP_STAGE=1 ACQ_MSB_STARTUP_STAGE_DIR="'"$STUBDIR"'/rocode2-stage"
+    . "'"$REPO_ROOT"'/acq.backends/secret-store.sh"
+    . "'"$REPO_ROOT"'/acq.backends/kit-translate.sh"
+    . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    _acq_msb_fetch_kit() { printf "%s\n" "'"$k"'"; }
+    acq_backend_provision rocode2box shell /tmp >/dev/null 2>&1
+  '
+  local log; log=$(cat "$CALLS")
+  # The exec-path startup command runs node on the :ro mount path, not the guest path.
+  assert_regex "$log" 'node /var/lib/acq/host/kit-files/home-agent-cfg-merge-mjs\.[0-9]+'
+  refute_regex "$log" 'node /home/agent/cfg/merge\.mjs'
+  # The --source DATA arg (a whole different token) is left at its guest path.
+  assert_regex "$log" -- '--source /home/agent/cfg/data\.jsonc'
+  # The staged --script-path body ALSO points node at the :ro copy (restart-safe).
+  local body; body=$(cat "$(find "$STUBDIR/rocode2-stage" -type f 2>/dev/null | head -n1)" 2>/dev/null)
+  assert_regex "$body" '/var/lib/acq/host/kit-files/home-agent-cfg-merge-mjs\.[0-9]+'
+  refute_regex "$body" '/home/agent/cfg/merge\.mjs'
+}
+
+@test "msb ro: the create-time host-config mount is read-only" {
+  local k="$STUBDIR/romount"; _ro_kit "$k"
+  : > "$CALLS"
+  run bash -c '
+    export ACQ_SECRET_STORE_DIR="'"$STUBDIR"'/romount-secrets"
+    . "'"$REPO_ROOT"'/acq.backends/secret-store.sh"
+    . "'"$REPO_ROOT"'/acq.backends/kit-translate.sh"
+    . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    _acq_msb_fetch_kit() { printf "%s\n" "'"$k"'"; }
+    acq_backend_provision romountbox shell /tmp >/dev/null 2>&1
+  '
+  # The host-config dir is mounted :ro at the well-known guest path.
+  assert_regex "$(cat "$CALLS")" -- '--volume [^ ]*romountbox[^ ]*\.config:/var/lib/acq/host:ro'
+}

From a699af38d9cb55d22f3628d3295f5b40798c7044 Mon Sep 17 00:00:00 2001
From: Bret Mogilefsky <bret.mogilefsky@gsa.gov>
Date: Tue, 22 Sep 2026 00:43:26 +0000
Subject: [PATCH 06/12] docs: reconcile ADR-0011/0021/KFM references with the
 host-config migration (ADR-0030)

Update the design-note and doc references that named the guest /var/lib/acq
markers (agent, workspace, ssh-auth-sock, kit-env, install-*, oci-ready) to
reflect that ADR-0030 moved them to acq's host-authoritative per-sandbox config
store. Behavior is unchanged; only the storage location and its trust boundary
moved. No bare tracker refs added.

Co-authored-by: OpenCode [claude_4_8_opus] <bret.mogilefsky@gsa.gov>
---
 acq.backends/msb.sh                           | 19 +++++++++--------
 docs/KNOWN_FAILURE_MODES.md                   | 11 +++++-----
 docs/adr/0011-msb-backend-and-neutral-kits.md | 21 ++++++++++++-------
 3 files changed, 30 insertions(+), 21 deletions(-)

diff --git a/acq.backends/msb.sh b/acq.backends/msb.sh
index b8157bcc..9e0ae39e 100644
--- a/acq.backends/msb.sh
+++ b/acq.backends/msb.sh
@@ -1115,10 +1115,11 @@ _acq_msb_wait_for_exec_ready() {
 # THE BOUNDARY — what stays on `msb exec`, and WHY it MUST:
 #
 #   1) INSTALL PHASE stays exec-based. install commands are run-once, gated by a
-#      root-owned marker keyed on a hash of the argv
-#      (_acq_msb_exec_install: /var/lib/acq/install-<cksum>), tested+written as
-#      uid 0 so the gate is independent of the command's own user. A create-time
-#      script re-runs on every restart by design — the OPPOSITE of run-once — so
+#      host-authoritative marker keyed on a hash of the argv
+#      (_acq_msb_exec_install: acq_host_config_has/_write "install-<cksum>", held
+#      on the host per ADR-0030 so a passwordless-sudo guest cannot forge it to
+#      suppress the step). A create-time script re-runs on every restart by
+#      design — the OPPOSITE of run-once — so
 #      folding install into the startup script would break its idempotency
 #      contract. install therefore stays out of the staged script entirely.
 #
@@ -1966,9 +1967,9 @@ _acq_msb_exec_flags_into() {
 
 # _acq_msb_exec_install NAME USER UFLAG_ARRVAR EFLAG_ARRVAR -- ARGV... — run an
 # install-phase command, gated by a per-command marker (hash of argv) so it runs
-# once per sandbox even across re-applies. The marker lives under /var/lib/acq
-# (root-owned) and is both TESTED and WRITTEN as uid 0, so the gate is
-# independent of the install command's own user.
+# once per sandbox even across re-applies. The marker is a key in the
+# host-authoritative config store (ADR-0030), so a passwordless-sudo guest cannot
+# forge it to suppress the install step.
 _acq_msb_exec_install() {
   local _name="$1" _user="$2" _uflagn="$3" _eflagn="$4"
   shift 4
@@ -4091,8 +4092,8 @@ EOF
 # forward on a RUNNING sandbox that acq is re-attaching to. See ADR-0021.
 #
 # WHY THIS EXISTS: the provision path wires the forward (emit --vsock, start the
-# socat bridge, write the /var/lib/acq/ssh-auth-sock marker), and the
-# stopped→resume path (acq_backend_start) restarts the bridge from that marker.
+# socat bridge, write the host-config ssh-auth-sock key), and the
+# stopped→resume path (acq_backend_start) restarts the bridge from that value.
 # But re-attaching to an ALREADY-RUNNING sandbox goes through neither: the heal
 # loop skips acq_backend_start (the sandbox is already running), so nothing
 # re-drives forwarding. That left two live gaps where the guest process env got
diff --git a/docs/KNOWN_FAILURE_MODES.md b/docs/KNOWN_FAILURE_MODES.md
index 7d185f2d..417c2b1b 100644
--- a/docs/KNOWN_FAILURE_MODES.md
+++ b/docs/KNOWN_FAILURE_MODES.md
@@ -1799,11 +1799,12 @@ sandbox, and it starts working again as soon as you
 `export SSH_AUTH_SOCK=/home/agent/.acq/ssh-agent.sock` by hand. Here the vsock
 route and the `socat` bridge are fine — what is missing is the
 **`SSH_AUTH_SOCK` env var in the agent's process**. acq injects that var
-(`-e SSH_AUTH_SOCK=…`) only when the persisted `/var/lib/acq/ssh-auth-sock`
-marker is present, and before the fix nothing re-established the bridge or wrote
-that marker when re-attaching to an already-running sandbox (the heal's
-start-if-stopped block is a no-op on a running sandbox, and only that path — or
-provision — wrote the marker).
+(`-e SSH_AUTH_SOCK=…`) only when the persisted ssh-agent sock value is present
+(recorded host-side in acq's per-sandbox config store, ADR-0030; originally a
+guest `/var/lib/acq/ssh-auth-sock` marker), and before the fix nothing
+re-established the bridge or wrote that value when re-attaching to an
+already-running sandbox (the heal's start-if-stopped block is a no-op on a
+running sandbox, and only that path — or provision — wrote it).
 
 Fixed in `acq.backends/msb.sh`: `acq_backend_ensure_kits_applied` now calls
 `_acq_msb_ensure_ssh_agent_forward` at the top of the heal, which re-drives the
diff --git a/docs/adr/0011-msb-backend-and-neutral-kits.md b/docs/adr/0011-msb-backend-and-neutral-kits.md
index c7406092..59ad85f0 100644
--- a/docs/adr/0011-msb-backend-and-neutral-kits.md
+++ b/docs/adr/0011-msb-backend-and-neutral-kits.md
@@ -405,13 +405,20 @@ strings). The translate layer:
 
 > **Update (2026-08-26):** The command-only scoping above dropped exactly the
 > agent-runtime config (`OPENCODE_CONFIG`-style vars) this vocabulary was
-> motivated by. The msb adapter now also persists the validated entries to a
-> root-owned guest marker (`/var/lib/acq/kit-env`, the same pattern as
-> `/var/lib/acq/agent` and `/var/lib/acq/ssh-auth-sock`) and replays them as
-> `-e` flags on every session path (attach, `acq exec`, `acq shell`), matching
-> sbx's sandbox-level env semantics. Names are re-validated on replay (tampered
-> marker defense) and the last value wins for a duplicate name (kits append in
-> application order, so a later kit overrides an earlier one).
+> motivated by. The msb adapter now also persists the validated entries and
+> replays them as `-e` flags on every session path (attach, `acq exec`,
+> `acq shell`), matching sbx's sandbox-level env semantics. Names are
+> re-validated on replay and the last value wins for a duplicate name (kits
+> append in application order, so a later kit overrides an earlier one).
+>
+> **Superseded storage (ADR-0030):** the persisted values described in this ADR
+> (`agent`, `workspace`, `ssh-auth-sock`, `kit-env`, and the run-once gate
+> markers) were originally written to root-owned **guest** files under
+> `/var/lib/acq/`. Because the in-sandbox agent has passwordless sudo, a guest
+> path is not tamper-proof against a prompt-injected agent. ADR-0030 moves all of
+> these to acq's **host-authoritative** per-sandbox config store (mounted into
+> the guest read-only where the guest must read them). The behavior described
+> here is unchanged; only the storage location and its trust boundary moved.
 
 Deliberately minimal (YAGNI): **static string values only** — no interpolation,
 no references to `files[]`-staged paths (a kit needing a computed value uses a

From 4343c4e267081aad342a332550cfa1cc9a07a3e6 Mon Sep 17 00:00:00 2001
From: Bret Mogilefsky <bret.mogilefsky@gsa.gov>
Date: Tue, 22 Sep 2026 17:26:01 +0000
Subject: [PATCH 07/12] fix(acq): resolve shellcheck SC2316/SC2144 in the
 host-config migration

CI pre-commit shellcheck flagged two errors introduced by the ADR-0030 work:

- SC2316 (acq.backends/msb.sh): `local ... readonly ...` applies `local` to a
  variable named `readonly`, which shellcheck reads as the readonly builtin.
  Rename the loop variable to `_readonly`.
- SC2144 (test/bats/72, 78): `[ ! -f "$DIR"/msb/<name>.*.config/<key> ]` uses a
  glob with -f, which does not work as intended. Replace with a globbed `ls`
  under `run bash -c` asserting empty output (the key is absent).

Behavior unchanged; offline bats suite still green (72/78/79/73/115).

Co-authored-by: OpenCode [claude_4_8_opus] <bret.mogilefsky@gsa.gov>
---
 acq.backends/msb.sh              | 6 +++---
 test/bats/72-msb-agent-user.bats | 3 ++-
 test/bats/78-msb-kit-env.bats    | 3 ++-
 3 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/acq.backends/msb.sh b/acq.backends/msb.sh
index 9e0ae39e..3d6fd1a9 100644
--- a/acq.backends/msb.sh
+++ b/acq.backends/msb.sh
@@ -1575,7 +1575,7 @@ _acq_msb_apply_kit_dir() {
 $(kit_spec_files "$spec")
 EOF
 
-  local path mode phase source readonly src _i
+  local path mode phase source _readonly src _i
   # Reset the per-kit readonly-file rewrite table (guest path -> :ro guest path)
   # before this kit's files are processed; _acq_msb_run_commands consults it to
   # rewrite startup argv so trusted code runs from the read-only mount (ADR-0030).
@@ -1587,13 +1587,13 @@ EOF
     mode=$(printf '%s' "$fline" | cut -f2)
     phase=$(printf '%s' "$fline" | cut -f3)
     source=$(printf '%s' "$fline" | cut -f4)
-    readonly=$(printf '%s' "$fline" | cut -f5)
+    _readonly=$(printf '%s' "$fline" | cut -f5)
     [ -n "$path" ] || continue
     src=""
     if [ -n "$source" ]; then
       src="${kitdir}/${source}"
     fi
-    if [ "$readonly" = "true" ] && [ -n "$src" ] && [ -f "$src" ]; then
+    if [ "$_readonly" = "true" ] && [ -n "$src" ] && [ -f "$src" ]; then
       # Trusted CODE (ADR-0030 Mechanism 2): stage it on the per-sandbox
       # host-config dir so the guest sees it through the READ-ONLY mount and a
       # passwordless-sudo agent cannot rewrite it. Do NOT copy it into the
diff --git a/test/bats/72-msb-agent-user.bats b/test/bats/72-msb-agent-user.bats
index ef69a4eb..fe555c1f 100644
--- a/test/bats/72-msb-agent-user.bats
+++ b/test/bats/72-msb-agent-user.bats
@@ -280,7 +280,8 @@ _attach() { # PRE_SNIPPET NAME
   assert_success
   assert_output --partial 'could not provision an OCI engine'
   # The host-store oci-ready key must NOT be written on a failed setup.
-  [ ! -f "$ACQ_PROVENANCE_DIR"/msb/ocifailbox.*.config/oci-ready ]
+  run bash -c 'ls "$1"/msb/ocifailbox.*.config/oci-ready 2>/dev/null' _ "$ACQ_PROVENANCE_DIR"
+  assert_output ''
 }
 
 @test "msb: an unsafe ACQ_MSB_PODMAN_PKGS is refused and never reaches an exec" {
diff --git a/test/bats/78-msb-kit-env.bats b/test/bats/78-msb-kit-env.bats
index 6f77bcba..e181640a 100644
--- a/test/bats/78-msb-kit-env.bats
+++ b/test/bats/78-msb-kit-env.bats
@@ -73,7 +73,8 @@ SPEC
   '
   assert_success
   refute_regex "$(cat "$CALLS")" '/var/lib/acq/kit-env'
-  [ ! -f "$ACQ_PROVENANCE_DIR"/msb/envbox2.*.config/kit-env ]
+  run bash -c 'ls "$1"/msb/envbox2.*.config/kit-env 2>/dev/null' _ "$ACQ_PROVENANCE_DIR"
+  assert_output ''
 }
 
 @test "msb kit env: acq exec replays persisted entries as -e flags; none when empty" {

From b61c3f9b310cc0880078bb85290a38543af99cd7 Mon Sep 17 00:00:00 2001
From: Bret Mogilefsky <bret.mogilefsky@gsa.gov>
Date: Wed, 23 Sep 2026 07:25:24 +0000
Subject: [PATCH 08/12] fix(acq): make readonly host-config startup code usable
 and legacy-safe

Address adversarial review findings on PR #504:

- Make the host-config mount root traversable by the guest agent (0711) while
  keeping flat acq-internal keys private (0600). readonly kit payloads under
  kit-files/ are now in a traversable directory and staged 0555, so startup code
  rewritten to /var/lib/acq/host/kit-files/... can actually be read/executed by
  user=agent through the :ro mount.
- Detect existing msb sandboxes that predate the ADR-0030 /var/lib/acq/host:ro
  mount. If the mount is absent or not traversable, do not rewrite readonly
  startup argv to a missing path; warn and fall back to the legacy guest copy so
  old sandboxes keep working until recreated.

Tests: extend 79-msb-readonly-kit-files for traversability modes and legacy
fallback. Targeted bats suites 79/72/78/73/115 pass locally.

Refs: GSA-TTS/agentic-coding-quickstart#503

Co-authored-by: OpenCode [claude_4_8_opus] <bret.mogilefsky@gsa.gov>
---
 acq.backends/common.sh                        | 14 +++++---
 acq.backends/msb.sh                           | 33 ++++++++++++++++---
 .../0030-host-authoritative-sandbox-config.md |  9 ++++-
 scripts/test-acq-lib.sh                       |  5 +++
 test/bats/79-msb-readonly-kit-files.bats      | 32 +++++++++++++++++-
 5 files changed, 82 insertions(+), 11 deletions(-)

diff --git a/acq.backends/common.sh b/acq.backends/common.sh
index 37a103fd..e98c3d7a 100644
--- a/acq.backends/common.sh
+++ b/acq.backends/common.sh
@@ -1531,6 +1531,11 @@ acq_cli_kits_load() {
 # was written. Atomic temp+rename write; fail-soft (mirrors the marker writes
 # it replaces, which were best-effort `|| true`).
 #
+# The sandbox config dir is chmod 0711: the guest must be able to traverse the
+# read-only mount root to execute `kit-files/...` staged code, but should not be
+# able to list acq-internal key names. Content-bearing flat keys remain 0600 on
+# the host; readonly kit code is staged under kit-files/ with executable perms.
+#
 # KEY charset is restricted ([A-Za-z0-9._-], no slash) so a key can never escape
 # the config dir; callers pass fixed literals (agent, workspace, ssh-auth-sock,
 # kit-env, and the gate markers).
@@ -1563,8 +1568,9 @@ _acq_host_config_key_ok() {
   esac
 }
 
-# Write one KEY's VALUE for a sandbox's host config. Creates the dir 0700 and the
-# file 0600 (world-unreadable on the host; the guest sees it via the :ro mount).
+# Write one KEY's VALUE for a sandbox's host config. Creates/traversabilizes the
+# dir 0711 and writes the file 0600 (world-unreadable on the host; the guest sees
+# only what it can traverse/read via the :ro mount).
 # Atomic temp+rename. Best-effort: warns (debug) and returns non-zero on failure
 # but never aborts the caller — preserving the fail-soft posture of the guest
 # markers this replaces.
@@ -1579,7 +1585,7 @@ acq_host_config_write() {
     acq_debug "host-config: could not create config dir: $dir"
     return 1
   fi
-  chmod 700 "$dir" 2>/dev/null || true
+  chmod 711 "$dir" 2>/dev/null || true
   file="$dir/$key"
   local tmp="${file}.tmp.$$"
   printf '%s' "$value" > "$tmp" 2>/dev/null || {
@@ -1631,7 +1637,7 @@ acq_host_config_append() {
   if ! mkdir -p "$dir" 2>/dev/null; then
     acq_debug "host-config: could not create config dir: $dir"; return 1
   fi
-  chmod 700 "$dir" 2>/dev/null || true
+  chmod 711 "$dir" 2>/dev/null || true
   file="$dir/$key"
   printf '%s\n' "$value" >> "$file" 2>/dev/null || {
     acq_debug "host-config: append failed: $file"; return 1; }
diff --git a/acq.backends/msb.sh b/acq.backends/msb.sh
index 3d6fd1a9..0b030b46 100644
--- a/acq.backends/msb.sh
+++ b/acq.backends/msb.sh
@@ -1581,6 +1581,10 @@ EOF
   # rewrite startup argv so trusted code runs from the read-only mount (ADR-0030).
   _ACQ_MSB_RO_REWRITE_FROM=()
   _ACQ_MSB_RO_REWRITE_TO=()
+  local _hcfg_mount_ok=0
+  if _acq_msb_host_config_mount_available "$name"; then
+    _hcfg_mount_ok=1
+  fi
   for _i in ${_frecs[@]+"${!_frecs[@]}"}; do
     fline="${_frecs[$_i]}"
     path=$(printf '%s' "$fline" | cut -f1)
@@ -1593,7 +1597,7 @@ EOF
     if [ -n "$source" ]; then
       src="${kitdir}/${source}"
     fi
-    if [ "$_readonly" = "true" ] && [ -n "$src" ] && [ -f "$src" ]; then
+    if [ "$_readonly" = "true" ] && [ -n "$src" ] && [ -f "$src" ] && [ "$_hcfg_mount_ok" -eq 1 ]; then
       # Trusted CODE (ADR-0030 Mechanism 2): stage it on the per-sandbox
       # host-config dir so the guest sees it through the READ-ONLY mount and a
       # passwordless-sudo agent cannot rewrite it. Do NOT copy it into the
@@ -1606,9 +1610,15 @@ EOF
         acq_debug "msb readonly kit file: $path -> $_ro_guest (:ro)"
       else
         echo "acq(msb): warning: could not stage read-only kit file '$path' for '$name';" \
-             "its startup command may fail." >&2
+             "falling back to the legacy guest copy." >&2
+        _readonly=""
+      fi
+    fi
+    if { [ "$_readonly" != "true" ] || [ "$_hcfg_mount_ok" -ne 1 ]; } && [ -n "$src" ] && [ -f "$src" ]; then
+      if [ "$_readonly" = "true" ]; then
+        echo "acq(msb): warning: sandbox '$name' has no readable ADR-0030 host-config mount;" \
+             "copying readonly kit file '$path' into the guest for compatibility. Recreate the sandbox to get tamper-resistant readonly startup code." >&2
       fi
-    elif [ -n "$src" ] && [ -f "$src" ]; then
       _acq_msb_copy_file_verified "$name" "$src" "$path" "$mode" || {
         echo "acq(msb): error: could not place kit file at ${name}:${path}" >&2
         echo "acq(msb):   subsequent kit commands that read it will fail." >&2
@@ -1657,6 +1667,18 @@ _acq_msb_reset_kit_env() {
   acq_host_config_clear msb "$1" kit-env
 }
 
+# _acq_msb_host_config_mount_available NAME — true iff this sandbox has the
+# ADR-0030 host-config dir mounted at ACQ_HOST_CONFIG_GUEST_DIR and traversable
+# by the agent user. Existing sandboxes created before ADR-0030 lack this
+# create-time mount; for those, readonly:true files must fall back to the legacy
+# guest-copy path rather than rewriting startup argv to a non-existent path.
+_acq_msb_host_config_mount_available() {
+  local name="$1"
+  _acq_msb_cli exec "$name" -u agent -- sh -c \
+    "test -d '$ACQ_HOST_CONFIG_GUEST_DIR' && test -r '$ACQ_HOST_CONFIG_GUEST_DIR' && test -x '$ACQ_HOST_CONFIG_GUEST_DIR'" \
+    </dev/null >/dev/null 2>&1
+}
+
 # _acq_msb_stage_readonly_file NAME KITDIR GUESTPATH SRC — stage one trusted kit
 # code file onto the per-sandbox host-config dir so the guest sees it through the
 # READ-ONLY mount (ADR-0030 Mechanism 2), and echo the guest path it appears at.
@@ -1680,7 +1702,8 @@ _acq_msb_stage_readonly_file() {
     acq_debug "msb readonly-stage: could not create ${cfgdir}/${reldir}"
     return 1
   fi
-  chmod 700 "$cfgdir" 2>/dev/null || true
+  chmod 711 "$cfgdir" 2>/dev/null || true
+  chmod 755 "${cfgdir}/${reldir}" 2>/dev/null || true
   dest="${cfgdir}/${reldir}/${slug}.${crc}"
   cp -f "$src" "$dest" 2>/dev/null || { acq_debug "msb readonly-stage: cp failed: $src -> $dest"; return 1; }
   chmod 0555 "$dest" 2>/dev/null || true
@@ -3185,7 +3208,7 @@ EOF
   local _hcfg_dir _hcfg_host
   if _hcfg_dir=$(acq_host_config_dir msb "$name"); then
     mkdir -p "$_hcfg_dir" 2>/dev/null || true
-    chmod 700 "$_hcfg_dir" 2>/dev/null || true
+    chmod 711 "$_hcfg_dir" 2>/dev/null || true
     # --volume takes HOST:GUEST[:ro]; the host side is what native msb resolves on
     # this machine (host_path → drive form under MSYS), the guest side is POSIX
     # (ACQ_HOST_CONFIG_GUEST_DIR). See ADR-0029.
diff --git a/docs/adr/0030-host-authoritative-sandbox-config.md b/docs/adr/0030-host-authoritative-sandbox-config.md
index b89115cb..646d9392 100644
--- a/docs/adr/0030-host-authoritative-sandbox-config.md
+++ b/docs/adr/0030-host-authoritative-sandbox-config.md
@@ -166,6 +166,9 @@ Concretely, this ADR introduces two mechanisms and a staged migration.
   on sbx via the `:ro` positional the CLI already honors (confirmed: sbx enforces
   read-only on extra mounts; msb builds the `:ro` `--volume` flag itself). Host
   and guest path forms follow ADR-0029.
+- The mount root is traversable but not listable (`0711`) so the guest `agent`
+  user can open/execute read-only kit payloads below `kit-files/`, while flat
+  acq-internal keys stay host-private (`0600`).
 - In-guest consumers (kit orchestrators, the agent) **read** from
   `/var/lib/acq/host/…` but cannot write it. Guest-owned read-write state stays
   on separate rw paths.
@@ -186,7 +189,11 @@ Concretely, this ADR introduces two mechanisms and a staged migration.
   reads (e.g. `opencode.jsonc`) must stay a normal guest-writable drop.
 - A file **without** `readonly: true` is unchanged: copied into the guest and
   invoked by its guest path (full backward compatibility; no shipped kit changes
-  behavior until it opts in).
+  behavior until it opts in). If an existing sandbox predates the
+  `/var/lib/acq/host` mount, acq warns and falls back to this legacy guest-copy
+  behavior for `readonly: true` files too, rather than rewriting startup argv to a
+  path that does not exist; recreating the sandbox restores the tamper-resistant
+  read-only path.
 - Kits that genuinely must *compute* runtime state in-guest still may — they
   write their output to a guest-owned **rw** path (e.g. a per-sandbox catalog
   cache), which acq never treats as authoritative configuration. (This is
diff --git a/scripts/test-acq-lib.sh b/scripts/test-acq-lib.sh
index 8159d9b7..77055e6e 100644
--- a/scripts/test-acq-lib.sh
+++ b/scripts/test-acq-lib.sh
@@ -299,6 +299,11 @@ case "$_msb_sub" in
       *"getent passwd agent"*)
         [ -n "${STUB_AGENT_PASSWD_SHELL+x}" ] || exit 1
         printf '%s\n' "$STUB_AGENT_PASSWD_SHELL" ;;
+      # ADR-0030 host-config mount probe. Default PRESENT, matching a freshly
+      # created sandbox on this branch; STUB_HOST_CONFIG_MOUNT=0 models a legacy
+      # sandbox created before the /var/lib/acq/host:ro mount existed.
+      *"test -d"*"/var/lib/acq/host"*)
+        [ "${STUB_HOST_CONFIG_MOUNT:-1}" = "0" ] && exit 1 || exit 0 ;;
       # The host-side bash probe deciding the agent's passwd shell.
       # Default PRESENT (the default image ships bash); STUB_GUEST_BASH=0
       # models a bash-less base. MUST precede the generic command-v arm.
diff --git a/test/bats/79-msb-readonly-kit-files.bats b/test/bats/79-msb-readonly-kit-files.bats
index aa6f3566..e55a6ff2 100644
--- a/test/bats/79-msb-readonly-kit-files.bats
+++ b/test/bats/79-msb-readonly-kit-files.bats
@@ -96,8 +96,17 @@ SPEC
   '
   local log; log=$(cat "$CALLS")
   # The readonly file is staged into the per-sandbox host config dir kit-files/.
-  local staged; staged=$(find "$ACQ_PROVENANCE_DIR"/msb/rocodebox.*.config/kit-files -type f 2>/dev/null | head -n1)
+  local cfg staged
+  cfg=$(ls -d "$ACQ_PROVENANCE_DIR"/msb/rocodebox.*.config 2>/dev/null | head -n1)
+  [ -n "$cfg" ]
+  staged=$(find "$cfg/kit-files" -type f 2>/dev/null | head -n1)
   [ -n "$staged" ]
+  # The mount root must be traversable by the guest agent (0711) while flat
+  # acq-internal keys stay private; kit-files must be traversable and files
+  # executable/readable from the :ro mount.
+  assert_equal "$(stat -c '%a' "$cfg")" "711"
+  assert_equal "$(stat -c '%a' "$cfg/kit-files")" "755"
+  assert_equal "$(stat -c '%a' "$staged")" "555"
   # It is NOT msb-copied into the guest at its declared guest path.
   refute_regex "$log" 'msb copy .*:/home/agent/cfg/merge\.mjs'
   # The plain data file IS copied into the guest (unchanged behavior).
@@ -128,6 +137,27 @@ SPEC
   refute_regex "$body" '/home/agent/cfg/merge\.mjs'
 }
 
+@test "msb ro: legacy sandbox without the host-config mount falls back to the guest copy" {
+  local k="$STUBDIR/legacyro"; _ro_kit "$k"
+  : > "$CALLS"
+  run bash -c '
+    export ACQ_SECRET_STORE_DIR="'"$STUBDIR"'/legacyro-secrets" STUB_HOST_CONFIG_MOUNT=0
+    . "'"$REPO_ROOT"'/acq.backends/secret-store.sh"
+    . "'"$REPO_ROOT"'/acq.backends/kit-translate.sh"
+    . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    _acq_msb_apply_kit_dir legacyrobox "'"$k"'" 2>&1
+  '
+  assert_success
+  # No mount -> no :ro rewrite; preserve compatibility by copying the trusted
+  # file into the guest and invoking the original path. Users can recreate the
+  # sandbox to get tamper-resistant readonly startup code.
+  local log; log=$(cat "$CALLS")
+  assert_regex "$log" 'msb copy .*legacyrobox:/home/agent/cfg/merge\.mjs'
+  assert_regex "$log" 'node /home/agent/cfg/merge\.mjs'
+  refute_regex "$log" '/var/lib/acq/host/kit-files'
+  assert_output --partial 'has no readable ADR-0030 host-config mount'
+}
+
 @test "msb ro: the create-time host-config mount is read-only" {
   local k="$STUBDIR/romount"; _ro_kit "$k"
   : > "$CALLS"

From e9c618309a228728bddaf6ad4f08a5543ac8b214 Mon Sep 17 00:00:00 2001
From: Bret Mogilefsky <bret.mogilefsky@gsa.gov>
Date: Thu, 24 Sep 2026 04:27:28 +0000
Subject: [PATCH 09/12] fix(acq): address host-config review feedback

Clear stale host-side instance state before fresh msb provisioning, verify the host-config mount refuses guest-root writes before trusting readonly staged kit code, and tighten staged kit-file directory listability.

Co-authored-by: OpenCode [gpt_5_5_default_v2] <bret.mogilefsky@gsa.gov>
---
 acq.backends/common.sh                        | 26 +++++++-
 acq.backends/msb.sh                           | 22 ++++---
 .../0030-host-authoritative-sandbox-config.md | 40 +++++++++---
 scripts/test-acq-lib.sh                       | 10 ++-
 test/bats/72-msb-agent-user.bats              | 62 +++++++++++++++++--
 test/bats/79-msb-readonly-kit-files.bats      | 22 ++++++-
 6 files changed, 155 insertions(+), 27 deletions(-)

diff --git a/acq.backends/common.sh b/acq.backends/common.sh
index e98c3d7a..bdd024d2 100644
--- a/acq.backends/common.sh
+++ b/acq.backends/common.sh
@@ -1535,6 +1535,8 @@ acq_cli_kits_load() {
 # read-only mount root to execute `kit-files/...` staged code, but should not be
 # able to list acq-internal key names. Content-bearing flat keys remain 0600 on
 # the host; readonly kit code is staged under kit-files/ with executable perms.
+# The traversable dirs intentionally make known kit-file paths host-readable too;
+# only non-sensitive trusted code may be staged there.
 #
 # KEY charset is restricted ([A-Za-z0-9._-], no slash) so a key can never escape
 # the config dir; callers pass fixed literals (agent, workspace, ssh-auth-sock,
@@ -1588,7 +1590,7 @@ acq_host_config_write() {
   chmod 711 "$dir" 2>/dev/null || true
   file="$dir/$key"
   local tmp="${file}.tmp.$$"
-  printf '%s' "$value" > "$tmp" 2>/dev/null || {
+  ( umask 077; printf '%s' "$value" > "$tmp" ) 2>/dev/null || {
     acq_debug "host-config: write failed: $tmp"; rm -f "$tmp" 2>/dev/null; return 1; }
   chmod 600 "$tmp" 2>/dev/null || true
   mv -f "$tmp" "$file" 2>/dev/null || {
@@ -1639,6 +1641,10 @@ acq_host_config_append() {
   fi
   chmod 711 "$dir" 2>/dev/null || true
   file="$dir/$key"
+  if [ ! -f "$file" ]; then
+    ( umask 077; : > "$file" ) 2>/dev/null || {
+      acq_debug "host-config: create failed: $file"; return 1; }
+  fi
   printf '%s\n' "$value" >> "$file" 2>/dev/null || {
     acq_debug "host-config: append failed: $file"; return 1; }
   chmod 600 "$file" 2>/dev/null || true
@@ -1657,6 +1663,24 @@ acq_host_config_clear() {
   return 0
 }
 
+# Remove per-sandbox instance keys before provisioning a freshly-created sandbox.
+# The host config dir is keyed by sandbox name, so a sandbox removed outside acq
+# can leave stale state behind for a later same-named sandbox. Clear run-once
+# gates and conditionally-written content keys before provision rewrites the
+# current instance's authoritative values.
+# Usage: acq_host_config_clear_instance_state BACKEND NAME
+acq_host_config_clear_instance_state() {
+  local backend="${1:-}" name="${2:-}"
+  [ -n "$backend" ] && [ -n "$name" ] || return 0
+  local dir
+  dir=$(acq_host_config_dir "$backend" "$name") || return 0
+  case "$dir" in ""|/|/*/) return 0 ;; esac
+  rm -f "$dir"/install-* "$dir"/agent-installed-* \
+        "$dir"/agent-user-ready "$dir"/oci-ready \
+        "$dir"/workspace "$dir"/ssh-auth-sock 2>/dev/null || true
+  return 0
+}
+
 # Remove a sandbox's entire host config dir (called from terminate). Best-effort.
 # Usage: acq_host_config_remove BACKEND NAME
 acq_host_config_remove() {
diff --git a/acq.backends/msb.sh b/acq.backends/msb.sh
index 0b030b46..92219010 100644
--- a/acq.backends/msb.sh
+++ b/acq.backends/msb.sh
@@ -1616,7 +1616,7 @@ EOF
     fi
     if { [ "$_readonly" != "true" ] || [ "$_hcfg_mount_ok" -ne 1 ]; } && [ -n "$src" ] && [ -f "$src" ]; then
       if [ "$_readonly" = "true" ]; then
-        echo "acq(msb): warning: sandbox '$name' has no readable ADR-0030 host-config mount;" \
+        echo "acq(msb): warning: sandbox '$name' has no readable or read-only ADR-0030 host-config mount;" \
              "copying readonly kit file '$path' into the guest for compatibility. Recreate the sandbox to get tamper-resistant readonly startup code." >&2
       fi
       _acq_msb_copy_file_verified "$name" "$src" "$path" "$mode" || {
@@ -1668,15 +1668,19 @@ _acq_msb_reset_kit_env() {
 }
 
 # _acq_msb_host_config_mount_available NAME — true iff this sandbox has the
-# ADR-0030 host-config dir mounted at ACQ_HOST_CONFIG_GUEST_DIR and traversable
-# by the agent user. Existing sandboxes created before ADR-0030 lack this
-# create-time mount; for those, readonly:true files must fall back to the legacy
-# guest-copy path rather than rewriting startup argv to a non-existent path.
+# ADR-0030 host-config dir mounted at ACQ_HOST_CONFIG_GUEST_DIR, traversable by
+# the agent user, and still write-refusing under guest root. Existing sandboxes
+# created before ADR-0030 lack this create-time mount; for those, readonly:true
+# files must fall back to the legacy guest-copy path rather than rewriting startup
+# argv to a non-existent or writable path.
 _acq_msb_host_config_mount_available() {
   local name="$1"
   _acq_msb_cli exec "$name" -u agent -- sh -c \
     "test -d '$ACQ_HOST_CONFIG_GUEST_DIR' && test -r '$ACQ_HOST_CONFIG_GUEST_DIR' && test -x '$ACQ_HOST_CONFIG_GUEST_DIR'" \
-    </dev/null >/dev/null 2>&1
+    </dev/null >/dev/null 2>&1 || return 1
+  _acq_msb_cli exec "$name" -u 0 -- sh -c \
+    '_dir=$1; _tmp="$_dir/.acq-ro-probe.$$"; if : > "$_tmp" 2>/dev/null; then rm -f "$_tmp" 2>/dev/null; exit 1; fi; exit 0' \
+    sh "$ACQ_HOST_CONFIG_GUEST_DIR" </dev/null >/dev/null 2>&1
 }
 
 # _acq_msb_stage_readonly_file NAME KITDIR GUESTPATH SRC — stage one trusted kit
@@ -1703,7 +1707,7 @@ _acq_msb_stage_readonly_file() {
     return 1
   fi
   chmod 711 "$cfgdir" 2>/dev/null || true
-  chmod 755 "${cfgdir}/${reldir}" 2>/dev/null || true
+  chmod 711 "${cfgdir}/${reldir}" 2>/dev/null || true
   dest="${cfgdir}/${reldir}/${slug}.${crc}"
   cp -f "$src" "$dest" 2>/dev/null || { acq_debug "msb readonly-stage: cp failed: $src -> $dest"; return 1; }
   chmod 0555 "$dest" 2>/dev/null || true
@@ -3331,6 +3335,10 @@ EOF
   acq_spin_stop "Waiting for the sandbox to finish booting"
   acq_debug "msb provision: exec-ready OK ($name)"
 
+  # Fresh create: stale host-side state from a same-named sandbox removed outside
+  # acq must not carry over into this new instance.
+  acq_host_config_clear_instance_state msb "$name"
+
   # Verify the kits' runtime prerequisites are present in the base image
   # (node/git/curl/update-ca-certificates). We do NOT install them: the kit
   # net-rules lock egress to the kits' own hosts, so a package mirror is
diff --git a/docs/adr/0030-host-authoritative-sandbox-config.md b/docs/adr/0030-host-authoritative-sandbox-config.md
index 646d9392..dd8fd2db 100644
--- a/docs/adr/0030-host-authoritative-sandbox-config.md
+++ b/docs/adr/0030-host-authoritative-sandbox-config.md
@@ -56,9 +56,9 @@ acq currently violates the safe form of this in two ways:
    those **guest-resident** files. A sudo-capable agent can overwrite a startup
    script or normalizer *between* provision and the next restart; the heal then
    executes the tampered code. This is the general form of the
-   "provider-facts file is root-owned, therefore safe" error flagged in the
-   `agentic-coding-patterns` PR #423 review — root-ownership is not the barrier
-   it appears to be.
+   "provider-facts file is root-owned, therefore safe" error flagged during
+   review of the `agentic-coding-patterns` neutral model-provider discovery work
+   — root-ownership is not the barrier it appears to be.
 
 A concrete instance motivating this ADR: the neutral model-provider discovery
 design (patterns ADR 0003) originally had each provider kit **write** a facts
@@ -163,12 +163,22 @@ Concretely, this ADR introduces two mechanisms and a staged migration.
   kit code on the host.
 - acq mounts that directory into the guest **read-only** at a well-known path:
   `/var/lib/acq/host/` (`:ro`). On msb via `--volume <hostdir>:/var/lib/acq/host:ro`;
-  on sbx via the `:ro` positional the CLI already honors (confirmed: sbx enforces
-  read-only on extra mounts; msb builds the `:ro` `--volume` flag itself). Host
-  and guest path forms follow ADR-0029.
-- The mount root is traversable but not listable (`0711`) so the guest `agent`
-  user can open/execute read-only kit payloads below `kit-files/`, while flat
-  acq-internal keys stay host-private (`0600`).
+  on sbx via the `:ro` positional the CLI already honors. This relies on backend
+  mount/export semantics, not Unix ownership inside the guest: sbx already
+  enforces read-only extra mounts, and msb 0.7.2 was live-verified to export the
+  virtiofs mount read-only even when guest root can make the guest-visible mount
+  flag appear `rw`. acq also probes that guest root cannot create a file in the
+  mount before it rewrites `readonly: true` startup code to that path; if the
+  probe fails, acq falls back to the legacy guest-copy path and warns. If a future
+  msb changes `--volume ...:ro` parsing or enforcement, acq must raise or gate
+  its minimum msb version before relying on ADR-0030. Host and guest path forms
+  follow ADR-0029.
+- The mount root and `kit-files/` subtree are traversable but not listable (`0711`)
+  so the guest `agent` user can open/execute known read-only kit payload paths,
+  while flat acq-internal keys stay host-private (`0600`). This is also a
+  host-side visibility relaxation: any local host user who can guess a staged
+  `kit-files/<slug>.<crc>` path can read the `0555` payload, so only non-sensitive
+  trusted code from public/pinned kits belongs there.
 - In-guest consumers (kit orchestrators, the agent) **read** from
   `/var/lib/acq/host/…` but cannot write it. Guest-owned read-write state stays
   on separate rw paths.
@@ -225,7 +235,11 @@ behavior:
    from there; stop reading the guest marker.
 5. **Presence gates** (`install-*`, `agent-installed-*`, `agent-user-ready`,
    `oci-ready`): move to the host config dir so a guest cannot forge them to
-   suppress provisioning. (Lower severity; last.)
+   suppress provisioning. Because the host config dir is keyed by sandbox name,
+   clear these gate keys, plus conditionally-written instance keys such as
+   `workspace` and `ssh-auth-sock`, at the start of a fresh provision so a
+   same-named sandbox recreated after an out-of-band `msb rm` cannot inherit stale
+   "already done" markers or session paths. (Lower severity; last.)
 
 ## Threat model and flows
 
@@ -307,6 +321,12 @@ sequenceDiagram
   script paths.
 - The current marker writes are best-effort; the migration must keep that
   fail-soft posture rather than converting a state-dir error into a hard abort.
+- Host-side state can outlive a sandbox if it is removed outside acq or cleanup
+  fails. Fresh provision must clear run-once gate keys before gated setup starts
+  so the marker means "this sandbox instance completed this step," not "some
+  same-named sandbox once completed this step," and must clear conditionally
+  written instance keys before rewriting only the values that apply to the new
+  sandbox.
 
 ### Neutral
 
diff --git a/scripts/test-acq-lib.sh b/scripts/test-acq-lib.sh
index 77055e6e..8c8e72de 100644
--- a/scripts/test-acq-lib.sh
+++ b/scripts/test-acq-lib.sh
@@ -299,11 +299,15 @@ case "$_msb_sub" in
       *"getent passwd agent"*)
         [ -n "${STUB_AGENT_PASSWD_SHELL+x}" ] || exit 1
         printf '%s\n' "$STUB_AGENT_PASSWD_SHELL" ;;
-      # ADR-0030 host-config mount probe. Default PRESENT, matching a freshly
-      # created sandbox on this branch; STUB_HOST_CONFIG_MOUNT=0 models a legacy
-      # sandbox created before the /var/lib/acq/host:ro mount existed.
+      # ADR-0030 host-config mount probes. Default PRESENT+READONLY, matching a
+      # freshly created sandbox on this branch; STUB_HOST_CONFIG_MOUNT=0 models a
+      # legacy sandbox created before the /var/lib/acq/host:ro mount existed, and
+      # STUB_HOST_CONFIG_WRITABLE=1 models a backend that accepts but does not
+      # enforce :ro.
       *"test -d"*"/var/lib/acq/host"*)
         [ "${STUB_HOST_CONFIG_MOUNT:-1}" = "0" ] && exit 1 || exit 0 ;;
+      *".acq-ro-probe"*)
+        [ "${STUB_HOST_CONFIG_WRITABLE:-0}" = "1" ] && exit 1 || exit 0 ;;
       # The host-side bash probe deciding the agent's passwd shell.
       # Default PRESENT (the default image ships bash); STUB_GUEST_BASH=0
       # models a bash-less base. MUST precede the generic command-v arm.
diff --git a/test/bats/72-msb-agent-user.bats b/test/bats/72-msb-agent-user.bats
index fe555c1f..ea1cc238 100644
--- a/test/bats/72-msb-agent-user.bats
+++ b/test/bats/72-msb-agent-user.bats
@@ -258,11 +258,20 @@ _attach() { # PRE_SNIPPET NAME
   refute_regex "$log" 'rm -rf /'
 }
 
-@test "msb: the OCI setup is skipped when the ready marker already exists" {
-  _provision ocirdybox shell 'export ACQ_SECRET_STORE_DIR="'"$STUBDIR"'/ociready-secrets" STUB_OCI_READY=1'
+@test "msb: OCI setup is skipped on heal when the ready marker already exists" {
+  : > "$CALLS"
+  run bash -c '
+    export ACQ_SECRET_STORE_DIR="'"$STUBDIR"'/ociready-secrets" STUB_OCI_READY=1
+    . "'"$REPO_ROOT"'/acq.backends/secret-store.sh"
+    . "'"$REPO_ROOT"'/acq.backends/kit-translate.sh"
+    . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    seed_host_config_gates msb ocirdybox
+    _acq_msb_ensure_oci ocirdybox
+  '
+  assert_success
   local log; log=$(cat "$CALLS")
-  # ADR-0030: the oci-ready gate is a host config key now, seeded by
-  # seed_host_config_gates from STUB_OCI_READY; a hit skips the setup block.
+  # ADR-0030: the oci-ready gate still skips idempotent OCI setup during a heal;
+  # fresh provision clears stale gates before this point.
   assert_equal "$(cat "$ACQ_PROVENANCE_DIR"/msb/ocirdybox.*.config/oci-ready 2>/dev/null)" "1"
   refute_regex "$log" 'PODMAN_PKGS='
   refute_regex "$log" '/usr/local/bin/docker'
@@ -275,6 +284,51 @@ _attach() { # PRE_SNIPPET NAME
   refute_regex "$log" 'oci-ready'
 }
 
+@test "msb: fresh provision clears stale host-side instance state" {
+  local k="$STUBDIR/freshgate-kit"; mkdir -p "$k"
+  cat >"$k/spec.yaml" <<'SPEC'
+schemaVersion: "hybrid/v1"
+kind: mixin
+name: freshgate-kit
+displayName: Fresh Gate Kit
+description: install marker regression kit
+commands:
+  - phase: install
+    user: "0"
+    command:
+      - sh
+      - -c
+      - printf freshgate-kit-install
+SPEC
+  run bash -c '
+    . "'"$REPO_ROOT"'/acq.backends/common.sh"
+    marker="install-$(printf "%s\0" sh -c "printf freshgate-kit-install" | cksum | cut -d" " -f1)"
+    acq_host_config_write msb freshgatebox agent-user-ready 1
+    acq_host_config_write msb freshgatebox oci-ready 1
+    acq_host_config_write msb freshgatebox agent-installed-opencode 1
+    acq_host_config_write msb freshgatebox "$marker" 1
+    acq_host_config_write msb freshgatebox workspace /stale/workspace
+    acq_host_config_write msb freshgatebox ssh-auth-sock /stale/agent.sock
+  '
+  assert_success
+
+  _provision freshgatebox opencode 'export ACQ_SECRET_STORE_DIR="'"$STUBDIR"'/freshgate-secrets"' "$k"
+  local log; log=$(cat "$CALLS")
+  assert_regex "$log" 'test -w /home/agent'
+  assert_regex "$log" 'PODMAN_PKGS='
+  assert_regex "$log" 'npm install -g --no-fund --no-audit opencode-ai'
+  assert_regex "$log" 'printf freshgate-kit-install'
+
+  run bash -c 'ls "$1"/msb/freshgatebox.*.config/install-* 2>/dev/null' _ "$ACQ_PROVENANCE_DIR"
+  assert_output --partial 'install-'
+  run bash -c 'cat "$1"/msb/freshgatebox.*.config/workspace 2>/dev/null' _ "$ACQ_PROVENANCE_DIR"
+  refute_output '/stale/workspace'
+  assert_output --partial '/tmp'
+  run bash -c 'cat "$1"/msb/freshgatebox.*.config/ssh-auth-sock 2>/dev/null' _ "$ACQ_PROVENANCE_DIR"
+  refute_output '/stale/agent.sock'
+  assert_output --partial '/home/agent/.acq/ssh-agent.sock'
+}
+
 @test "msb: an OCI setup failure is fail-soft (rc 0, warns, marker not touched)" {
   _provision ocifailbox shell 'export ACQ_SECRET_STORE_DIR="'"$STUBDIR"'/ocifail-secrets" STUB_OCI_SETUP_FAIL=1'
   assert_success
diff --git a/test/bats/79-msb-readonly-kit-files.bats b/test/bats/79-msb-readonly-kit-files.bats
index e55a6ff2..e02f6742 100644
--- a/test/bats/79-msb-readonly-kit-files.bats
+++ b/test/bats/79-msb-readonly-kit-files.bats
@@ -105,7 +105,7 @@ SPEC
   # acq-internal keys stay private; kit-files must be traversable and files
   # executable/readable from the :ro mount.
   assert_equal "$(stat -c '%a' "$cfg")" "711"
-  assert_equal "$(stat -c '%a' "$cfg/kit-files")" "755"
+  assert_equal "$(stat -c '%a' "$cfg/kit-files")" "711"
   assert_equal "$(stat -c '%a' "$staged")" "555"
   # It is NOT msb-copied into the guest at its declared guest path.
   refute_regex "$log" 'msb copy .*:/home/agent/cfg/merge\.mjs'
@@ -155,7 +155,25 @@ SPEC
   assert_regex "$log" 'msb copy .*legacyrobox:/home/agent/cfg/merge\.mjs'
   assert_regex "$log" 'node /home/agent/cfg/merge\.mjs'
   refute_regex "$log" '/var/lib/acq/host/kit-files'
-  assert_output --partial 'has no readable ADR-0030 host-config mount'
+  assert_output --partial 'has no readable or read-only ADR-0030 host-config mount'
+}
+
+@test "msb ro: writable host-config mount falls back to the guest copy" {
+  local k="$STUBDIR/writablero"; _ro_kit "$k"
+  : > "$CALLS"
+  run bash -c '
+    export ACQ_SECRET_STORE_DIR="'"$STUBDIR"'/writablero-secrets" STUB_HOST_CONFIG_WRITABLE=1
+    . "'"$REPO_ROOT"'/acq.backends/secret-store.sh"
+    . "'"$REPO_ROOT"'/acq.backends/kit-translate.sh"
+    . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    _acq_msb_apply_kit_dir writablerobox "'"$k"'" 2>&1
+  '
+  assert_success
+  local log; log=$(cat "$CALLS")
+  assert_regex "$log" 'msb copy .*writablerobox:/home/agent/cfg/merge\.mjs'
+  assert_regex "$log" 'node /home/agent/cfg/merge\.mjs'
+  refute_regex "$log" '/var/lib/acq/host/kit-files'
+  assert_output --partial 'has no readable or read-only ADR-0030 host-config mount'
 }
 
 @test "msb ro: the create-time host-config mount is read-only" {

From e30d909e24e32a0a71f907fbfe30786f898e4cec Mon Sep 17 00:00:00 2001
From: Bret Mogilefsky <bret.mogilefsky@gsa.gov>
Date: Thu, 24 Sep 2026 04:44:05 +0000
Subject: [PATCH 10/12] test(msb): make stale state test independent of ssh
 agent

The fresh-provision stale-state regression must prove a stale ssh-auth-sock value is cleared, but it should not require the CI host to expose SSH_AUTH_SOCK and create a replacement value.

Co-authored-by: OpenCode [gpt_5_5_default_v2] <bret.mogilefsky@gsa.gov>
---
 test/bats/72-msb-agent-user.bats | 1 -
 1 file changed, 1 deletion(-)

diff --git a/test/bats/72-msb-agent-user.bats b/test/bats/72-msb-agent-user.bats
index ea1cc238..bdd87bc7 100644
--- a/test/bats/72-msb-agent-user.bats
+++ b/test/bats/72-msb-agent-user.bats
@@ -326,7 +326,6 @@ SPEC
   assert_output --partial '/tmp'
   run bash -c 'cat "$1"/msb/freshgatebox.*.config/ssh-auth-sock 2>/dev/null' _ "$ACQ_PROVENANCE_DIR"
   refute_output '/stale/agent.sock'
-  assert_output --partial '/home/agent/.acq/ssh-agent.sock'
 }
 
 @test "msb: an OCI setup failure is fail-soft (rc 0, warns, marker not touched)" {

From 9d0f86309b9e1a7ef0d6d43a744ab79d00671e77 Mon Sep 17 00:00:00 2001
From: Bret Mogilefsky <bret.mogilefsky@gsa.gov>
Date: Fri, 2 Oct 2026 09:10:22 +0000
Subject: [PATCH 11/12] docs(adr): renumber host-authoritative config adr to
 0035

ADR-0030 was double-claimed. GSA-TTS/agentic-coding-quickstart#474 keeps ADR-0030 because patterns main already cites it for the devenv ADR.

Co-authored-by: OpenCode [gpt-5.5] <bret.mogilefsky@gsa.gov>
---
 acq.backends/common.sh                        |  2 +-
 acq.backends/kit-translate.sh                 |  2 +-
 acq.backends/msb.sh                           | 54 +++++++++----------
 acq.backends/sbx.sh                           |  2 +-
 docs/KNOWN_FAILURE_MODES.md                   |  2 +-
 docs/adr/0011-msb-backend-and-neutral-kits.md |  4 +-
 ...0035-host-authoritative-sandbox-config.md} |  4 +-
 scripts/test-acq-lib.sh                       | 10 ++--
 test/bats/115-ssh-agent-forward.bats          |  4 +-
 test/bats/71b-msb-secret-store-backends.bats  |  2 +-
 test/bats/72-msb-agent-user.bats              | 12 ++---
 test/bats/73-msb-kits-startup.bats            |  4 +-
 test/bats/78-msb-kit-env.bats                 |  4 +-
 test/bats/79-msb-readonly-kit-files.bats      |  6 +--
 14 files changed, 56 insertions(+), 56 deletions(-)
 rename docs/adr/{0030-host-authoritative-sandbox-config.md => 0035-host-authoritative-sandbox-config.md} (99%)

diff --git a/acq.backends/common.sh b/acq.backends/common.sh
index 8caa915d..f7066d6e 100644
--- a/acq.backends/common.sh
+++ b/acq.backends/common.sh
@@ -1542,7 +1542,7 @@ acq_cli_kits_load() {
 }
 
 # ============================================================================
-# Host-authoritative per-sandbox config store (ADR-0030)
+# Host-authoritative per-sandbox config store (ADR-0035)
 # ============================================================================
 # acq must NOT rely on guest-generated or guest-tamperable state to configure a
 # sandbox: the in-sandbox agent has passwordless sudo, so a root-owned GUEST path
diff --git a/acq.backends/kit-translate.sh b/acq.backends/kit-translate.sh
index 2260acfc..902c755e 100644
--- a/acq.backends/kit-translate.sh
+++ b/acq.backends/kit-translate.sh
@@ -492,7 +492,7 @@ _kit_vol_validate() {
 # readonly is "true" iff the entry declares `readonly: true` — a file whose
 # BYTES are trusted CODE acq must execute from a host-authoritative read-only
 # mount rather than a guest-writable copy a passwordless-sudo agent could tamper
-# (ADR-0030). Empty (treated as false) otherwise, so existing 4-field consumers
+# (ADR-0035). Empty (treated as false) otherwise, so existing 4-field consumers
 # and unflagged files are unaffected.
 kit_spec_files() {
   local spec="$1"
diff --git a/acq.backends/msb.sh b/acq.backends/msb.sh
index cf0ebf51..ee2a83f4 100644
--- a/acq.backends/msb.sh
+++ b/acq.backends/msb.sh
@@ -74,7 +74,7 @@ if ! command -v acq_is_known_agent >/dev/null 2>&1; then
   . "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/agents.sh"
 fi
 
-# Host-authoritative config store (ADR-0030). Normally defined in common.sh
+# Host-authoritative config store (ADR-0035). Normally defined in common.sh
 # (sourced before this adapter by acq_resolve_backend), but the offline session
 # paths (attach/run/shell) are exercised in tests that source THIS file directly
 # without common.sh. Guard-source it so acq_host_config_* are always defined when
@@ -658,7 +658,7 @@ ACQ_MSB_CLONES_DIR="${ACQ_MSB_CLONES_DIR:-${ACQ_STATE_DIR}/clones}"
 # always defined even if provision is not the entry point.
 _ACQ_MSB_STARTUP_STAGE_FILES=()
 _ACQ_MSB_STARTUP_STAGED=""
-# Per-kit read-only-file rewrite table (ADR-0030 Mechanism 2): parallel arrays
+# Per-kit read-only-file rewrite table (ADR-0035 Mechanism 2): parallel arrays
 # mapping a kit-declared guest path (FROM) to the path the same bytes appear at
 # on the read-only host-config mount (TO). _acq_msb_apply_kit_dir populates these
 # from `readonly: true` files[] entries; _acq_msb_run_commands / the staged
@@ -1117,7 +1117,7 @@ _acq_msb_wait_for_exec_ready() {
 #   1) INSTALL PHASE stays exec-based. install commands are run-once, gated by a
 #      host-authoritative marker keyed on a hash of the argv
 #      (_acq_msb_exec_install: acq_host_config_has/_write "install-<cksum>", held
-#      on the host per ADR-0030 so a passwordless-sudo guest cannot forge it to
+#      on the host per ADR-0035 so a passwordless-sudo guest cannot forge it to
 #      suppress the step). A create-time script re-runs on every restart by
 #      design — the OPPOSITE of run-once — so
 #      folding install into the startup script would break its idempotency
@@ -1578,7 +1578,7 @@ EOF
   local path mode phase source _readonly src _i
   # Reset the per-kit readonly-file rewrite table (guest path -> :ro guest path)
   # before this kit's files are processed; _acq_msb_run_commands consults it to
-  # rewrite startup argv so trusted code runs from the read-only mount (ADR-0030).
+  # rewrite startup argv so trusted code runs from the read-only mount (ADR-0035).
   _ACQ_MSB_RO_REWRITE_FROM=()
   _ACQ_MSB_RO_REWRITE_TO=()
   local _hcfg_mount_ok=0
@@ -1598,7 +1598,7 @@ EOF
       src="${kitdir}/${source}"
     fi
     if [ "$_readonly" = "true" ] && [ -n "$src" ] && [ -f "$src" ] && [ "$_hcfg_mount_ok" -eq 1 ]; then
-      # Trusted CODE (ADR-0030 Mechanism 2): stage it on the per-sandbox
+      # Trusted CODE (ADR-0035 Mechanism 2): stage it on the per-sandbox
       # host-config dir so the guest sees it through the READ-ONLY mount and a
       # passwordless-sudo agent cannot rewrite it. Do NOT copy it into the
       # guest's writable filesystem; record a rewrite so the invoking startup
@@ -1616,7 +1616,7 @@ EOF
     fi
     if { [ "$_readonly" != "true" ] || [ "$_hcfg_mount_ok" -ne 1 ]; } && [ -n "$src" ] && [ -f "$src" ]; then
       if [ "$_readonly" = "true" ]; then
-        echo "acq(msb): warning: sandbox '$name' has no readable or read-only ADR-0030 host-config mount;" \
+        echo "acq(msb): warning: sandbox '$name' has no readable or read-only ADR-0035 host-config mount;" \
              "copying readonly kit file '$path' into the guest for compatibility. Recreate the sandbox to get tamper-resistant readonly startup code." >&2
       fi
       _acq_msb_copy_file_verified "$name" "$src" "$path" "$mode" || {
@@ -1631,7 +1631,7 @@ EOF
   #    the kit's own commands (step 3) covers provisioning only; the block exists
   #    for agent-runtime config (see ADR-0011: OPENCODE_CONFIG-style vars), so
   #    the validated entries are also persisted to the HOST config store
-  #    (ADR-0030) that run/attach/shell read back and replay as `-e` flags — the
+  #    (ADR-0035) that run/attach/shell read back and replay as `-e` flags — the
   #    same role the guest /var/lib/acq/kit-env marker had, but host-authoritative
   #    so a passwordless-sudo agent cannot inject env into the agent process.
   local _kit_env=()
@@ -1662,15 +1662,15 @@ EOF
 # single-kit `acq kit apply` verb deliberately does NOT reset: a mid-life add
 # is additive, and replay's last-value-wins handles its overrides. Best-effort:
 # a failed reset degrades to the previous stale-retention behavior, never
-# aborts the apply. Host-authoritative (ADR-0030).
+# aborts the apply. Host-authoritative (ADR-0035).
 _acq_msb_reset_kit_env() {
   acq_host_config_clear msb "$1" kit-env
 }
 
 # _acq_msb_host_config_mount_available NAME — true iff this sandbox has the
-# ADR-0030 host-config dir mounted at ACQ_HOST_CONFIG_GUEST_DIR, traversable by
+# ADR-0035 host-config dir mounted at ACQ_HOST_CONFIG_GUEST_DIR, traversable by
 # the agent user, and still write-refusing under guest root. Existing sandboxes
-# created before ADR-0030 lack this create-time mount; for those, readonly:true
+# created before ADR-0035 lack this create-time mount; for those, readonly:true
 # files must fall back to the legacy guest-copy path rather than rewriting startup
 # argv to a non-existent or writable path.
 _acq_msb_host_config_mount_available() {
@@ -1685,7 +1685,7 @@ _acq_msb_host_config_mount_available() {
 
 # _acq_msb_stage_readonly_file NAME KITDIR GUESTPATH SRC — stage one trusted kit
 # code file onto the per-sandbox host-config dir so the guest sees it through the
-# READ-ONLY mount (ADR-0030 Mechanism 2), and echo the guest path it appears at.
+# READ-ONLY mount (ADR-0035 Mechanism 2), and echo the guest path it appears at.
 # Returns non-zero (and echoes nothing) on failure. The file is placed under a
 # `kit-files/<pathslug>.<crc>` subtree of the host-config dir (a direct
 # filesystem write, NOT acq_host_config_write, whose flat KEY charset forbids the
@@ -1716,7 +1716,7 @@ _acq_msb_stage_readonly_file() {
 }
 
 # _acq_msb_ro_rewrite_token TOKEN — echo TOKEN, or its read-only-mount equivalent
-# when TOKEN exactly equals a staged readonly file's declared guest path (ADR-0030
+# when TOKEN exactly equals a staged readonly file's declared guest path (ADR-0035
 # Mechanism 2). Whole-token match only (never substring), so a --flag value that
 # merely mentions the path is untouched. Bash 3.2 safe (parallel-array scan).
 _acq_msb_ro_rewrite_token() {
@@ -1874,7 +1874,7 @@ EOF
         ;;
       "__END__")
         reading=0
-        # ADR-0030 Mechanism 2: rewrite any argv token that names a readonly
+        # ADR-0035 Mechanism 2: rewrite any argv token that names a readonly
         # (trusted-code) kit file to its read-only-mount path, so startup runs the
         # :ro copy, not a guest-writable one. No-op when the rewrite table is
         # empty (the common case: no kit declared readonly files).
@@ -1995,7 +1995,7 @@ _acq_msb_exec_flags_into() {
 # _acq_msb_exec_install NAME USER UFLAG_ARRVAR EFLAG_ARRVAR -- ARGV... — run an
 # install-phase command, gated by a per-command marker (hash of argv) so it runs
 # once per sandbox even across re-applies. The marker is a key in the
-# host-authoritative config store (ADR-0030), so a passwordless-sudo guest cannot
+# host-authoritative config store (ADR-0035), so a passwordless-sudo guest cannot
 # forge it to suppress the install step.
 _acq_msb_exec_install() {
   local _name="$1" _user="$2" _uflagn="$3" _eflagn="$4"
@@ -2009,7 +2009,7 @@ _acq_msb_exec_install() {
   eval "_ef=(\${${_eflagn}[@]+\"\${${_eflagn}[@]}\"})"
 
   local marker
-  # Host-authoritative run-once gate (ADR-0030): a presence key in the host config
+  # Host-authoritative run-once gate (ADR-0035): a presence key in the host config
   # store, keyed by the command's cksum, instead of a guest `touch`/`test -f` a
   # passwordless-sudo agent could forge to SUPPRESS this install step.
   marker="install-$(printf '%s\0' "$@" | cksum | cut -d' ' -f1)"
@@ -2256,7 +2256,7 @@ _acq_msb_startup_body_into() {
   local _kit_env=()
   _acq_msb_collect_kit_env_into _kit_env "$_spec"
 
-  # ADR-0030 Mechanism 2: build this spec's readonly-file rewrite table so the
+  # ADR-0035 Mechanism 2: build this spec's readonly-file rewrite table so the
   # staged --script-path body (like the exec path) invokes trusted code from the
   # :ro mount. Staging runs at create-flag assembly, before _acq_msb_apply_kit_dir
   # populates the module-level table, so derive a LOCAL table from the same
@@ -3287,7 +3287,7 @@ EOF
   _acq_msb_vsock_flags_into _vsock_flags
   [ "${#_vsock_flags[@]}" -gt 0 ] && create_flags+=("${_vsock_flags[@]}")
 
-  # Host-authoritative config mount (ADR-0030). Mount this sandbox's host config
+  # Host-authoritative config mount (ADR-0035). Mount this sandbox's host config
   # dir into the guest READ-ONLY at ACQ_HOST_CONFIG_GUEST_DIR. acq writes the
   # sandbox's trusted config there on the HOST (agent, workspace, ssh-auth-sock,
   # kit-env, gate markers); the guest can read but — because the mount is
@@ -3480,7 +3480,7 @@ EOF
   # Record which agent this sandbox runs, so acq_backend_attach (which only gets
   # the sandbox name) knows what to launch — the sbx equivalent is that
   # `sbx run --name` re-launches the agent baked in at create. Written to the
-  # HOST-authoritative config store (ADR-0030), not a guest file: a
+  # HOST-authoritative config store (ADR-0035), not a guest file: a
   # passwordless-sudo agent could otherwise rewrite a guest marker and change
   # which binary acq relaunches. The value is still charset-checked defensively.
   case "$agent" in
@@ -3490,7 +3490,7 @@ EOF
 
   # Record the guest workspace path too. attach only gets the sandbox NAME, so it
   # cannot recompute the host→guest mapping (which now mirrors the host path);
-  # persist it (host-side, ADR-0030) so a name-only re-attach cds into the right
+  # persist it (host-side, ADR-0035) so a name-only re-attach cds into the right
   # place. The path was validated as an existing host dir above; the charset
   # guard is kept for defense-in-depth even though the value no longer enters a
   # guest sh -c string.
@@ -3732,7 +3732,7 @@ _acq_msb_install_agent() {
 # _acq_msb_exec_command) with HOME exported.
 _acq_msb_ensure_agent_user() {
   local name="$1"
-  # Host-authoritative run-once gate (ADR-0030): the user/sudoers setup is gated
+  # Host-authoritative run-once gate (ADR-0035): the user/sudoers setup is gated
   # on a host config key, not a guest marker a passwordless-sudo agent could
   # pre-create to SKIP the setup.
   local marker="agent-user-ready"
@@ -4041,7 +4041,7 @@ _acq_msb_start_ssh_agent_bridge() {
 
   # Record the guest sock path so attach/exec/start can resolve SSH_AUTH_SOCK
   # even when no provision flag is set. Only written when forwarding is active.
-  # Host-authoritative (ADR-0030): held on the host, not a guest marker a
+  # Host-authoritative (ADR-0035): held on the host, not a guest marker a
   # sudo agent could repoint. $_sock is acq's own constant.
   acq_host_config_write msb "$name" ssh-auth-sock "$_sock" || true
   acq_debug "msb: ssh-agent bridge started at $_sock (vsock port $_port) in $name"
@@ -4124,7 +4124,7 @@ _acq_msb_warn_if_agent_unreachable() {
 # _acq_msb_ssh_auth_sock_for NAME — echo the recorded guest ssh-agent sock path
 # (the SSH_AUTH_SOCK value git/ssh should use in the guest), or empty when
 # forwarding was never configured for this sandbox. Read from the HOST config
-# store (ADR-0030) so run/attach on a name-only re-entry still find it, and a
+# store (ADR-0035) so run/attach on a name-only re-entry still find it, and a
 # sudo guest cannot repoint SSH_AUTH_SOCK. See ADR-0021.
 _acq_msb_ssh_auth_sock_for() {
   local name="$1"
@@ -4167,7 +4167,7 @@ EOF
 }
 
 # _acq_msb_kit_env_flags_into ARRVAR NAME — build the `-e NAME=value` flag array
-# for the kit environment[] entries persisted in the HOST config store (ADR-0030)
+# for the kit environment[] entries persisted in the HOST config store (ADR-0035)
 # by _acq_msb_apply_kit_dir, so every session path (run/attach/shell) sees the env
 # the kits declared for agent runtime (see ADR-0011). Empty array when no kit
 # declared environment[]. Array passed by name (bash 3.2 compat).
@@ -4527,7 +4527,7 @@ EOF
       # Best-effort: mark ready so we do not re-run the (network-bound) install on
       # every provision/restart. (The /dev/net/tun grant and config writes above
       # are cheap + idempotent and re-run each pass regardless of this marker.)
-      # Host-authoritative (ADR-0030).
+      # Host-authoritative (ADR-0035).
       acq_host_config_write msb "$name" "$marker" 1 || true
       acq_debug "msb: OCI engine (rootless podman) ready in $name"
       return 0
@@ -4693,7 +4693,7 @@ acq_backend_run() {
 #                base image's Node REPL, and the passwd shell isn't exported).
 #
 # A bare `acq run <sandbox>` re-attach (no agent token) reads the agent recorded
-# at provision from the host config store (ADR-0030); `shell` (or a missing/failed
+# at provision from the host config store (ADR-0035); `shell` (or a missing/failed
 # agent binary) falls back to an interactive `/bin/sh -l` as `agent` — never a
 # root shell, never msb's Node-REPL default. Post-`--` args are forwarded to the agent.
 acq_backend_attach() {
@@ -4724,7 +4724,7 @@ _acq_msb_attach() {
   ws=$(_acq_msb_workspace_for "$name")
 
   # Read the agent recorded at provision. Default to `shell` if unset. The value
-  # comes from the HOST-authoritative config store (ADR-0030), not a guest file,
+  # comes from the HOST-authoritative config store (ADR-0035), not a guest file,
   # so a passwordless-sudo agent can no longer alter which binary is launched.
   # The charset guard is kept for defense-in-depth before the value enters the
   # `sh -c "command -v '$agent'"` below; fall back to a plain shell on anything
@@ -4844,7 +4844,7 @@ acq_backend_terminate() {
   # Same GONE-after-remove-attempt rule as the volumes above: delete the scratch
   # clone and drop the fetch-back remote only once the sandbox is really gone.
   _acq_msb_clone_cleanup "$1"
-  # Remove the host-authoritative config dir (ADR-0030) once the sandbox is gone.
+  # Remove the host-authoritative config dir (ADR-0035) once the sandbox is gone.
   acq_host_config_remove msb "$1" || true
   return "$_rc"
 }
diff --git a/acq.backends/sbx.sh b/acq.backends/sbx.sh
index c86e2c3f..4fb9a1a2 100644
--- a/acq.backends/sbx.sh
+++ b/acq.backends/sbx.sh
@@ -689,7 +689,7 @@ acq_backend_stop() {
 
 acq_backend_terminate() {
   sbx rm --force "$1"
-  # Remove any host-authoritative config dir for this sandbox (ADR-0030).
+  # Remove any host-authoritative config dir for this sandbox (ADR-0035).
   # sbx does not use the guest /var/lib/acq markers today (its parity mechanism
   # is `sbx run --name` + ~/.acq-extra-kits), so this is a defensive no-op unless
   # a future sbx path writes host config. Best-effort, never blocks removal.
diff --git a/docs/KNOWN_FAILURE_MODES.md b/docs/KNOWN_FAILURE_MODES.md
index 67ed465b..0dfd11b5 100644
--- a/docs/KNOWN_FAILURE_MODES.md
+++ b/docs/KNOWN_FAILURE_MODES.md
@@ -1800,7 +1800,7 @@ sandbox, and it starts working again as soon as you
 route and the `socat` bridge are fine — what is missing is the
 **`SSH_AUTH_SOCK` env var in the agent's process**. acq injects that var
 (`-e SSH_AUTH_SOCK=…`) only when the persisted ssh-agent sock value is present
-(recorded host-side in acq's per-sandbox config store, ADR-0030; originally a
+(recorded host-side in acq's per-sandbox config store, ADR-0035; originally a
 guest `/var/lib/acq/ssh-auth-sock` marker), and before the fix nothing
 re-established the bridge or wrote that value when re-attaching to an
 already-running sandbox (the heal's start-if-stopped block is a no-op on a
diff --git a/docs/adr/0011-msb-backend-and-neutral-kits.md b/docs/adr/0011-msb-backend-and-neutral-kits.md
index 59ad85f0..fc6d7e08 100644
--- a/docs/adr/0011-msb-backend-and-neutral-kits.md
+++ b/docs/adr/0011-msb-backend-and-neutral-kits.md
@@ -411,11 +411,11 @@ strings). The translate layer:
 > re-validated on replay and the last value wins for a duplicate name (kits
 > append in application order, so a later kit overrides an earlier one).
 >
-> **Superseded storage (ADR-0030):** the persisted values described in this ADR
+> **Superseded storage (ADR-0035):** the persisted values described in this ADR
 > (`agent`, `workspace`, `ssh-auth-sock`, `kit-env`, and the run-once gate
 > markers) were originally written to root-owned **guest** files under
 > `/var/lib/acq/`. Because the in-sandbox agent has passwordless sudo, a guest
-> path is not tamper-proof against a prompt-injected agent. ADR-0030 moves all of
+> path is not tamper-proof against a prompt-injected agent. ADR-0035 moves all of
 > these to acq's **host-authoritative** per-sandbox config store (mounted into
 > the guest read-only where the guest must read them). The behavior described
 > here is unchanged; only the storage location and its trust boundary moved.
diff --git a/docs/adr/0030-host-authoritative-sandbox-config.md b/docs/adr/0035-host-authoritative-sandbox-config.md
similarity index 99%
rename from docs/adr/0030-host-authoritative-sandbox-config.md
rename to docs/adr/0035-host-authoritative-sandbox-config.md
index dd8fd2db..7eac813b 100644
--- a/docs/adr/0030-host-authoritative-sandbox-config.md
+++ b/docs/adr/0035-host-authoritative-sandbox-config.md
@@ -11,7 +11,7 @@ risk_treatment: mitigate
 supersedes: []
 ---
 
-# ADR-0030: Host-Authoritative Sandbox Configuration (no trust in guest-generated state)
+# ADR-0035: Host-Authoritative Sandbox Configuration (no trust in guest-generated state)
 
 ## Context and Problem Statement
 
@@ -171,7 +171,7 @@ Concretely, this ADR introduces two mechanisms and a staged migration.
   mount before it rewrites `readonly: true` startup code to that path; if the
   probe fails, acq falls back to the legacy guest-copy path and warns. If a future
   msb changes `--volume ...:ro` parsing or enforcement, acq must raise or gate
-  its minimum msb version before relying on ADR-0030. Host and guest path forms
+  its minimum msb version before relying on ADR-0035. Host and guest path forms
   follow ADR-0029.
 - The mount root and `kit-files/` subtree are traversable but not listable (`0711`)
   so the guest `agent` user can open/execute known read-only kit payload paths,
diff --git a/scripts/test-acq-lib.sh b/scripts/test-acq-lib.sh
index 9a642d6a..bdd0969f 100644
--- a/scripts/test-acq-lib.sh
+++ b/scripts/test-acq-lib.sh
@@ -303,7 +303,7 @@ case "$_msb_sub" in
       *"getent passwd agent"*)
         [ -n "${STUB_AGENT_PASSWD_SHELL+x}" ] || exit 1
         printf '%s\n' "$STUB_AGENT_PASSWD_SHELL" ;;
-      # ADR-0030 host-config mount probes. Default PRESENT+READONLY, matching a
+      # ADR-0035 host-config mount probes. Default PRESENT+READONLY, matching a
       # freshly created sandbox on this branch; STUB_HOST_CONFIG_MOUNT=0 models a
       # legacy sandbox created before the /var/lib/acq/host:ro mount existed, and
       # STUB_HOST_CONFIG_WRITABLE=1 models a backend that accepts but does not
@@ -330,7 +330,7 @@ case "$_msb_sub" in
         [ "${STUB_OCI_SETUP_FAIL:-0}" = "1" ] && exit 1 || exit 0 ;;
       *"acq-oci-selftest"*)
         [ "${STUB_OCI_VERIFY_FAIL:-0}" = "1" ] && exit 1 || exit 0 ;;
-      # ADR-0030: the agent-user-ready and oci-ready run-once gates moved OFF the
+      # ADR-0035: the agent-user-ready and oci-ready run-once gates moved OFF the
       # guest /var/lib/acq markers onto the HOST config store (acq_host_config_*).
       # Tests seed those via seed_host_config_gates (from STUB_AGENT_USER_READY /
       # STUB_OCI_READY), so no guest `test -f` arm remains for them here.
@@ -395,7 +395,7 @@ case "$_msb_sub" in
         [ "${STUB_NPM_FAIL:-0}" = "1" ] && exit 1 || exit 0 ;;
       *"test -f "*) exit 1 ;;       # markers absent
       *"test -s "*) exit 0 ;;       # copied files present
-      # ADR-0030 migrated agent/workspace/ssh-auth-sock/kit-env OFF the guest
+      # ADR-0035 migrated agent/workspace/ssh-auth-sock/kit-env OFF the guest
       # /var/lib/acq markers onto the HOST config store (acq_host_config_*), which
       # acq now reads directly on the host — no `msb exec cat` happens for them.
       # The STUB_RECORDED_* knobs are seeded into the host store instead (see
@@ -552,7 +552,7 @@ load_acq() {
   # in setup() makes every assertion in the suite pass vacuously (#381 review).
 }
 
-# seed_host_config BACKEND NAME — populate the ADR-0030 host config store for a
+# seed_host_config BACKEND NAME — populate the ADR-0035 host config store for a
 # sandbox from the STUB_RECORDED_* env knobs, so tests that exercise the session
 # paths (attach/run/shell) find the agent/workspace/ssh-auth-sock/kit-env acq now
 # reads from the HOST (no guest `msb exec cat` happens for them anymore). Only a
@@ -575,7 +575,7 @@ seed_host_config() {
 # exports carry the store location into that subshell too.
 export -f seed_host_config 2>/dev/null || true
 
-# seed_host_config_gates BACKEND NAME — seed the ADR-0030 presence-gate keys
+# seed_host_config_gates BACKEND NAME — seed the ADR-0035 presence-gate keys
 # (agent-user-ready, oci-ready) from STUB_AGENT_USER_READY / STUB_OCI_READY, so a
 # test can model an already-provisioned sandbox (the run-once gates now live in
 # the host config store, not guest `touch`/`test -f` markers). Only a truthy knob
diff --git a/test/bats/115-ssh-agent-forward.bats b/test/bats/115-ssh-agent-forward.bats
index f83198a4..86113dec 100644
--- a/test/bats/115-ssh-agent-forward.bats
+++ b/test/bats/115-ssh-agent-forward.bats
@@ -144,7 +144,7 @@ s.bind(sys.argv[1])' "$1" >/dev/null 2>&1 && [ -S "$1" ]
   local log; log=$(cat "$CALLS")
   assert_regex "$log" "socat UNIX-LISTEN:'/home/agent/\.acq/ssh-agent\.sock'"
   assert_regex "$log" "VSOCK-CONNECT:2:'3552'"
-  # ADR-0030: the sock path is recorded in the HOST config store, not a guest
+  # ADR-0035: the sock path is recorded in the HOST config store, not a guest
   # /var/lib/acq/ssh-auth-sock marker.
   assert_equal "$(cat "$ACQ_PROVENANCE_DIR"/msb/sbox.*.config/ssh-auth-sock 2>/dev/null)" "/home/agent/.acq/ssh-agent.sock"
 }
@@ -316,7 +316,7 @@ s.bind(sys.argv[1])' "$1" >/dev/null 2>&1 && [ -S "$1" ]
   '
   local log; log=$(cat "$CALLS")
   assert_regex "$log" "socat UNIX-LISTEN:'/home/agent/\.acq/ssh-agent\.sock'"
-  # ADR-0030: the sock path is recorded in the HOST config store, not a guest marker.
+  # ADR-0035: the sock path is recorded in the HOST config store, not a guest marker.
   assert_equal "$(cat "$ACQ_PROVENANCE_DIR"/msb/reattachbox.*.config/ssh-auth-sock 2>/dev/null)" "/home/agent/.acq/ssh-agent.sock"
   # A running sandbox must NOT be routed through acq_backend_start.
   refute_regex "$log" 'msb start'
diff --git a/test/bats/71b-msb-secret-store-backends.bats b/test/bats/71b-msb-secret-store-backends.bats
index 79c7ccd1..08a285dd 100644
--- a/test/bats/71b-msb-secret-store-backends.bats
+++ b/test/bats/71b-msb-secret-store-backends.bats
@@ -283,7 +283,7 @@ _provision() { # NAME PRE_SNIPPET WS_ARGS...
   log=$(cat "$CALLS")
   assert_regex "$log" "--volume ${ws_app_h}:${ws_app}"
   assert_regex "$log" "--volume ${ws_lib_h}:${ws_lib}:ro"
-  # ADR-0030: the workspace record is written to the HOST config store now, not a
+  # ADR-0035: the workspace record is written to the HOST config store now, not a
   # guest /var/lib/acq/workspace marker. Assert the primary landed there.
   assert_equal "$(cat "$ACQ_PROVENANCE_DIR"/msb/mwbox.*.config/workspace 2>/dev/null)" "${ws_app}"
   [ "$(cat "$ACQ_PROVENANCE_DIR"/msb/mwbox.*.config/workspace 2>/dev/null)" != "/home/agent/workspace" ]
diff --git a/test/bats/72-msb-agent-user.bats b/test/bats/72-msb-agent-user.bats
index bdd87bc7..308be7d1 100644
--- a/test/bats/72-msb-agent-user.bats
+++ b/test/bats/72-msb-agent-user.bats
@@ -93,7 +93,7 @@ SPEC
   local log; log=$(cat "$CALLS")
   assert_regex "$log" 'npm install -g --no-fund --no-audit opencode-ai'
   assert_regex "$log" '--net-rule allow@registry\.npmjs\.org'
-  # ADR-0030: the launched-agent record is written to the HOST config store, not
+  # ADR-0035: the launched-agent record is written to the HOST config store, not
   # a guest /var/lib/acq/agent marker. Assert it landed in the host store.
   assert_equal "$(cat "$ACQ_PROVENANCE_DIR"/msb/instbox.*.config/agent 2>/dev/null)" "opencode"
 }
@@ -204,7 +204,7 @@ _attach() { # PRE_SNIPPET NAME
 }
 
 @test "msb: attach with a garbage recorded agent value falls back to shell, never runs the injection" {
-  # ADR-0030: the agent record now lives in the host config store (a sudo guest
+  # ADR-0035: the agent record now lives in the host config store (a sudo guest
   # can no longer plant it), but acq still charset-guards the value before it
   # enters `command -v '$agent'`. Seed a hostile value and prove the guard holds.
   _attach 'export STUB_RECORDED_AGENT="x'"'"';touch /tmp/acq_pwn;'"'"'" STUB_RECORDED_WORKSPACE=/tmp/wsp' injattach
@@ -218,7 +218,7 @@ _attach() { # PRE_SNIPPET NAME
   local log; log=$(cat "$CALLS")
   assert_regex "$log" 'PODMAN_PKGS='
   assert_regex "$log" '/usr/local/bin/docker'
-  # ADR-0030: the oci-ready gate is recorded in the host config store.
+  # ADR-0035: the oci-ready gate is recorded in the host config store.
   assert_equal "$(cat "$ACQ_PROVENANCE_DIR"/msb/ocibox.*.config/oci-ready 2>/dev/null)" "1"
   assert_regex "$log" '/etc/containers/storage\.conf'
   assert_regex "$log" 'driver = ..vfs..'
@@ -270,7 +270,7 @@ _attach() { # PRE_SNIPPET NAME
   '
   assert_success
   local log; log=$(cat "$CALLS")
-  # ADR-0030: the oci-ready gate still skips idempotent OCI setup during a heal;
+  # ADR-0035: the oci-ready gate still skips idempotent OCI setup during a heal;
   # fresh provision clears stale gates before this point.
   assert_equal "$(cat "$ACQ_PROVENANCE_DIR"/msb/ocirdybox.*.config/oci-ready 2>/dev/null)" "1"
   refute_regex "$log" 'PODMAN_PKGS='
@@ -452,7 +452,7 @@ SPEC
 
 @test "msb: repeated acq exec reads the workspace once per process (cached)" {
   : > "$CALLS"
-  # ADR-0030: the workspace is read from the HOST config store now, not a guest
+  # ADR-0035: the workspace is read from the HOST config store now, not a guest
   # `cat`, so the per-process cache is asserted via the resolved -w value being
   # applied to BOTH execs (a re-read would still yield the same value, but the
   # cache guarantees a single host lookup — proven by the stable -w on both).
@@ -481,7 +481,7 @@ SPEC
     acq_backend_ensure_kits_applied healshbox >/dev/null 2>&1
   '
   local log; log=$(cat "$CALLS")
-  # ADR-0030: agent-user-ready is a host config key; a hit skips useradd but
+  # ADR-0035: agent-user-ready is a host config key; a hit skips useradd but
   # still re-syncs the login shell (the heal path this test asserts).
   assert_regex "$log" 'acq-login-profile.* sh /bin/bash'
   refute_regex "$log" 'useradd'
diff --git a/test/bats/73-msb-kits-startup.bats b/test/bats/73-msb-kits-startup.bats
index 41adf45b..3d8be7ba 100644
--- a/test/bats/73-msb-kits-startup.bats
+++ b/test/bats/73-msb-kits-startup.bats
@@ -154,7 +154,7 @@ SPEC
     _acq_msb_apply_kit_dir instmarkerbox "$imk"
   '
   local log; log=$(cat "$CALLS")
-  # ADR-0030: the run-once install gate is a host config key now, not a guest
+  # ADR-0035: the run-once install gate is a host config key now, not a guest
   # test -f/touch. The install command still runs, and the gate key is written.
   assert_regex "$log" 'msb exec instmarkerbox -u 0'
   local instkey; instkey=$(ls "$ACQ_PROVENANCE_DIR"/msb/instmarkerbox.*.config/install-* 2>/dev/null | head -n1)
@@ -308,7 +308,7 @@ SPEC
   local log body
   log=$(cat "$CALLS")
   body=$(_staged_body mix-stage)
-  # ADR-0030: install is still exec-based and run-once, but the gate lives in the
+  # ADR-0035: install is still exec-based and run-once, but the gate lives in the
   # host config store now (not a guest test -f). Assert the install ran and a
   # gate key was recorded; startup is staged into the script body, not the gate.
   assert_regex "$log" 'echo INSTALL_ONLY_0017'
diff --git a/test/bats/78-msb-kit-env.bats b/test/bats/78-msb-kit-env.bats
index e181640a..ca858861 100644
--- a/test/bats/78-msb-kit-env.bats
+++ b/test/bats/78-msb-kit-env.bats
@@ -7,7 +7,7 @@
 # kit's own provisioning commands and never reached the agent session or
 # `acq exec`/`acq shell` — the kit env silently no-op'd at runtime. The fix
 # persists the validated entries and every session path replays each as
-# `msb exec -e NAME=value`. Per ADR-0030 the entries are persisted to the
+# `msb exec -e NAME=value`. Per ADR-0035 the entries are persisted to the
 # HOST-authoritative config store (acq_host_config_* kit-env key), not a guest
 # /var/lib/acq/kit-env marker a passwordless-sudo agent could tamper.
 #
@@ -164,7 +164,7 @@ RUBOCOP_PARALLELISM=4"
 
 @test "msb markers: an ABSENT host config must not kill session verbs under set -e" {
   # acq runs under `set -euo pipefail`. On a sandbox with no recorded host config
-  # (created before ADR-0030, or with no ssh-agent forwarding / kit env), the
+  # (created before ADR-0035, or with no ssh-agent forwarding / kit env), the
   # host reads return empty and must not terminate the session verb. All
   # STUB_RECORDED_* stay UNSET and nothing is seeded into the host store.
   : > "$CALLS"
diff --git a/test/bats/79-msb-readonly-kit-files.bats b/test/bats/79-msb-readonly-kit-files.bats
index e02f6742..c1719660 100644
--- a/test/bats/79-msb-readonly-kit-files.bats
+++ b/test/bats/79-msb-readonly-kit-files.bats
@@ -1,6 +1,6 @@
 #!/usr/bin/env bats
 #
-# 79-msb-readonly-kit-files.bats — ADR-0030 Mechanism 2: trusted startup
+# 79-msb-readonly-kit-files.bats — ADR-0035 Mechanism 2: trusted startup
 # execution from the read-only host-config mount.
 #
 # A kit files[] entry marked `readonly: true` carries trusted CODE that acq must
@@ -155,7 +155,7 @@ SPEC
   assert_regex "$log" 'msb copy .*legacyrobox:/home/agent/cfg/merge\.mjs'
   assert_regex "$log" 'node /home/agent/cfg/merge\.mjs'
   refute_regex "$log" '/var/lib/acq/host/kit-files'
-  assert_output --partial 'has no readable or read-only ADR-0030 host-config mount'
+  assert_output --partial 'has no readable or read-only ADR-0035 host-config mount'
 }
 
 @test "msb ro: writable host-config mount falls back to the guest copy" {
@@ -173,7 +173,7 @@ SPEC
   assert_regex "$log" 'msb copy .*writablerobox:/home/agent/cfg/merge\.mjs'
   assert_regex "$log" 'node /home/agent/cfg/merge\.mjs'
   refute_regex "$log" '/var/lib/acq/host/kit-files'
-  assert_output --partial 'has no readable or read-only ADR-0030 host-config mount'
+  assert_output --partial 'has no readable or read-only ADR-0035 host-config mount'
 }
 
 @test "msb ro: the create-time host-config mount is read-only" {

From 79743d5ea251996264b9c0394f0014309a596ec4 Mon Sep 17 00:00:00 2001
From: Bret Mogilefsky <bret.mogilefsky@gsa.gov>
Date: Thu, 8 Oct 2026 06:55:57 +0000
Subject: [PATCH 12/12] fix(msb): preserve legacy session context

---
 acq.backends/msb.sh                      | 22 ++++++++----
 docs/KNOWN_FAILURE_MODES.md              | 44 +++++++++++++++++++++++-
 scripts/test-acq-lib.sh                  |  1 +
 test/bats/72-msb-agent-user.bats         | 40 +++++++++++++++++++++
 test/bats/78-msb-kit-env.bats            | 12 +++++++
 test/bats/79-msb-readonly-kit-files.bats |  6 ++--
 6 files changed, 114 insertions(+), 11 deletions(-)

diff --git a/acq.backends/msb.sh b/acq.backends/msb.sh
index c540daca..0b7d6ebf 100644
--- a/acq.backends/msb.sh
+++ b/acq.backends/msb.sh
@@ -4420,9 +4420,9 @@ _ACQ_MSB_RUN_WS=""
 
 acq_backend_recorded_agent() {
   local name="$1" agent
-  agent=$(acq_provenance_field msb "$name" agent)
+  agent=$(acq_host_config_read msb "$name" agent | tr -d '[:space:]')
   if [ -z "$agent" ]; then
-    agent=$(acq_host_config_read msb "$name" agent | tr -d '[:space:]')
+    agent=$(acq_provenance_field msb "$name" agent)
   fi
   if [ -n "$agent" ] && acq_agent_safe_token "$agent"; then
     printf '%s\n' "$agent"
@@ -4432,8 +4432,9 @@ acq_backend_recorded_agent() {
 # _acq_msb_workspace_for NAME — the guest workspace a session starts in (-w).
 # Prefer an explicit ACQ_MSB_WORKSPACE override; otherwise the guest path
 # recorded at provision in the host config store (it mirrors the host mount path,
-# so it cannot be recomputed from NAME alone); fall back to the agent home if
-# nothing was recorded (older sandbox).
+# so it cannot be recomputed from NAME alone). A pre-ADR-0035 sandbox lacks that
+# key; use its trusted host provenance record before falling back to the agent
+# home. Never import the guest marker because a sudo-capable guest can forge it.
 _acq_msb_workspace_for() {
   local name="$1" ws=""
   if [ -n "${ACQ_MSB_WORKSPACE:-}" ]; then
@@ -4447,6 +4448,12 @@ _acq_msb_workspace_for() {
     fi
   else
     ws=$(acq_host_config_read msb "$name" workspace | tr -d '\r\n')
+    if [ -z "$ws" ]; then
+      ws=$(acq_workspace_record_read msb "$name" | tr -d '\r\n')
+      if [ -n "$ws" ] && command -v canonicalize_path >/dev/null 2>&1; then
+        ws=$(canonicalize_path "$ws")
+      fi
+    fi
   fi
   [ -n "$ws" ] || ws="/home/agent"
   printf '%s\n' "$ws"
@@ -4604,12 +4611,13 @@ _acq_msb_attach() {
   local ws
   ws=$(_acq_msb_workspace_for "$name")
 
-  # Read the agent recorded at provision. Default to `shell` if unset. The value
-  # comes from the host-authoritative config store (ADR-0035), not a guest file.
+  # Read the agent recorded at provision. Default to `shell` if unset. Prefer
+  # host provenance for pre-ADR-0035 sandboxes, then the host-authoritative config
+  # store; never import the guest marker.
   # Keep the charset guard before it enters the `sh -c "command -v '$agent'"`
   # below; fall back to a plain shell on anything unexpected.
   local agent
-  agent=$(acq_host_config_read msb "$name" agent | tr -d '[:space:]')
+  agent=$(acq_backend_recorded_agent "$name" | tr -d '[:space:]')
   if [ -z "$agent" ] || ! _acq_msb_safe_agent_token "$agent"; then
     agent="shell"
   fi
diff --git a/docs/KNOWN_FAILURE_MODES.md b/docs/KNOWN_FAILURE_MODES.md
index 936d992b..f403c49d 100644
--- a/docs/KNOWN_FAILURE_MODES.md
+++ b/docs/KNOWN_FAILURE_MODES.md
@@ -3,7 +3,7 @@ title: "Known Failure Modes"
 description: "Real-world failure patterns when using Docker SBX + USAi + agent frameworks"
 status: canonical
 tier: 2
-last_updated: "2026-10-03"
+last_updated: "2026-10-08"
 audience: "developers"
 keywords: ["debugging", "troubleshooting", "sbx", "usai", "failures"]
 ---
@@ -1644,6 +1644,48 @@ calls against a 0.6.9+ binary, `allow@dns` is safe to use directly.
 
 ---
 
+## 32.1. An Existing msb Sandbox Opens a Shell or `/home/agent` After Upgrading acq
+
+### Symptoms
+
+After upgrading acq, a name-only `acq run <sandbox>` against an existing msb
+sandbox opens a plain shell instead of its configured agent, or starts in
+`/home/agent` rather than the mounted workspace. The first resume may also
+re-run idempotent kit install and agent-user setup steps.
+
+### Root Cause
+
+ADR-0035 moves session configuration and run-once gates from guest-writable
+`/var/lib/acq` markers to the host-authoritative config store. Sandboxes created
+before that migration have no host-config keys. acq must not import their old
+guest markers because a passwordless-sudo agent can forge those values.
+
+### Fix
+
+Current acq releases recover the agent and workspace from their existing trusted
+host provenance record when the new host-config keys are absent. The regular
+`acq run`, `acq start`, and `acq restart` heal also reapplies the effective kit
+set, rebuilding kit environment entries and safely re-running missing
+idempotency gates once. SSH-agent forwarding is re-established during the same
+heal when configured.
+
+If the provenance record is missing or the replay fails, recreate the sandbox
+from its workspace:
+
+```bash
+acq rm <sandbox>
+acq run <agent> <workspace>
+```
+
+### Prevention / Status
+
+- Fixed without trusting legacy guest state. A one-time idempotent replay after
+  upgrade is expected for a sandbox that predates the host-config migration.
+- Keep work in the mounted workspace committed or backed up before recreating a
+  sandbox; recreation discards guest-local state.
+
+---
+
 ## 33. `--kit` Services Dead After a Resume/Reboot on msb — Ports Mapped, Nothing Listening
 
 ### Symptoms
diff --git a/scripts/test-acq-lib.sh b/scripts/test-acq-lib.sh
index fd0883b2..69039cb8 100644
--- a/scripts/test-acq-lib.sh
+++ b/scripts/test-acq-lib.sh
@@ -588,6 +588,7 @@ seed_host_config() {
   [ -n "${STUB_RECORDED_WORKSPACE+x}" ] && acq_host_config_write "$backend" "$name" workspace "$STUB_RECORDED_WORKSPACE"
   [ -n "${STUB_RECORDED_SSH_AUTH_SOCK+x}" ] && acq_host_config_write "$backend" "$name" ssh-auth-sock "$STUB_RECORDED_SSH_AUTH_SOCK"
   [ -n "${STUB_RECORDED_KIT_ENV+x}" ] && acq_host_config_write "$backend" "$name" kit-env "$STUB_RECORDED_KIT_ENV"
+  return 0
 }
 export -f seed_host_config 2>/dev/null || true
 
diff --git a/test/bats/72-msb-agent-user.bats b/test/bats/72-msb-agent-user.bats
index a64e31a7..757f4870 100644
--- a/test/bats/72-msb-agent-user.bats
+++ b/test/bats/72-msb-agent-user.bats
@@ -127,6 +127,34 @@ _attach() { # PRE_SNIPPET NAME
   refute_regex "$log" 'su - agent'
 }
 
+@test "msb: legacy sandbox uses trusted provenance for its agent and workspace" {
+  : > "$CALLS"
+  run bash -c '
+    set -euo pipefail
+    export STUB_AGENT_PRESENT=1
+    . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    acq_provenance_write msb legacybox opencode /tmp/legacy-repo
+    _acq_msb_attach legacybox </dev/null >/dev/null 2>&1
+  '
+  assert_success
+  local log; log=$(cat "$CALLS")
+  assert_regex "$log" 'msb exec -t -u agent -w /tmp/legacy-repo'
+  assert_regex "$log" 'legacybox -- opencode'
+  refute_regex "$log" 'legacybox -- /bin/sh -l'
+}
+
+@test "msb: host-config agent overrides stale provenance" {
+  run bash -c '
+    set -euo pipefail
+    . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    acq_provenance_write msb precedencebox opencode
+    acq_host_config_write msb precedencebox agent shell
+    acq_backend_recorded_agent precedencebox
+  '
+  assert_success
+  assert_output 'shell'
+}
+
 @test "msb: attach falls back to a shell (with notice) when the agent binary is missing" {
   _attach 'export STUB_RECORDED_AGENT=opencode STUB_RECORDED_WORKSPACE=/tmp/myrepo STUB_AGENT_PRESENT=0' attachbox
   assert_regex "$(cat "$CALLS")" 'attachbox -- /bin/sh -l'
@@ -210,6 +238,18 @@ _attach() { # PRE_SNIPPET NAME
   assert_regex "$(cat "$CALLS")" '\-w /home/agent wsbox'
 }
 
+@test "msb #421: acq exec uses trusted provenance for a legacy workspace" {
+  : > "$CALLS"
+  run bash -c '
+    set -euo pipefail
+    . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    acq_provenance_write msb legacywsbox shell /tmp/legacy-repo
+    acq_backend_run legacywsbox -- git status >/dev/null 2>&1
+  '
+  assert_success
+  assert_regex "$(cat "$CALLS")" '\-w /tmp/legacy-repo legacywsbox -- git status'
+}
+
 @test "msb #425: attach and shell forward the host TERM/COLORTERM when set" {
   _attach 'export TERM=xterm-256color COLORTERM=truecolor STUB_RECORDED_AGENT=opencode STUB_AGENT_PRESENT=1 STUB_RECORDED_WORKSPACE=/tmp/wsp' termbox
   local log; log=$(cat "$CALLS")
diff --git a/test/bats/78-msb-kit-env.bats b/test/bats/78-msb-kit-env.bats
index ca858861..590c4634 100644
--- a/test/bats/78-msb-kit-env.bats
+++ b/test/bats/78-msb-kit-env.bats
@@ -187,6 +187,18 @@ RUBOCOP_PARALLELISM=4"
   assert_regex "$(cat "$CALLS")" 'exec -u agent -e HOME=/home/agent -w /home/agent sbox -- git status'
 }
 
+@test "msb test helper: unset fixture values are safe under set -e" {
+  run bash -c '
+    set -euo pipefail
+    unset STUB_RECORDED_AGENT STUB_RECORDED_WORKSPACE STUB_RECORDED_SSH_AUTH_SOCK STUB_RECORDED_KIT_ENV
+    . "'"$REPO_ROOT"'/acq.backends/msb.sh"
+    seed_host_config msb unsetfixture
+    echo SURVIVED
+  '
+  assert_success
+  assert_output 'SURVIVED'
+}
+
 @test "msb kit env: heal rebuilds the marker — a var the kit no longer declares stops reaching sessions" {
   # The heal loop (and provision) applies the FULL effective kit set, so the
   # marker must be rebuilt from the current kits' environment[] each time. An
diff --git a/test/bats/79-msb-readonly-kit-files.bats b/test/bats/79-msb-readonly-kit-files.bats
index c1719660..5f87aa7e 100644
--- a/test/bats/79-msb-readonly-kit-files.bats
+++ b/test/bats/79-msb-readonly-kit-files.bats
@@ -104,9 +104,9 @@ SPEC
   # The mount root must be traversable by the guest agent (0711) while flat
   # acq-internal keys stay private; kit-files must be traversable and files
   # executable/readable from the :ro mount.
-  assert_equal "$(stat -c '%a' "$cfg")" "711"
-  assert_equal "$(stat -c '%a' "$cfg/kit-files")" "711"
-  assert_equal "$(stat -c '%a' "$staged")" "555"
+  assert_equal "$(stat -c '%a' "$cfg" 2>/dev/null || stat -f '%Lp' "$cfg" 2>/dev/null || echo '?')" "711"
+  assert_equal "$(stat -c '%a' "$cfg/kit-files" 2>/dev/null || stat -f '%Lp' "$cfg/kit-files" 2>/dev/null || echo '?')" "711"
+  assert_equal "$(stat -c '%a' "$staged" 2>/dev/null || stat -f '%Lp' "$staged" 2>/dev/null || echo '?')" "555"
   # It is NOT msb-copied into the guest at its declared guest path.
   refute_regex "$log" 'msb copy .*:/home/agent/cfg/merge\.mjs'
   # The plain data file IS copied into the guest (unchanged behavior).