agentwheel 0.20.10 → 0.20.12

package/README.md

@@ -427,6 +427,22 @@ apply journal that embeds and exactly correlates the missing manifest and graph
 discoverable for recovery. Legacy SSH state is also preserved and refused because the old records do
 not prove which endpoint owned it.
 
+After reviewing `agentwheel ownership recovery-plan`, use `--recover-legacy-state` only for an
+invalid local candidate whose historical files must remain preserved. The recovery plan ignores
+that candidate when constructing the new stable state; it does not authorize runtime replacement.
+Adopting matching unmanaged files still requires `--force-conflict`, while replacing differing files
+still requires `--replace-conflict`. Review the resulting plan before applying the same flags:
+
+```bash
+agentwheel plan --fleet example-fleet --agent lab-claude \
+  --recover-legacy-state --force-conflict --replace-conflict
+agentwheel install --fleet example-fleet --agent lab-claude \
+  --recover-legacy-state --force-conflict --replace-conflict
+```
+
+Once the stable manifest exists, normal status and planning use it while retaining the invalid
+historical candidate for explicit later cleanup.
+
 ## Core Ideas
 
 **Three places, one direction:**

package/dist/{apply-ZNEUBJU3.js → apply-ZGCJLZMZ.js}

@@ -5,9 +5,9 @@ import {
   commitManifestMetadataJournal,
   recoverPendingApply,
   uninstall
-} from "./chunk-P2JK34W7.js";
-import "./chunk-J7DKPDS7.js";
-import "./chunk-7VPI5J5Y.js";
+} from "./chunk-A44XYLUT.js";
+import "./chunk-FP26KSBM.js";
+import "./chunk-GE7F76AC.js";
 export {
   applyCombinedInstallPlan,
   applyInstallPlan,

package/dist/{chunk-P2JK34W7.js → chunk-A44XYLUT.js}

@@ -24,11 +24,11 @@ import {
   rollbackCompletedOperations,
   sourceLockPath,
   writeApplyJournal
-} from "./chunk-J7DKPDS7.js";
+} from "./chunk-FP26KSBM.js";
 import {
   pathExists,
   writeJsonAtomic
-} from "./chunk-7VPI5J5Y.js";
+} from "./chunk-GE7F76AC.js";
 
 // src/install/apply.ts
 import { execFile } from "child_process";

package/dist/{chunk-J7DKPDS7.js → chunk-FP26KSBM.js}

@@ -4,7 +4,7 @@ import {
   hashPath,
   pathExists,
   writeJsonAtomic
-} from "./chunk-7VPI5J5Y.js";
+} from "./chunk-GE7F76AC.js";
 
 // src/install/transaction.ts
 import { createHash as createHash6 } from "crypto";
@@ -2865,8 +2865,8 @@ async function recoverMutationRuntime(operationId, options = {}) {
     }
     mutation = GovernedMutation.activateExisting(receipt, baseline, lock);
     const [{ recoverPendingApply }, { readLinkedLocalApplyJournal: readLinkedLocalApplyJournal2, removeApplyJournal: removeApplyJournal2, localPathExists: localPathExists2 }] = await Promise.all([
-      import("./apply-ZNEUBJU3.js"),
-      import("./transaction-4ERCJXG7.js")
+      import("./apply-ZGCJLZMZ.js"),
+      import("./transaction-4KBNHDQX.js")
     ]);
     let missingReservation = false;
     for (const entry of pending) {

package/dist/{chunk-7VPI5J5Y.js → chunk-GE7F76AC.js}

@@ -90,6 +90,7 @@ async function withFilesystemLock(lockPath, timeoutMs, fn, description = "cache"
       break;
     } catch (error) {
       if (!isAlreadyExists(error)) throw error;
+      if (await removeStaleFilesystemLock(lockPath)) continue;
       if (Date.now() - started > timeoutMs) {
         throw new Error(`Timed out waiting for ${description} lock at ${lockPath}`);
       }
@@ -102,6 +103,26 @@ async function withFilesystemLock(lockPath, timeoutMs, fn, description = "cache"
     await rm(lockPath, { recursive: true, force: true });
   }
 }
+async function removeStaleFilesystemLock(lockPath) {
+  try {
+    const owner = JSON.parse(await readFile(join(lockPath, "owner.json"), "utf8"));
+    if (typeof owner.pid !== "number" || !Number.isSafeInteger(owner.pid) || owner.pid <= 0 || isProcessAlive(owner.pid)) return false;
+    const stalePath = `${lockPath}.stale-${process.pid}-${Date.now()}`;
+    await rename(lockPath, stalePath);
+    await rm(stalePath, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code !== "ESRCH";
+  }
+}
 function isAlreadyExists(error) {
   return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
 }

package/dist/{chunk-EMDIG24I.js → chunk-U2GRG4UI.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   pathExists
-} from "./chunk-7VPI5J5Y.js";
+} from "./chunk-GE7F76AC.js";
 
 // src/source/identify.ts
 import { homedir } from "os";

package/dist/{identify-D64HZTUT.js → identify-O54QXPQR.js}

@@ -2,8 +2,8 @@
 import {
   inferSourceDriverName,
   isExplicitSource
-} from "./chunk-EMDIG24I.js";
-import "./chunk-7VPI5J5Y.js";
+} from "./chunk-U2GRG4UI.js";
+import "./chunk-GE7F76AC.js";
 export {
   inferSourceDriverName,
   isExplicitSource

package/dist/index.js

@@ -37,7 +37,7 @@ import {
   uninstall,
   withManifestRevision,
   writeInstallManifest
-} from "./chunk-P2JK34W7.js";
+} from "./chunk-A44XYLUT.js";
 import {
   CURRENT_WORKSPACE_SCHEMA_VERSION,
   GovernedMutation,
@@ -98,10 +98,10 @@ import {
   workspaceSelectionImportSchema,
   writeApplyJournal,
   writeWorkspaceConfig
-} from "./chunk-J7DKPDS7.js";
+} from "./chunk-FP26KSBM.js";
 import {
   inferSourceDriverName
-} from "./chunk-EMDIG24I.js";
+} from "./chunk-U2GRG4UI.js";
 import {
   hashPath,
   isAlreadyExists,
@@ -110,7 +110,7 @@ import {
   pathExists,
   withFilesystemLock,
   writeJsonAtomic
-} from "./chunk-7VPI5J5Y.js";
+} from "./chunk-GE7F76AC.js";
 
 // src/cli/index.ts
 import { createHash as createHash15 } from "crypto";
@@ -5789,7 +5789,7 @@ var RegistryClient = class {
   }
 };
 async function resolvePackageSource(source, workspaceRoot, options = {}) {
-  const { isExplicitSource } = await import("./identify-D64HZTUT.js");
+  const { isExplicitSource } = await import("./identify-O54QXPQR.js");
   if (await isExplicitSource(source)) return { source };
   const entry = await new RegistryClient({ workspaceRoot, offline: options.offline, warn: options.warn }).resolve(source);
   if (!entry) {
@@ -8233,7 +8233,9 @@ async function createGraphSourcePlan(options) {
       graphLockPath,
       stableManifest,
       stableLock: stableLock2,
-      transport
+      transport,
+      recoverLegacyState: options.recoverLegacyState,
+      warn
     });
     return { priorState: priorState2, stableLock: stableLock2, stableSourceLock: stableSourceLock2 };
   };
@@ -8495,7 +8497,10 @@ function validateJournalManifestEnvelope(value, options, stateKey, journalPath)
   return manifest;
 }
 async function resolvePriorTargetState(options) {
-  const candidates = await discoverLegacyStateCandidates(options);
+  const candidates = await discoverLegacyStateCandidates({
+    ...options,
+    recoverLegacyState: options.recoverLegacyState === true || options.stableManifest !== void 0
+  });
   const correlated = candidates.filter((candidate) => candidate.manifest);
   if (options.stableManifest) {
     for (const candidate of correlated) {
@@ -8536,6 +8541,14 @@ async function resolvePriorTargetState(options) {
     };
   }
   if (options.stableLock) return { graphLock: options.stableLock };
+  if (candidates.length > 0 && options.recoverLegacyState) {
+    for (const candidate of candidates) {
+      options.warn?.(
+        `Legacy graph-only target state for ${options.adapter} at ${candidate.graphLockPath} has no correlated install manifest; runtime identity and ownership cannot be proven. Preserving it outside the recovered stable state.`
+      );
+    }
+    return {};
+  }
   if (candidates.length > 1) {
     throw new Error(`Ambiguous legacy target state for ${options.adapter}: multiple graph-only candidates were found.`);
   }
@@ -8563,34 +8576,28 @@ async function discoverLegacyStateCandidates(options) {
     const fingerprint = name.slice(0, -suffix.length);
     if (!/^[a-f0-9]{64}$/u.test(fingerprint)) continue;
     const graphLockPath = join33(directory, name);
-    let graphLock;
     try {
+      let graphLock;
       graphLock = await readGraphLock(graphLockPath);
-    } catch (error) {
-      throw new Error(
-        `Legacy graph lock at ${graphLockPath} is invalid or unsupported: ` + (error instanceof Error ? error.message : String(error))
-      );
-    }
-    if (graphLock.canonical.targetFingerprint !== fingerprint) {
-      throw new Error(
-        `Legacy graph lock fingerprint does not match its filename at ${graphLockPath}.`
-      );
-    }
-    if (options.transport.kind === "ssh") {
-      throw new Error(
-        `Legacy SSH target state at ${graphLockPath} does not record its original endpoint; Agentwheel cannot prove endpoint identity, so the graph lock was preserved.`
-      );
-    }
-    const graphLockDigest = digestGraphLock(graphLock);
-    const candidateStateKey = stateKeyFor(options.adapter, {
-      installationType: options.installationType,
-      stateKey: options.explicitStateKey,
-      targetFingerprint: fingerprint,
-      fleetId: options.fleetId
-    });
-    let manifest;
-    let sourceLock;
-    try {
+      if (graphLock.canonical.targetFingerprint !== fingerprint) {
+        throw new Error(
+          `Legacy graph lock fingerprint does not match its filename at ${graphLockPath}.`
+        );
+      }
+      if (options.transport.kind === "ssh") {
+        throw new Error(
+          `Legacy SSH target state at ${graphLockPath} does not record its original endpoint; Agentwheel cannot prove endpoint identity, so the graph lock was preserved.`
+        );
+      }
+      const graphLockDigest = digestGraphLock(graphLock);
+      const candidateStateKey = stateKeyFor(options.adapter, {
+        installationType: options.installationType,
+        stateKey: options.explicitStateKey,
+        targetFingerprint: fingerprint,
+        fleetId: options.fleetId
+      });
+      let manifest;
+      let sourceLock;
       manifest = await readInstallManifest(options.installRoot, options.adapter, options.transport, {
         installationType: options.installationType,
         stateKey: candidateStateKey
@@ -8599,32 +8606,32 @@ async function discoverLegacyStateCandidates(options) {
         installationType: options.installationType,
         stateKey: candidateStateKey
       });
-    } catch (error) {
-      throw new Error(
-        `Legacy target state for ${graphLockPath} is invalid: ` + (error instanceof Error ? error.message : String(error))
-      );
-    }
-    if (!manifest) {
-      if (sourceLock) {
-        throw new Error(`Legacy source lock for ${graphLockPath} has no correlated install manifest.`);
+      if (!manifest) {
+        if (sourceLock) {
+          throw new Error(`Legacy source lock for ${graphLockPath} has no correlated install manifest.`);
+        }
+        candidates.push({ stateKey: candidateStateKey, graphLockPath, graphLockDigest, graphLock });
+        continue;
       }
-      candidates.push({ stateKey: candidateStateKey, graphLockPath, graphLockDigest, graphLock });
-      continue;
+      const validated = validateLegacyManifestCandidate(manifest, {
+        ...options,
+        candidateStateKey,
+        graphLockDigest,
+        graphLockPath
+      });
+      candidates.push({
+        stateKey: candidateStateKey,
+        graphLockPath,
+        graphLockDigest,
+        graphLock,
+        manifest: validated,
+        sourceLock
+      });
+    } catch (error) {
+      const message = `Legacy target state for ${graphLockPath} is invalid: ` + (error instanceof Error ? error.message : String(error));
+      if (!options.recoverLegacyState) throw new Error(message);
+      options.warn?.(`${message} Preserving it outside the recovered stable state.`);
     }
-    const validated = validateLegacyManifestCandidate(manifest, {
-      ...options,
-      candidateStateKey,
-      graphLockDigest,
-      graphLockPath
-    });
-    candidates.push({
-      stateKey: candidateStateKey,
-      graphLockPath,
-      graphLockDigest,
-      graphLock,
-      manifest: validated,
-      sourceLock
-    });
   }
   return candidates;
 }
@@ -13703,10 +13710,10 @@ program.command("scan").description("scan a package source for validation findin
     await releaseGitSnapshotLease(resolved.cacheLeasePath);
   }
 });
-program.command("plan").description("preview what install would reconcile without writing").argument("[name-or-source]", "configured package name/source or package source to preview").option("--driver <driver>", "source driver").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("--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 agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--profile <name>", "workspace runtime profile").option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).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("--override <source-or-package::type/name>", "for source previews, allow the source to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--dry-run", "accepted for symmetry; plan never writes", false).option("--format <fmt>", "output format: human|json|mermaid|html", "human").option("--json", "print the resolved plan as JSON", false).option("--force-drift", "replace drifted managed artifacts during install planning", 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("--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 (source, options) => {
+program.command("plan").description("preview what install would reconcile without writing").argument("[name-or-source]", "configured package name/source or package source to preview").option("--driver <driver>", "source driver").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("--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 agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--profile <name>", "workspace runtime profile").option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).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("--override <source-or-package::type/name>", "for source previews, allow the source to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--dry-run", "accepted for symmetry; plan never writes", false).option("--format <fmt>", "output format: human|json|mermaid|html", "human").option("--json", "print the resolved plan as JSON", false).option("--force-drift", "replace drifted managed artifacts during install planning", 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("--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 (source, options) => {
   await runInstallCommand(source, { ...options, dryRun: true }, { apply: false });
 });
-program.command("install").description("install configured packages into runtime targets").argument("[name-or-source]", "configured package name/source or package source to add and install").option("--driver <driver>", "source driver").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("--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 agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).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("--override <source-or-package::type/name>", "when adding a source, allow it to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plan without writing", false).option("--format <fmt>", "output format: human|json|mermaid|html", "human").option("--json", "print the resolved plan as JSON", 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("--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, []).addHelpText("after", "\nScoped install never removes files owned only by other configured packages; run a full install to reconcile those removals.\n").action(async (source, options) => {
+program.command("install").description("install configured packages into runtime targets").argument("[name-or-source]", "configured package name/source or package source to add and install").option("--driver <driver>", "source driver").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("--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 agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).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("--override <source-or-package::type/name>", "when adding a source, allow it to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--profile <name>", "workspace runtime profile").option("--dry-run", "show plan without writing", false).option("--format <fmt>", "output format: human|json|mermaid|html", "human").option("--json", "print the resolved plan as JSON", 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("--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, []).addHelpText("after", "\nScoped install never removes files owned only by other configured packages; run a full install to reconcile those removals.\n").action(async (source, options) => {
   await runInstallCommand(source, options, { apply: !options.dryRun });
 });
 program.command("serve").description("serve a read-only live dashboard for the resolved install plan").argument("[name-or-source]", "configured package name/source or package source to preview").option("--driver <driver>", "source driver").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("--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 agent from merged config").option("--all", "run for every configured agent", false).option("--all-detected", "run for every runtime directory detected in the target root", false).option("--profile <name>", "workspace runtime profile").option("--mode <mode>", "pinned or tracking").option("--select <type/name>", "select an artifact by type/name (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "select a skill by name (repeatable or comma-separated)", collectSkillOption, []).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("--override <source-or-package::type/name>", "for source previews, allow the source to replace a colliding artifact (repeatable)", collectOverrideOption, []).option("--force-drift", "replace drifted managed artifacts during install planning", 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("--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, []).option("--bind <addr>", "interface to bind", "127.0.0.1").option("--port <n>", "TCP port (0 selects an ephemeral port)", "8765").option("--interval <seconds>", "background re-render cadence in seconds", "60").option("--once", "render once and skip the background re-render loop", false).action(async (source, options) => {
@@ -14907,7 +14914,8 @@ async function buildGraphPlansForTarget(target, source, options, behavior) {
     }
     const priorGroupState = await resolveCliTargetState(group.target, {
       ...targetOptions,
-      installationType: group.installationType
+      installationType: group.installationType,
+      recoverLegacyState: targetOptions.recoverLegacyState
     });
     const previousGroupLock = priorGroupState.graphLock;
     const dependencyUpdateRootNames = /* @__PURE__ */ new Set();
@@ -15016,7 +15024,8 @@ async function buildGraphPlansForTarget(target, source, options, behavior) {
       deferForeignStateCheck: targetOptions.deferForeignStateCheck === true || targetOptions.focusedArtifact !== void 0,
       replaceConflict: targetOptions.replaceConflict,
       retireExactMcp: targetOptions.retireExactMcp,
-      expectedFromWorkspaceOwner: targetOptions.expectedFromWorkspaceOwner
+      expectedFromWorkspaceOwner: targetOptions.expectedFromWorkspaceOwner,
+      recoverLegacyState: targetOptions.recoverLegacyState
     });
     if ((behavior.mode === "install" || behavior.mode === "update") && scopedRootId) {
       const manifest = result.previousManifest;
@@ -15842,7 +15851,9 @@ async function resolveCliTargetState(target, options) {
     graphLockPath: stableGraphLockPath,
     stableManifest,
     stableLock,
-    transport
+    transport,
+    recoverLegacyState: options.recoverLegacyState,
+    warn: options.warn
   });
   return {
     adapter,

package/dist/{transaction-4ERCJXG7.js → transaction-4KBNHDQX.js}

@@ -18,8 +18,8 @@ import {
   removeApplyJournal,
   rollbackCompletedOperations,
   writeApplyJournal
-} from "./chunk-J7DKPDS7.js";
-import "./chunk-7VPI5J5Y.js";
+} from "./chunk-FP26KSBM.js";
+import "./chunk-GE7F76AC.js";
 export {
   abortApplyJournal,
   acquireApplyLock,

package/openpack.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwheel",
-  "version": "0.20.10",
+  "version": "0.20.12",
   "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.10"
+  version: "0.20.12"
 ---
 
 # agentwheel
@@ -618,3 +618,17 @@ nothing else is stale. If it differs, regenerate only the affected graph locks (
 leave them uncommitted: lock commits belong to the approved install. `update --dependency` cannot
 recompute an edge whose root node id changed (e.g. after renaming the root package's artifacts);
 regenerate the locks instead.
+
+If target-state discovery rejects an invalid historical graph-lock/manifest pair, first write and
+review `agentwheel ownership recovery-plan`. For a complete local report, preview a stable-state
+recovery with the exact Fleet target:
+
+```bash
+agentwheel plan --fleet <fleet-id> --agent <agent> \
+  --recover-legacy-state --force-conflict --replace-conflict
+```
+
+`--recover-legacy-state` preserves the invalid historical files and only bypasses their use as the
+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.

package/skills/agentwheel-discovery/SKILL.md

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