# Code SHA resource governance handoff

## Context

TiDB code diagnosis no longer materializes a snapshot or Git worktree for each
selected commit. A shared bare mirror stores Git objects once, while a selected
code context is a small immutable reference of the form
`tidb:<40-character-sha>:source`. The context covers the complete selected
commit, including test files and testdata.

Code reads are performed on demand through backend-controlled Git object
queries (for example `ls-tree`, `grep`, and `show`). The agent does not invoke
Git directly. This removes the previous main reason for a strict per-user SHA
or worktree-count limit: every selected SHA no longer creates a separate
1–2 GB checkout.

The current code-investigator refinement contract is being updated separately
in PR #1128. It is intentionally out of scope for this resource-governance
task.

## Agreed direction

- Do not impose a strict per-user limit on the number of selected or retained
  SHA references.
- Continue to limit active code-diagnosis work, because model execution and
  concurrent Git reads still consume shared resources.
- Treat bare-mirror storage as a platform-level resource. A newly requested
  SHA can require a remote fetch and can grow the shared mirror, even though a
  prepared SHA reference itself is tiny.

## Decisions to confirm before implementation

### 1. Existing SHA limit scope

Recommended default: remove the legacy SHA-count limit for code diagnosis.

Confirm whether that limit is used only by code diagnosis or is also shared by
other code-version-selection features. If it is shared, retain the appropriate
non-diagnosis protection instead of removing it globally.

### 2. Active diagnosis concurrency

Recommended default:

- Per user: at most 2 active code-diagnosis runs.
- Global: retain the current limit of 6 active runs initially, then adjust from
  production metrics.

These limits apply to running diagnosis tasks, not the number of SHA references.

### 3. Mirror capacity protection

Recommended first phase:

- Emit metrics for bare-mirror size, first-SHA fetch count, and first-fetch
  latency/failures.
- At 80% of the PVC capacity, reject a request that would require a new remote
  fetch and return an actionable capacity error; existing mirror objects remain
  readable.
- Alert on the same threshold.

Do not automatically prune or run aggressive `git gc` in the first phase.
Those operations need coordination with concurrent Git readers, so retention
(TTL/LRU) should be designed after observing real mirror growth.

### 4. Commit fetch behavior

Recommended default: retain on-demand retrieval of any remotely reachable TiDB
commit. Return explicit errors for an unavailable commit, missing permission,
or a fetch timeout.

## Intended implementation scope after confirmation

1. Locate and remove or narrow the legacy per-user SHA/worktree limit.
2. Add per-user active code-diagnosis concurrency admission control.
3. Preserve the existing global active-diagnosis guard and make its usage
   observable.
4. Add bare-mirror storage and first-fetch metrics.
5. Add the PVC high-water admission guard and user-visible, localized failure
   copy if a UI change is needed.
6. Add focused backend tests for admission decisions and capacity thresholds.

## Deliberate non-goals for the first PR

- No per-SHA snapshot or worktree recreation.
- No automatic mirror eviction, prune, or Git garbage collection.
- No change to source-evidence validation at the immutable SHA.
- No change to the refinement-loop contract in PR #1128.