@cleocode/core 2026.4.11 → 2026.4.12

package/dist/store/agent-registry-accessor.js

@@ -1,26 +1,118 @@
 /**
- * Agent Registry Accessor — CRUD operations for agent data in signaldock.db.
+ * Agent Registry Accessor — cross-DB CRUD for agent data.
  *
- * signaldock.db is the SSoT for ALL agent data: identity, credentials,
- * capabilities, skills, transport config. No agent data lives in tasks.db.
+ * Post-T310 (ADR-037), agent identity lives in the GLOBAL
+ * `$XDG_DATA_HOME/cleo/signaldock.db:agents` table; per-project
+ * visibility and overrides live in the PROJECT
+ * `.cleo/conduit.db:project_agent_refs` table.
  *
- * API keys are encrypted at rest using the crypto/credentials module.
+ * This module provides three module-level functions that perform the
+ * in-memory cross-DB join, plus the backward-compatible
+ * `AgentRegistryAccessor` class that wraps them.
  *
- * @see docs/specs/DATABASE-ARCHITECTURE.md
- * @task T234
+ * Architecture:
+ *   global  signaldock.db — canonical identity (openGlobalDb)
+ *   project conduit.db    — project_agent_refs  (openConduitDb)
+ *   Join performed in Node (SQLite cannot cross-file-handle JOIN).
+ *
+ * @see .cleo/specs/T310-conduit-signaldock-spec.md §3.5
+ * @see .cleo/adrs/ADR-037-conduit-signaldock-separation.md
+ * @task T355
+ * @epic T310
  */
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { decrypt, encrypt } from '../crypto/credentials.js';
-import { ensureSignaldockDb, getSignaldockDbPath } from './signaldock-sqlite.js';
+import { join } from 'node:path';
+import { getCleoHome } from '../paths.js';
+import { deriveApiKey } from './api-key-kdf.js';
+import { ensureConduitDb, getConduitDbPath } from './conduit-sqlite.js';
+import { getGlobalSalt } from './global-salt.js';
+import { ensureGlobalSignaldockDb, getGlobalSignaldockDbPath } from './signaldock-sqlite.js';
+// ---------------------------------------------------------------------------
+// node:sqlite interop (createRequire for ESM / Vitest compat)
+// ---------------------------------------------------------------------------
 const _require = createRequire(import.meta.url);
-const { DatabaseSync: DatabaseSyncClass } = _require('node:sqlite');
-/** Convert a signaldock.db row to an AgentCredential, decrypting the API key. */
-async function rowToCredential(row, projectPath) {
-    const apiKey = row.api_key_encrypted ? await decrypt(row.api_key_encrypted, projectPath) : '';
+const { DatabaseSync } = _require('node:sqlite');
+// ---------------------------------------------------------------------------
+// Machine-key helper (internal — mirrors credentials.ts private getMachineKey)
+// ---------------------------------------------------------------------------
+/** Machine-key constants. */
+const MACHINE_KEY_LENGTH = 32;
+/**
+ * Read or auto-generate the machine key (32 bytes).
+ * Machine key lives at `getCleoHome()/machine-key` (same XDG root as the global salt).
+ *
+ * @returns A 32-byte Buffer.
+ * @task T355
+ * @epic T310
+ */
+function readMachineKey() {
+    const keyPath = join(getCleoHome(), 'machine-key');
+    if (!existsSync(keyPath)) {
+        const cleoHome = getCleoHome();
+        if (!existsSync(cleoHome)) {
+            mkdirSync(cleoHome, { recursive: true });
+        }
+        const key = randomBytes(MACHINE_KEY_LENGTH);
+        writeFileSync(keyPath, key, { mode: 0o600 });
+        return key;
+    }
+    // Validate permissions on POSIX
+    if (process.platform !== 'win32') {
+        const stat = statSync(keyPath);
+        const mode = stat.mode & 0o777;
+        if (mode !== 0o600) {
+            throw new Error(`Machine key at ${keyPath} has wrong permissions: expected 0o600, got 0o${mode.toString(8)}. ` +
+                `Fix with: chmod 600 ${keyPath}`);
+        }
+    }
+    const key = readFileSync(keyPath);
+    if (key.length !== MACHINE_KEY_LENGTH) {
+        throw new Error(`Machine key at ${keyPath} has wrong length: expected ${MACHINE_KEY_LENGTH} bytes, got ${key.length}.`);
+    }
+    return key;
+}
+// ---------------------------------------------------------------------------
+// Row-to-type converters
+// ---------------------------------------------------------------------------
+/**
+ * Convert a project_agent_refs row to a `ProjectAgentRef` contract object.
+ *
+ * @param row - Raw SQLite row from conduit.db:project_agent_refs.
+ * @returns Typed `ProjectAgentRef` object.
+ * @task T355
+ * @epic T310
+ */
+function rowToProjectRef(row) {
+    return {
+        agentId: row.agent_id,
+        attachedAt: row.attached_at,
+        role: row.role,
+        capabilitiesOverride: row.capabilities_override,
+        lastUsedAt: row.last_used_at,
+        enabled: row.enabled,
+    };
+}
+/**
+ * Convert a global signaldock.db:agents row to an `AgentCredential`.
+ * API key is stored as binary (derived via KDF) — returned as hex string.
+ * Legacy encrypted values (pre-T310) are left as-is; the reauth flag handles
+ * forced re-authentication at the CLI layer.
+ *
+ * @param row - Raw SQLite row from global signaldock.db:agents.
+ * @returns Typed `AgentCredential` (apiKey is hex-encoded derived bytes or empty).
+ * @task T355
+ * @epic T310
+ */
+function rowToCredential(row) {
     return {
         agentId: row.agent_id,
         displayName: row.name,
-        apiKey,
+        // api_key_encrypted stores the KDF-derived key as binary or a legacy ciphertext.
+        // Return as hex-encoded bytes for callers that need the raw key.
+        // The reauth flow in `cleo agent auth` handles re-keying (T358).
+        apiKey: row.api_key_encrypted ? Buffer.from(row.api_key_encrypted).toString('hex') : '',
         apiBaseUrl: row.api_base_url,
         classification: row.classification ?? undefined,
         privacyTier: row.privacy_tier,
@@ -34,17 +126,67 @@ async function rowToCredential(row, projectPath) {
         updatedAt: new Date(row.updated_at * 1000).toISOString(),
     };
 }
-/** Open signaldock.db for read/write operations. Caller must close. */
-function openDb(projectPath) {
-    const dbPath = getSignaldockDbPath(projectPath);
-    const db = new DatabaseSyncClass(dbPath);
+/**
+ * Merge a global agent row with an optional project_agent_refs row into an
+ * `AgentWithProjectOverride` object.
+ *
+ * @param agentRow - Row from global signaldock.db:agents.
+ * @param refRow   - Row from conduit.db:project_agent_refs, or null.
+ * @returns Merged `AgentWithProjectOverride`.
+ * @task T355
+ * @epic T310
+ */
+function mergeToAgentWithOverride(agentRow, refRow) {
+    return {
+        ...rowToCredential(agentRow),
+        projectRef: refRow ? rowToProjectRef(refRow) : null,
+    };
+}
+// ---------------------------------------------------------------------------
+// Database handle helpers (short-lived, caller closes)
+// ---------------------------------------------------------------------------
+/**
+ * Open a short-lived read/write handle to the GLOBAL signaldock.db.
+ * Caller MUST call `db.close()` when done.
+ *
+ * @task T355
+ * @epic T310
+ */
+function openGlobalDb() {
+    const dbPath = getGlobalSignaldockDbPath();
+    const db = new DatabaseSync(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.
+ * Open a short-lived read/write handle to the PROJECT conduit.db.
+ * Caller MUST call `db.close()` when done.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @task T355
+ * @epic T310
+ */
+function openConduitDb(projectRoot) {
+    const dbPath = getConduitDbPath(projectRoot);
+    const db = new DatabaseSync(dbPath);
+    db.exec('PRAGMA foreign_keys = ON');
+    db.exec('PRAGMA journal_mode = WAL');
+    return db;
+}
+// ---------------------------------------------------------------------------
+// junction table sync (global signaldock.db only)
+// ---------------------------------------------------------------------------
+/**
+ * Sync capabilities/skills to junction tables in global signaldock.db.
+ * Junction tables are the SSoT — JSON columns are a materialized cache.
+ *
+ * @param db         - Open handle to global signaldock.db.
+ * @param agentUuid  - The `id` (UUID primary key) from the agents row.
+ * @param capabilities - Array of capability slugs.
+ * @param skills       - Array of skill slugs.
+ * @task T355
+ * @epic T310
  */
 function syncJunctionTables(db, agentUuid, capabilities, skills) {
     db.prepare('DELETE FROM agent_capabilities WHERE agent_id = ?').run(agentUuid);
@@ -62,86 +204,336 @@ function syncJunctionTables(db, agentUuid, capabilities, skills) {
         }
     }
 }
-/** signaldock.db implementation of the AgentRegistryAPI. */
-export class AgentRegistryAccessor {
-    projectPath;
-    constructor(projectPath) {
-        this.projectPath = projectPath;
+// ---------------------------------------------------------------------------
+// Module-level cross-DB functions (spec §3.5)
+// ---------------------------------------------------------------------------
+/**
+ * Cross-DB agent lookup. Opens both the global signaldock.db and the
+ * current project's conduit.db, joins project_agent_refs ⨝ agents by
+ * agentId, and returns the merged view.
+ *
+ * Default (includeGlobal=false): returns null if no project_agent_refs row
+ * exists, even if the agent exists globally. An enabled=0 row is also treated
+ * as absent.
+ *
+ * includeGlobal=true: returns the global agent with `projectRef: null` if no
+ * project attachment row exists.
+ *
+ * Dangling soft-FK detection: if a project_agent_refs row exists but the
+ * referenced global agent does not, logs a WARN and returns null.
+ *
+ * @param projectRoot     - Absolute path to the project root directory.
+ * @param agentId         - Agent business identifier.
+ * @param opts.includeGlobal - When true, returns global identity even without project ref.
+ * @returns Merged agent record or null if not found.
+ *
+ * @task T355
+ * @epic T310
+ */
+export function lookupAgent(projectRoot, agentId, opts) {
+    const includeGlobal = opts?.includeGlobal ?? false;
+    const globalDb = openGlobalDb();
+    const conduitDb = openConduitDb(projectRoot);
+    try {
+        const agentRow = globalDb.prepare('SELECT * FROM agents WHERE agent_id = ?').get(agentId);
+        const refRow = conduitDb
+            .prepare('SELECT * FROM project_agent_refs WHERE agent_id = ?')
+            .get(agentId);
+        // Dangling soft-FK: ref exists in conduit but not in global
+        if (refRow && !agentRow) {
+            console.warn(`[agent-registry-accessor] WARN: dangling project_agent_refs row for agent_id="${agentId}". ` +
+                `No matching row in global signaldock.db:agents. Row will be ignored.`);
+            return null;
+        }
+        // Agent does not exist globally at all
+        if (!agentRow)
+            return null;
+        if (!includeGlobal) {
+            // INNER JOIN semantics: must have a project ref with enabled=1
+            if (!refRow || refRow.enabled === 0)
+                return null;
+            return mergeToAgentWithOverride(agentRow, refRow);
+        }
+        // includeGlobal=true: return global agent; populate projectRef only when enabled=1
+        const effectiveRef = refRow && refRow.enabled === 1 ? refRow : null;
+        return mergeToAgentWithOverride(agentRow, effectiveRef);
     }
-    /** Ensure signaldock.db exists with full schema before any operation. */
-    async ensureDb() {
-        await ensureSignaldockDb(this.projectPath);
+    finally {
+        globalDb.close();
+        conduitDb.close();
     }
-    async register(credential) {
-        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);
-            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);
+}
+/**
+ * Lists agents visible in the current project.
+ *
+ * Default (includeGlobal=false): INNER JOIN on project_agent_refs (enabled=1)
+ * — only agents explicitly attached to this project are returned.
+ *
+ * includeGlobal=true: returns all global agents regardless of project
+ * attachment, with projectRef populated for attached ones and null for the rest.
+ *
+ * includeDisabled=true: also returns agents with enabled=0 in project_agent_refs.
+ * Ignored when includeGlobal=true (all global agents are returned regardless).
+ *
+ * @param projectRoot            - Absolute path to the project root directory.
+ * @param opts.includeGlobal     - Include all global agents (bypasses project filter).
+ * @param opts.includeDisabled   - Include agents with enabled=0 in project_agent_refs.
+ * @returns Array of merged agent records.
+ *
+ * @task T355
+ * @epic T310
+ */
+export function listAgentsForProject(projectRoot, opts) {
+    const includeGlobal = opts?.includeGlobal ?? false;
+    const includeDisabled = opts?.includeDisabled ?? false;
+    const globalDb = openGlobalDb();
+    const conduitDb = openConduitDb(projectRoot);
+    try {
+        const allAgents = globalDb
+            .prepare('SELECT * FROM agents ORDER BY name ASC')
+            .all();
+        const allRefs = conduitDb
+            .prepare('SELECT * FROM project_agent_refs')
+            .all();
+        // Build a map from agentId → ref row for O(1) lookup during join
+        const refMap = new Map();
+        for (const ref of allRefs) {
+            refMap.set(ref.agent_id, ref);
+        }
+        const result = [];
+        for (const agentRow of allAgents) {
+            const ref = refMap.get(agentRow.agent_id);
+            if (includeGlobal) {
+                // Return all global agents; populate projectRef only for attached ones
+                const effectiveRef = ref && ref.enabled === 1 ? ref : null;
+                result.push(mergeToAgentWithOverride(agentRow, effectiveRef));
             }
             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);
+                // INNER JOIN: only agents with a project ref row
+                if (!ref)
+                    continue;
+                if (!includeDisabled && ref.enabled === 0)
+                    continue;
+                result.push(mergeToAgentWithOverride(agentRow, ref));
             }
         }
-        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) {
-        await this.ensureDb();
-        const db = openDb(this.projectPath);
-        try {
-            const row = db.prepare('SELECT * FROM agents WHERE agent_id = ?').get(agentId);
-            if (!row)
-                return null;
-            return rowToCredential(row, this.projectPath);
+    finally {
+        globalDb.close();
+        conduitDb.close();
+    }
+}
+/**
+ * Creates a new agent: writes identity row to global signaldock.db AND attaches
+ * it to the current project via conduit.db:project_agent_refs.
+ *
+ * Write order: global first, then project ref. If the project ref write fails,
+ * the global row remains (recoverable via `cleo agent attach <id>`).
+ *
+ * API key derivation: HMAC-SHA256(machineKey || globalSalt, agentId) per ADR-037 §5.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param spec        - Agent creation spec (without createdAt/updatedAt).
+ * @returns Merged agent record including the new project ref.
+ *
+ * @task T355
+ * @epic T310
+ */
+export function createProjectAgent(projectRoot, spec) {
+    ensureGlobalSignaldockDb();
+    ensureConduitDb(projectRoot);
+    const nowTs = Math.floor(Date.now() / 1000);
+    const nowIso = new Date(nowTs * 1000).toISOString();
+    // Derive API key using the T310 KDF
+    const machineKey = readMachineKey();
+    const globalSalt = getGlobalSalt();
+    const derivedKey = deriveApiKey({
+        machineKey,
+        globalSalt,
+        agentId: spec.agentId,
+    });
+    // Store as hex string in the encrypted column
+    const apiKeyEncrypted = derivedKey.toString('hex');
+    const globalDb = openGlobalDb();
+    try {
+        const existing = globalDb
+            .prepare('SELECT id FROM agents WHERE agent_id = ?')
+            .get(spec.agentId);
+        let agentUuid;
+        if (!existing) {
+            agentUuid = crypto.randomUUID();
+            globalDb
+                .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, requires_reauth)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'online', ?, ?, 0)`)
+                .run(agentUuid, spec.agentId, spec.displayName, spec.classification ?? 'custom', spec.privacyTier, JSON.stringify(spec.capabilities), JSON.stringify(spec.skills), spec.transportType ?? 'http', apiKeyEncrypted, spec.apiBaseUrl, spec.classification ?? null, JSON.stringify(spec.transportConfig), spec.isActive ? 1 : 0, spec.lastUsedAt ? Math.floor(new Date(spec.lastUsedAt).getTime() / 1000) : null, nowTs, nowTs);
+            syncJunctionTables(globalDb, agentUuid, spec.capabilities, spec.skills);
         }
-        finally {
-            db.close();
+        else {
+            agentUuid = existing.id;
+            // Update identity in global DB (idempotent re-register)
+            globalDb
+                .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(spec.displayName, spec.classification ?? 'custom', spec.privacyTier, JSON.stringify(spec.capabilities), JSON.stringify(spec.skills), spec.transportType ?? 'http', apiKeyEncrypted, spec.apiBaseUrl, spec.classification ?? null, JSON.stringify(spec.transportConfig), spec.isActive ? 1 : 0, nowTs, spec.agentId);
+            syncJunctionTables(globalDb, agentUuid, spec.capabilities, spec.skills);
+        }
+    }
+    finally {
+        globalDb.close();
+    }
+    // Attach to project via conduit.db:project_agent_refs
+    const conduitDb = openConduitDb(projectRoot);
+    try {
+        const existingRef = conduitDb
+            .prepare('SELECT agent_id, enabled FROM project_agent_refs WHERE agent_id = ?')
+            .get(spec.agentId);
+        if (!existingRef) {
+            conduitDb
+                .prepare(`INSERT INTO project_agent_refs (agent_id, attached_at, role, capabilities_override, last_used_at, enabled)
+           VALUES (?, ?, NULL, NULL, NULL, 1)`)
+                .run(spec.agentId, nowIso);
+        }
+        else if (existingRef.enabled === 0) {
+            // Re-enable a previously detached agent
+            conduitDb
+                .prepare(`UPDATE project_agent_refs SET enabled = 1, attached_at = ? WHERE agent_id = ?`)
+                .run(nowIso, spec.agentId);
         }
+        // If enabled=1 already, leave the existing ref intact
     }
+    finally {
+        conduitDb.close();
+    }
+    const result = lookupAgent(projectRoot, spec.agentId, { includeGlobal: false });
+    if (!result) {
+        throw new Error(`createProjectAgent: failed to retrieve agent after creation: ${spec.agentId}`);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// AgentRegistryAccessor class (backward-compatible wrapper)
+// ---------------------------------------------------------------------------
+/**
+ * AgentRegistryAccessor — backward-compatible CRUD wrapper around the
+ * cross-DB module-level functions.
+ *
+ * Post-T310 (ADR-037), the constructor accepts the project root (same
+ * semantics as `projectPath` in the pre-T310 version). All operations are
+ * routed through the cross-DB functions above.
+ *
+ * @task T355
+ * @epic T310
+ */
+export class AgentRegistryAccessor {
+    projectPath;
+    /**
+     * @param projectPath - Absolute path to the project root directory.
+     *   Used as the `projectRoot` argument for all cross-DB operations.
+     * @task T355
+     * @epic T310
+     */
+    constructor(projectPath) {
+        this.projectPath = projectPath;
+    }
+    /**
+     * Ensure both databases exist with their full schemas before any operation.
+     *
+     * @task T355
+     * @epic T310
+     */
+    ensureDbs() {
+        ensureGlobalSignaldockDb();
+        ensureConduitDb(this.projectPath);
+    }
+    /**
+     * Register (create or update) an agent in global signaldock.db and attach
+     * it to the current project via conduit.db:project_agent_refs.
+     *
+     * @param credential - Agent spec (without createdAt/updatedAt).
+     * @returns The registered agent credential.
+     * @task T355
+     * @epic T310
+     */
+    async register(credential) {
+        this.ensureDbs();
+        return createProjectAgent(this.projectPath, credential);
+    }
+    /**
+     * Get agent by agentId. Project-scoped by default (INNER JOIN).
+     *
+     * @param agentId             - Agent business identifier.
+     * @param opts.includeGlobal  - When true, returns global identity even without project ref.
+     * @returns The agent credential, or null if not found.
+     * @task T355
+     * @epic T310
+     */
+    async get(agentId, opts) {
+        this.ensureDbs();
+        return lookupAgent(this.projectPath, agentId, opts);
+    }
+    /**
+     * Lists project-scoped agents (INNER JOIN on project_agent_refs with enabled=1).
+     *
+     * @param filter - Optional filter (active field maps to is_active in global agents).
+     * @returns Array of agent credentials visible in this project.
+     * @task T355
+     * @epic T310
+     */
     async list(filter) {
-        await this.ensureDb();
-        const db = openDb(this.projectPath);
+        this.ensureDbs();
+        const results = listAgentsForProject(this.projectPath, { includeGlobal: false });
+        if (filter?.active !== undefined) {
+            return results.filter((a) => a.isActive === filter.active);
+        }
+        return results;
+    }
+    /**
+     * Lists all global agents (no project filter). Exposed for `--global` CLI flag.
+     *
+     * @param filter - Optional filter (active field maps to is_active in global agents).
+     * @returns Array of all globally registered agent credentials.
+     * @task T355
+     * @epic T310
+     */
+    async listGlobal(filter) {
+        this.ensureDbs();
+        const globalDb = openGlobalDb();
         try {
             const rows = filter?.active !== undefined
-                ? db
-                    .prepare('SELECT * FROM agents WHERE is_active = ?')
+                ? globalDb
+                    .prepare('SELECT * FROM agents WHERE is_active = ? ORDER BY name ASC')
                     .all(filter.active ? 1 : 0)
-                : db.prepare('SELECT * FROM agents').all();
-            return Promise.all(rows.map((row) => rowToCredential(row, this.projectPath)));
+                : globalDb
+                    .prepare('SELECT * FROM agents ORDER BY name ASC')
+                    .all();
+            return rows.map(rowToCredential);
         }
         finally {
-            db.close();
+            globalDb.close();
         }
     }
+    /**
+     * Update agent identity fields in global signaldock.db.
+     * Project-specific fields (role, capabilitiesOverride) require direct
+     * conduit.db manipulation (not yet exposed by this method).
+     *
+     * @param agentId  - Agent business identifier.
+     * @param updates  - Partial set of fields to update.
+     * @returns The updated agent credential (project-scoped lookup).
+     * @task T355
+     * @epic T310
+     */
     async update(agentId, updates) {
-        const existing = await this.get(agentId);
+        this.ensureDbs();
+        const existing = await this.get(agentId, { includeGlobal: true });
         if (!existing)
             throw new Error(`Agent not found: ${agentId}`);
         const nowTs = Math.floor(Date.now() / 1000);
-        const db = openDb(this.projectPath);
+        const globalDb = openGlobalDb();
         try {
             const sets = ['updated_at = ?'];
             const params = [nowTs];
@@ -182,40 +574,112 @@ export class AgentRegistryAccessor {
                 params.push(updates.isActive ? 1 : 0);
             }
             if (updates.apiKey !== undefined) {
-                const encrypted = await encrypt(updates.apiKey, this.projectPath);
+                // Re-derive using new T310 KDF
+                const machineKey = readMachineKey();
+                const globalSalt = getGlobalSalt();
+                const derivedKey = deriveApiKey({ machineKey, globalSalt, agentId });
                 sets.push('api_key_encrypted = ?');
-                params.push(encrypted);
+                params.push(derivedKey.toString('hex'));
             }
             params.push(agentId);
-            db.prepare(`UPDATE agents SET ${sets.join(', ')} WHERE agent_id = ?`).run(...params);
+            globalDb
+                .prepare(`UPDATE agents SET ${sets.join(', ')} WHERE agent_id = ?`)
+                .run(...params);
             // 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);
-                syncJunctionTables(db, agentRow.id, updates.capabilities ?? existing.capabilities, updates.skills ?? existing.skills);
+                const agentRow = globalDb
+                    .prepare('SELECT id FROM agents WHERE agent_id = ?')
+                    .get(agentId);
+                if (agentRow) {
+                    syncJunctionTables(globalDb, agentRow.id, updates.capabilities ?? existing.capabilities, updates.skills ?? existing.skills);
+                }
             }
         }
         finally {
-            db.close();
+            globalDb.close();
         }
-        const result = await this.get(agentId);
+        const result = await this.get(agentId, { includeGlobal: true });
         if (!result)
             throw new Error(`Agent not found after update: ${agentId}`);
         return result;
     }
+    /**
+     * Remove agent from current project (sets project_agent_refs.enabled=0).
+     * Does NOT delete from global signaldock.db (per ADR-037 §6 / Q4=C).
+     *
+     * @param agentId - Agent business identifier.
+     * @task T355
+     * @epic T310
+     */
     async remove(agentId) {
-        const existing = await this.get(agentId);
-        if (!existing)
-            throw new Error(`Agent not found: ${agentId}`);
-        const db = openDb(this.projectPath);
+        this.ensureDbs();
+        const conduitDb = openConduitDb(this.projectPath);
         try {
-            db.prepare('DELETE FROM agents WHERE agent_id = ?').run(agentId);
+            const ref = conduitDb
+                .prepare('SELECT agent_id FROM project_agent_refs WHERE agent_id = ?')
+                .get(agentId);
+            if (!ref) {
+                throw new Error(`Agent not found in current project: ${agentId}`);
+            }
+            conduitDb
+                .prepare('UPDATE project_agent_refs SET enabled = 0 WHERE agent_id = ?')
+                .run(agentId);
         }
         finally {
-            db.close();
+            conduitDb.close();
         }
     }
+    /**
+     * Remove agent from global signaldock.db.
+     * Requires explicit opt-in. Warns if cross-project refs may exist.
+     *
+     * @param agentId     - Agent business identifier.
+     * @param opts.force  - Skip the global-delete warning when refs exist.
+     * @task T355
+     * @epic T310
+     */
+    async removeGlobal(agentId, opts) {
+        this.ensureDbs();
+        const globalDb = openGlobalDb();
+        try {
+            const existing = globalDb.prepare('SELECT id FROM agents WHERE agent_id = ?').get(agentId);
+            if (!existing) {
+                throw new Error(`Agent not found globally: ${agentId}`);
+            }
+            if (!opts?.force) {
+                // Best-effort cross-project scan: check the current project's conduit.db
+                const conduitDb = openConduitDb(this.projectPath);
+                try {
+                    const ref = conduitDb
+                        .prepare('SELECT agent_id FROM project_agent_refs WHERE agent_id = ? AND enabled = 1')
+                        .get(agentId);
+                    if (ref) {
+                        throw new Error(`Agent "${agentId}" still has project references in the current project. ` +
+                            `Use removeGlobal(id, { force: true }) to skip this check.`);
+                    }
+                }
+                finally {
+                    conduitDb.close();
+                }
+            }
+            globalDb.prepare('DELETE FROM agents WHERE agent_id = ?').run(agentId);
+        }
+        finally {
+            globalDb.close();
+        }
+    }
+    /**
+     * Rotate API key via cloud endpoint and re-encrypt with the new T310 KDF
+     * in global signaldock.db.
+     *
+     * @param agentId - Agent business identifier.
+     * @returns Object with agentId and a redacted new API key string.
+     * @task T355
+     * @epic T310
+     */
     async rotateKey(agentId) {
-        const credential = await this.get(agentId);
+        this.ensureDbs();
+        const credential = await this.get(agentId, { includeGlobal: true });
         if (!credential)
             throw new Error(`Agent not found: ${agentId}`);
         const response = await fetch(`${credential.apiBaseUrl}/agents/${agentId}/rotate-key`, {
@@ -232,33 +696,87 @@ export class AgentRegistryAccessor {
         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 });
+        // Re-derive and store using T310 KDF
+        const machineKey = readMachineKey();
+        const globalSalt = getGlobalSalt();
+        const derivedKey = deriveApiKey({ machineKey, globalSalt, agentId });
+        const nowTs = Math.floor(Date.now() / 1000);
+        const globalDb = openGlobalDb();
+        try {
+            globalDb
+                .prepare('UPDATE agents SET api_key_encrypted = ?, updated_at = ?, requires_reauth = 0 WHERE agent_id = ?')
+                .run(derivedKey.toString('hex'), nowTs, agentId);
+        }
+        finally {
+            globalDb.close();
+        }
         return { agentId, newApiKey: `${newApiKey.substring(0, 8)}...rotated` };
     }
+    /**
+     * Get the most recently used active agent in the current project.
+     *
+     * @returns The most-recently-used active agent, or null if none found.
+     * @task T355
+     * @epic T310
+     */
     async getActive() {
-        await this.ensureDb();
-        const db = openDb(this.projectPath);
+        this.ensureDbs();
+        const globalDb = openGlobalDb();
+        const conduitDb = openConduitDb(this.projectPath);
         try {
-            const row = db
+            // Get all project-attached, enabled agent IDs ordered by project last_used_at
+            const enabledRefs = conduitDb
+                .prepare('SELECT agent_id, last_used_at FROM project_agent_refs WHERE enabled = 1 ORDER BY last_used_at DESC')
+                .all();
+            for (const ref of enabledRefs) {
+                const agentRow = globalDb
+                    .prepare('SELECT * FROM agents WHERE agent_id = ? AND is_active = 1')
+                    .get(ref.agent_id);
+                if (agentRow)
+                    return rowToCredential(agentRow);
+            }
+            // Fall back to global last_used_at if no project-local activity recorded
+            const row = globalDb
                 .prepare('SELECT * FROM agents WHERE is_active = 1 ORDER BY last_used_at DESC, created_at DESC LIMIT 1')
                 .get();
             if (!row)
                 return null;
-            return rowToCredential(row, this.projectPath);
+            return rowToCredential(row);
         }
         finally {
-            db.close();
+            globalDb.close();
+            conduitDb.close();
         }
     }
+    /**
+     * Update last_used_at in both global signaldock.db:agents and
+     * conduit.db:project_agent_refs.
+     *
+     * @param agentId - Agent business identifier.
+     * @task T355
+     * @epic T310
+     */
     async markUsed(agentId) {
-        await this.ensureDb();
+        this.ensureDbs();
         const nowTs = Math.floor(Date.now() / 1000);
-        const db = openDb(this.projectPath);
+        const nowIso = new Date(nowTs * 1000).toISOString();
+        const globalDb = openGlobalDb();
+        try {
+            globalDb
+                .prepare('UPDATE agents SET last_used_at = ?, updated_at = ? WHERE agent_id = ?')
+                .run(nowTs, nowTs, agentId);
+        }
+        finally {
+            globalDb.close();
+        }
+        const conduitDb = openConduitDb(this.projectPath);
         try {
-            db.prepare('UPDATE agents SET last_used_at = ?, updated_at = ? WHERE agent_id = ?').run(nowTs, nowTs, agentId);
+            conduitDb
+                .prepare('UPDATE project_agent_refs SET last_used_at = ? WHERE agent_id = ?')
+                .run(nowIso, agentId);
         }
         finally {
-            db.close();
+            conduitDb.close();
         }
     }
 }