Provider plugin load fails from CLI when installed via symlink (Homebrew)

[djbclark]

Description

In version 0.48.1, the fix implemented in #2756 successfully prevents a hard crash when the CodexBarCore resource bundle is missing, and the bundle is now correctly shipped inside /Applications/CodexBar.app/Contents/Helpers/.

However, the "Provider plugin load failed" error still occurs when running the CLI via a symlink, which is the default behavior when installing via Homebrew (where /opt/homebrew/bin/codexbar symlinks to /Applications/CodexBar.app/Contents/Helpers/CodexBarCLI).

Because Bundle.module (or the fallback logic in CodexBarCoreResources) appears to probe for the bundle adjacent to the invocation path (/opt/homebrew/bin/) rather than the resolved physical path of the executable, it fails to find CodexBar_CodexBarCore.bundle and gracefully fails out (rendering plugins like OpenRouter unusable from the CLI).

Steps to Reproduce

1. Install CodexBar via Homebrew (or manually create a symlink to CodexBarCLI).
2. Run codexbar usage from the symlinked path.
3. Observe the output: Error: Provider plugin load failed: CodexBarCore resource bundle is missing next to the executable; reinstall or update CodexBar

Workaround

Running the executable directly via its absolute physical path works perfectly:
/Applications/CodexBar.app/Contents/Helpers/CodexBarCLI usage

Or by symlinking the bundle into /opt/homebrew/bin/:
ln -s /Applications/CodexBar.app/Contents/Helpers/CodexBar_CodexBarCore.bundle /opt/homebrew/bin/CodexBar_CodexBarCore.bundle

Suggested Fix

Update the resource resolution logic to resolve symlinks (e.g., using URL(fileURLWithPath: CommandLine.arguments[0]).resolvingSymlinksInPath()) before checking for executable-adjacent bundles.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 12, 2026, 10:17 AM ET / 14:17 UTC.

Summary
This remains a bounded current CLI bug: the documented symlink installation path can leave bundled provider plugins unavailable because resource lookup does not canonicalize the executable path.

Reproducibility: yes. —source and docs establish a high-confidence path: invoke the documented symlinked helper with a bundled-plugin provider, where the current resolver probes an uncanonicalized executable-adjacent location. A repair worker should first encode that path as a failing regression.

Next step
A focused source-proven repair can add physical executable-path resolution and regression coverage without a product decision.

Review details

Best possible solution:

Canonicalize the physical CLI executable location before probing its adjacent bundle, then prove both direct and symlinked packaged-helper launches load a real bundled provider plugin.

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

Yes—source and docs establish a high-confidence path: invoke the documented symlinked helper with a bundled-plugin provider, where the current resolver probes an uncanonicalized executable-adjacent location. A repair worker should first encode that path as a failing regression.

Is this the best way to solve the issue?

Yes—the narrow maintainable fix is to derive the resource directory from the resolved executable URL and add direct-versus-symlink regression coverage, retaining all existing app and SwiftPM fallbacks.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The repair must preserve direct helper, standalone tarball, and SwiftPM-development resource lookup while changing only the packaged symlink path.

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

Label changes

Label changes:

• add P1: The documented CLI install path can make multiple bundled provider commands fail for installed users.
• add impact:other: The report blocks provider-plugin execution in the supported CLI workflow without fitting the more specific owned impact classes.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.
• add clawsweeper:queueable-fix: Current issue advisory state selects this label.
• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.

Label justifications:

• P1: The documented CLI install path can make multiple bundled provider commands fail for installed users.
• impact:other: The report blocks provider-plugin execution in the supported CLI workflow without fitting the more specific owned impact classes.

Evidence reviewed

Acceptance criteria:

• swift test --filter CodexBarCoreResourcesTests
• Add or extend a direct-versus-symlink packaged-helper resource regression.
• make test
• make check

What I checked:

• Documented affected installation path: The CLI documentation explicitly installs CodexBarCLI through /usr/local/bin/codexbar and /opt/homebrew/bin/codexbar symlinks, so this is supported behavior rather than an external packaging customization. (docs/cli.md:15, a90dfed5c264)
• Current resolver omits symlink resolution: Outside an app bundle, the resolver probes mainBundle.bundleURL or an injected directory directly; it does not derive and resolve the physical executable URL before looking beside it. (Sources/CodexBarCore/CodexBarCoreResources.swift:43, a90dfed5c264)
• Existing coverage misses the reported path: The resolver test supplies a real adjacent directory directly, but does not invoke a symlinked helper or assert canonicalization from an executable path. (Tests/CodexBarTests/CodexBarCoreResourcesTests.swift:36, a90dfed5c264)
• Established CLI precedent: CLI version lookup resolves its executable path through resolvingSymlinksInPath() before probing adjacent metadata, showing the repository already treats symlink invocation as a supported runtime case. (Sources/CodexBarCLI/CLIIO.swift:95, a90dfed5c264)
• Prior resource-bundle fix provenance: Commit 0954a74 added the safe resolver, bundled helper copy, and resource smoke coverage; its helper-copy logic retains the executable-adjacent contract but does not cover invocation through a symlink. (Scripts/package_app.sh:571, 0954a74a0b9d)
• Release check: The earlier resource resolver commit is contained by v0.49.0 and v0.49.1; current main retains the same unresolved executable-directory lookup, so no released/current-main fix for this symlink-specific case was found. (Sources/CodexBarCore/CodexBarCoreResources.swift:43, 0954a74a0b9d)

Likely related people:

• steipete: Introduced the current resource resolver, helper bundle packaging, and packaged resource smoke path in the prior resource-bundle fix. (role: resource-resolution feature introducer and recent area contributor; confidence: high; commits: 0954a74a0b9d, 330ae4384b18; files: Sources/CodexBarCore/CodexBarCoreResources.swift, Scripts/package_app.sh, Scripts/verify_packaged_app_launch.sh)
• Robert: Recent CLI version-path work canonicalizes executable symlinks, which is directly adjacent to the needed lookup behavior. (role: recent adjacent CLI-path contributor; confidence: medium; commits: 84f7cfe7de68; files: Sources/CodexBarCLI/CLIIO.swift, Tests/CodexBarTests/CLIEntryTests.swift)

How this review workflow works

• 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.