@haystackeditor/cli 0.15.20 → 0.15.21

package/README.md

@@ -65,6 +65,20 @@ haystack triage <ref> --json    # poll findings later / after --no-wait
 `traces_list`, `traces_get`, `dismiss`, `mark_reviewed`, `undismiss`,
 `request_review`, `trigger_review`, and `schema`.
 
+**`haystack verify mcp`** runs the cloud-verifier MCP server. Retained
+application state is available through `verify_reopen`, `verify_refork`, and
+`verify_cleanup`. Agents select state by an exact Archil fork ID or a stable
+run/test/side coordinate; refork returns a durable child ID that can be
+reopened or nested again without receiving provider credentials. The matching
+CLI flow is:
+
+```bash
+haystack verify reopen latest 3
+# inspect or mutate the returned sandbox
+haystack verify refork latest 3 attempt:fix-2
+haystack verify reopen archil:<disk-id>:branch:<returned-child>
+```
+
 **`haystack setup --json`** speaks NDJSON: events (`question`, `permission`,
 `progress`, `result`) on stdout, replies on stdin keyed by
 `requestID`/`permissionID`. `haystack schema setup` documents the full

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

@@ -0,0 +1,424 @@
+export declare const DEFAULT_CONTROL_PLANE = "http://127.0.0.1:3000";
+export declare const TERMINAL_RUN_STATUSES: Set<string>;
+export interface UniverseEvidence {
+    evidenceId: string;
+    kind: string;
+    label: string;
+    summary: string;
+    value?: unknown;
+    artifactUrl?: string;
+    step?: {
+        ordinal: number;
+        name: string;
+    };
+    details?: Record<string, unknown>;
+    capturedAt?: string;
+}
+export interface UniverseRef {
+    universeId: string;
+    side: 'base' | 'head';
+    status: string;
+    snapshotId?: string;
+    forkId?: string;
+    executionId?: string;
+    stateProvider?: 'e2b-snapshot' | 'archil';
+    stateLayers?: Array<{
+        layerId: string;
+        kind: 'compute-filesystem' | 'application-filesystem';
+        provider: 'e2b-snapshot' | 'archil';
+        immutableBaseId: string;
+        mutableOverlayId?: string;
+        mountPath?: string;
+        consistencyPoint?: string;
+    }>;
+    sandboxId?: string;
+    browserUrl?: string;
+    evidence: UniverseEvidence[];
+    startedAt?: string;
+    completedAt?: string;
+    expiresAt?: string;
+    stateExpiresAt?: string;
+}
+export interface RiskCell {
+    riskCellId: string;
+    ordinal: number;
+    title: string;
+    rationale?: string;
+    observableConsequence?: string;
+    activationConditions?: string[];
+    causalPath?: string[];
+    status: string;
+    severity?: string;
+    confidence?: number;
+    durationMs?: number;
+    base: UniverseRef;
+    head: UniverseRef;
+    agentJudgment?: {
+        verdict: string;
+        explanation: string;
+        intentEvidence?: string;
+    };
+    infrastructureError?: {
+        reason: string;
+        message: string;
+    };
+}
+export interface BisectProbe {
+    commit: string;
+    shortSha: string;
+    subject: string;
+    position: number;
+    status: string;
+    wave?: number;
+    sandboxId?: string;
+    durationMs?: number;
+    error?: string;
+}
+export interface BisectResult {
+    status: string;
+    signal: string;
+    predicate: string;
+    totalCandidates: number;
+    probes: BisectProbe[];
+    culpritSha?: string;
+    culpritSubject?: string;
+    parentSha?: string;
+    incidentProbe?: BisectProbe & {
+        ref?: string;
+        label?: string;
+    };
+}
+export interface VerificationChapter {
+    chapterId: string;
+    executionMode?: 'risk_cells' | 'bisect';
+    analysisMode?: string;
+    label: string;
+    repository: string;
+    pullRequest: string;
+    pullRequestUrl?: string;
+    status: string;
+    riskCells: RiskCell[];
+    bisect?: BisectResult;
+}
+export interface VerificationRunEvent {
+    eventId: string;
+    at: string;
+    phase: string;
+    message: string;
+    chapterId?: string;
+}
+export interface VerificationRun {
+    schemaVersion: string;
+    runId: string;
+    status: string;
+    command: string;
+    createdAt: string;
+    updatedAt: string;
+    chapters: VerificationChapter[];
+    events: VerificationRunEvent[];
+    summary: {
+        total: number;
+        completed: number;
+        passed: number;
+        failed: number;
+        infraErrors: number;
+        inconclusive?: number;
+    };
+}
+export declare function resolveServer(explicit?: string): string;
+export declare function setVerifyToken(token: string | undefined): void;
+export declare function verifyAuthHeaders(): Record<string, string>;
+export declare class VerifyUnauthorizedError extends Error {
+    constructor(server: string);
+}
+/**
+ * Find the repository that holds .haystack/verify — explicit flag, then
+ * HAYSTACK_VERIFY_REPO, then walking up from cwd. Null when nothing matches;
+ * server-backed commands still work without it.
+ */
+export declare function discoverVerifyRoot(explicit?: string): string | null;
+export declare function runsRoot(repoRoot: string): string;
+export declare function runDir(repoRoot: string, runId: string): string;
+export declare function listRunDirs(repoRoot: string): Array<{
+    runId: string;
+    changedAt: number;
+}>;
+/** Same alias rules as the control plane: run id verbatim, `latest`, or a chapter id. */
+export declare function resolveRunIdOnDisk(repoRoot: string, requested: string): string;
+export declare function loadRunFromDisk(repoRoot: string, runId: string): VerificationRun | null;
+export type ServerFetch = {
+    outcome: 'ok';
+    run: VerificationRun;
+} | {
+    outcome: 'not_found';
+} | {
+    outcome: 'unauthorized';
+} | {
+    outcome: 'unreachable';
+    reason: string;
+};
+export declare function fetchRunFromServer(server: string, idOrAlias: string): Promise<ServerFetch>;
+export interface LoadedRun {
+    run: VerificationRun;
+    source: 'server' | 'disk';
+    /**
+     * True when the run is non-terminal but nothing can still be driving it —
+     * a disk read with no reachable control plane. (The server performs the same
+     * marking itself by rewriting orphaned runs to `failed`.)
+     */
+    stale: boolean;
+}
+export declare function loadRunAuto(options: {
+    server: string;
+    repoRoot: string | null;
+    selector: string;
+}): Promise<LoadedRun>;
+export declare function isTerminal(run: VerificationRun): boolean;
+export interface RunListRow {
+    run_id: string;
+    chapters: string[];
+    status: string;
+    age: string | null;
+    updated_at: string;
+    tests: number;
+    passed: number;
+    failed: number;
+    could_not_run: number;
+    culprit_sha: string | null;
+}
+export interface RunListResult {
+    rows: RunListRow[];
+    source: 'server' | 'disk';
+    total: number;
+}
+/**
+ * List runs, newest first. Prefers the control plane's GET /runs (present on
+ * servers with the operator API; required for a remote control plane) and
+ * falls back to enumerating the runs directory.
+ */
+export declare function listRunRows(options: {
+    server: string;
+    repoRoot: string | null;
+    limit: number;
+}): Promise<RunListResult>;
+export declare function riskCellIdFor(chapterId: string, cellKey: string): string;
+/**
+ * Recover the planner's cellKey from artifact filenames (`<cellKey>-<side>-…`).
+ * run.json stores only the hashed riskCellId; the key is friendlier to type.
+ */
+/**
+ * Basename of an evidence artifactUrl. The executor URL-encodes the whole
+ * relative path (`<chapter>%2Fartifacts%2F<file>`), so decode before taking
+ * the last path segment.
+ */
+export declare function artifactFileOf(artifactUrl: string): string;
+/** Relative artifact path under the run's chapters/ dir, from an evidence URL. */
+export declare function artifactRelOf(artifactUrl: string): string | null;
+export declare function cellKeyOf(cell: RiskCell): string | null;
+export declare function formatDurationMs(ms: number | undefined): string | null;
+export declare function formatAge(iso: string | undefined): string | null;
+export declare function formatUntil(iso: string | null | undefined): string | null;
+export interface TestSummary {
+    ordinal: number;
+    cell_id: string;
+    cell_key: string | null;
+    title: string;
+    /** `passed` | `failed` | a live phase | `infra_error` (could not run — our defect, not a verdict). */
+    status: string;
+    severity: string | null;
+    verdict: string | null;
+    duration: string | null;
+    live_url: string | null;
+    live_expires_at: string | null;
+    live_expires: string | null;
+}
+export interface RunFinding {
+    chapter_id: string;
+    ordinal: number;
+    title: string;
+    severity: string | null;
+    verdict: string | null;
+    /** First paragraph of the judge's explanation; `verify show` / verify_cell has the whole thing. */
+    summary: string | null;
+    /** Failing oracle readings as "metric: base → head". */
+    changed_readings: string[];
+    live_url: string | null;
+}
+export interface RunSummary {
+    schema_version: '1.0.0';
+    run_id: string;
+    status: string;
+    stale: boolean;
+    source: 'server' | 'disk';
+    created_at: string;
+    updated_at: string;
+    age: string | null;
+    counts: {
+        total: number;
+        completed: number;
+        passed: number;
+        failed: number;
+        could_not_run: number;
+    };
+    /** One entry per failing test (and per isolated bisect culprit) — the "what broke" digest. */
+    findings: RunFinding[];
+    chapters: Array<{
+        chapter_id: string;
+        execution_mode: 'risk_cells' | 'bisect';
+        analysis_mode: string | null;
+        label: string;
+        repository: string;
+        pull_request: string;
+        status: string;
+        tests: TestSummary[];
+        bisect: null | {
+            status: string;
+            signal: string;
+            total_candidates: number;
+            probes_total: number;
+            probes_by_status: Record<string, number>;
+            culprit_sha: string | null;
+            culprit_subject: string | null;
+            parent_sha: string | null;
+        };
+    }>;
+    live_environments: Array<{
+        chapter_id: string;
+        ordinal: number;
+        title: string;
+        url: string;
+        expires_at: string | null;
+        expires: string | null;
+    }>;
+    /** Anything the verifier could not run or measure — reported as our failure, never as a finding. */
+    problems: string[];
+    last_event: {
+        at: string;
+        phase: string;
+        message: string;
+    } | null;
+    results_url: string;
+}
+/** Frozen-oracle readings for one cell, extracted from its assertion evidence. */
+export declare function oracleReadingsOf(cell: RiskCell): OracleReading[];
+export declare function summarizeRun(loaded: LoadedRun, server: string): RunSummary;
+/**
+ * Exit-code policy shared by `verify watch` and callers of the MCP wait tool:
+ * 0 — everything that ran passed (a found bisect culprit counts as success);
+ * 1 — at least one test failed;
+ * 2 — the run itself broke, went stale, or some test could not run.
+ */
+export declare function exitCodeFor(summary: RunSummary): number;
+export interface CellMatch {
+    chapter: VerificationChapter;
+    cell: RiskCell;
+}
+/** Match a test by ordinal, riskCellId, planner cellKey, or title substring. */
+export declare function findCell(run: VerificationRun, selector: string): CellMatch;
+/**
+ * Resolve a cell for an operator action without using its free-text title.
+ * Ordinals are scoped by the exact run, while riskCellId and planner cellKey
+ * are stable structured identifiers carried by the run.
+ */
+export declare function findCellByStableSelector(run: VerificationRun, selector: string): CellMatch;
+export interface OracleReading {
+    metric: string;
+    comparison: string;
+    base: unknown;
+    head: unknown;
+    changed: boolean;
+    result: 'pass' | 'fail' | 'unmeasurable';
+}
+export interface TimelineEntry {
+    sequence: number | null;
+    offset_ms: number | null;
+    method: string | null;
+    path: string;
+    status: string;
+    channel: string | null;
+    event_name: string | null;
+    step: string | null;
+}
+export interface UniverseDetail {
+    universe_id: string;
+    status: string;
+    sandbox_id: string | null;
+    state_provider: 'e2b-snapshot' | 'archil' | null;
+    snapshot_id: string | null;
+    fork_id: string | null;
+    execution_id: string | null;
+    state_layers: NonNullable<UniverseRef['stateLayers']>;
+    network: TimelineEntry[];
+    sdk_log: string[];
+    driver_failures: string[];
+    artifacts: Array<{
+        kind: string;
+        label: string;
+        url: string;
+        file: string;
+    }>;
+}
+export interface CellDetail {
+    schema_version: '1.0.0';
+    run_id: string;
+    chapter_id: string;
+    ordinal: number;
+    cell_id: string;
+    cell_key: string | null;
+    title: string;
+    status: string;
+    severity: string | null;
+    duration: string | null;
+    finding: string | null;
+    verdict: string | null;
+    explanation: string | null;
+    intent_evidence: string | null;
+    infrastructure_error: {
+        reason: string;
+        message: string;
+    } | null;
+    rationale: string | null;
+    observable_consequence: string | null;
+    oracle_readings: OracleReading[];
+    readings_changed: OracleReading[];
+    live_environment: {
+        url: string;
+        expires_at: string | null;
+        expires: string | null;
+    } | null;
+    base: UniverseDetail;
+    head: UniverseDetail;
+}
+export declare function cellDetail(run: VerificationRun, match: CellMatch, opts?: {
+    timeline?: boolean;
+}): CellDetail;
+export interface WatchCallbacks {
+    onEvent?: (event: VerificationRunEvent) => void;
+    onCellChange?: (chapterId: string, cell: RiskCell, previousStatus: string) => void;
+    onResolved?: (runId: string) => void;
+}
+export interface WatchResult {
+    loaded: LoadedRun;
+    timedOut: boolean;
+}
+/**
+ * Poll until the run reaches a terminal state. The terminal predicate is the
+ * run status alone — never a cell's: a cell legitimately sits in
+ * `provisioning` for minutes while sandbox creation retries.
+ *
+ * A stale marking (from the control plane, or from a disk read with no
+ * reachable server) is treated with suspicion rather than as terminal: a Vite
+ * restart re-creates the plugin's in-memory run registry while the old
+ * orchestrator can keep running in the same process, so "no orchestrator is
+ * driving this run" can be false. As long as run.json keeps advancing, the run
+ * is alive regardless of what the registry thinks; staleness is only accepted
+ * after a no-progress grace period.
+ */
+export declare function waitForTerminal(options: {
+    server: string;
+    repoRoot: string | null;
+    selector: string;
+    timeoutMs?: number;
+    intervalMs?: number;
+    callbacks?: WatchCallbacks;
+}): Promise<WatchResult>;