Record project-scope skill installs in the lock file

[samuv]

Summary

• Why: RFC THV-0080 requires every project-scoped skill install to be pinned in toolhive.lock.yaml — including transitively materialized toolhive.requires dependencies — with lock-write failure hard-failing the install (never a silently-unpinned skill). This is the largest PR in the stack; flagging it up front for extra review time.
• What:
  • Install hooks into the single existing choke point all install paths already funnel through (installAndRegister): compute contentDigest, upsert the lock entry, roll back the DB record (matching the existing group-registration rollback pattern) if the lock write fails.
  • toolhive.requires dependencies materialize recursively — a Visited set guards cycles, skills.MaxDependencies bounds the whole tree (not just one skill's declared list) — with RequiredBy merged (not overwritten) when a dependency is shared by multiple parents.
  • Uninstall cascades to orphaned, non-explicit dependencies via Lockfile.RemoveParentFromRequiredBy, itself cycle-safe.
  • The whole feature stays inert on main behind TOOLHIVE_SKILLS_LOCK_ENABLED until the full RFC v1 (this stack + the later Sigstore stack) lands — following the existing TOOLHIVE_DEV precedent (pkg/skills/gitresolver/reference.go) for staged rollouts. Every PR in the stack stays independently mergeable without exposing partial behavior to users.

Part of the production stack for #5715 (RFC THV-0080). Stack: 3/6 — lockfile → lock-service → install-hooks → sync → upgrade → cli-exitcodes. Based on #5893 (PR2).

Type of change

• New feature

Test plan

• Unit tests (task test)
• E2E tests (task test-e2e, scoped: ginkgo --label-filter=skills-lock)
• Linting (task lint-fix)

Unit coverage (86.3% for pkg/skills/skillsvc) targets the risk areas directly: contentDigest/source recorded correctly on install, dependency materialization, a dependency shared by two parents merging RequiredBy, a requires cycle terminating, the MaxDependencies tree-wide cap, lock-write failure rolling back the DB record, cascade uninstall (orphaned dependency removed, explicit dependency never cascaded, shared dependency survives one parent's removal, cascade cycle terminating). Two new E2E specs exercise the real HTTP API + thv serve subprocess + a real OCI push/install round-trip, confirming the lock file is written/removed correctly outside the unit-test harness.

Does this introduce a user-facing change?

Not yet — gated behind TOOLHIVE_SKILLS_LOCK_ENABLED, off by default. Once the full stack lands: project-scope thv skill install will write/update toolhive.lock.yaml and materialize toolhive.requires dependencies; thv skill uninstall will cascade-remove orphaned dependencies.

Special notes for reviewers

• toolhive.requires is read back from the extracted SKILL.md on disk (not from the OCI/git resolver's own parse) — this works uniformly across OCI and git sources without needing to plumb requires through every install path's return type.
• test/e2e/api_helpers.go's ServerConfig gains an ExtraEnv []string field (empty/no-op for every existing E2E test) so this PR's tests can opt into the feature flag on their own thv serve subprocess without turning it on for the whole E2E suite.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 81.93833% with 41 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.88%. Comparing base (97a9dfa) to head (187a35d).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/skills/skillsvc/content_digest.go	46.66%	8 Missing and 8 partials ⚠️
pkg/skills/skillsvc/uninstall.go	76.19%	9 Missing and 6 partials ⚠️
pkg/skills/skillsvc/lock.go	86.84%	5 Missing and 5 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5894      +/-   ##
==========================================
+ Coverage   71.84%   71.88%   +0.03%     
==========================================
  Files         708      711       +3     
  Lines       72811    73022     +211     
==========================================
+ Hits        52311    52489     +178     
- Misses      16765    16784      +19     
- Partials     3735     3749      +14     

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

[samuv]

Tracked in #5899 (RFC THV-0080 stack).

[JAORMX]

Panel review (spec / standards / security / library-reuse / duplication / golang-conventions / UX). Phase-2 mechanics are all correct — hard-fail on lock write, transitive requiredBy, dirhash contentDigest, source never rewritten, managed set. But there are two real correctness findings plus some standards/UX items. Commenting rather than approving.

Correctness (worth addressing before merge):

1. Dependency-cycle deadlock via the OCI path — pkg/skills/skillsvc/lock.go (materializeDependencies) re-enters s.Install, but the Visited cycle check only runs inside recordLockState, after the artifact install. The git path works because installFromGit locks on the resolved skill name; a requires reference that dispatches through installByName/installFromOCI locks on opts.Name before resolution (install.go:100). A cycle A → oci:.../A re-locks a key the outer install already holds and deadlocks, with the Visited set never consulted. Suggest a pre-install cycle check keyed on the requested reference, or locking only on resolved names everywhere.

2. Store/lock write ordering inverts the durable-first rule — recordLockState (lock.go) writes the lock entry before the store Update that marks the skill Managed. If the Update fails, rollback deletes the lock entry but the store record survives unmanaged with files still on disk — a state Uninstall won't cascade (it only cascades when existing.Managed). Mark Managed in the store first, or extend rollback to clear files/record on this failure.

Standards (mechanical): three go-style.md immutable-variable violations — the if x == "" { x = fallback } reassignment at lock.go:42, lock.go:91, uninstall.go:60. (library-reuse notes cmp.Or collapses the first to one line.)

UX: lock-write failures surface as generic HTTP 500s (install.go:267, uninstall.go:61) with no cause or recovery hint — a dead-end for the operator. Worth an actionable message. Also Managed isn't visible in skill list/skill info, so an operator can't tell why one uninstall touches the lock and another doesn't.

Security: verified clean on the main path (os.Root containment, atomic temp+rename, digest hardening, CWE-22). One Low TOCTOU: prevEntry snapshot is read outside the file lock (install.go:246) and could reinstate a stale entry on rollback under concurrent same-skill installs — take the snapshot inside Update's callback.

Deferred (confirm, not defects): Sigstore provenance recording and --allow-unsigned are Phase 5, correctly absent — acknowledged in feature_gate.go.