ultimate-pi 0.2.7 → 0.3.1

package/.agents/skills/harness-eval/SKILL.md

@@ -17,7 +17,7 @@ description: Run harness evaluation phase and emit EvalVerdict artifacts. Use wi
 2. Gather evidence: tests, diff scope, policy state, debate consensus packet.
 3. Emit verdict via `pi.appendEntry('harness-eval-verdict', { ... })` pattern (session custom entry).
 4. When Sentrux enabled, ensure `harness-sentrux-signal` exists (stub or MCP) per ADR 0006.
-5. Deterministic checks: `npm run harness:verify` and project test script.
+5. Deterministic checks: `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` (see `.pi/scripts/README.md`) and project test script.
 
 ## Verdict values
 

package/.agents/skills/harness-governor/SKILL.md

@@ -16,8 +16,8 @@ description: Enforce harness governance phases, policy gates, budgets, and promo
 1. Read current phase from `/harness-policy-status` or session `harness-policy-state`.
 2. Check ADRs: constitution (0001), eval promotion (0003), Sentrux (0006), drift (0007), rules lifecycle (0009).
 3. For promotion: require eval pass, no abort lock, debate consensus if escalated, Sentrux when `HARNESS_SENTRUX_REQUIRED=true`.
-4. After architecture changes: edit `.pi/harness/sentrux/architecture.manifest.json`, then `npm run harness:sentrux-sync` (or `/harness-sentrux-sync`).
-5. Run `npm run harness:verify` before claiming release readiness.
+4. After architecture changes: edit `.pi/harness/sentrux/architecture.manifest.json`, then `node "$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs" --force` (see `.pi/scripts/README.md` for `UP_PKG`) or `/harness-sentrux-sync`.
+5. Run `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` before claiming release readiness.
 
 ## Spec Distiller integration
 

package/.agents/skills/harness-spec/SKILL.md

@@ -16,7 +16,7 @@ description: Draft or refine harness artifact contracts under .pi/harness/specs.
 1. Read `.pi/harness/specs/README.md` for versioning rules (`contract_version`, optional fields only for compatible changes).
 2. Edit or add schema under `.pi/harness/specs/`.
 3. Update affected extensions to emit matching custom entries.
-4. Run `npm run harness:verify`.
+4. Run `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` (see `.pi/scripts/README.md`).
 5. Add or update an ADR under `.pi/harness/docs/adrs/` for breaking changes.
 
 ## Rules

package/.pi/PACKAGING.md

@@ -12,7 +12,7 @@ Aligned with [pi packages](https://github.com/badlogic/pi-mono/blob/main/package
 
 Pi does **not** define `scripts`, `agents`, or `providers` in the manifest.
 
-- **Harness scripts** → `.pi/scripts/` (npm `harness:*` scripts; see `.pi/scripts/README.md`)
+- **Harness scripts** → `.pi/scripts/` — run via `node` / `bash` and `$UP_PKG` (see `.pi/scripts/README.md`); do not require npm script aliases in consumer `package.json`
 - **Subagent agents** → `.pi/agents/**/*.md` (loaded by `@tintinweb/pi-subagents` from the **project** `.pi/agents/`; `/harness-setup` seeds them from the installed package)
 - **Providers** → install via `bundledDependencies` + user settings, not a separate manifest directory
 
@@ -22,6 +22,7 @@ We use an explicit allowlist (not the whole `.pi/` tree) so dev-only artifacts n
 
 - No `.pi/harness/runs/`, local `model-router.json`, or `firecrawl/.env`
 - Ship `.pi/settings.example.json`, not `.pi/settings.json` (dev checkout uses `".."` local package)
+- Include **`vendor/pi-model-router/`** ([`pi-model-router`](https://github.com/yeliu84/pi-model-router), MIT) — see repo [`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md); refresh with `npm run vendor:sync-router`
 
 ## Settings
 
@@ -34,4 +35,4 @@ We use an explicit allowlist (not the whole `.pi/` tree) so dev-only artifacts n
 
 Runtime pi extensions are regular `dependencies` (installed by `npm install` when pi installs the package). We do **not** use `bundledDependencies`: bundling pre-installs `node_modules` and breaks `npm install -g` / `pi update` for native modules such as `koffi` (empty stub dir, postinstall fails).
 
-`@mariozechner/pi-coding-agent` is a `peerDependency` (provided by the pi CLI).
+`@mariozechner/pi-coding-agent` (and sibling `@mariozechner/pi-ai`, `pi-tui`, `pi-agent-core` used by the vendored router) are provided by the Pi install / hoisted from the peer; ultimate-pi lists the latter three as `devDependencies` for `npm run check:ts`.

package/.pi/extensions/custom-header.ts

@@ -90,23 +90,6 @@ function ansiCell(
 }
 
 async function loadBanner(): Promise<string[]> {
-	// #region agent log
-	fetch("http://127.0.0.1:7928/ingest/a5d40896-34cb-4f12-97db-df7ada0b22f0", {
-		method: "POST",
-		headers: {
-			"Content-Type": "application/json",
-			"X-Debug-Session-Id": "7737a8",
-		},
-		body: JSON.stringify({
-			sessionId: "7737a8",
-			hypothesisId: "B",
-			location: "custom-header.ts:loadBanner",
-			message: "banner path",
-			data: { imagePath, cwd: process.cwd() },
-			timestamp: Date.now(),
-		}),
-	}).catch(() => {});
-	// #endregion
 	const Jimp = getJimpRuntime();
 	const image = await Jimp.read(imagePath);
 	resizeImageCompat(image, PIXEL_WIDTH, PIXEL_HEIGHT);

package/.pi/extensions/pi-model-router-harness.ts

@@ -0,0 +1,42 @@
+/**
+ * Vendored [pi-model-router](https://github.com/yeliu84/pi-model-router), gated behind
+ * a project-local `.pi/model-router.json` from `/harness-setup` so the extension
+ * (and built-in fallback tiers) never load before harness bootstrap.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import vendorModelRouter from "../../vendor/pi-model-router/extensions/index.js";
+
+function isHarnessRouterReady(cwd: string): boolean {
+	const path = join(cwd, ".pi", "model-router.json");
+	if (!existsSync(path)) {
+		return false;
+	}
+	try {
+		const data: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (typeof data !== "object" || data === null) {
+			return false;
+		}
+		const profiles = (data as { profiles?: unknown }).profiles;
+		return (
+			typeof profiles === "object" &&
+			profiles !== null &&
+			Object.keys(profiles).length > 0
+		);
+	} catch {
+		return false;
+	}
+}
+
+export default function piModelRouterHarness(pi: ExtensionAPI) {
+	const cwd = process.cwd();
+	if (!isHarnessRouterReady(cwd)) {
+		console.warn(
+			"[ultimate-pi] Model router disabled until `.pi/model-router.json` exists (generate via /harness-setup Step 3.5).",
+		);
+		return;
+	}
+	vendorModelRouter(pi);
+}

package/.pi/extensions/policy-gate.ts

@@ -178,6 +178,24 @@ export default function policyGate(pi: ExtensionAPI) {
 	pi.on("before_agent_start", async (event) => {
 		const bootstrapPrompt = isBootstrapPrompt(event.prompt);
 		const abortSignal = hasAbortSignal(event.prompt);
+
+		// /harness-setup instructions mention `harness-plan` (e.g. gh label text). That
+		// substring must not force inferPhase() to "plan" or bootstrap stays blocked.
+		if (bootstrapPrompt) {
+			state.phase = "execute";
+			state.approvedPlan = true;
+			state.planId = null;
+			state.budgetBypass = true;
+			state.aborted = false;
+			state.abortReason = null;
+			state.abortedAt = null;
+			state.updatedAt = nowIso();
+			pi.appendEntry("harness-policy-state", state);
+			return {
+				systemPrompt: `${event.systemPrompt}\n\n[PolicyGate]\nPhase=${state.phase}; ApprovedPlan=${state.approvedPlan}; PlanId=${state.planId ?? "none"}; Aborted=${state.aborted}; Bootstrap=harness-setup.`,
+			};
+		}
+
 		if (abortSignal) {
 			state.phase = "plan";
 			state.approvedPlan = false;

package/.pi/extensions/provider-payload-sanitize.ts

@@ -0,0 +1,66 @@
+/**
+ * Strip provider-specific fields from LLM request payloads before HTTP send.
+ *
+ * Strict OpenAI-compatible gateways return 400 when assistant history includes
+ * a top-level `reasoning` key (Cursor/thinking transcripts). Pi builds clean
+ * chat params; this is a safety net for any extra fields that slip through.
+ */
+
+import type {
+	BeforeProviderRequestEvent,
+	ExtensionAPI,
+} from "@mariozechner/pi-coding-agent";
+
+const CHAT_MESSAGE_EXTRA_KEYS = [
+	"reasoning",
+	"reasoning_text",
+	"chain_of_thought",
+	"chainOfThought",
+	"thinking",
+	"thought",
+] as const;
+
+function stripExtraChatFields(message: unknown): unknown {
+	if (
+		message === null ||
+		typeof message !== "object" ||
+		Array.isArray(message)
+	) {
+		return message;
+	}
+	const m = message as Record<string, unknown>;
+	if (typeof m.role !== "string") {
+		return message;
+	}
+	let touched = false;
+	const next = { ...m };
+	for (const k of CHAT_MESSAGE_EXTRA_KEYS) {
+		if (k in next) {
+			delete next[k];
+			touched = true;
+		}
+	}
+	return touched ? next : message;
+}
+
+function sanitizePayload(payload: unknown): unknown {
+	if (payload === null || typeof payload !== "object") {
+		return payload;
+	}
+	const body = payload as Record<string, unknown>;
+	const rawMessages = body.messages;
+	if (Array.isArray(rawMessages)) {
+		const messages = rawMessages.map(stripExtraChatFields);
+		if (messages.some((m, i) => m !== rawMessages[i])) {
+			return { ...body, messages };
+		}
+	}
+
+	return payload;
+}
+
+export default function providerPayloadSanitize(pi: ExtensionAPI) {
+	pi.on("before_provider_request", (event: BeforeProviderRequestEvent) => {
+		return sanitizePayload(event.payload);
+	});
+}

package/.pi/extensions/sentrux-rules-sync.ts

@@ -3,7 +3,6 @@
  */
 
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { resolveHarnessScript } from "./lib/harness-paths.js";
 
@@ -17,23 +16,6 @@ function resolveSyncScript(): string {
 
 function runSync(args: string[]): Promise<{ code: number; output: string }> {
 	const syncScript = resolveSyncScript();
-	// #region agent log
-	fetch("http://127.0.0.1:7928/ingest/a5d40896-34cb-4f12-97db-df7ada0b22f0", {
-		method: "POST",
-		headers: {
-			"Content-Type": "application/json",
-			"X-Debug-Session-Id": "7737a8",
-		},
-		body: JSON.stringify({
-			sessionId: "7737a8",
-			hypothesisId: "C",
-			location: "sentrux-rules-sync.ts:runSync",
-			message: "sync script path",
-			data: { syncScript, cwd: process.cwd(), exists: existsSync(syncScript) },
-			timestamp: Date.now(),
-		}),
-	}).catch(() => {});
-	// #endregion
 	return new Promise((resolve) => {
 		const child = spawn(process.execPath, [syncScript, ...args], {
 			cwd: process.cwd(),

package/.pi/harness/README.md

@@ -17,8 +17,9 @@ This scaffold is intentionally minimal and safe to adopt incrementally.
 ## Verification
 
 ```bash
-npm run harness:verify
-npm run harness:sentrux-sync   # after editing sentrux/architecture.manifest.json
+UP_PKG="$(node -p "require('path').dirname(require.resolve('ultimate-pi/package.json'))")"
+node "$UP_PKG/.pi/scripts/harness-verify.mjs"
+node "$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs" --force   # after editing sentrux/architecture.manifest.json
 ```
 
 ## Governance Extensions

package/.pi/harness/docs/adrs/0004-defer-ci-agent-smoke.md

@@ -15,7 +15,7 @@ Running full agent smoke or A/B harness comparisons in CI has high token cost an
 2. Deterministic schema/fixture CI is green for ≥4 weeks.
 3. At least 20 manual harness runs with `harness_run_completed` in PostHog.
 
-Phase 2 ships **deterministic** eval fixtures only (`npm run harness:verify`).
+Phase 2 ships **deterministic** eval fixtures only (`node "$UP_PKG/.pi/scripts/harness-verify.mjs"`; see `.pi/scripts/README.md`).
 
 ## Consequences
 

package/.pi/harness/docs/adrs/0006-sentrux-dual-layer.md

@@ -10,7 +10,7 @@ Evaluator trust requires both programmatic gates (policy, budget, integrity) and
 ## Decision
 
 1. **Rules file:** `.sentrux/rules.toml` synced from manifest — see [ADR 0009](0009-sentrux-rules-lifecycle.md).
-2. **CLI gate:** `npm run harness:verify` fails if `HARNESS_SENTRUX_REQUIRED=true` and no `harness-sentrux-signal` stub/file exists for the run (placeholder until MCP wired).
+2. **CLI gate:** `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` fails if `HARNESS_SENTRUX_REQUIRED=true` and no `harness-sentrux-signal` stub/file exists for the run (placeholder until MCP wired). Resolve `$UP_PKG` via [.pi/scripts/README.md](../../../scripts/README.md).
 3. **MCP layer (Q2+):** Evaluator sessions must record at least one Sentrux observation before `harness_eval_verdict` promotion when Sentrux is enabled.
 4. Observations flow through `observation-bus.ts` as `HarnessObservation` envelopes.
 5. PostHog event: `harness_sentrux_signal` with `signal_type` and `score` only — no secrets.

package/.pi/harness/docs/adrs/0009-sentrux-rules-lifecycle.md

@@ -11,13 +11,13 @@ Sentrux enforces architecture via [`.sentrux/rules.toml`](https://sentrux.dev/do
 
 1. **Canonical source:** [`.pi/harness/sentrux/architecture.manifest.json`](../../sentrux/architecture.manifest.json) — layers, boundaries, global constraints.
 2. **Generated artifact:** `.sentrux/rules.toml` — committed to git; managed block between `harness:managed:start/end` markers.
-3. **Sync command:** `npm run harness:sentrux-sync` (`.pi/scripts/sentrux-rules-sync.mjs`).
+3. **Sync command:** `node "$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs" --force` (resolve `$UP_PKG` via [.pi/scripts/README.md](../../../scripts/README.md)).
 4. **Pi command:** `/harness-sentrux-sync` via `sentrux-rules-sync.ts` extension.
 5. **When to sync:**
    - `/harness-setup` Step 2.8 (after sentrux install)
    - After editing `architecture.manifest.json`
    - On `agent_end` when harness phase is `plan` or `merge`
-   - `npm run harness:verify` fails if manifest hash ≠ last sync (`--check`)
+   - `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` fails if manifest hash ≠ last sync (`--check`)
 6. **Custom rules:** TOML outside the managed block is preserved on sync.
 
 ## Consequences

package/.pi/harness/evals/smoke/README.md

@@ -1,5 +1,5 @@
 # Deterministic harness smoke evals
 
-No LLM calls. Used by `npm run harness:verify` and CI.
+No LLM calls. Used by `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` and CI (see `.pi/scripts/README.md` for `UP_PKG`).
 
 Fixtures validate JSON schemas and golden expectations for trust-layer artifacts.

package/.pi/harness/evolution/README.md

@@ -5,7 +5,7 @@ Self-healing and meta-optimization read **JSONL first** (`.pi/harness/runs/*/eve
 ## Components
 
 - `self-healing-rules.json` — pattern → suggested remediation
-- `meta-optimizer.mjs` — scans run index, proposes router/tuning deltas
+- `meta-optimizer.mjs` — scans run index, proposes router/tuning deltas; run `node "$UP_PKG/.pi/harness/evolution/meta-optimizer.mjs"` (see `.pi/scripts/README.md`).
 - `chaos-drill.md` — manual chaos / failure injection checklist
 
 PostHog `harness_*` events are for dashboards; JSONL is the optimization source of truth per ADR 0008.

package/.pi/harness/evolution/chaos-drill.md

@@ -18,7 +18,7 @@ Run quarterly or before major harness releases. **No automation in Phase 2.**
 ## Pass criteria
 
 - All five scenarios produce expected custom entries and matching `harness_*` PostHog events within 60s.
-- `npm run harness:verify` still passes after drill.
+- `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` still passes after drill (see `.pi/scripts/README.md`).
 
 ## Rollback
 

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

@@ -41,6 +41,8 @@ echo "ultimate-pi package: $UP_PKG"
 
 For extension package names, read **`$UP_PKG/.pi/settings.example.json`** (shipped template). Merge its `packages` array into the **project** `.pi/settings.json` if missing — do not copy the repo-dev `.pi/settings.json` from the package (it may contain `".."` and is not published).
 
+If `require.resolve('ultimate-pi/package.json')` fails (bare clone without resolving the package name), run from **this repository root**: `UP_PKG="$(pwd)"`.
+
 ## Step 0.5 — Graphify (skip if `--skip-graphify`)
 
 **Critical:** `graphify . --wiki` and `graphify . --update` are **invalid** CLI (error: `unknown command '.'`). Use only:
@@ -57,12 +59,16 @@ Run from the **project root** (the external repo root, not ultimate-pi unless th
 ```bash
 mkdir -p ./raw .pi/harness/specs .pi/harness/runs .pi/harness/incidents .pi/harness/debates
 
-# Bundled with ultimate-pi harness; copy path if bootstrap runs from a linked harness checkout
-bash "$(node -p "require('path').join(require('path').dirname(require.resolve('ultimate-pi/package.json')),'.pi/scripts/harness-graphify-bootstrap.sh')")"
-# In ultimate-pi checkout: npm run harness:graphify-bootstrap
+# Copy JSON schemas + specs README from the package so plan-packet.schema.json exists
+# in the target repo immediately (before graphify or policy-gated planning).
+node "$UP_PKG/.pi/scripts/harness-seed-project-contracts.mjs" "$(pwd)"
+
+# Bundled with ultimate-pi harness; $UP_PKG is set in Step 0
+bash "$UP_PKG/.pi/scripts/harness-graphify-bootstrap.sh"
+# Developing ultimate-pi from repo root: UP_PKG="$(pwd)" then same command
 
 # Pass --force when $ARGUMENTS contains --force to rebuild an existing graph:
-# npm run harness:graphify-bootstrap -- --force
+# bash "$UP_PKG/.pi/scripts/harness-graphify-bootstrap.sh" --force
 ```
 
 If the bootstrap script is missing, run it from the installed ultimate-pi package (`.pi/scripts/` inside the npm package), or execute equivalent steps manually:
@@ -220,9 +226,9 @@ If user chose **cloud**, skip all 1.5.x steps. Just note:
 Run the bundled verifier from the **project root**. It installs missing npm globals, fixes common **Linux system dependencies** (Chrome libs for `agent-browser`), runs smoke tests, and exits non-zero if a required tool fails.
 
 ```bash
-npm run harness:cli-verify
-# ultimate-pi checkout: npm run harness:cli-verify
-# Reinstall everything: npm run harness:cli-verify -- --force
+bash "$UP_PKG/.pi/scripts/harness-cli-verify.sh"
+# ultimate-pi checkout: same (ensure Step 0 set UP_PKG="$(pwd)" or used require.resolve)
+# Reinstall everything: bash "$UP_PKG/.pi/scripts/harness-cli-verify.sh" --force
 ```
 
 **Required (script must exit 0):** firecrawl-cli, ctx7, biome, ast-grep (`sg`), sentrux (when harness manifest present).
@@ -237,14 +243,14 @@ sudo apt-get install -y libnss3 libnspr4 libgbm1 libatk1.0-0 libatk-bridge2.0-0
   libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \
   libasound2 libpango-1.0-0 libcairo2 libx11-6 libxcb1 libxext6 fonts-liberation
 agent-browser install --with-deps
-npm run harness:cli-verify
+bash "$UP_PKG/.pi/scripts/harness-cli-verify.sh"
 ```
 
 **Do not continue** past Step 2 if `harness-cli-verify.sh` exits non-zero.
 
 ### Manual reference (if script missing in target repo)
 
-Use `npm run harness:cli-verify` from the installed ultimate-pi package, or install tools individually:
+Use `bash "$UP_PKG/.pi/scripts/harness-cli-verify.sh"` (see Step 0 for `UP_PKG`), or install tools individually:
 
 ### 2.1 — firecrawl-cli (Web Search + Scrape + Crawl + Interact + Download + Parse)
 
@@ -420,10 +426,7 @@ Configure MCP server in `.pi/mcp.json` (see Step 4.3).
 
 Generate architectural rules from the harness manifest (creates/updates `.sentrux/rules.toml`):
 ```bash
-# From ultimate-pi checkout:
-npm run harness:sentrux-sync
-# From an external project (after pi install npm:ultimate-pi):
-npm run harness:sentrux-sync
+node "$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs" --force
 # Or in pi: /harness-sentrux-sync
 ```
 
@@ -441,7 +444,9 @@ sentrux gate --save . 2>/dev/null || echo "Baseline will be saved on first gate
 
 ## Step 3 — Pi Extension Packages
 
-Bundled extensions load from the installed `ultimate-pi` package. Optionally install the companion lockfile used in development:
+Bundled extensions load from the installed `ultimate-pi` package. **Per-turn 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 harness **gates** activation on `.pi/model-router.json` (Step **3.5** below) so `router/auto` and built-in tiers such as `openai/gpt-5.4-pro` 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`.
+
+Optionally install the companion lockfile used in development:
 
 ```bash
 UP_PKG="$(node -p "require('path').dirname(require.resolve('ultimate-pi/package.json'))")"
@@ -453,7 +458,7 @@ 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).
+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).
 
 Verify each package:
 
@@ -462,7 +467,8 @@ Verify each package:
 | `@posthog/pi` | Analytics event capture | F0 |
 | `pi-lean-ctx` | Context runtime (read/bash/find/grep/MCP bridge) | F0 |
 | `@tintinweb/pi-subagents` | L4 critic sub-agent spawn/control | P16 |
-| `@yeliu84/pi-model-router` | Per-turn intelligent model routing (auto high/medium/low tier selection) | F0 |
+| `@sting8k/pi-vcc` | VCC compaction / conversation memory | Shipped |
+| `pi-model-router` | Vendored (`vendor/`); activates after `.pi/model-router.json` exists | F0 |
 
 ## Step 3.5 — Model Router Configuration (Dynamic)
 
@@ -475,11 +481,12 @@ The script below:
 3. Only writes if file doesn't exist yet (safe to re-run, will skip existing)
 
 ```bash
-# Verify package installed first
-ls "$UP_PKG/node_modules/@yeliu84/pi-model-router/package.json" 2>/dev/null \
-  || ls "$UP_PKG/.pi/npm/node_modules/@yeliu84/pi-model-router/package.json" 2>/dev/null \
-  && echo "✓ model-router package" \
-  || echo "✗ model-router package — reinstall ultimate-pi or run npm install in $UP_PKG/.pi/npm"
+UP_PKG="$(node -p "require('path').dirname(require.resolve('ultimate-pi/package.json'))")"
+
+# 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 config from detected providers (only if missing)
 if [ -f .pi/model-router.json ]; then
@@ -587,15 +594,16 @@ console.log(`  Medium tier: ${mediumModel}`);
 console.log(`  Low tier: ${lowModel}`);
 GENDONE
 fi
-```
 
-Do NOT block. If generation fails, warn in report and continue.
+# Merge router defaults after config exists (never adds npm packages — router is vendored)
+node "$UP_PKG/.pi/scripts/harness-sync-model-router.mjs"
+```
 
-**Router is opt-in** — ultimate-pi no longer forces `defaultProvider: router` on install. After generating `model-router.json`, tell the user to enable routing when ready:
+Do NOT block. If generation fails, warn in report and continue (defaults script clears `defaultProvider` if it pointed at `router` while no config file exists).
 
-> `/router profile auto`
+**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`**) via `harness-sync-model-router.mjs` when `defaultProvider` was unset—then **`/reload`**.
 
-The pi TUI will intercept this and activate the `auto` profile. Then continue to Step 3.6.
+Manual override: **`/router profile auto`** anytime after reload if they changed defaults.
 
 ## Step 3.6 — Seed `.pi/agents` (pi-subagents)
 
@@ -702,7 +710,7 @@ Created: $(date +%Y-%m-%d)
 Re-run CLI verification (must pass unless `--skip-tools`):
 
 ```bash
-npm run harness:cli-verify
+bash "$UP_PKG/.pi/scripts/harness-cli-verify.sh"
 ```
 
 Then run the remaining checks:
@@ -741,10 +749,9 @@ 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"
 
-# model router
-ls "$UP_PKG/node_modules/@yeliu84/pi-model-router/package.json" 2>/dev/null \
-  || ls "$UP_PKG/.pi/npm/node_modules/@yeliu84/pi-model-router/package.json" 2>/dev/null \
-  && echo "✓ model-router package" || echo "✗ model-router package"
+# 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"
 
 # raw folder for graphify sources
@@ -801,7 +808,7 @@ Output summary table:
 
 Next steps:
 1. If tools missing: re-run with `--force` or install individually
-2. If graph not built: run `npm run harness:graphify-bootstrap` (or `graphify update .` from project root)
+2. If graph not built: run `bash "$UP_PKG/.pi/scripts/harness-graphify-bootstrap.sh"` (or `graphify update .` from project root)
 3. If hooks not installed: run `graphify hook install`
 4. If gh not authenticated: `gh auth login`
 5. If self-hosted Firecrawl unhealthy: `docker compose -f firecrawl/docker-compose.yaml logs`
@@ -811,9 +818,9 @@ Next steps:
 ## Guard Rails
 
 - **Internet required**: Several tools need npm registry access. Block if offline.
-- **CLI verify script**: Step 2 and Step 5 use `npm run harness:cli-verify` (`.pi/scripts/harness-cli-verify.sh`) — installs npm globals, Linux Chrome system libs for `agent-browser`, and smoke-tests each tool. Block on non-zero exit.
+- **CLI verify script**: Step 2 and Step 5 run `bash "$UP_PKG/.pi/scripts/harness-cli-verify.sh"` — installs npm globals, Linux Chrome system libs for `agent-browser`, and smoke-tests each tool. Block on non-zero exit.
 - **Graphify requires Python 3.10+**: Check `python3 --version`. Block if too old.
-- **Graphify bootstrap is mandatory** (unless `--skip-graphify`): Run `npm run harness:graphify-bootstrap`. Never use `graphify . --wiki`. Initial setup must run `graphify update .` and verify `graphify-out/graph.json` has nodes.
+- **Graphify bootstrap is mandatory** (unless `--skip-graphify`): Run `bash "$UP_PKG/.pi/scripts/harness-graphify-bootstrap.sh"`. Never use `graphify . --wiki`. Initial setup must run `graphify update .` and verify `graphify-out/graph.json` has nodes.
 - **Python packages (Graphify)**: Before install, detect via PATH, `pip`/`pip3 show graphifyy`, `uv`, or apt. Prefer `uv tool install graphifyy`.
 - **Node.js >= 18 required**: Some pi packages use modern Node APIs.
 - **Docker required for self-hosted**: Step 1.5 needs Docker Engine + Compose. Block if install fails.
@@ -836,7 +843,7 @@ Next steps:
 | Graphify install fails | Show installer output. Retry `uv tool install graphifyy` or `pip3 install --user graphifyy`. Ensure `~/.local/bin` is on PATH. |
 | `graphify update .` fails | Block setup. Corpus may have no code files, or graphify not on PATH. Show stderr. |
 | Invalid `graphify .` usage | Replace with `graphify update .` — the `.` subcommand does not exist. |
-| graphify-out empty / 0 nodes | Re-run `npm run harness:graphify-bootstrap -- --force` from project root. |
+| graphify-out empty / 0 nodes | Re-run `bash "$UP_PKG/.pi/scripts/harness-graphify-bootstrap.sh" --force` from project root. |
 | graphify hook install fails | Hooks need `.git/` directory. Verify inside git repo. Manual: `git config core.hooksPath .pi/git-hooks` |
 | firecrawl auth failed | Show manual login instructions. Continue with other tools. |
 | gh not installed | Show GitHub CLI install link. Skip label creation. |

package/.pi/scripts/README.md

@@ -2,16 +2,32 @@
 
 These scripts ship inside the `ultimate-pi` npm package under `.pi/scripts/`.
 
-Pi's package manifest (`package.json` → `pi`) only loads **extensions**, **skills**, **prompts**, and **themes** — there is no `scripts` field. Harness scripts are invoked via:
+Pi's package manifest (`package.json` → `pi`) only loads **extensions**, **skills**, **prompts**, and **themes** — there is no `scripts` field. **Do not rely on npm `harness:*` scripts** in the consuming project's `package.json`; external repos that install `ultimate-pi` may not define them.
 
-- `npm run harness:*` (see root `package.json`)
-- Extensions resolving paths with `resolveHarnessScript()` in `.pi/extensions/lib/harness-paths.ts`
+## Resolve `ultimate-pi` package root (`UP_PKG`)
 
-| Script | npm script |
-|--------|------------|
-| `harness-graphify-bootstrap.sh` | `harness:graphify-bootstrap` |
-| `harness-cli-verify.sh` | `harness:cli-verify` |
-| `harness-verify.mjs` | `harness:verify` |
-| `sentrux-rules-sync.mjs` | `harness:sentrux-sync` |
+**Consumer repo** (`ultimate-pi` in `node_modules`):
+
+```bash
+UP_PKG="$(node -p "require('path').dirname(require.resolve('ultimate-pi/package.json'))")"
+```
+
+**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`.
+
+## Invocations (from the consuming project root)
+
+| Action | Command |
+|--------|---------|
+| Graphify bootstrap | `bash "$UP_PKG/.pi/scripts/harness-graphify-bootstrap.sh"` |
+| CLI tool install + smoke tests | `bash "$UP_PKG/.pi/scripts/harness-cli-verify.sh"` |
+| Deterministic harness checks | `node "$UP_PKG/.pi/scripts/harness-verify.mjs"` |
+| Sentrux rules from manifest | `node "$UP_PKG/.pi/scripts/sentrux-rules-sync.mjs" --force` |
+| 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"` |
+
+Pass `--force` to shell scripts that support it (e.g. `harness-graphify-bootstrap.sh --force`, `harness-cli-verify.sh --force`).
 
 Repo-root `scripts/` (e.g. `regen_graphify_html.py`) is dev-only and excluded from the npm tarball via `.npmignore`.

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

@@ -259,8 +259,10 @@ verify_sentrux() {
 		return
 	fi
 	sentrux plugin add-standard 2>/dev/null || warn "sentrux plugin add-standard skipped"
-	if [ -f package.json ] && grep -q harness:sentrux-sync package.json 2>/dev/null; then
-		npm run harness:sentrux-sync 2>/dev/null || warn "npm run harness:sentrux-sync failed (needs package.json scripts)"
+	_sync_script="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/sentrux-rules-sync.mjs"
+	if [ -f "$_sync_script" ]; then
+		node "$_sync_script" --force 2>/dev/null ||
+			warn "sentrux rules sync failed (see .pi/scripts/README.md)"
 	fi
 	if sentrux check . &>/dev/null; then
 		pass "sentrux $(sentrux --version 2>/dev/null | head -1)"

package/.pi/scripts/harness-seed-project-contracts.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * Copy harness JSON contracts (and specs README) from the installed ultimate-pi
+ * package into the current project. External repos get `.pi/harness/specs/` before
+ * graphify or /harness-plan so paths like plan-packet.schema.json resolve locally.
+ *
+ * Usage:
+ *   node "$UP_PKG/.pi/scripts/harness-seed-project-contracts.mjs" [PROJECT_ROOT]
+ *
+ * PROJECT_ROOT defaults to process.cwd(). Package root is derived from this file
+ * (the script always lives under the shipped ultimate-pi package).
+ */
+
+import { copyFile, mkdir, readdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const UP_PKG = join(SCRIPT_DIR, "..", "..");
+const SPEC_SRC = join(UP_PKG, ".pi", "harness", "specs");
+
+const projectRoot = process.argv[2] || process.cwd();
+const specDest = join(projectRoot, ".pi", "harness", "specs");
+
+async function main() {
+	const names = await readdir(SPEC_SRC);
+	const toCopy = names.filter(
+		(n) => n.endsWith(".schema.json") || n === "README.md",
+	);
+	if (toCopy.length === 0) {
+		console.error(
+			"harness-seed-project-contracts: no schema files under",
+			SPEC_SRC,
+		);
+		process.exit(1);
+	}
+	await mkdir(specDest, { recursive: true });
+	for (const name of toCopy) {
+		await copyFile(join(SPEC_SRC, name), join(specDest, name));
+	}
+	console.log(
+		`harness-seed-project-contracts: copied ${toCopy.length} file(s) -> ${specDest}`,
+	);
+}
+
+main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});