Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -643,6 +643,7 @@ agentwheel mutation list
agentwheel mutation show <operation-id>
agentwheel mutation finalize <operation-id>
agentwheel mutation recover-runtime <operation-id>
agentwheel mutation recover-runtime <operation-id> --dry-run --json
```

See [the v1 revision-provider specification](docs/specs/revision-provider-v1.md) for configuration,
Expand Down Expand Up @@ -1064,3 +1065,10 @@ Built-in runtime targets:
## License

See [`LICENSE`](LICENSE).

For a partial guarded metadata transaction with zero runtime operations, `mutation recover-runtime --dry-run`
observes the linked journal, runtime block/file hashes, exact snapshots, and inventory without locks,
receipt/journal updates, files, or revision-provider calls. `mutation recover --dry-run` and
`mutation finalize --dry-run` show the same preview and identify `recover-runtime` as the required next
command; ordinary finalize/recover still refuse partial handlers. The preview is advisory: execution
revalidates repository leases and all guards under locks. Other runtime recovery shapes are refused.
19 changes: 18 additions & 1 deletion src/cli/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ import { pruneGitCache, releaseGitSnapshotLease } from "../source/cache.js";
import { listRegisteredFleets, registerFleet, resolveWorkspaceOwnershipScope, resolveWorkspaceScope, showRegisteredFleet } from "../model/fleet.js";
import { applyFleetNormalization, planFleetNormalization, recoverFleetNormalization, type FleetNormalizationSource } from "../lifecycle/fleet-normalize.js";
import { declareMutationPath } from "../mutation/declarations.js";
import { GovernedMutation, checkMutationProvider, mutationPolicyForWorkspace, recoverMutationRuntime, resumeMutation } from "../mutation/coordinator.js";
import { GovernedMutation, checkMutationProvider, mutationPolicyForWorkspace, recoverMutationRuntime, resumeMutation, previewMutationRecovery } from "../mutation/coordinator.js";
import { listMutationReceipts, readMutationReceipt, type MutationReceipt } from "../mutation/receipts.js";
import { isGovernedCommand, requiresCleanMutationPreflight } from "../mutation/commands.js";

Expand Down Expand Up @@ -1823,7 +1823,9 @@ for (const action of ["finalize", "recover"] as const) {
.description(`${action} one verified successful governed mutation idempotently`)
.argument("<operation-id>", "mutation operation id")
.option("--json", "print the updated receipt as JSON", false)
.option("--dry-run", "inspect zero-operation metadata recovery without writing", false)
.action(async (operationId, options) => {
if (options.dryRun) return printRecoveryPreview(await previewMutationRecovery(operationId, action), options.json);
const receipt = await resumeMutation(operationId, action);
if (options.json) return console.log(JSON.stringify(receipt, null, 2));
printMutationReceipt(receipt);
Expand All @@ -1835,7 +1837,9 @@ mutationCommand
.description("resume linked runtime apply journals, verify them, and finalize revisioning")
.argument("<operation-id>", "mutation operation id")
.option("--json", "print the updated receipt as JSON", false)
.option("--dry-run", "inspect zero-operation metadata recovery without writing", false)
.action(async (operationId, options) => {
if (options.dryRun) return printRecoveryPreview(await previewMutationRecovery(operationId), options.json);
const receipt = await recoverMutationRuntime(operationId);
if (options.json) return console.log(JSON.stringify(receipt, null, 2));
printMutationReceipt(receipt);
Expand Down Expand Up @@ -5497,3 +5501,16 @@ try {
console.error(error instanceof Error ? error.message : String(error));
process.exitCode = 1;
}

function printRecoveryPreview(preview: Awaited<ReturnType<typeof previewMutationRecovery>>, json: boolean): void {
if (json) return console.log(JSON.stringify(preview, null, 2));
console.log(`DRY RUN ${preview.operationId}: ${preview.status}; zero runtime operations`);
for (const journal of preview.journals) {
console.log(` ${journal.removesManifest ? "Remove" : "Write"} metadata: ${journal.manifestPath}`);
for (const path of journal.auditPaths) console.log(` Ensure audit intent: ${path}`);
console.log(` Resolve journal: ${journal.path}`);
}
for (const step of preview.steps) console.log(` ${step}`);
console.log(`Next: ${preview.nextCommand}`);
console.log("Advisory only; execution revalidates all guards. No revision provider was invoked.");
}
51 changes: 46 additions & 5 deletions src/install/apply.ts
Original file line number Diff line number Diff line change
Expand Up @@ -582,15 +582,33 @@ async function assertCommittedJournalState(
return actualManifest;
}

/** Observe a zero-operation metadata recovery without locks, providers, or durable writes. */
export async function previewMetadataJournal(journal: ApplyJournal, transport: TargetTransport = localTransport): Promise<{
manifestPath: string; auditPaths: string[]; removesManifest: boolean;
}> {
if (journal.operations.length || journal.completed.length || (!journal.metadataGuards && !journal.metadataAudit)) {
throw new Error("Read-only recovery preview requires a guarded metadata journal with zero runtime operations.");
}
const manifest = withManifestRevision({ ...journal.manifest, generatedAt: journal.createdAt });
if (journal.metadataGuards) await assertMetadataStateGuards(journal, manifest, journal.metadataGuards, transport, false, true);
if (journal.metadataAudit) await assertMetadataAuditGuards(journal, manifest, transport, false, true);
return {
manifestPath: installManifestPath(journal.targetRoot, journal.adapter, { installationType: journal.installationType, stateKey: journal.stateKey }),
auditPaths: journal.metadataAudit?.auditFiles.map((file) => metadataAuditPath(journal.metadataAudit!, file.path)) ?? [],
removesManifest: manifest.entries.length === 0 && !journal.metadataAudit,
};
}

/** Both initial commit and recovery accept only the exact reviewed before/after manifest states. */
async function assertMetadataAuditGuards(
journal: ApplyJournal,
after: InstallManifestV2,
transport: TargetTransport,
requireAfter = false,
readOnly = false,
): Promise<void> {
const audit = journal.metadataAudit!;
await assertOwnershipMetadataAuditPaths(journal, transport);
if (!readOnly) await assertOwnershipMetadataAuditPaths(journal, transport);
const sha = /^[a-f0-9]{64}$/;
if (transport.kind === "ssh" || (audit.kind !== "ownership-release" && audit.kind !== "ownership-handoff")
|| after.adapter !== journal.adapter || after.targetRoot !== journal.targetRoot
Expand All @@ -602,7 +620,7 @@ async function assertMetadataAuditGuards(
|| audit.auditFiles.length !== 1 || audit.runtime.length !== 1 || !audit.inventory.length) {
throw new Error("Invalid metadata-audit transaction; no state was committed.");
}
await assertMetadataStateGuards(journal, after, audit, transport, requireAfter);
await assertMetadataStateGuards(journal, after, audit, transport, requireAfter, readOnly);
for (const file of audit.auditFiles) {
const path = metadataAuditPath(audit, file.path);
await assertNoSymlinkPath(path);
Expand All @@ -623,6 +641,7 @@ async function assertMetadataStateGuards(
guards: MetadataStateGuards,
transport: TargetTransport,
requireAfter = false,
readOnly = false,
): Promise<void> {
const sha = /^[a-f0-9]{64}$/;
if (transport.kind === "ssh" || (journal.metadataAudit && journal.metadataGuards)
Expand All @@ -635,7 +654,7 @@ async function assertMetadataStateGuards(
|| !guards.inventory.length || !guards.runtime.length) {
throw new Error("Invalid guarded metadata transaction; no state was committed.");
}
assertOwnershipMetadataTransportSupported(transport, journal);
if (!readOnly) assertOwnershipMetadataTransportSupported(transport, journal);
if (transport.kind === "local") {
await assertNoSymlinkPath(journal.targetRoot);
await assertNoSymlinkPath(metadataDir(journal.targetRoot));
Expand All @@ -658,13 +677,35 @@ async function assertMetadataStateGuards(
}
for (const guard of guards.runtime) {
const path = metadataRuntimePath(journal.targetRoot, guard.path);
// Older metadata journals record the block hash but not its selector. Resolve it
// from the exact CAS-verified inventory, never from arbitrary live marker text.
const selectors = new Set(inventory.flatMap(({ manifest }) => {
if (manifest.version === 2) {
return manifest.entries
.filter((entry) => entry.path === guard.path && entry.mode === "managed-block" && entry.hash === guard.hash)
.map((entry) => managedInstructionSelector(entry.logicalSelector, entry.artifactType, entry.artifactName));
}
return manifest.entries
.filter((entry) => entry.path === guard.path && entry.mode === "managed-block" && entry.hash === guard.hash)
.map((entry) => managedInstructionSelector(undefined, entry.artifactType, entry.artifactName));
}));
if (!guard.managedBlock && selectors.size > 1) throw new Error(`Ambiguous metadata managed block at ${guard.path}.`);
const selector = guard.managedBlock?.selector ?? [...selectors][0];
const current = selector
? exactManagedInstructionBlockSnapshot(await transport.readFile(path), selector)
: undefined;
const runtimeHash = current ? current.hash : await transport.hashPath(path);
const expectedHash = guard.managedBlock?.hash ?? guard.hash;
// Legacy journals may pin a whole-file hash alongside an exact block snapshot.
// Preserve that file guard as well as comparing the live block with its recorded hash.
const legacyFileGuard = guard.managedBlock && guard.hash !== expectedHash;
if (!sha.test(guard.hash) || !sha.test(guard.snapshotDigest)
|| (await observeOwnershipRuntime(path, transport)).snapshotDigest !== guard.snapshotDigest
|| await transport.hashPath(path) !== guard.hash) {
|| runtimeHash !== expectedHash
|| (legacyFileGuard && await transport.hashPath(path) !== guard.hash)) {
throw new Error(`Metadata runtime CAS failed at ${guard.path}; runtime was preserved.`);
}
if (guard.managedBlock) {
const current = exactManagedInstructionBlockSnapshot(await transport.readFile(path), guard.managedBlock.selector);
if (canonicalJson(current) !== canonicalJson(guard.managedBlock)) {
throw new Error(`Managed instruction snapshot CAS failed at ${guard.path}.`);
}
Expand Down
2 changes: 1 addition & 1 deletion src/lifecycle/ownership-adopt-legacy.ts
Original file line number Diff line number Diff line change
Expand Up @@ -401,7 +401,7 @@ async function observe(request: AdoptLegacyOwnershipRequest, transport: TargetTr
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!,
runtime: selected.map((entry) => ({ path: entry.path, hash: entry.managedBlock?.hash ?? entry.runtimeHash!, snapshotDigest: entry.runtimeSnapshotDigest!,
...(entry.managedBlock ? { managedBlock: entry.managedBlock } : {}) })),
} } : {}),
};
Expand Down
48 changes: 48 additions & 0 deletions src/mutation/coordinator.ts
Original file line number Diff line number Diff line change
Expand Up @@ -397,6 +397,54 @@ async function transitionMutationRuntimeJournal(
}


export interface MutationRecoveryPreview {
dryRun: true;
operationId: string;
status: MutationReceipt["status"];
requestedAction: "finalize" | "recover" | "recover-runtime";
nextCommand: string;
runtimeOperations: 0;
journals: Array<{ path: string; manifestPath: string; auditPaths: string[]; removesManifest: boolean }>;
steps: string[];
}

/** Advisory observation only: execution must reacquire locks and revalidate all leases and guards. */
export async function previewMutationRecovery(
operationId: string,
requestedAction: MutationRecoveryPreview["requestedAction"] = "recover-runtime",
): Promise<MutationRecoveryPreview> {
const receipt = await readMutationReceipt(operationId);
assertRuntimeRecoveryReceipt(receipt);
const { readLinkedLocalApplyJournal } = await import("../install/transaction.js");
const { previewMetadataJournal } = await import("../install/apply.js");
const journals: MutationRecoveryPreview["journals"] = [];
for (const entry of receipt.runtimeJournals.filter((link) => link.status !== "resolved")) {
if (entry.transport === "ssh") throw new Error("Read-only recovery preview does not support SSH journals.");
let transport = localTransport;
if (entry.transport === "local-run-as") {
const pinned = entry.runAsIdentity!;
const current = resolveRunAsIdentity(pinned.user, pinned.root);
if (!sameRunAsIdentity(pinned, current)) throw new Error("Runtime recovery run-as identity changed.");
transport = createRunAsTransport(current);
}
const journal = await readLinkedLocalApplyJournal(entry.path, receipt.operationId, entry.journalDigest, entry.transportDescription, transport);
if (journal.mutation?.reason !== receipt.reason || journal.mutation.noCommit !== receipt.noCommit) {
throw new Error("Runtime apply journal mutation metadata does not match its durable receipt.");
}
journals.push({ path: entry.path, ...await previewMetadataJournal(journal, transport) });
}
return {
dryRun: true, operationId: receipt.operationId, status: receipt.status, requestedAction,
nextCommand: `agentwheel mutation recover-runtime ${receipt.operationId}`,
runtimeOperations: 0, journals,
steps: [
"Acquire mutation and runtime locks and revalidate receipt, journal, repository, inventory and runtime guards",
"Roll forward guarded metadata and audit intent without runtime operations",
"Resolve linked journals and verify revisioning under the recorded policy",
],
};
}

export async function resumeMutation(operationId: string, action: "finalize" | "recover"): Promise<MutationReceipt> {
let receipt = await readMutationReceipt(operationId);
if (["succeeded", "revisioning-skipped", "no-repository-delta"].includes(receipt.status)) return receipt;
Expand Down
Loading
Loading