| 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
- 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
--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
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
