@haystackeditor/cli 0.15.21 → 0.15.23

package/README.md

@@ -33,8 +33,8 @@ Most consumers of this CLI are coding agents. These invariants hold everywhere:
 - **Every JSON payload is versioned and schema'd.** Payloads carry
   `schema_version`; print the contract with `haystack schema <name>`
   (`haystack schema` lists all: `triage`, `pr`, `pr-status`, `inbox`, `ask`,
-  `traces`, `submit`, `action`, `error`, `setup`). Schemas are JSON-Schema
-  2020-12 and CI-guarded against drift.
+  `traces`, `submit`, `action`, `cloud-verifier`, `error`, `setup`). Schemas
+  are JSON-Schema 2020-12 and CI-guarded against drift.
 - **One state vocabulary.** All state tokens are snake_case across every
   command: verdicts are `good_to_merge` / `needs_review` / `needs_input`;
   feed buckets are `analyzing`, `good_to_merge`, `issues`, `needs_assignment`,
@@ -79,6 +79,43 @@ haystack verify refork latest 3 attempt:fix-2
 haystack verify reopen archil:<disk-id>:branch:<returned-child>
 ```
 
+**`haystack verify hosted`** is the authenticated production entry point for
+exact GitHub commit pairs. It uses the repository-default saved account,
+submits an idempotent run, and waits up to 35 minutes by default:
+
+```bash
+haystack verify hosted start owner/repo \
+  --base <40-character-commit-sha> \
+  --head <40-character-commit-sha> \
+  --json
+```
+
+Use `--no-wait` to return as soon as the workflow is queued. The result includes
+an account-bound `next_command`; use it verbatim on machines with multiple
+saved GitHub accounts. Repeating the same repository/base/head tuple reuses the
+same production run by default. Pass a new explicit `--idempotency-key` only
+when a fresh execution is intentional. A bounded wait that expires still emits
+the `cloud-verifier` schema with `timed_out: true`, the last observed status,
+and `next_command`, then exits 2. Read or resume a known run with:
+
+```bash
+haystack verify hosted status cv_<48-lowercase-hex-characters> \
+  --account <login> \
+  --wait \
+  --json
+```
+
+Agents can use the same production lifecycle over stdio MCP:
+
+```bash
+haystack verify hosted mcp --account <login>
+```
+
+The hosted server exposes only `verify_start`, `verify_status`, and
+`verify_wait`. Tool results use the same `cloud-verifier` schema as the CLI;
+credentials, repository source, provider metadata, and sandbox mutation are
+not exposed.
+
 **`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

@@ -41,15 +41,31 @@ export interface UniverseRef {
 }
 export interface RiskCell {
     riskCellId: string;
+    riskSourceId?: string;
     ordinal: number;
     title: string;
     rationale?: string;
     observableConsequence?: string;
     activationConditions?: string[];
     causalPath?: string[];
+    capabilityId?: string;
     status: string;
     severity?: string;
     confidence?: number;
+    sourceEvidence?: Array<{
+        evidenceId: string;
+        file: string;
+        line?: number;
+        excerpt?: string;
+        relationship: string;
+    }>;
+    oracles?: Array<{
+        oracleId: string;
+        kind: string;
+        description?: string;
+        measurement: string;
+        threshold?: string;
+    }>;
     durationMs?: number;
     base: UniverseRef;
     head: UniverseRef;
@@ -114,6 +130,7 @@ export interface VerificationRun {
     command: string;
     createdAt: string;
     updatedAt: string;
+    planSourceRunId?: string;
     chapters: VerificationChapter[];
     events: VerificationRunEvent[];
     summary: {
@@ -139,9 +156,15 @@ export declare class VerifyUnauthorizedError extends Error {
 export declare function discoverVerifyRoot(explicit?: string): string | null;
 export declare function runsRoot(repoRoot: string): string;
 export declare function runDir(repoRoot: string, runId: string): string;
+/**
+ * Read when a run began from the record itself. updatedAt and mtime both move
+ * when cleanup or a migration rewrites old runs and therefore cannot define
+ * "latest".
+ */
+export declare function runStartedAtMs(runJsonPath: string): number | null;
 export declare function listRunDirs(repoRoot: string): Array<{
     runId: string;
-    changedAt: number;
+    startedAt: 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;
@@ -179,6 +202,7 @@ export interface RunListRow {
     chapters: string[];
     status: string;
     age: string | null;
+    created_at?: string;
     updated_at: string;
     tests: number;
     passed: number;
@@ -400,6 +424,7 @@ export interface WatchCallbacks {
 export interface WatchResult {
     loaded: LoadedRun;
     timedOut: boolean;
+    endReason: 'terminal' | 'stale' | 'timeout';
 }
 /**
  * Poll until the run reaches a terminal state. The terminal predicate is the

package/dist/commands/verify-core.js

@@ -72,6 +72,36 @@ export function runsRoot(repoRoot) {
 export function runDir(repoRoot, runId) {
     return path.join(runsRoot(repoRoot), runId);
 }
+function isMissingFileError(error) {
+    return typeof error === 'object'
+        && error !== null
+        && 'code' in error
+        && error.code === 'ENOENT';
+}
+function runRecordReadError(runJsonPath, error) {
+    return new Error(`Could not read verifier run record ${runJsonPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+}
+/**
+ * Read when a run began from the record itself. updatedAt and mtime both move
+ * when cleanup or a migration rewrites old runs and therefore cannot define
+ * "latest".
+ */
+export function runStartedAtMs(runJsonPath) {
+    try {
+        const run = JSON.parse(fs.readFileSync(runJsonPath, 'utf8'));
+        if (typeof run.createdAt === 'string') {
+            const recorded = Date.parse(run.createdAt);
+            if (Number.isFinite(recorded))
+                return recorded;
+        }
+    }
+    catch (error) {
+        if (isMissingFileError(error))
+            return null;
+        throw runRecordReadError(runJsonPath, error);
+    }
+    return null;
+}
 export function listRunDirs(repoRoot) {
     let entries;
     try {
@@ -82,16 +112,12 @@ export function listRunDirs(repoRoot) {
     }
     return entries
         .filter(name => name.startsWith('run-'))
-        .map(name => {
-        try {
-            return { runId: name, changedAt: fs.statSync(path.join(runsRoot(repoRoot), name, 'run.json')).mtimeMs };
-        }
-        catch {
-            return { runId: name, changedAt: 0 };
-        }
-    })
-        .filter(entry => entry.changedAt > 0)
-        .sort((a, b) => b.changedAt - a.changedAt);
+        .map(name => ({
+        runId: name,
+        startedAt: runStartedAtMs(path.join(runsRoot(repoRoot), name, 'run.json')),
+    }))
+        .filter((entry) => (entry.startedAt !== null))
+        .sort((a, b) => b.startedAt - a.startedAt);
 }
 /** Same alias rules as the control plane: run id verbatim, `latest`, or a chapter id. */
 export function resolveRunIdOnDisk(repoRoot, requested) {
@@ -102,11 +128,14 @@ export function resolveRunIdOnDisk(repoRoot, requested) {
     return match?.runId ?? requested;
 }
 export function loadRunFromDisk(repoRoot, runId) {
+    const runJsonPath = path.join(runDir(repoRoot, runId), 'run.json');
     try {
-        return JSON.parse(fs.readFileSync(path.join(runDir(repoRoot, runId), 'run.json'), 'utf8'));
+        return JSON.parse(fs.readFileSync(runJsonPath, 'utf8'));
     }
-    catch {
-        return null;
+    catch (error) {
+        if (isMissingFileError(error))
+            return null;
+        throw runRecordReadError(runJsonPath, error);
     }
 }
 export async function fetchRunFromServer(server, idOrAlias) {
@@ -158,12 +187,13 @@ function rowOfRun(run) {
         run_id: run.runId,
         chapters: run.chapters.map(chapter => chapter.chapterId),
         status: run.status,
-        age: formatAge(run.updatedAt),
+        age: formatAge(run.createdAt),
+        created_at: run.createdAt,
         updated_at: run.updatedAt,
         tests: run.summary.total,
         passed: run.summary.passed,
         failed: run.summary.failed,
-        could_not_run: run.summary.infraErrors,
+        could_not_run: run.summary.infraErrors + (run.summary.inconclusive ?? 0),
         culprit_sha: bisect?.culpritSha ?? null,
     };
 }
@@ -184,7 +214,10 @@ export async function listRunRows(options) {
             const body = (await response.json());
             if (Array.isArray(body.runs)) {
                 // Recompute ages locally so they do not drift with server response caching.
-                const rows = body.runs.map(row => ({ ...row, age: formatAge(row.updated_at) ?? row.age }));
+                const rows = body.runs.map(row => ({
+                    ...row,
+                    age: formatAge(row.created_at || row.updated_at) ?? row.age,
+                }));
                 return { rows, source: 'server', total: body.total ?? rows.length };
             }
         }
@@ -504,7 +537,7 @@ export function summarizeRun(loaded, server) {
         source: loaded.source,
         created_at: run.createdAt,
         updated_at: run.updatedAt,
-        age: formatAge(run.updatedAt),
+        age: formatAge(run.createdAt),
         counts: {
             total: run.summary.total,
             completed: run.summary.completed,
@@ -729,8 +762,9 @@ export async function waitForTerminal(options) {
         }
         first = false;
         const staleMarked = loaded.stale || loaded.run.events.some(event => event.eventId.startsWith('evt-stale-'));
-        if (isTerminal(loaded.run) && !staleMarked)
-            return { loaded, timedOut: false };
+        if (isTerminal(loaded.run) && !staleMarked) {
+            return { loaded, timedOut: false, endReason: 'terminal' };
+        }
         const progressed = loaded.run.updatedAt !== lastUpdatedAt;
         lastUpdatedAt = loaded.run.updatedAt;
         if (staleMarked) {
@@ -739,15 +773,17 @@ export async function waitForTerminal(options) {
             }
             else {
                 noProgressSince = noProgressSince ?? Date.now();
-                if (Date.now() - noProgressSince > staleGraceMs)
-                    return { loaded, timedOut: false };
+                if (Date.now() - noProgressSince > staleGraceMs) {
+                    return { loaded, timedOut: false, endReason: 'stale' };
+                }
             }
         }
         else {
             noProgressSince = null;
         }
-        if (deadline && Date.now() > deadline)
-            return { loaded, timedOut: true };
+        if (deadline && Date.now() > deadline) {
+            return { loaded, timedOut: true, endReason: 'timeout' };
+        }
         await new Promise(resolve => setTimeout(resolve, intervalMs));
     }
 }

package/dist/commands/verify-hosted-mcp.d.ts

@@ -0,0 +1,12 @@
+import { type Tool } from '@modelcontextprotocol/sdk/types.js';
+export declare const HOSTED_VERIFY_TOOLS: Tool[];
+export interface HostedVerifyMcpOptions {
+    account?: string;
+}
+interface HostedToolContext {
+    token: string;
+    account?: string;
+}
+export declare function executeHostedVerifyTool(name: string, input: Record<string, unknown>, context: HostedToolContext): Promise<Record<string, unknown>>;
+export declare function runHostedVerifyMcpServer(options: HostedVerifyMcpOptions): Promise<void>;
+export {};

package/dist/commands/verify-hosted-mcp.js

@@ -0,0 +1,234 @@
+// Production Cloud Verifier MCP server: `haystack verify hosted mcp`.
+//
+// This intentionally exposes only the durable hosted run lifecycle. The local
+// specimen MCP server has artifact and retained-sandbox tools whose data model
+// does not exist in the source-free production result contract.
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { resolveAuthContext } from '../utils/auth.js';
+import { buildHostedJson, getHostedVerification, hostedResumeCommand, parseHostedRepository, startHostedVerification, waitForHostedVerification, } from './verify-hosted.js';
+const TERMINAL_STATUSES = new Set([
+    'complete',
+    'errored',
+    'expired',
+    'terminated',
+]);
+const DEFAULT_TIMEOUT_SECONDS = 30 * 60;
+const MAX_TIMEOUT_SECONDS = 60 * 60;
+const accountInput = {
+    type: 'string',
+    description: 'Saved Haystack account login. Omit to use the server default or active account.',
+};
+const runIdInput = {
+    type: 'string',
+    pattern: '^cv_[0-9a-f]{48}$',
+    description: 'Owned hosted run id.',
+};
+export const HOSTED_VERIFY_TOOLS = [
+    {
+        name: 'verify_start',
+        description: 'Start an authenticated production verification for an exact GitHub commit pair. Returns immediately; call verify_wait next.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                repository: {
+                    type: 'string',
+                    pattern: '^[A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100}$',
+                    description: 'Exact GitHub owner/repository name.',
+                },
+                base_commit: {
+                    type: 'string',
+                    pattern: '^[0-9a-f]{40}$',
+                    description: 'Exact 40-character lowercase base commit SHA.',
+                },
+                head_commit: {
+                    type: 'string',
+                    pattern: '^[0-9a-f]{40}$',
+                    description: 'Exact 40-character lowercase head commit SHA.',
+                },
+                idempotency_key: {
+                    type: 'string',
+                    pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$',
+                    description: 'Optional stable retry key. Omit to derive it from the exact repository and commits.',
+                },
+                account: accountInput,
+            },
+            required: ['repository', 'base_commit', 'head_commit'],
+        },
+    },
+    {
+        name: 'verify_status',
+        description: 'Read the current source-free production receipt for an owned hosted run.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                run_id: runIdInput,
+                account: accountInput,
+            },
+            required: ['run_id'],
+        },
+    },
+    {
+        name: 'verify_wait',
+        description: 'Wait for an owned production run to finish. A timeout returns the last observed status with timed_out=true; the run keeps going.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                run_id: runIdInput,
+                timeout_seconds: {
+                    type: 'integer',
+                    minimum: 10,
+                    maximum: MAX_TIMEOUT_SECONDS,
+                    description: 'Bounded wait in seconds (default 1800, maximum 3600).',
+                },
+                account: accountInput,
+            },
+            required: ['run_id'],
+        },
+    },
+];
+function requireInputString(input, field) {
+    const value = input[field];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`${field} required`);
+    }
+    return value;
+}
+function optionalInputString(input, field) {
+    const value = input[field];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`${field} must be a non-empty string`);
+    }
+    return value;
+}
+function assertExactInputFields(input, allowed) {
+    const allowedFields = new Set(allowed);
+    const unsupported = Object.keys(input).find(field => !allowedFields.has(field));
+    if (unsupported)
+        throw new Error(`unsupported input field: ${unsupported}`);
+}
+function assertToolInputFields(name, input) {
+    if (name === 'verify_start') {
+        assertExactInputFields(input, [
+            'account',
+            'base_commit',
+            'head_commit',
+            'idempotency_key',
+            'repository',
+        ]);
+        return;
+    }
+    if (name === 'verify_status') {
+        assertExactInputFields(input, ['account', 'run_id']);
+        return;
+    }
+    if (name === 'verify_wait') {
+        assertExactInputFields(input, ['account', 'run_id', 'timeout_seconds']);
+        return;
+    }
+    throw new Error(`unknown tool: ${name}`);
+}
+function nextCommand(state, account) {
+    return TERMINAL_STATUSES.has(state.status)
+        ? undefined
+        : hostedResumeCommand(state.runId, account);
+}
+export async function executeHostedVerifyTool(name, input, context) {
+    assertToolInputFields(name, input);
+    if (name === 'verify_start') {
+        const repository = requireInputString(input, 'repository');
+        const started = await startHostedVerification(repository, {
+            base: requireInputString(input, 'base_commit'),
+            head: requireInputString(input, 'head_commit'),
+            idempotencyKey: optionalInputString(input, 'idempotency_key'),
+            wait: false,
+        }, context.token);
+        return buildHostedJson('start', started.state, {
+            account: context.account,
+            idempotencyKey: started.idempotencyKey,
+            nextCommand: nextCommand(started.state, context.account),
+        });
+    }
+    if (name === 'verify_status') {
+        const state = await getHostedVerification(requireInputString(input, 'run_id'), context.token);
+        return buildHostedJson('status', state, {
+            account: context.account,
+            nextCommand: nextCommand(state, context.account),
+        });
+    }
+    if (name === 'verify_wait') {
+        const runId = requireInputString(input, 'run_id');
+        const rawTimeout = input.timeout_seconds;
+        const timeoutSeconds = rawTimeout === undefined
+            ? DEFAULT_TIMEOUT_SECONDS
+            : rawTimeout;
+        if (typeof timeoutSeconds !== 'number'
+            || !Number.isInteger(timeoutSeconds)
+            || timeoutSeconds < 10
+            || timeoutSeconds > MAX_TIMEOUT_SECONDS) {
+            throw new Error('timeout_seconds must be an integer from 10 to 3600');
+        }
+        const waited = await waitForHostedVerification(runId, context.token, {
+            intervalMs: 3_000,
+            timeoutMs: timeoutSeconds * 1_000,
+        });
+        return buildHostedJson('status', waited.state, {
+            account: context.account,
+            nextCommand: nextCommand(waited.state, context.account),
+            timedOut: waited.timedOut,
+        });
+    }
+    throw new Error(`unknown tool: ${name}`);
+}
+async function resolveToolContext(name, input, options) {
+    const requestedAccount = optionalInputString(input, 'account') ?? options.account;
+    const repository = name === 'verify_start'
+        ? parseHostedRepository(requireInputString(input, 'repository'))
+        : undefined;
+    const auth = await resolveAuthContext({
+        preferredLogin: requestedAccount,
+        owner: repository?.owner,
+        repo: repository?.repository,
+    });
+    return {
+        token: auth.token,
+        account: auth.token.startsWith('hsk_live_') ? undefined : auth.login,
+    };
+}
+export async function runHostedVerifyMcpServer(options) {
+    const mcp = new Server({ name: 'haystack-verify-hosted', version: '1.0.0' }, { capabilities: { tools: {} } });
+    mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: HOSTED_VERIFY_TOOLS }));
+    mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const input = (args ?? {});
+        try {
+            // Reject undeclared fields before account resolution so callers cannot
+            // use an invalid request to trigger credential or repository lookup.
+            assertToolInputFields(name, input);
+            const context = await resolveToolContext(name, input, options);
+            const result = await executeHostedVerifyTool(name, input, context);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{
+                        type: 'text',
+                        text: error instanceof Error ? error.message : String(error),
+                    }],
+            };
+        }
+    });
+    await mcp.connect(new StdioServerTransport());
+}

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

@@ -0,0 +1,60 @@
+export interface HostedStartOptions {
+    base: string;
+    head: string;
+    idempotencyKey?: string;
+    account?: string;
+    wait?: boolean;
+    interval?: string;
+    timeout?: string;
+    json?: boolean;
+}
+export interface HostedStatusOptions {
+    account?: string;
+    wait?: boolean;
+    interval?: string;
+    timeout?: string;
+    json?: boolean;
+}
+interface HostedRunState {
+    runId: string;
+    status: string;
+    repository?: string;
+    baseCommit?: string;
+    headCommit?: string;
+    createdAt?: string;
+    completedAt?: string;
+    output?: Record<string, unknown>;
+    error?: string;
+}
+interface HostedPollOptions {
+    intervalMs: number;
+    timeoutMs: number;
+    onStatus?: (state: HostedRunState) => void;
+}
+interface HostedWaitResult {
+    state: HostedRunState;
+    timedOut: boolean;
+}
+export declare function parseHostedRunState(value: unknown, expectedRunId?: string): HostedRunState;
+export declare function parseHostedRepository(value: string): {
+    owner: string;
+    repository: string;
+    fullName: string;
+};
+export declare function defaultHostedIdempotencyKey(repository: string, baseCommit: string, headCommit: string): string;
+export declare function startHostedVerification(repositoryArg: string, options: HostedStartOptions, token: string): Promise<{
+    state: HostedRunState;
+    idempotencyKey: string;
+}>;
+export declare function getHostedVerification(runId: string, token: string): Promise<HostedRunState>;
+export declare function waitForHostedVerification(runId: string, token: string, options: HostedPollOptions): Promise<HostedWaitResult>;
+export declare function buildHostedJson(operation: 'start' | 'status', state: HostedRunState, extras?: {
+    account?: string;
+    idempotencyKey?: string;
+    nextCommand?: string;
+    timedOut?: boolean;
+}): Record<string, unknown>;
+export declare function hostedResumeCommand(runId: string, account?: string): string;
+export declare function verifyHostedStartCommand(repositoryArg: string, options: HostedStartOptions): Promise<void>;
+export declare function verifyHostedStatusCommand(runId: string, options: HostedStatusOptions): Promise<void>;
+export {};