@iseoane/agent-depot 0.6.7 → 0.6.8

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.8] - 2026-11-04
+
+### Fixed
+
+- Versioned Claude Packages now follow the Host's literal plugin cache version,
+  with the plugin manifest taking precedence over marketplace metadata. A newer
+  Source commit at the same version is explained instead of offered as an update
+  Claude cannot apply. Successful literal-version changes are recognized even
+  when the commit is unchanged or the version strings normalize identically.
+- Package comparisons and results in the CLI and TUI now show the observed Host
+  version and commit together. Remembered evidence is labelled as recorded;
+  Pi updates between different commits at the same manifest version remain
+  available when verified Source ancestry proves progress.
+
 ## [0.6.7] - 2026-11-04
 
 ### Fixed

package/dist/src/package-bundles.js

@@ -56,8 +56,8 @@ export function parseClaudePluginManifest(raw, root) {
 /**
  * Reads one marketplace and returns a descriptor per `plugins` entry. The
  * `readPluginManifest` resolver supplies the raw plugin.json for an in-repo
- * entry, because the entry version overrides the plugin manifest version and
- * the plugin manifest owns the component inventory (agents, hooks, and so on).
+ * entry. The plugin manifest owns the component inventory and, when declared,
+ * its version takes precedence over marketplace entry metadata, as in Claude.
  * A `command` source and any source outside the repository yield a descriptor
  * with a warning rather than a throw.
  */
@@ -330,7 +330,7 @@ function buildMarketplaceDescriptor(entry, label, marketplaceRoot, metadataPlugi
         warnings.push(`marketplace entry name ${JSON.stringify(entryName)} differs from plugin manifest name ${JSON.stringify(plugin.name)}`);
     }
     const entryVersion = manifestVersionEvidence(entry.version, "marketplace-entry");
-    const version = entryVersion ?? plugin.version;
+    const version = plugin.version ?? entryVersion;
     return Object.freeze({
         host: "claude",
         coordinates: Object.freeze({ host: "claude", marketplaceRoot, pluginName: entryName }),

package/dist/src/package-cli.js

@@ -92,7 +92,9 @@ export function packageSelectionMatches(selection, value) {
 export function describePackageUpdateCheck(check) {
     const available = check.available === undefined ? "unknown" : describeVersion(check.available);
     const reason = check.reason === undefined ? "" : `; ${check.reason}`;
-    return `Package ${formatPackageSelection(check.installed.selection)}: ${check.status}; available ${available}${reason}`;
+    const installed = check.observed === undefined ? "unknown (host evidence unavailable)" : describeEvidence(check.observed);
+    const commit = check.available?.kind === "manifest-version" && check.availableCommit !== undefined ? `; commit ${check.availableCommit}` : "";
+    return `Package ${formatPackageSelection(check.installed.selection)}: ${check.status}; available ${available}${commit}${reason}; host ${installed}`;
 }
 export function describePackageResult(result) {
     switch (result.status) {
@@ -318,7 +320,9 @@ function formatPackageRecord(record) {
 function describeInspection(selection, inspection, output) {
     output(`Package inspect: ${formatPackageSelection(selection)}`);
     output(`  installed: ${describeEvidence(inspection.installed)}`);
-    output(`  available: ${inspection.available === undefined ? "unknown" : describeVersion(inspection.available)}`);
+    output(`  available: ${inspection.available === undefined ? "unknown" : describeVersion(inspection.available)}${inspection.availableCommit === undefined || inspection.available?.kind === "git-commit" ? "" : `; commit ${inspection.availableCommit}`}`);
+    if (inspection.updateReason !== undefined)
+        output(`  update: ${inspection.updateReason}`);
     output(`  approval: ${inspection.approval}`);
     if (inspection.drift !== undefined) {
         output(`  drift: ${inspection.drift}`);
@@ -389,7 +393,7 @@ function describeEvidence(evidence) {
         case "installed": {
             if (evidence.version !== undefined) {
                 const qualifier = evidence.reason === undefined ? "" : " (HEAD; local changes)";
-                return `installed ${evidence.version}${qualifier}`;
+                return `installed ${evidence.version}${evidence.commit === undefined ? "" : ` (commit ${evidence.commit})`}${qualifier}`;
             }
             if (evidence.commit !== undefined) {
                 return `installed commit ${evidence.commit}`;

package/dist/src/package-flow.js

@@ -4,7 +4,7 @@ import { sameAppVersion } from "./app-version.js";
 import { createPortableExecutableResolver } from "./executable-resolution.js";
 import { claudeMarketplaceName, discoverBundlesInSnapshot } from "./package-bundles.js";
 import { sourceBundleScope } from "./package-content.js";
-import { affectedBy, classifyUpdate, hostInstallId, packageApprovalDigest, planHostSteps, PackagePlanError, } from "./package-host-plans.js";
+import { affectedBy, classifyUpdate, claudeVersionUpdateNotice, hostInstallId, packageApprovalDigest, planHostSteps, PackagePlanError, } from "./package-host-plans.js";
 import { findInstalledBundle, readHostInstallView } from "./package-host-state.js";
 import { activeBundles as classifyActiveBundles, portableSkillConflicts, } from "./package-owned-skills.js";
 import { bundleRoot, describeCoordinates, selectionKey, } from "./package-model.js";
@@ -174,7 +174,9 @@ export function createPackageOperations(environment = {}) {
         const installedCommitIsAncestor = bundle?.resolvedCommit === undefined || installed.kind !== "installed" || installed.commit === undefined
             ? undefined
             : await contentAccess.isCommitAncestor?.(bundle.source, installed.commit, bundle.resolvedCommit).catch(() => undefined);
+        const updateReason = claudeVersionUpdateNotice(selection.host, installed, bundle?.available, bundle?.resolvedCommit);
         return Object.freeze({
+            ...(updateReason === undefined ? {} : { updateReason }),
             ...(bundle === undefined ? {} : { descriptor: bundle.descriptor }),
             installed,
             ...(bundle?.available === undefined ? {} : { available: bundle.available }),
@@ -187,13 +189,16 @@ export function createPackageOperations(environment = {}) {
     async function checkOne(record) {
         try {
             const inspection = await inspect(record.selection);
-            const status = classifyUpdate(inspection.installed, inspection.available, inspection.availableCommit, inspection.installedCommitIsAncestor);
+            const status = classifyUpdate(inspection.installed, inspection.available, inspection.availableCommit, inspection.installedCommitIsAncestor, record.selection.host);
             return Object.freeze({
                 installed: record,
+                observed: inspection.installed,
                 status,
                 ...(inspection.available === undefined ? {} : { available: inspection.available }),
                 ...(inspection.availableCommit === undefined ? {} : { availableCommit: inspection.availableCommit }),
-                ...(status === "unknown" ? { reason: inspection.drift ?? describeEvidence(inspection.installed) } : {}),
+                ...(status === "unknown"
+                    ? { reason: inspection.drift ?? describeEvidence(inspection.installed) }
+                    : inspection.updateReason === undefined ? {} : { reason: inspection.updateReason }),
             });
         }
         catch (error) {
@@ -234,7 +239,7 @@ export function createPackageOperations(environment = {}) {
                 if (contradiction !== undefined) {
                     return { status: "failed", reason: `${contradiction}; the selection record was left untouched` };
                 }
-                const change = installedEvidenceChange(context.previous, observed);
+                const change = installedEvidenceChange(context.previous, observed, context.selection.host, context.available);
                 if (change === "unknown") {
                     return {
                         status: "failed",
@@ -242,9 +247,10 @@ export function createPackageOperations(environment = {}) {
                     };
                 }
                 if (change === "unchanged") {
+                    const notice = claudeVersionUpdateNotice(context.selection.host, observed, context.available, context.origin.resolvedCommit);
                     return {
                         status: "failed",
-                        reason: `The observed version did not change (${describeEvidence(observed)}); the selection record was left untouched`,
+                        reason: `The observed version did not change (${describeEvidence(observed)}); the selection record was left untouched${notice === undefined ? "" : `. ${notice}`}`,
                     };
                 }
                 await writeSelection(context, observed);
@@ -524,15 +530,22 @@ function planDifference(plan, fresh) {
 /**
  * Three outcomes, not two. `unknown` means the two observations carry no
  * comparable evidence, and an update must not report that as a success. A host
- * that had nothing installed and now reports an install has changed.
+ * that had nothing installed and now reports an install has changed. Versioned
+ * Claude plugins use literal cache versions, just as update eligibility does.
  */
-function installedEvidenceChange(previous, observed) {
+function installedEvidenceChange(previous, observed, host, available) {
     if (observed.kind !== "installed" || previous === undefined || previous.kind === "unknown") {
         return "unknown";
     }
     if (previous.kind === "absent") {
         return "changed";
     }
+    if (host === "claude" && available?.kind === "manifest-version") {
+        if (previous.version === undefined || observed.version === undefined
+            || previous.reason !== undefined || observed.reason !== undefined)
+            return "unknown";
+        return previous.version === observed.version ? "unchanged" : "changed";
+    }
     const previousCommit = previous.commit === undefined ? undefined : gitCommitId(previous.commit);
     const observedCommit = observed.commit === undefined ? undefined : gitCommitId(observed.commit);
     if (previousCommit !== undefined && observedCommit !== undefined) {

package/dist/src/package-host-plans.js

@@ -124,13 +124,19 @@ export function packageApprovalDigest(declaration) {
 }
 /**
  * Compares installed evidence with available evidence. Manifest versions compare
- * through `sameAppVersion` and `compareAppVersions`; differing commits compare only
- * when cached Source history proves the installed commit is an ancestor.
+ * through `sameAppVersion` and `compareAppVersions` for Pi. Claude's explicit
+ * plugin version keys its cache: only a different version installs a new copy.
+ * Unversioned bundles compare commits only with proven Source ancestry.
  */
-export function classifyUpdate(installed, available, availableCommit, installedCommitIsAncestor) {
+export function classifyUpdate(installed, available, availableCommit, installedCommitIsAncestor, host = "pi") {
     if (installed.kind !== "installed" || installed.reason !== undefined || available === undefined) {
         return "unknown";
     }
+    if (host === "claude" && available.kind === "manifest-version") {
+        if (installed.version === undefined)
+            return "unknown";
+        return installed.version === available.version ? "current" : "update available";
+    }
     if (installed.commit !== undefined) {
         const sourceCommit = availableCommit ?? (available.kind === "git-commit" ? available.commit : undefined);
         if (sourceCommit === undefined)
@@ -151,6 +157,15 @@ export function classifyUpdate(installed, available, availableCommit, installedC
     }
     return "unknown";
 }
+/** A different Source commit is not a deliverable update to Claude's versioned cache. */
+export function claudeVersionUpdateNotice(host, installed, available, availableCommit) {
+    if (host !== "claude" || installed.kind !== "installed" || installed.reason !== undefined
+        || available?.kind !== "manifest-version" || installed.version !== available.version
+        || installed.commit === undefined || availableCommit === undefined
+        || normalizeCommit(installed.commit) === normalizeCommit(availableCommit))
+        return undefined;
+    return `The Source commit differs, but Claude caches plugin version ${available.version}; the publisher must change the declared plugin version to deliver those changes.`;
+}
 /** Validates one host argv with the shared portable-command rules. */
 export function assertValidHostArgv(argv, label) {
     try {

package/dist/src/tui/installations-rows.js

@@ -15,7 +15,7 @@ function PackageDetails({ row }) {
     const status = row.status.kind === "unknown" && row.status.reason === "local changes"
         ? "update not checked · local changes"
         : row.status.kind === "unknown" ? "cannot assess" : row.status.kind === "current" ? "up to date" : "update available";
-    return (_jsxs(Text, { children: [_jsx(Text, { color: theme.legend, children: "  " }), _jsxs(Text, { color: theme.value, children: [row.selection.host, "  "] }), version === undefined ? _jsx(Text, { color: theme.warning, children: row.installed }) : _jsxs(_Fragment, { children: [_jsx(Text, { color: theme.value, children: installedPrefix }), _jsx(Text, { color: theme.version, children: version }), _jsx(Text, { color: theme.value, children: installedSuffix })] }), _jsx(Text, { color: theme.value, children: "  available " }), _jsx(Text, { color: row.available === "unknown" ? theme.warning : theme.version, children: row.available }), _jsxs(Text, { color: theme.warning, children: ["  ", status] }), row.drift === undefined ? null : _jsxs(Text, { color: theme.warning, children: ["  drift: ", row.drift] })] }));
+    return (_jsxs(Text, { children: [_jsx(Text, { color: theme.legend, children: "  " }), _jsxs(Text, { color: theme.value, children: [row.selection.host, "  "] }), version === undefined ? _jsx(Text, { color: theme.warning, children: row.installed }) : _jsxs(_Fragment, { children: [_jsx(Text, { color: theme.value, children: installedPrefix }), _jsx(Text, { color: theme.version, children: version }), _jsx(Text, { color: theme.value, children: installedSuffix })] }), _jsx(Text, { color: theme.value, children: "  available " }), _jsx(Text, { color: row.available === "unknown" ? theme.warning : theme.version, children: row.available }), _jsxs(Text, { color: theme.warning, children: ["  ", status] }), row.updateReason === undefined ? null : _jsxs(Text, { color: theme.warning, children: ["  ", row.updateReason] }), row.drift === undefined ? null : _jsxs(Text, { color: theme.warning, children: ["  drift: ", row.drift] })] }));
 }
 /** One line of the Installations tree: cursor, indent, mark box, label and the leaf's details. */
 export function TreeRowLine({ row, selected, marked }) {

package/dist/src/tui/package-rows.js

@@ -1,10 +1,13 @@
 import { classifyUpdate } from "../package-host-plans.js";
 import { describeCoordinates, } from "../package-model.js";
 /** Version evidence as a short label; `unknown` when the host or the bundle states none. */
-export function packageVersionLabel(evidence) {
+export function packageVersionLabel(evidence, commit) {
     if (evidence === undefined)
         return "unknown";
-    return evidence.kind === "manifest-version" ? evidence.version : evidence.commit.slice(0, 7);
+    return evidence.kind === "manifest-version" ? versionWithCommit(evidence.version, commit) : evidence.commit.slice(0, 7);
+}
+function versionWithCommit(version, commit) {
+    return `${version}${commit === undefined ? "" : ` (${commit.slice(0, 7)})`}`;
 }
 /** What the host reports about an install, as one phrase. Never a guess. */
 export function installedEvidenceLabel(evidence) {
@@ -12,7 +15,7 @@ export function installedEvidenceLabel(evidence) {
         case "installed": {
             if (evidence.version !== undefined) {
                 const qualifier = evidence.reason === undefined ? "" : " (HEAD; local changes)";
-                return `installed ${evidence.version}${qualifier}`;
+                return `installed ${versionWithCommit(evidence.version, evidence.commit)}${qualifier}`;
             }
             if (evidence.reason !== undefined) {
                 const reason = evidence.reason.includes("local modifications") ? "local changes" : evidence.reason;
@@ -52,17 +55,18 @@ export function packageRow(record, inspection) {
         name: inspection.descriptor?.name ?? describeCoordinates(record.selection),
         installed: installedEvidenceLabel(inspection.installed),
         ...(inspection.installed.kind === "installed" && inspection.installed.version !== undefined
-            ? { installedVersion: inspection.installed.version }
+            ? { installedVersion: versionWithCommit(inspection.installed.version, inspection.installed.commit) }
             : inspection.installed.kind === "installed" && inspection.installed.commit !== undefined
                 ? { installedVersion: inspection.installed.commit.slice(0, 7) }
                 : {}),
-        available: packageVersionLabel(inspection.available),
-        status: packageRowStatus(inspection),
+        available: packageVersionLabel(inspection.available, inspection.availableCommit),
+        status: packageRowStatus(record.selection, inspection),
+        ...(inspection.updateReason === undefined ? {} : { updateReason: inspection.updateReason }),
         ...(inspection.drift === undefined ? {} : { drift: inspection.drift }),
     };
 }
-function packageRowStatus(inspection) {
-    const status = classifyUpdate(inspection.installed, inspection.available, inspection.availableCommit, inspection.installedCommitIsAncestor);
+function packageRowStatus(selection, inspection) {
+    const status = classifyUpdate(inspection.installed, inspection.available, inspection.availableCommit, inspection.installedCommitIsAncestor, selection.host);
     if (status === "unknown") {
         return {
             kind: "unknown",

package/dist/src/tui/updates-panel.js

@@ -24,7 +24,7 @@ function updateResultField(line, defaultOk) {
 /** What the last check found out: its age, how the sources were refreshed, and what failed. */
 export function CheckStatus({ data, now }) {
     const errors = data.results.filter((result) => result.error !== undefined);
-    return (_jsxs(BorderPanel, { title: "Update check", children: [_jsxs(Text, { color: theme.field, children: ["checked ", _jsx(Text, { color: theme.value, children: formatAgo(now - data.checkedAt) }), _jsx(Text, { color: theme.legend, children: " \u00B7 " }), _jsx(Text, { color: theme.value, children: describeRefresh(data) })] }), data.refresh.failed.map((failure) => (_jsxs(Text, { children: [_jsx(Text, { color: theme.warning, children: "[WARN] " }), _jsx(FieldLine, { label: "Refresh failed for", value: `${failure.source}: ${failure.reason}` })] }, failure.source))), data.appError ? _jsxs(Text, { children: [_jsx(Text, { color: theme.error, children: "[FAIL] " }), _jsx(FieldLine, { label: "Error (Apps):", value: data.appError })] }) : null, data.packageError ? _jsxs(Text, { children: [_jsx(Text, { color: theme.error, children: "[FAIL] " }), _jsx(FieldLine, { label: "Error (Packages):", value: data.packageError })] }) : null, errors.map((result) => _jsxs(Text, { children: [_jsx(Text, { color: theme.error, children: "[FAIL] " }), _jsx(FieldLine, { label: `Error (${result.scope}):`, value: result.error ?? "" })] }, result.scope))] }));
+    return (_jsxs(BorderPanel, { title: "Update check", children: [_jsxs(Text, { color: theme.field, children: ["checked ", _jsx(Text, { color: theme.value, children: formatAgo(now - data.checkedAt) }), _jsx(Text, { color: theme.legend, children: " \u00B7 " }), _jsx(Text, { color: theme.value, children: describeRefresh(data) })] }), data.refresh.failed.map((failure) => (_jsxs(Text, { children: [_jsx(Text, { color: theme.warning, children: "[WARN] " }), _jsx(FieldLine, { label: "Refresh failed for", value: `${failure.source}: ${failure.reason}` })] }, failure.source))), data.appError ? _jsxs(Text, { children: [_jsx(Text, { color: theme.error, children: "[FAIL] " }), _jsx(FieldLine, { label: "Error (Apps):", value: data.appError })] }) : null, data.rows.filter(row => row.kind === "package" && row.check.status === "current" && row.check.reason !== undefined).map(row => (_jsxs(Text, { color: theme.warning, children: [row.path, ": ", row.reason] }, row.key))), data.packageError ? _jsxs(Text, { children: [_jsx(Text, { color: theme.error, children: "[FAIL] " }), _jsx(FieldLine, { label: "Error (Packages):", value: data.packageError })] }) : null, errors.map((result) => _jsxs(Text, { children: [_jsx(Text, { color: theme.error, children: "[FAIL] " }), _jsx(FieldLine, { label: `Error (${result.scope}):`, value: result.error ?? "" })] }, result.scope))] }));
 }
 /** One line of the list: an update, the fold of unassessable items, or one of those when unfolded. */
 export function EntryLine({ entry, selected, checked, view, showUnknown }) {

package/dist/src/tui/updates.js

@@ -141,8 +141,10 @@ export async function loadUpdateRows(operations, environment, options) {
             check,
             path: `Package: ${describeCoordinates(check.installed.selection)}`,
             policy: formatVersionPolicy(check.installed.selection.version),
-            installed: recordedVersionLabel(check.installed),
-            available: check.available === undefined ? "?" : packageVersionLabel(check.available),
+            installed: check.observed === undefined
+                ? `${recordedVersionLabel(check.installed)} (recorded)`
+                : installedEvidenceLabel(check.observed).replace(/^installed (?:at )?/, ""),
+            available: check.available === undefined ? "?" : packageVersionLabel(check.available, check.availableCommit),
             status: packageStatusLabel(check.status),
             reason: check.reason ?? "the host reports no usable version evidence",
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iseoane/agent-depot",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "description": "A cross-platform catalog for reusable coding-agent skills.",
   "license": "MIT",
   "author": "iseoane",