@haystackeditor/cli 0.15.30 → 0.15.31

package/dist/commands/design-verify.d.ts

@@ -27,5 +27,7 @@ export interface DesignVerifyOptions {
     cwd?: string;
     commandTimeout?: string;
     action?: string;
+    history?: boolean;
+    limit?: string;
 }
 export declare function designVerifyCommand(identifier: string, options: DesignVerifyOptions): Promise<void>;

package/dist/commands/design-verify.js

@@ -16,8 +16,9 @@
 import chalk from 'chalk';
 import { loadToken } from '../utils/auth.js';
 import { parsePrRef } from '../utils/pr-ref.js';
-import { getDesignVerifierUniverseAction, startDesignVerifierUniverseAction, triggerDesignVerifier, waitForDesignVerifier, waitForDesignVerifierUniverseAction, } from '../utils/design-verifier-api.js';
+import { getDesignVerifierHistory, getDesignVerifierUniverseAction, startDesignVerifierUniverseAction, triggerDesignVerifier, waitForDesignVerifier, waitForDesignVerifierUniverseAction, } from '../utils/design-verifier-api.js';
 import { buildDesignVerifierAgentReport, designVerifierStageLabel, formatDesignVerifierAgentReport, } from '../utils/design-verifier-result.js';
+import { formatDesignVerifierHistory } from '../utils/design-verifier-history.js';
 function emit(json, payload, human) {
     if (json) {
         console.log(JSON.stringify(payload));
@@ -189,6 +190,31 @@ export async function designVerifyCommand(identifier, options) {
         process.exitCode = 1;
         return;
     }
+    if (options.history || options.limit !== undefined) {
+        try {
+            if (!options.history)
+                throw new Error('--limit requires --history');
+            if (options.run || options.case || options.universe || options.replay || options.execJson ||
+                options.cwd || options.commandTimeout || options.action || options.wait === false) {
+                throw new Error('--history cannot be combined with run or universe operations');
+            }
+            const limit = Number(options.limit ?? '20');
+            if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
+                throw new Error('--limit must be between 1 and 100');
+            }
+            const loaded = await getDesignVerifierHistory(pr.owner, pr.repo, token, limit);
+            if (loaded.status !== 'ok')
+                throw new Error(loaded.message);
+            emit(options.json, { ...loaded.history }, () => console.log(formatDesignVerifierHistory(loaded.history)));
+        }
+        catch (error) {
+            emit(options.json, { ok: false, error: error.message }, () => {
+                console.error(chalk.red(error.message));
+            });
+            process.exitCode = 2;
+        }
+        return;
+    }
     const pollIntervalSeconds = Number(options.pollInterval || '3');
     const timeoutSeconds = Number(options.timeout || '7200');
     if (!(Number.isFinite(pollIntervalSeconds) && pollIntervalSeconds >= 1 && pollIntervalSeconds <= 60)) {

package/dist/commands/verify-history.d.ts

@@ -0,0 +1,14 @@
+import type { VerifyHistoryReport } from '../types/verify-history.js';
+export interface VerifyHistoryOptions {
+    limit?: string;
+    account?: string;
+    json?: boolean;
+}
+/** Reject contradictory or mismatched data before printing health or findings. */
+export declare function parseVerifyHistoryReport(value: unknown, expected: {
+    owner: string;
+    name: string;
+    limit: number;
+}): VerifyHistoryReport;
+export declare function formatVerifyHistory(report: VerifyHistoryReport): string;
+export declare function verifyHistoryCommand(repository: string, options: VerifyHistoryOptions): Promise<void>;

package/dist/commands/verify-history.js

@@ -0,0 +1,152 @@
+import { resolveAuthContext } from '../utils/auth.js';
+import { haystackJson, HaystackApiError } from '../utils/haystack-api.js';
+const HEALTH = ['healthy', 'degraded', 'infrastructure-error', 'not-executed', 'unknown'];
+const LIFECYCLES = ['complete', 'failed', 'cancelled', 'budget-stopped', 'account-action'];
+const RUN_ID = /^cv_[0-9a-f]{48}$/;
+const COMMIT = /^[0-9a-f]{40}$/;
+const REPO_COMPONENT = /^(?!\.{1,2}$)[A-Za-z0-9_.-]{1,100}$/;
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function count(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+function timestamp(value) {
+    return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+/** Reject contradictory or mismatched data before printing health or findings. */
+export function parseVerifyHistoryReport(value, expected) {
+    const invalid = () => {
+        throw new Error('The hosted verifier returned invalid or mismatched history. No reliability summary was accepted.');
+    };
+    if (!record(value) || value.version !== 'dv-verify-history-v1'
+        || value.provider !== 'haystack' || value.scope !== 'user'
+        || !record(value.repository)
+        || typeof value.repository.owner !== 'string' || typeof value.repository.name !== 'string'
+        || value.repository.owner !== expected.owner
+        || value.repository.name !== expected.name
+        || typeof value.repository.repositoryId !== 'string'
+        || !/^github\.com:[1-9]\d*$/.test(value.repository.repositoryId)
+        || value.limit !== expected.limit || typeof value.hasMore !== 'boolean'
+        || !Array.isArray(value.runs) || value.runs.length > expected.limit
+        || (value.hasMore && value.runs.length !== expected.limit)
+        || !record(value.summary) || !record(value.summary.counts))
+        return invalid();
+    const counts = {
+        healthy: 0, degraded: 0, 'infrastructure-error': 0, 'not-executed': 0, unknown: 0,
+    };
+    const seen = new Set();
+    let usable = 0;
+    let previousCompletedAt = Infinity;
+    for (const run of value.runs) {
+        if (!record(run) || typeof run.runId !== 'string' || !RUN_ID.test(run.runId)
+            || seen.has(run.runId)
+            || typeof run.baseCommit !== 'string' || !COMMIT.test(run.baseCommit)
+            || typeof run.headCommit !== 'string' || !COMMIT.test(run.headCommit)
+            || !timestamp(run.createdAt) || !timestamp(run.completedAt)
+            || Date.parse(run.completedAt) < Date.parse(run.createdAt)
+            || Date.parse(run.completedAt) > previousCompletedAt
+            || (run.status !== 'complete' && run.status !== 'errored')
+            || (run.lifecycle !== null && !LIFECYCLES.includes(run.lifecycle))
+            || !HEALTH.includes(run.health)
+            || (run.regressionCount !== null && !count(run.regressionCount))
+            || (run.executedCaseCount !== null && !count(run.executedCaseCount))
+            || !Array.isArray(run.degradationCodes)
+            || run.degradationCodes.some(code => typeof code !== 'string' || code.length === 0)
+            || new Set(run.degradationCodes).size !== run.degradationCodes.length
+            || (run.supersededBy !== null && (typeof run.supersededBy !== 'string'
+                || !RUN_ID.test(run.supersededBy) || run.supersededBy === run.runId)))
+            return invalid();
+        if (run.health === 'unknown') {
+            if (run.status !== 'errored' || run.lifecycle !== null || run.regressionCount !== null
+                || run.executedCaseCount !== null || run.degradationCodes.length !== 0)
+                return invalid();
+        }
+        else if (run.lifecycle === null || run.regressionCount === null || run.executedCaseCount === null) {
+            return invalid();
+        }
+        else if ((run.lifecycle === 'complete') !== (run.status === 'complete')) {
+            return invalid();
+        }
+        if (run.health === 'healthy' && (run.lifecycle !== 'complete'
+            || run.executedCaseCount === 0 || run.degradationCodes.length !== 0))
+            return invalid();
+        if (run.health === 'not-executed' && (run.executedCaseCount !== 0 || run.regressionCount !== 0))
+            return invalid();
+        if (run.executedCaseCount === 0 && run.regressionCount !== null && run.regressionCount !== 0)
+            return invalid();
+        seen.add(run.runId);
+        previousCompletedAt = Date.parse(run.completedAt);
+        counts[run.health]++;
+        if ((run.health === 'healthy' || run.health === 'degraded')
+            && typeof run.executedCaseCount === 'number' && run.executedCaseCount > 0)
+            usable++;
+    }
+    const usableRate = value.runs.length === 0 ? null : usable / value.runs.length;
+    const summaryCounts = value.summary.counts;
+    if (value.summary.total !== value.runs.length || value.summary.usableRate !== usableRate
+        || HEALTH.some(health => summaryCounts[health] !== counts[health]))
+        return invalid();
+    return value;
+}
+function terminalSafe(value) {
+    return Array.from(value).filter(character => {
+        const point = character.codePointAt(0);
+        return point >= 32 && !(point >= 127 && point <= 159);
+    }).join('');
+}
+export function formatVerifyHistory(report) {
+    const { summary } = report;
+    const lines = [
+        `Your verification history for ${report.repository.owner}/${report.repository.name}`,
+        `Latest ${summary.total} finished runs for the selected account (limit ${report.limit}).`,
+    ];
+    if (summary.total === 0) {
+        lines.push('No finished hosted fleet runs found for this account and repository.');
+        return lines.join('\n');
+    }
+    const usable = report.runs.filter(run => (run.health === 'healthy' || run.health === 'degraded')
+        && run.executedCaseCount !== null && run.executedCaseCount > 0).length;
+    lines.push(`Usable evidence: ${Math.round(summary.usableRate * 100)}% of these runs (${usable}/${summary.total}).`, `Healthy: ${summary.counts.healthy}; partially degraded: ${summary.counts.degraded}; infrastructure error: ${summary.counts['infrastructure-error']}; not executed: ${summary.counts['not-executed']}; unknown: ${summary.counts.unknown}.`, 'Usable means healthy or partially degraded with at least one executed check.', 'This measures execution reliability. Bugs found are listed separately; they do not lower this rate.', '');
+    for (const run of report.runs) {
+        const health = run.health === 'degraded' ? 'partially degraded' : run.health;
+        const checks = run.executedCaseCount === null ? 'unknown checks executed' : `${run.executedCaseCount} checks executed`;
+        const regressions = run.regressionCount === null ? 'bugs found unknown'
+            : `${run.regressionCount} ${run.regressionCount === 1 ? 'bug' : 'bugs'} found`;
+        lines.push(`${terminalSafe(run.completedAt)}  ${health}  ${checks}  ${regressions}`, `  ${run.runId}  ${run.baseCommit.slice(0, 12)} -> ${run.headCommit.slice(0, 12)}`);
+        if (run.lifecycle && run.lifecycle !== 'complete')
+            lines.push(`  Run outcome: ${run.lifecycle}`);
+        if (run.degradationCodes.length)
+            lines.push(`  Limitations: ${run.degradationCodes.map(terminalSafe).join(', ')}`);
+        if (run.supersededBy)
+            lines.push(`  Replaced by: ${run.supersededBy}`);
+    }
+    if (report.hasMore)
+        lines.push('', 'Older finished runs exist. Increase --limit to show up to 100.');
+    return lines.join('\n');
+}
+export async function verifyHistoryCommand(repository, options) {
+    const parts = repository.split('/');
+    if (parts.length !== 2 || !parts.every(part => REPO_COMPONENT.test(part))) {
+        throw new Error('Use an exact GitHub owner/repository name for verification history.');
+    }
+    const limitText = options.limit ?? '20';
+    if (!/^[1-9]\d*$/.test(limitText) || Number(limitText) > 100) {
+        throw new Error('--limit must be a whole number from 1 to 100.');
+    }
+    const [owner, name] = parts;
+    const limit = Number(limitText);
+    const auth = await resolveAuthContext({ preferredLogin: options.account, owner, repo: name });
+    let response;
+    try {
+        response = await haystackJson(`/api/agent/cloud-verifier/history/${encodeURIComponent(owner)}/${encodeURIComponent(name)}?limit=${limit}`, auth.token, { method: 'GET' });
+    }
+    catch (error) {
+        if (error instanceof HaystackApiError && error.status === 404) {
+            throw new Error('Verification history was not found for this repository and account. Check repository access and use --account <login> if needed.');
+        }
+        throw error;
+    }
+    const report = parseVerifyHistoryReport(response, { owner, name, limit });
+    process.stdout.write((options.json ? JSON.stringify(report, null, 2) : formatVerifyHistory(report)) + '\n');
+}

package/dist/commands/verify-hosted.js

@@ -132,6 +132,9 @@ export function parseHostedRunState(value, expectedRunId) {
                 requireString(finding, 'caseId');
                 requireString(finding, 'judgment');
             }
+            if (fleetResult.savedChecks !== undefined) {
+                parseHostedSavedChecks(fleetResult.savedChecks, runId, headCommit);
+            }
             requireString(provenance, 'intent', /^(user|inferred)$/);
             if (status === 'complete' && fleetResult.lifecycle !== 'complete') {
                 throw new Error('Hosted fleet lifecycle disagrees with its completed job.');
@@ -216,6 +219,92 @@ export function parseHostedRepository(value) {
         fullName: value,
     };
 }
+/** The service validates the shared full contract. Check every additional
+ * field used by this published CLI before displaying or accepting a clean run. */
+function parseHostedSavedChecks(value, runId, headSha) {
+    const saved = requireRecord(value, 'Hosted saved checks');
+    if (saved.version !== 'dv-fleet-saved-check-result-v1'
+        || !Array.isArray(saved.descriptors) || !Array.isArray(saved.outcomes)
+        || !Array.isArray(saved.unresolvedFindings) || !Array.isArray(saved.conflicts)) {
+        throw new Error('Hosted saved checks have an invalid version or records.');
+    }
+    const completeness = requireRecord(saved.completeness, 'Hosted saved check completeness');
+    requireString(completeness, 'status', /^(complete|incomplete)$/);
+    if (completeness.status === 'incomplete' && (!Array.isArray(completeness.reasons) || completeness.reasons.length === 0)) {
+        throw new Error('Hosted saved check history has no explanation for missing evidence.');
+    }
+    const ref = (record) => {
+        requireString(record, 'checkId', /^[0-9a-f]{64}$/);
+        requireString(record, 'planRevisionId', /^[0-9a-f]{64}$/);
+        return `${record.checkId}:${record.planRevisionId}`;
+    };
+    const descriptors = new Map();
+    for (const value of saved.descriptors) {
+        const descriptor = requireRecord(value, 'Hosted saved check descriptor');
+        const key = ref(descriptor);
+        if (descriptor.version !== 'dv-fleet-saved-check-v1' || descriptors.has(key)) {
+            throw new Error('Hosted saved check descriptor identity is invalid or duplicated.');
+        }
+        requireString(descriptor, 'captureStatus', /^(captured|unavailable)$/);
+        descriptors.set(key, descriptor);
+    }
+    const outcomes = new Map();
+    for (const value of saved.outcomes) {
+        const outcome = requireRecord(value, 'Hosted saved check outcome');
+        const key = ref(outcome);
+        requireString(outcome, 'status', /^(passed|reproduced|blocked|inconclusive)$/);
+        if (outcome.version !== 'dv-fleet-saved-check-outcome-v1'
+            || (!descriptors.has(key) && completeness.status !== 'incomplete') || outcomes.has(key)
+            || outcome.publicRunId !== runId || outcome.headSha !== headSha
+            || (outcome.currentCaseId !== null && typeof outcome.currentCaseId !== 'string')
+            || (outcome.blockedCode !== null && typeof outcome.blockedCode !== 'string')) {
+            throw new Error('Hosted saved check outcome does not match its current run or original check.');
+        }
+        if ((outcome.status === 'blocked') !== (outcome.blockedCode !== null)
+            || (outcome.status === 'passed' && (descriptors.get(key)?.captureStatus !== 'captured'
+                || outcome.currentCaseId === null || !outcome.receipt || completeness.status !== 'complete'))) {
+            throw new Error('Hosted saved check outcome claims a pass without original execution evidence.');
+        }
+        outcomes.set(key, outcome);
+    }
+    const findings = new Set();
+    for (const value of saved.unresolvedFindings) {
+        const finding = requireRecord(value, 'Hosted unresolved finding');
+        const key = ref(finding);
+        requireString(finding, 'findingId');
+        const source = requireRecord(finding.firstObserved, 'Hosted original finding evidence');
+        requireString(source, 'publicRunId', RUN_ID);
+        requireString(source, 'caseId');
+        requireString(source, 'headSha', COMMIT_SHA);
+        if (finding.version !== 'dv-fleet-unresolved-finding-v1'
+            || (!descriptors.has(key) && completeness.status !== 'incomplete')
+            || findings.has(finding.findingId) || !Array.isArray(source.evidence) || source.evidence.length === 0
+            || outcomes.get(key)?.status === 'passed') {
+            throw new Error('Hosted unresolved finding has invalid original evidence or check identity.');
+        }
+        findings.add(finding.findingId);
+        if (finding.lastOutcome !== null) {
+            const last = requireRecord(finding.lastOutcome, 'Hosted unresolved finding outcome');
+            if (ref(last) !== key || last.status === 'passed')
+                throw new Error('Hosted unresolved finding lost its exact original check.');
+            requireString(last, 'status', /^(reproduced|blocked|inconclusive)$/);
+            if (last.blockedCode !== null)
+                requireString(last, 'blockedCode');
+        }
+    }
+    for (const value of saved.conflicts) {
+        const conflict = requireRecord(value, 'Hosted saved check conflict');
+        requireString(conflict, 'checkId', /^[0-9a-f]{64}$/);
+        if (!Array.isArray(conflict.planRevisionIds) || conflict.planRevisionIds.length < 2
+            || conflict.planRevisionIds.some(id => typeof id !== 'string' || !/^[0-9a-f]{64}$/.test(id))) {
+            throw new Error('Hosted saved check conflict is invalid.');
+        }
+    }
+    return saved;
+}
+function savedCheckDisplay(value) {
+    return String(value).replace(/[\u0000-\u001f\u007f-\u009f]/g, '');
+}
 function requireCommit(value, flag) {
     if (typeof value !== 'string' || !COMMIT_SHA.test(value)) {
         throw new Error(`${flag} must be an exact 40-character lowercase commit SHA.`);
@@ -499,6 +588,26 @@ function printHostedState(operation, state, options) {
             const finding = requireRecord(value, 'Hosted fleet finding');
             console.log(`  ${chalk.dim('Finding:')} ${finding.findingId} / ${finding.caseId}: ${finding.judgment}`);
         }
+        if (result.savedChecks !== undefined) {
+            const saved = requireRecord(result.savedChecks, 'Hosted saved checks');
+            const completeness = requireRecord(saved.completeness, 'Hosted saved check completeness');
+            const unresolved = saved.unresolvedFindings;
+            console.log(`  ${chalk.dim('Saved checks:')} ${completeness.status}; ${saved.conflicts.length} conflicts; ${unresolved.length} unresolved bugs`);
+            for (const value of unresolved) {
+                const finding = requireRecord(value, 'Hosted unresolved finding');
+                const source = requireRecord(finding.firstObserved, 'Hosted original finding evidence');
+                const last = finding.lastOutcome === null ? null : requireRecord(finding.lastOutcome, 'Hosted unresolved finding outcome');
+                console.log(`  ${chalk.yellow('Unresolved:')} ${savedCheckDisplay(finding.findingId)} / ${savedCheckDisplay(source.caseId)}`);
+                console.log(`    First reproduced at ${String(source.headSha).slice(0, 12)}; latest check: ${savedCheckDisplay(last?.status ?? 'not executed')}${last?.blockedCode ? ` (${savedCheckDisplay(last.blockedCode)})` : ''}`);
+            }
+            if (unresolved.length)
+                console.log('  Earlier bug evidence remains open until the exact saved check passes.');
+            if (completeness.status === 'incomplete')
+                console.log('  Saved check history is incomplete; this run cannot confirm earlier bugs are fixed.');
+        }
+        else {
+            console.log(`  ${chalk.dim('Saved checks:')} unavailable for this run`);
+        }
     }
     if (state.error)
         console.log(`  ${chalk.dim('Error:')} ${state.error}`);
@@ -516,6 +625,16 @@ function markNonSuccess(state, timedOut = false) {
             process.exitCode = 2;
             return;
         }
+        if (result.savedChecks !== undefined) {
+            const saved = requireRecord(result.savedChecks, 'Hosted saved checks');
+            const completeness = requireRecord(saved.completeness, 'Hosted saved check completeness');
+            if (completeness.status !== 'complete' || saved.conflicts.length > 0) {
+                process.exitCode = 2;
+                return;
+            }
+            if (saved.unresolvedFindings.length > 0)
+                process.exitCode = 1;
+        }
         if (result.findings.some(value => requireRecord(value, 'Hosted fleet finding').judgment === 'regression')) {
             process.exitCode = 1;
         }

package/dist/index.js

@@ -202,6 +202,7 @@ For launch specimens, run the local control plane from the Haystack repository:
 
 Examples:
   haystack verify --repo owner/repo --base main --head feature --json
+  haystack verify history owner/repo --limit 20
   haystack verify hosted start owner/repo --base <sha> --head <sha> --intent-file <path>
   haystack verify posthog-js-478         # start a run, then:
   haystack verify reproducibility posthog-js-478 --runs 3
@@ -220,6 +221,26 @@ Examples:
 `)
     .action((specimen, options) => runPublicCommand(() => verifyCommand(specimen, options), options.json));
 const verifyRunArg = 'Run id, chapter id (newest run of that chapter), or "latest" (default)';
+verify
+    .command('history')
+    .description('Read your recent finished hosted verification runs without starting a run')
+    .argument('<repository>', 'Exact GitHub owner/repository name')
+    .option('--limit <runs>', 'Number of recent finished runs to show, from 1 to 100 (default 20)')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .option('--json', 'Versioned history with execution health and separate bug counts')
+    .addHelpText('after', `
+History covers your hosted fleet runs for this repository. Reliability counts
+only these returned runs; it does not measure whether the code is bug-free.
+
+Examples:
+  haystack verify history owner/repo
+  haystack verify history owner/repo --limit 50 --account my-login --json
+`)
+    .action(async (repository, _options, cmd) => {
+    const options = { ...cmd.optsWithGlobals(), ...cmd.opts() };
+    const { verifyHistoryCommand } = await import('./commands/verify-history.js');
+    return runPublicCommand(() => verifyHistoryCommand(repository, options), options.json);
+});
 verify
     .command('precompute')
     .description('Precompute reusable verification inputs for the current working tree')
@@ -901,6 +922,8 @@ program
     // keeps retired auto-fix/verification wording out of the CLI surface).
     .description('Run a blind design-by-execution review of a PR')
     .option('--json', 'Machine-readable output')
+    .option('--history', 'Show recent execution reliability for this repository without starting a run')
+    .option('--limit <attempts>', 'Maximum recorded terminal attempts to show with --history (1–100, default 20)')
     .option('--no-wait', 'Return after the run is admitted instead of waiting for its verdict')
     .option('--run <run-id>', 'Resume and wait for an existing exact run id')
     .option('--poll-interval <seconds>', 'Status polling interval', '3')
@@ -921,6 +944,11 @@ outside the registered intent.
 The command waits for a behavioral verdict by default. Use --no-wait to
 return the run id immediately, or --run <run-id> to resume waiting.
 
+Read recent execution reliability across this repository's PRs:
+  haystack design-verify owner/repo#123 --history --limit 20
+History covers recorded terminal attempts, including partial or failed runs;
+it does not measure bug-detection accuracy or whether changes are bug-free.
+
 After a completed run, inspect or replay one retained case universe without
 receiving provider credentials:
   haystack design-verify owner/repo#123 --run RUN --case case-00001 --universe before --replay

package/dist/types/verify-history.d.ts

@@ -0,0 +1,38 @@
+/** Read-only history from the active hosted verifier, scoped to the caller's
+ * stable GitHub user and repository IDs. Counts describe the returned window,
+ * never bug correctness. Missing results remain unknown. */
+export type VerifyHistoryHealth = 'healthy' | 'degraded' | 'infrastructure-error' | 'not-executed' | 'unknown';
+export interface VerifyHistoryRun {
+    runId: string;
+    baseCommit: string;
+    headCommit: string;
+    createdAt: string;
+    completedAt: string;
+    status: 'complete' | 'errored';
+    lifecycle: 'complete' | 'failed' | 'cancelled' | 'budget-stopped' | 'account-action' | null;
+    health: VerifyHistoryHealth;
+    regressionCount: number | null;
+    executedCaseCount: number | null;
+    degradationCodes: string[];
+    supersededBy: string | null;
+}
+export interface VerifyHistoryReport {
+    version: 'dv-verify-history-v1';
+    provider: 'haystack';
+    scope: 'user';
+    repository: {
+        owner: string;
+        name: string;
+        repositoryId: string;
+    };
+    limit: number;
+    hasMore: boolean;
+    runs: VerifyHistoryRun[];
+    summary: {
+        total: number;
+        counts: Record<VerifyHistoryHealth, number>;
+        /** Healthy/degraded runs with executedCaseCount > 0, divided by total;
+         * null for an empty window. */
+        usableRate: number | null;
+    };
+}

package/dist/types/verify-history.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/design-verifier-api.d.ts

@@ -7,6 +7,7 @@
  * the server-side shared secret. This client just POSTs and interprets the
  * response.
  */
+import { type DesignVerifierHistoryReport } from './design-verifier-history.js';
 export type DesignVerifierTriggerResult = {
     status: 'started' | 'queued' | 'duplicate';
     runId: string;
@@ -184,6 +185,13 @@ export declare function waitForDesignVerifierUniverseAction(owner: string, repo:
 }>;
 export declare function triggerDesignVerifier(owner: string, repo: string, prNumber: number, token: string): Promise<DesignVerifierTriggerResult>;
 export declare function getDesignVerifierStatus(owner: string, repo: string, prNumber: number, runId: string, token: string): Promise<DesignVerifierStatusFetchResult>;
+export declare function getDesignVerifierHistory(owner: string, repo: string, token: string, limit?: number): Promise<{
+    status: 'ok';
+    history: DesignVerifierHistoryReport;
+} | {
+    status: 'denied' | 'unavailable' | 'error';
+    message: string;
+}>;
 export declare function waitForDesignVerifier(owner: string, repo: string, prNumber: number, runId: string, token: string, options?: {
     intervalMs?: number;
     timeoutMs?: number;

package/dist/utils/design-verifier-api.js

@@ -8,6 +8,7 @@
  * response.
  */
 import { haystackApiUrl } from './haystack-api.js';
+import { isDesignVerifierHistoryReport } from './design-verifier-history.js';
 function isDuration(value) {
     return value === null || (typeof value === 'number' && Number.isFinite(value) && value >= 0);
 }
@@ -239,6 +240,28 @@ export async function getDesignVerifierStatus(owner, repo, prNumber, runId, toke
         return { status: 'unavailable', message };
     return { status: 'error', message };
 }
+export async function getDesignVerifierHistory(owner, repo, token, limit = 20) {
+    const url = haystackApiUrl(`/api/design-verifier/history/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}?limit=${limit}`);
+    try {
+        const response = await fetch(url, { method: 'GET', headers: apiHeaders(token) });
+        const data = await response.json();
+        if (response.ok) {
+            if (!isDesignVerifierHistoryReport(data, { owner, repo, limit })) {
+                return { status: 'error', message: 'History endpoint returned an invalid or mismatched result.' };
+            }
+            return { status: 'ok', history: data };
+        }
+        const message = data?.message || data?.error || `HTTP ${response.status}`;
+        if (response.status === 401 || response.status === 403)
+            return { status: 'denied', message };
+        if ([404, 502, 503].includes(response.status))
+            return { status: 'unavailable', message };
+        return { status: 'error', message };
+    }
+    catch (error) {
+        return { status: 'error', message: error.message };
+    }
+}
 export async function waitForDesignVerifier(owner, repo, prNumber, runId, token, options = {}) {
     const intervalMs = options.intervalMs ?? 3000;
     const timeoutMs = options.timeoutMs ?? 2 * 60 * 60 * 1000;

package/dist/utils/design-verifier-history.d.ts

@@ -0,0 +1,46 @@
+/** FIXED CONTRACT: historical execution health, never a score for bug-detection accuracy. */
+export type DesignVerifierHistoryOutcome = 'healthy' | 'degraded' | 'invalid' | 'failed' | 'unknown';
+export interface DesignVerifierHistoryRun {
+    runId: string;
+    pr: number;
+    baseSha: string | null;
+    headSha: string | null;
+    createdAt: string;
+    finishedAt: string | null;
+    status: string;
+    outcome: DesignVerifierHistoryOutcome;
+    admitted: number | null;
+    losses: Array<{
+        code: string;
+        owner: string;
+        impact: 'degraded' | 'invalid';
+        count: number;
+    }>;
+}
+export interface DesignVerifierHistoryReport {
+    version: 'dv-cli-history-v1';
+    owner: string;
+    repo: string;
+    retentionDays: number;
+    limit: number;
+    runs: DesignVerifierHistoryRun[];
+    summary: {
+        total: number;
+        healthy: number;
+        degraded: number;
+        invalid: number;
+        failed: number;
+        unknown: number;
+        usableRate: number | null;
+        topBlockers: Array<{
+            code: string;
+            affectedRuns: number;
+        }>;
+    };
+}
+export declare function isDesignVerifierHistoryReport(value: unknown, expected: {
+    owner: string;
+    repo: string;
+    limit: number;
+}): value is DesignVerifierHistoryReport;
+export declare function formatDesignVerifierHistory(report: DesignVerifierHistoryReport): string;

package/dist/utils/design-verifier-history.js

@@ -0,0 +1,79 @@
+const outcomes = ['healthy', 'degraded', 'invalid', 'failed', 'unknown'];
+export function isDesignVerifierHistoryReport(value, expected) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const report = value;
+    if (report.version !== 'dv-cli-history-v1' || report.owner !== expected.owner ||
+        report.repo !== expected.repo || report.limit !== expected.limit ||
+        !Number.isSafeInteger(report.retentionDays) || report.retentionDays <= 0 ||
+        !Array.isArray(report.runs) || report.runs.length > report.limit || !report.summary)
+        return false;
+    const seen = new Set();
+    const counts = { healthy: 0, degraded: 0, invalid: 0, failed: 0, unknown: 0 };
+    const blockers = new Map();
+    for (const run of report.runs) {
+        if (!run || !Number.isSafeInteger(run.pr) || run.pr < 1 || typeof run.runId !== 'string')
+            return false;
+        const prefix = `${expected.owner}--${expected.repo}--${run.pr}--`;
+        if (!run.runId.startsWith(prefix) ||
+            !/^[0-9a-f]{12}(?:--attempt-[1-9]\d*)?$/.test(run.runId.slice(prefix.length)) ||
+            seen.has(run.runId) || !outcomes.includes(run.outcome) ||
+            !['succeeded', 'failed', 'failed-stale'].includes(run.status) ||
+            (run.outcome === 'failed') !== (run.status !== 'succeeded') ||
+            typeof run.createdAt !== 'string' || !Number.isFinite(Date.parse(run.createdAt)) ||
+            (run.finishedAt !== null && (typeof run.finishedAt !== 'string' || !Number.isFinite(Date.parse(run.finishedAt)))) ||
+            (run.baseSha !== null && typeof run.baseSha !== 'string') ||
+            (run.headSha !== null && typeof run.headSha !== 'string') ||
+            (run.admitted !== null && (!Number.isSafeInteger(run.admitted) || run.admitted < 0)) ||
+            !Array.isArray(run.losses) || run.losses.some(loss => !loss || typeof loss.code !== 'string' || !loss.code || typeof loss.owner !== 'string' ||
+            !loss.owner || !['degraded', 'invalid'].includes(loss.impact) ||
+            !Number.isSafeInteger(loss.count) || loss.count < 1))
+            return false;
+        if (['healthy', 'degraded'].includes(run.outcome) && (run.admitted === null || run.admitted === 0))
+            return false;
+        seen.add(run.runId);
+        counts[run.outcome]++;
+        for (const code of new Set(run.losses.map(loss => loss.code))) {
+            blockers.set(code, (blockers.get(code) || 0) + 1);
+        }
+    }
+    const summary = report.summary;
+    const usableRate = report.runs.length ? (counts.healthy + counts.degraded) / report.runs.length : null;
+    if (summary.total !== report.runs.length || summary.usableRate !== usableRate ||
+        outcomes.some(outcome => summary[outcome] !== counts[outcome]) ||
+        !Array.isArray(summary.topBlockers) || summary.topBlockers.length !== blockers.size)
+        return false;
+    const seenBlockers = new Set();
+    return summary.topBlockers.every(blocker => {
+        if (!blocker || seenBlockers.has(blocker.code) || blockers.get(blocker.code) !== blocker.affectedRuns)
+            return false;
+        seenBlockers.add(blocker.code);
+        return true;
+    });
+}
+function terminalSafe(value) {
+    return Array.from(value).filter(character => {
+        const point = character.codePointAt(0);
+        return point >= 32 && !(point >= 127 && point <= 159);
+    }).join('');
+}
+export function formatDesignVerifierHistory(report) {
+    const { summary } = report;
+    const lines = [`Execution history for ${terminalSafe(report.owner)}/${terminalSafe(report.repo)}`,
+        `Latest ${summary.total} recorded terminal attempts within ${report.retentionDays} days (limit ${report.limit}).`];
+    if (summary.total === 0) {
+        lines.push('No recorded attempts in this window. History starts when recording is deployed.');
+        return lines.join('\n');
+    }
+    lines.push(`Usable evidence: ${Math.round(summary.usableRate * 100)}% of attempts (${summary.healthy + summary.degraded}/${summary.total}).`, `Fully healthy: ${summary.healthy}; partially degraded: ${summary.degraded}; invalid: ${summary.invalid}; failed: ${summary.failed}; unknown: ${summary.unknown}.`, 'Usable includes partial evidence from degraded attempts. This measures execution reliability, not bug-detection accuracy.', '');
+    for (const run of report.runs) {
+        lines.push(`${run.finishedAt || run.createdAt}  PR #${run.pr}  ${run.outcome}  ${run.admitted ?? '?'} admitted cases`, `  ${run.runId}`);
+    }
+    if (summary.topBlockers.length) {
+        lines.push('', 'Most frequent blockers (attempts affected):');
+        for (const blocker of summary.topBlockers.slice(0, 5)) {
+            lines.push(`  ${terminalSafe(blocker.code)}: ${blocker.affectedRuns}`);
+        }
+    }
+    return lines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.15.30",
+  "version": "0.15.31",
   "description": "Set up Haystack for your project — automated PR review, triage, and merge queue",
   "type": "module",
   "bin": {