oh-my-opencode 4.19.4 → 5.0.0-beta.1

package/dist/shared/tmux/constants.d.ts

@@ -1 +1 @@
-export { POLL_INTERVAL_BACKGROUND_MS, SESSION_MISSING_GRACE_MS, SESSION_READY_POLL_INTERVAL_MS, SESSION_READY_TIMEOUT_MS, SESSION_TIMEOUT_MS, } from "@oh-my-opencode/tmux-core";
+export { AUTO_ACTIVATE_GRACE_MS, POLL_INTERVAL_BACKGROUND_MS, SESSION_MISSING_GRACE_MS, SESSION_READY_POLL_INTERVAL_MS, SESSION_READY_TIMEOUT_MS, SESSION_TIMEOUT_MS, } from "@oh-my-opencode/tmux-core";

package/dist/skills/ast-grep/SOURCE

@@ -1 +1 @@
-upstream: https://github.com/code-yeongyu/ast-grep-skill @ 3148c69 (ast-grep 0.43.0). Vendored as a sync; do not fork-drift.
+upstream: https://github.com/code-yeongyu/ast-grep-skill @ 3148c69 (ast-grep 0.45.0). Vendored as a sync; do not fork-drift.

package/dist/skills/ast-grep/install.ps1

@@ -21,7 +21,7 @@
   Force one method: scoop | winget | choco | npm | cargo | pip | github
 
 .PARAMETER Version
-  Pin a specific version when downloading from GitHub. Default: 0.43.0
+  Pin a specific version when downloading from GitHub. Default: 0.45.0
 
 .PARAMETER NoFallback
   Don't fall back to GitHub zip; fail if all package managers miss
@@ -37,7 +37,7 @@
 
 param(
     [string]$Method = "",
-    [string]$Version = "0.43.0",
+    [string]$Version = "0.45.0",
     [switch]$NoFallback,
     [switch]$Quiet
 )

package/dist/skills/ast-grep/install.sh

@@ -33,7 +33,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 SKILL_ROOT="$SCRIPT_DIR"
 CACHE_BIN_DIR="${OMO_AST_GREP_BIN_DIR:-$SKILL_ROOT/bin}"
 
-PINNED_VERSION="0.43.0"
+PINNED_VERSION="0.45.0"
 FORCED_METHOD=""
 USE_FALLBACK=1
 QUIET=0

package/dist/skills/ast-grep/references/install.md

@@ -94,7 +94,7 @@ If every package manager fails:
 #      app-aarch64-pc-windows-msvc.zip       Windows ARM64
 
 # 2. Download and extract:
-VERSION=0.43.0
+VERSION=0.45.0
 TRIPLE=aarch64-apple-darwin
 curl -fsSL "https://github.com/ast-grep/ast-grep/releases/download/${VERSION}/app-${TRIPLE}.zip" -o /tmp/ast-grep.zip
 unzip /tmp/ast-grep.zip -d /tmp/ast-grep
@@ -125,7 +125,7 @@ Requires Rust 1.74+. Slowest path; only useful when you need a specific commit o
 
 ```bash
 ast-grep --version            # or `sg --version`
-# ast-grep 0.43.0
+# ast-grep 0.45.0
 ```
 
 Then sanity-check a real query:

package/dist/skills/ast-grep/tests/smoke.sh

@@ -49,7 +49,7 @@ fake_sg() {
   cat > "$target" <<'SH'
 #!/usr/bin/env bash
 if [ "${1:-}" = "--version" ]; then
-  printf 'ast-grep 0.43.0 fake\n'
+  printf 'ast-grep 0.45.0 fake\n'
 else
   printf 'fake ast-grep\n'
 fi

package/dist/skills/start-work/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: start-work
-description: "Execute a Prometheus work plan in Codex with Boulder state, evidence ledger updates, worktree discipline, parallel subagents, and Stop-hook continuation. Use after planning when the user says start work, execute plan, continue plan, resume plan, or asks to run a .omo/plans plan."
+description: "Execute a Prometheus work plan with Boulder state, evidence ledger updates, worktree discipline, parallel subagents, and Stop-hook continuation. Use after planning when the user says start work, execute plan, continue plan, resume plan, or asks to run a .omo/plans plan."
 ---
 
 ## ABSOLUTE RULE: YOU ARE AN ORCHESTRATOR — NEVER THE IMPLEMENTER
@@ -22,8 +22,8 @@ When translating `load_skills=[...]`, name the skills inside the spawned agent's
 
 Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. On the v2 surface `agent_type` may be absent from the spawn schema — when absent, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
-### Delegation by difficulty (Codex tier workers)
-When tier worker agents are installed (Codex), size each implementation lane by difficulty and pass the matching `agent_type` where the spawn schema exposes it: LOW (one-file fix, boilerplate, config/copy) -> `lazycodex-worker-low`; MEDIUM (standard feature, few files, known patterns) -> `lazycodex-worker-medium`; HIGH (new module, cross-module refactor, concurrency/security/migration) -> `lazycodex-worker-high`. Explorer/librarian research lanes keep their own roles. Difficulty (model power) is orthogonal to the LIGHT/HEAVY rigor tier in step 4 — judge each on its own facts. On spawn surfaces without `agent_type` (deployed v2), state the tier inside `message`.
+### Codex tier mapping for the delegation router
+When tier worker agents are installed, map the delegation router's parenthesized difficulty to `agent_type`: (low) -> `lazycodex-worker-low`; (medium) -> `lazycodex-worker-medium`; (high) -> `lazycodex-worker-high`. Explorer/librarian research lanes keep their own roles. On spawn surfaces without `agent_type`, state the tier inside `message`. Difficulty (model power) is orthogonal to the LIGHT/HEAVY rigor tier in step 4 — judge each on its own facts.
 
 ## Codex Subagent Reliability
 
@@ -33,7 +33,7 @@ Plan and reviewer agents may run for a long time: spawn them in the background a
 
 # start-work
 
-Execute a Prometheus work plan until every top-level checkbox is complete. This skill pairs with the Codex `Stop` / `SubagentStop` continuation hook (`components/start-work-continuation`), which re-injects the next turn while `.omo/boulder.json` says this `codex:<session_id>` still has unchecked plan work.
+Execute a Prometheus work plan until every top-level checkbox is complete. This skill pairs with the harness's start-work continuation hook, which re-injects the next turn while `.omo/boulder.json` says this `codex:<session_id>` still has unchecked plan work.
 
 ## Usage
 
@@ -97,14 +97,58 @@ Write `.omo/boulder.json` before implementation starts. Prefix session ids with
 
 For PR/branch work, a task-owned worktree is mandatory before implementation starts: pass `--worktree`, or use `--make-pr`/`--ship`, which auto-create one. Verify the path with `git worktree list --porcelain` or create it with `git worktree add <path> <branch-or-HEAD>`, then store the absolute path as `worktree_path`. All edits, commands, tests, and evidence capture must run inside that worktree.
 
+## Parallel delivery lanes (teams and worktrees)
+
+Solo orchestration with parallel background workers is the default topology. Decide once, when the wave's lanes are known, and record the verdict in the ledger:
+
+- **Independent lanes -> parallel workers.** Separate files, no shared contract: one parallel spawn burst; no team.
+- **Overlapping lanes -> a team.** The lanes touch the same module or contract AND running them concurrently actually finishes sooner: stand up a team (where the harness has one) so one lane's discoveries relay through you mid-flight.
+- **PR-mode independent lanes -> a worktree per lane.** Under `--make-pr`/`--ship`, when a wave holds independent checkboxes, give each lane its own branch and task-owned worktree, delivered as its own PR.
+
+Landing rules, regardless of topology:
+
+- **Merge per verified unit.** A lane lands the moment its own gates pass — it never waits for the slowest sibling. Integrate landed work back into the base the remaining lanes branch from.
+- **Only the orchestrator merges.** Workers and team members never merge and never push the base branch.
+- **Conflicts are the orchestrator's job.** Decide the landing order and tell the later lane what changed; a worker never resolves a sibling's conflict blind.
+
 ## Phase 3: Execute the next checkbox
 
 1. Read the full selected plan.
 2. Find the first unchecked column-0 checkbox in `## TODOs` or `## Final Verification Wave`.
 3. Ignore nested checkboxes under acceptance criteria, evidence, and definition-of-done sections.
 4. Classify the checkbox tier and record it in its ledger entry. Default is LIGHT — a narrow change inside existing layers. Take HEAVY only on a fact you can point to: a new module / abstraction / domain model; auth, security, or session; an external integration; a DB schema or migration; concurrency or transaction boundaries; a cross-domain refactor; or the plan or user signals care. When unsure, take HEAVY; upgrade and redo skipped gates the moment a HEAVY fact surfaces; never downgrade.
-5. Decompose that checkbox into atomic sub-tasks. Collect every other unchecked checkbox in the same plan wave whose dependencies are met — their lanes execute concurrently.
-6. **DELEGATE EVERYTHING. YOU NEVER IMPLEMENT.** Dispatch ALL independent sub-tasks across those checkboxes in one parallel `multi_agent_v1.spawn_agent` burst; serialize only named dependencies. Verification and checkbox marking stay per-checkbox.
+5. Decompose that checkbox into atomic sub-tasks sized for ONE worker in ONE run — a sub-task that would need mid-flight steering is two sub-tasks. Collect every other unchecked checkbox in the same plan wave whose dependencies are met — their lanes execute concurrently. A wave that could split further but holds fewer than 3 independent sub-tasks is under-split.
+6. **DELEGATE EVERYTHING. YOU NEVER IMPLEMENT.** Route every sub-task through the delegation router below, then dispatch ALL independent sub-tasks across those checkboxes in one parallel worker-spawn burst (a single batched spawn call where the harness supports it); serialize only named dependencies. Verification and checkbox marking stay per-checkbox.
+7. Give every dispatched sub-task its completion condition and watch for it per the section below. A dispatch whose completion nobody watches is an unfinished dispatch.
+
+### Monitor every dispatched subagent to its completion condition
+
+A spawned worker is not fire-and-forget. For EACH subagent in the burst, name the observable state that ends its lane — the file written, the PR opened, the checkbox's gates green — and put a watcher on THAT state, never on a clock.
+
+- **Arm one watcher per lane, at spawn time.** The worker's own completion arrives on its own as an injected notification; arm an explicit `monitor` on top of it only when the lane's completion condition lives OUTSIDE the child's final message — CI turning green, a log line, a build artifact appearing, a branch landing. Watch the state itself (`monitor` with a command that exits or emits on that condition), and keep the burst's watchers distinct so one lane firing never reads as another's.
+- **NEVER poll and NEVER sleep.** No `sleep`, no timed retry loop, no re-reading the same status hoping it changed. Between waves, do independent root work or end the turn; an idle session is always woken. A single `task_output({ mode: "tail" })` peek is allowed only when a midpoint decision genuinely depends on it.
+- **Tear the watcher down the instant it resolves.** The moment a monitor fires, or you discover it was armed on the WRONG condition (it watches a path the lane never touches, a pattern that can never match, a lane you already cancelled), stop it with `kill_bash` and say so in the ledger. A stale watcher re-fires on unrelated output and corrupts the next wave's verdict.
+- **Then advance.** Fired watcher plus verified evidence means that lane's gates run and its checkbox closes; a mis-set watcher means re-arm it on the right condition or drop it, and continue. Never let a dead watcher hold the run open, and never treat watcher silence as a pass.
+
+### Delegation router — recommended task executor category
+
+When the plan annotates a todo with `Recommended task executor category:`, follow that annotation; deviate only for a reason recorded in the ledger entry. Otherwise route by shape, in the omo category vocabulary (category-capable harnesses pass it directly on the worker-spawn tool, e.g. `task(category="quick", ...)`; others map the parenthesized difficulty):
+
+| Category | Route here |
+| --- | --- |
+| `quick` (low) | mechanical, single-file, boilerplate, config/copy — the default for every splittable piece |
+| `unspecified-low` (low) | small tasks that fit no other category |
+| `unspecified-high` (medium) | standard features across a few files with known patterns |
+| `visual-engineering` (medium) | frontend, UI/UX, styling, animation |
+| `writing` (low) | documentation and prose |
+| `git` (low) | git operations |
+| `deep` (high) | hairy debugging, research-heavy or subtle cross-module work |
+| `ultrabrain` (high) | ONE genuinely hard, logic-heavy problem — hand it the goal, not step-by-step instructions |
+
+Sizing is a two-branch decision made per checkbox, before dispatch:
+
+- **Splittable work splits.** When the checkbox decomposes into independent pieces, dispatch them as a swarm of `quick`/`unspecified-low` workers in ONE parallel burst — many small cheap workers in parallel beat one large delegation.
+- **Cohesive hard work stays whole.** When splitting would sever shared reasoning (one algorithm, one migration, one subtle bug), send the WHOLE problem to `deep` or `ultrabrain` as ONE delegation. Never force-split work whose parts share one insight.
 
 Each sub-task message must include:
 
@@ -115,11 +159,12 @@ Each sub-task message must include:
 5. One Manual-QA channel, named with the exact tool and exact invocation (the literal `curl`, `send-keys`, `browser:control-in-app-browser` action, `page.click`, payload, selectors, and the binary observable that decides PASS/FAIL), not "verify it works". A LIGHT checkbox needs one real-surface proof of its deliverable, and auxiliary surfaces (CLI stdout, DB state diff, parsed config dump) are first-class when the surface is CLI- or data-shaped:
    - HTTP call: `curl -i` against the live endpoint.
    - Terminal / TUI: drive a real pty; `tmux send-keys` is fine for a boot/behavior smoke, but color/layout/CJK evidence goes through the xterm.js web terminal below, NEVER `tmux capture-pane`.
-   - Browser use: in Codex, use `browser:control-in-app-browser` first when available and the scenario does not need an authenticated or persistent user browser profile; otherwise drive the real page with Chrome, or agent-browser (https://github.com/vercel-labs/agent-browser) when Chrome is unavailable.
+   - Browser use: prefer the harness's in-app browser control when available and the scenario does not need an authenticated or persistent user browser profile; otherwise drive the real page with Chrome, or agent-browser (https://github.com/vercel-labs/agent-browser) when Chrome is unavailable.
    - Computer use: OS-level GUI automation against the running desktop app when the surface is not a page.
    - TUI visual evidence: when a TUI claim needs visual QA or PR proof, run `node script/qa/web-terminal-visual-qa.mjs --command "<cmd>" --input "{Enter}" --evidence-dir <dir>` (real pty rendered through xterm.js in Chrome) and attach `terminal.png` plus `metadata.json`.
 6. The adversarial classes that apply to this sub-task (from the 9 ultraqa classes) and how each is probed.
 7. Required artifact path and cleanup receipt.
+8. Tool-use expectations: batch independent tool calls in parallel; when the harness exposes a code-execution surface (eval), use it for multi-call steps instead of one-by-one calls.
 
 The 9 ultraqa classes are trigger-mapped: new input parsing → malformed input; untrusted external text → prompt injection; resumable or long-running flows → cancel/resume; generated or cached artifacts → stale state; uncommitted user files in scope → dirty worktree; long external commands → hung or long commands; new or timing-sensitive tests → flaky tests; log-based success claims → misleading success output; mid-operation interrupts → repeated interruptions. A class applies when its trigger fact holds. Probe each applicable class; record the rest as not-applicable with a one-line reason.
 
@@ -160,7 +205,7 @@ A worker done claim is never final: each implementation sub-task returns a `Done
 
 Rules:
 - `confirmed` is the only pass verdict. `false-positive`, `needs-fix`, and `needs-human-review` all block checkbox completion.
-- The verifier must be independent from the executor: use `lazycodex-gate-reviewer`, a scoped `worker` reviewer, or root only when root did not implement or materially rewrite that task.
+- The verifier must be independent from the executor: use the harness's gate reviewer (see the harness compatibility section) or a fresh reviewer worker on a strong model, or root only when root did not implement or materially rewrite that task.
 - A worker done claim must be independently verified before it becomes checkbox completion.
 - On any non-confirmed verdict, append the feedback to the ledger, reset the checkbox work to in-progress, and re-dispatch the executor with the exact failure.
 - The verifier must probe the applicable adversarial keys, including `stale_state`, `dirty_worktree`, and `misleading_success_output`, before allowing `FullyDone`.
@@ -191,5 +236,5 @@ When all top-level checkboxes in `## TODOs` and `## Final Verification Wave` are
 - **NO DIRECT IMPLEMENTATION BY THE ORCHESTRATOR.** Root NEVER edits product files, writes tests, or runs QA itself — a spawned worker does.
 - No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.
 - No PR/branch implementation, review, or merge in the main worktree; use the task-owned git worktree.
-- No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.
+- No unprefixed session ids in Boulder state. Sessions are always recorded as `codex:<session_id>`.
 - No stale-memory execution. The plan and ledger are the durable source of truth.

package/dist/skills/ultimate-browsing/SKILL.md

@@ -37,7 +37,7 @@ Read the matching reference before acting: [`references/insane-search/README.md`
 ## Tier 1 — insane-search (headless extraction)
 
 **When**: content extraction, blocked-URL bypass, media metadata — no browser UI needed.
-**Why first**: ~10x faster than a browser, no process spin-up; handles most "fetch this blocked page" requests via curl_cffi TLS impersonation, yt-dlp (1858 sites), Jina Reader, official public APIs, mobile URL transforms, and a Playwright real-Chrome fallback. The engine lives **inside this skill** at `engine/` and is invoked as a module.
+**Why first**: ~10x faster than a browser, no process spin-up; handles most "fetch this blocked page" requests via curl_cffi TLS impersonation, yt-dlp (1858 sites), official public APIs, mobile URL transforms, **Phase-2.5 surrogate archives** (Wayback / archive.today snapshots, provenance-tagged — see [`references/insane-search/cache-archive.md`](references/insane-search/cache-archive.md)), a key-gated Jina Reader (`JINA_API_KEY`), and a Playwright real-Chrome fallback. The engine lives **inside this skill** at `engine/` and is invoked as a module. Surrogate results are dated COPIES: a result whose `provenance` is `snapshot` must be reported with its `snapshot_timestamp`, never presented as the live page.
 
 ```bash
 # Core command — auto-detects WAF, runs the full fetch grid (run from the skill dir):
@@ -60,7 +60,7 @@ The full engine harness (rules R1-R7, the Phase 0 official-API index, the no-sit
 
 ## Tier 1.5 — agent-reach (platform-native readers)
 
-**When**: the target is a platform with a first-class API/CLI that beats generic fetching — especially Chinese platforms that stealth browsers still cannot reach cleanly. Several channels are zero-config (Douyin, Weibo via Jina, V2EX, Reddit, Jina Reader, RSS, YouTube); others need a one-time auth you supply via environment variables if you have access.
+**When**: the target is a platform with a first-class API/CLI that beats generic fetching — especially Chinese platforms that stealth browsers still cannot reach cleanly. Several channels are zero-config (Douyin, V2EX, Reddit, RSS, YouTube); others need a one-time auth you supply via environment variables if you have access (`JINA_API_KEY` for Jina Reader — anonymous access is dead, see `references/insane-search/jina.md`; `TWITTER_*` for X; a transcription key for podcasts).
 
 | Category | Platforms | Entry |
 |---|---|---|

package/dist/skills/ultimate-browsing/engine/__main__.py

@@ -39,6 +39,10 @@ def build_parser() -> argparse.ArgumentParser:
                    help="Upper bound across all phases (default 12).")
     p.add_argument("--no-playwright", action="store_true",
                    help="Skip Playwright fallback (curl-only).")
+    p.add_argument("--allow-proxy", action="store_true",
+                   help=("Enable kind=proxy surrogate entries (raw relay routes; "
+                        "MITM by construction — never citable alone, never "
+                        "receives cookies/auth headers). Off by default."))
     p.add_argument("--json", action="store_true",
                    help="Emit FetchResult as JSON to stdout (content omitted).")
     p.add_argument("--trace", action="store_true",
@@ -56,6 +60,7 @@ def main(argv: list[str] | None = None) -> int:
             timeout=args.timeout,
             max_attempts=args.max_attempts,
             enable_playwright=not args.no_playwright,
+            allow_surrogate_proxy=args.allow_proxy,
         )
     except Exception as e:
         print(f"engine fatal: {type(e).__name__}: {e}", file=sys.stderr)
@@ -96,7 +101,9 @@ def main(argv: list[str] | None = None) -> int:
         # Default: HTML to stdout, status to stderr.
         print(result.content, end="")
         print(f"\n[engine] ok={result.ok} verdict={result.verdict} "
-              f"profile={result.profile_used} attempts={len(result.trace)}",
+              f"profile={result.profile_used} attempts={len(result.trace)} "
+              f"provenance={result.provenance}"
+              + (f" snapshot_ts={result.snapshot_timestamp}" if result.snapshot_timestamp else ""),
               file=sys.stderr)
 
     return 0 if result.ok else 1

package/dist/skills/ultimate-browsing/engine/bias_check.py

@@ -54,6 +54,14 @@ URL_ALLOWLIST = {
     "www.google.com", "google.com",
     # Generic HTTP test endpoint for infrastructure / transport tests.
     "httpbin.org",
+    # Surrogate-tier infrastructure (engine/surrogates.yaml): archives/relays
+    # that serve a copy of ANY target URL. Same no-site-preference category as
+    # the google.com Referer — they are not target sites.
+    "archive.org", "web.archive.org",
+    "r.jina.ai",
+    # Placeholder host in the proxy-entry shape example; "canonical non-routable
+    # doc domain" (.invalid TLD), can never be a real target.
+    "relay.invalid",
 }
 
 # Files / dirs that must be clean.
@@ -80,6 +88,9 @@ EXPLICIT_ALLOW_FILES = {
     # None right now — add if needed with justification.
 }
 
+# NOTE-BIAS-OK convention for surrogate tests: fixture URLs (stub/interstitial
+# captures from third-party services) carry the marker on the flagged line.
+
 
 def _line_is_exempt(line: str, ext: str) -> bool:
     markers = COMMENT_OK_MARKERS.get(ext, ())

package/dist/skills/ultimate-browsing/engine/fetch_chain.py

@@ -40,6 +40,7 @@ def fetch(
     timeout: int = 25,
     max_attempts: int = 12,
     enable_playwright: bool = True,   # hook left for executor module
+    allow_surrogate_proxy: bool = False,  # opt-in: kind=proxy registry entries
 ) -> FetchResult:
     """Fetch `url` using the generic grid.
 
@@ -175,73 +176,110 @@ def fetch(
                     if att.verdict in (Verdict.STRONG_OK.value, Verdict.WEAK_OK.value):
                         return _build_result(resp, att, trace, profile_used=profile_id)
 
-    # -------- Phase 3: Playwright fallback (profile-driven order) -----------
-    if enable_playwright:
-        try:
-            from .executor import run_playwright_fallback  # lazy import
-            # Honour profile's `fallback_when_challenge` list — iterate the
-            # caller-declared order instead of capability-inferred single pick.
-            fb_profile = load_profile(profile_used or "unknown_challenge", profiles=profiles)
-            fb_order = fb_profile.get("fallback_when_challenge") or ["playwright_real_chrome"]
-            pw_attempt = None
-            pw_content = ""
-            for fb_name in fb_order:
-                if fb_name == "curl_grid_exhaust":
-                    # Already performed in Phase 2; nothing more to do here.
-                    continue
-                pw_attempt, pw_content = run_playwright_fallback(
+    # -------- Phase 2.5 + 3: fallback ladder (profile-driven order) ---------
+    # Surrogate routes are NOT browser work, so they run even when the caller
+    # disabled Playwright; only browser executors honour `enable_playwright`.
+    try:
+        # Honour profile's `fallback_when_challenge` list — iterate the
+        # caller-declared order instead of capability-inferred single pick.
+        fb_profile = load_profile(profile_used or "unknown_challenge", profiles=profiles)
+        fb_order = fb_profile.get("fallback_when_challenge") or ["playwright_real_chrome"]
+        pw_attempt = None
+        pw_content = ""
+        for fb_name in fb_order:
+            if fb_name == "curl_grid_exhaust":
+                # Already performed in Phase 2; nothing more to do here.
+                continue
+            if fb_name.startswith("surrogate_"):
+                # Phase 2.5: archive/reader/proxy routes serving a copy of
+                # the target. Cheaper than a browser; provenance-labeled.
+                from . import surrogate as surrogate_mod
+                s_atts, s_meta, s_content = surrogate_mod.run_surrogate(
                     url,
-                    profile_id=profile_used or "unknown_challenge",
+                    registry=surrogate_mod.load_surrogates(),
+                    allow_proxy=allow_surrogate_proxy,
+                    timeout=timeout,
                     success_selectors=success_selectors,
-                    device_class=device_class,
-                    force_executor=fb_name,
                 )
-                trace.append(pw_attempt)
-                if pw_attempt.verdict in (Verdict.STRONG_OK.value, Verdict.WEAK_OK.value):
+                trace.extend(s_atts)
+                s_att = s_atts[-1]
+                if s_att.verdict in (Verdict.STRONG_OK.value, Verdict.WEAK_OK.value):
                     return FetchResult(
                         ok=True,
-                        content=pw_content,
-                        final_url=pw_attempt.url,
-                        verdict=pw_attempt.verdict,
+                        content=s_content,
+                        final_url=s_att.url,
+                        verdict=s_att.verdict,
                         profile_used=profile_used,
                         trace=trace,
-                        summary=f"Playwright fallback succeeded via {fb_name}",
+                        summary=(
+                            f"surrogate {s_meta.get('surrogate')} succeeded"
+                            f" (provenance={s_meta.get('provenance')}"
+                            + (f" snapshot_ts={s_meta.get('snapshot_timestamp')})" if s_meta.get('snapshot_timestamp') else ")")
+                        ),
+                        provenance=str(s_meta.get("provenance", "live")),
+                        snapshot_timestamp=s_meta.get("snapshot_timestamp"),
+                        trust=str(s_meta.get("trust", "origin")),
                     )
-            # Synthesize a placeholder if no iteration ran (empty list).
-            if pw_attempt is None:
-                pw_attempt = Attempt(
-                    phase="fallback",
-                    executor="none",
-                    url=url,
-                    url_transform="original",
-                    impersonate=None,
-                    referer="",
-                    verdict=Verdict.UNKNOWN.value,
-                    error="profile has empty fallback_when_challenge",
+                continue
+            if not enable_playwright:
+                continue
+            from .executor import run_playwright_fallback  # lazy import
+            pw_attempt, pw_content = run_playwright_fallback(
+                url,
+                profile_id=profile_used or "unknown_challenge",
+                success_selectors=success_selectors,
+                device_class=device_class,
+                force_executor=fb_name,
+            )
+            trace.append(pw_attempt)
+            if pw_attempt.verdict in (Verdict.STRONG_OK.value, Verdict.WEAK_OK.value):
+                return FetchResult(
+                    ok=True,
+                    content=pw_content,
+                    final_url=pw_attempt.url,
+                    verdict=pw_attempt.verdict,
+                    profile_used=profile_used,
+                    trace=trace,
+                    summary=f"Playwright fallback succeeded via {fb_name}",
                 )
-                trace.append(pw_attempt)
-        except ImportError:
-            trace.append(Attempt(
+        # Synthesize a placeholder only when the profile genuinely offers no
+        # fallback route. Entries skipped because the caller disabled the
+        # browser are a caller choice, not a profile defect — no trace noise.
+        actionable = [n for n in fb_order if n != "curl_grid_exhaust"]
+        if pw_attempt is None and not actionable:
+            pw_attempt = Attempt(
                 phase="fallback",
-                executor="playwright",
+                executor="none",
                 url=url,
                 url_transform="original",
                 impersonate=None,
                 referer="",
                 verdict=Verdict.UNKNOWN.value,
-                error="executor module not available",
-            ))
-        except (RuntimeError, OSError) as e:
-            trace.append(Attempt(
-                phase="fallback",
-                executor="playwright",
-                url=url,
-                url_transform="original",
-                impersonate=None,
-                referer="",
-                verdict=Verdict.UNKNOWN.value,
-                error=f"{type(e).__name__}:{str(e)[:200]}",
-            ))
+                error="profile has empty fallback_when_challenge",
+            )
+            trace.append(pw_attempt)
+    except ImportError:
+        trace.append(Attempt(
+            phase="fallback",
+            executor="playwright",
+            url=url,
+            url_transform="original",
+            impersonate=None,
+            referer="",
+            verdict=Verdict.UNKNOWN.value,
+            error="executor module not available",
+        ))
+    except (RuntimeError, OSError) as e:
+        trace.append(Attempt(
+            phase="fallback",
+            executor="playwright",
+            url=url,
+            url_transform="original",
+            impersonate=None,
+            referer="",
+            verdict=Verdict.UNKNOWN.value,
+            error=f"{type(e).__name__}:{str(e)[:200]}",
+        ))
 
     # -------- Give up, return best we have ----------------------------------
     summary = format_summary(trace, profile_used)

package/dist/skills/ultimate-browsing/engine/result_schema.py

@@ -1,7 +1,10 @@
 from __future__ import annotations
 
 from dataclasses import asdict, dataclass, field
-from typing import Optional
+from typing import Literal, Optional
+
+Provenance = Literal["live", "snapshot", "proxy"]
+Trust = Literal["origin", "archive", "untrusted"]
 
 
 @dataclass
@@ -32,6 +35,9 @@ class FetchResult:
     profile_used: Optional[str] = None
     trace: list[Attempt] = field(default_factory=list)
     summary: str = ""
+    provenance: str = "live"                       # live | snapshot | proxy
+    snapshot_timestamp: Optional[str] = None      # archive's own timestamp, when snapshot
+    trust: str = "origin"                         # origin | archive | untrusted
 
     def to_dict(self) -> dict:
         return {
@@ -41,5 +47,8 @@ class FetchResult:
             "profile_used": self.profile_used,
             "trace": [a.to_dict() for a in self.trace],
             "summary": self.summary,
+            "provenance": self.provenance,
+            "snapshot_timestamp": self.snapshot_timestamp,
+            "trust": self.trust,
             "content_length": len(self.content),
         }