agentwheel 0.20.17 → 0.20.18

package/README.md

@@ -471,6 +471,35 @@ when every source entry is covered, apply removes the old manifest and source lo
 runtime files or the stable manifest. Preserve copies of those old state files before applying a
 retirement when they are needed as historical evidence.
 
+A nested, non-Fleet workspace (for example a profile checked out beneath a registered Fleet root)
+can inherit paths that older installs claimed under a fingerprint-only state key. Those claims name
+another plain workspace root, or this workspace's own root from before it was Fleet-qualified, so
+install refuses them as foreign. Adopt them into this workspace's stable state without
+`--force-foreign-state`, running from the workspace that owns the target:
+
+```bash
+agentwheel ownership adopt-legacy --agent <agent> \
+  --source-state-key <adapter>.<installation-type>.<legacy-fingerprint> \
+  --from-workspace-root <previous-owner-root> --json
+```
+
+The dry-run proves each moved entry: the previous owner root must hold a graph lock named by the
+legacy fingerprint, and for another workspace root exactly one such lock must match the entry's
+graph-lock digest, node, selector, and source hash. Only entries the current graph still installs at
+the same path with the same artifact identity move; the rest stay in the source manifest and are
+listed. The current graph groups packages as install does, by installation type and adapter
+configuration, and the command refuses when they resolve to more than one install state or when
+`--installation-type`, `--adapter-config`, or `--adapter-module` differs from what install resolves.
+Runtime bytes must match the recorded hash unless `--carry-drift` keeps that hash, so the next
+install reports drift instead of overwriting local changes. A path another owner still claims blocks the
+plan. A duplicate claim by the same previous owner is listed only when it sits under another legacy
+key of that root with the same proof and the same recorded artifact and hashes; run the command
+again with that key to retire it. Any other duplicate, including one in that root's current state,
+blocks the plan. Apply only the emitted command. It writes the stable manifest first and the legacy
+manifest second, and changes nothing else. A pending apply journal blocks the command. If an apply
+stops after the stable manifest was written, run the dry-run again: paths already in the stable
+state are then retired from the legacy key.
+
 ## Core Ideas
 
 **Three places, one direction:**