feat(sync): per-file staleness banner — MCP + CLI (closes #66 phase-1)

[Wolfvin]

Closes #66 (phase 1)

Ringkasan

Phase 1 dari issue #66 — per-file staleness banner. Detects when indexed files have been edited since the last scan dan surfaces a warning to the agent before the tool's actual output. Banner prepended ke semua read-tool MCP responses (suppressed on scan/init — those are the fix path).

Perubahan

New files

File	Purpose
scripts/sync/__init__.py	Re-exports public API
scripts/sync/pending.py	StaleFileDetector (thread-safe, in-memory Dict[str, float] cache, 5s TTL per workspace) + detect_stale_files() + format_staleness_banner()
scripts/commands/staleness.py	codelens staleness CLI command — manual check + full list when MCP banner truncates to 10
tests/test_staleness.py	41 tests (detection, cache, thread safety, banner formatting, CLI, MCP integration)
docs/sync/staleness-banner.md	Arsitektur + design decisions

Modified

• scripts/mcp_server.py — MCPServer._staleness_detector (lazy) + _attach_staleness_banner() prepends banner to read-tool responses (suppressed on scan/init) + _invalidate_staleness_cache() after successful scan
• README/SKILL/SKILL-QUICK/pyproject/skill.json/graph_model.py — sync'd via sync_command_count.py --apply (command count 70 → 71)

Detection algorithm

1. Load stored mtimes dari .codelens/mtimes.json (source of truth — written by incremental.save_mtimes() on every scan)
2. For each indexed file: os.stat() compare (st_size, st_mtime_ns)
3. If mtime differs, re-compute SHA-256 (only when needed) untuk confirm content actually changed — skips false positives dari touch / git checkout of identical content
4. Sort by edit_age ascending (most recent edit first)
5. Return tuple of StaleFile records

Cache

5s TTL per workspace, thread-safe via threading.Lock. Invalidated after successful scan so next read tool re-probes against fresh index. Exists karena walking 10k+ files on every tool call would add ~50ms latency.

Banner shape

⚠️ Some files referenced below were edited since the last index sync.
The index may be stale for these files — re-run `codelens scan` to refresh.
Stale files (showing 3 of 3, most recent first):
  • path/to/file.py (edited 2.3s ago, content differs)
  • other.js (edited 1m 12s ago, content differs)
  • third.ts (edited 5m 0s ago, size/mtime differ)

Plain text (not markdown) — renders correctly di terminal + MCP content blocks. ⚠️ marker untuk agent pattern-matching. "content differs" vs "size/mtime differ" distinguishes hash-confirmed staleness dari mtime-only staleness. Truncates to 10 files dengan "and N more" — full list via codelens staleness.

MCP integration

_attach_staleness_banner() dipanggil di 3 response paths:

1. Cached response — banner attached (staleness is workspace property, not call property)
2. Fresh success — banner attached, unless scan/init
3. Error response — banner attached, unless scan/init (staleness context lebih useful dari error itself)

Banner prepended to first content block's text AND attached as structured response['_staleness'] field. Both paths ensure warning surfaces regardless of how agents consume tool output.

After successful scan, _invalidate_staleness_cache(workspace) called so next read tool re-probes against fresh index.

Definition of Done (Phase 1, dari issue)

• In-memory Dict[str, float] (path → edit_timestamp), thread-safe via threading.Lock
• Walk indexed file list dengan os.stat(path) untuk compare (st_size, st_mtime_ns)
• Re-compute content-hash only when size/mtime changed
• Prepend ⚠️ Some files referenced below were edited since the last index sync… banner ke MCP responses
• Surface non-referenced pending files as small footer ("and N more" line + codelens staleness for full list)
• New file: scripts/sync/pending.py

Phase 2 (connect-time catch-up), Phase 3 (native file watcher), Phase 5 (anonymous telemetry) deferred ke follow-up issues per issue spec.

Verifikasi

• python3 -m pytest tests/test_staleness.py -v → 41 passed
• python3 -m pytest tests/test_staleness.py tests/test_command_count.py tests/test_doctor.py tests/test_cli.py tests/test_codelens.py tests/test_mcp_hooks.py → 220 passed, 0 failed
• python3 scripts/sync_command_count.py --check → clean
• codelens staleness smoke-tested end-to-end (text + json output, --no-confirm-hash flag)
• MCP integration verified: banner prepended on stale workspace, suppressed on fresh, cache invalidated after scan, init failure isolated

Design decisions

1. scripts/sync/ subpackage — staleness dan worktree mismatch (Phase 4, PR feat(sync): worktree index mismatch detection — doctor check + MCP banner (closes #66 phase-4) #154) are independent concerns sharing only the "index vs working tree" theme. Package keeps them discoverable without forcing them into one file.
2. Lazy detector construction in MCPServer — keeps import out of server startup path. If sync subpackage fails to import, server still starts; only staleness detection degraded.
3. Prepend (not append) banner — agents read top-to-bottom. Banner at bottom = agent acted on stale data before reaching it.
4. Both structured _staleness field AND prepended text — different agents consume tool output differently. Both paths ensure warning surfaces.
5. content_hash_changed tri-state (True/False/None) — True = hash confirmed stale, False = touch (skip), None = no stored hash available ("size/mtime differ").
6. mtimes.json as source of truth (not SQLite files table) — mtimes.json written by every scan including legacy JSON registry workspaces. SQLite files table only populated when persistent registry active.
7. 5s cache TTL — balances freshness (user edit → banner within seconds) against cost (re-stat 10k files on every call = ~50ms).

Findings (di luar scope)

• test_codelensignore.py::TestBackwardCompat::test_actual_target_dir_is_ignored fails di origin/main (pre-existing, bukan regresi dari PR ini).
• PR feat(sync): worktree index mismatch detection — doctor check + MCP banner (closes #66 phase-4) #154 (issue [FEATURE] Telemetry, file watcher & worktree detection — observability + reliability #66 Phase 4 — worktree mismatch) also creates scripts/sync/__init__.py dan modifies mcp_server.py. If PR feat(sync): worktree index mismatch detection — doctor check + MCP banner (closes #66 phase-4) #154 merges first, this PR needs a small rebase untuk resolve __init__.py overlap (both add same package marker) dan mcp_server.py overlap (both add methods to MCPServer — different method names, no conflict). BOS will resolve at merge time.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud