agentwheel 0.20.15 → 0.20.17

package/README.md

@@ -148,6 +148,8 @@ revalidates the exact contribution under the apply lock. It removes only the sel
 server; sibling servers and user configuration remain. The command previews by default. A later
 runtime approval must use the same command with `--apply` instead of `--dry-run`.
 
+When stable and legacy manifests disagree, `update --recover-legacy-state` explicitly uses recovered stable state while preserving legacy evidence. Preview the same command with `--dry-run` first.
+
 For a surgical dependency update, start with a dry-run:
 
 ```bash
@@ -459,6 +461,15 @@ agentwheel ownership retire-stale \
 
 The dry-run still proves exact destination coverage and runtime bytes. Apply only its emitted command,
 which includes the plan, source, destination, and manifest-inventory revisions.
+For duplicate state owned by the same registered Fleet, set both workspace roots to the Fleet root
+and add `--from-fleet-id <fleet-id>`. The planner selects only legacy paths covered by the stable
+Fleet manifest. For JSON deep merges it also accepts a source contribution that is an exact
+recursive subset of the destination contribution. Across package revisions, merge entries must
+identify the same package and artifact with equal source hashes; other merge contributions must
+match exactly. A source-only path stays in the legacy manifest;
+when every source entry is covered, apply removes the old manifest and source lock without changing
+runtime files or the stable manifest. Preserve copies of those old state files before applying a
+retirement when they are needed as historical evidence.
 
 ## Core Ideas
 

package/dist/index.js

@@ -10001,7 +10001,7 @@ async function observe(request, transport) {
   const normalized = normalizeRequest(request);
   const source = await requireManifest(normalized, normalized.sourceStateKey, transport, "source");
   const destination = await requireManifest(normalized, normalized.destinationStateKey, transport, "destination");
-  const sourceOwner = workspaceOwnerForRoot(normalized.fromWorkspaceRoot);
+  const sourceOwner = workspaceOwnerForRoot(normalized.fromWorkspaceRoot, normalized.fromFleetId);
   const destinationOwner = workspaceOwnerForRoot(normalized.toWorkspaceRoot, normalized.toFleetId);
   const destinationByPath = /* @__PURE__ */ new Map();
   for (const entry of destination.entries) {
@@ -10078,6 +10078,11 @@ function normalizeRequest(request) {
   const destinationStateKey = exactStateKey(request.adapter, request.destinationStateKey, request.installationType, "destination");
   if (sourceStateKey === destinationStateKey) throw new Error("Source and destination state keys must differ.");
   if (!request.toFleetId.trim()) throw new Error("Destination Fleet id is required.");
+  const fromFleetId = request.fromFleetId?.trim();
+  if (request.fromFleetId !== void 0 && !fromFleetId) throw new Error("Source Fleet id cannot be empty.");
+  if (fromFleetId && (fromFleetId !== request.toFleetId.trim() || resolve21(request.fromWorkspaceRoot) !== resolve21(request.toWorkspaceRoot))) {
+    throw new Error("Fleet-qualified stale ownership retirement requires the same source and destination Fleet and workspace root.");
+  }
   return {
     ...request,
     targetRoot,
@@ -10085,6 +10090,7 @@ function normalizeRequest(request) {
     sourceStateKey,
     destinationStateKey,
     fromWorkspaceRoot: resolve21(request.fromWorkspaceRoot),
+    ...fromFleetId ? { fromFleetId } : {},
     toWorkspaceRoot: resolve21(request.toWorkspaceRoot),
     toFleetId: request.toFleetId.trim()
   };
@@ -10121,6 +10127,7 @@ function assertRetirableSourceEntry(entry, abandonIncompleteMergeOwner) {
   }
 }
 async function assertContributionCoverage(source, destination, targetRoot, transport, abandonIncompleteMergeOwner) {
+  containedArtifactPath(targetRoot, source.path);
   const sourceManagedBlock = source.mode === "managed-block";
   const destinationManagedBlock = destination.mode === "managed-block";
   const sourceMerge = source.mergeStrategy !== void 0;
@@ -10146,8 +10153,19 @@ async function assertContributionCoverage(source, destination, targetRoot, trans
       if (abandonIncompleteMergeOwner) return "abandoned-incomplete-merge";
       throw new Error(`Cannot retire incomplete merge ownership at ${source.path}.`);
     }
-    const exactlyCovered = destination.mergeStrategy === source.mergeStrategy && hasMergeRemovalContent(destination.mergeRemoval) && contributionSelector(source) === contributionSelector(destination) && canonicalJson(source.mergeRemoval) === canonicalJson(destination.mergeRemoval);
+    const selectorsDiffer = contributionSelector(source) !== contributionSelector(destination);
+    if (selectorsDiffer && !sameContributionSelector(source, destination)) {
+      throw new Error(`Destination Fleet does not identify the same source merge artifact at ${source.path}.`);
+    }
+    if (source.mergeStrategy === "json-deep" && destination.mergeStrategy === "json-deep" && hasMergeRemovalContent(destination.mergeRemoval) && sameContributionSelector(source, destination)) {
+      if (canonicalJson(combineMergeRemovals(destination.mergeRemoval, source.mergeRemoval)) === canonicalJson(destination.mergeRemoval)) return "exact";
+      throw new Error(`Destination Fleet does not exactly cover stale source merge contribution at ${source.path}.`);
+    }
+    const exactlyCovered = destination.mergeStrategy === source.mergeStrategy && hasMergeRemovalContent(destination.mergeRemoval) && sameContributionSelector(source, destination) && canonicalJson(source.mergeRemoval) === canonicalJson(destination.mergeRemoval);
     if (exactlyCovered) return "exact";
+    if (selectorsDiffer) {
+      throw new Error(`Destination Fleet does not exactly cover stale source merge contribution at ${source.path}.`);
+    }
     const current = await transport.readFile(containedArtifactPath(targetRoot, source.path));
     if (!mergeContributionAbsent(source.mergeRemoval, source.mergeStrategy, current)) {
       throw new Error(`Destination Fleet does not exactly cover or replace stale source merge contribution at ${source.path}.`);
@@ -10159,6 +10177,15 @@ async function assertContributionCoverage(source, destination, targetRoot, trans
 function contributionSelector(entry) {
   return entry.logicalSelector ?? `${entry.artifactType}/${entry.artifactName}`;
 }
+function sameContributionSelector(source, destination) {
+  if (contributionSelector(source) === contributionSelector(destination)) return true;
+  if (!source.packageName || source.packageName !== destination.packageName || source.artifactType !== destination.artifactType || source.artifactName !== destination.artifactName || source.installName !== destination.installName || source.sourceHash !== destination.sourceHash || !source.graphNodeId || !destination.graphNodeId) return false;
+  const selector = artifactSelectorKey({ type: source.artifactType, name: source.artifactName });
+  if (source.logicalSelector !== `${source.graphNodeId}:${selector}` || destination.logicalSelector !== `${destination.graphNodeId}:${selector}`) return false;
+  const sourceAt = source.graphNodeId.lastIndexOf("@");
+  const destinationAt = destination.graphNodeId.lastIndexOf("@");
+  return sourceAt > 0 && destinationAt > 0 && source.graphNodeId.slice(0, sourceAt) === source.packageName && destination.graphNodeId.slice(0, destinationAt) === destination.packageName && source.graphNodeId.indexOf("+", sourceAt) > sourceAt && destination.graphNodeId.indexOf("+", destinationAt) > destinationAt;
+}
 function assertApplyPreconditions(request) {
   for (const [label, value] of [
     ["plan digest", request.planDigest],
@@ -13764,7 +13791,7 @@ program.command("sync", { hidden: true }).argument("[name-or-source]", "configur
   console.error("warning: 'agentwheel sync' is deprecated and will be removed in 0.10. Use 'agentwheel install'.");
   await runInstallCommand(source, options, { apply: !options.dryRun });
 });
-program.command("update").description("re-resolve tracking packages, then apply the result").argument("[name]", "configured package name or source to update").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "use the user workspace", false).option("--local", "use the nearest local workspace", false).option("--fleet <id>", "use one registered named fleet").option("-t, --target-root <path>", "workspace root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plans without writing", false).option("--force-drift", "replace drifted managed artifacts", false).option("--force-foreign-state", "plan even when another workspace owns install state at the same paths", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--reload-runtimes", "run configured runtime reload commands after executed semantic plugin changes", false).option("--restart-runtimes", "alias for --reload-runtimes", false).option("--allow-adapter-code", "allow loading local adapter code from configured packages", false).option("--select <type/name>", "temporarily select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--artifact <type/name>", "update only one configured artifact while preserving sibling state").option("--skill <name>", "temporarily select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--dependency <name-or-source>", "update one tracking dependency while keeping unrelated graph nodes locked (repeatable)", collectDependencyOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "exclude unrelated configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--refresh", "refresh available package versions even when the version-index TTL is fresh", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (name, options) => {
+program.command("update").description("re-resolve tracking packages, then apply the result").argument("[name]", "configured package name or source to update").option("--adapter <adapter>", "built-in adapter or comma-separated adapters").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--user", "use the user workspace", false).option("--local", "use the nearest local workspace", false).option("--fleet <id>", "use one registered named fleet").option("-t, --target-root <path>", "workspace root").option("--agent <name>", "named agent from merged config").option("--all", "run for every configured agent", false).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plans without writing", false).option("--force-drift", "replace drifted managed artifacts", false).option("--force-foreign-state", "plan even when another workspace owns install state at the same paths", false).option("--force-conflict", "adopt unmanaged destinations when their content already matches the desired artifact", false).option("--replace-conflict", "replace unmanaged destinations even when their content differs", false).option("--recover-legacy-state", "build a stable state while preserving invalid legacy candidates", false).option("--execute-plugins", "execute semantic plugin installs", false).option("--reload-runtimes", "run configured runtime reload commands after executed semantic plugin changes", false).option("--restart-runtimes", "alias for --reload-runtimes", false).option("--allow-adapter-code", "allow loading local adapter code from configured packages", false).option("--select <type/name>", "temporarily select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--artifact <type/name>", "update only one configured artifact while preserving sibling state").option("--skill <name>", "temporarily select a skill by name (repeatable or comma-separated)", collectSkillOption, []).option("--dependency <name-or-source>", "update one tracking dependency while keeping unrelated graph nodes locked (repeatable)", collectDependencyOption, []).option("--with-suggestions", "include suggested companion artifacts for selected roots", false).option("--suggestion <alias>", "include one suggested companion alias (repeatable or comma-separated)", collectSuggestionOption, []).option("--no-deps", "resolve only root sources and ignore requires with a warning").option("--only-source", "exclude unrelated configured workspace packages", false).option("--frozen-lock", "resolve strictly from the existing graph lock and cached sources", false).option("--offline", "resolve strictly from graph locks and local caches", false).option("--refresh", "refresh available package versions even when the version-index TTL is fresh", false).option("--yes", "trust all new transitive sources", false).option("--trust <pattern>", "pre-approve a transitive source glob (repeatable)", collectTrustOption, []).action(async (name, options) => {
   if (options.onlySource && options.dependency.length > 0) throw new Error("--only-source cannot be combined with --dependency.");
   if (options.onlySource && !name) throw new Error("--only-source requires a configured package argument.");
   if (name && options.dependency.length > 0) throw new Error("A package argument cannot be combined with --dependency.");
@@ -14035,7 +14062,7 @@ ownershipCommand.command("recovery-plan").description("write a read-only per-pat
     await rm10(stage, { recursive: true, force: true });
   }
 });
-ownershipCommand.command("retire-stale").description("retire stale source-manifest ownership already covered by one Fleet manifest").requiredOption("--from-workspace-root <path>", "exact stale workspace owner root").requiredOption("--to-workspace-root <path>", "registered destination Fleet root").requiredOption("--source-state-key <key>", "exact source install-manifest state key").option("--destination-state-key <key>", "exact Fleet-owned destination install-manifest state key (defaults to the stable target state)").requiredOption("--fleet <id>", "registered destination Fleet").option("--adapter <adapter>", "built-in adapter").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named destination Fleet agent").option("--profile <name>", "destination Fleet profile resolving to one target").option("--plan-digest <sha256>", "reviewed plan digest; required with --apply").option("--expected-source-revision <sha256>", "reviewed source manifest revision; required with --apply").option("--expected-destination-revision <sha256>", "reviewed destination manifest revision; required with --apply").option("--expected-inventory-revision <sha256>", "reviewed runtime manifest inventory revision; required with --apply").option("--abandon-incomplete-merge-owner", "explicitly retire incomplete legacy merge metadata without changing runtime bytes", false).option("--apply", "apply the exact reviewed metadata-only retirement", false).option("--json", "print the complete deterministic plan as JSON", false).action(async (options) => {
+ownershipCommand.command("retire-stale").description("retire stale source-manifest ownership already covered by one Fleet manifest").requiredOption("--from-workspace-root <path>", "exact stale workspace owner root").option("--from-fleet-id <id>", "exact stale Fleet owner id for same-Fleet duplicate state").requiredOption("--to-workspace-root <path>", "registered destination Fleet root").requiredOption("--source-state-key <key>", "exact source install-manifest state key").option("--destination-state-key <key>", "exact Fleet-owned destination install-manifest state key (defaults to the stable target state)").requiredOption("--fleet <id>", "registered destination Fleet").option("--adapter <adapter>", "built-in adapter").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named destination Fleet agent").option("--profile <name>", "destination Fleet profile resolving to one target").option("--plan-digest <sha256>", "reviewed plan digest; required with --apply").option("--expected-source-revision <sha256>", "reviewed source manifest revision; required with --apply").option("--expected-destination-revision <sha256>", "reviewed destination manifest revision; required with --apply").option("--expected-inventory-revision <sha256>", "reviewed runtime manifest inventory revision; required with --apply").option("--abandon-incomplete-merge-owner", "explicitly retire incomplete legacy merge metadata without changing runtime bytes", false).option("--apply", "apply the exact reviewed metadata-only retirement", false).option("--json", "print the complete deterministic plan as JSON", false).action(async (options) => {
   const normalizedOptions = normalizeRuntimeScopeOptions(options);
   const fleet = await showRegisteredFleet(options.fleet);
   const toWorkspaceRoot = normalizeCliPath(options.toWorkspaceRoot);
@@ -14061,6 +14088,7 @@ ownershipCommand.command("retire-stale").description("retire stale source-manife
     sourceStateKey: options.sourceStateKey,
     destinationStateKey: options.destinationStateKey ?? stableState.stateKey,
     fromWorkspaceRoot: normalizeCliPath(options.fromWorkspaceRoot),
+    fromFleetId: options.fromFleetId,
     toWorkspaceRoot,
     toFleetId: fleet.id,
     planDigest: options.planDigest,
@@ -14078,6 +14106,7 @@ ownershipCommand.command("retire-stale").description("retire stale source-manife
     "retire-stale",
     "--from-workspace-root",
     request.fromWorkspaceRoot,
+    ...request.fromFleetId ? ["--from-fleet-id", request.fromFleetId] : [],
     "--to-workspace-root",
     request.toWorkspaceRoot,
     "--source-state-key",
@@ -16209,6 +16238,7 @@ function compositeUpdateArguments(profile, packageName, options) {
   args.push("--profile", profile);
   if (options.dryRun) args.push("--dry-run");
   if (options.refresh) args.push("--refresh");
+  if (options.recoverLegacyState) args.push("--recover-legacy-state");
   if (options.forceDrift) args.push("--force-drift");
   if (options.forceForeignState) args.push("--force-foreign-state");
   if (options.forceConflict) args.push("--force-conflict");

package/openpack.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "name": "NestDevLab/agentwheel",
-  "version": "0.20.15",
+  "version": "0.20.17",
   "provides": [
     { "type": "skills", "path": "skills" }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwheel",
-  "version": "0.20.15",
+  "version": "0.20.17",
   "description": "Weave skills, rules, and instructions across every AI agent.",
   "type": "module",
   "license": "MIT",

package/skills/agentwheel/SKILL.md

@@ -5,7 +5,7 @@ allowed-tools: [Bash]
 license: MIT
 metadata:
   author: NestDevLab
-  version: "0.20.15"
+  version: "0.20.17"
 ---
 
 # agentwheel

package/skills/agentwheel-discovery/SKILL.md

@@ -5,7 +5,7 @@ allowed-tools: [Bash]
 license: MIT
 metadata:
   author: NestDevLab
-  version: "0.20.15"
+  version: "0.20.17"
 ---
 
 # Agentwheel Discovery