@haystackeditor/cli 0.15.18 → 0.15.20

package/dist/index.js

@@ -25,6 +25,7 @@ import { dirname, join } from 'node:path';
 import chalk from 'chalk';
 import { Command, Option } from 'commander';
 import { statusCommand } from './commands/status.js';
+import { withSchema } from './schema.js';
 import { initCommand } from './commands/init.js';
 import { authListCommand, authUseCommand, loginCommand, logoutCommand, whoamiCommand, } from './commands/login.js';
 import { handleAgenticTool, handleAutoMerge, handleAutoFix, handleWaitForReviewers, isAutoMergeEnabled, isAutoFixEnabled } from './commands/config.js';
@@ -36,6 +37,7 @@ import { listPolicies, addPolicy, removePolicy, initPolicies, addInstruction } f
 import { triageCommand } from './commands/triage.js';
 import { dismissCommand, markReviewedCommand, undismissCommand } from './commands/dismiss.js';
 import { requestReviewCommand } from './commands/request-review.js';
+import { reviewCommand } from './commands/review.js';
 import { prStatusCommand } from './commands/pr-status.js';
 import { prReadCommand } from './commands/pr.js';
 import { inboxListCommand } from './commands/inbox.js';
@@ -45,6 +47,7 @@ import { setupCommand } from './commands/setup.js';
 import { schemaCommand, listSchemas } from './commands/schema-cmd.js';
 import { registerWebhook, listWebhooks, rotateWebhookSecret, setWebhookEnabled, listDeliveries, replayDelivery, } from './commands/webhooks.js';
 import { editRulesCommand, validateRulesCommand } from './commands/rules.js';
+import { systemMapValidateCommand } from './commands/system-map.js';
 import { headlessLoginCommand, headlessLogoutCommand, listTokensCommand, revokeTokenCommand, } from './commands/tokens.js';
 // `mcp` is imported lazily inside its command action (below), NOT at the top level.
 // It is the only module that pulls in `@modelcontextprotocol/sdk`; keeping it out of
@@ -52,12 +55,19 @@ import { headlessLoginCommand, headlessLogoutCommand, listTokensCommand, revokeT
 // like `triage`/`submit`. (0.15.12 shipped `mcp.js` but published its package.json
 // WITHOUT `@modelcontextprotocol/sdk`, so the eager import here hard-crashed every
 // command at startup with ERR_MODULE_NOT_FOUND.)
-async function runPublicCommand(action) {
+async function runPublicCommand(action, json) {
     try {
         await action();
     }
     catch (err) {
-        console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+        const message = err instanceof Error ? err.message : String(err);
+        // In --json mode stdout must still carry one parseable document — emit the
+        // versioned error envelope (`haystack schema error`) instead of leaving
+        // stdout empty with prose on stderr.
+        if (json) {
+            process.stdout.write(JSON.stringify(withSchema('error', { status: 'error', error: message }), null, 2) + '\n');
+        }
+        console.error(chalk.red(message));
         process.exitCode = 1;
     }
 }
@@ -111,7 +121,7 @@ program
     .description('Onboarding wizard — scan repos for rules/policies and write Haystack config')
     .option('--json', 'Agent mode: emit NDJSON events on stdout, read answers on stdin (no TTY prompts)')
     .option('--repo <repo...>', 'Repo(s) to configure (owner/name); skips the repo picker')
-    .option('-y, --yes', 'Accept defaults non-interactively (keep all discovered items, confirm write)')
+    .option('-y, --yes', 'Accept defaults non-interactively (keep all discovered items, confirm write, ENABLE auto-merge — pass --no-auto-merge to opt out)')
     // Defining --no-auto-merge also accepts --auto-merge; default is "ask" unless
     // one is explicitly passed (detected via getOptionValueSource below).
     .option('--no-auto-merge', 'Set auto-merge in the written config (--auto-merge / --no-auto-merge; omit to be asked)')
@@ -246,7 +256,9 @@ program
     .option('--force', 'Skip pre-PR triage checks')
     .addOption(new Option('--auto-fix', 'Alpha auto-fix for entitled repositories').hideHelp())
     .option('--auto-merge', 'Apply auto-merge label (default: from .haystack.json, --no-auto-merge to disable)')
+    .option('--no-auto-merge', 'Do not apply the auto-merge label')
     .option('--no-wait', 'Skip waiting for analysis results')
+    .option('--json', 'Machine-readable: one JSON document on stdout (see `haystack schema submit`), progress on stderr')
     .option('--max-turns <n>', 'Max agentic turns per triage checker (overrides .haystack.json triage.maxTurns)', (v) => parseInt(v, 10))
     .option('--triage-timeout <seconds>', 'Wall-clock timeout per triage checker in seconds (overrides .haystack.json triage.timeoutMs)', (v) => parseInt(v, 10))
     .addHelpText('after', `
@@ -295,8 +307,22 @@ Review Routing:
                          needs-assignment queue (a teammate will pick it up)
   • --review <username>  Same label, plus requests review from that GitHub user
 
+Machine-readable output (--json):
+  stdout carries exactly one JSON document (schema: \`haystack schema submit\`);
+  all progress goes to stderr. On success the payload includes the PR ref,
+  the resolved title/body and their sources, auto-merge/auto-fix state with
+  source, and the analysis outcome. On failure it is an error envelope
+  { status: "error", error: "..." }.
+
+Exit codes:
+  0  PR created/updated (including verdict "needs_input" — the PR exists;
+     read the verdict from the JSON or from \`haystack triage\`)
+  1  Hard failure (bad flags, auth, push, PR creation, blocking triage
+     findings, or the analysis status check itself failing)
+
 Examples:
   haystack submit                      # Recommended: triage, create PR, auto-merge queue
+  haystack submit --json               # Agent mode: JSON on stdout, progress on stderr
   haystack submit --force              # Skip triage
   haystack submit --no-wait            # Don't wait for analysis
   haystack submit --title "Fix auth"   # Custom PR title
@@ -311,17 +337,23 @@ Examples:
   haystack submit --max-turns 12       # Raise triage turn cap to 12 per checker
   haystack submit --triage-timeout 300 # Raise triage wall-clock to 5 minutes
 `)
-    .action(async (options) => {
-    // Resolve --auto-merge default from .haystack.json when not explicitly set
-    if (options.autoMerge === undefined) {
+    .action(async (options, command) => {
+    // Resolve --auto-merge / --auto-fix defaults from .haystack.json when not
+    // explicitly set, and record WHERE each value came from so submit can
+    // announce the source (silent config-driven defaults are invisible to
+    // the caller otherwise).
+    const autoMergeFromCli = command.getOptionValueSource('autoMerge') === 'cli';
+    const autoFixFromCli = command.getOptionValueSource('autoFix') === 'cli';
+    if (!autoMergeFromCli) {
         options.autoMerge = await isAutoMergeEnabled();
     }
-    // Resolve --auto-fix default from .haystack.json (preferences.auto_fix).
     // Auto-fix remains alpha — the explicit --auto-fix flag still surfaces
     // discouragement warnings; opting in via repo config is the supported path.
-    if (options.autoFix === undefined) {
+    if (!autoFixFromCli) {
         options.autoFix = await isAutoFixEnabled();
     }
+    options.autoMergeSource = autoMergeFromCli ? 'flag' : 'config';
+    options.autoFixSource = autoFixFromCli ? 'flag' : 'config';
     return submitCommand(options);
 });
 program
@@ -363,35 +395,36 @@ inbox
     .command('list')
     .description('List PRs in your Haystack inbox')
     .option('--json', 'Output as JSON')
-    .action((options) => runPublicCommand(() => inboxListCommand(options)));
+    .action((options) => runPublicCommand(() => inboxListCommand(options), options.json));
 const prProgram = program.command('pr').description('Inspect one pull request');
 prProgram
     .command('get <ref>')
     .description('Get triage, merge blockers, and trace availability')
     .option('--json', 'Output as JSON')
-    .action((ref, options) => runPublicCommand(() => prReadCommand(ref, options)));
+    .action((ref, options) => runPublicCommand(() => prReadCommand(ref, options), options.json));
 program
     .command('ask <ref> <question>')
     .description('Ask Haystack about a pull request')
     .option('--json', 'Output the answer and every consulted customer-facing source as JSON')
     .option('--session <id>', 'Continue a previous Ask Haystack session')
-    .action((ref, question, options) => runPublicCommand(() => askHaystackCommand(ref, question, options)));
+    .action((ref, question, options) => runPublicCommand(() => askHaystackCommand(ref, question, options), options.json));
 const traces = program.command('traces').description('Inspect customer-owned Entire traces');
 traces
     .command('list <ref>')
     .description('List retained checkpoints for a pull request')
     .option('--json', 'Output as JSON')
-    .action((ref, options) => runPublicCommand(() => tracesListCommand(ref, options)));
+    .action((ref, options) => runPublicCommand(() => tracesListCommand(ref, options), options.json));
 traces
     .command('get <ref> <checkpoint>')
     .description('Get retained transcript chunks for one checkpoint')
     .option('--cursor <cursor>', 'Zero-based chunk cursor')
     .option('--limit <count>', 'Chunks per page', '20')
     .option('--json', 'Output as JSON')
-    .action((ref, checkpoint, options) => runPublicCommand(() => tracesGetCommand(ref, checkpoint, options)));
+    .action((ref, checkpoint, options) => runPublicCommand(() => tracesGetCommand(ref, checkpoint, options), options.json));
 program
     .command('dismiss <pr>')
     .description('Dismiss analysis findings for a PR')
+    .option('--json', 'Machine-readable output (see `haystack schema action`)')
     .addHelpText('after', `
 Dismiss analysis findings for a PR, moving it from "Issues Found" to
 "Good to Merge" in the Haystack feed.
@@ -413,6 +446,7 @@ Examples:
 program
     .command('mark-reviewed <pr>')
     .description('Mark human review as not needed for a PR')
+    .option('--json', 'Machine-readable output (see `haystack schema action`)')
     .addHelpText('after', `
 Mark human review as not needed for a PR, moving it from "Needs Review"
 to "Good to Merge" in the Haystack feed.
@@ -434,6 +468,7 @@ Examples:
 program
     .command('undismiss <pr>')
     .description('Undo a dismiss or mark-reviewed override for a PR')
+    .option('--json', 'Machine-readable output (see `haystack schema action`)')
     .addHelpText('after', `
 Clear all overrides (dismissed findings and/or review-not-needed) for a PR,
 returning it to its original feed bucket.
@@ -449,9 +484,39 @@ Examples:
   haystack undismiss acme/widgets#99     # Undo for specific repo
 `)
     .action(undismissCommand);
+program
+    .command('review [pr]')
+    .description('Trigger a fresh Haystack analysis for a PR (machine analysis — for HUMAN review use request-review)')
+    .option('--no-wait', 'Exit after triggering instead of waiting for results')
+    .option('--json', 'Machine-readable output (see `haystack schema action`)')
+    .addHelpText('after', `
+Re-run full Haystack analysis on a PR's current head.
+
+Haystack analyzes a PR once when it's opened (or marked ready); later
+pushes only get a resolution check against the existing findings. Use
+this command when new commits deserve fresh detection, or any time you
+want a second opinion.
+
+When called without a PR identifier, uses the last submitted PR.
+
+PR identifier formats:
+  (none)                                  Last submitted PR
+  123                                     PR number (uses current repo)
+  #123                                    PR number with hash
+  owner/repo#123                          Fully qualified
+  https://github.com/owner/repo/pull/123  GitHub URL
+
+Examples:
+  haystack review                             # Last submitted PR
+  haystack review 42                          # Current repo, PR #42
+  haystack review acme/widgets#99             # Specific repo
+  haystack review 42 --no-wait                # Trigger and exit
+`)
+    .action(reviewCommand);
 program
     .command('request-review <pr> [reviewer]')
     .description('Tag a PR as needing human review')
+    .option('--json', 'Machine-readable output (see `haystack schema action`)')
     .addHelpText('after', `
 Tag any PR with "needs human review", even after it was created.
 Adds the haystack:needs-review label to the PR, moving it from
@@ -522,9 +587,9 @@ config
     .description('Auto-merge safe PRs submitted via haystack submit (on|off|status)')
     .addHelpText('after', `
 Actions:
-  on, enable    Enable auto-merge for safe PRs
-  off, disable  Disable auto-merge
-  status        Show current status (default)
+  on, enable, true     Enable auto-merge for safe PRs
+  off, disable, false  Disable auto-merge
+  status               Show current status (default)
 
 When enabled, PRs submitted via \`haystack submit\` will be
 automatically merged if Haystack analysis finds no issues
@@ -542,9 +607,9 @@ config
     .description('(Alpha) Auto-fix mechanical issues on PRs submitted via haystack submit (on|off|status)')
     .addHelpText('after', `
 Actions:
-  on, enable    Enable auto-fix for mechanical issues
-  off, disable  Disable auto-fix
-  status        Show current status (default)
+  on, enable, true     Enable auto-fix for mechanical issues
+  off, disable, false  Disable auto-fix
+  status               Show current status (default)
 
 ⚠ Auto-fix is alpha. When enabled, PRs submitted via \`haystack submit\`
 are labeled haystack:auto-fix. The Haystack analysis pipeline then
@@ -853,6 +918,38 @@ rules
         process.exit(1);
     }
 });
+// ─── system-map ──────────────────────────────────────────────────────────────
+const systemMap = program
+    .command('system-map')
+    .description('Manage .haystack/system.yml — runtime facts that help Haystack QA run your system');
+systemMap
+    .command('validate')
+    .description('Check .haystack/system.yml against the rules Haystack QA will apply')
+    .option('--json', 'Machine-readable result')
+    .addHelpText('after', `
+The system map holds VERIFIED facts about how your system works — install/
+build commands, how services boot and signal readiness, seed/reset commands,
+dev-only test logins, external services that must never be touched live, and
+prebuilt CI artifacts. Haystack QA uses these facts to run more of what it
+already wants to test; the file never selects tests.
+
+Author it with the /map-your-system skill (haystack skills install), then run
+this before committing. Checks: valid YAML + version, no test-selection keys,
+no secret values, non-empty boot/login/run commands, artifact declarations.
+
+Examples:
+  haystack system-map validate
+  haystack system-map validate --json
+`)
+    .action(async (opts) => {
+    try {
+        await systemMapValidateCommand(opts);
+    }
+    catch (err) {
+        console.error(chalk.red('validate failed:'), err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
 // ─── mcp ─────────────────────────────────────────────────────────────────────
 program
     .command('mcp')

package/dist/schema.d.ts

@@ -13,9 +13,13 @@ export declare const SCHEMA_VERSIONS: {
     readonly triage: "2.0.0";
     readonly setup: "1.0.0";
     readonly pr: "2.0.0";
+    readonly 'pr-status': "1.0.0";
     readonly inbox: "1.0.0";
     readonly ask: "1.0.0";
     readonly traces: "1.0.0";
+    readonly submit: "1.0.0";
+    readonly action: "1.0.0";
+    readonly error: "1.0.0";
 };
 export type SchemaName = keyof typeof SCHEMA_VERSIONS;
 /** Wrap a payload with the `schema_version` envelope. */

package/dist/schema.js

@@ -13,9 +13,13 @@ export const SCHEMA_VERSIONS = {
     triage: '2.0.0',
     setup: '1.0.0',
     pr: '2.0.0',
+    'pr-status': '1.0.0',
     inbox: '1.0.0',
     ask: '1.0.0',
     traces: '1.0.0',
+    submit: '1.0.0',
+    action: '1.0.0',
+    error: '1.0.0',
 };
 /** Wrap a payload with the `schema_version` envelope. */
 export function withSchema(name, payload) {

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/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

@@ -110,6 +110,39 @@ export type AnalysisReadyResult = {
     status: 'error';
     message: string;
 };
+export type TriggerAnalysisResult = {
+    status: 'started';
+    requestId: string;
+} | {
+    status: 'already_processing';
+    requestId: string;
+} | {
+    status: 'rate_limited';
+    message: string;
+    retryAfterSeconds?: number;
+} | {
+    status: 'denied';
+    message: string;
+} | {
+    status: 'error';
+    message: string;
+};
+/**
+ * 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 declare function triggerAnalysis(owner: string, repo: string, prNumber: number, token: string, headSha?: string): Promise<TriggerAnalysisResult>;
+export type TriggerRunStatus = 'pending' | 'COMPLETED' | 'FAILED' | 'SUPERSEDED' | 'error';
+/**
+ * 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 declare function fetchTriggerStatus(requestId: string, token: string): Promise<{
+    status: TriggerRunStatus;
+    message?: string;
+}>;
 /**
  * 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.
@@ -139,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>;