@cleocode/core 2026.3.76 → 2026.4.0

package/src/store/agent-registry-accessor.ts

@@ -1,85 +1,194 @@
 /**
- * Agent Registry Accessor — CRUD operations for agent credentials in SQLite.
+ * Agent Registry Accessor — CRUD operations for agent data in signaldock.db.
+ *
+ * signaldock.db is the SSoT for ALL agent data: identity, credentials,
+ * capabilities, skills, transport config. No agent data lives in tasks.db.
  *
- * Implements the `AgentRegistryAPI` contract from `@cleocode/contracts`.
  * API keys are encrypted at rest using the crypto/credentials module.
  *
- * @see docs/specs/SIGNALDOCK-UNIFIED-AGENT-REGISTRY.md Section 3
- * @task T175
+ * @see docs/specs/DATABASE-ARCHITECTURE.md
+ * @task T234
  */
 
+import { createRequire } from 'node:module';
+import type { DatabaseSync } from 'node:sqlite';
 import type {
   AgentCredential,
   AgentListFilter,
   AgentRegistryAPI,
   TransportConfig,
 } from '@cleocode/contracts';
-import { desc, eq } from 'drizzle-orm';
-import type { NodeSQLiteDatabase } from 'drizzle-orm/node-sqlite';
-import { createInsertSchema, createSelectSchema } from 'drizzle-orm/zod';
 import { decrypt, encrypt } from '../crypto/credentials.js';
-import * as schema from './tasks-schema.js';
-
-const { agentCredentials } = schema;
+import { ensureSignaldockDb, getSignaldockDbPath } from './signaldock-sqlite.js';
 
-/** Typed database instance — preserves end-to-end type safety with the full schema. */
-type TypedDb = NodeSQLiteDatabase<typeof schema>;
+const _require = createRequire(import.meta.url);
+const { DatabaseSync: DatabaseSyncClass } = _require('node:sqlite') as {
+  DatabaseSync: new (...args: ConstructorParameters<typeof DatabaseSync>) => DatabaseSync;
+};
 
-/** Zod validation schemas for agent credentials (drizzle-orm/zod). */
-export const agentCredentialInsertSchema = createInsertSchema(agentCredentials);
-export const agentCredentialSelectSchema = createSelectSchema(agentCredentials);
+/** Raw row shape from signaldock.db agents table. */
+interface AgentDbRow {
+  id: string;
+  agent_id: string;
+  name: string;
+  description: string | null;
+  class: string;
+  privacy_tier: string;
+  capabilities: string;
+  skills: string;
+  transport_type: string;
+  api_key_encrypted: string | null;
+  api_base_url: string;
+  classification: string | null;
+  transport_config: string;
+  is_active: number;
+  last_used_at: number | null;
+  created_at: number;
+  updated_at: number;
+}
 
-/** Convert a database row to an AgentCredential, decrypting the API key. */
-async function rowToCredential(
-  row: typeof agentCredentials.$inferSelect,
-  projectPath: string,
-): Promise<AgentCredential> {
-  const apiKey = await decrypt(row.apiKeyEncrypted, projectPath);
+/** Convert a signaldock.db row to an AgentCredential, decrypting the API key. */
+async function rowToCredential(row: AgentDbRow, projectPath: string): Promise<AgentCredential> {
+  const apiKey = row.api_key_encrypted ? await decrypt(row.api_key_encrypted, projectPath) : '';
   return {
-    agentId: row.agentId,
-    displayName: row.displayName,
+    agentId: row.agent_id,
+    displayName: row.name,
     apiKey,
-    apiBaseUrl: row.apiBaseUrl,
+    apiBaseUrl: row.api_base_url,
     classification: row.classification ?? undefined,
-    privacyTier: row.privacyTier as AgentCredential['privacyTier'],
+    privacyTier: row.privacy_tier as AgentCredential['privacyTier'],
     capabilities: JSON.parse(row.capabilities) as string[],
     skills: JSON.parse(row.skills) as string[],
-    transportConfig: JSON.parse(row.transportConfig) as TransportConfig,
-    isActive: row.isActive,
-    lastUsedAt: row.lastUsedAt ? new Date(row.lastUsedAt).toISOString() : undefined,
-    createdAt: new Date(row.createdAt).toISOString(),
-    updatedAt: new Date(row.updatedAt).toISOString(),
+    transportType: (row.transport_type ?? 'http') as AgentCredential['transportType'],
+    transportConfig: JSON.parse(row.transport_config) as TransportConfig,
+    isActive: row.is_active === 1,
+    lastUsedAt: row.last_used_at ? new Date(row.last_used_at * 1000).toISOString() : undefined,
+    createdAt: new Date(row.created_at * 1000).toISOString(),
+    updatedAt: new Date(row.updated_at * 1000).toISOString(),
   };
 }
 
-/** SQLite implementation of the AgentRegistryAPI. */
+/** Open signaldock.db for read/write operations. Caller must close. */
+function openDb(projectPath: string): DatabaseSync {
+  const dbPath = getSignaldockDbPath(projectPath);
+  const db = new DatabaseSyncClass(dbPath);
+  db.exec('PRAGMA foreign_keys = ON');
+  db.exec('PRAGMA journal_mode = WAL');
+  return db;
+}
+
+/**
+ * Sync capabilities/skills to junction tables in signaldock.db.
+ * Junction tables are the SSoT — JSON columns are materialized cache.
+ */
+function syncJunctionTables(
+  db: DatabaseSync,
+  agentUuid: string,
+  capabilities: string[],
+  skills: string[],
+): void {
+  db.prepare('DELETE FROM agent_capabilities WHERE agent_id = ?').run(agentUuid);
+  db.prepare('DELETE FROM agent_skills WHERE agent_id = ?').run(agentUuid);
+  for (const cap of capabilities) {
+    const capRow = db.prepare('SELECT id FROM capabilities WHERE slug = ?').get(cap) as
+      | { id: string }
+      | undefined;
+    if (capRow) {
+      db.prepare(
+        'INSERT OR IGNORE INTO agent_capabilities (agent_id, capability_id) VALUES (?, ?)',
+      ).run(agentUuid, capRow.id);
+    }
+  }
+  for (const skill of skills) {
+    const skillRow = db.prepare('SELECT id FROM skills WHERE slug = ?').get(skill) as
+      | { id: string }
+      | undefined;
+    if (skillRow) {
+      db.prepare('INSERT OR IGNORE INTO agent_skills (agent_id, skill_id) VALUES (?, ?)').run(
+        agentUuid,
+        skillRow.id,
+      );
+    }
+  }
+}
+
+/** signaldock.db implementation of the AgentRegistryAPI. */
 export class AgentRegistryAccessor implements AgentRegistryAPI {
-  constructor(
-    private db: TypedDb,
-    private projectPath: string,
-  ) {}
+  constructor(private projectPath: string) {}
+
+  /** Ensure signaldock.db exists with full schema before any operation. */
+  private async ensureDb(): Promise<void> {
+    await ensureSignaldockDb(this.projectPath);
+  }
 
   async register(
     credential: Omit<AgentCredential, 'createdAt' | 'updatedAt'>,
   ): Promise<AgentCredential> {
-    const now = Date.now();
-    const apiKeyEncrypted = await encrypt(credential.apiKey, this.projectPath);
-
-    await this.db.insert(agentCredentials).values({
-      agentId: credential.agentId,
-      displayName: credential.displayName,
-      apiKeyEncrypted,
-      apiBaseUrl: credential.apiBaseUrl,
-      classification: credential.classification ?? null,
-      privacyTier: credential.privacyTier,
-      capabilities: JSON.stringify(credential.capabilities),
-      skills: JSON.stringify(credential.skills),
-      transportConfig: JSON.stringify(credential.transportConfig),
-      isActive: credential.isActive,
-      lastUsedAt: credential.lastUsedAt ? new Date(credential.lastUsedAt).getTime() : null,
-      createdAt: now,
-      updatedAt: now,
-    });
+    await this.ensureDb();
+    const nowTs = Math.floor(Date.now() / 1000);
+    const apiKeyEncrypted = credential.apiKey
+      ? await encrypt(credential.apiKey, this.projectPath)
+      : null;
+
+    const db = openDb(this.projectPath);
+    try {
+      const existing = db
+        .prepare('SELECT id FROM agents WHERE agent_id = ?')
+        .get(credential.agentId) as { id: string } | undefined;
+
+      if (!existing) {
+        const id = crypto.randomUUID();
+        db.prepare(
+          `INSERT INTO agents (id, agent_id, name, class, privacy_tier, capabilities, skills,
+           transport_type, api_key_encrypted, api_base_url, classification, transport_config,
+           is_active, last_used_at, status, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'online', ?, ?)`,
+        ).run(
+          id,
+          credential.agentId,
+          credential.displayName,
+          credential.classification ?? 'custom',
+          credential.privacyTier,
+          JSON.stringify(credential.capabilities),
+          JSON.stringify(credential.skills),
+          credential.transportType ?? 'http',
+          apiKeyEncrypted,
+          credential.apiBaseUrl,
+          credential.classification ?? null,
+          JSON.stringify(credential.transportConfig),
+          credential.isActive ? 1 : 0,
+          credential.lastUsedAt
+            ? Math.floor(new Date(credential.lastUsedAt).getTime() / 1000)
+            : null,
+          nowTs,
+          nowTs,
+        );
+        syncJunctionTables(db, id, credential.capabilities, credential.skills);
+      } else {
+        db.prepare(
+          `UPDATE agents SET name = ?, class = ?, privacy_tier = ?, capabilities = ?, skills = ?,
+           transport_type = ?, api_key_encrypted = ?, api_base_url = ?, classification = ?,
+           transport_config = ?, is_active = ?, updated_at = ? WHERE agent_id = ?`,
+        ).run(
+          credential.displayName,
+          credential.classification ?? 'custom',
+          credential.privacyTier,
+          JSON.stringify(credential.capabilities),
+          JSON.stringify(credential.skills),
+          credential.transportType ?? 'http',
+          apiKeyEncrypted,
+          credential.apiBaseUrl,
+          credential.classification ?? null,
+          JSON.stringify(credential.transportConfig),
+          credential.isActive ? 1 : 0,
+          nowTs,
+          credential.agentId,
+        );
+        syncJunctionTables(db, existing.id, credential.capabilities, credential.skills);
+      }
+    } finally {
+      db.close();
+    }
 
     const result = await this.get(credential.agentId);
     if (!result) throw new Error(`Failed to register agent: ${credential.agentId}`);
@@ -87,54 +196,110 @@ export class AgentRegistryAccessor implements AgentRegistryAPI {
   }
 
   async get(agentId: string): Promise<AgentCredential | null> {
-    const rows = await this.db
-      .select()
-      .from(agentCredentials)
-      .where(eq(agentCredentials.agentId, agentId));
-
-    if (rows.length === 0) return null;
-    return rowToCredential(rows[0]!, this.projectPath);
+    await this.ensureDb();
+    const db = openDb(this.projectPath);
+    try {
+      const row = db.prepare('SELECT * FROM agents WHERE agent_id = ?').get(agentId) as
+        | AgentDbRow
+        | undefined;
+      if (!row) return null;
+      return rowToCredential(row, this.projectPath);
+    } finally {
+      db.close();
+    }
   }
 
   async list(filter?: AgentListFilter): Promise<AgentCredential[]> {
-    const query =
-      filter?.active !== undefined
-        ? this.db
-            .select()
-            .from(agentCredentials)
-            .where(eq(agentCredentials.isActive, filter.active))
-        : this.db.select().from(agentCredentials);
-
-    const rows = await query;
-    return Promise.all(rows.map((row) => rowToCredential(row, this.projectPath)));
+    await this.ensureDb();
+    const db = openDb(this.projectPath);
+    try {
+      const rows =
+        filter?.active !== undefined
+          ? (db
+              .prepare('SELECT * FROM agents WHERE is_active = ?')
+              .all(filter.active ? 1 : 0) as unknown as AgentDbRow[])
+          : (db.prepare('SELECT * FROM agents').all() as unknown as AgentDbRow[]);
+      return Promise.all(rows.map((row) => rowToCredential(row, this.projectPath)));
+    } finally {
+      db.close();
+    }
   }
 
   async update(
     agentId: string,
     updates: Partial<Omit<AgentCredential, 'agentId' | 'createdAt'>>,
   ): Promise<AgentCredential> {
-    // C2 fix: pre-flight check — fail fast if agent doesn't exist
     const existing = await this.get(agentId);
     if (!existing) throw new Error(`Agent not found: ${agentId}`);
 
-    const now = Date.now();
-    const values: Record<string, unknown> = { updatedAt: now };
-
-    if (updates.displayName !== undefined) values['displayName'] = updates.displayName;
-    if (updates.apiBaseUrl !== undefined) values['apiBaseUrl'] = updates.apiBaseUrl;
-    if (updates.classification !== undefined) values['classification'] = updates.classification;
-    if (updates.privacyTier !== undefined) values['privacyTier'] = updates.privacyTier;
-    if (updates.capabilities !== undefined)
-      values['capabilities'] = JSON.stringify(updates.capabilities);
-    if (updates.skills !== undefined) values['skills'] = JSON.stringify(updates.skills);
-    if (updates.transportConfig !== undefined)
-      values['transportConfig'] = JSON.stringify(updates.transportConfig);
-    if (updates.isActive !== undefined) values['isActive'] = updates.isActive;
-    if (updates.apiKey !== undefined) {
-      values['apiKeyEncrypted'] = await encrypt(updates.apiKey, this.projectPath);
-    }
+    const nowTs = Math.floor(Date.now() / 1000);
+    const db = openDb(this.projectPath);
+    try {
+      const sets: string[] = ['updated_at = ?'];
+      const params: unknown[] = [nowTs];
 
-    await this.db.update(agentCredentials).set(values).where(eq(agentCredentials.agentId, agentId));
+      if (updates.displayName !== undefined) {
+        sets.push('name = ?');
+        params.push(updates.displayName);
+      }
+      if (updates.apiBaseUrl !== undefined) {
+        sets.push('api_base_url = ?');
+        params.push(updates.apiBaseUrl);
+      }
+      if (updates.classification !== undefined) {
+        sets.push('classification = ?');
+        params.push(updates.classification);
+      }
+      if (updates.privacyTier !== undefined) {
+        sets.push('privacy_tier = ?');
+        params.push(updates.privacyTier);
+      }
+      if (updates.capabilities !== undefined) {
+        sets.push('capabilities = ?');
+        params.push(JSON.stringify(updates.capabilities));
+      }
+      if (updates.skills !== undefined) {
+        sets.push('skills = ?');
+        params.push(JSON.stringify(updates.skills));
+      }
+      if (updates.transportType !== undefined) {
+        sets.push('transport_type = ?');
+        params.push(updates.transportType);
+      }
+      if (updates.transportConfig !== undefined) {
+        sets.push('transport_config = ?');
+        params.push(JSON.stringify(updates.transportConfig));
+      }
+      if (updates.isActive !== undefined) {
+        sets.push('is_active = ?');
+        params.push(updates.isActive ? 1 : 0);
+      }
+      if (updates.apiKey !== undefined) {
+        const encrypted = await encrypt(updates.apiKey, this.projectPath);
+        sets.push('api_key_encrypted = ?');
+        params.push(encrypted);
+      }
+
+      params.push(agentId);
+      db.prepare(`UPDATE agents SET ${sets.join(', ')} WHERE agent_id = ?`).run(
+        ...(params as Array<string | number | null>),
+      );
+
+      // Sync junction tables if capabilities or skills changed
+      if (updates.capabilities !== undefined || updates.skills !== undefined) {
+        const agentRow = db.prepare('SELECT id FROM agents WHERE agent_id = ?').get(agentId) as {
+          id: string;
+        };
+        syncJunctionTables(
+          db,
+          agentRow.id,
+          updates.capabilities ?? existing.capabilities,
+          updates.skills ?? existing.skills,
+        );
+      }
+    } finally {
+      db.close();
+    }
 
     const result = await this.get(agentId);
     if (!result) throw new Error(`Agent not found after update: ${agentId}`);
@@ -142,18 +307,21 @@ export class AgentRegistryAccessor implements AgentRegistryAPI {
   }
 
   async remove(agentId: string): Promise<void> {
-    // H2 fix: pre-flight check — throw if agent doesn't exist
     const existing = await this.get(agentId);
     if (!existing) throw new Error(`Agent not found: ${agentId}`);
 
-    await this.db.delete(agentCredentials).where(eq(agentCredentials.agentId, agentId));
+    const db = openDb(this.projectPath);
+    try {
+      db.prepare('DELETE FROM agents WHERE agent_id = ?').run(agentId);
+    } finally {
+      db.close();
+    }
   }
 
   async rotateKey(agentId: string): Promise<{ agentId: string; newApiKey: string }> {
     const credential = await this.get(agentId);
     if (!credential) throw new Error(`Agent not found: ${agentId}`);
 
-    // Call cloud API to rotate key
     const response = await fetch(`${credential.apiBaseUrl}/agents/${agentId}/rotate-key`, {
       method: 'POST',
       headers: {
@@ -170,30 +338,38 @@ export class AgentRegistryAccessor implements AgentRegistryAPI {
     const newApiKey = data.data?.apiKey;
     if (!newApiKey) throw new Error('Cloud API did not return a new API key');
 
-    // Re-encrypt and store locally
     await this.update(agentId, { apiKey: newApiKey });
-
-    // C1 fix: return only agentId, not plaintext key — callers use get() to retrieve
     return { agentId, newApiKey: `${newApiKey.substring(0, 8)}...rotated` };
   }
 
   async getActive(): Promise<AgentCredential | null> {
-    // H3 fix: secondary orderBy(createdAt desc) for deterministic tie-breaking
-    const rows = await this.db
-      .select()
-      .from(agentCredentials)
-      .where(eq(agentCredentials.isActive, true))
-      .orderBy(desc(agentCredentials.lastUsedAt), desc(agentCredentials.createdAt))
-      .limit(1);
-
-    if (rows.length === 0) return null;
-    return rowToCredential(rows[0]!, this.projectPath);
+    await this.ensureDb();
+    const db = openDb(this.projectPath);
+    try {
+      const row = db
+        .prepare(
+          'SELECT * FROM agents WHERE is_active = 1 ORDER BY last_used_at DESC, created_at DESC LIMIT 1',
+        )
+        .get() as AgentDbRow | undefined;
+      if (!row) return null;
+      return rowToCredential(row, this.projectPath);
+    } finally {
+      db.close();
+    }
   }
 
   async markUsed(agentId: string): Promise<void> {
-    await this.db
-      .update(agentCredentials)
-      .set({ lastUsedAt: Date.now(), updatedAt: Date.now() })
-      .where(eq(agentCredentials.agentId, agentId));
+    await this.ensureDb();
+    const nowTs = Math.floor(Date.now() / 1000);
+    const db = openDb(this.projectPath);
+    try {
+      db.prepare('UPDATE agents SET last_used_at = ?, updated_at = ? WHERE agent_id = ?').run(
+        nowTs,
+        nowTs,
+        agentId,
+      );
+    } finally {
+      db.close();
+    }
   }
 }

package/src/store/cross-db-cleanup.ts

@@ -11,7 +11,7 @@
  * @epic T029
  */
 
-import { eq, or } from 'drizzle-orm';
+import { and, eq, isNotNull, or } from 'drizzle-orm';
 import * as brainSchema from './brain-schema.js';
 import { getBrainDb } from './brain-sqlite.js';
 
@@ -177,6 +177,142 @@ export async function taskExistsInTasksDb(
  * if (await sessionExistsInTasksDb('ses_abc', db)) { /* safe to reference *\/ }
  * ```
  */
+/**
+ * Reconcile orphaned cross-DB references in brain.db.
+ *
+ * Scans brain.db for references to tasks/sessions that no longer exist in
+ * tasks.db and cleans them up:
+ * - brain_decisions with stale context_task_id or context_epic_id → nullify
+ * - brain_observations with stale source_session_id → nullify
+ * - brain_memory_links with stale task_id → delete row
+ *
+ * This is the background reconciliation pass mentioned in the module doc.
+ * Safe to run at any frequency — idempotent.
+ *
+ * @param cwd - Optional working directory
+ * @returns Counts of orphaned references cleaned up
+ */
+export async function reconcileOrphanedRefs(cwd?: string): Promise<{
+  decisionsFixed: number;
+  observationsFixed: number;
+  linksRemoved: number;
+}> {
+  let brainDb: Awaited<ReturnType<typeof getBrainDb>> | null = null;
+  const result = { decisionsFixed: 0, observationsFixed: 0, linksRemoved: 0 };
+
+  try {
+    brainDb = await getBrainDb(cwd);
+  } catch {
+    return result;
+  }
+
+  const { getDb } = await import('./sqlite.js');
+  let tasksDb: Awaited<ReturnType<typeof getDb>>;
+  try {
+    tasksDb = await getDb(cwd);
+  } catch {
+    return result;
+  }
+
+  try {
+    // 1. Find decisions with stale context_task_id
+    const decisionsWithTaskRef = await brainDb
+      .select({
+        id: brainSchema.brainDecisions.id,
+        contextTaskId: brainSchema.brainDecisions.contextTaskId,
+        contextEpicId: brainSchema.brainDecisions.contextEpicId,
+      })
+      .from(brainSchema.brainDecisions)
+      .where(
+        or(
+          isNotNull(brainSchema.brainDecisions.contextTaskId),
+          isNotNull(brainSchema.brainDecisions.contextEpicId),
+        ),
+      )
+      .all();
+
+    for (const d of decisionsWithTaskRef) {
+      if (d.contextTaskId) {
+        const exists = await taskExistsInTasksDb(d.contextTaskId, tasksDb);
+        if (!exists) {
+          await brainDb
+            .update(brainSchema.brainDecisions)
+            .set({ contextTaskId: null })
+            .where(eq(brainSchema.brainDecisions.id, d.id));
+          result.decisionsFixed++;
+        }
+      }
+      if (d.contextEpicId) {
+        const exists = await taskExistsInTasksDb(d.contextEpicId, tasksDb);
+        if (!exists) {
+          await brainDb
+            .update(brainSchema.brainDecisions)
+            .set({ contextEpicId: null })
+            .where(eq(brainSchema.brainDecisions.id, d.id));
+          result.decisionsFixed++;
+        }
+      }
+    }
+
+    // 2. Find observations with stale source_session_id
+    const obsWithSessionRef = await brainDb
+      .select({
+        id: brainSchema.brainObservations.id,
+        sourceSessionId: brainSchema.brainObservations.sourceSessionId,
+      })
+      .from(brainSchema.brainObservations)
+      .where(isNotNull(brainSchema.brainObservations.sourceSessionId))
+      .all();
+
+    for (const o of obsWithSessionRef) {
+      {
+        const exists = o.sourceSessionId
+          ? await sessionExistsInTasksDb(o.sourceSessionId, tasksDb)
+          : false;
+        if (!exists) {
+          await brainDb
+            .update(brainSchema.brainObservations)
+            .set({ sourceSessionId: null })
+            .where(eq(brainSchema.brainObservations.id, o.id));
+          result.observationsFixed++;
+        }
+      }
+    }
+
+    // 3. Find memory links with stale task_id
+    const allLinks = await brainDb
+      .select({
+        memoryType: brainSchema.brainMemoryLinks.memoryType,
+        memoryId: brainSchema.brainMemoryLinks.memoryId,
+        taskId: brainSchema.brainMemoryLinks.taskId,
+        linkType: brainSchema.brainMemoryLinks.linkType,
+      })
+      .from(brainSchema.brainMemoryLinks)
+      .all();
+
+    for (const link of allLinks) {
+      const exists = await taskExistsInTasksDb(link.taskId, tasksDb);
+      if (!exists) {
+        await brainDb
+          .delete(brainSchema.brainMemoryLinks)
+          .where(
+            and(
+              eq(brainSchema.brainMemoryLinks.memoryType, link.memoryType),
+              eq(brainSchema.brainMemoryLinks.memoryId, link.memoryId),
+              eq(brainSchema.brainMemoryLinks.taskId, link.taskId),
+              eq(brainSchema.brainMemoryLinks.linkType, link.linkType),
+            ),
+          );
+        result.linksRemoved++;
+      }
+    }
+  } catch {
+    // Non-fatal best-effort reconciliation
+  }
+
+  return result;
+}
+
 export async function sessionExistsInTasksDb(
   sessionId: string,
   tasksDb: Awaited<ReturnType<typeof import('./sqlite.js').getDb>>,
@@ -190,3 +326,41 @@ export async function sessionExistsInTasksDb(
     .all();
   return result.length > 0;
 }
+
+/**
+ * Verify an agent exists in signaldock.db before creating cross-DB references.
+ * Returns true if the agent_id exists in signaldock.db agents table.
+ *
+ * Provides write-guard for agent_instances and agent_error_log in tasks.db
+ * that reference agents whose identity lives in signaldock.db.
+ *
+ * @param agentId - Agent slug (e.g. 'cleo-db-lead') to verify
+ * @param cwd - Optional working directory
+ * @returns True if the agent exists in signaldock.db
+ *
+ * @task T238
+ */
+export async function agentExistsInSignaldockDb(agentId: string, cwd?: string): Promise<boolean> {
+  try {
+    const { getSignaldockDbPath } = await import('./signaldock-sqlite.js');
+    const { existsSync } = await import('node:fs');
+    const dbPath = getSignaldockDbPath(cwd);
+    if (!existsSync(dbPath)) return false;
+
+    const { createRequire } = await import('node:module');
+    const _require = createRequire(import.meta.url);
+    const { DatabaseSync } = _require('node:sqlite') as typeof import('node:sqlite');
+    const db = new DatabaseSync(dbPath);
+    try {
+      const row = db.prepare('SELECT id FROM agents WHERE agent_id = ?').get(agentId) as
+        | { id: string }
+        | undefined;
+      return !!row;
+    } finally {
+      db.close();
+    }
+  } catch {
+    // signaldock.db may not exist yet — non-fatal
+    return false;
+  }
+}