feat: warn when knowledge graphs are stale

[jiang4wqy]

Why

Understand Anything graphs are snapshots. After source files or Git history change, the dashboard and graph-consuming skills could continue presenting old relationships without telling the user. This addresses item 3 of #413: graph staleness was silent.

What the initial PR version missed

The first version established the warning path, but its freshness model was too narrow for real repositories:

• it checked only once when the dashboard mounted, so an already-open window did not update after later edits or commits
• it compared only the embedded graph commit with HEAD, so staged, unstaged, and untracked source changes were invisible
• it treated commit mismatches as a generic stale/behind state instead of distinguishing behind, ahead, and diverged histories
• repository-wide checks could report changes from a sibling project in a monorepo
• it checked only the knowledge graph, not the optional domain graph independently
• synchronous Git execution could block the dashboard server, and there were no explicit timeout/output limits
• the client trusted the endpoint shape too loosely, while errors and cache behavior were not hardened
• graph-consuming skills passed the stored hash directly to git diff without first resolving it as a commit
• the static demo could attempt a freshness request even though no live Git backend exists

What this revision adds

Core freshness engine

• adds asynchronous, shell-free Git execution with a 5-second timeout and bounded output
• reports fresh, dirty, stale, or unknown, with structured reasons instead of guessing
• detects staged, unstaged, and untracked project changes using NUL-delimited paths
• scopes commit and worktree checks to the selected project and ignores generated .understand-anything/ output
• resolves abbreviated graph hashes safely and classifies behind, ahead, and diverged histories
• evaluates knowledge and domain graph commits from one repository snapshot
• preserves the legacy staleness exports for compatibility

Dashboard behavior

• exposes token-protected /staleness.json data with sanitized failures and Cache-Control: no-store
• validates the complete response shape before rendering it
• fetches once on load, then refreshes only when the browser window receives focus
• aborts superseded requests and ignores late responses, preventing stale network results from overwriting newer state
• shows graph-specific status, relation-aware guidance, and up to eight changed paths on desktop and mobile
• skips freshness requests in the static demo unless VITE_STALENESS_URL is explicitly configured

Skill preflight and release metadata

• updates understand-chat, understand-diff, understand-domain, understand-explain, and understand-onboard
• resolves the stored graph commit with git rev-parse --verify --end-of-options before using it
• emits a soft warning without blocking the normal skill workflow
• bumps all five plugin manifests from 2.8.2 to 2.8.3

Scope

This PR detects and explains stale graphs; it does not silently regenerate them. Regeneration remains an explicit /understand or /understand --force action so opening or refocusing the dashboard cannot trigger expensive analysis unexpectedly.

Related work

• Addresses item 3 of Enhancement ideas from heavy use on a large, fast-moving Rust codebase #413 (silent graph staleness). Enhancement ideas from heavy use on a large, fast-moving Rust codebase #413 is an umbrella issue, so this PR intentionally does not auto-close it.
• Related context: Bug: auto-update PARTIAL_UPDATE overwrites fingerprints.json instead of merging — causes permanent FULL_UPDATE regression #152 tracks fingerprint merge corruption. This PR does not modify the graph merge algorithm.
• Partial implementation overlap: fix(staleness): read changed files with -z so non-ASCII/quoted paths are detected #452 fixes NUL-delimited paths in the legacy incremental merge helper. This PR independently uses NUL parsing in the new asynchronous freshness engine, so merge order should preserve fix(staleness): read changed files with -z so non-ASCII/quoted paths are detected #452's legacy-path fix.

Validation

Final publish branch after merging current main:

• pnpm lint
• Core build: pnpm --filter @understand-anything/core build
• Skill build: pnpm --filter @understand-anything/skill build
• Core tests: 41 files, 911 tests passed
• Dashboard tests: 10 files, 80 tests passed
• Root tests: 22 files passed, 1 conditionally skipped; 267 tests passed, 6 conditionally skipped
• Dashboard production build and static demo build passed
• Full workspace pnpm build passed
• git diff --check origin/main..HEAD passed
• production dashboard bundle contains no child_process runtime import

Manual browser validation used a real repository graph with 432 tracked files, 97 nodes, 183 edges, and 7 layers. Dirty, stale, and fresh transitions updated on window focus without reload; the changed-path summary and 390 px mobile layout were also checked.

[jiang4wqy]

@ZebangCheng

[ZebangCheng]

Thank you @jiang4wqy