@haystackeditor/cli 0.13.4 → 0.14.0

package/dist/commands/config.js

@@ -201,6 +201,46 @@ export async function isAutoMergeEnabled() {
         return false;
     }
 }
+/** Read the two queue-side toggles that depend on auto-merge. We re-read the
+ *  file rather than calling getPreference() because those settings live under
+ *  `merge_queue.*` instead of `preferences.*`. Returns null fields when the
+ *  config is missing or can't be parsed — callers treat null as "not set".
+ *  Note: loadHaystackConfig() process.exit(1)s on ENOENT, so this catch only
+ *  fires for unexpected failures (parse errors, permission denied). We use the
+ *  same logging helper as the other preference readers so failures surface in
+ *  stderr instead of silently rolling back to defaults. */
+function readDependentToggles() {
+    try {
+        const { config } = loadHaystackConfig();
+        return {
+            autoResolveConflicts: config.merge_queue?.auto_resolve_conflicts ?? null,
+            autoFixCiFailures: config.merge_queue?.auto_fix_ci_failures ?? null,
+        };
+    }
+    catch (err) {
+        logPreferenceLookupFailure('merge_queue dependent toggles', err);
+        return { autoResolveConflicts: null, autoFixCiFailures: null };
+    }
+}
+function printDependencyNote(autoMergeEnabled) {
+    const deps = readDependentToggles();
+    // Only mention dependents that are explicitly configured — silent for repos
+    // that never set them. Both rely on auto-merge because they're merge-queue
+    // features that only fire on enqueued PRs.
+    const items = [];
+    if (deps.autoResolveConflicts != null)
+        items.push(`auto-resolve-conflicts (${deps.autoResolveConflicts ? 'on' : 'off'})`);
+    if (deps.autoFixCiFailures != null)
+        items.push(`auto-fix-ci-failures (${deps.autoFixCiFailures ? 'on' : 'off'})`);
+    if (items.length === 0)
+        return;
+    if (autoMergeEnabled) {
+        console.log(chalk.dim(`Tied to auto-merge: ${items.join(', ')}.`));
+    }
+    else {
+        console.log(chalk.yellow(`Note: ${items.join(', ')} won't run while auto-merge is off — these are merge-queue features that only fire on enqueued PRs.`));
+    }
+}
 export async function getAutoMergeStatus() {
     const enabled = getPreference('auto_merge');
     console.log(chalk.bold('\nAuto-merge:'), enabled
@@ -215,6 +255,7 @@ export async function getAutoMergeStatus() {
         console.log(chalk.dim('Auto-merge is disabled. PRs require manual merge.'));
         console.log(chalk.dim('Enable with: haystack config auto-merge on'));
     }
+    printDependencyNote(enabled);
     console.log(chalk.dim('(Stored in .haystack.json — applies to all repo contributors)'));
     console.log();
 }
@@ -223,6 +264,7 @@ export async function enableAutoMerge() {
     console.log(chalk.green('\nAuto-merge enabled.\n'));
     console.log(chalk.dim('PRs submitted via `haystack submit` will be auto-merged'));
     console.log(chalk.dim('when analysis finds no issues (safe to merge).'));
+    printDependencyNote(true);
     console.log(chalk.dim('Commit .haystack.json to share with your team.\n'));
 }
 export async function disableAutoMerge() {
@@ -230,6 +272,7 @@ export async function disableAutoMerge() {
     console.log(chalk.yellow('\nAuto-merge disabled.\n'));
     console.log(chalk.dim('PRs will require manual merge after analysis.'));
     console.log(chalk.dim('Re-enable with: haystack config auto-merge on'));
+    printDependencyNote(false);
     console.log(chalk.dim('Commit .haystack.json to share with your team.\n'));
 }
 export async function handleAutoMerge(action) {

package/dist/commands/setup.js

@@ -92,28 +92,355 @@ async function fetchExistingConfig(owner, repo, token) {
         throw new Error('existing .haystack.json is malformed JSON — delete or fix it manually');
     }
 }
+// Bootstrap PR constants — kept in sync with the web wizard
+// (src/features/onboarding/services/onboardingApi.ts). The branch prefix and
+// the two labels are load-bearing: the worker's bootstrap merge path
+// (agent/cloudflare/src/merge-queue-cron.ts) keys off them.
+const CONFIG_COMMIT_MSG = 'chore: configure Haystack via CLI setup wizard';
+const AUTO_MERGE_LABEL = 'haystack:auto-merge';
+const ONBOARDING_BOOTSTRAP_LABEL = 'haystack:onboarding-bootstrap';
+const BOOTSTRAP_PR_TITLE = 'Configure Haystack';
+const BOOTSTRAP_PR_BODY = 'This PR was opened automatically by the Haystack CLI setup wizard because the default branch is protected.\n\n' +
+    'It adds the Haystack onboarding config:\n' +
+    '- `.haystack.json` — enables the Haystack merge queue and review automation\n' +
+    '- `.entire/settings.json` — enables AI-session trace capture (powers intent-drift triage)\n\n' +
+    'Both files are committed to this branch; `.entire/settings.json` lands in a follow-up commit ' +
+    'during setup step 7, so it may not be present the instant the PR opens.\n\n' +
+    'Haystack will bootstrap-merge this PR automatically once the labels are applied. ' +
+    'You can tweak the files from GitHub or re-run `haystack setup` anytime.';
+/**
+ * Encode a branch name for use in a URL path while preserving `/`
+ * separators (e.g. `release/stable`). encodeURIComponent on the whole
+ * string would turn `/` into `%2F`, which several GitHub endpoints reject.
+ */
+function encodeBranchPath(branch) {
+    return branch.split('/').map(encodeURIComponent).join('/');
+}
+/**
+ * Is the given branch protected such that a direct commit can't land —
+ * either by legacy branch protection OR a repository ruleset?
+ *
+ * Decided from GitHub's *structured* signals, not error-message text:
+ *   - `GET /repos/{o}/{r}/branches/{b}` → `.protected` (legacy protection)
+ *   - `GET /repos/{o}/{r}/rules/branches/{b}` → a `pull_request` rule means
+ *     "changes must go through a PR" (rulesets)
+ *
+ * Called on the write-failure path: a 409/422 from the direct commit tells
+ * us *that* something rejected the write; this tells us *whether* it was
+ * protection (→ open a bootstrap PR) vs. a genuine bad request (→ surface
+ * the error). If the probe itself can't be completed we throw — guessing
+ * from message wording is exactly the brittleness we're avoiding here.
+ */
+async function isBranchProtected(owner, repo, branch, token) {
+    const headers = ghHeaders(token);
+    const enc = encodeBranchPath(branch);
+    // Legacy branch protection — the `protected` boolean is authoritative.
+    const branchRes = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/branches/${enc}`, { headers });
+    if (branchRes.ok) {
+        const data = (await branchRes.json());
+        if (data.protected === true)
+            return true;
+    }
+    else if (branchRes.status !== 404) {
+        throw new Error(`Couldn't check branch protection: ${branchRes.status} — ${await branchRes.text()}`);
+    }
+    // Repository rulesets — `rules/branches` collapses every active rule on
+    // the branch into one list. A `pull_request` rule = "must merge via PR".
+    const rulesRes = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/rules/branches/${enc}`, { headers });
+    if (rulesRes.ok) {
+        const rules = (await rulesRes.json());
+        if (rules.some((r) => r.type === 'pull_request'))
+            return true;
+    }
+    else if (rulesRes.status !== 404) {
+        throw new Error(`Couldn't check repository rulesets: ${rulesRes.status} — ${await rulesRes.text()}`);
+    }
+    return false;
+}
+function ghHeaders(token) {
+    return {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github.v3+json',
+        'Content-Type': 'application/json',
+        'User-Agent': 'Haystack-CLI',
+    };
+}
+async function getDefaultBranch(owner, repo, token) {
+    const res = await fetch(`${GITHUB_API}/repos/${owner}/${repo}`, { headers: ghHeaders(token) });
+    if (!res.ok) {
+        throw new Error(`Failed to read repo metadata: ${res.status} — ${await res.text()}`);
+    }
+    return (await res.json()).default_branch;
+}
+async function getBranchSha(owner, repo, branch, token) {
+    // GitHub's git/ref/heads/{ref} endpoint expects literal slashes in the ref
+    // path — encodeURIComponent would turn `release/stable` into
+    // `release%2Fstable` and 404. encodeBranchPath escapes each segment but
+    // keeps the `/` separators.
+    const res = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/git/ref/heads/${encodeBranchPath(branch)}`, { headers: ghHeaders(token) });
+    if (!res.ok) {
+        throw new Error(`Failed to read branch ref: ${res.status} — ${await res.text()}`);
+    }
+    return (await res.json()).object.sha;
+}
+async function createBranch(owner, repo, branch, sha, token) {
+    const res = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/git/refs`, {
+        method: 'POST',
+        headers: ghHeaders(token),
+        body: JSON.stringify({ ref: `refs/heads/${branch}`, sha }),
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to create branch: ${res.status} — ${await res.text()}`);
+    }
+}
+async function createBootstrapPR(owner, repo, head, base, token) {
+    const res = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/pulls`, {
+        method: 'POST',
+        headers: ghHeaders(token),
+        body: JSON.stringify({ title: BOOTSTRAP_PR_TITLE, head, base, body: BOOTSTRAP_PR_BODY }),
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to open PR: ${res.status} — ${await res.text()}`);
+    }
+    return (await res.json());
+}
+/**
+ * Build a single commit containing `files` on top of `baseSha` via the Git
+ * Data API (blobs → tree → commit). Returns the new commit sha.
+ *
+ * Why not `PUT /contents/`: that updates a ref, and a ruleset whose
+ * `pull_request` rule targets `~ALL` branches blocks ref *updates* on
+ * EVERY branch — including a fresh onboarding branch. So
+ * createBranch-then-commitFileToBranch fails at the commit step. Building
+ * the commit as a standalone object and then *creating* a ref at it only
+ * ever creates a ref, never updates one (and there is no `creation`
+ * restriction in those rulesets), so it gets through. Also works fine for
+ * normally-protected repos. Critically: on a `~ALL` repo you cannot add a
+ * second commit afterward either, so BOTH onboarding files must land in
+ * this one commit.
+ */
+async function createCommitWithFiles(owner, repo, baseSha, files, message, token) {
+    const headers = ghHeaders(token);
+    // The new tree extends the base commit's tree.
+    const baseCommitRes = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/git/commits/${baseSha}`, { headers });
+    if (!baseCommitRes.ok) {
+        throw new Error(`Failed to read base commit: ${baseCommitRes.status} — ${await baseCommitRes.text()}`);
+    }
+    const baseTreeSha = (await baseCommitRes.json()).tree.sha;
+    // One blob per file.
+    const treeEntries = await Promise.all(files.map(async (f) => {
+        const blobRes = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/git/blobs`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ content: f.content, encoding: 'utf-8' }),
+        });
+        if (!blobRes.ok) {
+            throw new Error(`Failed to create blob for ${f.path}: ${blobRes.status} — ${await blobRes.text()}`);
+        }
+        const blob = (await blobRes.json());
+        return { path: f.path, mode: '100644', type: 'blob', sha: blob.sha };
+    }));
+    const treeRes = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/git/trees`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ base_tree: baseTreeSha, tree: treeEntries }),
+    });
+    if (!treeRes.ok) {
+        throw new Error(`Failed to create tree: ${treeRes.status} — ${await treeRes.text()}`);
+    }
+    const tree = (await treeRes.json());
+    const commitRes = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/git/commits`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ message, tree: tree.sha, parents: [baseSha] }),
+    });
+    if (!commitRes.ok) {
+        throw new Error(`Failed to create commit: ${commitRes.status} — ${await commitRes.text()}`);
+    }
+    return (await commitRes.json()).sha;
+}
+/**
+ * Compute the desired `.entire/settings.json` content for a repo: fetch the
+ * existing file (if any), strip the legacy `skip_raw_transcript` option, and
+ * serialize. Returns `null` when the file already exists and is unchanged
+ * (nothing to write). Otherwise returns the content AND the existing blob
+ * sha (or null if the file doesn't exist) — so the direct-write path can
+ * issue a correct update PUT without a second redundant GET. Pure read +
+ * transform — does no writes itself, so it can feed either the bootstrap-PR
+ * commit or the direct-write path.
+ *
+ * Non-404 read failures throw — they must NOT be silently coerced to
+ * "file doesn't exist", which would make the subsequent PUT a create and
+ * GitHub reject it 422, masking the real transient error.
+ */
+async function buildEntireSettingsContent(repoFullName, token) {
+    const [owner, repo] = repoFullName.split('/');
+    const headers = ghHeaders(token);
+    let settings = { enabled: true };
+    let originalContent = '';
+    let exists = false;
+    let existingSha = null;
+    const getResp = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/contents/.entire/settings.json`, { headers });
+    if (getResp.ok) {
+        exists = true;
+        const data = (await getResp.json());
+        existingSha = data.sha;
+        originalContent = Buffer.from(data.content, 'base64').toString('utf-8');
+        try {
+            settings = JSON.parse(originalContent);
+        }
+        catch {
+            console.log(chalk.dim(`  Existing .entire/settings.json in ${repoFullName} is malformed — will repair`));
+        }
+    }
+    else if (getResp.status !== 404) {
+        const errText = await getResp.text().catch(() => '');
+        const error = new Error(`Failed to read .entire/settings.json: ${getResp.status} ${errText}`);
+        trackError('entire_settings_read_failed', {
+            error_message: error.message,
+            repo: repoFullName,
+            status: getResp.status,
+        });
+        throw error;
+    }
+    // Remove legacy skip_raw_transcript if present (v0.5.3-haystack.2+ compacts automatically)
+    if (settings.strategy_options && typeof settings.strategy_options === 'object') {
+        const strategyOptions = settings.strategy_options;
+        delete strategyOptions.skip_raw_transcript;
+        if (Object.keys(strategyOptions).length === 0) {
+            delete settings.strategy_options;
+        }
+    }
+    const updatedContent = JSON.stringify(settings, null, 2) + '\n';
+    // Nothing to do if the file already exists unchanged.
+    if (exists && updatedContent === originalContent)
+        return null;
+    return { content: updatedContent, existingSha };
+}
+async function addBootstrapLabels(owner, repo, prNumber, prUrl, token) {
+    // CRITICAL, not best-effort: without BOTH labels the worker's bootstrap
+    // merge path never discovers the PR and it sits open forever. The label
+    // API failing is almost always transient, so retry a few times before
+    // giving up.
+    const labels = [AUTO_MERGE_LABEL, ONBOARDING_BOOTSTRAP_LABEL];
+    let lastErr = '';
+    for (let attempt = 1; attempt <= 3; attempt++) {
+        const res = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/issues/${prNumber}/labels`, {
+            method: 'POST',
+            headers: ghHeaders(token),
+            body: JSON.stringify({ labels }),
+        });
+        if (res.ok)
+            return;
+        lastErr = `${res.status} — ${await res.text()}`;
+        if (attempt < 3) {
+            await new Promise((resolve) => setTimeout(resolve, attempt * 500));
+        }
+    }
+    // Retries exhausted. The PR exists with the config committed — it just
+    // won't auto-merge without the labels. Throw an actionable error: name
+    // the PR, name the exact labels, and warn against re-running (which would
+    // open a duplicate PR on a fresh timestamped branch).
+    throw new Error(`opened PR ${prUrl} but couldn't apply the auto-merge labels after 3 tries (${lastErr}). ` +
+        `Add these labels to the PR manually so Haystack picks it up: ${labels.join(', ')}. ` +
+        `Don't re-run \`haystack setup\` — that opens a duplicate PR.`);
+}
+/**
+ * Protected-branch fallback: build ONE commit containing both onboarding
+ * files (`.haystack.json` + `.entire/settings.json`) via the Git Data API,
+ * CREATE a branch ref at it, open a PR, and apply the auto-merge + bootstrap
+ * labels.
+ *
+ * Why both files in one commit: a ruleset whose `pull_request` rule targets
+ * `~ALL` branches blocks ref *updates* on every branch — so you can neither
+ * commit to the default branch NOR add a second commit to the onboarding
+ * branch afterward. The only thing allowed is *creating* a ref. So both
+ * bootstrap-critical files (`.haystack.json` enables the merge queue,
+ * `.entire/settings.json` enables the trace capture intent-drift triage
+ * runs on) must land in the single commit the branch is created at.
+ */
+async function openBootstrapConfigPR(owner, repo, configContent, token, defaultBranch) {
+    const baseSha = await getBranchSha(owner, repo, defaultBranch, token);
+    // Branch prefix MUST stay `haystack/onboarding-` — the worker keys off it.
+    // The timestamp avoids collisions when setup is re-run.
+    const branchName = `haystack/onboarding-${Date.now()}`;
+    const files = [
+        { path: '.haystack.json', content: configContent },
+    ];
+    // Bundle .entire/settings.json into the same commit — on a ~ALL ruleset
+    // we can't add it later. It's repo-level config (independent of whether
+    // this dev installs the Entire binary locally), so it rides along here.
+    // The Git Data tree API overwrites by path, so existingSha isn't needed here.
+    //
+    // Best-effort: .entire/settings.json is the OPTIONAL file; .haystack.json
+    // is the bootstrap-critical one. A transient non-404 read failure here
+    // must NOT abort the whole PR (buildEntireSettingsContent throws on
+    // non-404). Catch it, warn, and ship the PR with just .haystack.json —
+    // far better than failing setup over the optional file. The customer can
+    // re-run `haystack setup` to pick up .entire/settings.json once GitHub
+    // is healthy.
+    // entireSettings === null means the file already exists unchanged — there's
+    // nothing to bundle, but the repo IS correctly configured, so that still
+    // counts as bundled. Only a read *failure* (caught below) sets this false.
+    let entireSettingsBundled = true;
+    try {
+        const entireSettings = await buildEntireSettingsContent(`${owner}/${repo}`, token);
+        if (entireSettings !== null) {
+            files.push({ path: '.entire/settings.json', content: entireSettings.content });
+        }
+    }
+    catch (err) {
+        // buildEntireSettingsContent already tracked this with the real HTTP
+        // status before throwing — don't re-emit a duplicate event here. Just
+        // warn and ship the PR with .haystack.json only.
+        entireSettingsBundled = false;
+        console.log(chalk.yellow(`  \u26a0 Couldn't read .entire/settings.json for ${owner}/${repo} (${err instanceof Error ? err.message : err}) — ` +
+            `opening the bootstrap PR with .haystack.json only. Re-run \`haystack setup\` to add session tracking.`));
+    }
+    const commitSha = await createCommitWithFiles(owner, repo, baseSha, files, CONFIG_COMMIT_MSG, token);
+    await createBranch(owner, repo, branchName, commitSha, token);
+    const pr = await createBootstrapPR(owner, repo, branchName, defaultBranch, token);
+    await addBootstrapLabels(owner, repo, pr.number, pr.html_url, token);
+    return { prUrl: pr.html_url, entireSettingsBundled };
+}
+/**
+ * Write `.haystack.json` to a repo. Tries a direct commit to the default
+ * branch first; on a protected-branch / ruleset error, falls back to opening
+ * a bootstrap PR (branch + commit + PR + labels) so setup still completes.
+ *
+ * Returns `{ bootstrapPR }` when the PR fallback was used (so the caller can
+ * thread the branch into step 7), `{}` on a clean direct commit.
+ */
 async function writeConfigToRepo(owner, repo, config, existingSha, token) {
     const content = JSON.stringify(config, null, 2) + '\n';
     const body = {
-        message: 'chore: configure Haystack via CLI setup wizard',
+        message: CONFIG_COMMIT_MSG,
         content: Buffer.from(content).toString('base64'),
     };
     if (existingSha)
         body.sha = existingSha;
     const response = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/contents/.haystack.json`, {
         method: 'PUT',
-        headers: {
-            Authorization: `Bearer ${token}`,
-            Accept: 'application/vnd.github.v3+json',
-            'Content-Type': 'application/json',
-            'User-Agent': 'Haystack-CLI',
-        },
+        headers: ghHeaders(token),
         body: JSON.stringify(body),
     });
-    if (!response.ok) {
-        const err = await response.text();
-        throw new Error(`Failed to write config: ${response.status} — ${err}`);
+    if (response.ok)
+        return {};
+    const err = await response.text();
+    // A 409/422 means *something* rejected the direct commit. Probe GitHub's
+    // structured protection signals to find out whether it was branch
+    // protection / a ruleset (→ open a bootstrap PR) or a genuine bad request
+    // (→ surface the error). Other statuses (auth, 404, 5xx) are never a
+    // protected-branch situation, so don't bother probing.
+    if (response.status === 409 || response.status === 422) {
+        const defaultBranch = await getDefaultBranch(owner, repo, token);
+        if (await isBranchProtected(owner, repo, defaultBranch, token)) {
+            // Protected — open a bootstrap PR instead of failing.
+            const bootstrapPR = await openBootstrapConfigPR(owner, repo, content, token, defaultBranch);
+            return { bootstrapPR };
+        }
     }
+    throw new Error(`Failed to write config: ${response.status} — ${err}`);
 }
 // =============================================================================
 // Merge helpers
@@ -234,6 +561,163 @@ function printPolicy(policy, index) {
 // =============================================================================
 // Wizard steps
 // =============================================================================
+// =============================================================================
+// Step 0.5: Ensure the Haystack GitHub App is installed
+// =============================================================================
+const HAYSTACK_APP_SLUG = 'haystack-code-reviewer-pr-hook';
+const HAYSTACK_APP_INSTALL_URL = `https://github.com/apps/${HAYSTACK_APP_SLUG}/installations/new`;
+const APP_INSTALL_POLL_INTERVAL_MS = 3000;
+const APP_INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
+class InstallationsAuthError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'InstallationsAuthError';
+    }
+}
+async function fetchHaystackInstallations(token) {
+    // /user/installations lists App installations the OAuth-authenticated user
+    // can manage. Returns 200 with `installations: []` when none exist.
+    const res = await fetch(`${GITHUB_API}/user/installations?per_page=100`, {
+        headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: 'application/vnd.github.v3+json',
+            'User-Agent': 'Haystack-CLI',
+        },
+    });
+    if (!res.ok) {
+        // 401/403 are auth-bucket failures — token revoked, expired, or missing
+        // the right scopes. Retrying never recovers; bail with a distinct error
+        // type so the poll loop can short-circuit and prompt re-auth.
+        if (res.status === 401 || res.status === 403) {
+            throw new InstallationsAuthError(res.status, `${res.status} ${await res.text()}`);
+        }
+        throw new Error(`failed to fetch installations: ${res.status} ${await res.text()}`);
+    }
+    const data = (await res.json());
+    return (data.installations ?? []).filter((i) => i.app_slug === HAYSTACK_APP_SLUG);
+}
+function tryOpenBrowser(url) {
+    // Best-effort browser open. Never blocks setup — the URL is also printed.
+    // Windows: `start` is a cmd.exe builtin, not a standalone executable, so we
+    // can't invoke it via execFileSync directly. Route through cmd /c.
+    try {
+        if (process.platform === 'win32') {
+            // The empty quoted string is `start`'s "window title" arg — required
+            // when the first arg might be quoted, prevents start from misparsing
+            // the URL as a title. /c terminates cmd after the command runs.
+            execSync(`cmd /c start "" "${url.replace(/"/g, '%22')}"`, { stdio: 'ignore' });
+        }
+        else {
+            const opener = process.platform === 'darwin' ? 'open' : 'xdg-open';
+            execFileSync(opener, [url], { stdio: 'ignore' });
+        }
+        return true;
+    }
+    catch (err) {
+        // Log so operators see systemic browser-open failures (corporate Linux
+        // without xdg-open, weird PATH, etc.). The user-visible UX is unchanged
+        // since the URL was already printed for manual copy.
+        console.log(chalk.dim(`  (Couldn't auto-open browser: ${err.message})`));
+        return false;
+    }
+}
+async function stepEnsureAppInstalled(token) {
+    console.log(chalk.bold('  Step 0: Verify GitHub App'));
+    let installed;
+    try {
+        installed = await fetchHaystackInstallations(token);
+    }
+    catch (err) {
+        if (err instanceof InstallationsAuthError) {
+            // Token is dead — retrying won't help. Prompt re-auth and exit so the
+            // user doesn't waste a 10-minute poll on something that will never work.
+            console.log(chalk.yellow(`\n  Your GitHub token is no longer valid (${err.status}).`));
+            console.log(chalk.dim('  Run `haystack login` to re-authenticate, then re-run `haystack setup`.\n'));
+            trackError('haystack_setup_installations_auth_failure', { status: err.status });
+            process.exit(1);
+        }
+        console.log(chalk.yellow(`  Could not check App installations: ${err.message}`));
+        console.log(chalk.dim(`  Continuing — install manually at ${HAYSTACK_APP_INSTALL_URL} if not yet installed.\n`));
+        // Probe failed but we proceed (refuse-to-fail UX so a transient blip can't
+        // brick setup). Still log so we can see if probes start failing
+        // systemically across users.
+        trackError('haystack_setup_installations_probe_failed', {
+            error_message: err.message,
+        });
+        return;
+    }
+    if (installed.length > 0) {
+        const accounts = installed.map((i) => i.account?.login).filter(Boolean).join(', ');
+        console.log(chalk.green(`  ✓ Haystack App installed${accounts ? ` (${accounts})` : ''}\n`));
+        return;
+    }
+    console.log(chalk.yellow('  The Haystack GitHub App is not installed yet.'));
+    console.log(chalk.dim('  Without it, Haystack can\'t analyze, triage, or merge your PRs.'));
+    console.log('');
+    console.log(`  Install at: ${chalk.cyan(HAYSTACK_APP_INSTALL_URL)}`);
+    const opened = tryOpenBrowser(HAYSTACK_APP_INSTALL_URL);
+    if (opened) {
+        console.log(chalk.dim('  (Opened in your browser. Pick the repos to grant access.)'));
+    }
+    console.log('');
+    console.log(chalk.dim('  Waiting for install to complete...'));
+    const startedAt = Date.now();
+    let consecutiveFailures = 0;
+    let lastError = null;
+    while (Date.now() - startedAt < APP_INSTALL_TIMEOUT_MS) {
+        await new Promise((resolve) => setTimeout(resolve, APP_INSTALL_POLL_INTERVAL_MS));
+        let current;
+        try {
+            current = await fetchHaystackInstallations(token);
+            consecutiveFailures = 0;
+            lastError = null;
+        }
+        catch (err) {
+            // Auth errors during the poll loop mean the token went bad mid-flow
+            // (e.g. user revoked it from GitHub settings). Same response as the
+            // initial check — bail with re-auth guidance instead of grinding for
+            // 10 minutes against a permanent failure.
+            if (err instanceof InstallationsAuthError) {
+                console.log(chalk.yellow(`\n  Your GitHub token became invalid (${err.status}) while waiting.`));
+                console.log(chalk.dim('  Run `haystack login` to re-authenticate, then re-run `haystack setup`.\n'));
+                trackError('haystack_setup_installations_auth_failure', { status: err.status, during: 'poll' });
+                process.exit(1);
+            }
+            // Per-tick failures are usually transient (token refresh race, brief
+            // GitHub API blip). Log the first one quietly so the user sees we're
+            // not silently spinning, but don't spam the terminal every 3s.
+            consecutiveFailures += 1;
+            lastError = err instanceof Error ? err.message : String(err);
+            if (consecutiveFailures === 1) {
+                console.log(chalk.dim(`  (Transient error checking installations: ${lastError} — retrying...)`));
+            }
+            continue;
+        }
+        if (current.length > 0) {
+            const accounts = current.map((i) => i.account?.login).filter(Boolean).join(', ');
+            console.log(chalk.green(`\n  ✓ App installed${accounts ? ` (${accounts})` : ''}\n`));
+            return;
+        }
+    }
+    // Timeout is a real failure — emit a structured telemetry event so we can
+    // route it to ops alerting (Slack via the existing trackError → PostHog
+    // pipeline). Include whether the polling itself was failing (lastError
+    // non-null after the final tick) so we can tell "user didn't click install"
+    // apart from "GitHub API was down."
+    trackError('haystack_setup_app_install_timeout', {
+        consecutive_failures: consecutiveFailures,
+        last_error: lastError,
+        timeout_ms: APP_INSTALL_TIMEOUT_MS,
+    });
+    console.log(chalk.yellow('\n  Timed out waiting for App install.'));
+    if (lastError) {
+        console.log(chalk.dim(`  Last error checking installations: ${lastError}`));
+    }
+    console.log(chalk.dim(`  Install at ${HAYSTACK_APP_INSTALL_URL}, then re-run \`haystack setup\`.\n`));
+    process.exit(1);
+}
 async function stepSelectRepos(token) {
     console.log(chalk.bold('\n  Step 1: Select repositories\n'));
     console.log(chalk.dim('  Fetching your repositories...'));
@@ -440,19 +924,30 @@ async function stepConfirm(selectedRepos, rules, signals, policies, token) {
     ]);
     if (!confirmed) {
         console.log(chalk.yellow('\n  Setup cancelled.\n'));
-        return false;
+        return { confirmed: false, bootstrapPRs: new Map() };
     }
     // Write to each repo
     const failedRepos = [];
+    const bootstrapPRs = new Map();
     for (const repoFullName of selectedRepos) {
         const [owner, repo] = repoFullName.split('/');
         try {
             process.stdout.write(chalk.dim(`  Writing to ${repoFullName}...`));
             const existing = await fetchExistingConfig(owner, repo, token);
             const mergedConfig = existing ? deepMerge(existing.config, config) : config;
-            await writeConfigToRepo(owner, repo, mergedConfig, existing?.sha ?? null, token);
+            const result = await writeConfigToRepo(owner, repo, mergedConfig, existing?.sha ?? null, token);
             process.stdout.write('\r\x1b[K');
-            console.log(chalk.green(`  ✓ ${repoFullName}`));
+            if (result.bootstrapPR) {
+                // Default branch was protected — config landed in a bootstrap PR
+                // that Haystack will auto-merge once its labels are processed.
+                // Step 7 adds .entire/settings.json to this same PR.
+                bootstrapPRs.set(repoFullName, result.bootstrapPR);
+                console.log(chalk.green(`  ✓ ${repoFullName}`) + chalk.dim(' (default branch protected — opened a PR)'));
+                console.log(chalk.dim(`    ${result.bootstrapPR.prUrl}`));
+            }
+            else {
+                console.log(chalk.green(`  ✓ ${repoFullName}`));
+            }
         }
         catch (err) {
             process.stdout.write('\r\x1b[K');
@@ -465,7 +960,7 @@ async function stepConfirm(selectedRepos, rules, signals, policies, token) {
         process.exit(1);
     }
     console.log(chalk.green('\n  Setup complete!\n'));
-    return true;
+    return { confirmed: true, bootstrapPRs };
 }
 // =============================================================================
 // Main command
@@ -495,6 +990,10 @@ export async function setupCommand() {
     }
     const user = (await userResponse.json());
     console.log(chalk.dim(`  Logged in as ${chalk.bold(user.login)}\n`));
+    // Step 0.5: Ensure the Haystack GitHub App is installed. Without it, all
+    // the server-side machinery (merge queue, analysis, fixer, review chat) is
+    // dark — the user would write .haystack.json and then nothing would happen.
+    await stepEnsureAppInstalled(token);
     // Step 1: Select repos
     const selectedRepos = await stepSelectRepos(token);
     // Steps 2-4: Scan for rules, wait-for signals, and review policies
@@ -504,11 +1003,13 @@ export async function setupCommand() {
     // Step 5: Review
     const reviewed = await stepReview(rules, signals, policies);
     // Step 6: Confirm & write
-    const confirmed = await stepConfirm(selectedRepos, reviewed.rules, reviewed.signals, reviewed.policies, token);
+    const { confirmed, bootstrapPRs } = await stepConfirm(selectedRepos, reviewed.rules, reviewed.signals, reviewed.policies, token);
     if (!confirmed)
         return;
-    // Step 7: Install Entire CLI (session tracking)
-    await stepInstallEntire(selectedRepos, token);
+    // Step 7: Install Entire CLI (session tracking). bootstrapPRs tells it
+    // which repos had a protected default branch so it can commit
+    // .entire/settings.json to the same PR instead of a doomed direct PUT.
+    await stepInstallEntire(selectedRepos, token, bootstrapPRs);
 }
 // =============================================================================
 // Step 7: Install Entire CLI for session tracking
@@ -595,68 +1096,36 @@ async function installEntireBinary() {
     }
 }
 /**
- * Write .entire/settings.json via the GitHub API.
- * selectedRepos are GitHub full names (owner/repo), not local paths.
+ * Write .entire/settings.json directly to the default branch.
+ *
+ * This is the DIRECT path only. Repos whose default branch is protected
+ * never reach here — step 6's openBootstrapConfigPR already bundled
+ * .entire/settings.json into the bootstrap PR's single commit (on a ~ALL
+ * ruleset you can't add it as a later commit, so it must ride along in the
+ * branch-creation commit). stepInstallEntire skips this call for those
+ * repos. So if we're here, step 6 proved the default branch accepts a
+ * direct commit.
  */
 async function configureEntireSettingsViaAPI(repoFullName, token) {
     const [owner, repo] = repoFullName.split('/');
-    const filePath = '.entire/settings.json';
-    const headers = {
-        Authorization: `Bearer ${token}`,
-        Accept: 'application/vnd.github.v3+json',
-        'User-Agent': 'Haystack-CLI',
-        'Content-Type': 'application/json',
-    };
-    // Fetch existing .entire/settings.json (if any)
-    let existingSha = null;
-    let settings = { enabled: true };
-    let originalContent = '';
-    const getResp = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/contents/${filePath}`, { headers });
-    if (getResp.ok) {
-        const data = (await getResp.json());
-        existingSha = data.sha;
-        originalContent = Buffer.from(data.content, 'base64').toString('utf-8');
-        try {
-            settings = JSON.parse(originalContent);
-        }
-        catch {
-            // Malformed JSON — keep sha for update but use fresh defaults
-            console.log(chalk.dim(`  Existing .entire/settings.json in ${repoFullName} is malformed — will repair`));
-        }
-    }
-    else if (getResp.status !== 404) {
-        // Non-404 failure (auth, network, rate limit) — don't guess, surface it
-        const errText = await getResp.text().catch(() => '');
-        const error = new Error(`Failed to read .entire/settings.json: ${getResp.status} ${errText}`);
-        trackError('entire_settings_read_failed', {
-            error_message: error.message,
-            repo: repoFullName,
-            status: getResp.status,
-        });
-        throw error;
-    }
-    // 404 → file doesn't exist, existingSha stays null → PUT will create
-    // Remove legacy skip_raw_transcript if present (v0.5.3-haystack.2+ compacts automatically)
-    if (settings.strategy_options && typeof settings.strategy_options === 'object') {
-        const strategyOptions = settings.strategy_options;
-        delete strategyOptions.skip_raw_transcript;
-        if (Object.keys(strategyOptions).length === 0) {
-            delete settings.strategy_options;
-        }
-    }
-    const updatedContent = JSON.stringify(settings, null, 2) + '\n';
-    // Skip write if nothing changed (avoids no-op commits)
-    if (existingSha && updatedContent === originalContent) {
+    const result = await buildEntireSettingsContent(repoFullName, token);
+    // null → file already exists unchanged; nothing to write.
+    if (result === null)
         return;
-    }
-    const content = Buffer.from(updatedContent).toString('base64');
+    // buildEntireSettingsContent already fetched the file — reuse its
+    // content + existingSha. A second GET here would (a) be redundant and
+    // (b) on a transient non-404 failure fall back to existingSha=null,
+    // turning the PUT into a create that GitHub rejects 422 — masking the
+    // real read error. (Non-404 read failures already threw upstream.)
+    const { content, existingSha } = result;
+    const headers = ghHeaders(token);
     const body = {
         message: 'chore: configure Entire CLI settings',
-        content,
+        content: Buffer.from(content).toString('base64'),
     };
     if (existingSha)
         body.sha = existingSha;
-    const putResp = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/contents/${filePath}`, {
+    const putResp = await fetch(`${GITHUB_API}/repos/${owner}/${repo}/contents/.entire/settings.json`, {
         method: 'PUT',
         headers,
         body: JSON.stringify(body),
@@ -673,7 +1142,7 @@ async function configureEntireSettingsViaAPI(repoFullName, token) {
         throw error;
     }
 }
-async function stepInstallEntire(selectedRepos, token) {
+async function stepInstallEntire(selectedRepos, token, bootstrapPRs) {
     console.log(chalk.bold('\n  Step 7: Session tracking (Entire CLI)\n'));
     const status = isEntireInstalled();
     let binaryReady = status.installed && status.isHaystackFork;
@@ -718,10 +1187,31 @@ async function stepInstallEntire(selectedRepos, token) {
         console.log(chalk.dim('  Skipping session tracking.\n'));
     }
     // Configure .entire/settings.json on each repo via GitHub API
-    // (works even if binary install failed — settings are remote; skip if user declined)
+    // (works even if binary install failed — settings are remote; skip if user declined).
+    // Repos whose default branch was protected went the bootstrap-PR route in
+    // step 6, which ALREADY bundled .entire/settings.json into that PR's
+    // single commit (on a ~ALL ruleset it can't be added as a later commit).
+    // So we skip those here and only direct-write the non-protected repos.
     if (userConsented) {
         let configured = 0;
+        let bundled = 0;
         for (const repoFullName of selectedRepos) {
+            const bootstrapPR = bootstrapPRs.get(repoFullName);
+            if (bootstrapPR) {
+                if (bootstrapPR.entireSettingsBundled) {
+                    // .entire/settings.json made it into the bootstrap PR's commit.
+                    console.log(chalk.green(`  ✓ ${repoFullName}`) + chalk.dim(' (in bootstrap PR)'));
+                    bundled++;
+                }
+                else {
+                    // Step 6 shipped the bootstrap PR with .haystack.json only — the
+                    // optional settings read failed transiently. Don't count it as
+                    // configured; the warning was already shown in step 6.
+                    console.log(chalk.yellow(`  ⚠ ${repoFullName}`) +
+                        chalk.dim(' — bootstrap PR has .haystack.json only; re-run setup to add session tracking'));
+                }
+                continue;
+            }
             try {
                 process.stdout.write(chalk.dim(`  Configuring ${repoFullName}...`));
                 await configureEntireSettingsViaAPI(repoFullName, token);
@@ -734,9 +1224,9 @@ async function stepInstallEntire(selectedRepos, token) {
                 console.log(chalk.yellow(`  ⚠ ${repoFullName}: ${err instanceof Error ? err.message : err}`));
             }
         }
-        if (configured > 0) {
-            console.log(chalk.green(`\n  ✓ Session tracking configured on ${configured} repo(s) (transcripts auto-compacted)\n`));
-            trackSetupEvent('entire_configured', { configured, total: selectedRepos.length });
+        if (configured > 0 || bundled > 0) {
+            console.log(chalk.green(`\n  ✓ Session tracking configured on ${configured + bundled} repo(s) (transcripts auto-compacted)\n`));
+            trackSetupEvent('entire_configured', { configured: configured + bundled, total: selectedRepos.length });
         }
         else {
             console.log(chalk.yellow('\n  ⚠ Could not configure session tracking on any repos.\n'));

package/dist/types.d.ts

@@ -63,6 +63,9 @@ declare const MergeQueueConfigSchema: z.ZodObject<{
     merge_queue: z.ZodOptional<z.ZodBoolean>;
     /** Automatically rebase PRs that develop merge conflicts after pushes to the base branch */
     auto_resolve_conflicts: z.ZodOptional<z.ZodBoolean>;
+    /** Dispatch the Haystack agent to fix failing CI checks. Defaults to true; set
+     *  false to escalate CI failures to the PR author instead of attempting a fix. */
+    auto_fix_ci_failures: z.ZodOptional<z.ZodBoolean>;
     /** Grace period configuration before auto-merging */
     merge_debounce: z.ZodOptional<z.ZodObject<{
         /** Default wait time in minutes before auto-merging */
@@ -113,6 +116,7 @@ declare const MergeQueueConfigSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     merge_queue?: boolean | undefined;
     auto_resolve_conflicts?: boolean | undefined;
+    auto_fix_ci_failures?: boolean | undefined;
     merge_debounce?: {
         default_minutes?: number | undefined;
         authors?: Record<string, number> | undefined;
@@ -130,6 +134,7 @@ declare const MergeQueueConfigSchema: z.ZodObject<{
 }, {
     merge_queue?: boolean | undefined;
     auto_resolve_conflicts?: boolean | undefined;
+    auto_fix_ci_failures?: boolean | undefined;
     merge_debounce?: {
         default_minutes?: number | undefined;
         authors?: Record<string, number> | undefined;
@@ -1179,6 +1184,9 @@ export declare const HaystackConfigSchema: z.ZodObject<{
         merge_queue: z.ZodOptional<z.ZodBoolean>;
         /** Automatically rebase PRs that develop merge conflicts after pushes to the base branch */
         auto_resolve_conflicts: z.ZodOptional<z.ZodBoolean>;
+        /** Dispatch the Haystack agent to fix failing CI checks. Defaults to true; set
+         *  false to escalate CI failures to the PR author instead of attempting a fix. */
+        auto_fix_ci_failures: z.ZodOptional<z.ZodBoolean>;
         /** Grace period configuration before auto-merging */
         merge_debounce: z.ZodOptional<z.ZodObject<{
             /** Default wait time in minutes before auto-merging */
@@ -1229,6 +1237,7 @@ export declare const HaystackConfigSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         merge_queue?: boolean | undefined;
         auto_resolve_conflicts?: boolean | undefined;
+        auto_fix_ci_failures?: boolean | undefined;
         merge_debounce?: {
             default_minutes?: number | undefined;
             authors?: Record<string, number> | undefined;
@@ -1246,6 +1255,7 @@ export declare const HaystackConfigSchema: z.ZodObject<{
     }, {
         merge_queue?: boolean | undefined;
         auto_resolve_conflicts?: boolean | undefined;
+        auto_fix_ci_failures?: boolean | undefined;
         merge_debounce?: {
             default_minutes?: number | undefined;
             authors?: Record<string, number> | undefined;
@@ -1280,6 +1290,7 @@ export declare const HaystackConfigSchema: z.ZodObject<{
     merge_queue?: {
         merge_queue?: boolean | undefined;
         auto_resolve_conflicts?: boolean | undefined;
+        auto_fix_ci_failures?: boolean | undefined;
         merge_debounce?: {
             default_minutes?: number | undefined;
             authors?: Record<string, number> | undefined;
@@ -1406,6 +1417,7 @@ export declare const HaystackConfigSchema: z.ZodObject<{
     merge_queue?: {
         merge_queue?: boolean | undefined;
         auto_resolve_conflicts?: boolean | undefined;
+        auto_fix_ci_failures?: boolean | undefined;
         merge_debounce?: {
             default_minutes?: number | undefined;
             authors?: Record<string, number> | undefined;

package/dist/types.js

@@ -123,6 +123,9 @@ const MergeQueueConfigSchema = z.object({
     merge_queue: z.boolean().optional(),
     /** Automatically rebase PRs that develop merge conflicts after pushes to the base branch */
     auto_resolve_conflicts: z.boolean().optional(),
+    /** Dispatch the Haystack agent to fix failing CI checks. Defaults to true; set
+     *  false to escalate CI failures to the PR author instead of attempting a fix. */
+    auto_fix_ci_failures: z.boolean().optional(),
     /** Grace period configuration before auto-merging */
     merge_debounce: z.object({
         /** Default wait time in minutes before auto-merging */

package/package.json

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