@cleocode/core 2026.5.133 → 2026.6.0

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

@@ -1,34 +1,56 @@
 /**
  * Agent Registry Accessor — cross-DB CRUD for agent data.
  *
- * 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.
+ * Post-T11622 cutover (folds T11578 AC2), agent identity lives in the GLOBAL
+ * PREFIXED `agent_registry_agents` table (+ `agent_registry_capabilities` /
+ * `agent_registry_skills` / `agent_registry_agent_capabilities` /
+ * `agent_registry_agent_skills`); per-project visibility and overrides live in the
+ * PROJECT `conduit_project_agent_refs` table (T11578 · AC4 — conduit namespace
+ * cutover). The bare legacy `agents` shape is no longer read or written.
  *
- * This module provides three module-level functions that perform the
- * in-memory cross-DB join, plus the backward-compatible
- * `AgentRegistryAccessor` class that wraps them.
+ * Post-E6-L5 (T11525) / E6-L6 (T11526), both tables are hosted inside the
+ * CONSOLIDATED dual-scope `cleo.db` files (global `$XDG_DATA_HOME/cleo/cleo.db`
+ * and project `.cleo/cleo.db`) — the standalone `signaldock.db` / `conduit.db`
+ * files are gone. The global `agent_registry_*` tables are owned by the
+ * consolidated cleo-global migration (T11622 rename of `signaldock_*`);
+ * `ensureGlobalAgentRegistryDb()` opens the shared consolidated handle. The
+ * prefixed conduit `conduit_project_agent_refs` table is created by the
+ * consolidated cleo-project migration (T11578 · AC4) and `ensureConduitDb()`
+ * ensures the project `cleo.db` is open. The read path MUST therefore go through
+ * those `ensure*` calls so it shares the same handle as the write path (T11562 —
+ * agents read/write path divergence regression).
+ *
+ * The consolidated `agent_registry_agents` table carries TEXT ISO-8601 timestamps
+ * (`created_at` / `updated_at` / `last_used_at`, each with a GLOB CHECK) — every
+ * write path below stamps ISO strings, not the legacy epoch integers (T11622
+ * write-path constraint reconciliation).
+ *
+ * This module provides three module-level functions that perform the in-memory
+ * cross-DB join, plus the backward-compatible `AgentRegistryAccessor` class that
+ * wraps them.
  *
  * Architecture:
- *   global  signaldock.db — canonical identity (openGlobalDb)
- *   project conduit.db    — project_agent_refs  (openConduitDb)
+ *   global  cleo.db — canonical identity `agent_registry_agents` (openGlobalDb → ensureGlobalAgentRegistryDb)
+ *   project cleo.db — `conduit_project_agent_refs` (openConduitDb)
  *   Join performed in Node (SQLite cannot cross-file-handle JOIN).
  *
  * @see .cleo/rcasd/T310/specification/T310-specification.md §3.5
  * @see .cleo/adrs/ADR-037-conduit-signaldock-separation.md
  * @task T355
+ * @task T11562
+ * @task T11622
  * @epic T310
+ * @epic T11249
  */
 import { randomBytes } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import { getCleoHome } from '../paths.js';
+import { ensureGlobalAgentRegistryDb, getGlobalAgentRegistryNativeDb, } from './agent-registry-store.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';
 import { applyPerfPragmas } from './sqlite-pragmas.js';
 // ---------------------------------------------------------------------------
 // node:sqlite interop (createRequire for ESM / Vitest compat)
@@ -96,12 +118,12 @@ function rowToProjectRef(row) {
     };
 }
 /**
- * Convert a global signaldock.db:agents row to an `AgentCredential`.
+ * Convert a global cleo.db:agent_registry_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.
+ * @param row - Raw SQLite row from global cleo.db:agent_registry_agents.
  * @returns Typed `AgentCredential` (apiKey is hex-encoded derived bytes or empty).
  * @task T355
  * @epic T310
@@ -122,9 +144,11 @@ function rowToCredential(row) {
         transportType: (row.transport_type ?? 'http'),
         transportConfig: JSON.parse(row.transport_config),
         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(),
+        // T11622 cutover: `agent_registry_agents` timestamps are TEXT ISO-8601 — read
+        // through as-is (no epoch→ms conversion).
+        lastUsedAt: row.last_used_at ?? undefined,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
     };
 }
 /**
@@ -149,7 +173,7 @@ function coerceTier(value) {
  * 'fallback', canSpawn: false, orchLevel: 2). Callers that need strict
  * migration presence MUST check `row.tier !== undefined` before invoking.
  *
- * @param row - Raw SQLite row from signaldock.db:agents
+ * @param row - Raw SQLite row from cleo.db:agent_registry_agents
  * @returns The extended field block, with safe fallbacks for absent columns
  * @task T897
  * @epic T889
@@ -181,7 +205,7 @@ function rowToExtendedFields(row) {
  * never been bound to a `.cant`). Callers that need a synthesized fallback
  * envelope MUST handle the null return explicitly.
  *
- * @param row - Raw agents row from signaldock.db
+ * @param row - Raw agent_registry_agents row from the global cleo.db
  * @returns A ResolvedAgent envelope, or null when provenance is missing
  * @task T897
  * @epic T889
@@ -209,7 +233,7 @@ export function rowToResolvedAgent(row) {
  * 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 agentRow - Row from global cleo.db:agent_registry_agents.
  * @param refRow   - Row from conduit.db:project_agent_refs, or null.
  * @returns Merged `AgentWithProjectOverride`.
  * @task T355
@@ -225,16 +249,43 @@ function mergeToAgentWithOverride(agentRow, refRow) {
 // 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.
+ * Acquire the SHARED, fully-migrated handle to the GLOBAL agent identity DB —
+ * the consolidated dual-scope global `cleo.db` (post-E6-L5 / T11525).
+ *
+ * Routes through {@link ensureGlobalAgentRegistryDb}, which opens the consolidated
+ * `cleo.db` via `openDualScopeDb('global')` (whose consolidated cleo-global
+ * migration creates the prefixed `agent_registry_*` tables this accessor's raw SQL
+ * now queries, post-T11622 cutover), reconciles the health-probe ledger, and
+ * stores the native handle for reuse. The returned handle is the SAME one the
+ * write path uses — reads and writes are aligned to `cleo.db` (T11562).
+ *
+ * Replaces the previous `new DatabaseSync(getGlobalAgentRegistryDbPath())` raw-open,
+ * which diverged from the write path (T11562).
+ *
+ * The handle is SHARED and co-owned by the nexus / skills global domains — its
+ * lifecycle is owned by `openDualScopeDb`. Callers MUST NOT call `db.close()` on
+ * it (doing so would break in-flight sibling queries). This is why every former
+ * `globalDb.close()` in this module was removed (T11562).
  *
+ * @returns The shared consolidated global `cleo.db` native handle.
+ * @throws {Error} If the shared handle is unexpectedly absent after ensure.
  * @task T355
+ * @task T11562
  * @epic T310
+ * @epic T11249
  */
-function openGlobalDb() {
-    const dbPath = getGlobalSignaldockDbPath();
-    const db = new DatabaseSync(dbPath);
-    applyPerfPragmas(db); // replaces inline PRAGMA calls with SSoT set (T9023)
+async function openGlobalDb() {
+    // Idempotent: opens the consolidated global cleo.db, runs the legacy
+    // (the consolidated cleo-global migration creates the agent_registry_* tables),
+    // and caches the shared native handle (T11622 cutover).
+    await ensureGlobalAgentRegistryDb();
+    const db = getGlobalAgentRegistryNativeDb();
+    if (!db) {
+        throw new Error('openGlobalDb: ensureGlobalAgentRegistryDb() did not yield a shared global ' +
+            'cleo.db handle (getGlobalAgentRegistryNativeDb() returned null). This indicates ' +
+            'the dual-scope global chokepoint failed to initialize — fix the caller, do ' +
+            'not suppress.');
+    }
     return db;
 }
 /**
@@ -252,13 +303,13 @@ function openConduitDb(projectRoot) {
     return db;
 }
 // ---------------------------------------------------------------------------
-// junction table sync (global signaldock.db only)
+// junction table sync (global cleo.db (Agent Registry) only)
 // ---------------------------------------------------------------------------
 /**
- * Sync capabilities/skills to junction tables in global signaldock.db.
+ * Sync capabilities/skills to junction tables in global cleo.db (Agent Registry).
  * Junction tables are the SSoT — JSON columns are a materialized cache.
  *
- * @param db         - Open handle to global signaldock.db.
+ * @param db         - Open handle to global cleo.db (Agent Registry).
  * @param agentUuid  - The `id` (UUID primary key) from the agents row.
  * @param capabilities - Array of capability slugs.
  * @param skills       - Array of skill slugs.
@@ -266,18 +317,20 @@ function openConduitDb(projectRoot) {
  * @epic T310
  */
 function syncJunctionTables(db, agentUuid, capabilities, skills) {
-    db.prepare('DELETE FROM agent_capabilities WHERE agent_id = ?').run(agentUuid);
-    db.prepare('DELETE FROM agent_skills WHERE agent_id = ?').run(agentUuid);
+    db.prepare('DELETE FROM agent_registry_agent_capabilities WHERE agent_id = ?').run(agentUuid);
+    db.prepare('DELETE FROM agent_registry_agent_skills WHERE agent_id = ?').run(agentUuid);
     for (const cap of capabilities) {
-        const capRow = db.prepare('SELECT id FROM capabilities WHERE slug = ?').get(cap);
+        const capRow = db
+            .prepare('SELECT id FROM agent_registry_capabilities WHERE slug = ?')
+            .get(cap);
         if (capRow) {
-            db.prepare('INSERT OR IGNORE INTO agent_capabilities (agent_id, capability_id) VALUES (?, ?)').run(agentUuid, capRow.id);
+            db.prepare('INSERT OR IGNORE INTO agent_registry_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);
+        const skillRow = db.prepare('SELECT id FROM agent_registry_skills WHERE slug = ?').get(skill);
         if (skillRow) {
-            db.prepare('INSERT OR IGNORE INTO agent_skills (agent_id, skill_id) VALUES (?, ?)').run(agentUuid, skillRow.id);
+            db.prepare('INSERT OR IGNORE INTO agent_registry_agent_skills (agent_id, skill_id) VALUES (?, ?)').run(agentUuid, skillRow.id);
         }
     }
 }
@@ -285,7 +338,7 @@ function syncJunctionTables(db, agentUuid, capabilities, skills) {
 // Module-level cross-DB functions (spec §3.5)
 // ---------------------------------------------------------------------------
 /**
- * Cross-DB agent lookup. Opens both the global signaldock.db and the
+ * Cross-DB agent lookup. Opens both the global cleo.db (Agent Registry) and the
  * current project's conduit.db, joins project_agent_refs ⨝ agents by
  * agentId, and returns the merged view.
  *
@@ -299,27 +352,42 @@ function syncJunctionTables(db, agentUuid, capabilities, skills) {
  * Dangling soft-FK detection: if a project_agent_refs row exists but the
  * referenced global agent does not, logs a WARN and returns null.
  *
+ * Both `agents` (global) and `project_agent_refs` (project) tables are
+ * materialized into their consolidated `cleo.db` files lazily, so this function
+ * ensures both DBs (via the shared `openGlobalDb` / `ensureConduitDb`
+ * chokepoints) before reading — keeping the read path aligned with the write
+ * path (T11562). It is therefore async.
+ *
  * @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
+ * @task T11562
  * @epic T310
+ * @epic T11249
  */
-export function lookupAgent(projectRoot, agentId, opts) {
+export async function lookupAgent(projectRoot, agentId, opts) {
     const includeGlobal = opts?.includeGlobal ?? false;
-    const globalDb = openGlobalDb();
+    // Ensure the consolidated project cleo.db has the prefixed
+    // `conduit_project_agent_refs` table (T11578 · AC4) before the raw-open read
+    // below (mirrors the global side, which is ensured inside openGlobalDb).
+    await ensureConduitDb(projectRoot);
+    // SHARED global cleo.db handle — do NOT close (lifecycle owned by openDualScopeDb).
+    const globalDb = await openGlobalDb();
     const conduitDb = openConduitDb(projectRoot);
     try {
-        const agentRow = globalDb.prepare('SELECT * FROM agents WHERE agent_id = ?').get(agentId);
+        const agentRow = globalDb
+            .prepare('SELECT * FROM agent_registry_agents WHERE agent_id = ?')
+            .get(agentId);
         const refRow = conduitDb
-            .prepare('SELECT * FROM project_agent_refs WHERE agent_id = ?')
+            .prepare('SELECT * FROM conduit_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.`);
+                `No matching row in global cleo.db:agents. Row will be ignored.`);
             return null;
         }
         // Agent does not exist globally at all
@@ -336,7 +404,7 @@ export function lookupAgent(projectRoot, agentId, opts) {
         return mergeToAgentWithOverride(agentRow, effectiveRef);
     }
     finally {
-        globalDb.close();
+        // NOTE: globalDb is the SHARED dual-scope handle — never close it (T11562).
         conduitDb.close();
     }
 }
@@ -352,25 +420,38 @@ export function lookupAgent(projectRoot, agentId, opts) {
  * includeDisabled=true: also returns agents with enabled=0 in project_agent_refs.
  * Ignored when includeGlobal=true (all global agents are returned regardless).
  *
+ * Both `agents` (global) and `project_agent_refs` (project) tables are
+ * materialized into their consolidated `cleo.db` files lazily, so this function
+ * ensures both DBs (via the shared `openGlobalDb` / `ensureConduitDb`
+ * chokepoints) before reading — keeping the read path aligned with the write
+ * path (T11562). It is therefore async.
+ *
  * @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
+ * @task T11562
  * @epic T310
+ * @epic T11249
  */
-export function listAgentsForProject(projectRoot, opts) {
+export async function listAgentsForProject(projectRoot, opts) {
     const includeGlobal = opts?.includeGlobal ?? false;
     const includeDisabled = opts?.includeDisabled ?? false;
-    const globalDb = openGlobalDb();
+    // Ensure the consolidated project cleo.db has the prefixed
+    // `conduit_project_agent_refs` table (T11578 · AC4) before the raw-open read
+    // below (mirrors the global side, which is ensured inside openGlobalDb).
+    await ensureConduitDb(projectRoot);
+    // SHARED global cleo.db handle — do NOT close (lifecycle owned by openDualScopeDb).
+    const globalDb = await openGlobalDb();
     const conduitDb = openConduitDb(projectRoot);
     try {
         const allAgents = globalDb
-            .prepare('SELECT * FROM agents ORDER BY name ASC')
+            .prepare('SELECT * FROM agent_registry_agents ORDER BY name ASC')
             .all();
         const allRefs = conduitDb
-            .prepare('SELECT * FROM project_agent_refs')
+            .prepare('SELECT * FROM conduit_project_agent_refs')
             .all();
         // Build a map from agentId → ref row for O(1) lookup during join
         const refMap = new Map();
@@ -397,12 +478,12 @@ export function listAgentsForProject(projectRoot, opts) {
         return result;
     }
     finally {
-        globalDb.close();
+        // NOTE: globalDb is the SHARED dual-scope handle — never close it (T11562).
         conduitDb.close();
     }
 }
 /**
- * Creates a new agent: writes identity row to global signaldock.db AND attaches
+ * Creates a new agent: writes identity row to global cleo.db (Agent Registry) 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,
@@ -417,9 +498,12 @@ export function listAgentsForProject(projectRoot, opts) {
  * @task T355
  * @epic T310
  */
-export function createProjectAgent(projectRoot, spec) {
-    ensureGlobalSignaldockDb();
-    ensureConduitDb(projectRoot);
+export async function createProjectAgent(projectRoot, spec) {
+    // E6-L3 (T11523): ensureConduitDb is now async (routes through the dual-scope
+    // cleo.db chokepoint). ensureGlobalAgentRegistryDb is already async. Await both so
+    // the bare schema exists before the short-lived raw handles below read/write it.
+    await ensureGlobalAgentRegistryDb();
+    await ensureConduitDb(projectRoot);
     const nowTs = Math.floor(Date.now() / 1000);
     const nowIso = new Date(nowTs * 1000).toISOString();
     // Derive API key using the T310 KDF
@@ -432,52 +516,53 @@ export function createProjectAgent(projectRoot, spec) {
     });
     // Store as hex string in the encrypted column
     const apiKeyEncrypted = derivedKey.toString('hex');
-    const globalDb = openGlobalDb();
-    try {
+    // SHARED global cleo.db handle — do NOT close (lifecycle owned by openDualScopeDb).
+    const globalDb = await openGlobalDb();
+    {
         const existing = globalDb
-            .prepare('SELECT id FROM agents WHERE agent_id = ?')
+            .prepare('SELECT id FROM agent_registry_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,
+                .prepare(`INSERT INTO agent_registry_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);
+                .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, 
+            // T11622 cutover: TEXT ISO-8601 to satisfy the consolidated GLOB CHECK.
+            spec.lastUsedAt ? new Date(spec.lastUsedAt).toISOString() : null, nowIso, nowIso);
             syncJunctionTables(globalDb, agentUuid, spec.capabilities, spec.skills);
         }
         else {
             agentUuid = existing.id;
             // Update identity in global DB (idempotent re-register)
             globalDb
-                .prepare(`UPDATE agents SET name = ?, class = ?, privacy_tier = ?, capabilities = ?, skills = ?,
+                .prepare(`UPDATE agent_registry_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);
+                .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, nowIso, spec.agentId);
             syncJunctionTables(globalDb, agentUuid, spec.capabilities, spec.skills);
         }
     }
-    finally {
-        globalDb.close();
-    }
+    // NOTE: globalDb is the SHARED dual-scope handle — never close it (T11562).
     // 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 = ?')
+            .prepare('SELECT agent_id, enabled FROM conduit_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)
+                .prepare(`INSERT INTO conduit_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 = ?`)
+                .prepare(`UPDATE conduit_project_agent_refs SET enabled = 1, attached_at = ? WHERE agent_id = ?`)
                 .run(nowIso, spec.agentId);
         }
         // If enabled=1 already, leave the existing ref intact
@@ -485,7 +570,7 @@ export function createProjectAgent(projectRoot, spec) {
     finally {
         conduitDb.close();
     }
-    const result = lookupAgent(projectRoot, spec.agentId, { includeGlobal: false });
+    const result = await lookupAgent(projectRoot, spec.agentId, { includeGlobal: false });
     if (!result) {
         throw new Error(`createProjectAgent: failed to retrieve agent after creation: ${spec.agentId}`);
     }
@@ -501,7 +586,7 @@ export function createProjectAgent(projectRoot, spec) {
  * with `enabled=0`, it is re-enabled (idempotent). If the row already has
  * `enabled=1`, this is a no-op.
  *
- * The agent MUST already exist in the global `signaldock.db:agents` table.
+ * The agent MUST already exist in the global `cleo.db:agent_registry_agents` table.
  * This function does NOT validate global existence — callers must check via
  * `lookupAgent(..., { includeGlobal: true })` first.
  *
@@ -518,17 +603,17 @@ export function attachAgentToProject(projectRoot, agentId, opts) {
     const nowIso = new Date().toISOString();
     try {
         const existingRef = conduitDb
-            .prepare('SELECT agent_id, enabled FROM project_agent_refs WHERE agent_id = ?')
+            .prepare('SELECT agent_id, enabled FROM conduit_project_agent_refs WHERE agent_id = ?')
             .get(agentId);
         if (!existingRef) {
             conduitDb
-                .prepare(`INSERT INTO project_agent_refs (agent_id, attached_at, role, capabilities_override, last_used_at, enabled)
+                .prepare(`INSERT INTO conduit_project_agent_refs (agent_id, attached_at, role, capabilities_override, last_used_at, enabled)
            VALUES (?, ?, ?, ?, NULL, 1)`)
                 .run(agentId, nowIso, opts?.role ?? null, opts?.capabilitiesOverride ?? null);
         }
         else if (existingRef.enabled === 0) {
             conduitDb
-                .prepare(`UPDATE project_agent_refs SET enabled = 1, attached_at = ?, role = ?, capabilities_override = ? WHERE agent_id = ?`)
+                .prepare(`UPDATE conduit_project_agent_refs SET enabled = 1, attached_at = ?, role = ?, capabilities_override = ? WHERE agent_id = ?`)
                 .run(nowIso, opts?.role ?? null, opts?.capabilitiesOverride ?? null, agentId);
         }
         // enabled=1 already — no-op
@@ -540,7 +625,7 @@ export function attachAgentToProject(projectRoot, agentId, opts) {
 /**
  * Detach an agent from the current project by setting `project_agent_refs.enabled=0`.
  *
- * This is a soft-delete: the global `signaldock.db:agents` row is preserved.
+ * This is a soft-delete: the global `cleo.db:agent_registry_agents` row is preserved.
  * The agent can be re-attached later via `attachAgentToProject`.
  *
  * Returns `false` if no row exists in `project_agent_refs` for the given agentId
@@ -557,11 +642,13 @@ export function detachAgentFromProject(projectRoot, agentId) {
     const conduitDb = openConduitDb(projectRoot);
     try {
         const ref = conduitDb
-            .prepare('SELECT agent_id FROM project_agent_refs WHERE agent_id = ?')
+            .prepare('SELECT agent_id FROM conduit_project_agent_refs WHERE agent_id = ?')
             .get(agentId);
         if (!ref)
             return false;
-        conduitDb.prepare('UPDATE project_agent_refs SET enabled = 0 WHERE agent_id = ?').run(agentId);
+        conduitDb
+            .prepare('UPDATE conduit_project_agent_refs SET enabled = 0 WHERE agent_id = ?')
+            .run(agentId);
         return true;
     }
     finally {
@@ -584,7 +671,7 @@ export function getProjectAgentRef(projectRoot, agentId) {
     const conduitDb = openConduitDb(projectRoot);
     try {
         const row = conduitDb
-            .prepare('SELECT * FROM project_agent_refs WHERE agent_id = ?')
+            .prepare('SELECT * FROM conduit_project_agent_refs WHERE agent_id = ?')
             .get(agentId);
         if (!row)
             return null;
@@ -625,12 +712,14 @@ export class AgentRegistryAccessor {
      * @task T355
      * @epic T310
      */
-    ensureDbs() {
-        ensureGlobalSignaldockDb();
-        ensureConduitDb(this.projectPath);
+    async ensureDbs() {
+        // E6-L3 (T11523): ensureConduitDb is now async (dual-scope cleo.db
+        // chokepoint); ensureGlobalAgentRegistryDb is already async. Await both.
+        await ensureGlobalAgentRegistryDb();
+        await ensureConduitDb(this.projectPath);
     }
     /**
-     * Register (create or update) an agent in global signaldock.db and attach
+     * Register (create or update) an agent in global cleo.db (Agent Registry) and attach
      * it to the current project via conduit.db:project_agent_refs.
      *
      * @param credential - Agent spec (without createdAt/updatedAt).
@@ -639,7 +728,7 @@ export class AgentRegistryAccessor {
      * @epic T310
      */
     async register(credential) {
-        this.ensureDbs();
+        await this.ensureDbs();
         return createProjectAgent(this.projectPath, credential);
     }
     /**
@@ -652,7 +741,7 @@ export class AgentRegistryAccessor {
      * @epic T310
      */
     async get(agentId, opts) {
-        this.ensureDbs();
+        await this.ensureDbs();
         return lookupAgent(this.projectPath, agentId, opts);
     }
     /**
@@ -664,8 +753,8 @@ export class AgentRegistryAccessor {
      * @epic T310
      */
     async list(filter) {
-        this.ensureDbs();
-        const results = listAgentsForProject(this.projectPath, { includeGlobal: false });
+        await this.ensureDbs();
+        const results = await listAgentsForProject(this.projectPath, { includeGlobal: false });
         if (filter?.active !== undefined) {
             return results.filter((a) => a.isActive === filter.active);
         }
@@ -680,24 +769,20 @@ export class AgentRegistryAccessor {
      * @epic T310
      */
     async listGlobal(filter) {
-        this.ensureDbs();
-        const globalDb = openGlobalDb();
-        try {
-            const rows = filter?.active !== undefined
-                ? globalDb
-                    .prepare('SELECT * FROM agents WHERE is_active = ? ORDER BY name ASC')
-                    .all(filter.active ? 1 : 0)
-                : globalDb
-                    .prepare('SELECT * FROM agents ORDER BY name ASC')
-                    .all();
-            return rows.map(rowToCredential);
-        }
-        finally {
-            globalDb.close();
-        }
+        await this.ensureDbs();
+        // SHARED global cleo.db handle — do NOT close (lifecycle owned by openDualScopeDb).
+        const globalDb = await openGlobalDb();
+        const rows = filter?.active !== undefined
+            ? globalDb
+                .prepare('SELECT * FROM agent_registry_agents WHERE is_active = ? ORDER BY name ASC')
+                .all(filter.active ? 1 : 0)
+            : globalDb
+                .prepare('SELECT * FROM agent_registry_agents ORDER BY name ASC')
+                .all();
+        return rows.map(rowToCredential);
     }
     /**
-     * Update agent identity fields in global signaldock.db.
+     * Update agent identity fields in global cleo.db (Agent Registry).
      * Project-specific fields (role, capabilitiesOverride) require direct
      * conduit.db manipulation (not yet exposed by this method).
      *
@@ -708,15 +793,17 @@ export class AgentRegistryAccessor {
      * @epic T310
      */
     async update(agentId, updates) {
-        this.ensureDbs();
+        await 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 globalDb = openGlobalDb();
-        try {
+        // T11622 cutover: `agent_registry_agents.updated_at` is TEXT ISO-8601 (GLOB CHECK).
+        const nowIso = new Date().toISOString();
+        // SHARED global cleo.db handle — do NOT close (lifecycle owned by openDualScopeDb).
+        const globalDb = await openGlobalDb();
+        {
             const sets = ['updated_at = ?'];
-            const params = [nowTs];
+            const params = [nowIso];
             if (updates.displayName !== undefined) {
                 sets.push('name = ?');
                 params.push(updates.displayName);
@@ -763,21 +850,19 @@ export class AgentRegistryAccessor {
             }
             params.push(agentId);
             globalDb
-                .prepare(`UPDATE agents SET ${sets.join(', ')} WHERE agent_id = ?`)
+                .prepare(`UPDATE agent_registry_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 = globalDb
-                    .prepare('SELECT id FROM agents WHERE agent_id = ?')
+                    .prepare('SELECT id FROM agent_registry_agents WHERE agent_id = ?')
                     .get(agentId);
                 if (agentRow) {
                     syncJunctionTables(globalDb, agentRow.id, updates.capabilities ?? existing.capabilities, updates.skills ?? existing.skills);
                 }
             }
         }
-        finally {
-            globalDb.close();
-        }
+        // NOTE: globalDb is the SHARED dual-scope handle — never close it (T11562).
         const result = await this.get(agentId, { includeGlobal: true });
         if (!result)
             throw new Error(`Agent not found after update: ${agentId}`);
@@ -785,24 +870,24 @@ export class AgentRegistryAccessor {
     }
     /**
      * Remove agent from current project (sets project_agent_refs.enabled=0).
-     * Does NOT delete from global signaldock.db (per ADR-037 §6 / Q4=C).
+     * Does NOT delete from global cleo.db (Agent Registry) (per ADR-037 §6 / Q4=C).
      *
      * @param agentId - Agent business identifier.
      * @task T355
      * @epic T310
      */
     async remove(agentId) {
-        this.ensureDbs();
+        await this.ensureDbs();
         const conduitDb = openConduitDb(this.projectPath);
         try {
             const ref = conduitDb
-                .prepare('SELECT agent_id FROM project_agent_refs WHERE agent_id = ?')
+                .prepare('SELECT agent_id FROM conduit_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 = ?')
+                .prepare('UPDATE conduit_project_agent_refs SET enabled = 0 WHERE agent_id = ?')
                 .run(agentId);
         }
         finally {
@@ -810,7 +895,7 @@ export class AgentRegistryAccessor {
         }
     }
     /**
-     * Remove agent from global signaldock.db.
+     * Remove agent from global cleo.db (Agent Registry).
      * Requires explicit opt-in. Warns if cross-project refs may exist.
      *
      * @param agentId     - Agent business identifier.
@@ -819,38 +904,37 @@ export class AgentRegistryAccessor {
      * @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();
+        await this.ensureDbs();
+        // SHARED global cleo.db handle — do NOT close (lifecycle owned by openDualScopeDb).
+        const globalDb = await openGlobalDb();
+        const existing = globalDb
+            .prepare('SELECT id FROM agent_registry_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 conduit_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.`);
                 }
             }
-            globalDb.prepare('DELETE FROM agents WHERE agent_id = ?').run(agentId);
-        }
-        finally {
-            globalDb.close();
+            finally {
+                conduitDb.close();
+            }
         }
+        globalDb.prepare('DELETE FROM agent_registry_agents WHERE agent_id = ?').run(agentId);
+        // NOTE: globalDb is the SHARED dual-scope handle — never close it (T11562).
     }
     /**
      * Rotate API key via cloud endpoint and re-encrypt with the new T310 KDF
-     * in global signaldock.db.
+     * in global cleo.db (Agent Registry).
      *
      * @param agentId - Agent business identifier.
      * @returns Object with agentId and a redacted new API key string.
@@ -858,7 +942,7 @@ export class AgentRegistryAccessor {
      * @epic T310
      */
     async rotateKey(agentId) {
-        this.ensureDbs();
+        await this.ensureDbs();
         const credential = await this.get(agentId, { includeGlobal: true });
         if (!credential)
             throw new Error(`Agent not found: ${agentId}`);
@@ -880,16 +964,14 @@ export class AgentRegistryAccessor {
         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();
-        }
+        // T11622 cutover: `updated_at` is TEXT ISO-8601 (GLOB CHECK).
+        const nowIso = new Date().toISOString();
+        // SHARED global cleo.db handle — do NOT close (lifecycle owned by openDualScopeDb).
+        const globalDb = await openGlobalDb();
+        globalDb
+            .prepare('UPDATE agent_registry_agents SET api_key_encrypted = ?, updated_at = ?, requires_reauth = 0 WHERE agent_id = ?')
+            .run(derivedKey.toString('hex'), nowIso, agentId);
+        // NOTE: globalDb is the SHARED dual-scope handle — never close it (T11562).
         return { agentId, newApiKey: `${newApiKey.substring(0, 8)}...rotated` };
     }
     /**
@@ -900,36 +982,37 @@ export class AgentRegistryAccessor {
      * @epic T310
      */
     async getActive() {
-        this.ensureDbs();
-        const globalDb = openGlobalDb();
+        await this.ensureDbs();
+        // SHARED global cleo.db handle — do NOT close (lifecycle owned by openDualScopeDb).
+        const globalDb = await openGlobalDb();
         const conduitDb = openConduitDb(this.projectPath);
         try {
             // 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')
+                .prepare('SELECT agent_id, last_used_at FROM conduit_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')
+                    .prepare('SELECT * FROM agent_registry_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')
+                .prepare('SELECT * FROM agent_registry_agents WHERE is_active = 1 ORDER BY last_used_at DESC, created_at DESC LIMIT 1')
                 .get();
             if (!row)
                 return null;
             return rowToCredential(row);
         }
         finally {
-            globalDb.close();
+            // NOTE: globalDb is the SHARED dual-scope handle — never close it (T11562).
             conduitDb.close();
         }
     }
     /**
-     * Update last_used_at in both global signaldock.db:agents and
+     * Update last_used_at in both global cleo.db:agent_registry_agents and
      * conduit.db:project_agent_refs.
      *
      * @param agentId - Agent business identifier.
@@ -937,22 +1020,20 @@ export class AgentRegistryAccessor {
      * @epic T310
      */
     async markUsed(agentId) {
-        this.ensureDbs();
-        const nowTs = Math.floor(Date.now() / 1000);
-        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();
-        }
+        await this.ensureDbs();
+        // T11622 cutover: `last_used_at` / `updated_at` are TEXT ISO-8601 (GLOB CHECK)
+        // in `agent_registry_agents`; `conduit_project_agent_refs.last_used_at` is also ISO.
+        const nowIso = new Date().toISOString();
+        // SHARED global cleo.db handle — do NOT close (lifecycle owned by openDualScopeDb).
+        const globalDb = await openGlobalDb();
+        globalDb
+            .prepare('UPDATE agent_registry_agents SET last_used_at = ?, updated_at = ? WHERE agent_id = ?')
+            .run(nowIso, nowIso, agentId);
+        // NOTE: globalDb is the SHARED dual-scope handle — never close it (T11562).
         const conduitDb = openConduitDb(this.projectPath);
         try {
             conduitDb
-                .prepare('UPDATE project_agent_refs SET last_used_at = ? WHERE agent_id = ?')
+                .prepare('UPDATE conduit_project_agent_refs SET last_used_at = ? WHERE agent_id = ?')
                 .run(nowIso, agentId);
         }
         finally {