Scope createRepositorySourceSnapshot fingerprint to subtree (subproject resume cascade)

[ppsplus-bradh]

Summary

In the recursive monorepo docs feature, createRepositorySourceSnapshot
(src/agent/utils.ts) builds a source fingerprint that is not scoped to
the subproject subtree. This leaves a residual cross-subproject cascade on
subproject resume: a sibling commit can force a subproject to discard its
interrupted plan and replan, even though that subproject did not change.

Found during adversarial review of the upstream re-integration merge e9cb709
(PR langchain-ai#439). This is conservative — it can only cause extra planning, never
a false skip and never stale output — so it is a follow-up, not a blocker.

Invariant at stake

The recursive feature guarantees no cross-subproject cascade: a subproject
must not regenerate or replan merely because a sibling subproject changed.
This is enforced by scoping git evidence to a subtree via a GitScope pathspec
(git status/diff are repo-wide regardless of cwd). getUpdateNoopStatus,
getChangedPathsSinceLastUpdate, and getRepositoryChangedPaths all already
honor a scope?: GitScope; plannerEvidenceScope(role) in
src/generation/repository-run.ts maps the run's RecursionRole to the right
scope.

The gap

createRepositorySourceSnapshot fingerprints two repo-wide inputs:

1. git status --porcelain dirty-tree entries — filtered only by
   assertFingerprintGitPath / isFingerprintSourcePath, which reject ../
   escapes but include sibling repo-root-relative paths
   (e.g. packages/other/x.ts).
2. The repo-wide HEAD commit hash.

Because both are repo-wide, a subproject's fingerprint changes whenever any
sibling changes or any commit advances HEAD.

Impact (established by review)

• Fresh subproject runs are safe — the no-op skip decision uses the scoped
  getUpdateNoopStatus, not the fingerprint. The fingerprint only appears in a
  self-consistent stability check (current-vs-current mid-run drift detection)
  and in resumeRepositoryRun.
• Subproject resume is where it bites: a sibling commit between begin and
  resume flips the fingerprint → sourceChanged=true → the interrupted plan is
  discarded and the subproject replans. Conservative (extra planning only).
• A rarer mid-run race (sibling change between the two stability snapshots) can
  abort a no-op finalize and fall through to planning — also conservative.

Why the fix is non-trivial

Scoping only the git status --porcelain query is insufficient: the
repo-wide HEAD hash alone still flips the fingerprint when a sibling commit
advances HEAD. A full subtree-scoped fingerprint needs a subtree-scoped notion
of "HEAD" too (e.g. git log -1 --format=%H -- <subtree>, or the subtree tree
hash git rev-parse HEAD:<subtree>) rather than the global HEAD — and that value
interacts with the page-manifest baseline gitHead, which is compared against
global commit ranges in getRepositoryChangedPaths(root, ignore, baseline, scope). So the manifest-baseline vs fingerprint-HEAD semantics must be reasoned
through carefully to avoid breaking page fast-forwarding.

Acceptance criteria

• Subproject resume ignores a sibling-only commit (no replan).
• A subproject's own in-subtree change still triggers replan on resume.
• Non-recursive (single-repo) and root runs are byte-identical to
  today (gate on recursionRole, mirroring how noopScope leaves root
  repo-wide).
• Page-manifest fast-forward / update-window behavior stays correct.
• Backward-compat: existing persisted .run.json / page manifests carry
  repo-wide hashes; first resume/update after the change behaves sanely
  (worst case: one conservative replan, never stale output).

A detailed implementation plan (options + recommendation) will be added as a
comment.

[ppsplus-bradh]

Implementation plan

Recommendation: full subtree-scoped fingerprint (scope+normalize the status
query AND use a subtree-last-commit as HEAD), gated to recursionRole === "subproject" only. Status-only is insufficient (global HEAD still flips the
fingerprint on any sibling commit); a tree-hash HEAD breaks the manifest
baseline (see the crux below).

What is actually scoped today (verified empirically from a subproject cwd)

createRepositorySourceSnapshot (src/agent/utils.ts:390-463) hashes four git
queries plus file bytes:

Input	Query	Scoped to subtree today?	Path namespace
tracked bytes	ls-files --cached (utils.ts:401)	Yes (self-scopes to cwd)	cwd-relative
untracked bytes	ls-files --others (utils.ts:402-407)	Yes	cwd-relative
dirty status	status --porcelain (utils.ts:408-414)	No — repo-wide	repo-root-relative
HEAD	rev-parse --verify HEAD (utils.ts:483-503)	No — global	commit hash

So the byte-hash (dominant content) is already subtree-only; the leak surface is
exactly status + HEAD.

Second bug surfaced during grounding (namespace mismatch)

git status --porcelain returns repo-root-relative paths even from a
subdirectory (pkgA/openwiki/x.md), but isFingerprintSourcePath /
isOpenWikiPath / openWikiIgnore.ignores (utils.ts:570-577, 1036-1040)
operate in the cwd-relative namespace. So a subproject's own regenerated
wiki (pkgA/openwiki/*, committed not gitignored) is not excluded from the
fingerprint status entries. This appears to make hasRepositorySourceChanged
(repository-run.ts:1622-1627) report true at finish for any subproject
update that rewrites pages — a self-churn forcing the interrupted branch. This
is a functional defect, not merely conservative — to confirm during
implementation. The fix's path-normalization step resolves it as a natural
consequence, and is the main reason to fix rather than document-only.

The crux: source.gitHead becomes a git diff baseline

source.gitHead flows into the page manifest as entry.gitHead
(page-manifest.ts:314), which is then used as a git diff <base>..HEAD
baseline in getRepositoryPageUpdateWindows (repository-run.ts:857,869) and
fastForwardUnchangedRepositoryPageCoverage (:908). The baseline must stay a
real, reachable commit:

• Tree hash (git rev-parse HEAD:<subtree>): BREAKS — not a commit;
  diffing a subtree tree against whole-repo HEAD misaligns paths. Rejected.
• Subtree-last-touching commit (git log -1 --format=%H -- .): SAFE — a
  real ancestor; stays put across a sibling-only commit; git diff <subtreeCommit>..HEAD -- . yields exactly the subtree's changes. Verified.

One value serves both roles: the subtree-last-commit is hashed into the
fingerprint and returned as gitHead for the manifest baseline. HEAD-for-
fingerprint and HEAD-for-manifest do not need to diverge (they only would if
we chose a tree hash — which we reject).

Implementation steps

1. Thread scope?: GitScope into createRepositorySourceSnapshot
   (utils.ts:390) and createRepositorySourceFingerprint (:472). When
   undefined, output is byte-identical to today.
2. Scope + normalize status: append the pathspec via
   gitScopeArgs(scope, false).pathspec (-- .), then strip the
   git rev-parse --show-prefix prefix from each porcelain path so
   isOpenWikiPath/openWikiIgnore match correctly (empty prefix at root →
   inert for unscoped runs). This also fixes the namespace bug above.
3. Scope HEAD: for the subproject scope, replace the global
   rev-parse --verify HEAD with git log -1 --format=%H -- . (handle the
   "no commit touches the subtree yet" empty case like the current unborn-branch
   path). Keep the global query for scope === undefined.
4. Gate to subproject only — mirror noopScope (repository-run.ts:360-361,
   subproject → {mode:"subproject"}, everything else → undefined), not
   plannerEvidenceScope (which also scopes root). Call sites:
   beginRepositoryRun (:407,453,455,464), resumeRepositoryRun (:606),
   hasRepositorySourceChanged (:1625). Guarantees single-repo and root runs
   are byte-identical.

Leave repo-wide (deliberately)

• .last-update.json gitHead (utils.ts:277-282, compared globally in
  getUpdateNoopStatus): internally consistent (global compare + scoped diff),
  independent of the fingerprint. Don't touch.
• Root-run fingerprint: leave repo-wide. Root re-planning when sub-wikis
  change does not violate the "no cross-subproject cascade" invariant (root
  is the aggregator). Scoping it correctly needs root-excluding-nested in the
  byte-hash + a scoped root HEAD — a larger, separate follow-up.
• .workspaces-state.json gitHead: bookkeeping only. Leave.

Migration (no schema bump)

• Pre-upgrade .run.json: first resume computes a scoped fingerprint →
  sourceChanged=true → one-time replan, resets targetGitHead to the subtree
  commit. Conservative, never stale.
• Pre-upgrade manifest entries: entry.gitHead is a global commit (real, so
  scoped diffs from it still work); fast-forward re-stamps with the scoped
  fingerprint + subtree commit on the first clean run. Self-healing.
• entry.gitHead stays a commit hash; SourceFingerprintSchema unchanged.

Minimum tests

1. Subproject resume ignores a sibling commit (no replan); baseline would
   replan.
2. Own-subtree change triggers replan on resume.
3. Non-recursive byte-identical — golden assertion that scope:undefined
   output is unchanged (guards --show-prefix stripping being inert at root).
4. Scoped-fingerprint units (cwd=pkgA): sibling commit / sibling dirty / own
   openwiki/ churn → stable; own src change → changes; gitHead equals
   git log -1 --format=%H -- ..
5. Page-manifest fast-forward: sibling commit → fast-forwarded (empty scoped
   diff), no regen; own-subtree commit → not fast-forwarded.
6. Subtree-commit baseline is a valid git diff base..HEAD -- . base (+ a
   negative test documenting why a tree hash is wrong).

Scope recommendation

Implement the full subproject-gated fix; leave root and .last-update.json
repo-wide. Do-nothing is defensible for the sibling leak alone (conservative),
but the namespace self-churn (item "Second bug") is a functional defect, so fix
now. Blast radius is confined to subproject runs by the recursionRole gate.

Plan produced by a grounded read of the current code; all git-semantics claims
verified empirically.

[ppsplus-bradh]

Resolved — fix implemented, reviewed, and pushed to PR langchain-ai#439

Commits (on feat/recursive-monorepo-docs):

• 5cabc55 — the fix: thread an optional GitScope through createRepositorySourceSnapshot/createRepositorySourceFingerprint, gated to recursionRole === "subproject" only (root and single-repo runs stay repo-wide and byte-identical). Status query gains -- . + git rev-parse --show-prefix path normalization; subproject HEAD becomes the subtree's last-touching commit (git log -1 -- .), a real ancestor so it remains a valid git diff <base>..HEAD -- . manifest baseline; unborn: sentinel for the no-commit-yet / unborn-branch edges. Also fixes the second bug found during planning (repo-root-relative status paths meant a subproject's own committed openwiki/ output wasn't excluded → hasRepositorySourceChanged reported true on every page-rewriting update).
• 82821ff — adversarial-review follow-ups.

Adversarial review outcome: correct, no HIGH/MEDIUM defects. Verified empirically (throwaway repos) that the subtree-last-commit stays a valid scoped diff base even through evil/TREESAME merge shapes, and that the fingerprint (not the baseline) is the real correctness gate — so a wrong baseline can never produce a false skip. Three LOW findings, all addressed in 82821ff:

1. readSubtreeFingerprintHead now confirms HEAD doesn't resolve (rev-parse --verify HEAD) before returning unborn:, so a git log failure on a born branch propagates instead of being masked (parity with the whole-repo path).
2. Strengthened a tautological test (now advances global HEAD past the subtree so it fails without the fix).
3. Added the mixed-baseline migration coverage (global commit as a subtree-scoped diff base across sibling commits) + an unborn-branch subproject snapshot test.

Verification: typecheck ✓ · build ✓ · lint ✓ · full suite 3659 passed / 3 skipped / 0 failed.

Deliberately deferred (documented in the fix): the root-run fingerprint stays repo-wide — root is the aggregator, so re-planning it when a sub-wiki changes does not violate the no-cross-subproject-cascade invariant. Scoping root correctly needs root-excluding-nested in the byte-hash + a scoped root HEAD, which is a separate follow-up if ever wanted.

Closing as fixed; lands on main when PR langchain-ai#439 merges.