diff --git a/README.md b/README.md index 6c8bf5d8..8dfbdcee 100644 --- a/README.md +++ b/README.md @@ -107,6 +107,7 @@ Fragments are Agentwheel composition inputs, not runtime file-drop targets. | `agentwheel uninstall ` | Remove a configured package from runtimes and config. | | `agentwheel uninstall --keep-files` | Remove from config/manifest while leaving runtime files unmanaged. | | `agentwheel status` | Show configured packages, manifest/lock presence, and install state. For a named fleet, use `--fleet --profile `; `--fleet --all` uses profile `all` when present. | +| `agentwheel ownership migrate-legacy` | Plan or apply metadata-only migration of current-owner legacy claims, including exact merge contributions, into the current install state. See [operator procedure](docs/ownership-legacy-migration.md). | | `agentwheel ownership handoff ` | Transfer one manifest entry to a different workspace root after exact owner, hash, and revision checks; runtime content is not rewritten. | | `agentwheel mcp retire ` | Preview removal of one exact legacy MCP contribution under an explicitly selected install-state key; add `--apply` only after review. | | `agentwheel doctor` | Check runtime setup and suggest explicit companion/selected skill install commands when they are missing. | diff --git a/docs/ownership-legacy-migration.md b/docs/ownership-legacy-migration.md new file mode 100644 index 00000000..cf102583 --- /dev/null +++ b/docs/ownership-legacy-migration.md @@ -0,0 +1,105 @@ +# Migrate current-owner legacy state + +`ownership migrate-legacy` moves verified entries already owned by the current workspace (or +its registered fleet) from an explicitly selected old manifest into the state key that configured +`install` uses. It does not change owners, graph locks, workspace configuration, or runtime files. +Use `ownership handoff` separately when the owner must change. No historical graph lock is required. + +```bash +cd /path/to/governing-workspace +agentwheel ownership migrate-legacy --local --agent example \ + --source-state-key openclaw.user.old-key --json > /tmp/migration-plan.json +``` + +A registered fleet can instead use `--fleet example`. Choose one agent or one profile resolving to +one target. Configured packages must resolve to one adapter configuration and installation type. +The destination is calculated exactly as for install, including explicit configured state keys. +Use repeatable `--path relative/path` to select a subset; otherwise all current-owner entries move. +Other owners' source entries remain untouched. + +The plan computes desired coverage from the current graph, as `ownership adopt-legacy` does, and +records it in the plan JSON and digest. Each selected entry reports whether the configured packages +still install it. An entry the graph no longer installs is refused by default: after migration the +next `install` would treat it as stale and remove its runtime files. Pass `--allow-undesired` only +when that removal is intended or the configuration will be updated first; the flag is part of the +digest, so plan and apply must agree on it. An entry whose path the graph assigns to a different +artifact is always refused. A destination manifest that is absent next to a stable graph lock is +refused too; reconcile that orphan lock before migrating. + +Review the owner, target, source/destination keys, selected paths, full inventory revision and +plan digest. Apply the same selection, adding the reviewed values (use `absent` for a null revision). +The plan's `applyCommand` prints the exact command, including `--reason`: + +```bash +agentwheel ownership migrate-legacy --local --agent example \ + --source-state-key openclaw.user.old-key \ + --plan-digest "$(jq -r .planDigest /tmp/migration-plan.json)" \ + --expected-source-revision "$(jq -r '.source.revision // "absent"' /tmp/migration-plan.json)" \ + --expected-destination-revision "$(jq -r '.destination.revision // "absent"' /tmp/migration-plan.json)" \ + --expected-inventory-revision "$(jq -r .manifestInventoryRevision /tmp/migration-plan.json)" \ + --apply --reason 'Migrate reviewed current-owner claims' +agentwheel install --local --agent example --dry-run --format json +``` + +Apply requires an effective `mutationPolicy` with `journal: "required"` (revisioning may be `off` +or `commit-after-verify`) and a durable receipt for the governing workspace. Without it, apply +refuses before touching target metadata. This ensures both destination and source journals have +a recovery path through `mutation recover-runtime `; keep the operation ID from +the command's mutation receipt output. + +Local-run-as targets use the same command and pinned identity checks. Apply runs through the normal +GovernedMutation receipt and confined worker; SSH is unsupported. Planning is read-only. Apply takes +the target lock, re-reads both manifests and refuses unless their revisions still equal the plan's, +then checks the complete inventory, runtime hashes and runtime +snapshots again at each metadata commit. Drift, missing files, semantic commands/plugins, incomplete +merge ownership, overlapping claims and pending journals fail closed. Exact managed instruction +blocks and complete JSON/TOML/YAML merge contributions are verified using the existing ownership +checks. The full runtime file is guarded even when only one contribution is owned. + +The destination commits first. If interrupted, recover the pending journal through the original +mutation receipt (`mutation recover-runtime `), then obtain a new plan. An exact +duplicate already in the destination is retired from the source without rewriting the destination. +An emptied source manifest and its old source lock are removed by the existing state cleanup. +An absent source yields an empty plan, so repeated migration is a no-op. With `--path`, a path that +is already absent from the source and present in the destination with a verified current-owner +entry is listed under `alreadyMigrated` and selects nothing, so the same command can be rerun. A +path missing from both manifests, or owned by another workspace, is still refused. A fresh digest +is required for each apply; do not reuse a pre-interruption plan. + +## Operator validation on a snapshot copy + +An operator first captures the runtime and `.agentwheel` into a separate readable snapshot using +their existing backup procedure, with no install or migration running. The checker refuses a +snapshot that holds a runtime apply lock or a pending apply journal. It only reads the snapshot +root it is given and never resolves a live service root itself; keeping the live root out of +`--snapshot-root` is the operator's responsibility. Pass only that +snapshot, an exact old state key, and the exact current owner string from the snapshot (after any +separately reviewed handoff). A metadata-only snapshot is insufficient: include every claimed +runtime path needed to verify hashes and merge contributions. + +```bash +python3 scripts/legacy-migration-copy-check.py \ + --snapshot-root "$SNAPSHOT_ROOT" --source-state-key "$SOURCE_STATE_KEY" \ + --current-owner "$CURRENT_OWNER" --cli "$PWD/dist/index.js" +python3 scripts/legacy-migration-copy-check.py \ + --snapshot-root "$SNAPSHOT_ROOT" --source-state-key "$SOURCE_STATE_KEY" \ + --current-owner "$CURRENT_OWNER" --cli "$PWD/dist/index.js" --apply +python3 scripts/legacy-migration-copy-check.py \ + --snapshot-root "$SNAPSHOT_ROOT" --source-state-key "$SOURCE_STATE_KEY" \ + --current-owner "$CURRENT_OWNER" --cli "$PWD/dist/index.js" --apply \ + --path relative/path +``` + +Each invocation creates a new disposable directory and prints its location. The CLI runs with a +minimal environment (`PATH`, `HOME` set to the copy, and the isolated mutation state root); on a +failure its stderr and stdout are printed before the checker exits. Repeatable `--path` is passed +through unchanged, and the rerun must report exactly those paths as already migrated. The copy is +an isolated empty workspace with no configured packages, so the checker always passes +`--allow-undesired`; desired coverage is verified only by the real plan. Only that copy's +manifest target roots and matching owner strings are rebased into an isolated plain workspace; +source/destination revisions and plan digests are then recomputed. The copy apply uses a durable +receipt, verifies all non-metadata bytes and modes, and proves the next plan selects nothing. +The printed directory is a full copy of the runtime snapshot and may hold the same sensitive files; +review it, then remove it. This verifies copied legacy claims, not the live endpoint, +service permissions, fleet identity or a real install; the CLI and confined-worker tests cover those +contracts separately. Never copy this rebased metadata back to the real target. diff --git a/scripts/legacy-migration-copy-check.py b/scripts/legacy-migration-copy-check.py new file mode 100644 index 00000000..e1c80d8d --- /dev/null +++ b/scripts/legacy-migration-copy-check.py @@ -0,0 +1,126 @@ +#!/usr/bin/env python3 +"""Verify metadata-only migration on a disposable copy of an existing snapshot. + +The operator must pass an already captured, readable snapshot containing +.agentwheel and its claimed runtime paths, never a live service root: this +script only reads --snapshot-root and cannot tell a snapshot from a live root. +The evidence directory it prints holds a full copy of that runtime; remove it +once the run has been reviewed. +""" +import argparse +import hashlib +import json +from pathlib import Path +import os +import shutil +import stat +import subprocess +import sys +import tempfile + +PENDING_METADATA_SUFFIXES = ('.runtime-apply-lock', '.apply-journal.json') + + +def snapshot(root): + result = {} + for path in sorted(root.rglob('*')): + if path.relative_to(root).parts[0] == '.agentwheel': + continue + info = path.lstat() + if stat.S_ISLNK(info.st_mode): + raise RuntimeError(f'Symlinks are unsupported in this copy check: {path}') + result[str(path.relative_to(root))] = [stat.S_IMODE(info.st_mode), + hashlib.sha256(path.read_bytes()).hexdigest() if path.is_file() else None] + return result + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--snapshot-root', type=Path, required=True) + parser.add_argument('--source-state-key', required=True) + parser.add_argument('--current-owner', required=True, help='exact owner string after any separately reviewed handoff') + parser.add_argument('--cli', type=Path, required=True) + parser.add_argument('--node', default='node') + parser.add_argument('--path', action='append', default=[], dest='paths', + help='select one exact relative runtime path (repeatable), passed to migrate-legacy') + parser.add_argument('--apply', action='store_true', help='also apply on the disposable copy and verify runtime equality') + args = parser.parse_args() + source = args.snapshot_root.resolve(strict=True) + cli = args.cli.resolve(strict=True) + if source == Path('/') or not (source / '.agentwheel').is_dir(): + raise RuntimeError('Expected an already captured snapshot with .agentwheel metadata') + if any(path.is_symlink() for path in source.rglob('*')): + raise RuntimeError('Copy check refuses symlinks') + pending = sorted(path.name for path in (source / '.agentwheel').iterdir() if path.name.endswith(PENDING_METADATA_SUFFIXES)) + if pending: + raise RuntimeError(f'Snapshot holds a runtime apply lock or pending journal, so it was captured mid-apply: {", ".join(pending)}') + key = args.source_state_key + if not key or any(c not in 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-' for c in key): + raise RuntimeError('Source state key must be canonical') + base = Path(tempfile.mkdtemp(prefix='aw-legacy-copy-')) + print(f'Evidence directory (full runtime copy, remove after review): {base}', flush=True) + target, workspace, pack = base / 'target', base / 'workspace', base / 'pack' + shutil.copytree(source, target, symlinks=True) + state = json.loads((target / '.agentwheel' / f'{key}.install-manifest.json').read_text()) + adapter, installation_type = state['adapter'], state['installationType'] + if adapter not in ('openclaw', 'claude', 'codex', 'copilot', 'hermes'): + raise RuntimeError('Copy checker currently supports built-in adapters only') + if not any(entry.get('workspaceOwner') == args.current_owner for entry in state['entries']): + raise RuntimeError('No source entries have the exact selected current owner') + # Rebase only metadata in the disposable copy; runtime bytes remain untouched. + # The copy uses an isolated plain workspace instead of the real registered fleet. + for path in (target / '.agentwheel').glob('*.install-manifest.json'): + manifest = json.loads(path.read_text()) + manifest['targetRoot'] = str(target) + for entry in manifest['entries']: + if entry.get('workspaceOwner') == args.current_owner: + entry['workspaceOwner'] = f'workspace-root:{workspace}' + path.write_text(json.dumps(manifest, indent=2) + '\n') + (workspace / '.agentwheel').mkdir(parents=True) + pack.mkdir() + config = {'schemaVersion': 4, + 'agents': {'copy': {'adapter': adapter, 'root': str(target), 'transport': 'local', 'installationType': installation_type}}, + # Migration resolves identity only: no sources are installed or executed. + 'packages': [{'name': 'copy-selection', 'source': str(pack), 'driver': 'local', 'mode': 'pinned', 'installationType': installation_type}], + 'mutationPolicy': {'reason': 'required', 'journal': 'required', 'revisioning': {'mode': 'off'}}} + (workspace / '.agentwheel/config.json').write_text(json.dumps(config, indent=2) + '\n') + # Keep operator credentials and Agentwheel overrides out of the copy run. + env = {'PATH': os.environ.get('PATH', os.defpath), 'HOME': str(target), 'AGENTWHEEL_MUTATION_STATE_ROOT': str(base / 'receipts')} + if 'LANG' in os.environ: + env['LANG'] = os.environ['LANG'] + # The copy's pack is empty, so every entry is undesired here. A real apply must review + # desiredCoverage and run without --allow-undesired unless removal on next install is intended. + command = [args.node, str(cli), 'ownership', 'migrate-legacy', '--local', '--agent', 'copy', '--source-state-key', key, + '--allow-undesired', *[arg for path in args.paths for arg in ('--path', path)]] + def run(extra): + result = subprocess.run(command + extra, cwd=workspace, env=env, capture_output=True, text=True) + if result.returncode: + print(result.stderr, end='', file=sys.stderr) + print(result.stdout, end='', file=sys.stderr) + raise RuntimeError(f'migrate-legacy exited with {result.returncode}') + return result.stdout + before = snapshot(target) + plan = json.loads(run(['--json'])) + (base / 'plan.json').write_text(json.dumps(plan, indent=2) + '\n') + print(f'Plan digest: {plan["planDigest"]}; selected entries: {len(plan["selected"])}', flush=True) + if not plan['selected']: + raise RuntimeError('Expected a nonempty migration plan') + if args.apply: + applied = run(['--apply', '--json', '--reason', 'Verify reviewed migration on disposable snapshot copy', + '--plan-digest', plan['planDigest'], '--expected-source-revision', plan['source']['revision'] or 'absent', + '--expected-destination-revision', plan['destination']['revision'] or 'absent', + '--expected-inventory-revision', plan['manifestInventoryRevision']]) + (base / 'applied.json').write_text(applied) + if snapshot(target) != before: + raise RuntimeError('Runtime bytes or modes changed in disposable copy') + repeated = json.loads(run(['--json'])) + if repeated['selected'] or sorted(item['path'] for item in repeated['alreadyMigrated']) != sorted(set(args.paths)): + raise RuntimeError('Migration was not idempotent') + (base / 'after.json').write_text(json.dumps(repeated, indent=2) + '\n') + print('PASS: copied claims migrated, runtime bytes/modes unchanged, rerun is a no-op') + elif snapshot(target) != before: + raise RuntimeError('Plan changed runtime files') + + +if __name__ == '__main__': + main() diff --git a/src/cli/index.ts b/src/cli/index.ts index ac491a9b..7acac5bf 100644 --- a/src/cli/index.ts +++ b/src/cli/index.ts @@ -49,6 +49,7 @@ import { resolveCliVersion } from "./version.js"; import { applyArtifactOwnershipHandoff, planArtifactOwnershipHandoff, workspaceOwnerForRoot } from "../lifecycle/ownership.js"; import { applyRetireStaleOwnership, planRetireStaleOwnership } from "../lifecycle/ownership-retire-stale.js"; import { applyReleaseOwnership, planReleaseOwnership } from "../lifecycle/ownership-release.js"; +import { applyMigrateLegacyOwnership, planMigrateLegacyOwnership } from "../lifecycle/ownership-migrate-legacy.js"; import { applyAdoptLegacyOwnership, desiredCoverageFromPlan, planAdoptLegacyOwnership } from "../lifecycle/ownership-adopt-legacy.js"; import { inventoryHistoricalLocks, planLegacyRecovery } from "../lifecycle/legacy-recovery-plan.js"; import { discoverPackageVersions, effectiveTrackingRef, type VersionAvailability } from "../version/policy.js"; @@ -1333,6 +1334,87 @@ ownershipCommand if (!options.apply) console.log(`Apply: ${applyCommand}`); }); +/** What a plain install of the group would install now, resolved against the same stable state identity. */ +async function legacyDesiredCoverage(group: PackageGraphGroup, adapter: Awaited>, stableStateKey: string, action: string) { + const { installationType, adapterOptions } = group; + const stableGraphLockPath = graphLockPathForTarget( + group.target.workspaceRoot, + targetKeyForTarget(group.target, adapter.name), + adapter.name, + targetFingerprintParts(group.target, adapter, adapterOptions, installationType), + targetIdentityContext(group.target, adapter, installationType), + ); + const desiredCoverage = await withFreshReadOnlyGraphPlan(group.target, adapter, adapterOptions, installationType, group.packages, async (graphPlan) => { + if (graphPlan.plan.stateKey !== stableStateKey || graphPlan.graphLockPath !== stableGraphLockPath) { + throw new Error(`Current source graph resolved a different target state identity; ${action} cannot proceed.`); + } + return desiredCoverageFromPlan(graphPlan.plan); + }); + return { stableGraphLockPath, desiredCoverage }; +} + +ownershipCommand + .command("migrate-legacy") + .description("plan metadata-only migration of current-owner entries into the current install state; runtime bytes never change") + .requiredOption("--source-state-key ", "exact old install-manifest state key") + .option("--path ", "select one exact relative runtime path (repeatable); defaults to all current-owner entries", (value: string, previous: string[]) => [...previous, value], []) + .option("--agent ", "one named local or local-run-as target") + .option("--profile ", "profile resolving to one target") + .option("--fleet ", "registered governing fleet") + .option("--local", "use the nearest local workspace", false) + .option("--user", "use the user workspace", false) + .option("-i, --installation-type ", "installation type used by configured packages") + .option("--allow-undesired", "also migrate entries the configured packages no longer install; the next install removes them", false) + .option("--plan-digest ", "reviewed plan digest; required with --apply") + .option("--expected-source-revision ", "reviewed source revision; required with --apply") + .option("--expected-destination-revision ", "reviewed destination revision; required with --apply") + .option("--expected-inventory-revision ", "reviewed full inventory revision; required with --apply") + .option("--apply", "apply the exact reviewed metadata migration", false) + .option("--json", "print the complete deterministic plan as JSON", false) + .action(async (options, command: Command) => { + if (Boolean(options.agent) === Boolean(options.profile)) throw new Error("Legacy state migration requires exactly one of --agent or --profile."); + const plainOptions = { ...normalizeRuntimeScopeOptions(options), installationType: undefined }; + const targets = await resolveCliTargets(plainOptions); + if (targets.length !== 1) throw new Error("Legacy state migration requires exactly one target."); + const target = targets[0]!; + if (target.transport === "ssh") throw new Error("Legacy state migration does not support SSH targets."); + const config = await readMergedWorkspaceConfig(target.workspaceRoot); + const groups = new Map(); + for (const pkg of packagesForCliTarget(config.packages, target, plainOptions)) graphGroupForPackage(groups, target, pkg, plainOptions).packages.push(pkg); + if (groups.size !== 1) throw new Error("Legacy state migration requires packages resolving to exactly one adapter configuration and installation type."); + const group = [...groups.values()][0]!; + if (options.installationType && options.installationType !== group.installationType) throw new Error("Requested installation type differs from configured install state."); + const adapter = await resolveAdapterForTarget(group.target, group.adapterOptions); + const stable = installStateForTarget(group.target, adapter, group.adapterOptions, group.installationType); + const { stableGraphLockPath, desiredCoverage } = await legacyDesiredCoverage(group, adapter, stable.stateKey, "legacy state migration"); + const request = { targetRoot: stable.installRoot, adapter: adapter.name, installationType: group.installationType, + sourceStateKey: options.sourceStateKey, destinationStateKey: stable.stateKey, workspaceRoot: target.workspaceRoot, + desiredCoverage, destinationGraphLockPath: stableGraphLockPath, allowUndesired: options.allowUndesired === true, + paths: options.path.length ? options.path : undefined, transport: transportForTarget(target), + planDigest: options.planDigest, expectedSourceRevision: options.expectedSourceRevision, + expectedDestinationRevision: options.expectedDestinationRevision, expectedInventoryRevision: options.expectedInventoryRevision }; + const result = options.apply ? await applyMigrateLegacyOwnership(request) : await planMigrateLegacyOwnership(request); + const applyArgs = ["agentwheel", "ownership", "migrate-legacy", "--source-state-key", result.source.stateKey, + ...(options.agent ? ["--agent", options.agent] : ["--profile", options.profile]), + ...(options.fleet ? ["--fleet", options.fleet] : []), ...(options.local ? ["--local"] : []), ...(options.user ? ["--user"] : []), + "--installation-type", group.installationType, + ...options.path.flatMap((path: string) => ["--path", path]), + ...(result.allowUndesired ? ["--allow-undesired"] : []), + "--plan-digest", result.planDigest, "--expected-source-revision", result.source.revision ?? "absent", + "--expected-destination-revision", result.destination.revision ?? "absent", "--expected-inventory-revision", result.manifestInventoryRevision, "--apply", + "--reason", (command.optsWithGlobals() as GlobalMutationOptions).reason ?? ""]; + const applyCommand = applyArgs.map(shellQuoteArgument).join(" "); + if (options.json) { console.log(JSON.stringify({ ...result, applyCommand }, null, 2)); return; } + console.log(`${options.apply ? "Migrated legacy state" : "Legacy state migration plan"}: ${result.selected.length} entries`); + console.log(`Owner: ${result.owner}`); + console.log(`Source: ${result.source.stateKey} revision ${result.source.revision ?? "absent"}`); + console.log(`Destination: ${result.destination.stateKey} revision ${result.destination.revision ?? "absent"}`); + for (const entry of result.selected) console.log(`- ${entry.path}: ${entry.action}${entry.desired ? "" : " (not desired: the next install removes it)"}`); + for (const entry of result.alreadyMigrated) console.log(` already migrated ${entry.path}`); + console.log(`Plan digest: ${result.planDigest}`); + if (!options.apply) console.log(`Apply from ${target.workspaceRoot}: ${applyCommand}`); + }); + ownershipCommand .command("adopt-legacy") .description("move proven legacy-keyed ownership into this workspace's stable target state without rewriting runtime artifacts") @@ -1411,19 +1493,7 @@ ownershipCommand } const adapter = await resolveAdapterForTarget(group.target, adapterOptions); const stable = installStateForTarget(group.target, adapter, adapterOptions, installationType); - const stableGraphLockPath = graphLockPathForTarget( - group.target.workspaceRoot, - targetKeyForTarget(group.target, adapter.name), - adapter.name, - targetFingerprintParts(group.target, adapter, adapterOptions, installationType), - targetIdentityContext(group.target, adapter, installationType), - ); - const desiredCoverage = await withFreshReadOnlyGraphPlan(group.target, adapter, adapterOptions, installationType, group.packages, async (graphPlan) => { - if (graphPlan.plan.stateKey !== stable.stateKey || graphPlan.graphLockPath !== stableGraphLockPath) { - throw new Error("Current source graph resolved a different target state identity; legacy ownership adoption cannot proceed."); - } - return desiredCoverageFromPlan(graphPlan.plan); - }); + const { stableGraphLockPath, desiredCoverage } = await legacyDesiredCoverage(group, adapter, stable.stateKey, "legacy ownership adoption"); const request = { targetRoot: stable.installRoot, adapter: adapter.name, diff --git a/src/lifecycle/ownership-adopt-legacy.ts b/src/lifecycle/ownership-adopt-legacy.ts index 467bea5c..3d84fee1 100644 --- a/src/lifecycle/ownership-adopt-legacy.ts +++ b/src/lifecycle/ownership-adopt-legacy.ts @@ -195,7 +195,7 @@ export async function applyAdoptLegacyOwnership(request: AdoptLegacyOwnershipReq generatedAt: now, entries: [...base.entries, ...adopted].sort((left, right) => left.path.localeCompare(right.path)), }); - await commitMetadata(next, destination?.revision ?? null, now, transport, guards); + await commitOwnershipManifestMetadata(next, destination?.revision ?? null, now, transport, guards); if (guards) guards = { ...guards, inventory: [...guards.inventory.filter((item) => item.stateKey !== current.destination.stateKey), @@ -204,7 +204,7 @@ export async function applyAdoptLegacyOwnership(request: AdoptLegacyOwnershipReq }; } declareMutationPath(current.source.manifestPath); - await commitMetadata({ ...source, entries: retained }, source.revision, now, transport, guards); + await commitOwnershipManifestMetadata({ ...source, entries: retained }, source.revision, now, transport, guards); return { ...current, applied: true, @@ -218,7 +218,7 @@ export async function applyAdoptLegacyOwnership(request: AdoptLegacyOwnershipReq } } -async function commitMetadata( +export async function commitOwnershipManifestMetadata( manifest: InstallManifestV2, baseRevision: string | null, now: string, @@ -275,11 +275,7 @@ async function observe(request: AdoptLegacyOwnershipRequest, transport: TargetTr } const source = await requireManifest(identity, input.sourceStateKey, transport, "source"); const destination = await readDestination(identity, input.destinationStateKey, transport); - if (!destination && await pathExists(request.destinationGraphLockPath)) { - throw new Error( - `Destination has a stable graph lock without a stable manifest at ${request.destinationGraphLockPath}; reconcile it before adopting legacy ownership.`, - ); - } + await assertNoOrphanDestinationGraphLock(Boolean(destination), request.destinationGraphLockPath, "adopting legacy ownership"); const desiredByPath = new Map(); for (const item of request.desiredCoverage) desiredByPath.set(item.path, [...desiredByPath.get(item.path) ?? [], item]); const { entries: selectedEntries, retained, provenance } = await selectLegacySource( @@ -402,14 +398,7 @@ async function observe(request: AdoptLegacyOwnershipRequest, transport: TargetTr retained: retained.sort((left, right) => left.path.localeCompare(right.path) || left.owner.localeCompare(right.owner)), remainingDuplicates: remainingDuplicates.sort((left, right) => left.stateKey.localeCompare(right.stateKey) || left.path.localeCompare(right.path)), - // identity only, so a newer package revision doesn't invalidate a reviewed plan - desiredCoverage: request.desiredCoverage - .filter((item) => selectedPaths.has(item.path)) - .map(({ path, artifactType, artifactName, kind, mode, logicalSelector }) => ({ path, artifactType, artifactName, kind, - ...(mode ? { mode, logicalSelector: managedInstructionSelector(logicalSelector, artifactType, artifactName) } : {}) })) - .sort((left, right) => left.path.localeCompare(right.path) - || left.artifactType.localeCompare(right.artifactType) - || left.artifactName.localeCompare(right.artifactName)), + desiredCoverage: desiredCoverageIdentity(request.desiredCoverage, selectedPaths), ...(guardedInventory ? { metadataGuards: { inventory: guardedInventory.map((item) => ({ stateKey: item.stateKey, revision: item.manifest.revision })), runtime: selected.map((entry) => ({ path: entry.path, hash: entry.runtimeHash!, snapshotDigest: entry.runtimeSnapshotDigest!, @@ -603,7 +592,26 @@ function assertSupportedLegacyEntry(entry: InstallManifestEntry, targetRoot: str containedArtifactPath(targetRoot, entry.path); } -function desiredCovers(item: AdoptLegacyDesiredArtifact, entry: InstallManifestEntry): boolean { +export type DesiredCoverageIdentity = Pick; + +// Identity only, so a newer package revision doesn't invalidate a reviewed plan. +export function desiredCoverageIdentity(coverage: AdoptLegacyDesiredArtifact[], paths: ReadonlySet): DesiredCoverageIdentity[] { + return coverage + .filter((item) => paths.has(item.path)) + .map(({ path, artifactType, artifactName, kind, mode, logicalSelector }) => ({ path, artifactType, artifactName, kind, + ...(mode ? { mode, logicalSelector: managedInstructionSelector(logicalSelector, artifactType, artifactName) } : {}) })) + .sort((left, right) => left.path.localeCompare(right.path) + || left.artifactType.localeCompare(right.artifactType) + || left.artifactName.localeCompare(right.artifactName)); +} + +export async function assertNoOrphanDestinationGraphLock(destinationExists: boolean, graphLockPath: string, action: string): Promise { + if (!destinationExists && await pathExists(graphLockPath)) { + throw new Error(`Destination has a stable graph lock without a stable manifest at ${graphLockPath}; reconcile it before ${action}.`); + } +} + +export function desiredCovers(item: AdoptLegacyDesiredArtifact, entry: InstallManifestEntry): boolean { return item.artifactType === entry.artifactType && item.artifactName === entry.artifactName && item.kind === entry.kind diff --git a/src/lifecycle/ownership-migrate-legacy.ts b/src/lifecycle/ownership-migrate-legacy.ts new file mode 100644 index 00000000..ec218265 --- /dev/null +++ b/src/lifecycle/ownership-migrate-legacy.ts @@ -0,0 +1,198 @@ +import { createHash } from "node:crypto"; +import { resolve } from "node:path"; +import { listInstallManifests, readInstallManifest, withManifestRevision } from "../install/manifest.js"; +import { installManifestPath } from "../install/paths.js"; +import { acquireApplyLock, assertNoSymlinkPath, assertOwnershipMetadataTransportSupported, + listAllApplyJournals, observeOwnershipRuntime, type MetadataStateGuards } from "../install/transaction.js"; +import type { InstallManifestEntry, InstallManifestV2 } from "../model/manifest.js"; +import { resolveWorkspaceOwnershipScope } from "../model/fleet.js"; +import { workspaceOwnerForRoot } from "../model/workspace-owner.js"; +import { activeMutationMetadata } from "../mutation/coordinator.js"; +import { declareMutationPath } from "../mutation/declarations.js"; +import { localTransport, type TargetTransport } from "../transport/index.js"; +import { assertNoOrphanDestinationGraphLock, commitOwnershipManifestMetadata, desiredCoverageIdentity, desiredCovers, + type AdoptLegacyDesiredArtifact, type DesiredCoverageIdentity } from "./ownership-adopt-legacy.js"; +import { containedArtifactPath, verifyManifestEntryRuntime } from "./ownership.js"; +import { assertExpected, canonicalJson, entryDigest, exactStateKey, ownershipRunAsEndpoint, requireManifest } from "./ownership-retire-stale.js"; + +export interface MigrateLegacyOwnershipRequest { + targetRoot: string; + adapter: string; + installationType: string; + sourceStateKey: string; + destinationStateKey: string; + workspaceRoot: string; + globalRoot?: string; + /** What a plain install of the configured packages would install now. */ + desiredCoverage: AdoptLegacyDesiredArtifact[]; + destinationGraphLockPath: string; + /** Migrate entries the configured packages no longer install; the next install then removes them. */ + allowUndesired?: boolean; + paths?: string[]; + transport?: TargetTransport; + planDigest?: string; + expectedSourceRevision?: string; + expectedDestinationRevision?: string; + expectedInventoryRevision?: string; +} + +export interface MigrateLegacyOwnershipPlan { + adapter: string; + installationType: string; + targetRoot: string; + owner: string; + source: { stateKey: string; manifestPath: string; revision: string | null }; + destination: { stateKey: string; manifestPath: string; revision: string | null }; + selected: Array<{ path: string; sourceEntryDigest: string; action: "migrate" | "retire-covered"; desired: boolean }>; + alreadyMigrated: Array<{ path: string; destinationEntryDigest: string }>; + retained: Array<{ path: string; owner: string }>; + allowUndesired: boolean; + desiredCoverage: DesiredCoverageIdentity[]; + manifestInventoryRevision: string; + metadataGuards: MetadataStateGuards; + transport?: ReturnType; + planDigest: string; +} + +/** An explicit old state key plus exact current ownership replaces graph-lock provenance. + * The destination key is resolved by the CLI using the same identity as install. */ +export async function planMigrateLegacyOwnership(request: MigrateLegacyOwnershipRequest): Promise { + const transport = request.transport ?? localTransport; + if (transport.kind === "ssh") throw new Error("Legacy state migration does not support SSH targets."); + const targetRoot = resolve(request.targetRoot); + const installationType = request.installationType; + const sourceKey = exactStateKey(request.adapter, request.sourceStateKey, installationType, "source"); + const destinationKey = exactStateKey(request.adapter, request.destinationStateKey, installationType, "destination"); + if (sourceKey === destinationKey) throw new Error("Source and destination state keys must differ."); + const scope = await resolveWorkspaceOwnershipScope(request.workspaceRoot, { globalRoot: request.globalRoot }); + const owner = workspaceOwnerForRoot(scope.root, scope.fleetId); + const endpoint = ownershipRunAsEndpoint(transport, targetRoot); + if ((await listAllApplyJournals(targetRoot, undefined, transport)).length) throw new Error("Pending runtime apply journals must be recovered before migration."); + const identity = { targetRoot, adapter: request.adapter, installationType }; + const load = async (key: string) => await readInstallManifest(targetRoot, request.adapter, transport, { installationType, stateKey: key }) + ? requireManifest(identity, key, transport, "migration") : undefined; + const source = await load(sourceKey), destination = await load(destinationKey); + await assertNoOrphanDestinationGraphLock(Boolean(destination), request.destinationGraphLockPath, "migrating legacy state"); + if (source?.adapterCode || destination?.adapterCode) throw new Error("Programmatic adapter state cannot be migrated."); + const inventory = await listInstallManifests(targetRoot, undefined, transport); + if (transport.kind === "local") { + await assertNoSymlinkPath(targetRoot); + for (const item of inventory) await assertNoSymlinkPath(item.path); + } + const requested = request.paths ? [...new Set(request.paths)].sort() : undefined; + for (const path of requested ?? []) containedArtifactPath(targetRoot, path); + const entries = source?.entries.filter(entry => entry.workspaceOwner === owner && (!requested || requested.includes(entry.path))) ?? []; + // A path already moved by an earlier apply has left the source and sits, owned and unchanged, in the destination. + const alreadyMigrated: MigrateLegacyOwnershipPlan["alreadyMigrated"] = []; + for (const path of requested ?? []) { + if (entries.some(entry => entry.path === path)) continue; + const atPath = destination?.entries.filter(entry => entry.path === path) ?? []; + if (!source?.entries.some(entry => entry.path === path) && atPath.length === 1 && atPath[0]!.workspaceOwner === owner) { + await verifyManifestEntryRuntime(targetRoot, atPath[0]!, transport); + alreadyMigrated.push({ path, destinationEntryDigest: entryDigest(atPath[0]!) }); + } else { + throw new Error("Every selected path must exist in the source and be owned by the current workspace."); + } + } + const desiredByPath = new Map(); + for (const item of request.desiredCoverage) desiredByPath.set(item.path, [...desiredByPath.get(item.path) ?? [], item]); + const selected: MigrateLegacyOwnershipPlan["selected"] = []; + const runtime: MetadataStateGuards["runtime"] = []; + for (const entry of entries) { + if (entry.semanticPlugin || entry.semanticCommand || entry.executed) throw new Error(`Unsupported semantic claim at ${entry.path}.`); + const path = containedArtifactPath(targetRoot, entry.path); + if (path === targetRoot || path.startsWith(`${targetRoot}/.agentwheel/`) || path === `${targetRoot}/.agentwheel`) { + throw new Error(`Runtime claim overlaps metadata at ${entry.path}.`); + } + const observation = await observeOwnershipRuntime(path, transport); + if (observation.kind !== entry.kind) throw new Error(`Runtime kind differs at ${entry.path}.`); + await verifyManifestEntryRuntime(targetRoot, entry, transport); + let covered = false; + for (const item of inventory) for (const other of item.manifest.entries) { + const otherPath = containedArtifactPath(targetRoot, other.path); + if (!(otherPath === path || otherPath.startsWith(`${path}/`) || path.startsWith(`${otherPath}/`))) continue; + // Inventory objects are parsed separately: compare digests, and reject duplicate source entries below. + if (item.stateKey === sourceKey && entryDigest(other as InstallManifestEntry) === entryDigest(entry) + && source!.entries.filter(candidate => candidate.path === entry.path).length === 1) continue; + if (item.stateKey === destinationKey && item.manifest.version === 2 + && entryDigest(other as InstallManifestEntry) === entryDigest(entry) && !covered) { covered = true; continue; } + throw new Error(`Conflicting or overlapping ownership claim at ${entry.path} in ${item.stateKey}.`); + } + const desiredAtPath = desiredByPath.get(entry.path) ?? []; + // Retiring an exact duplicate leaves the destination, and so the next install, unchanged. + if (!covered && desiredAtPath.length && !desiredAtPath.some(item => desiredCovers(item, entry))) { + throw new Error(`The current graph plans a different artifact at ${entry.path}; legacy state cannot be migrated there.`); + } + if (!covered && !desiredAtPath.length && !request.allowUndesired) { + throw new Error(`The configured packages no longer install ${entry.path}, so the next install would remove it after migration; ` + + "select only desired paths with --path, or pass --allow-undesired to migrate it anyway."); + } + selected.push({ path: entry.path, sourceEntryDigest: entryDigest(entry), action: covered ? "retire-covered" : "migrate", desired: desiredAtPath.length > 0 }); + runtime.push({ path: entry.path, hash: await transport.hashPath(path), snapshotDigest: observation.snapshotDigest }); + } + const selectedDigests = new Set(selected.map(entry => entry.sourceEntryDigest)); + const withoutDigest = { + adapter: request.adapter, installationType, targetRoot, owner, + source: { stateKey: sourceKey, manifestPath: installManifestPath(targetRoot, request.adapter, { stateKey: sourceKey }), revision: source?.revision ?? null }, + destination: { stateKey: destinationKey, manifestPath: installManifestPath(targetRoot, request.adapter, { stateKey: destinationKey }), revision: destination?.revision ?? null }, + selected: selected.sort((a, b) => a.path.localeCompare(b.path)), + alreadyMigrated, + retained: (source?.entries ?? []).filter(entry => !selectedDigests.has(entryDigest(entry))) + .map(entry => ({ path: entry.path, owner: entry.workspaceOwner })).sort((a, b) => a.path.localeCompare(b.path)), + allowUndesired: request.allowUndesired === true, + desiredCoverage: desiredCoverageIdentity(request.desiredCoverage, new Set(selected.map(entry => entry.path))), + manifestInventoryRevision: createHash("sha256").update(JSON.stringify(inventory.map(item => [item.fileName, item.manifest.revision]))).digest("hex"), + metadataGuards: { inventory: inventory.map(item => ({ stateKey: item.stateKey, revision: item.manifest.revision })), runtime: runtime.sort((a, b) => a.path.localeCompare(b.path)) }, + ...(endpoint ? { transport: endpoint } : {}), + }; + return { ...withoutDigest, planDigest: createHash("sha256").update(canonicalJson(withoutDigest)).digest("hex") }; +} + +export async function applyMigrateLegacyOwnership(request: MigrateLegacyOwnershipRequest) { + for (const [label, value] of [["plan digest", request.planDigest], ["source revision", request.expectedSourceRevision], + ["destination revision", request.expectedDestinationRevision], ["inventory revision", request.expectedInventoryRevision]] as const) { + if (!value || (!/^[a-f0-9]{64}$/.test(value) && !(label.endsWith("revision") && !label.startsWith("inventory") && value === "absent"))) { + throw new Error(`Applying legacy state migration requires reviewed ${label}.`); + } + } + const transport = request.transport ?? localTransport; + const mutation = activeMutationMetadata(); + if (!mutation || resolve(mutation.workspaceRoot) !== resolve(request.workspaceRoot)) { + throw new Error("Legacy state migration requires a caller-owned durable mutation receipt for this workspace; configure mutationPolicy.journal as required before applying."); + } + assertOwnershipMetadataTransportSupported(transport); + const lock = await acquireApplyLock(request.targetRoot, request.adapter, transport, {}, { installationType: request.installationType, stateKey: request.destinationStateKey }); + try { + const plan = await planMigrateLegacyOwnership(request); + assertExpected(request.planDigest!, plan.planDigest, "plan digest"); + assertExpected(request.expectedSourceRevision!, plan.source.revision ?? "absent", "source revision"); + assertExpected(request.expectedDestinationRevision!, plan.destination.revision ?? "absent", "destination revision"); + assertExpected(request.expectedInventoryRevision!, plan.manifestInventoryRevision, "inventory revision"); + if (!plan.selected.length) return { ...plan, applied: true, migratedEntries: 0, retiredCoveredEntries: 0 }; + const identity = { targetRoot: plan.targetRoot, adapter: plan.adapter, installationType: plan.installationType }; + const source = await requireManifest(identity, plan.source.stateKey, transport, "source"); + const destination = await readInstallManifest(plan.targetRoot, plan.adapter, transport, { installationType: plan.installationType, stateKey: plan.destination.stateKey }) + ? await requireManifest(identity, plan.destination.stateKey, transport, "destination") : undefined; + // The entries committed below come from this read, not from the plan. + assertExpected(plan.source.revision ?? "absent", source.revision, "source revision"); + assertExpected(plan.destination.revision ?? "absent", destination?.revision ?? "absent", "destination revision"); + const selected = new Map(plan.selected.map(entry => [entry.sourceEntryDigest, entry.action])); + const adopted = source.entries.filter(entry => selected.get(entryDigest(entry)) === "migrate"); + const now = new Date().toISOString(); + let guards = plan.metadataGuards; + // Destination first. An interrupted transfer leaves exact duplicates, never unowned runtime. + if (adopted.length) { + const next: InstallManifestV2 = withManifestRevision({ ...(destination ?? { version: 2, adapter: plan.adapter, + installationType: plan.installationType, targetRoot: plan.targetRoot, stateKey: plan.destination.stateKey, legacy: false, + revision: "pending-migration", entries: [], generatedAt: now }), generatedAt: now, + entries: [...destination?.entries ?? [], ...adopted].sort((a, b) => a.path.localeCompare(b.path)) }); + declareMutationPath(plan.destination.manifestPath); + await commitOwnershipManifestMetadata(next, plan.destination.revision, now, transport, guards); + guards = { ...guards, inventory: [...guards.inventory.filter(item => item.stateKey !== plan.destination.stateKey), + { stateKey: plan.destination.stateKey, revision: next.revision }].sort((a, b) => a.stateKey.localeCompare(b.stateKey)) }; + } + declareMutationPath(plan.source.manifestPath); + await commitOwnershipManifestMetadata({ ...source, entries: source.entries.filter(entry => !selected.has(entryDigest(entry))) }, source.revision, now, transport, guards); + return { ...plan, applied: true, migratedEntries: adopted.length, retiredCoveredEntries: plan.selected.length - adopted.length }; + } finally { await lock.release(); } +} diff --git a/src/mutation/commands.ts b/src/mutation/commands.ts index 94570cb7..30c33ea6 100644 --- a/src/mutation/commands.ts +++ b/src/mutation/commands.ts @@ -47,6 +47,7 @@ export const commandGovernance = { "ownership recovery-plan": "incidental-cache", "ownership retire-stale": "governed-apply", "ownership release-claim": "governed-apply", + "ownership migrate-legacy": "governed-apply", "ownership adopt-legacy": "governed-apply", "mcp retire": "governed-apply", eject: "governed-always", diff --git a/test/ownership-migrate-legacy-cli.test.ts b/test/ownership-migrate-legacy-cli.test.ts new file mode 100644 index 00000000..26843193 --- /dev/null +++ b/test/ownership-migrate-legacy-cli.test.ts @@ -0,0 +1,86 @@ +import { execFile } from "node:child_process"; +import { mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { promisify } from "node:util"; +import { afterEach, beforeAll, expect, it } from "vitest"; +import { ensureCliBuild } from "./helpers/ensure-cli-build.js"; +const exec = promisify(execFile), cli = join(process.cwd(), "dist/index.js"), roots: string[] = []; +beforeAll(() => ensureCliBuild(cli), 120_000); +afterEach(async () => { await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true }))); }); +async function graphLocks(dir: string): Promise { + const found: string[] = []; + for (const item of await readdir(dir, { withFileTypes: true }).catch(() => [])) { + const path = join(dir, item.name); + if (item.isDirectory()) found.push(...await graphLocks(path)); + else if (item.name.endsWith(".graph-lock.json")) found.push(path); + } + return found; +} + +/** Installs the selected skills, then moves their state under a legacy key with no stable graph lock left behind. */ +async function legacyFixture(skills: string[]) { + const root = await mkdtemp(join(tmpdir(), "aw-migrate-cli-")); roots.push(root); + const workspace = join(root, "workspace"), target = join(root, "target"), pack = join(root, "pack"), home = join(root, "home"); + for (const path of [join(workspace, ".agentwheel"), target, home, ...skills.map(name => join(pack, "skills", name))]) await mkdir(path, { recursive: true }); + await writeFile(join(pack, "openpack.json"), JSON.stringify({ schemaVersion: 2, name: "fixture/migration", version: "1.0.0", provides: [{ type: "skills", path: "skills" }] })); + for (const name of skills) await writeFile(join(pack, `skills/${name}/SKILL.md`), `---\nname: ${name}\ndescription: Synthetic fixture\n---\nExample\n`); + const configPath = join(workspace, ".agentwheel/config.json"); + const writeConfig = (select: string[]) => writeFile(configPath, JSON.stringify({ schemaVersion: 4, mutationPolicy: { reason: "required", journal: "required", revisioning: { mode: "off" } }, + agents: { example: { adapter: "claude", root: target, transport: "local" } }, + packages: [{ name: "example", driver: "local", source: pack, mode: "pinned", select }] })); + await writeConfig(skills.map(name => `skills/${name}`)); + const run = (args: string[]) => exec(process.execPath, [cli, ...args, "--reason", "Verify synthetic migration CLI"], { cwd: workspace, + env: { ...process.env, HOME: home, AGENTWHEEL_MUTATION_STATE_ROOT: join(root, "receipts") }, maxBuffer: 10 * 1024 * 1024 }); + await run(["install", "--agent", "example"]); + const metadata = join(target, ".agentwheel"), current = (await readdir(metadata)).find(path => path.endsWith(".install-manifest.json"))!; + const currentPath = join(metadata, current), legacyKey = "claude.local.legacy"; + const manifest = JSON.parse(await readFile(currentPath, "utf8")); manifest.stateKey = legacyKey; + await writeFile(currentPath, JSON.stringify(manifest)); + await rename(currentPath, join(metadata, `${legacyKey}.install-manifest.json`)); + const locks = await graphLocks(join(workspace, ".agentwheel")); + return { workspace, target, run, writeConfig, current, legacyKey, locks, + args: ["ownership", "migrate-legacy", "--agent", "example", "--source-state-key", legacyKey] }; +} + +const applyArgs = (plan: { planDigest: string; source: { revision: string | null }; destination: { revision: string | null }; manifestInventoryRevision: string }) => [ + "--plan-digest", plan.planDigest, "--expected-source-revision", plan.source.revision ?? "absent", + "--expected-destination-revision", plan.destination.revision ?? "absent", "--expected-inventory-revision", plan.manifestInventoryRevision, "--apply"]; + +it("migrates a configured target state and makes the next install dry-run managed", async () => { + const { target, run, current, locks, args } = await legacyFixture(["example"]); + expect(locks.length).toBeGreaterThan(0); + await expect(run([...args, "--json"])).rejects.toThrow(/stable graph lock without a stable manifest/); + for (const lock of locks) await rm(lock); + const before = await readFile(join(target, ".claude/skills/example/SKILL.md")); + const plan = JSON.parse((await run([...args, "--json"])).stdout); + expect(plan.selected).toMatchObject([{ desired: true }]); + expect(plan.desiredCoverage).toHaveLength(1); + expect(plan.destination.stateKey).toBe(current.replace(".install-manifest.json", "")); + expect(plan.applyCommand).toContain("--reason 'Verify synthetic migration CLI'"); + await run([...args, ...applyArgs(plan)]); + expect(await readFile(join(target, ".claude/skills/example/SKILL.md"))).toEqual(before); + const install = JSON.parse((await run(["install", "--agent", "example", "--dry-run", "--format", "json"])).stdout); + expect(install.targets[0].hasBlockingChanges).toBe(false); + expect(install.targets[0].operations[0].action).toBe("skip"); +}, 60_000); + +it("refuses entries the configured packages no longer install unless explicitly allowed", async () => { + const { run, writeConfig, locks, args } = await legacyFixture(["example", "retired"]); + for (const lock of locks) await rm(lock); + await writeConfig(["skills/example"]); + await expect(run([...args, "--json"])).rejects.toThrow(/no longer install \.claude\/skills\/retired/); + const allowed = JSON.parse((await run([...args, "--allow-undesired", "--json"])).stdout); + expect(allowed.allowUndesired).toBe(true); + expect(allowed.selected.map((entry: { path: string; desired: boolean }) => [entry.path, entry.desired])) + .toEqual([[".claude/skills/example", true], [".claude/skills/retired", false]]); + expect(allowed.applyCommand).toContain("--allow-undesired"); + const strict = JSON.parse((await run([...args, "--path", ".claude/skills/example", "--json"])).stdout); + expect(strict.planDigest).not.toBe(allowed.planDigest); + await expect(run([...args, ...applyArgs({ ...strict, planDigest: allowed.planDigest }), "--path", ".claude/skills/example"])).rejects.toThrow(/Stale plan digest/); + await run([...args, "--path", ".claude/skills/example", ...applyArgs(strict)]); + const rerun = JSON.parse((await run([...args, "--path", ".claude/skills/example", "--json"])).stdout); + expect(rerun.selected).toEqual([]); + expect(rerun.alreadyMigrated).toMatchObject([{ path: ".claude/skills/example" }]); + await run([...args, "--path", ".claude/skills/example", ...applyArgs(rerun)]); +}, 60_000); diff --git a/test/ownership-migrate-legacy.test.ts b/test/ownership-migrate-legacy.test.ts new file mode 100644 index 00000000..50d4ec20 --- /dev/null +++ b/test/ownership-migrate-legacy.test.ts @@ -0,0 +1,249 @@ +import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { afterEach, describe, expect, it } from "vitest"; +import { readInstallManifest, writeInstallManifest } from "../src/install/manifest.js"; +import { installManifestPath } from "../src/install/paths.js"; +import { applyMigrateLegacyOwnership as applyRaw, planMigrateLegacyOwnership, type MigrateLegacyOwnershipRequest } from "../src/lifecycle/ownership-migrate-legacy.js"; +import { workspaceOwnerForRoot } from "../src/model/workspace-owner.js"; +import type { InstallManifestEntry, InstallManifestV2 } from "../src/model/manifest.js"; +import { localTransport } from "../src/transport/index.js"; +import { GovernedMutation, recoverMutationRuntime } from "../src/mutation/coordinator.js"; + +const roots: string[] = []; +const originalState = process.env.AGENTWHEEL_MUTATION_STATE_ROOT; +afterEach(async () => { + if (originalState === undefined) delete process.env.AGENTWHEEL_MUTATION_STATE_ROOT; + else process.env.AGENTWHEEL_MUTATION_STATE_ROOT = originalState; + await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true }))); }); +const sourceKey = "openclaw.user.legacy", destinationKey = "openclaw.user.current"; +async function fixture(merge = false) { + const root = await mkdtemp(join(tmpdir(), "aw-migration-")); roots.push(root); + process.env.AGENTWHEEL_MUTATION_STATE_ROOT = join(root, "receipts"); + const target = join(root, "target"), workspace = join(root, "workspace"); + await mkdir(join(workspace, ".agentwheel"), { recursive: true }); + await writeFile(join(workspace, ".agentwheel/config.json"), JSON.stringify({ schemaVersion: 4, packages: [], mutationPolicy: { reason: "required", journal: "required", revisioning: { mode: "off" } } })); + const path = merge ? ".openclaw/openclaw.json" : ".openclaw/skills/example/SKILL.md"; + const live = join(target, path); + await mkdir(dirname(live), { recursive: true }); + await writeFile(live, merge ? '{"tools":{"allow":["example"]},"userSetting":true}\n' : "Example skill\n"); + const entry: InstallManifestEntry = { path, artifactType: merge ? "settings" : "skills", artifactName: "example", installName: "example", + kind: "file", hash: merge ? "a".repeat(64) : await localTransport.hashPath(live), sourceHash: "b".repeat(64), + updatedAt: new Date().toISOString(), channel: "managed", dependencyRole: "root", owners: ["example"], refCount: 1, workspaceOwner: workspaceOwnerForRoot(workspace), + ...(merge ? { mergeStrategy: "openclaw-json-deep" as const, mergeRemoval: { tools: { allow: ["example"] } } } : {}) }; + const manifest: InstallManifestV2 = { version: 2, adapter: "openclaw", installationType: "user", stateKey: sourceKey, + targetRoot: target, generatedAt: new Date().toISOString(), revision: "pending-fixture-00", legacy: false, entries: [entry] }; + await writeInstallManifest(manifest); + const request: MigrateLegacyOwnershipRequest = { targetRoot: target, workspaceRoot: workspace, globalRoot: join(root, "home"), adapter: "openclaw", + installationType: "user", sourceStateKey: sourceKey, destinationStateKey: destinationKey, + desiredCoverage: [{ path, artifactType: entry.artifactType, artifactName: "example", kind: "file" }], + destinationGraphLockPath: join(workspace, ".agentwheel/locks/stable.graph-lock.json") }; + return { root, target, workspace, path, live, entry, manifest, request }; +} +async function applyMigrateLegacyOwnership(request: MigrateLegacyOwnershipRequest) { + const mutation = await GovernedMutation.begin({ workspaceRoot: request.workspaceRoot, globalRoot: request.globalRoot, + commandName: "agentwheel ownership migrate-legacy", reason: "Verify synthetic metadata migration" }); + try { const result = await applyRaw(request); await mutation?.complete(); return result; } + catch (error) { await mutation?.fail(error); throw error; } +} +async function reviewed(request: MigrateLegacyOwnershipRequest) { + const plan = await planMigrateLegacyOwnership(request); + return { ...request, planDigest: plan.planDigest, expectedSourceRevision: plan.source.revision ?? "absent", + expectedDestinationRevision: plan.destination.revision ?? "absent", expectedInventoryRevision: plan.manifestInventoryRevision }; +} +/** Serves the real manifest for the first `honest` reads of `path`, then a copy with one extra foreign entry. */ +function tamperedReads(path: string, honest: number, extra: InstallManifestEntry) { + let reads = 0; + return { reads: () => reads, transport: { ...localTransport, async readFile(candidate: string) { + const raw = await localTransport.readFile(candidate); + if (candidate !== path || ++reads <= honest) return raw; + const manifest = JSON.parse(raw); + return JSON.stringify({ ...manifest, entries: [...manifest.entries, extra] }); + } } }; +} +const read = (target: string, key: string) => readInstallManifest(target, "openclaw", localTransport, { installationType: "user", stateKey: key }); + +describe("current-owner legacy state migration", () => { + it.each([false, true])("moves exact claims including merge contributions, never runtime bytes (merge=%s)", async merge => { + const f = await fixture(merge), before = await readFile(f.live); + const first = await planMigrateLegacyOwnership(f.request); + expect(await planMigrateLegacyOwnership(f.request)).toEqual(first); + expect(await read(f.target, destinationKey)).toBeUndefined(); + const result = await applyMigrateLegacyOwnership(await reviewed(f.request)); + expect(result.migratedEntries).toBe(1); + expect((await read(f.target, destinationKey))?.entries).toEqual([f.entry]); + expect(await read(f.target, sourceKey)).toBeUndefined(); + expect(await readFile(f.live)).toEqual(before); + expect((await planMigrateLegacyOwnership(f.request)).selected).toEqual([]); + expect((await applyMigrateLegacyOwnership(await reviewed(f.request))).migratedEntries).toBe(0); + }); + + it("refuses entries the configured packages no longer install unless the reviewed plan allows them", async () => { + const f = await fixture(); + const covered = await planMigrateLegacyOwnership(f.request); + expect(covered.selected).toMatchObject([{ path: f.path, desired: true }]); + expect(covered.desiredCoverage).toEqual([{ path: f.path, artifactType: "skills", artifactName: "example", kind: "file" }]); + const undesired = { ...f.request, desiredCoverage: [] }; + await expect(planMigrateLegacyOwnership(undesired)).rejects.toThrow(/no longer install .*--allow-undesired/); + const allowed = await planMigrateLegacyOwnership({ ...undesired, allowUndesired: true }); + expect(allowed).toMatchObject({ allowUndesired: true, desiredCoverage: [], selected: [{ path: f.path, desired: false }] }); + expect((await planMigrateLegacyOwnership({ ...f.request, allowUndesired: true })).planDigest).not.toBe(covered.planDigest); + const reviewedAllowed = await reviewed({ ...undesired, allowUndesired: true }); + await expect(applyMigrateLegacyOwnership({ ...reviewedAllowed, allowUndesired: false })).rejects.toThrow(/no longer install/); + await expect(applyMigrateLegacyOwnership({ ...reviewedAllowed, desiredCoverage: f.request.desiredCoverage })).rejects.toThrow(/Stale plan digest/); + const other = { ...f.request, desiredCoverage: [{ path: f.path, artifactType: "skills", artifactName: "replacement", kind: "file" }] }; + for (const request of [other, { ...other, allowUndesired: true }]) { + await expect(planMigrateLegacyOwnership(request)).rejects.toThrow(/plans a different artifact/); + } + expect(await read(f.target, destinationKey)).toBeUndefined(); + expect((await applyMigrateLegacyOwnership(reviewedAllowed)).migratedEntries).toBe(1); + }); + + it("refuses a stable graph lock left without a destination manifest", async () => { + const f = await fixture(); + await mkdir(dirname(f.request.destinationGraphLockPath), { recursive: true }); + await writeFile(f.request.destinationGraphLockPath, "{}"); + await expect(planMigrateLegacyOwnership(f.request)) + .rejects.toThrow(`Destination has a stable graph lock without a stable manifest at ${f.request.destinationGraphLockPath}; reconcile it before migrating legacy state.`); + await writeInstallManifest({ ...f.manifest, stateKey: destinationKey, entries: [] }); + expect((await planMigrateLegacyOwnership(f.request)).selected).toHaveLength(1); + }); + + it.each(["source", "destination"] as const)("refuses an apply whose re-read %s differs from the reviewed plan", async side => { + const f = await fixture(); + if (side === "destination") { + await writeInstallManifest({ ...f.manifest, stateKey: destinationKey, entries: [{ ...f.entry, path: ".openclaw/skills/unrelated/SKILL.md" }] }); + } + const path = installManifestPath(f.target, "openclaw", { stateKey: side === "source" ? sourceKey : destinationKey }); + const counter = tamperedReads(path, Number.POSITIVE_INFINITY, f.entry); + await planMigrateLegacyOwnership({ ...f.request, transport: counter.transport }); + const destinationBefore = side === "destination" ? await readFile(path) : undefined; + const extra = { ...f.entry, path: ".openclaw/skills/injected/SKILL.md", workspaceOwner: "workspace:other" }; + const { transport } = tamperedReads(path, counter.reads(), extra); + await expect(applyMigrateLegacyOwnership({ ...await reviewed(f.request), transport })).rejects.toThrow(`Stale ${side} revision`); + expect((await read(f.target, sourceKey))?.entries).toEqual([f.entry]); + if (destinationBefore) expect(await readFile(path)).toEqual(destinationBefore); + else expect(await read(f.target, destinationKey)).toBeUndefined(); + }); + + it("treats an explicitly selected path that an earlier apply migrated as a no-op", async () => { + const f = await fixture(); + const foreign = { ...f.entry, path: ".openclaw/skills/other", workspaceOwner: "workspace:other" }; + await writeInstallManifest({ ...f.manifest, entries: [f.entry, foreign] }); + const request = { ...f.request, paths: [f.path] }; + expect((await applyMigrateLegacyOwnership(await reviewed(request))).migratedEntries).toBe(1); + const rerun = await planMigrateLegacyOwnership(request); + expect(rerun.selected).toEqual([]); + expect(rerun.alreadyMigrated).toEqual([{ path: f.path, destinationEntryDigest: expect.stringMatching(/^[a-f0-9]{64}$/) }]); + const destination = await readFile(installManifestPath(f.target, "openclaw", { stateKey: destinationKey })); + expect((await applyMigrateLegacyOwnership(await reviewed(request))).migratedEntries).toBe(0); + expect(await readFile(installManifestPath(f.target, "openclaw", { stateKey: destinationKey }))).toEqual(destination); + await expect(planMigrateLegacyOwnership({ ...f.request, paths: [".openclaw/skills/missing"] })).rejects.toThrow(/current workspace/); + await expect(planMigrateLegacyOwnership({ ...f.request, paths: [foreign.path] })).rejects.toThrow(/current workspace/); + await writeFile(f.live, "Drift\n"); + await expect(planMigrateLegacyOwnership(request)).rejects.toThrow(); + }); + + it("still refuses missing and foreign explicit paths once a full apply removed the source", async () => { + const f = await fixture(); + expect((await applyMigrateLegacyOwnership(await reviewed(f.request))).migratedEntries).toBe(1); + expect(await read(f.target, sourceKey)).toBeUndefined(); + const destination = (await read(f.target, destinationKey)) as InstallManifestV2; + const foreign = { ...f.entry, path: ".openclaw/skills/other", workspaceOwner: "workspace:other" }; + await writeInstallManifest({ ...destination, entries: [...destination.entries, foreign] }); + await expect(planMigrateLegacyOwnership({ ...f.request, paths: [".openclaw/skills/missing"] })).rejects.toThrow(/current workspace/); + await expect(planMigrateLegacyOwnership({ ...f.request, paths: [foreign.path] })).rejects.toThrow(/current workspace/); + expect((await planMigrateLegacyOwnership({ ...f.request, paths: [f.path] })).alreadyMigrated.map(item => item.path)).toEqual([f.path]); + }); + + it("supports unsuffixed source and explicitly configured destination state keys", async () => { + const f = await fixture(); + await rm(installManifestPath(f.target, "openclaw", { stateKey: sourceKey })); + await writeInstallManifest({ ...f.manifest, stateKey: "openclaw.user" }); + const request = { ...f.request, sourceStateKey: "openclaw.user", destinationStateKey: "configured-target" }; + await applyMigrateLegacyOwnership(await reviewed(request)); + expect((await read(f.target, "configured-target"))?.entries).toEqual([f.entry]); + }); + + it("preserves foreign entries and refuses explicitly selected foreign ownership", async () => { + const f = await fixture(); + const foreign = { ...f.entry, path: ".openclaw/skills/other", workspaceOwner: "workspace:other" }; + await writeInstallManifest({ ...f.manifest, entries: [f.entry, foreign] }); + await expect(planMigrateLegacyOwnership({ ...f.request, paths: [foreign.path] })).rejects.toThrow(/current workspace/); + await applyMigrateLegacyOwnership(await reviewed(f.request)); + expect((await read(f.target, sourceKey))?.entries).toEqual([foreign]); + }); + + it.each([false, true])("rejects runtime drift (merge=%s)", async merge => { + const f = await fixture(merge); + await writeFile(f.live, merge ? '{"tools":{"allow":["changed"]}}' : "Changed\n"); + await expect(planMigrateLegacyOwnership(f.request)).rejects.toThrow(); + expect(await read(f.target, destinationKey)).toBeUndefined(); + }); + + it("refuses incomplete merge metadata and foreign, duplicate, cross-adapter, and ancestor claims", async () => { + const f = await fixture(true); + await writeInstallManifest({ ...f.manifest, entries: [{ ...f.entry, mergeRemoval: undefined }] }); + await expect(planMigrateLegacyOwnership(f.request)).rejects.toThrow(/incomplete merge/); + await writeInstallManifest(f.manifest); + for (const other of [ { ...f.entry, workspaceOwner: "workspace:other" }, f.entry, { ...f.entry, path: ".openclaw" } ]) { + await writeInstallManifest({ ...f.manifest, stateKey: "openclaw.user.other", entries: [other] }); + await expect(planMigrateLegacyOwnership(f.request)).rejects.toThrow(/Conflicting/); + } + await rm(installManifestPath(f.target, "openclaw", { stateKey: "openclaw.user.other" })); + await writeInstallManifest({ ...f.manifest, adapter: "claude", stateKey: "claude.user.other", entries: [f.entry] }); + await expect(planMigrateLegacyOwnership(f.request)).rejects.toThrow(/Conflicting/); + }); + + it("retires exact covered duplicates after destination-first interruption", async () => { + const f = await fixture(true), before = await readFile(f.live); + await writeInstallManifest({ ...f.manifest, stateKey: destinationKey }); + expect((await planMigrateLegacyOwnership(f.request)).selected[0]?.action).toBe("retire-covered"); + const replacement = [{ path: f.path, artifactType: "settings", artifactName: "replacement", kind: "file" as const }]; + for (const desiredCoverage of [[], replacement]) { + expect((await planMigrateLegacyOwnership({ ...f.request, desiredCoverage })).selected) + .toMatchObject([{ path: f.path, action: "retire-covered" }]); + } + const destination = await readFile(installManifestPath(f.target, "openclaw", { stateKey: destinationKey })); + await applyMigrateLegacyOwnership(await reviewed(f.request)); + expect(await readFile(installManifestPath(f.target, "openclaw", { stateKey: destinationKey }))).toEqual(destination); + expect(await read(f.target, sourceKey)).toBeUndefined(); + expect(await readFile(f.live)).toEqual(before); + }); + + it("refuses even a reviewed local apply without a matching durable receipt", async () => { + const f = await fixture(); + await expect(applyRaw(await reviewed(f.request))).rejects.toThrow(/durable mutation receipt/); + expect(await read(f.target, destinationKey)).toBeUndefined(); + }); + + it("requires all reviewed values and refuses stale runtime, manifest and inventory", async () => { + const f = await fixture(); + await expect(applyMigrateLegacyOwnership(f.request)).rejects.toThrow(/reviewed/); + const request = await reviewed(f.request); + await writeFile(f.live, "Drift\n"); + await expect(applyMigrateLegacyOwnership(request)).rejects.toThrow(); + await writeFile(f.live, "Example skill\n"); + await writeInstallManifest({ ...f.manifest, stateKey: "openclaw.user.unrelated", entries: [] }); + await expect(applyMigrateLegacyOwnership(request)).rejects.toThrow(/Stale/); + expect(await read(f.target, destinationKey)).toBeUndefined(); + }); + + it("refuses pending journals and recovers a crash after the destination journal write", async () => { + const f = await fixture(), before = await readFile(f.live); + let fail = true; + const transport = { ...localTransport, async writeJsonAtomic(path: string, data: unknown) { + await localTransport.writeJsonAtomic(path, data); + if (fail && path.endsWith(".apply-journal.json")) { fail = false; throw new Error("Injected crash"); } + } }; + const request = await reviewed({ ...f.request, transport }); + await expect(applyMigrateLegacyOwnership(request)).rejects.toThrow(/Injected crash/); + await expect(planMigrateLegacyOwnership(f.request)).rejects.toThrow(/Pending/); + const journal = JSON.parse(await readFile(join(f.target, ".agentwheel", `${destinationKey}.apply-journal.json`), "utf8")); + const recovered = await recoverMutationRuntime(journal.mutation.operationId); + expect(recovered.runtimeJournals.every(item => item.status === "resolved")).toBe(true); + await applyMigrateLegacyOwnership(await reviewed(f.request)); + expect(await readFile(f.live)).toEqual(before); + expect(await read(f.target, sourceKey)).toBeUndefined(); + }); +}); diff --git a/test/run-as-ownership.test.ts b/test/run-as-ownership.test.ts index aaaa355d..fc92a8e1 100644 --- a/test/run-as-ownership.test.ts +++ b/test/run-as-ownership.test.ts @@ -1,3 +1,4 @@ +import { applyMigrateLegacyOwnership, planMigrateLegacyOwnership } from "../src/lifecycle/ownership-migrate-legacy.js"; import { createHash } from "node:crypto"; import { chmod, link, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises"; import { spawnSync } from "node:child_process"; @@ -118,6 +119,23 @@ async function retireRequest(f: Awaited>) { } describe.skipIf(process.platform !== "linux" || uid === 0).sequential("confined run-as ownership metadata", () => { + it("migrates current-owner state through the confined worker without runtime changes", async () => { + const f = await fixture(), before = await f.transport.ownershipObservation!(f.artifact); + await writeInstallManifest({ ...f.manifest, entries: [{ ...f.entry, workspaceOwner: workspaceOwnerForRoot(f.workspace) }] }); + const request = { targetRoot: f.target, workspaceRoot: f.workspace, globalRoot: f.home, adapter: "openclaw", + installationType: "user", sourceStateKey: sourceKey, destinationStateKey: destinationKey, transport: f.transport, + desiredCoverage: f.adopt.desiredCoverage, destinationGraphLockPath: f.adopt.destinationGraphLockPath }; + const plan = await planMigrateLegacyOwnership(request); + expect(plan.transport?.identity).toEqual(f.transport.runAsIdentity); + const reviewed = { ...request, planDigest: plan.planDigest, expectedSourceRevision: plan.source.revision!, + expectedDestinationRevision: plan.destination.revision ?? "absent", expectedInventoryRevision: plan.manifestInventoryRevision }; + await expect(applyMigrateLegacyOwnership(reviewed)).rejects.toThrow(/durable.*receipt/i); + expect(await governed(f, () => applyMigrateLegacyOwnership(reviewed))).toMatchObject({ migratedEntries: 1 }); + expect(await f.transport.ownershipObservation!(f.artifact)).toEqual(before); + expect((await readInstallManifest(f.target, "openclaw", f.transport, { installationType: "user", stateKey: destinationKey }))?.entries) + .toEqual([{ ...f.entry, workspaceOwner: workspaceOwnerForRoot(f.workspace) }]); + }, 30_000); + it("adopts and retires metadata only with a durable caller receipt, preserving every runtime byte and mode", async () => { const f = await fixture(), before = await f.transport.ownershipObservation!(f.artifact), lock = await readFile(f.lockPath); const plan = await planAdoptLegacyOwnership(f.adopt), request = reviewedAdoption(f.adopt, plan);