@haystackeditor/cli 0.15.19 → 0.15.21

package/dist/states.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Canonical machine-readable PR-state vocabulary for every CLI JSON surface.
+ *
+ * One concept, one spelling: all `--json` output uses snake_case state tokens.
+ * Before this module existed the same state appeared as `good_to_merge`
+ * (triage/pr get/inbox) and `good-to-merge` (pr-status, raw server buckets),
+ * so no single parser worked across commands. Server responses that use
+ * kebab-case are normalized at the edge via `normalizeFeedBucket`.
+ */
+/** Public triage verdict — emitted by `triage`, `pr get`, `submit`, `pr-status`. */
+export declare const TRIAGE_VERDICTS: readonly ["good_to_merge", "needs_review", "needs_input"];
+export type TriageVerdict = (typeof TRIAGE_VERDICTS)[number];
+/**
+ * Map the server's internal analysis verdict ('clean' | 'has-issues' |
+ * 'needs-review', with a rating-based fallback for pre-verdict analyses) to
+ * the public triage verdict. This mapping used to be duplicated inline in
+ * triage.ts and pr.ts.
+ */
+export declare function toPublicVerdict(analysisVerdict: string | null | undefined, haystackRating?: number | null): TriageVerdict;
+/**
+ * Known feed buckets in canonical snake_case form. The server may introduce
+ * new buckets; `normalizeFeedBucket` converts mechanically so unknown buckets
+ * pass through in the same convention instead of crashing or leaking kebab-case.
+ */
+export declare const FEED_BUCKETS: readonly ["analyzing", "auto_fixing", "good_to_merge", "failed_when_merging", "issues", "needs_assignment", "needs_shepherding", "needs_fixing", "awaiting_review", "review_requested", "snoozed"];
+export type FeedBucket = (typeof FEED_BUCKETS)[number];
+/** Normalize a server feed bucket (kebab-case) to the canonical snake_case form. */
+export declare function normalizeFeedBucket(bucket: string): string;
+export declare function normalizeFeedBucket(bucket: string | null | undefined): string | null;

package/dist/states.js

@@ -0,0 +1,46 @@
+/**
+ * Canonical machine-readable PR-state vocabulary for every CLI JSON surface.
+ *
+ * One concept, one spelling: all `--json` output uses snake_case state tokens.
+ * Before this module existed the same state appeared as `good_to_merge`
+ * (triage/pr get/inbox) and `good-to-merge` (pr-status, raw server buckets),
+ * so no single parser worked across commands. Server responses that use
+ * kebab-case are normalized at the edge via `normalizeFeedBucket`.
+ */
+/** Public triage verdict — emitted by `triage`, `pr get`, `submit`, `pr-status`. */
+export const TRIAGE_VERDICTS = ['good_to_merge', 'needs_review', 'needs_input'];
+/**
+ * Map the server's internal analysis verdict ('clean' | 'has-issues' |
+ * 'needs-review', with a rating-based fallback for pre-verdict analyses) to
+ * the public triage verdict. This mapping used to be duplicated inline in
+ * triage.ts and pr.ts.
+ */
+export function toPublicVerdict(analysisVerdict, haystackRating) {
+    const verdict = analysisVerdict ?? ((haystackRating ?? 0) >= 5 ? 'clean' : 'has-issues');
+    if (verdict === 'clean')
+        return 'good_to_merge';
+    if (verdict === 'needs-review')
+        return 'needs_review';
+    return 'needs_input';
+}
+/**
+ * Known feed buckets in canonical snake_case form. The server may introduce
+ * new buckets; `normalizeFeedBucket` converts mechanically so unknown buckets
+ * pass through in the same convention instead of crashing or leaking kebab-case.
+ */
+export const FEED_BUCKETS = [
+    'analyzing',
+    'auto_fixing',
+    'good_to_merge',
+    'failed_when_merging',
+    'issues',
+    'needs_assignment',
+    'needs_shepherding',
+    'needs_fixing',
+    'awaiting_review',
+    'review_requested',
+    'snoozed',
+];
+export function normalizeFeedBucket(bucket) {
+    return bucket == null ? null : bucket.replace(/-/g, '_');
+}

package/dist/triage/runner.d.ts

@@ -16,6 +16,13 @@ export interface RunTriageOptions {
  * Returns the first one found, or null if none available.
  */
 export declare function detectAgenticCLI(): AgenticCLI | null;
+/**
+ * Build the CLI command + args for the detected agentic tool.
+ */
+export declare function buildCommand(cli: AgenticCLI, prompt: string, maxTurns: number): {
+    command: string;
+    args: string[];
+};
 /**
  * Run pre-PR triage checks using parallel sub-agent processes.
  *

package/dist/triage/runner.js

@@ -86,7 +86,7 @@ export function detectAgenticCLI() {
 /**
  * Build the CLI command + args for the detected agentic tool.
  */
-function buildCommand(cli, prompt, maxTurns) {
+export function buildCommand(cli, prompt, maxTurns) {
     switch (cli) {
         case 'claude':
             return {
@@ -101,7 +101,7 @@ function buildCommand(cli, prompt, maxTurns) {
         case 'codex':
             return {
                 command: 'codex',
-                args: ['exec', prompt, '--full-auto', '--ephemeral'],
+                args: ['exec', prompt, '--full-auto'],
             };
         case 'gemini':
             return {

package/dist/types.d.ts

@@ -719,11 +719,52 @@ declare const TriageConfigSchema: z.ZodObject<{
     maxTurns?: Partial<Record<"code-review" | "rules-validator" | "intent-drift", number>> | undefined;
     timeoutMs?: number | undefined;
 }>;
+declare const PreferencesSchema: z.ZodObject<{
+    /** Run analysis automatically for PR webhook events (default: true) */
+    automatic_analysis: z.ZodOptional<z.ZodBoolean>;
+    /** Enable sandbox-backed verification for this repository */
+    sandbox_enabled: z.ZodOptional<z.ZodBoolean>;
+    /** Enroll submitted PRs in auto-merge by default */
+    auto_merge: z.ZodOptional<z.ZodBoolean>;
+    /** Allow Haystack to attempt automatic fixes */
+    auto_fix: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    automatic_analysis?: boolean | undefined;
+    sandbox_enabled?: boolean | undefined;
+    auto_merge?: boolean | undefined;
+    auto_fix?: boolean | undefined;
+}, {
+    automatic_analysis?: boolean | undefined;
+    sandbox_enabled?: boolean | undefined;
+    auto_merge?: boolean | undefined;
+    auto_fix?: boolean | undefined;
+}>;
 export declare const HaystackConfigSchema: z.ZodObject<{
     /** Config version (must be "1") */
     version: z.ZodLiteral<"1">;
     /** Project name (for display) */
     name: z.ZodOptional<z.ZodString>;
+    /** Repository-level Haystack behavior */
+    preferences: z.ZodOptional<z.ZodObject<{
+        /** Run analysis automatically for PR webhook events (default: true) */
+        automatic_analysis: z.ZodOptional<z.ZodBoolean>;
+        /** Enable sandbox-backed verification for this repository */
+        sandbox_enabled: z.ZodOptional<z.ZodBoolean>;
+        /** Enroll submitted PRs in auto-merge by default */
+        auto_merge: z.ZodOptional<z.ZodBoolean>;
+        /** Allow Haystack to attempt automatic fixes */
+        auto_fix: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        automatic_analysis?: boolean | undefined;
+        sandbox_enabled?: boolean | undefined;
+        auto_merge?: boolean | undefined;
+        auto_fix?: boolean | undefined;
+    }, {
+        automatic_analysis?: boolean | undefined;
+        sandbox_enabled?: boolean | undefined;
+        auto_merge?: boolean | undefined;
+        auto_fix?: boolean | undefined;
+    }>>;
     /** Package manager override (auto-detected if not specified) */
     package_manager: z.ZodOptional<z.ZodEnum<["npm", "pnpm", "yarn", "bun"]>>;
     /** Development server configuration */
@@ -1315,6 +1356,12 @@ export declare const HaystackConfigSchema: z.ZodObject<{
         root?: string | undefined;
         depends_on?: string[] | undefined;
     }> | undefined;
+    preferences?: {
+        automatic_analysis?: boolean | undefined;
+        sandbox_enabled?: boolean | undefined;
+        auto_merge?: boolean | undefined;
+        auto_fix?: boolean | undefined;
+    } | undefined;
     package_manager?: "npm" | "pnpm" | "yarn" | "bun" | undefined;
     dev_server?: {
         command: string;
@@ -1442,6 +1489,12 @@ export declare const HaystackConfigSchema: z.ZodObject<{
         root?: string | undefined;
         depends_on?: string[] | undefined;
     }> | undefined;
+    preferences?: {
+        automatic_analysis?: boolean | undefined;
+        sandbox_enabled?: boolean | undefined;
+        auto_merge?: boolean | undefined;
+        auto_fix?: boolean | undefined;
+    } | undefined;
     package_manager?: "npm" | "pnpm" | "yarn" | "bun" | undefined;
     dev_server?: {
         command: string;
@@ -1559,6 +1612,7 @@ export type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
 export type SecretDeclaration = z.infer<typeof SecretDeclarationSchema>;
 export type MergeQueueConfig = z.infer<typeof MergeQueueConfigSchema>;
 export type TriageConfig = z.infer<typeof TriageConfigSchema>;
+export type Preferences = z.infer<typeof PreferencesSchema>;
 /**
  * Project detection results
  */

package/dist/types.js

@@ -280,6 +280,19 @@ const TriageConfigSchema = z.object({
     timeoutMs: z.number().int().positive().optional(),
 });
 // =============================================================================
+// REPOSITORY PREFERENCES
+// =============================================================================
+const PreferencesSchema = z.object({
+    /** Run analysis automatically for PR webhook events (default: true) */
+    automatic_analysis: z.boolean().optional(),
+    /** Enable sandbox-backed verification for this repository */
+    sandbox_enabled: z.boolean().optional(),
+    /** Enroll submitted PRs in auto-merge by default */
+    auto_merge: z.boolean().optional(),
+    /** Allow Haystack to attempt automatic fixes */
+    auto_fix: z.boolean().optional(),
+});
+// =============================================================================
 // MAIN CONFIG
 // =============================================================================
 export const HaystackConfigSchema = z.object({
@@ -287,6 +300,8 @@ export const HaystackConfigSchema = z.object({
     version: z.literal('1'),
     /** Project name (for display) */
     name: z.string().optional(),
+    /** Repository-level Haystack behavior */
+    preferences: PreferencesSchema.optional(),
     /** Package manager override (auto-detected if not specified) */
     package_manager: z.enum(['npm', 'pnpm', 'yarn', 'bun']).optional(),
     /** Development server configuration */

package/dist/utils/action-output.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared machine-readable envelope for the mutating commands
+ * (dismiss, mark-reviewed, undismiss, request-review, review).
+ *
+ * One schema for all of them (`haystack schema action`): every payload
+ * carries `action`, `status`, and `ref`, so an agent can drive any state
+ * change with a single parser. Success payloads go to stdout as the only
+ * stdout content; human/progress output stays on stderr in --json mode.
+ */
+export type ActionName = 'dismiss' | 'mark_reviewed' | 'undismiss' | 'request_review' | 'trigger_review' | 'clear_pending';
+export interface ActionPayload extends Record<string, unknown> {
+    action: ActionName;
+    status: 'ok';
+    ref: string;
+    /** Human-readable statement of what changed. */
+    detail: string;
+}
+/** Print the success envelope (JSON mode only — human output is the caller's). */
+export declare function emitActionPayload(payload: ActionPayload): void;
+/**
+ * Print a failure (JSON error envelope on stdout when --json, red text on
+ * stderr always) and exit 1.
+ */
+export declare function failAction(json: boolean | undefined, action: ActionName, ref: string | null, message: string): never;

package/dist/utils/action-output.js

@@ -0,0 +1,26 @@
+/**
+ * Shared machine-readable envelope for the mutating commands
+ * (dismiss, mark-reviewed, undismiss, request-review, review).
+ *
+ * One schema for all of them (`haystack schema action`): every payload
+ * carries `action`, `status`, and `ref`, so an agent can drive any state
+ * change with a single parser. Success payloads go to stdout as the only
+ * stdout content; human/progress output stays on stderr in --json mode.
+ */
+import chalk from 'chalk';
+import { withSchema } from '../schema.js';
+/** Print the success envelope (JSON mode only — human output is the caller's). */
+export function emitActionPayload(payload) {
+    console.log(JSON.stringify(withSchema('action', payload), null, 2));
+}
+/**
+ * Print a failure (JSON error envelope on stdout when --json, red text on
+ * stderr always) and exit 1.
+ */
+export function failAction(json, action, ref, message) {
+    if (json) {
+        process.stdout.write(JSON.stringify(withSchema('action', { action, status: 'error', ref, error: message }), null, 2) + '\n');
+    }
+    console.error(chalk.red(`\n${message}\n`));
+    process.exit(1);
+}

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

@@ -172,5 +172,16 @@ export interface AutoFixManifest {
     timestamp: string;
     resultSha?: string;
 }
+/**
+ * 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 declare function fetchAutoFixManifest(owner: string, repo: string, prNumber: number, token?: string): Promise<AutoFixManifest | null>;
+/**
+ * Null means "synthesis does not exist (yet)". Auth failures (401/403) THROW
+ * a classified HaystackApiError — see fetchAutoFixManifest for why.
+ */
 export declare function fetchRatingSynthesis(owner: string, repo: string, prNumber: number, token?: string): Promise<RatingSynthesis | null>;

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
 // ============================================================================
@@ -187,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 {
@@ -336,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();
@@ -355,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
@@ -368,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();
@@ -384,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;