fix(s3): eng+dx review — 10 hardening fixes (T1-T9 + T2-b)

CLAUDE.md

@@ -0,0 +1,40 @@
+# Agent-S — Project Rules
+
+GUI automation framework (Simular AI `gui_agents`), Python 3.12.
+Active branch: `feat/agent-s3-foundation-orchestration-observability`.
+s3 = current version (CLI `agent_s=gui_agents.s3.cli_app:main`).
+
+## Skill routing
+
+When the user's request matches an available skill, invoke it via the Skill tool. When in doubt, invoke the skill.
+
+Key routing rules:
+- Product ideas/brainstorming → invoke /office-hours
+- Strategy/scope → invoke /plan-ceo-review
+- Architecture → invoke /plan-eng-review
+- Design system/plan review → invoke /design-consultation or /plan-design-review
+- Full review pipeline → invoke /autoplan
+- Bugs/errors → invoke /investigate
+- QA/testing site behavior → invoke /qa or /qa-only
+- Code review/diff check → invoke /review
+- Visual polish → invoke /design-review
+- Ship/deploy/PR → invoke /ship or /land-and-deploy
+- Save progress → invoke /context-save
+- Resume context → invoke /context-restore
+- Author a backlog-ready spec/issue → invoke /spec
+
+## Env-var reference
+
+All gates default OFF (unset = stub/subprocess path). Set to `1` to enable.
+
+| Env var | Default | Effect |
+|---|---|---|
+| `AGENT_S3_USE_DOCKER` | unset | CLI agent runs LLM code in a Docker sandbox (`DockerExecutor`) instead of host subprocess. Needs docker daemon + SDK. |
+| `AGENT_S3_USE_MEMORY` | unset | CLI agent queries `VectorMemory` at cycle start + saves winning trajectories at "done". Loads ~90MB model on first call. |
+| `AGENT_S3_USE_HEALING` | unset | CLI agent calls `SelfHealingEngine.diagnose` on the except path; if recovery found, exec corrected action + continue. Needs `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`. |
+| `AGENT_S3_API_TIER4` | unset | API `POST /tasks` routes through `_tier4_handler` (Docker→VectorMemory→Observability cycle) instead of the stub handler. Needs docker + memory + keys. |
+| `AGENT_S3_CHROMA_URL` | unset | `VectorMemory` auto-promotes to `provider="remote"` (HttpClient to a `chroma run` server). Multi-process safe. Unset = local PersistentClient (single-writer, 1 process). |
+| `AGENT_S3_SHUTDOWN_TIMEOUT` | `30` | Seconds the API lifespan waits for worker threads on shutdown before abandoning them. |
+| `AGENT_S3_CONTEXT_ID` | (set by code) | Propagated into Docker env + ChromaDB metadata for trace correlation. Set per-request by the framework, not by the user. |
+
+See `docs/TIER4.md` for the full tier4 onboarding checklist.

docs/TIER4.md

@@ -0,0 +1,73 @@
+# TIER 4 — Super Agent onboarding
+
+TIER 4 turns Agent-S3 from a default subprocess agent into a sandboxed, memory-equipped,
+self-healing agent. It is **fully env-gated** — every gate defaults OFF, so the base
+agent is unchanged until you opt in. This doc lists every prerequisite in one place so
+you don't have to grep three module docstrings.
+
+## Prerequisites
+
+| Need | Why | How to check |
+|---|---|---|
+| **Docker daemon running** | `DockerExecutor` runs LLM code in an ephemeral `python:3.11-slim` container | `docker info` succeeds |
+| **Docker SDK installed** | `docker` Python package (import-guarded; loads without it, fails at instantiation) | `python -c "import docker"` |
+| **An LLM API key** | `SelfHealingEngine` needs a VLM to diagnose failures | `OPENAI_API_KEY` (gpt-4o) **or** `ANTHROPIC_API_KEY` (claude-sonnet-5) set in env |
+| **~90MB model download** (first run only) | `VectorMemory` default `provider="local"` loads `all-MiniLM-L6-v2` via sentence-transformers | first `AGENT_S3_USE_MEMORY=1` run takes ~10s extra; cached after |
+| **First container pull** (first run only) | `python:3.11-slim` image pulled on first `DockerExecutor` use | first `AGENT_S3_USE_DOCKER=1` run takes ~30s extra; cached after |
+
+## Env gates (all default OFF — set to `1`)
+
+| Env var | Effect |
+|---|---|
+| `AGENT_S3_USE_DOCKER=1` | CLI runs LLM code in Docker sandbox (falls back to host subprocess if daemon/SDK unavailable) |
+| `AGENT_S3_USE_MEMORY=1` | CLI queries `VectorMemory` at cycle start + saves winning trajectories at "done" |
+| `AGENT_S3_USE_HEALING=1` | CLI calls `SelfHealingEngine.diagnose` on failure; if recovery found, execs corrected action + continues |
+| `AGENT_S3_API_TIER4=1` | API `POST /tasks` routes through `_tier4_handler` (Docker→VectorMemory→Observability) instead of the stub |
+| `AGENT_S3_CHROMA_URL=<url>` | `VectorMemory` uses a remote `chroma run` server (multi-process safe) instead of local PersistentClient |
+| `AGENT_S3_SHUTDOWN_TIMEOUT=<sec>` | API shutdown grace period (default 30s) |
+
+## First run (CLI)
+
+```bash
+# 1. daemon + key
+docker info                                    # must succeed
+export ANTHROPIC_API_KEY=sk-...                # or OPENAI_API_KEY
+
+# 2. enable all three CLI gates
+export AGENT_S3_USE_DOCKER=1 AGENT_S3_USE_MEMORY=1 AGENT_S3_USE_HEALING=1
+
+# 3. run — first cycle is slower (model load + image pull, one-time)
+agent_s
+```
+
+## First run (API tier4)
+
+```bash
+export AGENT_S3_API_TIER4=1 AGENT_S3_USE_DOCKER=1 AGENT_S3_USE_MEMORY=1
+export ANTHROPIC_API_KEY=sk-...
+uvicorn gui_agents.s3.api.main:app --port 8000
+
+# POST /tasks now runs the full tier4 cycle
+curl -X POST localhost:8000/tasks -H 'Content-Type: application/json' \
+  -d '{"instruction":"open calculator","code":"```python\nimport pyautogui\npyautogui.press(\"win\")\n```"}'
+```
+
+## What each gate does NOT do
+
+- `USE_DOCKER` unset → LLM code runs on the **host** via `subprocess` with full user privileges. The Docker sandbox is the mitigation; it is opt-in. Only enable the agent in trusted environments either way.
+- `USE_MEMORY` unset → no trajectory recall; every cycle starts fresh.
+- `USE_HEALING` unset → failures raise; no VLM diagnosis or corrected retry.
+- `API_TIER4` unset → `POST /tasks` uses the stub handler (no Docker/VectorMemory cycle).
+
+## Multi-worker note
+
+The Docker reaper (`reap_orphans`) scopes containers by owner PID. With
+`uvicorn --workers N` (N>1), a worker only knows its own PID and may reap another
+worker's live containers. **Use a single worker** for tier4, or move container labels
+to a per-process UUID (see `_alive_pids` docstring).
+
+## Observability
+
+- Logs: `logs/*.log` under logger `desktopenv.agent.*` (JSON, `context_id` correlated).
+- Metrics: `ObservabilityManager` singleton (`track_task`/`track_action`).
+- Slack: set `AGENT_S3_SLACK_WEBHOOK` for alert export.

graphify-out/.graphify_labels.json

@@ -0,0 +1 @@
+{"0": "macOS ACI Grounding", "1": "Agent-S2 Core + Utils", "2": "B-Bon Behavior Narrator", "3": "S3 Architecture Analysis Docs", "4": "S2.5 Grounding + Engine", "5": "S2 LMM Engine Backends", "6": "S3 Procedural TaskStore", "7": "S1 Base + Multimodal Agent", "8": "Community 8", "9": "Community 9", "10": "S2.5 OSWorld ACI Actions", "11": "S3 Persistence Layer", "12": "Windows Agent Arena Grounding", "13": "Community 13", "14": "Community 14", "15": "Community 15", "16": "Community 16", "17": "S3 Grounding + Screenshot Cache", "18": "S1 Knowledge Base", "19": "S2.5 Agents Layer", "20": "S3 MCP Client", "21": "S1 Graph Search Agent", "22": "S1 Common Utilities", "23": "S3 B-Bon Judge + LMM Agent", "24": "S3 Orchestrator (ReAct)", "25": "S1 Manager (DAG Planner)", "26": "Community 26", "27": "Community 27", "28": "S3 Logging + DAG Executor", "29": "Community 29", "30": "Community 30", "31": "Community 31", "32": "Community 32", "33": "Community 33", "34": "Community 34", "35": "Community 35", "36": "Community 36", "37": "Community 37", "38": "Community 38", "39": "Community 39", "40": "Community 40", "41": "Community 41", "42": "Community 42", "43": "Community 43", "44": "Community 44", "45": "Community 45", "46": "Community 46", "47": "Community 47", "48": "Community 48", "49": "Community 49", "50": "Community 50", "51": "Community 51", "52": "Community 52", "53": "Community 53", "54": "Community 54", "55": "Community 55", "56": "Community 56", "57": "Community 57", "58": "Community 58", "59": "Community 59", "60": "Community 60", "61": "Community 61", "62": "Community 62", "63": "Community 63", "64": "Community 64", "65": "Community 65", "66": "Community 66", "67": "Community 67", "68": "Community 68", "69": "Community 69", "70": "Community 70", "71": "Community 71", "72": "Community 72", "73": "Community 73", "74": "Community 74", "75": "Community 75", "76": "Community 76", "77": "Community 77", "78": "Community 78", "79": "Community 79", "80": "Community 80", "81": "Community 81", "82": "Community 82", "83": "Community 83", "84": "Community 84", "85": "Community 85", "86": "Community 86", "87": "Community 87", "88": "Community 88", "89": "Community 89", "90": "Community 90", "91": "Community 91", "92": "Community 92", "93": "Community 93", "94": "Community 94", "95": "Community 95", "96": "Community 96", "97": "Community 97", "98": "Community 98", "99": "Community 99", "100": "Community 100", "101": "Community 101", "102": "Community 102", "103": "Community 103", "104": "Community 104", "105": "Community 105", "106": "Community 106", "107": "Community 107", "108": "Community 108", "109": "Community 109", "110": "Community 110", "111": "Community 111", "112": "Community 112", "113": "Community 113", "114": "Community 114", "115": "Community 115", "116": "Community 116", "117": "Community 117", "118": "Community 118", "119": "Community 119", "120": "Community 120", "121": "Community 121", "122": "Community 122", "123": "Community 123", "124": "Community 124", "125": "Community 125", "126": "Community 126", "127": "Community 127", "128": "Community 128", "129": "Community 129", "130": "Community 130", "131": "Community 131", "132": "Community 132", "133": "Community 133", "134": "Community 134", "135": "Community 135", "136": "Community 136"}