agentwheel 0.21.4 → 0.21.6

package/README.md

@@ -139,6 +139,23 @@ 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.
 
+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
+and installation type. The existing target identity, source owner, exact merge contribution, hash,
+revision, pending-journal and migration guards still apply. For example:
+
+```bash
+agentwheel ownership handoff mcp/example.json --local --agent local-codex \
+  --source-state-key codex.user.existing-state \
+  --from-workspace-root /old/workspace --to-workspace-root /new/workspace --dry-run
+```
+
+Apply only the same reviewed selection with `--expected-hash` and `--expected-revision`. An explicit
+key is never inferred from other claims and does not allow incomplete merge ownership or drift to
+be carried for merge artifacts.
+
+
 For a one-time MCP rename, keep the legacy artifact in a dedicated cutover workspace rather than
 the canonical desired-state profile. Set the legacy manifest `stateKey` on its named agent, then
 preview one runtime at a time:

package/dist/index.js

@@ -20032,7 +20032,7 @@ async function inspectInstalledState(source, destination, packageNames) {
       if (!sourceGraphArtifacts.has(graphEntryIdentity(sourceEntry.entry))) {
         throw new Error(`Source manifest entry is not covered by its graph lock: ${sourceEntry.renderedPath}`);
       }
-      if (sourceEntry.entry.owners.some((owner) => !selected.has(owner))) {
+      if (sourceEntry.entry.owners.some((owner) => !ownerMatchesPackage(owner, selected))) {
         throw new Error(`Partial ownership at ${sourceEntry.renderedPath} includes packages outside the normalization selection.`);
       }
       const destinationRenderedPath = renderedEntryPathForRoot(destinationState.installRoot, sourceEntry.entry.path);
@@ -21682,7 +21682,7 @@ 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("--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("--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).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-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("--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).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.");
   }
@@ -21698,9 +21698,15 @@ ownershipCommand.command("handoff").description("transfer one managed artifact b
   if (!artifactType || !artifactName || extra.length > 0) {
     throw new Error(`Ownership handoff selector must be exactly type/name: ${selector}`);
   }
-  const target = targets[0];
+  const target = options.sourceStateKey === void 0 ? targets[0] : { ...targets[0], stateKey: options.sourceStateKey };
+  if (options.sourceStateKey !== void 0 && (stateKeyFor(target.adapter, { stateKey: options.sourceStateKey }) !== options.sourceStateKey || !options.sourceStateKey.startsWith(`${target.adapter}.`))) {
+    throw new Error("The source state key must be exact, canonical, and scoped to the selected adapter.");
+  }
   const state = await resolveCliTargetState(target, normalizedOptions);
   const { adapter, installationType } = state;
+  if (options.sourceStateKey !== void 0 && options.sourceStateKey !== `${adapter.name}.${installationType}` && !options.sourceStateKey.startsWith(`${adapter.name}.${installationType}.`)) {
+    throw new Error("The source state key must match the selected installation type.");
+  }
   if (state.migration) {
     throw new Error(
       "Migrate the target state before ownership handoff by running a full agentwheel install for this target."

package/openpack.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwheel",
-  "version": "0.21.4",
+  "version": "0.21.6",
   "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.21.4"
+  version: "0.21.6"
 ---
 
 # agentwheel

package/skills/agentwheel-discovery/SKILL.md

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