Overhaul plugin update + Homebrew install path for Cowork / Claude Desktop

[Data-Wise]

Summary

craft has no working story for updating or installing a Claude Code plugin on Cowork / Claude Desktop, and no Homebrew-based install path for that surface. The release skill currently punts it as a manual, unverifiable step. A real-world release this week (savant v1.7.0 → v1.7.1) exposed every failure mode end-to-end. This issue proposes overhauling both: (1) the Cowork/Desktop plugin-update flow, and (2) a Homebrew "post-install" path for plugins on Cowork/Desktop.

Motivation — what actually happened (savant v1.7.x)

savant is a private plugin consumed by two surfaces: Claude Code CLI (savant@local-plugins) and Cowork/Claude Desktop (savant@savant-private, a private self-marketplace). The CLI surface self-heals and updated cleanly to 1.7.1. The Cowork surface could not be brought current despite multiple attempts:

1. The marketplace clone goes stale and never pulls. Desktop's local clone at …/local-agent-mode-sessions/<s>/<s>/cowork_plugins/marketplaces/<mp>/ was frozen 299 commits behind origin/main. A plain git fetch from it succeeds, so the source is reachable — Desktop's "refresh marketplace" simply isn't advancing it.
2. Plugin "update" silently no-ops. Because the clone still advertised the old manifest, the in-app Update found "nothing newer" and wrote nothing. Registry installed_plugins.json pin stayed at the old version with an unchanged lastUpdated; no new cache/<mp>/<plugin>/<version>/ dir was ever created.
3. "Updated" in the UI ≠ installed. After the marketplace clone was refreshed, Desktop's plugins UI showed the new version as available, which reads as "updated" — but the installed cache + registry were still the old version. The two are easy to confuse and there is no surfaced distinction.
4. No compliant shell completion. Governance (R04 "update via plugin update, never re-copy"; R05 "cache/** is read-only") correctly forbids hand-writing the cache dir + editing the registry JSON, so there is no safe manual workaround — the only compliant path is Desktop's own update, which is the thing that's broken.
5. Not auto-verifiable. skills-audit.py reads the registry/cache and reports drift, but craft offers nothing to act on it for this surface, and the release skill's verify-surfaces step (below) treats it as a non-blocking WARN.

Net: a released, tagged, CI-green plugin could not reach one of its two consumer surfaces, and craft had no command, no verification, and no recovery path for it.

Current state in craft (what exists, and why it doesn't cover this)

Surface	File	Covers
Release consumer-refresh	skills/release/SKILL.md Step 5	One-line "re-pull the marketplace in the Desktop UI, then restart" — no automation, no verify
Verify surfaces	skills/release/SKILL.md Step 13.6	Desktop/Cowork = WARN (one-time, not auto-verifiable) — explicitly punted
Homebrew	commands/dist/homebrew.md, skills/distribution/homebrew-*	Formula (CLI tools) + Cask (Tauri native desktop apps) — not plugin distribution to Cowork/Desktop
Marketplace	skills/distribution/dist-extras/ (replaces deprecated commands/dist/marketplace.md)	Claude Code plugin marketplace listings only — no Cowork/Desktop
Desktop tracking	commands/code/desktop-watch.md → release-watch.py	Monitors Desktop release notes — not install/update

There is no surface that (a) updates a plugin in Cowork/Claude Desktop, (b) verifies the install actually landed in cache+registry, or (c) installs/updates a plugin there via Homebrew.

Proposed overhaul

Part 1 — Cowork / Desktop plugin-update flow (make it real, make it verifiable)

• Detect the storage layout across Desktop versions (the local-agent-mode-sessions/*/*/cowork_plugins/ path is version-specific and undocumented; the audit's glob already drifted once). Resolve the active registry + cache + marketplace-clone paths dynamically.
• Diagnose the marketplace clone: report clone HEAD vs origin/main, commits-behind, fetch reachability, and whether the advertised manifest version matches canon.
• Refresh the marketplace source compliantly (the read-side git pull of the clone is not a cache write — R04/R05-clean) so the in-app update has something newer to install, OR document the exact Desktop UI sequence that forces it.
• Verify the install landed: assert a new cache/<mp>/<plugin>/<version>/ dir exists AND the registry pin + lastUpdated advanced — not just that the UI lists it as available. Distinguish available vs installed explicitly.
• Recovery path when update no-ops: documented quit-and-relaunch (full Cmd-Q, not in-app restart) and uninstall→reinstall, with a verification re-check after each.
• Wire into the release skill: upgrade Step 13.6 for Desktop/Cowork from WARN to an actual verify + remediate step (still non-blocking on the release, but actionable and honest about installed-vs-available).

Part 2 — Homebrew "post-install" path for plugins on Cowork/Desktop

• A Homebrew-driven install/update mechanism for a Claude Code plugin consumed by Cowork/Desktop (distinct from the existing Tauri cask for native apps and formula for CLIs).
• Likely a small formula/cask whose install step performs the compliant marketplace add + plugin install/update (or refreshes the marketplace clone) so brew upgrade keeps the Desktop surface current without the broken in-app path.
• Reuse the existing homebrew-* skills + tap-update machinery from the release pipeline; add a plugin-distribution mode.

Acceptance criteria

• A craft command (e.g. /craft:dist:cowork or an extension of dist:homebrew/dist-extras) updates a plugin on Cowork/Claude Desktop and verifies the install landed (cache dir + registry pin advanced), not just availability.
• Dynamic resolution of the Desktop plugin-storage paths (survives the next Desktop layout change).
• Compliant with R04/R05 (no hand-writing the cache; marketplace-source refresh only).
• A Homebrew install/update path for the plugin on Cowork/Desktop, integrated with the tap machinery.
• Release skill Step 13.6 upgraded from "WARN, not auto-verifiable" to a verify+remediate step for Desktop/Cowork.
• Documented recovery (quit-relaunch / reinstall) when the in-app update no-ops.

Evidence / references

• Failure trace: savant v1.7.0→v1.7.1 Cowork refresh (marketplace clone 299 commits behind; registry untouched; no 1.7.1 cache dir; UI "available" ≠ installed).
• Audit tool that detects (but can't fix) the drift: ~/.claude/scripts/skills-audit.py.
• craft files: skills/release/SKILL.md (Steps 5, 13.6, 10b), commands/dist/homebrew.md, skills/distribution/dist-extras/, commands/code/desktop-watch.md.

🤖 Generated with Claude Code

[Data-Wise]

Resolved in v2.50.0 — Homebrew Cowork/Desktop verification (Step 10d: blocking aggregator-sync + @local-plugins verify). https://github.com/Data-Wise/craft/releases/tag/v2.50.0

[Data-Wise]

Reopening — the "Resolved in v2.50.0" closure was incorrect

Live repro today: savant's Cowork/Desktop install (savant@savant-private) is pinned at
v1.8.0 vs canon v2.11.0 — 10 releases behind. This is the exact failure mode this
issue was originally filed for (in-app plugin update silently no-ops), still reproducing.

Why the closing comment doesn't hold up

The comment cited v2.50.0's "Homebrew Cowork/Desktop verification (Step 10d: blocking
aggregator-sync + @local-plugins verify)" as the fix. Checked both scripts that shipped in
that release:

grep -n "Cowork\|cowork\|savant-private\|@local-plugins" scripts/post_install_check.py scripts/verify_caveats.py

Zero hits in either file. They gate Homebrew distribution (verify_caveats.py,
post_install_check.py) and the aggregator-sync.yml CI action (a PR-merge check against
Data-Wise/claude-plugins) — an unrelated surface that happens to share the @local-plugins
suffix with the CLI registry, not the Cowork/Desktop install path this issue is about.

Confirmed the release skill itself is unchanged for this surface — skills/release/SKILL.md
still carries the exact pre-issue stub:

| Cowork | WARN | Cowork report + remind (manual store) |

Same wording, same non-blocking WARN, same "manual store" punt that was true when this issue
was filed.

Root cause (re-confirmed, not just re-asserted)

There's still no discoverable CLI/API surface for Cowork/Desktop's plugin installer.
fix-local-plugins.sh's existing Cowork block already does the maximum R04/R05-compliant
action (rewrite the registry pin directly) when the canon cache dir exists — and still can't
act in this case, because Desktop's own marketplace-clone refresh (upstream of that check) is
the thing that's broken. This matches the original issue's Part 1 diagnosis exactly; nothing
found since changes that assessment.

Proposed permanent fix, given true automation isn't buildable from outside the app

1. Quantify the WARN. Report how many releases behind the Cowork pin is (here: 10),
   not just "drift exists." A flat WARN is easy to let ride silently for months; a number
   forces attention.
2. Ship a single local recovery script. fix-local-plugins.sh already computes everything
   needed to diagnose this. Package the diagnosis + the two unavoidable manual Desktop-UI steps
   (uninstall → reinstall → full Cmd-Q relaunch) into one guided script, so recovery is
   "run this" instead of re-deriving the steps from scratch each time.
3. Correct the surface-matrix language in skills/release/SKILL.md so a future release
   doesn't get closed against the wrong verification again — the aggregator/@local-plugins
   gate and the actual Cowork/Desktop install gate need visibly distinct names, not a shared
   "Cowork" label pointing at unrelated code.

Evidence trail: savant v2.11.0 release (tag, main HEAD e7f2d2c) vs. Cowork registry pin
v1.8.0; docs/CHANGELOG.md v2.50.0 entry; skills/release/SKILL.md lines ~265, ~282;
scripts/post_install_check.py, scripts/verify_caveats.py (grepped, zero Cowork references).

🤖 Generated with Claude Code

[Data-Wise]

Audit finding: still valid. skills/release/SKILL.md Step 13.6 (lines 253-283) treats Cowork as WARN/manual-remind and Desktop as INFO-only — no verify-installed-vs-available logic, no dynamic path resolution, no Homebrew plugin-install path exists yet. Matches the issue's own current-state table. This is a genuine large feature, not attempting inline — leaving open for scoped planning.

[Data-Wise]

Audit finding (2026-07-26): still valid, correctly scoped — no action taken.

PR #280 (3ced7f751) already shipped the tactical drift-visibility fix (quantified "N releases behind," cowork-recover.sh, disambiguated the aggregator/@local-plugins gate from the actual Cowork/Desktop gate). Confirmed against current dev: skills/release/SKILL.md still lists Cowork/Desktop as WARN/INFO tiers with no installed-vs-available verification or dynamic path resolution, and no Homebrew plugin-install path for Cowork/Desktop exists. The structural asks remain genuinely unbuilt and warrant a dedicated /craft:plan pass. Leaving open as-is, matching the prior 2026-07-24 audit's conclusion.

[Data-Wise]

Grounded (2026-07-26): still valid, unchanged, no craft-side work has landed against it.

Verified against current dev:

• skills/release/SKILL.md Step 13.6 "Surface Registry Phase" still treats Cowork as WARN ("Cowork report + remind... manual claude plugin marketplace add; non-blocking") and Desktop as INFO ("DXT store; report only") — exactly the punted, non-actionable posture this issue describes. Nothing has upgraded these to a real update/verify/remediate flow.
• No command or script exists that detects the Cowork/Desktop storage layout, diagnoses marketplace-clone staleness, or verifies cache+registry actually advanced post-update — confirmed by absence (no desktop-install-verify-type script, no references in scripts/ or commands/dist/).
• commands/dist/homebrew.md confirms the existing Homebrew surface is Cask (Tauri native apps) or Formula (CLI/plugin source) — neither is a Cowork/Desktop plugin-install path, so the gap the issue identifies is real, not superseded by existing tooling.
• One inaccuracy in the original write-up: it cites commands/code/desktop-watch.md — no such file exists; the actual release-notes watcher is commands/code/release-watch.md / scripts/release-watch.py. Doesn't change the issue's substance (that watcher tracks Desktop release notes, not install/update state, same as originally claimed).

Keeping open, unmodified in scope. This is the one issue from the 2026-07-26 triage batch judged worth prioritizing — the other two open at the time (#213, #170-adjacent... correction: #213 and #133) are being closed as lower-value/non-actionable in a separate pass.