feat(cli): opt-in exit contract for index_repository

[Blysspeak]

Refs #2168

Opt-in exit contract for cli index_repository

A freshness gate cannot read a tool's account of itself, it reads the process
status. Today index_repository returns 0 for an index that parsed part of
the tree, and the same 1 whether the repository is missing or a pipeline fell
over inside one that exists. Callers cannot tell those apart.

Nothing changes unless CBM_GATE=1 is set. Without it the CLI exits
exactly as before. With it, grading happens in the CLI only; MCP responses are
untouched, so agents and scripts/soak-test.sh, which judge by JSON-RPC and
tool-level isError, see exactly what they saw before.

outcome	today	with CBM_GATE=1
indexed, clean	0	0
indexed, files parsed partially above threshold	0	2
indexed, a file did not parse at all	0	2
indexed, node count far below expectation (status: degraded)	0	2
pipeline failed inside a reachable repository	1	1
repo_path absent, unreadable, or not a directory	1	3

Thresholds, both optional, negative disables the check:

• CBM_GATE_MAX_UNUSABLE, default 0, absolute count of unparsable files
• CBM_GATE_MAX_PARTIAL_PCT, default 10, share of partially parsed files

The two defaults differ deliberately. A file that did not parse at all is a
defect and gets no tolerance. Partial parsing marks constructs a grammar does
not cover, a property of language support rather than of index quality: this
repository itself sits at 5.8% with a fully working graph. A gate its own
project cannot pass gets switched off, which protects nothing.

Additive fields

• files_indexed and parse_partial_pct on the index response. The ratio had
  no denominator, and a gate that can only pass or fail cannot say how
  partial a parse was.
• reason on failures, target_unavailable or pipeline_failed. The hint
  text read identically for both.

Verification

Full suite on this branch: 8001 passed, 1 failed, 7 skipped. The one failure is
daemon_ipc_posix_single_uid_userns_real_smoke_issue1830, which fails the same
way on a clean build of main at 055fbb7 on this machine (user-namespace
setup), so it is unrelated to this change.

13 tests in the cli suite pin the contract, including that an unset, empty
or 0 CBM_GATE leaves the historical status untouched.

End to end on this repository (clean git worktree of this branch, isolated
CBM_CACHE_DIR and CBM_RUNTIME_DIR), exit status read without a pipeline so
$? is the command's own:

gate unset:
  missing path                                   exit 1   (unchanged)
  this repository                                exit 0   (unchanged)
CBM_GATE=1:
  missing path                                   exit 3   reason target_unavailable
  this repository                                exit 0   files_indexed 1065, parse_partial_pct 5.8, under the default 10
CBM_GATE=1 CBM_GATE_MAX_PARTIAL_PCT=5:
  this repository                                exit 2

The same sequence against a binary built from main at 055fbb7 gives
1 / 0 / 1 / 0 / 0: today's status, unchanged by the variable.

[github-actions]

Thanks for opening this — it has been seen, and it is queued.

This note is automated, but it is not a brush-off: it exists so you know where your PR stands instead of having to guess from silence.

Current review status: working through a backlog. 0.9.1-rc.1 is out, so the release freeze that held reviews is over — but it left a large queue of open pull requests behind it, and we are reading through them oldest-first. The background is in discussion #1144.

What that means for this PR, concretely:

• It will not be closed for inactivity. No stale bot touches pull requests here.
• It may still sit a while before a human reads it. That is on us, not on you.
• Older PRs are read first, so a recent one is not being skipped — it is behind a queue.

Things that will genuinely speed it up whenever review does happen:

• Keep it rebased on main — the tree is moving quickly right now, and a conflicting branch cannot be reviewed as the diff you intended.
• Get CI green, or say which failures you believe are pre-existing.
• Keep the change to one claim. Bundled features and refactors get split before they get merged, which costs you a round trip.
• Every commit needs a sign-off (git commit -s) — CI enforces DCO.

If this fixes a bug, a reproduction we can run is worth more than a description of the symptom.

Thanks for contributing, and sorry in advance for the wait.

[DeusData]

Thank you for the detailed CLI proposal and its tests. This spans exit-status semantics, environment defaults, output fields and index handling, so we need more time to review the compatibility and scope decisions before giving a direction. Please do not read the triage labels as approval of new defaults.

The review queue is currently full, so detailed feedback may take a little time. We are working through it carefully and appreciate the work you have put into supporting the project. Thank you for your patience.

[Blysspeak]

Reworked after your note on defaults, and narrowed to one claim per the contributing guide.

The contract is now opt-in: nothing changes unless CBM_GATE=1 is set, so no existing caller sees a new code. graph_generation, seed_symbols_list, absolute_path and .cbmignore are out of this PR; if any of them is wanted I will open an issue for it separately.

Rebased on main, clang-format fixed, tracking issue #2168 with measurements on a clean main build and on this branch.