pi-python-helper 0.1.0

package/extensions/tools/testing.ts

@@ -0,0 +1,350 @@
+import { Type } from 'typebox';
+import { failure, result } from '../../src/core/result.ts';
+import { runCommand } from '../../src/core/runner.ts';
+import { pytestCommand } from '../../src/build/commands.ts';
+import { changedPaths, listTestFiles } from '../../src/build/discover.ts';
+import { diagnoseFailure, refineWithDeclarations } from '../../src/build/failure.ts';
+import { parsePytestOutput } from '../../src/build/pytest.ts';
+import { selectTests } from '../../src/build/selection.ts';
+import { buildDeclaredIndex } from '../../src/dependencies/plan.ts';
+import { runScanProject } from '../../src/project/scanner.ts';
+import { messageOf, resolveProjectRoot, text, type Pi } from '../shared.ts';
+
+/** Cross-check a diagnosis against what the project actually declares. */
+async function refine(
+  diagnosis: ReturnType<typeof diagnoseFailure>,
+  cwd: string,
+  root: string | undefined,
+  signal: AbortSignal | undefined,
+): Promise<ReturnType<typeof diagnoseFailure>> {
+  if (!diagnosis.missingModule || !root) return diagnosis;
+  const scan = await runScanProject(cwd, { root, mode: 'all', maxFiles: 2000 }, signal);
+  if (!scan.ok || !scan.payload) return diagnosis;
+  const declared = new Set(
+    buildDeclaredIndex(
+      scan.payload.manifest ?? {
+        dependencies: [],
+        optionalDependencies: {},
+        dependencyGroups: {},
+      },
+    ).keys(),
+  );
+  const localModules = new Set(scan.payload.imports?.localModules ?? []);
+  return refineWithDeclarations(diagnosis, { declared, localModules });
+}
+
+export function registerTestingTools(pi: Pi): void {
+  pi.registerTool({
+    name: 'py_test_select',
+    label: 'Python Test Select',
+    description:
+      'Select focused pytest targets from changed files using pytest naming conventions, without running tests. Read-only.',
+    promptSnippet: 'Select focused Python tests from changed files',
+    promptGuidelines: [
+      'Use py_test_select after changing Python source to choose a focused pytest target instead of running the whole suite.',
+    ],
+    parameters: Type.Object({
+      changedPaths: Type.Optional(
+        Type.Array(Type.String(), {
+          description: 'Changed paths; defaults to git diff plus untracked files.',
+        }),
+      ),
+      testFiles: Type.Optional(
+        Type.Array(Type.String(), { description: 'Known test files; defaults to a project scan.' }),
+      ),
+      path: Type.Optional(
+        Type.String({ description: 'Project directory to scan for test files.' }),
+      ),
+    }),
+    async execute(_id, params, signal, _update, ctx) {
+      const started = Date.now();
+      try {
+        const root = (await resolveProjectRoot(ctx.cwd, params.path)) ?? ctx.cwd;
+        let changed = params.changedPaths ?? [];
+        let changedSource = 'argument';
+        if (!changed.length) {
+          const discovered = await changedPaths(ctx.cwd, signal);
+          changed = discovered.paths;
+          changedSource = discovered.source === 'git' ? 'git' : (discovered.error ?? 'none');
+        }
+        const testFiles = params.testFiles ?? (await listTestFiles(root));
+        const selection = selectTests(changed, testFiles);
+        const command = pytestCommand(ctx.cwd, {
+          targets: selection.fellBackToAll ? [] : selection.selected.map((entry) => entry.path),
+        });
+
+        return text(
+          result(ctx.cwd, started, {
+            ok: selection.selected.length > 0 || testFiles.length === 0,
+            summary:
+              `${selection.selected.length} test file(s) selected from ${testFiles.length} known test file(s) ` +
+              `for ${selection.changedSourceFiles.length} changed source file(s) (${changedSource}).` +
+              (selection.fellBackToAll
+                ? ' No match was found, so the full suite is in scope.'
+                : ''),
+            data: { ...selection, pytestTargets: selection.selected.map((entry) => entry.path) },
+            evidence: [
+              {
+                kind: 'test_selection',
+                changedSourceFiles: selection.changedSourceFiles,
+                changedTestFiles: selection.changedTestFiles,
+                selected: selection.selected,
+                fellBackToAll: selection.fellBackToAll,
+              },
+            ],
+            warnings:
+              testFiles.length === 0
+                ? [
+                    {
+                      code: 'NO_TEST_FILES',
+                      message:
+                        'No pytest test files were found. Create tests/test_<module>.py to enable focused selection.',
+                      severity: 'warning' as const,
+                    },
+                  ]
+                : [],
+            errors: [],
+            suggestions: selection.selected.length
+              ? [
+                  {
+                    message: `Run the selected targets with py_test, or use py_test with lastFailed=true to rerun only previous failures.`,
+                    confidence: 'high' as const,
+                  },
+                ]
+              : [],
+            commands: [command],
+            projectRoot: root,
+          }),
+        );
+      } catch (error) {
+        return text(failure(ctx.cwd, started, messageOf(error), 'INTERNAL_ERROR'));
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: 'py_test',
+    label: 'Python Test',
+    description:
+      'Preview or run pytest through uv run --frozen and summarise failures by test, file, and first project frame. Does not modify sources.',
+    promptSnippet: 'Preview or run Python tests and summarise failures',
+    promptGuidelines: [
+      'Use py_test with execute=false first; a preview is never a passing test run.',
+      'Use py_test after changing Python sources; it does not rebuild anything, so run py_sync first when dependencies changed.',
+    ],
+    parameters: Type.Object({
+      targets: Type.Optional(Type.Array(Type.String())),
+      lastFailed: Type.Optional(
+        Type.Boolean({ description: 'Rerun only tests that failed last time (--lf).' }),
+      ),
+      keyword: Type.Optional(Type.String({ description: 'pytest -k expression.' })),
+      maxFail: Type.Optional(Type.Integer({ minimum: 1, maximum: 1000 })),
+      execute: Type.Optional(Type.Boolean()),
+      timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 3600 })),
+      path: Type.Optional(Type.String()),
+    }),
+    async execute(_id, params, signal, _update, ctx) {
+      const started = Date.now();
+      try {
+        const root = (await resolveProjectRoot(ctx.cwd, params.path)) ?? ctx.cwd;
+        const command = pytestCommand(ctx.cwd, {
+          targets: params.targets,
+          lastFailed: params.lastFailed,
+          keyword: params.keyword,
+          maxFail: params.maxFail,
+        });
+        if (!params.execute) {
+          return text(
+            result(ctx.cwd, started, {
+              ok: true,
+              summary: 'pytest command preview generated; no test was executed.',
+              data: { executed: false, command },
+              evidence: [{ kind: 'command_preview', ...command }],
+              warnings: [],
+              errors: [],
+              suggestions: [
+                {
+                  message: 'Set execute=true to run the previewed pytest command.',
+                  confidence: 'high' as const,
+                },
+              ],
+              commands: [command],
+              projectRoot: root,
+            }),
+          );
+        }
+
+        const run = await runCommand(command.executable, command.args, {
+          cwd: ctx.cwd,
+          signal,
+          timeoutMs: (params.timeoutSeconds ?? 900) * 1000,
+          maxBytes: 512 * 1024,
+        });
+        const report = parsePytestOutput(run.stdout, run.stderr);
+        const firstFailure = report.failures[0];
+        const diagnosis = firstFailure
+          ? await refine(diagnoseFailure(`${run.stdout}\n${run.stderr}`), ctx.cwd, root, signal)
+          : undefined;
+
+        const failures = report.failures.slice(0, 20);
+        const timedOut = run.timedOut;
+        const failedCount = report.counts.failed + report.counts.errors;
+        const ok = run.code === 0 && !timedOut && !report.incomplete;
+        const errors: { code: string; message: string; severity: 'error' }[] = [];
+        if (timedOut) {
+          errors.push({
+            code: 'TEST_TIMEOUT',
+            message: 'pytest was terminated after exceeding the time limit.',
+            severity: 'error',
+          });
+        } else if (failedCount > 0) {
+          errors.push({
+            code: 'TESTS_FAILED',
+            message: `${report.counts.failed} test(s) failed and ${report.counts.errors} error(s) were reported.`,
+            severity: 'error',
+          });
+        } else if (report.incomplete) {
+          errors.push({
+            code: 'INCOMPLETE_TEST_OUTPUT',
+            message: 'pytest produced no summary, so no test result can be trusted.',
+            severity: 'error',
+          });
+        }
+
+        return text(
+          result(ctx.cwd, started, {
+            ok,
+            summary: timedOut
+              ? 'pytest exceeded the time limit and was terminated.'
+              : report.incomplete
+                ? 'pytest did not reach a summary; inspect the captured output before trusting any result.'
+                : `${report.counts.passed} passed, ${report.counts.failed} failed, ${report.counts.errors} error(s), ${report.counts.skipped} skipped.`,
+            data: {
+              executed: true,
+              exitCode: run.code,
+              truncated: run.truncated,
+              timedOut,
+              counts: report.counts,
+              summaryLine: report.summaryLine,
+              noTestsRan: report.noTestsRan,
+              failures,
+              failureCount: report.failures.length,
+              firstFailure: diagnosis,
+            },
+            evidence: [
+              {
+                kind: 'pytest_run',
+                exitCode: run.code,
+                counts: report.counts,
+                failures: failures.map((failure) => failure.test),
+                executed: true,
+              },
+            ],
+            warnings: [
+              ...(report.counts.warnings
+                ? [
+                    {
+                      code: 'PYTEST_WARNINGS',
+                      message: `pytest reported ${report.counts.warnings} warning(s); inspect them before changing test code.`,
+                      severity: 'warning' as const,
+                    },
+                  ]
+                : []),
+              ...(report.incomplete
+                ? [
+                    {
+                      code: 'INCOMPLETE_TEST_OUTPUT',
+                      message:
+                        'No pytest summary was found in the output; the run may have crashed during collection.',
+                      severity: 'warning' as const,
+                    },
+                  ]
+                : []),
+            ],
+            errors,
+            suggestions: diagnosis?.suggestions ?? [],
+            commands: [command],
+            truncated: run.truncated,
+            projectRoot: root,
+          }),
+        );
+      } catch (error) {
+        return text(failure(ctx.cwd, started, messageOf(error), 'INTERNAL_ERROR'));
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: 'py_failure_diagnose',
+    label: 'Python Failure Diagnose',
+    description:
+      'Classify the first actionable cause in bounded Python, pytest, or uv output and point at the first non-library traceback frame. Read-only.',
+    promptSnippet: 'Diagnose the first actionable Python failure',
+    promptGuidelines: [
+      'Use py_failure_diagnose on bounded command output instead of reading a full traceback in context; traceback frames inside site-packages are never the cause.',
+    ],
+    parameters: Type.Object({
+      output: Type.String({ description: 'Bounded stdout/stderr from the failing command.' }),
+      path: Type.Optional(
+        Type.String({ description: 'Project directory used to classify the missing module.' }),
+      ),
+    }),
+    async execute(_id, params, signal, _update, ctx) {
+      const started = Date.now();
+      try {
+        const root = await resolveProjectRoot(ctx.cwd, params.path);
+        const base = diagnoseFailure(params.output);
+        const diagnosis = await refine(base, ctx.cwd, root, signal);
+        const libraryFrames = diagnosis.frames.filter((frame) => frame.library).length;
+
+        return text(
+          result(ctx.cwd, started, {
+            ok: diagnosis.kind !== 'unknown',
+            summary: `${diagnosis.kind}: ${diagnosis.summary}`,
+            data: {
+              ...diagnosis,
+              libraryFrameCount: libraryFrames,
+              totalFrameCount: diagnosis.frames.length,
+            },
+            evidence: [
+              {
+                kind: 'failure_diagnosis',
+                failureKind: diagnosis.kind,
+                firstUserFrame: diagnosis.firstUserFrame ?? null,
+                libraryFrameCount: libraryFrames,
+              },
+              ...diagnosis.evidence.map((entry) => ({ kind: 'failure_evidence', ...entry })),
+            ],
+            warnings:
+              diagnosis.kind === 'unknown'
+                ? [
+                    {
+                      code: 'UNCLASSIFIED_FAILURE',
+                      message:
+                        'The output did not match a known Python, pytest, or uv failure pattern.',
+                      severity: 'warning' as const,
+                    },
+                  ]
+                : [],
+            errors:
+              diagnosis.kind === 'unknown'
+                ? []
+                : [
+                    {
+                      code: 'FAILURE_DIAGNOSED',
+                      message: diagnosis.summary,
+                      severity: 'error' as const,
+                      path: diagnosis.firstUserFrame?.path,
+                      line: diagnosis.firstUserFrame?.line,
+                    },
+                  ],
+            suggestions: diagnosis.suggestions,
+            projectRoot: root,
+          }),
+        );
+      } catch (error) {
+        return text(failure(ctx.cwd, started, messageOf(error), 'INTERNAL_ERROR'));
+      }
+    },
+  });
+}

package/extensions/tools/validation.ts

@@ -0,0 +1,344 @@
+import { Type } from 'typebox';
+import { failure, result, warn } from '../../src/core/result.ts';
+import { runCommand } from '../../src/core/runner.ts';
+import { pytestCommand, uvLockCheck, uvSyncFrozen } from '../../src/build/commands.ts';
+import { diagnoseFailure } from '../../src/build/failure.ts';
+import { parsePytestOutput } from '../../src/build/pytest.ts';
+import { detectStaleArtifacts } from '../../src/build/staleness.ts';
+import {
+  compareInstalledConformance,
+  requiredDeclarationsFrom,
+} from '../../src/project/conformance.ts';
+import { readInstalledDistributions } from '../../src/project/installed.ts';
+import { summarizeValidation, type ValidationStep } from '../../src/validation/bundle.ts';
+import { join } from 'node:path';
+import { isFile } from '../../src/project/root.ts';
+import { runScanProject } from '../../src/project/scanner.ts';
+import { messageOf, resolveProjectRoot, text, type Pi } from '../shared.ts';
+
+function stepFrom(run: { code: number | null; timedOut: boolean }): ValidationStep {
+  return { executed: true, ok: run.code === 0 && !run.timedOut, exitCode: run.code };
+}
+
+export function registerValidationTools(pi: Pi): void {
+  pi.registerTool({
+    name: 'py_sync',
+    label: 'Python Sync',
+    description:
+      'Preview or run uv lock --check or uv sync --frozen. Execution is opt-in because it modifies .venv. Does not edit sources.',
+    promptSnippet: 'Preview or run the uv environment sync',
+    promptGuidelines: [
+      'Use py_sync with execute=false to preview the uv command, and execute=true only when the environment must be created or refreshed.',
+    ],
+    parameters: Type.Object({
+      mode: Type.Optional(
+        Type.Union([Type.Literal('check'), Type.Literal('sync')], {
+          description: 'check runs uv lock --check; sync runs uv sync --frozen --all-groups.',
+        }),
+      ),
+      execute: Type.Optional(Type.Boolean()),
+      timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 1800 })),
+      path: Type.Optional(Type.String()),
+    }),
+    async execute(_id, params, signal, _update, ctx) {
+      const started = Date.now();
+      try {
+        const root = (await resolveProjectRoot(ctx.cwd, params.path)) ?? ctx.cwd;
+        const mode = params.mode ?? 'check';
+        const command = mode === 'check' ? uvLockCheck(ctx.cwd) : uvSyncFrozen(ctx.cwd);
+        const lockPresent = await isFile(join(root, 'uv.lock'));
+
+        if (!params.execute) {
+          return text(
+            result(ctx.cwd, started, {
+              ok: true,
+              summary: `${mode} command preview generated; nothing was executed.`,
+              data: { executed: false, mode, command, lockPresent },
+              evidence: [{ kind: 'command_preview', ...command }],
+              warnings: lockPresent
+                ? []
+                : [
+                    warn(
+                      'LOCKFILE_MISSING',
+                      'uv.lock does not exist, so uv lock --check cannot confirm the declared dependencies.',
+                      root,
+                    ),
+                  ],
+              errors: [],
+              suggestions: [
+                {
+                  message:
+                    mode === 'check'
+                      ? 'Set execute=true to verify that uv.lock matches pyproject.toml.'
+                      : 'Set execute=true to synchronise .venv from the lockfile.',
+                  confidence: 'high' as const,
+                },
+              ],
+              commands: [command],
+              projectRoot: root,
+            }),
+          );
+        }
+
+        const run = await runCommand(command.executable, command.args, {
+          cwd: ctx.cwd,
+          signal,
+          timeoutMs: (params.timeoutSeconds ?? 600) * 1000,
+          maxBytes: 256 * 1024,
+        });
+        const output = `${run.stdout}\n${run.stderr}`;
+        const diagnosis = run.code === 0 ? undefined : diagnoseFailure(output);
+
+        return text(
+          result(ctx.cwd, started, {
+            ok: run.code === 0,
+            summary: run.timedOut
+              ? 'uv exceeded the time limit and was terminated.'
+              : run.code === 0
+                ? mode === 'check'
+                  ? 'uv.lock matches pyproject.toml.'
+                  : 'The environment was synchronised from the lockfile.'
+                : `uv ${mode} failed: ${diagnosis?.summary ?? 'see the captured output.'}`,
+            data: {
+              executed: true,
+              mode,
+              exitCode: run.code,
+              truncated: run.truncated,
+              timedOut: run.timedOut,
+              stdoutTail: run.stdout.slice(-4000),
+              stderrTail: run.stderr.slice(-4000),
+              diagnosis,
+            },
+            evidence: [{ kind: 'uv_command', mode, exitCode: run.code, executed: true }],
+            warnings: run.truncated
+              ? [
+                  {
+                    code: 'OUTPUT_TRUNCATED',
+                    message: 'Command output was truncated; only the tail is reported.',
+                    severity: 'warning' as const,
+                  },
+                ]
+              : [],
+            errors:
+              run.code === 0
+                ? []
+                : [
+                    {
+                      code: mode === 'check' ? 'LOCKFILE_OUT_OF_DATE' : 'SYNC_FAILED',
+                      message:
+                        diagnosis?.summary ??
+                        run.stderr.trim().slice(0, 500) ??
+                        'uv exited with a non-zero status.',
+                      severity: 'error' as const,
+                    },
+                  ],
+            suggestions: diagnosis?.suggestions ?? [],
+            commands: [command],
+            truncated: run.truncated,
+            projectRoot: root,
+          }),
+        );
+      } catch (error) {
+        return text(failure(ctx.cwd, started, messageOf(error), 'INTERNAL_ERROR'));
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: 'py_validation_bundle',
+    label: 'Python Validation Bundle',
+    description:
+      'Preview or run one evidence-oriented sequence: uv lock --check, uv sync --frozen, pytest, and a stale-artifact check. Execution is opt-in.',
+    promptSnippet: 'Run the Python sync and test validation bundle',
+    promptGuidelines: [
+      'Use py_validation_bundle with execute=false first; a preview is never a passing validation.',
+      'Use py_validation_bundle as the single completion gate after changing Python sources or dependencies.',
+    ],
+    parameters: Type.Object({
+      targets: Type.Optional(Type.Array(Type.String())),
+      execute: Type.Optional(Type.Boolean()),
+      timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 3600 })),
+      path: Type.Optional(Type.String()),
+    }),
+    async execute(_id, params, signal, _update, ctx) {
+      const started = Date.now();
+      try {
+        const root = (await resolveProjectRoot(ctx.cwd, params.path)) ?? ctx.cwd;
+        const lockPresent = await isFile(join(root, 'uv.lock'));
+        const lock = uvLockCheck(ctx.cwd);
+        const sync = uvSyncFrozen(ctx.cwd);
+        const test = pytestCommand(ctx.cwd, { targets: params.targets });
+        const timeoutMs = (params.timeoutSeconds ?? 1800) * 1000;
+        const commands = [lock, sync, test];
+
+        if (!params.execute) {
+          return text(
+            result(ctx.cwd, started, {
+              ok: true,
+              summary: `Validation sequence preview generated (${lockPresent ? 'uv lock --check, uv sync, pytest' : 'uv sync, pytest'}); nothing was executed.`,
+              data: { executed: false, lockPresent, steps: commands },
+              evidence: [
+                {
+                  kind: 'validation_preview',
+                  steps: commands.map((entry) => entry.args.join(' ')),
+                },
+              ],
+              warnings: lockPresent
+                ? []
+                : [
+                    warn(
+                      'LOCKFILE_MISSING',
+                      'uv.lock does not exist; the lock check step cannot run and drift will not be detected.',
+                      root,
+                    ),
+                  ],
+              errors: [],
+              suggestions: [
+                {
+                  message: 'Set execute=true to run the sequence. This creates or refreshes .venv.',
+                  confidence: 'high' as const,
+                },
+              ],
+              commands,
+              projectRoot: root,
+            }),
+          );
+        }
+
+        const lockRun = lockPresent
+          ? await runCommand(lock.executable, lock.args, {
+              cwd: ctx.cwd,
+              signal,
+              timeoutMs,
+              maxBytes: 256 * 1024,
+            })
+          : undefined;
+        const syncRun = await runCommand(sync.executable, sync.args, {
+          cwd: ctx.cwd,
+          signal,
+          timeoutMs,
+          maxBytes: 256 * 1024,
+        });
+        const testRun =
+          syncRun.code === 0
+            ? await runCommand(test.executable, test.args, {
+                cwd: ctx.cwd,
+                signal,
+                timeoutMs,
+                maxBytes: 512 * 1024,
+              })
+            : undefined;
+
+        const report = testRun ? parsePytestOutput(testRun.stdout, testRun.stderr) : undefined;
+        const scan = await runScanProject(ctx.cwd, { root, mode: 'manifest' }, signal);
+        const installed = await readInstalledDistributions(join(root, '.venv'));
+        const conformance = compareInstalledConformance({
+          lock: scan.payload?.lock,
+          installed,
+          projectName: scan.payload?.manifest?.name ?? undefined,
+          requiredDeclarations: requiredDeclarationsFrom(scan.payload?.manifest),
+        });
+        const staleness = await detectStaleArtifacts(root);
+
+        const lockStep: ValidationStep = lockRun
+          ? stepFrom(lockRun)
+          : { executed: false, ok: false, exitCode: null };
+        const syncStep = stepFrom(syncRun);
+        const testStep: ValidationStep = testRun
+          ? {
+              ...stepFrom(testRun),
+              failures: report ? report.counts.failed + report.counts.errors : undefined,
+            }
+          : { executed: false, ok: false, exitCode: null };
+
+        const summary = summarizeValidation({
+          lock: lockStep,
+          sync: syncStep,
+          test: testStep,
+          conformance: conformance.verdict,
+          stale: staleness.stale,
+        });
+
+        const diagnosis =
+          testRun && testStep.ok === false
+            ? diagnoseFailure(`${testRun.stdout}\n${testRun.stderr}`)
+            : undefined;
+
+        return text(
+          result(ctx.cwd, started, {
+            ok: summary.ok,
+            summary: summary.reason,
+            data: {
+              executed: true,
+              checks: summary.checks,
+              lock: { ...lockStep, present: lockPresent },
+              sync: syncStep,
+              test: {
+                ...testStep,
+                counts: report?.counts,
+                failures: report?.failures.slice(0, 20),
+              },
+              conformance,
+              staleArtifacts: staleness,
+              firstFailure: diagnosis,
+            },
+            evidence: [
+              {
+                kind: 'validation_bundle',
+                checks: summary.checks,
+                lockExitCode: lockStep.exitCode ?? null,
+                syncExitCode: syncStep.exitCode ?? null,
+                testExitCode: testStep.exitCode ?? null,
+                testCounts: report?.counts ?? null,
+                conformanceVerdict: conformance.verdict,
+                stale: staleness.stale,
+              },
+            ],
+            warnings: [
+              ...conformance.warnings,
+              ...staleness.artifacts.map((artifact) => ({
+                code: artifact.code,
+                message: artifact.message,
+                severity: 'warning' as const,
+                path: artifact.path,
+              })),
+              ...(staleness.incompleteReason
+                ? [
+                    {
+                      code: 'STALENESS_UNVERIFIED',
+                      message: `Stale-artifact check was incomplete: ${staleness.incompleteReason}`,
+                      severity: 'warning' as const,
+                    },
+                  ]
+                : []),
+            ],
+            errors: summary.ok
+              ? []
+              : [
+                  {
+                    code: 'VALIDATION_FAILED',
+                    message: summary.reason,
+                    severity: 'error' as const,
+                  },
+                ],
+            suggestions: summary.ok
+              ? []
+              : [
+                  {
+                    message:
+                      'Fix the failing step before reporting completion; a partial run is not evidence.',
+                    confidence: 'high' as const,
+                  },
+                  ...(diagnosis?.suggestions ?? []),
+                ],
+            commands,
+            projectRoot: root,
+            pythonVersion: scan.payload?.pythonVersion,
+          }),
+        );
+      } catch (error) {
+        return text(failure(ctx.cwd, started, messageOf(error), 'INTERNAL_ERROR'));
+      }
+    },
+  });
+}