feat(deps): install skill dependencies just-in-time (#621)

[luongnv89]

Closes #621

Summary

ASM now lets a calling agent discover optional skill dependencies, acquire only the ones a run actually reaches, use a returned path immediately, and release that session afterward. Parent installation no longer installs optional dependents, and cleanup preserves anything that was already present.

Approach

Option 2 — Caller-owned temporary acquisition leases: add asm deps discover|acquire|release|cleanup around persistent session leases. The main agent owns try/finally control flow. ASM records ownership, returns a directly usable skillMdPath, and recovers only explicitly stale sessions later.

Decision Record

• Root cause: ASM had install, get, and library-activation primitives, but no caller-owned temporary lifecycle for optional skill dependencies. Permanent install treated skills as durable, while asm get cleaned clones at request end rather than at the enclosing task boundary.
• Options considered: Option 1 — Reference-only point-of-use delivery; Option 2 — Caller-owned temporary acquisition leases; Option 3 — Dependency transaction and graph protocol
• Options rejected: Option 1 — Retrieval without a durable temporary installation that remains until caller-controlled cleanup; Option 3 — Recursive graph transactions and renewal belong to Resolve shared skill dependencies during install #247/Explore skill-graph concept as evolution of bundles (atoms / molecules / compounds) #239 and exceed this issue
• Selected option: Option 2 — Caller-owned temporary acquisition leases
• Residual risk: Hard-interruption cleanup is eventual and cutoff-based; a still-active caller session must not be classified stale. ASM does not promise that a foreign provider will rescan its catalog mid-session.
• Design-confirm: confirmed Option 2 at design-confirm checkpoint (complexity: XL)

Analyzed at: feat/621-install-skill-dependencies-just-in-time @ b8ce73d (2026-09-09)

Changes

File	Change
src/dependency-leases.ts	Persistent caller-owned leases, interprocess locking, ownership-safe cleanup
src/commands/deps.ts	discover, acquire, release, and cleanup commands
src/cli.ts	Route deps through existing CLI dispatch
src/utils/frontmatter.ts	Parse optional YAML dependency sequences
src/utils/types.ts	Dependency and lease contracts
src/scanner.ts	Expose declared dependencies without installing them
src/installer-core.ts	Keep optional dependencies out of eager parent install
src/commands/get.ts	Reuse resolution for discover/acquire
src/formatter.ts / src/formatter-core.ts	Format lease command output
src/config.ts	Sandboxed lease storage path
src/eval/providers/skill-best-practice/v1/index.ts	Allow and validate dependency metadata
README.md	Document the caller-owned JIT lifecycle and its limits
skills/skill-creator/**	Author optional dependencies for first-use acquisition
skills/skill-auto-improver/**	Align preflight with caller-owned leases

Test Results

• Unit tests: 2732 passed
• Integration tests: included in unit suite
• E2e tests: 179 passed
• Build: passed
• QA cycles: 5

Acceptance Criteria Verification

Criterion	Status	Evidence
A skill's optional dependent skills are not installed merely because the parent skill is installed	pass	src/installer.test.ts parent-install cases; src/commands/install-run.ts still installs only explicit skills
During a run, a dependent skill can be installed at the point it is first needed, and is usable immediately afterwards	pass	src/dependency-leases.test.ts acquire returns readable skillMdPath; src/cli.test.ts deps acquire
Dependent skills installed for a run are removed when the task finishes	pass	src/dependency-leases.test.ts release removes only lease-owned artifacts
A dependent skill that was already installed before the run is still installed after the cleanup	pass	lease records pre-existing targets and preserves them on release
Cleanup also happens when the task fails or is interrupted, so no run-installed skill is left behind	pass	idempotent release for caller finally; asm deps cleanup --stale-before recovers explicitly stale sessions. ASM does not detect arbitrary caller failure.