@shadowforge0/aquifer-memory 1.8.0 → 1.9.0

package/core/doctor.js

@@ -0,0 +1,924 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { backendCapabilities } = require('./backends/capabilities');
+const { MCP_TOOL_MANIFEST } = require('./mcp-manifest');
+const { createOperatorObservability } = require('./operator-observability');
+
+const STATUS_ORDER = {
+  ok: 0,
+  warn: 1,
+  fail: 2,
+};
+
+const EXPECTED_MCP_TOOL_COUNT = 10;
+
+function qi(identifier) {
+  return `"${String(identifier).replace(/"/g, '""')}"`;
+}
+
+function sqlSchema(schema) {
+  if (typeof schema === 'string' && schema.startsWith('"') && schema.endsWith('"')) return schema;
+  return qi(schema || 'public');
+}
+
+function toCount(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : 0;
+}
+
+function overallStatus(checks = []) {
+  let current = 'ok';
+  for (const check of checks) {
+    if (!check || !STATUS_ORDER.hasOwnProperty(check.status)) continue;
+    if (STATUS_ORDER[check.status] > STATUS_ORDER[current]) current = check.status;
+  }
+  return current;
+}
+
+function makeCheck(id, status, summary, details = {}, nextAction = null) {
+  return {
+    id,
+    status,
+    summary,
+    details,
+    nextAction,
+  };
+}
+
+function isTableMissing(error) {
+  return error && error.code === '42P01';
+}
+
+function readPackageMeta(overrides = {}) {
+  if (overrides.packageName && overrides.packageVersion) {
+    return {
+      name: overrides.packageName,
+      version: overrides.packageVersion,
+    };
+  }
+  try {
+    const packageJsonPath = overrides.packageJsonPath || path.join(__dirname, '..', 'package.json');
+    const parsed = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    return {
+      name: overrides.packageName || parsed.name || null,
+      version: overrides.packageVersion || parsed.version || null,
+    };
+  } catch {
+    return {
+      name: overrides.packageName || null,
+      version: overrides.packageVersion || null,
+    };
+  }
+}
+
+function resolveManifestTools(manifest) {
+  if (Array.isArray(manifest)) return manifest;
+  if (manifest && Array.isArray(manifest.tools)) return manifest.tools;
+  return [];
+}
+
+function normalizeToolCount(input) {
+  if (input === null || input === undefined) return null;
+  if (Array.isArray(input)) return input.length;
+  if (typeof input === 'number') return Number.isFinite(input) ? input : null;
+  if (typeof input === 'object' && Array.isArray(input.tools)) return input.tools.length;
+  return null;
+}
+
+function sumCounts(counts = {}) {
+  return Object.values(counts).reduce((sum, value) => sum + toCount(value), 0);
+}
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function fileExists(filePath) {
+  try {
+    return fs.existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+
+function pickCapabilitySummary(profile = {}) {
+  const capabilities = profile.capabilities || {};
+  return {
+    persistence: capabilities.persistence || 'unknown',
+    curatedBootstrap: capabilities.curatedBootstrap || 'unknown',
+    curatedRecall: capabilities.curatedRecall || 'unknown',
+    finalizationLedger: capabilities.finalizationLedger || 'unknown',
+    operatorCompaction: capabilities.operatorCompaction || 'unknown',
+    operatorCheckpoint: capabilities.operatorCheckpoint || 'unknown',
+    migrationHandshake: capabilities.migrationHandshake || 'unknown',
+  };
+}
+
+async function checkDbReadiness({ pool, schemaName, schemaSql, tenantId, dbConfigured, backendKind }) {
+  if (backendKind !== 'postgres') {
+    return makeCheck(
+      'db',
+      'warn',
+      'Database/schema readiness is only available on the PostgreSQL backend.',
+      {
+        backendKind,
+        configured: Boolean(dbConfigured),
+        schema: schemaName,
+        tenantId,
+      },
+      'Use the PostgreSQL backend if you need DB-backed governance diagnostics.',
+    );
+  }
+  if (!dbConfigured || !pool || typeof pool.query !== 'function') {
+    return makeCheck(
+      'db',
+      'fail',
+      'Database is not configured for read-only governance checks.',
+      {
+        configured: Boolean(dbConfigured),
+        schema: schemaName,
+        tenantId,
+      },
+      'Configure a PostgreSQL database connection, then rerun `aquifer doctor`.',
+    );
+  }
+
+  try {
+    const tableResult = await pool.query(
+      `SELECT
+         EXISTS(
+           SELECT 1
+             FROM information_schema.tables
+            WHERE table_schema = $1
+              AND table_name = 'sessions'
+         ) AS has_sessions,
+         EXISTS(
+           SELECT 1
+             FROM information_schema.tables
+            WHERE table_schema = $1
+              AND table_name = 'session_summaries'
+         ) AS has_session_summaries,
+         EXISTS(
+           SELECT 1
+             FROM information_schema.tables
+            WHERE table_schema = $1
+              AND table_name = 'memory_records'
+         ) AS has_memory_records,
+         EXISTS(
+           SELECT 1
+             FROM information_schema.tables
+            WHERE table_schema = $1
+              AND table_name = 'session_finalizations'
+         ) AS has_session_finalizations,
+         EXISTS(
+           SELECT 1
+             FROM information_schema.tables
+            WHERE table_schema = $1
+              AND table_name = 'compaction_runs'
+         ) AS has_compaction_runs,
+         EXISTS(
+           SELECT 1
+             FROM information_schema.tables
+            WHERE table_schema = $1
+              AND table_name = 'checkpoint_runs'
+         ) AS has_checkpoint_runs`,
+      [schemaName],
+    );
+    const row = tableResult.rows[0] || {};
+    const tables = {
+      sessions: row.has_sessions === true,
+      sessionSummaries: row.has_session_summaries === true,
+      memoryRecords: row.has_memory_records === true,
+      sessionFinalizations: row.has_session_finalizations === true,
+      compactionRuns: row.has_compaction_runs === true,
+      checkpointRuns: row.has_checkpoint_runs === true,
+    };
+    const missingBase = [];
+    if (!tables.sessions) missingBase.push('sessions');
+    if (!tables.sessionSummaries) missingBase.push('session_summaries');
+
+    if (missingBase.length > 0) {
+      return makeCheck(
+        'db',
+        'fail',
+        `Schema ${schemaName} is missing required tables: ${missingBase.join(', ')}.`,
+        {
+          configured: true,
+          schema: schemaName,
+          tenantId,
+          tables,
+        },
+        'Run `aquifer migrate`, then rerun `aquifer doctor`.',
+      );
+    }
+
+    await pool.query(
+      `SELECT 1
+         FROM ${schemaSql}.sessions
+        WHERE tenant_id = $1
+        LIMIT 1`,
+      [tenantId],
+    );
+
+    const missingGovernance = [];
+    if (!tables.memoryRecords) missingGovernance.push('memory_records');
+    if (!tables.sessionFinalizations) missingGovernance.push('session_finalizations');
+    if (!tables.compactionRuns) missingGovernance.push('compaction_runs');
+    if (!tables.checkpointRuns) missingGovernance.push('checkpoint_runs');
+
+    if (missingGovernance.length > 0) {
+      return makeCheck(
+        'db',
+        'warn',
+        `Schema ${schemaName} is reachable, but governance tables are incomplete: ${missingGovernance.join(', ')}.`,
+        {
+          configured: true,
+          schema: schemaName,
+          tenantId,
+          tables,
+        },
+        'Run `aquifer migrate` to materialize the missing governance tables.',
+      );
+    }
+
+    return makeCheck(
+      'db',
+      'ok',
+      `Schema ${schemaName} is reachable and tenant-scoped reads are ready.`,
+      {
+        configured: true,
+        schema: schemaName,
+        tenantId,
+        tables,
+      },
+      null,
+    );
+  } catch (error) {
+    return makeCheck(
+      'db',
+      'fail',
+      `Database readiness check failed: ${error.message}`,
+      {
+        configured: true,
+        schema: schemaName,
+        tenantId,
+        error: error.message,
+      },
+      'Verify the database connection, schema name, and tenant configuration.',
+    );
+  }
+}
+
+async function checkMigrations({ backendKind, listPendingMigrations }) {
+  if (backendKind !== 'postgres') {
+    return makeCheck(
+      'migrations',
+      'warn',
+      'Migration readiness is only available on the PostgreSQL backend.',
+      {
+        backendKind,
+      },
+      'Use the PostgreSQL backend if you need migration and governance workflows.',
+    );
+  }
+  if (typeof listPendingMigrations !== 'function') {
+    return makeCheck(
+      'migrations',
+      'warn',
+      'Migration planner is not wired into this doctor integration.',
+      {},
+      'Wire `listPendingMigrations()` into the doctor runner.',
+    );
+  }
+  try {
+    const plan = await listPendingMigrations();
+    const pending = Array.isArray(plan && plan.pending) ? plan.pending : [];
+    if (pending.length > 0) {
+      return makeCheck(
+        'migrations',
+        'fail',
+        `${pending.length} pending migration${pending.length === 1 ? '' : 's'} detected.`,
+        {
+          required: Array.isArray(plan.required) ? plan.required : [],
+          applied: Array.isArray(plan.applied) ? plan.applied : [],
+          pending,
+        },
+        'Run `aquifer migrate`, then rerun `aquifer doctor`.',
+      );
+    }
+    return makeCheck(
+      'migrations',
+      'ok',
+      'No pending migrations.',
+      {
+        required: Array.isArray(plan.required) ? plan.required : [],
+        applied: Array.isArray(plan.applied) ? plan.applied : [],
+        pending: [],
+      },
+      null,
+    );
+  } catch (error) {
+    return makeCheck(
+      'migrations',
+      'fail',
+      `Migration readiness check failed: ${error.message}`,
+      {
+        error: error.message,
+      },
+      'Verify the migration planner can read the target schema.',
+    );
+  }
+}
+
+function checkPackage({ packageMeta, nodeVersion }) {
+  const details = {
+    packageName: packageMeta.name,
+    packageVersion: packageMeta.version,
+    nodeVersion,
+  };
+  if (!packageMeta.version) {
+    return makeCheck(
+      'package',
+      'warn',
+      `Aquifer package metadata is incomplete${nodeVersion ? ` on Node ${nodeVersion}` : ''}.`,
+      details,
+      'Verify the installed package metadata before release or support work.',
+    );
+  }
+  return makeCheck(
+    'package',
+    'ok',
+    `${packageMeta.name || 'aquifer'}@${packageMeta.version} on Node ${nodeVersion}.`,
+    details,
+    null,
+  );
+}
+
+function checkBackend({ backendKind, backendProfile }) {
+  const profile = backendCapabilities(backendKind);
+  const profileName = backendProfile || profile.profile;
+  const details = {
+    kind: profile.kind,
+    profile: profileName,
+    label: profile.label,
+    capabilities: pickCapabilitySummary(profile),
+  };
+  if (profile.profile !== 'full') {
+    return makeCheck(
+      'backend',
+      'warn',
+      `${profile.label}; governance coverage is degraded on this backend.`,
+      details,
+      profile.upgradeHint || 'Use the PostgreSQL backend for full governance coverage.',
+    );
+  }
+  return makeCheck(
+    'backend',
+    'ok',
+    profile.label,
+    details,
+    null,
+  );
+}
+
+function checkServing({ memoryServing }) {
+  const mode = memoryServing && memoryServing.servingMode ? memoryServing.servingMode : 'legacy';
+  const activeScopeKey = memoryServing && memoryServing.defaultActiveScopeKey
+    ? memoryServing.defaultActiveScopeKey
+    : null;
+  const activeScopePath = memoryServing && Array.isArray(memoryServing.defaultActiveScopePath)
+    ? memoryServing.defaultActiveScopePath
+    : [];
+  const details = {
+    mode,
+    activeScopeKey,
+    activeScopePath,
+  };
+  if (mode === 'curated' && !activeScopeKey && activeScopePath.length === 0) {
+    return makeCheck(
+      'serving',
+      'warn',
+      'Serving mode is curated, but no active scope is configured.',
+      details,
+      'Set `AQUIFER_MEMORY_ACTIVE_SCOPE_KEY` or `AQUIFER_MEMORY_ACTIVE_SCOPE_PATH` for curated serving.',
+    );
+  }
+  return makeCheck(
+    'serving',
+    'ok',
+    mode === 'curated'
+      ? `Curated serving is scoped to ${activeScopeKey || activeScopePath[activeScopePath.length - 1]}.`
+      : 'Legacy serving mode is active.',
+    details,
+    null,
+  );
+}
+
+function checkMcpTools({ manifestTools, runtimeTools, expectedMcpToolCount }) {
+  const manifestCount = manifestTools.length;
+  const runtimeCount = normalizeToolCount(runtimeTools);
+  const details = {
+    expectedCount: expectedMcpToolCount,
+    manifestCount,
+    runtimeCount,
+    manifestTools: manifestTools.map(tool => tool.name).filter(Boolean),
+  };
+  if (manifestCount !== expectedMcpToolCount) {
+    return makeCheck(
+      'mcp-tools',
+      'fail',
+      `MCP manifest exposes ${manifestCount} tools; expected ${expectedMcpToolCount}.`,
+      details,
+      'Restore the fixed MCP surface before release or deployment.',
+    );
+  }
+  if (runtimeCount !== null && runtimeCount !== manifestCount) {
+    return makeCheck(
+      'mcp-tools',
+      'fail',
+      `MCP runtime exposes ${runtimeCount} tools, but the manifest declares ${manifestCount}.`,
+      details,
+      'Reload the MCP server so runtime and manifest tool counts match.',
+    );
+  }
+  return makeCheck(
+    'mcp-tools',
+    'ok',
+    `MCP surface exposes ${manifestCount} tools.`,
+    details,
+    null,
+  );
+}
+
+async function checkSessionBacklog({ pool, schemaSql, tenantId, backendKind }) {
+  if (backendKind !== 'postgres') {
+    return makeCheck(
+      'session-backlog',
+      'warn',
+      'Session backlog inspection is only available on the PostgreSQL backend.',
+      {
+        backendKind,
+      },
+      'Use the PostgreSQL backend to inspect DB-backed session processing backlog.',
+    );
+  }
+  try {
+    const result = await pool.query(
+      `SELECT processing_status, COUNT(*)::int AS count
+         FROM ${schemaSql}.sessions
+        WHERE tenant_id = $1
+          AND processing_status IN ('pending', 'processing', 'partial', 'failed')
+        GROUP BY processing_status`,
+      [tenantId],
+    );
+    const counts = Object.fromEntries(result.rows.map(row => [row.processing_status, toCount(row.count)]));
+    const failed = toCount(counts.failed);
+    const backlog = sumCounts(counts);
+    if (failed > 0) {
+      return makeCheck(
+        'session-backlog',
+        'fail',
+        `${failed} failed session${failed === 1 ? '' : 's'} require attention.`,
+        {
+          counts,
+          totalBacklog: backlog,
+        },
+        'Inspect failed session processing before relying on continuity output.',
+      );
+    }
+    if (backlog > 0) {
+      return makeCheck(
+        'session-backlog',
+        'warn',
+        `${backlog} session${backlog === 1 ? '' : 's'} are still pending, processing, or partial.`,
+        {
+          counts,
+          totalBacklog: backlog,
+        },
+        'Let session processing drain or re-run the worker path before trust-sensitive reads.',
+      );
+    }
+    return makeCheck(
+      'session-backlog',
+      'ok',
+      'No session processing backlog.',
+      {
+        counts,
+        totalBacklog: 0,
+      },
+      null,
+    );
+  } catch (error) {
+    return makeCheck(
+      'session-backlog',
+      isTableMissing(error) ? 'warn' : 'fail',
+      isTableMissing(error)
+        ? 'Session backlog table is not available yet.'
+        : `Session backlog check failed: ${error.message}`,
+      {
+        error: error.message,
+      },
+      isTableMissing(error)
+        ? 'Run `aquifer migrate`, then rerun `aquifer doctor`.'
+        : 'Verify the sessions table is readable for the target tenant.',
+    );
+  }
+}
+
+async function checkFinalizationBacklog({ pool, schemaSql, tenantId, backendKind }) {
+  if (backendKind !== 'postgres') {
+    return makeCheck(
+      'finalization-backlog',
+      'warn',
+      'Finalization backlog inspection is only available on the PostgreSQL backend.',
+      {
+        backendKind,
+      },
+      'Use the PostgreSQL backend to inspect the finalization ledger.',
+    );
+  }
+  try {
+    const result = await pool.query(
+      `SELECT status, COUNT(*)::int AS count
+         FROM ${schemaSql}.session_finalizations
+        WHERE tenant_id = $1
+          AND status IN ('pending', 'processing', 'failed', 'deferred')
+        GROUP BY status`,
+      [tenantId],
+    );
+    const counts = Object.fromEntries(result.rows.map(row => [row.status, toCount(row.count)]));
+    const failed = toCount(counts.failed);
+    const backlog = sumCounts(counts);
+    if (failed > 0) {
+      return makeCheck(
+        'finalization-backlog',
+        'fail',
+        `${failed} failed finalization row${failed === 1 ? '' : 's'} require attention.`,
+        {
+          counts,
+          totalBacklog: backlog,
+        },
+        'Inspect the failed finalization rows before relying on curated continuity.',
+      );
+    }
+    if (backlog > 0) {
+      return makeCheck(
+        'finalization-backlog',
+        'warn',
+        `${backlog} finalization row${backlog === 1 ? '' : 's'} are still pending, processing, or deferred.`,
+        {
+          counts,
+          totalBacklog: backlog,
+        },
+        'Let finalization complete or clear deferred rows before expecting new current-memory output.',
+      );
+    }
+    return makeCheck(
+      'finalization-backlog',
+      'ok',
+      'No finalization backlog.',
+      {
+        counts,
+        totalBacklog: 0,
+      },
+      null,
+    );
+  } catch (error) {
+    return makeCheck(
+      'finalization-backlog',
+      isTableMissing(error) ? 'warn' : 'fail',
+      isTableMissing(error)
+        ? 'Finalization ledger table is not available yet.'
+        : `Finalization backlog check failed: ${error.message}`,
+      {
+        error: error.message,
+      },
+      isTableMissing(error)
+        ? 'Run `aquifer migrate`, then rerun `aquifer doctor`.'
+        : 'Verify the finalization ledger is readable for the target tenant.',
+    );
+  }
+}
+
+async function checkOperatorClaims({ operatorObservability, tenantId, backendKind }) {
+  if (backendKind !== 'postgres') {
+    return makeCheck(
+      'operator-stale-claims',
+      'warn',
+      'Operator stale-claim inspection is only available on the PostgreSQL backend.',
+      {
+        backendKind,
+      },
+      'Use the PostgreSQL backend to inspect compaction and checkpoint ledgers.',
+    );
+  }
+  if (!operatorObservability || typeof operatorObservability.status !== 'function') {
+    return makeCheck(
+      'operator-stale-claims',
+      'warn',
+      'Operator observability is not wired into this doctor integration.',
+      {},
+      'Wire operator observability into the doctor runner.',
+    );
+  }
+  try {
+    const result = await operatorObservability.status({ tenantId, limit: 5 });
+    const staleClaims = Array.isArray(result.compaction && result.compaction.staleClaims)
+      ? result.compaction.staleClaims
+      : [];
+    const checkpointCounts = result.checkpoint && result.checkpoint.statusCounts
+      ? result.checkpoint.statusCounts
+      : {};
+    if (staleClaims.length > 0) {
+      return makeCheck(
+        'operator-stale-claims',
+        'warn',
+        `${staleClaims.length} stale compaction claim${staleClaims.length === 1 ? '' : 's'} detected.`,
+        {
+          staleClaims,
+          checkpointStatusCounts: checkpointCounts,
+        },
+        'Inspect or reclaim stale operator claims before the next apply run.',
+      );
+    }
+    return makeCheck(
+      'operator-stale-claims',
+      'ok',
+      'No stale compaction claims detected.',
+      {
+        staleClaims: [],
+        checkpointStatusCounts: checkpointCounts,
+      },
+      null,
+    );
+  } catch (error) {
+    return makeCheck(
+      'operator-stale-claims',
+      'fail',
+      `Operator stale-claim check failed: ${error.message}`,
+      {
+        error: error.message,
+      },
+      'Verify the operator ledgers are readable for the target tenant.',
+    );
+  }
+}
+
+function checkOpenClawHost({ openclawHome, env = process.env }) {
+  const home = path.resolve(openclawHome || env.OPENCLAW_HOME || path.join(os.homedir(), '.openclaw'));
+  const configPath = path.join(home, 'openclaw.json');
+  const extensionPath = path.join(home, 'extensions', 'aquifer-memory');
+  const packagePath = path.join(home, 'node_modules', '@shadowforge0', 'aquifer-memory', 'package.json');
+  const config = readJsonSafe(configPath);
+  const mcpServer = config && config.mcp && config.mcp.servers ? config.mcp.servers.aquifer : null;
+  const pluginEntry = config && config.plugins && config.plugins.entries ? config.plugins.entries['aquifer-memory'] : null;
+  const loadPaths = config && config.plugins && config.plugins.load && Array.isArray(config.plugins.load.paths)
+    ? config.plugins.load.paths
+    : [];
+  const details = {
+    openclawHome: home,
+    homeExists: fileExists(home),
+    configPath,
+    configExists: fileExists(configPath),
+    packagePath,
+    packageInstalled: fileExists(packagePath),
+    extensionPath,
+    extensionExists: fileExists(extensionPath),
+    pluginEnabled: pluginEntry ? pluginEntry.enabled !== false : false,
+    loadPathPresent: loadPaths.includes(extensionPath),
+    mcpConfigured: Boolean(mcpServer),
+    mcpCommand: mcpServer ? mcpServer.command || null : null,
+    mcpArgs: mcpServer && Array.isArray(mcpServer.args) ? mcpServer.args : [],
+  };
+
+  if (!details.homeExists) {
+    return makeCheck(
+      'openclaw-host',
+      'fail',
+      `OpenClaw home does not exist: ${home}.`,
+      details,
+      'Pass --openclaw-home or set OPENCLAW_HOME to the installed OpenClaw home.',
+    );
+  }
+  if (!details.configExists) {
+    return makeCheck(
+      'openclaw-host',
+      'warn',
+      'OpenClaw home exists, but openclaw.json was not found.',
+      details,
+      'Run `aquifer install-openclaw --openclaw-home "$OPENCLAW_HOME"` after OpenClaw creates its config.',
+    );
+  }
+
+  const missing = [];
+  if (!details.packageInstalled) missing.push('package');
+  if (!details.extensionExists) missing.push('extension');
+  if (!details.pluginEnabled) missing.push('plugin');
+  if (!details.loadPathPresent) missing.push('plugin_load_path');
+  if (!details.mcpConfigured) missing.push('mcp_server');
+
+  if (missing.length > 0) {
+    return makeCheck(
+      'openclaw-host',
+      'warn',
+      `OpenClaw Aquifer wiring is incomplete: ${missing.join(', ')}.`,
+      details,
+      'Run `aquifer install-openclaw --openclaw-home "$OPENCLAW_HOME"` and review the dry-run output first if needed.',
+    );
+  }
+
+  return makeCheck(
+    'openclaw-host',
+    'ok',
+    'OpenClaw Aquifer MCP and extension wiring are present.',
+    details,
+    null,
+  );
+}
+
+function codexHookInstalled(hooksPath) {
+  const hooks = readJsonSafe(hooksPath);
+  if (!hooks || typeof hooks !== 'object') return false;
+  const text = JSON.stringify(hooks);
+  return text.includes('checkpoint-heartbeat');
+}
+
+function checkCodexHost({ codexHome, hooksPath, env = process.env }) {
+  const home = path.resolve(codexHome || env.CODEX_HOME || path.join(os.homedir(), '.codex'));
+  const resolvedHooksPath = path.resolve(hooksPath || env.CODEX_HOOKS_PATH || path.join(home, 'hooks.json'));
+  const sessionsDir = path.resolve(env.CODEX_SESSIONS_DIR || path.join(home, 'sessions'));
+  const stateDir = path.resolve(env.AQUIFER_CODEX_STATE_DIR || path.join(home, 'aquifer-state'));
+  const wrapperEnvPresent = Boolean(
+    env.CODEX_AQUIFER_AGENT_ID
+      || env.CODEX_AQUIFER_SOURCE
+      || env.CODEX_AQUIFER_SESSION_KEY
+      || env.CODEX_HOME
+      || env.CODEX_ENV_PATH
+  );
+  const details = {
+    codexHome: home,
+    homeExists: fileExists(home),
+    hooksPath: resolvedHooksPath,
+    hooksFileExists: fileExists(resolvedHooksPath),
+    checkpointHeartbeatHookInstalled: codexHookInstalled(resolvedHooksPath),
+    sessionsDir,
+    sessionsDirExists: fileExists(sessionsDir),
+    stateDir,
+    stateDirExists: fileExists(stateDir),
+    wrapperEnvPresent,
+  };
+
+  if (!details.homeExists) {
+    return makeCheck(
+      'codex-host',
+      'warn',
+      `Codex home does not exist or is not discoverable: ${home}.`,
+      details,
+      'Set CODEX_HOME or run this check from a Codex environment before relying on hook diagnostics.',
+    );
+  }
+  if (!details.hooksFileExists) {
+    return makeCheck(
+      'codex-host',
+      'warn',
+      'Codex hooks file was not found; checkpoint heartbeat hook is not installed.',
+      details,
+      'Preview `aquifer codex-recovery checkpoint-heartbeat-hook --scope-key <scope> --json`, then apply it deliberately.',
+    );
+  }
+  if (!details.checkpointHeartbeatHookInstalled) {
+    return makeCheck(
+      'codex-host',
+      'warn',
+      'Codex hooks file exists, but no Aquifer checkpoint heartbeat hook was detected.',
+      details,
+      'Install the checkpoint heartbeat hook with `aquifer codex-recovery checkpoint-heartbeat-hook --scope-key <scope> --apply`.',
+    );
+  }
+
+  return makeCheck(
+    'codex-host',
+    'ok',
+    'Codex checkpoint heartbeat hook is installed.',
+    details,
+    null,
+  );
+}
+
+function createDoctor(options = {}) {
+  const schemaName = options.schema || 'public';
+  const schemaSql = options.recordsSchema || options.schemaSql || sqlSchema(schemaName);
+  const packageMeta = readPackageMeta(options);
+  const manifestTools = resolveManifestTools(options.mcpManifest || MCP_TOOL_MANIFEST);
+  const expectedMcpToolCount = options.expectedMcpToolCount || EXPECTED_MCP_TOOL_COUNT;
+  const operatorObservability = options.operatorObservability
+    || (options.pool && options.backendKind !== 'local'
+      ? createOperatorObservability({
+        pool: options.pool,
+        schema: schemaSql,
+        defaultTenantId: options.defaultTenantId || 'default',
+      })
+      : null);
+
+  async function run(input = {}) {
+    const backendKind = input.backendKind || options.backendKind || 'postgres';
+    const backendProfile = input.backendProfile || options.backendProfile || null;
+    const tenantId = input.tenantId || options.defaultTenantId || 'default';
+    const dbConfigured = input.dbConfigured !== undefined
+      ? Boolean(input.dbConfigured)
+      : (options.dbConfigured !== undefined ? Boolean(options.dbConfigured) : Boolean(options.pool));
+    const memoryServing = input.memoryServing || options.memoryServing || null;
+    const runtimeTools = input.mcpRuntimeTools !== undefined ? input.mcpRuntimeTools : options.mcpRuntimeTools;
+    const listPendingMigrations = input.listPendingMigrations || options.listPendingMigrations || null;
+    const host = input.host || options.host || null;
+    const env = input.env || options.env || process.env;
+
+    const checks = [];
+    checks.push(checkPackage({
+      packageMeta,
+      nodeVersion: input.nodeVersion || options.nodeVersion || process.version,
+    }));
+    checks.push(checkBackend({ backendKind, backendProfile }));
+    checks.push(await checkDbReadiness({
+      pool: options.pool,
+      schemaName,
+      schemaSql,
+      tenantId,
+      dbConfigured,
+      backendKind,
+    }));
+    checks.push(await checkMigrations({
+      backendKind,
+      listPendingMigrations,
+    }));
+    checks.push(checkServing({ memoryServing }));
+    checks.push(checkMcpTools({
+      manifestTools,
+      runtimeTools,
+      expectedMcpToolCount,
+    }));
+    checks.push(await checkSessionBacklog({
+      pool: options.pool,
+      schemaSql,
+      tenantId,
+      backendKind,
+    }));
+    checks.push(await checkFinalizationBacklog({
+      pool: options.pool,
+      schemaSql,
+      tenantId,
+      backendKind,
+    }));
+    checks.push(await checkOperatorClaims({
+      operatorObservability,
+      tenantId,
+      backendKind,
+    }));
+    const normalizedHost = host ? String(host).trim().toLowerCase() : null;
+    if (normalizedHost === 'openclaw' || input.openclawHome || options.openclawHome) {
+      checks.push(checkOpenClawHost({
+        openclawHome: input.openclawHome || options.openclawHome || null,
+        env,
+      }));
+    }
+    if (normalizedHost === 'codex') {
+      checks.push(checkCodexHost({
+        codexHome: input.codexHome || options.codexHome || null,
+        hooksPath: input.hooksPath || options.hooksPath || null,
+        env,
+      }));
+    }
+    if (normalizedHost && !['openclaw', 'codex'].includes(normalizedHost)) {
+      checks.push(makeCheck(
+        'host',
+        'warn',
+        `No host-scoped doctor checks are defined for "${normalizedHost}".`,
+        { host: normalizedHost },
+        'Use --host openclaw or --host codex for host-specific diagnostics.',
+      ));
+    }
+
+    const status = overallStatus(checks);
+    return {
+      ok: status === 'ok',
+      status,
+      checks,
+    };
+  }
+
+  return {
+    run,
+  };
+}
+
+module.exports = {
+  EXPECTED_MCP_TOOL_COUNT,
+  createDoctor,
+};