ultimate-pi 0.18.1 → 0.19.1

package/.pi/prompts/harness-setup.md

@@ -14,7 +14,6 @@ Bootstraps the complete ultimate-pi agentic harness: Graphify knowledge graph, C
 | Pitfall | Correct approach |
 |---------|------------------|
 | `UP_PKG="$(pwd)"` in an **external** repo | Wrong — scripts live in the npm package. Resolve via `harness-resolve-up-pkg.mjs` (see Step 0). |
-| Provider detection from `OPENAI_*` / `ANTHROPIC_*` env only | Wrong for pi users — keys live in `~/.pi/agent/auth.json`. Use `harness-generate-model-router.mjs` (Pi `ModelRegistry.getAvailable()`). |
 | Re-running 2.1–2.8 manually after CLI verify | Wasteful — trust `harness-cli-verify.sh` output; only fix reported ✗ lines. |
 | Overwriting `AGENTS.md` after graphify | Graphify appends a section — **merge**, do not replace (Step 4.3). |
 | `sentrux-rules-sync` without project manifest | Use **`harness-sentrux-bootstrap.mjs`** (Step 4.2) — seeds manifest + idempotent rules sync. |
@@ -141,6 +140,8 @@ python3 "$UP_PKG/.pi/scripts/harness-web.py" scrape "https://example.com" -o .we
 
 After pi loads extensions, agents should smoke **`web_search`** once (not `UP_PKG` / `import scrapling` preflight). Example intent: query `ultimate-pi harness`, `limit` 2.
 
+**WRS subagent models (optional):** set env vars to any Pi `provider/model-id` — `HARNESS_WEB_FAST_MODEL`, `HARNESS_WEB_EXPANDER_MODEL`, `HARNESS_WEB_QUALITY_MODEL` (see **web-retrieval** skill). Add to `.env` via `harness-sync-env.mjs` or export in shell.
+
 - **`--skip-tools`:** skip Step 2 (includes Scrapling verify).
 - On Linux/WSL, if stealth scrape fails, install browser libs from `harness-cli-verify.sh` output or use `--fast` for static targets.
 
@@ -154,9 +155,9 @@ bash "$UP_PKG/.pi/scripts/harness-cli-verify.sh"
 # Reinstall everything: bash "$UP_PKG/.pi/scripts/harness-cli-verify.sh" --force
 ```
 
-**Required (script must exit 0):** scrapling + harness-web smoke, ctx7, biome, ast-grep (`sg`), sentrux (when harness manifest present).
+**Required (script must exit 0):** scrapling + harness-web smoke, ctx7, ast-grep (`sg`), sentrux (when harness manifest present).
 
-**Warnings allowed:** gh (if not authenticated), agent-browser (if OS libs need manual `sudo apt-get install`), cocoindex-code (empty corpus on tiny repos; first `[full]` install downloads local embedding model).
+**Warnings allowed:** biome (optional; skipped for non-JS/TS repos or if install fails), gh (if not authenticated), agent-browser (if OS libs need manual `sudo apt-get install`), cocoindex-code (empty corpus on tiny repos; first `[full]` install downloads local embedding model).
 
 If the script reports **agent-browser shared library errors** on Linux/WSL, run the fix it prints, then re-verify:
 
@@ -189,7 +190,7 @@ python3 "$UP_PKG/.pi/scripts/harness-web.py" search "query" -o .web/search.json
 python3 "$UP_PKG/.pi/scripts/harness-web.py" scrape "https://example.com" -o .web/page.md --fast
 ```
 
-See `.agents/skills/scrapling-web/SKILL.md`.
+See `.agents/skills/web-retrieval/SKILL.md` (install + env).
 
 ### 2.2 — ctx7 (Context7 Library Docs + Skills Management)
 
@@ -251,21 +252,21 @@ ccc status
 
 Verify: `ccc doctor` and `ccc search --limit 3 "export function"` (no `--refresh`).
 
-### 2.5 — biome (Lint + Format Gate)
+### 2.5 — biome (Optional, JS/TS-focused lint + format)
 
-```bash
-if ! command -v biome &>/dev/null || [ "$FORCE" = "true" ]; then
-	npm install -g @biomejs/biome
-fi
-```
+Biome is **not a hard requirement** for harness setup. Install/use it when the target project is JS/TS (for example, has `package.json` or already uses `biome.json`). For other stacks, skip and use the repo's native formatter/linter.
 
-Check if project already has biome config:
 ```bash
-ls biome.json 2>/dev/null && echo "biome.json found — using project config" || echo "No biome.json — using defaults"
+if [ -f package.json ] || [ -f biome.json ]; then
+  if ! command -v biome &>/dev/null || [ "$FORCE" = "true" ]; then
+    npm install -g @biomejs/biome
+  fi
+  biome --version
+else
+  echo "Skipping biome (non-JS/TS repo; optional tool)"
+fi
 ```
 
-Verify: `biome --version`
-
 ### 2.6 — ast-grep (AST-Aware Structural Code Search)
 
 ```bash
@@ -327,7 +328,14 @@ sentrux plugin add-standard 2>/dev/null || echo "Plugins already installed or fa
 
 ## Step 3 — Pi Extension Packages
 
-Bundled extensions load from the installed `ultimate-pi` package. **Session-locked model routing** comes from a **vendored** fork of [`yeliu84/pi-model-router`](https://github.com/yeliu84/pi-model-router) in `vendor/pi-model-router/`, wired through [`.pi/extensions/pi-model-router-harness.ts`](.pi/extensions/pi-model-router-harness.ts). The router picks **one concrete model** when the session starts (from the first user prompt + system prompt complexity), then changes **thinking level only** each turn. The harness **gates** activation on `.pi/model-router.json` (Step **3.5** below) so `router/auto` cannot load prematurely. Attribution: see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and `vendor/pi-model-router/UPSTREAM_PIN.md`. Maintainer refresh: `npm run vendor:sync-router`.
+Bundled extensions load from the installed `ultimate-pi` package. The harness lens wrapper at `.pi/extensions/harness-lens.ts` loads `.pi/extensions/lib/harness-lens/` for edit autopatch, secrets blocking, deferred format, and LSP tools. Structural search uses shell `sg` (installed globally by setup); architecture gates use Sentrux. See [ADR 0045](.pi/harness/docs/adrs/0045-harness-lens-minimal-contract.md).
+
+Harness lens findings are **complementary** to Sentrux:
+
+- **Harness lens:** fast edit-time and turn-time code feedback; standalone lens widgets/health telemetry are disabled, and findings flow through the harness PostHog telemetry layer.
+- **Sentrux:** architecture-quality signal and gate (`.sentrux/rules.toml`, `sentrux-signal.yaml`, harness review/evaluate inputs).
+
+Do not treat harness lens as a replacement for Sentrux. If a future lens change adds architecture-boundary gating that duplicates Sentrux, keep Sentrux authoritative and disable/remove the overlapping lens path.
 
 Optionally install the companion lockfile used in development:
 
@@ -341,51 +349,19 @@ else
 fi
 ```
 
-Merge extension entries from `$UP_PKG/.pi/settings.example.json` into this project's `.pi/settings.json` `packages` array (add any missing `npm:…` entries; keep existing user packages). **Do not add** `npm:@yeliu84/pi-model-router` (superseded by the vendored router).
+Merge extension entries from `$UP_PKG/.pi/settings.example.json` into this project's `.pi/settings.json` `packages` array (add any missing `npm:…` entries; keep existing user packages).
 
 Verify each package:
 
 | Package | Purpose | Phase |
 |---------|---------|-------|
 | `@posthog/pi` | Analytics event capture | F0 |
-| `pi-lean-ctx` | Context runtime (read/bash/find/grep/MCP bridge) | F0 |
+| `context-mode` | Context runtime and MCP context-saving tools | F0 |
 | `harness-subagents` (bundled extension) | L4 `subagent` tool, subprocess spawns, package agents | P16 |
 | Vendored `pi-vcc` (`vendor/pi-vcc`, `.pi/extensions/ultimate-pi-vcc.ts`) | VCC compaction / `vcc_recall` — env-only: `HARNESS_VCC_COMPACTION` (default on), `HARNESS_VCC_DEBUG` | Shipped |
-| `pi-model-router` | Vendored (`vendor/`); activates after `.pi/model-router.json` exists | F0 |
-
-## Step 3.5 — Model Router Configuration (Dynamic)
-
-`.pi/model-router.json` is **user-specific** (gitignored). Generate from **Pi authenticated providers** (`~/.pi/agent/auth.json`, OAuth, env) — **not** env-var guessing alone.
-
-Pi API (see `packages/coding-agent` docs / SDK example `02-custom-model.ts`):
-
-- `AuthStorage.create()` → credentials store
-- `ModelRegistry.create(authStorage)` → registry
-- `await modelRegistry.getAvailable()` → models with working auth (same as interactive pi)
-
-```bash
-# Verify vendored extension source ships with ultimate-pi
-ls "$UP_PKG/vendor/pi-model-router/extensions/index.ts" 2>/dev/null \
-  && echo "✓ vendored pi-model-router" \
-  || echo "✗ missing vendor/pi-model-router"
-
-# Generate from Pi registry (skips if .pi/model-router.json exists; --force to regenerate)
-node "$UP_PKG/.pi/scripts/harness-generate-model-router.mjs"
-# Preview only: node "$UP_PKG/.pi/scripts/harness-generate-model-router.mjs" --dry-run
-
-# Merge router defaults after config exists (never adds npm packages — router is vendored)
-node "$UP_PKG/.pi/scripts/harness-sync-model-router.mjs"
-```
-
-If generation prints "No authenticated Pi providers": warn in report — user should run **`/login`** in pi (or `pi login`) then re-run Step 3.5. Do **not** infer providers from `OPENAI_API_KEY` alone; pi sessions often use `opencode-go` via auth.json without those env vars.
-
-Do NOT block setup. If no config is written, `harness-sync-model-router.mjs` clears a premature `defaultProvider: "router"` in `.pi/settings.json`.
-
-**Router onboarding** — The vendored extension starts only after `.pi/model-router.json` appears. Running the script above prepares that file plus optional Pi defaults (**`router` / `auto`**, or whatever `defaultProfile` is) via `harness-sync-model-router.mjs` when `defaultProvider` was unset—then **`/reload`**. Generated profiles use **one model SKU per profile**; high/medium/low tiers differ in **thinking** only. Subagents resolve their subprocess model from the **agent system prompt** complexity (same lock rules).
-
-Manual override: **`/router profile auto`** or **`/router profile opencode-go`** anytime after reload if they changed defaults.
+| Harness lens (`.pi/extensions/harness-lens.ts` → `.pi/extensions/lib/harness-lens/index.ts`) | Edit autopatch, secrets block, deferred format, LSP tools; PostHog lens telemetry; Sentrux remains architecture gate; `sg` is shell-only | F0 |
 
-## Step 3.6 — Harness agents (package-resolved)
+## Step 3.5 — Harness agents (package-resolved)
 
 `harness-subagents` loads agents from the installed **`ultimate-pi`** package (`$UP_PKG/.pi/agents/**`) with namespaced ids (`harness/running/executor`, `harness/reviewing/evaluator`, `pi-pi/agent-expert`). **Do not copy** agents into the project unless you want a deliberate override.
 
@@ -500,10 +476,9 @@ Ensure `.gitignore` contains harness runtime entries (see repo root `.gitignore`
 !.pi/harness/incidents/README.md
 .pi/harness/debates/*
 !.pi/harness/debates/README.md
-.pi/harness/router/proposals/*
 
-# Model router config (user-specific — generated from env)
-.pi/model-router.json
+# Harness lens runtime config/cache and local diagnostics state
+.pi/harness/.lens/
 
 # sentrux baselines and local meta (rules.toml is committed)
 .sentrux/*
@@ -564,7 +539,7 @@ Created: $(date +%Y-%m-%d)
 - .pi/harness/specs/ → Harness contracts and schema docs
 - .pi/harness/incidents/ → Incident and override records
 - `.agents/skills/` (npm package) → Harness skills (no copy into `.pi/skills/` needed)
-- `.pi/agents/` → Optional per-repo agent overrides (package agents load automatically — see Step 3.6)
+- `.pi/agents/` → Optional per-repo agent overrides (package agents load automatically — see Step 3.5)
 
 ## Graphify-First Workflow
 
@@ -580,7 +555,7 @@ Created: $(date +%Y-%m-%d)
 - Decisions and incidents in `.pi/harness/` with structured artifacts
 - `GRAPHIFY_VIZ_NODE_LIMIT=200000 graphify update .` after significant code changes
 - ast-grep (`sg`) is the default code search tool — use `sg -p 'pattern'` for structural search, never grep for code
-- Create `.sg/rules/` for project-wide code quality rules
+- Use shell `sg` for structural search; project-specific ast-grep rule dirs are optional in the **target repo**, not a harness template default
 ```
 
 ## Step 5 — Verification
@@ -627,10 +602,11 @@ print(f'✓ knowledge graph built ({n} nodes)' if n else '✗ graph.json has 0 n
 " 2>/dev/null || echo "✗ no graph built yet"
 graphify hook status 2>/dev/null && echo "✓ graphify git hooks installed" || echo "✗ graphify git hooks not installed"
 
-# vendored model router
-ls "$UP_PKG/vendor/pi-model-router/extensions/index.ts" 2>/dev/null \
-  && echo "✓ vendored pi-model-router" || echo "✗ vendor/pi-model-router missing"
-ls .pi/model-router.json 2>/dev/null && echo "✓ model-router config" || echo "✗ model-router config"
+# harness lens extension
+ls "$UP_PKG/.pi/extensions/harness-lens.ts" 2>/dev/null \
+  && echo "✓ harness lens wrapper" || echo "✗ harness lens wrapper missing"
+ls "$UP_PKG/.pi/extensions/lib/harness-lens/index.ts" 2>/dev/null \
+  && echo "✓ harness lens upstream pin" || echo "✗ harness lens upstream pin missing"
 
 # raw folder for graphify sources
 ls -d ./raw 2>/dev/null && echo "✓ ./raw directory exists" || echo "! ./raw directory missing"
@@ -672,13 +648,13 @@ Output summary table:
 | ctx7 | ✓/✗ | Login: yes/no |
 | agent-browser | ✓/✗ | Config: .pi/harness/browser.json |
 | cocoindex-code | ✓/✗ | `ccc status`; index auto-refreshed before harness scouts |
-| biome | ✓/✗ | Project config: found/default |
+| biome | ✓/✗/skip | Optional; JS/TS-focused (skip on non-JS/TS stacks) |
 | ast-grep | ✓/✗ | AST-aware code search (`sg`)
 | gh CLI | ✓/✗ | Auth: yes/no |
 | sentrux | ✓/✗ | CLI + plugins; rules via Step 4.2 bootstrap |
 | Sentrux rules.toml | ✓/✗ | `.sentrux/rules.toml` synced from manifest |
-| pi extensions | ✓/✗ | 4 packages |
-| model router | ✓/✗ | Package + config verified, activation via `/router profile auto` (or `opencode-go`) |
+| pi extensions | ✓/✗ | bundled extensions + harness lens wrapper |
+| harness lens | ✓/✗ | `.pi/extensions/harness-lens.ts`; PostHog owns lens telemetry; complements Sentrux architecture signal |
 | `.env` | ✓/✗/ask | Created / keys appended / user declined |
 
 | .gitignore | ✓/✗ | entries added (incl. `.env`) |
@@ -728,11 +704,10 @@ Next steps:
 | gh not installed | Show GitHub CLI install link. Skip label creation. |
 | pi packages install fail | Show error output. Check npm permissions. |
 | graph already exists | Report node count. Refresh with `graphify update .` unless user passed `--force`. |
-| biome.json missing | Create minimal config. |
+| biome.json missing | No action required. Biome is optional; use project-native tooling. |
 | settings.json not writable | Warn. Settings won't persist across sessions. |
 | No internet | Block for tool installs. Continue for graphify-only steps if `--skip-tools`. |
 | sentrux install fails | Show install script output. Fallback: download from https://github.com/sentrux/sentrux/releases/latest |
-| No model-router.json / "No authenticated Pi providers" | Run `/login` in pi, then `node "$UP_PKG/.pi/scripts/harness-generate-model-router.mjs" --force` |
 | UP_PKG not found | `pi install npm:ultimate-pi` or `npm i -g ultimate-pi`; verify with `node "$UP_PKG/.pi/scripts/harness-resolve-up-pkg.mjs"` |
 | No `.env` at project root | `ask_user` create vs skip; on create: `harness-sync-env.mjs --create-missing` |
 

package/.pi/scripts/README.md

@@ -14,7 +14,7 @@ UP_PKG="$(node -p "require('path').dirname(require.resolve('ultimate-pi/package.
 
 **Developing this repo** (clone of `ultimate-pi`): from the repo root, `UP_PKG="$(pwd)"` (or the same `require.resolve` after `npm install`).
 
-From **Typescript extensions**, use `resolveHarnessScript()` / `getHarnessPackageRoot()` in `.pi/extensions/lib/harness-paths.ts`.
+From **Typescript extensions**, use `resolveHarnessScript()` / `getHarnessPackageRoot()` in `.pi/lib/harness-paths.ts`.
 
 ## Invocations (from the consuming project root)
 
@@ -29,11 +29,8 @@ From **Typescript extensions**, use `resolveHarnessScript()` / `getHarnessPackag
 | Sentrux rules drift check (CI) | `node "$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs" --check` |
 | Sentrux run/review check or gate (root-resolving) | `node "$UP_PKG/.pi/scripts/harness-sentrux-cli.mjs" check` / `gate [--save]` |
 | Resolve package root (`UP_PKG`) | `node "$UP_PKG/.pi/scripts/harness-resolve-up-pkg.mjs"` |
-| Model-router config (Pi auth) | `node "$UP_PKG/.pi/scripts/harness-generate-model-router.mjs"` |
 | Project `.env` (append-only) | `node "$UP_PKG/.pi/scripts/harness-sync-env.mjs"` (`--create-missing` after user confirms) |
-| Model-router / Pi defaults | `harness-sync-model-router.mjs` (Step 3.5 of `/harness-setup`) |
-| Vendor router sync (this repo only) | `bash .pi/scripts/vendor-sync-pi-model-router.sh` or `npm run vendor:sync-router` |
-| Meta-optimizer (JSONL proposals) | `node "$UP_PKG/.pi/harness/evolution/meta-optimizer.mjs"` |
+| Harness lens extension | `.pi/extensions/harness-lens.ts` → `.pi/lib/harness-lens/index.ts` (loaded by `.pi/extensions`; PostHog owns lens telemetry) |
 
 Pass `--force` to shell scripts that support it (e.g. `harness-graphify-bootstrap.sh --force`, `harness-cli-verify.sh --force`).
 

package/.pi/scripts/gen-web-heuristic-angles-json.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/** Regenerate .pi/harness/web-heuristic-angles.json from shipped Python defaults. */
+import { execFileSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..", "harness");
+const out = join(root, "web-heuristic-angles.json");
+const py = join(dirname(fileURLToPath(import.meta.url)), "harness_web", "heuristic_angles_shipped.py");
+const json = execFileSync(
+	"python3",
+	[
+		"-c",
+		`import json, importlib.util
+spec = importlib.util.spec_from_file_location("shipped", ${JSON.stringify(py)})
+mod = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(mod)
+print(json.dumps(mod.SHIPPED_HEURISTIC_ANGLES, indent=2))`,
+	],
+	{ encoding: "utf-8" },
+);
+writeFileSync(out, `${json}\n`, "utf-8");
+console.log(`wrote ${out}`);

package/.pi/scripts/generate-agents-policy-yaml.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * Generate .pi/harness/agents.policy.yaml from harness agent .md frontmatter + submit registry.
+ */
+
+import { readFile, writeFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { walkAgentsDir } from "../lib/harness-agent-discovery.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const AGENTS_DIR = join(ROOT, ".pi", "agents");
+const OUT = join(ROOT, ".pi", "harness", "agents.policy.yaml");
+
+const SUBMIT_BY_AGENT = {
+	"harness/planning/planning-context": ["submit_planning_context"],
+	"harness/planning/decompose": ["submit_decomposition_brief", "submit_human_required"],
+	"harness/planning/hypothesis": ["submit_hypothesis_brief"],
+	"harness/planning/hypothesis-validator": ["submit_hypothesis_validation"],
+	"harness/planning/plan-evaluator": ["submit_validation_turn"],
+	"harness/planning/plan-adversary": ["submit_adversary_brief"],
+	"harness/planning/sprint-contract-auditor": ["submit_sprint_audit"],
+	"harness/planning/review-integrator": ["submit_review_round_draft"],
+	"harness/planning/implementation-researcher": ["submit_implementation_research"],
+	"harness/planning/stack-researcher": ["submit_stack_brief"],
+	"harness/planning/execution-plan-author": ["submit_execution_plan_brief"],
+	"harness/running/executor": ["submit_executor_handoff"],
+	"harness/reviewing/evaluator": ["submit_eval_verdict"],
+	"harness/reviewing/adversary": ["submit_adversary_report"],
+	"harness/reviewing/tie-breaker": ["submit_human_required"],
+	"harness/trace-librarian": ["submit_human_required"],
+	"harness/incident-recorder": ["submit_human_required"],
+	"harness/sentrux-steward": ["submit_sentrux_manifest_proposal"],
+};
+
+function parseFrontmatter(content) {
+	const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!m) return {};
+	return parseYaml(m[1]) ?? {};
+}
+
+function kindFor(id) {
+	if (id.startsWith("harness/planning/")) return "planner";
+	if (id === "harness/running/executor") return "executor";
+	if (id === "harness/reviewing/evaluator") return "evaluator";
+	if (id === "harness/reviewing/adversary") return "adversary";
+	if (id === "harness/reviewing/tie-breaker") return "tie_breaker";
+	if (id === "harness/trace-librarian") return "trace";
+	if (id === "harness/incident-recorder") return "incident";
+	if (id === "harness/sentrux-steward" || id === "harness/sentrux-bootstrap")
+		return "planner";
+	return "other";
+}
+
+const KIND_BASE = {
+	planner: ["read", "grep", "find", "ls"],
+	executor: ["read", "write", "edit", "bash", "grep", "find", "ls"],
+	evaluator: ["read", "grep", "find", "ls"],
+	adversary: ["read", "grep", "find", "ls"],
+	tie_breaker: ["read", "grep", "find", "ls"],
+	trace: ["read", "grep", "find", "ls"],
+	incident: ["read", "grep", "find", "ls"],
+	other: ["read", "grep", "find", "ls"],
+};
+
+function csvTools(fm) {
+	const raw = fm.tools;
+	if (!raw) return [];
+	return String(raw)
+		.split(",")
+		.map((t) => t.trim())
+		.filter(Boolean);
+}
+
+async function main() {
+	const files = new Map();
+	walkAgentsDir(AGENTS_DIR, "package", files);
+
+	const kinds = {
+		planner: { tools: KIND_BASE.planner, extensions: false, read_only: true },
+		executor: { tools: KIND_BASE.executor, extensions: true, read_only: false },
+		evaluator: { tools: KIND_BASE.evaluator, extensions: false, read_only: true },
+		adversary: { tools: KIND_BASE.adversary, extensions: false, read_only: true },
+		tie_breaker: {
+			tools: KIND_BASE.tie_breaker,
+			extensions: false,
+			read_only: true,
+		},
+		trace: { tools: KIND_BASE.trace, extensions: false, read_only: true },
+		incident: { tools: KIND_BASE.incident, extensions: false, read_only: true },
+		other: { tools: KIND_BASE.other, extensions: false, read_only: true },
+	};
+
+	const agents = {};
+
+	for (const [id, file] of files) {
+		if (!id.startsWith("harness/")) continue;
+		const fm = parseFrontmatter(file.content);
+		const kind = kindFor(id);
+		const base = new Set(KIND_BASE[kind] ?? KIND_BASE.other);
+		const fromFm = csvTools(fm);
+		const submit = SUBMIT_BY_AGENT[id] ?? [];
+		const toolsAdd = [...new Set([...fromFm, ...submit])].filter(
+			(t) => !base.has(t),
+		);
+		const entry = { kind };
+		if (toolsAdd.length > 0) entry.tools_add = toolsAdd;
+		if (fm.extensions === false) entry.extensions = false;
+		if (fm.extensions === true) entry.extensions = true;
+		if (typeof fm.max_turns === "number") entry.max_turns = fm.max_turns;
+		if (typeof fm.thinking === "string") entry.thinking = fm.thinking;
+		if (submit.length === 1) entry.submit_tool = submit[0];
+		agents[id] = entry;
+	}
+
+	// plan-synthesizer: parent-only, minimal policy for spawn if ever used
+	agents["harness/planning/plan-synthesizer"] = {
+		kind: "planner",
+		tools_add: [
+			"submit_decomposition_brief",
+			"submit_hypothesis_brief",
+			"submit_execution_plan_brief",
+		],
+		extensions: false,
+	};
+
+	const doc = {
+		apiVersion: "harness.toolkit/v1",
+		kinds,
+		agents,
+	};
+
+	const yaml = [
+		"# Generated/maintained SSOT for harness agent tools (see ADR 0049).",
+		"# Regenerate hints: node .pi/scripts/generate-agents-policy-yaml.mjs",
+		"",
+	];
+	const { stringify } = await import("yaml");
+	yaml.push(stringify(doc));
+	await writeFile(OUT, yaml.join("\n"), "utf8");
+	console.log(`Wrote ${OUT} (${Object.keys(agents).length} harness agents)`);
+}
+
+main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});

package/.pi/scripts/harness-agents-manifest.mjs

@@ -7,6 +7,7 @@
  *   node .pi/scripts/harness-agents-manifest.mjs --check
  */
 
+import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -15,6 +16,10 @@ import {
 	sha256Content,
 	walkAgentsDir,
 } from "../lib/harness-agent-discovery.mjs";
+import {
+	loadAgentsPolicyMerged,
+	packageAgentsPolicyPath,
+} from "../lib/agents-policy.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const MANIFEST_PATH = join(ROOT, ".pi", "harness", "agents.manifest.json");
@@ -27,7 +32,7 @@ async function readPackageMeta() {
 	return { name: pkg.name ?? "ultimate-pi", version: pkg.version ?? "0.0.0" };
 }
 
-function buildManifest(packageFiles, packageName, packageVersion) {
+async function buildManifest(packageFiles, packageName, packageVersion) {
 	const agents = {};
 	for (const f of packageFiles.values()) {
 		agents[f.id] = {
@@ -35,11 +40,17 @@ function buildManifest(packageFiles, packageName, packageVersion) {
 			sha256: sha256Content(f.content),
 		};
 	}
+	const policyPath = packageAgentsPolicyPath(ROOT);
+	let policy_sha256;
+	if (existsSync(policyPath)) {
+		policy_sha256 = sha256Content(await readFile(policyPath, "utf-8"));
+	}
 	return {
 		schema_version: "1.0.0",
 		package: packageName,
 		package_version: packageVersion,
 		generated_at: new Date().toISOString(),
+		...(policy_sha256 ? { policy_sha256 } : {}),
 		agents,
 	};
 }
@@ -68,6 +79,37 @@ function getDriftReport(manifest, packageFiles) {
 	return { ok: items.length === 0, items };
 }
 
+function frontmatterHasToolLists(content) {
+	const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!m) return false;
+	return /^tools:/m.test(m[1]) || /^disallowed_tools:/m.test(m[1]);
+}
+
+function verifyAgentsPolicy(packageFiles) {
+	const items = [];
+	const policyPath = packageAgentsPolicyPath(ROOT);
+	if (!existsSync(policyPath)) {
+		return { ok: false, items: [{ id: "*", kind: "missing_agents_policy_yaml" }] };
+	}
+	const merged = loadAgentsPolicyMerged(ROOT, ROOT);
+	for (const [id, file] of packageFiles) {
+		if (!id.startsWith("harness/")) continue;
+		if (frontmatterHasToolLists(file.content)) {
+			items.push({ id, kind: "frontmatter_tools" });
+		}
+		if (!merged.agents.has(id)) {
+			items.push({ id, kind: "missing_policy_entry" });
+		}
+	}
+	for (const id of merged.agents.keys()) {
+		if (!id.startsWith("harness/")) continue;
+		if (!packageFiles.has(id)) {
+			items.push({ id, kind: "orphan_policy_entry" });
+		}
+	}
+	return { ok: items.length === 0, items };
+}
+
 async function loadPackageFiles() {
 	const files = new Map();
 	walkAgentsDir(PACKAGE_AGENTS, "package", files);
@@ -81,7 +123,7 @@ async function main() {
 	const mode = process.argv.includes("--check") ? "check" : "write";
 	const { name, version } = await readPackageMeta();
 	const packageFiles = await loadPackageFiles();
-	const built = buildManifest(packageFiles, name, version);
+	const built = await buildManifest(packageFiles, name, version);
 
 	if (mode === "write") {
 		await writeFile(MANIFEST_PATH, `${JSON.stringify(built, null, "\t")}\n`, "utf-8");
@@ -107,6 +149,19 @@ async function main() {
 		process.exit(1);
 	}
 
+	const policyCheck = verifyAgentsPolicy(packageFiles);
+	if (!policyCheck.ok) {
+		for (const item of policyCheck.items) {
+			console.error(`policy: ${item.id} (${item.kind})`);
+		}
+		process.exit(1);
+	}
+
+	if (built.policy_sha256 && onDisk.policy_sha256 !== built.policy_sha256) {
+		console.error("policy_sha256 mismatch — regenerate manifest with --write");
+		process.exit(1);
+	}
+
 	if (onDisk.package_version !== version) {
 		console.error(
 			`package_version mismatch: manifest=${onDisk.package_version} package=${version}`,
@@ -114,7 +169,9 @@ async function main() {
 		process.exit(1);
 	}
 
-	console.log(`agents.manifest.json OK (${Object.keys(built.agents).length} agents)`);
+	console.log(
+		`agents.manifest.json OK (${Object.keys(built.agents).length} agents, policy aligned)`,
+	);
 }
 
 main().catch((err) => {

package/.pi/scripts/harness-agt-doctor.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env npx tsx
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { doctorHarnessPolicies } from "../lib/agt/policy-engine.js";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const doc = doctorHarnessPolicies(ROOT);
+if (!doc.ok) {
+	console.error("AGT policy doctor failed:");
+	for (const e of doc.errors) console.error(`  - ${e}`);
+	process.exit(1);
+}
+const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf-8")) as {
+	files?: string[];
+};
+const files = pkg.files ?? [];
+if (
+	!files.some(
+		(f: string) =>
+			f === ".pi/harness/policies" || f.startsWith(".pi/harness/policies/"),
+	)
+) {
+	console.error("package.json files[] missing .pi/harness/policies");
+	process.exit(1);
+}
+if (
+	!files.includes(".pi/lib") &&
+	!files.some((f) => f.startsWith(".pi/lib/"))
+) {
+	console.error("package.json files[] missing .pi/lib (ships .pi/lib/agt)");
+	process.exit(1);
+}
+console.log(
+	`AGT doctor OK (${doc.loaded.length} policies at ${doc.policyDir})`,
+);

package/.pi/scripts/harness-cli-verify.sh

@@ -214,6 +214,11 @@ verify_scrapling() {
 	else
 		fail "harness-web search smoke failed (ddg_html)"
 	fi
+	if python3 "$_hw" search-deep "ultimate-pi harness" --expand-heuristic -o .web/verify-search-deep.json --limit 3 2>/dev/null | grep -q wrote; then
+		pass "harness-web search-deep smoke (heuristic angles)"
+	else
+		fail "harness-web search-deep smoke failed"
+	fi
 	if python3 "$_hw" scrape "https://example.com" -o .web/verify-page.md --fast 2>/dev/null | grep -q wrote; then
 		pass "harness-web scrape --fast smoke"
 	else
@@ -262,11 +267,18 @@ verify_cocoindex() {
 
 verify_biome() {
 	log "[biome]"
-	npm_global_install "@biomejs/biome" "biome" || { fail "biome npm install"; return; }
+	if [ ! -f "${ROOT}/package.json" ] && [ ! -f "${ROOT}/biome.json" ]; then
+		warn "biome skipped (non-JS/TS repo detected; optional tool)"
+		return
+	fi
+	npm_global_install "@biomejs/biome" "biome" || {
+		warn "biome npm install failed (optional — use your stack's formatter/linter)"
+		return
+	}
 	if biome --version &>/dev/null; then
 		pass "biome $(biome --version 2>/dev/null | head -1)"
 	else
-		fail "biome --version failed"
+		warn "biome --version failed (optional — use your stack's formatter/linter)"
 	fi
 }