@haystackeditor/cli 0.15.10 → 0.15.12

package/dist/utils/analysis-api.js

@@ -10,17 +10,54 @@
 // ============================================================================
 // Constants
 // ============================================================================
-const PROD_API_BASE = 'https://8z9ssbamdj.execute-api.us-west-2.amazonaws.com/prod';
+/**
+ * Analysis API base.
+ *
+ * IMPORTANT: this used to point directly at AWS API Gateway. That worked
+ * when the CLI carried a GitHub token (X-GitHub-Token header to the
+ * Lambda), but BROKE for `haystack login --headless` users — an
+ * hsk_live_* token would land on AWS as if it were a GH token, the
+ * Lambda would 401, and triage / pr / chat / MCP would silently return
+ * nothing. The right move is to route reads through the auth-worker,
+ * which:
+ *
+ *   1. Knows how to introspect hsk_live tokens (and GH tokens, agent JWTs,
+ *      session cookies) — single normalized auth path.
+ *   2. Applies the hsk_live scope gate (denyForCliScope) before forwarding
+ *      to AWS, so a repo-scoped CI token can't read other repos' synthesis.
+ *   3. Adds the right backend token (install token for org-installed reads,
+ *      fallback otherwise) — so private-repo reads work without the CLI
+ *      ever holding a GH token.
+ *
+ * Override with HAYSTACK_API_BASE for local dev (e.g., http://localhost:8788
+ * pointing at a local auth-worker).
+ */
+const ANALYSIS_API_BASE = process.env.HAYSTACK_API_BASE ?? 'https://haystackeditor.com';
+/** Build the auth-worker URL for a v3 result file (rating_synthesis.json, etc). */
+function v3ResultUrl(owner, repo, prNumber, file) {
+    // The auth-worker exposes `/api/analysis/{prIdentifier}/{file}` (see
+    // V3_API_PATTERNS in infra/auth-worker/index.js). prIdentifier format:
+    // owner/repo#prnum, URL-encoded as %2F + %23.
+    const prId = encodeURIComponent(`${owner}/${repo}#${prNumber}`);
+    return `${ANALYSIS_API_BASE}/api/analysis/${prId}${file ? `/${file}` : ''}`;
+}
 // ============================================================================
 // API helpers
 // ============================================================================
+/**
+ * Build headers for an auth-worker-proxied analysis request.
+ *
+ * Auth-worker accepts hsk_live_*, GH tokens, agent JWTs, and session
+ * cookies on `Authorization: Bearer`. The legacy `X-GitHub-Token` header
+ * targeted AWS directly and is no longer used.
+ */
 function apiHeaders(token) {
     const headers = {
         'Cache-Control': 'no-cache',
         'User-Agent': 'Haystack-CLI',
     };
     if (token) {
-        headers['X-GitHub-Token'] = token;
+        headers['Authorization'] = `Bearer ${token}`;
     }
     return headers;
 }
@@ -32,7 +69,7 @@ function apiHeaders(token) {
  * Returns 'ready' if complete, 'pending' if not yet available, or 'error' for server failures.
  */
 export async function checkAnalysisReady(owner, repo, prNumber, token) {
-    const url = `${PROD_API_BASE}/v3/result/${owner}/${repo}/${prNumber}`;
+    const url = v3ResultUrl(owner, repo, prNumber);
     let response;
     try {
         response = await fetch(url, {
@@ -57,97 +94,130 @@ export async function checkAnalysisReady(owner, repo, prNumber, token) {
     return data.status === 'COMPLETED' ? { status: 'ready' } : { status: 'pending' };
 }
 /**
- * Fetch analysis results once complete. Combines bug detection and rule violations.
+ * Fetch analysis results once complete. Used by `haystack submit`'s
+ * wait-for-triage loop to render a verdict block.
+ *
+ * Verdict semantics — three distinct signals, never conflated:
+ *
+ *   state                 = is the analysis itself clean?
+ *                           → 'good-to-merge' iff analysisVerdict === 'clean'
+ *                              AND !needsHumanReview. canAutoMerge is NOT
+ *                              the source of truth (it only means "analysis
+ *                              would let this through" — review policy,
+ *                              grace period, or a missing auto-merge label
+ *                              can still block).
+ *                              Falls back to haystackRating ≥ 5 only when
+ *                              analysisVerdict is absent (legacy payloads).
+ *   needsHumanReview      = preserved on the return shape so callers can
+ *                           distinguish "clean + needs human" from clean.
+ *   autoMerged            = was the PR ACTUALLY merged? Read from the
+ *                           GitHub REST endpoint, not from anything in
+ *                           the synthesis. canAutoMerge is eligibility,
+ *                           not outcome — never claim "auto-merged" from
+ *                           the analysis side.
+ *
+ * Sources from the v3 rating-synthesis path (auth-worker-proxied — so
+ * hsk_live tokens, GH tokens, agent JWTs, and cookies all work, and the
+ * scope gate runs). The legacy v2 bug-detection / rule-violation /
+ * merge-decision JSONs are no longer queried (no auth-worker proxy).
  */
-export async function fetchAnalysisResults(owner, repo, prNumber, token) {
-    const prIdentifier = `${owner}/${repo}#${prNumber}`;
-    const encodedId = encodeURIComponent(prIdentifier);
-    const reviewUrl = `https://haystackeditor.com/review/${owner}/${repo}/${prNumber}`;
-    const issues = [];
-    // Fetch bug detection
-    try {
-        const bugUrl = `${PROD_API_BASE}/v2/analysis/${encodedId}/bug_detection.json`;
-        const bugResp = await fetch(bugUrl, {
-            headers: apiHeaders(token),
-        });
-        if (bugResp.ok) {
-            const bugData = await bugResp.json();
-            if (bugData.bugs) {
-                for (const bug of bugData.bugs) {
-                    issues.push({
-                        file: bug.file || 'unknown',
-                        line: bug.line,
-                        message: bug.description || 'Bug detected',
-                        severity: bug.severity === 'critical' || bug.severity === 'high' ? 'error' : 'warning',
-                        source: 'bug-detection',
-                    });
-                }
-            }
-        }
-    }
-    catch {
-        // Bug detection not available — not fatal
-    }
-    // Fetch rule violations
+async function isPrMerged(owner, repo, prNumber, token) {
+    // Authoritative merge check. We hit the same auth-worker proxy as the
+    // rest of the CLI so hsk_live / OAuth / install tokens all work, AND
+    // scope enforcement happens here too (a token not scoped to this repo
+    // would 403; we treat that as "unknown → not merged" rather than
+    // crashing the submit flow).
+    if (!token)
+        return false;
     try {
-        const rulesUrl = `${PROD_API_BASE}/v2/analysis/${encodedId}/rule_violations.json`;
-        const rulesResp = await fetch(rulesUrl, {
-            headers: apiHeaders(token),
+        const base = process.env.HAYSTACK_API_BASE ?? 'https://haystackeditor.com';
+        const res = await fetch(`${base}/api/github/repos/${owner}/${repo}/pulls/${prNumber}`, {
+            headers: {
+                Accept: 'application/vnd.github+json',
+                Authorization: `Bearer ${token}`,
+                'User-Agent': 'Haystack-CLI',
+            },
         });
-        if (rulesResp.ok) {
-            const rulesData = await rulesResp.json();
-            if (rulesData.violations) {
-                for (const v of rulesData.violations) {
-                    issues.push({
-                        file: v.file || 'unknown',
-                        line: v.line,
-                        message: v.message || `Rule violation: ${v.rule || 'unknown'}`,
-                        severity: v.severity === 'error' ? 'error' : 'warning',
-                        source: 'rule-violation',
-                    });
-                }
-            }
-        }
+        if (!res.ok)
+            return false;
+        const data = (await res.json());
+        return data.merged === true;
     }
     catch {
-        // Rule violations not available — not fatal
+        return false;
     }
-    // Fetch merge decision (to check if auto-merged)
-    let autoMerged = false;
-    try {
-        const mergeUrl = `${PROD_API_BASE}/v2/analysis/${encodedId}/merge_decision.json`;
-        const mergeResp = await fetch(mergeUrl, {
-            headers: apiHeaders(token),
-        });
-        if (mergeResp.ok) {
-            const mergeData = await mergeResp.json();
-            autoMerged = mergeData.autoMerged === true;
-        }
+}
+export async function fetchAnalysisResults(owner, repo, prNumber, token) {
+    const reviewUrl = `https://haystackeditor.com/review/${owner}/${repo}/${prNumber}`;
+    const [synthesis, autoMerged] = await Promise.all([
+        fetchRatingSynthesis(owner, repo, prNumber, token),
+        isPrMerged(owner, repo, prNumber, token),
+    ]);
+    if (!synthesis) {
+        return {
+            state: 'needs-input',
+            bugCount: 0,
+            warningCount: 0,
+            ruleViolationCount: 0,
+            summary: 'Analysis is ready but synthesis could not be loaded.',
+            issues: [],
+            reviewUrl,
+            autoMerged,
+        };
     }
-    catch {
-        // Merge decision not available — not fatal
-    }
-    const bugCount = issues.filter(i => i.source === 'bug-detection').length;
-    const ruleViolationCount = issues.filter(i => i.source === 'rule-violation').length;
-    const warningCount = issues.filter(i => i.severity === 'warning').length;
-    const errorCount = issues.filter(i => i.severity === 'error').length;
-    const state = errorCount === 0 && warningCount === 0 ? 'good-to-merge' : 'needs-input';
-    // Build summary
+    const display = synthesis.synthesisDisplay ?? [];
+    const issues = display.map((d) => ({
+        file: 'unknown', // synthesis findings don't always carry a path; the rich data lives on the feed
+        message: d.summary || d.detail || `Finding (${d.category})`,
+        severity: 'warning',
+        // Map the synthesis source onto the verdict's two-bucket model.
+        // Anything other than an explicit rule violation lands on bug-detection.
+        source: d.source === 'rule-violation' ? 'rule-violation' : 'bug-detection',
+    }));
+    const bugCount = issues.filter((i) => i.source === 'bug-detection').length;
+    const ruleViolationCount = issues.filter((i) => i.source === 'rule-violation').length;
+    const warningCount = issues.length;
+    // Three discrete signals, NEVER conflated:
+    //   verdictKind     : 'clean' | 'has-issues' | 'needs-review'
+    //                     (legacy payloads without analysisVerdict fall back
+    //                     to haystackRating ≥ 5 → 'clean')
+    //   needsHumanReview: true if review policy demands a human, OR if the
+    //                     orchestrator escalated verdict to 'needs-review'
+    //                     (which carries the same semantic).
+    //   analysisIsClean : true iff verdict is 'clean' OR 'needs-review'
+    //                     (both mean: no bugs/violations were found; the
+    //                     review-policy gate is the separate axis).
+    //
+    // good-to-merge = analysis clean AND no human required.
+    // 'has-issues'   → state 'needs-input'.
+    // 'needs-review' → state 'needs-input' + needsHumanReview true.
+    // 'clean' + needsHumanReview → same as 'needs-review' (defensive — the
+    //  orchestrator should already have escalated, but we handle the case
+    //  where it didn't).
+    const verdictKind = synthesis.analysisVerdict
+        ?? (synthesis.haystackRating >= 5 ? 'clean' : 'has-issues');
+    const analysisIsClean = verdictKind === 'clean' || verdictKind === 'needs-review';
+    const needsHumanReview = synthesis.needsHumanReview === true || verdictKind === 'needs-review';
+    const isGoodToMerge = analysisIsClean && !needsHumanReview;
+    const state = isGoodToMerge ? 'good-to-merge' : 'needs-input';
     let summary;
     if (state === 'good-to-merge') {
-        summary = autoMerged ? 'No issues found. PR was auto-merged.' : 'No issues found. Safe to merge.';
+        summary = autoMerged
+            ? 'No blocking issues. PR was merged.'
+            : 'No blocking issues. Safe to merge.';
+    }
+    else if (analysisIsClean && needsHumanReview) {
+        summary = 'Analysis is clean, but review policy requires a human reviewer.';
     }
     else {
         const parts = [];
-        if (errorCount > 0)
-            parts.push(`${errorCount} error(s)`);
-        if (warningCount > 0)
-            parts.push(`${warningCount} warning(s)`);
         if (bugCount > 0)
-            parts.push(`${bugCount} bug(s)`);
+            parts.push(`${bugCount} finding(s)`);
         if (ruleViolationCount > 0)
             parts.push(`${ruleViolationCount} rule violation(s)`);
-        summary = parts.join(', ') + ' found.';
+        summary = parts.length > 0
+            ? parts.join(', ') + ' found.'
+            : `Rating ${synthesis.haystackRating}/5 — see the feed for details.`;
     }
     return {
         state,
@@ -158,10 +228,11 @@ export async function fetchAnalysisResults(owner, repo, prNumber, token) {
         issues,
         reviewUrl,
         autoMerged,
+        needsHumanReview,
     };
 }
 export async function fetchAutoFixManifest(owner, repo, prNumber, token) {
-    const url = `${PROD_API_BASE}/v3/result/${owner}/${repo}/${prNumber}/auto-fix-manifest.json`;
+    const url = v3ResultUrl(owner, repo, prNumber, 'auto-fix-manifest.json');
     try {
         const response = await fetch(url, {
             headers: apiHeaders(token),
@@ -184,8 +255,10 @@ export async function fetchAutoFixManifest(owner, repo, prNumber, token) {
     }
 }
 export async function fetchRatingSynthesis(owner, repo, prNumber, token) {
-    // Use v3/result endpoint (same as the Lambda serves generic files)
-    const url = `${PROD_API_BASE}/v3/result/${owner}/${repo}/${prNumber}/rating_synthesis.json`;
+    // Route through the auth-worker (/api/analysis/{prId}/rating_synthesis.json)
+    // so hsk_live tokens are introspected and the scope gate applies — see
+    // ANALYSIS_API_BASE comment above.
+    const url = v3ResultUrl(owner, repo, prNumber, 'rating_synthesis.json');
     try {
         const response = await fetch(url, {
             headers: apiHeaders(token),

package/dist/utils/auth.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Path to a long-lived `hsk_live_*` token created by `haystack login --headless`.
+ * If present (or HAYSTACK_CLI_TOKEN is set), it takes priority over the
+ * regular OAuth credentials. CI environments use this exclusively.
+ *
+ * Why a separate file (not just an entry in credentials.json):
+ *   1. Different lifecycle — the OAuth flow renews + refreshes; hsk_live
+ *      tokens are mint-once-revoke-never until explicit revocation.
+ *   2. Easier to commit accidentally and easier to .gitignore (one file).
+ *   3. Different shape — hsk_live tokens carry server-side scope that the
+ *      OAuth token doesn't, and we don't want to model both in one schema.
+ */
+export declare const HEADLESS_TOKEN_FILE: string;
+interface HeadlessTokenFile {
+    token: string;
+    id?: string;
+    label?: string;
+    created_at?: string;
+}
 export interface StoredAccount {
     github_token: string;
     created_at: string;
@@ -46,5 +65,15 @@ export declare function removeAccount(login?: string): Promise<string | null>;
 export declare function getActiveLogin(): Promise<string | null>;
 export declare function getRepoDefaultAccount(owner: string, repo: string): Promise<string | null>;
 export declare function setRepoDefaultAccount(owner: string, repo: string, login: string): Promise<void>;
+/** Thrown by {@link resolveAuthContext} when no usable credential is found. */
+export declare class NotLoggedInError extends Error {
+    constructor(message?: string);
+}
+/** Read the headless CLI token if one is configured. Env var wins over the
+ *  on-disk file so CI can override without touching the home directory. */
+export declare function readHeadlessToken(): Promise<HeadlessTokenFile | null>;
+export declare function writeHeadlessToken(record: HeadlessTokenFile): Promise<string>;
+export declare function clearHeadlessToken(): Promise<void>;
 export declare function resolveAuthContext(options?: ResolveAuthOptions): Promise<ResolvedAuthContext>;
 export declare function loadToken(options?: ResolveAuthOptions): Promise<string | null>;
+export {};

package/dist/utils/auth.js

@@ -4,6 +4,20 @@ import * as path from 'path';
 const CONFIG_DIR = path.join(os.homedir(), '.haystack');
 const TOKEN_FILE = path.join(CONFIG_DIR, 'credentials.json');
 const TOKEN_FILE_DISPLAY = '~/.haystack/credentials.json';
+/**
+ * Path to a long-lived `hsk_live_*` token created by `haystack login --headless`.
+ * If present (or HAYSTACK_CLI_TOKEN is set), it takes priority over the
+ * regular OAuth credentials. CI environments use this exclusively.
+ *
+ * Why a separate file (not just an entry in credentials.json):
+ *   1. Different lifecycle — the OAuth flow renews + refreshes; hsk_live
+ *      tokens are mint-once-revoke-never until explicit revocation.
+ *   2. Easier to commit accidentally and easier to .gitignore (one file).
+ *   3. Different shape — hsk_live tokens carry server-side scope that the
+ *      OAuth token doesn't, and we don't want to model both in one schema.
+ */
+export const HEADLESS_TOKEN_FILE = path.join(CONFIG_DIR, 'cli-token');
+const HEADLESS_TOKEN_FILE_DISPLAY = '~/.haystack/cli-token';
 const GITHUB_LOGIN_PATTERN = /^[A-Za-z\d](?:[A-Za-z\d]|-(?=[A-Za-z\d])){0,38}$/;
 function emptyStore() {
     return {
@@ -337,7 +351,60 @@ export async function setRepoDefaultAccount(owner, repo, login) {
     store.repoDefaults[key] = storedLogin;
     await saveStore(store);
 }
+/** Thrown by {@link resolveAuthContext} when no usable credential is found. */
+export class NotLoggedInError extends Error {
+    constructor(message = 'Not logged in. Run `haystack login` first.') {
+        super(message);
+        this.name = 'NotLoggedInError';
+    }
+}
+/** Read the headless CLI token if one is configured. Env var wins over the
+ *  on-disk file so CI can override without touching the home directory. */
+export async function readHeadlessToken() {
+    const envToken = process.env.HAYSTACK_CLI_TOKEN;
+    if (envToken && envToken.startsWith('hsk_live_')) {
+        return { token: envToken, label: 'env:HAYSTACK_CLI_TOKEN' };
+    }
+    try {
+        const raw = await fs.readFile(HEADLESS_TOKEN_FILE, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.token === 'string' && parsed.token.startsWith('hsk_live_')) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeHeadlessToken(record) {
+    await fs.mkdir(CONFIG_DIR, { recursive: true });
+    // 0600 so other users on a shared machine can't read the token. The file
+    // contains a long-lived credential — mode matters here in a way that doesn't
+    // for credentials.json, which can be re-minted via OAuth at any time.
+    await fs.writeFile(HEADLESS_TOKEN_FILE, JSON.stringify(record, null, 2) + '\n', {
+        mode: 0o600,
+    });
+    return HEADLESS_TOKEN_FILE_DISPLAY;
+}
+export async function clearHeadlessToken() {
+    try {
+        await fs.unlink(HEADLESS_TOKEN_FILE);
+    }
+    catch { /* not present is fine */ }
+}
 export async function resolveAuthContext(options = {}) {
+    // hsk_live tokens win unconditionally. They were created explicitly by
+    // the operator with `haystack login --headless` (or set via env in CI)
+    // — that intent should not be overridden by a stale OAuth cookie.
+    const headless = await readHeadlessToken();
+    if (headless) {
+        return {
+            login: headless.label ?? 'headless',
+            token: headless.token,
+            source: 'active',
+        };
+    }
     const store = await loadCredentialsStore();
     const { preferredLogin, owner, repo } = options;
     if (preferredLogin) {
@@ -370,7 +437,7 @@ export async function resolveAuthContext(options = {}) {
             source: 'active',
         };
     }
-    throw new Error('Not logged in. Run `haystack login` first.');
+    throw new NotLoggedInError();
 }
 export async function loadToken(options = {}) {
     try {
@@ -378,7 +445,8 @@ export async function loadToken(options = {}) {
         return context.token;
     }
     catch (error) {
-        if (error instanceof Error && error.message.startsWith('Not logged in.')) {
+        // Classify by type, not message text (see pr-rules.yml PR007).
+        if (error instanceof NotLoggedInError) {
             return null;
         }
         throw error;

package/dist/utils/git.d.ts

@@ -68,6 +68,10 @@ export interface PushAuth {
  * Without `auth`, falls back to `git push -u <remote>` using ambient creds.
  */
 export declare function pushBranch(remoteName: string, branchName: string, auth?: PushAuth): void;
+/** Thrown when a git remote URL is not a recognized GitHub SSH/HTTPS URL. */
+export declare class UnsupportedRemoteUrlError extends Error {
+    constructor(url: string);
+}
 /**
  * Parse remote URL to extract owner and repo
  * Supports both SSH and HTTPS URLs
@@ -86,6 +90,38 @@ export declare function getLastCommitSha(): string;
  * Returns the combined log, or empty string if no commits or on error.
  */
 export declare function getCommitMessagesSinceBase(baseBranch: string): string;
+/**
+ * Resolve the git ref to diff a PR branch against for review.
+ *
+ * A bare local `<base>` ref is frequently stale (not checked out or pulled in a
+ * while). When it sits behind HEAD's true fork point, the three-dot merge-base
+ * jumps far back in history and inflates the review diff to include code from
+ * already-merged PRs — reviewers then mis-attribute pre-existing code to this
+ * PR. So we prefer the freshly-fetched remote base. This mirrors
+ * getCommitMessagesSinceBase, which already compares against the remote base.
+ *
+ * Returns a fully-qualified ref (`refs/remotes/origin/<base>` or
+ * `refs/heads/<base>`) so a tag that happens to share the name can never shadow
+ * the ref we mean — `git rev-parse <name>` prefers refs/tags/* over both
+ * refs/heads/* and refs/remotes/*. The bare `<base>` name is only returned as a
+ * last resort when nothing qualified resolves (the eventual `git diff` then
+ * errors and the caller falls back to running it itself).
+ *
+ * Resolution:
+ *   1. Best-effort fetch the remote base (`haystack submit` is already online —
+ *      it pushes and opens a PR — so one ref fetch is cheap).
+ *   2. If the fetch succeeded, the remote-tracking ref is the authoritative
+ *      remote tip — use it (even over a local <base> with unpushed commits; the
+ *      PR will merge into the remote base, not the local one).
+ *   3. If the fetch failed (offline, private origin without ambient git creds,
+ *      base not on remote), don't blindly trust a possibly-stale *cached*
+ *      remote-tracking ref — pick whichever of it and local <base> is more
+ *      advanced (the one that is not an ancestor of the other), since a base
+ *      behind HEAD's fork point is exactly what balloons the diff.
+ *   4. Fall back to whatever single qualified ref resolves, then the bare
+ *      <base> name (preserves prior behavior rather than breaking triage).
+ */
+export declare function resolveDiffBaseRef(baseBranch: string): string;
 /**
  * Get the number of commits ahead of base branch
  */

package/dist/utils/git.js

@@ -257,6 +257,13 @@ function translatePushError(err, repoSlug) {
 // ============================================================================
 // Remote operations
 // ============================================================================
+/** Thrown when a git remote URL is not a recognized GitHub SSH/HTTPS URL. */
+export class UnsupportedRemoteUrlError extends Error {
+    constructor(url) {
+        super(`Unsupported remote URL format: ${url}`);
+        this.name = 'UnsupportedRemoteUrlError';
+    }
+}
 /**
  * Parse remote URL to extract owner and repo
  * Supports both SSH and HTTPS URLs
@@ -285,10 +292,13 @@ export function parseRemoteUrl(remoteName = 'origin') {
                 remoteName,
             };
         }
-        throw new Error(`Unsupported remote URL format: ${url}`);
+        throw new UnsupportedRemoteUrlError(url);
     }
     catch (err) {
-        if (err instanceof Error && err.message.includes('Unsupported')) {
+        // Propagate the "unrecognized URL" case as-is; wrap everything else (the
+        // `git remote get-url` command itself failing) in a friendlier message.
+        // 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}'`);
@@ -356,6 +366,107 @@ export function getCommitMessagesSinceBase(baseBranch) {
         }
     }
 }
+/** True if `ref` resolves to a commit in the current repo. */
+function gitRefResolves(ref) {
+    try {
+        execSync(`git rev-parse --verify --quiet ${ref}^{commit}`, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** True if `ancestor` is an ancestor of (or equal to) `descendant`. */
+function gitIsAncestor(ancestor, descendant) {
+    try {
+        // exit 0 => ancestor; exit 1 => not; both non-throwing for us via stdio pipe
+        execSync(`git merge-base --is-ancestor ${ancestor} ${descendant}`, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the git ref to diff a PR branch against for review.
+ *
+ * A bare local `<base>` ref is frequently stale (not checked out or pulled in a
+ * while). When it sits behind HEAD's true fork point, the three-dot merge-base
+ * jumps far back in history and inflates the review diff to include code from
+ * already-merged PRs — reviewers then mis-attribute pre-existing code to this
+ * PR. So we prefer the freshly-fetched remote base. This mirrors
+ * getCommitMessagesSinceBase, which already compares against the remote base.
+ *
+ * Returns a fully-qualified ref (`refs/remotes/origin/<base>` or
+ * `refs/heads/<base>`) so a tag that happens to share the name can never shadow
+ * the ref we mean — `git rev-parse <name>` prefers refs/tags/* over both
+ * refs/heads/* and refs/remotes/*. The bare `<base>` name is only returned as a
+ * last resort when nothing qualified resolves (the eventual `git diff` then
+ * errors and the caller falls back to running it itself).
+ *
+ * Resolution:
+ *   1. Best-effort fetch the remote base (`haystack submit` is already online —
+ *      it pushes and opens a PR — so one ref fetch is cheap).
+ *   2. If the fetch succeeded, the remote-tracking ref is the authoritative
+ *      remote tip — use it (even over a local <base> with unpushed commits; the
+ *      PR will merge into the remote base, not the local one).
+ *   3. If the fetch failed (offline, private origin without ambient git creds,
+ *      base not on remote), don't blindly trust a possibly-stale *cached*
+ *      remote-tracking ref — pick whichever of it and local <base> is more
+ *      advanced (the one that is not an ancestor of the other), since a base
+ *      behind HEAD's fork point is exactly what balloons the diff.
+ *   4. Fall back to whatever single qualified ref resolves, then the bare
+ *      <base> name (preserves prior behavior rather than breaking triage).
+ */
+export function resolveDiffBaseRef(baseBranch) {
+    const remoteRef = `refs/remotes/origin/${baseBranch}`;
+    const localRef = `refs/heads/${baseBranch}`;
+    // Freshen the remote base so the merge-base reflects the true fork point.
+    // Fetch with a fully-qualified refspec rather than a bare
+    // `git fetch origin <base>`:
+    //   - Explicit destination: in clones whose configured fetch refspec does
+    //     not cover <base> — a `--single-branch` clone, or `haystack submit
+    //     --base release/x` — a bare fetch updates only FETCH_HEAD and leaves
+    //     refs/remotes/origin/<base> stale or absent.
+    //   - Qualified source (`refs/heads/<base>`): if the remote has both a
+    //     branch and a tag named <base> (e.g. a `release` / `v1.0` base), an
+    //     unqualified source could resolve to the tag and force the
+    //     remote-tracking ref to it, making triage diff against the tag.
+    // `+` force-updates the remote-tracking ref to the remote tip (correct even
+    // if <base> was rewound on the remote).
+    let fetched = false;
+    try {
+        execSync(`git fetch origin +refs/heads/${baseBranch}:${remoteRef}`, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        fetched = true;
+    }
+    catch {
+        // Offline / no creds / base not on remote — fall through to degraded
+        // selection below using whatever refs already exist locally.
+    }
+    const remoteResolves = gitRefResolves(remoteRef);
+    // Happy path: we just refreshed the remote base, so it's authoritative.
+    if (fetched && remoteResolves)
+        return remoteRef;
+    // Degraded path: fetch failed (or didn't produce the ref). Prefer the more
+    // up-to-date of the cached remote ref and the local branch; only a base that
+    // lags HEAD's fork point balloons the diff, so pick the one that's ahead.
+    const localResolves = gitRefResolves(localRef);
+    if (remoteResolves && localResolves) {
+        // If the remote ref is an ancestor of the local ref, local is ahead → use it.
+        return gitIsAncestor(remoteRef, localRef) ? localRef : remoteRef;
+    }
+    if (remoteResolves)
+        return remoteRef;
+    if (localResolves)
+        return localRef;
+    return baseBranch;
+}
 /**
  * Get the number of commits ahead of base branch
  */

package/dist/utils/prompter.js

@@ -139,7 +139,10 @@ class JsonPrompter {
         return id in this.answers;
     }
     emit(event) {
-        process.stdout.write(JSON.stringify(event) + '\n');
+        // Stamp every NDJSON event with the setup schema version so agent
+        // consumers can pin a contract. See docs/SPEC-CLI-FIRST-CLASS.md.
+        const stamped = { schema_version: '1.0.0', ...event };
+        process.stdout.write(JSON.stringify(stamped) + '\n');
     }
     /** Lazily open stdin only when we actually need an answer the agent must send. */
     ensureStdin() {