create-harness-vibe-coding 0.8.16 → 0.8.18

package/templates/common/Harness/specs/workflows/WF-MAX.md

@@ -22,6 +22,24 @@ WF-MAX is **explicit only**. Enter ONLY when the user explicitly types `/wf-max`
 
 **WF-Max-Strict** (explicit `--strict`, `strict wf-max`, or `strict mode`): unconditional fan-out per span formula. Every file gets a Worker.
 
+## Mandatory Fan-Out Contract
+
+`/wf-max` MUST attempt native subagent fan-out before implementation planning is considered complete. A solo controller path is allowed only after an explicit degradation record.
+
+Minimum W0 attempt:
+
+- Start `task-scribe` when available to maintain task state and the dispatch ledger.
+- Start at least one independent read-only planning/exploration/review lane. For real multi-domain tasks, prefer `explore-manager` plus scoped researchers or codebase explorers.
+- Record `fanoutAttempted: true`, runtime, channel tried, agents requested, configured/runtime limit facts, result, and degradation reason in the task PLAN or PROGRESS.
+
+Mode interaction:
+
+- WF-Max-Useful may shrink the fan-out after the first native attempt when write sets or review lenses are not meaningfully independent. It may not silently skip the attempt.
+- WF-Max-Strict continues through the span formula until the Harness caps, runtime caps, user budget, or safety gates stop dispatch.
+- If native manager fan-out is unavailable, the controller dispatches leaf agents directly with exact WF-MAX dispatch packets; if no independent channel exists, stop honestly and ask the user.
+
+OpenCode-specific requirement: project `opencode.json` must set `subagent_depth >= 2` for manager -> worker nesting, and WF-MAX manager agents must expose `permission.task` allowlists for their child agents. Without those two settings, OpenCode may accept `/wf-max` but fail to fan out from manager subagents.
+
 ## CEO Contract
 
 CEO reads, plans, dispatches, synthesizes, and writes task state only.
@@ -68,6 +86,11 @@ Every Worker dispatch or peer-CLI call must be bounded by the controller's comma
 
 Record the channel actually used, command/tool form, timeout, exit status, and a <=250 token Evidence-Packet in the task capsule. Do not create ad hoc probe scripts or write peer-CLI output to `%TEMP%`; persistent evidence belongs only under the current task's `evidence/` directory when it is intentionally part of the task record.
 
+### Peer CLI Output Contract
+
+- `opencode run --agent reviewer`: installed agent is `mode: subagent` per `.opencode/agents/reviewer.md`. Do NOT claim primary-runner role use without a live probe.
+- Parse JSON/JSONL peer CLI output: fail on empty/non-JSON, error events, budget errors, fallback warnings, or missing final model text.
+
 ## Parallelism Priority
 
 1. Read-only exploration — max parallel, all readSets
@@ -104,11 +127,21 @@ WF-MAX fan-out is bounded. Unbounded worker dispatch is forbidden.
 - **Overflow discipline**: Cross-CLI overflow (Codex → Claude, Claude → Codex) is allowed only after native subagent pool is genuinely exhausted (not just busy). Each overflow dispatch costs context; prefer closing completed agents first.
 - **Idle workers**: Close completed agents before declaring the pool exhausted. Do not spawn new workers while idle capacity is available.
 
+## Runtime Capacity Map
+
+Harness treats vendor/runtime limits as outer ceilings, not as permission to exceed the WF-MAX caps above.
+
+| Runtime | Native limit/config surface | Harness rule |
+| --- | --- | --- |
+| Claude Code | Official docs describe subagent caps for session total `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` (default 200), concurrency `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` (default 20), and spawn depth `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` (default 3); use current Claude Code agent/subagent settings when available. | Record the detected limit/source when known; Harness WF-MAX caps still apply unless the user approves a task-local override. Do not raise environment limits without user approval. |
+| Codex | Official manual documents `[agents].max_concurrent_threads_per_session`; `agents.max_threads` is a legacy alias. Local codex-cli 0.144.x can reject scalar `[agents]` caps from project `.codex/config.toml` during TUI `skills/list`. | Do not scaffold Codex scalar agent caps into `.codex/config.toml`. Probe the installed runtime first; Harness manages a conservative task-local cap through the dispatch ledger unless `codex --strict-config doctor` verifies the config shape. |
+| OpenCode | Official config uses `subagent_depth`; default `1` permits primary -> subagent but blocks subagent -> subagent. `0` disables subagent launches; `2` permits one nested manager -> worker level. No official concurrent-count cap was found in the current docs. | Generated config sets `subagent_depth = 2`; Harness manages total/per-wave counts through WF-MAX caps and manager `permission.task` allowlists. |
+
 ## Organization Model
 
 ```
 CEO(1) -> Manager_1(span) -> Worker_1..n
-       -> Manager_2(span) -> Sub-Manager(span) -> Worker_1..n
+       -> Manager_2(span) -> Worker_1..n
 ```
 
 ## D-GATE
@@ -121,7 +154,7 @@ D-GATE is mandatory before implementation waves per [WF-KERNEL.md](WF-KERNEL.md)
 2. Close completed agents; fill idle slots immediately.
 3. Cross-CLI overflow: use an available peer CLI with explicit dispatch packets: `claude -p`, `codex exec`, or `opencode run --agent <role> --dir .`.
 4. Bounded-pass fallback only when subagents and overflow are exhausted.
-5. Generated Codex config defaults to `agents.max_threads = 12` and `agents.max_depth = 1`. Ask the user before raising `agents.max_threads` above that default. Keep `max_depth = 1` unless recursive delegation is explicitly approved.
+5. Codex compatibility guard: do not write scalar `[agents]` capacity fields into project `.codex/config.toml` by default. Probe the installed version first; local codex-cli 0.144.x has been observed to reject those fields during TUI `skills/list`. Harness manages Codex WF-MAX concurrency through the dispatch ledger and asks the user before any project/global Codex config change.
 6. Do not rely on Codex++, undocumented config, environment variables, forked/derived conversations, or third-party forks as stable capacity.
 
 ## Anti-Patterns and Sizing

package/templates/common/Harness/specs/workflows/WF-STATE.md

@@ -1,77 +1,193 @@
-# WF-STATE — Lightweight Resumable State Machine
+# WF-STATE - Lightweight Resumable State Machine
 
-Purpose: persist resumable workflow state across compaction, new Claude Code windows, new terminals, and project reopen. It is NOT a scheduler, daemon, lock manager, async runtime, or graph framework.
+Purpose: persist resumable workflow state across compaction, new Claude Code
+windows, new terminals, and project reopen. It is NOT a scheduler, daemon, lock
+manager, async runtime, or graph framework.
 
 ## State Files
 
 | File | Role |
 |------|------|
-| `Harness/PROGRESS.md` | Global active pointer — which task is current |
-| `Harness/tasks/<task-id>/STATE.json` | Machine-readable resume truth |
+| `Harness/PROGRESS.md` | Derived global active pointer and Task Index |
+| `Harness/tasks/<task-id>/STATE.json` | Canonical machine-readable resume truth |
 | `Harness/tasks/<task-id>/PROGRESS.md` | Human-readable summary |
 | `Harness/tasks/<task-id>/PLAN.md` | Plan, decisions, scope context |
 
-Task id convention: new task capsules MUST use `task-<verb>-<noun>[-detail]`
-(kebab-case, 2-5 words after the prefix), for example
-`task-fix-login-flow`. Do not create bare task names such as
+Task id convention: new task capsules MUST use
+`task-<verb>-<noun>[-detail]` (kebab-case, 2-5 words after the prefix), for
+example `task-fix-login-flow`. Do not create bare task names such as
 `fix-login-flow`.
 
 ## Enums
 
+### status
+
+`active`, `blocked`, `in_progress`, `running`, `pending`,
+`needs-user-decision`, `complete`, `verified`, `archived`, `abandoned`,
+`obsolete`, `done`, `closed`, `closeout`, `skipped`, `failed`
+
 ### phase
-`intake`, `clarify`, `requirements`, `prd`, `acceptance`, `plan`, `explore`, `implement`, `verify`, `review`, `fix`, `reflect`, `closeout`, `blocked`, `archived`
+
+`intake`, `clarify`, `requirements`, `prd`, `acceptance`, `plan`, `explore`,
+`implement`, `verify`, `review`, `fix`, `reflect`, `closeout`, `blocked`,
+`verified`, `archived`
+
+Legacy aliases such as `Implementation`, `Validation`, and
+`Verified/Complete` are normalized by `task-state.mjs`.
 
 ### item status (queues)
+
 `pending`, `ready`, `running`, `done`, `blocked`, `skipped`, `failed`
 
 ### mode
-`direct`, `wf`, `wf-max`, `wf-auto`, `wf-auto-spark`, `wf-review`, `wf-browser`
+
+`direct`, `wf`, `wf-max`, `wf-auto`, `wf-auto-spark`, `wf-review`,
+`wf-browser`
 
 ### tier
+
 `none`, `light`, `standard`, `full`, `max-useful`, `max-strict`
 
 ## Rules
 
-1. **STATE.json is machine-readable resume truth.** On session start, the agent reads it to know where it left off.
-2. **PROGRESS.md is human-readable summary.** It mirrors key state but is secondary for machine reasoning.
-3. **PLAN.md is plan/decision context.** Load only when decisions or scope need review.
-4. **On every phase transition, dispatch return, blocker, verification result, review finding, or closeout, update STATE.json.** task-scribe or controller writes; production agents never write task state.
+1. **STATE.json is machine-readable resume truth.** On session start, the agent
+   reads it to know where it left off.
+2. **PROGRESS.md is human-readable summary.** It mirrors key state but is
+   secondary for machine reasoning and may be rewritten from state.
+3. **PLAN.md is plan/decision context.** Load only when decisions or scope need
+   review.
+4. **On every phase transition, dispatch return, blocker, verification result,
+   review finding, or closeout, update STATE.json through
+   `Harness/scripts/task-state.mjs` when the command covers the change.**
+   task-scribe or controller writes; production agents never write task state.
 5. **Long logs/transcripts never go into STATE.json.** Store paths only.
-6. **task-scribe may update STATE.json and task summaries; production agents may not.**
-7. **If STATE.json conflicts with PLAN/PROGRESS, controller stops and reconciles before continuing.**
+6. **task-scribe may update STATE.json and task summaries; production agents may
+   not.**
+7. **If STATE.json conflicts with PLAN/PROGRESS, controller stops and reconciles
+   before continuing.**
+
+## CLI Contract
+
+Use `Harness/scripts/task-state.mjs` as the deterministic state writer:
+
+- `node Harness/scripts/task-state.mjs list --json`
+- `node Harness/scripts/task-state.mjs validate --json`
+- `node Harness/scripts/task-state.mjs reconcile --dry-run --json`
+- `node Harness/scripts/task-state.mjs reconcile --apply`
+- `node Harness/scripts/task-state.mjs set-active <task-id>`
+- `node Harness/scripts/task-state.mjs transition <task-id> --status <status> --phase <phase>`
+- `node Harness/scripts/task-state.mjs archive --keep 5 --dry-run --json`
+- `node Harness/scripts/task-state.mjs archive --keep 5 --apply`
+
+Do not rely on prompt instructions alone to keep active task, task `STATE.json`,
+task `PROGRESS.md`, and root `Harness/PROGRESS.md` synchronized.
+
+## Links (Cross-Task Dependencies)
+
+STATE.json `links` enables cross-task dependency resolution without reading
+every task capsule:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `links.dependsOn` | `string[]` | Task IDs this task depends on (blockers) |
+| `links.blocks` | `string[]` | Task IDs this task blocks |
+| `links.related` | `string[]` | Related task IDs (no dependency direction) |
+
+When resolving `links.dependsOn`, the controller reads only the listed tasks'
+STATE.json, not all task capsules. A task with unresolved dependsOn entries
+should stay in the blocked queue until its dependencies resolve.
+
+## Work Items (Parallel Dispatch)
+
+STATE.json `workItems[]` enables fine-grained parallel dispatch tracking with
+per-item dependencies:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique item identifier |
+| `status` | `string` | `pending`, `ready`, `running`, `done`, `blocked`, `skipped`, `failed` |
+| `phase` | `string` | Phase this item belongs to |
+| `dependsOn` | `string[]` | Item IDs this item depends on |
+| `parallelGroup` | `string` | Group name for concurrent dispatch (optional) |
+| `readSet` | `string[]` | Files/patterns the item may read |
+| `writeSet` | `string[]` | Files/patterns the item may write |
+| `agent` | `string` | Agent role assigned (optional) |
+| `evidence` | `string` | Evidence path or summary (optional) |
+| `next` | `string` | Next action after this item completes (optional) |
+
+`workItems` is an additive array — it supplements the dispatchLedger and queues
+for finer-grained tracking. The dispatchLedger remains the canonical record of
+subagent dispatches.
+
+## Open Tasks
+
+"Open tasks" are non-archived task capsules with status one of:
+`active`, `in_progress`, `running`, `pending`, `blocked`,
+`needs-user-decision`.
+
+The active pointer (`Harness/PROGRESS.md`) marks the single task the agent
+should resume. Other open tasks remain visible in the Task Index but are not
+automatically loaded.
+
+## Queue Entry Normalization
+
+Queues (`ready`, `running`, `blocked`, `done`) accept both plain string entries
+and object entries. The normalization rules are backward-compatible:
+
+- A plain string entry is treated as a task or dispatch item ID.
+- An object entry may contain the same fields as a work item (`id`, `status`,
+  `dependsOn`, etc.) for richer inline tracking.
+- `task-state.mjs` preserves both forms during reconcile — it does not coerce
+  objects to strings or vice versa.
+
+This enables incremental adoption: existing STATE.json files with string-only
+queues continue to work without changes.
 
 ## Resume Protocol
 
 New window / session start:
+
 1. Read `CLAUDE.md`.
-2. If user says "continue", "resume", "last task", "current task", "status", or the work is not a simple direct task:
-   - Read `Harness/PROGRESS.md` → find Active Task
-   - If Active Task exists, read `Harness/tasks/<active-task>/STATE.json`
-   - Read `Harness/tasks/<active-task>/PROGRESS.md`
-   - Read `Harness/tasks/<active-task>/PLAN.md` only if decisions/scope need review
+2. If user says "continue", "resume", "last task", "current task", "status",
+   or the work is not a simple direct task:
+   - Read `Harness/PROGRESS.md` and find Active Task.
+   - If Active Task exists, read `Harness/tasks/<active-task>/STATE.json`.
+   - Read `Harness/tasks/<active-task>/PROGRESS.md`.
+   - Read `Harness/tasks/<active-task>/PLAN.md` only if decisions/scope need review.
 3. From STATE.json, determine:
-   - Current phase, gate, tier
-   - activeQuestion (needs user answer before proceeding)
-   - Queues: ready (can dispatch immediately), running (awaiting results), blocked (needs resolution), done
-   - nextAction (what to do next)
+   - Current phase, gate, tier.
+   - activeQuestion (needs user answer before proceeding).
+   - Queues: ready (can dispatch immediately), running (awaiting results),
+     blocked (needs resolution), done.
+   - nextAction (what to do next).
+   - **links.dependsOn**: if non-empty, check whether any dependency tasks are
+     still open (their STATE.json has a non-archived status). Report blocked
+     dependencies to the user.
+   - **workItems[]**: if non-empty, inspect items with status `running` or
+     `ready` for parallel dispatch candidates.
 4. Do NOT bulk-read `Harness/tasks/` to find context. Use the active pointer.
-5. Direct simple tasks may skip STATE/PLAN/PROGRESS unless the user says "continue"/"resume".
+5. Direct simple tasks may skip STATE/PLAN/PROGRESS unless the user says
+   "continue"/"resume".
 
 ## State Transitions
 
-```
-intake → clarify → requirements → prd → acceptance → plan
-→ explore → implement → verify → review
-→ (fix → verify → review loop)
-→ reflect → closeout
+```text
+intake -> clarify -> requirements -> prd -> acceptance -> plan
+-> explore -> implement -> verify -> review
+-> (fix -> verify -> review loop)
+-> reflect -> closeout
 ```
 
-Any phase may transition to `blocked` if a dependency, user decision, or external input is required.
+Any phase may transition to `blocked` if a dependency, user decision, or external
+input is required.
 
 ## Dispatch Ledger
 
-Every dispatch packet MUST have an `id`. On return, controller or task-scribe updates the ledger item:
-- `id`, `agent`, `role`, `phase`, `status` (pending/ready/running/done/blocked/skipped/failed), `evidence`
+Every dispatch packet MUST have an `id`. On return, controller or task-scribe
+updates the ledger item:
+
+- `id`, `agent`, `role`, `phase`, `status` (`pending`, `ready`, `running`,
+  `done`, `blocked`, `skipped`, `failed`), `evidence`
 
 See [WF-KERNEL.md](WF-KERNEL.md) for the dispatch packet format.
 
@@ -79,10 +195,13 @@ See [WF-KERNEL.md](WF-KERNEL.md) for the dispatch packet format.
 
 - `/wf` uses the STATE ready queue for dynamic orchestration.
 - `/wf-max` uses the SAME STATE ready queue for maximum safe fan-out.
-- When a subagent returns or goes idle, controller immediately dispatches the next ready item.
+- When a subagent returns or goes idle, controller immediately dispatches the
+  next ready item.
 - task-scribe is the exception for task-state writes.
-- Production source agents do not write STATE/PLAN/PROGRESS unless explicitly dispatched as task-scribe.
+- Production source agents do not write STATE/PLAN/PROGRESS unless explicitly
+  dispatched as task-scribe.
 
 ## Template
 
-See `Harness/tasks/_template/STATE.json` for the canonical template. On task creation, copy and populate from the template.
+See `Harness/tasks/_template/STATE.json` for the canonical template. On task
+creation, copy and populate from the template.

package/templates/common/Harness/tasks/_template/STATE.json

@@ -10,12 +10,18 @@
   "activeQuestion": null,
   "nextAction": "Define goal and acceptance criteria",
   "acceptance": [],
+  "links": {
+    "dependsOn": [],
+    "blocks": [],
+    "related": []
+  },
   "queues": {
     "ready": [],
     "running": [],
     "blocked": [],
     "done": []
   },
+  "workItems": [],
   "dispatchLedger": [],
   "decisions": [],
   "risks": [],

package/templates/common/opencode.json

@@ -1,6 +1,7 @@
 {
   "$schema": "https://opencode.ai/config.json",
   "instructions": [".claude/rules/ecc/common.md"],
+  "subagent_depth": 2,
   "permission": {
     "bash": {
       "*": "ask",

package/templates/optional/catalog.json

@@ -1,12 +1,5 @@
 {
   "skills": [
-    {
-      "id": "browser-e2e",
-      "title": "Browser E2E",
-      "description": "Mandatory real-browser smoke workflow using Playwright, Chrome DevTools/CDP, or documented manual evidence.",
-      "files": ["skills/browser-e2e"],
-      "tags": ["e2e", "browser", "playwright", "cdp"]
-    },
     {
       "id": "ui-ux-review",
       "title": "UI/UX Review",
@@ -37,8 +30,8 @@
     }
   ],
   "presets": {
-    "web-app": ["ts-react-frontend", "browser-e2e", "ui-ux-review"],
-    "fullstack": ["ts-react-frontend", "python-backend", "browser-e2e", "github-pr-review"]
+    "web-app": ["ts-react-frontend", "ui-ux-review"],
+    "fullstack": ["ts-react-frontend", "python-backend", "github-pr-review"]
   },
   "externalRecommendations": [
     {

package/templates/optional/skills/browser-e2e/.claude/skills/browser-e2e/SKILL.md

@@ -1,42 +0,0 @@
----
-name: browser-e2e
-description: Mandatory real-browser smoke and end-to-end verification using Playwright, Chrome DevTools/CDP, or documented manual browser evidence.
----
-
-# Browser E2E
-
-## When To Use
-
-Use this skill when a change affects browser-visible behavior, navigation, forms, routing, layout, or client-side integration. Web/UI acceptance requires loading the app in a real browser before claiming the UI is done.
-
-## Docs To Load
-
-- `Harness/workflows/browser-e2e.md`
-- `Harness/PROGRESS.md` and current task `tasks/<id>/PLAN.md`
-- Existing project test, build, and run instructions.
-
-## Required Inputs
-
-- Target URL or command to start the app.
-- User flows or pages to verify.
-- Expected behavior and supported viewport/browser scope.
-- Selector contract: stable accessible labels/roles and `data-testid` hooks for critical inputs, buttons, filters, rows, empty/error/loading states, and other targetable UI states.
-
-## Allowed Writes
-
-- Browser test files in the project's existing test locations.
-- Evidence artifacts such as screenshots, traces, or reports in existing artifact folders.
-- Notes in current task plan when the active task asks for plan tracking.
-
-## Output Format
-
-Return changed files, commands run, browser evidence paths, verified flows, failures, and follow-up risks.
-Include the selectors used for CDP/Playwright/manual verification.
-
-## PROGRESS.md & Task PLAN.md Updates
-
-Update `Harness/tasks/<task-id>/PLAN.md` only when executing a tracked plan item or recording evidence requested by the current task.
-
-## dispatch.md Usage
-
-Use `Harness/specs/runtime/dispatch.md` only when splitting independent browser checks across workers is explicitly useful.

package/templates/optional/skills/browser-e2e/.claude/skills/wf-browser/SKILL.md

@@ -1,201 +0,0 @@
----
-name: wf-browser
-description: AI-driven browser automation for E2E testing, web scraping, form filling, and UI verification. Powered by Browser Use (89.1% WebVoyager benchmark). Use for Claude /wf-browser, Codex $wf-browser, browser testing, web automation, page interaction, form filling, screenshot verification, or any task requiring real browser control. Dual mode: CLI (fast iteration, no LLM needed) + Python Agent API (complex multi-step workflows with AI reasoning).
----
-
-# WF Browser — AI Browser Automation
-
-Load:
-
-- `Harness/workflows/browser-e2e.md`
-- Official `browser-use` skill at `~/.claude/skills/browser-use/SKILL.md` (auto-installed if missing)
-- `Harness/PROGRESS.md` when work is active
-
-## Cache Discipline
-
-Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: keep workflow
-docs stable, use CLI state/screenshot paths as dynamic evidence, and avoid
-replaying full browser logs or screenshots in prompts unless a failed AC needs
-targeted inspection.
-
-## Modes
-
-Choose based on task complexity:
-
-### Mode 1: CLI (fast iteration, ~50ms per call)
-
-Best for: single-page checks, quick screenshots, form fills, element inspection. No LLM needed — Claude Code reasons and issues CLI commands.
-
-```bash
-browser-use --headed open https://example.com   # Open page (headed = visible browser)
-browser-use state                                # Get page title, text, interactive elements with indices
-browser-use screenshot evidence.png              # Capture screenshot as evidence
-browser-use click 5                              # Click element by index from state output
-browser-use input 3 "user@example.com"           # Fill input field by index
-browser-use eval "document.title"                # Run JavaScript in page
-browser-use close                                # Close browser when done
-```
-
-Daemon keeps the browser open between commands — no cold-start per action.
-
-### Mode 2: Python Agent API (multi-step AI reasoning)
-
-Best for: complex multi-page workflows, dynamic navigation, data extraction across pages. Needs LLM API key.
-
-```python
-from browser_use.beta import Agent, BrowserProfile
-from browser_use.llm import ChatAnthropic
-
-agent = Agent(
-    task="Go to github.com, search for 'browser-use', click the first result, and report the star count",
-    llm=ChatAnthropic(model="claude-haiku-4-5-20251001"),
-    browser_profile=BrowserProfile(headless=False),
-)
-history = await agent.run()
-print(history.final_result())
-```
-
-## Environment Setup
-
-Run once per machine:
-
-```bash
-# 1. Install browser-use with CLI extras
-pip install "browser-use[cli]"
-
-# 2. Install Chromium browser
-browser-use install
-
-# 3. Verify installation
-browser-use doctor
-
-# 4. (Optional) Set LLM API key for Agent mode
-# Create .env file with: ANTHROPIC_API_KEY=sk-ant-...
-# Or: OPENAI_API_KEY=sk-...
-# Or: BROWSER_USE_API_KEY=bu-...
-```
-
-### Windows GBK Encoding Fix
-
-If you see `UnicodeEncodeError: 'gbk' codec can't encode character`, the install is auto-patched. If not, set env var before commands:
-
-```bash
-set PYTHONIOENCODING=utf-8
-```
-
-### Windows Daemon Patches
-
-Browser Use v0.13.1 has two known issues on Windows that are auto-patched on install. If `browser-use open` fails with "Failed to start daemon" or socket timeout, re-apply:
-
-```bash
-python -c "
-import browser_use.skill_cli.main as m
-p = m.__file__
-c = open(p, encoding='utf-8').read()
-# Patch 1: auto-clean stale state on dead PID
-c = c.replace(
-    'probe = _probe_session(session)\n\n\t# Socket reachable',
-    'probe = _probe_session(session)\n\n\t# Auto-clean stale state\n\tif not probe.socket_reachable and not probe.pid_alive and probe.phase:\n\t\t_clean_session_files(session)\n\t\tprobe = _probe_session(session)\n\n\t# Socket reachable'
-)
-# Patch 2: auto-recover from stale session instead of erroring
-c = c.replace(
-    \"f'Error: Session {session!r} is alive (phase={probe.phase}) but socket unreachable.\",\"
-    \"f'Warning: Session {session!r} has stale state (phase={probe.phase}), auto-cleaning...\",\"
-)
-c = c.replace(
-    \"sys.exit(1)\n\n\t\telif probe.phase == 'shutting_down'\",
-    \"_terminate_pid(probe.pid)\n\t\t\t_clean_session_files(session)\n\n\t\telif probe.phase == 'shutting_down'\"
-)
-# Patch 3: extend daemon startup timeout (15s -> 30s)
-c = c.replace('deadline = time.time() + 15', 'deadline = time.time() + 30')
-open(p, 'w', encoding='utf-8').write(c)
-print('Patches applied')
-"
-```
-
-### Requirements
-
-| Requirement | Version | Check |
-|-------------|---------|-------|
-| Python | >= 3.11 | `python --version` |
-| pip | any | `pip --version` |
-| Chromium | auto-installed | `browser-use doctor` |
-| LLM API key | for Agent mode only | check `.env` |
-
-## Common Patterns
-
-### Login Persistence
-
-```bash
-# Use real Chrome profile (preserves cookies/logins)
-browser-use --profile "Default" open https://app.target.com
-# Or connect to running Chrome with remote debugging
-browser-use connect
-```
-
-### E2E Test Flow
-
-```bash
-browser-use --headed open https://yourapp.local
-browser-use state                          # Verify page loaded
-browser-use screenshot step1-landing.png   # Evidence
-browser-use input 3 "test@email.com"       # Fill email
-browser-use input 5 "password123"          # Fill password
-browser-use click 8                        # Click login button
-browser-use wait text "Dashboard"           # Wait for navigation text
-browser-use state                          # Verify logged in
-browser-use screenshot step2-dashboard.png # Evidence
-browser-use close
-```
-
-### Console & Network Log Capture
-
-```bash
-browser-use eval "console.log('checkpoint');"   # Inject log marker
-browser-use eval "document.title"                # Read page state via JS
-browser-use get text 5                           # Get text of element index 5
-browser-use get value 3                          # Get value of input element index 3
-# For full console/network: use Python Agent mode with Playwright's page.on('console') and page.on('request')
-```
-
-### Error Recovery
-
-```bash
-# If daemon crashes or gets stuck:
-browser-use close          # Clean shutdown
-# Then restart:
-browser-use open <url>     # Fresh daemon starts automatically
-```
-
-## Verification Contract
-
-Every browser task must produce:
-
-1. **State evidence**: `browser-use state` output or screenshot
-2. **Action log**: sequence of commands issued
-3. **Result assertion**: explicit before/after state comparison
-
-No browser/UI claim without real-browser evidence.
-
-## Architecture Note
-
-Browser Use wraps Playwright with AI reasoning. The daemon keeps Chromium running between CLI commands (~50ms latency). The Agent mode adds an LLM observation→decision→action loop on top. This replaces fragile CSS-selector scripts with semantic element targeting via accessibility tree snapshots.
-
-Benchmarks: 89.1% WebVoyager (SOTA), 78k+ GitHub stars, MIT license.
-
-## Security
-
-- **Never log or screenshot credentials** — redact password fields, API keys, tokens before capturing evidence
-- **Chrome profiles contain sensitive data** — only use `--profile` with explicit user approval; never share profile data
-- **Screenshots may capture PII** — review before saving to task evidence directory
-- **Scraping targets need approval** — confirm the target site's ToS allow automated access before scraping
-- **`browser-use input` commands with passwords** — use placeholder values in documentation; never hardcode real credentials
-- **Agent mode sandbox** — run Agent API with `allowed_domains` restriction when possible
-
-## Return
-
-- CLI commands issued and their output
-- screenshot paths
-- agent history (if Agent mode used)
-- verification pass/fail with evidence
-- remaining risks (flaky selectors, auth issues, CAPTCHAs)