#10367: CLI/Ops: resilient browser fill + failover hardening + operations templates
docs
app: macos
cli
agents
stale
Cluster:
Browser Enhancements and Fixes
## Summary
This PR delivers reliability and operational guardrails in five areas:
1. Auth failover reliability
- Better failover reason resolution when all profiles are unavailable.
- Repeated auth failures now open a temporary auth circuit (profile disable) rather than repeated short cooldown loops.
- Improved failover messaging with explicit reconfiguration hint.
2. Browser stale target resilience
- `ensureTabAvailable` now recovers stale/invalid `targetId` when exactly one usable tab exists for all drivers (not only extension profiles).
- Added regression test for openclaw-driver behavior.
3. Tool input safety (`read`)
- Added preflight guard for directory paths to prevent downstream `EISDIR` failures.
- Improved malformed `read` diagnostics with expected argument shape.
4. Config version drift guardrail
- Added strict mode: when `OPENCLAW_STRICT_CONFIG_VERSION=1`, future-written config versions fail validation instead of warn-only.
- Added compat test coverage.
5. Operations documentation scaffolding
- Added standardized operations templates for status, backlog, and session reports:
- `docs/operations/STATUS_TEMPLATE.md`
- `docs/operations/OPERATIONS_BACKLOG_TEMPLATE.md`
- `docs/operations/SESSION_TEMPLATE.md`
- `docs/operations/README.md`
Also includes previously committed CLI browser improvement in this branch:
- label-based `openclaw browser fill` descriptors (`type + label + value`) with snapshot-based ref resolution.
## Files
Core reliability:
- `src/agents/pi-embedded-runner/run.ts`
- `src/agents/auth-profiles/usage.ts`
- `src/browser/server-context.ts`
- `src/agents/pi-tools.read.ts`
- `src/config/io.ts`
- `src/agents/pi-embedded-subscribe.handlers.tools.ts`
Tests:
- `src/agents/auth-profiles/usage.test.ts`
- `src/browser/server-context.ensure-tab-available.prefers-last-target.test.ts`
- `src/agents/pi-tools.read.test.ts`
- `src/config/io.compat.test.ts`
- `src/cli/browser-cli-actions-input/shared.test.ts`
Docs:
- `docs/operations/*`
## Validation
Executed locally:
- `pnpm vitest run src/config/io.compat.test.ts src/browser/server-context.ensure-tab-available.prefers-last-target.test.ts src/agents/pi-tools.read.test.ts src/agents/auth-profiles/usage.test.ts`
- `pnpm tsgo`
- `pnpm oxlint --type-aware` on changed files
- `pnpm oxfmt --check` on changed files
All passed.
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
- Adds stricter auth-profile failover handling (including auth “circuit” disable after repeated failures) and improves failover messaging.
- Makes `ensureTabAvailable` recover from stale/invalid `targetId` when only one usable tab exists, and adds regression coverage.
- Wraps the `read` tool to fail fast on directory paths and improves malformed-argument diagnostics.
- Introduces strict config version validation via `OPENCLAW_STRICT_CONFIG_VERSION` and adds compatibility tests.
- Adds operations documentation templates under `docs/operations/`.
<h3>Confidence Score: 4/5</h3>
- Mostly safe to merge, with one docs formatting issue to fix.
- Core code changes are small and covered by targeted tests; the main concrete problem found is a malformed markdown table in the new operations backlog template.
- docs/operations/OPERATIONS_BACKLOG_TEMPLATE.md
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#23363: Browser: fallback to managed profile and improve runtime diagnostics
by isdoho · 2026-02-22
82.0%
#15050: fix: transcript corruption resilience — strip aborted tool_use bloc...
by yashchitneni · 2026-02-12
80.4%
#11048: fix: address repository issues (env, author, CI comments, security ...
by cavula · 2026-02-07
79.7%
#7085: test: skip flaky workspace-paths & safe-bins tests on non-Linux/CI ...
by ThinkIbrokeIt · 2026-02-02
79.7%
#21589: Post-Performance Roadmap: Milestones A–D (contracts, observability,...
by Doji-Hammer · 2026-02-20
79.4%
#14368: fix: skip auth profile cooldown on format errors to prevent provide...
by koatora20 · 2026-02-12
79.1%
#7252: docs: align config examples and tool docs with current runtime
by nice-and-precise · 2026-02-02
79.0%
#10894: Docs: fix legacy branding, add config reference, expand cron troubl...
by biv0711 · 2026-02-07
78.6%
#11602: fix(config): skip stale legacy config files when openclaw.json exists
by akoscz · 2026-02-08
78.6%
#13881: fix: Address Greptile feedback - test isolation and channel resolution
by trevorgordon981 · 2026-02-11
78.5%