Fix PortfolioTruth repository topology observation

[saagpatel]

What

Make PortfolioTruth repository-state observation topology-aware for conventional bare repositories, bare coordinators with linked worktrees, and working checkouts that intentionally track recovery refs.

Why

The configured path was treated as one ordinary working repository. That left a dangling bare coordinator as an opaque unknown and could present a recovery-tracking local main as if it represented GitHub's default branch.

Review Of What Was Built

• Recognizes conventional bare repositories during workspace discovery without climbing into a parent repository.
• Enumerates coordinator and linked-worktree state without exposing dirty file names.
• Selects a local worktree only when independently observed remote-default head evidence resolves it uniquely; the remote branch is a deterministic tie-break.
• Emits precise fail-closed reason codes for missing evidence, no matching worktree, malformed evidence, and ambiguous candidates.
• Preserves the existing repository-state envelope while adding topology and selection detail.

Cleanup Review

The repair is limited to the repository observer, bare-root discovery, and their fixtures. It does not edit portfolio-index, operator-os-explainer, catalog/reconcile files owned by the separate data-integrity lane, generated PortfolioTruth output, or Fable-owned UI/content.

Verification Summary

• Focused topology/discovery corpus: 18 passed.
• Full suite: 2,958 passed, 2 skipped.
• Ruff and git diff --check: passed.
• Live read-only probe: portfolio-index selects the clean linked worktree at GitHub's default head; operator-os-explainer returns remote_default_worktree_not_found against GitHub's current default head.
• Independent review: no remaining P0-P2 merge-relevant findings.

Shipped Summary

On this branch, active-product repository state no longer trusts a dangling coordinator HEAD, a stale local tracking ref, or ambiguous worktree topology as canonical remote-default truth.

Next Phase

Let head-bound CI and independent PR review complete. After merge, refresh the live GitHub repository evidence and regenerate canonical PortfolioTruth from the reviewed producer so the persisted snapshot reflects the repaired semantics.

Remaining Roadmap

• Merge through the protected default-branch workflow after checks/review.
• Refresh canonical PortfolioTruth with fresh remote-default evidence; no product or deployment mutation is required.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4f031e3980

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve unknown state when the Git probe fails

When Git cannot execute this probe—for example because safe-directory validation rejects the checkout, the repository is corrupt, or the Git executable is unavailable—the caught CalledProcessError/OSError is converted to None, causing a real repository to be reported as not_a_repository. Previously, these observation failures produced unknown; preserve that distinction so canonical portfolio truth does not claim the repository is absent merely because it could not be inspected.

AGENTS.md reference: src/AGENTS.md:L5-L10

Useful? React with 👍 / 👎.