@knowzai/cli 0.3.0 → 0.5.0

package/dist/lib/platform-backup.js

@@ -1,10 +1,12 @@
-import { chmodSync, closeSync, copyFileSync, cpSync, createReadStream, createWriteStream, existsSync, fstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { assertLocalEngineContext, readSavedLocalEngine } from './local-engine-context.js';
+import { acquireRuntimeLock } from './runtime-lock.js';
+import { closeSync, copyFileSync, cpSync, createReadStream, createWriteStream, existsSync, fstatSync, openSync, readFileSync, readSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { createCipheriv, createDecipheriv, createHash, randomBytes, scryptSync } from 'node:crypto';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { pipeline } from 'node:stream/promises';
-import { ExitCode, KnowzError } from '@knowzai/core';
+import { ExitCode, KnowzError, createPrivateTempDirectory, ensurePrivateDirectory, protectPrivatePath, publishPrivateFile, withPrivateOutput } from '@knowzai/core';
 import { redactPlatformSecrets, parseEnv, writePrivateFile, } from './platform-runtime.js';
 export const BACKUP_SECURITY_WARNING = 'SECURITY WARNING: this backup contains the kzin_ installation credential, all tenant PII, legacy plaintext API-key columns, and every stack secret (.env, JWT, MinIO root password, and SuperAdmin passphrase). Treat it like a production credentials file; use --encrypt and store it securely.';
 export const BACKUP_SCRYPT = { N: 1 << 15, r: 8, p: 1, maxmem: 96 * 1024 * 1024 };
@@ -32,9 +34,12 @@ function composeInvocation(paths, projectName, engine, action) {
         command: front.command,
         args: [
             ...front.baseArgs,
-            '--project-name', projectName,
-            '--file', paths.composeFile,
-            '--env-file', paths.envFile,
+            '--project-name',
+            projectName,
+            '--file',
+            paths.composeFile,
+            '--env-file',
+            paths.envFile,
             ...action,
         ],
         options: {
@@ -69,42 +74,82 @@ export function planBackup(paths, projectName, env, opts) {
     const steps = [];
     if (!opts.postgresRunning) {
         steps.push({
-            kind: 'compose', description: 'start postgres',
-            invocation: composeInvocation(paths, projectName, engine, ['up', '--detach', '--wait', 'postgres']),
+            kind: 'compose',
+            description: 'start postgres',
+            invocation: composeInvocation(paths, projectName, engine, [
+                'up',
+                '--detach',
+                '--wait',
+                'postgres',
+            ]),
         });
     }
     for (const database of ['KnowzMaster', 'KnowzKnowledge']) {
         steps.push({
-            kind: 'compose', description: `dump ${database}`,
+            kind: 'compose',
+            description: `dump ${database}`,
             invocation: composeInvocation(paths, projectName, engine, [
-                'exec', '-T', 'postgres', 'pg_dump', '-U', pgUser, '-Fc', '-f', `/tmp/${database}.dump`, database,
+                'exec',
+                '-T',
+                'postgres',
+                'pg_dump',
+                '-U',
+                pgUser,
+                '-Fc',
+                '-f',
+                `/tmp/${database}.dump`,
+                database,
             ]),
         });
         steps.push({
-            kind: 'compose', description: `copy ${database} dump`,
+            kind: 'compose',
+            description: `copy ${database} dump`,
             invocation: composeInvocation(paths, projectName, engine, [
-                'cp', `postgres:/tmp/${database}.dump`, join(staging, 'pg', `${database}.dump`),
+                'cp',
+                `postgres:/tmp/${database}.dump`,
+                join(staging, 'pg', `${database}.dump`),
             ]),
         });
         steps.push({
-            kind: 'compose', description: `remove staged ${database} dump`,
-            invocation: composeInvocation(paths, projectName, engine, ['exec', '-T', 'postgres', 'rm', '-f', `/tmp/${database}.dump`]),
+            kind: 'compose',
+            description: `remove staged ${database} dump`,
+            invocation: composeInvocation(paths, projectName, engine, [
+                'exec',
+                '-T',
+                'postgres',
+                'rm',
+                '-f',
+                `/tmp/${database}.dump`,
+            ]),
         });
     }
     for (const volume of ['miniodata', 'objectsdata', 'identity']) {
         const physical = `${projectName}_knowz-portable-${volume}`;
         steps.push({
-            kind: 'engine-run', description: `snapshot ${volume}`,
+            kind: 'engine-run',
+            description: `snapshot ${volume}`,
             invocation: engineInvocation(engine, paths.runtimeDir, [
-                'run', '--rm', '-v', `${physical}:/src:ro`, '-v', `${staging}:/out`,
-                'alpine', 'tar', '-czf', `/out/volumes/${volume}.tar.gz`, '-C', '/src', '.',
+                'run',
+                '--rm',
+                '-v',
+                `${physical}:/src:ro`,
+                '-v',
+                `${staging}:/out`,
+                'alpine',
+                'tar',
+                '-czf',
+                `/out/volumes/${volume}.tar.gz`,
+                '-C',
+                '/src',
+                '.',
             ]),
         });
     }
     steps.push({ kind: 'fs', description: 'write manifest' });
     if (!opts.postgresRunning) {
         steps.push({
-            kind: 'compose', description: 'stop postgres',
+            kind: 'compose',
+            description: 'stop postgres',
             invocation: composeInvocation(paths, projectName, engine, ['stop', 'postgres']),
         });
     }
@@ -118,41 +163,105 @@ export function planRestore(paths, projectName, manifest, opts) {
         steps.push({ kind: 'fs', description: 'restore runtime configuration and portable assets' });
     for (const volume of manifest.volumes) {
         const physical = `${projectName}_knowz-portable-${volume}`;
-        steps.push({ kind: 'engine-run', description: `wipe ${physical}`, invocation: engineInvocation(engine, paths.runtimeDir, ['volume', 'rm', '--force', physical]) });
-        steps.push({ kind: 'engine-run', description: `create ${physical}`, invocation: engineInvocation(engine, paths.runtimeDir, ['volume', 'create', physical]) });
+        steps.push({
+            kind: 'engine-run',
+            description: `wipe ${physical}`,
+            invocation: engineInvocation(engine, paths.runtimeDir, ['volume', 'rm', '--force', physical]),
+        });
+        steps.push({
+            kind: 'engine-run',
+            description: `create ${physical}`,
+            invocation: engineInvocation(engine, paths.runtimeDir, ['volume', 'create', physical]),
+        });
         if (volume !== 'identity' || opts.mode === 'replace-installation') {
             steps.push({
-                kind: 'engine-run', description: `extract volumes/${volume}.tar.gz`,
+                kind: 'engine-run',
+                description: `extract volumes/${volume}.tar.gz`,
                 invocation: engineInvocation(engine, paths.runtimeDir, [
-                    'run', '--rm', '-v', `${physical}:/dst`, '-v', `${staging}:/in:ro`,
-                    'alpine', 'tar', '-xzf', `/in/volumes/${volume}.tar.gz`, '-C', '/dst',
+                    'run',
+                    '--rm',
+                    '-v',
+                    `${physical}:/dst`,
+                    '-v',
+                    `${staging}:/in:ro`,
+                    'alpine',
+                    'tar',
+                    '-xzf',
+                    `/in/volumes/${volume}.tar.gz`,
+                    '-C',
+                    '/dst',
                 ]),
             });
         }
     }
     const pgVolume = `${projectName}_knowz-portable-pgdata`;
-    steps.push({ kind: 'engine-run', description: `wipe ${pgVolume}`, invocation: engineInvocation(engine, paths.runtimeDir, ['volume', 'rm', '--force', pgVolume]) });
-    steps.push({ kind: 'engine-run', description: `create ${pgVolume}`, invocation: engineInvocation(engine, paths.runtimeDir, ['volume', 'create', pgVolume]) });
-    steps.push({ kind: 'compose', description: 'start postgres', invocation: composeInvocation(paths, projectName, engine, ['up', '--detach', '--wait', 'postgres']) });
+    steps.push({
+        kind: 'engine-run',
+        description: `wipe ${pgVolume}`,
+        invocation: engineInvocation(engine, paths.runtimeDir, ['volume', 'rm', '--force', pgVolume]),
+    });
+    steps.push({
+        kind: 'engine-run',
+        description: `create ${pgVolume}`,
+        invocation: engineInvocation(engine, paths.runtimeDir, ['volume', 'create', pgVolume]),
+    });
+    steps.push({
+        kind: 'compose',
+        description: 'start postgres',
+        invocation: composeInvocation(paths, projectName, engine, [
+            'up',
+            '--detach',
+            '--wait',
+            'postgres',
+        ]),
+    });
     const pgUser = opts.pgUser || 'knowz';
     for (const database of manifest.pgDatabases) {
         steps.push({
-            kind: 'compose', description: `copy ${database} dump`,
-            invocation: composeInvocation(paths, projectName, engine, ['cp', join(staging, 'pg', `${database}.dump`), `postgres:/tmp/${database}.dump`]),
+            kind: 'compose',
+            description: `copy ${database} dump`,
+            invocation: composeInvocation(paths, projectName, engine, [
+                'cp',
+                join(staging, 'pg', `${database}.dump`),
+                `postgres:/tmp/${database}.dump`,
+            ]),
         });
         steps.push({
-            kind: 'compose', description: `restore ${database}`,
+            kind: 'compose',
+            description: `restore ${database}`,
             invocation: composeInvocation(paths, projectName, engine, [
-                'exec', '-T', 'postgres', 'pg_restore', '--clean', '--if-exists', '--no-owner',
-                '-U', pgUser, '-d', database, `/tmp/${database}.dump`,
+                'exec',
+                '-T',
+                'postgres',
+                'pg_restore',
+                '--clean',
+                '--if-exists',
+                '--no-owner',
+                '-U',
+                pgUser,
+                '-d',
+                database,
+                `/tmp/${database}.dump`,
             ]),
         });
         steps.push({
-            kind: 'compose', description: `remove staged ${database} dump`,
-            invocation: composeInvocation(paths, projectName, engine, ['exec', '-T', 'postgres', 'rm', '-f', `/tmp/${database}.dump`]),
+            kind: 'compose',
+            description: `remove staged ${database} dump`,
+            invocation: composeInvocation(paths, projectName, engine, [
+                'exec',
+                '-T',
+                'postgres',
+                'rm',
+                '-f',
+                `/tmp/${database}.dump`,
+            ]),
         });
     }
-    steps.push({ kind: 'compose', description: 'stop postgres', invocation: composeInvocation(paths, projectName, engine, ['stop', 'postgres']) });
+    steps.push({
+        kind: 'compose',
+        description: 'stop postgres',
+        invocation: composeInvocation(paths, projectName, engine, ['stop', 'postgres']),
+    });
     return steps;
 }
 function fileSha256(path) {
@@ -206,13 +315,16 @@ export function parseAndValidateManifest(json) {
     if (!isRecord(value) || value.schemaVersion !== 1) {
         throw new KnowzError('Unsupported backup manifest schemaVersion; expected 1.', ExitCode.Usage);
     }
-    if (value.includesIdentity !== true || !Array.isArray(value.pgDatabases) || !Array.isArray(value.volumes) || !isRecord(value.checksums)) {
+    if (value.includesIdentity !== true ||
+        !Array.isArray(value.pgDatabases) ||
+        !Array.isArray(value.volumes) ||
+        !isRecord(value.checksums)) {
         throw new KnowzError('Backup manifest is incomplete or invalid.', ExitCode.Usage);
     }
     const databases = value.pgDatabases.map(String);
     const volumes = value.volumes.map(String);
-    if (!['KnowzMaster', 'KnowzKnowledge'].every(database => databases.includes(database)) ||
-        !['miniodata', 'objectsdata', 'identity'].every(volume => volumes.includes(volume))) {
+    if (!['KnowzMaster', 'KnowzKnowledge'].every((database) => databases.includes(database)) ||
+        !['miniodata', 'objectsdata', 'identity'].every((volume) => volumes.includes(volume))) {
         throw new KnowzError('Backup manifest does not contain every required portable data store.', ExitCode.Usage);
     }
     const checksums = Object.fromEntries(Object.entries(value.checksums).filter((entry) => typeof entry[1] === 'string'));
@@ -233,28 +345,18 @@ export function parseAndValidateManifest(json) {
 export function validateBackupChecksums(stagingDir, manifest) {
     for (const artifact of BACKUP_ARTIFACTS) {
         const expected = manifest.checksums[artifact];
-        if (!expected || !existsSync(join(stagingDir, artifact)) || fileSha256(join(stagingDir, artifact)) !== expected) {
+        if (!expected ||
+            !existsSync(join(stagingDir, artifact)) ||
+            fileSha256(join(stagingDir, artifact)) !== expected) {
             throw new KnowzError(`Backup checksum validation failed for ${artifact}.`, ExitCode.Usage);
         }
     }
 }
 export function createPrivateStaging(parent) {
-    const staging = mkdtempSync(join(parent, '.backup-'));
-    chmodSync(staging, 0o700);
-    return staging;
+    return createPrivateTempDirectory(parent, '.backup-');
 }
 export function finalizePrivateArchive(source, destination) {
-    chmodSync(source, 0o600);
-    try {
-        renameSync(source, destination);
-    }
-    catch (error) {
-        if (error.code !== 'EXDEV')
-            throw error;
-        copyFileSync(source, destination);
-        rmSync(source, { force: true });
-    }
-    chmodSync(destination, 0o600);
+    publishPrivateFile(source, destination);
 }
 function encryptionHeader(path) {
     const fd = openSync(path, 'r');
@@ -272,13 +374,22 @@ function encryptionHeader(path) {
         catch {
             throw new KnowzError('Encrypted backup header is invalid.', ExitCode.Usage);
         }
-        if (!isRecord(parsed) || parsed.v !== 1 || parsed.alg !== 'aes-256-gcm' || parsed.kdf !== 'scrypt' ||
-            typeof parsed.salt !== 'string' || typeof parsed.nonce !== 'string') {
+        if (!isRecord(parsed) ||
+            parsed.v !== 1 ||
+            parsed.alg !== 'aes-256-gcm' ||
+            parsed.kdf !== 'scrypt' ||
+            typeof parsed.salt !== 'string' ||
+            typeof parsed.nonce !== 'string') {
             throw new KnowzError('Encrypted backup header is unsupported.', ExitCode.Usage);
         }
         const tag = Buffer.alloc(16);
         readSync(fd, tag, 0, 16, size - 16);
-        return { header: parsed, ciphertextOffset: newline + 1, size, tag };
+        return {
+            header: parsed,
+            ciphertextOffset: newline + 1,
+            size,
+            tag,
+        };
     }
     finally {
         closeSync(fd);
@@ -289,19 +400,23 @@ export async function encryptStream(input, output, passphrase) {
     const nonce = randomBytes(12);
     const key = scryptSync(passphrase, salt, 32, BACKUP_SCRYPT);
     const header = {
-        v: 1, alg: 'aes-256-gcm', kdf: 'scrypt', salt: salt.toString('base64'), nonce: nonce.toString('base64'),
+        v: 1,
+        alg: 'aes-256-gcm',
+        kdf: 'scrypt',
+        salt: salt.toString('base64'),
+        nonce: nonce.toString('base64'),
     };
-    writeFileSync(output, `${JSON.stringify(header)}\n`, { mode: 0o600 });
-    const cipher = createCipheriv('aes-256-gcm', key, nonce);
-    try {
-        await pipeline(createReadStream(input), cipher, createWriteStream(output, { flags: 'a', mode: 0o600 }));
-        writeFileSync(output, cipher.getAuthTag(), { flag: 'a', mode: 0o600 });
-        chmodSync(output, 0o600);
-    }
-    catch (cause) {
-        rmSync(output, { force: true });
-        throw new KnowzError('Could not encrypt the backup archive.', ExitCode.Generic, { cause });
-    }
+    await withPrivateOutput(output, async (temporary) => {
+        writeFileSync(temporary, `${JSON.stringify(header)}\n`);
+        const cipher = createCipheriv('aes-256-gcm', key, nonce);
+        try {
+            await pipeline(createReadStream(input), cipher, createWriteStream(temporary, { flags: 'a' }));
+            writeFileSync(temporary, cipher.getAuthTag(), { flag: 'a' });
+        }
+        catch (cause) {
+            throw new KnowzError('Could not encrypt the backup archive.', ExitCode.Generic, { cause });
+        }
+    });
 }
 export async function decryptStream(input, output, passphrase) {
     const envelope = encryptionHeader(input);
@@ -310,14 +425,14 @@ export async function decryptStream(input, output, passphrase) {
     const key = scryptSync(passphrase, salt, 32, BACKUP_SCRYPT);
     const decipher = createDecipheriv('aes-256-gcm', key, nonce);
     decipher.setAuthTag(envelope.tag);
-    try {
-        await pipeline(createReadStream(input, { start: envelope.ciphertextOffset, end: envelope.size - 17 }), decipher, createWriteStream(output, { mode: 0o600 }));
-        chmodSync(output, 0o600);
-    }
-    catch (cause) {
-        rmSync(output, { force: true });
-        throw new KnowzError('Wrong passphrase or tampered archive.', ExitCode.Auth, { cause });
-    }
+    await withPrivateOutput(output, async (temporary) => {
+        try {
+            await pipeline(createReadStream(input, { start: envelope.ciphertextOffset, end: envelope.size - 17 }), decipher, createWriteStream(temporary));
+        }
+        catch (cause) {
+            throw new KnowzError('Wrong passphrase or tampered archive.', ExitCode.Auth, { cause });
+        }
+    });
 }
 export async function runRestorePreflight(paths, projectName, opts) {
     if (!opts.yes && !opts.isTty) {
@@ -327,7 +442,11 @@ export async function runRestorePreflight(paths, projectName, opts) {
     const invocation = existsSync(paths.composeFile) && existsSync(paths.envFile)
         ? composeInvocation(paths, projectName, engine, ['ps', '--services', '--status', 'running'])
         : engineInvocation(engine, process.cwd(), [
-            'ps', '--filter', `label=com.docker.compose.project=${projectName}`, '--format', '{{.Names}}',
+            'ps',
+            '--filter',
+            `label=com.docker.compose.project=${projectName}`,
+            '--format',
+            '{{.Names}}',
         ]);
     const result = await Promise.resolve(opts.runner(invocation.command, invocation.args, invocation.options));
     if (result.status !== 0) {
@@ -370,7 +489,8 @@ function ensureBackupRuntime(paths) {
     const env = parseEnv(readFileSync(paths.envFile, 'utf8'));
     const pgHost = env.PG_HOST?.trim();
     const s3Endpoint = env.S3_ENDPOINT?.trim();
-    if ((pgHost && pgHost !== 'postgres') || (s3Endpoint && !/^https?:\/\/minio(?::|\/|$)/i.test(s3Endpoint))) {
+    if ((pgHost && pgHost !== 'postgres') ||
+        (s3Endpoint && !/^https?:\/\/minio(?::|\/|$)/i.test(s3Endpoint))) {
         throw new KnowzError('Portable backup v1 does not support external database or object-storage backends.', ExitCode.Usage);
     }
     return env;
@@ -386,7 +506,10 @@ function resolveArchiveDestination(out, projectName, encrypted, now) {
         destination = resolve(process.cwd(), filename);
     else {
         const candidate = resolve(out);
-        destination = existsSync(candidate) && statSync(candidate).isDirectory() ? join(candidate, filename) : candidate;
+        destination =
+            existsSync(candidate) && statSync(candidate).isDirectory()
+                ? join(candidate, filename)
+                : candidate;
         if (encrypted && !destination.endsWith('.enc'))
             destination += '.enc';
     }
@@ -398,52 +521,81 @@ function resolveArchiveDestination(out, projectName, encrypted, now) {
 }
 export async function runPortableBackup(input) {
     const env = ensureBackupRuntime(input.paths);
-    const engine = requireEngine(input.engine);
+    const engine = await assertLocalEngineContext(requireEngine(input.engine), {
+        runner: input.runner,
+        savedEngine: readSavedLocalEngine(input.paths.stateFile),
+    });
     if (input.encrypt && !input.passphrase)
         throw new KnowzError('A backup passphrase is required for --encrypt.', ExitCode.Auth);
     const now = input.now?.() ?? new Date();
     const destination = resolveArchiveDestination(input.out, input.projectName, input.encrypt, now);
     const secrets = knownSecretValues(env);
-    const staging = createPrivateStaging(input.paths.runtimeDir);
-    const plainArchive = join(input.paths.runtimeDir, `.backup-${process.pid}-${Date.now()}.tar.gz`);
-    let startedPostgres = false;
-    let stopInvocation;
+    const unlock = acquireRuntimeLock(input.paths.runtimeDir);
     try {
-        mkdirSync(join(staging, 'pg'), { recursive: true, mode: 0o700 });
-        mkdirSync(join(staging, 'volumes'), { recursive: true, mode: 0o700 });
-        mkdirSync(join(staging, 'runtime'), { recursive: true, mode: 0o700 });
-        copyFileSync(input.paths.envFile, join(staging, 'runtime/.env'));
-        copyFileSync(input.paths.stateFile, join(staging, 'runtime/state.json'));
-        const ps = composeInvocation(input.paths, input.projectName, engine, ['ps', '--services', '--status', 'running', 'postgres']);
-        const status = await runInvocation(ps, 'inspect postgres', input.runner, secrets);
-        const postgresRunning = (status.stdout ?? '').split(/\r?\n/).some(service => service.trim() === 'postgres');
-        const plan = planBackup(input.paths, input.projectName, env, { postgresRunning, engine, stagingDir: staging });
-        stopInvocation = plan.find(step => step.description === 'stop postgres')?.invocation;
-        startedPostgres = !postgresRunning;
-        await executeBackupSteps(plan.filter(step => step.description !== 'stop postgres'), input.runner, secrets);
-        const manifest = buildManifest(input.projectName, env, input.cliVersion, input.encrypt, staging);
-        writeFileSync(join(staging, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
-        await runInvocation({ command: 'tar', args: ['-czf', plainArchive, '-C', staging, '.'], options: { cwd: input.paths.runtimeDir, shell: false } }, 'create backup archive', input.runner, secrets);
-        chmodSync(plainArchive, 0o600);
-        if (input.encrypt) {
-            await encryptStream(plainArchive, destination, input.passphrase);
-            rmSync(plainArchive, { force: true });
+        const staging = createPrivateStaging(input.paths.runtimeDir);
+        const plainArchive = join(input.paths.runtimeDir, `.backup-${process.pid}-${Date.now()}.tar.gz`);
+        let startedPostgres = false;
+        let stopInvocation;
+        try {
+            ensurePrivateDirectory(join(staging, 'pg'));
+            ensurePrivateDirectory(join(staging, 'volumes'));
+            ensurePrivateDirectory(join(staging, 'runtime'));
+            writePrivateFile(join(staging, 'runtime/.env'), readFileSync(input.paths.envFile, 'utf8'));
+            writePrivateFile(join(staging, 'runtime/state.json'), readFileSync(input.paths.stateFile, 'utf8'));
+            const ps = composeInvocation(input.paths, input.projectName, engine, [
+                'ps',
+                '--services',
+                '--status',
+                'running',
+                'postgres',
+            ]);
+            const status = await runInvocation(ps, 'inspect postgres', input.runner, secrets);
+            const postgresRunning = (status.stdout ?? '')
+                .split(/\r?\n/)
+                .some((service) => service.trim() === 'postgres');
+            const plan = planBackup(input.paths, input.projectName, env, {
+                postgresRunning,
+                engine,
+                stagingDir: staging,
+            });
+            stopInvocation = plan.find((step) => step.description === 'stop postgres')?.invocation;
+            startedPostgres = !postgresRunning;
+            await executeBackupSteps(plan.filter((step) => step.description !== 'stop postgres'), input.runner, secrets);
+            const manifest = buildManifest(input.projectName, env, input.cliVersion, input.encrypt, staging);
+            writeFileSync(join(staging, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`, {
+                mode: 0o600,
+            });
+            await runInvocation({
+                command: 'tar',
+                args: ['-czf', plainArchive, '-C', staging, '.'],
+                options: { cwd: input.paths.runtimeDir, shell: false },
+            }, 'create backup archive', input.runner, secrets);
+            protectPrivatePath(plainArchive);
+            if (input.encrypt) {
+                await encryptStream(plainArchive, destination, input.passphrase);
+                rmSync(plainArchive, { force: true });
+            }
+            else {
+                finalizePrivateArchive(plainArchive, destination);
+            }
+            input.emit?.(BACKUP_SECURITY_WARNING);
+            return { archive: destination, encrypted: input.encrypt, warning: BACKUP_SECURITY_WARNING };
         }
-        else {
-            finalizePrivateArchive(plainArchive, destination);
+        finally {
+            if (startedPostgres && stopInvocation) {
+                try {
+                    await runInvocation(stopInvocation, 'stop postgres', input.runner, secrets);
+                }
+                catch {
+                    /* Preserve the primary result/error. */
+                }
+            }
+            rmSync(staging, { recursive: true, force: true });
+            rmSync(plainArchive, { force: true });
         }
-        input.emit?.(BACKUP_SECURITY_WARNING);
-        return { archive: destination, encrypted: input.encrypt, warning: BACKUP_SECURITY_WARNING };
     }
     finally {
-        if (startedPostgres && stopInvocation) {
-            try {
-                await runInvocation(stopInvocation, 'stop postgres', input.runner, secrets);
-            }
-            catch { /* Preserve the primary result/error. */ }
-        }
-        rmSync(staging, { recursive: true, force: true });
-        rmSync(plainArchive, { force: true });
+        unlock();
     }
 }
 function validateTarListing(listing) {
@@ -479,12 +631,31 @@ function installPortableAssets(paths) {
     if (![compose, contract, postgres].every(existsSync)) {
         throw new KnowzError('Packaged portable runtime assets are incomplete.', ExitCode.Generic);
     }
-    mkdirSync(paths.runtimeDir, { recursive: true, mode: 0o700 });
+    ensurePrivateDirectory(paths.runtimeDir);
     copyFileSync(compose, paths.composeFile);
     copyFileSync(contract, join(paths.runtimeDir, 'runtime-contract.json'));
     rmSync(paths.postgresInitDir, { recursive: true, force: true });
     cpSync(postgres, paths.postgresInitDir, { recursive: true });
 }
+export function rewriteRestoredRuntimeState(json, name, engine) {
+    let state;
+    try {
+        state = JSON.parse(json);
+        if (!state || Array.isArray(state) || typeof state !== 'object')
+            throw new Error();
+    }
+    catch {
+        throw new KnowzError('Archive runtime state is invalid JSON.', ExitCode.Usage);
+    }
+    return (JSON.stringify({
+        ...state,
+        name,
+        engine,
+        healthPassed: false,
+        restoredAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+    }, null, 2) + '\n');
+}
 export async function runPortableRestore(input) {
     if (!input.yes && !input.isTty) {
         throw new KnowzError('Refusing to restore without --yes (no TTY).', ExitCode.Usage);
@@ -494,20 +665,34 @@ export async function runPortableRestore(input) {
         throw new KnowzError(`Backup archive not found: ${archive}`, ExitCode.Usage);
     if (archive.endsWith('.enc') && !input.passphrase)
         throw new KnowzError('A passphrase is required to restore this encrypted backup.', ExitCode.Auth);
-    const engine = requireEngine(input.engine);
-    const stagingParent = mkdtempSync(join(tmpdir(), 'knowz-restore-'));
-    chmodSync(stagingParent, 0o700);
+    const engine = await assertLocalEngineContext(requireEngine(input.engine), {
+        runner: input.runner,
+        savedEngine: readSavedLocalEngine(input.paths.stateFile),
+    });
+    const stagingParent = createPrivateTempDirectory(tmpdir(), 'knowz-restore-');
     const extracted = join(stagingParent, 'extracted');
-    mkdirSync(extracted, { mode: 0o700 });
+    ensurePrivateDirectory(extracted);
     const plainArchive = archive.endsWith('.enc') ? join(stagingParent, 'backup.tar.gz') : archive;
     try {
         if (archive.endsWith('.enc'))
             await decryptStream(archive, plainArchive, input.passphrase);
-        const list = await runInvocation({ command: 'tar', args: ['-tzf', plainArchive], options: { cwd: stagingParent, shell: false } }, 'inspect backup archive', input.runner, []);
+        const list = await runInvocation({
+            command: 'tar',
+            args: ['-tzf', plainArchive],
+            options: { cwd: stagingParent, shell: false },
+        }, 'inspect backup archive', input.runner, []);
         validateTarListing(list.stdout ?? '');
-        const verboseList = await runInvocation({ command: 'tar', args: ['-tvzf', plainArchive], options: { cwd: stagingParent, shell: false } }, 'inspect backup archive entry types', input.runner, []);
+        const verboseList = await runInvocation({
+            command: 'tar',
+            args: ['-tvzf', plainArchive],
+            options: { cwd: stagingParent, shell: false },
+        }, 'inspect backup archive entry types', input.runner, []);
         validateTarEntryTypes(verboseList.stdout ?? '');
-        await runInvocation({ command: 'tar', args: ['-xzf', plainArchive, '--no-same-owner', '--no-same-permissions', '-C', extracted], options: { cwd: stagingParent, shell: false } }, 'extract backup archive', input.runner, []);
+        await runInvocation({
+            command: 'tar',
+            args: ['-xzf', plainArchive, '--no-same-owner', '--no-same-permissions', '-C', extracted],
+            options: { cwd: stagingParent, shell: false },
+        }, 'extract backup archive', input.runner, []);
         const manifestPath = join(extracted, 'manifest.json');
         if (!existsSync(manifestPath))
             throw new KnowzError('Backup archive has no manifest.json.', ExitCode.Usage);
@@ -522,7 +707,10 @@ export async function runPortableRestore(input) {
         input.emit?.(identityWarning);
         input.emit?.('Data Protection keys are deliberately excluded from portable backups. Re-enter federation, Twilio, phone-pool, and tenant-resource credentials after restore.');
         await runRestorePreflight(input.paths, input.projectName, {
-            yes: input.yes, isTty: input.isTty, engine, runner: input.runner,
+            yes: input.yes,
+            isTty: input.isTty,
+            engine,
+            runner: input.runner,
         });
         if (!input.yes) {
             const confirmed = await input.confirmName?.();
@@ -530,47 +718,77 @@ export async function runPortableRestore(input) {
                 throw new KnowzError('Restore confirmation did not match the platform name.', ExitCode.Usage);
         }
         const runtimeExisted = existsSync(input.paths.runtimeDir);
-        if (!runtimeExisted)
-            installPortableAssets(input.paths);
-        else if (!existsSync(input.paths.composeFile))
-            installPortableAssets(input.paths);
-        if (!existsSync(input.paths.envFile))
-            writePrivateFile(input.paths.envFile, readFileSync(join(extracted, 'runtime/.env'), 'utf8'));
-        else
-            input.emit?.('Existing runtime .env preserved; the archive copy was skipped.');
-        if (!existsSync(input.paths.stateFile))
-            writePrivateFile(input.paths.stateFile, readFileSync(join(extracted, 'runtime/state.json'), 'utf8'));
-        const env = parseEnv(readFileSync(input.paths.envFile, 'utf8'));
-        const secrets = knownSecretValues(env);
-        const plan = planRestore(input.paths, input.projectName, manifest, {
-            mode: input.mode, runtimeDirExists: runtimeExisted, engine, stagingDir: extracted, pgUser: env.PG_USER || 'knowz',
-        });
-        const stop = plan.find(step => step.description === 'stop postgres')?.invocation;
-        let postgresStarted = false;
+        const unlock = acquireRuntimeLock(input.paths.runtimeDir);
         try {
-            for (const step of plan) {
-                if (!step.invocation || step.description === 'stop postgres')
-                    continue;
-                await runInvocation(step.invocation, step.description, input.runner, secrets);
-                if (step.description === 'start postgres')
-                    postgresStarted = true;
+            await runRestorePreflight(input.paths, input.projectName, {
+                yes: input.yes,
+                isTty: input.isTty,
+                engine,
+                runner: input.runner,
+            });
+            if (!runtimeExisted && (existsSync(input.paths.stateFile) || existsSync(input.paths.envFile)))
+                throw new KnowzError('Restore target changed during validation.', ExitCode.Usage);
+            if (!runtimeExisted)
+                installPortableAssets(input.paths);
+            else if (!existsSync(input.paths.composeFile))
+                installPortableAssets(input.paths);
+            if (!existsSync(input.paths.envFile))
+                writePrivateFile(input.paths.envFile, readFileSync(join(extracted, 'runtime/.env'), 'utf8'));
+            else
+                input.emit?.('Existing runtime .env preserved; the archive copy was skipped.');
+            if (!existsSync(input.paths.stateFile))
+                writePrivateFile(input.paths.stateFile, rewriteRestoredRuntimeState(readFileSync(join(extracted, 'runtime/state.json'), 'utf8'), input.projectName, engine));
+            const env = parseEnv(readFileSync(input.paths.envFile, 'utf8'));
+            const secrets = knownSecretValues(env);
+            const plan = planRestore(input.paths, input.projectName, manifest, {
+                mode: input.mode,
+                runtimeDirExists: runtimeExisted,
+                engine,
+                stagingDir: extracted,
+                pgUser: env.PG_USER || 'knowz',
+            });
+            const stop = plan.find((step) => step.description === 'stop postgres')?.invocation;
+            let postgresStarted = false;
+            try {
+                for (const step of plan) {
+                    if (!step.invocation || step.description === 'stop postgres')
+                        continue;
+                    await runInvocation(step.invocation, step.description, input.runner, secrets);
+                    if (step.description === 'start postgres')
+                        postgresStarted = true;
+                }
             }
-        }
-        finally {
-            if (postgresStarted && stop) {
-                try {
-                    await runInvocation(stop, 'stop postgres', input.runner, secrets);
+            finally {
+                if (postgresStarted && stop) {
+                    try {
+                        await runInvocation(stop, 'stop postgres', input.runner, secrets);
+                    }
+                    catch {
+                        /* Preserve primary failure. */
+                    }
                 }
-                catch { /* Preserve primary failure. */ }
             }
+            if (input.mode === 'clone') {
+                const warning = 'Clone restore created an empty identity volume: this is a new seat. Run `knowz activate`, then `knowz up`.';
+                input.emit?.(warning);
+                return {
+                    platformName: input.projectName,
+                    mode: input.mode,
+                    next: 'knowz activate && knowz up',
+                    warning,
+                };
+            }
+            input.emit?.('Restore complete. Start the stack with `knowz up`.');
+            return {
+                platformName: input.projectName,
+                mode: input.mode,
+                next: 'knowz up',
+                warning: identityWarning,
+            };
         }
-        if (input.mode === 'clone') {
-            const warning = 'Clone restore created an empty identity volume: this is a new seat. Run `knowz activate`, then `knowz up`.';
-            input.emit?.(warning);
-            return { platformName: input.projectName, mode: input.mode, next: 'knowz activate && knowz up', warning };
+        finally {
+            unlock();
         }
-        input.emit?.('Restore complete. Start the stack with `knowz up`.');
-        return { platformName: input.projectName, mode: input.mode, next: 'knowz up', warning: identityWarning };
     }
     finally {
         rmSync(stagingParent, { recursive: true, force: true });