cli index_repository: exit status does not distinguish a partial index from a missing repository #2168

Problem

cli index_repository exits 0 for an index that parsed part of the tree, and exits 1 both when repo_path does not exist and when the pipeline fails inside a repository that does. A shell caller (set -e, a pre-commit gate, CI) cannot tell those outcomes apart without parsing the JSON.

Measured on this repository with a clean build of main at 055fbb7:

# tree: this repository checked out in a clean git worktree, isolated CBM_CACHE_DIR / CBM_RUNTIME_DIR
cli index_repository --repo_path /does/not/exist --name x ; echo $?
  {"status":"error","hint":"Pipeline failed. Check repo_path exists ..."}     exit 1
cli index_repository --repo_path <worktree> --name m --mode full ; echo $?
  status indexed, parse_partial_count 62, no denominator in the response      exit 0

62 partially parsed files out of 1065 is 5.8%, and a missing path exits with the same 1 as a pipeline failure inside a real repository.

The MCP side is fine: agents read isError and the response fields. This is only about the process status of the CLI.

Proposal

An opt-in contract, graded in the CLI, MCP responses untouched. Nothing changes unless CBM_GATE=1 is set, so no existing caller sees a new code:

Thresholds via environment, negative disables a check:

• CBM_GATE_MAX_UNUSABLE, count of files that did not parse at all, default 0
• CBM_GATE_MAX_PARTIAL_PCT, share of partially parsed files, default 10

Two additive response fields so a gate can quote the number in a refusal: files_indexed (the denominator) and parse_partial_pct. On failure, reason is target_unavailable or pipeline_failed.

Same repository, same build plus the change:

# same tree, same isolation, binary built from the PR branch
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

Why opt-in

This repository itself sits at 5.8% partially parsed files with a fully working graph, because partial parsing marks constructs a grammar does not cover. A gate that fires by default would start failing callers who never asked for it. Behind a switch it breaks nobody, and flipping the default later is a one-line change if you want it.

Status

Implementation with tests is in #2092, narrowed to exactly this change.