docs: preserve E2E and AWS runtime findings

Author: Gini

AGENTS.md

@@ -32,3 +32,13 @@ Linear is the source of truth for ONEVibe delivery. Use the dedicated project:
 The release-critical dependency order is `ONE-216` conversation persistence → `ONE-217` conversation-scoped microVM → `ONE-218` Claude/LiteLLM inside the microVM → `ONE-219` durable event streaming → `ONE-220` sandbox PPTX/PDF → `ONE-221` real-provider E2E. `ONE-222` hardening can proceed alongside the later backend slices. UX (`ONE-223`) and OpenVTC approval integration (`ONE-224`) must not displace this backend gate.
 
 Read `docs/LINEAR-BOARD.md` before changing issue state or scope. The API credential is read only into a shell variable from `../handover/onecomputer-handover-secrets-lean/mac/linear-api-key.txt`; never print, commit, paste, or place it in a URL. Keep one major epic In Progress and attach exact commit/test/provider evidence in issue comments after material slices.
+
+## Durable engineering memory
+
+Documentation is part of every material slice. Update `docs/IMPLEMENTATION-LOG.md` for shipped behavior and `docs/LIVE-E2E-ENGINEERING-LOG.md` for live observations, failed experiments, provider/runtime IDs that are safe to retain, fixes, and remaining gates. Architecture or credential decisions receive a dedicated document/ADR; do not leave them only in chat or Linear comments. Keep secrets, account IDs, raw provider bodies, auth headers, and credential values out of all docs.
+
+For AWS/Bedrock runtime work, read `docs/AGENTCORE-AWS-RUNTIME.md` and the referenced files in `/Users/gini/Desktop/agentcore-claude-codex-runtime-harness`. Reuse the standard refreshable AWS provider-chain pattern and explicit Bedrock configuration. Never mount `~/.aws`, copy profile credentials, or place static `AWS_*` values in a retained sandbox.
+
+## Frontend foundation
+
+Use `assistant-ui` as the preferred foundation for ONEVibe conversation threads, streaming messages, composer, history navigation, accessible message actions, and tool-state rendering. Preserve ONEComputer's bespoke dark/light visual system and custom evidence/artifact rail rather than forcing those surfaces into generic chat components. Any adoption must bind to the real server transcript/SSE contracts; demo arrays or browser-authoritative history are prohibited.

docs/AGENTCORE-AWS-RUNTIME.md

@@ -0,0 +1,80 @@
+# AgentCore AWS runtime study for ONEVibe
+
+## Decision
+
+ONEVibe may reuse the AgentCore harness's explicit Bedrock model/region configuration and its reliance on the standard AWS credential chain. It must not copy the harness's temporary cross-account Secrets Manager credentials into a retained sandbox environment, mount a host AWS profile, or assume AgentCore's execution-role injection exists in ONEComputer.
+
+The production target is:
+
+```text
+host/cloud workload identity
+  → ONEVibe credential broker outside the sandbox
+  → STS AssumeRole with a Bedrock-only session policy
+  → AWS container credential-provider endpoint
+  → retained sandbox standard AWS credential chain
+  → Claude Code / Agent SDK → Bedrock
+```
+
+## What the reference harness does
+
+Deployment scripts create a `boto3.Session` from an explicit CLI profile or `AWS_PROFILE`, then call STS to verify the effective caller before building/deploying:
+
+- `/Users/gini/Desktop/agentcore-claude-codex-runtime-harness/invgini-agentcore-runtimes/scripts-v2/build_and_push.py`
+- `/Users/gini/Desktop/agentcore-claude-codex-runtime-harness/invgini-agentcore-runtimes/scripts-v2/deploy_runtime.py`
+
+The normal AgentCore runtime receives temporary execution-role credentials from AgentCore. Claude inherits the standard AWS provider chain from its process environment; credentials are not arguments to `ClaudeAgentOptions`:
+
+- `runtimes/claude-python/app/main.py`
+- `runtimes/claude-python/app/session.py`
+- `docs/AGENTCORE_SKILLS_ARCHITECTURE_20260712.md`
+
+The optional cross-account workaround reads one Secrets Manager secret at process startup and writes its fields into `AWS_*` environment variables:
+
+- `runtimes/claude-python/app/credential_bootstrap.py`
+- `docs/CROSS_ACCOUNT_BEDROCK_SANDBOX.md`
+
+That workaround does not refresh credentials and is unsuitable for retained ONEVibe sandboxes.
+
+## Bedrock configuration worth reusing
+
+The runtime separates the AgentCore control-plane region from the Bedrock model-serving region. Inside the runtime it sets:
+
+- `CLAUDE_CODE_USE_BEDROCK=1`
+- `AWS_REGION`
+- `AWS_DEFAULT_REGION`
+- an allowlisted Bedrock inference-profile/model ID
+- Claude model selection variables
+
+Claude Code also requires the minimum inference-profile discovery permissions in addition to invocation. A readiness check must perform a real signed request; cached SSO identity or a successful historical STS lookup is insufficient because refresh can still fail later.
+
+## ONEVibe implementation contract
+
+The sandbox launcher must start from an environment allowlist and remove inherited `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_PROFILE`, `AWS_CONFIG_FILE`, and `AWS_SHARED_CREDENTIALS_FILE`. It must never mount `~/.aws`.
+
+The sandbox receives only:
+
+- `AWS_CONTAINER_CREDENTIALS_FULL_URI`
+- `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE`
+- `AWS_REGION`
+- `AWS_DEFAULT_REGION`
+- `CLAUDE_CODE_USE_BEDROCK=1`
+- approved model/inference-profile configuration
+
+The token file identifies one sandbox/lease generation; it contains no AWS credential, is read-only, mode `0400`, and is revoked when the lease is released or replaced.
+
+The broker must authenticate that token, map it server-side to tenant/user/conversation/lease generation, assume only a Bedrock role with a restrictive session policy, return standard expiring container credentials, refresh before expiry, and reject sandbox-supplied role/account/region/model choices. Logs retain only safe metadata such as role alias, region, expiry, result category, and lease ID.
+
+## Threat and failure gates
+
+- Host `AWS_*` leakage can select the wrong account or widen authority.
+- A mounted AWS directory exposes profiles and SSO caches to model-accessible tools.
+- Static environment credentials in a retained sandbox both leak and expire without refresh.
+- A shared unauthenticated broker lets one sandbox request another tenant's authority.
+- Cached identity is not readiness; force a signed Bedrock request.
+- Model entitlement, inference-profile, region, and signer-account mismatches must produce distinct sanitized errors.
+- Retained sessions can outlive image/config changes; bind session continuity to lease ID and generation.
+
+## POC boundary
+
+The current Azure POC uses a scoped Anthropic-compatible relay token injected into the Claude process. That is sufficient to prove the conversation/sandbox/artifact spine, but not this production AWS credential design. Track short-lived secret injection under ONE-227 and implement the container-provider broker before production Bedrock promotion.
+

docs/IMPLEMENTATION-LOG.md

@@ -91,3 +91,5 @@
 - Completed the relational chat-history cutover. SQLite is now authoritative for conversations, turns, and messages; a one-time checksum-recorded importer handles legacy JSON, and stale or forged `messages.json` state cannot override canonical history after restart. A real API stop/start probe returned the identical completed transcript from the database.
 - Added generation-fenced runtime leases and changed ONEComputer ownership from one disposable sandbox per run to one retained development sandbox per durable conversation. Allocation ambiguity fails closed as `unknown`; follow-ups reuse the same provider identity; separate conversations cannot share an active lease; teardown is an explicit server-only action. The controlled E2E now requires same-conversation reuse, cross-conversation separation, sandbox-origin PPTX/PDF, evidence validity, and explicit cleanup.
 - Attempted that upgraded harness against Azure with the sandbox-reachable LiteLLM relay. The provider returned HTTP 504 before yielding a sandbox identity; ONEVibe fenced the lease as `unknown`, did not retry, and the provider list showed no visible sandbox row. The attempt exposed an HTML provider-body projection bug, which was removed so external error bodies can no longer enter task evidence.
+- Promoted and hardened the Azure async lifecycle path: persisted provisioning identity before bootstrap, consistent single-resource lifecycle reads, headless Claude Code as the required runtime, optional Desktop installation, explicit managed CLI paths, stdin prompt transport, and a relay-only development proxy bypass that keeps TLS verification enabled. The first real sandbox Claude turn then completed through the scoped public relay with durable transcript/tool events and a lease-bound session. The PPTX gate remains open because the image lacks deterministic slide/PDF rendering dependencies.
+- Studied the AgentCore Claude/Codex harness's AWS chain and documented the accepted production design in `AGENTCORE-AWS-RUNTIME.md`: a sandbox-scoped AWS container credential-provider endpoint backed by short-lived STS sessions, never mounted profiles or copied static keys. Added `LIVE-E2E-ENGINEERING-LOG.md` so failed provider experiments and their fixes remain durable engineering evidence.

docs/LIVE-E2E-ENGINEERING-LOG.md

@@ -0,0 +1,48 @@
+# ONEVibe live E2E engineering log
+
+This is the durable failure-and-evidence log for the backend POC. It records observed facts and fixes so future agents do not repeat the same experiments.
+
+## 2026-07-16 — Azure ONEComputer + sandbox Claude
+
+### Allocation lifecycle
+
+The first upgraded harness attempt received HTTP 504 from `POST /v1/sandboxes` without a sandbox ID. ONEVibe fenced the lease as `unknown` and did not retry. Azure was running a deployment branch without the async lifecycle repair.
+
+The focused provider repair was promoted to Azure. A controlled probe then returned a persisted `provisioning` ID in seven seconds and accepted DELETE with HTTP 204 during bootstrap.
+
+### Bootstrap readiness
+
+The single-sandbox GET route bypassed persisted status and mapped “Docker container running” to `bootstrapped=true`. ONEVibe launched before Claude existed and observed exit 127. The endpoint now merges the persisted lifecycle record exactly like list responses; a regression test holds state at `provisioning` even if raw Docker state says started.
+
+The provider also installed Claude Desktop before the headless CLI in one fail-fast chain and ignored the install result. Claude Code installation is now required and terminal on failure; Desktop is optional and disabled by default unless `ONECOMPUTER_INSTALL_CLAUDE_DESKTOP=true`.
+
+### Process launch
+
+The managed CLI lives under `/opt/node22/bin` and `/home/kasm-user/.npm-global/bin`; ONEVibe now adds those paths explicitly.
+
+A background child could lose its temporary prompt before reading it. ONEVibe now passes the prompt through stdin and deletes the temporary file after Claude exits but before artifact enumeration.
+
+### Model transport
+
+The handover relay URL was host-loopback and unreachable from the sandbox. The POC now uses the scoped public sandbox relay endpoint. The development sandbox inherited a MITM proxy whose CA was rejected by Claude for that endpoint. With `gatewayEnforced=false`, only the configured relay hostname is appended to `NO_PROXY`; TLS verification remains enabled. Attested gateway mode receives no bypass.
+
+### First real Claude success
+
+Task `task_f4e8bb67f44144` completed a real Claude turn inside sandbox `onevibe-67f44144` through the scoped public relay. It persisted a Claude session bound to lease generation 1, streamed assistant and tool events, extracted files, and retained the sandbox until explicit release.
+
+The deck gate failed: the sandbox lacked `python-pptx`/PDF libraries, package installation hit the development proxy certificate, and only `outline.md` plus control files were delivered. This proves ONE-218's execution spine partially but leaves ONE-220/221 open.
+
+### Security findings
+
+- Provider response bodies were projected into a failure event; commit `f603a69` now emits only operation and HTTP status.
+- Claude requested Bash despite an intended file-tool allowlist. `--allowedTools` is an approval control, not a capability-removal mechanism. Do not claim Bash is unavailable until the command uses a true tool-availability restriction and a negative test proves it.
+- Current Kasm remains a development sandbox with known production-isolation gaps tracked separately.
+
+### Next acceptance steps
+
+1. Provide a deterministic slide renderer inside the sandbox image or via a governed sandbox-local tool; do not rely on live package installation.
+2. Restrict available Claude tools explicitly and test Bash absence for modes that do not require it.
+3. Complete two turns in the same sandbox/session and a second conversation in a distinct sandbox.
+4. Validate real PPTX/PDF magic bytes, transcript restart, evidence chain, and explicit cleanup.
+5. Run credential/workspace/event/export residue scans.
+