agentwheel 0.20.9 → 0.20.11

package/dist/index.js

@@ -3,6 +3,7 @@ import {
   MergeAdoptionMismatchError,
   applyCombinedInstallPlan,
   assertExactMergeContribution,
+  assertMergedSourceContribution,
   assertOperationContained,
   assertSafeInstallName,
   canonicalGraphLockJson,
@@ -36,7 +37,7 @@ import {
   uninstall,
   withManifestRevision,
   writeInstallManifest
-} from "./chunk-E7Z2YB2C.js";
+} from "./chunk-A44XYLUT.js";
 import {
   CURRENT_WORKSPACE_SCHEMA_VERSION,
   GovernedMutation,
@@ -97,10 +98,10 @@ import {
   workspaceSelectionImportSchema,
   writeApplyJournal,
   writeWorkspaceConfig
-} from "./chunk-SHPNLNBR.js";
+} from "./chunk-FP26KSBM.js";
 import {
   inferSourceDriverName
-} from "./chunk-EMDIG24I.js";
+} from "./chunk-U2GRG4UI.js";
 import {
   hashPath,
   isAlreadyExists,
@@ -109,14 +110,14 @@ import {
   pathExists,
   withFilesystemLock,
   writeJsonAtomic
-} from "./chunk-7VPI5J5Y.js";
+} from "./chunk-GE7F76AC.js";
 
 // src/cli/index.ts
-import { createHash as createHash14 } from "crypto";
+import { createHash as createHash15 } from "crypto";
 import { existsSync } from "fs";
-import { mkdir as mkdir16, rm as rm10, writeFile as writeFile13 } from "fs/promises";
-import { homedir as homedir12 } from "os";
-import { dirname as dirname22, join as join45, resolve as resolve25 } from "path";
+import { mkdir as mkdir16, mkdtemp as mkdtemp4, realpath as realpath2, rm as rm10, writeFile as writeFile13 } from "fs/promises";
+import { homedir as homedir12, tmpdir as tmpdir5 } from "os";
+import { basename as basename21, dirname as dirname23, isAbsolute as isAbsolute4, join as join46, relative as relative10, resolve as resolve26 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { Command } from "commander";
 
@@ -3112,14 +3113,14 @@ async function writeMermaidAsset(response) {
     "content-type": "application/javascript; charset=utf-8",
     "cache-control": "public, max-age=3600"
   });
-  await new Promise((resolve26) => {
+  await new Promise((resolve27) => {
     const stream = createReadStream(assetPath);
     stream.on("error", () => {
       if (!response.headersSent) writeText(response, 404, "Mermaid asset unavailable.\n");
       else response.destroy();
-      resolve26();
+      resolve27();
     });
-    stream.on("end", resolve26);
+    stream.on("end", resolve27);
     stream.pipe(response);
   });
 }
@@ -3146,14 +3147,14 @@ function escapeHtml2(value) {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
 }
 function listen(server, port, bind) {
-  return new Promise((resolve26, reject) => {
+  return new Promise((resolve27, reject) => {
     const onError = (error) => {
       server.off("listening", onListening);
       reject(error);
     };
     const onListening = () => {
       server.off("error", onError);
-      resolve26();
+      resolve27();
     };
     server.once("error", onError);
     server.once("listening", onListening);
@@ -3161,7 +3162,7 @@ function listen(server, port, bind) {
   });
 }
 function waitForShutdown(server, beforeClose) {
-  return new Promise((resolve26) => {
+  return new Promise((resolve27) => {
     let closing = false;
     const shutdown = () => {
       if (closing) return;
@@ -3169,7 +3170,7 @@ function waitForShutdown(server, beforeClose) {
       process.off("SIGINT", shutdown);
       process.off("SIGTERM", shutdown);
       beforeClose();
-      server.close(() => resolve26());
+      server.close(() => resolve27());
     };
     process.once("SIGINT", shutdown);
     process.once("SIGTERM", shutdown);
@@ -3179,7 +3180,7 @@ function waitForShutdown(server, beforeClose) {
       process.off("SIGINT", shutdown);
       process.off("SIGTERM", shutdown);
       beforeClose();
-      resolve26();
+      resolve27();
     });
   });
 }
@@ -3732,7 +3733,7 @@ async function fetchClawHubPackage(fetchImpl, packageName) {
   throw new Error(`ClawHub lookup failed for ${packageName}`);
 }
 async function delay(ms) {
-  await new Promise((resolve26) => setTimeout(resolve26, ms));
+  await new Promise((resolve27) => setTimeout(resolve27, ms));
 }
 function parseClawHubSource(source) {
   if (!source.startsWith(sourcePrefix)) {
@@ -3909,7 +3910,7 @@ async function withGitCacheMaintenanceLock(cacheRoot, timeoutMs, fn) {
       if (Date.now() - started > timeoutMs) {
         throw new Error(`Timed out waiting for git cache maintenance lock at ${lockPath}`);
       }
-      await new Promise((resolve26) => setTimeout(resolve26, 50));
+      await new Promise((resolve27) => setTimeout(resolve27, 50));
     }
   }
   try {
@@ -5788,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) {
@@ -6775,8 +6776,8 @@ function verifyIntegrity(integrity, sourceHash, label) {
 async function withCachePathLock(path, fn) {
   const previous = cacheLocks.get(path) ?? Promise.resolve();
   let release = () => void 0;
-  const current = previous.then(() => new Promise((resolve26) => {
-    release = resolve26;
+  const current = previous.then(() => new Promise((resolve27) => {
+    release = resolve27;
   }));
   cacheLocks.set(path, current);
   await previous;
@@ -8141,6 +8142,9 @@ async function createGraphSourcePlan(options) {
   if (options.roots.length === 0) {
     throw new Error("At least one source is required for a graph plan.");
   }
+  if (options.freshGraphOnly && options.readOnly !== true) {
+    throw new Error("Fresh graph recovery is read-only and cannot be used for install planning.");
+  }
   const workspaceRoot = options.workspaceRoot ?? options.targetRoot;
   const transport = options.transport ?? localTransport;
   const warnings = [];
@@ -8229,16 +8233,18 @@ async function createGraphSourcePlan(options) {
       graphLockPath,
       stableManifest,
       stableLock: stableLock2,
-      transport
+      transport,
+      recoverLegacyState: options.recoverLegacyState,
+      warn
     });
     return { priorState: priorState2, stableLock: stableLock2, stableSourceLock: stableSourceLock2 };
   };
-  const { priorState, stableLock, stableSourceLock } = await readPriorState();
+  const { priorState, stableLock, stableSourceLock } = options.freshGraphOnly ? { priorState: {}, stableLock: void 0, stableSourceLock: void 0 } : await readPriorState();
   const previousLock = priorState.graphLock;
-  const registryClient = new RegistryClient({ workspaceRoot, offline: lockMode, offlineLabel: lockLabel, warn });
+  const registryClient = new RegistryClient({ workspaceRoot, cachePath: options.registryCachePath, offline: lockMode, offlineLabel: lockLabel, warn });
   const graph = await resolveDependencyGraph(options.roots, {
     workspaceRoot,
-    cacheRoot: join33(workspaceRoot, ".agentwheel", "cache"),
+    cacheRoot: options.cacheRoot ?? join33(workspaceRoot, ".agentwheel", "cache"),
     registryClient,
     noDeps: options.noDeps,
     includeSuggestions: options.includeSuggestions,
@@ -8491,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) {
@@ -8559,34 +8568,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
@@ -8595,32 +8598,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;
 }
@@ -10149,10 +10152,262 @@ function canonicalJson(value) {
   return `{${Object.keys(record).filter((key) => record[key] !== void 0).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
 }
 
+// src/lifecycle/legacy-recovery-plan.ts
+import { createHash as createHash10 } from "crypto";
+import { readdir as readdir10 } from "fs/promises";
+import { basename as basename20, dirname as dirname21, join as join39, posix as posix3, relative as relative8, resolve as resolve22 } from "path";
+async function inventoryHistoricalLocks(fleetRoot) {
+  const root = join39(fleetRoot, ".agentwheel", "locks");
+  const found = [];
+  async function visit(dir) {
+    for (const entry of await readdir10(dir, { withFileTypes: true }).catch((error) => {
+      if (error.code === "ENOENT") return [];
+      throw error;
+    })) {
+      const path = join39(dir, entry.name);
+      if (entry.isDirectory()) await visit(path);
+      else if (entry.isFile() && entry.name.endsWith(".graph-lock.json")) {
+        const lock = await readGraphLock(path);
+        found.push({ path, digest: sha2564(canonicalGraphLockJson(lock)), lock });
+      }
+    }
+  }
+  await visit(root);
+  return found.sort((a, b) => a.path.localeCompare(b.path));
+}
+async function planLegacyRecovery(input) {
+  const { graphPlan, installRoot, targetKey: targetKey2, adapter, installationType, historicalLocks, transport } = input;
+  assertCompleteGraphPlan(graphPlan);
+  const binding = {
+    targetLockDir: dirname21(graphPlan.graphLockPath),
+    stableLockPath: graphPlan.graphLockPath,
+    stableStateKey: graphPlan.plan.stateKey,
+    currentFingerprint: graphPlan.targetFingerprint,
+    expectedOwner: workspaceOwnerForRoot(input.workspaceRoot, input.fleetId),
+    installRoot,
+    adapter,
+    installationType,
+    fleetId: input.fleetId,
+    explicitStateKey: input.explicitStateKey,
+    transportKind: transport.kind
+  };
+  const manifests = await listInstallManifests(installRoot, adapter, transport);
+  const paths = /* @__PURE__ */ new Set();
+  const desired = /* @__PURE__ */ new Map();
+  const nodeHashes = new Map(graphPlan.bundle.graphLock.canonical.nodes.map((node) => [node.id, node.sourceHash]));
+  for (const op of graphPlan.plan.operations) {
+    if (!op.desiredHash || op.action === "remove" || op.action === "keep") continue;
+    const path = relative8(installRoot, op.destPath);
+    if (path.startsWith("..") || path === "") throw new Error(`Planner destination escapes target: ${op.destPath}`);
+    paths.add(path);
+    const items = desired.get(path) ?? [];
+    items.push(op);
+    desired.set(path, items);
+  }
+  for (const item of manifests) for (const entry of item.manifest.entries) paths.add(entry.path);
+  const resolutionWarnings = graphPlan.warnings.filter((warning) => !/^skip (?:artifact|dependency) .+ \((?:selected but )?not targeted: runtimes=\[[^\]]+\]\)$/.test(warning));
+  const complete = resolutionWarnings.length === 0;
+  const output = [];
+  for (const path of [...paths].sort()) {
+    const allClaims = manifests.flatMap((item) => item.manifest.entries.filter((entry) => entry.path === path).map((entry) => claimFor(item, entry, historicalLocks, binding)));
+    const claims = allClaims.filter((claim) => claim.scope !== "foreign");
+    const foreignClaims = allClaims.filter((claim) => claim.scope === "foreign");
+    const current = desired.get(path) ?? [];
+    const currentHashes = [...new Set(current.map((item) => item.desiredHash))];
+    const currentSourceHashes = [...new Set(current.map((item) => item.graphNodeId ? nodeHashes.get(item.graphNodeId) : void 0).filter((value) => Boolean(value)))].sort();
+    const currentNodeIds = [...new Set(current.map((item) => item.graphNodeId).filter((value) => Boolean(value)))].sort();
+    const currentSelectors = [...new Set(current.map((item) => item.logicalSelector).filter((value) => Boolean(value)))].sort();
+    const currentOwners = [...new Set(current.flatMap((item) => item.owners ?? []))].sort();
+    const livePath = resolve22(installRoot, path);
+    if (relative8(installRoot, livePath).startsWith("..")) throw new Error(`Manifest path escapes target: ${path}`);
+    const liveHash = await transport.pathExists(livePath) ? await transport.hashPath(livePath) : null;
+    const reasons = [];
+    const currentResults = await Promise.all(current.map((op) => verifyCurrentOperation(op, liveHash, transport)));
+    const currentGraphStatus = current.length === 0 ? "absent" : currentResults.every((result) => result === "exact-match") ? "exact-match" : currentResults.some((result) => result === "unverifiable") ? "unverifiable" : "mismatch";
+    if (currentHashes.length > 1 && current.some((op) => !op.mergeStrategy && op.mode !== "managed-block")) {
+      reasons.push("current graph has divergent hashes for the destination");
+    }
+    if (currentGraphStatus === "mismatch") reasons.push("live contribution differs from current source");
+    if (currentGraphStatus === "unverifiable") reasons.push("current contribution could not be verified");
+    if (current.some((op) => op.action === "conflict" || op.action === "drift")) reasons.push("install planner has a blocking operation");
+    if (!complete) reasons.push("current source graph has resolution warnings; completeness unproven");
+    if (claims.some((claim) => claim.scope === "unbound" || claim.evidence.length)) reasons.push("historical provenance unresolved");
+    if (foreignClaims.length) reasons.push("foreign manifest claim conflicts with destination");
+    if (new Set(claims.map((claim) => `${claim.owner}:${claim.hash}:${claim.sourceHash}:${claim.graphLockDigest ?? ""}`)).size > 1) {
+      reasons.push("competing same-target claims diverge");
+    }
+    if (current.length === 0 && claims.length === 0) reasons.push("no same-target historical claim");
+    if (current.length === 0) {
+      for (const claim of claims) {
+        if (claim.scope !== "same-target") continue;
+        const item = manifests.find((manifest) => manifest.path === claim.manifestPath);
+        const entry = item.manifest.entries.find((candidate) => candidate.path === path && candidate.sourceHash === claim.sourceHash);
+        if (!await verifyHistoricalEntry(entry, livePath, liveHash, transport)) {
+          reasons.push("live contribution differs from same-target historical claim");
+          break;
+        }
+      }
+    }
+    const category = reasons.length ? "unresolved" : currentGraphStatus === "exact-match" ? "current-graph-exact-match" : "retirement-candidate";
+    output.push({
+      path,
+      category,
+      reasons,
+      currentHash: currentHashes.length === 1 ? currentHashes[0] : null,
+      currentHashes: currentHashes.sort(),
+      currentSourceHashes,
+      currentNodeIds,
+      currentSelectors,
+      currentOwners,
+      currentGraphStatus,
+      liveHash,
+      claims,
+      foreignClaims
+    });
+  }
+  const counts = { "current-graph-exact-match": 0, "retirement-candidate": 0, unresolved: 0 };
+  const currentGraphCounts = { "exact-match": 0, mismatch: 0, absent: 0, unverifiable: 0 };
+  for (const path of output) counts[path.category]++;
+  for (const path of output) currentGraphCounts[path.currentGraphStatus]++;
+  return {
+    targetRoot: installRoot,
+    targetKey: targetKey2,
+    adapter,
+    installationType,
+    currentGraphLockDigest: graphPlan.graphLockDigest,
+    roots: graphPlan.graph.roots.map((root) => ({ rootId: root.rootId, source: root.source, graphNodeId: root.graphNodeId, selected: root.selected })),
+    resolutionWarnings,
+    complete,
+    paths: output,
+    counts,
+    currentGraphCounts
+  };
+}
+function claimFor(item, entry, locks, binding) {
+  const digest2 = "graphLockDigest" in entry ? entry.graphLockDigest : void 0;
+  const nodeId = "graphNodeId" in entry ? entry.graphNodeId : void 0;
+  const selector = "logicalSelector" in entry ? entry.logicalSelector : void 0;
+  const matches = locks.filter((candidate) => candidate.digest === digest2);
+  const evidence = [];
+  const owner = "workspaceOwner" in entry ? entry.workspaceOwner : legacyUnownedWorkspaceOwner;
+  const sameRoot = binding.transportKind === "ssh" ? posix3.normalize(item.manifest.targetRoot) === posix3.normalize(binding.installRoot) : resolve22(item.manifest.targetRoot) === resolve22(binding.installRoot);
+  const inTargetDir = matches.filter((candidate) => resolve22(dirname21(candidate.path)) === resolve22(binding.targetLockDir));
+  const boundLocks = inTargetDir.filter((candidate) => lockBindsState(candidate, item, binding));
+  if (owner !== binding.expectedOwner) evidence.push("workspace owner differs from selected Fleet target");
+  if (item.manifest.version !== 2 || item.manifest.installationType !== binding.installationType) evidence.push("installation type differs or manifest is legacy v1");
+  if (!sameRoot) evidence.push("manifest target root differs from selected Fleet target");
+  if (item.manifest.version === 2 && (item.manifest.stateKey !== item.stateKey || item.manifest.adapter !== binding.adapter)) {
+    evidence.push("manifest state key or adapter differs from filename");
+  }
+  if (!digest2) evidence.push("historical graph-lock digest missing");
+  else if (matches.length === 0) evidence.push("historical graph-lock digest has no matching lock");
+  if (matches.length && !inTargetDir.length) evidence.push("claim belongs to another Fleet target graph");
+  if (inTargetDir.length && !boundLocks.length) evidence.push("graph-lock fingerprint, filename, or state key does not bind claim");
+  if (boundLocks.length && !boundLocks.some((candidate) => candidate.lock.canonical.artifacts.some((artifact) => artifact.graphNodeId === nodeId && artifact.logicalSelector === selector))) {
+    evidence.push("historical graph-lock selector/node does not cover claim");
+  } else if (boundLocks.length && !boundLocks.some((candidate) => candidate.lock.canonical.artifacts.some((artifact) => artifact.graphNodeId === nodeId && artifact.logicalSelector === selector && artifact.hash === entry.sourceHash))) {
+    evidence.push("historical graph-lock artifact hash differs from manifest source hash");
+  }
+  const foreign = owner !== binding.expectedOwner || !sameRoot || item.manifest.version !== 2 || item.manifest.installationType !== binding.installationType || item.manifest.version === 2 && (item.manifest.stateKey !== item.stateKey || item.manifest.adapter !== binding.adapter) || matches.length > 0 && inTargetDir.length === 0;
+  const scope = foreign ? "foreign" : boundLocks.length && evidence.length === 0 ? "same-target" : "unbound";
+  return {
+    scope,
+    manifestPath: item.path,
+    stateKey: item.stateKey,
+    manifestStateKey: item.manifest.version === 2 ? item.manifest.stateKey : void 0,
+    installationType: item.manifest.version === 2 ? item.manifest.installationType : void 0,
+    targetRoot: item.manifest.targetRoot,
+    owner,
+    hash: entry.hash,
+    sourceHash: entry.sourceHash,
+    graphLockDigest: digest2,
+    graphNodeId: nodeId,
+    logicalSelector: selector,
+    owners: "owners" in entry ? entry.owners : [entry.packageName ?? "legacy"],
+    lockPaths: matches.map((candidate) => candidate.path),
+    evidence
+  };
+}
+function lockBindsState(candidate, manifest, binding) {
+  const name = basename20(candidate.path);
+  if (!name.endsWith(".graph-lock.json")) return false;
+  const fingerprint = name.slice(0, -".graph-lock.json".length);
+  if (!/^[a-f0-9]{64}$/u.test(fingerprint)) return false;
+  const stable = resolve22(candidate.path) === resolve22(binding.stableLockPath);
+  if (stable) {
+    return manifest.stateKey === binding.stableStateKey && candidate.lock.canonical.targetFingerprint === binding.currentFingerprint;
+  }
+  return candidate.lock.canonical.targetFingerprint === fingerprint && manifest.stateKey === stateKeyFor(binding.adapter, {
+    installationType: binding.installationType,
+    stateKey: binding.explicitStateKey,
+    targetFingerprint: fingerprint,
+    fleetId: binding.fleetId
+  });
+}
+async function verifyCurrentOperation(op, liveHash, transport) {
+  if (liveHash === null || !op.desiredHash) return "mismatch";
+  if (op.semanticPlugin || op.programmaticOperation) return "unverifiable";
+  if (op.mode === "managed-block") {
+    const selector = managedInstructionSelector(op.logicalSelector, op.artifactType, op.artifactName);
+    const state = await readManagedInstructionBlockState(op.destPath, selector, transport);
+    return state.hasBlock && !state.drifted && state.hash === op.desiredHash ? "exact-match" : "mismatch";
+  }
+  if (op.mergeStrategy) {
+    if (!op.sourcePath) return "unverifiable";
+    try {
+      await assertMergedSourceContribution(op.sourcePath, op.mergeStrategy, await transport.readFile(op.destPath));
+      return "exact-match";
+    } catch {
+      return "mismatch";
+    }
+  }
+  return liveHash === op.desiredHash ? "exact-match" : "mismatch";
+}
+async function verifyHistoricalEntry(entry, livePath, liveHash, transport) {
+  if (liveHash === null || entry.semanticPlugin) return false;
+  if (entry.mode === "managed-block") {
+    const selector = managedInstructionSelector(
+      "logicalSelector" in entry ? entry.logicalSelector : void 0,
+      entry.artifactType,
+      entry.artifactName
+    );
+    const state = await readManagedInstructionBlockState(livePath, selector, transport);
+    return state.hasBlock && !state.drifted && state.hash === entry.hash;
+  }
+  if (entry.mergeStrategy) {
+    if (!hasMergeRemovalContent(entry.mergeRemoval)) return false;
+    try {
+      assertExactMergeContribution(entry.mergeRemoval, entry.mergeStrategy, await transport.readFile(livePath));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return entry.hash === liveHash;
+}
+function assertCompleteGraphPlan(plan) {
+  const sourceNodes = plan.graph.nodes.filter((node) => node.selected.length > 0);
+  const lockedNodes = new Map(plan.bundle.graphLock.canonical.nodes.map((node) => [node.id, node]));
+  for (const node of sourceNodes) {
+    const locked = lockedNodes.get(node.id);
+    if (!locked || locked.sourceHash !== node.sourceHash || node.selected.some((selector) => !locked.selected.includes(selector))) {
+      throw new Error(`Current source graph omitted selected node or dependency: ${node.id}`);
+    }
+  }
+  for (const edge of plan.graph.edges) {
+    if (!plan.bundle.graphLock.canonical.edges.some((locked) => locked.from === edge.from && locked.to === edge.to && locked.alias === edge.alias)) {
+      throw new Error(`Current source graph omitted dependency edge: ${edge.from} -> ${edge.to}`);
+    }
+  }
+}
+function sha2564(value) {
+  return createHash10("sha256").update(value).digest("hex");
+}
+
 // src/version/policy.ts
 import { execFile as execFile3 } from "child_process";
 import { readFile as readFile23 } from "fs/promises";
-import { join as join39, resolve as resolve22 } from "path";
+import { join as join40, resolve as resolve23 } from "path";
 import { promisify as promisify3 } from "util";
 import { parse as parseJsonc } from "jsonc-parser";
 import { z as z5 } from "zod";
@@ -10246,7 +10501,7 @@ async function discoverVersionsFromSource(pkg, workspaceRoot) {
     if (tagged.length > 0) return tagged;
   }
   if (driverName === "local") {
-    const root = resolve22(workspaceRoot, pkg.source);
+    const root = resolve23(workspaceRoot, pkg.source);
     const manifest2 = await readPackageManifest(root);
     const current = manifest2 ? [{ version: manifest2.version, ref: pkg.requestedRef ?? root }] : [];
     try {
@@ -10261,7 +10516,7 @@ async function discoverVersionsFromSource(pkg, workspaceRoot) {
   }
   const driver = getSourceDriver(driverName);
   const resolved = await driver.resolve(pkg.source, {
-    cacheRoot: join39(workspaceRoot, ".agentwheel", "cache"),
+    cacheRoot: join40(workspaceRoot, ".agentwheel", "cache"),
     mode: "tracking",
     ref: pkg.requestedRef
   });
@@ -10355,7 +10610,7 @@ function gitUrlFromSource(source) {
   throw new Error(`Version discovery does not support Git source: ${source}`);
 }
 function versionCachePath(workspaceRoot) {
-  return join39(workspaceRoot, ".agentwheel", "cache", "version-index.json");
+  return join40(workspaceRoot, ".agentwheel", "cache", "version-index.json");
 }
 async function readVersionCache(path) {
   if (!await pathExists(path)) return { schemaVersion: 1, sources: {} };
@@ -10369,7 +10624,7 @@ async function readVersionCache(path) {
 // src/profile/members.ts
 import { execFile as execFile4 } from "child_process";
 import { readFile as readFile24 } from "fs/promises";
-import { join as join40, resolve as resolve23 } from "path";
+import { join as join41, resolve as resolve24 } from "path";
 import { promisify as promisify4 } from "util";
 import { z as z7 } from "zod";
 
@@ -10544,7 +10799,7 @@ async function invokeMemberStatus(member, parentWorkspace, chain, options, cliEn
   let stderr = "";
   try {
     if (member.transport === "local") {
-      const workspace = resolve23(parentWorkspace, member.workspace);
+      const workspace = resolve24(parentWorkspace, member.workspace);
       const result = await execFileAsync4(process.execPath, [cliEntry, ...args], {
         cwd: workspace,
         env: env2,
@@ -10590,7 +10845,7 @@ async function runMemberAgentwheel(member, parentWorkspace, args, chain) {
         process.execPath,
         [process.argv[1], ...memberCommandArgs(member, args)],
         {
-          cwd: resolve23(parentWorkspace, member.workspace),
+          cwd: resolve24(parentWorkspace, member.workspace),
           env: env2,
           maxBuffer: 20 * 1024 * 1024
         }
@@ -10670,7 +10925,7 @@ function memberFailure(member, health, error) {
   };
 }
 function memberCachePath(workspaceRoot, profileName, memberId) {
-  return join40(workspaceRoot, ".agentwheel", "cache", "member-status", profileName, `${memberId}.json`);
+  return join41(workspaceRoot, ".agentwheel", "cache", "member-status", profileName, `${memberId}.json`);
 }
 async function readMemberCache(path) {
   if (!await pathExists(path)) return void 0;
@@ -10696,7 +10951,7 @@ function assertNoCompositeCycle(workspaceRoot, profileName, chain) {
   }
 }
 function compositeKey(workspaceRoot, profileName) {
-  return `${resolve23(workspaceRoot)}#${profileName}`;
+  return `${resolve24(workspaceRoot)}#${profileName}`;
 }
 
 // src/status/repository.ts
@@ -10743,10 +10998,10 @@ function valueAfter(lines, prefix) {
 }
 
 // src/catalogue/client.ts
-import { createHash as createHash10 } from "crypto";
+import { createHash as createHash11 } from "crypto";
 import { readFile as readFile25, rm as rm8 } from "fs/promises";
 import { homedir as homedir9 } from "os";
-import { join as join41 } from "path";
+import { join as join42 } from "path";
 
 // src/model/catalogue.ts
 import { z as z8 } from "zod";
@@ -11018,18 +11273,18 @@ var CatalogueClient = class {
     }
     return {
       value: schema.parse(value),
-      digest: createHash10("sha256").update(bytes).digest("hex")
+      digest: createHash11("sha256").update(bytes).digest("hex")
     };
   }
 };
 function defaultCatalogueCachePath() {
-  return join41(homedir9(), ".agentwheel", "catalogue-cache.json");
+  return join42(homedir9(), ".agentwheel", "catalogue-cache.json");
 }
 function sameSources2(a, b) {
   return a.length === b.length && a.every((source, index) => source === b[index]);
 }
 function catalogueContentHash(enriched, vercel) {
-  return createHash10("sha256").update(JSON.stringify({ enriched, vercel })).digest("hex");
+  return createHash11("sha256").update(JSON.stringify({ enriched, vercel })).digest("hex");
 }
 
 // src/search/index.ts
@@ -11391,9 +11646,9 @@ function includesToken(normalizedText, token) {
 }
 
 // src/semantic/index.ts
-import { createHash as createHash11 } from "crypto";
+import { createHash as createHash12 } from "crypto";
 import { homedir as homedir10 } from "os";
-import { join as join42 } from "path";
+import { join as join43 } from "path";
 import { env, pipeline } from "@huggingface/transformers";
 var DEFAULT_SEMANTIC_INDEX_URL = "https://raw.githubusercontent.com/NestDevLab/agentwheel-registry/main/catalogue-semantic-index/gte-v1/";
 var CONTRACT = {
@@ -11481,13 +11736,13 @@ var SemanticSearchClient = class {
     if (!response.ok) throw new Error(`Semantic index file failed (${response.status}): ${descriptor.path}`);
     const bytes = new Uint8Array(await response.arrayBuffer());
     if (bytes.byteLength !== descriptor.bytes) throw new Error(`Semantic index file size does not match: ${descriptor.path}`);
-    const digest2 = createHash11("sha256").update(bytes).digest("hex");
+    const digest2 = createHash12("sha256").update(bytes).digest("hex");
     if (digest2 !== descriptor.sha256) throw new Error(`Semantic index checksum does not match: ${descriptor.path}`);
     return bytes;
   }
 };
 async function embedQuery(query) {
-  env.cacheDir = join42(homedir10(), ".agentwheel", "semantic-models");
+  env.cacheDir = join43(homedir10(), ".agentwheel", "semantic-models");
   const extractor = await pipeline("feature-extraction", CONTRACT.model.id, {
     revision: CONTRACT.model.revision,
     dtype: CONTRACT.model.dtype,
@@ -11571,9 +11826,9 @@ function ensureTrailingSlash(value) {
 }
 
 // src/trial/skill.ts
-import { createHash as createHash12 } from "crypto";
+import { createHash as createHash13 } from "crypto";
 import { readFile as readFile26, stat as stat13 } from "fs/promises";
-import { join as join43 } from "path";
+import { join as join44 } from "path";
 import { parse as parseYaml2 } from "yaml";
 var MAX_TRIAL_SKILL_BYTES = 512 * 1024;
 async function createSkillTrial(driver, resolved, selectors) {
@@ -11585,7 +11840,7 @@ async function createSkillTrial(driver, resolved, selectors) {
     throw new Error("Skill trial requires exactly one selected skill. Use --skill <name> or --select skills/<name>.");
   }
   const artifact = skills[0];
-  const path = artifact.kind === "dir" ? join43(artifact.sourcePath, "SKILL.md") : artifact.sourcePath;
+  const path = artifact.kind === "dir" ? join44(artifact.sourcePath, "SKILL.md") : artifact.sourcePath;
   const info = await stat13(path);
   if (info.size > MAX_TRIAL_SKILL_BYTES) {
     throw new Error(`Skill trial exceeds the ${MAX_TRIAL_SKILL_BYTES / 1024} KiB content limit.`);
@@ -11601,7 +11856,7 @@ async function createSkillTrial(driver, resolved, selectors) {
     skill: {
       name: artifact.name,
       relativePath: artifact.relativePath,
-      sha256: createHash12("sha256").update(content).digest("hex"),
+      sha256: createHash13("sha256").update(content).digest("hex"),
       frontmatter,
       content
     }
@@ -11620,10 +11875,10 @@ function readSkillFrontmatter(content, artifact) {
 }
 
 // src/lifecycle/fleet-normalize.ts
-import { createHash as createHash13 } from "crypto";
-import { readFile as readFile27, readdir as readdir10, rm as rm9 } from "fs/promises";
+import { createHash as createHash14 } from "crypto";
+import { readFile as readFile27, readdir as readdir11, rm as rm9 } from "fs/promises";
 import { homedir as homedir11 } from "os";
-import { dirname as dirname21, isAbsolute as isAbsolute3, join as join44, relative as relative8, resolve as resolve24 } from "path";
+import { dirname as dirname22, isAbsolute as isAbsolute3, join as join45, relative as relative9, resolve as resolve25 } from "path";
 async function planFleetNormalization(request) {
   const normalizedRequest = normalizeRequest2(request);
   const destinationScope = await resolveWorkspaceScope({
@@ -11653,7 +11908,7 @@ async function planFleetNormalization(request) {
         `Package '${name}' has divergent declarations. Source, driver, adapter, adapter configuration, installation type, version policy, selections, aliases, overrides, and suggestions must match before normalization.`
       );
     }
-    packages.push({ name, declarationDigest: sha2564(sourceDeclaration) });
+    packages.push({ name, declarationDigest: sha2565(sourceDeclaration) });
   }
   if (!legacySelfNormalization) await assertSourceFleetPostcondition(normalizedRequest, sourceScope, candidates);
   if ((normalizedRequest.profile || normalizedRequest.agent || normalizedRequest.artifacts || normalizedRequest.orphanedOwnerRoots) && !legacySelfNormalization) {
@@ -11684,7 +11939,7 @@ async function planFleetNormalization(request) {
     packages,
     installedState
   };
-  return { ...planWithoutDigest, planDigest: sha2564(canonicalJson2(planWithoutDigest)) };
+  return { ...planWithoutDigest, planDigest: sha2565(canonicalJson2(planWithoutDigest)) };
 }
 async function applyFleetNormalization(request, hooks = {}) {
   if (!request.apply) throw new Error("Fleet normalization is dry-run by default; pass --apply with --plan-digest <digest>.");
@@ -11822,7 +12077,7 @@ async function assertNormalizationPostconditions(journal) {
   }
   for (const graphLock of journal.graphLocks) {
     const raw = await readOptionalRecord(graphLock.path);
-    const digest2 = raw ? sha2564(canonicalJson2(await readGraphLock(graphLock.path))) : null;
+    const digest2 = raw ? sha2565(canonicalJson2(await readGraphLock(graphLock.path))) : null;
     if (digest2 !== graphLock.afterDigest) {
       throw new Error(`Fleet normalization graph-lock postcheck failed: ${graphLock.path}`);
     }
@@ -11894,17 +12149,17 @@ function normalizeRequest2(request) {
     ...profile ? { profile } : {},
     ...agent ? { agent } : {},
     ...orphanedOwnerRoots ? { orphanedOwnerRoots } : {},
-    ...request.globalRoot ? { globalRoot: resolve24(request.globalRoot) } : {}
+    ...request.globalRoot ? { globalRoot: resolve25(request.globalRoot) } : {}
   };
 }
 function normalizeOrphanedOwnerRoot(value) {
   const root = value.trim();
   if (!root || !isAbsolute3(root)) throw new Error(`Invalid orphaned owner root '${value}'; expected an absolute workspace path.`);
-  return resolve24(root);
+  return resolve25(root);
 }
 async function normalizationRoots(request) {
   const destination = await showRegisteredFleet(request.destinationFleet, { globalRoot: request.globalRoot });
-  const source = request.from === "user" ? resolve24(request.globalRoot ?? homedir11()) : (await showRegisteredFleet(request.from.slice("fleet:".length), { globalRoot: request.globalRoot })).root;
+  const source = request.from === "user" ? resolve25(request.globalRoot ?? homedir11()) : (await showRegisteredFleet(request.from.slice("fleet:".length), { globalRoot: request.globalRoot })).root;
   return { source, destination: destination.root };
 }
 async function withOrderedLocks(roots, fn) {
@@ -11912,7 +12167,7 @@ async function withOrderedLocks(roots, fn) {
     if (index === roots.length) return fn();
     const root = roots[index];
     return withFilesystemLock(
-      join44(root, ".agentwheel", "fleet-normalize.lock"),
+      join45(root, ".agentwheel", "fleet-normalize.lock"),
       5e3,
       () => run(index + 1),
       "fleet normalization"
@@ -12011,10 +12266,10 @@ async function inspectInstalledState(source, destination, packageNames) {
     const destinationGraphAfter = destinationGraph?.lock ?? destinationGraphFromSource(sourceGraph.lock, destinationState.targetFingerprint);
     graphTransfers.push({
       sourceGraphLockPath: sourceGraph.path,
-      sourceGraphLockDigest: sha2564(canonicalJson2(sourceGraph.lock)),
+      sourceGraphLockDigest: sha2565(canonicalJson2(sourceGraph.lock)),
       destinationGraphLockPath: destinationState.graphLockPath,
-      destinationGraphLockDigest: destinationGraph ? sha2564(canonicalJson2(destinationGraph.lock)) : null,
-      destinationGraphLockAfterDigest: sha2564(canonicalJson2(destinationGraphAfter)),
+      destinationGraphLockDigest: destinationGraph ? sha2565(canonicalJson2(destinationGraph.lock)) : null,
+      destinationGraphLockAfterDigest: sha2565(canonicalJson2(destinationGraphAfter)),
       targetKey: sourceGraph.targetKey,
       adapter: destinationState.adapter,
       targetFingerprint: destinationState.targetFingerprint
@@ -12118,7 +12373,7 @@ async function inspectLegacySelfInstalledState(fleet, packageNames, profileName,
   let normalizedGraphCount = 0;
   for (const graph of graphCandidates) {
     const destinationState = await targetStateForGraph(fleet, graph, fleet.fleetId);
-    if (resolve24(destinationState.graphLockPath) === resolve24(graph.path)) {
+    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))) {
         assertCorrelatedGraphManifest(
@@ -12133,7 +12388,7 @@ async function inspectLegacySelfInstalledState(fleet, packageNames, profileName,
       }
     }
     const legacyState = await legacyTargetStateForGraph(fleet, graph);
-    if (resolve24(legacyState.graphLockPath) !== resolve24(graph.path)) {
+    if (resolve25(legacyState.graphLockPath) !== resolve25(graph.path)) {
       throw new Error(`Legacy graph lock target identity is stale or noncanonical: ${graph.path}`);
     }
     const legacyManifest = (await collectManifestPaths([legacyState.manifestPath]))[0];
@@ -12241,7 +12496,7 @@ async function inspectLegacySelfInstalledState(fleet, packageNames, profileName,
       )
     });
     if (!selectedArtifacts) {
-      const fullDigest = sha2564(canonicalJson2(graph.lock));
+      const fullDigest = sha2565(canonicalJson2(graph.lock));
       const existingDestinationGraph = graphCandidates.find((candidate) => candidate.path === destinationState.graphLockPath);
       if (existingDestinationGraph) assertGraphIsSubset(graph, existingDestinationGraph);
       const destinationGraph = destinationGraphFromSource(graph.lock, destinationState.targetFingerprint);
@@ -12249,8 +12504,8 @@ async function inspectLegacySelfInstalledState(fleet, packageNames, profileName,
         sourceGraphLockPath: graph.path,
         sourceGraphLockDigest: fullDigest,
         destinationGraphLockPath: destinationState.graphLockPath,
-        destinationGraphLockDigest: existingDestinationGraph ? sha2564(canonicalJson2(existingDestinationGraph.lock)) : null,
-        destinationGraphLockAfterDigest: sha2564(canonicalJson2(destinationGraph)),
+        destinationGraphLockDigest: existingDestinationGraph ? sha2565(canonicalJson2(existingDestinationGraph.lock)) : null,
+        destinationGraphLockAfterDigest: sha2565(canonicalJson2(destinationGraph)),
         targetKey: graph.targetKey,
         adapter: graph.adapter,
         targetFingerprint: destinationState.targetFingerprint
@@ -12308,7 +12563,7 @@ function targetKeysForAgent(scope, name) {
 async function runtimeRoots(scope) {
   const roots = /* @__PURE__ */ new Set([scope.root]);
   if (scope.config.packages.some((pkg) => pkg.installationType === "user") || Object.values(scope.config.agents).some((agent) => agent.installationType === "user")) {
-    roots.add(resolve24(process.env.AGENTWHEEL_TEST_HOME || process.env.HOME || homedir11()));
+    roots.add(resolve25(process.env.AGENTWHEEL_TEST_HOME || process.env.HOME || homedir11()));
   }
   for (const [name, agent] of Object.entries(scope.config.agents)) {
     if (agent.transport === "ssh") throw new Error(`Installed-state normalization cannot inspect SSH agent '${name}' locally.`);
@@ -12326,17 +12581,17 @@ async function runtimeRoots(scope) {
 async function collectManifests(roots) {
   const found = /* @__PURE__ */ new Map();
   for (const root of roots) {
-    const dir = join44(root, ".agentwheel");
+    const dir = join45(root, ".agentwheel");
     let names;
     try {
-      names = await readdir10(dir);
+      names = await readdir11(dir);
     } catch (error) {
       if (isMissing(error)) continue;
       throw error;
     }
     for (const name of names.sort((a, b) => a.localeCompare(b))) {
       if (!name.endsWith(".install-manifest.json")) continue;
-      const path = join44(dir, name);
+      const path = join45(dir, name);
       const raw = JSON.parse(await readFile27(path, "utf8"));
       const parsed = installManifestSchema.parse(raw);
       if (parsed.version !== 2) {
@@ -12345,14 +12600,14 @@ async function collectManifests(roots) {
         }
         continue;
       }
-      if (resolve24(parsed.targetRoot) !== resolve24(root)) {
+      if (resolve25(parsed.targetRoot) !== resolve25(root)) {
         throw new Error(`Install manifest target root does not match its enumerated runtime root: ${path}`);
       }
       const expectedPath = installManifestPath(parsed.targetRoot, parsed.adapter, {
         installationType: parsed.installationType,
         stateKey: parsed.stateKey
       });
-      if (resolve24(expectedPath) !== resolve24(path)) {
+      if (resolve25(expectedPath) !== resolve25(path)) {
         throw new Error(`Install manifest state identity does not match its canonical path: ${path}`);
       }
       found.set(path, { path, raw, manifest: { ...parsed, revision: computeManifestRevision(raw), legacy: false } });
@@ -12373,7 +12628,7 @@ async function collectManifestPaths(paths) {
       installationType: parsed.installationType,
       stateKey: parsed.stateKey
     });
-    if (resolve24(expectedPath) !== resolve24(path)) {
+    if (resolve25(expectedPath) !== resolve25(path)) {
       throw new Error(`Install manifest state identity does not match its canonical path: ${path}`);
     }
     found.push({ path, raw, manifest: { ...parsed, revision: computeManifestRevision(raw), legacy: false } });
@@ -12392,14 +12647,14 @@ function assertNoForeignSamePathOwnership(manifests, renderedPaths, allowedOwner
   }
 }
 async function relevantGraphLocks(workspaceRoot, selected, targetKeys, include) {
-  const root = join44(workspaceRoot, ".agentwheel", "locks");
+  const root = join45(workspaceRoot, ".agentwheel", "locks");
   if (!await pathExists(root)) return [];
   const results = [];
   for (const path of await listFiles(root)) {
     if (!path.endsWith(".graph-lock.json")) continue;
     const lock = await readGraphLock(path);
     if (!lock.canonical.roots.some((candidate2) => selected.has(candidate2.rootId))) continue;
-    const parts = relative8(root, path).split(/[\\/]/);
+    const parts = relative9(root, path).split(/[\\/]/);
     if (parts.length !== 3) throw new Error(`Graph lock path is not canonical: ${path}`);
     const [targetKey2, adapter] = parts;
     if (targetKeys && !targetKeys.has(targetKey2)) continue;
@@ -12416,7 +12671,7 @@ async function relevantGraphLocks(workspaceRoot, selected, targetKeys, include)
     const projection = relevantGraphProjection(lock, selected);
     results.push({
       ...candidate,
-      digest: sha2564(canonicalJson2(projection)),
+      digest: sha2565(canonicalJson2(projection)),
       artifactIdentities: lock.canonical.artifacts.filter((artifact) => artifact.owners.some((owner) => ownerMatchesGraphPackage(lock, owner, selected))).map(graphArtifactIdentity).sort()
     });
   }
@@ -12441,7 +12696,7 @@ async function hasRelevantLegacyManifestCandidate(scope, graph, selected) {
   const legacyManifest = (await collectManifestPaths([legacyState.manifestPath]))[0];
   if (legacyManifest?.manifest.entries.some((entry) => entryMatchesGraphPackages(entry, graph.lock, selected))) return true;
   const stableState = await targetStateForGraph(scope, graph, scope.fleetId ?? null);
-  if (resolve24(stableState.graphLockPath) !== resolve24(graph.path)) return false;
+  if (resolve25(stableState.graphLockPath) !== resolve25(graph.path)) return false;
   const stableManifest = (await collectManifestPaths([stableState.manifestPath]))[0];
   return stableManifest?.manifest.entries.some((entry) => entryMatchesGraphPackages(entry, graph.lock, selected)) ?? false;
 }
@@ -12462,7 +12717,7 @@ async function legacyManifestPathForConfiguredTarget(scope, graph) {
     baseDir: scope.root
   });
   const targetRoot = resolveConfigPath(agent.root, scope.root);
-  const installRoot = resolve24(installRootForAdapterInstallationType(adapter, targetRoot, agent.installationType, false));
+  const installRoot = resolve25(installRootForAdapterInstallationType(adapter, targetRoot, agent.installationType, false));
   const stateKey = stateKeyFor(adapter.name, {
     installationType: agent.installationType,
     stateKey: agent.stateKey,
@@ -12530,7 +12785,7 @@ async function targetStateForGraph(scope, graph, identityFleetId = scope.fleetId
     ssh: void 0,
     ...agent?.stateKey ? { stateKey: agent.stateKey } : {}
   };
-  const installRoot = resolve24(installRootForAdapterInstallationType(adapter, targetRoot, installationType, false));
+  const installRoot = resolve25(installRootForAdapterInstallationType(adapter, targetRoot, installationType, false));
   const targetIdentity = resolveTargetStateIdentity({
     targetFingerprintParts: fingerprintParts,
     workspaceRoot: scope.root,
@@ -12562,16 +12817,16 @@ async function targetStateForGraph(scope, graph, identityFleetId = scope.fleetId
 async function installedTargetStateForGraph(scope, graph, manifests, owners, selected, identityFleetId = scope.fleetId ?? null) {
   const stable = await targetStateForGraph(scope, graph, identityFleetId);
   let state;
-  if (resolve24(graph.path) === resolve24(stable.graphLockPath)) {
+  if (resolve25(graph.path) === resolve25(stable.graphLockPath)) {
     state = stable;
   } else {
     const released = await releasedTargetStateForGraph(scope, graph, identityFleetId);
-    if (resolve24(graph.path) !== resolve24(released.graphLockPath)) {
+    if (resolve25(graph.path) !== resolve25(released.graphLockPath)) {
       throw new Error(`Graph lock target identity is stale or noncanonical: ${graph.path}`);
     }
     state = released;
   }
-  const manifest = manifests.find((candidate) => resolve24(candidate.path) === resolve24(state.manifestPath));
+  const manifest = manifests.find((candidate) => resolve25(candidate.path) === resolve25(state.manifestPath));
   if (!manifest) {
     throw new Error(`Graph lock is not covered by its canonical install manifest: ${state.manifestPath}`);
   }
@@ -12595,7 +12850,7 @@ async function releasedTargetStateForGraph(scope, graph, identityFleetId = scope
     ...current,
     stateKey,
     targetFingerprint,
-    graphLockPath: join44(dirname21(graph.path), `${targetFingerprint}.graph-lock.json`),
+    graphLockPath: join45(dirname22(graph.path), `${targetFingerprint}.graph-lock.json`),
     manifestPath: installManifestPath(current.installRoot, current.adapter, {
       installationType: current.installationType,
       stateKey
@@ -12603,7 +12858,7 @@ async function releasedTargetStateForGraph(scope, graph, identityFleetId = scope
   };
 }
 function assertCorrelatedGraphManifest(graph, state, manifest, owners, selected) {
-  if (manifest.manifest.adapter !== state.adapter || manifest.manifest.installationType !== state.installationType || manifest.manifest.stateKey !== state.stateKey || resolve24(manifest.manifest.targetRoot) !== resolve24(state.installRoot)) {
+  if (manifest.manifest.adapter !== state.adapter || manifest.manifest.installationType !== state.installationType || manifest.manifest.stateKey !== state.stateKey || resolve25(manifest.manifest.targetRoot) !== resolve25(state.installRoot)) {
     throw new Error(`Install manifest identity does not match graph target state: ${manifest.path}`);
   }
   const entries = manifest.manifest.entries.filter((entry) => entryMatchesGraphPackages(entry, graph.lock, selected));
@@ -12611,7 +12866,7 @@ function assertCorrelatedGraphManifest(graph, state, manifest, owners, selected)
     throw new Error(`Graph lock is not covered by selected install-manifest contributions: ${graph.path}`);
   }
   const graphArtifacts = new Set(graph.artifactIdentities);
-  const graphLockDigest = sha2564(canonicalJson2(graph.lock));
+  const graphLockDigest = sha2565(canonicalJson2(graph.lock));
   for (const entry of entries) {
     if (!owners.has(entry.workspaceOwner)) {
       throw new Error(`Graph lock manifest owner mismatch at ${manifest.path}: ${entry.workspaceOwner}.`);
@@ -12660,7 +12915,7 @@ function destinationGraphFromSource(source, targetFingerprint) {
 function mergeDestinationManifest(existing, state, generatedAt, desiredEntries, replaceOwners = /* @__PURE__ */ new Set()) {
   if (existing) {
     const manifest2 = existing.manifest;
-    if (manifest2.adapter !== state.adapter || manifest2.installationType !== state.installationType || manifest2.stateKey !== state.stateKey || resolve24(manifest2.targetRoot) !== state.installRoot) {
+    if (manifest2.adapter !== state.adapter || manifest2.installationType !== state.installationType || manifest2.stateKey !== state.stateKey || resolve25(manifest2.targetRoot) !== state.installRoot) {
       throw new Error(`Destination manifest identity diverges from the derived target: ${existing.path}`);
     }
   }
@@ -12720,7 +12975,7 @@ async function assertEquivalentRuntimeState(entry, sourcePath, destinationPath)
       const content = await readFile27(path, "utf8");
       if (hasMergeRemovalContent(entry.mergeRemoval)) {
         assertExactMergeContribution(entry.mergeRemoval, entry.mergeStrategy, content);
-      } else if (resolve24(sourcePath) === resolve24(destinationPath) && entry.mergeStrategy !== "codex-toml-mcp") {
+      } else if (resolve25(sourcePath) === resolve25(destinationPath) && entry.mergeStrategy !== "codex-toml-mcp") {
         assertExactMergeContribution({}, entry.mergeStrategy, content);
       } else {
         throw new Error(`Installed-state normalization cannot prove incomplete merge ownership at ${path}.`);
@@ -12731,8 +12986,8 @@ async function assertEquivalentRuntimeState(entry, sourcePath, destinationPath)
   await assertEquivalentRuntimeBytes(sourcePath, destinationPath, entry.hash);
 }
 function renderedEntryPathForRoot(root, entryPath) {
-  const normalizedRoot = resolve24(root);
-  const candidate = resolve24(normalizedRoot, entryPath);
+  const normalizedRoot = resolve25(root);
+  const candidate = resolve25(normalizedRoot, entryPath);
   if (candidate !== normalizedRoot && !candidate.startsWith(`${normalizedRoot}/`)) {
     throw new Error(`Install manifest entry escapes its target root: ${entryPath}`);
   }
@@ -12823,8 +13078,8 @@ function ownerMatchesGraphPackage(lock, owner, selected) {
   return ownerMatchesPackage(owner, selected) || lock.canonical.roots.some((root) => selected.has(root.rootId) && root.graphNodeId === owner);
 }
 function renderedEntryPath(manifest, entry) {
-  const root = resolve24(manifest.targetRoot);
-  const candidate = resolve24(root, entry.path);
+  const root = resolve25(manifest.targetRoot);
+  const candidate = resolve25(root, entry.path);
   if (candidate !== root && !candidate.startsWith(`${root}/`)) {
     throw new Error(`Install manifest entry escapes its target root: ${entry.path}`);
   }
@@ -12979,7 +13234,7 @@ async function buildJournalGraphLockStates(plan) {
   for (const transfer of plan.installedState.graphTransfers) {
     const sourceBefore = JSON.parse(await readFile27(transfer.sourceGraphLockPath, "utf8"));
     const sourceLock = await readGraphLock(transfer.sourceGraphLockPath);
-    const sourceDigest = sha2564(canonicalJson2(sourceLock));
+    const sourceDigest = sha2565(canonicalJson2(sourceLock));
     if (sourceDigest !== transfer.sourceGraphLockDigest) {
       throw new Error(`Source graph lock changed after planning: ${transfer.sourceGraphLockPath}`);
     }
@@ -12997,9 +13252,9 @@ async function buildJournalGraphLockStates(plan) {
       continue;
     }
     const destinationBefore = await readOptionalRecord(transfer.destinationGraphLockPath);
-    const destinationBeforeDigest = destinationBefore ? sha2564(canonicalJson2(await readGraphLock(transfer.destinationGraphLockPath))) : null;
+    const destinationBeforeDigest = destinationBefore ? sha2565(canonicalJson2(await readGraphLock(transfer.destinationGraphLockPath))) : null;
     const destinationAfter = destinationBefore ? await readGraphLock(transfer.destinationGraphLockPath) : destinationGraphFromSource(sourceLock, transfer.targetFingerprint);
-    const destinationAfterDigest = sha2564(canonicalJson2(destinationAfter));
+    const destinationAfterDigest = sha2565(canonicalJson2(destinationAfter));
     if (destinationBeforeDigest !== transfer.destinationGraphLockDigest || destinationAfterDigest !== transfer.destinationGraphLockAfterDigest) {
       throw new Error(`Destination graph lock changed after planning: ${transfer.destinationGraphLockPath}`);
     }
@@ -13109,7 +13364,7 @@ async function assertJournalRecoverable(journal) {
   }
   for (const graphLock of journal.graphLocks) {
     const raw = await readOptionalRecord(graphLock.path);
-    const digest2 = raw ? sha2564(canonicalJson2(await readGraphLock(graphLock.path))) : null;
+    const digest2 = raw ? sha2565(canonicalJson2(await readGraphLock(graphLock.path))) : null;
     if (digest2 !== graphLock.beforeDigest && digest2 !== graphLock.afterDigest) {
       throw new Error(`Cannot recover fleet normalization because graph lock changed outside the transaction: ${graphLock.path}`);
     }
@@ -13162,10 +13417,10 @@ function packageMap(config) {
   return result;
 }
 function configRevision(config) {
-  return sha2564(canonicalJson2(config));
+  return sha2565(canonicalJson2(config));
 }
 function normalizationJournalPath(sourceRoot, destinationFleet) {
-  return join44(sourceRoot, ".agentwheel", `fleet-normalize-${destinationFleet}.journal.json`);
+  return join45(sourceRoot, ".agentwheel", `fleet-normalize-${destinationFleet}.journal.json`);
 }
 function canonicalJson2(value) {
   return JSON.stringify(sortValue(value));
@@ -13177,8 +13432,8 @@ function sortValue(value) {
   }
   return value;
 }
-function sha2564(value) {
-  return createHash13("sha256").update(value).digest("hex");
+function sha2565(value) {
+  return createHash14("sha256").update(value).digest("hex");
 }
 function assertDigest(value) {
   if (!/^[a-f0-9]{64}$/.test(value)) throw new Error(`Invalid plan digest: ${value}`);
@@ -13216,6 +13471,7 @@ var commandGovernance = {
   "package migrate": "governed-always",
   remember: "governed-always",
   "ownership handoff": "governed-unless-dry-run",
+  "ownership recovery-plan": "incidental-cache",
   "ownership retire-stale": "governed-apply",
   "mcp retire": "governed-apply",
   eject: "governed-always",
@@ -13322,7 +13578,7 @@ fleetCommand.command("normalize").description("plan or apply duplicate desired-s
 });
 cacheCommand.command("prune").description("remove old Git source snapshots while preserving locked commits").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>", "explicit workspace root").option("--keep <count>", "newest snapshots to retain per source", parsePositiveInteger, 3).option("--apply", "delete the selected snapshots; without this flag only preview", false).action(async (options) => {
   const targetRoot = await workspaceContextRootFromOptions(normalizeRuntimeScopeOptions(options));
-  const cacheRoot = join45(targetRoot, ".agentwheel", "cache");
+  const cacheRoot = join46(targetRoot, ".agentwheel", "cache");
   const result = await pruneGitCache(cacheRoot, { keepSnapshots: options.keep, dryRun: !options.apply });
   const verb = options.apply ? "Removed" : "Would remove";
   for (const path of result.removedPaths) console.log(`${verb} ${path}`);
@@ -13340,7 +13596,7 @@ program.command("list").description("list artifacts exposed by a package source"
   const resolvedInput = await resolvePackageSource(source, targetRoot);
   const selectedArtifacts = selectedArtifactsFromOptionsOrRegistry(options, resolvedInput.registryEntry);
   const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedInput.source));
-  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join45(targetRoot, ".agentwheel", "cache") }))));
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join46(targetRoot, ".agentwheel", "cache") }))));
   try {
     const artifacts = filterArtifactsBySelection(await driver.list(resolved), selectedArtifacts);
     for (const artifact of artifacts) {
@@ -13409,7 +13665,7 @@ program.command("try").description("read and validate one skill for the current
   const resolvedInput = await resolvePackageSource(source, targetRoot);
   const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedInput.source));
   const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, {
-    cacheRoot: join45(targetRoot, ".agentwheel", "cache")
+    cacheRoot: join46(targetRoot, ".agentwheel", "cache")
   }))));
   try {
     const trial = await createSkillTrial(driver, resolved, selectedArtifactsFromOptionsOrRegistry(options, resolvedInput.registryEntry));
@@ -13431,7 +13687,7 @@ program.command("scan").description("scan a package source for validation findin
   const targetRoot = await workspaceContextRootFromOptions(normalizeRuntimeScopeOptions(options));
   const resolvedInput = await resolvePackageSource(source, targetRoot);
   const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedInput.source));
-  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join45(targetRoot, ".agentwheel", "cache") }))));
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join46(targetRoot, ".agentwheel", "cache") }))));
   try {
     const result = await driver.scan(resolved);
     if (result.findings.length === 0) {
@@ -13446,10 +13702,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) => {
@@ -13636,7 +13892,7 @@ ownershipCommand.command("handoff").description("transfer one managed artifact b
   const toWorkspaceRoot = normalizeCliPath(options.toWorkspaceRoot);
   if (options.toFleet) {
     const fleet = await showRegisteredFleet(options.toFleet);
-    if (resolve25(fleet.root) !== resolve25(toWorkspaceRoot)) {
+    if (resolve26(fleet.root) !== resolve26(toWorkspaceRoot)) {
       throw new Error(`Destination fleet '${options.toFleet}' is registered at ${fleet.root}, not ${toWorkspaceRoot}.`);
     }
   }
@@ -13662,11 +13918,85 @@ ownershipCommand.command("handoff").description("transfer one managed artifact b
   console.log(`Manifest revision: ${result.manifestRevision}`);
   console.log(`Owner: ${result.fromOwner} -> ${result.toOwner}`);
 });
+ownershipCommand.command("recovery-plan").description("write a read-only per-path legacy ownership evidence report").requiredOption("--fleet <id>", "registered Fleet containing the current source graph").requiredOption("--report <path>", "new private JSON report path").option("--agent <name>", "one named Fleet target").option("--profile <name>", "Fleet profile resolving to one target").action(async (options) => {
+  const targets = await resolveCliTargets({ fleet: options.fleet, agent: options.agent, profile: options.profile });
+  if (targets.length !== 1) throw new Error(`Recovery planning requires one Fleet target, found ${targets.length}.`);
+  const target = targets[0];
+  if (target.fleetId !== options.fleet) throw new Error("Resolved target does not belong to the selected Fleet.");
+  const adapter = await resolveAdapterForTarget(target, {});
+  const transport = transportForTarget(target);
+  const requestedReport = normalizeCliPath(options.report);
+  const reportPath = join46(await realpath2(dirname23(requestedReport)), basename21(requestedReport));
+  const reportInsideTarget = relative10(resolve26(target.targetRoot), reportPath);
+  if (reportInsideTarget === "" || !reportInsideTarget.startsWith("..") && !isAbsolute4(reportInsideTarget)) {
+    throw new Error("Recovery report must be outside the runtime target root.");
+  }
+  const installationType = target.installationType ?? resolveInstallationTypeForAdapter(adapter, void 0);
+  const config = await readMergedWorkspaceConfig(target.workspaceRoot);
+  if (config.packages.length === 0) throw new Error("Fleet has no configured source packages.");
+  const stage = await mkdtemp4(join46(tmpdir5(), "agentwheel-recovery-"));
+  const priorTmpdir = process.env.TMPDIR;
+  try {
+    process.env.TMPDIR = stage;
+    const graphPlan = await createGraphSourcePlan({
+      roots: config.packages.map((pkg) => ({
+        rootId: pkg.name,
+        source: pkg.source,
+        mode: pkg.mode,
+        version: pkg.version,
+        ref: pkg.requestedRef,
+        select: pkg.selection ? void 0 : normalizeArtifactSelectors(pkg.select, pkg.skills),
+        selection: pkg.selection,
+        aliases: pkg.aliases,
+        overrides: pkg.overrides,
+        includeSuggestions: pkg.withSuggestions,
+        suggestionAliases: pkg.suggestions,
+        useLock: false
+      })),
+      targetRoot: target.targetRoot,
+      workspaceRoot: target.workspaceRoot,
+      fleetId: target.fleetId,
+      adapter,
+      transport,
+      targetKey: targetKeyForTarget(target, adapter.name),
+      targetFingerprintParts: targetFingerprintParts(target, adapter, adapterOptionsForTarget(target, {}), installationType),
+      installationType,
+      stateKey: target.stateKey,
+      readOnly: true,
+      yes: true,
+      freshGraphOnly: true,
+      deferForeignStateCheck: true,
+      cacheRoot: join46(stage, "source-cache"),
+      registryCachePath: join46(stage, "registry.json")
+    });
+    const installRoot = installRootForAdapterInstallationType(adapter, target.targetRoot, installationType, transport.kind === "ssh");
+    const report = await planLegacyRecovery({
+      graphPlan,
+      installRoot,
+      workspaceRoot: target.workspaceRoot,
+      fleetId: target.fleetId,
+      explicitStateKey: target.stateKey,
+      targetKey: targetKeyForTarget(target, adapter.name),
+      adapter: adapter.name,
+      installationType,
+      historicalLocks: await inventoryHistoricalLocks(target.workspaceRoot),
+      transport
+    });
+    await writeFile13(reportPath, `${JSON.stringify(report, null, 2)}
+`, { mode: 384, flag: "wx" });
+    console.log(`Recovery report: ${reportPath}`);
+    console.log(JSON.stringify(report.counts));
+  } finally {
+    if (priorTmpdir === void 0) delete process.env.TMPDIR;
+    else process.env.TMPDIR = priorTmpdir;
+    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) => {
   const normalizedOptions = normalizeRuntimeScopeOptions(options);
   const fleet = await showRegisteredFleet(options.fleet);
   const toWorkspaceRoot = normalizeCliPath(options.toWorkspaceRoot);
-  if (resolve25(fleet.root) !== resolve25(toWorkspaceRoot)) {
+  if (resolve26(fleet.root) !== resolve26(toWorkspaceRoot)) {
     throw new Error(`Destination Fleet '${options.fleet}' is registered at ${fleet.root}, not ${toWorkspaceRoot}.`);
   }
   const targets = await resolveCliTargets(normalizedOptions);
@@ -13674,7 +14004,7 @@ ownershipCommand.command("retire-stale").description("retire stale source-manife
     throw new Error(`Stale ownership retirement requires exactly one destination Fleet target, found ${targets.length}.`);
   }
   const target = targets[0];
-  if (target.fleetId !== options.fleet || resolve25(target.workspaceRoot) !== resolve25(fleet.root)) {
+  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);
@@ -13832,7 +14162,7 @@ journalCommand.command("list").description("show pending apply journals for reso
     if (!journal) continue;
     pending += 1;
     console.log(`PENDING ${state.adapter.name}/${state.installationType} at ${state.installRoot}`);
-    console.log(`  journal: ${join45(state.installRoot, ".agentwheel", `${state.state.stateKey}.apply-journal.json`)}`);
+    console.log(`  journal: ${join46(state.installRoot, ".agentwheel", `${state.state.stateKey}.apply-journal.json`)}`);
     console.log(`  stateKey: ${state.state.stateKey}`);
     console.log(`  createdAt: ${journal.createdAt}`);
     console.log(`  updatedAt: ${journal.updatedAt}`);
@@ -14168,14 +14498,14 @@ async function packageEntryFromSource(source, targetRoot, options) {
     );
   }
   const bundle = options.deferGraphRendering ? await stageSourceRaw(driver, resolvedSource, {
-    cacheRoot: join45(targetRoot, ".agentwheel", "cache"),
+    cacheRoot: join46(targetRoot, ".agentwheel", "cache"),
     mode: options.mode,
     ref: initialVersion?.ref,
     frozenLock: lockMode
   }) : await stageSource(driver, resolvedSource, {
     workspaceRoot: targetRoot,
     adapter,
-    cacheRoot: join45(targetRoot, ".agentwheel", "cache"),
+    cacheRoot: join46(targetRoot, ".agentwheel", "cache"),
     mode: options.mode,
     ref: initialVersion?.ref,
     frozenLock: lockMode,
@@ -14576,7 +14906,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();
@@ -14685,7 +15016,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;
@@ -14756,7 +15088,7 @@ function scopeUpdatePlanToDependencies(result, selectors, previousLock, manifest
     selectedPreviousNodeIds,
     selectedRootIds
   );
-  const graphLockDigest = createHash14("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
+  const graphLockDigest = createHash15("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
   return {
     ...result,
     bundle: { ...result.bundle, graphLock },
@@ -14882,7 +15214,7 @@ function operationBelongsToDependencyUpdate(operation, allowedNodeIds, allowedNa
 function scopeInstallPlanToArtifact(result, rootId, focused, manifest) {
   const scoped = scopePlanOperationsToArtifact(result, rootId, focused, manifest);
   const graphLock = focusedGraphLockForInstall(scoped.bundle.graphLock, rootId, focused);
-  const graphLockDigest = createHash14("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
+  const graphLockDigest = createHash15("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
   return {
     ...scoped,
     bundle: { ...scoped.bundle, graphLock },
@@ -14893,7 +15225,7 @@ function scopeInstallPlanToArtifact(result, rootId, focused, manifest) {
 function scopeUpdatePlanToArtifact(result, rootId, focused, previousLock, manifest) {
   const scoped = scopePlanOperationsToArtifact(result, rootId, focused, manifest, previousLock);
   const graphLock = mergeFocusedArtifactGraphLock(scoped.bundle.graphLock, previousLock, rootId, focused);
-  const graphLockDigest = createHash14("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
+  const graphLockDigest = createHash15("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
   return {
     ...scoped,
     bundle: { ...scoped.bundle, graphLock },
@@ -15188,7 +15520,7 @@ function scopeUpdatePlanToRoot(result, rootId, previousLock, manifest) {
     selectedPreviousNodeIds,
     /* @__PURE__ */ new Set([rootId])
   );
-  const graphLockDigest = createHash14("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
+  const graphLockDigest = createHash15("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
   return {
     ...scoped,
     bundle: { ...scoped.bundle, graphLock },
@@ -15260,7 +15592,7 @@ function keepManifestEntryOperation(entry, targetRoot, scopeDescription, operati
     artifactType: entry.artifactType,
     artifactName: entry.artifactName,
     kind: entry.kind,
-    destPath: operation?.destPath ?? join45(targetRoot, entry.path),
+    destPath: operation?.destPath ?? join46(targetRoot, entry.path),
     relativeDestPath: entry.path,
     desiredHash: entry.sourceHash,
     currentHash: operation?.currentHash ?? entry.hash,
@@ -15511,7 +15843,9 @@ async function resolveCliTargetState(target, options) {
     graphLockPath: stableGraphLockPath,
     stableManifest,
     stableLock,
-    transport
+    transport,
+    recoverLegacyState: options.recoverLegacyState,
+    warn: options.warn
   });
   return {
     adapter,
@@ -15526,7 +15860,7 @@ async function resolveCliTargetState(target, options) {
     migration: prior.migration,
     targetStateFilePreconditions: {
       graphLockPath: stableGraphLockPath,
-      graphLockRevision: stableLock ? createHash14("sha256").update(canonicalGraphLockJson(stableLock)).digest("hex") : null,
+      graphLockRevision: stableLock ? createHash15("sha256").update(canonicalGraphLockJson(stableLock)).digest("hex") : null,
       sourceLockRevision: computeSourceLockRevision(stableSourceLock)
     }
   };
@@ -15549,7 +15883,7 @@ async function collectTargetStatus(target, options) {
   const pending = await collectPendingInstallWork(target, options);
   const foreignObservations = pending.foreignStateObservations;
   const effectiveGraphLock = graphLock ?? pending.observedGraphLock;
-  const observedManifestRevision = foreignObservations.length > 0 ? createHash14("sha256").update(JSON.stringify(foreignObservations.map((observation) => [
+  const observedManifestRevision = foreignObservations.length > 0 ? createHash15("sha256").update(JSON.stringify(foreignObservations.map((observation) => [
     observation.fileName,
     observation.manifestRevision
   ]).sort())).digest("hex") : null;
@@ -15796,7 +16130,7 @@ async function assertCompositeMutationSupported(workspaceRoot, profile, readOnly
         `Composite-profile mutation is refused before member execution because ${member.id} uses ${member.transport}; durable remote policy and recovery preflight is not implemented.`
       );
     }
-    const memberRoot = resolve25(workspaceRoot, member.workspace);
+    const memberRoot = resolve26(workspaceRoot, member.workspace);
     const memberPolicy = await mutationPolicyForWorkspace(memberRoot);
     if (memberPolicy?.revisioning.mode === "commit-after-verify") {
       throw new Error(
@@ -16032,12 +16366,12 @@ async function printDoctor(target, options) {
   const requestedSkills = doctorSkillRequests(target, options);
   const skills = [];
   for (const request of requestedSkills) {
-    const skillPath = join45(state.installRoot, targetMapping.dest, request.name);
+    const skillPath = join46(state.installRoot, targetMapping.dest, request.name);
     const exists = await pathExists(skillPath);
     const manifestEntry = manifest?.entries.find((entry) => {
       if (entry.artifactType !== "skills") return false;
       const legacyInstallName = "installName" in entry && typeof entry.installName === "string" ? entry.installName : void 0;
-      return entry.artifactName === request.name || legacyInstallName === request.name || entry.path === join45(targetMapping.dest, request.name);
+      return entry.artifactName === request.name || legacyInstallName === request.name || entry.path === join46(targetMapping.dest, request.name);
     });
     const status = manifestEntry ? "managed" : exists ? "present-unmanaged" : "missing";
     skills.push({
@@ -16117,7 +16451,7 @@ function doctorSkillLabel(name) {
   return `${name} skill`;
 }
 function isSyncwheelWorkspace(targetRoot) {
-  return existsSync(join45(targetRoot, ".syncwheel", "manifest.json"));
+  return existsSync(join46(targetRoot, ".syncwheel", "manifest.json"));
 }
 function skillInstallCommand(adapter, installationType, options, skill, behavior = {}) {
   const args = [
@@ -16280,14 +16614,14 @@ function looksLikeSourceSpecifier(value) {
 }
 function normalizeCliPath(value) {
   if (value === "~") return homedir12();
-  if (value.startsWith("~/")) return resolve25(homedir12(), value.slice(2));
-  return resolve25(value);
+  if (value.startsWith("~/")) return resolve26(homedir12(), value.slice(2));
+  return resolve26(value);
 }
 function shellQuoteArgument(value) {
   return /^[a-z0-9_./:@%+=,-]+$/i.test(value) ? value : `'${value.replace(/'/g, `'"'"'`)}'`;
 }
 function isHomePath(path) {
-  return resolve25(path) === resolve25(homedir12());
+  return resolve26(path) === resolve26(homedir12());
 }
 function adapterListFromOption(adapter) {
   if (!adapter) return [];
@@ -16342,11 +16676,11 @@ function filterUninstallPlanBySelection(plan, selected) {
   };
 }
 async function initPackage(root) {
-  await mkdir16(join45(root, "instructions"), { recursive: true });
-  await mkdir16(join45(root, "rules"), { recursive: true });
-  await mkdir16(join45(root, "skills"), { recursive: true });
-  const manifestPath = join45(root, "openpack.json");
-  const instructionsPath = join45(root, "instructions", "AGENTS.md");
+  await mkdir16(join46(root, "instructions"), { recursive: true });
+  await mkdir16(join46(root, "rules"), { recursive: true });
+  await mkdir16(join46(root, "skills"), { recursive: true });
+  const manifestPath = join46(root, "openpack.json");
+  const instructionsPath = join46(root, "instructions", "AGENTS.md");
   const manifest = {
     schemaVersion: CURRENT_OPENPACK_SCHEMA_VERSION,
     name: "example/agentwheel-package",
@@ -16364,7 +16698,7 @@ async function initPackage(root) {
   await writeFile13(instructionsPath, "# Agent Instructions\n", "utf8");
 }
 async function defaultBootstrapPackage(_root) {
-  const packageRoot = await findAgentwheelPackageRoot(dirname22(fileURLToPath3(import.meta.url)));
+  const packageRoot = await findAgentwheelPackageRoot(dirname23(fileURLToPath3(import.meta.url)));
   if (!packageRoot) return void 0;
   return {
     name: "agentwheel",
@@ -16408,10 +16742,10 @@ function withFleetExample(config) {
   };
 }
 async function findAgentwheelPackageRoot(start) {
-  let current = resolve25(start);
+  let current = resolve26(start);
   while (true) {
     if (await findPackageManifestPath(current, { warnLegacy: false })) return current;
-    const parent = dirname22(current);
+    const parent = dirname23(current);
     if (parent === current) return void 0;
     current = parent;
   }
@@ -16536,14 +16870,14 @@ async function governedCommandContext(command, options) {
     const kind = String(command.args[0] ?? "workspace");
     return {
       workspaceRoot: workspaceRoot2,
-      anticipatedPaths: kind === "package" ? [join45(targetRoot, "openpack.json"), join45(targetRoot, "instructions", "AGENTS.md")] : [workspaceConfigPath(targetRoot)]
+      anticipatedPaths: kind === "package" ? [join46(targetRoot, "openpack.json"), join46(targetRoot, "instructions", "AGENTS.md")] : [workspaceConfigPath(targetRoot)]
     };
   }
   if (path === "package migrate") {
     const packageRoot = normalizeTargetRoot(String(command.args[0] ?? "."));
     return {
       workspaceRoot: await findExistingWorkspaceRoot(packageRoot) ?? packageRoot,
-      anticipatedPaths: ["agentwheel.json", "agentwheel.jsonc", "openpack.json", "openpack.jsonc"].map((name) => join45(packageRoot, name))
+      anticipatedPaths: ["agentwheel.json", "agentwheel.jsonc", "openpack.json", "openpack.jsonc"].map((name) => join46(packageRoot, name))
     };
   }
   const source = typeof command.args[0] === "string" ? command.args[0] : void 0;
@@ -16555,7 +16889,7 @@ async function governedCommandContext(command, options) {
   const anticipatedPaths = [];
   if (path === "add") anticipatedPaths.push(workspaceConfigPath(workspaceRoot));
   if (path === "remember" && options.runtime) {
-    anticipatedPaths.push(join45(workspaceRoot, ".agentwheel", "overlays", options.runtime, "instructions.local.md"));
+    anticipatedPaths.push(join46(workspaceRoot, ".agentwheel", "overlays", options.runtime, "instructions.local.md"));
   }
   if (path === "uninstall" && source) anticipatedPaths.push(workspaceConfigPath(workspaceRoot));
   return {