@juicesharp/rpiv-pi 1.17.0 → 1.18.0

package/README.md

@@ -8,7 +8,9 @@
   </a>
 </div>
 
-> **Pi compatibility** - `rpiv-pi` `0.14.x` tracks `@earendil-works/pi-coding-agent` `0.70.x` and `@tintinweb/pi-subagents` `0.6.x`. If you see peer-dep resolution issues after a Pi upgrade, open an issue.
+> **Pi compatibility** - `rpiv-pi` tracks `@earendil-works/pi-coding-agent` and `@tintinweb/pi-subagents` `0.10.x`. If you see peer-dep resolution issues after a Pi upgrade, open an issue.
+
+> **⚠️ Upgrading to `@tintinweb/pi-subagents` `0.10.x`** - frontmatter tool gating changed: extension tools now route through `ext:<extension>/<tool>`. The bundled `web-search-researcher` is migrated - run `/rpiv-update-agents` to refresh it. Customised copies need a manual edit (see CHANGELOG).
 
 > **⚠️ Upgrading from `0.13.x`** - `1.0.0` swaps the subagent provider from `npm:pi-subagents` (nicobailon fork) back to `npm:@tintinweb/pi-subagents` (resumed maintenance). On first launch after upgrade you'll see *"rpiv-pi requires 1 sibling extension(s): @tintinweb/pi-subagents"* - **run `/rpiv-setup` once and restart Pi**. The setup dialog previews both changes (install `@tintinweb/pi-subagents`, remove `npm:pi-subagents` from `~/.pi/agent/settings.json`) and applies them only after you confirm. After restart, run `/rpiv-update-agents` to refresh the 12 bundled specialist frontmatters. Customised `<cwd>/.pi/agents/*.md` files are not touched. The tool name reverts from `subagent` → `Agent` (param `subagent_type`/`description`/`prompt`) - only your own custom skills/agents need editing; the bundled rpiv-pi specialists are migrated in this release.
 
@@ -169,7 +171,7 @@ Invoke via `/skill:<name>` from inside a Pi Agent session.
 | Command | Description |
 |---|---|
 | `/rpiv-setup` | Install all sibling plugins in one go |
-| `/rpiv-update-agents` | Refresh `~/.pi/agent/agents/` from bundled agent definitions and clean up legacy per-project agent directories |
+| `/rpiv-update-agents` | Refresh `~/.pi/agent/agents/` from bundled agent definitions and clean up legacy per-project agent directories. Re-reads `models.json` before syncing, so mid-session per-agent `model`/`thinking` overrides take effect on disk |
 | `/advisor` | Configure advisor model and reasoning effort |
 | `/btw` | Ask a side question without polluting the main conversation _(requires `@juicesharp/rpiv-btw`, opt-in)_ |
 | `/languages` | Pick the UI language for rpiv-* TUI strings (Deutsch / English / Español / Français / Português / Português (Brasil) / Русский / Українська) |
@@ -210,12 +212,68 @@ Pi Agent discovers extensions via `"extensions": ["./extensions"]` and skills vi
 
 - **Web search** - run `/web-search-config` to pick a provider (Brave, Tavily, Serper, Exa, Jina, or Firecrawl) and set its API key; the per-provider env var (e.g. `BRAVE_SEARCH_API_KEY`, `EXA_API_KEY`) also works and takes precedence
 - **Advisor** - run `/advisor` to select a reviewer model and reasoning effort
+- **Models & reasoning effort** - run `/rpiv-models` to pick a model and reasoning level for the global default, a specific bundled agent, a workflow stage, a skill, or a per-preset stage; the picker writes `~/.config/rpiv-pi/models.json`. See **Model configuration** below for the cascade ladder and worked examples.
 - **Side questions** _(opt-in: `pi install npm:@juicesharp/rpiv-btw`)_ - type `/btw <question>` anytime (even mid-stream) to ask the primary model a one-off question; answer appears in a borderless bottom overlay and never enters the main conversation
 - **UI language** - run `/languages` to pick the locale for rpiv-* TUI strings, or pass `pi --locale <code>` at startup. Detection priority: flag → `~/.config/rpiv-i18n/locale.json` → `LANG` / `LC_ALL` → English. LLM-facing copy stays English by design
 - **Agent concurrency** - open the `/agents` overlay and tune `Settings → Max concurrency` to match your provider's rate limits. `@tintinweb/pi-subagents` owns this setting; rpiv-pi does not seed it.
 - **Agent profiles** - synced to `~/.pi/agent/agents/` from bundled defaults; refresh with `/rpiv-update-agents` (overwrites rpiv-managed files, preserves your custom agents).
 - **Non-default agent directory** - if you set `PI_CODING_AGENT_DIR` (e.g. `~/.config/pi/agent` for an XDG-style layout), rpiv-pi reads and writes the same `settings.json` Pi does — sibling detection, `/rpiv-setup`, and `/rpiv-update-agents` all follow the env var. Leading `~` is expanded.
 
+### Model configuration (models.json)
+
+`rpiv-pi` reads `~/.config/rpiv-pi/models.json` to apply per-agent, per-stage, per-skill, and per-preset model + reasoning-effort overrides. The file is optional — missing or malformed JSON degrades to no overrides. Run `/rpiv-models` to edit it via cascade pickers, or hand-edit.
+
+**Cascade ladder** (most specific first; each layer composes per-field against `defaults`):
+
+1. `presets[workflow].stages[stage]` — per-workflow per-stage override (e.g. `ship.plan`).
+2. `stages[stage]` — flat per-stage override (applies across every workflow that has it).
+3. `skills[skill]` — per-skill override; applies to **both** `/wf` workflow stages AND user-typed standalone `/skill:<name>` invocations.
+4. `defaults` — global fallback.
+
+The standalone `/skill:` bracket has one exception: it arms ONLY on an explicit `skills[<name>]` entry. `defaults` does NOT trigger arming for user-typed `/skill:` invocations — your current session model stays sovereign.
+
+**Worked example A — per-skill overrides for everyday short turns**:
+
+```json
+{
+  "defaults": "anthropic/claude-opus-4-7",
+  "skills": {
+    "commit": "zai/glm-4-7",
+    "changelog": "zai/glm-4-7",
+    "research": { "model": "openai/gpt-5.5", "thinking": "high" }
+  }
+}
+```
+
+With this file, your default is Opus; `/skill:commit` and `/skill:changelog` use the cheaper GLM-4.7; `/skill:research` uses GPT-5.5 at high reasoning effort. Workflow-dispatched runs of the same skills get the same overrides (via the cascade's skill rung).
+
+**Worked example B — per-workflow stage overrides for full pipelines**:
+
+```json
+{
+  "defaults": "anthropic/claude-opus-4-7",
+  "presets": {
+    "ship": {
+      "stages": {
+        "plan":   "openai/gpt-5.5",
+        "design": { "model": "openai/gpt-5.5", "thinking": "high" }
+      }
+    },
+    "polish": {
+      "stages": {
+        "plan": "zai/glm-4-7"
+      }
+    }
+  }
+}
+```
+
+With this file, `/wf ship plan` and `/wf ship design` use GPT-5.5; `/wf polish plan` uses GLM-4.7; everything else falls through to Opus. Per-workflow overrides take precedence over the flat `stages` block when both define the same stage.
+
+**Model key form** — canonical is `provider/modelId` (slash-separated). The legacy `provider:modelId` (colon) form still parses for back-compatibility with persisted advisor configs; new saves emit slash form, and legacy values auto-migrate on the next save.
+
+**Reasoning levels** — six values accepted in the `thinking` field: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. Note the distinction between **`off`** (explicitly disable reasoning) and **omitting** the field (inherit the session/baseline level). In `/rpiv-models` the effort picker offers `inherit (no override)` and `off (disable reasoning)` as separate choices. Any other value is rejected with a warning.
+
 ## Uninstall
 
 1. Remove rpiv-pi from Pi: `pi uninstall npm:@juicesharp/rpiv-pi`

package/agents/slice-verifier.md

@@ -37,6 +37,7 @@ The caller's dispatch prompt provides:
 - `slice_id` — identifier for the slice under audit, in whatever vocabulary the orchestrator uses
 - `current_slice_code` — verbatim content of the just-generated slice the orchestrator intends to lock, covering BOTH the code fences (every `#### N. path/...` block) AND the slice's success criteria (`### Success Criteria:` Automated + Manual subsections). When present, audit this AS the current slice; the artifact's `slice_id` section may legitimately be a skeleton (empty code fence + empty criteria) at this stage because writes are gated on developer approval. When absent, fall back to the artifact's `slice_id` section — and if that is also empty, the slice is truly missing and that is a real violation.
 - `target_files` — files the slice modifies, depends on, or assumes about
+- `overlapping_priors` — OPTIONAL. Precomputed list of priors sharing a file/symbol with this slice; drives Step 3 when present.
 
 Read the artifact in full (no limit/offset). Read every target file in full.
 
@@ -48,7 +49,9 @@ Locate the artifact's commitments — architectural decisions, contracts, scoped
 
 ### Step 3: Cross-slice audit
 
-Walk every change/file in every locked prior slice (slice headings preceding `slice_id` in artifact order). For each: state what it produced, check the current slice for overlaps/collisions/redeclarations, verify every cross-slice symbol reference matches character-for-character, verify every claim the current slice makes about prior-slice behaviors against the projected intermediate state.
+If `overlapping_priors` is given, trust it: deep-walk exactly those prior slices, collapse the rest to one `no overlap — <slice ids>` note. Otherwise, partition locked prior slices (headings preceding `slice_id` in artifact order) by overlap with the current slice: a prior slice OVERLAPS if it touches a `target_files` entry OR declares a symbol the current slice references. Non-overlapping slices cannot collide — collapse them to one aggregate note (`no overlap — <slice ids>`) and do not walk them.
+
+Walk every OVERLAPPING prior slice in full. For each: state what it produced, check the current slice for overlaps/collisions/redeclarations, verify every cross-slice symbol reference matches character-for-character, verify every claim the current slice makes about prior-slice behaviors against the projected intermediate state.
 
 The projected intermediate state is HEAD plus every locked prior slice's code fence applied in order — a symbol, file, or export declared NEW in an upstream slice exists in that pre-state even though it is absent from HEAD. Verify cross-slice references against the upstream slice's code fence in the artifact, not against the live working tree.
 

package/agents/web-search-researcher.md

@@ -1,7 +1,8 @@
 ---
 name: web-search-researcher
 description: Do you find yourself desiring information that you don't quite feel well-trained (confident) on? Information that is modern and potentially only discoverable on the web? Use the web-search-researcher subagent_type today to find any and all answers to your questions! It will research deeply to figure out and attempt to answer your questions! If you aren't immediately satisfied you can get your money back! (Not really - but you can re-run web-search-researcher with an altered prompt in the event you're not satisfied the first time)
-tools: web_search, web_fetch, read, grep, find, ls
+extensions: [rpiv-web-tools]
+tools: read, grep, find, ls, ext:rpiv-web-tools/web_search, ext:rpiv-web-tools/web_fetch
 ---
 
 You are an expert web research specialist focused on finding accurate, relevant information from web sources. Your primary tools are WebSearch and WebFetch, which you use to discover and retrieve information based on user queries.

package/extensions/rpiv-core/agents.test.ts

@@ -16,11 +16,13 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
 	CLEANUP_SKIP_REASON,
 	cleanupPerCwdAgents,
+	injectModelFrontmatter,
 	isSafeDestructiveOp,
 	SYNC_OP,
 	summarizeCleanupSkips,
 	syncBundledAgents,
 } from "./agents.js";
+import type { ModelsConfig } from "./models-config.js";
 import { BUNDLED_AGENTS_DIR } from "./paths.js";
 
 const sha256 = (s: string | Buffer) => createHash("sha256").update(s).digest("hex");
@@ -915,3 +917,121 @@ describe("isSafeDestructiveOp", () => {
 		expect(isSafeDestructiveOp({ hasV2Data: false, knownHash: HASH_A, destHash: HASH_B })).toBe(false);
 	});
 });
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Agent frontmatter injection (Phase 2)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("agent frontmatter injection", () => {
+	const agentContent = [
+		"---",
+		"name: test-agent",
+		"description: Test agent",
+		"tools: grep, find",
+		"isolated: true",
+		"---",
+		"",
+		"You are a test agent.",
+	].join("\n");
+
+	// --- Direct unit tests on the pure transform (the load-bearing invariants) ---
+
+	const cfg: ModelsConfig = {
+		agents: { "test-agent": { model: "anthropic/claude-sonnet-4-20250514", thinking: "high" } },
+	};
+
+	it("injects model and thinking before the closing ---", () => {
+		const out = injectModelFrontmatter(agentContent, "test-agent.md", cfg);
+		// Post-slash-canonical migration: models.json value passes through to
+		// frontmatter byte-for-byte. No translation step.
+		expect(out).toContain("model: anthropic/claude-sonnet-4-20250514");
+		expect(out).toContain("thinking: high");
+		// Injected keys land inside the frontmatter block, before the body.
+		const fmEnd = out.indexOf("\n---", 3);
+		expect(out.indexOf("model:")).toBeLessThan(fmEnd);
+		expect(out.indexOf("You are a test agent.")).toBeGreaterThan(fmEnd);
+	});
+
+	it("is idempotent — inject(inject(x)) === inject(x) (drift prevention)", () => {
+		const once = injectModelFrontmatter(agentContent, "test-agent.md", cfg);
+		const twice = injectModelFrontmatter(once, "test-agent.md", cfg);
+		expect(twice).toBe(once);
+	});
+
+	it("emits the models.json model value byte-for-byte (strengthened idempotency)", () => {
+		const out = injectModelFrontmatter(agentContent, "test-agent.md", cfg);
+		const fmModelLine = out.split("\n").find((l) => l.startsWith("model: "));
+		// Post-slash-canonical: the frontmatter `model:` value equals the
+		// models.json `model` field char-for-char — no translation layer.
+		expect(fmModelLine).toBe(`model: ${cfg.agents!["test-agent"].model}`);
+	});
+
+	it("returns content unchanged when no override is configured", () => {
+		expect(injectModelFrontmatter(agentContent, "other-agent.md", cfg)).toBe(agentContent);
+		expect(injectModelFrontmatter(agentContent, "test-agent.md", {})).toBe(agentContent);
+	});
+
+	it("replaces an existing model key in place rather than duplicating it", () => {
+		const withModel = agentContent.replace("name: test-agent", "name: test-agent\nmodel: openai/gpt-5.5");
+		const out = injectModelFrontmatter(withModel, "test-agent.md", cfg);
+		expect(out.match(/^model:/gm)?.length).toBe(1);
+		expect(out).toContain("model: anthropic/claude-sonnet-4-20250514");
+	});
+
+	it("injects an explicit thinking: off (disable reasoning) and stays idempotent", () => {
+		const offCfg: ModelsConfig = { agents: { "test-agent": { model: "anthropic/opus", thinking: "off" } } };
+		const out = injectModelFrontmatter(agentContent, "test-agent.md", offCfg);
+		expect(out).toContain("thinking: off");
+		expect(injectModelFrontmatter(out, "test-agent.md", offCfg)).toBe(out);
+	});
+
+	it("cascades a defaults model into an otherwise-unconfigured agent", () => {
+		const defaultsCfg: ModelsConfig = {
+			defaults: { model: "openai/o3-pro" },
+			agents: { "other-agent": { model: "openai/o3-pro" } },
+		};
+		const out = injectModelFrontmatter(agentContent, "test-agent.md", defaultsCfg);
+		expect(out).toContain("model: openai/o3-pro");
+	});
+
+	// --- End-to-end sync seam tests (real bundled agent) ---
+
+	const REAL_AGENT = "codebase-analyzer.md";
+	const writeModels = (config: unknown) => {
+		const dir = join(homedir(), ".config", "rpiv-pi");
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(join(dir, "models.json"), JSON.stringify(config), "utf-8");
+	};
+	const destContent = (name: string) => readFileSync(join(homedir(), ".pi", "agent", "agents", name), "utf-8");
+
+	it("injects model and thinking into the synced agent .md file", () => {
+		writeModels({ agents: { "codebase-analyzer": { model: "openai/o3-pro", thinking: "high" } } });
+
+		const result = syncBundledAgents(true);
+		expect([...result.added, ...result.updated, ...result.unchanged]).toContain(REAL_AGENT);
+
+		const written = destContent(REAL_AGENT);
+		expect(written).toContain("model: openai/o3-pro");
+		expect(written).toContain("thinking: high");
+	});
+
+	it("produces no false pendingUpdate when re-synced (idempotent on disk)", () => {
+		writeModels({ agents: { "codebase-analyzer": { model: "openai/o3-pro", thinking: "high" } } });
+
+		syncBundledAgents(true);
+		const result2 = syncBundledAgents(false);
+
+		// Re-sync must see the injected agent as unchanged, never pendingUpdate.
+		expect(result2.pendingUpdate).not.toContain(REAL_AGENT);
+		expect(result2.unchanged).toContain(REAL_AGENT);
+	});
+
+	it("does not inject when no config exists for the agent", () => {
+		// No models.json — global test setup already removed it in beforeEach.
+		const result = syncBundledAgents(true);
+		expect([...result.added, ...result.updated, ...result.unchanged]).toContain(REAL_AGENT);
+
+		// Dest content must equal the raw bundled source — no frontmatter injected.
+		expect(destContent(REAL_AGENT)).toBe(bundledContent(REAL_AGENT));
+	});
+});

package/extensions/rpiv-core/agents.ts

@@ -16,7 +16,6 @@
 
 import { createHash } from "node:crypto";
 import {
-	copyFileSync,
 	existsSync,
 	mkdirSync,
 	readdirSync,
@@ -28,6 +27,8 @@ import {
 } from "node:fs";
 import { isAbsolute, join, resolve, sep } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { parseFrontmatterBounds } from "./frontmatter.js";
+import { getAgentModelConfig, loadModelsConfig, type ModelsConfig } from "./models-config.js";
 import { BUNDLED_AGENTS_DIR } from "./paths.js";
 import { isPlainObject, toErrorMessage } from "./utils.js";
 
@@ -327,6 +328,80 @@ function enumerateSourceFiles(result: SyncResult): string[] | null {
 	}
 }
 
+/**
+ * Apply key-value updates to frontmatter lines.
+ *
+ * For each key in `keysToSet`, replaces the existing line if present
+ * (within the frontmatter bounds), or inserts a new line before the
+ * closing `---`. Returns the (possibly modified) lines array.
+ *
+ * The closing-fence index (`bounds.end`) is stable across in-place
+ * replacements — only the value changes, not the line count — so the
+ * insertion point remains correct without re-scanning.
+ */
+function applyKeyUpdates(
+	lines: string[],
+	bounds: { start: number; end: number },
+	keysToSet: { key: string; value: string }[],
+): string[] {
+	const result = [...lines];
+	const insertLines: string[] = [];
+
+	for (const { key, value } of keysToSet) {
+		const prefix = `${key}: `;
+		const existingIdx = result.findIndex((line, i) => i > 0 && i < bounds.end && line.startsWith(prefix));
+		if (existingIdx !== -1) {
+			result[existingIdx] = `${prefix}${value}`;
+		} else {
+			insertLines.push(`${prefix}${value}`);
+		}
+	}
+
+	if (insertLines.length > 0) {
+		result.splice(bounds.end, 0, ...insertLines);
+	}
+
+	return result;
+}
+
+/**
+ * Inject model/thinking frontmatter into agent .md content.
+ *
+ * Idempotent: re-injecting produces identical bytes. The function finds
+ * the closing `---` of the YAML frontmatter block and inserts or replaces
+ * `model:` and `thinking:` lines deterministically.
+ *
+ * If no override is configured for this agent, returns content unchanged.
+ *
+ * Exported so the idempotency invariant can be unit-tested directly:
+ * `inject(inject(x)) === inject(x)` (see Verification Notes).
+ */
+export function injectModelFrontmatter(content: string, agentFile: string, config: ModelsConfig): string {
+	// Strip .md extension — source entries are filenames like "codebase-analyzer.md"
+	// but models.json keys are agent names like "codebase-analyzer".
+	const agentKey = agentFile.replace(/\.md$/, "");
+	const override = getAgentModelConfig(config, agentKey);
+	if (!override || (override.model === undefined && override.thinking === undefined)) {
+		return content;
+	}
+
+	const lines = content.split("\n");
+	const bounds = parseFrontmatterBounds(lines);
+	if (!bounds) return content;
+
+	const keysToSet: { key: string; value: string }[] = [];
+	// D9 (post-slash-canonical migration): models.json values are byte-equal to
+	// the agent frontmatter form (both `provider/modelId`). No translation step
+	// — re-injecting produces identical bytes by construction; the idempotency
+	// invariant at injectModelFrontmatter's JSDoc strengthens from "deterministic
+	// translation" to "byte pass-through".
+	if (override.model !== undefined) keysToSet.push({ key: "model", value: override.model });
+	if (override.thinking !== undefined) keysToSet.push({ key: "thinking", value: override.thinking });
+
+	const updated = applyKeyUpdates(lines, bounds, keysToSet);
+	return updated.join("\n");
+}
+
 /**
  * Step 2: Process each source file — copy new, record unchanged, update or gate.
  * Returns the new manifest built from source entries.
@@ -341,6 +416,10 @@ function processSourceEntries(
 ): Manifest {
 	const newManifest: Manifest = {};
 
+	// Hoisted above the loop: loadModelsConfig() reads+parses JSON, so calling it
+	// per-entry would re-read the file once per agent (~15×) every session_start.
+	const config = loadModelsConfig();
+
 	for (const entry of sourceEntries) {
 		const src = join(BUNDLED_AGENTS_DIR, entry);
 		const dest = safeJoin(targetDir, entry);
@@ -359,11 +438,16 @@ function processSourceEntries(
 			newManifest[entry] = knownHash;
 			continue;
 		}
-		const srcHash = sha256(srcContent);
+		// Inject configured model/thinking frontmatter BEFORE hashing so the
+		// manifest hash matches what actually lands on disk (D4: hash-after-transform).
+		// injectModelFrontmatter strips .md from entry for config lookup and is a
+		// no-op when no override is configured.
+		const injected = injectModelFrontmatter(srcContent.toString("utf-8"), entry, config);
+		const srcHash = sha256(injected);
 
 		if (!existsSync(dest)) {
 			try {
-				copyFileSync(src, dest);
+				writeFileSync(dest, injected, "utf-8");
 				result.added.push(entry);
 				newManifest[entry] = srcHash;
 			} catch (e) {
@@ -391,7 +475,7 @@ function processSourceEntries(
 
 		if (apply || isSafeDestructiveOp({ hasV2Data, knownHash, destHash })) {
 			try {
-				copyFileSync(src, dest);
+				writeFileSync(dest, injected, "utf-8");
 				result.updated.push(entry);
 				newManifest[entry] = srcHash;
 			} catch (e) {
@@ -581,7 +665,10 @@ export function cleanupPerCwdAgents(cwd: string): CleanupResult {
 		return result;
 	}
 
-	// Edge state 2: verify all managed files match current source content
+	// Edge state 2: verify all managed files match current source content.
+	// Hoisted config read (same reasoning as processSourceEntries): one JSON
+	// read for the whole cleanup pass, not one per managed file.
+	const cleanupConfig = loadModelsConfig();
 	for (const [name] of Object.entries(manifest)) {
 		const srcPath = safeJoin(BUNDLED_AGENTS_DIR, name);
 		const destPath = safeJoin(perCwdDir, name);
@@ -615,7 +702,11 @@ export function cleanupPerCwdAgents(cwd: string): CleanupResult {
 			return result;
 		}
 
-		if (sha256(destContent) !== sha256(srcContent)) {
+		// Compare against the injected form — the dest holds injected content
+		// (D4), so comparing raw source would falsely flag every configured agent
+		// as diverged. injectModelFrontmatter strips .md from name for lookup.
+		const cleanupInjected = injectModelFrontmatter(srcContent.toString("utf-8"), name, cleanupConfig);
+		if (sha256(destContent) !== sha256(cleanupInjected)) {
 			// User edited this file — conservative gate.
 			result.skipped.push({ dir: perCwdDir, reason: CLEANUP_SKIP_REASON.DIVERGED });
 			return result;

package/extensions/rpiv-core/artifact-collector.ts

@@ -34,7 +34,8 @@ import {
 	type OutputSpec,
 	type ParseCtx,
 	transcriptPathCollector,
-} from "@juicesharp/rpiv-workflow";
+	// Runner-free entry — keeps the ~530ms engine off the startup path.
+} from "@juicesharp/rpiv-workflow/registration";
 
 // ---------------------------------------------------------------------------
 // Collectors — text-scan over assistant transcript

package/extensions/rpiv-core/built-in-workflows.ts

@@ -34,7 +34,7 @@ import {
 	type RunState,
 	typeboxSchema,
 	type Workflow,
-} from "@juicesharp/rpiv-workflow";
+} from "@juicesharp/rpiv-workflow/registration";
 import { Type } from "typebox";
 import { rpivBucketOutcome } from "./artifact-collector.js";
 

package/extensions/rpiv-core/frontmatter.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { parseFrontmatterBounds } from "./frontmatter.js";
+
+describe("parseFrontmatterBounds", () => {
+	it("returns bounds for well-formed frontmatter", () => {
+		const content = ["---", "name: test", "---", "body"].join("\n");
+		expect(parseFrontmatterBounds(content.split("\n"))).toEqual({ start: 0, end: 2 });
+	});
+
+	it("returns bounds when frontmatter has many lines", () => {
+		const content = ["---", "name: test", "description: long", "tools: grep", "---", "body"].join("\n");
+		expect(parseFrontmatterBounds(content.split("\n"))).toEqual({ start: 0, end: 4 });
+	});
+
+	it("returns bounds when content ends immediately after closing ---", () => {
+		const content = ["---", "name: test", "---"].join("\n");
+		expect(parseFrontmatterBounds(content.split("\n"))).toEqual({ start: 0, end: 2 });
+	});
+
+	it("returns null when content is empty", () => {
+		expect(parseFrontmatterBounds("".split("\n"))).toBeNull();
+	});
+
+	it("returns null when there is no opening ---", () => {
+		const content = "name: test\n---\nbody";
+		expect(parseFrontmatterBounds(content.split("\n"))).toBeNull();
+	});
+
+	it("returns null when there is no closing ---", () => {
+		const content = ["---", "name: test", "body"].join("\n");
+		expect(parseFrontmatterBounds(content.split("\n"))).toBeNull();
+	});
+
+	it("returns null for single-line content with no ---", () => {
+		expect(parseFrontmatterBounds("just text".split("\n"))).toBeNull();
+	});
+
+	it("returns null for content that is only opening ---", () => {
+		expect(parseFrontmatterBounds("---".split("\n"))).toBeNull();
+	});
+
+	it("handles frontmatter with empty lines between keys", () => {
+		const content = ["---", "name: test", "", "tools: grep", "---", "body"].join("\n");
+		expect(parseFrontmatterBounds(content.split("\n"))).toEqual({ start: 0, end: 4 });
+	});
+
+	it("picks the first closing --- after the opening", () => {
+		const content = ["---", "name: test", "---", "---", "body"].join("\n");
+		expect(parseFrontmatterBounds(content.split("\n"))).toEqual({ start: 0, end: 2 });
+	});
+});

package/extensions/rpiv-core/frontmatter.ts

@@ -0,0 +1,32 @@
+/**
+ * Frontmatter utilities for rpiv-core.
+ *
+ * Pure functions — no ExtensionAPI, no side effects, fail-soft.
+ */
+
+// ---------------------------------------------------------------------------
+// Frontmatter bounds
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the line indices of the YAML frontmatter block in `content`.
+ *
+ * Returns `{ start, end }` where `start` is the 0-based line index of the
+ * opening `---` and `end` is the 0-based line index of the closing `---`.
+ * Returns `null` when the content has no valid frontmatter block (missing
+ * opening fence, missing closing fence, or empty content).
+ *
+ * Takes a pre-split lines array so callers can reuse the same split for
+ * both bounds detection and subsequent mutation without double-splitting.
+ */
+export function parseFrontmatterBounds(lines: string[]): { start: number; end: number } | null {
+	if (lines[0] !== "---") return null;
+
+	for (let i = 1; i < lines.length; i++) {
+		if (lines[i] === "---") {
+			return { start: 0, end: i };
+		}
+	}
+
+	return null; // unclosed frontmatter
+}

package/extensions/rpiv-core/index.ts

@@ -7,16 +7,20 @@
  * Tool-owning plugins are siblings (see siblings.ts); install via /rpiv-setup.
  *
  * Workflow runtime + `/wf` command live in `@juicesharp/rpiv-workflow`. We
- * contribute three built-in workflows (small / mid / large) via the
+ * contribute five built-in workflows (ship / build / arch / vet / polish) via the
  * sibling's `registerBuiltIns` programmatic API so they're available to
  * users running `/wf` without authoring their own.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { FLAG_DEBUG } from "./constants.js";
+import { registerModelOverrideLifecycle, registerModelOverrideSessionStart } from "./model-override.js";
+import { registerModelsConfigValidation } from "./models-config-validate.js";
 import { registerBuiltInWorkflows } from "./register-built-in-workflows.js";
+import { registerRpivModelsCommand } from "./rpiv-models/index.js";
 import { registerSessionHooks } from "./session-hooks.js";
 import { registerSetupCommand } from "./setup-command.js";
+import { registerSkillBracket } from "./skill-bracket.js";
 import { registerUpdateAgentsCommand } from "./update-agents-command.js";
 
 export default function (pi: ExtensionAPI) {
@@ -31,11 +35,36 @@ export default function (pi: ExtensionAPI) {
 	registerSessionHooks(pi);
 	registerUpdateAgentsCommand(pi);
 	registerSetupCommand(pi);
-	// Built-in workflows feed the sibling's `/wf` command. Deferred behind a
-	// dynamic import so a missing sibling degrades gracefully instead of taking
-	// the whole extension down (see register-built-in-workflows.ts). Fire-and-
-	// forget: the registry is read lazily at `/wf` time, long after this settles.
-	registerBuiltInWorkflows().catch((err: unknown) => {
-		console.error("[rpiv-core] failed to register built-in workflows:", err);
-	});
+	registerRpivModelsCommand(pi); // /rpiv-models cascade picker
+	// Warn-on-miss: surface models.json record-key typos (skills.committ,
+	// presets.shipp) that pass schema validation but silently never apply.
+	registerModelsConfigValidation(pi);
+	// Stage model/effort override: the session_start hook captures modelRegistry +
+	// current model UNCONDITIONALLY (independent of rpiv-workflow), and the
+	// lifecycle listener registration degrades gracefully when the sibling is
+	// absent (isModuleNotFound guard inside registerModelOverrideLifecycle).
+	registerModelOverrideSessionStart(pi);
+	// Standalone /skill: model/effort override bracket. MUST register AFTER
+	// registerModelOverrideSessionStart so the bracket's `getCapturedModel()`
+	// read at input-arm time sees the populated baseline. The bracket's
+	// `input` + `agent_end` handlers are independent of rpiv-workflow's
+	// presence — they read models.json directly.
+	registerSkillBracket(pi);
+	// Both registerModelOverrideLifecycle and registerBuiltInWorkflows dynamically
+	// `import("@juicesharp/rpiv-workflow")`. Firing them concurrently makes jiti
+	// (Pi's dev loader) hand the second caller a half-initialized barrel namespace
+	// whose re-export getters (e.g. registerBuiltIns) read from a not-yet-evaluated
+	// submodule and throw "Cannot read properties of undefined". Chaining them means
+	// the second import resolves from jiti's module cache after the first has fully
+	// evaluated the barrel — no race. Both are fire-and-forget (the workflow
+	// registry is read lazily at `/wf` time, long after this settles) and both
+	// degrade gracefully when the sibling is absent (isModuleNotFound guards).
+	const logRegistrationFailure = (label: string) => (err: unknown) =>
+		console.error(`[rpiv-core] failed to register ${label}:`, err);
+
+	registerModelOverrideLifecycle(pi)
+		.catch(logRegistrationFailure("model override lifecycle"))
+		.finally(() => {
+			registerBuiltInWorkflows().catch(logRegistrationFailure("built-in workflows"));
+		});
 }