agentwheel 0.22.0 → 0.22.2

package/README.md

@@ -139,6 +139,25 @@ refused unless `--carry-drift` is passed: the dry-run prints the runtime hash, t
 `--expected-runtime-hash <sha256>`, and the manifest keeps the recorded hash so the next install
 still reports the drift. Merge and managed-block entries never carry drift.
 
+Qualify a Fleet-owned source with `--from-fleet <id>` together with its exact
+`--from-workspace-root`; use `--to-fleet <id>` for a Fleet-owned destination. Both IDs must
+be registered at the specified roots. These options qualify ownership, whereas `--fleet`
+selects the governing workspace. `--from-fleet` cannot be combined with
+`--from-unknown-owner`. For example, preview returning one entry to its original plain owner:
+
+```bash
+agentwheel ownership handoff skills/example-skill --local --agent local-codex --installation-type user \
+  --source-state-key codex.user.existing-state \
+  --from-workspace-root /fleet/control --from-fleet example-fleet \
+  --to-workspace-root /original/workspace --dry-run
+```
+
+Reverse handoffs require a fresh reviewed plan against the post-handoff state; they do not
+reuse old manifest revisions or erase audit history. For run-as targets, also pass the reviewed
+`--plan-digest` and `--expected-inventory-revision` when applying. The qualified old/new owner
+identities are included in the native plan, its digest and the audit. Each handoff changes the
+inventory revision, so review subsequent operations against their exact intermediate states.
+
 Use `--source-state-key <exact-key>` when an existing source manifest must be selected explicitly.
 This is a command-local equivalent of a named agent's `stateKey`; it does not edit agent configuration,
 move state files, or reconstruct graph locks. The key must be canonical and match the selected adapter
@@ -527,6 +546,23 @@ agentwheel ownership retire-stale \
   --fleet <fleet-id> --agent <agent> --json
 ```
 
+To use a target configured in a nested workspace while retiring ownership into its containing
+registered Fleet, run from that workspace and select the destination owner separately:
+
+```bash
+agentwheel ownership retire-stale --local --agent service-agent \
+  --to-fleet <fleet-id> --to-workspace-root <fleet-root> \
+  --from-workspace-root <stale-owner-root> \
+  --source-state-key <stale-state-key> \
+  --destination-state-key <fleet-owned-state-key> --json
+```
+
+`--to-fleet` qualifies the destination owner; `--local`, `--user`, or `--fleet` selects the target
+workspace and its configured transport. The selected workspace must be within the registered
+Fleet root, including after symlink resolution, and cannot identify a different Fleet.
+The original `--fleet <id>` command remains supported for targets configured directly at that
+Fleet root. Neither form changes agent configuration or relaxes contribution and revision guards.
+
 The dry-run still proves exact destination coverage and runtime bytes. Apply only its emitted command,
 which includes the plan, source, destination, and manifest-inventory revisions.
 For duplicate state owned by the same registered Fleet, set both workspace roots to the Fleet root

package/dist/index.js

@@ -797,11 +797,11 @@ function parseTree(text, errors = [], options = ParseOptions.DEFAULT) {
       onValue({ type: getNodeType(value), offset, length, parent: currentParent, value });
       ensurePropertyComplete(offset + length);
     },
-    onSeparator: (sep12, offset, length) => {
+    onSeparator: (sep13, offset, length) => {
       if (currentParent.type === "property") {
-        if (sep12 === ":") {
+        if (sep13 === ":") {
           currentParent.colonOffset = offset;
-        } else if (sep12 === ",") {
+        } else if (sep13 === ",") {
           ensurePropertyComplete(offset);
         }
       }
@@ -14730,14 +14730,14 @@ var init_artifact = __esm({
       include: external_exports.string().min(1),
       markers: external_exports.boolean().optional(),
       optional: external_exports.boolean().optional()
-    });
+    }).strict();
     packageCompositionRuleSchema = external_exports.object({
       target: external_exports.string().min(1),
       include: external_exports.string().min(1),
       exclude: external_exports.array(external_exports.string().min(1)).optional(),
       runtimes: external_exports.array(external_exports.string().min(1)).optional(),
       markers: external_exports.boolean().optional()
-    });
+    }).strict();
     packageSupersedesEntrySchema = external_exports.object({
       package: external_exports.string().min(1),
       selector: external_exports.string().min(1),
@@ -20415,6 +20415,7 @@ var init_transaction = __esm({
 
 // src/install/toml-merge.ts
 import { mkdir as mkdir8, readFile as readFile16, writeFile as writeFile8 } from "fs/promises";
+import { parse as parseToml } from "smol-toml";
 import { dirname as dirname13 } from "path";
 async function mergeCodexTomlMcp(sourcePath, destPath) {
   const source = JSON.parse(await readFile16(sourcePath, "utf8"));
@@ -20429,6 +20430,39 @@ function mismatchedCodexTomlMcpServers(source, currentContent) {
   const servers = extractMcpServers(source);
   return Object.entries(servers).filter(([name, server]) => extractMcpServerBlock(currentContent, name) !== formatMcpServer(name, server)).map(([name]) => name);
 }
+function mismatchedManagedCodexTomlMcpServers(source, currentContent) {
+  const servers = extractMcpServers(source);
+  let current;
+  try {
+    const parsed = parseToml(currentContent, { integersAsBigInt: "asNeeded" });
+    current = isPlainRecord(parsed.mcp_servers) ? parsed.mcp_servers : void 0;
+  } catch {
+    return Object.keys(servers);
+  }
+  return Object.entries(servers).filter(([name, server]) => {
+    try {
+      const rendered = parseToml(formatMcpServer(name, server), { integersAsBigInt: "asNeeded" });
+      const expected = isPlainRecord(rendered.mcp_servers) ? rendered.mcp_servers[name] : void 0;
+      return !current || !Object.hasOwn(current, name) || !managedValueMatches(current[name], expected);
+    } catch {
+      return true;
+    }
+  }).map(([name]) => name);
+}
+function managedValueMatches(actual, expected) {
+  if (Array.isArray(expected)) {
+    return Array.isArray(actual) && actual.length === expected.length && expected.every((value, index) => managedValueMatches(actual[index], value));
+  }
+  if (isPlainRecord(expected)) {
+    return isPlainRecord(actual) && Object.entries(expected).every(([key, value]) => Object.hasOwn(actual, key) && managedValueMatches(actual[key], value));
+  }
+  return actual === expected;
+}
+function isPlainRecord(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === null || prototype === Object.prototype;
+}
 function extractMcpServers(source) {
   const raw = isRecord2(source.mcpServers) ? source.mcpServers : source;
   const servers = {};
@@ -20617,8 +20651,18 @@ function assertExactMergeContribution(contribution, strategy, currentContent) {
     throw new MergeAdoptionMismatchError(`exact merge contribution differs or is missing at ${mismatch}`);
   }
 }
+function assertManagedMergeContribution(contribution, strategy, currentContent) {
+  if (strategy !== "codex-toml-mcp") {
+    assertExactMergeContribution(contribution, strategy, currentContent);
+    return;
+  }
+  const mismatched = mismatchedManagedCodexTomlMcpServers(contribution, currentContent);
+  if (mismatched.length > 0) {
+    throw new MergeAdoptionMismatchError(`managed MCP fields differ or are missing for ${mismatched.join(", ")}`);
+  }
+}
 async function assertMergedSourceContribution(sourcePath, strategy, currentContent) {
-  assertExactMergeContribution(await readMergeSource(sourcePath, strategy), strategy, currentContent);
+  assertManagedMergeContribution(await readMergeSource(sourcePath, strategy), strategy, currentContent);
 }
 function assertExactMcpMergeContribution(removal, strategy, currentContent) {
   if (strategy === "codex-toml-mcp") {
@@ -21813,7 +21857,9 @@ async function applyOperation(operation, context) {
       if (!await transport.pathExists(operation.destPath)) {
         throw new Error(`Merge skip destination disappeared after planning: ${operation.relativeDestPath}`);
       }
-      assertExactMergeContribution(operation.mergeRemoval, operation.mergeStrategy, await transport.readFile(operation.destPath));
+      const exactAdoption = operation.exactMergeAdoption === true || operation.reason === "force adopting exact unmanaged merge contribution" || operation.reason === "repairing exact incomplete merge ownership";
+      const verify = exactAdoption ? assertExactMergeContribution : assertManagedMergeContribution;
+      verify(operation.mergeRemoval, operation.mergeStrategy, await transport.readFile(operation.destPath));
       verifiedCurrentHash = await transport.hashPath(operation.destPath);
     } else if (!operation.semanticPlugin && !operation.programmaticOperation) {
       if (!await transport.pathExists(operation.destPath)) {
@@ -22448,7 +22494,7 @@ import { createHash as createHash32 } from "crypto";
 import { existsSync } from "fs";
 import { mkdir as mkdir28, mkdtemp as mkdtemp6, readFile as readFile45, realpath as realpath4, rm as rm16, writeFile as writeFile24 } from "fs/promises";
 import { homedir as homedir18, tmpdir as tmpdir7 } from "os";
-import { basename as basename24, dirname as dirname41, isAbsolute as isAbsolute17, join as join66, relative as relative22, resolve as resolve48 } from "path";
+import { basename as basename24, dirname as dirname41, isAbsolute as isAbsolute17, join as join66, relative as relative22, resolve as resolve48, sep as sep12 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { Command } from "commander";
 
@@ -23690,6 +23736,7 @@ async function createPlanFromOperations(desiredOps, adapter, targetRoot, manifes
           mergeCreatedDestination: existing2?.mergeCreatedDestination,
           currentHash: currentHash2,
           manifestHash: existing2?.hash,
+          exactMergeAdoption: true,
           reason: existing2 ? "repairing exact incomplete merge ownership" : "force adopting exact unmanaged merge contribution"
         });
         continue;
@@ -27082,7 +27129,8 @@ async function expandMarkdownIncludes(artifacts, packageRoot, options = {}) {
         entry,
         packageRoot,
         artifactPaths,
-        nodeId: options.nodeId
+        nodeId: options.nodeId,
+        packageName: options.packageName
       }));
       const externalEntries = isPrimaryMarkdownFile(artifact, file2) ? options.additionalComposeEntries?.(artifact) ?? [] : [];
       const result = await expandFile(file2, packageRoot, [...localEntries, ...externalEntries], artifactPaths, options);
@@ -27114,12 +27162,13 @@ async function expandFile(file2, packageRoot, appendEntries, artifactPaths, opti
   const expanded = await expandContent(raw, packageRoot, [owner], artifactPaths, options);
   let content = expanded.content;
   const composedFrom = [...expanded.composedFrom];
-  const appliedComposeIdentities = /* @__PURE__ */ new Set();
+  const appliedComposeIdentities = /* @__PURE__ */ new Map();
   for (const external of appendEntries) {
     const { entry } = external;
     const included = await expandInclude(entry.include, external.packageRoot, external.artifactPaths, {
       ...options,
       nodeId: external.nodeId,
+      packageName: external.packageName,
       optional: entry.optional === true,
       markers: entry.markers !== false,
       chain: [owner]
@@ -27127,10 +27176,15 @@ async function expandFile(file2, packageRoot, appendEntries, artifactPaths, opti
     if (!included) continue;
     const markerMode = entry.markers === false ? "plain" : "markers";
     const identity = `${markerMode}\0${included.identity}`;
-    if (external.deduplicate) {
-      if (appliedComposeIdentities.has(identity)) continue;
+    const previous = appliedComposeIdentities.get(identity);
+    if (external.deduplicate && previous) {
+      if (previous.hash !== included.hash) {
+        throw new Error(`Conflicting OpenPack composition revisions for ${included.selector}: ${previous.selector} (${previous.hash}) and ${included.selector} (${included.hash}). Select one revision explicitly.`);
+      }
+      composedFrom.push(...included.composedFrom);
+      continue;
     }
-    appliedComposeIdentities.add(identity);
+    appliedComposeIdentities.set(identity, { hash: included.hash, selector: included.selector });
     content = `${content.trimEnd()}
 
 ${included.rendered}
@@ -27150,6 +27204,7 @@ async function expandContent(content, packageRoot, chain, artifactPaths, options
   }
   const composedFrom = [];
   const replacements = [];
+  const semanticReplacements = [];
   for (const match of content.matchAll(includePattern)) {
     const selector = cleanSelector(match[2] ?? "");
     const included = await expandInclude(selector, packageRoot, artifactPaths, {
@@ -27163,13 +27218,14 @@ async function expandContent(content, packageRoot, chain, artifactPaths, options
       end: (match.index ?? 0) + match[0].length,
       value: included?.rendered ?? ""
     });
+    semanticReplacements.push({ start: match.index ?? 0, end: (match.index ?? 0) + match[0].length, value: included?.semanticContent ?? "" });
     if (included) composedFrom.push(...included.composedFrom);
   }
   let expanded = applyReplacements(content, replacements);
   expanded = expanded.replace(escapedIncludePattern, (_match, optional2, selector) => {
     return `<!-- openpack:include${optional2 ?? ""} ${cleanSelector(selector)} -->`;
   });
-  return { content: expanded, composedFrom: uniqueComposedFrom(composedFrom) };
+  return { content: expanded, semanticContent: applyReplacements(content, semanticReplacements), composedFrom: uniqueComposedFrom(composedFrom) };
 }
 async function expandInclude(selector, packageRoot, artifactPaths, options) {
   const parsed = parseOpenPackIncludeSelector(selector);
@@ -27178,6 +27234,7 @@ async function expandInclude(selector, packageRoot, artifactPaths, options) {
   let includePackageRoot = packageRoot;
   let includeArtifactPaths = artifactPaths;
   let includeNodeId = options.nodeId;
+  let includePackageName = options.packageName;
   let displaySelector = displaySelectorForInclude(parsed.selector, options.nodeId, options.originNodeId);
   if (parsed.alias) {
     if (!options.nodeId || !options.resolveCrossPackageInclude) {
@@ -27196,6 +27253,7 @@ async function expandInclude(selector, packageRoot, artifactPaths, options) {
     includePackageRoot = resolved.packageRoot;
     includeArtifactPaths = resolved.artifactPaths;
     includeNodeId = resolved.toNodeId;
+    includePackageName = resolved.packageName;
     displaySelector = `${resolved.toNodeId}:${parsed.selector}`;
   } else {
     sourcePath = artifactPaths.get(parsed.selector) ?? resolvePackageSelector(packageRoot, parsed.selector);
@@ -27215,13 +27273,14 @@ async function expandInclude(selector, packageRoot, artifactPaths, options) {
   const { optional: _optional2, markers: _markers, chain: _chain, ...childOptions } = options;
   const expanded = await expandContent(raw, includePackageRoot, [...options.chain, displaySelector], includeArtifactPaths, {
     ...childOptions,
-    nodeId: includeNodeId
+    nodeId: includeNodeId,
+    packageName: includePackageName
   });
   const contentHash = sha2563(expanded.content);
-  const identity = `${includeNodeId ?? resolve28(includePackageRoot)}\0${parsed.selector}\0${contentHash}`;
+  const identity = `${includePackageName ?? includeNodeId ?? resolve28(includePackageRoot)}\0${parsed.selector}`;
   const ownEntry = { selector: displaySelector, hash: contentHash };
   const composedFrom = uniqueComposedFrom([ownEntry, ...expanded.composedFrom]);
-  if (!options.markers) return { rendered: expanded.content, composedFrom, identity };
+  if (!options.markers) return { rendered: expanded.content, composedFrom, identity, hash: sha2563(expanded.semanticContent), selector: displaySelector, semanticContent: expanded.semanticContent };
   return {
     rendered: [
       `<!-- BEGIN openpack:include ${displaySelector} sha256:${contentHash.slice(0, markerHashLength)} -->`,
@@ -27229,7 +27288,10 @@ async function expandInclude(selector, packageRoot, artifactPaths, options) {
       `<!-- END openpack:include ${displaySelector} -->`
     ].join("\n"),
     composedFrom,
-    identity
+    identity,
+    hash: sha2563(expanded.semanticContent),
+    selector: displaySelector,
+    semanticContent: expanded.semanticContent
   };
 }
 function parseOpenPackIncludeSelector(selector) {
@@ -29497,6 +29559,7 @@ async function renderGraphIntoRoot(root, graph, targetContext) {
     const compositionArtifacts = runtimeArtifacts;
     const expandedArtifacts = await expandMarkdownIncludes(compositionArtifacts, staged.root, {
       nodeId: rawNode.node.id,
+      packageName: rawNode.node.name,
       originNodeId: rawNode.node.id,
       additionalComposeEntries: (artifact) => matchingCompositionEntries(
         artifact,
@@ -29534,6 +29597,7 @@ async function renderGraphIntoRoot(root, graph, targetContext) {
         includeEdges.set(`${includeEdge.fromNodeId}\0${includeEdge.alias}\0${includeEdge.toNodeId}\0${includeEdge.selector}\0${includeEdge.sourceHash}`, includeEdge);
         return {
           toNodeId: edge.to,
+          packageName: target.rawNode.node.name,
           packageRoot: target.root,
           artifactPaths: target.artifactPaths,
           sourcePath,
@@ -29621,6 +29685,7 @@ function matchingCompositionEntries(artifact, targetNodeId, runtime, rules) {
       packageRoot: candidate.packageRoot,
       artifactPaths: candidate.artifactPaths,
       nodeId: candidate.ownerNodeId,
+      packageName: candidate.ownerPackageName,
       deduplicate: true
     });
   }
@@ -32400,6 +32465,7 @@ init_adapter();
 init_transaction();
 init_transport();
 import { resolve as resolve40 } from "path";
+init_workspace();
 var unknownWorkspaceOwner = "workspace:unknown";
 async function planArtifactOwnershipHandoff(request) {
   return validateOwnershipHandoff(request, request.transport ?? localTransport);
@@ -32461,6 +32527,11 @@ async function applyArtifactOwnershipHandoff(request) {
   }
 }
 async function validateOwnershipHandoff(request, transport) {
+  if (request.fromFleetId !== void 0 && (request.fromWorkspaceRoot === void 0 || request.fromUnknownOwner === true)) {
+    throw new Error("A source fleet requires fromWorkspaceRoot and cannot be combined with fromUnknownOwner.");
+  }
+  if (request.fromFleetId !== void 0) fleetIdSchema.parse(request.fromFleetId);
+  if (request.toFleetId !== void 0) fleetIdSchema.parse(request.toFleetId);
   const endpoint = ownershipRunAsEndpoint(transport, request.targetRoot);
   if (request.expectedHash) assertSha256(request.expectedHash, "expected artifact hash");
   if (request.expectedRevision) assertSha256(request.expectedRevision, "expected manifest revision");
@@ -32488,7 +32559,7 @@ async function validateOwnershipHandoff(request, transport) {
     );
   }
   const entry = matches[0];
-  const fromOwner = request.fromUnknownOwner === true ? unknownWorkspaceOwner : workspaceOwnerForRoot(request.fromWorkspaceRoot);
+  const fromOwner = request.fromUnknownOwner === true ? unknownWorkspaceOwner : workspaceOwnerForRoot(request.fromWorkspaceRoot, request.fromFleetId);
   const toOwner = workspaceOwnerForRoot(request.toWorkspaceRoot, request.toFleetId);
   if (fromOwner === toOwner) throw new Error("Ownership handoff requires different workspace roots.");
   if (entry.workspaceOwner !== fromOwner) {
@@ -37371,13 +37442,28 @@ ownershipCommand.command("release-claim").description("release one exact plain o
   console.log(`Plan digest: ${result.planDigest}`);
   if (!options.apply) console.log("Apply with this same scope and reason plus --apply --plan-digest, --expected-source-revision and --expected-inventory-revision from this plan.");
 });
-ownershipCommand.command("handoff").description("transfer one managed artifact between Agentwheel workspace roots").argument("<selector>", "exact artifact selector in type/name form").option("--from-workspace-root <path>", "current owning workspace root").option("--from-unknown-owner", "hand off an artifact recorded as workspace:unknown", false).requiredOption("--to-workspace-root <path>", "new owning workspace root").option("--source-state-key <key>", "explicit source install-manifest state key for this handoff only").option("--to-fleet <id>", "qualify the new owner with a registered fleet id").option("--expected-hash <sha256>", "expected recorded artifact hash; required when applying").option("--expected-revision <sha256>", "expected install manifest revision; required when applying").option("--plan-digest <sha256>", "reviewed plan digest; required for run-as handoff").option("--expected-inventory-revision <sha256>", "reviewed full inventory revision; required for run-as handoff").option("--carry-drift", "accept a file or directory whose runtime differs from the recorded hash; the recorded hash is kept", false).option("--expected-runtime-hash <sha256>", "expected drifted runtime hash; required when applying with --carry-drift").option("--adapter <adapter>", "built-in adapter").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("--profile <name>", "workspace runtime profile (must resolve to one target)").option("--dry-run", "validate all preconditions without writing the manifest", false).option("--json", "print the complete deterministic ownership handoff plan", false).action(async (selector, options) => {
+ownershipCommand.command("handoff").description("transfer one managed artifact between Agentwheel workspace roots").argument("<selector>", "exact artifact selector in type/name form").option("--from-workspace-root <path>", "current owning workspace root").option("--from-fleet <id>", "qualify the current owner with a registered fleet id").option("--from-unknown-owner", "hand off an artifact recorded as workspace:unknown", false).requiredOption("--to-workspace-root <path>", "new owning workspace root").option("--source-state-key <key>", "explicit source install-manifest state key for this handoff only").option("--to-fleet <id>", "qualify the new owner with a registered fleet id").option("--expected-hash <sha256>", "expected recorded artifact hash; required when applying").option("--expected-revision <sha256>", "expected install manifest revision; required when applying").option("--plan-digest <sha256>", "reviewed plan digest; required for run-as handoff").option("--expected-inventory-revision <sha256>", "reviewed full inventory revision; required for run-as handoff").option("--carry-drift", "accept a file or directory whose runtime differs from the recorded hash; the recorded hash is kept", false).option("--expected-runtime-hash <sha256>", "expected drifted runtime hash; required when applying with --carry-drift").option("--adapter <adapter>", "built-in adapter").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("--profile <name>", "workspace runtime profile (must resolve to one target)").option("--dry-run", "validate all preconditions without writing the manifest", false).option("--json", "print the complete deterministic ownership handoff plan", false).action(async (selector, options) => {
   if (!options.dryRun && (!options.expectedHash || !options.expectedRevision)) {
     throw new Error("Applying an ownership handoff requires --expected-hash and --expected-revision from a reviewed --dry-run.");
   }
   if (Boolean(options.fromWorkspaceRoot) === (options.fromUnknownOwner === true)) {
     throw new Error("Ownership handoff requires exactly one of --from-workspace-root or --from-unknown-owner.");
   }
+  if (options.fromFleet !== void 0 && (!options.fromWorkspaceRoot || options.fromUnknownOwner)) {
+    throw new Error("--from-fleet requires --from-workspace-root and cannot be combined with --from-unknown-owner.");
+  }
+  const fromWorkspaceRoot = options.fromWorkspaceRoot === void 0 ? void 0 : normalizeCliPath(options.fromWorkspaceRoot);
+  const toWorkspaceRoot = normalizeCliPath(options.toWorkspaceRoot);
+  for (const [id, root, label] of [
+    [options.fromFleet, fromWorkspaceRoot, "Source"],
+    [options.toFleet, toWorkspaceRoot, "Destination"]
+  ]) {
+    if (id === void 0) continue;
+    const fleet = await showRegisteredFleet(id);
+    if (resolve48(fleet.root) !== resolve48(root)) {
+      throw new Error(`${label} fleet '${id}' is registered at ${fleet.root}, not ${root}.`);
+    }
+  }
   const normalizedOptions = normalizeRuntimeScopeOptions(options);
   const targets = await resolveCliTargets(normalizedOptions);
   if (targets.length !== 1) {
@@ -37401,13 +37487,6 @@ ownershipCommand.command("handoff").description("transfer one managed artifact b
       "Migrate the target state before ownership handoff by running a full agentwheel install for this target."
     );
   }
-  const toWorkspaceRoot = normalizeCliPath(options.toWorkspaceRoot);
-  if (options.toFleet) {
-    const fleet = await showRegisteredFleet(options.toFleet);
-    if (resolve48(fleet.root) !== resolve48(toWorkspaceRoot)) {
-      throw new Error(`Destination fleet '${options.toFleet}' is registered at ${fleet.root}, not ${toWorkspaceRoot}.`);
-    }
-  }
   const request = {
     workspaceRoot: await workspaceRootFromOptions(normalizedOptions),
     reason: options.reason,
@@ -37419,7 +37498,7 @@ ownershipCommand.command("handoff").description("transfer one managed artifact b
     adapter: adapter.name,
     artifactType,
     artifactName,
-    ...options.fromUnknownOwner === true ? { fromUnknownOwner: true } : { fromWorkspaceRoot: normalizeCliPath(options.fromWorkspaceRoot) },
+    ...options.fromUnknownOwner === true ? { fromUnknownOwner: true } : { fromWorkspaceRoot, fromFleetId: options.fromFleet },
     toWorkspaceRoot,
     toFleetId: options.toFleet,
     expectedHash: options.expectedHash,
@@ -37485,20 +37564,43 @@ ownershipCommand.command("recovery-plan").description("write a read-only per-pat
     console.log(JSON.stringify(report.counts));
   });
 });
-ownershipCommand.command("retire-stale").description("retire stale source-manifest ownership already covered by one Fleet manifest").requiredOption("--from-workspace-root <path>", "exact stale workspace owner root").option("--from-fleet-id <id>", "exact stale Fleet owner id for same-Fleet duplicate state").requiredOption("--to-workspace-root <path>", "registered destination Fleet root").requiredOption("--source-state-key <key>", "exact source install-manifest state key").option("--destination-state-key <key>", "exact Fleet-owned destination install-manifest state key (defaults to the stable target state)").requiredOption("--fleet <id>", "registered destination Fleet").option("--adapter <adapter>", "built-in adapter").option("-i, --installation-type <type>", "installation type (for example local or user)").option("--adapter-config <path>", "adapter JSON/JSONC file").option("--adapter-module <path>", "local programmatic adapter module").option("--allow-adapter-code", "allow loading local adapter code", false).option("-t, --target-root <path>", "runtime/project root").option("--agent <name>", "named destination Fleet agent").option("--profile <name>", "destination Fleet profile resolving to one target").option("--plan-digest <sha256>", "reviewed plan digest; required with --apply").option("--expected-source-revision <sha256>", "reviewed source manifest revision; required with --apply").option("--expected-destination-revision <sha256>", "reviewed destination manifest revision; required with --apply").option("--expected-inventory-revision <sha256>", "reviewed runtime manifest inventory revision; required with --apply").option("--abandon-incomplete-merge-owner", "explicitly retire incomplete legacy merge metadata without changing runtime bytes", false).option("--apply", "apply the exact reviewed metadata-only retirement", false).option("--json", "print the complete deterministic plan as JSON", false).action(async (options) => {
+ownershipCommand.command("retire-stale").description("retire stale source-manifest ownership already covered by one Fleet manifest").requiredOption("--from-workspace-root <path>", "exact stale workspace owner root").option("--from-fleet-id <id>", "exact stale Fleet owner id for same-Fleet duplicate state").requiredOption("--to-workspace-root <path>", "registered destination Fleet root").requiredOption("--source-state-key <key>", "exact source install-manifest state key").option("--destination-state-key <key>", "exact Fleet-owned destination install-manifest state key (defaults to the stable target state)").option("--to-fleet <id>", "registered destination Fleet owner, independent of target workspace scope").option("--user", "use the user workspace", false).option("--local", "use the nearest local workspace", false).option("--fleet <id>", "use one registered named fleet (also the destination owner unless --to-fleet is set)").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 destinationFleet = options.toFleet ?? options.fleet;
+  if (!destinationFleet) throw new Error("Stale ownership retirement requires --to-fleet <id> or the legacy --fleet <id> scope.");
+  const fleet = await showRegisteredFleet(destinationFleet);
   const toWorkspaceRoot = normalizeCliPath(options.toWorkspaceRoot);
   if (resolve48(fleet.root) !== resolve48(toWorkspaceRoot)) {
-    throw new Error(`Destination Fleet '${options.fleet}' is registered at ${fleet.root}, not ${toWorkspaceRoot}.`);
+    throw new Error(`Destination Fleet '${destinationFleet}' is registered at ${fleet.root}, not ${toWorkspaceRoot}.`);
+  }
+  const assertDestinationWorkspace = async (workspaceRoot, fleetId) => {
+    const fleetRoot = resolve48(fleet.root);
+    const canonicalFleetRoot = await realpath4(fleetRoot);
+    const within = (root, path) => {
+      const suffix = relative22(root, path);
+      return suffix === "" || suffix !== ".." && !suffix.startsWith(`..${sep12}`) && !isAbsolute17(suffix);
+    };
+    if (canonicalFleetRoot !== fleetRoot || fleetId !== void 0 && fleetId !== fleet.id || !within(fleetRoot, resolve48(workspaceRoot)) || !within(canonicalFleetRoot, await realpath4(workspaceRoot))) {
+      throw new Error(`Resolved target workspace does not belong to destination Fleet '${fleet.id}'.`);
+    }
+  };
+  if (options.toFleet) {
+    await resolveWorkspaceScope({ fleet: fleet.id });
+    if (normalizedOptions.targetRoot && !normalizedOptions.workspaceTargetDerived) {
+      await assertDestinationWorkspace(normalizedOptions.targetRoot);
+    }
+    const scope = await resolveCliWorkspaceScope(normalizedOptions);
+    await assertDestinationWorkspace(scope.root, scope.fleetId);
   }
   const targets = await resolveCliTargets(normalizedOptions);
   if (targets.length !== 1) {
     throw new Error(`Stale ownership retirement requires exactly one destination Fleet target, found ${targets.length}.`);
   }
   const target = targets[0];
-  if (target.fleetId !== options.fleet || resolve48(target.workspaceRoot) !== resolve48(fleet.root)) {
-    throw new Error(`Resolved target does not belong to destination Fleet '${options.fleet}'.`);
+  if (options.toFleet) {
+    await assertDestinationWorkspace(target.workspaceRoot, target.fleetId);
+  } else if (target.fleetId !== fleet.id || resolve48(target.workspaceRoot) !== resolve48(fleet.root)) {
+    throw new Error(`Resolved target does not belong to destination Fleet '${fleet.id}'.`);
   }
   const adapterOptions = adapterOptionsForTarget(target, normalizedOptions);
   const adapter = await resolveAdapterForTarget(target, adapterOptions);
@@ -37522,7 +37624,8 @@ ownershipCommand.command("retire-stale").description("retire stale source-manife
     transport: transportForTarget(target)
   };
   const result = options.apply ? await applyRetireStaleOwnership(request) : await planRetireStaleOwnership(request);
-  const targetArgs = options.profile ? ["--profile", options.profile] : target.agentName ? ["--agent", target.agentName] : ["--adapter", adapter.name, "--target-root", target.targetRoot];
+  const workspaceArgs = options.toFleet ? options.fleet ? ["--fleet", options.fleet] : options.user ? ["--user"] : options.targetRoot ? [] : ["--local"] : ["--fleet", fleet.id];
+  const targetArgs = options.profile ? ["--profile", options.profile] : target.agentName ? ["--agent", target.agentName] : ["--adapter", adapter.name, ...workspaceArgs.length ? [] : ["--target-root", target.targetRoot]];
   const applyArgs = [
     "agentwheel",
     "ownership",
@@ -37536,8 +37639,9 @@ ownershipCommand.command("retire-stale").description("retire stale source-manife
     request.sourceStateKey,
     "--destination-state-key",
     request.destinationStateKey,
-    "--fleet",
-    request.toFleetId,
+    ...options.toFleet ? ["--to-fleet", request.toFleetId] : [],
+    ...workspaceArgs,
+    ...(options.profile || target.agentName) && options.targetRoot ? ["--target-root", normalizedOptions.targetRoot] : [],
     ...targetArgs,
     "--installation-type",
     installationType,
@@ -38777,13 +38881,23 @@ function preserveUnrelatedGraphPackages(current, previous, selectedCurrentNodeId
   for (const root of selectedCurrentRoots) {
     if (!previous.canonical.roots.some((candidate) => candidate.rootId === root.rootId)) roots.push(root);
   }
+  const preservedNodeIds = /* @__PURE__ */ new Set();
+  if (selectedRootIds.size > 0) {
+    for (const root of previous.canonical.roots) {
+      if (!selectedRootIds.has(root.rootId)) {
+        for (const id of graphRootClosure(previous, root.rootId)) preservedNodeIds.add(id);
+      }
+    }
+  }
+  const replacedOwners = new Set([...selectedPreviousNodeIds].filter((id) => !preservedNodeIds.has(id)));
+  for (const id of selectedRootIds) replacedOwners.add(`workspace:${id}`);
   const currentNodes = current.canonical.nodes.filter((node) => selectedCurrentNodeIds.has(node.id));
-  const previousNodes = previous.canonical.nodes.filter((node) => !selectedPreviousNodeIds.has(node.id));
+  const previousNodes = previous.canonical.nodes.filter((node) => !selectedPreviousNodeIds.has(node.id) || preservedNodeIds.has(node.id)).map((node) => ({ ...node, requiredBy: node.requiredBy.filter((owner) => !replacedOwners.has(owner)) }));
   const selectedCurrentArtifacts = current.canonical.artifacts.filter((artifact) => selectedCurrentNodeIds.has(artifact.graphNodeId));
-  const previousArtifacts = previous.canonical.artifacts.filter((artifact) => !selectedPreviousNodeIds.has(artifact.graphNodeId));
+  const previousArtifacts = previous.canonical.artifacts.filter((artifact) => !selectedPreviousNodeIds.has(artifact.graphNodeId) || preservedNodeIds.has(artifact.graphNodeId)).map((artifact) => ({ ...artifact, owners: artifact.owners.filter((owner) => !replacedOwners.has(owner)) }));
   const edgeTouchesSelected = (from, to) => selectedCurrentNodeIds.has(from) || selectedCurrentNodeIds.has(to);
-  const previousEdge = (edge) => !selectedPreviousNodeIds.has(edge.from) && !selectedPreviousNodeIds.has(edge.to);
-  const previousIncludeEdge = (edge) => !selectedPreviousNodeIds.has(edge.fromNodeId) && !selectedPreviousNodeIds.has(edge.toNodeId);
+  const previousEdge = (edge) => preservedNodeIds.has(edge.from) || !selectedPreviousNodeIds.has(edge.from) && !selectedPreviousNodeIds.has(edge.to);
+  const previousIncludeEdge = (edge) => preservedNodeIds.has(edge.fromNodeId) || !selectedPreviousNodeIds.has(edge.fromNodeId) && !selectedPreviousNodeIds.has(edge.toNodeId);
   const selectedCurrentRootIds = new Set(selectedCurrentRoots.map((root) => root.graphNodeId));
   const currentRootOrNode = (id) => selectedCurrentNodeIds.has(id) || selectedCurrentRootIds.has(id);
   const previousRootOrNode = (id) => selectedPreviousNodeIds.has(id) || previous.canonical.roots.some((root) => selectedRootIds.has(root.rootId) && root.graphNodeId === id);
@@ -38792,28 +38906,38 @@ function preserveUnrelatedGraphPackages(current, previous, selectedCurrentNodeId
     canonical: {
       ...current.canonical,
       roots,
-      nodes: [...currentNodes, ...previousNodes],
-      edges: [
+      nodes: uniqueBy([...currentNodes.map((node) => {
+        const old = previousNodes.find((candidate) => candidate.id === node.id);
+        return old ? {
+          ...node,
+          requiredBy: sortedUniqueValues([...node.requiredBy, ...old.requiredBy]),
+          selected: sortedUniqueValues([...node.selected, ...old.selected])
+        } : node;
+      }), ...previousNodes], (node) => node.id),
+      edges: uniqueBy([
         ...current.canonical.edges.filter((edge) => edgeTouchesSelected(edge.from, edge.to)),
         ...previous.canonical.edges.filter(previousEdge)
-      ],
-      includeEdges: [
+      ], (edge) => `${edge.from}\0${edge.alias}\0${edge.to}`),
+      includeEdges: uniqueBy([
         ...current.canonical.includeEdges.filter((edge) => edgeTouchesSelected(edge.fromNodeId, edge.toNodeId)),
         ...previous.canonical.includeEdges.filter(previousIncludeEdge)
-      ],
-      artifacts: [...selectedCurrentArtifacts, ...previousArtifacts],
-      namespacing: [
+      ], graphIncludeEdgeIdentity),
+      artifacts: uniqueBy([...selectedCurrentArtifacts.map((artifact) => {
+        const old = previousArtifacts.find((candidate) => graphArtifactIdentity2(candidate) === graphArtifactIdentity2(artifact));
+        return old ? { ...artifact, owners: sortedUniqueValues([...artifact.owners, ...old.owners]) } : artifact;
+      }), ...previousArtifacts], graphArtifactIdentity2),
+      namespacing: uniqueBy([
         ...current.canonical.namespacing.filter((entry) => currentRootOrNode(entry.graphNodeId)),
-        ...previous.canonical.namespacing.filter((entry) => !previousRootOrNode(entry.graphNodeId))
-      ],
-      overrides: [
+        ...previous.canonical.namespacing.filter((entry) => !previousRootOrNode(entry.graphNodeId) || preservedNodeIds.has(entry.graphNodeId))
+      ], (entry) => `${entry.graphNodeId}\0${entry.type}\0${entry.name}`),
+      overrides: uniqueBy([
         ...current.canonical.overrides.filter((entry) => currentRootOrNode(entry.graphNodeId) || currentRootOrNode(entry.overriddenGraphNodeId)),
-        ...previous.canonical.overrides.filter((entry) => !previousRootOrNode(entry.graphNodeId) && !previousRootOrNode(entry.overriddenGraphNodeId))
-      ],
-      plainNameIncumbents: [
+        ...previous.canonical.overrides.filter((entry) => !selectedRootIds.has(entry.rootId) && (!previousRootOrNode(entry.graphNodeId) && !previousRootOrNode(entry.overriddenGraphNodeId) || preservedNodeIds.has(entry.graphNodeId)))
+      ], (entry) => `${entry.rootId}\0${entry.selector}`),
+      plainNameIncumbents: uniqueBy([
         ...current.canonical.plainNameIncumbents.filter((entry) => currentRootOrNode(entry.graphNodeId)),
-        ...previous.canonical.plainNameIncumbents.filter((entry) => !previousRootOrNode(entry.graphNodeId))
-      ]
+        ...previous.canonical.plainNameIncumbents.filter((entry) => !previousRootOrNode(entry.graphNodeId) || preservedNodeIds.has(entry.graphNodeId))
+      ], (entry) => `${entry.adapter}\0${entry.targetFingerprint}\0${entry.type}\0${entry.name}`)
     }
   });
 }
@@ -39143,16 +39267,31 @@ function uniqueBy(values, key) {
     return true;
   });
 }
-function scopeInstallPlanToRoot(result, rootId, manifest) {
+function scopeInstallPlanToRoot(result, rootId, manifest, previousLock) {
   const scopedOwners = scopedGraphOwnerKeys(result, rootId);
+  const exclusiveOwners = new Set(scopedOwners);
+  if (previousLock) {
+    for (const id of graphRootClosure(previousLock, rootId)) exclusiveOwners.add(id);
+    for (const root of previousLock.canonical.roots) {
+      if (root.rootId === rootId) continue;
+      for (const id of graphRootClosure(previousLock, root.rootId)) exclusiveOwners.delete(id);
+    }
+  }
   const manifestByPath = new Map((manifest?.entries ?? []).map((entry) => [entry.path, entry]));
   const preservedPaths = /* @__PURE__ */ new Set();
   const plannedPaths = /* @__PURE__ */ new Set();
   const operations = [];
   for (const operation of result.plan.operations) {
     plannedPaths.add(operation.relativeDestPath);
-    if (operationBelongsToScopedRoot(operation, scopedOwners)) {
-      operations.push(operation);
+    const stale = operation.action === "remove" || operation.action === "drift" && !operation.desiredHash;
+    const exclusivelyOwned = operation.owners?.length && operation.owners.every((owner) => exclusiveOwners.has(owner));
+    if (stale ? exclusivelyOwned : operationBelongsToScopedRoot(operation, scopedOwners)) {
+      const entry2 = manifestByPath.get(operation.relativeDestPath);
+      const foreignOwners = entry2 && "owners" in entry2 && Array.isArray(entry2.owners) ? entry2.owners.filter((owner) => typeof owner === "string" && !exclusiveOwners.has(owner)) : [];
+      operations.push(stale || !operation.owners ? operation : {
+        ...operation,
+        owners: sortedUniqueValues([...operation.owners, ...foreignOwners])
+      });
       continue;
     }
     const entry = manifestByPath.get(operation.relativeDestPath);
@@ -39178,7 +39317,7 @@ function scopeInstallPlanToRoot(result, rootId, manifest) {
   };
 }
 function scopeUpdatePlanToRoot(result, rootId, previousLock, manifest) {
-  const scoped = scopeInstallPlanToRoot(result, rootId, manifest);
+  const scoped = scopeInstallPlanToRoot(result, rootId, manifest, previousLock);
   const selectedCurrentNodeIds = graphRootClosure(scoped.bundle.graphLock, rootId);
   const selectedPreviousNodeIds = graphRootClosure(previousLock, rootId);
   const graphLock = preserveUnrelatedGraphPackages(

package/openpack.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwheel",
-  "version": "0.22.0",
+  "version": "0.22.2",
   "description": "Weave skills, rules, and instructions across every AI agent.",
   "type": "module",
   "license": "MIT",
@@ -53,6 +53,7 @@
     "@skillkit/core": "1.24.0",
     "commander": "14.0.2",
     "jsonc-parser": "3.3.1",
+    "smol-toml": "1.9.1",
     "typescript": "5.9.3",
     "yaml": "2.8.2",
     "zod": "4.1.13"

package/skills/agentwheel/SKILL.md

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

package/skills/agentwheel-discovery/SKILL.md

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