refactor: close the final provider-architecture audit items

[steipete]

Provider architecture resolutions

1. Derive provider-specific PTY watchdog, executable-override, and probe-working-directory behavior from ProviderTTYLaunchConfig on each provider descriptor instead of hard-coding Claude in the shared runner.
2. Rename the shared PTY opt-in to useProviderProbeWorkingDirectory and carry the descriptor-derived behavior through provider version detection and its focused tests.
3. Relocate StatusItemController+ClaudeSwapMenu.swift into the Claude provider-owned source directory.
4. Mark the two intentional Codex historical-usage writes accurately: live weekly samples and usage-breakdown backfill.
5. Mark the intentional Codex empty-menu default accurately.
6. Mark the intentional Claude legacy plan-utilization migration and Codex visible-account/session ownership boundaries accurately.
7. Mark the Codex app-server executable default accurately as RPC-client ownership rather than shared provider policy.
8. Replace the generic token-cost reset justification with the truthful legacy Codex/Claude failure-gate reason, explicitly documenting the open question that including Vertex AI's shared transcript scanner would change error-surfacing behavior.

Scanner tightening

• Keep a single labeled or positional provider argument as an architecture finding.
• Recognize fully qualified UsageProvider.<case> references while excluding matching derived instance aliases.
• Record 133 newly recognized provider tokens as exact line/anchor/provider-set suppressions, each with a written ownership reason.

🤖 Generated with Claude Code

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 5, 2026, 11:53 PM ET / August 6, 2026, 03:53 UTC.

ClawSweeper review

What this changes

This PR moves Claude-specific PTY watchdog, executable-override, and probe-directory rules into its provider descriptor, and tightens the provider-architecture audit with exact suppressions for newly recognized references.

Merge readiness

⚠️ Ready for maintainer review - 3 items remain

Keep open for normal owner sign-off: the PR is a focused provider-launch refactor with no discrete correctness defect found, while VISION.md classifies broad refactors as sign-off work.

Priority: P3
Reviewed head: fc6af0267f3145791d727d4eb940106a12edd9fb
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The patch has a coherent descriptor boundary and fail-closed audit checks, with normal sign-off and pending CI remaining.
Proof confidence	🌊 off-meta tidepool	Not applicable: This owner-authored internal refactor has no direct user-visible behavior claim; focused tests and the pending CI shards are the relevant validation.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This owner-authored internal refactor has no direct user-visible behavior claim; focused tests and the pending CI shards are the relevant validation.
Evidence reviewed	5 items	Descriptor-owned launch behavior: Claude’s descriptor now owns the override key, watchdog helper name, and prepared probe working directory; the shared runner consumes those fields rather than naming Claude directly. Shared runner preserves the launch decision: The runner resolves descriptor launch metadata, conditionally wraps the executable with its declared watchdog, and applies the descriptor directory only when requested. Audit suppressions fail closed: Each newly recognized reference is checked against an exact file, line, anchor, provider set, and non-empty ownership reason before it is removed from the audit result.
Findings	None	None.
Security	None	None.

How this fits together

CodexBar starts provider CLIs through a shared pseudo-terminal runner. Provider descriptors supply CLI metadata that determines how the runner resolves an executable, helper watchdog, and safe working directory before collecting usage output.

flowchart LR
A[Provider descriptor] --> B[PTY launch metadata]
C[CLI probe request] --> D[Shared PTY runner]
B --> D
D --> E[Executable and working directory selection]
E --> F[Provider CLI]
F --> G[Usage and version output]

Loading

Decision needed

Question	Recommendation
Should this broad provider-architecture refactor be approved under VISION.md’s sign-off rule once its pending test shards complete?	Approve after CI completes: Accept the descriptor-owned launch metadata and exact audit suppression model once the pending test shards are green.

Why: The source supports the refactor’s correctness, but VISION.md reserves broad refactors for explicit human approval rather than automated cleanup.

Before merge

• Resolve merge risk (P1) - VISION.md calls for sign-off on broad refactors; the large architecture-audit table should receive normal human review after the pending test shards complete.
• Complete next step (P2) - Owner sign-off is required for this broad refactor under VISION.md; no narrow automated repair is identified.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production versus test delta	production +73/-37, tests +932/-52	About 90% of changed lines are audit-test coverage and exact suppressions, so review should focus on their fail-closed matching semantics.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Merge the descriptor-owned launch model after owner sign-off and successful focused/macOS test coverage, retaining exact anchored audit suppressions as the guard against future policy drift.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Merge the descriptor-owned launch model after owner sign-off and successful focused/macOS test coverage, retaining exact anchored audit suppressions as the guard against future policy drift.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a refactor PR, not a report of broken externally reproducible behavior.

Is this the best way to solve the issue?

Yes. The descriptor configuration preserves the prior Claude-specific launch inputs while removing the shared runner’s direct Claude dependency, and the audit suppressions are exact-anchor checked.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 770ec06d2fc4.

Labels

Label justifications:

• P3: This is internal provider-architecture maintenance without a reported user-facing regression.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This owner-authored internal refactor has no direct user-visible behavior claim; focused tests and the pending CI shards are the relevant validation.

Evidence

What I checked:

• Descriptor-owned launch behavior: Claude’s descriptor now owns the override key, watchdog helper name, and prepared probe working directory; the shared runner consumes those fields rather than naming Claude directly. (Sources/CodexBarCore/Providers/Claude/ClaudeProviderDescriptor.swift:5, fc6af0267f31)
• Shared runner preserves the launch decision: The runner resolves descriptor launch metadata, conditionally wraps the executable with its declared watchdog, and applies the descriptor directory only when requested. (Sources/CodexBarCore/Host/PTY/TTYCommandRunner.swift:641, fc6af0267f31)
• Audit suppressions fail closed: Each newly recognized reference is checked against an exact file, line, anchor, provider set, and non-empty ownership reason before it is removed from the audit result. (Tests/CodexBarTests/ProviderArchitectureGatekeeperTests.swift:3418, fc6af0267f31)
• Feature-history routing: Recent history shows the provider-architecture and PTY surfaces have been developed through a sequence of commits by steipete, including the current main provider-architecture gatekeeper work. (Sources/CodexBarCore/Host/PTY/TTYCommandRunner.swift:641, 770ec06d2fc4)
• Current-main comparison: Current main is 770ec06; this branch remains a distinct 13-file change and is not part of the released main tree. (Sources/CodexBarCore/Host/PTY/TTYCommandRunner.swift:641, fc6af0267f31)

Likely related people:

• steipete: Current and preceding provider-architecture, descriptor, and PTY commits are authored by steipete; this PR is also owner-authored. (role: recent area contributor and feature-history owner; confidence: high; commits: fc6af0267f31, 770ec06d2fc4, 4cdb349cbc57; files: Sources/CodexBarCore/Host/PTY/TTYCommandRunner.swift, Sources/CodexBarCore/Providers/Claude/ClaudeProviderDescriptor.swift, Tests/CodexBarTests/ProviderArchitectureGatekeeperTests.swift)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.