[zzet]

Every new-path checkout discovery shared one daemon-wide limit of 32 jobs, and a job was allocated before its family was known. One hung mount, a burst of worktree adds in one family, or sessions opened in untracked Git directories could fill that limit. From then on, every new worktree in every family was refused with "capacity reached". This draft bounds discovery per family, so a pending discovery is refused only inside its own worktree.

Draft status: the first three commits are done and tested. The last commit is a labelled wip: commit holding review fixes that have not been compiled or run yet, so CI on this draft may be red.

Changes

• gitstate.MarkerCommonDir. It reads a checkout's family common dir from its .git marker, with the reader the dirty sampler already uses, and resolves symlinks the way git rev-parse --path-format=absolute does. No Git process is spawned. A test asserts it matches Git for a main checkout, a linked worktree, a subdirectory and a relative path.
• Indexer: per-family bound.
  • The family is resolved from the marker before a job is allocated. A path outside Git, or in an unknown family, returns not-found with no job and no Git spawn.
  • A discovery already running for a path still answers it, so a binding that changes under a pending proof is still reported stale.
  • Each family runs at most 8 discoveries at once, and only that family's new paths are refused while it is full. Finished jobs that only keep a result do not count.
  • The daemon-wide bound of 32 now counts only workers still running past their work deadline, and refuses only families that own one.
  • The proof inside the job is unchanged.
• Typed refusal. A refusal is a CheckoutDiscoveryPendingError naming the checkout root, the family and a reason: in_progress, draining, family_capacity or stuck_capacity. It still unwraps to ErrCheckoutMutationBusy, so every caller keeps treating it as retryable.
• Daemon admission refusal. It carries data.path (the checkout root), data.family, data.reason and state: discovery_pending, and stays retryable: true.

Tested (first three commits, at 213c320)

• On the base, the new indexer and daemon tests fail: one family fills all 32 discovery slots, and another family's new worktree is refused with "capacity reached".
• At 213c320, -race runs pass, 108 top-level tests in all:
  • gitstate TestResolveFamilyDirs*;
  • indexer TestObserveCheckoutPath*, including both new stuck-family tests and every existing binding-change subtest;
  • the internal/mcp checkout and worktree discovery, admission, source, mutation, freshness and ref-view tests;
  • the cmd/gortex admission, discovery and reload tests.
• cmd/gortex coverage includes:
  • the new daemon-level TestDispatcher_PendingDiscoveryStaysInItsWorktree: one family's discovery is hung; another family's worktree, the primary checkout and an unrelated tracked repository keep answering, and only paths inside the hung worktree are refused;
  • TestCheckoutAdmissionErrorPendingDiscoveryGolden.
• golangci-lint 2.14.0 over gitstate, indexer, mcp and cmd/gortex reports 0 issues.

Untested wip commit (926c2bb)

This commit holds the fixes for the last review round. None of them has been compiled or run.

• A request that joins a running discovery is refused with that job's own root and family, not with what its own marker read finds now.
• A proven job that no caller has authorized runs no Git work, so it no longer counts against its family's bound.
• data.path falls back to the session path when a refusal names no root.
• Two tests are tightened:
  • the indexer test now fails on any refusal of another family's worktree other than its own in_progress;
  • the daemon test first waits for a stuck session to be refused as draining.
• New tests: TestObserveCheckoutPathJoinedRefusalNamesItsOwnCheckout and TestObserveCheckoutPathDeniedDiscoveriesLeaveFamilyCapacity.

Once these fixes pass, they will be squashed into the indexer and daemon commits.

Not done

• Landing order. This lands after perf(daemon): add fair lanes for MCP dispatch #1159 and fix(startup): preserve loading admission until repository identity is ready #1162. The branch is rebased onto main once both are in; small conflicts are expected only in checkoutAdmissionError and the doc comment on checkoutForRequestPath.
• Benchmarks. The benchmark scenario "add worktrees while sessions are open" is not built yet; it builds on feat(bench): add strict budget collection and nightly evidence checks #1160's harness. The upgraded-user fixture depends on Make the v0.64.10 store upgrade safe: kill-tested harness, free-space precheck, backup #1028. The release-blocking benchmark item and the loadedit-8 ±15% check stay open until both exist.
• Manual check: the hung-git shim walkthrough from the issue has not been run.
• Known limits:
  • The marker read does not follow a symlinked .git entry, so such a checkout is not auto-discovered. Linked worktrees never use one.
  • Tool-level refusals stay plain-text view_building errors. Their text now names the root, family and reason, but structured data is only on the daemon admission error.

Refs #1033