@cleocode/core 2026.3.74 → 2026.3.76

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":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxE,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,gFAAgF;IAChF,4EAA4E;IAC5E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACvC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxC,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,CAAC;QACnC,WAAW,EAAE;YACX,OAAO,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE;YACrC,UAAU,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE;SAC5B;QACD,SAAS,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE;QAC1B,YAAY,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE;KACjC,CAAC,CAAC;IACH,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,EAAE,aAAa,CAAC,CAAC;IAC3D,yBAAyB;IACzB,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CACb,0CAA0C,OAAO,2BAA2B,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CACxG,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAEzD,0DAA0D;IAC1D,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;IAC9D,MAAM,eAAe,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAC9C,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CACb,kEAAkE,OAAO,KAAK,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,EAAE,CAChH,CAAC;IACJ,CAAC;IAED,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"}

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

@@ -0,0 +1,199 @@
+/**
+ * Agent Registry Accessor — CRUD operations for agent credentials in SQLite.
+ *
+ * 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
+ */
+
+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;
+
+/** Typed database instance — preserves end-to-end type safety with the full schema. */
+type TypedDb = NodeSQLiteDatabase<typeof schema>;
+
+/** Zod validation schemas for agent credentials (drizzle-orm/zod). */
+export const agentCredentialInsertSchema = createInsertSchema(agentCredentials);
+export const agentCredentialSelectSchema = createSelectSchema(agentCredentials);
+
+/** 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);
+  return {
+    agentId: row.agentId,
+    displayName: row.displayName,
+    apiKey,
+    apiBaseUrl: row.apiBaseUrl,
+    classification: row.classification ?? undefined,
+    privacyTier: row.privacyTier 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(),
+  };
+}
+
+/** SQLite implementation of the AgentRegistryAPI. */
+export class AgentRegistryAccessor implements AgentRegistryAPI {
+  constructor(
+    private db: TypedDb,
+    private projectPath: string,
+  ) {}
+
+  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,
+    });
+
+    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> {
+    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);
+  }
+
+  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)));
+  }
+
+  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);
+    }
+
+    await this.db.update(agentCredentials).set(values).where(eq(agentCredentials.agentId, agentId));
+
+    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> {
+    // 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));
+  }
+
+  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: {
+        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');
+
+    // 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);
+  }
+
+  async markUsed(agentId: string): Promise<void> {
+    await this.db
+      .update(agentCredentials)
+      .set({ lastUsedAt: Date.now(), updatedAt: Date.now() })
+      .where(eq(agentCredentials.agentId, agentId));
+  }
+}

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/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> {

package/src/store/signaldock-sqlite.ts

@@ -0,0 +1,227 @@
+/**
+ * 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, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import type { DatabaseSync } from 'node:sqlite';
+import { fileURLToPath } from 'node:url';
+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);
+}
+
+/**
+ * Resolve the path to the consolidated migration SQL.
+ *
+ * The migration lives in the signaldock-storage crate at:
+ * crates/signaldock-storage/migrations/2026-03-28-000000_initial/up.sql
+ *
+ * We resolve it relative to the project root (monorepo layout).
+ */
+function resolveMigrationSql(cwd?: string): string | null {
+  // Try monorepo layout first (development)
+  const projectRoot = cwd ?? process.cwd();
+  const monorepoPath = join(
+    projectRoot,
+    'crates',
+    'signaldock-storage',
+    'migrations',
+    '2026-03-28-000000_initial',
+    'up.sql',
+  );
+  if (existsSync(monorepoPath)) return monorepoPath;
+
+  // Try relative to this file (installed package)
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  const installedPath = join(
+    thisDir,
+    '..',
+    '..',
+    '..',
+    '..',
+    'crates',
+    'signaldock-storage',
+    'migrations',
+    '2026-03-28-000000_initial',
+    'up.sql',
+  );
+  if (existsSync(installedPath)) return installedPath;
+
+  return null;
+}
+
+/**
+ * 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;
+      }
+    })();
+
+    if (!hasSchema) {
+      // Run the consolidated migration
+      const migrationPath = resolveMigrationSql(cwd);
+      if (!migrationPath) {
+        throw new Error(
+          'signaldock-storage migration SQL not found. Ensure crates/signaldock-storage/ exists.',
+        );
+      }
+
+      const migrationSql = readFileSync(migrationPath, 'utf-8');
+
+      // Execute the full migration SQL in one shot.
+      // node:sqlite's exec() handles multiple statements natively.
+      // We wrap in a transaction for atomicity.
+      db.exec('BEGIN TRANSACTION');
+      try {
+        db.exec(migrationSql);
+        db.exec('COMMIT');
+      } catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+      }
+    }
+
+    // Record schema version in a metadata table
+    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(`
+      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

@@ -783,6 +783,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 +875,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

@@ -99,6 +99,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,42 @@ 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 (Unified Agent Registry — T170/T173) ===
+
+/**
+ * Agent credentials for the unified agent registry.
+ * Stores encrypted API keys and transport configuration for registered agents.
+ * Replaces loose clawmsgr-*.json config files.
+ *
+ * @see docs/specs/SIGNALDOCK-UNIFIED-AGENT-REGISTRY.md Section 3.1
+ */
+export const agentCredentials = sqliteTable(
+  'agent_credentials',
+  {
+    agentId: text('agent_id').primaryKey(),
+    displayName: text('display_name').notNull(),
+    /** API key encrypted at rest using AES-256-GCM with machine-bound key. */
+    apiKeyEncrypted: text('api_key_encrypted').notNull(),
+    apiBaseUrl: text('api_base_url').notNull().default('https://api.signaldock.io'),
+    classification: text('classification'),
+    privacyTier: text('privacy_tier').notNull().default('public'),
+    /** JSON array of capability slugs. */
+    capabilities: text('capabilities').notNull().default('[]'),
+    /** JSON array of skill slugs. */
+    skills: text('skills').notNull().default('[]'),
+    /** JSON object with transport-specific settings. */
+    transportConfig: text('transport_config').notNull().default('{}'),
+    isActive: integer('is_active', { mode: 'boolean' }).notNull().default(true),
+    lastUsedAt: integer('last_used_at'),
+    createdAt: integer('created_at').notNull(),
+    updatedAt: integer('updated_at').notNull(),
+  },
+  (table) => [
+    index('idx_agent_credentials_active').on(table.isActive),
+    index('idx_agent_credentials_last_used').on(table.lastUsedAt),
+  ],
+);
+
+export type AgentCredentialRow = typeof agentCredentials.$inferSelect;
+export type NewAgentCredentialRow = typeof agentCredentials.$inferInsert;