From 92ff30a0c616a7e984a9796b1309cfc54d698891 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 09:43:14 +0000 Subject: [PATCH 1/5] feat: migrate current-owner legacy install claims without runtime writes --- CHANGELOG.md | 4 + src/cli/index.ts | 56 ++++++++ src/lifecycle/ownership-adopt-legacy.ts | 6 +- src/lifecycle/ownership-migrate-legacy.ts | 161 ++++++++++++++++++++++ src/mutation/commands.ts | 1 + test/ownership-migrate-legacy.test.ts | 127 +++++++++++++++++ 6 files changed, 352 insertions(+), 3 deletions(-) create mode 100644 src/lifecycle/ownership-migrate-legacy.ts create mode 100644 test/ownership-migrate-legacy.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index cae74170..9e081e04 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Changelog +## Unreleased + +- Add reviewed, metadata-only `ownership migrate-legacy` for current-owner claims, including exact managed JSON contributions and confined local-run-as targets. + ## 0.22.6 - Refuse a pin that would bring a different artifact onto an install name already taken in a profile, before anything is written. Collisions already in the config only warn, so a pin can still repair them, and an unreachable source only warns. diff --git a/src/cli/index.ts b/src/cli/index.ts index ac491a9b..ddd042bd 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,61 @@ ownershipCommand if (!options.apply) console.log(`Apply: ${applyCommand}`); }); +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("--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) => { + 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 request = { targetRoot: stable.installRoot, adapter: adapter.name, installationType: group.installationType, + sourceStateKey: options.sourceStateKey, destinationStateKey: stable.stateKey, workspaceRoot: target.workspaceRoot, + 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]), + "--plan-digest", result.planDigest, "--expected-source-revision", result.source.revision ?? "absent", + "--expected-destination-revision", result.destination.revision ?? "absent", "--expected-inventory-revision", result.manifestInventoryRevision, "--apply"]; + 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"}`); + 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") diff --git a/src/lifecycle/ownership-adopt-legacy.ts b/src/lifecycle/ownership-adopt-legacy.ts index 467bea5c..00033a34 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, diff --git a/src/lifecycle/ownership-migrate-legacy.ts b/src/lifecycle/ownership-migrate-legacy.ts new file mode 100644 index 00000000..e90925d3 --- /dev/null +++ b/src/lifecycle/ownership-migrate-legacy.ts @@ -0,0 +1,161 @@ +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 { declareMutationPath } from "../mutation/declarations.js"; +import { localTransport, type TargetTransport } from "../transport/index.js"; +import { commitOwnershipManifestMetadata } 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; + 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" }>; + retained: Array<{ path: string; owner: string }>; + 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].every(key => key.startsWith(`${request.adapter}.${installationType}.`))) { + throw new Error("State keys must match the selected adapter and installation type."); + } + 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); + 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))) ?? []; + // An absent source is an idempotent no-op. An existing source must prove every explicit selection. + if (source && requested?.some(path => !entries.some(entry => entry.path === path))) { + throw new Error("Every selected path must exist in the source and be owned by the current workspace."); + } + 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; + if (item.stateKey === sourceKey && other === entry) 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) === entryDigest(entry) && !covered) { covered = true; continue; } + throw new Error(`Conflicting or overlapping ownership claim at ${entry.path} in ${item.stateKey}.`); + } + selected.push({ path: entry.path, sourceEntryDigest: entryDigest(entry), action: covered ? "retire-covered" : "migrate" }); + 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)), + 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)), + 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; + 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 = plan.destination.revision ? await requireManifest(identity, plan.destination.stateKey, transport, "destination") : undefined; + 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.test.ts b/test/ownership-migrate-legacy.test.ts new file mode 100644 index 00000000..8a077ef1 --- /dev/null +++ b/test/ownership-migrate-legacy.test.ts @@ -0,0 +1,127 @@ +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, 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 { applyJournalPath } from "../src/install/transaction.js"; +import { recoverPendingApply } from "../src/install/apply.js"; + +const roots: string[] = []; +afterEach(async () => { 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); + 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: [] })); + 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), + 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 }; + return { root, target, workspace, path, live, entry, manifest, request }; +} +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 }; +} +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("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 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("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/); + await recoverPendingApply(f.target, "openclaw", { installationType: "user", stateKey: destinationKey }); + await applyMigrateLegacyOwnership(await reviewed(f.request)); + expect(await readFile(f.live)).toEqual(before); + expect(await read(f.target, sourceKey)).toBeUndefined(); + }); +}); From ad4519cf0c3c9a389439178a769af92632804c9a Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 09:48:10 +0000 Subject: [PATCH 2/5] test: cover legacy migration guards, confined worker and operator copy checks --- CHANGELOG.md | 4 +- README.md | 1 + docs/ownership-legacy-migration.md | 72 +++++++++++++++ scripts/legacy-migration-copy-check.py | 104 ++++++++++++++++++++++ src/lifecycle/ownership-migrate-legacy.ts | 6 +- test/ownership-migrate-legacy-cli.test.ts | 39 ++++++++ test/ownership-migrate-legacy.test.ts | 14 ++- test/run-as-ownership.test.ts | 17 ++++ 8 files changed, 246 insertions(+), 11 deletions(-) create mode 100644 docs/ownership-legacy-migration.md create mode 100644 scripts/legacy-migration-copy-check.py create mode 100644 test/ownership-migrate-legacy-cli.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 9e081e04..3bbe0be5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,11 +1,9 @@ # Changelog -## Unreleased +## 0.22.6 - Add reviewed, metadata-only `ownership migrate-legacy` for current-owner claims, including exact managed JSON contributions and confined local-run-as targets. -## 0.22.6 - - Refuse a pin that would bring a different artifact onto an install name already taken in a profile, before anything is written. Collisions already in the config only warn, so a pin can still repair them, and an unreachable source only warns. - Refuse a pin that would leave a package override matching nothing, which also breaks install, and point at selectors by source that survive a pin. - Report every colliding install name in one error instead of stopping at the first. 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..334d5249 --- /dev/null +++ b/docs/ownership-legacy-migration.md @@ -0,0 +1,72 @@ +# 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. + +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): + +```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 +``` + +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 and checks manifest revisions, 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. 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. The checker below never opens a live service root. 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 +``` + +Each invocation creates a new disposable directory and prints its location. 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. +Keep the printed directory as evidence. 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..8efa036e --- /dev/null +++ b/scripts/legacy-migration-copy-check.py @@ -0,0 +1,104 @@ +#!/usr/bin/env python3 +"""Verify metadata-only migration on a disposable copy of an existing snapshot. + +Never accesses a live service root. The operator supplies an already captured, +readable snapshot containing .agentwheel and its claimed runtime paths. +""" +import argparse +import hashlib +import json +from pathlib import Path +import os +import shutil +import stat +import subprocess +import tempfile + + +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('--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') + 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-')) + 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') + env = {**os.environ, 'HOME': str(target), 'AGENTWHEEL_MUTATION_STATE_ROOT': str(base / 'receipts')} + command = [args.node, str(cli), 'ownership', 'migrate-legacy', '--local', '--agent', 'copy', '--source-state-key', key] + def run(extra): + return subprocess.run(command + extra, cwd=workspace, env=env, check=True, capture_output=True, text=True).stdout + before = snapshot(target) + plan = json.loads(run(['--json'])) + (base / 'plan.json').write_text(json.dumps(plan, indent=2) + '\n') + print(f'Evidence directory: {base}', flush=True) + 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']: + 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/lifecycle/ownership-migrate-legacy.ts b/src/lifecycle/ownership-migrate-legacy.ts index e90925d3..26e2777a 100644 --- a/src/lifecycle/ownership-migrate-legacy.ts +++ b/src/lifecycle/ownership-migrate-legacy.ts @@ -53,9 +53,6 @@ export async function planMigrateLegacyOwnership(request: MigrateLegacyOwnership 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].every(key => key.startsWith(`${request.adapter}.${installationType}.`))) { - throw new Error("State keys must match the selected adapter and installation type."); - } 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); @@ -93,12 +90,11 @@ export async function planMigrateLegacyOwnership(request: MigrateLegacyOwnership 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; - if (item.stateKey === sourceKey && other === entry) 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) === entryDigest(entry) && !covered) { covered = true; continue; } + && entryDigest(other as InstallManifestEntry) === entryDigest(entry) && !covered) { covered = true; continue; } throw new Error(`Conflicting or overlapping ownership claim at ${entry.path} in ${item.stateKey}.`); } selected.push({ path: entry.path, sourceEntryDigest: entryDigest(entry), action: covered ? "retire-covered" : "migrate" }); diff --git a/test/ownership-migrate-legacy-cli.test.ts b/test/ownership-migrate-legacy-cli.test.ts new file mode 100644 index 00000000..baeeb9e3 --- /dev/null +++ b/test/ownership-migrate-legacy-cli.test.ts @@ -0,0 +1,39 @@ +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 }))); }); +it("migrates a configured target state and makes the next install dry-run managed", async () => { + 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"), join(pack, "skills/example"), target, home]) 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" }] })); + await writeFile(join(pack, "skills/example/SKILL.md"), "---\nname: example\ndescription: Synthetic fixture\n---\nExample\n"); + await writeFile(join(workspace, ".agentwheel/config.json"), JSON.stringify({ schemaVersion: 4, + agents: { example: { adapter: "claude", root: target, transport: "local" } }, + packages: [{ name: "example", driver: "local", source: pack, mode: "pinned", select: ["skills/example"] }] })); + const run = (args: string[]) => exec(process.execPath, [cli, ...args], { 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 before = await readFile(join(target, ".claude/skills/example/SKILL.md")); + const args = ["ownership", "migrate-legacy", "--agent", "example", "--source-state-key", legacyKey]; + const plan = JSON.parse((await run([...args, "--json"])).stdout); + expect(plan.selected).toHaveLength(1); + expect(plan.destination.stateKey).toBe(current.replace(".install-manifest.json", "")); + await run([...args, "--plan-digest", plan.planDigest, "--expected-source-revision", plan.source.revision, + "--expected-destination-revision", "absent", "--expected-inventory-revision", plan.manifestInventoryRevision, "--apply"]); + 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); diff --git a/test/ownership-migrate-legacy.test.ts b/test/ownership-migrate-legacy.test.ts index 8a077ef1..0ec773b2 100644 --- a/test/ownership-migrate-legacy.test.ts +++ b/test/ownership-migrate-legacy.test.ts @@ -8,7 +8,6 @@ import { applyMigrateLegacyOwnership, planMigrateLegacyOwnership, type MigrateLe 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 { applyJournalPath } from "../src/install/transaction.js"; import { recoverPendingApply } from "../src/install/apply.js"; const roots: string[] = []; @@ -25,7 +24,7 @@ async function fixture(merge = false) { 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), - dependencyRole: "root", owners: ["example"], refCount: 1, workspaceOwner: workspaceOwnerForRoot(workspace), + 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] }; @@ -56,6 +55,15 @@ describe("current-owner legacy state migration", () => { expect((await applyMigrateLegacyOwnership(await reviewed(f.request))).migratedEntries).toBe(0); }); + 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" }; @@ -119,7 +127,7 @@ describe("current-owner legacy state migration", () => { const request = await reviewed({ ...f.request, transport }); await expect(applyMigrateLegacyOwnership(request)).rejects.toThrow(/Injected crash/); await expect(planMigrateLegacyOwnership(f.request)).rejects.toThrow(/Pending/); - await recoverPendingApply(f.target, "openclaw", { installationType: "user", stateKey: destinationKey }); + await recoverPendingApply(f.target, "openclaw", localTransport, { installationType: "user", stateKey: destinationKey }); 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..052cb903 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,22 @@ 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 }; + 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); From b417ca07f0d4a19239e80e04b731b42cd3b2d845 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 09:51:23 +0000 Subject: [PATCH 3/5] fix: require durable receipts for recoverable legacy state migration --- docs/ownership-legacy-migration.md | 6 +++++ src/lifecycle/ownership-migrate-legacy.ts | 5 ++++ test/ownership-migrate-legacy-cli.test.ts | 4 ++-- test/ownership-migrate-legacy.test.ts | 29 +++++++++++++++++++---- 4 files changed, 37 insertions(+), 7 deletions(-) diff --git a/docs/ownership-legacy-migration.md b/docs/ownership-legacy-migration.md index 334d5249..b7eac575 100644 --- a/docs/ownership-legacy-migration.md +++ b/docs/ownership-legacy-migration.md @@ -31,6 +31,12 @@ agentwheel ownership migrate-legacy --local --agent example \ 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 and checks manifest revisions, the complete inventory, runtime hashes and runtime diff --git a/src/lifecycle/ownership-migrate-legacy.ts b/src/lifecycle/ownership-migrate-legacy.ts index 26e2777a..3687599d 100644 --- a/src/lifecycle/ownership-migrate-legacy.ts +++ b/src/lifecycle/ownership-migrate-legacy.ts @@ -7,6 +7,7 @@ import { acquireApplyLock, assertNoSymlinkPath, assertOwnershipMetadataTransport 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 { commitOwnershipManifestMetadata } from "./ownership-adopt-legacy.js"; @@ -123,6 +124,10 @@ export async function applyMigrateLegacyOwnership(request: MigrateLegacyOwnershi } } 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 { diff --git a/test/ownership-migrate-legacy-cli.test.ts b/test/ownership-migrate-legacy-cli.test.ts index baeeb9e3..37a0bc21 100644 --- a/test/ownership-migrate-legacy-cli.test.ts +++ b/test/ownership-migrate-legacy-cli.test.ts @@ -14,10 +14,10 @@ it("migrates a configured target state and makes the next install dry-run manage for (const path of [join(workspace, ".agentwheel"), join(pack, "skills/example"), target, home]) 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" }] })); await writeFile(join(pack, "skills/example/SKILL.md"), "---\nname: example\ndescription: Synthetic fixture\n---\nExample\n"); - await writeFile(join(workspace, ".agentwheel/config.json"), JSON.stringify({ schemaVersion: 4, + await writeFile(join(workspace, ".agentwheel/config.json"), 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: ["skills/example"] }] })); - const run = (args: string[]) => exec(process.execPath, [cli, ...args], { cwd: workspace, + 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"))!; diff --git a/test/ownership-migrate-legacy.test.ts b/test/ownership-migrate-legacy.test.ts index 0ec773b2..930cf9ec 100644 --- a/test/ownership-migrate-legacy.test.ts +++ b/test/ownership-migrate-legacy.test.ts @@ -4,20 +4,25 @@ 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, planMigrateLegacyOwnership, type MigrateLegacyOwnershipRequest } from "../src/lifecycle/ownership-migrate-legacy.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 { recoverPendingApply } from "../src/install/apply.js"; +import { GovernedMutation, recoverMutationRuntime } from "../src/mutation/coordinator.js"; const roots: string[] = []; -afterEach(async () => { await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true }))); }); +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: [] })); + 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 }); @@ -33,6 +38,12 @@ async function fixture(merge = false) { installationType: "user", sourceStateKey: sourceKey, destinationStateKey: destinationKey }; 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", @@ -105,6 +116,12 @@ describe("current-owner legacy state migration", () => { 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/); @@ -127,7 +144,9 @@ describe("current-owner legacy state migration", () => { const request = await reviewed({ ...f.request, transport }); await expect(applyMigrateLegacyOwnership(request)).rejects.toThrow(/Injected crash/); await expect(planMigrateLegacyOwnership(f.request)).rejects.toThrow(/Pending/); - await recoverPendingApply(f.target, "openclaw", localTransport, { installationType: "user", stateKey: destinationKey }); + 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(); From b893cdab44c376783c86cb2f8777bbe08dfd0677 Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:44:19 +0000 Subject: [PATCH 4/5] fix(ownership): gate legacy migration on desired coverage and re-read revisions Compute desired coverage for migrate-legacy like adopt-legacy, record it in the plan digest, and refuse entries the graph no longer installs unless --allow-undesired is passed. Refuse an orphan destination graph lock, re-check source and destination revisions after the apply re-read, and treat already-migrated --path selections as a no-op. Harden the snapshot copy check and include --reason in the printed apply command. --- CHANGELOG.md | 2 - docs/ownership-legacy-migration.md | 41 ++++++++++-- scripts/legacy-migration-copy-check.py | 36 ++++++++-- src/cli/index.ts | 44 ++++++++----- src/lifecycle/ownership-adopt-legacy.ts | 36 ++++++---- src/lifecycle/ownership-migrate-legacy.ts | 49 ++++++++++++-- test/ownership-migrate-legacy-cli.test.ts | 65 +++++++++++++++--- test/ownership-migrate-legacy.test.ts | 80 ++++++++++++++++++++++- test/run-as-ownership.test.ts | 3 +- 9 files changed, 293 insertions(+), 63 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3bbe0be5..cae74170 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,8 +2,6 @@ ## 0.22.6 -- Add reviewed, metadata-only `ownership migrate-legacy` for current-owner claims, including exact managed JSON contributions and confined local-run-as targets. - - Refuse a pin that would bring a different artifact onto an install name already taken in a profile, before anything is written. Collisions already in the config only warn, so a pin can still repair them, and an unreachable source only warns. - Refuse a pin that would leave a package override matching nothing, which also breaks install, and point at selectors by source that survive a pin. - Report every colliding install name in one error instead of stopping at the first. diff --git a/docs/ownership-legacy-migration.md b/docs/ownership-legacy-migration.md index b7eac575..cf102583 100644 --- a/docs/ownership-legacy-migration.md +++ b/docs/ownership-legacy-migration.md @@ -17,8 +17,18 @@ The destination is calculated exactly as for install, including explicit configu 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): +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 \ @@ -39,7 +49,8 @@ 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 and checks manifest revisions, the complete inventory, runtime hashes and runtime +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 @@ -49,13 +60,19 @@ The destination commits first. If interrupted, recover the pending journal throu 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. A fresh digest is required -for each apply; do not reuse a pre-interruption plan. +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. The checker below never opens a live service root. Pass only that +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. @@ -67,12 +84,22 @@ python3 scripts/legacy-migration-copy-check.py \ 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. Only that copy's +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. -Keep the printed directory as evidence. This verifies copied legacy claims, not the live endpoint, +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 index 8efa036e..ead3f1f4 100644 --- a/scripts/legacy-migration-copy-check.py +++ b/scripts/legacy-migration-copy-check.py @@ -1,8 +1,11 @@ #!/usr/bin/env python3 """Verify metadata-only migration on a disposable copy of an existing snapshot. -Never accesses a live service root. The operator supplies an already captured, -readable snapshot containing .agentwheel and its claimed runtime paths. +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 @@ -12,8 +15,11 @@ import shutil import stat import subprocess +import sys import tempfile +PENDING_METADATA_SUFFIXES = ('.runtime-apply-lock', '.apply-journal.json') + def snapshot(root): result = {} @@ -35,6 +41,8 @@ def main(): 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) @@ -43,6 +51,9 @@ def main(): 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') @@ -72,14 +83,25 @@ def main(): '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') - env = {**os.environ, 'HOME': str(target), 'AGENTWHEEL_MUTATION_STATE_ROOT': str(base / 'receipts')} - command = [args.node, str(cli), 'ownership', 'migrate-legacy', '--local', '--agent', 'copy', '--source-state-key', key] + # 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): - return subprocess.run(command + extra, cwd=workspace, env=env, check=True, capture_output=True, text=True).stdout + 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'Evidence directory: {base}', flush=True) + print(f'Evidence directory (full runtime copy, remove after review): {base}', flush=True) print(f'Plan digest: {plan["planDigest"]}; selected entries: {len(plan["selected"])}', flush=True) if not plan['selected']: raise RuntimeError('Expected a nonempty migration plan') @@ -92,7 +114,7 @@ def run(extra): if snapshot(target) != before: raise RuntimeError('Runtime bytes or modes changed in disposable copy') repeated = json.loads(run(['--json'])) - if repeated['selected']: + 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') diff --git a/src/cli/index.ts b/src/cli/index.ts index ddd042bd..7acac5bf 100644 --- a/src/cli/index.ts +++ b/src/cli/index.ts @@ -1334,6 +1334,25 @@ 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") @@ -1345,13 +1364,14 @@ ownershipCommand .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) => { + .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); @@ -1366,8 +1386,10 @@ ownershipCommand 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 }; @@ -1377,14 +1399,18 @@ ownershipCommand ...(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"]; + "--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}`); }); @@ -1467,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 00033a34..3d84fee1 100644 --- a/src/lifecycle/ownership-adopt-legacy.ts +++ b/src/lifecycle/ownership-adopt-legacy.ts @@ -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 index 3687599d..824b9ae0 100644 --- a/src/lifecycle/ownership-migrate-legacy.ts +++ b/src/lifecycle/ownership-migrate-legacy.ts @@ -10,7 +10,8 @@ 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 { commitOwnershipManifestMetadata } from "./ownership-adopt-legacy.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"; @@ -22,6 +23,11 @@ export interface MigrateLegacyOwnershipRequest { 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; @@ -37,8 +43,11 @@ export interface MigrateLegacyOwnershipPlan { 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" }>; + 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; @@ -63,6 +72,7 @@ export async function planMigrateLegacyOwnership(request: MigrateLegacyOwnership 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") { @@ -72,14 +82,32 @@ export async function planMigrateLegacyOwnership(request: MigrateLegacyOwnership 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))) ?? []; - // An absent source is an idempotent no-op. An existing source must prove every explicit selection. - if (source && requested?.some(path => !entries.some(entry => entry.path === path))) { - throw new Error("Every selected path must exist in the source and be owned by the current workspace."); + // 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 if (source) { + 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 desiredAtPath = desiredByPath.get(entry.path) ?? []; + if (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 (!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."); + } 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}.`); @@ -98,7 +126,7 @@ export async function planMigrateLegacyOwnership(request: MigrateLegacyOwnership && entryDigest(other as InstallManifestEntry) === entryDigest(entry) && !covered) { covered = true; continue; } throw new Error(`Conflicting or overlapping ownership claim at ${entry.path} in ${item.stateKey}.`); } - selected.push({ path: entry.path, sourceEntryDigest: entryDigest(entry), action: covered ? "retire-covered" : "migrate" }); + 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)); @@ -107,8 +135,11 @@ export async function planMigrateLegacyOwnership(request: MigrateLegacyOwnership 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 } : {}), @@ -139,7 +170,11 @@ export async function applyMigrateLegacyOwnership(request: MigrateLegacyOwnershi 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 = plan.destination.revision ? await requireManifest(identity, plan.destination.stateKey, transport, "destination") : undefined; + 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(); diff --git a/test/ownership-migrate-legacy-cli.test.ts b/test/ownership-migrate-legacy-cli.test.ts index 37a0bc21..26843193 100644 --- a/test/ownership-migrate-legacy-cli.test.ts +++ b/test/ownership-migrate-legacy-cli.test.ts @@ -8,15 +8,28 @@ 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 }))); }); -it("migrates a configured target state and makes the next install dry-run managed", async () => { +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"), join(pack, "skills/example"), target, home]) await mkdir(path, { recursive: true }); + 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" }] })); - await writeFile(join(pack, "skills/example/SKILL.md"), "---\nname: example\ndescription: Synthetic fixture\n---\nExample\n"); - await writeFile(join(workspace, ".agentwheel/config.json"), JSON.stringify({ schemaVersion: 4, mutationPolicy: { reason: "required", journal: "required", revisioning: { mode: "off" } }, + 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: ["skills/example"] }] })); + 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"]); @@ -25,15 +38,49 @@ it("migrates a configured target state and makes the next install dry-run manage 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 args = ["ownership", "migrate-legacy", "--agent", "example", "--source-state-key", legacyKey]; const plan = JSON.parse((await run([...args, "--json"])).stdout); - expect(plan.selected).toHaveLength(1); + expect(plan.selected).toMatchObject([{ desired: true }]); + expect(plan.desiredCoverage).toHaveLength(1); expect(plan.destination.stateKey).toBe(current.replace(".install-manifest.json", "")); - await run([...args, "--plan-digest", plan.planDigest, "--expected-source-revision", plan.source.revision, - "--expected-destination-revision", "absent", "--expected-inventory-revision", plan.manifestInventoryRevision, "--apply"]); + 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 index 930cf9ec..bdc7866a 100644 --- a/test/ownership-migrate-legacy.test.ts +++ b/test/ownership-migrate-legacy.test.ts @@ -35,7 +35,9 @@ async function fixture(merge = false) { 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 }; + 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) { @@ -49,6 +51,16 @@ async function reviewed(request: MigrateLegacyOwnershipRequest) { 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", () => { @@ -66,6 +78,72 @@ describe("current-owner legacy state migration", () => { 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("supports unsuffixed source and explicitly configured destination state keys", async () => { const f = await fixture(); await rm(installManifestPath(f.target, "openclaw", { stateKey: sourceKey })); diff --git a/test/run-as-ownership.test.ts b/test/run-as-ownership.test.ts index 052cb903..fc92a8e1 100644 --- a/test/run-as-ownership.test.ts +++ b/test/run-as-ownership.test.ts @@ -123,7 +123,8 @@ describe.skipIf(process.platform !== "linux" || uid === 0).sequential("confined 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 }; + 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!, From d4c76f790d0c06f3d72af3c94a606b4204a8ca7a Mon Sep 17 00:00:00 2001 From: Yehonal <147092+Yehonal@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:21:36 +0000 Subject: [PATCH 5/5] Guard missing legacy selections and preserve evidence --- scripts/legacy-migration-copy-check.py | 2 +- src/lifecycle/ownership-migrate-legacy.ts | 19 ++++++++++--------- test/ownership-migrate-legacy.test.ts | 17 +++++++++++++++++ 3 files changed, 28 insertions(+), 10 deletions(-) diff --git a/scripts/legacy-migration-copy-check.py b/scripts/legacy-migration-copy-check.py index ead3f1f4..e1c80d8d 100644 --- a/scripts/legacy-migration-copy-check.py +++ b/scripts/legacy-migration-copy-check.py @@ -58,6 +58,7 @@ def main(): 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()) @@ -101,7 +102,6 @@ def run(extra): before = snapshot(target) plan = json.loads(run(['--json'])) (base / 'plan.json').write_text(json.dumps(plan, indent=2) + '\n') - print(f'Evidence directory (full runtime copy, remove after review): {base}', flush=True) print(f'Plan digest: {plan["planDigest"]}; selected entries: {len(plan["selected"])}', flush=True) if not plan['selected']: raise RuntimeError('Expected a nonempty migration plan') diff --git a/src/lifecycle/ownership-migrate-legacy.ts b/src/lifecycle/ownership-migrate-legacy.ts index 824b9ae0..ec218265 100644 --- a/src/lifecycle/ownership-migrate-legacy.ts +++ b/src/lifecycle/ownership-migrate-legacy.ts @@ -90,7 +90,7 @@ export async function planMigrateLegacyOwnership(request: MigrateLegacyOwnership 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 if (source) { + } else { throw new Error("Every selected path must exist in the source and be owned by the current workspace."); } } @@ -100,14 +100,6 @@ export async function planMigrateLegacyOwnership(request: MigrateLegacyOwnership 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 desiredAtPath = desiredByPath.get(entry.path) ?? []; - if (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 (!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."); - } 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}.`); @@ -126,6 +118,15 @@ export async function planMigrateLegacyOwnership(request: MigrateLegacyOwnership && 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 }); } diff --git a/test/ownership-migrate-legacy.test.ts b/test/ownership-migrate-legacy.test.ts index bdc7866a..50d4ec20 100644 --- a/test/ownership-migrate-legacy.test.ts +++ b/test/ownership-migrate-legacy.test.ts @@ -144,6 +144,18 @@ describe("current-owner legacy state migration", () => { 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 })); @@ -187,6 +199,11 @@ describe("current-owner legacy state migration", () => { 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);