@0xcraft/powershot 1.0.0

package/dist/cli/args.js

@@ -0,0 +1,76 @@
+import { parseArgs } from 'node:util';
+export const HELP = `
+psh — code review for machine-written code
+
+  psh review                          staged + unstaged + untracked
+  psh review --from main --to feat/x  branch range
+  psh review --commit <hash>          a single commit
+  psh scan <path>                     audit existing files, no git history needed
+  psh delegate                        emit the judging work for an agent you already pay for
+  psh session list | view <id>        runs that can be resumed, or replayed as a page
+  psh session diff <a> <b>            what one review found that the other did not
+  psh dismiss <id> [--reason "..."]   record that a finding is correct, and stop showing it
+  psh dismiss list | restore <fp>     what has been waved through, and undoing it
+  psh agent <name> | list             teach a coding agent to use this tool
+  psh bench --repo <path>             replay real commits and count what the checks say
+
+Options
+  --verify-only          deterministic checks only — no model, no tokens
+  --checks a,b           run only these checks
+  --min-severity <s>     info | low | medium | high | critical   (default: low)
+  --format <f>           text · compact · markdown · json · sarif · codequality · manifest
+  --absorb <file>        merge findings a delegated agent produced
+  --last <n>             bench: how many commits to replay (default 50)
+  --cases <dir>          bench: labelled .json cases to score against
+  --tools                let judges read files and search before answering
+  --resume <id>          continue a run, reusing judge results already paid for
+  --output <path>        write the report to a file instead of stdout
+  --report <f>=<path>    write this format to that file; repeatable, one run
+  --budget k=v,...       requests · inputTokens · outputTokens · toolCalls · elapsedMs · units
+  --no-cache             ask every judge again, ignoring answers already paid for
+  --max-bundle <n>       lines per judge prompt (default 1200)
+  --help
+
+Exit codes: 0 clean · 1 findings reported · 2 bad usage · 3 review incomplete.
+A stage that failed makes the run non-zero even with nothing to report — "we found
+nothing" and "we could not look" must not be the same answer to a pipeline.
+`;
+export function parseCliArgs(args = process.argv.slice(2)) {
+    return parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            from: { type: 'string' },
+            to: { type: 'string' },
+            commit: { type: 'string' },
+            format: { type: 'string', default: 'text' },
+            checks: { type: 'string' },
+            'min-severity': { type: 'string' },
+            'verify-only': { type: 'boolean', default: false },
+            repo: { type: 'string' },
+            last: { type: 'string' },
+            cases: { type: 'string' },
+            tools: { type: 'boolean', default: false },
+            resume: { type: 'string' },
+            output: { type: 'string' },
+            'no-cache': { type: 'boolean', default: false },
+            report: { type: 'string', multiple: true },
+            budget: { type: 'string' },
+            'show-dismissed': { type: 'boolean', default: false },
+            reason: { type: 'string' },
+            'max-bundle': { type: 'string' },
+            absorb: { type: 'string' },
+            help: { type: 'boolean', short: 'h', default: false },
+        },
+    });
+}
+export function positiveNumber(value, flag, fallback) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    if (Number.isFinite(parsed) && parsed > 0)
+        return parsed;
+    process.stderr.write(flag + ' must be a positive number, got "' + String(value) + '"\n');
+    return undefined;
+}
+//# sourceMappingURL=args.js.map

package/dist/cli/bench-command.js

@@ -0,0 +1,89 @@
+import { f1, loadCases, precision, recall, replayRepo, runCases } from '#app/bench.js';
+import { repoRoot } from '#app/git.js';
+import { dim, bold, steel, yellow } from '#app/report/ansi.js';
+import { positiveNumber } from './args.js';
+function percentage(value) {
+    return (value * 100).toFixed(1) + '%';
+}
+function total(scores) {
+    return scores.reduce((sum, score) => ({ tp: sum.tp + score.tp, fp: sum.fp + score.fp, fn: sum.fn + score.fn }), { tp: 0, fp: 0, fn: 0 });
+}
+export async function runBenchCommand(values) {
+    const root = values.repo !== undefined ? repoRoot(values.repo) : repoRoot(process.cwd());
+    const out = process.stdout;
+    if (values.cases !== undefined) {
+        const cases = loadCases(values.cases);
+        if (cases.length === 0) {
+            process.stderr.write('No .json cases found in ' + values.cases + '\n');
+            return 2;
+        }
+        const reports = await runCases(root, cases);
+        out.write('\n ' + bold('PowerShot bench') + dim('  ·  ' + cases.length + ' labelled case(s)') + '\n\n');
+        for (const report of reports) {
+            if (!report.complete) {
+                out.write('  ' + yellow(report.state) + '  ' + report.name + dim('   ' + report.reasons.join('; ')) + '\n');
+                continue;
+            }
+            const exact = report.score.fp === 0 && report.score.fn === 0;
+            out.write('  ' + (exact ? steel('pass') : yellow('diff')) + '  ' + report.name +
+                dim('   tp ' + report.score.tp + ' · fp ' + report.score.fp + ' · fn ' + report.score.fn) + '\n');
+        }
+        const complete = reports.filter((report) => report.complete);
+        const score = total(complete.map((report) => report.score));
+        if (complete.length > 0) {
+            out.write('\n ' + bold('precision ' + percentage(precision(score))) + dim('  ·  ') +
+                'recall ' + percentage(recall(score)) + dim('  ·  ') + 'F1 ' + percentage(f1(score)) + '\n\n');
+        }
+        else {
+            out.write('\n ' + yellow('No complete case could be scored.') + '\n\n');
+        }
+        if (complete.length !== reports.length)
+            return 3;
+        return score.fp + score.fn > 0 ? 1 : 0;
+    }
+    const last = positiveNumber(values.last, '--last', 50);
+    if (last === undefined)
+        return 2;
+    process.stderr.write(dim(' ◇ replaying ' + last + ' commit(s) from ' + root) + '\n');
+    const report = await replayRepo(root, last, (line) => process.stderr.write(dim(' ◇ ' + line) + '\n'));
+    out.write('\n ' + bold('PowerShot bench') + dim('  ·  ' + report.commits + ' complete commit(s)') + '\n');
+    out.write(dim(' ' + '─'.repeat(70)) + '\n\n');
+    if (report.findings === 0 && report.partial === 0 && report.failed === 0 && report.falseClean === 0) {
+        out.write(' ' + steel('✔') + '  No findings across ' + report.commits + ' reviewed commits.\n');
+        out.write(dim('    On already-merged history that is the result to want: the checks stayed quiet.') + '\n\n');
+        return 0;
+    }
+    out.write(' ' + report.findings + ' finding(s) on ' + report.noisy.length + ' of ' + report.commits + ' complete commits\n');
+    out.write(dim('    ' + report.verified + ' verified · ' + report.judged + ' judged' +
+        (report.positions.added + report.positions.context > 0
+            ? '  ·  judged on a changed line: ' + report.positions.added + '/' + (report.positions.added + report.positions.context)
+            : '')) + '\n');
+    const coverage = report.coverage;
+    out.write(dim('    coverage ' + coverage.selected + ' reviewed · ' + coverage.limited + ' limited · ' +
+        coverage.waived + ' waived · ' + coverage.failed + ' failed') + '\n');
+    out.write((report.falseClean > 0 ? yellow('    ' + report.falseClean + ' commit(s) reported clean by an incomplete run')
+        : dim('    no commit was reported clean by an incomplete run')) + '\n');
+    if (report.usage.requests > 0) {
+        out.write(dim('    ' + report.usage.requests + ' request(s) · ' + report.usage.inputTokens + ' in · ' +
+            report.usage.outputTokens + ' out · ' + Math.round(report.usage.elapsedMs / 1000) + 's') + '\n');
+    }
+    out.write(dim('    Already-merged code — treat each as a likely false positive until read.') + '\n\n');
+    const rows = [...report.byCheck.entries()].sort((left, right) => right[1] - left[1]);
+    for (const [check, count] of rows) {
+        out.write('   ' + String(count).padStart(4) + '  ' + check + dim('   ' + (count / report.commits).toFixed(2) + ' per commit') + '\n');
+    }
+    out.write('\n');
+    for (const commit of report.noisy.slice(0, 12)) {
+        out.write(dim('   ' + commit.commit + '  ' + commit.subject.slice(0, 58)) + '\n');
+        for (const finding of commit.findings.slice(0, 4)) {
+            out.write('     ' + yellow(finding.check) + ' ' + dim(finding.file + ':' + finding.line) + '  ' + finding.title.slice(0, 60) + '\n');
+        }
+    }
+    if (report.partial > 0)
+        out.write(dim('\n   ' + report.partial + ' commit(s) were partial and not scored') + '\n');
+    if (report.failed > 0)
+        out.write(dim('   ' + report.failed + ' commit(s) failed and were not scored') + '\n');
+    out.write('\n');
+    return report.partial > 0 || report.failed > 0 || report.falseClean > 0 ? 3 : 0;
+}
+//# sourceMappingURL=bench-command.js.map

package/dist/cli/dismiss-command.js

@@ -0,0 +1,42 @@
+import { Dismissals, lastReport } from '#app/dismissed.js';
+import { repoRoot } from '#app/git.js';
+import { dim, bold, steel } from '#app/report/ansi.js';
+export function runDismissCommand(positionals, reason) {
+    const root = repoRoot(process.cwd());
+    const dismissals = Dismissals.open(root);
+    const subject = positionals[1];
+    if (!subject || subject === 'list') {
+        const all = dismissals.list();
+        if (all.length === 0) {
+            process.stdout.write(dim('\n Nothing has been dismissed.\n\n'));
+            return 0;
+        }
+        process.stdout.write('\n ' + bold('Dismissed') + dim('  ·  committed, so the team shares it') + '\n\n');
+        for (const dismissal of all) {
+            process.stdout.write('  ' + steel(dismissal.fingerprint.slice(0, 8)) + '  ' + dismissal.check + dim(' · ' + dismissal.file) + '\n');
+            process.stdout.write(dim('            ' + dismissal.code.slice(0, 68)) + '\n');
+            if (dismissal.reason)
+                process.stdout.write(dim('            because: ' + dismissal.reason) + '\n');
+        }
+        process.stdout.write('\n' + dim(' psh dismiss restore <fingerprint>') + '\n\n');
+        return 0;
+    }
+    if (subject === 'restore') {
+        const fingerprint = positionals[2];
+        if (!fingerprint || !dismissals.remove(fingerprint)) {
+            process.stderr.write('No dismissal starting with "' + (fingerprint ?? '') + '". Try: psh dismiss list\n');
+            return 2;
+        }
+        process.stdout.write(dim(' restored — it will be reported again\n'));
+        return 0;
+    }
+    const finding = lastReport(root).find((item) => item.id.toLowerCase() === subject.toLowerCase());
+    if (!finding) {
+        process.stderr.write('No finding "' + subject + '" in the last review. Run psh review first.\n');
+        return 2;
+    }
+    const added = dismissals.add(finding, reason, new Date().toISOString());
+    process.stdout.write((added ? ' dismissed ' : ' already dismissed ') + finding.check + ' at ' + finding.file + ':' + finding.line + '\n');
+    return 0;
+}
+//# sourceMappingURL=dismiss-command.js.map

package/dist/cli/environment.js

@@ -0,0 +1,32 @@
+import { join } from 'node:path';
+import { repoRoot } from '#app/git.js';
+import { dim, yellow } from '#app/report/ansi.js';
+const REPOSITORY_ENV = /_API_KEY$/;
+export function loadRepositoryEnv() {
+    try {
+        if (process.env.CI)
+            return;
+        const inherited = { ...process.env };
+        process.loadEnvFile(join(repoRoot(process.cwd()), '.env'));
+        const refused = [];
+        for (const key of Object.keys(process.env)) {
+            if (Object.prototype.hasOwnProperty.call(inherited, key))
+                continue;
+            if (REPOSITORY_ENV.test(key))
+                continue;
+            delete process.env[key];
+            refused.push(key);
+        }
+        for (const [key, value] of Object.entries(inherited)) {
+            if (value !== undefined)
+                process.env[key] = value;
+        }
+        if (refused.length > 0) {
+            process.stderr.write(yellow(' ◇ .env') + dim('     ignored ' + refused.join(', ') + ' — only *_API_KEY may come from the repository') + '\n');
+        }
+    }
+    catch {
+        // A missing .env and a directory outside Git are both normal startup states.
+    }
+}
+//# sourceMappingURL=environment.js.map

package/dist/cli/reports.js

@@ -0,0 +1,64 @@
+import { writeFileSync } from 'node:fs';
+import { dim } from '#app/report/ansi.js';
+import { codeQuality } from '#app/report/codequality.js';
+import { compact } from '#app/report/compact.js';
+import { markdown } from '#app/report/markdown.js';
+import { sarif } from '#app/report/sarif.js';
+import { terminal } from '#app/report/terminal.js';
+export const REPORT_FORMATS = ['text', 'compact', 'markdown', 'json', 'sarif', 'codequality', 'manifest'];
+export function isReportFormat(value) {
+    return REPORT_FORMATS.includes(value);
+}
+export function parseReportSpecs(values = []) {
+    const reports = [];
+    for (const spec of values) {
+        const separator = spec.indexOf('=');
+        const format = separator === -1 ? spec : spec.slice(0, separator);
+        if (!isReportFormat(format))
+            return '--report format must be one of: ' + REPORT_FORMATS.join(', ');
+        const path = separator === -1 ? '' : spec.slice(separator + 1);
+        if (!path)
+            return '--report needs a path: --report ' + format + '=<file>';
+        reports.push({ format, path });
+    }
+    return reports;
+}
+function jsonResult(result) {
+    return JSON.stringify(result, (_key, value) => (value instanceof Set ? [...value] : value), 2) + '\n';
+}
+export function renderReport(format, result, manifest, target) {
+    if (format === 'manifest')
+        return JSON.stringify(manifest, null, 2) + '\n';
+    if (format === 'compact')
+        return compact(result.findings);
+    if (format === 'codequality')
+        return codeQuality(result.findings);
+    if (format === 'sarif')
+        return sarif(result.findings);
+    if (format === 'json')
+        return jsonResult(result);
+    if (format === 'markdown')
+        return markdown(result.findings, manifest);
+    return terminal(result.findings, {
+        subtitle: target,
+        ...result.stats,
+        state: manifest.state,
+        notLookedAt: manifest.notLookedAt,
+    });
+}
+export function publishReports(options) {
+    const { result, manifest, target } = options;
+    for (const report of options.additional) {
+        writeFileSync(report.path, renderReport(report.format, result, manifest, target));
+        process.stderr.write(dim(' written to ' + report.path) + '\n');
+    }
+    const primary = renderReport(options.format, result, manifest, target);
+    if (options.output !== undefined) {
+        writeFileSync(options.output, primary);
+        process.stderr.write(dim(' written to ' + options.output) + '\n');
+    }
+    else {
+        process.stdout.write(primary);
+    }
+}
+//# sourceMappingURL=reports.js.map

package/dist/cli/review-command.js

@@ -0,0 +1,268 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { Budget, parseLimits } from '#app/budget.js';
+import { loadConfig, policyChanged } from '#app/config.js';
+import { absorbDelegated, delegateBrief } from '#app/delegate.js';
+import { baseRefOf, checkRange, headSha, repoRoot, shaOf } from '#app/git.js';
+import { JUDGES } from '#app/judges/prompts.js';
+import { RunManifest, coverageProblems, hashOf, writeManifest } from '#app/manifest.js';
+import { Trace } from '#app/otel.js';
+import { PACKAGE_VERSION } from '#app/package-meta.js';
+import { dim, yellow } from '#app/report/ansi.js';
+import { progress, stage } from '#app/report/terminal.js';
+import { review } from '#app/review.js';
+import { scanPaths } from '#app/scan.js';
+import { Session } from '#app/session.js';
+import { withTargetTree } from '#app/snapshot.js';
+import { SEVERITIES } from '#app/types.js';
+import { VERIFIERS } from '#app/verifiers/index.js';
+import { positiveNumber } from './args.js';
+import { REPORT_FORMATS, isReportFormat, parseReportSpecs, publishReports, } from './reports.js';
+function targetName(command, values, positionals) {
+    if (command === 'scan')
+        return 'scan ' + (positionals[1] ?? '.');
+    if (values.commit)
+        return 'commit ' + values.commit;
+    if (values.from)
+        return values.from + '...' + values.to;
+    return 'workspace';
+}
+export async function runReviewCommand(command, values, positionals) {
+    if (!isReportFormat(values.format)) {
+        process.stderr.write('--format must be one of: ' + REPORT_FORMATS.join(', ') + '\n');
+        return 2;
+    }
+    if ((values.from && !values.to) || (values.to && !values.from)) {
+        process.stderr.write('--from and --to must be given together.\n');
+        return 2;
+    }
+    const root = repoRoot(process.cwd());
+    const range = { from: values.from, to: values.to, commit: values.commit };
+    // Ref validation must precede policy loading because the policy is read through Git.
+    try {
+        checkRange(root, range);
+    }
+    catch (error) {
+        process.stderr.write(error.message + '\n');
+        return 2;
+    }
+    const gated = values.from !== undefined || values.commit !== undefined;
+    const policyBase = gated ? baseRefOf(root, range) : undefined;
+    const config = loadConfig(root, {
+        verifiers: [...new Set(VERIFIERS.flatMap((verifier) => [verifier.name, verifier.id ?? verifier.name]))],
+        judges: JUDGES.map((judge) => judge.name),
+    }, policyBase);
+    const verifierChecks = new Set(VERIFIERS.flatMap((verifier) => [verifier.name, verifier.id ?? verifier.name]));
+    const judgeChecks = new Set(JUDGES.map((judge) => judge.name));
+    const requestedChecks = values.checks?.split(',').map((check) => check.trim()).filter(Boolean);
+    if (values.checks !== undefined && requestedChecks?.length === 0) {
+        process.stderr.write('--checks must name at least one check\n');
+        return 2;
+    }
+    if (requestedChecks) {
+        const knownChecks = new Set([...verifierChecks, ...judgeChecks]);
+        const unknown = requestedChecks.filter((name) => !knownChecks.has(name));
+        if (unknown.length > 0) {
+            process.stderr.write('--checks has unknown name(s): ' + unknown.join(', ') + '\n');
+            return 2;
+        }
+        if (command === 'delegate') {
+            const deterministic = requestedChecks.filter((name) => !judgeChecks.has(name));
+            if (deterministic.length > 0) {
+                process.stderr.write('delegate accepts judge names only, not: ' + deterministic.join(', ') + '\n');
+                return 2;
+            }
+        }
+        else if (values['verify-only']) {
+            const judges = requestedChecks.filter((name) => judgeChecks.has(name) && !verifierChecks.has(name));
+            if (judges.length > 0) {
+                process.stderr.write('--verify-only cannot run judge check(s): ' + judges.join(', ') + '\n');
+                return 2;
+            }
+        }
+    }
+    if (policyBase && policyChanged(root, policyBase)) {
+        process.stderr.write(yellow(' ◇ policy') + dim('   this change edits powershot.config.json — reviewed under the base policy') + '\n');
+    }
+    if (values['min-severity']) {
+        const minimum = values['min-severity'];
+        if (!SEVERITIES.includes(minimum)) {
+            process.stderr.write('--min-severity must be one of: ' + SEVERITIES.join(', ') + '\n');
+            return 2;
+        }
+        config.minSeverity = minimum;
+    }
+    const bundleLimit = positiveNumber(values['max-bundle'], '--max-bundle', 1200);
+    if (bundleLimit === undefined)
+        return 2;
+    const maxBundle = values['max-bundle'] === undefined ? undefined : bundleLimit;
+    const reportSpecs = parseReportSpecs(values.report);
+    if (typeof reportSpecs === 'string') {
+        process.stderr.write(reportSpecs + '\n');
+        return 2;
+    }
+    if (command === 'delegate' && values.absorb !== undefined) {
+        process.stderr.write('--absorb cannot be used with delegate\n');
+        return 2;
+    }
+    // Invalid delegated output must not leave behind a resumable session.
+    const absorbed = values.absorb !== undefined
+        ? absorbDelegated(readFileSync(values.absorb, 'utf8'))
+        : undefined;
+    let limits = {};
+    if (values.budget !== undefined) {
+        const parsed = parseLimits(values.budget);
+        if (typeof parsed === 'string') {
+            process.stderr.write(parsed + '\n');
+            return 2;
+        }
+        limits = parsed;
+    }
+    const quiet = values.format === 'json' || values.format === 'sarif' || values.format === 'compact';
+    const target = targetName(command, values, positionals);
+    let session;
+    if (values.resume !== undefined) {
+        session = Session.open(root, values.resume);
+        if (!session) {
+            process.stderr.write('No session ' + values.resume + '. Try: psh session list\n');
+            return 2;
+        }
+        if (!session.askedBy(config.provider, config.model)) {
+            const previous = session.asked;
+            process.stderr.write('Session ' + values.resume + ' was judged by ' + previous?.provider + '/' + previous?.model +
+                ', and this run would use ' + config.provider + '/' + config.model + '.\n' +
+                'Resuming would mix two reviewers into one report. Start a fresh run, or switch back.\n');
+            return 2;
+        }
+    }
+    else if (!values['verify-only'] && command !== 'delegate') {
+        session = Session.create(root, target, { provider: config.provider, model: config.model });
+    }
+    if (command === 'delegate') {
+        const { buildGround } = await import('#app/ground.js');
+        const { collectChanges, statedIntent } = await import('#app/git.js');
+        const { matchesAny } = await import('#app/config.js');
+        const changes = collectChanges(root, range).filter((change) => !matchesAny(change.path, config.ignore));
+        if (changes.length === 0) {
+            process.stderr.write('Nothing to review.\n');
+            return 0;
+        }
+        const ground = await withTargetTree(root, range, (tree) => buildGround(tree, changes));
+        process.stdout.write(delegateBrief(ground, config, {
+            intent: statedIntent(root, range),
+            maxBundleLines: maxBundle,
+            checks: requestedChecks,
+        }));
+        return 0;
+    }
+    const canceller = new AbortController();
+    let interrupted = false;
+    const onInterrupt = () => {
+        if (interrupted)
+            process.exit(130);
+        interrupted = true;
+        canceller.abort();
+        process.stderr.write(dim('\n ◇ stopping after the current unit — press Ctrl-C again to exit now') + '\n');
+    };
+    const manifest = new RunManifest(session?.id ?? createHash('sha1').update(target + ':' + Date.now()).digest('hex').slice(0, 8));
+    const trace = new Trace();
+    const runSpan = trace.span('review', { target });
+    const result = await withTargetTree(root, command === 'scan' ? {} : range, (tree) => review({
+        root: tree,
+        stateRoot: root,
+        range,
+        changes: command === 'scan' ? scanPaths(root, positionals[1] ?? '.') : undefined,
+        config,
+        session,
+        tools: values.tools,
+        maxBundleLines: maxBundle,
+        signal: canceller.signal,
+        cache: !values['no-cache'],
+        budget: new Budget(limits),
+        manifest,
+        showDismissed: values['show-dismissed'],
+        absorbed,
+        onCancelable: (active) => {
+            if (!active) {
+                process.off('SIGINT', onInterrupt);
+                process.off('SIGTERM', onInterrupt);
+                return;
+            }
+            process.on('SIGINT', onInterrupt);
+            process.on('SIGTERM', onInterrupt);
+        },
+        verifyOnly: values['verify-only'],
+        checks: requestedChecks,
+        onProgress: quiet ? undefined : (line) => process.stderr.write(progress(line) + '\n'),
+        onStage: quiet ? undefined : stage,
+    }));
+    runSpan({
+        findings: result.findings.length,
+        verified: result.stats.verified,
+        judged: result.stats.judged,
+        files: result.stats.files,
+    });
+    await trace.flush();
+    const record = manifest.build({
+        operation: command,
+        repositoryHead: headSha(root),
+        target: {
+            requested: { from: values.from, to: values.to, commit: values.commit },
+            base: policyBase ? shaOf(root, policyBase) : undefined,
+            head: headSha(root),
+        },
+        policy: {
+            source: policyBase ? 'base' : 'head',
+            ref: policyBase,
+            hash: hashOf(JSON.stringify(config)),
+        },
+        engine: {
+            version: PACKAGE_VERSION,
+            provider: config.provider,
+            model: config.model,
+            tools: values.tools,
+            verifyOnly: values['verify-only'],
+        },
+        files: result.plan?.items() ?? [],
+        skippedChecks: result.skippedChecks ?? [],
+        findings: {
+            total: result.findings.length,
+            verified: result.stats.verified,
+            judged: result.stats.judged,
+            dismissed: result.stats.dismissed,
+            droppedPosition: result.droppedPosition ?? 0,
+        },
+        usage: result.usage ?? { requests: 0, inputTokens: 0, outputTokens: 0, toolCalls: 0, elapsedMs: 0, units: 0 },
+        failures: result.failures,
+        cancelled: result.cancelled,
+        budgetStop: result.budgetStop,
+    });
+    const gaps = coverageProblems(record);
+    if (gaps.length > 0) {
+        const failure = 'manifest: ' + gaps.join('; ');
+        result.failures.push(failure);
+        record.state = 'failed';
+        record.failures.push(failure);
+        record.notLookedAt.push(failure);
+        process.stderr.write(yellow(' ◇ manifest') + dim(' ' + gaps.join('; ')) + '\n');
+    }
+    session?.saveReport(result.findings, { state: record.state, notLookedAt: record.notLookedAt });
+    writeManifest(root, record);
+    publishReports({
+        format: values.format,
+        output: values.output,
+        additional: reportSpecs,
+        result,
+        manifest: record,
+        target,
+    });
+    if (values.format === 'text' && session && !values['verify-only']) {
+        process.stderr.write(dim(' session ' + session.id + '  ·  psh review --resume ' + session.id) + '\n');
+    }
+    if (interrupted)
+        return 130;
+    if (result.failures.length > 0 || gaps.length > 0 || record.state !== 'complete')
+        return 3;
+    return result.findings.length > 0 ? 1 : 0;
+}
+//# sourceMappingURL=review-command.js.map

package/dist/cli/session-command.js

@@ -0,0 +1,62 @@
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { repoRoot } from '#app/git.js';
+import { dim, bold, steel, yellow } from '#app/report/ansi.js';
+import { viewer } from '#app/report/viewer.js';
+import { Session } from '#app/session.js';
+export function runSessionCommand(positionals) {
+    const root = repoRoot(process.cwd());
+    const operation = positionals[1];
+    if (operation === 'diff') {
+        const older = positionals[2] ? Session.open(root, positionals[2]) : undefined;
+        const newer = positionals[3] ? Session.open(root, positionals[3]) : undefined;
+        if (!older?.report || !newer?.report || older.report.state !== 'complete' || newer.report.state !== 'complete') {
+            process.stderr.write('Need two complete sessions: psh session diff <older> <newer>\n');
+            return 2;
+        }
+        const { fixed, introduced, remaining } = Session.compare(older, newer);
+        const out = process.stdout;
+        out.write('\n ' + bold('Between ') + older.id + dim(' and ') + newer.id + '\n\n');
+        const show = (label, list, paint) => {
+            out.write(' ' + paint(String(list.length).padStart(3) + '  ' + label) + '\n');
+            for (const finding of list.slice(0, 10)) {
+                out.write(dim('      ' + finding.check + '  ' + finding.file + ':' + finding.line + '  ') + finding.title.slice(0, 60) + '\n');
+            }
+        };
+        show('fixed', fixed, steel);
+        show('introduced', introduced, yellow);
+        out.write(' ' + dim(String(remaining.length).padStart(3) + '  still there') + '\n\n');
+        return introduced.length > 0 ? 1 : 0;
+    }
+    if (operation === 'view') {
+        const id = positionals[2];
+        const session = id ? Session.open(root, id) : undefined;
+        if (!session?.report) {
+            process.stderr.write('No finished session ' + (id ?? '') + '. Try: psh session list\n');
+            return 2;
+        }
+        const output = join(root, '.powershot', 'sessions', session.id + '.html');
+        writeFileSync(output, viewer(session.report.findings, {
+            id: session.id,
+            target: session.target,
+            started: session.started,
+            state: session.report.state ?? 'unknown',
+            notLookedAt: session.report.notLookedAt ?? ['session predates verdict recording'],
+        }));
+        process.stdout.write(output + '\n');
+        return 0;
+    }
+    const rows = Session.list(root);
+    if (rows.length === 0) {
+        process.stdout.write(dim('\n No resumable sessions.\n\n'));
+        return 0;
+    }
+    process.stdout.write('\n ' + bold('Sessions') + '\n\n');
+    for (const row of rows) {
+        process.stdout.write('  ' + steel(row.id) + '  ' + dim(row.started.slice(0, 19).replace('T', ' ')) +
+            '  ' + row.target + dim('   ' + row.done + ' unit(s) done') + '\n');
+    }
+    process.stdout.write('\n' + dim(' psh review --resume <id>') + '\n\n');
+    return 0;
+}
+//# sourceMappingURL=session-command.js.map

package/dist/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from './cli/app.js';
+runCli().then((code) => process.exit(code), (error) => {
+    process.stderr.write('psh: ' + error.message + '\n');
+    process.exit(2);
+});
+//# sourceMappingURL=cli.js.map