@aopslabs/aops 0.3.24 → 0.3.26

package/dist/lib/agent-assets/native-fs.js

@@ -543,9 +543,9 @@ function defaultNativeRoot() {
     return moduleDirectory.endsWith(`${path.sep}dist`) ? bundled : compiledOrSource;
 }
 function injectedNativeManifestSha256() {
-    return typeof "99724da24c7a8af713cd05f83646af0ddbf95c89fc892ce31f0edc7d21874483" === 'undefined'
+    return typeof "d079a8a4ff6a05567912c963ac82f52259e980fafc22a041e4934932cdf7c2dd" === 'undefined'
         ? undefined
-        : "99724da24c7a8af713cd05f83646af0ddbf95c89fc892ce31f0edc7d21874483";
+        : "d079a8a4ff6a05567912c963ac82f52259e980fafc22a041e4934932cdf7c2dd";
 }
 function sha256(bytes) {
     return createHash('sha256').update(bytes).digest('hex');

package/dist/lib/community-migration-snapshot.js

@@ -265,6 +265,33 @@ export function readCommunityNativeSnapshotEvidenceV1(params) {
     }
     return { evidencePath, evidenceSha256, evidence };
 }
+export function assertBackupUnchanged(params) {
+    const reread = hashHeldFile(params.heldFd, false);
+    if (reread.sha256 !== params.expectedSha256 || reread.byteLength !== params.expectedByteLength) {
+        throw new Error('community_native_snapshot_backup_identity_changed');
+    }
+}
+export function openBackupForVerify(params) {
+    const noFollow = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+    const verifyFd = openSync(params.backupPath, constants.O_RDONLY | noFollow);
+    try {
+        const written = fstatSync(params.writtenFd, { bigint: true });
+        const opened = fstatSync(verifyFd, { bigint: true });
+        if (!opened.isFile() || opened.nlink !== 1n ||
+            opened.dev !== written.dev || opened.ino !== written.ino ||
+            opened.size !== BigInt(params.expectedByteLength)) {
+            throw new Error('community_native_snapshot_backup_identity_changed');
+        }
+    }
+    catch (error) {
+        try {
+            closeSync(verifyFd);
+        }
+        catch { }
+        throw error;
+    }
+    return verifyFd;
+}
 async function runDocker(params) {
     const result = await params.runtime.run({
         command: 'docker',
@@ -298,7 +325,7 @@ async function runDockerCapture(params) {
     }
     return result.stdout;
 }
-function hashHeldFile(fd, syncBeforeRead = true) {
+export function hashHeldFile(fd, syncBeforeRead = true) {
     if (syncBeforeRead)
         fsyncSync(fd);
     const before = fstatSync(fd, { bigint: true });
@@ -473,13 +500,18 @@ export async function createCommunityNativeManagedSnapshotV1(params) {
             operation: 'verify_create',
             signal: params.signal,
         });
+        const verifyFd = openBackupForVerify({
+            backupPath,
+            writtenFd: backupFd,
+            expectedByteLength: backup.byteLength,
+        });
         try {
             await runDocker({
                 runtime,
                 args: ['container', 'exec', '-i', state.containerName, 'pg_restore', '-U', 'aops',
                     '-d', verifyDatabase, '--no-owner', '--no-acl', '--exit-on-error'],
                 operation: 'verify_restore',
-                inputFd: backupFd,
+                inputFd: verifyFd,
                 signal: params.signal,
             });
             const restored = await (params.planStrictPgSchema ?? planCommunityStrictPgSchema)({
@@ -490,6 +522,10 @@ export async function createCommunityNativeManagedSnapshotV1(params) {
             assertRestoredState(params.planning, restored);
         }
         finally {
+            try {
+                closeSync(verifyFd);
+            }
+            catch { }
             await runDocker({
                 runtime,
                 args: ['container', 'exec', state.containerName, 'dropdb', '-U', 'aops', '--if-exists', '--force', verifyDatabase],
@@ -497,6 +533,11 @@ export async function createCommunityNativeManagedSnapshotV1(params) {
                 signal: params.signal,
             });
         }
+        assertBackupUnchanged({
+            heldFd: backupFd,
+            expectedSha256: backup.sha256,
+            expectedByteLength: backup.byteLength,
+        });
         const dataFingerprint = sourceDataFingerprint(params.planning);
         const evidence = {
             schemaVersion: 1,

package/dist/lib/community-native-backup.js

@@ -0,0 +1,386 @@
+import { spawn } from 'node:child_process';
+import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { assertBackupUnchanged, hashHeldFile, openBackupForVerify } from './community-migration-snapshot.js';
+export async function runNativePgProcess(params) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(params.tool, params.args, {
+            env: params.env ? { ...process.env, ...params.env } : process.env,
+            stdio: [
+                params.inputFd === undefined ? 'ignore' : params.inputFd,
+                params.outputFd === undefined ? 'ignore' : params.outputFd,
+                'inherit',
+            ],
+            shell: false,
+        });
+        child.on('error', reject);
+        child.on('close', (exitCode, signal) => resolve({ exitCode, signal }));
+    });
+}
+export function pgEnvironmentFromUrl(repoUrl) {
+    let parsed;
+    try {
+        parsed = new URL(repoUrl);
+    }
+    catch {
+        throw new Error('community_native_backup_repo_url_invalid');
+    }
+    if (parsed.protocol !== 'postgres:' && parsed.protocol !== 'postgresql:') {
+        throw new Error('community_native_backup_repo_url_invalid');
+    }
+    const database = decodeURIComponent(parsed.pathname.replace(/^\//, ''));
+    if (!database)
+        throw new Error('community_native_backup_repo_url_invalid');
+    const env = {
+        PGHOST: parsed.hostname,
+        PGDATABASE: database,
+    };
+    if (parsed.port)
+        env.PGPORT = parsed.port;
+    if (parsed.username)
+        env.PGUSER = decodeURIComponent(parsed.username);
+    if (parsed.password)
+        env.PGPASSWORD = decodeURIComponent(parsed.password);
+    const sslmode = parsed.searchParams.get('sslmode');
+    if (sslmode)
+        env.PGSSLMODE = sslmode;
+    return env;
+}
+export function resolvePgTool(tool, options = {}) {
+    const exists = options.exists ?? existsSync;
+    const executable = process.platform === 'win32' ? `${tool}.exe` : tool;
+    if (options.explicit)
+        return options.explicit;
+    if (options.binDir)
+        return path.join(options.binDir, executable);
+    const candidates = process.platform === 'darwin'
+        ? ['/Applications/pgAdmin 4.app/Contents/SharedSupport', '/opt/homebrew/bin', '/usr/local/bin']
+        : process.platform === 'win32'
+            ? ['C:\\Program Files\\PostgreSQL\\17\\bin', 'C:\\Program Files\\PostgreSQL\\16\\bin']
+            : ['/usr/bin', '/usr/local/bin'];
+    for (const dir of candidates) {
+        const candidate = path.join(dir, executable);
+        if (exists(candidate))
+            return candidate;
+    }
+    return executable;
+}
+function assertSafeBackupRoot(backupRoot) {
+    mkdirSync(backupRoot, { recursive: true, mode: 0o700 });
+    const stats = lstatSync(backupRoot, { bigint: true });
+    if (stats.isSymbolicLink() || !stats.isDirectory()) {
+        throw new Error('community_backup_root_unsafe');
+    }
+    return realpathSync.native(backupRoot);
+}
+export function verifyHeldBackupAgainstReceipt(params) {
+    const hashed = hashHeldFile(params.heldFd, false);
+    if (hashed.byteLength !== params.receipt.byteLength) {
+        throw new Error('community_native_backup_size_mismatch');
+    }
+    if (hashed.sha256 !== params.receipt.sha256) {
+        throw new Error('community_native_backup_digest_mismatch');
+    }
+}
+export function planSchemaRewind(params) {
+    const inArchive = new Set([...params.archiveSchemas, 'public']);
+    const orphaned = params.databaseSchemas.filter((name) => !inArchive.has(name));
+    if (orphaned.length > 0) {
+        throw new Error(`community_native_restore_schema_not_in_backup:${orphaned.join(',')}:` +
+            'dropping_would_lose_them_keeping_would_leave_a_partial_rewind');
+    }
+    const drop = new Set(params.databaseSchemas);
+    drop.add('public');
+    return { drop: [...drop].sort() };
+}
+export function quoteSchemaIdentifier(name) {
+    if (name === '' || name.includes('\u0000')) {
+        throw new Error('community_native_restore_schema_name_unrepresentable');
+    }
+    return `"${name.replace(/"/g, '""')}"`;
+}
+export function parseArchiveSchemas(pgRestoreListOutput) {
+    const names = new Set();
+    for (const line of pgRestoreListOutput.split('\n')) {
+        const match = /\bSCHEMA\s+-\s+(\S+)/.exec(line);
+        if (match?.[1])
+            names.add(match[1]);
+    }
+    return [...names].sort();
+}
+export async function resolveSchemaRewindPlan(params) {
+    const pgEnv = pgEnvironmentFromUrl(params.repoUrl);
+    const capture = params.captureOutput ?? defaultCaptureOutput;
+    const query = "select nspname from pg_namespace where nspname not in ('information_schema','pg_catalog','pg_toast') and nspname not like 'pg_temp%' and nspname not like 'pg_toast_temp%'";
+    const databaseSchemas = (await capture({
+        tool: resolvePgTool('psql', { explicit: params.psql, binDir: params.pgBinDir }),
+        args: ['--dbname', String(pgEnv.PGDATABASE), '--tuples-only', '--no-align', '--quiet', '--command', query],
+        env: pgEnv,
+    }))
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+    const archiveSchemas = parseArchiveSchemas(await capture(params.archiveFd === undefined
+        ? {
+            tool: resolvePgTool('pg_restore', { explicit: params.pgRestore, binDir: params.pgBinDir }),
+            args: ['--list', params.archivePath],
+        }
+        : {
+            tool: resolvePgTool('pg_restore', { explicit: params.pgRestore, binDir: params.pgBinDir }),
+            args: ['--list'],
+            inputFd: params.archiveFd,
+        }));
+    return planSchemaRewind({ databaseSchemas, archiveSchemas });
+}
+async function defaultCaptureOutput(params) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(params.tool, params.args, {
+            stdio: [params.inputFd ?? 'ignore', 'pipe', 'inherit'],
+            shell: false,
+            env: params.env ? { ...process.env, ...params.env } : process.env,
+        });
+        let out = '';
+        const stdout = child.stdout;
+        if (!stdout) {
+            reject(new Error('community_native_restore_schema_probe_no_output'));
+            return;
+        }
+        stdout.setEncoding('utf8');
+        stdout.on('data', (chunk) => { out += chunk; });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code !== 0)
+                reject(new Error(`community_native_restore_schema_probe_failed:exit_${String(code)}`));
+            else
+                resolve(out);
+        });
+    });
+}
+function hashBackupAtPath(backupPath) {
+    const fd = openSync(backupPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        return hashHeldFile(fd, false).sha256;
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch { }
+    }
+}
+export async function verifyCommunityNativeBackupV1(params) {
+    const readText = params.readFileText ?? ((candidate) => readFileSync(candidate, 'utf8'));
+    const receiptPath = `${params.backupPath}.json`;
+    if (!existsSync(receiptPath))
+        throw new Error('community_native_backup_receipt_missing');
+    let record;
+    try {
+        record = JSON.parse(readText(receiptPath));
+    }
+    catch {
+        throw new Error('community_native_backup_receipt_unreadable');
+    }
+    if (record?.kind !== 'native-pg-custom' || record.schemaVersion !== 1 || record.verified !== true) {
+        throw new Error('community_native_backup_receipt_invalid');
+    }
+    if (record.verifiedBy !== undefined && record.verifiedBy !== 'pg-restore-list') {
+        throw new Error('community_native_backup_receipt_unknown_verification_depth');
+    }
+    if (path.resolve(String(record.path)) !== path.resolve(params.backupPath)) {
+        throw new Error('community_native_backup_receipt_path_mismatch');
+    }
+    const stats = params.statFile ? params.statFile(params.backupPath) : statSync(params.backupPath);
+    if (stats.size !== record.byteLength)
+        throw new Error('community_native_backup_size_mismatch');
+    const digest = params.hashFile ? params.hashFile(params.backupPath) : hashBackupAtPath(params.backupPath);
+    if (digest !== record.sha256)
+        throw new Error('community_native_backup_digest_mismatch');
+    return record;
+}
+export async function createCommunityNativeBackupV1(params) {
+    const run = params.runProcess ?? runNativePgProcess;
+    const now = params.now ?? (() => new Date());
+    const backupRoot = assertSafeBackupRoot(params.backupRoot);
+    const label = params.label ? `-${params.label.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 64)}` : '';
+    const backupPath = path.join(backupRoot, `${now().toISOString().replace(/[:.]/g, '-')}${label}-${randomUUID()}.dump`);
+    const noFollow = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+    const backupFd = openSync(backupPath, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | noFollow, 0o600);
+    let keep = false;
+    try {
+        const pgEnv = pgEnvironmentFromUrl(params.repoUrl);
+        const dump = await run({
+            tool: resolvePgTool('pg_dump', { explicit: params.pgDump, binDir: params.pgBinDir }),
+            args: ['--format=custom', '--no-owner', '--no-acl'],
+            outputFd: backupFd,
+            env: pgEnv,
+        });
+        if (dump.exitCode !== 0) {
+            throw new Error(`community_native_backup_dump_failed:exit_${String(dump.exitCode ?? 'null')}`);
+        }
+        const hashed = hashHeldFile(backupFd);
+        const verifyFd = openBackupForVerify({
+            backupPath,
+            writtenFd: backupFd,
+            expectedByteLength: hashed.byteLength,
+        });
+        try {
+            const verify = await run({
+                tool: resolvePgTool('pg_restore', { explicit: params.pgRestore, binDir: params.pgBinDir }),
+                args: ['--list'],
+                inputFd: verifyFd,
+            });
+            if (verify.exitCode !== 0) {
+                throw new Error(`community_native_backup_verify_failed:exit_${String(verify.exitCode ?? 'null')}`);
+            }
+        }
+        finally {
+            try {
+                closeSync(verifyFd);
+            }
+            catch { }
+        }
+        assertBackupUnchanged({
+            heldFd: backupFd,
+            expectedSha256: hashed.sha256,
+            expectedByteLength: hashed.byteLength,
+        });
+        const record = {
+            schemaVersion: 1,
+            kind: 'native-pg-custom',
+            path: backupPath,
+            sha256: hashed.sha256,
+            byteLength: hashed.byteLength,
+            verified: true,
+            verifiedBy: 'pg-restore-list',
+            createdAt: now().toISOString(),
+            instanceName: params.instanceName,
+            releaseVersion: params.releaseVersion ?? null,
+        };
+        const receiptPath = `${backupPath}.json`;
+        if (existsSync(receiptPath))
+            throw new Error('community_native_backup_receipt_already_exists');
+        writeFileSync(receiptPath, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+        keep = true;
+        return { record, receiptPath };
+    }
+    finally {
+        try {
+            closeSync(backupFd);
+        }
+        catch { }
+        if (!keep) {
+            try {
+                const { unlinkSync } = await import('node:fs');
+                unlinkSync(backupPath);
+            }
+            catch { }
+        }
+    }
+}
+export async function restoreCommunityNativeBackupV1(params) {
+    if (params.confirmDataRewind !== true) {
+        throw new Error('community_native_restore_confirmation_required:pass_--confirm-data-rewind');
+    }
+    if (params.skipPreRestoreBackup === true && params.confirmNoUndo !== true) {
+        throw new Error('community_native_restore_no_undo_confirmation_required:pass_--confirm-no-undo');
+    }
+    const run = params.runProcess ?? runNativePgProcess;
+    const receiptPath = `${params.backupPath}.json`;
+    if (!existsSync(receiptPath))
+        throw new Error('community_native_backup_receipt_missing');
+    let record;
+    try {
+        record = JSON.parse(readFileSync(receiptPath, 'utf8'));
+    }
+    catch {
+        throw new Error('community_native_backup_receipt_unreadable');
+    }
+    if (record?.kind !== 'native-pg-custom' || record.schemaVersion !== 1 || record.verified !== true) {
+        throw new Error('community_native_backup_receipt_invalid');
+    }
+    if (path.resolve(String(record.path)) !== path.resolve(params.backupPath)) {
+        throw new Error('community_native_backup_receipt_path_mismatch');
+    }
+    const noFollow = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+    const archiveFd = openSync(params.backupPath, constants.O_RDONLY | noFollow);
+    let preRestoreBackup = null;
+    try {
+        const pgEnv = pgEnvironmentFromUrl(params.repoUrl);
+        const probeFd = openBackupForVerify({
+            backupPath: params.backupPath,
+            writtenFd: archiveFd,
+            expectedByteLength: record.byteLength,
+        });
+        let rewindPlan;
+        try {
+            rewindPlan = await resolveSchemaRewindPlan({
+                repoUrl: params.repoUrl,
+                archivePath: params.backupPath,
+                archiveFd: probeFd,
+                pgBinDir: params.pgBinDir,
+                psql: params.psql,
+                pgRestore: params.pgRestore,
+                captureOutput: params.captureSchemaProbe,
+            });
+        }
+        finally {
+            try {
+                closeSync(probeFd);
+            }
+            catch { }
+        }
+        if (params.skipPreRestoreBackup !== true) {
+            const taken = await createCommunityNativeBackupV1({
+                backupRoot: params.backupRoot,
+                repoUrl: params.repoUrl,
+                instanceName: params.instanceName,
+                releaseVersion: params.releaseVersion ?? null,
+                pgBinDir: params.pgBinDir,
+                pgDump: params.pgDump,
+                pgRestore: params.pgRestore,
+                now: params.now,
+                runProcess: params.runProcess,
+            });
+            preRestoreBackup = {
+                path: taken.record.path,
+                sha256: taken.record.sha256,
+                byteLength: taken.record.byteLength,
+            };
+        }
+        verifyHeldBackupAgainstReceipt({ heldFd: archiveFd, receipt: record });
+        const rewind = await run({
+            tool: resolvePgTool('psql', { explicit: params.psql, binDir: params.pgBinDir }),
+            args: [
+                '--dbname', String(pgEnv.PGDATABASE),
+                '--set', 'ON_ERROR_STOP=1',
+                '--quiet',
+                '--command',
+                `${rewindPlan.drop.map((name) => `DROP SCHEMA IF EXISTS ${quoteSchemaIdentifier(name)} CASCADE;`).join(' ')} CREATE SCHEMA public;`,
+            ],
+            env: pgEnv,
+        });
+        if (rewind.exitCode !== 0) {
+            throw new Error(`community_native_restore_rewind_failed:exit_${String(rewind.exitCode ?? 'null')}`);
+        }
+        const restore = await run({
+            tool: resolvePgTool('pg_restore', { explicit: params.pgRestore, binDir: params.pgBinDir }),
+            args: [
+                '--dbname', String(pgEnv.PGDATABASE),
+                '--no-owner', '--no-acl', '--exit-on-error',
+            ],
+            inputFd: archiveFd,
+            env: pgEnv,
+        });
+        if (restore.exitCode !== 0) {
+            throw new Error(`community_native_restore_failed:exit_${String(restore.exitCode ?? 'null')}`);
+        }
+    }
+    finally {
+        try {
+            closeSync(archiveFd);
+        }
+        catch { }
+    }
+    return { restored: record, preRestoreBackup };
+}

package/dist/lib/community-native-lifecycle.js

@@ -10,7 +10,8 @@ import { resolveCommunityInstallPaths } from './community-lifecycle.js';
 import { buildCommunityInstanceContract, } from './community-instance-contract.js';
 import { COMMUNITY_NATIVE_POSTGRES_CONTRACT_PATH, assertCommunityNativePostgresInstanceState, assertCommunityNativePostgresState, buildCommunityNativePostgresUrl, setupCommunityNativePostgres, startCommunityNativePostgres, } from './community-native-postgres.js';
 import { COMMUNITY_NATIVE_MIGRATION_POLICY_PATH, assertCommunityNativeMigrationReceiptV1, planCommunityNativeMigration, runCommunityNativeMigration, } from './community-native-migration.js';
-import { createCommunityExternalSnapshotAttestationV1, writeCommunityExternalSnapshotAttestationV1, } from './community-migration-snapshot.js';
+import { createCommunityExternalSnapshotAttestationV1, createCommunityNativeManagedSnapshotV1, writeCommunityExternalSnapshotAttestationV1, } from './community-migration-snapshot.js';
+import { createCommunityNativeBackupV1 } from './community-native-backup.js';
 import { createCommunityNativeApplicationReferenceV1, readCommunityNativeApplicationUpdate, sameCommunityNativeApplicationContent, writeCommunityNativeApplicationRollbackOutcome, writeCommunityNativeApplicationRollbackPrepared, writeCommunityNativeApplicationUpdateOutcome, writeCommunityNativeApplicationUpdatePrepared, } from './community-native-application-recovery.js';
 const PUBLIC_ROOT_NAME = 'aops-community-distribution';
 const PUBLIC_SERVER_PACKAGE_NAME = '@aopslabs/aops-server';
@@ -1195,10 +1196,17 @@ export async function attestCommunityNativeExternalSnapshot(params, dependencies
         evidence,
     };
 }
-function childEnvironment(params) {
+const FORWARDED_TUNING_ENV_KEYS = new Set([
+    'CHATV3_RATE_OPEN_PER_MIN',
+    'CHATV3_RATE_MEMBER_PER_MIN',
+    'CHATV3_RATE_LOCAL_PER_MIN',
+]);
+export function childEnvironment(params) {
     const env = { ...(params.env ?? process.env) };
     for (const key of Object.keys(env)) {
         const upper = key.toUpperCase();
+        if (FORWARDED_TUNING_ENV_KEYS.has(upper))
+            continue;
         if (/^PG[A-Z0-9_]+$/i.test(key) ||
             /(?:^|_)(?:AUTH|COOKIE|DATABASE|ENCRYPT|JWT|PASSWORD|PG|POSTGRES|REPO|SECRET|SESSION|SQLITE|TOKEN)(?:_|$)/i.test(key) ||
             /^(?:AOPS|PROJECTMAN|DOCMAN|AGENTSPACE|CHATV3|AUTHV2|KANBAN|SPRINT|TASKER|FILEMAN|SYS)_/i.test(key) ||
@@ -1529,6 +1537,16 @@ function removeControlIfExact(paths, launchId) {
         throw new Error('community_native_control_launch_mismatch');
     rmSync(paths.controlPath, { force: true });
 }
+function reconcileDisappearedRecord(record, reason, now) {
+    if (record.status !== 'starting' && record.status !== 'running')
+        return record;
+    return {
+        ...record,
+        status: 'failed',
+        updatedAt: now().toISOString(),
+        failure: record.failure ?? reason,
+    };
+}
 async function observeInstalledNative(params) {
     const record = params.processRecord;
     const identityPresent = existsSync(params.paths.identityPath);
@@ -1607,7 +1625,8 @@ async function observeInstalledNative(params) {
     if (!identity) {
         if (!supervisorAlive && !hostAlive) {
             return {
-                runtimeState: 'crashed', recoverable: true, process: record, identity: null,
+                runtimeState: 'crashed', recoverable: true, identity: null,
+                process: reconcileDisappearedRecord(record, 'community_native_process_disappeared_without_identity', params.now),
                 supervisorAlive: false, hostAlive: false, health: 'not-checked',
                 reason: 'community_native_process_disappeared_without_identity',
             };
@@ -1620,7 +1639,8 @@ async function observeInstalledNative(params) {
     }
     if (!supervisorAlive && !hostAlive) {
         return {
-            runtimeState: 'crashed', recoverable: true, process: record, identity,
+            runtimeState: 'crashed', recoverable: true, identity,
+            process: reconcileDisappearedRecord(record, 'community_native_process_disappeared', params.now),
             supervisorAlive: false, hostAlive: false, health: 'not-checked',
             reason: 'community_native_process_disappeared',
         };
@@ -1689,6 +1709,10 @@ export async function stopCommunityNativeInstall(params = {}) {
         now,
     });
     if (observed.runtimeState === 'stopped' || observed.runtimeState === 'crashed') {
+        if (observed.runtimeState === 'crashed' && observed.process &&
+            inspection.process && inspection.process.status !== observed.process.status) {
+            writeProcess(inspection.paths, observed.process);
+        }
         return { status: 'already-stopped', state: inspection.state, process: observed.process };
     }
     if (!observed.process || !observed.identity || !observed.supervisorAlive ||
@@ -1842,6 +1866,60 @@ export function resolveCommunityNativeLaunchMode(input) {
         throw new Error('community_native_launch_mode_conflict');
     return input.foreground === true ? 'foreground' : 'detached';
 }
+export async function resolveCommunityNativeSnapshotEvidence(params) {
+    if (params.context.planning.migrationPlan.action !== 'migrate')
+        return null;
+    const exists = params.fileExists ?? existsSync;
+    if (params.postgres.mode === 'container') {
+        const create = params.createManagedSnapshot ?? createCommunityNativeManagedSnapshotV1;
+        const snapshot = await create({
+            planning: params.context.planning,
+            policy: params.context.policy,
+            sourceRoot: params.context.sourceRoot,
+            state: params.postgres,
+            instanceName: params.instanceName,
+            instanceRoot: params.instanceRoot,
+            backupRoot: params.backupRoot,
+            evidenceRoot: params.evidenceRoot,
+            runtime: params.postgresRuntime,
+            signal: params.signal,
+        });
+        return { path: snapshot.evidencePath, policy: 'managed-verified-only-v1' };
+    }
+    const attestationPath = path.join(params.evidenceRoot, `external-${params.context.planning.acceptedPlanSha256}.json`);
+    if (exists(attestationPath)) {
+        return { path: attestationPath, policy: 'managed-or-external-attested-v1' };
+    }
+    const postgres = params.postgres;
+    const loadUrl = params.loadRepoUrl
+        ?? ((state) => {
+            const configRef = state.configRef;
+            if (typeof configRef !== 'string' || configRef.trim() === '') {
+                throw new Error('community_native_snapshot_external_config_ref_missing');
+            }
+            return loadExternalPostgresUrl(configRef, state.tlsPolicy);
+        });
+    const createBackup = params.createExternalBackup ?? createCommunityNativeBackupV1;
+    const writeAttestation = params.writeExternalAttestation ?? writeCommunityExternalSnapshotAttestationV1;
+    const firstPending = params.context.planning.migrationPlan.pendingMigrations?.[0]?.tag;
+    const { record } = await createBackup({
+        backupRoot: params.backupRoot,
+        repoUrl: loadUrl(postgres),
+        instanceName: params.instanceName,
+        label: firstPending ? `pre-${firstPending}` : 'pre-migration',
+    });
+    const written = writeAttestation({
+        planning: params.context.planning,
+        policy: params.context.policy,
+        evidenceRoot: params.evidenceRoot,
+        provider: 'aops-cli-native-pg-dump',
+        snapshotRef: record.path,
+        snapshotDigest: record.sha256,
+        attestedBy: 'aops-cli',
+        restoreInstructionsRef: `aops db restore --backup ${record.path} --confirm-data-rewind`,
+    });
+    return { path: written.evidencePath, policy: 'managed-or-external-attested-v1' };
+}
 async function launchInstalledNative(params) {
     throwIfNativeAborted(params.signal);
     assertCommunityNativePathLayout(params.paths, { requireInstanceRoot: true });
@@ -1911,6 +1989,17 @@ async function launchInstalledNative(params) {
         sourceFingerprint: params.state.source.sourceFingerprint,
         requiredPlanSha256: params.requiredMigrationPlanSha256,
         requiredAction: params.requiredMigrationAction,
+        snapshotEvidenceProvider: (context) => resolveCommunityNativeSnapshotEvidence({
+            context,
+            postgres,
+            instanceName: params.state.instanceName,
+            instanceRoot: params.paths.instanceRoot,
+            backupRoot: params.paths.backupRoot,
+            evidenceRoot: params.paths.migrationEvidenceRoot,
+            postgresRuntime: params.postgresRuntime,
+            signal: params.signal,
+            createManagedSnapshot: params.createManagedSnapshot,
+        }),
         onPlanAccepted: (context) => {
             const pendingMigrationCount = context.migrationPlan.pendingMigrations.length;
             params.progress?.({

package/dist/lib/community-native-migration.js

@@ -212,6 +212,26 @@ function receiptFromResult(invocation, result, completedAt, migrationLogCount) {
         migrationLogCount,
     });
 }
+export async function reportCommunityNativePendingMigrations(params, dependencies = {}) {
+    try {
+        const policy = readCommunityNativeMigrationPolicy(params.sourceRoot);
+        const planning = await (dependencies.planStrictPgSchema ?? planCommunityStrictPgSchema)({
+            repoUrl: params.repoUrl,
+            workspaceRoot: params.sourceRoot,
+            policy,
+        });
+        const pending = planning.migrationPlan.pendingMigrations ?? [];
+        return {
+            status: 'planned',
+            action: planning.migrationPlan.action,
+            pendingMigrationCount: pending.length,
+            pendingMigrationTags: pending.map((entry) => String(entry.tag ?? '')).filter(Boolean),
+        };
+    }
+    catch (error) {
+        return { status: 'unavailable', reason: error instanceof Error ? error.message : String(error) };
+    }
+}
 export async function runCommunityNativeMigration(invocation, dependencies = {}) {
     const prior = invocation.priorIntentExpectation;
     if (!path.isAbsolute(invocation.sourceRoot) || !invocation.repoUrl ||