fix: resolve graph freshness from repos nested under the project root

[pgm-serdkara]

Problem

A parent directory holding several checkouts is a valid analysis root:

~/Code/Acme/
├── api/     ← git repo
├── web/     ← git repo
└── .ua/knowledge-graph.json

getGraphFreshnessBatch builds one snapshot by running git rev-parse --show-toplevel / rev-parse HEAD in the project directory. That directory has no HEAD of its own, so the call throws and every graph is reported as:

{"status":"unknown","reason":"git-head-unavailable","graphCommitHash":"0818f44…"}

The dashboard then shows a permanent "Knowledge graph freshness could not be verified" banner. The confusing part for users is that re-running /understand does not clear it — the trigger is where the dashboard is pointed, not the age of the data, so the banner reappears immediately after a fresh full rebuild. Note the endpoint reads the correct graphCommitHash from meta.json; it simply has no HEAD to compare it against.

Fix

When the root snapshot fails, scan one level down for directories containing .git, and resolve each graph against the nested repo that can verify its commit via rev-parse --verify <hash>^{commit}.

Three deliberate choices:

1. Ownership is decided by commit hash, not directory name or metadata. Hashes are unique, so it is unambiguous, requires no new fields, and existing graphs resolve with no re-analysis.
2. Resolution is per graph, so knowledge and domain graphs can live in different sibling repos.
3. Timeouts do not trigger the scan — it would multiply a 5s wait by the number of nested repos, so git-command-timeout still returns immediately.

When nested repos exist but none owns the commit, the reason is now graph-commit-unavailable rather than git-head-unavailable, which is more accurate once repos are known to exist. A genuinely empty non-repo directory still returns git-head-unavailable exactly as before.

The scan is capped at 32 subdirectories and skips dotdirs and node_modules, so a wide parent directory cannot spawn unbounded git processes.

Tests

Four cases added to graph-freshness.integration.test.ts, all against real Git repositories:

• falls back to the nested repo owning the commit → fresh
• picks the correct sibling among several → stale / behind with the right headCommitHash and changedFiles
• batch: two graphs resolve to two different sibling repos
• nested repos exist but none owns the commit → graph-commit-unavailable

createRepository was refactored to share a new initRepositoryAt helper so repos can be created at a chosen path.

Verified on this branch's base commit:

• pnpm --filter @understand-anything/core test → 980 passed (46 files), including the pre-existing git-head-unavailable and missing-graph-commit cases
• pnpm lint → clean
• pnpm --filter @understand-anything/core build → clean

Also verified end-to-end against a real multi-repo parent directory: the dashboard's /staleness.json went from git-head-unavailable to {"status":"fresh","commitsBehind":0,"commitsAhead":0}, and the banner disappeared.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Fixes graph freshness evaluation when the configured project root is a non-repo parent directory containing multiple Git checkouts (nested repos). This aligns the freshness banner behavior with how graphs are actually produced (from a nested repo commit) so the dashboard can correctly verify freshness instead of permanently reporting git-head-unavailable.

Changes:

• Add a fallback path in getGraphFreshnessBatch that scans one level down for nested Git repos and resolves each graph against the repo that contains the graph’s commit.
• Introduce helpers for nested repo discovery, snapshot creation, and commit ownership resolution.
• Expand integration tests to cover nested-repo scenarios and refactor repository setup helpers for flexible repo placement.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
understand-anything-plugin/packages/core/src/staleness.ts	Adds nested-repo scanning + per-graph snapshot resolution when the project root has no Git HEAD.
understand-anything-plugin/packages/core/src/tests/graph-freshness.integration.test.ts	Adds integration coverage for nested-repo freshness resolution; refactors repo init helpers.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.