agentwheel 0.20.12 → 0.20.14

package/README.md

@@ -414,12 +414,14 @@ label is not endpoint identity.
 
 State created by an older Agentwheel release may be named with the full target fingerprint. For a
 local target, Agentwheel adopts that state only when one canonical graph lock, its v2 install
-manifest, the contribution owner, target details, and graph-lock digest all agree. A supported
-install or uninstall carries an explicit migration and revalidates the old and new state under the
-shared apply lock before replacing the legacy paths. An explicit `stateKey` remains the manifest and
-source-lock key while its legacy graph-lock path moves. Ownership handoff and retirement require a
-full install to migrate first. Status, dependency inspection, uninstall, and journal commands use
-the same discovery rules.
+manifest, the contribution owner, and target details agree. When a tracked graph lock has advanced
+past the installed manifest, Agentwheel uses the manifest only as prior runtime state and resolves
+the graph fresh; it never treats that newer lock as the previously installed graph. Mixed digests
+inside the owned contribution still fail closed. A supported install or uninstall carries an
+explicit migration and revalidates the old and new state under the shared apply lock before replacing
+the legacy paths. An explicit `stateKey` remains the manifest and source-lock key while its legacy
+graph-lock path moves. Status, dependency inspection, uninstall, and journal commands use the same
+discovery rules.
 
 Agentwheel refuses ambiguous candidates, a graph lock without its correlated manifest, or
 disagreeing stable and legacy state, and preserves those files for manual reconciliation. A pending
@@ -443,6 +445,21 @@ agentwheel install --fleet example-fleet --agent lab-claude \
 Once the stable manifest exists, normal status and planning use it while retaining the invalid
 historical candidate for explicit later cleanup.
 
+When stale ownership must be retired before the target-state migration can run, bind the retirement
+to the exact already-installed Fleet manifest instead of asking target-state discovery to choose it:
+
+```bash
+agentwheel ownership retire-stale \
+  --from-workspace-root <missing-worktree> \
+  --to-workspace-root <fleet-root> \
+  --source-state-key <stale-state-key> \
+  --destination-state-key <fleet-owned-state-key> \
+  --fleet <fleet-id> --agent <agent> --json
+```
+
+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.
+
 ## Core Ideas
 
 **Three places, one direction:**

package/dist/index.js

@@ -8469,12 +8469,15 @@ async function discoverTargetApplyJournal(options) {
       throw new Error(`Legacy apply journal graph-lock digest mismatch at ${item.path}.`);
     }
     const manifest = validateJournalManifestEnvelope(journal.manifest, options, journalStateKey, item.path);
-    validateLegacyManifestCandidate(manifest, {
+    const validatedManifest = validateLegacyManifestCandidate(manifest, {
       ...options,
       candidateStateKey: journalStateKey,
       graphLockDigest: journal.graphLockDigest,
       graphLockPath: journal.graphLockPath
     });
+    if (!validatedManifest.graphLockCorrelated) {
+      throw new Error(`Legacy apply journal install manifest graph-lock digest mismatch at ${item.path}.`);
+    }
     correlated.push({ path: item.path, stateKey: journalStateKey });
   }
   if (correlated.length > 1) {
@@ -8496,6 +8499,8 @@ function validateJournalManifestEnvelope(value, options, stateKey, journalPath)
   }
   return manifest;
 }
+var LegacyContributionScopeMismatchError = class extends Error {
+};
 async function resolvePriorTargetState(options) {
   const candidates = await discoverLegacyStateCandidates({
     ...options,
@@ -8503,21 +8508,29 @@ async function resolvePriorTargetState(options) {
   });
   const correlated = candidates.filter((candidate) => candidate.manifest);
   if (options.stableManifest) {
+    const compatible = [];
     for (const candidate of correlated) {
-      if (!sameManifestContributions(options.stableManifest, candidate.manifest)) {
+      if (sameManifestContributions(options.stableManifest, candidate.manifest)) {
+        compatible.push(candidate);
+        continue;
+      }
+      if (!options.recoverLegacyState) {
         throw new Error(
           `Stable and legacy target states coexist with disagreeing contributions for ${options.adapter}; reconcile them explicitly.`
         );
       }
+      options.warn?.(
+        `Legacy target state for ${options.adapter} at ${candidate.graphLockPath} disagrees with the stable manifest. Preserving it outside the explicitly recovered stable state.`
+      );
     }
-    const sameKeyCandidates = correlated.filter((candidate) => candidate.stateKey === options.stateKey);
+    const sameKeyCandidates = compatible.filter((candidate) => candidate.stateKey === options.stateKey);
     if (!options.stableLock && sameKeyCandidates.length > 1) {
       throw new Error(`Ambiguous legacy target state for ${options.adapter}: multiple correlated graph locks use the explicit state key.`);
     }
     if (!options.stableLock && sameKeyCandidates.length === 1) {
       const candidate = sameKeyCandidates[0];
       return {
-        graphLock: candidate.graphLock,
+        graphLock: candidate.graphLockCorrelated ? candidate.graphLock : void 0,
         manifest: options.stableManifest,
         migration: migrationFromCandidate(candidate)
       };
@@ -8535,7 +8548,7 @@ async function resolvePriorTargetState(options) {
   if (correlated.length === 1) {
     const candidate = correlated[0];
     return {
-      graphLock: candidate.graphLock,
+      graphLock: candidate.graphLockCorrelated ? candidate.graphLock : void 0,
       manifest: candidate.manifest,
       migration: migrationFromCandidate(candidate)
     };
@@ -8610,7 +8623,7 @@ async function discoverLegacyStateCandidates(options) {
         if (sourceLock) {
           throw new Error(`Legacy source lock for ${graphLockPath} has no correlated install manifest.`);
         }
-        candidates.push({ stateKey: candidateStateKey, graphLockPath, graphLockDigest, graphLock });
+        candidates.push({ stateKey: candidateStateKey, graphLockPath, graphLockDigest, graphLock, graphLockCorrelated: false });
         continue;
       }
       const validated = validateLegacyManifestCandidate(manifest, {
@@ -8619,16 +8632,26 @@ async function discoverLegacyStateCandidates(options) {
         graphLockDigest,
         graphLockPath
       });
+      if (!validated.graphLockCorrelated) {
+        options.warn?.(
+          `Legacy graph lock at ${graphLockPath} advanced beyond its installed manifest; using the manifest as prior runtime state and resolving the dependency graph fresh.`
+        );
+      }
       candidates.push({
         stateKey: candidateStateKey,
         graphLockPath,
         graphLockDigest,
         graphLock,
-        manifest: validated,
+        graphLockCorrelated: validated.graphLockCorrelated,
+        manifest: validated.manifest,
         sourceLock
       });
     } catch (error) {
       const message = `Legacy target state for ${graphLockPath} is invalid: ` + (error instanceof Error ? error.message : String(error));
+      if (error instanceof LegacyContributionScopeMismatchError) {
+        options.warn?.(`${message} Preserving it as foreign state for ownership validation.`);
+        continue;
+      }
       if (!options.recoverLegacyState) throw new Error(message);
       options.warn?.(`${message} Preserving it outside the recovered stable state.`);
     }
@@ -8651,14 +8674,17 @@ function validateLegacyManifestCandidate(manifest, options) {
   if (normalizeInstallRoot2(manifest.targetRoot, options.transport.kind) !== normalizeInstallRoot2(options.installRoot, options.transport.kind)) {
     throw new Error(`Legacy target state target root mismatch at ${options.graphLockPath}.`);
   }
-  const correlated = manifest.entries.filter((entry) => entry.graphLockDigest === options.graphLockDigest);
-  if (correlated.length === 0) {
-    throw new Error(`Legacy install manifest graph-lock digest does not match ${options.graphLockPath}.`);
+  const ownedEntries = manifest.entries.filter((entry) => entry.workspaceOwner === options.workspaceOwner);
+  if (ownedEntries.length === 0) {
+    throw new LegacyContributionScopeMismatchError(
+      `Legacy target state contribution scope does not match ${options.graphLockPath}.`
+    );
   }
-  if (correlated.some((entry) => entry.workspaceOwner !== options.workspaceOwner)) {
-    throw new Error(`Legacy target state contribution scope does not match ${options.graphLockPath}.`);
+  const manifestDigests = new Set(ownedEntries.map((entry) => entry.graphLockDigest));
+  if (manifestDigests.size !== 1) {
+    throw new Error(`Legacy install manifest has inconsistent graph-lock digests at ${options.graphLockPath}.`);
   }
-  return manifest;
+  return { manifest, graphLockCorrelated: manifestDigests.has(options.graphLockDigest) };
 }
 function migrationFromCandidate(candidate) {
   return {
@@ -11907,6 +11933,13 @@ async function planFleetNormalization(request) {
     const sourcePackage = sourceByName.get(name);
     const destinationPackage = destinationByName.get(name);
     if (!sourcePackage || !destinationPackage) {
+      if (legacySelfNormalization && normalizedRequest.orphanedOwnerRoots?.length && normalizedRequest.packages?.includes(name)) {
+        packages.push({
+          name,
+          declarationDigest: sha2565(canonicalJson2({ name, evidence: "orphaned-installed-state" }))
+        });
+        continue;
+      }
       throw new Error(`Package '${name}' must be an existing duplicate in both source and destination fleets.`);
     }
     const sourceDeclaration = canonicalJson2(sourcePackage);
@@ -12376,11 +12409,12 @@ async function inspectLegacySelfInstalledState(fleet, packageNames, profileName,
   const legacyOwner = workspaceOwnerForRoot(fleet.root);
   const fleetOwner = workspaceOwnerForRoot(fleet.root, fleet.fleetId);
   const orphanedOwners = await orphanedWorkspaceOwners(orphanedOwnerRoots);
+  const allowOrphanedRetiredPackages = orphanedOwners.size > 0;
   const knownLegacyOwners = /* @__PURE__ */ new Set([legacyOwner, ...orphanedOwners]);
   const transferableOwners = orphanedOwners.size > 0 ? orphanedOwners : /* @__PURE__ */ new Set([legacyOwner]);
   let normalizedGraphCount = 0;
   for (const graph of graphCandidates) {
-    const destinationState = await targetStateForGraph(fleet, graph, fleet.fleetId);
+    const destinationState = await targetStateForGraph(fleet, graph, fleet.fleetId, allowOrphanedRetiredPackages);
     if (resolve25(destinationState.graphLockPath) === resolve25(graph.path)) {
       const destinationManifest = (await collectManifestPaths([destinationState.manifestPath]))[0];
       if (destinationManifest?.manifest.entries.some((entry) => entry.workspaceOwner === fleetOwner && entryMatchesPackages(entry, selected))) {
@@ -12395,7 +12429,7 @@ async function inspectLegacySelfInstalledState(fleet, packageNames, profileName,
         continue;
       }
     }
-    const legacyState = await legacyTargetStateForGraph(fleet, graph);
+    const legacyState = await legacyTargetStateForGraph(fleet, graph, allowOrphanedRetiredPackages);
     if (resolve25(legacyState.graphLockPath) !== resolve25(graph.path)) {
       throw new Error(`Legacy graph lock target identity is stale or noncanonical: ${graph.path}`);
     }
@@ -12410,8 +12444,8 @@ async function inspectLegacySelfInstalledState(fleet, packageNames, profileName,
   }
   const manifestPaths = /* @__PURE__ */ new Set();
   for (const graph of graphs) {
-    manifestPaths.add((await legacyTargetStateForGraph(fleet, graph)).manifestPath);
-    manifestPaths.add((await targetStateForGraph(fleet, graph, fleet.fleetId)).manifestPath);
+    manifestPaths.add((await legacyTargetStateForGraph(fleet, graph, allowOrphanedRetiredPackages)).manifestPath);
+    manifestPaths.add((await targetStateForGraph(fleet, graph, fleet.fleetId, allowOrphanedRetiredPackages)).manifestPath);
   }
   const manifests = await collectManifestPaths([...manifestPaths]);
   const relevantEntries = manifests.flatMap((manifest) => manifest.manifest.entries.filter((entry) => graphs.some((graph) => entryMatchesGraphPackages(entry, graph.lock, selected)) && entryMatchesArtifacts(entry, selectedArtifacts)).map((entry) => ({ manifest, entry, renderedPath: renderedEntryPath(manifest.manifest, entry) })));
@@ -12448,8 +12482,8 @@ async function inspectLegacySelfInstalledState(fleet, packageNames, profileName,
   const renderedPaths = /* @__PURE__ */ new Set();
   const orphanedUnmanagedPaths = /* @__PURE__ */ new Set();
   for (const graph of graphs) {
-    const legacyState = await legacyTargetStateForGraph(fleet, graph);
-    const destinationState = await targetStateForGraph(fleet, graph, fleet.fleetId);
+    const legacyState = await legacyTargetStateForGraph(fleet, graph, allowOrphanedRetiredPackages);
+    const destinationState = await targetStateForGraph(fleet, graph, fleet.fleetId, allowOrphanedRetiredPackages);
     if (graph.path === destinationState.graphLockPath) {
       throw new Error(`Fleet '${fleet.fleetId}' graph state is already normalized to fleet-qualified identity.`);
     }
@@ -12733,7 +12767,7 @@ async function legacyManifestPathForConfiguredTarget(scope, graph) {
   });
   return installManifestPath(installRoot, adapter.name, { installationType: agent.installationType, stateKey });
 }
-async function targetStateForGraph(scope, graph, identityFleetId = scope.fleetId ?? null) {
+async function targetStateForGraph(scope, graph, identityFleetId = scope.fleetId ?? null, allowMissingNamedAgentPackages = false) {
   const agent = scope.config.agents[graph.targetKey];
   if (agent?.transport === "ssh") {
     throw new Error(`Installed-state normalization cannot hand off SSH target '${graph.targetKey}' locally.`);
@@ -12742,10 +12776,10 @@ async function targetStateForGraph(scope, graph, identityFleetId = scope.fleetId
     throw new Error(`Graph adapter '${graph.adapter}' does not match configured target adapter '${agent.adapter}'.`);
   }
   const graphPackages = graph.lock.canonical.roots.map((root) => scope.config.packages.find((pkg) => pkg.name === root.rootId));
-  if (graphPackages.some((pkg) => !pkg)) {
+  if (graphPackages.some((pkg) => !pkg) && !(allowMissingNamedAgentPackages && agent && agent.installationType)) {
     throw new Error(`Graph target '${graph.targetKey}' contains a package absent from the fleet configuration.`);
   }
-  const packages = graphPackages;
+  const packages = graphPackages.filter((pkg) => pkg !== void 0);
   if (!agent) {
     if (graph.targetKey !== graph.adapter) {
       throw new Error(
@@ -12760,18 +12794,18 @@ async function targetStateForGraph(scope, graph, identityFleetId = scope.fleetId
       throw new Error(`Graph adapter '${graph.adapter}' does not match direct package adapter '${packageAdapter}'.`);
     }
   }
-  const installationType = oneEffectiveValue(
+  const installationType = packages.length > 0 ? oneEffectiveValue(
     packages.map((pkg) => pkg.installationType ?? agent?.installationType ?? "local"),
     `installation type for target '${graph.targetKey}'`
-  );
-  const adapterConfig = oneEffectiveOptionalValue(
+  ) : agent.installationType;
+  const adapterConfig = packages.length > 0 ? oneEffectiveOptionalValue(
     packages.map((pkg) => agent?.adapterConfig ?? pkg.adapterConfig),
     `adapter config for target '${graph.targetKey}'`
-  );
-  const adapterModule = oneEffectiveOptionalValue(
+  ) : agent?.adapterConfig;
+  const adapterModule = packages.length > 0 ? oneEffectiveOptionalValue(
     packages.map((pkg) => agent?.adapterModule ?? pkg.adapterModule),
     `adapter module for target '${graph.targetKey}'`
-  );
+  ) : agent?.adapterModule;
   const adapter = await resolveAdapter({
     adapter: agent?.adapter ?? graph.adapter,
     adapterConfig,
@@ -12841,8 +12875,8 @@ async function installedTargetStateForGraph(scope, graph, manifests, owners, sel
   assertCorrelatedGraphManifest(graph, state, manifest, owners, selected);
   return state;
 }
-async function releasedTargetStateForGraph(scope, graph, identityFleetId = scope.fleetId ?? null) {
-  const current = await targetStateForGraph(scope, graph, identityFleetId);
+async function releasedTargetStateForGraph(scope, graph, identityFleetId = scope.fleetId ?? null, allowMissingNamedAgentPackages = false) {
+  const current = await targetStateForGraph(scope, graph, identityFleetId, allowMissingNamedAgentPackages);
   const targetFingerprint = graph.lock.canonical.targetFingerprint;
   if (!targetFingerprint || !/^[a-f0-9]{64}$/u.test(targetFingerprint)) {
     throw new Error(`Released graph lock has an invalid target fingerprint: ${graph.path}`);
@@ -12887,8 +12921,8 @@ function assertCorrelatedGraphManifest(graph, state, manifest, owners, selected)
     }
   }
 }
-async function legacyTargetStateForGraph(scope, graph) {
-  return releasedTargetStateForGraph(scope, graph, null);
+async function legacyTargetStateForGraph(scope, graph, allowMissingNamedAgentPackages = false) {
+  return releasedTargetStateForGraph(scope, graph, null, allowMissingNamedAgentPackages);
 }
 function assertGraphIsSubset(source, destination) {
   const sourceRoots = new Map(source.lock.canonical.roots.map((root) => [root.rootId, canonicalJson2(root)]));
@@ -14000,7 +14034,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").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").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);
@@ -14015,19 +14049,16 @@ ownershipCommand.command("retire-stale").description("retire stale source-manife
   if (target.fleetId !== options.fleet || resolve26(target.workspaceRoot) !== resolve26(fleet.root)) {
     throw new Error(`Resolved target does not belong to destination Fleet '${options.fleet}'.`);
   }
-  const state = await resolveCliTargetState(target, normalizedOptions);
-  const { adapter, installationType } = state;
-  if (state.migration) {
-    throw new Error(
-      "Migrate the target state before ownership retirement by running a full agentwheel install for this target."
-    );
-  }
+  const adapterOptions = adapterOptionsForTarget(target, normalizedOptions);
+  const adapter = await resolveAdapterForTarget(target, adapterOptions);
+  const installationType = normalizedOptions.installationType ?? target.installationType ?? resolveInstallationTypeForAdapter(adapter, void 0);
+  const stableState = installStateForTarget(target, adapter, adapterOptions, installationType);
   const request = {
-    targetRoot: state.installRoot,
+    targetRoot: stableState.installRoot,
     adapter: adapter.name,
     installationType,
     sourceStateKey: options.sourceStateKey,
-    destinationStateKey: state.stableStateKey,
+    destinationStateKey: options.destinationStateKey ?? stableState.stateKey,
     fromWorkspaceRoot: normalizeCliPath(options.fromWorkspaceRoot),
     toWorkspaceRoot,
     toFleetId: fleet.id,
@@ -14050,6 +14081,8 @@ ownershipCommand.command("retire-stale").description("retire stale source-manife
     request.toWorkspaceRoot,
     "--source-state-key",
     request.sourceStateKey,
+    "--destination-state-key",
+    request.destinationStateKey,
     "--fleet",
     request.toFleetId,
     ...targetArgs,

package/openpack.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwheel",
-  "version": "0.20.12",
+  "version": "0.20.14",
   "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.12"
+  version: "0.20.14"
 ---
 
 # agentwheel
@@ -632,3 +632,10 @@ agentwheel plan --fleet <fleet-id> --agent <agent> \
 planning base. `--force-conflict` adopts exact existing content; `--replace-conflict` permits the
 reviewed plan to update differing unmanaged content. Apply only the same reviewed target and flags.
 After the first stable install, rerun the ordinary plan without recovery flags and require a no-op.
+
+An advanced tracked graph lock with an otherwise valid owned v2 manifest is an ordinary migration:
+Agentwheel keeps the manifest as prior runtime state, resolves the graph fresh, and does not trust the
+advanced lock as installed history. If stale foreign ownership blocks that migration, use
+`agentwheel ownership retire-stale --destination-state-key <exact-fleet-state-key>` to produce a
+metadata-only, revision-gated retirement plan against the already-installed Fleet manifest. Do not
+guess the state key or apply without the exact command emitted by the dry-run.

package/skills/agentwheel-discovery/SKILL.md

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