@moretea-labs/forge 1.6.0 → 1.7.0

package/src/runtime/control-plane/persistence/controller-home-migration.ts

@@ -0,0 +1,487 @@
+import { createHash, randomUUID } from 'crypto';
+import { chmodSync, createReadStream, existsSync, mkdirSync, renameSync, statSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import {
+  backupControlPlaneDatabase,
+  CONTROL_PLANE_SCHEMA_VERSION,
+  inspectControlPlaneDatabaseFile,
+  listControlPlaneRecords,
+  readControlPlaneRecord,
+  readControlPlaneRecordWithinTransaction,
+  withControlPlaneTransaction,
+  writeControlPlaneRecord,
+  writeControlPlaneRecordWithinTransaction,
+  type ControlPlaneDatabaseInspection,
+  type ControlPlaneRecord,
+} from './sqlite-store';
+import { listRepositories } from '../../../cli/repositories/registry';
+
+const MIGRATION_NAMESPACE = 'controller_home_migration';
+const MIGRATION_SCOPE = 'controller';
+const IMPORTABLE_REFERENCED_NAMESPACES = [
+  'execution_work_validation_index',
+  'execution_edit_validation_run',
+  'execution_edit_validation_index',
+  'chatgpt_work_conversation_binding',
+  'controller_session_claim_store',
+  'controller_round_relay',
+  'external_controller_launch_reservation',
+] as const;
+const TERMINAL_WORK_STATUSES = new Set(['completed', 'failed', 'cancelled']);
+
+export interface ControllerHomeMigrationRecordRef {
+  namespace: string;
+  scope: string;
+  key: string;
+  schemaVersion: number;
+  sourceRevision: number;
+  sourceUpdatedAt: string;
+}
+
+export interface ControllerHomeMigrationConflict extends ControllerHomeMigrationRecordRef {
+  kind: 'payload_conflict';
+}
+
+export interface ControllerHomeMigrationPreview {
+  sourceHome: string;
+  destinationHome: string;
+  sourceDatabase: {
+    path: string;
+    sha256: string;
+    walPath?: string;
+    walSha256?: string;
+    inspection: ControlPlaneDatabaseInspection;
+  };
+  destinationDatabase: {
+    path: string;
+    exists: boolean;
+    inspection?: ControlPlaneDatabaseInspection;
+  };
+  selected: ControllerHomeMigrationRecordRef[];
+  selectedByNamespace: Record<string, number>;
+  identical: ControllerHomeMigrationRecordRef[];
+  conflicts: ControllerHomeMigrationConflict[];
+  archivedOnly: {
+    terminalWorkContracts: number;
+    excludedNamespaces: readonly string[];
+    auditChain: 'retained_in_source_sqlite';
+  };
+}
+
+interface ImportedRecord extends ControllerHomeMigrationRecordRef {
+  destinationRevision: number;
+}
+
+interface ControllerHomeMigrationRecord {
+  schemaVersion: 1;
+  migrationId: string;
+  status: 'applied' | 'rolled_back';
+  sourceHome: string;
+  destinationHome: string;
+  sourceDatabase: ControllerHomeMigrationPreview['sourceDatabase'];
+  destinationBackupPath: string;
+  selected: ControllerHomeMigrationRecordRef[];
+  imported: ImportedRecord[];
+  identical: ControllerHomeMigrationRecordRef[];
+  archivedOnly: ControllerHomeMigrationPreview['archivedOnly'];
+  sourceArchive: {
+    databaseModeBefore: number;
+    databaseModeAfter: number;
+    walModeBefore?: number;
+    walModeAfter?: number;
+    state: 'read_only' | 'restored';
+  };
+  appliedAt: string;
+  rolledBackAt?: string;
+}
+
+export interface AppliedControllerHomeMigration {
+  preview: ControllerHomeMigrationPreview;
+  migration: ControllerHomeMigrationRecord;
+  reportPath: string;
+}
+
+/**
+ * Archives imported Work that cannot be routed because its repository was not
+ * migrated. This is a migration operation, not a Work execution transition:
+ * original payloads remain in the frozen source SQLite and each target record
+ * receives a new auditable terminal revision.
+ */
+export function archiveUnroutableMigratedWork(input: {
+  destinationHome: string;
+  migrationId: string;
+}): { migrationId: string; archivedWorkIds: string[]; archivedHandleIds: string[]; skipped: string[] } {
+  const destinationHome = resolve(input.destinationHome);
+  const migration = readControlPlaneRecord<ControllerHomeMigrationRecord>(destinationHome, MIGRATION_NAMESPACE, MIGRATION_SCOPE, input.migrationId);
+  if (!migration?.value || migration.value.status !== 'applied') throw new Error(`CONTROLLER_HOME_MIGRATION_NOT_APPLIED: ${input.migrationId}`);
+  const knownRepositories = new Set(listRepositories(destinationHome, { includeRemoved: false }).map((repository) => repository.repoId));
+  const imported = new Set(migration.value.imported.map((record) => recordIdentity({ namespace: record.namespace, scope: record.scope, key: record.key })));
+  const archivedWorkIds: string[] = [];
+  const archivedHandleIds: string[] = [];
+  const skipped: string[] = [];
+  withControlPlaneTransaction(destinationHome, (database) => {
+    for (const record of listControlPlaneRecords<unknown>(destinationHome, { namespace: 'work_contract', limit: 5_000 })) {
+      if (!imported.has(recordIdentity(record)) || knownRepositories.has(record.scope)) continue;
+      const value = record.value as Record<string, unknown>;
+      if (TERMINAL_WORK_STATUSES.has(String(value.status ?? ''))) { skipped.push(record.key); continue; }
+      writeControlPlaneRecordWithinTransaction(database, {
+        namespace: record.namespace, scope: record.scope, key: record.key, schemaVersion: record.schemaVersion,
+        value: { ...value, status: 'cancelled', updatedAt: new Date().toISOString(), terminalReason: 'CONTROLLER_HOME_MIGRATION_UNROUTABLE_REPOSITORY_ARCHIVED' },
+        action: 'controller_home_migration_archive_unroutable_work', expectedRevision: record.revision,
+      });
+      archivedWorkIds.push(record.key);
+    }
+    for (const record of listControlPlaneRecords<unknown>(destinationHome, { namespace: 'execution_work_handle', limit: 5_000 })) {
+      if (!imported.has(recordIdentity(record)) || knownRepositories.has(record.scope)) continue;
+      const value = record.value as Record<string, unknown>;
+      if (String(value.state ?? '') === 'cleaned') { skipped.push(record.key); continue; }
+      const finalization = typeof value.finalization === 'object' && value.finalization ? value.finalization : {};
+      writeControlPlaneRecordWithinTransaction(database, {
+        namespace: record.namespace, scope: record.scope, key: record.key, schemaVersion: record.schemaVersion,
+        value: { ...value, state: 'cleaned', updatedAt: new Date().toISOString(), failureReason: 'CONTROLLER_HOME_MIGRATION_UNROUTABLE_REPOSITORY_ARCHIVED', finalization: { ...finalization, validation: 'skipped', commit: 'skipped', merge: 'skipped', branchCleanup: 'skipped', worktreeCleanup: 'skipped' } },
+        action: 'controller_home_migration_archive_unroutable_handle', expectedRevision: record.revision,
+      });
+      archivedHandleIds.push(record.key);
+    }
+  });
+  return { migrationId: input.migrationId, archivedWorkIds, archivedHandleIds, skipped };
+}
+
+function databasePath(home: string): string {
+  return join(resolve(home), 'control-plane.sqlite');
+}
+
+function recordRef(record: ControlPlaneRecord<unknown>): ControllerHomeMigrationRecordRef {
+  return {
+    namespace: record.namespace,
+    scope: record.scope,
+    key: record.key,
+    schemaVersion: record.schemaVersion,
+    sourceRevision: record.revision,
+    sourceUpdatedAt: record.updatedAt,
+  };
+}
+
+function recordIdentity(record: Pick<ControlPlaneRecord<unknown>, 'namespace' | 'scope' | 'key'>): string {
+  return `${record.namespace}\u0000${record.scope}\u0000${record.key}`;
+}
+
+function sameRecord(left: ControlPlaneRecord<unknown>, right: ControlPlaneRecord<unknown>): boolean {
+  return left.schemaVersion === right.schemaVersion && JSON.stringify(left.value) === JSON.stringify(right.value);
+}
+
+function referencesOneOf(value: unknown, ids: ReadonlySet<string>): boolean {
+  if (typeof value === 'string') return ids.has(value);
+  if (!value || typeof value !== 'object') return false;
+  if (Array.isArray(value)) return value.some((entry) => referencesOneOf(entry, ids));
+  return Object.values(value as Record<string, unknown>).some((entry) => referencesOneOf(entry, ids));
+}
+
+function addRecord(
+  selected: Map<string, ControlPlaneRecord<unknown>>,
+  record: ControlPlaneRecord<unknown>,
+): void {
+  selected.set(recordIdentity(record), record);
+}
+
+function allRecords(home: string, namespace: string): ControlPlaneRecord<unknown>[] {
+  return listControlPlaneRecords<unknown>(home, { namespace, limit: 5_000 });
+}
+
+function sourceSelection(sourceHome: string): {
+  records: ControlPlaneRecord<unknown>[];
+  terminalWorkContracts: number;
+} {
+  const selected = new Map<string, ControlPlaneRecord<unknown>>();
+  const workContracts = allRecords(sourceHome, 'work_contract');
+  const activeWork = workContracts.filter((record) => {
+    const status = (record.value as { status?: unknown }).status;
+    return typeof status === 'string' && !TERMINAL_WORK_STATUSES.has(status);
+  });
+  for (const record of activeWork) addRecord(selected, record);
+
+  const planIds = new Set(
+    activeWork
+      .map((record) => (record.value as { planId?: unknown }).planId)
+      .filter((value): value is string => typeof value === 'string' && value.length > 0),
+  );
+  for (const record of allRecords(sourceHome, 'plan_contract')) {
+    if (planIds.has(record.key)) addRecord(selected, record);
+  }
+
+  const workIds = new Set(activeWork.map((record) => record.key));
+  const workHandles = allRecords(sourceHome, 'execution_work_handle').filter((record) => {
+    const value = record.value as { workId?: unknown; workContractId?: unknown };
+    return (typeof value.workId === 'string' && workIds.has(value.workId))
+      || (typeof value.workContractId === 'string' && workIds.has(value.workContractId));
+  });
+  for (const record of workHandles) addRecord(selected, record);
+
+  const sessionIds = new Set(
+    workHandles
+      .map((record) => (record.value as { sessionId?: unknown }).sessionId)
+      .filter((value): value is string => typeof value === 'string' && value.length > 0),
+  );
+  for (const record of allRecords(sourceHome, 'execution_session')) {
+    const sessionId = (record.value as { sessionId?: unknown }).sessionId;
+    if (sessionIds.has(record.key) || (typeof sessionId === 'string' && sessionIds.has(sessionId))) addRecord(selected, record);
+  }
+
+  const referenceIds = new Set<string>([...workIds, ...planIds, ...sessionIds]);
+  for (const namespace of IMPORTABLE_REFERENCED_NAMESPACES) {
+    for (const record of allRecords(sourceHome, namespace)) {
+      if (referencesOneOf(record.value, referenceIds)) addRecord(selected, record);
+    }
+  }
+
+  return {
+    records: [...selected.values()].sort((left, right) => recordIdentity(left).localeCompare(recordIdentity(right))),
+    terminalWorkContracts: workContracts.length - activeWork.length,
+  };
+}
+
+async function sha256(path: string): Promise<string> {
+  return await new Promise<string>((resolveHash, reject) => {
+    const hash = createHash('sha256');
+    const input = createReadStream(path);
+    input.on('error', reject);
+    input.on('data', (chunk: Buffer) => hash.update(chunk));
+    input.on('end', () => resolveHash(hash.digest('hex')));
+  });
+}
+
+function selectedByNamespace(records: readonly ControllerHomeMigrationRecordRef[]): Record<string, number> {
+  return records.reduce<Record<string, number>>((counts, record) => {
+    counts[record.namespace] = (counts[record.namespace] ?? 0) + 1;
+    return counts;
+  }, {});
+}
+
+function destinationRecordIfPresent(
+  destinationHome: string,
+  destinationExists: boolean,
+  record: ControlPlaneRecord<unknown>,
+): ControlPlaneRecord<unknown> | undefined {
+  if (!destinationExists) return undefined;
+  return readControlPlaneRecord<unknown>(destinationHome, record.namespace, record.scope, record.key);
+}
+
+export async function previewControllerHomeMigration(input: {
+  sourceHome: string;
+  destinationHome: string;
+}): Promise<ControllerHomeMigrationPreview> {
+  const sourceHome = resolve(input.sourceHome);
+  const destinationHome = resolve(input.destinationHome);
+  if (sourceHome === destinationHome) throw new Error('CONTROLLER_HOME_MIGRATION_SAME_HOME');
+  const sourceDatabase = databasePath(sourceHome);
+  if (!existsSync(sourceDatabase)) throw new Error(`CONTROLLER_HOME_MIGRATION_SOURCE_DATABASE_MISSING: ${sourceDatabase}`);
+  const sourceWal = `${sourceDatabase}-wal`;
+  const sourceWalExists = existsSync(sourceWal);
+
+  const selection = sourceSelection(sourceHome);
+  const selected = selection.records.map(recordRef);
+  const destinationDatabase = databasePath(destinationHome);
+  const destinationExists = existsSync(destinationDatabase);
+  const identical: ControllerHomeMigrationRecordRef[] = [];
+  const conflicts: ControllerHomeMigrationConflict[] = [];
+  for (const record of selection.records) {
+    const destination = destinationRecordIfPresent(destinationHome, destinationExists, record);
+    if (!destination) continue;
+    if (sameRecord(record, destination)) identical.push(recordRef(record));
+    else conflicts.push({ ...recordRef(record), kind: 'payload_conflict' });
+  }
+
+  return {
+    sourceHome,
+    destinationHome,
+    sourceDatabase: {
+      path: sourceDatabase,
+      sha256: await sha256(sourceDatabase),
+      ...(sourceWalExists ? { walPath: sourceWal, walSha256: await sha256(sourceWal) } : {}),
+      inspection: inspectControlPlaneDatabaseFile(sourceDatabase),
+    },
+    destinationDatabase: {
+      path: destinationDatabase,
+      exists: destinationExists,
+      ...(destinationExists ? { inspection: inspectControlPlaneDatabaseFile(destinationDatabase) } : {}),
+    },
+    selected,
+    selectedByNamespace: selectedByNamespace(selected),
+    identical,
+    conflicts,
+    archivedOnly: {
+      terminalWorkContracts: selection.terminalWorkContracts,
+      excludedNamespaces: ['mcp credentials', 'runtime release authority', 'runtime owner', 'Recovery state', 'plugin configuration', 'process bindings and logs'],
+      auditChain: 'retained_in_source_sqlite',
+    },
+  };
+}
+
+function reportPath(destinationHome: string, migrationId: string): string {
+  return join(destinationHome, 'archives', 'controller-home-migrations', `${migrationId}.json`);
+}
+
+function writeReport(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+export async function applyControllerHomeMigration(input: {
+  sourceHome: string;
+  destinationHome: string;
+}): Promise<AppliedControllerHomeMigration> {
+  const preview = await previewControllerHomeMigration(input);
+  if (preview.conflicts.length > 0) {
+    throw new Error(`CONTROLLER_HOME_MIGRATION_CONFLICTS: ${preview.conflicts.length}`);
+  }
+  const migrationId = `controller-home-${randomUUID()}`;
+  const destinationBackupPath = join(
+    preview.destinationHome,
+    'backups',
+    'controller-home-migrations',
+    `${migrationId}.before.sqlite`,
+  );
+  backupControlPlaneDatabase(preview.destinationHome, destinationBackupPath);
+  const sourceMode = statSync(preview.sourceDatabase.path).mode & 0o777;
+  const sourceWalMode = preview.sourceDatabase.walPath && existsSync(preview.sourceDatabase.walPath)
+    ? statSync(preview.sourceDatabase.walPath).mode & 0o777
+    : undefined;
+  const imported: ImportedRecord[] = [];
+  const selectedRecords = sourceSelection(preview.sourceHome).records;
+  const migration = withControlPlaneTransaction(preview.destinationHome, (database) => {
+    for (const record of selectedRecords) {
+      const current = readControlPlaneRecordWithinTransaction<unknown>(database, record.namespace, record.scope, record.key);
+      if (current) {
+        if (sameRecord(record, current)) continue;
+        throw new Error(`CONTROLLER_HOME_MIGRATION_CONFLICT: ${record.namespace}/${record.scope}/${record.key}`);
+      }
+      const written = writeControlPlaneRecordWithinTransaction(database, {
+        namespace: record.namespace,
+        scope: record.scope,
+        key: record.key,
+        schemaVersion: record.schemaVersion,
+        value: record.value,
+        action: 'controller_home_migration_import',
+        expectedRevision: null,
+      });
+      imported.push({ ...recordRef(record), destinationRevision: written.revision });
+    }
+    const value: ControllerHomeMigrationRecord = {
+      schemaVersion: 1,
+      migrationId,
+      status: 'applied',
+      sourceHome: preview.sourceHome,
+      destinationHome: preview.destinationHome,
+      sourceDatabase: preview.sourceDatabase,
+      destinationBackupPath,
+      selected: preview.selected,
+      imported,
+      identical: preview.identical,
+      archivedOnly: preview.archivedOnly,
+      sourceArchive: {
+        databaseModeBefore: sourceMode,
+        databaseModeAfter: sourceMode,
+        ...(sourceWalMode === undefined ? {} : { walModeBefore: sourceWalMode, walModeAfter: sourceWalMode }),
+        state: 'restored',
+      },
+      appliedAt: new Date().toISOString(),
+    };
+    writeControlPlaneRecordWithinTransaction(database, {
+      namespace: MIGRATION_NAMESPACE,
+      scope: MIGRATION_SCOPE,
+      key: migrationId,
+      schemaVersion: 1,
+      value,
+      action: 'controller_home_migration_applied',
+      expectedRevision: null,
+    });
+    return value;
+  });
+
+  // Only the legacy SQLite authority is frozen. Its full audit history stays
+  // queryable in place; no OAuth, Runtime, Recovery, or plugin files move.
+  const readOnlyMode = sourceMode & ~0o222;
+  chmodSync(preview.sourceDatabase.path, readOnlyMode);
+  const readOnlyWalMode = sourceWalMode === undefined ? undefined : sourceWalMode & ~0o222;
+  if (preview.sourceDatabase.walPath && readOnlyWalMode !== undefined) chmodSync(preview.sourceDatabase.walPath, readOnlyWalMode);
+  const archived = {
+    ...migration,
+    sourceArchive: {
+      databaseModeBefore: sourceMode,
+      databaseModeAfter: readOnlyMode,
+      ...(sourceWalMode === undefined ? {} : { walModeBefore: sourceWalMode, walModeAfter: readOnlyWalMode }),
+      state: 'read_only' as const,
+    },
+  };
+  writeControlPlaneRecord(preview.destinationHome, {
+    namespace: MIGRATION_NAMESPACE,
+    scope: MIGRATION_SCOPE,
+    key: migrationId,
+    schemaVersion: 1,
+    value: archived,
+    action: 'controller_home_migration_archive_source',
+    expectedRevision: 1,
+  });
+  const path = reportPath(preview.destinationHome, migrationId);
+  writeReport(path, { preview, migration: archived });
+  return { preview, migration: archived, reportPath: path };
+}
+
+export function rollbackControllerHomeMigration(input: {
+  destinationHome: string;
+  migrationId: string;
+}): ControllerHomeMigrationRecord {
+  const destinationHome = resolve(input.destinationHome);
+  const current = readControlPlaneRecord<ControllerHomeMigrationRecord>(
+    destinationHome,
+    MIGRATION_NAMESPACE,
+    MIGRATION_SCOPE,
+    input.migrationId,
+  );
+  if (!current) throw new Error(`CONTROLLER_HOME_MIGRATION_NOT_FOUND: ${input.migrationId}`);
+  if (current.value.status === 'rolled_back') return current.value;
+
+  const rolledBack = withControlPlaneTransaction(destinationHome, (database) => {
+    for (const imported of current.value.imported) {
+      const record = readControlPlaneRecordWithinTransaction<unknown>(database, imported.namespace, imported.scope, imported.key);
+      if (!record || record.revision !== imported.destinationRevision) {
+        throw new Error(`CONTROLLER_HOME_MIGRATION_ROLLBACK_CONFLICT: ${imported.namespace}/${imported.scope}/${imported.key}`);
+      }
+      database.prepare(`
+        DELETE FROM control_plane_audit
+        WHERE namespace = ? AND scope = ? AND record_key = ?
+      `).run(imported.namespace, imported.scope, imported.key);
+      database.prepare(`
+        DELETE FROM control_plane_records
+        WHERE namespace = ? AND scope = ? AND record_key = ?
+      `).run(imported.namespace, imported.scope, imported.key);
+    }
+    const value: ControllerHomeMigrationRecord = {
+      ...current.value,
+      status: 'rolled_back',
+      sourceArchive: {
+        ...current.value.sourceArchive,
+        state: 'restored',
+      },
+      rolledBackAt: new Date().toISOString(),
+    };
+    writeControlPlaneRecordWithinTransaction(database, {
+      namespace: MIGRATION_NAMESPACE,
+      scope: MIGRATION_SCOPE,
+      key: current.value.migrationId,
+      schemaVersion: CONTROL_PLANE_SCHEMA_VERSION,
+      value,
+      action: 'controller_home_migration_rolled_back',
+      expectedRevision: current.revision,
+    });
+    return value;
+  });
+  chmodSync(rolledBack.sourceDatabase.path, rolledBack.sourceArchive.databaseModeBefore);
+  if (rolledBack.sourceDatabase.walPath && rolledBack.sourceArchive.walModeBefore !== undefined) {
+    chmodSync(rolledBack.sourceDatabase.walPath, rolledBack.sourceArchive.walModeBefore);
+  }
+  writeReport(reportPath(destinationHome, rolledBack.migrationId), { migration: rolledBack });
+  return rolledBack;
+}

package/src/runtime/control-plane/persistence/sqlite-store.ts

@@ -207,6 +207,37 @@ function openDatabase(controllerHome: string): SqliteDatabase {
   }
 }
 
+/**
+ * Open an already initialized authority for SELECT-only callers without
+ * re-running WAL/schema setup. In WAL mode a reader can coexist with a writer
+ * holding BEGIN IMMEDIATE; forcing PRAGMA journal_mode/DDL on every read turns
+ * that harmless writer reservation into a synchronous busy_timeout on the
+ * Canonical Runtime event loop.
+ */
+function openDatabaseForRead(controllerHome: string): SqliteDatabase {
+  const path = controlPlaneDatabasePath(controllerHome);
+  if (!existsSync(path)) return openDatabase(controllerHome);
+
+  const database = openRawDatabase(path);
+  try {
+    database.exec('PRAGMA busy_timeout = 5000; PRAGMA foreign_keys = ON;');
+    const schemaVersion = assertSupportedSchema(database, path);
+    if (schemaVersion !== undefined) return database;
+  } catch (error) {
+    database.close();
+    const busy = sqliteBusyError(path, error);
+    if (busy) throw busy;
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.startsWith('CONTROL_PLANE_')) throw error;
+    throw new Error(`CONTROL_PLANE_SQLITE_CORRUPT: ${path}: ${message}`);
+  }
+
+  // Preserve first-use/partially initialized compatibility: only a database
+  // with no schema authority falls back to the initializer/writer path.
+  database.close();
+  return openDatabase(controllerHome);
+}
+
 function rowToRecord<T>(row: StoredRecordRow): ControlPlaneRecord<T> {
   let value: T;
   try {
@@ -321,7 +352,7 @@ export function withControlPlaneTransaction<T>(controllerHome: string, operation
 }
 
 export function readControlPlaneRecord<T>(controllerHome: string, namespace: string, scope: string, key: string): ControlPlaneRecord<T> | undefined {
-  const database = openDatabase(controllerHome);
+  const database = openDatabaseForRead(controllerHome);
   try {
     return selectRecord<T>(database, namespace, scope, key);
   } finally {
@@ -361,7 +392,7 @@ export function listControlPlaneRecords<T>(
   controllerHome: string,
   input: { namespace: string; scope?: string; limit?: number },
 ): ControlPlaneRecord<T>[] {
-  const database = openDatabase(controllerHome);
+  const database = openDatabaseForRead(controllerHome);
   try {
     const limit = Math.max(1, Math.min(Math.trunc(input.limit ?? 1000), 5000));
     const rows = input.scope === undefined

package/src/runtime/control-plane/release-retention.ts

@@ -106,6 +106,60 @@ function releasePathFromAuthorityRecord(
   return canonical(releasePath);
 }
 
+function loadPackageConnectorReleaseProtection(controllerHome: string, releasesRoot: string): string | undefined {
+  const connectorRoot = join(controllerHome, 'runtime', 'connector-service');
+  if (!existsSync(connectorRoot)) return undefined;
+  const authorityPath = join(connectorRoot, 'authority.json');
+  if (!existsSync(authorityPath)) throw new Error('package connector release authority is missing');
+
+  const parsed = JSON.parse(readFileSync(authorityPath, 'utf8')) as Record<string, unknown>;
+  const releaseId = typeof parsed.releaseId === 'string' ? parsed.releaseId.trim() : '';
+  const releaseRootValue = typeof parsed.releaseRoot === 'string' ? parsed.releaseRoot.trim() : '';
+  const packageRoot = typeof parsed.packageRoot === 'string' ? parsed.packageRoot.trim() : '';
+  const endpoint = typeof parsed.endpoint === 'string' ? parsed.endpoint.trim() : '';
+  if (parsed.schemaVersion !== 1 || !releaseId || !releaseRootValue || !packageRoot || !endpoint) {
+    throw new Error('package connector release authority is invalid');
+  }
+  const releaseRoot = resolve(releaseRootValue);
+  if (basename(releaseRoot) !== releaseId || !directChild(releasesRoot, releaseRoot) || !existsSync(releaseRoot)) {
+    throw new Error('package connector release is outside runtime release authority or missing');
+  }
+  return canonical(releaseRoot);
+}
+
+function loadRecoveryKnownGoodReleaseProtection(controllerHome: string, releasesRoot: string): Set<string> {
+  const knownGoodPath = join(controllerHome, 'recovery', 'state', 'known-good.json');
+  const protectedPaths = new Set<string>();
+  if (!existsSync(knownGoodPath)) return protectedPaths;
+  const parsed = JSON.parse(readFileSync(knownGoodPath, 'utf8')) as Record<string, unknown>;
+  if (parsed.schemaVersion !== 1 || !Array.isArray(parsed.releases)) {
+    throw new Error('standalone recovery known-good authority is invalid');
+  }
+  for (const raw of parsed.releases) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('standalone recovery known-good release record is invalid');
+    const record = raw as Record<string, unknown>;
+    const releaseId = typeof record.revision === 'string' ? record.revision.trim() : '';
+    const manifestPathValue = typeof record.path === 'string' ? record.path.trim() : '';
+    if (!releaseId || !manifestPathValue) throw new Error('standalone recovery known-good release identity is incomplete');
+    const manifestPath = resolve(manifestPathValue);
+    const releaseRoot = dirname(manifestPath);
+    if (
+      basename(manifestPath) !== 'manifest.json'
+      || basename(releaseRoot) !== releaseId
+      || !directChild(releasesRoot, releaseRoot)
+    ) {
+      throw new Error('standalone recovery known-good release is outside runtime releases');
+    }
+    // Known-good history is append-only recovery evidence. A historical record
+    // may legitimately outlive the retained release directory after a bounded
+    // cleanup pass. Missing historical artifacts therefore protect nothing and
+    // must not disable retention for the remaining authoritative releases.
+    if (!existsSync(manifestPath) || !existsSync(releaseRoot)) continue;
+    protectedPaths.add(canonical(releaseRoot));
+  }
+  return protectedPaths;
+}
+
 function loadRuntimeProtection(controllerHome: string): RuntimeProtection | undefined {
   const releasesRoot = join(controllerHome, 'runtime', 'releases');
   if (!existsSync(releasesRoot)) return undefined;
@@ -124,6 +178,11 @@ function loadRuntimeProtection(controllerHome: string): RuntimeProtection | unde
   if (previous !== undefined) {
     releasePaths.add(releasePathFromAuthorityRecord(releasesRoot, previous, 'previous'));
   }
+  const connectorRelease = loadPackageConnectorReleaseProtection(controllerHome, releasesRoot);
+  if (connectorRelease) releasePaths.add(connectorRelease);
+  for (const knownGoodRelease of loadRecoveryKnownGoodReleaseProtection(controllerHome, releasesRoot)) {
+    releasePaths.add(knownGoodRelease);
+  }
 
   const backupPaths = new Set<string>();
   let backupAuthoritySafe = true;
@@ -409,8 +468,9 @@ function scanLinkedReleaseFamily(
 /**
  * Reclaim immutable Controller release history while preserving the exact
  * rollback authorities. Runtime keeps active + previous + the previous DB
- * backup; Recovery/Supervisor keep current + previous. Missing or malformed
- * authority always fails closed.
+ * backup plus the immutable release backing the persistent public MCP Gateway;
+ * Recovery/Supervisor keep current + previous. Missing or malformed authority
+ * always fails closed.
  */
 export function cleanupControllerReleaseHistory(
   controllerHome: string,