@perkos/perkos-a2a 0.12.28 → 0.12.30

package/dist/repair.js

@@ -1,9 +1,24 @@
 import { spawn } from "node:child_process";
-import { createHash } from "node:crypto";
-import { mkdtemp, mkdir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
-import { homedir, tmpdir } from "node:os";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { chmod, mkdir, open, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { configFingerprint, runtimeAttemptPath, runtimeStatusPath, } from "./runtime-evidence.js";
+export class RepairFailure extends Error {
+    code;
+    phase;
+    retryable;
+    requiresProductFix;
+    constructor(code, phase, message, retryable, requiresProductFix) {
+        super(message);
+        this.code = code;
+        this.phase = phase;
+        this.retryable = retryable;
+        this.requiresProductFix = requiresProductFix;
+        this.name = "RepairFailure";
+    }
+}
 const PROTECTED_PATHS = [
     "agentName",
     "relay.apiKey",
@@ -58,6 +73,16 @@ function assertProtected(before, after) {
         }
     }
 }
+function redactProtectedValues(message, config) {
+    let redacted = message;
+    for (const dotted of PROTECTED_PATHS) {
+        const value = getAt(config, dotted);
+        if (typeof value === "string" && value.length >= 4) {
+            redacted = redacted.split(value).join("[REDACTED]");
+        }
+    }
+    return redacted;
+}
 async function pathExists(path) {
     try {
         await stat(path);
@@ -67,10 +92,83 @@ async function pathExists(path) {
         return false;
     }
 }
-async function atomicWriteJson(path, value) {
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code ?? "")
+        : undefined;
+}
+/**
+ * Atomically replace normal config files, but preserve the inode for Docker/
+ * Kubernetes bind-mounted files where rename(2) fails with EBUSY/EXDEV/EPERM.
+ * A caller-owned backup is always written before this function is used.
+ */
+export async function writeJsonConfig(path, value, renameFile = rename) {
+    const serialized = `${JSON.stringify(value, null, 2)}\n`;
     const temporary = `${path}.perkos-repair-${process.pid}.tmp`;
-    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
-    await rename(temporary, path);
+    await writeFile(temporary, serialized, { mode: 0o600 });
+    try {
+        await renameFile(temporary, path);
+        return "atomic";
+    }
+    catch (error) {
+        const code = errorCode(error);
+        if (code !== "EBUSY" && code !== "EXDEV" && code !== "EPERM")
+            throw error;
+        await rm(temporary, { force: true });
+        const handle = await open(path, "r+");
+        try {
+            await handle.truncate(0);
+            await handle.writeFile(serialized, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        return "inplace-ebusy-fallback";
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+export async function acquireRepairLock(stateDir) {
+    await mkdir(stateDir, { recursive: true, mode: 0o700 });
+    const lockPath = join(stateDir, "perkos-a2a-connect.lock");
+    const attempt = async () => open(lockPath, "wx", 0o600);
+    let handle;
+    try {
+        handle = await attempt();
+    }
+    catch (error) {
+        if (errorCode(error) !== "EEXIST")
+            throw error;
+        let stale = false;
+        try {
+            const lock = JSON.parse(await readFile(lockPath, "utf8"));
+            const pid = typeof lock.pid === "number" ? lock.pid : Number.NaN;
+            const createdAt = typeof lock.createdAt === "string" ? Date.parse(lock.createdAt) : Number.NaN;
+            if (Number.isFinite(pid)) {
+                try {
+                    process.kill(pid, 0);
+                }
+                catch (probeError) {
+                    stale = errorCode(probeError) === "ESRCH";
+                }
+            }
+            if (!Number.isFinite(pid) && Number.isFinite(createdAt) && Date.now() - createdAt > 10 * 60_000)
+                stale = true;
+        }
+        catch { /* malformed locks are not removed unless old enough */ }
+        if (!stale)
+            throw new Error("another perkos-a2a connect/repair is already in progress");
+        await rm(lockPath, { force: true });
+        handle = await attempt();
+    }
+    await handle.writeFile(`${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`, "utf8");
+    await handle.sync();
+    return async () => {
+        await handle.close();
+        await rm(lockPath, { force: true });
+    };
 }
 function parseJsonOutput(output) {
     const trimmed = output.trim();
@@ -121,8 +219,8 @@ async function processIdentityWithStart(run, status) {
     return startTime ? { ...identity, startTime } : identity;
 }
 function processChanged(before, after) {
-    if (before.pid !== undefined && after.pid !== undefined)
-        return before.pid !== after.pid;
+    if (before.pid !== undefined && after.pid !== undefined && before.pid !== after.pid)
+        return true;
     if (before.startTime && after.startTime)
         return before.startTime !== after.startTime;
     return false;
@@ -150,13 +248,17 @@ export function postRestartStateFromLogs(output, agentName, startedAt) {
     return verifyLogState(logTextSince(output, startedAt), agentName);
 }
 function verifyLogState(text, agentName) {
+    const heartbeatCount = text.match(/\[perkos-heartbeat\].*status=200/gu)?.length ?? 0;
     return {
+        configLoaded: false,
         connected: text.includes("Connected to relay hub"),
         registered: text.includes("Registered with relay hub"),
-        heartbeat200: /\[perkos-heartbeat\].*status=200/u.test(text),
+        heartbeat200: heartbeatCount > 0,
+        heartbeatCount,
         chatAuthed: text.includes(`[perkos-chat] authed as agent:${agentName}`),
         duplicatePlugin: text.toLowerCase().includes("duplicate plugin id detected"),
         duplicateRegistration: text.toLowerCase().includes("duplicate registration replaced"),
+        stableSeconds: 0,
     };
 }
 export const defaultCommandRunner = (command, args) => new Promise((resolveResult, reject) => {
@@ -191,6 +293,23 @@ function replacePluginEntry(document, config, enabled) {
     const previous = isObject(entries["perkos-a2a"]) ? entries["perkos-a2a"] : {};
     entries["perkos-a2a"] = { ...previous, enabled, config };
 }
+function enableExternalRestart(document) {
+    const previous = structuredClone(document.commands);
+    if (!isObject(document.commands))
+        document.commands = {};
+    document.commands.restart = true;
+    return previous;
+}
+function restoreExternalRestart(document, previous) {
+    if (previous === undefined)
+        delete document.commands;
+    else
+        document.commands = previous;
+}
+function restartObservedInLogs(output, startedAt) {
+    const text = logTextSince(output, startedAt).toLowerCase();
+    return text.includes("signal sigusr1 received") || text.includes("gateway restarting");
+}
 function assertIdentity(config, expectedName, expectedId) {
     if (config.agentName !== expectedName)
         throw new Error("configured agentName does not match this invitation");
@@ -208,6 +327,115 @@ function assertUnder(parent, child) {
         return;
     throw new Error("managed install escaped the OpenClaw npm root");
 }
+async function sha256File(path) {
+    return createHash("sha256").update(await readFile(path)).digest("hex");
+}
+async function readJsonOptional(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writePrivateJson(path, value) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const mode = await writeJsonConfig(path, value);
+    await chmod(path, 0o600);
+    return mode;
+}
+function repairStateRoot(stateDir) {
+    return join(stateDir, "perkos-a2a");
+}
+function receiptPath(stateDir, version, artifactSha256) {
+    return join(repairStateRoot(stateDir), "receipts", `${version}-${artifactSha256}.json`);
+}
+function journalPath(stateDir) {
+    return join(repairStateRoot(stateDir), "repair-journal.json");
+}
+async function inspectManagedInstall(input) {
+    const inspectResult = await mustRun(input.run, input.openclaw, ["plugins", "inspect", "perkos-a2a", "--json"], "plugin inspection");
+    const inspect = parseJsonOutput(inspectResult.stdout);
+    if (!isObject(inspect))
+        throw new Error("plugin inspection result is invalid");
+    const plugin = isObject(inspect.plugin) ? inspect.plugin : {};
+    const install = isObject(inspect.install) ? inspect.install : {};
+    const installPathValue = install.installPath ?? plugin.installPath;
+    if (plugin.id !== "perkos-a2a" || typeof installPathValue !== "string" || typeof plugin.rootDir !== "string") {
+        throw new Error("managed npm install was not recorded");
+    }
+    const npmRoot = await realpath(join(input.stateDir, "npm"));
+    const managedPath = await realpath(installPathValue);
+    const activeRoot = await realpath(plugin.rootDir);
+    assertUnder(npmRoot, managedPath);
+    if (activeRoot !== managedPath)
+        throw new Error("PerkOS is still loading from a non-managed plugin source");
+    const packagePath = join(managedPath, "package.json");
+    const manifestPath = join(managedPath, "openclaw.plugin.json");
+    const indexPath = join(managedPath, "dist", "index.js");
+    const repairCliPath = join(managedPath, "dist", "repair-cli.js");
+    const packageJson = JSON.parse(await readFile(packagePath, "utf8"));
+    const installedManifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    const bin = isObject(packageJson.bin) ? packageJson.bin : {};
+    if (packageJson.name !== "@perkos/perkos-a2a"
+        || packageJson.version !== input.targetVersion
+        || installedManifest.id !== "perkos-a2a"
+        || installedManifest.version !== input.targetVersion
+        || bin["perkos-a2a"] !== "dist/repair-cli.js"
+        || !await pathExists(indexPath)
+        || !await pathExists(repairCliPath)) {
+        throw new Error("installed plugin identity/version does not match the repair target");
+    }
+    return {
+        installRoot: managedPath,
+        artifactKind: typeof install.artifactKind === "string" ? install.artifactKind : undefined,
+        source: typeof install.source === "string" ? install.source : typeof plugin.source === "string" ? plugin.source : undefined,
+        spec: typeof install.spec === "string" ? install.spec : typeof plugin.spec === "string" ? plugin.spec : undefined,
+        packageJsonHash: await sha256File(packagePath),
+        manifestHash: await sha256File(manifestPath),
+        indexHash: await sha256File(indexPath),
+        repairCliHash: await sha256File(repairCliPath),
+    };
+}
+function receiptMatches(receipt, evidence, version, artifactSha256) {
+    return Boolean(receipt)
+        && receipt?.schemaVersion === 1
+        && receipt.targetVersion === version
+        && receipt.artifactSha256 === artifactSha256
+        && receipt.installRootRealpath === evidence.installRoot
+        && receipt.packageJsonHash === evidence.packageJsonHash
+        && receipt.manifestHash === evidence.manifestHash
+        && receipt.indexHash === evidence.indexHash
+        && receipt.repairCliHash === evidence.repairCliHash;
+}
+function mergeWriteMode(current, next) {
+    return current === "inplace-ebusy-fallback" || next === "inplace-ebusy-fallback"
+        ? "inplace-ebusy-fallback"
+        : "atomic";
+}
+function configLoadedLogMatches(text, input) {
+    return text.includes(`[perkos-a2a] config loaded version=${input.version} agentId=${input.agentId} attemptId=${input.attemptId} fingerprint=${input.fingerprint}`);
+}
+async function runtimeStatusMatches(path, input) {
+    const status = await readJsonOptional(path);
+    if (!status)
+        return false;
+    const loadedAt = Date.parse(status.loadedAt);
+    if (status.schemaVersion !== 1
+        || status.version !== input.version
+        || status.agentId !== input.agentId
+        || status.attemptId !== input.attemptId
+        || status.fingerprint !== input.fingerprint
+        || !Number.isFinite(loadedAt)
+        || loadedAt < input.startedAt - 2_000)
+        return false;
+    try {
+        return await realpath(status.pluginRoot) === input.installRoot;
+    }
+    catch {
+        return false;
+    }
+}
 async function wait(ms) {
     await new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
 }
@@ -224,136 +452,311 @@ export async function repairOpenClaw(options, run = defaultCommandRunner) {
         throw new Error("repair CLI manifest/schema is invalid");
     if (!await pathExists(artifactPath))
         throw new Error("verified plugin artifact is missing");
-    const artifactDigest = createHash("sha256").update(await readFile(artifactPath)).digest("hex");
+    const artifactDigest = await sha256File(artifactPath);
     if (artifactDigest !== options.artifactSha256.toLowerCase())
         throw new Error(`plugin artifact checksum mismatch: ${artifactDigest}`);
-    const migrationDir = await mkdtemp(join(tmpdir(), "perkos-a2a-repair-"));
-    const backupRoot = join(stateDir, "perkos-migration-backups");
-    await mkdir(backupRoot, { recursive: true, mode: 0o700 });
-    const backupPath = join(migrationDir, "openclaw.before.json");
-    const legacyExtension = join(stateDir, "extensions", "perkos-a2a");
-    const quarantinePath = join(backupRoot, `perkos-a2a-extension-${Date.now()}`);
-    const originalRaw = await readFile(configPath, "utf8");
-    let document;
-    try {
-        document = JSON.parse(originalRaw);
-    }
-    catch {
-        throw new Error("OpenClaw config must be strict JSON for safe automatic repair");
-    }
-    const existingConfig = openClawConfig(document);
-    const before = structuredClone(existingConfig ?? options.initialConfig);
-    if (!isObject(before))
-        throw new Error("existing PerkOS plugin config is missing");
-    await writeFile(backupPath, originalRaw, { mode: 0o600 });
-    const normalized = normalizeToSchema(before, manifest.configSchema);
-    if (!isObject(normalized.value))
-        throw new Error("normalized PerkOS config is invalid");
-    assertProtected(before, normalized.value);
-    assertIdentity(normalized.value, options.expectedAgentName, options.expectedAgentId);
-    let quarantined = false;
-    let committed = false;
+    const releaseRepairLock = await acquireRepairLock(stateDir);
     try {
-        replacePluginEntry(document, {}, false);
-        await atomicWriteJson(configPath, document);
-        if (await pathExists(legacyExtension)) {
-            const legacyManifest = JSON.parse(await readFile(join(legacyExtension, "openclaw.plugin.json"), "utf8"));
-            if (legacyManifest.id !== "perkos-a2a")
-                throw new Error("refusing to quarantine a non-PerkOS extension");
-            await rename(legacyExtension, quarantinePath);
-            quarantined = true;
+        const priorJournal = await readJsonOptional(journalPath(stateDir));
+        const canResume = priorJournal?.schemaVersion === 1
+            && priorJournal.phase !== "done"
+            && priorJournal.targetVersion === version
+            && priorJournal.artifactSha256 === artifactDigest
+            && priorJournal.expectedAgentName === options.expectedAgentName
+            && priorJournal.expectedAgentId === options.expectedAgentId;
+        const resumedFromPhase = canResume ? priorJournal.phase : undefined;
+        let journal = canResume ? priorJournal : {
+            schemaVersion: 1,
+            attemptId: randomUUID(),
+            hmacKeyHex: randomBytes(32).toString("hex"),
+            targetVersion: version,
+            artifactSha256: artifactDigest,
+            expectedAgentName: options.expectedAgentName,
+            expectedAgentId: options.expectedAgentId,
+            phase: "detect",
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+        };
+        const setPhase = async (phase) => {
+            journal = { ...journal, phase, updatedAt: new Date().toISOString() };
+            await writePrivateJson(journalPath(stateDir), journal);
+        };
+        await setPhase("detect");
+        const backupRoot = join(stateDir, "perkos-migration-backups");
+        await mkdir(backupRoot, { recursive: true, mode: 0o700 });
+        const reusableBackup = canResume && priorJournal.backupPath && await pathExists(priorJournal.backupPath)
+            ? priorJournal.backupPath
+            : undefined;
+        const backupPath = reusableBackup ?? join(backupRoot, `openclaw-${Date.now()}.before.json`);
+        const legacyExtension = join(stateDir, "extensions", "perkos-a2a");
+        const quarantinePath = join(backupRoot, `perkos-a2a-extension-${Date.now()}`);
+        const originalRaw = await readFile(configPath, "utf8");
+        const identitySourceRaw = reusableBackup ? await readFile(reusableBackup, "utf8") : originalRaw;
+        let document;
+        try {
+            document = JSON.parse(originalRaw);
+        }
+        catch {
+            throw new Error("OpenClaw config must be strict JSON for safe automatic repair");
         }
-        await mustRun(run, openclaw, ["plugins", "install", `npm-pack:${artifactPath}`, "--force"], "managed plugin install");
-        const inspectResult = await mustRun(run, openclaw, ["plugins", "inspect", "perkos-a2a", "--json"], "plugin inspection");
-        const inspect = parseJsonOutput(inspectResult.stdout);
-        if (!isObject(inspect))
-            throw new Error("plugin inspection result is invalid");
-        const plugin = isObject(inspect.plugin) ? inspect.plugin : {};
-        const install = isObject(inspect.install) ? inspect.install : {};
-        if (plugin.id !== "perkos-a2a" || install.artifactKind !== "npm-pack" || typeof install.installPath !== "string" || typeof plugin.rootDir !== "string") {
-            throw new Error("managed npm install was not recorded");
+        let identitySource;
+        try {
+            identitySource = JSON.parse(identitySourceRaw);
+        }
+        catch {
+            throw new Error("OpenClaw repair backup must be strict JSON");
+        }
+        const existingConfig = openClawConfig(identitySource);
+        const before = structuredClone(existingConfig ?? options.initialConfig);
+        if (!isObject(before))
+            throw new Error("existing PerkOS plugin config is missing");
+        if (!reusableBackup) {
+            await writeFile(backupPath, originalRaw, { mode: 0o600 });
+            await chmod(backupPath, 0o600);
         }
-        const npmRoot = await realpath(join(stateDir, "npm"));
-        const managedPath = await realpath(install.installPath);
-        const activeRoot = await realpath(plugin.rootDir);
-        assertUnder(npmRoot, managedPath);
-        if (activeRoot !== managedPath)
-            throw new Error("PerkOS is still loading from a non-managed plugin source");
-        const installedManifest = JSON.parse(await readFile(join(managedPath, "openclaw.plugin.json"), "utf8"));
-        if (installedManifest.id !== "perkos-a2a" || installedManifest.version !== version)
-            throw new Error("installed plugin version does not match repair CLI");
-        const currentRaw = await readFile(configPath, "utf8");
-        const currentDocument = JSON.parse(currentRaw);
-        replacePluginEntry(currentDocument, normalized.value, true);
-        await atomicWriteJson(configPath, currentDocument);
-        await mustRun(run, openclaw, ["config", "validate"], "config validation");
-        const doctor = await mustRun(run, openclaw, ["plugins", "doctor"], "plugin doctor");
-        const doctorText = `${doctor.stdout}\n${doctor.stderr}`.toLowerCase();
-        if (doctorText.includes("duplicate plugin id detected"))
-            throw new Error("duplicate plugin source remains after migration");
-        committed = true;
-        const emptyPostRestart = verifyLogState("", options.expectedAgentName);
-        const restartResult = { requested: false, verified: false };
-        let postRestart = emptyPostRestart;
-        if (!options.skipRestart) {
-            const beforeStatusResult = await mustRun(run, openclaw, ["gateway", "status", "--json"], "pre-restart gateway status");
-            const beforeStatus = await processIdentityWithStart(run, parseJsonOutput(beforeStatusResult.stdout));
-            restartResult.beforePid = beforeStatus.pid;
-            restartResult.beforeStartTime = beforeStatus.startTime;
-            const restartStartedAt = Date.now();
-            await mustRun(run, openclaw, ["gateway", "restart", "--safe", "--skip-deferral", "--json"], "gateway restart");
-            restartResult.requested = true;
-            const deadline = Date.now() + (options.timeoutMs ?? 90_000);
-            let recentLogs = "";
-            while (Date.now() < deadline) {
-                await wait(options.pollIntervalMs ?? 2_000);
-                const status = await run(openclaw, ["gateway", "status", "--json", "--require-rpc"]);
-                if (status.code !== 0)
-                    continue;
-                const afterStatus = await processIdentityWithStart(run, parseJsonOutput(status.stdout));
-                restartResult.afterPid = afterStatus.pid;
-                restartResult.afterStartTime = afterStatus.startTime;
-                restartResult.verified = processChanged(beforeStatus, afterStatus);
-                const logs = await run(openclaw, ["logs", "--json", "--limit", "1000", "--max-bytes", "2000000"]);
-                if (logs.code === 0)
-                    recentLogs = logs.stdout;
-                postRestart = postRestartStateFromLogs(recentLogs, options.expectedAgentName, restartStartedAt);
-                if (restartResult.verified && postRestart.connected && postRestart.registered && postRestart.heartbeat200 && postRestart.chatAuthed && !postRestart.duplicatePlugin && !postRestart.duplicateRegistration)
-                    break;
+        journal = { ...journal, backupPath };
+        await setPhase("snapshot");
+        const normalized = normalizeToSchema(before, manifest.configSchema);
+        if (!isObject(normalized.value))
+            throw new Error("normalized PerkOS config is invalid");
+        assertProtected(before, normalized.value);
+        assertIdentity(normalized.value, options.expectedAgentName, options.expectedAgentId);
+        let quarantined = false;
+        let installCommitted = journal.installCommitted === true;
+        let configCommitted = false;
+        let configWriteMode = "atomic";
+        let receiptUsed = false;
+        let receiptCreated = false;
+        let installEvidence;
+        try {
+            replacePluginEntry(document, {}, false);
+            configWriteMode = mergeWriteMode(configWriteMode, await writeJsonConfig(configPath, document));
+            if (await pathExists(legacyExtension)) {
+                const legacyManifest = JSON.parse(await readFile(join(legacyExtension, "openclaw.plugin.json"), "utf8"));
+                if (legacyManifest.id !== "perkos-a2a")
+                    throw new Error("refusing to quarantine a non-PerkOS extension");
+                await rename(legacyExtension, quarantinePath);
+                quarantined = true;
+            }
+            await setPhase("install");
+            const receiptFile = receiptPath(stateDir, version, artifactDigest);
+            const receipt = await readJsonOptional(receiptFile);
+            if (receipt) {
+                try {
+                    const candidate = await inspectManagedInstall({ run, openclaw, stateDir, targetVersion: version });
+                    if (receiptMatches(receipt, candidate, version, artifactDigest)) {
+                        installEvidence = candidate;
+                        receiptUsed = true;
+                    }
+                }
+                catch { /* reinstall and certify from the verified artifact */ }
             }
-            if (!restartResult.verified)
-                throw new Error("gateway restart was not verified by a new PID/start time");
-            if (!postRestart.connected || !postRestart.registered || !postRestart.heartbeat200 || !postRestart.chatAuthed || postRestart.duplicatePlugin || postRestart.duplicateRegistration) {
-                throw new Error(`post-restart verification failed: ${JSON.stringify(postRestart)}`);
+            if (!installEvidence) {
+                const installResult = await run(openclaw, ["plugins", "install", `npm-pack:${artifactPath}`, "--force"]);
+                const installError = `${installResult.stderr}\n${installResult.stdout}`;
+                if (installResult.code !== 0 && !/EBUSY|resource busy|rename/iu.test(installError)) {
+                    throw new Error(`managed plugin install failed: ${installError.trim().slice(0, 500)}`);
+                }
+                installCommitted = true;
+                journal = { ...journal, installCommitted: true };
+                await setPhase("install");
+                installEvidence = await inspectManagedInstall({ run, openclaw, stateDir, targetVersion: version });
+                const newReceipt = {
+                    schemaVersion: 1,
+                    targetVersion: version,
+                    artifactSha256: artifactDigest,
+                    packageJsonHash: installEvidence.packageJsonHash,
+                    manifestHash: installEvidence.manifestHash,
+                    indexHash: installEvidence.indexHash,
+                    repairCliHash: installEvidence.repairCliHash,
+                    installRootRealpath: installEvidence.installRoot,
+                    createdAt: new Date().toISOString(),
+                };
+                await writePrivateJson(receiptFile, newReceipt);
+                receiptCreated = true;
             }
+            installCommitted = true;
+            journal = { ...journal, installCommitted: true };
+            await setPhase("migrate-config");
+            const currentRaw = await readFile(configPath, "utf8");
+            const currentDocument = JSON.parse(currentRaw);
+            replacePluginEntry(currentDocument, normalized.value, true);
+            configWriteMode = mergeWriteMode(configWriteMode, await writeJsonConfig(configPath, currentDocument));
+            configCommitted = true;
+            await setPhase("validate-config");
+            await mustRun(run, openclaw, ["config", "validate"], "config validation");
+            const doctor = await mustRun(run, openclaw, ["plugins", "doctor"], "plugin doctor");
+            const doctorText = `${doctor.stdout}\n${doctor.stderr}`.toLowerCase();
+            if (doctorText.includes("duplicate plugin id detected"))
+                throw new Error("duplicate plugin source remains after migration");
+            const activeEvidence = await inspectManagedInstall({ run, openclaw, stateDir, targetVersion: version });
+            if (activeEvidence.installRoot !== installEvidence.installRoot)
+                throw new Error("managed plugin root changed during config migration");
+            const emptyPostRestart = verifyLogState("", options.expectedAgentName);
+            const restartResult = { requested: false, verified: false };
+            let postRestart = emptyPostRestart;
+            const expectedFingerprint = configFingerprint(normalized.value, journal.hmacKeyHex);
+            if (!options.skipRestart) {
+                const runtimeAttempt = {
+                    schemaVersion: 1,
+                    attemptId: journal.attemptId,
+                    targetVersion: version,
+                    expectedAgentId: options.expectedAgentId,
+                    hmacKeyHex: journal.hmacKeyHex,
+                    createdAt: new Date().toISOString(),
+                };
+                await writePrivateJson(runtimeAttemptPath(stateDir), runtimeAttempt);
+                await setPhase("restart");
+                const beforeStatusResult = await mustRun(run, openclaw, ["gateway", "status", "--json"], "pre-restart gateway status");
+                const beforeStatus = await processIdentityWithStart(run, parseJsonOutput(beforeStatusResult.stdout));
+                restartResult.beforePid = beforeStatus.pid;
+                restartResult.beforeStartTime = beforeStatus.startTime;
+                const restartStartedAt = Date.now();
+                let restoreRestartPermission;
+                try {
+                    if (beforeStatus.pid === 1) {
+                        const permissionRaw = await readFile(configPath, "utf8");
+                        const permissionDocument = JSON.parse(permissionRaw);
+                        const previousPermission = enableExternalRestart(permissionDocument);
+                        configWriteMode = mergeWriteMode(configWriteMode, await writeJsonConfig(configPath, permissionDocument));
+                        restoreRestartPermission = async () => {
+                            const latest = JSON.parse(await readFile(configPath, "utf8"));
+                            restoreExternalRestart(latest, previousPermission);
+                            configWriteMode = mergeWriteMode(configWriteMode, await writeJsonConfig(configPath, latest));
+                        };
+                        await wait(options.pollIntervalMs ?? 2_000);
+                        await mustRun(run, "kill", ["-USR1", "1"], "PID 1 in-process gateway restart");
+                        restartResult.method = "in-process-sigusr1";
+                    }
+                    else {
+                        await mustRun(run, openclaw, ["gateway", "restart", "--safe", "--skip-deferral", "--json"], "gateway restart");
+                        restartResult.method = "service";
+                    }
+                    restartResult.requested = true;
+                    await setPhase("runtime-checks");
+                    const stabilityWindowMs = options.stabilityWindowMs ?? 180_000;
+                    const requiredHeartbeatCount = options.requiredHeartbeatCount ?? 3;
+                    const deadline = Date.now() + (options.timeoutMs ?? 300_000);
+                    let healthySince;
+                    let recentLogs = "";
+                    while (Date.now() < deadline) {
+                        await wait(options.pollIntervalMs ?? 2_000);
+                        const status = await run(openclaw, ["gateway", "status", "--json", "--require-rpc"]);
+                        if (status.code !== 0) {
+                            healthySince = undefined;
+                            continue;
+                        }
+                        const afterStatus = await processIdentityWithStart(run, parseJsonOutput(status.stdout));
+                        restartResult.afterPid = afterStatus.pid;
+                        restartResult.afterStartTime = afterStatus.startTime;
+                        const logs = await run(openclaw, ["logs", "--json", "--limit", "2000", "--max-bytes", "4000000"]);
+                        if (logs.code === 0)
+                            recentLogs = logs.stdout;
+                        const freshText = logTextSince(recentLogs, restartStartedAt);
+                        postRestart = verifyLogState(freshText, options.expectedAgentName);
+                        postRestart.configLoaded = configLoadedLogMatches(freshText, {
+                            version,
+                            agentId: options.expectedAgentId,
+                            attemptId: journal.attemptId,
+                            fingerprint: expectedFingerprint,
+                        }) || await runtimeStatusMatches(runtimeStatusPath(stateDir), {
+                            version,
+                            agentId: options.expectedAgentId,
+                            attemptId: journal.attemptId,
+                            fingerprint: expectedFingerprint,
+                            installRoot: installEvidence.installRoot,
+                            startedAt: restartStartedAt,
+                        });
+                        const processIdentityChanged = processChanged(beforeStatus, afterStatus);
+                        const freshRestartLogs = restartObservedInLogs(recentLogs, restartStartedAt);
+                        restartResult.verified = processIdentityChanged || (restartResult.method === "in-process-sigusr1" && freshRestartLogs);
+                        restartResult.verifiedBy = processIdentityChanged
+                            ? "process-identity"
+                            : restartResult.verified
+                                ? "fresh-restart-logs"
+                                : undefined;
+                        const healthy = restartResult.verified
+                            && postRestart.configLoaded
+                            && postRestart.connected
+                            && postRestart.registered
+                            && postRestart.heartbeatCount >= requiredHeartbeatCount
+                            && postRestart.chatAuthed
+                            && !postRestart.duplicatePlugin
+                            && !postRestart.duplicateRegistration;
+                        if (!healthy) {
+                            healthySince = undefined;
+                            continue;
+                        }
+                        healthySince ??= Date.now();
+                        postRestart.stableSeconds = Math.floor((Date.now() - healthySince) / 1_000);
+                        if (Date.now() - healthySince >= stabilityWindowMs)
+                            break;
+                    }
+                    if (!restartResult.verified)
+                        throw new Error("gateway restart was not verified by process identity or fresh in-process restart logs");
+                    if (!postRestart.configLoaded
+                        || !postRestart.connected
+                        || !postRestart.registered
+                        || postRestart.heartbeatCount < requiredHeartbeatCount
+                        || !postRestart.chatAuthed
+                        || postRestart.duplicatePlugin
+                        || postRestart.duplicateRegistration)
+                        throw new Error(`post-restart verification failed: ${JSON.stringify(postRestart)}`);
+                    if (healthySince === undefined || Date.now() - healthySince < stabilityWindowMs) {
+                        throw new Error(`post-restart transport did not remain healthy for ${stabilityWindowMs}ms`);
+                    }
+                }
+                finally {
+                    await restoreRestartPermission?.();
+                }
+            }
+            await setPhase("done");
+            return {
+                schemaVersion: 1,
+                ok: true,
+                phase: "done",
+                version,
+                mode: existingConfig ? "repaired" : "installed",
+                trustLevel: "trusted",
+                strictMode: true,
+                resumedFromPhase,
+                artifactVerified: true,
+                source: "managed-npm",
+                installEvidence: {
+                    artifactKind: installEvidence.artifactKind,
+                    source: installEvidence.source,
+                    spec: installEvidence.spec,
+                    receiptUsed,
+                    receiptCreated,
+                    installRoot: installEvidence.installRoot,
+                },
+                configWriteMode,
+                normalized: true,
+                removedUnsupportedPaths: normalized.removed,
+                quarantinedLegacyExtension: quarantined,
+                configValid: true,
+                pluginDoctorClean: true,
+                restart: restartResult,
+                postRestart,
+            };
         }
-        return {
-            ok: true,
-            version,
-            mode: existingConfig ? "repaired" : "installed",
-            artifactVerified: true,
-            source: "managed-npm",
-            normalized: true,
-            removedUnsupportedPaths: normalized.removed,
-            quarantinedLegacyExtension: quarantined,
-            configValid: true,
-            pluginDoctorClean: true,
-            restart: restartResult,
-            postRestart,
-        };
-    }
-    catch (error) {
-        if (!committed) {
-            await writeFile(configPath, originalRaw, { mode: 0o600 });
-            if (quarantined && await pathExists(quarantinePath) && !await pathExists(legacyExtension)) {
-                await mkdir(dirname(legacyExtension), { recursive: true });
-                await rename(quarantinePath, legacyExtension);
+        catch (error) {
+            if (!installCommitted) {
+                await writeFile(configPath, originalRaw, { mode: 0o600 });
+                if (quarantined && await pathExists(quarantinePath) && !await pathExists(legacyExtension)) {
+                    await mkdir(dirname(legacyExtension), { recursive: true });
+                    await rename(quarantinePath, legacyExtension);
+                }
             }
+            const rawMessage = error instanceof Error ? error.message : String(error);
+            const message = redactProtectedValues(rawMessage, before);
+            if (error instanceof RepairFailure)
+                throw error;
+            throw new RepairFailure(installCommitted && !configCommitted ? "REPAIR_RESUME_REQUIRED" : "REPAIR_FAILED", journal.phase, message, installCommitted, false);
         }
-        throw error;
     }
     finally {
-        await rm(migrationDir, { recursive: true, force: true });
+        await releaseRepairLock();
     }
 }
 //# sourceMappingURL=repair.js.map