agentwheel 0.20.16 → 0.20.18

package/README.md

@@ -461,6 +461,44 @@ agentwheel ownership retire-stale \
 
 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
+and add `--from-fleet-id <fleet-id>`. The planner selects only legacy paths covered by the stable
+Fleet manifest. For JSON deep merges it also accepts a source contribution that is an exact
+recursive subset of the destination contribution. Across package revisions, merge entries must
+identify the same package and artifact with equal source hashes; other merge contributions must
+match exactly. A source-only path stays in the legacy manifest;
+when every source entry is covered, apply removes the old manifest and source lock without changing
+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