refactor tests

README.md

@@ -46,27 +46,34 @@ recreated.
    OpenCode models.
 3. Create `secrets/gitea_token`, `secrets/webhook_secret`, and
    `secrets/opencode_server_password`. Use high-entropy values for both secret/password files.
-4. Log in to the Gitea container registry with a personal access token, then pull the image:
+4. Create the writable state directories for the non-root container user:
+
+   ```sh
+   mkdir -p data/agentci data/opencode
+   sudo chown -R 10001:10001 data/agentci data/opencode
+   ```
+
+5. Log in to the Gitea container registry with a personal access token, then pull the image:
 
    ```sh
    docker login git.krtss.de
    docker compose pull
    ```
 
-5. Authenticate the configured OpenCode providers before starting the persistent server:
+6. Authenticate the configured OpenCode providers before starting the persistent server:
 
    ```sh
    docker compose run --rm opencode opencode auth login
    docker compose run --rm opencode opencode auth list
    ```
 
-6. Start the services:
+7. Start the services:
 
    ```sh
    docker compose up --no-build -d
    ```
 
-7. In Gitea, create a JSON webhook targeting `http://agentci:8080/webhooks/gitea`. Set the same
+8. In Gitea, create a JSON webhook targeting `http://agentci:8080/webhooks/gitea`. Set the same
    webhook secret and subscribe to issue comments, PR timeline comments, and PR review comments.
 
 OpenCode caches provider state. After adding or changing authentication on an already running
@@ -129,10 +136,11 @@ OpenCode permits still has the Unix-level access of that container user, so envi
 is only accidental-exposure hygiene and cannot protect readable files from an allowed shell command.
 
 Docker remains the OS boundary. The services run as non-root without added capabilities,
-privileged mode, an unconfined seccomp/AppArmor profile, or a nested `bubblewrap` sandbox. The only
-host bind mount is the read-only installer directory; there are no
-writable host filesystem mounts. The OpenCode HTTP server is not published to the host, is password
-protected, and is reachable by Agent CI over an internal Compose network.
+privileged mode, an unconfined seccomp/AppArmor profile, or a nested `bubblewrap` sandbox. Persistent
+state is exposed through writable host bind mounts at `./data/agentci` and `./data/opencode`; protect
+these directories because they contain private repository clones, installed tools, provider state,
+and resumable sessions. The OpenCode HTTP server is not published to the host, is password protected,
+and is reachable by Agent CI over an internal Compose network.
 
 ## Development environments
 
@@ -146,13 +154,13 @@ AGENTCI_PYTHON_VERSION=3.13
 AGENTCI_DOTNET_CHANNEL=10.0
 ```
 
-Every name resolves to a file in `install-scripts/`, mounted read-only at
-`/etc/agentci/install-scripts`. Names cannot contain paths and duplicates are rejected. Installers
-run after each implementation clone or branch sync and fail the job on an unknown script, timeout,
-or non-zero exit. They receive no Agent CI or Gitea secret values in their environment, but remain
-trusted operator code. Tools persist under `/var/lib/agentci/dev-tools`, and OpenCode can read or
-modify them through shell commands permitted by its active agent policy. See
-`install-scripts/README.md` for the script contract.
+Every name resolves to a file under `/etc/agentci/install-scripts`, copied from `install-scripts/`
+when the image is built. Rebuild the image after adding, replacing, or removing an installer. Names
+cannot contain paths and duplicates are rejected. Installers run after each implementation clone or
+branch sync and fail the job on an unknown script, timeout, or non-zero exit. They receive no Agent CI
+or Gitea secret values in their environment, but remain trusted operator code. Tools persist under
+`./data/agentci/dev-tools`, and OpenCode can read or modify them through shell commands permitted by
+its active agent policy. See `install-scripts/README.md` for the script contract.
 
 Agent CI continues to create branches, validate diffs, commit, and push after OpenCode returns. This
 keeps workflow behavior deterministic, but an OpenCode agent with shell permission can still run
@@ -160,10 +168,10 @@ Git commands itself.
 
 ## State and recovery
 
-The `agentci_data` volume contains SQLite, workflow clones, and installed development runtimes.
-The `opencode_home` volume contains provider authentication, OpenCode's database, and resumable
+The `data/agentci` directory contains SQLite, workflow clones, and installed development runtimes.
+The `data/opencode` directory contains provider authentication, OpenCode's database, and resumable
 sessions. Tea's Gitea token configuration is regenerated in an ephemeral tmpfs and is not copied to
-`opencode_home`. Back up both persistent volumes together.
+`data/opencode`. Back up both persistent directories together.
 
 SQLite stores the current job state, an idempotent event inbox, and durable listener tasks. State
 transitions and workflow creation/linking commit atomically; timestamps are storage metadata rather