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

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

@@ -1,3 +1,6 @@
+import { writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
 
@@ -7,16 +10,34 @@ import { discoverLenses, getLensContent } from '../lenses';
 import { resolveModelPlan } from '../model-plan';
 import { runPipeline } from '../passes';
 import {
-  buildDiffSection,
   buildLensResult,
+  buildPipelineResult,
   buildReviewBasePrompt,
+  buildSinglePassResult,
   pickLensToolOutputs,
-  renderPipelineReport,
   runTools,
 } from '../reviewer';
-import type { DiffSource } from '../diff';
+import type { ReviewPointer } from '../reviewer';
 import type { LensResult, ReviewConfig } from '../types';
 
+/**
+ * Spill the full review context to a temp Markdown file and return a pointer
+ * (path + byte size + line count). Both pi's tool-output and `read` caps are
+ * ~50KB / 2000 lines, so large reviews would otherwise be truncated and lost
+ * on compaction. The on-disk file survives compaction and can be paged.
+ *
+ * Node-only IO (no Bun) per the extension runtime constraint.
+ */
+async function writeReviewTempFile(content: string): Promise<ReviewPointer> {
+  const path = join(tmpdir(), `pi-code-review-${Date.now()}.md`);
+  await writeFile(path, content, 'utf8');
+  return {
+    path,
+    bytes: Buffer.byteLength(content, 'utf8'),
+    lines: content.split('\n').length,
+  };
+}
+
 export function registerReviewTool(pi: ExtensionAPI) {
   pi.registerTool({
     name: 'code_review',
@@ -148,17 +169,33 @@ export function registerReviewTool(pi: ExtensionAPI) {
             signal,
           );
           ctx.ui.setStatus('code-review', undefined);
-          return {
-            content: [{ type: 'text', text: renderPipelineReport(pipeline, diff) }],
+          // Every pass failed (e.g. the review model/pi-ai was unavailable for
+          // each call). The swallowed failures would render as a misleading
+          // "0 findings" report — instead, degrade to the single-pass prompt so
+          // the reviewing agent still produces a real review.
+          const allPassesFailed =
+            config.review.passes > 0 && pipeline.telemetry.failedPasses >= config.review.passes;
+          if (!allPassesFailed) {
+            return buildPipelineResult(
+              {
+                pipeline,
+                diff,
+                basePrompt,
+                lensNames,
+                availableLenses: [...available.keys()],
+                changedFiles,
+              },
+              writeReviewTempFile,
+              onUpdate,
+            );
+          }
+          onUpdate?.({
+            content: [{ type: 'text', text: 'all review passes failed — single-pass fallback' }],
             details: {
-              mode: 'pipeline',
-              lensCount: lensNames.length,
-              availableLenses: [...available.keys()],
-              changedFiles,
-              findings: pipeline.findings,
-              telemetry: pipeline.telemetry,
+              failedPasses: pipeline.telemetry.failedPasses,
+              passError: pipeline.telemetry.passErrorSample,
             },
-          };
+          });
         } catch (cause) {
           // Pipeline failed hard (e.g. model/pi-ai unavailable at runtime) —
           // degrade to the single-pass prompt instead of failing the review.
@@ -172,20 +209,25 @@ export function registerReviewTool(pi: ExtensionAPI) {
 
       ctx.ui.setStatus('code-review', undefined);
 
-      // 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 }],
-        details: {
-          mode: 'single-pass',
-          lensCount: lensNames.length,
+      // Fallback: spill the full single-pass review context to a temp file and
+      // return a compact summary + pointer (degrades gracefully on empty
+      // context or a write failure). Used when no model is available (e.g.
+      // print mode) or passes are disabled in config.
+      //
+      // This is the PRIMARY truncation culprit: the full context embeds the
+      // diff (up to 50KB) plus every lens's tool outputs (20KB each), which
+      // easily blows past pi's 50KB tool-output cap.
+      return buildSinglePassResult(
+        {
+          results,
+          diff,
+          lensNames,
           availableLenses: [...available.keys()],
           changedFiles,
         },
-      };
+        writeReviewTempFile,
+        onUpdate,
+      );
     },
   });
 }
@@ -204,42 +246,3 @@ function resolveLensNames(
   return [...available.keys()];
 }
 
-/**
- * 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:',
-    '',
-    '```json',
-    '[',
-    '  { "file": "path/to/file.ts", "line": 42, "severity": "warning", "message": "Description" }',
-    ']',
-    '```',
-    '',
-    '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/diff.ts

@@ -23,6 +23,14 @@ export type DiffOptions = { base?: string; staged?: boolean };
  *  the whole review. */
 const GIT_TIMEOUT_MS = 30_000;
 
+/** Cap on untracked files diffed against /dev/null so a repo full of generated
+ *  junk can't blow up the prompt. The whole diff is truncated downstream too. */
+const MAX_UNTRACKED_FILES = 200;
+
+/** The empty tree object — diffing a path against it yields a full new-file
+ *  diff portably (no reliance on /dev/null path handling across platforms). */
+const NULL_DEVICE = '/dev/null';
+
 function git(args: string[], cwd: string): Effect.Effect<string, ExecError, Executor> {
   return Effect.gen(function* () {
     const executor = yield* Executor;
@@ -31,6 +39,51 @@ function git(args: string[], cwd: string): Effect.Effect<string, ExecError, Exec
   });
 }
 
+/**
+ * Diff every untracked (new, not-yet-`git add`ed) file against /dev/null so
+ * brand-new files show up in a working-directory review — `git diff HEAD`
+ * omits them entirely, which is exactly the class of change agents introduce.
+ *
+ * Read-only: it NEVER touches the index (no `git add -N`). `git diff --no-index`
+ * exits non-zero when files differ, but pi.exec resolves with the diff on stdout
+ * regardless; any per-file failure degrades to an empty string rather than
+ * sinking the whole review.
+ */
+function collectUntrackedEffect(
+  cwd: string,
+): Effect.Effect<{ diff: string; files: string[] }, never, Executor> {
+  return Effect.gen(function* () {
+    const listed = yield* git(['ls-files', '--others', '--exclude-standard'], cwd).pipe(
+      Effect.orElseSucceed(() => ''),
+    );
+    const files = listed
+      .split('\n')
+      .map((f) => f.trim())
+      .filter(Boolean);
+    if (files.length === 0) return { diff: '', files: [] };
+
+    const parts = yield* Effect.forEach(
+      files.slice(0, MAX_UNTRACKED_FILES),
+      (file) =>
+        git(['diff', '--no-index', '--', NULL_DEVICE, file], cwd).pipe(
+          Effect.orElseSucceed(() => ''),
+        ),
+      { concurrency: 4 },
+    );
+    return { diff: parts.filter((part) => part.trim()).join('\n'), files };
+  });
+}
+
+/** Append a one-line-per-file summary of untracked files to a `--stat` block so
+ *  the change overview reflects new files that git's own stat never lists. */
+function appendUntrackedStat(stat: string, files: string[]): string {
+  if (files.length === 0) return stat;
+  const shown = files.slice(0, MAX_UNTRACKED_FILES);
+  const lines = shown.map((file) => ` ${file} | (new, untracked)`);
+  const note = `${files.length} untracked file(s) included`;
+  return [stat.trimEnd(), ...lines, note].filter(Boolean).join('\n');
+}
+
 /** Collect the diff from the working directory or a specific base ref. */
 export function collectDiffEffect(
   cwd: string,
@@ -49,20 +102,31 @@ export function collectDiffEffect(
       return { diff, stat, label: `changes since ${options.base}` };
     }
 
-    // Default: working directory changes (unstaged + staged) relative to HEAD.
-    // `git diff HEAD` fails on a repo with no commits (HEAD is unborn), so
+    // Default: EVERYTHING the agent is working on but hasn't committed —
+    // tracked changes (unstaged + staged) relative to HEAD, PLUS untracked
+    // (brand-new) files. `git diff HEAD` covers only the former; untracked
+    // files are collected separately and merged so new files are reviewed too.
+    // `git diff HEAD` also 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);
+    const untracked = yield* collectUntrackedEffect(cwd);
 
-    // No HEAD (fresh repo) or an empty HEAD diff → fall back to the working dir.
+    let tracked: string;
+    let stat: string;
+    let label: string;
     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' };
+      // No HEAD (fresh repo) or no tracked changes → use the bare working dir.
+      tracked = yield* git(['diff'], cwd);
+      stat = yield* git(['diff', '--stat'], cwd);
+      label = 'working directory changes';
+    } else {
+      tracked = headDiff.right;
+      stat = yield* git(['diff', 'HEAD', '--stat'], cwd);
+      label = 'all uncommitted changes';
     }
 
-    const stat = yield* git(['diff', 'HEAD', '--stat'], cwd);
-    return { diff: headDiff.right, stat, label: 'all uncommitted changes' };
+    const diff = [tracked, untracked.diff].filter((part) => part.trim()).join('\n');
+    return { diff, stat: appendUntrackedStat(stat, untracked.files), label };
   });
 }
 
@@ -72,19 +136,31 @@ export function getChangedFilesEffect(
   options: DiffOptions,
 ): Effect.Effect<string[], ExecError, Executor> {
   return Effect.gen(function* () {
-    const args = ['diff', '--name-only'];
-    if (options.staged) args.push('--staged');
-    else if (options.base) args.push(options.base);
-    else args.push('HEAD');
+    if (options.staged || options.base) {
+      const args = ['diff', '--name-only', options.staged ? '--staged' : options.base!];
+      const stdout = yield* git(args, cwd);
+      return splitPaths(stdout);
+    }
 
-    const stdout = yield* git(args, cwd);
-    return stdout
-      .split('\n')
-      .map((f) => f.trim())
-      .filter(Boolean);
+    // Default: tracked changes vs HEAD (tolerate an unborn HEAD) plus untracked
+    // files, deduped, so the changed-file list mirrors the merged default diff.
+    const tracked = yield* git(['diff', '--name-only', 'HEAD'], cwd).pipe(
+      Effect.orElseSucceed(() => ''),
+    );
+    const untracked = yield* git(['ls-files', '--others', '--exclude-standard'], cwd).pipe(
+      Effect.orElseSucceed(() => ''),
+    );
+    return [...new Set([...splitPaths(tracked), ...splitPaths(untracked)])];
   });
 }
 
+function splitPaths(stdout: string): string[] {
+  return stdout
+    .split('\n')
+    .map((f) => f.trim())
+    .filter(Boolean);
+}
+
 // ── Promise wrappers (live Executor from pi) ──────────────────────────────────
 
 export function collectDiff(

package/extensions/code-reviewer/passes.ts

@@ -16,6 +16,7 @@
 
 import { Effect } from 'effect';
 
+import { causeMessage } from './errors';
 import { type ModelResolution, Reviewer, makeReviewerService } from './effects/model';
 import type {
   CandidateFinding,
@@ -355,7 +356,11 @@ export function runPassesEffect(
   config: ReviewPipelineConfig,
   plan: ModelPlan,
   signal?: AbortSignal,
-): Effect.Effect<{ perPass: RawFinding[][]; failedPasses: number }, never, Reviewer> {
+): Effect.Effect<
+  { perPass: RawFinding[][]; failedPasses: number; passErrorSample?: string },
+  never,
+  Reviewer
+> {
   return Effect.gen(function* () {
     const reviewer = yield* Reviewer;
     const indices = Array.from({ length: config.passes }, (_unused, index) => index);
@@ -380,19 +385,29 @@ export function runPassesEffect(
             })
             .pipe(Effect.either);
           return result._tag === 'Right'
-            ? { findings: parseFindings(result.right), failed: false }
-            : { findings: [] as RawFinding[], failed: true };
+            ? { findings: parseFindings(result.right), failed: false, error: undefined }
+            : { findings: [] as RawFinding[], failed: true, error: describePassError(result.left) };
         }),
       { concurrency: Math.max(1, config.concurrency) },
     );
 
+    const failures = outcomes.filter((outcome) => outcome.failed);
     return {
       perPass: outcomes.map((outcome) => outcome.findings),
-      failedPasses: outcomes.filter((outcome) => outcome.failed).length,
+      failedPasses: failures.length,
+      passErrorSample: failures[0]?.error,
     };
   });
 }
 
+/** Best-effort human message for a failed pass: the ModelError's own message
+ *  when present, else its underlying cause. */
+function describePassError(error: unknown): string {
+  const message = (error as { message?: unknown }).message;
+  if (typeof message === 'string' && message.trim()) return message;
+  return causeMessage((error as { cause?: unknown }).cause);
+}
+
 function buildValidatorUser(basePrompt: string, candidates: CandidateFinding[]): string {
   const list = candidates
     .map((candidate, index) => {
@@ -514,7 +529,12 @@ export function runPipelineEffect(
 ): Effect.Effect<PipelineResult, never, Reviewer> {
   return Effect.gen(function* () {
     hooks.onStage?.(`running ${config.passes} passes`);
-    const { perPass, failedPasses } = yield* runPassesEffect(basePrompt, config, plan, signal);
+    const { perPass, failedPasses, passErrorSample } = yield* runPassesEffect(
+      basePrompt,
+      config,
+      plan,
+      signal,
+    );
 
     const buckets = bucketFindings(perPass);
     const { kept, droppedLowSignal } = selectCandidates(buckets, config);
@@ -547,6 +567,7 @@ export function runPipelineEffect(
       droppedFalsePositives,
       droppedLowSignal,
       failedPasses,
+      passErrorSample,
       passModels: plan.passes.map((assignment) => assignment.label),
       validatorModel: plan.validator.label,
     };

package/extensions/code-reviewer/reviewer.ts

@@ -1,5 +1,9 @@
 import { platform } from 'node:os';
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type {
+  AgentToolResult,
+  AgentToolUpdateCallback,
+  ExtensionAPI,
+} from '@earendil-works/pi-coding-agent';
 import { Effect } from 'effect';
 
 import type { DiffSource } from './diff';
@@ -118,6 +122,71 @@ export function buildReviewBasePrompt(lensSections: string[], diff: DiffSource):
   ].join('\n');
 }
 
+/** Pointer to the temp file holding the full review context. */
+export type ReviewPointer = { path: string; bytes: number; lines: number };
+
+/** Round bytes to whole KB for a human-readable size (min 1KB). */
+function toKb(bytes: number): number {
+  return Math.max(1, Math.round(bytes / 1024));
+}
+
+/**
+ * Condense a git `--stat` block into a one-line "N files, +ins -del" summary.
+ * Returns '' when the diffstat has no recognizable summary line.
+ */
+function summarizeDiffStat(stat: string): string {
+  const lastLine = stat.trim().split('\n').pop()?.trim() ?? '';
+  const files = lastLine.match(/(\d+) files? changed/)?.[1];
+  if (!files) return '';
+  const insertions = lastLine.match(/(\d+) insertions?\(\+\)/)?.[1];
+  const deletions = lastLine.match(/(\d+) deletions?\(-\)/)?.[1];
+  const parts = [`${files} file${files === '1' ? '' : 's'}`];
+  if (insertions) parts.push(`+${insertions}`);
+  if (deletions) parts.push(`-${deletions}`);
+  return parts.join(', ');
+}
+
+/**
+ * Compact inline header for the single-pass fallback. The full review context
+ * (diff, lenses, instructions) lives in a temp file — see {@link buildPointer} —
+ * so this only names the lenses and the diff scope. Pure (no IO).
+ */
+export function buildInlineSummary(lensNames: string[], diff: DiffSource): string {
+  const stat = summarizeDiffStat(diff.stat);
+  const diffLine = stat ? `${diff.label} (${stat})` : diff.label;
+  return [
+    '# Code Review Summary',
+    `- **Lenses**: ${lensNames.join(', ') || '(none)'}`,
+    `- **Diff**: ${diffLine}`,
+  ].join('\n');
+}
+
+/**
+ * Inline pointer to the temp file holding the full review context. pi's tool
+ * output / `read` caps are both ~50KB / 2000 lines, so the directive tells the
+ * agent to page large content with `read` offset/limit. Pure (no IO).
+ *
+ * `mode` switches the action sentence: single-pass needs the agent to perform
+ * the whole review from the file; pipeline only needs it to drill into the diff
+ * behind an already-rendered finding.
+ */
+export function buildPointer(pointer: ReviewPointer, mode: 'single-pass' | 'pipeline'): string {
+  const size = `(${pointer.lines} lines, ${toKb(pointer.bytes)}KB)`;
+  if (mode === 'single-pass') {
+    return [
+      '📄 Full review context (diff, lens definitions, tool outputs, instructions)',
+      `saved to: \`${pointer.path}\``,
+      `${size}. **Read that file** to perform the review — page large content with`,
+      '`read` offset/limit.',
+    ].join('\n');
+  }
+  return [
+    '---',
+    `📄 Full diff + lens context saved to: \`${pointer.path}\``,
+    `${size}. Use \`read\` (offset/limit) to inspect the diff behind a finding.`,
+  ].join('\n');
+}
+
 const SEVERITY_EMOJI: Record<ValidatedFinding['severity'], string> = {
   blocker: '🔴',
   warning: '🟡',
@@ -159,10 +228,38 @@ export function renderPipelineReport(result: PipelineResult, diff: DiffSource):
     '',
   ];
 
+  // A pass fails when its model call errors; failures are swallowed into 0
+  // findings, so an all-failed run must NOT masquerade as a clean review.
+  const someFailed = telemetry.failedPasses > 0;
+  const allFailed = telemetry.passes > 0 && telemetry.failedPasses >= telemetry.passes;
+  const errSuffix = telemetry.passErrorSample ? ` — e.g. ${telemetry.passErrorSample}` : '';
+
   if (findings.length === 0) {
+    if (allFailed) {
+      return [
+        ...header,
+        `> ⚠️ **Inconclusive — all ${telemetry.passes} review pass(es) failed${errSuffix}.**`,
+        '> No analysis actually ran; this is NOT a clean result. Re-run the review',
+        '> (check that the review model / pi-ai is available) before trusting it.',
+      ].join('\n');
+    }
+    if (someFailed) {
+      return [
+        ...header,
+        `> ⚠️ **Partial review — ${telemetry.failedPasses}/${telemetry.passes} pass(es) failed${errSuffix}.**`,
+        `> The ${telemetry.passes - telemetry.failedPasses} surviving pass(es) found nothing, but coverage was reduced.`,
+      ].join('\n');
+    }
     return [...header, 'No bugs found that survived validation. ✅'].join('\n');
   }
 
+  const partialWarning = someFailed
+    ? [
+        `> ⚠️ **Partial review — ${telemetry.failedPasses}/${telemetry.passes} pass(es) failed${errSuffix}; findings below may be incomplete.**`,
+        '',
+      ]
+    : [];
+
   // Only attribute models per finding when more than one distinct model ran
   // (a bake-off); with a single model it's noise.
   const multiModel = new Set(telemetry.passModels).size > 1;
@@ -180,7 +277,7 @@ export function renderPipelineReport(result: PipelineResult, diff: DiffSource):
     return `- ${SEVERITY_EMOJI[finding.severity]} **${finding.severity}** ${where} — ${finding.message} _(${meta})_${justification}`;
   });
 
-  return [...header, '## Findings', '', ...lines].join('\n');
+  return [...header, ...partialWarning, '## Findings', '', ...lines].join('\n');
 }
 
 /** Build the lens-specific section of the review prompt (no diff duplication). */
@@ -235,6 +332,158 @@ export function buildLensResult(
   };
 }
 
+/**
+ * Build the agent-facing review instructions for the single-pass fallback. 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.
+ * Returns '' when no lens produced a section (nothing to review).
+ */
+export 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:',
+    '',
+    '```json',
+    '[',
+    '  { "file": "path/to/file.ts", "line": 42, "severity": "warning", "message": "Description" }',
+    ']',
+    '```',
+    '',
+    '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');
+}
+
+/** Persist the full review context somewhere durable, returning a pointer. */
+export type ReviewTempWriter = (content: string) => Promise<ReviewPointer>;
+
+type ReviewToolResult = AgentToolResult<Record<string, unknown>>;
+
+/**
+ * Assemble the single-pass fallback result. The full review context is spilled
+ * to a temp file (via the injected {@link ReviewTempWriter}) so it survives
+ * pi's tool-output cap; the inline payload is just a summary + pointer.
+ * Degrades gracefully: an empty context yields a "no applicable lenses" notice,
+ * and a temp-write failure falls back to the (truncation-prone) inline context
+ * rather than throwing out of the tool.
+ */
+export async function buildSinglePassResult(
+  args: {
+    results: LensResult[];
+    diff: DiffSource;
+    lensNames: string[];
+    availableLenses: string[];
+    changedFiles: string[];
+  },
+  writeTemp: ReviewTempWriter,
+  onUpdate?: AgentToolUpdateCallback,
+): Promise<ReviewToolResult> {
+  const fullContext = buildToolContext(args.results, args.diff);
+  const baseDetails: Record<string, unknown> = {
+    mode: 'single-pass',
+    lensCount: args.lensNames.length,
+    availableLenses: args.availableLenses,
+    changedFiles: args.changedFiles,
+  };
+
+  // No lens produced any context (e.g. the requested lenses matched none of the
+  // available ones) — there is nothing to review, so don't point the agent at
+  // an empty temp file.
+  if (!fullContext.trim()) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `No applicable lenses for this review. Available: ${args.availableLenses.join(', ') || '(none)'}.`,
+        },
+      ],
+      details: baseDetails,
+    };
+  }
+
+  try {
+    const pointer = await writeTemp(fullContext);
+    const summary = `${buildInlineSummary(args.lensNames, args.diff)}\n\n${buildPointer(pointer, 'single-pass')}`;
+    return {
+      content: [{ type: 'text', text: summary }],
+      details: { ...baseDetails, contextFile: pointer.path },
+    };
+  } catch (cause) {
+    onUpdate?.({
+      content: [{ type: 'text', text: 'temp-file write failed — returning inline context' }],
+      details: { writeError: cause instanceof Error ? cause.message : String(cause) },
+    });
+    return { content: [{ type: 'text', text: fullContext }], details: baseDetails };
+  }
+}
+
+/**
+ * Assemble the pipeline result. The validated findings are the valuable output
+ * and stay inline; the diff + lens context is spilled to a temp file (via the
+ * injected {@link ReviewTempWriter}) purely so the agent can drill into the
+ * diff behind a finding. A write failure must NOT discard a completed pipeline,
+ * so on failure the findings are returned WITHOUT a pointer.
+ */
+export async function buildPipelineResult(
+  args: {
+    pipeline: PipelineResult;
+    diff: DiffSource;
+    basePrompt: string;
+    lensNames: string[];
+    availableLenses: string[];
+    changedFiles: string[];
+  },
+  writeTemp: ReviewTempWriter,
+  onUpdate?: AgentToolUpdateCallback,
+): Promise<ReviewToolResult> {
+  const report = renderPipelineReport(args.pipeline, args.diff);
+  let text = report;
+  let contextFile: string | undefined;
+  try {
+    const pointer = await writeTemp(args.basePrompt);
+    text = `${report}\n\n${buildPointer(pointer, 'pipeline')}`;
+    contextFile = pointer.path;
+  } catch (cause) {
+    onUpdate?.({
+      content: [
+        { type: 'text', text: 'temp-file write failed — findings returned without diff pointer' },
+      ],
+      details: { writeError: cause instanceof Error ? cause.message : String(cause) },
+    });
+  }
+  return {
+    content: [{ type: 'text', text }],
+    details: {
+      mode: 'pipeline',
+      lensCount: args.lensNames.length,
+      availableLenses: args.availableLenses,
+      changedFiles: args.changedFiles,
+      findings: args.pipeline.findings,
+      telemetry: args.pipeline.telemetry,
+      ...(contextFile ? { contextFile } : {}),
+    },
+  };
+}
+
 /** Promise wrapper: run a deduped tool set once, building a live Executor from `pi`. */
 export function runTools(
   pi: Pick<ExtensionAPI, 'exec'>,

package/extensions/code-reviewer/types.ts

@@ -95,6 +95,9 @@ export type PipelineTelemetry = {
   droppedFalsePositives: number;
   droppedLowSignal: number;
   failedPasses: number;
+  /** A representative error message from the first failed pass, surfaced so a
+   *  fully-failed run reports WHY instead of a misleading "0 findings". */
+  passErrorSample?: string;
   /** Model key used for each pass (parallel to pass index). */
   passModels: string[];
   /** Model key used for the validator stage. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-code-reviewer",
-  "version": "0.5.0",
+  "version": "0.6.2",
   "description": "Multi-lens code review extension for pi — configurable review criteria per project",
   "keywords": [
     "pi-package"