feat(cli/dir): dirctl install list, agents, outdated, and pin/unpin

[akijakya]

The read side of package management: see what is installed, and see what is stale.

Builds on #2134, now merged, which made the manifest the single source of truth.

install list and install agents

dirctl install list lists installed packages from the manifest — name, agent, kind, scope, version, flags — with -o json.

dirctl install list <name> mirrors brew list <formula>: that package's skill files and MCP server keys. It answers "what did this actually put on my machine?", otherwise unanswerable without reading every agent config by hand.

Both stat what they report, since the manifest is the only provenance an installed artifact has and a user can delete one behind our back. Anything a row names but disk does not have is marked missing.

dirctl install agents is the old install list under its new name — detected agents and the files install would touch.

install outdated

Compares each row against the Directory it was installed from.

Only rows needing attention are listed, with --all for the full table. Two groups qualify: upgradable, and rows that could not be assessed at all. The second is there because a silently omitted missing or not found row reads as "fine".

Status	Meaning
upgradable	A higher version exists, or the same version now resolves to different content (content changed)
up to date	Nothing newer. Also covers an upstream that is behind — a downgrade is never offered
pinned	Held. The newer version is still shown
missing	The recorded artifacts are gone, so nothing can be upgraded
not found	No record under that name
non-semver	The versions carry no ordering, so no claim is made
skipped	Installed from a different client context

--exit-code gates CI. It is computed on the unfiltered set, so --all cannot change it, and on upgradable alone, since no upgrade would fix a missing row. Also --pre and --include-pinned.

Its first four columns match install list, so the two tables read as views of one manifest.

install pin / unpin

Hold a package at its installed version, and release the hold, across every agent it is installed into.

They exist as verbs because install-time pinning alone cannot hold a version you already have: you upgraded, something broke, you want to sit still.

How the comparison works

cli/internal/pkgupdate is a pure unit. The resolver, the stat, the binary's own version, the active context and the row filters are all injected, so every status above is reachable in a unit test with no server and no filesystem.

It resolves once per distinct name, not once per row, through namingv1.Resolve(name, ""), which returns every {name, version, cid} without pulling record bodies. A package in three agents costs one call.

A resolver failure is a per-row status, so one unreachable name cannot hide the verdict on the others. builtin rows compare against skill.RecordVersion() and issue no RPC.

The manifest gains a context field, recorded on every install. A row pulled from a colleague's Directory says nothing about the one configured now, so it is skipped rather than compared. An empty name on either side means "no claim" and matches anything, so older rows and unnamed contexts stay checkable.

Everything here except outdated runs without a client.

Breaking change

dirctl install list shipped in v1.6.2 showing detected agents. It now lists installed packages, and that view is dirctl install agents. Docs and skill references are updated here, and the release notes carry a BREAKING entry.

Out of scope

install upgrade, manifest rows for dirctl init's built-in install, and bare-name resolution by highest version are #2030.

Closes #2029.

Validation

• cd cli && go test ./... and task lint:go (pinned golangci-lint 2.13.2): pass, 0 issues. ./cmd/install/... ./internal/... also pass at -count=2, which catches the in-process opts singleton trap.
• Two failures elsewhere in task test — server/store/oci integration and cli/cmd/auth at -count=2 — reproduce on unmodified main.
• Every pkgupdate status has a unit test with an injected resolver and stat, including the once-per-name call count, the built-in path issuing no RPC, and the lexical trap that ranks 1.10.0 below 1.9.0.
• Manual, against a local daemon with two versions of one record pushed: list, list <name>, -o json, agents, outdated --all, pin/unpin and uninstall all behave as described.

[codecov]

Codecov Report

❌ Patch coverage is 83.45679% with 67 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cli/cmd/install/outdated.go	68.5%	34 Missing ⚠️
cli/cmd/install/output.go	55.0%	9 Missing ⚠️
cli/cmd/install/list.go	92.7%	6 Missing ⚠️
cli/internal/pkgupdate/pkgupdate.go	94.8%	5 Missing ⚠️
cli/cmd/install/install.go	70.0%	3 Missing ⚠️
cli/cmd/install/multi.go	0.0%	3 Missing ⚠️
cli/cmd/install/pin.go	90.9%	3 Missing ⚠️
cli/cmd/install/uninstall_recorded.go	93.1%	2 Missing ⚠️
cli/cmd/install/agents.go	92.3%	1 Missing ⚠️
cli/cmd/install/context.go	66.7%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

🟡 Changes recommended

No-op installs fail to reconcile the manifest, and recorded uninstall has selection, digest, and failure-handling correctness issues.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds manifest-driven package inspection, update checks, pinning, and offline global uninstall behavior to dirctl.

Changes:

• Adds install agents, list, outdated, pin, and unpin.
• Introduces package update comparison and artifact inspection.
• Makes global uninstall manifest-driven and simplifies no-op reporting.

File summaries

File	Description
docs/content/dir/dir-features-scenarios.md	Updates install command guidance.
docs/content/dir/dir-cli-reference.md	Documents package-management commands.
cli/util/reference/reference.go	Simplifies resolver errors.
cli/internal/pkgupdate/pkgupdate.go	Adds update comparison engine.
cli/internal/pkgupdate/pkgupdate_test.go	Tests update statuses.
cli/internal/pkgstate/pkgstate.go	Adds context and artifact-kind metadata.
cli/internal/pkgstate/pkgstate_test.go	Tests new manifest fields.
cli/internal/agentinstall/remove.go	Adds manifest-driven removal.
cli/internal/agentinstall/remove_test.go	Tests recorded removal.
cli/internal/agentinstall/installed.go	Inspects recorded artifacts.
cli/internal/agentinstall/installed_test.go	Tests artifact inspection.
cli/internal/agentcfg/summary.go	Omits unchanged summary lines.
cli/internal/agentcfg/summary_test.go	Tests summary filtering.
cli/internal/agentcfg/selection.go	Adds agent lookup by ID.
cli/internal/agentcfg/result.go	Adds change detection helpers.
cli/internal/agentcfg/plan.go	Omits unchanged plan lines.
cli/internal/agentcfg/plan_test.go	Tests plan filtering.
cli/cmd/root.go	Configures offline commands.
cli/cmd/install/uninstall.go	Routes global uninstall through manifest.
cli/cmd/install/uninstall_recorded.go	Implements recorded uninstall flow.
cli/cmd/install/uninstall_recorded_test.go	Tests recorded uninstall behavior.
cli/cmd/install/pin.go	Implements pin and unpin.
cli/cmd/install/pin_test.go	Tests pin state changes.
cli/cmd/install/output.go	Adds table and JSON output helpers.
cli/cmd/install/outdated.go	Implements outdated reporting.
cli/cmd/install/outdated_test.go	Tests outdated output.
cli/cmd/install/manifest.go	Records context and adds manifest helpers.
cli/cmd/install/list.go	Implements installed-package listing.
cli/cmd/install/list_test.go	Tests list output.
cli/cmd/install/install.go	Registers commands and skips no-op prompts.
cli/cmd/install/install_test.go	Tests command registration.
cli/cmd/install/context.go	Resolves active context names.
cli/cmd/install/batch.go	Skips no-op batch confirmation.
cli/cmd/install/agents.go	Preserves the former agent listing.
CHANGELOG.md	Records features and breaking changes.
.skill/SKILL.md	Updates connectivity guidance.
.skill/references/install.md	Updates install workflows.

Review details

Suppressed comments (1)

cli/cmd/install/outdated.go:253

• Raw string inequality does not mean the upstream is older. Equivalent versions such as installed v1.0.0 and upstream 1.0.0 compare equal in pkgupdate, but this renders the latter in parentheses as a downgrade. Use the semantic version comparison here and parenthesize only when the latest version is strictly lower.

	if row.Status == pkgupdate.StatusUpToDate && row.Latest != row.Entry.Version {
		return "(" + row.Latest + ")"

• Files reviewed: 37/37 changed files
• Comments generated: 9
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Context provenance and edge-case status reporting can produce incorrect outdated results.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 21/21 changed files
• Comments generated: 4
• Review effort level: Balanced

[ramizpolic]

LGTM, great work!

i would suggest to consider pulling these common methods into a dedicated package (at least the list locally installed operation). we could potentially leverage it inside the Runtime component