@cleocode/core 2026.3.74 → 2026.4.0

package/src/store/signaldock-sqlite.ts

@@ -0,0 +1,429 @@
+/**
+ * SQLite store for signaldock.db — local agent messaging database.
+ *
+ * Creates and manages .cleo/signaldock.db using node:sqlite directly.
+ * Runs the consolidated Diesel migration SQL (from signaldock-storage crate)
+ * to bootstrap all 22 tables for local agent infrastructure.
+ *
+ * This is the Node.js bootstrap path. In production cloud, the Rust
+ * signaldock-storage crate manages this DB via Diesel ORM directly.
+ * Locally, we create the DB here so that cleo init scaffolds the full
+ * .cleo/ directory with all databases ready.
+ *
+ * @task T223
+ */
+
+import { existsSync, mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import type { DatabaseSync } from 'node:sqlite';
+import { getCleoDirAbsolute } from '../paths.js';
+
+const _require = createRequire(import.meta.url);
+const { DatabaseSync: DatabaseSyncClass } = _require('node:sqlite') as {
+  DatabaseSync: new (...args: ConstructorParameters<typeof DatabaseSync>) => DatabaseSync;
+};
+
+/** Database file name within .cleo/ directory. */
+const DB_FILENAME = 'signaldock.db';
+
+/** Schema version for signaldock databases. */
+export const SIGNALDOCK_SCHEMA_VERSION = '2026.3.76';
+
+/**
+ * Get the path to the signaldock.db SQLite database file.
+ */
+export function getSignaldockDbPath(cwd?: string): string {
+  const cleoDir = cwd ? join(cwd, '.cleo') : getCleoDirAbsolute();
+  return join(cleoDir, DB_FILENAME);
+}
+
+// ---------------------------------------------------------------------------
+// Embedded migration SQL — bundled so signaldock.db works in ANY project,
+// not just the monorepo where crates/signaldock-storage/ exists.
+// Source: crates/signaldock-storage/migrations/
+// ---------------------------------------------------------------------------
+
+/**
+ * Ordered migration entries. Each has a name (for tracking) and SQL.
+ * Add new migrations to the END of this array.
+ */
+const EMBEDDED_MIGRATIONS: Array<{ name: string; sql: string }> = [
+  {
+    name: '2026-03-28-000000_initial',
+    sql: `-- Consolidated initial migration for SignalDock storage (19 sqlx migrations merged).
+CREATE TABLE IF NOT EXISTS users (
+    id TEXT PRIMARY KEY, email TEXT NOT NULL UNIQUE, password_hash TEXT NOT NULL,
+    name TEXT, slug TEXT, default_agent_id TEXT, username TEXT, display_username TEXT,
+    email_verified INTEGER NOT NULL DEFAULT 0, image TEXT, role TEXT NOT NULL DEFAULT 'user',
+    banned INTEGER NOT NULL DEFAULT 0, ban_reason TEXT, ban_expires TEXT,
+    two_factor_enabled INTEGER NOT NULL DEFAULT 0, metadata TEXT,
+    created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_users_slug ON users(slug);
+
+CREATE TABLE IF NOT EXISTS organization (
+    id TEXT PRIMARY KEY NOT NULL, name TEXT NOT NULL, slug TEXT, logo TEXT, metadata TEXT,
+    owner_id TEXT, created_at INTEGER NOT NULL DEFAULT (strftime('%s','now')),
+    updated_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_organization_slug ON organization(slug);
+
+CREATE TABLE IF NOT EXISTS agents (
+    id TEXT PRIMARY KEY, agent_id TEXT NOT NULL UNIQUE, name TEXT NOT NULL,
+    description TEXT, class TEXT NOT NULL DEFAULT 'custom',
+    privacy_tier TEXT NOT NULL DEFAULT 'public', owner_id TEXT REFERENCES users(id),
+    endpoint TEXT, webhook_secret TEXT, capabilities TEXT NOT NULL DEFAULT '[]',
+    skills TEXT NOT NULL DEFAULT '[]', avatar TEXT, messages_sent INTEGER NOT NULL DEFAULT 0,
+    messages_received INTEGER NOT NULL DEFAULT 0, conversation_count INTEGER NOT NULL DEFAULT 0,
+    friend_count INTEGER NOT NULL DEFAULT 0, status TEXT NOT NULL DEFAULT 'online',
+    last_seen INTEGER, payment_config TEXT, api_key_hash TEXT,
+    organization_id TEXT REFERENCES organization(id) ON DELETE SET NULL,
+    created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS agents_agent_id_idx ON agents(agent_id);
+CREATE INDEX IF NOT EXISTS agents_owner_idx ON agents(owner_id);
+CREATE INDEX IF NOT EXISTS agents_class_idx ON agents(class);
+CREATE INDEX IF NOT EXISTS agents_privacy_idx ON agents(privacy_tier);
+CREATE INDEX IF NOT EXISTS agents_org_idx ON agents(organization_id);
+
+CREATE TABLE IF NOT EXISTS conversations (
+    id TEXT PRIMARY KEY, participants TEXT NOT NULL,
+    visibility TEXT NOT NULL DEFAULT 'private', message_count INTEGER NOT NULL DEFAULT 0,
+    last_message_at INTEGER, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS messages (
+    id TEXT PRIMARY KEY, conversation_id TEXT NOT NULL REFERENCES conversations(id),
+    from_agent_id TEXT NOT NULL, to_agent_id TEXT NOT NULL, content TEXT NOT NULL,
+    content_type TEXT NOT NULL DEFAULT 'text', status TEXT NOT NULL DEFAULT 'pending',
+    attachments TEXT NOT NULL DEFAULT '[]', group_id TEXT, metadata TEXT DEFAULT '{}',
+    reply_to TEXT, created_at INTEGER NOT NULL, delivered_at INTEGER, read_at INTEGER
+);
+CREATE INDEX IF NOT EXISTS messages_conversation_idx ON messages(conversation_id);
+CREATE INDEX IF NOT EXISTS messages_from_agent_idx ON messages(from_agent_id);
+CREATE INDEX IF NOT EXISTS messages_to_agent_idx ON messages(to_agent_id);
+CREATE INDEX IF NOT EXISTS messages_created_at_idx ON messages(created_at);
+CREATE INDEX IF NOT EXISTS idx_messages_group_id ON messages(group_id) WHERE group_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_messages_reply_to ON messages(reply_to) WHERE reply_to IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS claim_codes (
+    id TEXT PRIMARY KEY, agent_id TEXT NOT NULL REFERENCES agents(id),
+    code TEXT NOT NULL UNIQUE, expires_at INTEGER NOT NULL, used_at INTEGER,
+    used_by TEXT REFERENCES users(id), created_at INTEGER NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS claim_codes_code_idx ON claim_codes(code);
+CREATE INDEX IF NOT EXISTS claim_codes_agent_idx ON claim_codes(agent_id);
+
+CREATE TABLE IF NOT EXISTS connections (
+    id TEXT PRIMARY KEY, agent_a TEXT NOT NULL REFERENCES agents(id),
+    agent_b TEXT NOT NULL REFERENCES agents(id), status TEXT NOT NULL DEFAULT 'pending',
+    initiated_by TEXT NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS connections_agent_a_idx ON connections(agent_a);
+CREATE INDEX IF NOT EXISTS connections_agent_b_idx ON connections(agent_b);
+
+CREATE TABLE IF NOT EXISTS delivery_jobs (
+    id TEXT PRIMARY KEY, message_id TEXT NOT NULL, payload TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending', attempts INTEGER NOT NULL DEFAULT 0,
+    max_attempts INTEGER NOT NULL DEFAULT 6, next_attempt_at INTEGER NOT NULL,
+    last_error TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_delivery_jobs_status ON delivery_jobs(status, next_attempt_at);
+
+CREATE TABLE IF NOT EXISTS dead_letters (
+    id TEXT PRIMARY KEY, message_id TEXT NOT NULL, job_id TEXT NOT NULL,
+    reason TEXT NOT NULL, attempts INTEGER NOT NULL, created_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_dead_letters_message ON dead_letters(message_id);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(content, from_agent_id, content='messages', content_rowid='rowid');
+INSERT INTO messages_fts(messages_fts) VALUES('rebuild');
+CREATE TRIGGER IF NOT EXISTS messages_ai AFTER INSERT ON messages BEGIN
+    INSERT INTO messages_fts(rowid, content, from_agent_id) VALUES (new.rowid, new.content, new.from_agent_id);
+END;
+CREATE TRIGGER IF NOT EXISTS messages_ad AFTER DELETE ON messages BEGIN
+    INSERT INTO messages_fts(messages_fts, rowid, content, from_agent_id) VALUES('delete', old.rowid, old.content, old.from_agent_id);
+END;
+CREATE TRIGGER IF NOT EXISTS messages_au AFTER UPDATE ON messages BEGIN
+    INSERT INTO messages_fts(messages_fts, rowid, content, from_agent_id) VALUES('delete', old.rowid, old.content, old.from_agent_id);
+    INSERT INTO messages_fts(rowid, content, from_agent_id) VALUES (new.rowid, new.content, new.from_agent_id);
+END;
+
+CREATE TABLE IF NOT EXISTS message_pins (
+    id TEXT PRIMARY KEY, message_id TEXT NOT NULL, conversation_id TEXT NOT NULL,
+    pinned_by TEXT NOT NULL, note TEXT, created_at INTEGER NOT NULL, UNIQUE(message_id, pinned_by)
+);
+CREATE INDEX IF NOT EXISTS idx_pins_conversation ON message_pins(conversation_id);
+CREATE INDEX IF NOT EXISTS idx_pins_agent ON message_pins(pinned_by);
+
+CREATE TABLE IF NOT EXISTS attachments (
+    slug TEXT PRIMARY KEY, conversation_id TEXT NOT NULL, from_agent_id TEXT NOT NULL,
+    content BLOB NOT NULL, original_size INTEGER NOT NULL, compressed_size INTEGER NOT NULL,
+    content_hash TEXT NOT NULL, format TEXT NOT NULL DEFAULT 'text', title TEXT,
+    tokens INTEGER NOT NULL DEFAULT 0, expires_at INTEGER NOT NULL DEFAULT 0,
+    storage_key TEXT, mode TEXT NOT NULL DEFAULT 'draft',
+    version_count INTEGER NOT NULL DEFAULT 1, current_version INTEGER NOT NULL DEFAULT 1,
+    created_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS attachments_conversation_idx ON attachments(conversation_id);
+CREATE INDEX IF NOT EXISTS attachments_agent_idx ON attachments(from_agent_id);
+
+CREATE TABLE IF NOT EXISTS capabilities (
+    id TEXT PRIMARY KEY, slug TEXT NOT NULL UNIQUE, name TEXT NOT NULL,
+    description TEXT NOT NULL, category TEXT NOT NULL, created_at INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS skills (
+    id TEXT PRIMARY KEY, slug TEXT NOT NULL UNIQUE, name TEXT NOT NULL,
+    description TEXT NOT NULL, category TEXT NOT NULL, created_at INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS agent_capabilities (
+    agent_id TEXT NOT NULL REFERENCES agents(id), capability_id TEXT NOT NULL REFERENCES capabilities(id),
+    PRIMARY KEY (agent_id, capability_id)
+);
+CREATE TABLE IF NOT EXISTS agent_skills (
+    agent_id TEXT NOT NULL REFERENCES agents(id), skill_id TEXT NOT NULL REFERENCES skills(id),
+    PRIMARY KEY (agent_id, skill_id)
+);
+
+CREATE TABLE IF NOT EXISTS accounts (
+    id TEXT PRIMARY KEY NOT NULL, user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    account_id TEXT NOT NULL, provider_id TEXT NOT NULL, access_token TEXT, refresh_token TEXT,
+    id_token TEXT, access_token_expires_at TEXT, refresh_token_expires_at TEXT, scope TEXT,
+    password TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_accounts_user_id ON accounts(user_id);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_accounts_provider ON accounts(provider_id, account_id);
+
+CREATE TABLE IF NOT EXISTS sessions (
+    id TEXT PRIMARY KEY NOT NULL, user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    token TEXT NOT NULL UNIQUE, ip_address TEXT, user_agent TEXT, expires_at TEXT NOT NULL,
+    active_organization_id TEXT, impersonated_by TEXT, active INTEGER NOT NULL DEFAULT 1,
+    created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_sessions_token ON sessions(token);
+CREATE INDEX IF NOT EXISTS idx_sessions_user_id ON sessions(user_id);
+
+CREATE TABLE IF NOT EXISTS verifications (
+    id TEXT PRIMARY KEY NOT NULL, identifier TEXT NOT NULL, value TEXT NOT NULL,
+    expires_at TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_verifications_identifier ON verifications(identifier);
+
+CREATE TABLE IF NOT EXISTS org_agent_keys (
+    id TEXT PRIMARY KEY NOT NULL, organization_id TEXT NOT NULL REFERENCES organization(id) ON DELETE CASCADE,
+    agent_id TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+    created_by TEXT NOT NULL, created_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS org_agent_keys_org_idx ON org_agent_keys(organization_id);
+CREATE INDEX IF NOT EXISTS org_agent_keys_agent_idx ON org_agent_keys(agent_id);
+
+CREATE TABLE IF NOT EXISTS attachment_versions (
+    id TEXT PRIMARY KEY, slug TEXT NOT NULL REFERENCES attachments(slug) ON DELETE CASCADE,
+    version_number INTEGER NOT NULL, author_agent_id TEXT NOT NULL,
+    change_type TEXT NOT NULL DEFAULT 'patch', patch_text TEXT, storage_key TEXT NOT NULL,
+    content_hash TEXT NOT NULL, original_size INTEGER NOT NULL, compressed_size INTEGER NOT NULL,
+    tokens INTEGER NOT NULL, change_summary TEXT, sections_modified TEXT NOT NULL DEFAULT '[]',
+    tokens_added INTEGER NOT NULL DEFAULT 0, tokens_removed INTEGER NOT NULL DEFAULT 0,
+    created_at INTEGER NOT NULL, UNIQUE(slug, version_number)
+);
+CREATE INDEX IF NOT EXISTS idx_attachment_versions_slug ON attachment_versions(slug);
+CREATE INDEX IF NOT EXISTS idx_attachment_versions_author ON attachment_versions(author_agent_id);
+
+CREATE TABLE IF NOT EXISTS attachment_approvals (
+    id TEXT PRIMARY KEY, slug TEXT NOT NULL REFERENCES attachments(slug) ON DELETE CASCADE,
+    reviewer_agent_id TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'pending', comment TEXT,
+    version_reviewed INTEGER NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL,
+    UNIQUE(slug, reviewer_agent_id)
+);
+CREATE INDEX IF NOT EXISTS idx_attachment_approvals_slug ON attachment_approvals(slug);
+
+CREATE TABLE IF NOT EXISTS attachment_contributors (
+    slug TEXT NOT NULL REFERENCES attachments(slug) ON DELETE CASCADE,
+    agent_id TEXT NOT NULL, version_count INTEGER NOT NULL DEFAULT 0,
+    total_tokens_added INTEGER NOT NULL DEFAULT 0, total_tokens_removed INTEGER NOT NULL DEFAULT 0,
+    first_contribution_at INTEGER NOT NULL, last_contribution_at INTEGER NOT NULL,
+    PRIMARY KEY (slug, agent_id)
+);`,
+  },
+  {
+    name: '2026-03-30-000001_agent_connections',
+    sql: `-- Add transport_type to agents table for connection mode classification.
+ALTER TABLE agents ADD COLUMN transport_type TEXT NOT NULL DEFAULT 'http';
+CREATE INDEX idx_agents_transport_type ON agents(transport_type);
+
+CREATE TABLE agent_connections (
+    id TEXT PRIMARY KEY NOT NULL, agent_id TEXT NOT NULL,
+    transport_type TEXT NOT NULL DEFAULT 'http', connection_id TEXT,
+    connected_at BIGINT NOT NULL, last_heartbeat BIGINT NOT NULL,
+    connection_metadata TEXT, created_at BIGINT NOT NULL,
+    FOREIGN KEY (agent_id) REFERENCES agents(agent_id) ON DELETE CASCADE,
+    UNIQUE(agent_id, connection_id)
+);
+CREATE INDEX idx_agent_connections_agent ON agent_connections(agent_id);
+CREATE INDEX idx_agent_connections_transport ON agent_connections(transport_type);
+CREATE INDEX idx_agent_connections_heartbeat ON agent_connections(last_heartbeat);`,
+  },
+  {
+    name: '2026-03-31-000001_agent_credentials',
+    sql: `-- Move agent credentials into signaldock.db agents table (T234 clean-cut).
+ALTER TABLE agents ADD COLUMN api_key_encrypted TEXT;
+ALTER TABLE agents ADD COLUMN api_base_url TEXT NOT NULL DEFAULT 'https://api.signaldock.io';
+ALTER TABLE agents ADD COLUMN classification TEXT;
+ALTER TABLE agents ADD COLUMN transport_config TEXT NOT NULL DEFAULT '{}';
+ALTER TABLE agents ADD COLUMN is_active INTEGER NOT NULL DEFAULT 1;
+ALTER TABLE agents ADD COLUMN last_used_at INTEGER;
+CREATE INDEX IF NOT EXISTS idx_agents_is_active ON agents(is_active);
+CREATE INDEX IF NOT EXISTS idx_agents_last_used ON agents(last_used_at);`,
+  },
+];
+
+/**
+ * Ensure signaldock.db exists and has the full schema applied.
+ *
+ * Idempotent — safe to call multiple times. Uses `CREATE TABLE IF NOT EXISTS`
+ * and `CREATE INDEX IF NOT EXISTS` throughout.
+ *
+ * @returns Object with action ('created' | 'exists') and the database path.
+ */
+export async function ensureSignaldockDb(
+  cwd?: string,
+): Promise<{ action: 'created' | 'exists'; path: string }> {
+  const dbPath = getSignaldockDbPath(cwd);
+  const alreadyExists = existsSync(dbPath);
+
+  // Ensure parent directory exists
+  mkdirSync(dirname(dbPath), { recursive: true });
+
+  // Open or create the database
+  const db = new DatabaseSyncClass(dbPath);
+
+  try {
+    // Set pragmas for optimal performance
+    db.exec('PRAGMA journal_mode = WAL');
+    db.exec('PRAGMA busy_timeout = 5000');
+    db.exec('PRAGMA synchronous = NORMAL');
+    db.exec('PRAGMA foreign_keys = ON');
+    db.exec('PRAGMA cache_size = -64000'); // 64MB
+
+    // Check if schema already applied (agents table as sentinel)
+    const hasSchema = (() => {
+      try {
+        const result = db
+          .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='agents'")
+          .get() as { name: string } | undefined;
+        return !!result;
+      } catch {
+        return false;
+      }
+    })();
+
+    // Ensure migration tracking tables exist
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS _signaldock_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
+      )
+    `);
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS _signaldock_migrations (
+        name TEXT PRIMARY KEY,
+        applied_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
+      )
+    `);
+
+    // Apply embedded migrations (works in ANY project, not just monorepo)
+    for (const migration of EMBEDDED_MIGRATIONS) {
+      // Skip already-applied migrations
+      const applied = db
+        .prepare('SELECT name FROM _signaldock_migrations WHERE name = ?')
+        .get(migration.name) as { name: string } | undefined;
+      if (applied) continue;
+
+      db.exec('BEGIN TRANSACTION');
+      try {
+        db.exec(migration.sql);
+        db.prepare('INSERT INTO _signaldock_migrations (name) VALUES (?)').run(migration.name);
+        db.exec('COMMIT');
+      } catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+      }
+    }
+
+    // Record schema version
+    db.exec(`
+      INSERT OR REPLACE INTO _signaldock_meta (key, value, updated_at)
+      VALUES ('schema_version', '${SIGNALDOCK_SCHEMA_VERSION}', strftime('%s', 'now'))
+    `);
+
+    return {
+      action: alreadyExists && hasSchema ? 'exists' : 'created',
+      path: dbPath,
+    };
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Check signaldock.db health — table count, WAL mode, schema version.
+ *
+ * Used by `cleo doctor` to verify signaldock.db integrity.
+ *
+ * @returns Health report object or null if DB doesn't exist.
+ */
+export async function checkSignaldockDbHealth(cwd?: string): Promise<{
+  exists: boolean;
+  path: string;
+  tableCount: number;
+  walMode: boolean;
+  schemaVersion: string | null;
+  foreignKeysEnabled: boolean;
+} | null> {
+  const dbPath = getSignaldockDbPath(cwd);
+  if (!existsSync(dbPath)) {
+    return {
+      exists: false,
+      path: dbPath,
+      tableCount: 0,
+      walMode: false,
+      schemaVersion: null,
+      foreignKeysEnabled: false,
+    };
+  }
+
+  const db = new DatabaseSyncClass(dbPath);
+  try {
+    const tables = db
+      .prepare(
+        "SELECT COUNT(*) as count FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'",
+      )
+      .get() as { count: number };
+
+    const journalMode = db.prepare('PRAGMA journal_mode').get() as { journal_mode: string };
+    const fkEnabled = db.prepare('PRAGMA foreign_keys').get() as { foreign_keys: number };
+
+    let schemaVersion: string | null = null;
+    try {
+      const meta = db
+        .prepare("SELECT value FROM _signaldock_meta WHERE key = 'schema_version'")
+        .get() as { value: string } | undefined;
+      schemaVersion = meta?.value ?? null;
+    } catch {
+      // Meta table may not exist
+    }
+
+    return {
+      exists: true,
+      path: dbPath,
+      tableCount: tables.count,
+      walMode: journalMode.journal_mode === 'wal',
+      schemaVersion,
+      foreignKeysEnabled: fkEnabled.foreign_keys === 1,
+    };
+  } finally {
+    db.close();
+  }
+}

package/src/store/sqlite-data-accessor.ts

@@ -14,6 +14,7 @@
 import type { Session, Task, TaskStatus } from '@cleocode/contracts';
 import { and, eq, inArray, isNull, like, ne, notInArray, or, sql } from 'drizzle-orm';
 import { archivedTaskToRow, rowToSession, rowToTask, taskToRow } from './converters.js';
+import { cleanupBrainRefsOnSessionDelete } from './cross-db-cleanup.js';
 import type {
   ArchiveFile,
   DataAccessor,
@@ -380,6 +381,8 @@ export async function createSqliteDataAccessor(cwd?: string): Promise<DataAccess
     async removeSingleSession(sessionId: string): Promise<void> {
       const db = await getDb(cwd);
       await db.delete(schema.sessions).where(eq(schema.sessions.id, sessionId)).run();
+      // Best-effort cross-db cleanup: nullify brain.db references to this session
+      void cleanupBrainRefsOnSessionDelete(sessionId, cwd);
     },
 
     // ---- Targeted query methods (Phase 2 modernization) ----
@@ -783,6 +786,7 @@ export async function createSqliteDataAccessor(cwd?: string): Promise<DataAccess
         ['createdBy', 'createdBy'],
         ['modifiedBy', 'modifiedBy'],
         ['sessionId', 'sessionId'],
+        ['assignee', 'assignee'],
       ];
 
       for (const [key, col] of fieldMap) {
@@ -874,6 +878,74 @@ export async function createSqliteDataAccessor(cwd?: string): Promise<DataAccess
       const meta = await getMetaValue<{ schemaVersion?: string }>(cwd, 'file_meta');
       return meta?.schemaVersion ?? null;
     },
+
+    // ---- Agent instances ----
+
+    async listAgentInstances(filters) {
+      const { listAgentInstances: listAgents } = await import('../agents/registry.js');
+      // Cast generic string filters to the specific union types expected by the agents module
+      return listAgents(filters as Parameters<typeof listAgents>[0], cwd);
+    },
+
+    async getAgentInstance(agentId) {
+      const { getAgentInstance: getAgent } = await import('../agents/registry.js');
+      return getAgent(agentId, cwd);
+    },
+
+    // ---- Agent task claiming ----
+
+    async claimTask(taskId: string, agentId: string): Promise<void> {
+      const nativeDb = getNativeTasksDb();
+      if (!nativeDb) {
+        throw new Error('Native database not initialized');
+      }
+
+      // Verify the task exists first
+      const existsRow = nativeDb.prepare('SELECT assignee FROM tasks WHERE id = ?').get(taskId) as
+        | { assignee: string | null }
+        | undefined;
+      if (!existsRow) {
+        throw new Error(`Task not found: ${taskId}`);
+      }
+
+      // Atomic claim: only succeeds if assignee IS NULL or already claimed by this agent.
+      // This prevents race conditions between concurrent agents.
+      const result = nativeDb
+        .prepare(
+          'UPDATE tasks SET assignee = ?, updated_at = ? WHERE id = ? AND (assignee IS NULL OR assignee = ?)',
+        )
+        .run(agentId, new Date().toISOString(), taskId, agentId) as { changes: number };
+
+      if (result.changes === 0) {
+        // Row was not updated — task is claimed by a different agent
+        const currentRow = nativeDb
+          .prepare('SELECT assignee FROM tasks WHERE id = ?')
+          .get(taskId) as { assignee: string | null } | undefined;
+        throw new Error(
+          `Task ${taskId} is already claimed by agent: ${currentRow?.assignee ?? 'unknown'}`,
+        );
+      }
+    },
+
+    async unclaimTask(taskId: string): Promise<void> {
+      const nativeDb = getNativeTasksDb();
+      if (!nativeDb) {
+        throw new Error('Native database not initialized');
+      }
+
+      // Verify the task exists
+      const existsRow = nativeDb.prepare('SELECT id FROM tasks WHERE id = ?').get(taskId) as
+        | { id: string }
+        | undefined;
+      if (!existsRow) {
+        throw new Error(`Task not found: ${taskId}`);
+      }
+
+      // Clear the assignee — no-op if already null
+      nativeDb
+        .prepare('UPDATE tasks SET assignee = NULL, updated_at = ? WHERE id = ?')
+        .run(new Date().toISOString(), taskId);
+    },
   };
 
   return accessor;

package/src/store/sqlite.ts

@@ -403,7 +403,10 @@ export { isSqliteBusy } from './migration-manager.js';
  */
 import type { RequiredColumn } from './migration-manager.js';
 
-const REQUIRED_TASK_COLUMNS: RequiredColumn[] = [{ name: 'pipeline_stage', ddl: 'text' }];
+const REQUIRED_TASK_COLUMNS: RequiredColumn[] = [
+  { name: 'pipeline_stage', ddl: 'text' },
+  { name: 'assignee', ddl: 'text' },
+];
 
 /**
  * Required columns that MUST exist on the sessions table before the

package/src/store/task-store.ts

@@ -78,7 +78,14 @@ export async function updateTask(
 
   if (updates.title !== undefined) updateRow.title = updates.title;
   if (updates.description !== undefined) updateRow.description = updates.description;
-  if (updates.status !== undefined) updateRow.status = updates.status;
+  if (updates.status !== undefined) {
+    updateRow.status = updates.status;
+    // Clear stale timestamps when status resets to non-terminal state
+    if (updates.status === 'pending' || updates.status === 'active') {
+      if (updates.cancelledAt === undefined) updateRow.cancelledAt = null;
+      if (updates.completedAt === undefined) updateRow.completedAt = null;
+    }
+  }
   if (updates.priority !== undefined) updateRow.priority = updates.priority;
   if (updates.type !== undefined) updateRow.type = updates.type;
   if (updates.parentId !== undefined) updateRow.parentId = updates.parentId;
@@ -99,6 +106,7 @@ export async function updateTask(
     updateRow.cancellationReason = updates.cancellationReason;
   if (updates.verification !== undefined)
     updateRow.verificationJson = JSON.stringify(updates.verification);
+  if (updates.assignee !== undefined) updateRow.assignee = updates.assignee;
 
   db.update(schema.tasks).set(updateRow).where(eq(schema.tasks.id, taskId)).run();
 

package/src/store/tasks-schema.ts

@@ -196,6 +196,8 @@ export const tasks = sqliteTable(
     // Not referencing lifecycle_stages.id so that stage binding works without
     // requiring a lifecycle pipeline record for every task.
     pipelineStage: text('pipeline_stage'),
+    /** Agent ID that has claimed/is assigned to this task. */
+    assignee: text('assignee'),
   },
   (table) => [
     index('idx_tasks_status').on(table.status),
@@ -205,6 +207,7 @@ export const tasks = sqliteTable(
     index('idx_tasks_priority').on(table.priority),
     index('idx_tasks_session_id').on(table.sessionId),
     index('idx_tasks_pipeline_stage').on(table.pipelineStage),
+    index('idx_tasks_assignee').on(table.assignee),
     // T033 composite indexes
     index('idx_tasks_parent_status').on(table.parentId, table.status),
     index('idx_tasks_status_priority').on(table.status, table.priority),
@@ -850,3 +853,7 @@ export type ReleaseManifestRow = typeof releaseManifests.$inferSelect;
 export type NewReleaseManifestRow = typeof releaseManifests.$inferInsert;
 export type ExternalTaskLinkRow = typeof externalTaskLinks.$inferSelect;
 export type NewExternalTaskLinkRow = typeof externalTaskLinks.$inferInsert;
+
+// agent_credentials REMOVED from tasks.db — T234 clean-cut.
+// Agent data (identity, credentials, capabilities, skills) now lives
+// exclusively in signaldock.db. See AgentRegistryAccessor.

package/src/system/__tests__/health.test.ts

@@ -27,7 +27,7 @@ describe('system health audit_log checks', () => {
     await getDb(projectRoot);
     closeDb();
 
-    const result = getSystemHealth(projectRoot);
+    const result = await getSystemHealth(projectRoot);
     const auditLog = result.checks.find((c) => c.name === 'audit_log');
 
     expect(auditLog).toBeDefined();
@@ -45,7 +45,7 @@ describe('system health audit_log checks', () => {
     db.close();
     expect(existsSync(dbPath)).toBe(true);
 
-    const result = getSystemHealth(projectRoot);
+    const result = await getSystemHealth(projectRoot);
     const auditLog = result.checks.find((c) => c.name === 'audit_log');
 
     expect(auditLog).toBeDefined();

package/src/system/health.ts

@@ -145,7 +145,7 @@ export interface DiagnosticsResult {
 }
 
 /** Run system health checks (SQLite-first per ADR-006). */
-export function getSystemHealth(projectRoot: string, opts?: { detailed?: boolean }): HealthResult {
+export async function getSystemHealth(projectRoot: string, opts?: { detailed?: boolean }): Promise<HealthResult> {
   const cleoDir = join(projectRoot, '.cleo');
   const checks: HealthCheck[] = [];
 
@@ -181,6 +181,58 @@ export function getSystemHealth(projectRoot: string, opts?: { detailed?: boolean
     checks.push(checkAuditLogAvailability(dbPath));
   }
 
+  // Check signaldock.db with schema health (local agent messaging per T225)
+  const sdDbPath = join(cleoDir, 'signaldock.db');
+  if (existsSync(sdDbPath)) {
+    try {
+      const { DatabaseSync: SdDb } = _require('node:sqlite') as {
+        DatabaseSync: new (path: string) => {
+          prepare(sql: string): { get(...args: unknown[]): unknown };
+          close(): void;
+        };
+      };
+      const sdDb = new SdDb(sdDbPath);
+      try {
+        const tables = sdDb
+          .prepare(
+            "SELECT COUNT(*) as count FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '_signaldock%'",
+          )
+          .get() as { count: number };
+        const journalMode = sdDb.prepare('PRAGMA journal_mode').get() as {
+          journal_mode: string;
+        };
+        let schemaVersion = 'unknown';
+        try {
+          const meta = sdDb
+            .prepare("SELECT value FROM _signaldock_meta WHERE key = 'schema_version'")
+            .get() as { value: string } | undefined;
+          schemaVersion = meta?.value ?? 'unknown';
+        } catch {
+          /* meta table may not exist */
+        }
+        checks.push({
+          name: 'signaldock_db',
+          status: tables.count >= 20 ? 'pass' : 'warn',
+          message: `signaldock.db: ${tables.count} tables, ${journalMode.journal_mode}, v${schemaVersion}`,
+        });
+      } finally {
+        sdDb.close();
+      }
+    } catch {
+      checks.push({
+        name: 'signaldock_db',
+        status: 'pass',
+        message: `signaldock.db: ${statSync(sdDbPath).size} bytes`,
+      });
+    }
+  } else {
+    checks.push({
+      name: 'signaldock_db',
+      status: 'warn',
+      message: 'signaldock.db not found. Run: cleo init',
+    });
+  }
+
   // Check config.json (config remains JSON per ADR-006)
   const configPath = join(cleoDir, 'config.json');
   if (existsSync(configPath)) {
@@ -264,7 +316,7 @@ export async function getSystemDiagnostics(
   projectRoot: string,
   opts?: { checks?: string[] },
 ): Promise<DiagnosticsResult> {
-  const healthResult = getSystemHealth(projectRoot, { detailed: true });
+  const healthResult = await getSystemHealth(projectRoot, { detailed: true });
 
   const diagChecks: DiagnosticsCheck[] = healthResult.checks.map((c) => ({
     name: c.name,