ultimate-pi 0.18.1 → 0.19.1

package/.pi/scripts/harness-verify.mjs

@@ -5,7 +5,7 @@
 
 import { readFile, access } from "node:fs/promises";
 import { constants } from "node:fs";
-import { join, dirname, resolve } from "node:path";
+import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 
@@ -42,6 +42,10 @@ const REQUIRED_ADRS = [
 	"0037-subagent-submit-tools.md",
 	"0038-budget-telemetry-only.md",
 	"0040-practice-grounded-orchestration.md",
+	"0045-harness-lens-minimal-contract.md",
+	"0046-agt-policy-engine.md",
+	"0047-agt-layered-security.md",
+	"0048-tool-call-hook-order.md",
 ];
 
 const REQUIRED_EXTENSIONS = [
@@ -148,32 +152,59 @@ async function checkSentruxRules() {
 	ok(".sentrux/rules.toml present");
 }
 
-async function checkModelRouterThinkingOnly() {
-	const path = join(ROOT, ".pi", "model-router.json");
-	if (!(await fileExists(path))) {
-		ok("model-router.json absent (skip thinking-only tier check)");
-		return;
+async function checkHarnessLens(pkgJson) {
+	if (!pkgJson.files?.includes(".pi/lib/harness-lens")) {
+		fail(
+			'package.json "files" must include .pi/lib/harness-lens (npm publish ships harness lens extension)',
+		);
 	}
-	let raw;
-	try {
-		raw = JSON.parse(await readFile(path, "utf-8"));
-	} catch {
-		fail("invalid .pi/model-router.json");
-	}
-	const profiles = raw.profiles ?? {};
-	for (const [name, profile] of Object.entries(profiles)) {
-		const high = profile?.high?.model;
-		const medium = profile?.medium?.model;
-		const low = profile?.low?.model;
-		if (
-			!(high && medium && low && high === medium && medium === low)
-		) {
-			fail(
-				`model-router profile "${name}" must use the same model on high/medium/low (thinking-only tiers)`,
-			);
-		}
+	ok('package.json files includes .pi/lib/harness-lens');
+
+	const piExtensions = pkgJson.pi?.extensions ?? [];
+	if (!piExtensions.includes("./.pi/extensions")) {
+		fail('package.json pi.extensions must include ./.pi/extensions');
+	}
+	if (piExtensions.includes("./vendor/pi-lens/index.ts")) {
+		fail('package.json pi.extensions must not load vendor/pi-lens directly');
+	}
+	ok("package.json loads harness extension directory");
+
+	const harnessLens = join(ROOT, ".pi", "extensions", "harness-lens.ts");
+	if (!(await fileExists(harnessLens))) fail("missing .pi/extensions/harness-lens.ts");
+	ok("harness lens extension wrapper");
+
+	const lensIndex = join(ROOT, ".pi", "lib", "harness-lens", "index.ts");
+	if (!(await fileExists(lensIndex))) {
+		fail("missing .pi/lib/harness-lens/index.ts");
+	}
+	ok(".pi/lib/harness-lens/index.ts");
+
+	const legacyExtLib = join(ROOT, ".pi", "extensions", "lib");
+	if (await fileExists(legacyExtLib)) {
+		fail(".pi/extensions/lib must not exist (shared code lives in .pi/lib/)");
+	}
+	ok("no legacy .pi/extensions/lib directory");
+
+	const lensIndexSource = await readFile(lensIndex, "utf8");
+	if (lensIndexSource.includes("ast_grep_search")) {
+		fail("harness-lens index must not register ast_grep_search");
+	}
+	if (lensIndexSource.includes("lib/lens")) {
+		fail("harness-lens index must not import lib/lens");
 	}
-	ok("model-router.json thinking-only (same model per profile)");
+	ok("harness-lens index contract (no ast_grep, no lib/lens imports)");
+
+	const rulesDir = join(ROOT, ".pi", "lib", "harness-lens", "rules");
+	if (await fileExists(rulesDir)) {
+		fail("harness-lens bundled rules/ directory must not exist");
+	}
+	ok("no bundled harness-lens rules/ directory");
+
+	const upstreamPin = join(ROOT, ".pi", "lib", "harness-lens", "UPSTREAM_PIN.md");
+	if (await fileExists(upstreamPin)) {
+		fail("harness-lens UPSTREAM_PIN.md must not exist (harness-native, no upstream sync)");
+	}
+	ok("no harness-lens UPSTREAM_PIN.md");
 }
 
 async function checkSentruxGate() {
@@ -235,7 +266,7 @@ async function main() {
 		ok(`extension ${name}`);
 	}
 
-	const libPath = join(ROOT, ".pi", "extensions", "lib", "harness-posthog.ts");
+	const libPath = join(ROOT, ".pi", "lib", "harness-posthog.ts");
 	if (!(await fileExists(libPath))) fail("missing lib/harness-posthog.ts");
 	ok("lib/harness-posthog.ts");
 
@@ -246,6 +277,8 @@ async function main() {
 	const pkgJson = JSON.parse(
 		await readFile(join(ROOT, "package.json"), "utf-8"),
 	);
+	await checkHarnessLens(pkgJson);
+
 	if (!pkgJson.files?.includes("vendor/pi-subagents")) {
 		fail(
 			'package.json "files" must include vendor/pi-subagents (npm publish ships subagents vendor)',
@@ -263,13 +296,7 @@ async function main() {
 	if (!(await fileExists(subagentsVendor))) {
 		fail("missing vendor/pi-subagents/src/subagents.ts");
 	}
-	const bridgePath = join(
-		ROOT,
-		".pi",
-		"extensions",
-		"lib",
-		"harness-subagents-bridge.ts",
-	);
+	const bridgePath = join(ROOT, ".pi", "lib", "harness-subagents-bridge.ts");
 	if (!(await fileExists(bridgePath))) {
 		fail("missing harness-subagents-bridge.ts");
 	}
@@ -280,6 +307,14 @@ async function main() {
 	if (!bridgeSrc.includes("packageRoot")) {
 		fail("harness-subagents-bridge must pass packageRoot for agent discovery");
 	}
+	if (
+		!bridgeSrc.includes("subprocessGovernanceExtensionPath") &&
+		!bridgeSrc.includes("subagentGovernanceExtensionPath")
+	) {
+		fail(
+			"harness-subagents-bridge must set subprocessGovernanceExtensionPath for all subagents",
+		);
+	}
 	const subagentsSrc = await readFile(subagentsVendor, "utf-8");
 	if (!subagentsSrc.includes("discoverAgents")) {
 		fail("vendor subagents.ts must implement discoverAgents");
@@ -301,12 +336,46 @@ async function main() {
 	if (!policyGateSrc.includes('pi.on("tool_call", async (event, ctx)')) {
 		fail("policy-gate tool_call must receive ctx for run context");
 	}
-	if (!policyGateSrc.includes("evaluateContextModeMutation")) {
-		fail(
-			"policy-gate.ts must evaluate context-mode execute tools via evaluateContextModeMutation",
-		);
+	if (!policyGateSrc.includes("evaluateAgtHarnessToolCall")) {
+		fail("policy-gate.ts must delegate tool_call to AGT evaluateAgtHarnessToolCall");
 	}
-	ok("policy-gate plan-phase writes");
+	const govPath = join(ROOT, ".pi", "extensions", "subagent-governance.ts");
+	const govAlias = join(
+		ROOT,
+		".pi",
+		"extensions",
+		"harness-subagent-governance.ts",
+	);
+	if (!(await fileExists(govPath))) {
+		fail("missing subagent-governance.ts subprocess bundle");
+	}
+	if (!(await fileExists(govAlias))) {
+		fail("missing harness-subagent-governance.ts re-export alias");
+	}
+	ok("policy-gate + subprocess governance");
+
+	const agtDoctorPath = join(ROOT, ".pi", "scripts", "harness-agt-doctor.ts");
+	const { code: agtDoctorCode, out: agtDoctorOut } = await new Promise(
+		(resolve) => {
+			const child = spawn(
+				"npx",
+				["-y", "tsx", agtDoctorPath],
+				{ cwd: ROOT, stdio: ["ignore", "pipe", "pipe"], shell: true },
+			);
+			let out = "";
+			child.stdout?.on("data", (d) => {
+				out += d.toString();
+			});
+			child.stderr?.on("data", (d) => {
+				out += d.toString();
+			});
+			child.on("close", (code) => resolve({ code: code ?? 1, out }));
+		},
+	);
+	if (agtDoctorCode !== 0) {
+		fail(agtDoctorOut.trim() || "AGT policy doctor failed");
+	}
+	ok("AGT policy doctor");
 
 	const runCtxFixture = join(SMOKE, "run-context.fixture.json");
 	if (!(await fileExists(runCtxFixture))) {
@@ -332,7 +401,12 @@ async function main() {
 	ok("test-diff-golden.json");
 
 	await checkSentruxGate();
-	await checkModelRouterThinkingOnly();
+
+	const AGENTS_POLICY = join(ROOT, ".pi", "harness", "agents.policy.yaml");
+	if (!(await fileExists(AGENTS_POLICY))) {
+		fail("missing .pi/harness/agents.policy.yaml");
+	}
+	ok("agents.policy.yaml present");
 
 	if (!(await fileExists(AGENTS_MANIFEST))) {
 		fail(
@@ -350,9 +424,87 @@ async function main() {
 	}
 	ok("agents.manifest.json in sync");
 
+	await checkWrsContracts();
+
 	console.log("\nharness:verify PASS");
 }
 
+async function checkWrsContracts() {
+	const systemMd = join(ROOT, ".pi", "SYSTEM.md");
+	const toolsTs = join(ROOT, ".pi", "extensions", "harness-web-tools.ts");
+	const runCli = join(ROOT, ".pi", "lib", "harness-web", "run-cli.ts");
+	const webRetrievalSkill = join(ROOT, ".agents", "skills", "web-retrieval", "SKILL.md");
+	const adr = join(
+		ROOT,
+		".pi",
+		"harness",
+		"docs",
+		"adrs",
+		"0050-agentic-web-retrieval-stack.md",
+	);
+
+	for (const p of [systemMd, toolsTs, runCli, webRetrievalSkill, adr]) {
+		if (!(await fileExists(p))) fail(`WRS contract missing file: ${p}`);
+	}
+
+	const sys = await readFile(systemMd, "utf-8");
+	if (!sys.includes("tier=deep") && !sys.includes('tier: "deep"')) {
+		fail("SYSTEM.md must document deep tier default for WRS");
+	}
+	if (!sys.includes("web-retrieval")) {
+		fail("SYSTEM.md must reference web-retrieval skill");
+	}
+	if (!sys.includes(".web/cache") && !sys.includes("HARNESS_WEB_CACHE")) {
+		fail("SYSTEM.md must document pooled WRS cache under .web/cache/");
+	}
+
+	const tools = await readFile(toolsTs, "utf-8");
+	if (!tools.includes('Literal("deep")')) {
+		fail("harness-web-tools.ts must define tier enum including deep");
+	}
+	if (!tools.includes("anglesFile")) {
+		fail("harness-web-tools.ts must expose anglesFile on web_search");
+	}
+
+	const cli = await readFile(runCli, "utf-8");
+	if (!cli.includes("tier=deep")) {
+		fail("run-cli.ts harnessWebContextLine must mention tier=deep");
+	}
+
+	const artifactsTs = join(ROOT, ".pi", "lib", "harness-web", "artifacts.ts");
+	if (!(await fileExists(artifactsTs))) {
+		fail("missing harness-web/artifacts.ts for scoped .web paths");
+	}
+	const cacheTs = join(ROOT, ".pi", "lib", "harness-web", "cache.ts");
+	if (!(await fileExists(cacheTs))) {
+		fail("missing harness-web/cache.ts for pooled .web/cache/");
+	}
+	if (!tools.includes("refreshCache") || !tools.includes("lookupSearchCache")) {
+		fail("harness-web-tools.ts must implement pooled cache (refreshCache, lookupSearchCache)");
+	}
+	const heuristicYaml = join(ROOT, ".pi", "harness", "web-heuristic-angles.yaml");
+	if (!(await fileExists(heuristicYaml))) {
+		fail("missing .pi/harness/web-heuristic-angles.yaml");
+	}
+	const heuristicPy = join(ROOT, ".pi", "scripts", "harness_web", "heuristic_config.py");
+	if (!(await fileExists(heuristicPy))) {
+		fail("missing harness_web/heuristic_config.py");
+	}
+
+	const rankPy = join(ROOT, ".pi", "scripts", "harness_web", "rank.py");
+	const anglesPy = join(ROOT, ".pi", "scripts", "harness_web", "deep_search.py");
+	for (const p of [rankPy, anglesPy]) {
+		if (!(await fileExists(p))) fail(`WRS python module missing: ${p}`);
+	}
+
+	const expander = join(ROOT, ".pi", "agents", "harness", "web-retrieval", "web-query-expander.md");
+	if (!(await fileExists(expander))) {
+		fail("missing web-query-expander agent");
+	}
+
+	ok("WRS contracts (SYSTEM.md, tools, modules, web-retrieval skill, ADR)");
+}
+
 main().catch((err) => {
 	console.error(err);
 	process.exit(1);

package/.pi/scripts/harness-web-policy-guard.mjs

@@ -12,13 +12,13 @@ const ROOT = resolve(new URL("../..", import.meta.url).pathname);
 const ALLOWED_FILES = new Set([
 	".pi/extensions/harness-web-guard.ts",
 	".pi/extensions/harness-web-tools.ts",
-	".pi/extensions/lib/harness-web/run-cli.ts",
+	".pi/lib/harness-web/run-cli.ts",
 	".pi/extensions/harness-run-context.ts",
-	".pi/extensions/lib/ask-user/schema.ts",
+	".pi/lib/ask-user/schema.ts",
 	".pi/scripts/harness-web.py",
 	".pi/scripts/harness-web-search.md",
 	".pi/scripts/harness-web-policy-guard.mjs",
-	".agents/skills/scrapling-web/SKILL.md",
+	".agents/skills/web-retrieval/SKILL.md",
 	".pi/scripts/harness-cli-verify.sh",
 	".pi/scripts/harness_web/output.py",
 	"AGENTS.md",

package/.pi/scripts/harness-web.py

@@ -9,6 +9,7 @@ import shutil
 import sys
 import time
 from pathlib import Path
+from urllib.parse import urlparse
 
 # Re-exec with scrapling's uv-tool Python when the library is not on default python3.
 def _bootstrap_scrapling() -> None:
@@ -34,10 +35,28 @@ if str(SCRIPT_DIR) not in sys.path:
     sys.path.insert(0, str(SCRIPT_DIR))
 
 from harness_web.config import HarnessWebConfig, load_config  # noqa: E402
-from harness_web.output import write_search_results  # noqa: E402
-from harness_web.scrape import bulk_scrape, map_url, scrape_url  # noqa: E402
+from harness_web.deep_search import run_deep_search  # noqa: E402
+from harness_web.evidence_bundle import build_evidence_bundle, write_evidence_bundle  # noqa: E402
+from harness_web.find_similar import run_find_similar  # noqa: E402
+from harness_web.output import (  # noqa: E402
+    write_deep_search_results,
+    write_search_results,
+)
+from harness_web.scrape import (  # noqa: E402
+    bulk_scrape,
+    map_url,
+    scrape_url,
+    scrape_url_with_highlights,
+)
 from harness_web.search import search  # noqa: E402
 
+TIER_LIMITS = {
+    "instant": 5,
+    "standard": 10,
+    "deep": 10,
+    "research": 15,
+}
+
 DEFAULT_WEB_DIR = ".web"
 
 
@@ -45,26 +64,153 @@ def _default_out(sub: str) -> Path:
     return Path(DEFAULT_WEB_DIR) / sub
 
 
+def _tier_limit(tier: str, cli_limit: int | None) -> int:
+    if cli_limit is not None:
+        return cli_limit
+    return TIER_LIMITS.get(tier, 10)
+
+
 def cmd_search(args: argparse.Namespace, config: HarnessWebConfig) -> int:
+    tier = getattr(args, "tier", None) or "standard"
+    limit = _tier_limit(tier, args.limit)
     out = Path(args.output or _default_out("search.json"))
-    results = search(args.query, limit=args.limit, config=config)
-    write_search_results(out, results, args.query, engine=config.search_engine)
-    print(f"wrote {out} ({len(results)} results)")
+    results = search(args.query, limit=limit, config=config)
+    write_search_results(out, results, args.query, engine=config.search_engine, tier=tier)
+    print(f"wrote {out} ({len(results)} results, tier={tier})")
     return 0
 
 
-def cmd_scrape(args: argparse.Namespace, config: HarnessWebConfig) -> int:
-    out = Path(args.output or _default_out("page.md"))
-    fast = config.use_fast_for_url(args.url, args.fast)
-    scrape_url(
+def cmd_search_deep(args: argparse.Namespace, config: HarnessWebConfig) -> int:
+    out = Path(args.output or _default_out("search-deep.json"))
+    angles_path = Path(args.angles_file) if args.angles_file else None
+    plan, ranked = run_deep_search(
+        args.query,
+        config=config,
+        angles_file=angles_path,
+        expand_heuristic=args.expand_heuristic,
+        category=args.category,
+        per_angle_limit=args.per_angle_limit,
+        final_limit=args.limit,
+    )
+    angle_dicts = [
+        {"id": a.id, "query": a.query, "rationale": a.rationale} for a in plan.angles
+    ]
+    write_deep_search_results(
+        out,
+        query=args.query,
+        engine=config.search_engine,
+        tier="deep",
+        plan_angles=angle_dicts,
+        ranked_web=ranked,
+    )
+    print(f"wrote {out} ({len(ranked)} fused results, {len(plan.angles)} angles)")
+    return 0
+
+
+def cmd_find_similar(args: argparse.Namespace, config: HarnessWebConfig) -> int:
+    out = Path(args.output or _default_out("search-deep.json"))
+    plan, ranked = run_find_similar(
         args.url,
-        str(out),
         config=config,
-        fast=fast,
-        wait_ms=args.wait_for,
+        final_limit=args.limit,
+        per_angle_limit=args.per_angle_limit,
+        fast_fetch=args.fast,
+    )
+    angle_dicts = [
+        {"id": a.id, "query": a.query, "rationale": a.rationale} for a in plan.angles
+    ]
+    write_deep_search_results(
+        out,
+        query=plan.intent,
+        engine=config.search_engine,
+        tier="deep",
+        plan_angles=angle_dicts,
+        ranked_web=ranked,
     )
-    mode = "fast" if fast else "stealth"
-    print(f"wrote {out} ({mode})")
+    print(f"wrote {out} ({len(ranked)} similar results)")
+    return 0
+
+
+def cmd_scrape(args: argparse.Namespace, config: HarnessWebConfig) -> int:
+    out = Path(args.output or _default_out("page.md"))
+    fast = config.use_fast_for_url(args.url, args.fast)
+    hl_out = args.highlights_output
+    hl_query = (args.highlight_query or "").strip()
+    if args.highlights and hl_query:
+        scrape_url_with_highlights(
+            args.url,
+            str(out),
+            hl_out or str(_default_out("highlights.json")),
+            config=config,
+            fast=fast,
+            wait_ms=args.wait_for,
+            highlight_query=hl_query,
+        )
+        print(f"wrote {out} (highlights)")
+    else:
+        scrape_url(
+            args.url,
+            str(out),
+            config=config,
+            fast=fast,
+            wait_ms=args.wait_for,
+        )
+        mode = "fast" if fast else "stealth"
+        print(f"wrote {out} ({mode})")
+    return 0
+
+
+def cmd_contents_batch(args: argparse.Namespace, config: HarnessWebConfig) -> int:
+    import json
+
+    out_dir = Path(args.output or _default_out("contents"))
+    out_dir.mkdir(parents=True, exist_ok=True)
+    urls: list[str] = list(args.urls or [])
+    if args.from_search:
+        data = json.loads(Path(args.from_search).read_text(encoding="utf-8"))
+        for item in data.get("data", {}).get("web", []):
+            u = (item.get("url") or "").strip()
+            if u:
+                urls.append(u)
+    if not urls:
+        print("contents-batch: no URLs", file=sys.stderr)
+        return 1
+
+    hl_query = (args.highlight_query or "").strip()
+    manifest: list[dict] = []
+    sleep_sec = config.rate_limit_ms / 1000.0
+    for i, url in enumerate(urls[: args.limit]):
+        if i and sleep_sec > 0:
+            time.sleep(sleep_sec)
+        safe = urlparse(url).netloc.replace(".", "_")
+        md_path = out_dir / f"{safe}.md"
+        hl_path = out_dir / f"{safe}.highlights.json" if args.highlights and hl_query else None
+        fast = config.use_fast_for_url(url, args.fast)
+        try:
+            if hl_path:
+                scrape_url_with_highlights(
+                    url,
+                    str(md_path),
+                    str(hl_path),
+                    config=config,
+                    fast=fast,
+                    wait_ms=None,
+                    highlight_query=hl_query,
+                )
+            else:
+                scrape_url(url, str(md_path), config=config, fast=fast, wait_ms=None)
+            manifest.append({"url": url, "markdown": str(md_path), "ok": True})
+        except Exception as err:  # noqa: BLE001
+            manifest.append({"url": url, "ok": False, "error": str(err)})
+
+    manifest_path = out_dir / "manifest.json"
+    manifest_path.write_text(json.dumps({"urls": manifest}, indent=2) + "\n", encoding="utf-8")
+    if args.evidence_bundle and args.from_search:
+        eb_path = Path(args.evidence_bundle)
+        bundle = build_evidence_bundle(Path(args.from_search), query=hl_query)
+        write_evidence_bundle(eb_path, bundle)
+        print(f"wrote {eb_path}")
+    print(f"wrote {len(manifest)} entries to {out_dir}")
     return 0
 
 
@@ -132,9 +278,41 @@ def build_parser() -> argparse.ArgumentParser:
     ps = sub.add_parser("search", help="Search via configured SERP (HARNESS_WEB_SEARCH_ENGINE)")
     ps.add_argument("query", help="Search query")
     ps.add_argument("-o", "--output", help="JSON output path (default: .web/search.json)")
-    ps.add_argument("--limit", type=int, default=5)
+    ps.add_argument("--limit", type=int, default=None)
+    ps.add_argument(
+        "--tier",
+        choices=("instant", "standard", "deep", "research"),
+        default="standard",
+        help="WRS tier (instant=5, standard=10 results)",
+    )
     ps.set_defaults(func=cmd_search)
 
+    pd = sub.add_parser("search-deep", help="Multi-angle SERP fusion (WRS deep)")
+    pd.add_argument("query", help="Original research intent")
+    pd.add_argument("-o", "--output", help="JSON output (default: .web/search-deep.json)")
+    pd.add_argument("--limit", type=int, default=10, help="Final fused result count")
+    pd.add_argument("--per-angle-limit", type=int, default=8, help="SERP hits per angle")
+    pd.add_argument(
+        "--angles-file",
+        metavar="YAML",
+        help="Angles from web-query-expander (.web/angles.yaml)",
+    )
+    pd.add_argument(
+        "--expand-heuristic",
+        action="store_true",
+        help="Emergency angle templates without expander subagent",
+    )
+    pd.add_argument("--category", help="Hint: code|company|people|paper|news")
+    pd.set_defaults(func=cmd_search_deep)
+
+    pf = sub.add_parser("find-similar", help="Pages similar to a seed URL")
+    pf.add_argument("url", help="Seed URL")
+    pf.add_argument("-o", "--output", help="JSON output (default: .web/search-deep.json)")
+    pf.add_argument("--limit", type=int, default=10)
+    pf.add_argument("--per-angle-limit", type=int, default=6)
+    pf.add_argument("--fast", action="store_true", help="Fast HTTP for seed fetch")
+    pf.set_defaults(func=cmd_find_similar)
+
     pc = sub.add_parser("scrape", help="Scrape a URL to markdown")
     pc.add_argument("url")
     pc.add_argument("-o", "--output", help="Markdown output (default: .web/page.md)")
@@ -150,8 +328,33 @@ def build_parser() -> argparse.ArgumentParser:
         metavar="MS",
         help="Extra wait after load (stealth mode, milliseconds)",
     )
+    pc.add_argument("--highlights", action="store_true", help="Extract query-aligned excerpts")
+    pc.add_argument("--highlight-query", help="Query for highlight scoring")
+    pc.add_argument(
+        "--highlights-output",
+        help="Highlights JSON path (default: .web/highlights.json)",
+    )
     pc.set_defaults(func=cmd_scrape)
 
+    pbatch = sub.add_parser("contents-batch", help="Batch scrape URLs to markdown manifest")
+    pbatch.add_argument("urls", nargs="*", help="URLs to fetch")
+    pbatch.add_argument("-o", "--output", help="Output directory (default: .web/contents)")
+    pbatch.add_argument("--limit", type=int, default=5)
+    pbatch.add_argument(
+        "--from-search",
+        metavar="JSON",
+        help="URLs from search.json or search-deep.json",
+    )
+    pbatch.add_argument("--fast", action="store_true")
+    pbatch.add_argument("--highlights", action="store_true")
+    pbatch.add_argument("--highlight-query", default="")
+    pbatch.add_argument(
+        "--evidence-bundle",
+        metavar="JSON",
+        help="Write evidence-bundle.json from --from-search",
+    )
+    pbatch.set_defaults(func=cmd_contents_batch)
+
     pb = sub.add_parser("bulk-scrape", help="Search then scrape multiple URLs")
     pb.add_argument("query", nargs="?", help="Search query when not using --from-search")
     pb.add_argument("-o", "--output", help="Output directory (default: .web/bulk)")

package/.pi/scripts/harness_web/deep_search.py

@@ -0,0 +1,55 @@
+"""WRS deep search orchestration."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .config import HarnessWebConfig
+from .multi_search import multi_search
+from .query_angles import AnglesPlan, resolve_angles
+from .rank import fuse_angle_results
+
+
+def _rerank_mode() -> str:
+    mode = os.environ.get("HARNESS_WEB_RERANK", "off").strip().lower()
+    if mode in ("off", "lexical", "embed"):
+        return mode
+    return "off"
+
+
+def run_deep_search(
+    query: str,
+    *,
+    config: HarnessWebConfig,
+    angles_file: Path | None = None,
+    expand_heuristic: bool = False,
+    category: str | None = None,
+    per_angle_limit: int = 8,
+    final_limit: int = 10,
+) -> tuple[AnglesPlan, list[dict]]:
+    plan = resolve_angles(
+        query,
+        angles_file=angles_file,
+        expand_heuristic=expand_heuristic,
+        category=category,
+    )
+    per_angle = multi_search(plan, per_angle_limit=per_angle_limit, config=config)
+    # Strip internal tags before fusion
+    clean: dict[str, list[dict[str, str]]] = {}
+    for aid, rows in per_angle.items():
+        clean[aid] = [
+            {
+                "url": r.get("url", ""),
+                "title": r.get("title", ""),
+                "description": r.get("description", ""),
+            }
+            for r in rows
+        ]
+    ranked = fuse_angle_results(
+        clean,
+        final_limit=final_limit,
+        intent=plan.intent,
+        rerank_mode=_rerank_mode(),
+    )
+    return plan, [h.to_web_dict() for h in ranked]