docs: sync runner-selfhosting-cleanup design docs

Claude-Session: https://claude.ai/code/session_01XhENr63WL9npkKrJGnzDc1

Author: mmabrouk

docs/design/agent-workflows/projects/runner-selfhosting-cleanup/README.md

@@ -27,7 +27,7 @@ The normal deployment uses one runner service. That runner can support both loca
 - API and web get provider availability from the same environment value, set once per deployment by the hosting templates. A discovery endpoint is deferred (RSH-7).
 - Daytona configuration belongs under the runner namespace. Code-evaluator Daytona configuration is separate.
 - The runner never discovers an operator's home directory or automatically uploads Pi or Claude OAuth state.
-- Subscription authentication is an explicit local self-hosting setup: a read-only Compose volume mount taught in a tutorial. There is no bootstrap manifest in version 1 (RSH-4).
+- Subscription authentication is an explicit local self-hosting setup: a read-write Compose volume mount taught in a tutorial. The harness runs directly out of the mount so it can refresh its own OAuth token; there is no per-run copy and no bootstrap manifest in version 1 (RSH-4).
 - Runtime customization (extra binaries, certificates, dependencies) happens through operator-built images and the shipped Daytona snapshot scripts, not runner configuration.
 - Remote subscription authentication is unsupported until the relevant provider explicitly approves the integration and Agenta defines a safe product contract.
 - Pi installation is detected and repaired by the runtime. There is no deployment-wide "Pi is installed" boolean.
@@ -50,7 +50,7 @@ The normal deployment uses one runner service. That runner can support both loca
 - Runner provider selection and configuration.
 - Runner-specific Daytona names and validation.
 - Runner-to-Services routing and authentication.
-- Local subscription setup through explicit read-only mounts.
+- Local subscription setup through explicit read-write mounts.
 - Removal of automatic Daytona OAuth upload.
 - Removal of deployment-wide runtime facts and hidden policy switches.
 - A structured warning when a durable mount degrades.

docs/design/agent-workflows/projects/runner-selfhosting-cleanup/context.md

@@ -50,7 +50,7 @@ DAYTONA_JWT_TOKEN and DAYTONA_ORGANIZATION_ID.
 
 Nothing was wrong with the user's Daytona account. The request reached a runner deployment that was not configured for Daytona. The setup made it easy to split capabilities accidentally.
 
-The target local QA deployment is one trusted development runner with both providers enabled and explicit read-only local subscription mounts. This is a development convenience, not a production multi-tenant topology. A local harness shares the runner container and can inspect other same-user processes through `/proc`.
+The target local QA deployment is one trusted development runner with both providers enabled and explicit read-write local subscription mounts. This is a development convenience, not a production multi-tenant topology. A local harness shares the runner container and can inspect other same-user processes through `/proc`.
 
 ## Trust boundaries
 

docs/design/agent-workflows/projects/runner-selfhosting-cleanup/documentation-plan.md

@@ -92,7 +92,7 @@ The opt-in path for a trusted personal deployment. Covers the three supported lo
 login, Claude Code OAuth, and the ChatGPT/Codex login.
 
 1. Find the supported login state for the harness on the operator's machine.
-2. Add the read-only volume mount in the Compose file and point the harness config variable at it.
+2. Add the read-write volume mount in the Compose file and point the harness config variable at it.
 3. Run a self-managed agent and confirm it uses the mounted login.
 4. Remove the mount and confirm the run fails with the explicit missing-configuration error.
 

docs/design/agent-workflows/projects/runner-selfhosting-cleanup/interface.md

@@ -187,20 +187,24 @@ The two problems this replaces the manifest for:
 
 ### Local subscription mounts
 
-The operator mounts credential state read-only into the runner container and points the harness config variable at it. The Compose files ship commented examples:
+The operator mounts credential state read-write into the runner container and points the harness config variable at it. The Compose files ship commented examples:
 
 ~~~yaml
 runner:
   # Opt-in: use your own harness subscription for local runs.
   # volumes:
-  #   - ~/.pi:/agenta/harness/pi:ro
+  #   - ~/.pi:/agenta/harness/pi:rw
   # environment:
   #   - PI_CODING_AGENT_DIR=/agenta/harness/pi
 ~~~
 
 Rules:
 
-- Mounts are read-only. The runner copies the state into a per-run directory so harness writes never touch the operator's source credential.
+- Mounts are read-write, and the harness runs directly out of the mount. There is no per-run copy of the credential state.
+
+  A subscription login is an OAuth login: the harness refreshes its access token mid-run and writes the new one back to its own config directory. A read-only mount plus a per-run copy discarded that refresh, so as soon as the provider rotated the refresh token the next run failed and the operator had to log in again by hand. Letting the harness own its token lifecycle, exactly as it does on a normal local install, is the only shape that survives rotation.
+
+  The tradeoff: harness writes land in the operator's login directory (refreshed tokens, and any skills or system prompt a run installs), and concurrent local subscription runs share that directory the same way two local harness sessions do. This path is single-trusted-operator only, so both are acceptable.
 - A `runtime_provided` local run without the matching mount fails with an error naming the missing configuration.
 - Mounted subscription state never leaves the runner container. Daytona runs never receive it.
 - One personal subscription belongs to one operator. The docs state this is a single-tenant convenience.
@@ -250,7 +254,7 @@ The fail-loud contract (a required mount failure fails the run, no silent durabl
 
 ### Docker Compose
 
-The runner service enumerates only runner variables. It has no shared `env_file`. The examples include commented, opt-in read-only volumes for subscription inputs (section 6).
+The runner service enumerates only runner variables. It has no shared `env_file`. The examples include commented, opt-in read-write volumes for subscription inputs (section 6).
 
 One runner service can enable `local,daytona`; there is no second subscription runner in the default stack.
 

docs/design/agent-workflows/projects/runner-selfhosting-cleanup/open-issues.md

@@ -26,7 +26,7 @@ No implementation or tutorial should precede that decision.
 
 ## RSH-4: Declarative bootstrap assets, hooks, and network plugins
 
-Version 1 ships no bootstrap manifest at all: local subscription state arrives through an operator-owned read-only Compose mount, and runtime customization happens through images and snapshots. If operator demand shows a real need for declarative per-run file assets (typed manifest, validation, Daytona upload of non-auth files), design it then, together with hooks: repository checkout, VPN enrollment, certificate rotation, custom initialization.
+Version 1 ships no bootstrap manifest at all: local subscription state arrives through an operator-owned read-write Compose mount, and runtime customization happens through images and snapshots. If operator demand shows a real need for declarative per-run file assets (typed manifest, validation, Daytona upload of non-auth files), design it then, together with hooks: repository checkout, VPN enrollment, certificate rotation, custom initialization.
 
 A future design must define:
 

docs/design/agent-workflows/projects/runner-selfhosting-cleanup/plan.md

@@ -12,7 +12,7 @@ Goal: restore a trustworthy 8280 test environment before larger refactors.
 - Remove the dead `AGENTA_AGENT_SANDBOX_DAYTONA_SNAPSHOT` line.
 - Point the 8280 deployment at one trusted development runner.
 - Give that runner the Daytona provisioning credential.
-- Keep local Pi and Claude login inputs read-only and explicit.
+- Keep local Pi and Claude login inputs read-write and explicit (the harness owns its token lifecycle).
 - Remove or stop the two ad hoc runner services after the unified runner passes the matrix.
 - Record the exact local setup without committing personal credentials.
 

docs/design/agent-workflows/projects/runner-selfhosting-cleanup/qa.md

@@ -91,12 +91,12 @@ Assert the presence of only configured runner values, runner token reference, AP
 
 ## 4. Subscription mount tests
 
-- every runtime-provided run gets a unique per-run config copy;
-- Pi receives `PI_CODING_AGENT_DIR` pointing at the copy;
-- Claude receives `CLAUDE_CONFIG_DIR` pointing at the copy;
-- the operator source is mounted read-only and harness writes do not mutate it;
-- teardown removes the per-run copy;
-- concurrent runs cannot see each other's copies;
+- every runtime-provided run runs directly out of the operator's mount (no per-run config copy);
+- Pi receives `PI_CODING_AGENT_DIR` pointing at the mount;
+- Claude receives `CLAUDE_CONFIG_DIR` pointing at the mount;
+- the operator source is mounted read-write and a token the harness refreshes persists to it;
+- teardown does NOT delete the mount;
+- concurrent local subscription runs share the mount (accepted: single trusted operator);
 - subscription state never uploads to a Daytona sandbox;
 - content and credential paths do not appear in logs or traces.
 
@@ -130,9 +130,9 @@ Before deleting the extra runners:
 
 1. Record the currently selected `AGENTA_RUNNER_INTERNAL_URL`.
 2. Confirm which service contains the Daytona credential.
-3. Confirm which read-only subscription inputs exist.
+3. Confirm which read-write subscription inputs exist.
 4. Configure the normal runner with enabled providers `local,daytona`.
-5. Add local-only Pi and Claude read-only subscription mounts.
+5. Add local-only Pi and Claude read-write subscription mounts.
 6. Run the primary matrix.
 7. Confirm the Daytona sandbox count returns to zero.
 8. Stop the legacy subscription sidecars.

docs/design/agent-workflows/projects/runner-selfhosting-cleanup/research.md

@@ -34,7 +34,7 @@ That couples three unrelated decisions:
 2. the runner happens to have Pi state;
 3. the state should be copied to a third-party remote sandbox.
 
-The target removes this inference. Local subscription use requires an explicit read-only mount. Daytona runtime-provided subscription authentication is unsupported in version 1.
+The target removes this inference. Local subscription use requires an explicit read-write mount. Daytona runtime-provided subscription authentication is unsupported in version 1.
 
 ### Runtime-fact and policy booleans
 

docs/design/agent-workflows/projects/runner-selfhosting-cleanup/status.md

@@ -9,7 +9,7 @@ Last updated: 2026-07-13
 Owner review plus a second reviewing agent converged on a re-scope for the MVP release. All four owner comments were adopted:
 
 - Cut the runner `GET /capabilities` endpoint. API and runner read the same enabled-provider value from one deployment entry (the API already had this pattern via `AGENTA_SANDBOX_LOCAL_ALLOWED`). Deferred as RSH-7.
-- Cut the declarative bootstrap manifest. Local subscriptions use an operator-owned read-only Compose mount; runtime customization uses custom images and the existing Daytona snapshot scripts. Deferred as RSH-4.
+- Cut the declarative bootstrap manifest. Local subscriptions use an operator-owned read-write Compose mount; runtime customization uses custom images and the existing Daytona snapshot scripts. Deferred as RSH-4.
 - Cut the fail-loud mount rework. Version 1 keeps best-effort behavior plus one structured degradation warning. Deferred as RSH-11.
 - Confirmed customization is owned by the operator through scripts and images, not runner environment machinery.
 
@@ -46,10 +46,54 @@ The managed-deployment migration is assessed in a private working note outside t
 
 - [ ] Phase 0: local QA and snapshot repair.
 - [ ] Phase 1: canonical names and typed runner configuration.
-- [ ] Phase 2: runner environment narrowing.
-- [ ] Phase 3: subscription cleanup.
+- [x] Phase 2: runner environment narrowing.
+- [x] Phase 3: subscription cleanup.
 - [ ] Phase 4: hosting layout and public documentation.
 
+## Phases 2 + 3 landed (2026-07-14)
+
+Shipped in `fix/runner-env-narrowing` (stacked on `refactor/runner-config-names`):
+
+- Deleted `shouldUploadOwnLogin` + `uploadPiAuthToSandbox` and their tests. The runner no longer
+  discovers its own Pi login and uploads it to a Daytona sandbox.
+- `buildRunPlan` rejects Daytona + `runtime_provided`, and rejects a local `runtime_provided` run
+  whose subscription mount (`PI_CODING_AGENT_DIR` / `CLAUDE_CONFIG_DIR`) is unset, before any
+  sandbox side effect.
+- Local `runtime_provided` Pi and Claude runs read and write the operator's read-write mounted
+  login DIRECTLY: no per-run copy. The harness refreshes its own OAuth token and the new token
+  persists to the mount, so a rotated refresh token no longer breaks the next run. Tradeoff:
+  concurrent local subscription runs share the harness config dir (single-trusted-operator path).
+- Removed the static `AGENTA_API_KEY` exporter fallback in `tracing/otel.ts`; export auth rides
+  the per-run caller credential.
+- One structured `mount degraded kind=<k> cause=<c>` warning at each durable-null site
+  (session cwd, agent mount, harness transcript). Failure behavior unchanged (RSH-11 still open).
+- Helm: `AGENTA_RUNNER_TOKEN` wired via `agentRunner.auth.tokenSecretRef` in
+  `runner-deployment.yaml` + `_helpers.tpl` (both ends), values.yaml/schema examples, and a
+  rendered-chart secret-absence test (`hosting/kubernetes/helm/tests/`) wired into CI.
+- Compose: commented opt-in read-write subscription mount examples on the OSS + EE runner service.
+
+No-ops on this base (deletions already satisfied, nothing to remove): `commonEnv` is absent from
+the runner deployment (the #5286 include that would add it is not an ancestor of this base),
+`AGENTA_RUNNER_INHERIT_ALL_PROVIDER_KEYS` has zero code occurrences, and
+`AGENTA_SESSION_HARNESS_MOUNTS` was already removed from `services/runner/src` in phase 1.
+
+## Deferred to post-release: credentialMode strictness flip
+
+The interface's required-`credentialMode` contract (interface.md section 5) is NOT free on this
+base, so the flip is deliberately deferred and this slice keeps the existing inference branch.
+
+The caller audit (research.md / the env-narrowing spec section 9) found one structural path that
+omits the field: a **model-less agent template** in the SDK agent handler. When `_agent_model_ref`
+returns `None` (`sdks/python/agenta/sdk/agents/handler.py`, model-less template branch), no
+`resolved_connection` is threaded, so `wire_resolved_connection()` returns `{}` and the run request
+carries no `credentialMode` / `provider` / `deployment`. Every model-configured caller sends all
+three via `ResolvedConnection.to_wire()`.
+
+Post-release work to unblock the flip: thread a sentinel `ResolvedConnection` (credential_mode
+`"none"`, or `"runtime_provided"` for a self-managed harness) when `model_ref is None` in
+`handler.py`, confirm across the matrix, then make `credentialMode` required in `buildRunPlan` and
+delete the inference branch. `AGENTA_RUNNER_INHERIT_ALL_PROVIDER_KEYS` is already deleted (no-op).
+
 ## Review guidance
 
 The draft PR has inline decision threads on the most consequential choices. Resolve those before implementation. Small naming edits can land directly in this workspace; changes that alter credential movement, remote subscription support, or mount behavior should update the interface, plan, and QA documents together.