Introduce cache-aware layered handoff (prefix/delta) with lazy file context across CLI, hooks, and MCP

[JordanCoin]

Summary

This PR upgrades codemap from a single handoff blob into a cache-aware, agent-agnostic context transport layer.

It adds deterministic, budgeted, layered handoff artifacts (prefix + delta), lazy file-detail loading, cache telemetry, and hook output de-duplication so context is more useful and less wasteful across sessions/agents.

Problem

Large repos and repeated session hooks can burn context quickly and redundantly:

• session hooks could output too much text
• multiple session-start blocks repeated the same “what changed” signal
• handoff data was useful but not structured for cache reuse
• no stable split between slow-changing context and fast-changing context

What Changed

1. Layered handoff artifacts

• Added prefix snapshot (stable project context) and delta snapshot (recent work context).
• Added deterministic hashes: prefix_hash, delta_hash, combined_hash.
• Persisted split artifacts:
• .codemap/handoff.latest.json
• .codemap/handoff.prefix.json
• .codemap/handoff.delta.json

2. Lazy loading

• Delta now carries changed-file stubs (path, status, size, hash).
• Added on-demand full detail loading for a specific changed file.
• CLI: codemap handoff --detail <file> .
• MCP: get_handoff with file="<path>"

3. Cache metrics + observability

• Added reuse telemetry in artifact JSON (metrics block).
• Appends metrics entries to .codemap/handoff.metrics.log.
• Added metrics log cap (keeps last 500 lines).

4. Deterministic + budgeted output

• Added shared output budget/truncation policy in limits.
• Unified line-safe truncation across hooks/MCP/handoff renderers.
• Removed volatile relative-time rendering from compact handoff output.
• Preserved timestamp only when content actually changed.

5. Hook UX improvements (de-dup)

• Session-start now avoids overlapping “changed files” blocks.
• If recent handoff already has changed-file context:
• skip branch diff block
• skip last-session-events block
• keep the richer recent handoff block

6. Robustness improvements

• Session-stop handoff now resolves a valid base ref (not hardcoded main fallback only).
• Improved changed-file filtering behavior and binary/log noise handling.
• Added fallback file-count resolution when daemon state is unavailable.

7. Compatibility + migration

• Legacy top-level handoff fields remain for compatibility.
• Marked as deprecated for planned schema v2 removal after client migration.
• Save behavior clarified:
• CLI handoff saves by default (--no-save to disable)
• MCP get_handoff is read-only by default (save=true to persist)

Why This Matters

• Better continuity when switching between Claude/Codex/MCP clients.
• Lower context waste from redundant hook output.
• More cache-stable context shape (static-ish prefix + dynamic delta).
• Better tooling/debuggability via hashes + metrics.
• Keeps human output focused while preserving telemetry for automation.

Validation

• go test ./...
• go vet ./...
• staticcheck ./...
• gofmt -l .

All passing.

Follow-ups

• Remove legacy top-level mirrors in schema v2.
• Optional hash strategy for very large changed files (size-gated/partial hashing).
• Potentially rotate metrics by file size in addition to line count.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 548a81531a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".