@cleocode/core 2026.4.11 → 2026.4.13

package/src/store/sqlite-backup.ts

@@ -2,22 +2,36 @@
  * SQLite backup via VACUUM INTO with snapshot rotation.
  *
  * Produces self-contained, WAL-free copies of CLEO SQLite databases
- * (tasks.db, brain.db at project tier; nexus.db at global tier) into
- * `.cleo/backups/sqlite/` (project) or `$XDG_DATA_HOME/cleo/backups/sqlite/`
- * (global) with a configurable rotation limit. All errors are swallowed —
- * backup failure must never interrupt normal operation.
+ * (tasks.db, brain.db, conduit.db at project tier; nexus.db, signaldock.db at
+ * global tier) into `.cleo/backups/sqlite/` (project) or
+ * `$XDG_DATA_HOME/cleo/backups/sqlite/` (global) with a configurable rotation
+ * limit. Also provides raw-file backup for the global-salt binary (not SQLite).
+ * All errors are swallowed — backup failure must never interrupt normal operation.
  *
  * @task T4873
  * @task T5158 — extended to cover brain.db
  * @task T306  — extended to cover global-tier nexus.db (epic T299)
+ * @task T369  — extended to cover conduit.db (project), signaldock.db (global),
+ *               and global-salt raw-file backup (epic T310)
  * @epic T4867
  */
 
-import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  statSync,
+  unlinkSync,
+} from 'node:fs';
 import { join } from 'node:path';
 import { getCleoDir, getCleoHome } from '../paths.js';
 import { getBrainNativeDb } from './brain-sqlite.js';
+import { getConduitNativeDb } from './conduit-sqlite.js';
+import { getGlobalSaltPath } from './global-salt.js';
 import { getNexusNativeDb } from './nexus-sqlite.js';
+import { getGlobalSignaldockNativeDb } from './signaldock-sqlite.js';
 import { getNativeDb } from './sqlite.js';
 
 /** Maximum number of snapshots retained per database (oldest rotated out). */
@@ -46,11 +60,16 @@ interface SnapshotTarget {
 
 /**
  * Canonical list of snapshot targets. Ordering is insertion order — tasks.db
- * snapshots first (highest-value operational state), then brain.db.
+ * snapshots first (highest-value operational state), then brain.db, then
+ * conduit.db (project messaging state).
+ *
+ * @task T369
+ * @epic T310
  */
 const SNAPSHOT_TARGETS: SnapshotTarget[] = [
   { prefix: 'tasks', getDb: getNativeDb },
   { prefix: 'brain', getDb: getBrainNativeDb },
+  { prefix: 'conduit', getDb: getConduitNativeDb }, // Added T369 — project messaging DB
 ];
 
 /**
@@ -308,10 +327,16 @@ export function listSqliteBackupsAll(
 export type BackupScope = 'project' | 'global';
 
 /**
- * Registered global-tier snapshot targets. `signaldock` is reserved for T310
- * — only `nexus` is active in v2026.4.11.
+ * Registered global-tier snapshot targets. Both `nexus` and `signaldock` are
+ * active as of T369 (epic T310).
+ *
+ * @task T369
+ * @epic T310
  */
-const GLOBAL_SNAPSHOT_TARGETS: SnapshotTarget[] = [{ prefix: 'nexus', getDb: getNexusNativeDb }];
+const GLOBAL_SNAPSHOT_TARGETS: SnapshotTarget[] = [
+  { prefix: 'nexus', getDb: getNexusNativeDb },
+  { prefix: 'signaldock', getDb: getGlobalSignaldockNativeDb }, // Activated T369 — global agent registry
+];
 
 /**
  * Resolve the global-tier backup directory, creating it on first use.
@@ -333,12 +358,13 @@ function resolveGlobalBackupDir(cleoHomeOverride?: string): string {
  * Non-fatal: errors from any individual step are surfaced via the return value
  * but never thrown — a failed snapshot MUST NOT interrupt normal operation.
  *
- * @param dbName         - Which global-tier DB to snapshot (`'nexus'`; `'signaldock'` reserved for T310)
+ * @param dbName         - Which global-tier DB to snapshot (`'nexus'` or `'signaldock'`)
  * @param opts.rotation  - Maximum retained snapshots per prefix (default 10)
  * @param opts.cleoHomeOverride - Override `getCleoHome()` path (use in tests to target a tmp dir)
  * @returns Object containing the new snapshot path and any rotated (deleted) file paths
  *
  * @task T306
+ * @task T369 — activated signaldock target (epic T310)
  * @epic T299
  * @why ADR-036 §Backup Mechanism requires VACUUM INTO rotation at the global tier;
  *      nexus.db has zero backup coverage prior to v2026.4.11.
@@ -453,3 +479,152 @@ export function listGlobalSqliteBackups(
     return [];
   }
 }
+
+// ============================================================================
+// Global-salt raw-file backup (ADR-037 §5)
+// @task T369
+// @epic T310
+// ============================================================================
+
+/** Filename prefix for global-salt backup files. */
+const GLOBAL_SALT_BACKUP_PREFIX = 'global-salt';
+
+/** Regex matching global-salt backup filenames: `global-salt-YYYYMMDD-HHmmss`. */
+const GLOBAL_SALT_BACKUP_PATTERN = /^global-salt-\d{8}-\d{6}$/;
+
+/**
+ * Resolve the backup directory for global-salt files: `{cleoHome}/backups/`.
+ * Global-salt backups live directly under `backups/` (not `backups/sqlite/`)
+ * to make clear they are binary files, not SQLite databases.
+ */
+function resolveGlobalSaltBackupDir(cleoHomeOverride?: string): string {
+  const base = cleoHomeOverride ?? getCleoHome();
+  return join(base, 'backups');
+}
+
+/**
+ * Rotate global-salt backup files: delete the oldest until fewer than
+ * {@link MAX_SNAPSHOTS} remain. Returns the paths of deleted files.
+ * Non-fatal on any filesystem error.
+ */
+function rotateGlobalSaltBackups(backupDir: string): string[] {
+  const rotated: string[] = [];
+  try {
+    const files = readdirSync(backupDir)
+      .filter((f) => GLOBAL_SALT_BACKUP_PATTERN.test(f))
+      .map((f) => ({
+        name: f,
+        path: join(backupDir, f),
+        mtimeMs: statSync(join(backupDir, f)).mtimeMs,
+      }))
+      .sort((a, b) => a.mtimeMs - b.mtimeMs); // oldest first
+
+    while (files.length >= MAX_SNAPSHOTS) {
+      const oldest = files.shift();
+      if (!oldest) break;
+      try {
+        unlinkSync(oldest.path);
+        rotated.push(oldest.path);
+      } catch {
+        // non-fatal rotation failure
+      }
+    }
+  } catch {
+    // non-fatal
+  }
+  return rotated;
+}
+
+/**
+ * Creates a raw-file backup of the global-salt binary at
+ * `${getCleoHome()}/backups/global-salt-YYYYMMDD-HHmmss` with `0o600`
+ * permissions. Rotates to {@link MAX_SNAPSHOTS} (10) copies, deleting the
+ * oldest when the limit is reached.
+ *
+ * Non-fatal: errors are swallowed — salt backup failure must never block cleo.
+ * Returns empty strings and no rotated paths on failure.
+ *
+ * @param opts.cleoHomeOverride - Override `getCleoHome()` path (use in tests to target a tmp dir)
+ * @returns Object with the new snapshot path and any rotated (deleted) file paths
+ *
+ * @task T369
+ * @epic T310
+ * @why ADR-037 §5 — global-salt is security-critical; losing it invalidates
+ *      all API keys. Backup enables recovery from accidental deletion.
+ */
+export async function backupGlobalSalt(opts?: {
+  cleoHomeOverride?: string;
+}): Promise<{ snapshotPath: string; rotated: string[] }> {
+  try {
+    const cleoHome = opts?.cleoHomeOverride ?? getCleoHome();
+    const saltSourcePath = opts?.cleoHomeOverride
+      ? join(cleoHome, 'global-salt')
+      : getGlobalSaltPath();
+
+    if (!existsSync(saltSourcePath)) {
+      return { snapshotPath: '', rotated: [] };
+    }
+
+    const backupDir = resolveGlobalSaltBackupDir(opts?.cleoHomeOverride);
+    mkdirSync(backupDir, { recursive: true });
+
+    const rotated = rotateGlobalSaltBackups(backupDir);
+
+    const snapshotName = `${GLOBAL_SALT_BACKUP_PREFIX}-${formatTimestamp(new Date())}`;
+    const snapshotPath = join(backupDir, snapshotName);
+
+    copyFileSync(saltSourcePath, snapshotPath);
+    chmodSync(snapshotPath, 0o600);
+
+    return { snapshotPath, rotated };
+  } catch {
+    // non-fatal — backup failure must never interrupt normal operation
+    return { snapshotPath: '', rotated: [] };
+  }
+}
+
+/**
+ * A single entry returned by {@link listGlobalSaltBackups}.
+ *
+ * @task T369
+ * @epic T310
+ */
+export interface GlobalSaltBackupEntry {
+  /** Backup filename, e.g. `global-salt-20260408-143022`. */
+  name: string;
+  /** Absolute path to the backup file. */
+  path: string;
+  /** File size in bytes (should be 32 for a valid global-salt). */
+  size: number;
+  /** Last-modified timestamp. */
+  mtime: Date;
+}
+
+/**
+ * List global-salt backup files from `$XDG_DATA_HOME/cleo/backups/`, sorted
+ * newest-first by mtime.
+ *
+ * Returns an empty array when the backup directory does not exist.
+ *
+ * @param cleoHomeOverride - Override `getCleoHome()` path (use in tests to target a tmp dir)
+ *
+ * @task T369
+ * @epic T310
+ */
+export function listGlobalSaltBackups(cleoHomeOverride?: string): GlobalSaltBackupEntry[] {
+  try {
+    const backupDir = resolveGlobalSaltBackupDir(cleoHomeOverride);
+    if (!existsSync(backupDir)) return [];
+
+    return readdirSync(backupDir)
+      .filter((f) => GLOBAL_SALT_BACKUP_PATTERN.test(f))
+      .map((f) => {
+        const filePath = join(backupDir, f);
+        const s = statSync(filePath);
+        return { name: f, path: filePath, size: s.size, mtime: new Date(s.mtimeMs) };
+      })
+      .sort((a, b) => b.mtime.getTime() - a.mtime.getTime()); // newest first
+  } catch {
+    return [];
+  }
+}

package/src/store/t310-readiness.ts

@@ -0,0 +1,119 @@
+/**
+ * T310-readiness gate: detect conduit.db vs legacy signaldock.db at project tier.
+ *
+ * T311 backup/restore code paths reference `.cleo/conduit.db` (project tier) and
+ * `$XDG_DATA_HOME/cleo/signaldock.db` (global tier) per ADR-037. A project that
+ * has not yet been migrated (still has `.cleo/signaldock.db` without a
+ * `.cleo/conduit.db`) will confuse T311 export/import commands. This gate runs
+ * as a precondition on every T311 CLI verb.
+ *
+ * @task T342
+ * @epic T311
+ * @why T311 export/import references .cleo/conduit.db (project tier) and
+ *      $XDG_DATA_HOME/cleo/signaldock.db (global tier) per ADR-037.
+ *      If the current project is still on the pre-T310 topology, T311
+ *      commands must surface a clear error telling the user to run a
+ *      cleo command first to trigger migration.
+ * @what Throws T310MigrationRequiredError with instructions if legacy
+ *       signaldock.db exists AND conduit.db does not.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getProjectRoot } from '../paths.js';
+
+// ---------------------------------------------------------------------------
+// Error class
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown by `assertT310Ready` when the current project is still on the
+ * pre-T310 topology: `.cleo/signaldock.db` is present but `.cleo/conduit.db`
+ * is absent. T311 commands cannot proceed until migration has run.
+ *
+ * @task T342
+ * @epic T311
+ */
+export class T310MigrationRequiredError extends Error {
+  /**
+   * @param projectRoot - Absolute path to the project root that needs migration.
+   */
+  constructor(public readonly projectRoot: string) {
+    super(
+      `T310 migration required: .cleo/signaldock.db still exists at ${projectRoot} ` +
+        `without a .cleo/conduit.db. Run any cleo command from within the project ` +
+        `(e.g. \`cleo version\`) to trigger the automatic T310 migration, then retry.`,
+    );
+    this.name = 'T310MigrationRequiredError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Asserts the current project is on the post-T310 topology. Does nothing
+ * if conduit.db exists (migration already ran) OR if no legacy signaldock.db
+ * exists (fresh install — no migration needed).
+ *
+ * Throws when legacy signaldock.db is present AND conduit.db is absent,
+ * which indicates the project has not yet been migrated to the T310 topology
+ * expected by T311 backup/restore commands.
+ *
+ * @param projectRoot - Absolute path to the project root. Defaults to
+ *   `getProjectRoot()` (walks ancestors for `.cleo/` sentinel).
+ * @throws {T310MigrationRequiredError} if legacy signaldock.db exists
+ *   without conduit.db at the project tier.
+ *
+ * @task T342
+ * @epic T311
+ *
+ * @example
+ * ```typescript
+ * // Precondition guard at the top of every T311 CLI verb handler:
+ * assertT310Ready();
+ * ```
+ */
+export function assertT310Ready(projectRoot?: string): void {
+  const root = projectRoot ?? getProjectRoot();
+  const legacyPath = join(root, '.cleo', 'signaldock.db');
+  const conduitPath = join(root, '.cleo', 'conduit.db');
+
+  if (existsSync(legacyPath) && !existsSync(conduitPath)) {
+    throw new T310MigrationRequiredError(root);
+  }
+}
+
+/**
+ * Returns true if T311 commands can safely run on the current project.
+ *
+ * This is the non-throwing companion to `assertT310Ready`. Returns false
+ * only when the pre-T310 topology is detected (legacy signaldock.db exists
+ * without conduit.db). All other states — fresh installs, fully-migrated
+ * projects — return true.
+ *
+ * @param projectRoot - Absolute path to the project root. Defaults to
+ *   `getProjectRoot()` (walks ancestors for `.cleo/` sentinel).
+ * @returns `true` if the project is on the post-T310 topology or is a fresh
+ *   install; `false` if migration is required.
+ *
+ * @task T342
+ * @epic T311
+ *
+ * @example
+ * ```typescript
+ * if (!isT310Ready()) {
+ *   console.error('Run `cleo version` to trigger T310 migration first.');
+ * }
+ * ```
+ */
+export function isT310Ready(projectRoot?: string): boolean {
+  try {
+    assertT310Ready(projectRoot);
+    return true;
+  } catch (err) {
+    if (err instanceof T310MigrationRequiredError) return false;
+    throw err;
+  }
+}

package/src/system/backup.ts

@@ -22,7 +22,6 @@
  *
  * @task T4783
  * @task T5158 — extended to use VACUUM INTO for .db files and atomicWrite for JSON
- * @task T306  — extended to support global-tier scope (nexus.db; epic T299)
  */
 
 import {
@@ -87,15 +86,6 @@ export interface BackupResult {
   type: string;
   /** Files that were successfully captured into this backup. */
   files: string[];
-  /**
-   * Global-tier snapshot results, populated when `opts.includeGlobal` is true.
-   * Key is the DB name (e.g. `'nexus'`), value is the snapshot path or an
-   * empty string when the DB was not initialized.
-   *
-   * @task T306
-   * @epic T299
-   */
-  global?: Record<string, string>;
 }
 
 /** Result shape returned by {@link restoreBackup}. */
@@ -122,31 +112,12 @@ export interface RestoreResult {
  * when `safeSqliteSnapshot` asks for them. This makes the function
  * self-contained — callers do not need to pre-open the DBs.
  *
- * When `opts.includeGlobal` is true, also snapshots global-tier databases
- * (currently `nexus.db`) via {@link vacuumIntoGlobalBackup}. Global snapshots
- * are written to `$XDG_DATA_HOME/cleo/backups/sqlite/` and returned in
- * `result.global`.
- *
  * Async because opening the database engines requires async migration
  * reconciliation (ADR-012). The CLI dispatch layer awaits this result.
- *
- * @task T306
- * @epic T299
  */
 export async function createBackup(
   projectRoot: string,
-  opts?: {
-    type?: string;
-    note?: string;
-    /**
-     * When true, also snapshot global-tier databases (nexus.db).
-     * Defaults to false for backwards compatibility.
-     *
-     * @task T306
-     * @epic T299
-     */
-    includeGlobal?: boolean;
-  },
+  opts?: { type?: string; note?: string },
 ): Promise<BackupResult> {
   const cleoDir = join(projectRoot, '.cleo');
   const btype = opts?.type || 'snapshot';
@@ -241,38 +212,7 @@ export async function createBackup(
     // non-fatal
   }
 
-  // Global-tier backup (nexus.db) — only when explicitly requested.
-  // @task T306 @epic T299
-  const globalResults: Record<string, string> = {};
-  if (opts?.includeGlobal) {
-    // Ensure nexus.db is initialized so its native handle is available.
-    try {
-      const { getNexusDb } = await import('../store/nexus-sqlite.js');
-      await getNexusDb();
-    } catch {
-      // nexus.db open failed — vacuumIntoGlobalBackup will return empty path
-    }
-    try {
-      const { vacuumIntoGlobalBackup } = await import('../store/sqlite-backup.js');
-      const nexusResult = await vacuumIntoGlobalBackup('nexus');
-      globalResults['nexus'] = nexusResult.snapshotPath;
-    } catch {
-      // non-fatal — global backup failure must not block project backup
-      globalResults['nexus'] = '';
-    }
-  }
-
-  const result: BackupResult = {
-    backupId,
-    path: backupDir,
-    timestamp,
-    type: btype,
-    files: backedUp,
-  };
-  if (opts?.includeGlobal) {
-    result.global = globalResults;
-  }
-  return result;
+  return { backupId, path: backupDir, timestamp, type: btype, files: backedUp };
 }
 
 /** A single backup entry returned by listSystemBackups. */

package/src/system/runtime.ts

@@ -35,8 +35,6 @@ export interface RuntimeDiagnostics {
   };
   naming: {
     cli: string;
-    /** Legacy field. CLI dispatch only. */
-    mcp: string;
     server: string;
   };
   node: string;
@@ -73,14 +71,14 @@ function detectFromDataRoot(dataRoot: string): RuntimeChannel | null {
   return null;
 }
 
-function getExpectedNaming(channel: RuntimeChannel): { cli: string; mcp: string; server: string } {
+function getExpectedNaming(channel: RuntimeChannel): { cli: string; server: string } {
   switch (channel) {
     case 'dev':
-      return { cli: 'cleo-dev', mcp: 'cli', server: 'cleo-dev' };
+      return { cli: 'cleo-dev', server: 'cleo-dev' };
     case 'beta':
-      return { cli: 'cleo-beta', mcp: 'cli', server: 'cleo-beta' };
+      return { cli: 'cleo-beta', server: 'cleo-beta' };
     default:
-      return { cli: 'cleo', mcp: 'cli', server: 'cleo' };
+      return { cli: 'cleo', server: 'cleo' };
   }
 }