@cleocode/core 2026.4.11 → 2026.4.12

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/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' };
   }
 }
 

package/src/tasks/__tests__/error-hints.test.ts

@@ -0,0 +1,256 @@
+/**
+ * Regression tests: CleoError fix hints on task-layer throws.
+ *
+ * Each test invokes a core function with invalid input and asserts that
+ * the thrown CleoError carries:
+ *   - options.fix   — a non-empty string with a concrete recovery action
+ *   - options.details.field — the specific field that failed
+ *
+ * @task T341
+ * @epic T335
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { CleoError } from '../../errors.js';
+import { createTestDb, type TestDbEnv } from '../../store/__tests__/test-db-helper.js';
+import { resetDbState } from '../../store/sqlite.js';
+import {
+  addTask,
+  validateDepends,
+  validateLabels,
+  validatePhaseFormat,
+  validateSize,
+  validateStatus,
+  validateTaskType,
+  validateTitle,
+} from '../add.js';
+import { findTasks } from '../find.js';
+import { showLabelTasks } from '../labels.js';
+import { showTask } from '../show.js';
+
+// ---------------------------------------------------------------------------
+// Helper: assert a CleoError has fix + details
+// ---------------------------------------------------------------------------
+
+function assertErrorHints(
+  fn: () => unknown,
+  opts: { fixIncludes?: string; detailsField?: string },
+): void {
+  let caught: unknown;
+  try {
+    fn();
+  } catch (err) {
+    caught = err;
+  }
+  expect(caught).toBeInstanceOf(CleoError);
+  const e = caught as CleoError;
+  expect(e.fix).toBeTruthy();
+  if (opts.fixIncludes) {
+    expect(e.fix).toContain(opts.fixIncludes);
+  }
+  if (opts.detailsField) {
+    expect(e.details).toBeDefined();
+    expect(e.details!.field).toBe(opts.detailsField);
+  }
+}
+
+async function assertAsyncErrorHints(
+  fn: () => Promise<unknown>,
+  opts: { fixIncludes?: string; detailsField?: string },
+): Promise<void> {
+  let caught: unknown;
+  try {
+    await fn();
+  } catch (err) {
+    caught = err;
+  }
+  expect(caught).toBeInstanceOf(CleoError);
+  const e = caught as CleoError;
+  expect(e.fix).toBeTruthy();
+  if (opts.fixIncludes) {
+    expect(e.fix).toContain(opts.fixIncludes);
+  }
+  if (opts.detailsField) {
+    expect(e.details).toBeDefined();
+    expect(e.details!.field).toBe(opts.detailsField);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('error-hints: validateTitle', () => {
+  it('empty title — fix mentions cleo add, field=title', () => {
+    assertErrorHints(() => validateTitle(''), {
+      fixIncludes: 'cleo add',
+      detailsField: 'title',
+    });
+  });
+
+  it('whitespace-only title — fix mentions cleo add, field=title', () => {
+    assertErrorHints(() => validateTitle('   '), {
+      fixIncludes: 'cleo add',
+      detailsField: 'title',
+    });
+  });
+
+  it('title too long — fix mentions 200, field=title, details has expected/actual', () => {
+    let caught: unknown;
+    try {
+      validateTitle('a'.repeat(201));
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(CleoError);
+    const e = caught as CleoError;
+    expect(e.fix).toContain('200');
+    expect(e.details).toBeDefined();
+    expect(e.details!.field).toBe('title');
+    expect(e.details!.expected).toBe(200);
+    expect(e.details!.actual).toBe(201);
+  });
+});
+
+describe('error-hints: validateStatus', () => {
+  it('invalid status — fix mentions --status, field=status', () => {
+    assertErrorHints(() => validateStatus('broken'), {
+      fixIncludes: '--status',
+      detailsField: 'status',
+    });
+  });
+});
+
+describe('error-hints: validateSize', () => {
+  it('invalid size — fix mentions --size, field=size', () => {
+    assertErrorHints(() => validateSize('giant'), {
+      fixIncludes: '--size',
+      detailsField: 'size',
+    });
+  });
+});
+
+describe('error-hints: validateTaskType', () => {
+  it('invalid type — fix mentions --type, field=type', () => {
+    assertErrorHints(() => validateTaskType('mega-task'), {
+      fixIncludes: '--type',
+      detailsField: 'type',
+    });
+  });
+});
+
+describe('error-hints: validateLabels', () => {
+  it('invalid label — fix mentions pattern, field=labels', () => {
+    assertErrorHints(() => validateLabels(['UPPERCASE']), {
+      fixIncludes: '^[a-z]',
+      detailsField: 'labels',
+    });
+  });
+});
+
+describe('error-hints: validatePhaseFormat', () => {
+  it('invalid phase — fix mentions pattern, field=phase', () => {
+    assertErrorHints(() => validatePhaseFormat('UPPER_CASE'), {
+      fixIncludes: '^[a-z]',
+      detailsField: 'phase',
+    });
+  });
+});
+
+describe('error-hints: validateDepends (sync helper)', () => {
+  it('invalid dep ID format — fix mentions T### format, field=depends', () => {
+    assertErrorHints(() => validateDepends(['invalid'], []), {
+      fixIncludes: 'T###',
+      detailsField: 'depends',
+    });
+  });
+
+  it('dep not found — fix mentions cleo find, field=depends', () => {
+    assertErrorHints(() => validateDepends(['T999'], []), {
+      fixIncludes: 'find',
+      detailsField: 'depends',
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Anti-hallucination throw (add.ts line ~436)
+// ---------------------------------------------------------------------------
+
+describe('error-hints: anti-hallucination (title === description)', () => {
+  let env: TestDbEnv;
+
+  beforeEach(async () => {
+    resetDbState();
+    env = await createTestDb();
+  });
+
+  afterEach(async () => {
+    await env.cleanup();
+  });
+
+  it('throws with fix mentioning --desc, field=description', async () => {
+    await assertAsyncErrorHints(
+      () =>
+        addTask(
+          {
+            title: 'same text',
+            description: 'same text',
+          },
+          env.tempDir,
+          env.accessor,
+        ),
+      { fixIncludes: '--desc', detailsField: 'description' },
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// findTasks — query required
+// ---------------------------------------------------------------------------
+
+describe('error-hints: findTasks (query required)', () => {
+  it('missing query — fix mentions cleo find, field=query', async () => {
+    await assertAsyncErrorHints(() => findTasks({}), {
+      fixIncludes: 'cleo find',
+      detailsField: 'query',
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// showTask — task ID required
+// ---------------------------------------------------------------------------
+
+describe('error-hints: showTask (id required)', () => {
+  it('empty id — fix mentions cleo show, field=taskId', async () => {
+    await assertAsyncErrorHints(() => showTask(''), {
+      fixIncludes: 'cleo show',
+      detailsField: 'taskId',
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// showLabelTasks — no tasks with label
+// ---------------------------------------------------------------------------
+
+describe('error-hints: showLabelTasks (label not found)', () => {
+  let env: TestDbEnv;
+
+  beforeEach(async () => {
+    resetDbState();
+    env = await createTestDb();
+  });
+
+  afterEach(async () => {
+    await env.cleanup();
+  });
+
+  it('no tasks with label — fix mentions cleo labels, field=label', async () => {
+    await assertAsyncErrorHints(
+      () => showLabelTasks('nonexistent-label', env.tempDir, env.accessor),
+      { fixIncludes: 'cleo labels', detailsField: 'label' },
+    );
+  });
+});