Add plugin key rotation workflows

[samuv]

Summary

• Plugin projects have the same key-rotation and adoption gap as skills. This mirrors the lock-driven re-anchor contract so both user-facing surfaces apply the same trust rules.
• Add --public-key support to plugin upgrade and sync adoption, require --allow-signer-change for replacement anchors, and retain the recorded key whenever it still verifies.
• Share project transaction locking between skills and plugins while preserving per-plugin locking for user-scoped operations.
• Update the CLI, API, SDK, architecture documentation, and regression coverage for plugin key rotation.

Fixes #6640

Type of change

• Bug fix
• New feature
• Refactoring (no behavior change)
• Dependency update
• Documentation
• Other (describe):

Test plan

• Unit tests (task test)
• E2E tests (task test-e2e)
• Linting (task lint-fix)
• Manual testing (describe below)

task gen, task docs, and task build pass. Changed-package unit tests pass. The full task test run reaches five unrelated pkg/api failures because no container runtime is available. The focused plugin key-trust E2E suite compiles and reaches setup, where it stops for the same missing runtime.

Changes

Area	Change
Plugin CLI and API	Accept and validate replacement public keys for upgrade and sync adoption.
Plugin service	Re-anchor only after successful verification and update trust state transactionally.
Project transactions	Move shared project locking into pkg/projecttxn for skills and plugins.
Generated reference	Regenerate CLI, OpenAPI, and Go SDK outputs.
Tests and architecture	Cover rotation, adoption, rollback, concurrency, and documented trust semantics.

Does this introduce a user-facing change?

Yes. thv ai-plugin upgrade --allow-signer-change --public-key <PUBLIC_KEY_PATH> can re-anchor a key-pinned OCI plugin, and thv ai-plugin sync --adopt --public-key <PUBLIC_KEY_PATH> can adopt an installed key-signed plugin.

Implementation plan

Approved implementation plan

1. Mirror the approved skill key-rotation contract for plugin upgrade and sync adoption.
2. Keep lock-first policy selection, try the recorded key first, and consider the replacement only after a conclusive mismatch.
3. Reuse strict OCI snapshots for explicit replacement-key re-anchors and preserve ordinary upgrade compatibility.
4. Extract project transaction locking for shared skill and plugin use while retaining user-scope plugin locks.
5. Add unit and E2E coverage, then regenerate CLI and API documentation.

Special notes for reviewers

This is the second PR in the stack and is based on #6662. The approved PR-size exception keeps plugin parity, shared transaction extraction, tests, and generated outputs in one reviewable change.

[codecov]

Codecov Report

❌ Patch coverage is 82.50000% with 84 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@97b81d8). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
pkg/plugins/pluginsvc/upgrade.go	74.73%	71 Missing ⚠️
pkg/projecttxn/transaction.go	82.85%	6 Missing ⚠️
pkg/plugins/pluginsvc/sync.go	94.11%	3 Missing ⚠️
pkg/plugins/pluginsvc/verify.go	92.00%	2 Missing ⚠️
pkg/plugins/pluginsvc/install_extraction.go	88.88%	1 Missing ⚠️
pkg/skills/lockfile/lockfile.go	87.50%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6663   +/-   ##
=======================================
  Coverage        ?   79.20%           
=======================================
  Files           ?      792           
  Lines           ?    79873           
  Branches        ?        0           
=======================================
  Hits            ?    63263           
  Misses          ?    16605           
  Partials        ?        5           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[JAORMX]

Reviewed the plugin-only stack against #6662: initially 32904c3 vs 560a05b, then verified the exact trees at f155300 vs d655077. The rebase changes only go.mod/go.sum relative to the initially reviewed plugin head; all implementation blobs are identical.

Spec: the plugin flow follows #6640's old-key-first, lock-first, explicit replacement and offline-adoption contract. No separate spec mismatch found.
Standards: the new projecttxn package exposes implementation-oriented Lock/LockPath helpers; reducing that API or documenting its canonical-root precondition would be worthwhile, but current production callers normalize roots, so this is nonblocking.
Domain: one newly added metadata-refresh rollback path can leave SQLite metadata inconsistent with the lock after cancellation (inline). Shared project transaction locking and the bounded trust-only rollback otherwise follow the intended design.

I excluded inherited SDK issues and concerns outside the documented contract, including crash-atomic journaling and treating offline adoption as authentication of already-materialized filesystem bytes. The keyless fallback for an unrecorded legacy entry is also consistent with the per-entry policy, not a replacement-key bypass.

Nonblocking: document public_key's base64-encoded DER SPKI representation and allowed option combinations in the API fields so generated SDK/OpenAPI docs explain the wire contract.

Core #297 has now been re-reviewed and approved at e5c9df0. The local cancellation issue on skills #6662 still needs its separate fix. All 46 checks passed on the originally reviewed plugin head; the new head's CI was still running at the last check. No local tests or linters were run.

going with the approval from jakub