@cleocode/core 2026.3.74 → 2026.4.0

package/src/store/__tests__/test-db-helper.js

@@ -39,7 +39,19 @@ export async function createTestDb() {
         verification: { enabled: false },
     });
     writeFileSync(join(cleoDir, 'config.json'), configContent);
+    // Verify write succeeded
+    const { readdirSync } = await import('node:fs');
+    const contents = readdirSync(cleoDir);
+    if (!contents.includes('config.json')) {
+        throw new Error(`createTestDb: config.json not found in ${cleoDir} after write (contents: ${JSON.stringify(contents)})`);
+    }
     const accessor = await createSqliteDataAccessor(tempDir);
+    // Verify config.json still exists after DB initialization
+    const { readdirSync: readdirSync2 } = await import('node:fs');
+    const contentsAfterDb = readdirSync2(cleoDir);
+    if (!contentsAfterDb.includes('config.json')) {
+        throw new Error(`createTestDb: config.json DELETED by createSqliteDataAccessor! ${cleoDir}: ${JSON.stringify(contentsAfterDb)}`);
+    }
     return {
         tempDir,
         cleoDir,

package/src/store/__tests__/test-db-helper.js.map

@@ -1 +1 @@
-{"version":3,"file":"test-db-helper.js","sourceRoot":"","sources":["test-db-helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AActE;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC;IAC1D,oDAAoD;IACpD,YAAY,EAAE,CAAC;IAEf,MAAM,QAAQ,GAAG,MAAM,wBAAwB,CAAC,OAAO,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAEvC,OAAO;QACL,OAAO;QACP,OAAO;QACP,QAAQ;QACR,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAC;YACvB,YAAY,EAAE,CAAC;YACf,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,KAA4C;IACpE,OAAO,KAAK,CAAC,GAAG,CACd,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC;QACC,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,QAAQ,CAAC,CAAC,EAAE,EAAE;QAChC,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,SAAS;QACvC,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,SAAS;QAC7B,QAAQ,EAAE,CAAC,CAAC,QAAQ,IAAI,QAAQ;QAChC,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAClD,GAAG,CAAC;KACL,CAAS,CACb,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAsB,EACtB,KAA4C;IAE5C,+CAA+C;IAC/C,MAAM,QAAQ,CAAC,YAAY,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAC;IAExD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO;IACT,CAAC;IAED,wCAAwC;IACxC,MAAM,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAEnC,oEAAoE;IACpE,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,MAAM,QAAQ,CAAC,gBAAgB,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,0EAA0E;IAC1E,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrE,IAAI,OAAO,EAAE,CAAC;QACZ,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;YAC7B,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC5C,MAAM,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"test-db-helper.js","sourceRoot":"","sources":["test-db-helper.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,375 @@
+/**
+ * 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.
+ *
+ * API keys are encrypted at rest using the crypto/credentials module.
+ *
+ * @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 { decrypt, encrypt } from '../crypto/credentials.js';
+import { ensureSignaldockDb, getSignaldockDbPath } from './signaldock-sqlite.js';
+
+const _require = createRequire(import.meta.url);
+const { DatabaseSync: DatabaseSyncClass } = _require('node:sqlite') as {
+  DatabaseSync: new (...args: ConstructorParameters<typeof DatabaseSync>) => DatabaseSync;
+};
+
+/** 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 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.agent_id,
+    displayName: row.name,
+    apiKey,
+    apiBaseUrl: row.api_base_url,
+    classification: row.classification ?? undefined,
+    privacyTier: row.privacy_tier as AgentCredential['privacyTier'],
+    capabilities: JSON.parse(row.capabilities) as string[],
+    skills: JSON.parse(row.skills) as string[],
+    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(),
+  };
+}
+
+/** 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 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> {
+    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}`);
+    return result;
+  }
+
+  async get(agentId: string): Promise<AgentCredential | null> {
+    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[]> {
+    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> {
+    const existing = await this.get(agentId);
+    if (!existing) throw new Error(`Agent not found: ${agentId}`);
+
+    const nowTs = Math.floor(Date.now() / 1000);
+    const db = openDb(this.projectPath);
+    try {
+      const sets: string[] = ['updated_at = ?'];
+      const params: unknown[] = [nowTs];
+
+      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}`);
+    return result;
+  }
+
+  async remove(agentId: string): Promise<void> {
+    const existing = await this.get(agentId);
+    if (!existing) throw new Error(`Agent not found: ${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}`);
+
+    const response = await fetch(`${credential.apiBaseUrl}/agents/${agentId}/rotate-key`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${credential.apiKey}`,
+        'X-Agent-Id': agentId,
+      },
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to rotate key on cloud: ${response.status} ${response.statusText}`);
+    }
+
+    const data = (await response.json()) as { data?: { apiKey?: string } };
+    const newApiKey = data.data?.apiKey;
+    if (!newApiKey) throw new Error('Cloud API did not return a new API key');
+
+    await this.update(agentId, { apiKey: newApiKey });
+    return { agentId, newApiKey: `${newApiKey.substring(0, 8)}...rotated` };
+  }
+
+  async getActive(): Promise<AgentCredential | null> {
+    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.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/converters.ts

@@ -57,6 +57,7 @@ export function rowToTask(row: TaskRow): Task {
           }
         : undefined,
     pipelineStage: row.pipelineStage ?? undefined,
+    assignee: row.assignee ?? undefined,
   };
 }
 
@@ -92,6 +93,7 @@ export function taskToRow(task: Partial<Task> & { id: string }): NewTaskRow {
     modifiedBy: task.provenance?.modifiedBy ?? null,
     sessionId: task.provenance?.sessionId ?? null,
     pipelineStage: task.pipelineStage ?? null,
+    assignee: task.assignee ?? null,
   };
 }
 

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;
+  }
+}

package/src/store/db-helpers.ts

@@ -79,6 +79,7 @@ export async function upsertTask(
     sessionId: row.sessionId,
     // T060: pipeline stage name (RCASD-IVTR+C)
     pipelineStage: row.pipelineStage ?? null,
+    assignee: row.assignee ?? null,
     // Always include archive metadata so unarchive clears stale values (T5034)
     archivedAt: archiveFields?.archivedAt ?? null,
     archiveReason: archiveFields?.archiveReason ?? null,

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

@@ -303,6 +303,29 @@ export class SafetyDataAccessor implements DataAccessor {
     return this.inner.removeSingleSession(sessionId);
   }
 
+  // ---- Agent instances ----
+
+  async listAgentInstances(filters?: {
+    status?: string | string[];
+    agentType?: string | string[];
+  }) {
+    return this.inner.listAgentInstances(filters);
+  }
+
+  async getAgentInstance(agentId: string) {
+    return this.inner.getAgentInstance(agentId);
+  }
+
+  // ---- Agent task claiming ----
+
+  async claimTask(taskId: string, agentId: string): Promise<void> {
+    return this.inner.claimTask(taskId, agentId);
+  }
+
+  async unclaimTask(taskId: string): Promise<void> {
+    return this.inner.unclaimTask(taskId);
+  }
+
   // ---- Lifecycle ----
 
   async close(): Promise<void> {