agentwheel 0.18.1 → 0.18.2

package/dist/index.js

@@ -10483,7 +10483,7 @@ async function createGraphSourcePlan(options) {
     replaceConflict: options.replaceConflict,
     warn
   });
-  if (options.forceForeignState !== true || options.fleetId) {
+  if ((options.forceForeignState !== true || options.fleetId) && options.deferForeignStateCheck !== true) {
     await assertNoForeignWorkspaceState({
       installRoot: resolvedInstallRoot,
       adapter: options.adapter.name,
@@ -10509,6 +10509,19 @@ async function createGraphSourcePlan(options) {
     recoveredPendingApply
   };
 }
+async function assertNoForeignWorkspaceStateForPlan(plan, options) {
+  if (!plan.stateKey) throw new Error(`Foreign-state validation requires a state key for ${plan.adapter}.`);
+  await assertNoForeignWorkspaceState({
+    installRoot: plan.targetRoot,
+    adapter: plan.adapter,
+    transport: options.transport ?? localTransport,
+    workspaceRoot: options.workspaceRoot,
+    workspaceOwner: options.workspaceOwner,
+    globalRoot: options.globalRoot,
+    stateKey: plan.stateKey,
+    plannedPaths: options.plannedPaths ?? plan.operations.map((operation) => operation.relativeDestPath)
+  });
+}
 function graphLockPathForTarget(workspaceRoot, targetKey2, adapter, targetFingerprintParts2) {
   return pathForGraphLock(workspaceRoot, targetKey2, adapter, computeTargetFingerprint(targetFingerprintParts2));
 }
@@ -13280,7 +13293,10 @@ async function planFleetNormalization(request) {
     packages.push({ name, declarationDigest: sha2564(sourceDeclaration) });
   }
   if (!legacySelfNormalization) await assertSourceFleetPostcondition(normalizedRequest, sourceScope, candidates);
-  const installedState = legacySelfNormalization ? await inspectLegacySelfInstalledState(destinationScope, candidates) : await inspectInstalledState(sourceScope, destinationScope, candidates);
+  if ((normalizedRequest.profile || normalizedRequest.artifacts) && !legacySelfNormalization) {
+    throw new Error("--profile and --artifact are supported only for legacy same-fleet ownership normalization.");
+  }
+  const installedState = legacySelfNormalization ? await inspectLegacySelfInstalledState(destinationScope, candidates, normalizedRequest.profile, normalizedRequest.artifacts) : await inspectInstalledState(sourceScope, destinationScope, candidates);
   const planWithoutDigest = {
     version: 1,
     request: normalizedRequest,
@@ -13444,10 +13460,16 @@ async function assertSourceFleetPostcondition(request, source, selectedPackages)
 function normalizeRequest(request) {
   const packages = request.packages === void 0 ? void 0 : sortedUnique8(request.packages);
   if (request.packages !== void 0 && packages?.length === 0) throw new Error("--package requires at least one package name.");
+  const artifacts = request.artifacts === void 0 ? void 0 : sortedUnique8(request.artifacts.map((artifact) => normalizeArtifactSelector(artifact)));
+  if (request.artifacts !== void 0 && artifacts?.length === 0) throw new Error("--artifact requires at least one type/name selector.");
+  const profile = request.profile?.trim();
+  if (request.profile !== void 0 && !profile) throw new Error("--profile requires a profile name.");
   return {
     destinationFleet: request.destinationFleet.trim(),
     from: request.from,
     ...packages ? { packages } : {},
+    ...artifacts ? { artifacts } : {},
+    ...profile ? { profile } : {},
     ...request.globalRoot ? { globalRoot: resolve25(request.globalRoot) } : {}
   };
 }
@@ -13631,19 +13653,45 @@ async function inspectInstalledState(source, destination, packageNames) {
     transfers: [...transfers.values()].sort((a, b) => `${a.sourceManifestPath}:${a.destinationManifestPath}`.localeCompare(`${b.sourceManifestPath}:${b.destinationManifestPath}`))
   };
 }
-async function inspectLegacySelfInstalledState(fleet, packageNames) {
+async function inspectLegacySelfInstalledState(fleet, packageNames, profileName, artifactNames) {
   if (fleet.kind !== "fleet" || !fleet.fleetId) {
     throw new Error("Legacy self-normalization requires a registered named fleet destination.");
   }
   const selected = new Set(packageNames);
-  const [graphs, roots] = await Promise.all([
-    relevantGraphLocks(fleet.root, selected),
-    runtimeRoots(fleet)
-  ]);
-  const manifests = await collectManifests(roots);
+  const selectedArtifacts = artifactNames ? new Set(artifactNames) : void 0;
+  const targetKeys = profileName ? targetKeysForProfile(fleet, profileName) : void 0;
+  const graphCandidates = await relevantGraphLocks(
+    fleet.root,
+    selected,
+    targetKeys,
+    async (graph) => hasRelevantLegacyManifestCandidate(fleet, graph, selected)
+  );
+  const graphs = [];
   const legacyOwner = workspaceOwnerForRoot(fleet.root);
   const fleetOwner = workspaceOwnerForRoot(fleet.root, fleet.fleetId);
-  const relevantEntries = manifests.flatMap((manifest) => manifest.manifest.entries.filter((entry) => entryMatchesPackages(entry, selected)).map((entry) => ({ manifest, entry, renderedPath: renderedEntryPath(manifest.manifest, entry) })));
+  let normalizedGraphCount = 0;
+  for (const graph of graphCandidates) {
+    const legacyState = await legacyTargetStateForGraph(fleet, graph);
+    const legacyManifest = (await collectManifestPaths([legacyState.manifestPath]))[0];
+    const relevantManifestEntries2 = legacyManifest?.manifest.entries.filter((entry) => entryMatchesGraphPackages(entry, graph.lock, selected) && entryMatchesArtifacts(entry, selectedArtifacts)) ?? [];
+    if (relevantManifestEntries2.length > 0) {
+      graphs.push(graph);
+    }
+    const destinationState = await targetStateForGraph(fleet, graph, fleet.fleetId);
+    if (destinationState.graphLockPath === graph.path && legacyManifest?.manifest.entries.some((entry) => entry.workspaceOwner === fleetOwner && entryMatchesPackages(entry, selected))) {
+      normalizedGraphCount += 1;
+    }
+  }
+  if (graphs.length === 0 && normalizedGraphCount > 0) {
+    throw new Error(`Fleet '${fleet.fleetId}' installed state is already normalized to fleet-qualified ownership.`);
+  }
+  const manifestPaths = /* @__PURE__ */ new Set();
+  for (const graph of graphs) {
+    manifestPaths.add((await legacyTargetStateForGraph(fleet, graph)).manifestPath);
+    manifestPaths.add((await targetStateForGraph(fleet, graph, fleet.fleetId)).manifestPath);
+  }
+  const manifests = await collectManifestPaths([...manifestPaths]);
+  const relevantEntries = manifests.flatMap((manifest) => manifest.manifest.entries.filter((entry) => graphs.some((graph) => entryMatchesGraphPackages(entry, graph.lock, selected)) && entryMatchesArtifacts(entry, selectedArtifacts)).map((entry) => ({ manifest, entry, renderedPath: renderedEntryPath(manifest.manifest, entry) })));
   const legacyEntries = relevantEntries.filter((entry) => entry.entry.workspaceOwner === legacyOwner);
   const qualifiedEntries = relevantEntries.filter((entry) => entry.entry.workspaceOwner === fleetOwner);
   const foreignEntries = relevantEntries.filter((entry) => entry.entry.workspaceOwner !== legacyOwner && entry.entry.workspaceOwner !== fleetOwner);
@@ -13652,17 +13700,17 @@ async function inspectLegacySelfInstalledState(fleet, packageNames) {
       `Legacy self-normalization owner mismatch at ${foreignEntries[0].renderedPath}: expected ${legacyOwner}, found foreign owner ${foreignEntries[0].entry.workspaceOwner}.`
     );
   }
-  if (qualifiedEntries.length > 0) {
-    throw new Error(`Fleet '${fleet.fleetId}' installed state is already normalized to fleet-qualified ownership.`);
-  }
   if (legacyEntries.length === 0) {
+    if (qualifiedEntries.length > 0) {
+      throw new Error(`Fleet '${fleet.fleetId}' installed state is already normalized to fleet-qualified ownership.`);
+    }
     throw new Error(`Fleet '${fleet.fleetId}' has no legacy same-root manifest ownership to normalize.`);
   }
   if (graphs.length === 0) {
     throw new Error("Legacy same-root install manifests exist without matching graph lock evidence; self-normalization is blocked.");
   }
   for (const graph of graphs) {
-    if (!graph.allRootsSelected) {
+    if (!selectedArtifacts && !graph.allRootsSelected) {
       throw new Error(`Legacy graph lock is only partially selected and cannot be moved safely: ${graph.path}`);
     }
   }
@@ -13671,14 +13719,11 @@ async function inspectLegacySelfInstalledState(fleet, packageNames) {
   const coveredEntries = /* @__PURE__ */ new Set();
   const renderedPaths = /* @__PURE__ */ new Set();
   for (const graph of graphs) {
-    const legacyState = await targetStateForGraph(fleet, graph, null);
+    const legacyState = await legacyTargetStateForGraph(fleet, graph);
     const destinationState = await targetStateForGraph(fleet, graph, fleet.fleetId);
     if (graph.path === destinationState.graphLockPath) {
       throw new Error(`Fleet '${fleet.fleetId}' graph state is already normalized to fleet-qualified identity.`);
     }
-    if (legacyState.graphLockPath !== graph.path) {
-      throw new Error(`Legacy graph lock target identity is stale or noncanonical: ${graph.path}`);
-    }
     const expectedEntries = legacyEntries.filter((entry) => entry.manifest.path === legacyState.manifestPath);
     if (expectedEntries.length === 0) {
       throw new Error(`Legacy graph lock is not covered by its canonical same-root install manifest: ${legacyState.manifestPath}`);
@@ -13716,18 +13761,22 @@ async function inspectLegacySelfInstalledState(fleet, packageNames) {
       renderedPaths: sortedUnique8(expectedEntries.map((entry) => entry.renderedPath)),
       destinationRenderedPaths: sortedUnique8(expectedEntries.map((entry) => entry.renderedPath))
     });
-    const fullDigest = sha2564(canonicalJson2(graph.lock));
-    const destinationGraph = destinationGraphFromSource(graph.lock, destinationState.targetFingerprint);
-    graphTransfers.push({
-      sourceGraphLockPath: graph.path,
-      sourceGraphLockDigest: fullDigest,
-      destinationGraphLockPath: destinationState.graphLockPath,
-      destinationGraphLockDigest: null,
-      destinationGraphLockAfterDigest: sha2564(canonicalJson2(destinationGraph)),
-      targetKey: graph.targetKey,
-      adapter: graph.adapter,
-      targetFingerprint: destinationState.targetFingerprint
-    });
+    if (!selectedArtifacts) {
+      const fullDigest = sha2564(canonicalJson2(graph.lock));
+      const existingDestinationGraph = graphCandidates.find((candidate) => candidate.path === destinationState.graphLockPath);
+      if (existingDestinationGraph) assertGraphIsSubset(graph, existingDestinationGraph);
+      const destinationGraph = destinationGraphFromSource(graph.lock, destinationState.targetFingerprint);
+      graphTransfers.push({
+        sourceGraphLockPath: graph.path,
+        sourceGraphLockDigest: fullDigest,
+        destinationGraphLockPath: destinationState.graphLockPath,
+        destinationGraphLockDigest: existingDestinationGraph ? sha2564(canonicalJson2(existingDestinationGraph.lock)) : null,
+        destinationGraphLockAfterDigest: sha2564(canonicalJson2(destinationGraph)),
+        targetKey: graph.targetKey,
+        adapter: graph.adapter,
+        targetFingerprint: destinationState.targetFingerprint
+      });
+    }
   }
   if (coveredEntries.size !== legacyEntries.length) {
     throw new Error("Legacy same-root manifest ownership is only partially covered by canonical graph locks.");
@@ -13735,13 +13784,21 @@ async function inspectLegacySelfInstalledState(fleet, packageNames) {
   return {
     graphLockDigests: graphs.map((graph) => graph.digest).sort(),
     sourceManifestCount: new Set(legacyEntries.map((entry) => entry.manifest.path)).size,
-    destinationManifestCount: 0,
+    destinationManifestCount: new Set(qualifiedEntries.map((entry) => entry.manifest.path)).size,
     renderedPathCount: renderedPaths.size,
     sourceGraphLockPaths: graphs.map((graph) => graph.path).sort((a, b) => a.localeCompare(b)),
     graphTransfers: graphTransfers.sort((a, b) => a.sourceGraphLockPath.localeCompare(b.sourceGraphLockPath)),
     transfers: [...transfers.values()].sort((a, b) => a.sourceManifestPath.localeCompare(b.sourceManifestPath))
   };
 }
+function targetKeysForProfile(scope, name) {
+  const profile = scope.config.profiles[name];
+  if (!profile) throw new Error(`Unknown fleet profile '${name}'.`);
+  if (isCompositeWorkspaceProfile(profile)) {
+    throw new Error(`Fleet normalization requires a concrete local profile; '${name}' is composite.`);
+  }
+  return new Set(profile.runtimes.map((runtime) => runtime.agent ?? runtime.adapter));
+}
 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")) {
@@ -13751,10 +13808,8 @@ async function runtimeRoots(scope) {
     if (agent.transport === "ssh") throw new Error(`Installed-state normalization cannot inspect SSH agent '${name}' locally.`);
     roots.add(resolveConfigPath(agent.root, scope.root));
   }
-  for (const [name, profile] of Object.entries(scope.config.profiles)) {
-    if (isCompositeWorkspaceProfile(profile)) {
-      throw new Error(`Installed-state normalization cannot prove composite profile '${name}' locally.`);
-    }
+  for (const profile of Object.values(scope.config.profiles)) {
+    if (isCompositeWorkspaceProfile(profile)) continue;
     for (const runtime of profile.runtimes) {
       if (runtime.agent) continue;
       roots.add(runtime.targetRoot ? resolveConfigPath(runtime.targetRoot, scope.root) : scope.root);
@@ -13799,34 +13854,74 @@ async function collectManifests(roots) {
   }
   return [...found.values()].sort((a, b) => a.path.localeCompare(b.path));
 }
-async function relevantGraphLocks(workspaceRoot, selected) {
+async function collectManifestPaths(paths) {
+  const found = [];
+  for (const path of [...new Set(paths)].sort((a, b) => a.localeCompare(b))) {
+    if (!await pathExists(path)) continue;
+    const raw = JSON.parse(await readFile37(path, "utf8"));
+    const parsed = installManifestSchema.parse(raw);
+    if (parsed.version !== 2) {
+      throw new Error(`Legacy v1 install manifest cannot prove fleet ownership: ${path}`);
+    }
+    const expectedPath = installManifestPath(parsed.targetRoot, parsed.adapter, {
+      installationType: parsed.installationType,
+      stateKey: parsed.stateKey
+    });
+    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 } });
+  }
+  return found;
+}
+async function relevantGraphLocks(workspaceRoot, selected, targetKeys, include) {
   const root = join50(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((candidate) => selected.has(candidate.rootId))) continue;
+    if (!lock.canonical.roots.some((candidate2) => selected.has(candidate2.rootId))) continue;
     const parts = relative8(root, path).split(/[\\/]/);
     if (parts.length !== 3) throw new Error(`Graph lock path is not canonical: ${path}`);
     const [targetKey2, adapter, fileName] = parts;
+    if (targetKeys && !targetKeys.has(targetKey2)) continue;
     const pathFingerprint = basename22(fileName, ".graph-lock.json");
     if (!lock.canonical.targetFingerprint || lock.canonical.targetFingerprint !== pathFingerprint) {
       throw new Error(`Graph lock fingerprint does not match its canonical path: ${path}`);
     }
-    const projection = relevantGraphProjection(lock, selected);
-    results.push({
+    const candidate = {
       path,
       lock,
-      digest: sha2564(canonicalJson2(projection)),
+      digest: "",
       allRootsSelected: lock.canonical.roots.every((rootEntry) => selected.has(rootEntry.rootId)),
-      artifactIdentities: lock.canonical.artifacts.filter((artifact) => artifact.owners.some((owner) => selected.has(owner))).map(graphArtifactIdentity).sort(),
+      artifactIdentities: [],
       targetKey: targetKey2,
       adapter
+    };
+    if (include && !await include(candidate)) continue;
+    const projection = relevantGraphProjection(lock, selected);
+    results.push({
+      ...candidate,
+      digest: sha2564(canonicalJson2(projection)),
+      artifactIdentities: lock.canonical.artifacts.filter((artifact) => artifact.owners.some((owner) => ownerMatchesGraphPackage(lock, owner, selected))).map(graphArtifactIdentity).sort()
     });
   }
   return results.sort((a, b) => a.path.localeCompare(b.path));
 }
+function isCurrentLocalTarget(scope, graph) {
+  const agent = scope.config.agents[graph.targetKey];
+  if (agent?.transport === "ssh") {
+    throw new Error(`Installed-state normalization cannot hand off SSH target '${graph.targetKey}' locally.`);
+  }
+  return Boolean(agent) || graph.targetKey === graph.adapter;
+}
+async function hasRelevantLegacyManifestCandidate(scope, graph, selected) {
+  if (!isCurrentLocalTarget(scope, graph)) return false;
+  const state = await legacyTargetStateForGraph(scope, graph);
+  const manifest = (await collectManifestPaths([state.manifestPath]))[0];
+  return manifest?.manifest.entries.some((entry) => entryMatchesGraphPackages(entry, graph.lock, selected)) ?? false;
+}
 async function targetStateForGraph(scope, graph, identityFleetId = scope.fleetId ?? null) {
   const agent = scope.config.agents[graph.targetKey];
   if (agent?.transport === "ssh") {
@@ -13906,6 +14001,40 @@ async function targetStateForGraph(scope, graph, identityFleetId = scope.fleetId
     manifestPath: installManifestPath(installRoot, adapter.name, { installationType, stateKey })
   };
 }
+async function legacyTargetStateForGraph(scope, graph) {
+  const current = await targetStateForGraph(scope, graph, null);
+  const targetFingerprint = graph.lock.canonical.targetFingerprint;
+  const stateKey = stateKeyFor(current.adapter, {
+    installationType: current.installationType,
+    targetFingerprint
+  });
+  return {
+    ...current,
+    stateKey,
+    targetFingerprint,
+    graphLockPath: graph.path,
+    manifestPath: installManifestPath(current.installRoot, current.adapter, {
+      installationType: current.installationType,
+      stateKey
+    })
+  };
+}
+function assertGraphIsSubset(source, destination) {
+  const sourceRoots = new Map(source.lock.canonical.roots.map((root) => [root.rootId, canonicalJson2(root)]));
+  for (const root of destination.lock.canonical.roots) {
+    if (sourceRoots.get(root.rootId) !== canonicalJson2(root)) {
+      throw new Error(
+        `Partially normalized destination graph diverges at root '${root.rootId}': ${destination.path}`
+      );
+    }
+  }
+  const sourceArtifacts = new Set(source.lock.canonical.artifacts.map(graphArtifactIdentity));
+  for (const artifact of destination.lock.canonical.artifacts) {
+    if (!sourceArtifacts.has(graphArtifactIdentity(artifact))) {
+      throw new Error(`Partially normalized destination graph contains divergent artifact state: ${destination.path}`);
+    }
+  }
+}
 function destinationGraphFromSource(source, targetFingerprint) {
   const sourceFingerprint = source.canonical.targetFingerprint;
   return {
@@ -14003,9 +14132,9 @@ function relevantGraphProjection(lock, selected) {
       }
     }
   }
-  const artifacts = lock.canonical.artifacts.filter((artifact) => artifact.owners.some((owner) => selected.has(owner)));
+  const artifacts = lock.canonical.artifacts.filter((artifact) => artifact.owners.some((owner) => ownerMatchesGraphPackage(lock, owner, selected)));
   for (const artifact of artifacts) {
-    if (artifact.owners.some((owner) => !selected.has(owner))) {
+    if (artifact.owners.some((owner) => !ownerMatchesGraphPackage(lock, owner, selected))) {
       throw new Error(`Graph artifact ${artifact.logicalSelector} has partial ownership outside the selected normalization packages.`);
     }
     nodeIds.add(artifact.graphNodeId);
@@ -14036,7 +14165,27 @@ function relevantManifestEntries(manifests, selected, owners) {
   return manifests.flatMap((manifest) => manifest.manifest.entries.filter((entry) => entryMatchesPackages(entry, selected) && owners.has(entry.workspaceOwner)).map((entry) => ({ manifest, entry, renderedPath: renderedEntryPath(manifest.manifest, entry) })));
 }
 function entryMatchesPackages(entry, selected) {
-  return entry.owners.some((owner) => selected.has(owner)) || (entry.packageName ? selected.has(entry.packageName) : false);
+  return entry.owners.some((owner) => ownerMatchesPackage(owner, selected)) || (entry.packageName ? selected.has(entry.packageName) : false);
+}
+function entryMatchesGraphPackages(entry, lock, selected) {
+  return entry.owners.some((owner) => ownerMatchesGraphPackage(lock, owner, selected)) || (entry.packageName ? selected.has(entry.packageName) : false);
+}
+function entryMatchesArtifacts(entry, selected) {
+  if (!selected) return true;
+  return selected.has(entry.logicalSelector ?? `${entry.artifactType}/${entry.artifactName}`) || selected.has(`${entry.artifactType}/${entry.artifactName}`);
+}
+function normalizeArtifactSelector(value) {
+  const selector = value.trim();
+  if (!/^[^/\s]+\/[^/\s]+$/.test(selector)) {
+    throw new Error(`Invalid --artifact selector '${value}'; expected type/name.`);
+  }
+  return selector;
+}
+function ownerMatchesPackage(owner, selected) {
+  return selected.has(owner) || owner.startsWith("workspace:") && selected.has(owner.slice("workspace:".length));
+}
+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 = resolve25(manifest.targetRoot);
@@ -14438,14 +14587,16 @@ fleetCommand.command("show").description("show one registered fleet").argument("
 Root: ${fleet.root}
 Required packages: ${fleet.requiredPackages.join(", ")}`);
 });
-fleetCommand.command("normalize").description("plan or apply duplicate desired-state ownership normalization").argument("<destinationFleet>", "destination fleet id").requiredOption("--from <scope>", "user or fleet:<sourceFleet>").option("--package <name>", "limit to one duplicate package (repeatable)", collectValueOption, []).option("--apply", "apply a reviewed plan", false).option("--recover", "restore source state from a pending normalization journal", false).option("--plan-digest <sha256>", "exact digest from the reviewed dry-run").option("--json", "print the plan or result as JSON", false).action(async (destinationFleet, options) => {
+fleetCommand.command("normalize").description("plan or apply duplicate desired-state ownership normalization").argument("<destinationFleet>", "destination fleet id").requiredOption("--from <scope>", "user or fleet:<sourceFleet>").option("--package <name>", "limit to one duplicate package (repeatable)", collectValueOption, []).option("--artifact <type/name>", "limit same-fleet ownership normalization to one artifact (repeatable)", collectValueOption, []).option("--profile <name>", "limit same-fleet installed-state normalization to one concrete profile").option("--apply", "apply a reviewed plan", false).option("--recover", "restore source state from a pending normalization journal", false).option("--plan-digest <sha256>", "exact digest from the reviewed dry-run").option("--json", "print the plan or result as JSON", false).action(async (destinationFleet, options) => {
   const request = {
     destinationFleet,
     from: options.from,
-    ...options.package.length > 0 ? { packages: options.package } : {}
+    ...options.package.length > 0 ? { packages: options.package } : {},
+    ...options.artifact.length > 0 ? { artifacts: options.artifact } : {},
+    ...options.profile ? { profile: options.profile } : {}
   };
-  if (options.recover && (options.apply || options.planDigest || options.package.length > 0)) {
-    throw new Error("--recover cannot be combined with --apply, --plan-digest, or --package.");
+  if (options.recover && (options.apply || options.planDigest || options.package.length > 0 || options.artifact.length > 0 || options.profile)) {
+    throw new Error("--recover cannot be combined with --apply, --plan-digest, --package, --artifact, or --profile.");
   }
   const result = options.recover ? await recoverFleetNormalization(request) : options.apply ? await applyFleetNormalization({ ...request, apply: true, planDigest: options.planDigest }) : await planFleetNormalization(request);
   console.log(options.json ? JSON.stringify(result, null, 2) : formatFleetNormalization(result));
@@ -15243,7 +15394,8 @@ async function packageSelectsSkillForTarget(target, pkg, selector, options) {
     scope: pkg.name,
     onlySource: true,
     dryRun: true,
-    suppressEmptyMessage: true
+    suppressEmptyMessage: true,
+    deferForeignStateCheck: true
   }, { mode: "install" });
   try {
     return results.some((result) => result.bundle.graphLock.canonical.roots.some(
@@ -15644,6 +15796,7 @@ async function buildGraphPlansForTarget(target, source, options, behavior) {
       forceDrift: targetOptions.forceDrift,
       forceConflict: targetOptions.forceConflict,
       forceForeignState: targetOptions.forceForeignState,
+      deferForeignStateCheck: targetOptions.deferForeignStateCheck === true || targetOptions.focusedArtifact !== void 0,
       replaceConflict: targetOptions.replaceConflict,
       retireExactMcp: targetOptions.retireExactMcp,
       expectedFromWorkspaceOwner: targetOptions.expectedFromWorkspaceOwner
@@ -15651,7 +15804,21 @@ async function buildGraphPlansForTarget(target, source, options, behavior) {
     if ((behavior.mode === "install" || behavior.mode === "update") && scopedRootId) {
       const state = installStateForTarget(group.target, adapter, group.adapterOptions, group.installationType);
       const manifest = await readInstallManifest(state.installRoot, adapter.name, transport, state);
-      results.push(targetOptions.focusedArtifact ? previousGroupLock ? scopeUpdatePlanToArtifact(result, scopedRootId, targetOptions.focusedArtifact, previousGroupLock, manifest) : scopeInstallPlanToArtifact(result, scopedRootId, targetOptions.focusedArtifact, manifest) : previousGroupLock ? scopeUpdatePlanToRoot(result, scopedRootId, previousGroupLock, manifest) : scopeInstallPlanToRoot(result, scopedRootId, manifest));
+      const scopedResult = targetOptions.focusedArtifact ? previousGroupLock ? scopeUpdatePlanToArtifact(result, scopedRootId, targetOptions.focusedArtifact, previousGroupLock, manifest) : scopeInstallPlanToArtifact(result, scopedRootId, targetOptions.focusedArtifact, manifest) : previousGroupLock ? scopeUpdatePlanToRoot(result, scopedRootId, previousGroupLock, manifest) : scopeInstallPlanToRoot(result, scopedRootId, manifest);
+      if (targetOptions.focusedArtifact && (targetOptions.forceForeignState !== true || group.target.fleetId)) {
+        const focusedPaths = scopedResult.plan.operations.filter((operation) => operationMatchesFocusedArtifact(
+          operation,
+          targetOptions.focusedArtifact,
+          focusedArtifactOwnerKeys(result.bundle.graphLock, previousGroupLock, scopedRootId, targetOptions.focusedArtifact)
+        )).map((operation) => operation.relativeDestPath);
+        await assertNoForeignWorkspaceStateForPlan(scopedResult.plan, {
+          transport,
+          workspaceRoot: group.target.workspaceRoot,
+          workspaceOwner: workspaceOwnerForRoot(group.target.workspaceRoot, group.target.fleetId),
+          plannedPaths: focusedPaths
+        });
+      }
+      results.push(scopedResult);
     } else if (scopedDependencyUpdate) {
       const state = installStateForTarget(group.target, adapter, group.adapterOptions, group.installationType);
       const manifest = await readInstallManifest(state.installRoot, adapter.name, transport, state);
@@ -15847,11 +16014,7 @@ function scopeUpdatePlanToArtifact(result, rootId, focused, previousLock, manife
 function scopePlanOperationsToArtifact(result, rootId, focused, manifest, previousLock) {
   const currentArtifacts = focusedArtifactsForRoot(result.bundle.graphLock, rootId, focused);
   const previousArtifacts = previousLock ? focusedArtifactsForRoot(previousLock, rootId, focused) : [];
-  const focusedOwnerKeys = /* @__PURE__ */ new Set([
-    `workspace:${rootId}`,
-    ...currentArtifacts.map((artifact) => artifact.graphNodeId),
-    ...previousArtifacts.map((artifact) => artifact.graphNodeId)
-  ]);
+  const focusedOwnerKeys = focusedArtifactOwnerKeys(result.bundle.graphLock, previousLock, rootId, focused);
   const manifestByPath = new Map((manifest?.entries ?? []).map((entry) => [entry.path, entry]));
   const plannedPaths = /* @__PURE__ */ new Set();
   const preservedPaths = /* @__PURE__ */ new Set();
@@ -15889,6 +16052,15 @@ function scopePlanOperationsToArtifact(result, rootId, focused, manifest, previo
     }
   };
 }
+function focusedArtifactOwnerKeys(currentLock, previousLock, rootId, focused) {
+  const currentArtifacts = focusedArtifactsForRoot(currentLock, rootId, focused);
+  const previousArtifacts = previousLock ? focusedArtifactsForRoot(previousLock, rootId, focused) : [];
+  return /* @__PURE__ */ new Set([
+    `workspace:${rootId}`,
+    ...currentArtifacts.map((artifact) => artifact.graphNodeId),
+    ...previousArtifacts.map((artifact) => artifact.graphNodeId)
+  ]);
+}
 function operationMatchesFocusedArtifact(operation, focused, ownerKeys) {
   if (!matchesCanonicalFocusedArtifact(operation.artifactType, operation.artifactName, focused)) {
     return false;
@@ -17066,11 +17238,13 @@ function formatFleetNormalization(result) {
   if ("recovered" in result) return `Recovered fleet normalization source state and removed journal: ${result.journalPath}`;
   if ("applied" in result) return `Applied fleet normalization ${result.planDigest}: ${result.packages.join(", ")}`;
   const packageArgs = result.packages.map((pkg) => `--package ${shellQuoteArg2(pkg.name)}`).join(" ");
+  const artifactArgs = result.request.artifacts?.map((artifact) => ` --artifact ${shellQuoteArg2(artifact)}`).join("") ?? "";
+  const profileArg = result.request.profile ? ` --profile ${shellQuoteArg2(result.request.profile)}` : "";
   return [
     `Fleet normalization plan: ${result.source.root} -> ${result.destination.root}`,
     `Packages: ${result.packages.map((pkg) => pkg.name).join(", ")}`,
     `Plan digest: ${result.planDigest}`,
-    `Apply: agentwheel fleet normalize ${result.destination.fleetId} --from ${result.request.from} ${packageArgs} --apply --plan-digest ${result.planDigest}`
+    `Apply: agentwheel fleet normalize ${result.destination.fleetId} --from ${result.request.from} ${packageArgs}${artifactArgs}${profileArg} --apply --plan-digest ${result.planDigest}`
   ].join("\n");
 }
 function shouldDefaultUserInstall(nameOrSource, options) {

package/openpack.json

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

package/package.json

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

package/skills/agentwheel/SKILL.md

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

package/skills/agentwheel-discovery/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: agentwheel-discovery
-description: MUST use proactively when a request describes repeated manual work, inconsistent results, lost information, a missing capability, or an unavailable integration—even if the user did not ask for a skill. Run Agentwheel semantic search before generic brainstorming or workflow advice, suggest up to three evidence-backed reusable skills or integrations, and offer a read-only trial without installing or changing anything.
+description: MUST use proactively when a request expresses an operational intent that an existing reusable skill or integration could plausibly fulfill—even if the user did not ask for a skill or describe a capability gap. Inspect installed artifacts, then run Agentwheel semantic search before generic or manual solution design when none already covers the intent. Suggest up to three evidence-backed matches and offer a read-only trial without installing or changing anything.
 allowed-tools: [Bash]
 license: MIT
 metadata:
   author: NestDevLab
-  version: "0.18.1"
+  version: "0.18.2"
 ---
 
 # Agentwheel Discovery
@@ -25,11 +25,12 @@ This skill is optional: install it only when proactive recommendations are wante
 
 ## When To Search
 
-Use this skill before generic brainstorming, planning, or workflow advice whenever the request
-describes repeated manual work, inconsistent outputs, lost information, a missing operational
-capability, or an unavailable integration. The user does not need to mention Agentwheel, skills,
-discovery, search, or a catalogue. Run the first semantic search in the same turn; do not merely
-describe a workflow and defer discovery.
+Use this skill whenever a request expresses an operational outcome that an existing reusable skill
+or integration could plausibly deliver. This includes repeated manual work, inconsistent outputs,
+lost information, missing capabilities, and unavailable integrations. The user does not need to
+mention Agentwheel, skills, discovery, search, a catalogue, or a capability gap. Search before
+generic brainstorming, planning, manual workflow advice, or an unsolicited custom solution. Run
+the first semantic search in the same turn; do not merely describe a workflow and defer discovery.
 
 This is a per-turn judgment, not a background monitor. Delegated agents follow the same trigger
 when this skill is available.

package/skills/agentwheel-smoke/scripts/smoke.mjs

@@ -20,7 +20,7 @@ if (parsed.error) {
 const config = findConfigs(cwd, home);
 const harness = detectHarness(skillRoot, cwd, home);
 const envHint = detectHarnessFromEnv();
-const agentwheel = inspectAgentwheel(parsed.statusArgs, envHint);
+const agentwheel = inspectAgentwheel(parsed.statusArgs, envHint, harness);
 const manifests = findStateFiles(harness.runtimeRoot ?? projectRootFromConfig(config.projectConfig) ?? cwd);
 const assessment = assess({ harness, agentwheel, manifests, config });
 const report = {
@@ -50,11 +50,11 @@ function parseArgs(args) {
       json = true;
       continue;
     }
-    if (["--all", "--all-detected"].includes(arg)) {
+    if (["--all", "--all-detected", "--user", "--local"].includes(arg)) {
       statusArgs.push(arg);
       continue;
     }
-    if (["--agent", "--profile", "--target-root", "--adapter", "--installation-type"].includes(arg)) {
+    if (["--agent", "--profile", "--target-root", "--adapter", "--installation-type", "--fleet"].includes(arg)) {
       const value = args[index + 1];
       if (!value || value.startsWith("--")) return { error: `${arg} requires a value.` };
       statusArgs.push(arg, value);
@@ -66,12 +66,14 @@ function parseArgs(args) {
   return { json, statusArgs };
 }
 
-function inspectAgentwheel(statusArgs, hint) {
+function inspectAgentwheel(statusArgs, hint, harness) {
   const which = run("command", ["-v", "agentwheel"], { shell: true });
   const version = which.ok ? run("agentwheel", ["--version"]) : { ok: false, code: null, stdout: "", stderr: "agentwheel not found" };
-  let effectiveStatusArgs = statusArgs;
+  let effectiveStatusArgs = hasWorkspaceScope(statusArgs)
+    ? statusArgs
+    : [...defaultWorkspaceScope(harness), ...statusArgs];
   let status = which.ok ? run("agentwheel", ["status", ...effectiveStatusArgs]) : { ok: false, code: null, stdout: "", stderr: "agentwheel not found" };
-  if (!status.ok && statusArgs.length === 0 && /Multiple runtime directories detected/i.test(status.stderr) && hint?.adapter) {
+  if (!status.ok && effectiveStatusArgs.length === 0 && /Multiple runtime directories detected/i.test(status.stderr) && hint?.adapter) {
     effectiveStatusArgs = ["--adapter", hint.adapter, "--installation-type", hint.installationType ?? "local"];
     status = run("agentwheel", ["status", ...effectiveStatusArgs]);
   }
@@ -90,6 +92,16 @@ function inspectAgentwheel(statusArgs, hint) {
   };
 }
 
+function hasWorkspaceScope(args) {
+  return args.some((arg) => ["--user", "--local", "--fleet", "--target-root"].includes(arg));
+}
+
+function defaultWorkspaceScope(harness) {
+  if (harness?.installationType === "user") return ["--user"];
+  if (harness?.installationType === "local") return ["--local"];
+  return [];
+}
+
 function run(command, args, options = {}) {
   try {
     const stdout = execFileSync(command, args, {