@haystackeditor/cli 0.15.19 → 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';
@@ -46,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
@@ -53,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;
     }
 }
@@ -112,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)')
@@ -247,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', `
@@ -296,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
@@ -312,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
@@ -364,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.
@@ -414,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.
@@ -435,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.
@@ -452,8 +486,9 @@ Examples:
     .action(undismissCommand);
 program
     .command('review [pr]')
-    .description('Trigger a fresh Haystack analysis for a 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.
 
@@ -481,6 +516,7 @@ Examples:
 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
@@ -551,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
@@ -571,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
@@ -882,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

@@ -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[]>;