@gr8ful/spf 0.9.2 → 0.10.0

package/dist/core/watch.js

@@ -55,11 +55,17 @@
  * retry loop, no auto-merge; those remain deliberately out of scope.
  */
 import path from "node:path";
+import { attemptAdwId, attemptBranch, attemptWorktreePath, runBestOf } from "./fanout.js";
 import { PRIORITY_RANK } from "./data_types.js";
 import { parseRefineMarker } from "./refine.js";
+import { newId } from "./utils.js";
 const MAX_ORPHAN_ATTEMPTS = 2;
 /** GitHub's own documented sub-issue nesting cap (see `github_provider.ts`'s `linkChild` doc comment) — `rollUp`'s own recursion bound, so a malformed/cyclic hierarchy can't spin forever. */
 const MAX_ROLLUP_DEPTH = 8;
+/** Twin of `MAX_N` in `cli/commands/fanout.ts` — the fan-out lane's own attempt-count ceiling (`watch.fanout.n`'s schema bound), duplicated as a literal so the pre-sweep (§8.5) can size itself without importing a CLI command module. */
+const MAX_FANOUT_N = 8;
+/** §8.7's salt ceiling — and therefore §8.5's sweep range too. Bounds an otherwise-unbounded probe/sweep against an issue fanned out over and over. */
+const MAX_FANOUT_SALT = 8;
 export function createWatchState() {
     return { inflight: new Set(), refining: new Set(), inflightParents: new Map() };
 }
@@ -542,8 +548,337 @@ export async function finishReviews(deps) {
         }
     }
 }
-/** One issue's full claim -> chain -> PR path, run in the background — `claimNewWork` doesn't await this. */
-async function runIssue(deps, issue) {
+/**
+ * The half of a claimed issue's path that runs once a WINNING tree exists:
+ * empty-diff check, push, PR, marker, transition, notify. Called by
+ * `runIssueSingle` with its sole attempt's tree and by `runIssueFanout` with
+ * `pickBest`'s winner — it never learns which, because nothing about opening
+ * a PR depends on how many candidates were considered.
+ *
+ * `diffBase` is a PARAMETER, not `origin/${deps.baseBranch}` recomputed here:
+ * the fan-out lane pins one base SHA for the whole fan-out (see
+ * `runIssueFanout`) and the winner must be diffed against the SAME commit its
+ * siblings were ranked against, not against wherever `origin/<base>` has
+ * moved to by now. The single lane passes `origin/${deps.baseBranch}` — the
+ * literal expression it used inline before this extraction.
+ *
+ * `extraNotifyFields`, when given, are appended to the `pr_opened` notify's
+ * `fields` — additive, never replacing any of the four fields below. The
+ * fan-out lane uses this for one `["fanout", "<n> attempts, won by <adw_id>"]`
+ * entry; the single lane passes nothing, so its notify is byte-identical to
+ * before this extraction.
+ *
+ * IT CATCHES NOTHING, deliberately. The try/catch that covers this region
+ * lives one level up, in each lane's own caller, and this extraction does not
+ * move it. So EVERY caller must still hold the winner's `{worktreePath,
+ * branch}` in whatever its own catch cleans up, for the whole duration of
+ * this call: the throws in here are ordinary (`push` rejected, `openPr` 5xx,
+ * a tracker write failing), and on any of them the caller's catch is the only
+ * thing that removes the tree and deletes the branch.
+ */
+async function openPrForWinner(deps, issue, won) {
+    const wtGit = deps.worktreeGit(won.worktreePath);
+    if (wtGit.diffFiles(won.diffBase).length === 0) {
+        deps.log(`watch: ${issue.id}: chain succeeded but committed nothing — blocked`);
+        deps.notify({
+            kind: "issue_blocked",
+            level: "notice",
+            title: `issue ${issue.id} blocked`,
+            detail: `Chain "${deps.chain}" (adw_id ${won.adwId}) completed but left no committed changes.`,
+            fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.chain], ["adw_id", won.adwId]],
+        });
+        await deps.provider.transition(issue, "blocked", `Chain "${deps.chain}" (adw_id ${won.adwId}) completed but left no committed changes.`);
+        cleanupWorktree(deps, { worktree: won.worktreePath, branch: won.branch });
+        return;
+    }
+    wtGit.push("origin", won.branch);
+    // The human merging this PR sees whatever the reviewer found — or, if
+    // nothing reviewed this change at all, is told that plainly rather than
+    // left to assume a silent approval. `reviewSummary` is already
+    // sanitized/truncated by the caller (see runChain's own doc comment).
+    const reviewLine = won.reviewSummary
+        ? won.reviewSummary
+        : won.reviewRequired
+            ? "Reviewer ran, but no verdict could be read back from the session data."
+            : `Nothing reviewed this change — chain \`${deps.chain}\` has no reviewer step.`;
+    // The reviewer's biggest complaint about a bare "automated by spf watch"
+    // body: it never says what was actually asked for, only chain plumbing.
+    // The issue body IS that ask (it's the same text `runIssue`/`runChain`
+    // built the prompt from) and is already sitting on `issue` — no new DB
+    // read needed to surface it. Capped defensively: a Jira description can
+    // be arbitrarily long, and this is a PR body, not the source of record.
+    const MAX_ISSUE_BODY_CHARS = 4000;
+    const issueBody = issue.body.trim();
+    const askSection = issueBody.length > MAX_ISSUE_BODY_CHARS ? `${issueBody.slice(0, MAX_ISSUE_BODY_CHARS)}\n\n_(truncated)_` : issueBody || "_(no description on the issue)_";
+    // No cross-linking magic keyword here on purpose (a code host paired
+    // with a different tracker has no "Closes #n" convention to hook into
+    // — see provider.ts) — the issue id in the title/body is plain text
+    // for humans, and, on a Jira+Bitbucket pairing, exactly what Jira's own
+    // Bitbucket integration scans for to link the PR automatically.
+    const pr = await deps.codeHost.openPr({
+        branch: won.branch,
+        title: `${issue.title} (${issue.id})`,
+        body: `${askSection}\n\n---\n\n**Review:** ${reviewLine}\n\n_Automated by \`spf watch\` — chain \`${deps.chain}\`, adw_id \`${won.adwId}\`, issue ${issue.id}._`,
+        base: deps.baseBranch,
+    });
+    await deps.provider.writeMarker(issue, { worktree: won.worktreePath, branch: won.branch, pr: pr.number, attempt: 0 });
+    await deps.provider.transition(issue, "review");
+    deps.log(`watch: ${issue.id}: opened PR #${pr.number} — review`);
+    deps.notify({
+        kind: "pr_opened",
+        // Unlike `issue_claimed`/`issue_done` (routine milestones), an opened PR
+        // is a standing ask for a human reviewer — the same "needs a human, not
+        // a failure" bucket as `issue_blocked`, so it ships to an
+        // `attention`-scoped channel, not just `all`.
+        level: "notice",
+        title: `PR #${pr.number} opened`,
+        detail: reviewLine,
+        fields: [
+            ["issue", issue.id],
+            ["title", issue.title],
+            ["chain", deps.chain],
+            ["review", won.reviewSummary ? "reviewed" : won.reviewRequired ? "reviewer ran, no verdict" : "not reviewed"],
+            ...(won.extraNotifyFields ?? []),
+        ],
+        url: pr.url || undefined,
+    });
+}
+/**
+ * `issue-<id>` at `r = 0` — matching `runIssueSingle`'s own adw_id scheme, so
+ * the common case (an issue's first fan-out) is the id a human would guess
+ * (`spf phases issue-42-2` works as advertised). `r > 0` salts it — see
+ * `runIssueFanout`'s salt probe for why a PROBED salt, not a counter anyone
+ * maintains, decides `r`.
+ */
+function baseFor(issue, r) {
+    return r === 0 ? `issue-${issue.id}` : `issue-${issue.id}-r${r}`;
+}
+/**
+ * Tear down a whole SET of worktree/branch pairs — EVERY worktree in the
+ * list first, then every branch, never pair by pair. The pairs a fan-out
+ * pre-sweep has to cover are cross-linked (the winner's renamed branch can
+ * live in a *different* entry's fan-out worktree — see the rename step in
+ * `runIssueFanout`), and `git branch -D` refuses to delete a branch that is
+ * checked out in ANY worktree still on disk while `deleteLocalBranch`
+ * swallows that refusal (a bare `spawnSync` whose status is never read —
+ * `git_helper.ts`). A name-by-name (pairwise) sweep can therefore try to
+ * delete a branch that is still checked out in an entry later in the SAME
+ * list, silently fail, and leave the issue permanently wedged the next time
+ * something tries to create that branch. Two full passes over the whole list
+ * remove that ordering dependency entirely — the same rule
+ * `removeRunWorktree` documents for its own single pair (worktree before
+ * branch), applied at the granularity a sweep across many pairs needs.
+ */
+function sweepPairs(deps, pairs) {
+    for (const p of pairs) {
+        if (!p.worktree)
+            continue;
+        try {
+            deps.git.worktreeRemove(p.worktree);
+        }
+        catch (error) {
+            deps.log(`watch: sweep warning: ${error.message}`);
+        }
+    }
+    for (const p of pairs) {
+        if (!p.branch)
+            continue;
+        try {
+            deps.git.deleteLocalBranch(p.branch);
+        }
+        catch (error) {
+            deps.log(`watch: sweep warning: ${error.message}`);
+        }
+    }
+}
+/**
+ * `watch.fanout.n > 1`: run `n` sibling attempts of this issue's prompt via
+ * `core/fanout.ts`'s `runBestOf`, let it pick a winner, rename the winner's
+ * branch onto the canonical `spf-watch/<id>-<slug>` name, then hand it to
+ * `openPrForWinner` — the same tail `runIssueSingle` uses.
+ *
+ * `won` is a single mutable local (unlike the single lane's deterministic
+ * `worktreePath`/`branch` locals) because the fan-out lane's cleanup
+ * coordinates change three times over the course of one claim: null while
+ * nothing of watch's own exists yet, the winner's fan-out tree/branch right
+ * after selection, then the winner's tree on the renamed canonical branch
+ * from the rename onward — including all the way through `openPrForWinner`,
+ * which catches nothing itself. `won` is intentionally never nulled before
+ * that call: doing so would disarm this catch for `push`/`openPr` failures,
+ * the single most failure-prone part of the whole flow, and leak a full
+ * checkout plus the canonical branch on every one of them.
+ */
+async function runIssueFanout(deps, issue, fanout) {
+    const n = fanout.n;
+    let won = null;
+    try {
+        // Read for its PAIR (the pre-sweep needs to know what a previous cycle
+        // recorded), never for `attempt` — see the salt probe below for why that
+        // field cannot be the fan-out lane's re-claim counter.
+        const marker0 = await deps.provider.readMarker(issue);
+        // SALT PROBE (§8.7 in the design doc): the smallest r whose n attempt
+        // ids have NO session rows yet. `WatchMarker.attempt` only advances on
+        // reconcileOrphans' retry path — an ordinary blocked -> re-labeled ready
+        // -> re-claim never touches it — so it cannot answer "is this base
+        // still clean," but the sessions a previous claim's attempts actually
+        // wrote can (adwIdsFree's own doc comment has the full argument).
+        let salt = 0;
+        for (; salt <= MAX_FANOUT_SALT; salt++) {
+            const ids = Array.from({ length: n }, (_, i) => attemptAdwId(baseFor(issue, salt), i + 1));
+            if (fanout.adwIdsFree(ids))
+                break;
+        }
+        const baseAdwId = salt <= MAX_FANOUT_SALT ? baseFor(issue, salt) : `issue-${issue.id}-x${newId(4)}`;
+        if (salt > MAX_FANOUT_SALT) {
+            deps.log(`watch: ${issue.id}: exhausted ${MAX_FANOUT_SALT + 1} deterministic fan-out base id(s) — falling back to a random one (${baseAdwId})`);
+        }
+        // PRE-SWEEP: one list, two passes (sweepPairs) — marker0's own recorded
+        // pair (the only way to reach a stale RENAMED winner from a crash after
+        // §8.3's rename), the canonical single-lane pair (the rename target
+        // below must find it free), and every deterministic attempt name under
+        // every base this claim can have used (0..salt inclusive — bases above
+        // salt were never reached, so nothing can be there).
+        const branch = branchNameFor(issue);
+        const worktreePath = worktreePathFor(deps, issue);
+        const pairs = [
+            { worktree: marker0?.worktree, branch: marker0?.branch },
+            { worktree: worktreePath, branch },
+        ];
+        for (let r = 0; r <= Math.min(salt, MAX_FANOUT_SALT); r++) {
+            const base = baseFor(issue, r);
+            for (let i = 1; i <= MAX_FANOUT_N; i++) {
+                pairs.push({
+                    worktree: attemptWorktreePath(deps.worktreesDir, base, i),
+                    branch: attemptBranch(base, i),
+                });
+            }
+        }
+        sweepPairs(deps, pairs);
+        // The base is fetched and resolved to a SHA exactly ONCE, loudly, here —
+        // matching the single lane's own unguarded, fatal-on-failure fetch
+        // (`runIssueSingle`) rather than `runBestOf`'s own per-attempt,
+        // failure-swallowing fetch. `pinnedGit` suppresses the N redundant
+        // fetches `runBestOf` would otherwise issue against a base already
+        // fetched here, and pins every attempt (and the eventual `diffFiles`
+        // check in `openPrForWinner`) to the identical commit even if
+        // `origin/<base>` moves mid-fan-out.
+        deps.git.fetch("origin", deps.baseBranch);
+        const baseSha = deps.git.rev(`origin/${deps.baseBranch}`);
+        const pinnedGit = { ...deps.git, fetch: () => { } };
+        // CLAIM-TIME MARKER WRITE — mirrors the single lane's own write
+        // (`runIssueSingle`) and, like it, drops `pr`. Without this, a marker
+        // surviving from a PREVIOUS cycle (e.g. a human hand-returning a
+        // `review` issue with an open PR back to `ready`) would carry that
+        // stale `pr` through the sweep and the whole fan-out window untouched —
+        // and if the daemon dies mid-fan-out, `reconcileOrphans` would read that
+        // stale `marker.pr` on restart, find it open or merged, and resume the
+        // issue straight to `review` (its RESUME path, never reached again from
+        // `ready`/`blocked`), leaking this claim's worktrees/branches forever
+        // with nothing left to sweep them on a future claim. `attempt` is
+        // PRESERVED here (not reset to 0) so the orphan-retry counter survives a
+        // claim that has not yet produced a winner; it only becomes the literal
+        // `0` once a real winner marker is written below, matching the single
+        // lane's own reset at that point.
+        await deps.provider.writeMarker(issue, { attempt: marker0?.attempt ?? 0 });
+        const result = await runBestOf({
+            chainName: deps.chain,
+            prompt: `${issue.title}\n\n${issue.body}`.trim(),
+            n,
+            concurrency: fanout.concurrency,
+            baseAdwId,
+            baseBranch: baseSha,
+            repoRoot: fanout.repoRoot,
+            worktreesDir: deps.worktreesDir,
+            git: pinnedGit,
+            linkDataDir: deps.linkDataDir,
+            runAttempt: fanout.runAttempt,
+            readMetrics: fanout.readMetrics,
+            log: deps.log,
+        });
+        deps.log(`watch: ${issue.id}: best of ${n} — ${result.basis}`);
+        if (!result.winner) {
+            const first = attemptAdwId(baseAdwId, 1);
+            const last = attemptAdwId(baseAdwId, n);
+            const detail = `Chain "${deps.chain}" did not succeed in any of ${n} attempt(s) (adw_ids ${first}..${last}): ${result.basis}. ` +
+                `Run \`spf phases <adw_id>\` on any attempt for detail.`;
+            deps.notify({
+                kind: "issue_blocked",
+                level: "notice",
+                title: `issue ${issue.id} blocked`,
+                detail,
+                fields: [
+                    ["issue", issue.id],
+                    ["title", issue.title],
+                    ["chain", deps.chain],
+                    ["adw_id", `${baseAdwId}-1..${n}`],
+                    ["attempts", String(n)],
+                ],
+            });
+            await deps.provider.transition(issue, "blocked", detail);
+            // NO cleanupWorktree call: `won` is still null — nothing of watch's
+            // own survived `runBestOf`, which already cleaned every attempt it
+            // owned (losers as it went, and there is no winner to keep here).
+            return;
+        }
+        const winner = result.winner;
+        won = { worktree: winner.worktree, branch: winner.branch }; // still spf/fanout/*
+        await deps.provider.writeMarker(issue, { worktree: won.worktree, branch: won.branch, attempt: 0 });
+        // RENAME (§8.3): `spf/fanout/*` branches are never pushed by SPF
+        // (`core/fanout.ts`'s own stated contract) — pushing one from watch
+        // would contradict the module this composes. Renaming preserves
+        // everything downstream that reads a branch name (WatchMarker.branch,
+        // the PR head, finishReviews' cleanup, the Jira/Bitbucket branch-name
+        // auto-link). Order matters: `createBranch` (a `git checkout -b` INSIDE
+        // the winner's worktree) must run before `deleteLocalBranch` on the old
+        // name, because git refuses to delete a branch checked out in a
+        // worktree — the winner's own worktree is that checkout until this line
+        // runs. `createBranch` CAN throw (most commonly: the canonical name
+        // already exists) — the pre-sweep above is what keeps that name free by
+        // the time this runs; if it still throws, `won` has not been reassigned
+        // yet, so the catch below cleans the pre-rename pair, correctly.
+        const wtGit = deps.worktreeGit(winner.worktree);
+        wtGit.createBranch(branch);
+        deps.git.deleteLocalBranch(winner.branch);
+        won = { worktree: winner.worktree, branch };
+        await deps.provider.writeMarker(issue, { worktree: won.worktree, branch: won.branch, attempt: 0 });
+        const review = fanout.reviewFor({ cwd: winner.worktree, adwId: winner.adw_id, chainOptions: deps.chainOptions });
+        // `won` stays set from here on — openPrForWinner catches nothing, so
+        // this function's own catch (below) is the only cleanup for a throw
+        // from push/openPr/writeMarker/transition/notify inside it, exactly as
+        // runIssueSingle's catch is for the single lane.
+        await openPrForWinner(deps, issue, {
+            branch: won.branch,
+            worktreePath: won.worktree,
+            adwId: winner.adw_id,
+            diffBase: baseSha,
+            reviewRequired: review.reviewRequired,
+            reviewSummary: review.reviewSummary,
+            extraNotifyFields: [["fanout", `${n} attempts, won by ${winner.adw_id}`]],
+        });
+    }
+    catch (error) {
+        const message = error.message;
+        deps.log(`watch: ${issue.id}: error: ${message}`);
+        deps.notify({
+            kind: "watch_error",
+            level: "error",
+            title: `issue ${issue.id} errored`,
+            detail: message,
+            fields: [["issue", issue.id], ["title", issue.title]],
+        });
+        await deps.provider.transition(issue, "blocked", `spf watch error: ${message}`).catch(() => undefined);
+        cleanupWorktree(deps, won);
+    }
+}
+/**
+ * Today's single-dispatch path — `runIssue`'s entire body before fan-out
+ * existed, moved intact with its post-win tail extracted into
+ * `openPrForWinner` above: same statements, same order, same values. This is
+ * what makes `watch.fanout.n: 1` (the default) a no-op for the running
+ * daemon: same adw_id, same worktree, same fetch semantics, same marker,
+ * same PR, same notifications as before this feature existed.
+ */
+async function runIssueSingle(deps, issue) {
     const branch = branchNameFor(issue);
     const worktreePath = worktreePathFor(deps, issue);
     const adwId = `issue-${issue.id}`;
@@ -578,56 +913,13 @@ async function runIssue(deps, issue) {
             cleanupWorktree(deps, { worktree: worktreePath, branch });
             return;
         }
-        const wtGit = deps.worktreeGit(worktreePath);
-        if (wtGit.diffFiles(`origin/${deps.baseBranch}`).length === 0) {
-            deps.log(`watch: ${issue.id}: chain succeeded but committed nothing — blocked`);
-            deps.notify({
-                kind: "issue_blocked",
-                level: "notice",
-                title: `issue ${issue.id} blocked`,
-                detail: `Chain "${deps.chain}" (adw_id ${adwId}) completed but left no committed changes.`,
-                fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.chain], ["adw_id", adwId]],
-            });
-            await deps.provider.transition(issue, "blocked", `Chain "${deps.chain}" (adw_id ${adwId}) completed but left no committed changes.`);
-            cleanupWorktree(deps, { worktree: worktreePath, branch });
-            return;
-        }
-        wtGit.push("origin", branch);
-        // The human merging this PR sees whatever the reviewer found — or, if
-        // nothing reviewed this change at all, is told that plainly rather than
-        // left to assume a silent approval. `reviewSummary` is already
-        // sanitized/truncated by the caller (see runChain's own doc comment).
-        const reviewLine = result.reviewSummary
-            ? result.reviewSummary
-            : result.reviewRequired
-                ? "Reviewer ran, but no verdict could be read back from the session data."
-                : `Nothing reviewed this change — chain \`${deps.chain}\` has no reviewer step.`;
-        // No cross-linking magic keyword here on purpose (a code host paired
-        // with a different tracker has no "Closes #n" convention to hook into
-        // — see provider.ts) — the issue id in the title/body is plain text
-        // for humans, and, on a Jira+Bitbucket pairing, exactly what Jira's own
-        // Bitbucket integration scans for to link the PR automatically.
-        const pr = await deps.codeHost.openPr({
+        await openPrForWinner(deps, issue, {
             branch,
-            title: `${issue.title} (${issue.id})`,
-            body: `Automated by \`spf watch\` — chain \`${deps.chain}\`, adw_id \`${adwId}\`, issue ${issue.id}.\n\n${reviewLine}`,
-            base: deps.baseBranch,
-        });
-        await deps.provider.writeMarker(issue, { worktree: worktreePath, branch, pr: pr.number, attempt: 0 });
-        await deps.provider.transition(issue, "review");
-        deps.log(`watch: ${issue.id}: opened PR #${pr.number} — review`);
-        deps.notify({
-            kind: "pr_opened",
-            level: "info",
-            title: `PR #${pr.number} opened`,
-            detail: reviewLine,
-            fields: [
-                ["issue", issue.id],
-                ["title", issue.title],
-                ["chain", deps.chain],
-                ["review", result.reviewSummary ? "reviewed" : result.reviewRequired ? "reviewer ran, no verdict" : "not reviewed"],
-            ],
-            url: pr.url || undefined,
+            worktreePath,
+            adwId,
+            diffBase: `origin/${deps.baseBranch}`,
+            reviewRequired: result.reviewRequired,
+            reviewSummary: result.reviewSummary,
         });
     }
     catch (error) {
@@ -644,6 +936,17 @@ async function runIssue(deps, issue) {
         cleanupWorktree(deps, { worktree: worktreePath, branch });
     }
 }
+/**
+ * One issue's full claim -> chain -> PR path, run in the background —
+ * `claimNewWork` doesn't await this. `deps.fanout` unset (or `n <= 1`) takes
+ * the single-dispatch path exactly as it always has; `watch.fanout.n > 1`
+ * fans out via `runBestOf` first.
+ */
+async function runIssue(deps, issue) {
+    if (!deps.fanout || deps.fanout.n <= 1)
+        return runIssueSingle(deps, issue);
+    return runIssueFanout(deps, issue, deps.fanout);
+}
 /**
  * The spec's own `<prefix>:priority:pN` label, or `null` if it was never
  * set. Deliberately NOT `issuePriority`'s default-to-`p2` behavior: `null`

package/dist/core/worktree_data.d.ts

@@ -0,0 +1 @@
+export declare function excludeSpfDataFromGit(worktreePath: string): void;

package/dist/core/worktree_data.js

@@ -0,0 +1,37 @@
+/**
+ * Keep a worktree's `.spf/data` symlink invisible to `git status`/`git add -A`.
+ *
+ * Moved here (out of `cli/commands/fanout.ts`) so both `cli/commands/fanout.ts`
+ * and `cli/commands/watch.ts` can call it without either command importing the
+ * other — `spawnSync` + `node:fs` only, no chains, no db, no sandbox, matching
+ * `core/git_helper.ts`'s own dependency discipline.
+ *
+ * `.spf/data/` — a trailing-slash DIRECTORY pattern, the shape a tracked
+ * `.gitignore` uses — does NOT match a SYMLINK of the same name, so without
+ * this, `git status` shows `?? .spf/data` and a committing chain's
+ * `git_helper.commitAll` (`git add -A`) stages it. Following a printed
+ * `git merge <branch>` instruction then fast-forwards the symlink straight
+ * into the MAIN repo, replacing its real `.spf/data` directory with a symlink
+ * pointing back at itself — destroying the trace db (`ls .spf/data` becomes
+ * `ELOOP`; see `paths.healBrokenDataDir` for the recovery side of this same
+ * bug). `info/exclude` is per-worktree, local-only, and idempotent to append
+ * to — the opposite of adding a pattern to a tracked `.gitignore`, which would
+ * ship this workaround into every clone for a symlink only a scoped-worktree
+ * caller (fan-out attempts, `spf watch`'s own build-lane worktrees) ever
+ * creates.
+ */
+import { spawnSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+export function excludeSpfDataFromGit(worktreePath) {
+    const resolved = spawnSync("git", ["rev-parse", "--git-path", "info/exclude"], { cwd: worktreePath, encoding: "utf-8" });
+    if (resolved.status !== 0)
+        return; // best-effort: worst case is the pre-existing staging risk, not a crash
+    const excludePath = path.resolve(worktreePath, resolved.stdout.trim());
+    const line = ".spf/data";
+    const existing = existsSync(excludePath) ? readFileSync(excludePath, "utf-8") : "";
+    if (existing.split("\n").some((l) => l.trim() === line))
+        return;
+    mkdirSync(path.dirname(excludePath), { recursive: true });
+    appendFileSync(excludePath, `${existing && !existing.endsWith("\n") ? "\n" : ""}${line}\n`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",