tensor-grep-ledger

name	tensor-grep-ledger
description	Use when coordinating multiple agents on the same repo with tg ledger — advisory claim/release/list (Slice 1) and content-addressed finding record/find reuse (Slice 2). Never blocks edits; overlaps are informational. Distinct from tg evidence emit (produces receipts) and from docs/BACKLOG.md (product backlog, not this CLI).

tensor-grep ledger (EXPERIMENTAL, ADVISORY-tier)

Verified against tg 1.110.14 (LIVE 2026-08-11 gotcontext-saddle — Slice 1 rollup

• Slice 2 find repo-visibility reconfirmed; prior 1.101.22 / 1.93.0 #706).

tg ledger is ADVISORY-tier, not MANDATORY or OPTIONAL, in the vocabulary a multi-agent-coordination ecosystem needs to stay legible (the same MANDATORY/OPTIONAL/ADVISORY split the ruah coordination layer uses): a claim never blocks an edit, overlaps are reported for the caller to decide, and treating one as a lock is a misuse of the contract, not a bug in it.

When to use

Need	Command
Tell sibling agents "I'm touching this symbol/file"	tg ledger claim
See live claims on a root	tg ledger list
Drop a claim	tg ledger release
Publish an artifact for reuse (evidence / blast-radius / context / map)	tg ledger record
Reuse a prior artifact instead of recomputing	tg ledger find

Advisory only — claim never blocks an edit. Overlaps are reported for the caller to decide.

Slice 1 — claims (PATH-canonicalization FIXED, v1.93.0/#706)

tg ledger claim REPO --symbol open_session --intent edit --agent-id "$AGENT_ID" --json
tg ledger list REPO --json
tg ledger release REPO --claim-id "$CLAIM_ID" --json
# or: tg ledger release REPO --symbol open_session --agent-id "$AGENT_ID" --json

• Fixed behavior (v1.93.0, #706 — the root cause of the 1.92.1-era "PATH trap" was PHYSICAL: each command resolved the store directory from the literal PATH argument, so claim core/hooks and list . landed in two different on-disk stores). Claims now canonicalize to the nearest .git ancestor (a worktree's .git FILE — not just a directory — is resolved correctly; a non-git dir falls back to the literal path), so claim core/hooks and list . (or list $REPO_ROOT, or any other subtree PATH under the same repo) hit the same store. list [PATH] additionally rolls scope UP: a claim recorded at core/hooks is visible from a list at the repo root, matched by a segment-wise _scope_contains check (root-relative POSIX segments), not a naive string-prefix compare — so core/hooks-extra can no longer false-match a claim scoped to core/hooks. ClaimRecord gained a stored scope field (root-relative POSIX path), but only list matches against it (the _scope_contains rollup above). release deliberately does NOT scope-match: it matches ONLY by exact --claim-id, or --symbol restricted to the resolved agent's OWN live claims — the PATH SCOPING paragraph of release_claim's docstring says why (adding rollup-scope matching to release would let one call silently drop an unrelated sibling agent's claim that merely shares a symbol name under a broader/ancestor scope). Scope awareness entered release only on the FAILURE path: a release with --claim-id/--symbol that matches nothing now emits unmatched_reason + a bounded live_claims_elsewhere list (so the caller can see the claim IS there, just not under the id/symbol asked for) instead of a bare released_count: 0. A bare-path release with neither --claim-id nor --symbol now fails closed ("requires --claim-id or --symbol") rather than silently no-op'ing.
• Migration note: claim/list/release stores written before #706 (keyed by the pre-fix literal-path scheme) become invisible orphans under the new canonical-store resolution — their content is TTL-bounded (see below) and safe to hand-delete; they are not corrupt, just superseded.

Dogfood: claim/list/release round-trip PASS from any subtree PATH under the same repo (v1.93.0/#706 closing dogfood); record+find fresh PASS including find . after record core/hooks (1.101.17).

Slice 2 — findings reuse (repo-visible find as of 1.101.17 dogfood)

Live dogfood (1.101.17): after tg ledger record core/hooks --receipt …, tg ledger find PATH --symbol S --fresh-only returns fresh findings for PATH in {., core/hooks, core, $REPO_ROOT, core/skills} — same-repo visibility, not limited to the literal record PATH. Prefer an explicit PATH on record still; do not assume cross-repo visibility. Older skills claiming Slice 2 is strictly literal-path-rooted are stale relative to this binary.

tg evidence emit REPO --capsule capsule.json --query "task" --json --agent-id "$AGENT_ID" > receipt.json
tg ledger record REPO --receipt receipt.json --artifact-kind evidence-receipt --symbol open_session --agent-id "$AGENT_ID" --json
tg ledger find REPO --symbol open_session --artifact-kind evidence-receipt --fresh-only --json
# also OK: tg ledger find . --symbol open_session --fresh-only --json

--artifact-kind: evidence-receipt | blast-radius | context-pack | repo-map.

find exit contract (3-state):

Exit	Meaning
0	≥1 fresh finding (revision matches — safe to reuse)
1	nothing matched or matches exist but none fresh → recompute
2	fail-closed (missing --symbol, corrupt index/blob)

Dogfood (1.101.17): after record, find at . / subtree / abs root → exit 0, any_fresh: true.

Agent loop with ledger

tg ledger claim REPO/src --symbol SYM --agent-id "$AGENT_ID" --json
# if overlaps: coordinate or proceed knowingly (advisory)
tg agent REPO/src "task" --json > capsule.json
tg evidence emit REPO --capsule capsule.json --query "task" --json --agent-id "$AGENT_ID" > receipt.json
tg ledger record REPO --receipt receipt.json --symbol SYM --agent-id "$AGENT_ID" --json
tg ledger release REPO --symbol SYM --agent-id "$AGENT_ID" --json

Claim visibility is not proof of correctness — this loop is coordination, not verification. A clean claim/release round-trip (like a conflict-free git rebase) only proves agents coordinated; it says nothing about whether the merged result is right. Motivating incident: a multi-PR drain sequentially rebased several parallel PRs onto a shared test_lang_registry file — every rebase was conflict-free, but a silent auto-merge had dropped a lang_* import, caught only when the test suite was re-run afterward (ImportError), not by the clean rebase itself. Run real validation (tests, dogfood) before/after release, not just an uncontested claim — the ledger tells you who touched what, never whether it's correct.

Related

• tensor-grep, tensor-grep-enterprise-agent, tensor-grep-enterprise-review-bundle
• Surface/schema may change in a minor release — re-check tg ledger --help on upgrades