@cleocode/core 2026.4.9 → 2026.4.12

package/dist/store/chain-schema.js

@@ -0,0 +1,51 @@
+/**
+ * Drizzle ORM schema for WarpChain storage in tasks.db.
+ *
+ * Tables: warp_chains, warp_chain_instances
+ * Stores chain definitions and runtime instances bound to epics.
+ *
+ * @task T5403
+ */
+import { sql } from 'drizzle-orm';
+import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+/** Chain instance status values. */
+export const WARP_CHAIN_INSTANCE_STATUSES = [
+    'pending',
+    'active',
+    'completed',
+    'failed',
+    'cancelled',
+];
+// === WARP_CHAINS TABLE ===
+/** Stored WarpChain definitions (serialized as JSON). */
+export const warpChains = sqliteTable('warp_chains', {
+    id: text('id').primaryKey(),
+    name: text('name').notNull(),
+    version: text('version').notNull(),
+    description: text('description'),
+    definition: text('definition').notNull(), // JSON-serialized WarpChain
+    validated: integer('validated', { mode: 'boolean' }).default(false),
+    createdAt: text('created_at').default(sql `(datetime('now'))`),
+    updatedAt: text('updated_at').default(sql `(datetime('now'))`),
+}, (table) => [index('idx_warp_chains_name').on(table.name)]);
+// === WARP_CHAIN_INSTANCES TABLE ===
+/** Runtime chain instances bound to epics. */
+export const warpChainInstances = sqliteTable('warp_chain_instances', {
+    id: text('id').primaryKey(),
+    chainId: text('chain_id')
+        .notNull()
+        .references(() => warpChains.id, { onDelete: 'cascade' }),
+    epicId: text('epic_id').notNull(),
+    variables: text('variables'), // JSON
+    stageToTask: text('stage_to_task'), // JSON
+    status: text('status').notNull().default('pending'),
+    currentStage: text('current_stage'),
+    gateResults: text('gate_results'), // JSON array of GateResult
+    createdAt: text('created_at').default(sql `(datetime('now'))`),
+    updatedAt: text('updated_at').default(sql `(datetime('now'))`),
+}, (table) => [
+    index('idx_warp_instances_chain').on(table.chainId),
+    index('idx_warp_instances_epic').on(table.epicId),
+    index('idx_warp_instances_status').on(table.status),
+]);
+//# sourceMappingURL=chain-schema.js.map

package/dist/store/chain-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-schema.js","sourceRoot":"","sources":["../../src/store/chain-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAE5E,oCAAoC;AACpC,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,SAAS;IACT,QAAQ;IACR,WAAW;IACX,QAAQ;IACR,WAAW;CACH,CAAC;AAEX,4BAA4B;AAE5B,yDAAyD;AACzD,MAAM,CAAC,MAAM,UAAU,GAAG,WAAW,CACnC,aAAa,EACb;IACE,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE;IAC3B,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE;IAC5B,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE;IAClC,WAAW,EAAE,IAAI,CAAC,aAAa,CAAC;IAChC,UAAU,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE,EAAE,4BAA4B;IACtE,SAAS,EAAE,OAAO,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACnE,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,GAAG,CAAA,mBAAmB,CAAC;IAC7D,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,GAAG,CAAA,mBAAmB,CAAC;CAC9D,EACD,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAC1D,CAAC;AAEF,qCAAqC;AAErC,8CAA8C;AAC9C,MAAM,CAAC,MAAM,kBAAkB,GAAG,WAAW,CAC3C,sBAAsB,EACtB;IACE,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE;IAC3B,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC;SACtB,OAAO,EAAE;SACT,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;IAC3D,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE;IACjC,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC,EAAE,OAAO;IACrC,WAAW,EAAE,IAAI,CAAC,eAAe,CAAC,EAAE,OAAO;IAC3C,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC;IACnD,YAAY,EAAE,IAAI,CAAC,eAAe,CAAC;IACnC,WAAW,EAAE,IAAI,CAAC,cAAc,CAAC,EAAE,2BAA2B;IAC9D,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,GAAG,CAAA,mBAAmB,CAAC;IAC7D,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,GAAG,CAAA,mBAAmB,CAAC;CAC9D,EACD,CAAC,KAAK,EAAE,EAAE,CAAC;IACT,KAAK,CAAC,0BAA0B,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC;IACnD,KAAK,CAAC,yBAAyB,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC;IACjD,KAAK,CAAC,2BAA2B,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC;CACpD,CACF,CAAC"}

package/dist/store/cleanup-legacy.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Idempotent cleanup of legacy and stray CLEO database files.
+ *
+ * Provides two independent cleanup functions:
+ *
+ * 1. {@link detectAndRemoveLegacyGlobalFiles} — removes stale files left at
+ *    the global CLEO home directory (`getCleoHome()`) by pre-v2026.4.11
+ *    naming migrations. Safe to call on repeat invocations — existence-checks
+ *    guard every deletion.
+ *
+ *    Files targeted (see ADR-036 §Decision/Global-Tier table):
+ *      - workspace.db              (pre-nexus naming relic)
+ *      - workspace.db.bak-pre-rename  (safety copy from a long-landed rename)
+ *      - workspace.db-shm          (SQLite shared-memory sidecar of workspace.db)
+ *      - workspace.db-shm-wal      (SQLite WAL sidecar of workspace.db)
+ *      - nexus-pre-cleo.db.bak     (pre-CLEO backup of nexus — migration complete)
+ *
+ *    Live files (nexus.db, signaldock.db, machine-key, config.json, etc.) are
+ *    NEVER touched. The function only acts on the explicit LEGACY_FILES list.
+ *
+ * 2. {@link detectAndRemoveStrayProjectNexus} — removes a stray
+ *    `{projectRoot}/.cleo/nexus.db` that violates ADR-036's global-only
+ *    nexus contract. Some pre-v2026.4.11 code path accidentally created a
+ *    zero-byte nexus.db at project tier; this cleans it up on first run.
+ *
+ * @task T304
+ * @task T307
+ * @epic T299
+ * @adr ADR-036
+ * @why v2026.4.10 left workspace.db and pre-cleo backups at global tier;
+ *   ADR-036 mandates their deletion to eliminate diagnostic confusion and
+ *   false impressions of active legacy databases.
+ */
+/** Result returned by {@link detectAndRemoveLegacyGlobalFiles}. */
+export interface LegacyCleanupResult {
+    /** Filenames (basename only) that were successfully deleted. */
+    removed: string[];
+    /** Files that could not be deleted, with error messages. */
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+}
+/**
+ * Detect and remove legacy global-tier files from the CLEO home directory.
+ *
+ * Idempotent: safe to call when some or all files are already absent. Each
+ * file is individually existence-checked before attempting deletion. Failures
+ * on individual files are captured in `errors` rather than thrown, so the
+ * caller receives a complete picture of what was (and was not) cleaned up.
+ *
+ * Logs each successful deletion at `info` level and each failure at `warn`
+ * level via the shared pino logger.
+ *
+ * @param cleoHomeOverride - Optional directory override for tests. When
+ *   omitted the canonical `getCleoHome()` path is used. Prefer passing this
+ *   parameter in test harnesses rather than mutating `CLEO_HOME` environment
+ *   variables, as it avoids global state contamination between test runs.
+ * @returns A {@link LegacyCleanupResult} describing what was removed and any
+ *   errors encountered.
+ *
+ * @example
+ * ```typescript
+ * // Production usage (runs against real global home)
+ * const result = detectAndRemoveLegacyGlobalFiles();
+ * if (result.removed.length > 0) {
+ *   // Legacy files were cleaned up
+ * }
+ *
+ * // Test usage (runs against tmp directory)
+ * const result = detectAndRemoveLegacyGlobalFiles('/tmp/fake-cleo-home');
+ * ```
+ *
+ * @task T304
+ * @epic T299
+ */
+export declare function detectAndRemoveLegacyGlobalFiles(cleoHomeOverride?: string): LegacyCleanupResult;
+/** Result returned by {@link detectAndRemoveStrayProjectNexus}. */
+export interface StrayNexusCleanupResult {
+    /** Whether a stray nexus.db was found and deleted. */
+    removed: boolean;
+    /** Absolute path that was checked (and removed if `removed` is true). */
+    path: string;
+}
+/**
+ * Detect and remove a stray project-tier `.cleo/nexus.db` file.
+ *
+ * ADR-036 declares nexus.db as **global-only** — it lives exclusively under
+ * `getCleoHome()` (e.g. `~/.local/share/cleo/nexus.db` on Linux). A
+ * zero-byte stray was discovered at `/mnt/projects/cleocode/.cleo/nexus.db`
+ * (created 2026-03-31), likely produced by an early `cleo init` / `cleo
+ * nexus init` invocation that ran before the canonical path was fully wired
+ * through `getNexusDbPath()`.
+ *
+ * This function is idempotent: calling it when no stray file exists is a
+ * no-op. It is designed to be called once per CLI startup (alongside
+ * {@link detectAndRemoveLegacyGlobalFiles}) so that users who upgrade to
+ * v2026.4.11 have the stray silently cleaned up on the first `cleo` run.
+ *
+ * @param projectRoot - Absolute path to the project root directory. When
+ *   omitted the caller is responsible for supplying the current project
+ *   root from `getProjectRoot()`. An override parameter is accepted here to
+ *   keep tests hermetic (avoids reading live `process.cwd()` state).
+ * @returns A {@link StrayNexusCleanupResult} indicating whether a file was
+ *   removed and the absolute path that was checked.
+ *
+ * @example
+ * ```typescript
+ * // Production usage
+ * import { getProjectRoot } from '../paths.js';
+ * const result = detectAndRemoveStrayProjectNexus(getProjectRoot());
+ * if (result.removed) {
+ *   // Stray project-tier nexus.db has been cleaned up
+ * }
+ *
+ * // Test usage (hermetic)
+ * const result = detectAndRemoveStrayProjectNexus('/tmp/fake-project-root');
+ * ```
+ *
+ * @task T307
+ * @epic T299
+ * @adr ADR-036
+ * @why ADR-036 §Decision/Global-Tier: nexus.db is global-only. A stray
+ *   project-tier copy was created by pre-v2026.4.11 code and must be removed
+ *   to prevent diagnostic confusion and guard against future regressions.
+ */
+export declare function detectAndRemoveStrayProjectNexus(projectRoot: string): StrayNexusCleanupResult;
+//# sourceMappingURL=cleanup-legacy.d.ts.map

package/dist/store/cleanup-legacy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup-legacy.d.ts","sourceRoot":"","sources":["../../src/store/cleanup-legacy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AA6BH,mEAAmE;AACnE,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4DAA4D;IAC5D,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,gCAAgC,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAsB/F;AAMD,mEAAmE;AACnE,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,gCAAgC,CAAC,WAAW,EAAE,MAAM,GAAG,uBAAuB,CAuB7F"}

package/dist/store/cleanup-legacy.js

@@ -0,0 +1,171 @@
+/**
+ * Idempotent cleanup of legacy and stray CLEO database files.
+ *
+ * Provides two independent cleanup functions:
+ *
+ * 1. {@link detectAndRemoveLegacyGlobalFiles} — removes stale files left at
+ *    the global CLEO home directory (`getCleoHome()`) by pre-v2026.4.11
+ *    naming migrations. Safe to call on repeat invocations — existence-checks
+ *    guard every deletion.
+ *
+ *    Files targeted (see ADR-036 §Decision/Global-Tier table):
+ *      - workspace.db              (pre-nexus naming relic)
+ *      - workspace.db.bak-pre-rename  (safety copy from a long-landed rename)
+ *      - workspace.db-shm          (SQLite shared-memory sidecar of workspace.db)
+ *      - workspace.db-shm-wal      (SQLite WAL sidecar of workspace.db)
+ *      - nexus-pre-cleo.db.bak     (pre-CLEO backup of nexus — migration complete)
+ *
+ *    Live files (nexus.db, signaldock.db, machine-key, config.json, etc.) are
+ *    NEVER touched. The function only acts on the explicit LEGACY_FILES list.
+ *
+ * 2. {@link detectAndRemoveStrayProjectNexus} — removes a stray
+ *    `{projectRoot}/.cleo/nexus.db` that violates ADR-036's global-only
+ *    nexus contract. Some pre-v2026.4.11 code path accidentally created a
+ *    zero-byte nexus.db at project tier; this cleans it up on first run.
+ *
+ * @task T304
+ * @task T307
+ * @epic T299
+ * @adr ADR-036
+ * @why v2026.4.10 left workspace.db and pre-cleo backups at global tier;
+ *   ADR-036 mandates their deletion to eliminate diagnostic confusion and
+ *   false impressions of active legacy databases.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getLogger } from '../logger.js';
+import { getCleoHome } from '../paths.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Exhaustive list of legacy filenames that MUST be removed from the global
+ * CLEO home directory. No other files are touched.
+ *
+ * @task T304
+ */
+const LEGACY_FILES = [
+    'workspace.db',
+    'workspace.db.bak-pre-rename',
+    'workspace.db-shm',
+    'workspace.db-shm-wal',
+    'nexus-pre-cleo.db.bak',
+];
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Detect and remove legacy global-tier files from the CLEO home directory.
+ *
+ * Idempotent: safe to call when some or all files are already absent. Each
+ * file is individually existence-checked before attempting deletion. Failures
+ * on individual files are captured in `errors` rather than thrown, so the
+ * caller receives a complete picture of what was (and was not) cleaned up.
+ *
+ * Logs each successful deletion at `info` level and each failure at `warn`
+ * level via the shared pino logger.
+ *
+ * @param cleoHomeOverride - Optional directory override for tests. When
+ *   omitted the canonical `getCleoHome()` path is used. Prefer passing this
+ *   parameter in test harnesses rather than mutating `CLEO_HOME` environment
+ *   variables, as it avoids global state contamination between test runs.
+ * @returns A {@link LegacyCleanupResult} describing what was removed and any
+ *   errors encountered.
+ *
+ * @example
+ * ```typescript
+ * // Production usage (runs against real global home)
+ * const result = detectAndRemoveLegacyGlobalFiles();
+ * if (result.removed.length > 0) {
+ *   // Legacy files were cleaned up
+ * }
+ *
+ * // Test usage (runs against tmp directory)
+ * const result = detectAndRemoveLegacyGlobalFiles('/tmp/fake-cleo-home');
+ * ```
+ *
+ * @task T304
+ * @epic T299
+ */
+export function detectAndRemoveLegacyGlobalFiles(cleoHomeOverride) {
+    const log = getLogger('cleanup-legacy');
+    const cleoHome = cleoHomeOverride ?? getCleoHome();
+    const removed = [];
+    const errors = [];
+    for (const fileName of LEGACY_FILES) {
+        const fullPath = path.join(cleoHome, fileName);
+        try {
+            if (fs.existsSync(fullPath)) {
+                fs.unlinkSync(fullPath);
+                removed.push(fileName);
+                log.info({ file: fullPath }, 'Removed legacy global file');
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            errors.push({ file: fileName, error: message });
+            log.warn({ file: fullPath, error: message }, 'Failed to remove legacy global file');
+        }
+    }
+    return { removed, errors };
+}
+/**
+ * Detect and remove a stray project-tier `.cleo/nexus.db` file.
+ *
+ * ADR-036 declares nexus.db as **global-only** — it lives exclusively under
+ * `getCleoHome()` (e.g. `~/.local/share/cleo/nexus.db` on Linux). A
+ * zero-byte stray was discovered at `/mnt/projects/cleocode/.cleo/nexus.db`
+ * (created 2026-03-31), likely produced by an early `cleo init` / `cleo
+ * nexus init` invocation that ran before the canonical path was fully wired
+ * through `getNexusDbPath()`.
+ *
+ * This function is idempotent: calling it when no stray file exists is a
+ * no-op. It is designed to be called once per CLI startup (alongside
+ * {@link detectAndRemoveLegacyGlobalFiles}) so that users who upgrade to
+ * v2026.4.11 have the stray silently cleaned up on the first `cleo` run.
+ *
+ * @param projectRoot - Absolute path to the project root directory. When
+ *   omitted the caller is responsible for supplying the current project
+ *   root from `getProjectRoot()`. An override parameter is accepted here to
+ *   keep tests hermetic (avoids reading live `process.cwd()` state).
+ * @returns A {@link StrayNexusCleanupResult} indicating whether a file was
+ *   removed and the absolute path that was checked.
+ *
+ * @example
+ * ```typescript
+ * // Production usage
+ * import { getProjectRoot } from '../paths.js';
+ * const result = detectAndRemoveStrayProjectNexus(getProjectRoot());
+ * if (result.removed) {
+ *   // Stray project-tier nexus.db has been cleaned up
+ * }
+ *
+ * // Test usage (hermetic)
+ * const result = detectAndRemoveStrayProjectNexus('/tmp/fake-project-root');
+ * ```
+ *
+ * @task T307
+ * @epic T299
+ * @adr ADR-036
+ * @why ADR-036 §Decision/Global-Tier: nexus.db is global-only. A stray
+ *   project-tier copy was created by pre-v2026.4.11 code and must be removed
+ *   to prevent diagnostic confusion and guard against future regressions.
+ */
+export function detectAndRemoveStrayProjectNexus(projectRoot) {
+    const log = getLogger('cleanup-legacy');
+    const strayPath = path.join(projectRoot, '.cleo', 'nexus.db');
+    if (fs.existsSync(strayPath)) {
+        try {
+            fs.unlinkSync(strayPath);
+            log.warn({ path: strayPath }, 'Removed stray project-tier nexus.db (violates ADR-036 global-only contract)');
+            return { removed: true, path: strayPath };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log.warn({ path: strayPath, error: message }, 'Failed to remove stray project-tier nexus.db — manual deletion may be required');
+            return { removed: false, path: strayPath };
+        }
+    }
+    return { removed: false, path: strayPath };
+}
+//# sourceMappingURL=cleanup-legacy.js.map

package/dist/store/cleanup-legacy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup-legacy.js","sourceRoot":"","sources":["../../src/store/cleanup-legacy.ts"],"names":[],"mappings":"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"}

package/dist/store/conduit-sqlite.d.ts

@@ -0,0 +1,184 @@
+/**
+ * SQLite store for conduit.db — project-tier messaging and agent-ref database.
+ *
+ * Creates and manages .cleo/conduit.db using node:sqlite directly.
+ * Applies the full conduit.db DDL (from spec §2.1) to bootstrap all
+ * project-local messaging tables and the project_agent_refs override table.
+ *
+ * Architecture (ADR-037):
+ *   conduit.db   — project-scoped (this module) — messaging, delivery, attachments,
+ *                  project_agent_refs
+ *   signaldock.db — global-scoped (T346) — agents, capabilities, cloud-sync tables
+ *
+ * CRUD accessors for project_agent_refs land in T353.
+ * Cross-DB join accessor changes land in T355.
+ * Migration executor from signaldock.db → conduit.db lands in T358.
+ *
+ * @task T344
+ * @epic T310
+ * @why ADR-037 splits single signaldock.db into project-tier conduit.db
+ *      (this module) and global-tier signaldock.db (T346). This module owns
+ *      the project-tier path helper, initializer, schema DDL, and health check.
+ * @what Path helper, database initializer, schema applier, health check, and
+ *       native DB accessor for project-local tables. No CRUD, no migrations.
+ */
+import type { DatabaseSync as _DatabaseSyncType } from 'node:sqlite';
+import type { ProjectAgentRef } from '@cleocode/contracts';
+type DatabaseSync = _DatabaseSyncType;
+declare const DatabaseSync: new (path: import("fs").PathLike, options?: import("node:sqlite").DatabaseSyncOptions | undefined) => DatabaseSync;
+/** Database file name within .cleo/ directory. */
+export declare const CONDUIT_DB_FILENAME = "conduit.db";
+/** Schema version for conduit.db — updated when DDL changes. */
+export declare const CONDUIT_SCHEMA_VERSION = "2026.4.12";
+/**
+ * Returns the project-tier conduit.db path.
+ *
+ * Always resolves to `<projectRoot>/.cleo/conduit.db`. The caller is
+ * responsible for supplying the absolute project root (e.g. via
+ * `getProjectRoot()` from `../paths.js`).
+ *
+ * @task T344
+ * @epic T310
+ * @param projectRoot - Absolute path to the project root directory.
+ * @returns Absolute path to `<projectRoot>/.cleo/conduit.db`.
+ */
+export declare function getConduitDbPath(projectRoot: string): string;
+/**
+ * Applies the conduit.db schema idempotently using CREATE TABLE IF NOT EXISTS.
+ *
+ * Exposed for the migration executor (T358) which needs to apply the schema
+ * to a newly created conduit.db during the signaldock.db → conduit.db
+ * migration. Also called internally by `ensureConduitDb` on every open.
+ *
+ * @task T344
+ * @epic T310
+ * @param db - An open node:sqlite DatabaseSync instance.
+ */
+export declare function applyConduitSchema(db: DatabaseSync): void;
+/**
+ * Opens or creates conduit.db for the given project root.
+ *
+ * On first call for a given projectRoot:
+ *   1. Creates `<projectRoot>/.cleo/` directory if missing.
+ *   2. Opens (or creates) the SQLite file.
+ *   3. Sets WAL mode and enables foreign keys.
+ *   4. Applies all DDL via `applyConduitSchema` (idempotent).
+ *   5. Records `schema_version` in `_conduit_meta`.
+ *   6. Records the initial migration in `_conduit_migrations`.
+ *   7. Stores the open handle in the module singleton.
+ *
+ * On subsequent calls the existing singleton is returned immediately if the
+ * resolved path matches; otherwise the previous handle is closed and a new
+ * one is opened (test-isolation safety).
+ *
+ * Caller MUST call `closeConduitDb()` when done to release the handle.
+ *
+ * @task T344
+ * @epic T310
+ * @param projectRoot - Absolute path to the project root directory.
+ * @returns Object with `action` (`'created'` | `'exists'`) and `path`.
+ */
+export declare function ensureConduitDb(projectRoot: string): {
+    action: 'created' | 'exists';
+    path: string;
+};
+/**
+ * Returns the live node:sqlite DatabaseSync handle for conduit.db.
+ *
+ * Returns `null` if `ensureConduitDb` has not been called yet for this
+ * process, or if `closeConduitDb` has been called since the last open.
+ *
+ * @task T344
+ * @epic T310
+ * @returns The open DatabaseSync instance, or `null` if not initialized.
+ */
+export declare function getConduitNativeDb(): DatabaseSync | null;
+/**
+ * Closes the conduit.db connection and resets the module singleton.
+ *
+ * Safe to call multiple times. No-op if the database is already closed.
+ *
+ * @task T344
+ * @epic T310
+ */
+export declare function closeConduitDb(): void;
+/**
+ * Attaches an agent to the current project. If a row exists with enabled=0,
+ * re-enables it (update attached_at timestamp). If a row exists with enabled=1,
+ * no-op. Inserts a new row otherwise.
+ *
+ * @param db - conduit.db handle (from ensureConduitDb).
+ * @param agentId - Global signaldock.db:agents.id (soft FK, not validated here).
+ * @param opts - Optional role and capabilities override.
+ * @task T353
+ * @epic T310
+ */
+export declare function attachAgentToProject(db: DatabaseSync, agentId: string, opts?: {
+    role?: string | null;
+    capabilitiesOverride?: string | null;
+}): void;
+/**
+ * Detaches an agent from the current project by setting enabled=0.
+ * Does NOT delete the row (preserves attachment history for audit).
+ *
+ * @param db - conduit.db handle (from ensureConduitDb).
+ * @param agentId - Agent ID to detach.
+ * @task T353
+ * @epic T310
+ */
+export declare function detachAgentFromProject(db: DatabaseSync, agentId: string): void;
+/**
+ * Lists project_agent_refs rows. By default returns only enabled=1 rows.
+ * Pass enabledOnly=false to return all rows regardless of enabled state.
+ *
+ * @param db - conduit.db handle (from ensureConduitDb).
+ * @param opts - Filter options. Defaults to `{ enabledOnly: true }`.
+ * @returns Array of ProjectAgentRef rows ordered by attached_at DESC.
+ * @task T353
+ * @epic T310
+ */
+export declare function listProjectAgentRefs(db: DatabaseSync, opts?: {
+    enabledOnly?: boolean;
+}): ProjectAgentRef[];
+/**
+ * Returns a single project_agent_refs row by agentId, or null if not found.
+ *
+ * @param db - conduit.db handle (from ensureConduitDb).
+ * @param agentId - Agent ID to look up.
+ * @returns The ProjectAgentRef row, or null if the agent is not attached.
+ * @task T353
+ * @epic T310
+ */
+export declare function getProjectAgentRef(db: DatabaseSync, agentId: string): ProjectAgentRef | null;
+/**
+ * Updates the last_used_at timestamp for an agent to now.
+ * No-op if the agent_id does not exist in project_agent_refs.
+ *
+ * @param db - conduit.db handle (from ensureConduitDb).
+ * @param agentId - Agent ID to update.
+ * @task T353
+ * @epic T310
+ */
+export declare function updateProjectAgentLastUsed(db: DatabaseSync, agentId: string): void;
+/**
+ * Checks conduit.db health — table count, WAL mode, schema version, and
+ * foreign keys status.
+ *
+ * Used by `cleo doctor` to verify conduit.db integrity. Does NOT require
+ * `ensureConduitDb` to have been called; opens and closes the DB internally.
+ *
+ * @task T344
+ * @epic T310
+ * @param projectRoot - Absolute path to the project root directory.
+ * @returns Health report object. `exists: false` when conduit.db is absent.
+ */
+export declare function checkConduitDbHealth(projectRoot: string): {
+    exists: boolean;
+    path: string;
+    tableCount: number;
+    walMode: boolean;
+    schemaVersion: string | null;
+    foreignKeysEnabled: boolean;
+};
+export {};
+//# sourceMappingURL=conduit-sqlite.d.ts.map

package/dist/store/conduit-sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conduit-sqlite.d.ts","sourceRoot":"","sources":["../../src/store/conduit-sqlite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAQH,OAAO,KAAK,EAAE,YAAY,IAAI,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAG3D,KAAK,YAAY,GAAG,iBAAiB,CAAC;AACtC,QAAA,MAAQ,YAAY,wGAC8D,YACjF,CAAC;AAEF,kDAAkD;AAClD,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,cAAc,CAAC;AA+PlD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAEzD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG;IACpD,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;CACd,CA0DA;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,GAAG,IAAI,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAYrC;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACpE,IAAI,CAWN;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAE9E;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,YAAY,EAChB,IAAI,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/B,eAAe,EAAE,CAyBnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAyB5F;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAKlF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG;IACzD,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CA8CA"}