@dreki-gg/pi-code-reviewer 0.3.0 → 0.5.0

package/README.md

@@ -35,6 +35,32 @@ This creates:
 
 The `code_review` tool is also available for programmatic use by the agent.
 
+## How the review runs (Bugbot-style pipeline)
+
+When a session model is available, the `code_review` tool **runs the review
+itself** rather than returning a prompt for one downstream pass. It drives a
+multi-stage pipeline modeled on Cursor's Bugbot:
+
+1. **Parallel adversarial passes** (default 5) over the diff. Each pass gets a
+   different focus — trust boundaries, control flow, async/lifecycle, types,
+   state integrity, security, resources, contracts — plus a temperature jitter,
+   so passes reason down different paths instead of collapsing onto the same
+   findings.
+2. **Bucket + majority vote.** Near-duplicate findings are fused (same file +
+   line proximity + message similarity) and tracked by how many distinct passes
+   surfaced them. Low-signal single-pass *notes* are dropped; blockers and
+   warnings are never dropped for low votes.
+3. **Validator stage.** One batched call tries to *falsify* each surviving
+   candidate and drops false positives. It **fails open** — if the validator
+   errors, candidates are surfaced unvalidated rather than silently lost.
+
+The tool returns finished, validated findings as a Markdown report (vote count,
+confidence, validator justification) plus structured `details`.
+
+**Fallback:** if no model is available (e.g. print mode) or `review.passes` is
+`0`, the tool returns the previous single-pass review prompt and the calling
+agent produces findings in its follow-up message.
+
 ## Lenses
 
 A lens is a markdown file that defines review criteria, project tools to run, and severity rules:
@@ -59,6 +85,13 @@ Evaluates changes for correctness and adherence to project standards.
 - note: Style suggestions
 ```
 
+> **Tools must be fast and exit on their own** (typecheck, lint, unit tests).
+> Do **not** list dev servers, watch mode, e2e suites, or full production
+> builds — they bind ports / run for minutes and belong in CI. Tools are
+> **deduped across lenses and run concurrently**, so a command shared by
+> several lenses runs once, and a slow/hanging command stalls the whole review
+> (bounded by `toolTimeoutMs`).
+
 ### Bundled lenses
 
 The package ships with four example lenses:
@@ -79,7 +112,19 @@ Run `/review-init` to scaffold these (customized for your project's tools) into
 ```json
 {
   "lensDir": ".code-review/lenses",
-  "defaultLenses": ["code-quality", "maintainability"]
+  "defaultLenses": ["code-quality", "maintainability"],
+  "toolTimeoutMs": 60000,
+  "toolConcurrency": 4,
+  "review": {
+    "passes": 5,
+    "validate": true,
+    "minVotes": 2,
+    "concurrency": 5,
+    "temperature": 0.4,
+    "maxFindings": 50,
+    "passModels": [{ "model": "anthropic/claude-opus-4-8", "reasoning": "low" }],
+    "validateModel": { "model": "anthropic/claude-opus-4-8", "reasoning": "medium" }
+  }
 }
 ```
 
@@ -87,4 +132,32 @@ Run `/review-init` to scaffold these (customized for your project's tools) into
 | --- | --- | --- |
 | `lensDir` | `.code-review/lenses` | Directory containing lens files |
 | `defaultLenses` | `[]` (all) | Lenses to run when none specified |
+| `toolTimeoutMs` | `60000` | Per-tool wall-clock timeout (ms); an exceeding tool is killed and reported as timed-out |
+| `toolConcurrency` | `4` | Max distinct tools run in parallel (tools are deduped across lenses first) |
+| `review.passes` | `5` | Parallel adversarial bug-finding passes. `0` disables the pipeline (single-pass prompt fallback). |
+| `review.validate` | `true` | Run the validator stage that falsifies each surviving candidate. |
+| `review.minVotes` | `2` | Min distinct passes a NOTE bucket needs to survive pre-validation (blockers/warnings exempt). |
+| `review.concurrency` | `= passes` | Max passes run concurrently. |
+| `review.temperature` | `0.4` | Base sampling temperature; each pass adds a small jitter so passes diverge. |
+| `review.maxFindings` | `50` | Hard cap on findings returned. |
+| `review.passModel` | session model | Model for ALL passes: a spec string (`"provider/id"`, bare id, or name) or `{ "model", "reasoning" }`. |
+| `review.passModels` | — | List of models **rotated round-robin across passes** — a bake-off in one run. Overrides `passModel`. |
+| `review.validateModel` | session model | Model for the validator stage (string or `{ "model", "reasoning" }`). |
+
+Each step accepts either a plain spec string or `{ "model": "provider/id", "reasoning": "low" }`
+where `reasoning` is one of `minimal` / `low` / `medium` / `high` / `xhigh` (applied as the
+thinking effort for that step; ignored by providers that don't support it).
+
+> By default the pipeline reuses the **session's current model** (`ctx.model`) —
+> no separate API key or model config. More passes = deeper coverage but higher
+> token/latency cost; tune `review.passes` to taste (3 = cheap, 8 = Bugbot
+> parity).
+>
+> **Model bake-off.** Set `passModels` to a list to run the same diff through
+> several models in one review and compare. Models are assigned round-robin to
+> passes, each finding is annotated with the model(s) that caught it, and the
+> report shows a per-model breakdown. Use a cheap model for `passModels` and a
+> stronger one for `validateModel` (or vice-versa) to probe the speed/cost/
+> quality frontier. Specs are matched as `provider/id`, a bare `id`, or a
+> display `name`; an unknown spec falls back to the session model with a warning.
 

package/extensions/code-reviewer/commands/review-init.ts

@@ -12,10 +12,20 @@ export function registerReviewInitCommand(pi: ExtensionAPI) {
           `Initialize a code review configuration for this project.`,
           ``,
           `1. Read the project's AGENTS.md, package.json, and any CONTEXT.md to understand the stack and conventions.`,
-          `2. Create a \`.code-review.json\` config file at the project root.`,
+          `2. Create a \`.code-review.json\` config file at the project root. Supported keys:`,
+          `   - \`lensDir\` (default \`.code-review/lenses\`), \`defaultLenses\` (lenses run when none are specified),`,
+          `   - \`toolTimeoutMs\` (per-tool timeout, default 60000), \`toolConcurrency\` (parallel tools, default 4),`,
+          `   - \`review\` (self-driving pipeline): \`passes\` (default 5, 0 disables), \`validate\` (default true),`,
+          `     \`minVotes\` (default 2), \`concurrency\` (default = passes), \`temperature\` (default 0.4), \`maxFindings\` (default 50),`,
+          `     and per-step models for a bake-off: \`passModel\`, \`passModels\` (rotated across passes), \`validateModel\``,
+          `     (each a "provider/id", bare id, or display name; default = the session model).`,
           `3. Create lens files in \`.code-review/lenses/\` — start with: code-quality.md, maintainability.md`,
-          `4. Each lens should reference the project's actual tools (from package.json scripts).`,
-          `5. Tailor the criteria to the project's stack and conventions.`,
+          `4. Each lens's \`## Tools\` must list ONLY fast, non-side-effecting commands that EXIT on their own`,
+          `   (e.g. typecheck, lint, unit tests). Do NOT list dev servers, watch mode, e2e suites, or full`,
+          `   production builds — they bind ports / run for minutes and belong in CI. Tools are deduped across`,
+          `   lenses and run concurrently, so a slow or hanging command stalls the whole review.`,
+          `5. Tailor the criteria to the project's stack and conventions; prefer concrete, pattern-matched checks`,
+          `   (name the project's real failure modes + the diff "smells" to look for) over generic virtues.`,
           ``,
           `Config path: ${configPath}`,
         ].join('\n'),

package/extensions/code-reviewer/commands/review-tool.ts

@@ -4,9 +4,18 @@ import { Type } from 'typebox';
 import { loadConfig, getLensDir } from '../config';
 import { collectDiff, getChangedFiles } from '../diff';
 import { discoverLenses, getLensContent } from '../lenses';
-import { reviewWithLens } from '../reviewer';
-import { buildReport } from '../report';
-import type { LensResult, ReviewConfig, ReviewReport } from '../types';
+import { resolveModelPlan } from '../model-plan';
+import { runPipeline } from '../passes';
+import {
+  buildDiffSection,
+  buildLensResult,
+  buildReviewBasePrompt,
+  pickLensToolOutputs,
+  renderPipelineReport,
+  runTools,
+} from '../reviewer';
+import type { DiffSource } from '../diff';
+import type { LensResult, ReviewConfig } from '../types';
 
 export function registerReviewTool(pi: ExtensionAPI) {
   pi.registerTool({
@@ -72,6 +81,23 @@ export function registerReviewTool(pi: ExtensionAPI) {
         };
       }
 
+      const selected = lensNames.map((name) => available.get(name)!);
+
+      // Run the DISTINCT tool set once (deduped across lenses), concurrently —
+      // not once per lens. A command shared by several lenses executes a single
+      // time and its output is shared.
+      const allTools = [...new Set(selected.flatMap((lens) => lens.tools))];
+      if (allTools.length > 0) {
+        ctx.ui.setStatus('code-review', `🔍 Running ${allTools.length} tool(s)...`);
+      }
+      const toolOutputs = await runTools(
+        pi,
+        cwd,
+        allTools,
+        { timeoutMs: config.toolTimeoutMs, concurrency: config.toolConcurrency },
+        signal,
+      );
+
       const results: LensResult[] = [];
       for (let i = 0; i < lensNames.length; i++) {
         if (signal?.aborted) break;
@@ -84,33 +110,80 @@ export function registerReviewTool(pi: ExtensionAPI) {
           details: { currentLens: name, lensIndex: i + 1, totalLenses: lensNames.length },
         });
 
-        const lens = available.get(name)!;
+        const lens = selected[i];
         const content = (await getLensContent(lensDir, name)) ?? '';
-        const result = await reviewWithLens(pi, ctx, cwd, lens, content, diff, signal);
-        results.push(result);
+        results.push(buildLensResult(lens, content, pickLensToolOutputs(lens, toolOutputs)));
       }
 
-      ctx.ui.setStatus('code-review', undefined);
+      const changedFiles = await getChangedFiles(pi, cwd, {
+        base: params.base,
+        staged: params.staged,
+      });
 
-      const report: ReviewReport = {
-        diff: diff.diff,
-        diffStat: diff.stat,
-        lenses: results,
-        generatedAt: new Date().toISOString().slice(0, 10),
-      };
+      // Self-driving path: when a model is available and passes are enabled,
+      // the tool runs the Bugbot-style pipeline itself (parallel adversarial
+      // passes → bucket → majority vote → validate) and returns FINISHED,
+      // validated findings — not a prompt for a single downstream pass.
+      const lensSections = results.map((result) => result._lensSection).filter(Boolean) as string[];
+      if (ctx.model && config.review.passes > 0 && lensSections.length > 0 && !signal?.aborted) {
+        try {
+          const { resolution, plan, warnings } = resolveModelPlan(
+            config.review,
+            ctx.model,
+            ctx.modelRegistry,
+          );
+          for (const warning of warnings) ctx.ui.notify(warning, 'warning');
+          const basePrompt = buildReviewBasePrompt(lensSections, diff);
+          const pipeline = await runPipeline(
+            resolution,
+            plan,
+            basePrompt,
+            config.review,
+            {
+              onStage: (stage) => {
+                ctx.ui.setStatus('code-review', `🔍 ${stage}...`);
+                onUpdate?.({ content: [{ type: 'text', text: stage }], details: { stage } });
+              },
+            },
+            signal,
+          );
+          ctx.ui.setStatus('code-review', undefined);
+          return {
+            content: [{ type: 'text', text: renderPipelineReport(pipeline, diff) }],
+            details: {
+              mode: 'pipeline',
+              lensCount: lensNames.length,
+              availableLenses: [...available.keys()],
+              changedFiles,
+              findings: pipeline.findings,
+              telemetry: pipeline.telemetry,
+            },
+          };
+        } catch (cause) {
+          // Pipeline failed hard (e.g. model/pi-ai unavailable at runtime) —
+          // degrade to the single-pass prompt instead of failing the review.
+          ctx.ui.setStatus('code-review', undefined);
+          onUpdate?.({
+            content: [{ type: 'text', text: 'pipeline unavailable — single-pass fallback' }],
+            details: { pipelineError: cause instanceof Error ? cause.message : String(cause) },
+          });
+        }
+      }
+
+      ctx.ui.setStatus('code-review', undefined);
 
-      const markdown = buildReport(report);
-      const toolContext = buildToolContext(results);
+      // Fallback: return the review task for a single downstream pass (the
+      // agent produces findings in its follow-up message). Used when no model
+      // is available (e.g. print mode) or passes are disabled in config.
+      const text = buildToolContext(results, diff);
 
       return {
-        content: [{ type: 'text', text: markdown + toolContext }],
+        content: [{ type: 'text', text }],
         details: {
+          mode: 'single-pass',
           lensCount: lensNames.length,
           availableLenses: [...available.keys()],
-          changedFiles: await getChangedFiles(pi, cwd, {
-            base: params.base,
-            staged: params.staged,
-          }),
+          changedFiles,
         },
       };
     },
@@ -131,17 +204,42 @@ function resolveLensNames(
   return [...available.keys()];
 }
 
-function buildToolContext(results: LensResult[]): string {
-  const prompts = results.map((r) => r._prompt).filter(Boolean);
-
-  if (prompts.length === 0) return '';
+/**
+ * Build the agent-facing review instructions appended to the report. The diff
+ * is embedded ONCE (not per lens) followed by each lens's section — large
+ * diffs would otherwise be repeated for every lens, bloating the tool output.
+ */
+function buildToolContext(results: LensResult[], diff: DiffSource): string {
+  const sections = results.map((r) => r._lensSection).filter(Boolean) as string[];
+  if (sections.length === 0) return '';
 
   return [
+    `# Code Review — ${new Date().toISOString().slice(0, 10)}`,
+    '',
+    '## Changes',
+    '```',
+    diff.stat.trim() || '(no diffstat)',
+    '```',
+    '',
+    'Evaluate the diff through each lens below; the tool outputs are automated analysis.',
+    '',
+    buildDiffSection(diff),
+    '',
+    '## Lenses',
+    '',
+    ...sections,
+    '',
+    '## Instructions',
     '',
-    '---',
+    'For each lens above, review the diff against its criteria and output a JSON array of findings:',
     '',
-    'The tool outputs above provide automated analysis. Now evaluate the diff through each lens criteria:',
+    '```json',
+    '[',
+    '  { "file": "path/to/file.ts", "line": 42, "severity": "warning", "message": "Description" }',
+    ']',
+    '```',
     '',
-    ...prompts,
+    'After each lens JSON array, write a 2-3 sentence summary.',
+    'If a lens has no findings, return an empty array `[]` and note the code looks good.',
   ].join('\n');
 }

package/extensions/code-reviewer/commands/review.ts

@@ -3,7 +3,16 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { loadConfig, getLensDir } from '../config';
 import { collectDiff } from '../diff';
 import { discoverLenses, getLensContent } from '../lenses';
-import { reviewWithLens, buildDiffSection } from '../reviewer';
+import { resolveModelPlan } from '../model-plan';
+import { runPipeline } from '../passes';
+import {
+  buildDiffSection,
+  buildLensResult,
+  buildReviewBasePrompt,
+  pickLensToolOutputs,
+  renderPipelineReport,
+  runTools,
+} from '../reviewer';
 import { parseReviewArgs } from '../parse-args';
 
 export function registerReviewCommand(pi: ExtensionAPI) {
@@ -47,24 +56,56 @@ export function registerReviewCommand(pi: ExtensionAPI) {
       }
 
       ctx.ui.notify(`Reviewing ${diff.label} through ${lensNames.length} lens(es)...`, 'info');
-      ctx.ui.setStatus('code-review', `🔍 Reviewing (0/${lensNames.length})...`);
+
+      const selected = lensNames.map((name) => available.get(name)!);
+
+      // Run the DISTINCT tool set once (deduped across lenses), concurrently.
+      const allTools = [...new Set(selected.flatMap((lens) => lens.tools))];
+      ctx.ui.setStatus('code-review', `🔍 Running ${allTools.length} tool(s)...`);
+      const toolOutputs = await runTools(pi, cwd, allTools, {
+        timeoutMs: config.toolTimeoutMs,
+        concurrency: config.toolConcurrency,
+      });
 
       const lensSections: string[] = [];
       for (let i = 0; i < lensNames.length; i++) {
         const name = lensNames[i];
         ctx.ui.setStatus('code-review', `🔍 Lens ${i + 1}/${lensNames.length}: ${name}`);
 
-        const lens = available.get(name)!;
+        const lens = selected[i];
         const content = (await getLensContent(lensDir, name)) ?? '';
-        const result = await reviewWithLens(pi, ctx, cwd, lens, content, diff);
-
-        if (result._lensSection) {
-          lensSections.push(result._lensSection);
-        }
+        const result = buildLensResult(lens, content, pickLensToolOutputs(lens, toolOutputs));
+        if (result._lensSection) lensSections.push(result._lensSection);
       }
 
       ctx.ui.setStatus('code-review', undefined);
 
+      // Self-driving path: run the Bugbot-style pipeline in-command and deliver
+      // the validated report in-session for discussion. Mirrors the tool.
+      if (ctx.model && config.review.passes > 0 && lensSections.length > 0) {
+        try {
+          const { resolution, plan, warnings } = resolveModelPlan(
+            config.review,
+            ctx.model,
+            ctx.modelRegistry,
+          );
+          for (const warning of warnings) ctx.ui.notify(warning, 'warning');
+          const basePrompt = buildReviewBasePrompt(lensSections, diff);
+          const pipeline = await runPipeline(resolution, plan, basePrompt, config.review, {
+            onStage: (stage) => ctx.ui.setStatus('code-review', `🔍 ${stage}...`),
+          });
+          ctx.ui.setStatus('code-review', undefined);
+          pi.sendUserMessage(renderPipelineReport(pipeline, diff), { deliverAs: 'followUp' });
+          return;
+        } catch (cause) {
+          ctx.ui.setStatus('code-review', undefined);
+          ctx.ui.notify(
+            `Pipeline unavailable (${cause instanceof Error ? cause.message : String(cause)}) — single-pass fallback`,
+            'warning',
+          );
+        }
+      }
+
       const combinedPrompt = [
         `Review the following changes through ${lensNames.length} lens(es): ${lensNames.join(', ')}.`,
         '',

package/extensions/code-reviewer/config.ts

@@ -10,13 +10,98 @@ import { Effect } from 'effect';
 import { resolve } from 'node:path';
 
 import { FileSystem, nodeFileSystemService } from './effects/filesystem';
-import type { ReviewConfig } from './types';
+import type { ModelStepConfig, ReasoningLevel, ReviewConfig, ReviewPipelineConfig } from './types';
+
+const REASONING_LEVELS = new Set<ReasoningLevel>(['minimal', 'low', 'medium', 'high', 'xhigh']);
 
 const CONFIG_FILE = '.code-review.json';
 const DEFAULT_LENS_DIR = '.code-review/lenses';
+const DEFAULT_TOOL_TIMEOUT_MS = 60_000;
+const DEFAULT_TOOL_CONCURRENCY = 4;
+
+const DEFAULT_PIPELINE: ReviewPipelineConfig = {
+  passes: 5,
+  validate: true,
+  minVotes: 2,
+  concurrency: 5,
+  temperature: 0.4,
+  maxFindings: 50,
+};
 
 function defaultConfig(): ReviewConfig {
-  return { lensDir: DEFAULT_LENS_DIR, defaultLenses: [] };
+  return {
+    lensDir: DEFAULT_LENS_DIR,
+    defaultLenses: [],
+    toolTimeoutMs: DEFAULT_TOOL_TIMEOUT_MS,
+    toolConcurrency: DEFAULT_TOOL_CONCURRENCY,
+    review: { ...DEFAULT_PIPELINE },
+  };
+}
+
+/** Coerce a config value to a non-negative integer (0 allowed: disables passes). */
+function nonNegativeIntOr(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0
+    ? Math.floor(value)
+    : fallback;
+}
+
+/** Coerce a config value to a number within [min, max]. */
+function clampNumberOr(value: unknown, fallback: number, min: number, max: number): number {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? Math.min(max, Math.max(min, value))
+    : fallback;
+}
+
+/** Coerce a config value to a model step: a non-empty spec string or
+ *  `{ model, reasoning }`. Returns undefined for anything else. */
+function parseModelStep(value: unknown): ModelStepConfig | undefined {
+  if (typeof value === 'string') return value.trim() ? value.trim() : undefined;
+  if (typeof value === 'object' && value !== null) {
+    const record = value as Record<string, unknown>;
+    const model = typeof record.model === 'string' ? record.model.trim() : '';
+    if (!model) return undefined;
+    const reasoning =
+      typeof record.reasoning === 'string' &&
+      REASONING_LEVELS.has(record.reasoning as ReasoningLevel)
+        ? (record.reasoning as ReasoningLevel)
+        : undefined;
+    return reasoning ? { model, reasoning } : { model };
+  }
+  return undefined;
+}
+
+/** Coerce a config value to a non-empty array of model steps, or undefined. */
+function parseModelStepArray(value: unknown): ModelStepConfig[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const steps = value
+    .map(parseModelStep)
+    .filter((step): step is ModelStepConfig => step !== undefined);
+  return steps.length > 0 ? steps : undefined;
+}
+
+function parsePipeline(raw: unknown): ReviewPipelineConfig {
+  if (typeof raw !== 'object' || raw === null) return { ...DEFAULT_PIPELINE };
+  const review = raw as Record<string, unknown>;
+  const passes = nonNegativeIntOr(review.passes, DEFAULT_PIPELINE.passes);
+  return {
+    passes,
+    validate: typeof review.validate === 'boolean' ? review.validate : DEFAULT_PIPELINE.validate,
+    minVotes: positiveIntOr(review.minVotes, DEFAULT_PIPELINE.minVotes),
+    // Default concurrency tracks pass count so all passes fan out at once.
+    concurrency: positiveIntOr(review.concurrency, Math.max(1, passes)),
+    temperature: clampNumberOr(review.temperature, DEFAULT_PIPELINE.temperature, 0, 2),
+    maxFindings: positiveIntOr(review.maxFindings, DEFAULT_PIPELINE.maxFindings),
+    passModel: parseModelStep(review.passModel),
+    passModels: parseModelStepArray(review.passModels),
+    validateModel: parseModelStep(review.validateModel),
+  };
+}
+
+/** Coerce a config value to a positive integer, falling back when absent/invalid. */
+function positiveIntOr(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? Math.floor(value)
+    : fallback;
 }
 
 export function loadConfigEffect(cwd: string): Effect.Effect<ReviewConfig, never, FileSystem> {
@@ -30,6 +115,9 @@ export function loadConfigEffect(cwd: string): Effect.Effect<ReviewConfig, never
       return {
         lensDir: parsed.lensDir ?? DEFAULT_LENS_DIR,
         defaultLenses: parsed.defaultLenses ?? [],
+        toolTimeoutMs: positiveIntOr(parsed.toolTimeoutMs, DEFAULT_TOOL_TIMEOUT_MS),
+        toolConcurrency: positiveIntOr(parsed.toolConcurrency, DEFAULT_TOOL_CONCURRENCY),
+        review: parsePipeline((parsed as { review?: unknown }).review),
       };
     } catch {
       // Malformed config — fall back to defaults.

package/extensions/code-reviewer/diff.ts

@@ -19,10 +19,14 @@ export type DiffSource = {
 
 export type DiffOptions = { base?: string; staged?: boolean };
 
+/** git diffs are normally instant; cap them so a pathological repo can't hang
+ *  the whole review. */
+const GIT_TIMEOUT_MS = 30_000;
+
 function git(args: string[], cwd: string): Effect.Effect<string, ExecError, Executor> {
   return Effect.gen(function* () {
     const executor = yield* Executor;
-    const result = yield* executor.exec('git', args, { cwd });
+    const result = yield* executor.exec('git', args, { cwd, timeout: GIT_TIMEOUT_MS });
     return result.stdout;
   });
 }
@@ -46,17 +50,19 @@ export function collectDiffEffect(
     }
 
     // Default: working directory changes (unstaged + staged) relative to HEAD.
-    const diff = yield* git(['diff', 'HEAD'], cwd);
+    // `git diff HEAD` fails on a repo with no commits (HEAD is unborn), so
+    // tolerate that and fall back to the bare working-directory diff.
+    const headDiff = yield* git(['diff', 'HEAD'], cwd).pipe(Effect.either);
 
-    // If no HEAD diff, fall back to just the working directory.
-    if (!diff.trim()) {
+    // No HEAD (fresh repo) or an empty HEAD diff → fall back to the working dir.
+    if (headDiff._tag === 'Left' || !headDiff.right.trim()) {
       const wdDiff = yield* git(['diff'], cwd);
       const wdStat = yield* git(['diff', '--stat'], cwd);
       return { diff: wdDiff, stat: wdStat, label: 'working directory changes' };
     }
 
     const stat = yield* git(['diff', 'HEAD', '--stat'], cwd);
-    return { diff, stat, label: 'all uncommitted changes' };
+    return { diff: headDiff.right, stat, label: 'all uncommitted changes' };
   });
 }
 

package/extensions/code-reviewer/effects/model.ts

@@ -0,0 +1,112 @@
+/**
+ * Reviewer service — wraps the session's current model so a single completion
+ * becomes an injectable, typed Effect. The self-driving pipeline (see
+ * `passes.ts`) depends on this Tag; the live implementation drives
+ * `@earendil-works/pi-ai`'s `completeSimple` over `ctx.model`, while tests
+ * provide a deterministic fake instead of calling a real provider.
+ *
+ * `@earendil-works/pi-ai` is an OPTIONAL peer dependency, so the runtime import
+ * is deferred (`import()`), reached only when the harness actually hands us a
+ * model. The extension stays loadable in environments without pi-ai.
+ */
+
+import type { Api, AssistantMessage, Model, TextContent } from '@earendil-works/pi-ai';
+import { Context, Effect } from 'effect';
+
+import { ModelError } from '../errors';
+import type { ReasoningLevel } from '../types';
+
+/** The model key meaning "use the session's current model". */
+export const DEFAULT_MODEL_KEY = 'default';
+
+export type CompletionRequest = {
+  /** Which model to run this call on — {@link DEFAULT_MODEL_KEY} or a key the
+   *  resolution map holds. Unknown keys fall back to the default model. */
+  modelKey: string;
+  system: string;
+  user: string;
+  /** Sampling temperature; the pipeline jitters this per pass. */
+  temperature?: number;
+  /** Reasoning/thinking effort for this call (provider-dependent). */
+  reasoning?: ReasoningLevel;
+  /** Identifies which pipeline stage is calling, for error context. */
+  stage: string;
+  signal?: AbortSignal;
+};
+
+export interface ReviewerService {
+  readonly complete: (request: CompletionRequest) => Effect.Effect<string, ModelError>;
+}
+
+export class Reviewer extends Context.Tag('CodeReviewer/Reviewer')<Reviewer, ReviewerService>() {}
+
+/** Resolved models the pipeline can run against: a default (session) model plus
+ *  any config-specified models keyed by their spec string. */
+export type ModelResolution = {
+  defaultModel: Model<Api>;
+  byKey: Map<string, Model<Api>>;
+};
+
+/** Resolve a config model spec to a registered model. Accepts "provider/id",
+ *  a bare model `id`, a `"provider/id"` composite, or a display `name`. */
+export function resolveModelSpec(
+  registry: { getAll: () => Model<Api>[] },
+  spec: string,
+): Model<Api> | undefined {
+  const trimmed = spec.trim();
+  if (!trimmed) return undefined;
+  const all = registry.getAll();
+
+  const slash = trimmed.indexOf('/');
+  if (slash > 0) {
+    const provider = trimmed.slice(0, slash);
+    const id = trimmed.slice(slash + 1);
+    const exact = all.find((model) => model.provider === provider && model.id === id);
+    if (exact) return exact;
+  }
+  return (
+    all.find((model) => model.id === trimmed) ??
+    all.find((model) => `${model.provider}/${model.id}` === trimmed) ??
+    all.find((model) => model.name === trimmed)
+  );
+}
+
+/** Flatten an assistant message to its plain-text content (drop thinking/tool). */
+export function extractText(message: AssistantMessage): string {
+  return message.content
+    .filter((block): block is TextContent => block.type === 'text')
+    .map((block) => block.text)
+    .join('\n')
+    .trim();
+}
+
+/** Build a live Reviewer that routes each call to the model named by its
+ *  `modelKey` (falling back to the default/session model) via pi-ai. */
+export function makeReviewerService(resolution: ModelResolution): ReviewerService {
+  return {
+    complete: (request) =>
+      Effect.tryPromise({
+        try: async () => {
+          const { completeSimple } = await import('@earendil-works/pi-ai');
+          const model = resolution.byKey.get(request.modelKey) ?? resolution.defaultModel;
+          const message = await completeSimple(
+            model,
+            {
+              systemPrompt: request.system,
+              messages: [{ role: 'user', content: request.user, timestamp: Date.now() }],
+            },
+            {
+              temperature: request.temperature,
+              reasoning: request.reasoning,
+              signal: request.signal,
+            },
+          );
+          if (message.stopReason === 'error') {
+            throw new Error(message.errorMessage ?? 'model returned an error stop reason');
+          }
+          return extractText(message);
+        },
+        catch: (cause) => new ModelError({ stage: request.stage, cause }),
+      }),
+  };
+}