@haystackeditor/cli 0.15.18 → 0.15.20

package/dist/utils/analysis-api.js

@@ -7,6 +7,7 @@
  * Analysis is triggered automatically by the GitHub App webhook when a PR
  * is created or updated — the CLI does not need to trigger it directly.
  */
+import { classifyHttpError } from './haystack-api.js';
 // ============================================================================
 // Constants
 // ============================================================================
@@ -61,9 +62,114 @@ function apiHeaders(token) {
     }
     return headers;
 }
-// ============================================================================
-// API functions
-// ============================================================================
+/**
+ * Trigger a fresh full analysis for a PR via the auth-worker
+ * (`/api/analysis-trigger/{owner}/{repo}/{pr}`). Requires auth — triggers
+ * start a real analysis run. Returns the request id to wait on.
+ */
+export async function triggerAnalysis(owner, repo, prNumber, token, headSha) {
+    const url = `${ANALYSIS_API_BASE}/api/analysis-trigger/${owner}/${repo}/${prNumber}`;
+    let response;
+    try {
+        // Force semantics ride on a server-set header at the trigger route.
+        // commitSha matters for dedup: without it, ingestion matches this
+        // request onto any in-flight run for an OLDER head and the CLI would
+        // wait on (and render) stale results.
+        response = await fetch(url, {
+            method: 'POST',
+            headers: { ...apiHeaders(token), 'Content-Type': 'application/json' },
+            body: JSON.stringify(headSha ? { commitSha: headSha } : {}),
+        });
+    }
+    catch (err) {
+        return { status: 'error', message: err.message };
+    }
+    let data = {};
+    let parseFailed = false;
+    try {
+        data = await response.json();
+    }
+    catch {
+        // Recorded, not swallowed: for non-OK responses the status-code handling
+        // below surfaces the failure; a 2xx with an unparseable body is its own
+        // explicit error (never "empty data") so callers can't mistake a
+        // malformed response for a normal one.
+        parseFailed = true;
+    }
+    if (parseFailed && response.ok) {
+        return { status: 'error', message: `Trigger endpoint returned invalid JSON (HTTP ${response.status})` };
+    }
+    if (response.status === 429) {
+        return {
+            status: 'rate_limited',
+            message: data.message || 'Too many analysis requests. Please wait before trying again.',
+            retryAfterSeconds: data.retryAfter,
+        };
+    }
+    if (response.status === 401 || response.status === 403) {
+        return {
+            status: 'denied',
+            message: data.message || data.error || `HTTP ${response.status}`,
+        };
+    }
+    if (!response.ok) {
+        return { status: 'error', message: data.message || data.error || `HTTP ${response.status}` };
+    }
+    if (!data.request_id) {
+        return { status: 'error', message: 'Trigger response did not include a request id' };
+    }
+    if (data.status === 'already_processing') {
+        return { status: 'already_processing', requestId: data.request_id };
+    }
+    return { status: 'started', requestId: data.request_id };
+}
+// Terminal states of the v3 status vocabulary (map_status_for_frontend in
+// haystack-v3-request-status). Everything else — QUEUED, PROCESSING,
+// CLONING, PREPARING, ANALYZING, not_found (row lag), and any state a newer
+// backend introduces — reads as pending: misclassifying a healthy
+// in-progress state as an error would abort the wait.
+const TERMINAL_STATUSES = {
+    COMPLETED: 'COMPLETED',
+    FAILED: 'FAILED',
+    TIMED_OUT: 'FAILED',
+    SUPERSEDED: 'SUPERSEDED',
+};
+/**
+ * Poll the status of a triggered run by request id. The PR-level result
+ * endpoint can't distinguish a fresh re-run on the same head from the
+ * previous completed analysis — the request id can.
+ */
+export async function fetchTriggerStatus(requestId, token) {
+    const url = `${ANALYSIS_API_BASE}/api/analysis-trigger/status/${requestId}`;
+    try {
+        const response = await fetch(url, { headers: apiHeaders(token) });
+        // The status Lambda returns not_found as a 404 WITH a JSON body — parse
+        // before rejecting on status code so "not yet written" is distinguishable
+        // from a real transport failure.
+        let data = {};
+        try {
+            data = await response.json();
+        }
+        catch {
+            return { status: 'error', message: `HTTP ${response.status}` };
+        }
+        const status = typeof data.status === 'string' ? data.status : '';
+        const terminal = TERMINAL_STATUSES[status];
+        if (terminal) {
+            return { status: terminal, message: data.message };
+        }
+        // Only successful responses (plus the documented 404 not_found row-lag
+        // case) read as pending — a 5xx carrying {"status":"error"} must count
+        // toward the error budget, not spin the wait for the full timeout.
+        if (response.ok || (response.status === 404 && status === 'not_found')) {
+            return { status: 'pending', message: data.message };
+        }
+        return { status: 'error', message: data.message || `HTTP ${response.status}` };
+    }
+    catch (err) {
+        return { status: 'error', message: err.message };
+    }
+}
 /**
  * Check if analysis results are available for a PR by polling the result endpoint.
  * Returns 'ready' if complete, 'pending' if not yet available, or 'error' for server failures.
@@ -82,7 +188,9 @@ export async function checkAnalysisReady(owner, repo, prNumber, token) {
     if (response.status === 404)
         return { status: 'pending' };
     if (!response.ok) {
-        return { status: 'error', message: `HTTP ${response.status}` };
+        // Classified, actionable message — a bare "HTTP 403" used to send agents
+        // into a retry loop when the fix was `haystack login`.
+        return { status: 'error', message: (await classifyHttpError(response, 'Analysis status check')).message };
     }
     let data;
     try {
@@ -231,12 +339,22 @@ export async function fetchAnalysisResults(owner, repo, prNumber, token) {
         needsHumanReview,
     };
 }
+/**
+ * Null means "artifact does not exist (yet)" — 404s and transient
+ * network/parse failures. Auth failures (401/403) THROW a classified
+ * HaystackApiError instead: collapsing them into null used to make an
+ * expired token read as "not available yet — try again in a moment",
+ * sending agents into a retry loop when the fix was `haystack login`.
+ */
 export async function fetchAutoFixManifest(owner, repo, prNumber, token) {
     const url = v3ResultUrl(owner, repo, prNumber, 'auto-fix-manifest.json');
     try {
         const response = await fetch(url, {
             headers: apiHeaders(token),
         });
+        if (response.status === 401 || response.status === 403) {
+            throw await classifyHttpError(response, 'Auto-fix manifest fetch');
+        }
         if (!response.ok)
             return null;
         const data = await response.json();
@@ -250,10 +368,17 @@ export async function fetchAutoFixManifest(owner, repo, prNumber, token) {
         }
         return data;
     }
-    catch {
+    catch (err) {
+        if (err instanceof Error && err.name === 'HaystackApiError')
+            throw err;
+        // Transient network/parse failure — same "not available" semantics as 404.
         return null;
     }
 }
+/**
+ * Null means "synthesis does not exist (yet)". Auth failures (401/403) THROW
+ * a classified HaystackApiError — see fetchAutoFixManifest for why.
+ */
 export async function fetchRatingSynthesis(owner, repo, prNumber, token) {
     // Route through the auth-worker (/api/analysis/{prId}/rating_synthesis.json)
     // so hsk_live tokens are introspected and the scope gate applies — see
@@ -263,6 +388,9 @@ export async function fetchRatingSynthesis(owner, repo, prNumber, token) {
         const response = await fetch(url, {
             headers: apiHeaders(token),
         });
+        if (response.status === 401 || response.status === 403) {
+            throw await classifyHttpError(response, 'Rating synthesis fetch');
+        }
         if (!response.ok)
             return null;
         const data = await response.json();
@@ -279,7 +407,10 @@ export async function fetchRatingSynthesis(owner, repo, prNumber, token) {
         }
         return data;
     }
-    catch {
+    catch (err) {
+        if (err instanceof Error && err.name === 'HaystackApiError')
+            throw err;
+        // Transient network/parse failure — same "not available" semantics as 404.
         return null;
     }
 }

package/dist/utils/auth.js

@@ -399,6 +399,13 @@ export async function resolveAuthContext(options = {}) {
     // — that intent should not be overridden by a stale OAuth cookie.
     const headless = await readHeadlessToken();
     if (headless) {
+        // The headless token wins, but dropping an explicit --account silently
+        // would leave the caller authenticated as someone they didn't ask for —
+        // say so on stderr.
+        if (options.preferredLogin) {
+            console.error(`--account ${options.preferredLogin} is ignored: a headless token (${headless.label ?? 'token file'}) takes precedence. ` +
+                'Unset HAYSTACK_CLI_TOKEN or remove the token file (`haystack logout --headless`) to use saved accounts.');
+        }
         return {
             login: headless.label ?? 'headless',
             token: headless.token,

package/dist/utils/git.d.ts

@@ -78,7 +78,10 @@ export declare class UnsupportedRemoteUrlError extends Error {
  */
 export declare function parseRemoteUrl(remoteName?: string): GitRemoteInfo;
 /**
- * Get the last commit message (first line only)
+ * Get the last commit message (first line only).
+ *
+ * Throws instead of guessing: this feeds the default PR title, and the old
+ * silent fallback ('Update') shipped meaningless titles when git failed.
  */
 export declare function getLastCommitMessage(): string;
 /**

package/dist/utils/git.js

@@ -22,8 +22,10 @@ export function getCurrentBranch() {
             stdio: ['pipe', 'pipe', 'pipe'],
         }).trim();
     }
-    catch {
-        throw new Error('Failed to get current branch. Are you in a git repository?');
+    catch (err) {
+        const stderr = err?.stderr?.toString().trim();
+        throw new Error(`Failed to get the current branch${stderr ? ` (${stderr})` : ''}. ` +
+            'Run from inside a git repository.');
     }
 }
 /**
@@ -296,19 +298,25 @@ export function parseRemoteUrl(remoteName = 'origin') {
     }
     catch (err) {
         // Propagate the "unrecognized URL" case as-is; wrap everything else (the
-        // `git remote get-url` command itself failing) in a friendlier message.
+        // `git remote get-url` command itself failing) with the underlying git
+        // error preserved — "No such remote 'origin'" is the actual diagnosis.
         // Classify by type, not message text (see pr-rules.yml PR007).
         if (err instanceof UnsupportedRemoteUrlError) {
             throw err;
         }
-        throw new Error(`Failed to get remote URL for '${remoteName}'`);
+        const stderr = err?.stderr?.toString().trim();
+        const cause = stderr || (err instanceof Error ? err.message : String(err));
+        throw new Error(`Failed to get remote URL for '${remoteName}': ${cause}`);
     }
 }
 // ============================================================================
 // Commit operations
 // ============================================================================
 /**
- * Get the last commit message (first line only)
+ * Get the last commit message (first line only).
+ *
+ * Throws instead of guessing: this feeds the default PR title, and the old
+ * silent fallback ('Update') shipped meaningless titles when git failed.
  */
 export function getLastCommitMessage() {
     try {
@@ -317,8 +325,10 @@ export function getLastCommitMessage() {
             stdio: ['pipe', 'pipe', 'pipe'],
         }).trim();
     }
-    catch {
-        return 'Update';
+    catch (err) {
+        const stderr = err?.stderr?.toString().trim();
+        throw new Error(`Could not read the last commit message${stderr ? ` (${stderr})` : ''}. ` +
+            'Commit your changes first, or pass an explicit --title.');
     }
 }
 /**

package/dist/utils/haystack-api.d.ts

@@ -12,6 +12,21 @@ export interface CliIdentity {
     login: string;
     id: number;
 }
+/**
+ * Typed error for non-OK Haystack API responses. Callers classify by
+ * `status` (never by message substring) and the message always carries a
+ * remediation an agent can act on.
+ */
+export declare class HaystackApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+    get isAuthError(): boolean;
+}
+/**
+ * Build an actionable error for a non-OK response: what failed, the HTTP
+ * class it failed with, and the next command to run.
+ */
+export declare function classifyHttpError(response: Response, context: string): Promise<HaystackApiError>;
 export declare function haystackJson<T>(path: string, token: string, init?: RequestInit): Promise<T>;
 export declare function fetchCliIdentity(token: string): Promise<CliIdentity>;
 export declare function fetchHaystackInstallations(token: string): Promise<UserInstallation[]>;

package/dist/utils/haystack-api.js

@@ -1,4 +1,20 @@
 const HAYSTACK_API_BASE = process.env.HAYSTACK_API_BASE ?? 'https://haystackeditor.com';
+/**
+ * Typed error for non-OK Haystack API responses. Callers classify by
+ * `status` (never by message substring) and the message always carries a
+ * remediation an agent can act on.
+ */
+export class HaystackApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = 'HaystackApiError';
+        this.status = status;
+    }
+    get isAuthError() {
+        return this.status === 401 || this.status === 403;
+    }
+}
 function headers(token, extra) {
     const result = new Headers(extra);
     result.set('Authorization', `Bearer ${token}`);
@@ -6,17 +22,52 @@ function headers(token, extra) {
     result.set('User-Agent', 'Haystack-CLI');
     return result;
 }
-async function errorMessage(response) {
-    const text = await response.text().catch(() => '');
+/** Extract the server's own message if the body is JSON; truncate raw bodies. */
+async function serverMessage(response) {
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch (err) {
+        // A transport failure while reading the error body is itself signal —
+        // say so instead of reporting it as "no detail" (the status-based
+        // classification in classifyHttpError stands either way).
+        return `error body unreadable: ${err instanceof Error ? err.message : String(err)}`;
+    }
     if (!text)
-        return `HTTP ${response.status}`;
+        return null;
     try {
         const parsed = JSON.parse(text);
-        return parsed.message ?? parsed.error ?? text;
+        return parsed.message ?? parsed.error ?? null;
     }
     catch {
-        return text;
+        // Not JSON (HTML error page, plain text) — never dump a full raw body.
+        return text.slice(0, 200);
+    }
+}
+/**
+ * Build an actionable error for a non-OK response: what failed, the HTTP
+ * class it failed with, and the next command to run.
+ */
+export async function classifyHttpError(response, context) {
+    const detail = await serverMessage(response);
+    const suffix = detail ? ` (${detail})` : '';
+    if (response.status === 401) {
+        return new HaystackApiError(401, `${context}: authentication failed${suffix}. Run \`haystack login\` to re-authenticate.`);
+    }
+    if (response.status === 403) {
+        return new HaystackApiError(403, `${context}: access denied${suffix}. Your token may lack access to this repository — run \`haystack auth list\` to check accounts, or \`haystack login\` to add one.`);
+    }
+    if (response.status === 404) {
+        return new HaystackApiError(404, `${context}: not found${suffix}. Check the PR number and repository.`);
+    }
+    if (response.status === 429) {
+        return new HaystackApiError(429, `${context}: rate limited${suffix}. Wait before retrying.`);
+    }
+    if (response.status >= 500) {
+        return new HaystackApiError(response.status, `${context}: Haystack server error (HTTP ${response.status})${suffix}. Retry in a moment.`);
     }
+    return new HaystackApiError(response.status, `${context}: unexpected response (HTTP ${response.status})${suffix}.`);
 }
 export async function haystackJson(path, token, init = {}) {
     const response = await fetch(`${HAYSTACK_API_BASE}${path}`, {
@@ -24,7 +75,7 @@ export async function haystackJson(path, token, init = {}) {
         headers: headers(token, init.headers),
     });
     if (!response.ok) {
-        throw new Error(`${response.status} ${await errorMessage(response)}`);
+        throw await classifyHttpError(response, `Haystack API ${path}`);
     }
     return response.json();
 }
@@ -46,7 +97,7 @@ export async function fetchAnalysisArtifact(owner, repo, prNumber, file, token)
     if (response.status === 404)
         return null;
     if (!response.ok) {
-        throw new Error(`${response.status} ${await errorMessage(response)}`);
+        throw await classifyHttpError(response, `Analysis artifact ${file}`);
     }
     const data = await response.json();
     if (!data || typeof data !== 'object' || !('download_url' in data) || !data.download_url) {

package/dist/utils/pr-ref.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared PR-identifier parsing for every command that takes a PR ref.
+ *
+ * One grammar, one error message, one repo-inference path. This used to be
+ * duplicated per command, and the copies drifted: different "accepted formats"
+ * lists (none mentioned the `#123` form the regex accepted), and one copy let
+ * a raw git error escape where the others gave a friendly hint. Commands must
+ * import from here rather than reimplementing the grammar.
+ *
+ * Accepted formats, in the order they are tried:
+ *   https://github.com/owner/repo/pull/123   GitHub URL
+ *   owner/repo#123                           Fully qualified
+ *   123 or #123                              PR number (repo inferred from the `origin` remote)
+ */
+export interface ParsedPR {
+    owner: string;
+    repo: string;
+    prNumber: number;
+}
+/** The accepted-formats block used in parse errors and help text. */
+export declare function acceptedPrRefFormats(commandName: string): string;
+/**
+ * Parse a PR identifier. `commandName` is interpolated into error messages so
+ * the agent can copy a corrected invocation verbatim (e.g. "triage",
+ * "pr get", "traces list").
+ */
+export declare function parsePrRef(identifier: string, commandName: string): ParsedPR;

package/dist/utils/pr-ref.js

@@ -0,0 +1,56 @@
+/**
+ * Shared PR-identifier parsing for every command that takes a PR ref.
+ *
+ * One grammar, one error message, one repo-inference path. This used to be
+ * duplicated per command, and the copies drifted: different "accepted formats"
+ * lists (none mentioned the `#123` form the regex accepted), and one copy let
+ * a raw git error escape where the others gave a friendly hint. Commands must
+ * import from here rather than reimplementing the grammar.
+ *
+ * Accepted formats, in the order they are tried:
+ *   https://github.com/owner/repo/pull/123   GitHub URL
+ *   owner/repo#123                           Fully qualified
+ *   123 or #123                              PR number (repo inferred from the `origin` remote)
+ */
+import { parseRemoteUrl } from './git.js';
+/** The accepted-formats block used in parse errors and help text. */
+export function acceptedPrRefFormats(commandName) {
+    return (`  haystack ${commandName} 123\n` +
+        `  haystack ${commandName} #123\n` +
+        `  haystack ${commandName} owner/repo#123\n` +
+        `  haystack ${commandName} https://github.com/owner/repo/pull/123`);
+}
+/**
+ * Parse a PR identifier. `commandName` is interpolated into error messages so
+ * the agent can copy a corrected invocation verbatim (e.g. "triage",
+ * "pr get", "traces list").
+ */
+export function parsePrRef(identifier, commandName) {
+    const urlMatch = identifier.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)\/?$/);
+    if (urlMatch) {
+        return { owner: urlMatch[1], repo: urlMatch[2], prNumber: parseInt(urlMatch[3], 10) };
+    }
+    // owner/repo#123 — repo segment may not contain `/` (a stray extra segment
+    // used to silently become part of the repo name and 404 downstream).
+    const qualifiedMatch = identifier.match(/^([^/#\s]+)\/([^/#\s]+)#(\d+)$/);
+    if (qualifiedMatch) {
+        return { owner: qualifiedMatch[1], repo: qualifiedMatch[2], prNumber: parseInt(qualifiedMatch[3], 10) };
+    }
+    const numberMatch = identifier.match(/^#?(\d+)$/);
+    if (numberMatch) {
+        const prNumber = parseInt(numberMatch[1], 10);
+        try {
+            const remote = parseRemoteUrl('origin');
+            return { owner: remote.owner, repo: remote.repo, prNumber };
+        }
+        catch (err) {
+            throw new Error(`Cannot determine the repository for PR #${prNumber} ` +
+                `(${err instanceof Error ? err.message : String(err)}).\n` +
+                `Run from inside a checkout with an "origin" remote, or use the full format:\n` +
+                `  haystack ${commandName} owner/repo#${prNumber}`);
+        }
+    }
+    throw new Error(`Invalid PR identifier: "${identifier}"\n\n` +
+        `Accepted formats:\n${acceptedPrRefFormats(commandName)}\n\n` +
+        `See \`haystack ${commandName.split(' ')[0]} --help\` for details.`);
+}

package/package.json

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

package/schemas/action.v1.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.haystackeditor.com/cli/schemas/action.v1.json",
+  "title": "haystack <dismiss|mark-reviewed|undismiss|request-review|review> --json",
+  "description": "Shared envelope for every mutating command. Exactly one document on stdout; progress on stderr. status 'error' payloads accompany exit code 1.",
+  "type": "object",
+  "required": ["schema_version", "action", "status"],
+  "properties": {
+    "schema_version": { "type": "string", "const": "1.0.0" },
+    "action": { "type": "string", "enum": ["dismiss", "mark_reviewed", "undismiss", "request_review", "trigger_review", "clear_pending"] },
+    "status": { "type": "string", "enum": ["ok", "error"] },
+    "ref": { "type": ["string", "null"], "description": "owner/repo#number. Null on errors that happen before the ref resolves." },
+    "error": { "type": "string", "description": "Present only when status is 'error'. Actionable message including the remediation." },
+    "detail": { "type": "string", "description": "Human-readable statement of what changed." },
+    "head_sha": { "type": "string", "description": "dismiss/mark_reviewed: the head commit the override is tied to. A new commit invalidates the override." },
+    "reviewer": { "type": ["string", "null"], "description": "request_review: the GitHub user review was requested from, or null for the needs-assignment queue." },
+    "reviewer_request_failed": { "type": ["string", "null"], "description": "request_review: set when the label was applied but the specific-reviewer request failed (partial success)." },
+    "request_id": { "type": "string", "description": "trigger_review: the analysis run id." },
+    "run_status": { "type": "string", "enum": ["started", "already_processing", "completed", "superseded", "running"], "description": "trigger_review: state of the triggered run when the command returned." },
+    "next": { "type": ["string", "null"], "description": "Follow-up command to read results (e.g. `haystack triage <ref> --json`)." }
+  }
+}

package/schemas/error.v1.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.haystackeditor.com/cli/schemas/error.v1.json",
+  "title": "Generic --json error envelope",
+  "description": "Emitted on stdout (with exit code 1) when a read command invoked with --json fails before it can produce its own payload. Commands with richer contracts (submit, action) embed status:'error' in their own schemas instead.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "status", "error"],
+  "properties": {
+    "schema_version": { "type": "string", "const": "1.0.0" },
+    "status": { "type": "string", "const": "error" },
+    "error": { "type": "string", "description": "Actionable message including the remediation." }
+  }
+}

package/schemas/pr-status.v1.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.haystackeditor.com/cli/schemas/pr-status.v1.json",
+  "title": "haystack pr-status <ref> --json",
+  "description": "Which Haystack feed bucket a PR is in, and why. All state tokens are snake_case — the same vocabulary as `haystack triage --json` and `haystack pr get --json`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "ref", "bucket", "in_feed", "feed_priority", "reason", "analysis", "needs_human_review", "labels", "overrides", "author", "is_author", "is_open", "state_synced_at", "stale_warning"],
+  "properties": {
+    "schema_version": { "type": "string", "const": "1.0.0" },
+    "ref": { "type": "string", "description": "owner/repo#number" },
+    "bucket": {
+      "type": ["string", "null"],
+      "description": "Feed bucket in snake_case. Known values are enumerated below; new buckets may appear (always snake_case). Null when the PR is unclassified (closed or not yet analyzed).",
+      "examples": ["analyzing", "auto_fixing", "good_to_merge", "failed_when_merging", "issues", "needs_assignment", "needs_shepherding", "needs_fixing", "awaiting_review", "review_requested", "snoozed"]
+    },
+    "in_feed": { "type": ["boolean", "null"], "description": "Null when the PR is unclassified (e.g. closed)." },
+    "feed_priority": { "type": ["number", "null"] },
+    "reason": { "type": "string", "description": "Human-readable explanation of the classification." },
+    "analysis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "verdict", "rating"],
+      "properties": {
+        "status": { "type": "string", "enum": ["pending", "in_queue", "ready", "error"] },
+        "verdict": {
+          "anyOf": [
+            { "type": "string", "enum": ["good_to_merge", "needs_review", "needs_input"] },
+            { "type": "null" }
+          ],
+          "description": "Null until analysis is ready."
+        },
+        "rating": {
+          "anyOf": [
+            { "type": "integer", "minimum": 1, "maximum": 5 },
+            { "type": "null" }
+          ]
+        }
+      }
+    },
+    "needs_human_review": { "type": ["boolean", "null"] },
+    "labels": { "type": "array", "items": { "type": "string" } },
+    "overrides": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["snoozed", "dismissed", "dismissed_agent_alerts", "dismissed_needs_assignment", "manually_good_to_merge"],
+      "properties": {
+        "snoozed": { "type": "boolean" },
+        "dismissed": { "type": "boolean" },
+        "dismissed_agent_alerts": { "type": "boolean" },
+        "dismissed_needs_assignment": { "type": "boolean" },
+        "manually_good_to_merge": { "type": "boolean" }
+      }
+    },
+    "author": { "type": ["string", "null"], "description": "Null when the server could not resolve PR metadata." },
+    "is_author": { "type": ["boolean", "null"] },
+    "is_open": { "type": ["boolean", "null"] },
+    "state_synced_at": { "type": ["string", "null"] },
+    "stale_warning": { "type": ["string", "null"] }
+  }
+}