@haystackeditor/cli 0.12.3 → 0.13.0

package/README.md

@@ -241,7 +241,7 @@ The `setup` wizard writes `.haystack.json` to your repos with discovered rules,
 ## How It Works
 
 1. Run `haystack setup` to configure your repos (or `haystack init` for local-only config)
-2. Install the [Haystack GitHub App](https://haystackeditor.com/github-app)
+2. Install the [Haystack GitHub App](https://github.com/apps/haystack-code-reviewer-pr-hook/installations/new)
 3. When PRs are opened, Haystack automatically:
    - Analyzes the code for bugs, instruction drift, and rule violations
    - Reports results on the PR

package/dist/commands/submit.d.ts

@@ -20,5 +20,7 @@ export interface SubmitOptions {
     wait?: boolean;
     autoFix?: boolean;
     autoMerge?: boolean;
+    maxTurns?: number;
+    triageTimeout?: number;
 }
 export declare function submitCommand(options: SubmitOptions): Promise<void>;

package/dist/commands/submit.js

@@ -14,6 +14,7 @@ import fs from 'fs';
 import { findGitRoot, getCurrentBranch, getDefaultBranch, hasUncommittedChanges, parseRemoteUrl, pushBranch, getLastCommitMessage, getCommitMessagesSinceBase, } from '../utils/git.js';
 import { createPullRequest, findExistingPR, requireGitHubAuth, requestReviewers, } from '../utils/github-api.js';
 import { runTriage } from '../triage/runner.js';
+import { loadConfig } from '../utils/config.js';
 import { checkAnalysisReady, fetchAnalysisResults } from '../utils/analysis-api.js';
 import { savePendingSubmit, updatePendingSubmit } from '../utils/pending-state.js';
 import { ensureHaystackLabels, addLabelsToIssue, } from '../utils/github-api.js';
@@ -54,6 +55,47 @@ function checkerDisplayName(checker) {
         default: return checker;
     }
 }
+/**
+ * Merge triage-tuning knobs from two sources, in ascending precedence:
+ *   defaults (in runner.ts) < .haystack.json triage.* < CLI flags
+ *
+ * --max-turns <N> applies the same number to every checker. Per-checker
+ * granularity stays in .haystack.json (less common, more verbose).
+ */
+async function resolveTriageOptions(options) {
+    let config = null;
+    try {
+        config = await loadConfig();
+    }
+    catch (err) {
+        // loadConfig returns null when the file doesn't exist — it only throws on
+        // read/parse failures, which we must surface so a malformed config doesn't
+        // silently lose the user's project-level triage overrides.
+        console.warn(chalk.yellow(`⚠ Could not load .haystack.json: ${err.message}`));
+        console.warn(chalk.dim('  Triage will use CLI flags / defaults — fix the config to apply project overrides.'));
+    }
+    const triageConfig = config?.triage ?? {};
+    const maxTurns = { ...(triageConfig.maxTurns ?? {}) };
+    if (typeof options.maxTurns === 'number' && options.maxTurns > 0) {
+        for (const name of ['code-review', 'rules-validator', 'intent-drift']) {
+            maxTurns[name] = options.maxTurns;
+        }
+    }
+    // loadConfig does a raw `as HaystackConfig` cast (no Zod runtime parse), so
+    // malformed .haystack.json values can reach us as strings/negatives/NaN.
+    // Mirror the positive-number guard we already apply to maxTurns before
+    // letting this flow into setTimeout.
+    const configTimeoutMs = typeof triageConfig.timeoutMs === 'number' && triageConfig.timeoutMs > 0
+        ? triageConfig.timeoutMs
+        : undefined;
+    const timeoutMs = typeof options.triageTimeout === 'number' && options.triageTimeout > 0
+        ? options.triageTimeout * 1000
+        : configTimeoutMs;
+    return {
+        maxTurns: Object.keys(maxTurns).length > 0 ? maxTurns : undefined,
+        timeoutMs,
+    };
+}
 function isCodexNetworkDisabledTriageError(err) {
     const message = err instanceof Error ? err.message : String(err);
     return message.includes('CODEX_SANDBOX_NETWORK_DISABLED=1');
@@ -80,11 +122,19 @@ function printTriageSummary(result) {
             console.log('');
         }
     }
-    // Errors from sub-agent failures
+    // Hard errors from sub-agent failures (auth, crashes) — these block submit.
     if (result.errors.length > 0) {
-        console.log(chalk.yellow('  Checker errors:'));
+        console.log(chalk.red('  Checker errors:'));
         for (const err of result.errors) {
-            console.log(chalk.yellow(`    ! ${err}`));
+            console.log(chalk.red(`    ✗ ${err}`));
+        }
+        console.log('');
+    }
+    // Soft failures (max turns, timeout) — non-blocking, purely informational.
+    if (result.warnings.length > 0) {
+        console.log(chalk.yellow('  Checker warnings (non-blocking):'));
+        for (const warn of result.warnings) {
+            console.log(chalk.yellow(`    ! ${warn}`));
         }
         console.log('');
     }
@@ -93,9 +143,14 @@ function printTriageSummary(result) {
     const errorCount = result.results.reduce((sum, r) => sum + r.issues.filter((i) => i.severity === 'error').length, 0);
     const warningCount = result.results.reduce((sum, r) => sum + r.issues.filter((i) => i.severity === 'warning').length, 0);
     const duration = (result.duration / 1000).toFixed(1);
-    if (result.passed) {
+    if (result.passed && result.results.length > 0) {
         console.log(chalk.green(`  All checks passed (${duration}s)\n`));
     }
+    else if (result.passed) {
+        // No blocking issues, but nothing actually completed either — the
+        // triage-unavailable warning will print separately.
+        console.log(chalk.yellow(`  No checkers produced results (${duration}s)\n`));
+    }
     else {
         const parts = [];
         if (errorCount > 0)
@@ -162,11 +217,17 @@ export async function submitCommand(options) {
     if (!options.force) {
         console.log(chalk.dim('\nRunning pre-PR triage checks...'));
         try {
-            const triageResult = await runTriage(gitRoot, baseBranch);
+            const triageOptions = await resolveTriageOptions(options);
+            const triageResult = await runTriage(gitRoot, baseBranch, triageOptions);
             printTriageSummary(triageResult);
-            const triageInfraFailure = triageResult.results.length === 0 && triageResult.errors.length > 0;
+            // No valid results means we got zero signal from triage. That's
+            // "unavailable" whether the cause was a hard error (auth crash) or a
+            // soft cap (every checker hit max turns). Either way don't pretend it
+            // passed — print the warning and continue.
+            const triageInfraFailure = triageResult.results.length === 0 &&
+                (triageResult.errors.length > 0 || triageResult.warnings.length > 0);
             if (triageInfraFailure) {
-                console.log(chalk.yellow('\n⚠ Triage unavailable (sub-agents failed to run). Continuing with submit.\n'));
+                console.log(chalk.yellow('\n⚠ Triage unavailable (no checkers produced results). Continuing with submit.\n'));
             }
             if (!triageResult.passed) {
                 if (triageInfraFailure) {

package/dist/index.js

@@ -38,7 +38,7 @@ const program = new Command();
 program
     .name('haystack')
     .description('Haystack CLI — automated PR review, triage, and merge queue')
-    .version('0.12.3');
+    .version('0.13.0');
 program
     .command('init')
     .description('Create .haystack.json configuration')
@@ -97,6 +97,8 @@ program
     .option('--auto-fix', 'Alpha auto-fix for straightforward mechanical issues (discouraged)')
     .option('--auto-merge', 'Apply auto-merge label (default: from .haystack.json, --no-auto-merge to disable)')
     .option('--no-wait', 'Skip waiting for analysis results')
+    .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', `
 This command is designed for AI coding agents to submit PRs.
 
@@ -116,6 +118,22 @@ Pre-PR Triage:
   Use --auto-fix only when explicitly opting into the alpha fixer for
   straightforward mechanical issues.
 
+  Triage budgets:
+  • --max-turns <n>         Raise/lower the per-checker tool-use turn cap.
+                            Defaults: code-review 8, rules-validator 10,
+                            intent-drift 10. Applies the same N to all three.
+  • --triage-timeout <sec>  Raise/lower the per-checker wall-clock timeout
+                            (default: 180s).
+
+  Persist these in .haystack.json to apply per project:
+
+    {
+      "triage": {
+        "maxTurns": { "code-review": 12 },
+        "timeoutMs": 240000
+      }
+    }
+
 Review Routing:
   If repo auto-merge is enabled in .haystack.json, plain \`haystack submit\`
   enters the auto-merge queue after submission. Otherwise it still runs the
@@ -146,6 +164,8 @@ Examples:
   haystack submit --draft              # Create as draft PR
   haystack submit --review             # ⚠ Blocks auto-merge, needs human approval
   haystack submit --review octocat     # ⚠ Blocks auto-merge, requests review from octocat
+  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

package/dist/triage/prompts.d.ts

@@ -11,14 +11,14 @@
  * Build the code review prompt.
  * Always runs — looks for objective bugs in the diff.
  */
-export declare function buildCodeReviewPrompt(baseBranch: string, outputPath: string, precomputedDiff?: string | null): string;
+export declare function buildCodeReviewPrompt(baseBranch: string, outputPath: string, maxTurns: number, timeoutMs: number, precomputedDiff?: string | null): string;
 /**
  * Build the rules validator prompt.
  * Runs if .haystack/pr-rules.yml exists OR agent instruction files are found.
  *
  * @returns The prompt string, or null if no rules content or agent policies provided.
  */
-export declare function buildRulesValidatorPrompt(baseBranch: string, rulesYaml: string, outputPath: string, agentPolicies?: {
+export declare function buildRulesValidatorPrompt(baseBranch: string, rulesYaml: string, outputPath: string, maxTurns: number, timeoutMs: number, agentPolicies?: {
     filename: string;
     content: string;
 }[], precomputedDiff?: string | null): string | null;
@@ -28,4 +28,4 @@ export declare function buildRulesValidatorPrompt(baseBranch: string, rulesYaml:
  *
  * @returns The prompt string, or null if no trace files provided.
  */
-export declare function buildIntentDriftPrompt(baseBranch: string, traceFiles: string[], outputPath: string, precomputedDiff?: string | null): string | null;
+export declare function buildIntentDriftPrompt(baseBranch: string, traceFiles: string[], outputPath: string, maxTurns: number, timeoutMs: number, precomputedDiff?: string | null): string | null;

package/dist/triage/prompts.js

@@ -55,11 +55,29 @@ const INTENT_DRIFT_SCHEMA = `{
 // ============================================================================
 // Prompt builders
 // ============================================================================
+/**
+ * Build the time-budget preamble shared by every checker prompt. Agents don't
+ * otherwise know about the externally-enforced turn cap and wall-clock
+ * deadline, so they'd happily burn budget on deep dives and get SIGTERM'd.
+ * Telling them up front makes them triage instead of exhaustively explore.
+ */
+function buildTimeBudgetHeader(maxTurns, timeoutMs) {
+    const minutes = Math.round(timeoutMs / 60_000);
+    return `## Time budget (hard limits)
+
+- You have **${maxTurns} tool-use turns max** and **~${minutes} minutes wall-clock** before this process is killed.
+- Be decisive. Skip speculative exploration. If a file looks incidental, don't open it.
+- Prefer the provided diff over running fresh searches unless the diff alone is ambiguous.
+- Report only findings you can confirm quickly. A timeout produces ZERO findings, so ship a partial high-confidence result rather than chase a perfect one that never lands.
+- Write the output JSON file EARLY (even if partial) and update it if you find more. Never exit without writing.
+
+`;
+}
 /**
  * Build the code review prompt.
  * Always runs — looks for objective bugs in the diff.
  */
-export function buildCodeReviewPrompt(baseBranch, outputPath, precomputedDiff) {
+export function buildCodeReviewPrompt(baseBranch, outputPath, maxTurns, timeoutMs, precomputedDiff) {
     const diffSection = precomputedDiff
         ? `## Diff (precomputed)
 
@@ -79,7 +97,7 @@ ${precomputedDiff}
 3. Identify only REAL BUGS — things that will definitely crash, produce wrong results, or corrupt data.`;
     return `You are a pre-PR code reviewer. Your job is to find OBJECTIVE BUGS in the code changes that will cause incorrect runtime behavior.
 
-${diffSection}
+${buildTimeBudgetHeader(maxTurns, timeoutMs)}${diffSection}
 
 ## What to flag
 
@@ -122,7 +140,7 @@ Be extremely conservative. False positives waste the developer's time. Only flag
  *
  * @returns The prompt string, or null if no rules content or agent policies provided.
  */
-export function buildRulesValidatorPrompt(baseBranch, rulesYaml, outputPath, agentPolicies, precomputedDiff) {
+export function buildRulesValidatorPrompt(baseBranch, rulesYaml, outputPath, maxTurns, timeoutMs, agentPolicies, precomputedDiff) {
     const hasRules = rulesYaml.trim().length > 0;
     const hasPolicies = agentPolicies && agentPolicies.length > 0;
     if (!hasRules && !hasPolicies)
@@ -196,7 +214,7 @@ ${precomputedDiff}
 3. If you need more context, read just the relevant section of the file — do NOT read entire large files.`;
     return `You are a PR rules validator. Your job is to check the code changes against project rules and policies, then flag violations.
 
-${rulesSection}${policiesSection}${diffInstructions}
+${buildTimeBudgetHeader(maxTurns, timeoutMs)}${rulesSection}${policiesSection}${diffInstructions}
 
 ## Important
 
@@ -223,13 +241,13 @@ ${RULES_VALIDATOR_SCHEMA}
  *
  * @returns The prompt string, or null if no trace files provided.
  */
-export function buildIntentDriftPrompt(baseBranch, traceFiles, outputPath, precomputedDiff) {
+export function buildIntentDriftPrompt(baseBranch, traceFiles, outputPath, maxTurns, timeoutMs, precomputedDiff) {
     if (traceFiles.length === 0)
         return null;
     const traceFileList = traceFiles.map(f => `- \`${f}\``).join('\n');
     return `You are an intent drift detector. Your job is to check whether an AI coding agent faithfully implemented what the user asked for.
 
-## Context
+${buildTimeBudgetHeader(maxTurns, timeoutMs)}## Context
 
 This PR was created by an AI coding agent. The agent's session transcripts (traces) are stored locally. You will compare what the user asked the agent to do against what was actually implemented in the diff.
 

package/dist/triage/runner.d.ts

@@ -5,6 +5,12 @@
  * parallel sub-processes for each checker, and collects structured JSON results.
  */
 import type { AgenticCLI, TriageResult } from './types.js';
+export interface RunTriageOptions {
+    /** Per-checker max-turn overrides (CLI flag > .haystack.json > defaults). */
+    maxTurns?: Partial<Record<string, number>>;
+    /** Per-checker wall-clock timeout override, in ms. */
+    timeoutMs?: number;
+}
 /**
  * Detect which agentic CLI is installed.
  * Returns the first one found, or null if none available.
@@ -18,4 +24,4 @@ export declare function detectAgenticCLI(): AgenticCLI | null;
  * @returns Aggregated triage results
  * @throws If no agentic CLI is detected
  */
-export declare function runTriage(gitRoot: string, baseBranch: string): Promise<TriageResult>;
+export declare function runTriage(gitRoot: string, baseBranch: string, options?: RunTriageOptions): Promise<TriageResult>;

package/dist/triage/runner.js

@@ -10,14 +10,20 @@ import { join } from 'path';
 import chalk from 'chalk';
 import { buildCodeReviewPrompt, buildRulesValidatorPrompt, buildIntentDriftPrompt } from './prompts.js';
 import { findRelevantTraces } from './traces.js';
+import { trackError } from '../utils/telemetry.js';
 // ============================================================================
 // Constants
 // ============================================================================
 const TRIAGE_DIR = '.haystack/triage';
-const TIMEOUT_MS = 300_000; // 5 minutes per checker
-/** Max agentic turns per checker — kept tight since these are read-only tasks */
-const MAX_TURNS = {
-    'code-review': 5,
+/** Wall-clock timeout per checker. Overridable via .haystack.json triage.timeoutMs or --triage-timeout. */
+const DEFAULT_TIMEOUT_MS = 180_000; // 3 minutes
+/**
+ * Default max agentic turns per checker. Overridable via .haystack.json
+ * triage.maxTurns or --max-turns. code-review tends to saturate first because
+ * it reads the diff line-by-line; 8 is the breakeven we landed on empirically.
+ */
+const DEFAULT_MAX_TURNS = {
+    'code-review': 8,
     'rules-validator': 10,
     'intent-drift': 10,
 };
@@ -107,7 +113,7 @@ function buildCommand(cli, prompt, maxTurns) {
  * Spawn a sub-agent process and wait for it to complete.
  * Returns the exit code.
  */
-function spawnChecker(cli, config, cwd) {
+function spawnChecker(cli, config, cwd, timeoutMs) {
     return new Promise((resolve) => {
         const { command, args } = buildCommand(cli, config.prompt, config.maxTurns);
         let stdout = '';
@@ -134,8 +140,8 @@ function spawnChecker(cli, config, cwd) {
         // Timeout
         const timer = setTimeout(() => {
             proc.kill('SIGTERM');
-            stderr += `\nProcess killed after ${TIMEOUT_MS / 1000}s timeout`;
-        }, TIMEOUT_MS);
+            stderr += `\nProcess killed after ${Math.round(timeoutMs / 1000)}s timeout`;
+        }, timeoutMs);
         proc.on('close', (code) => {
             clearTimeout(timer);
             resolve({ exitCode: code ?? 1, output: `${stdout}\n${stderr}`.trim() });
@@ -146,6 +152,30 @@ function spawnChecker(cli, config, cwd) {
         });
     });
 }
+/**
+ * Classify why a checker failed to produce a valid JSON result.
+ *
+ * - `max_turns`: the sub-agent exhausted its --max-turns budget. Expected when
+ *   the diff is too large for the budget; should not block submit.
+ * - `timeout`: we killed the process at the configured wall-clock cap. Also non-blocking.
+ * - `error`: anything else (auth failure, crash, malformed output). Blocks.
+ *
+ * The max-turns markers come from the CLIs themselves (Claude CLI prints
+ * "Reached max turns", Codex prints "turn limit"). If a new CLI is added, add
+ * its marker here — unknown failures fall through to `error` (safe default).
+ */
+function classifyCheckerFailure(output) {
+    const summary = summarizeCheckerFailureOutput(output) ?? '(no output)';
+    // Claude: "Reached max turns (N)". Codex/Gemini variants: "turn limit", "max iterations".
+    if (/reached max turns|max turns reached|turn limit|max iterations/i.test(output)) {
+        return { kind: 'max_turns', summary };
+    }
+    // Our own SIGTERM message from spawnChecker.
+    if (/process killed after \d+s timeout/i.test(output)) {
+        return { kind: 'timeout', summary };
+    }
+    return { kind: 'error', summary };
+}
 function summarizeCheckerFailureOutput(output) {
     const lines = output
         .split('\n')
@@ -212,8 +242,18 @@ function readCheckerResult(outputPath, checkerName) {
  * @returns Aggregated triage results
  * @throws If no agentic CLI is detected
  */
-export async function runTriage(gitRoot, baseBranch) {
+export async function runTriage(gitRoot, baseBranch, options = {}) {
     const startTime = Date.now();
+    // Merge defaults with caller-provided overrides. The caller (submit.ts) is
+    // responsible for layering CLI flags on top of .haystack.json values before
+    // calling us — we just see a flat override map.
+    const maxTurns = { ...DEFAULT_MAX_TURNS };
+    for (const [name, value] of Object.entries(options.maxTurns ?? {})) {
+        if (typeof value === 'number' && value > 0) {
+            maxTurns[name] = value;
+        }
+    }
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     // Detect CLI
     const cli = detectAgenticCLI();
     if (!cli) {
@@ -252,9 +292,9 @@ export async function runTriage(gitRoot, baseBranch) {
     const codeReviewOutput = join(triageDir, 'code-review.json');
     checkers.push({
         name: 'code-review',
-        prompt: buildCodeReviewPrompt(baseBranch, codeReviewOutput, precomputedDiff),
+        prompt: buildCodeReviewPrompt(baseBranch, codeReviewOutput, maxTurns['code-review'], timeoutMs, precomputedDiff),
         outputFile: codeReviewOutput,
-        maxTurns: MAX_TURNS['code-review'],
+        maxTurns: maxTurns['code-review'],
     });
     // 2. Rules validator (if pr-rules.yml or agent instruction files exist)
     const rulesPath = join(gitRoot, '.haystack', 'pr-rules.yml');
@@ -263,13 +303,13 @@ export async function runTriage(gitRoot, baseBranch) {
     const agentPolicyFiles = discoverAgentPolicyFiles(gitRoot);
     if (hasRulesYaml || agentPolicyFiles.length > 0) {
         const rulesValidatorOutput = join(triageDir, 'rules-validator.json');
-        const rulesPrompt = buildRulesValidatorPrompt(baseBranch, rulesYaml, rulesValidatorOutput, agentPolicyFiles, precomputedDiff);
+        const rulesPrompt = buildRulesValidatorPrompt(baseBranch, rulesYaml, rulesValidatorOutput, maxTurns['rules-validator'], timeoutMs, agentPolicyFiles, precomputedDiff);
         if (rulesPrompt) {
             checkers.push({
                 name: 'rules-validator',
                 prompt: rulesPrompt,
                 outputFile: rulesValidatorOutput,
-                maxTurns: MAX_TURNS['rules-validator'],
+                maxTurns: maxTurns['rules-validator'],
             });
         }
     }
@@ -277,13 +317,13 @@ export async function runTriage(gitRoot, baseBranch) {
     const traceFiles = findRelevantTraces(gitRoot, baseBranch);
     if (traceFiles.length > 0) {
         const intentDriftOutput = join(triageDir, 'intent-drift.json');
-        const driftPrompt = buildIntentDriftPrompt(baseBranch, traceFiles, intentDriftOutput, precomputedDiff);
+        const driftPrompt = buildIntentDriftPrompt(baseBranch, traceFiles, intentDriftOutput, maxTurns['intent-drift'], timeoutMs, precomputedDiff);
         if (driftPrompt) {
             checkers.push({
                 name: 'intent-drift',
                 prompt: driftPrompt,
                 outputFile: intentDriftOutput,
-                maxTurns: MAX_TURNS['intent-drift'],
+                maxTurns: maxTurns['intent-drift'],
             });
         }
     }
@@ -298,7 +338,7 @@ export async function runTriage(gitRoot, baseBranch) {
     const spawnResults = await Promise.allSettled(checkers.map(async (checker) => {
         const startLabel = chalk.dim(`  [${checker.name}]`);
         console.log(`${startLabel} Starting...`);
-        const result = await spawnChecker(cli, checker, gitRoot);
+        const result = await spawnChecker(cli, checker, gitRoot, timeoutMs);
         if (result.exitCode === 0) {
             console.log(`${startLabel} ${chalk.green('Done')}`);
         }
@@ -310,30 +350,55 @@ export async function runTriage(gitRoot, baseBranch) {
     // Collect results
     const results = [];
     const errors = [];
+    const warnings = [];
     for (const spawnResult of spawnResults) {
         if (spawnResult.status === 'rejected') {
             errors.push(`Checker failed: ${spawnResult.reason}`);
+            trackError('triage_checker_failed', {
+                checker: 'unknown',
+                kind: 'spawn_rejected',
+                cli,
+                reason: String(spawnResult.reason),
+            });
             continue;
         }
         const { checker, result } = spawnResult.value;
         const checkerResult = readCheckerResult(checker.outputFile, checker.name);
         if (checkerResult) {
             results.push(checkerResult);
+            continue;
+        }
+        // Sub-agent didn't produce valid output — classify as warning vs hard error.
+        const classification = classifyCheckerFailure(result.output);
+        if (classification.kind === 'max_turns') {
+            warnings.push(`${checker.name}: hit max turns (${checker.maxTurns}) — raise via --max-turns or .haystack.json triage.maxTurns, or split the PR into smaller changes`);
+        }
+        else if (classification.kind === 'timeout') {
+            warnings.push(`${checker.name}: wall-clock timeout after ${Math.round(timeoutMs / 1000)}s — consider splitting the PR`);
         }
         else {
-            // Sub-agent didn't produce valid output
-            const failureSummary = summarizeCheckerFailureOutput(result.output);
-            const errMsg = result.exitCode !== 0
-                ? `${checker.name}: process exited with code ${result.exitCode}${failureSummary ? ` (${failureSummary})` : ''}`
-                : `${checker.name}: no valid result file produced`;
-            errors.push(errMsg);
+            const exitPart = result.exitCode !== 0 ? ` (exit ${result.exitCode})` : '';
+            errors.push(`${checker.name}: ${classification.summary}${exitPart}`);
         }
+        // Emit telemetry for every failed checker so we can tune defaults empirically.
+        trackError('triage_checker_failed', {
+            checker: checker.name,
+            kind: classification.kind,
+            cli,
+            max_turns: checker.maxTurns,
+            timeout_ms: timeoutMs,
+            exit_code: result.exitCode,
+            summary: classification.summary,
+        });
     }
+    // Warnings are non-blocking by design — they're expected outcomes of the
+    // turn/time caps, not signs of real problems.
     const passed = results.every(r => r.passed) && errors.length === 0;
     return {
         passed,
         results,
         errors,
+        warnings,
         duration: Date.now() - startTime,
     };
 }

package/dist/triage/types.d.ts

@@ -39,8 +39,10 @@ export type CheckerResult = CodeReviewResult | RulesValidatorResult | IntentDrif
 export interface TriageResult {
     passed: boolean;
     results: CheckerResult[];
-    /** Errors from sub-agent crashes or missing output */
+    /** Hard errors — auth failures, crashed sub-agents, unknown failures. Block submit. */
     errors: string[];
+    /** Soft failures — sub-agent hit max turns or wall-clock timeout. Do NOT block submit. */
+    warnings: string[];
     /** Total duration in ms */
     duration: number;
 }

package/dist/types.d.ts

@@ -702,6 +702,18 @@ declare const SecretDeclarationSchema: z.ZodObject<{
     services?: string[] | undefined;
     description?: string | undefined;
 }>;
+declare const TriageConfigSchema: z.ZodObject<{
+    /** Per-checker max agentic turns. Unspecified checkers use built-in defaults. */
+    maxTurns: z.ZodOptional<z.ZodRecord<z.ZodEnum<["code-review", "rules-validator", "intent-drift"]>, z.ZodNumber>>;
+    /** Wall-clock timeout per checker, in milliseconds. */
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    maxTurns?: Partial<Record<"code-review" | "rules-validator" | "intent-drift", number>> | undefined;
+    timeoutMs?: number | undefined;
+}, {
+    maxTurns?: Partial<Record<"code-review" | "rules-validator" | "intent-drift", number>> | undefined;
+    timeoutMs?: number | undefined;
+}>;
 export declare const HaystackConfigSchema: z.ZodObject<{
     /** Config version (must be "1") */
     version: z.ZodLiteral<"1">;
@@ -1249,6 +1261,19 @@ export declare const HaystackConfigSchema: z.ZodObject<{
             timeout_minutes?: number | undefined;
         } | undefined;
     }>>;
+    /** Pre-PR triage configuration (turn budgets, timeouts) */
+    triage: z.ZodOptional<z.ZodObject<{
+        /** Per-checker max agentic turns. Unspecified checkers use built-in defaults. */
+        maxTurns: z.ZodOptional<z.ZodRecord<z.ZodEnum<["code-review", "rules-validator", "intent-drift"]>, z.ZodNumber>>;
+        /** Wall-clock timeout per checker, in milliseconds. */
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        maxTurns?: Partial<Record<"code-review" | "rules-validator" | "intent-drift", number>> | undefined;
+        timeoutMs?: number | undefined;
+    }, {
+        maxTurns?: Partial<Record<"code-review" | "rules-validator" | "intent-drift", number>> | undefined;
+        timeoutMs?: number | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     version: "1";
     name?: string | undefined;
@@ -1371,6 +1396,10 @@ export declare const HaystackConfigSchema: z.ZodObject<{
         services?: string[] | undefined;
         description?: string | undefined;
     }> | undefined;
+    triage?: {
+        maxTurns?: Partial<Record<"code-review" | "rules-validator" | "intent-drift", number>> | undefined;
+        timeoutMs?: number | undefined;
+    } | undefined;
 }, {
     version: "1";
     name?: string | undefined;
@@ -1493,6 +1522,10 @@ export declare const HaystackConfigSchema: z.ZodObject<{
         services?: string[] | undefined;
         description?: string | undefined;
     }> | undefined;
+    triage?: {
+        maxTurns?: Partial<Record<"code-review" | "rules-validator" | "intent-drift", number>> | undefined;
+        timeoutMs?: number | undefined;
+    } | undefined;
 }>;
 export type HaystackConfig = z.infer<typeof HaystackConfigSchema>;
 export type VerificationCommand = z.infer<typeof VerificationCommandSchema>;
@@ -1513,6 +1546,7 @@ export type DatabaseConfig = z.infer<typeof DatabaseConfigSchema>;
 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>;
 /**
  * Project detection results
  */

package/dist/types.js

@@ -267,6 +267,16 @@ const SecretDeclarationSchema = z.object({
     services: z.array(z.string()).optional(),
 });
 // =============================================================================
+// TRIAGE CONFIGURATION
+// =============================================================================
+const TriageCheckerNameSchema = z.enum(['code-review', 'rules-validator', 'intent-drift']);
+const TriageConfigSchema = z.object({
+    /** Per-checker max agentic turns. Unspecified checkers use built-in defaults. */
+    maxTurns: z.record(TriageCheckerNameSchema, z.number().int().positive()).optional(),
+    /** Wall-clock timeout per checker, in milliseconds. */
+    timeoutMs: z.number().int().positive().optional(),
+});
+// =============================================================================
 // MAIN CONFIG
 // =============================================================================
 export const HaystackConfigSchema = z.object({
@@ -294,4 +304,6 @@ export const HaystackConfigSchema = z.object({
     secrets: z.record(z.string(), SecretDeclarationSchema).optional(),
     /** Merge queue configuration for autonomous PR maintenance */
     merge_queue: MergeQueueConfigSchema.optional(),
+    /** Pre-PR triage configuration (turn budgets, timeouts) */
+    triage: TriageConfigSchema.optional(),
 });

package/package.json

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