@shadowforge0/aquifer-memory 1.6.0 → 1.8.0

package/scripts/codex-recovery.js

@@ -7,6 +7,36 @@ const path = require('path');
 
 const { createAquiferFromConfig } = require('../consumers/shared/factory');
 const codex = require('../consumers/codex');
+const {
+  cmdCheckpointHeartbeat,
+  cmdCheckpointHeartbeatHook,
+  cmdCheckpointPrompt,
+  cmdCheckpointTick,
+} = require('./codex-checkpoint-commands');
+const {
+  acquireHeartbeatClaim,
+  checkpointCheckIntervalMs,
+  checkpointClaimDir,
+  checkpointClaimTtlMs,
+  checkpointDueFromMarker,
+  checkpointEveryMessages,
+  checkpointEveryUserMessages,
+  checkpointHeartbeatCommand,
+  checkpointMarkerDir,
+  checkpointQuietMs,
+  checkpointSchedulerDir,
+  checkpointSpoolDir,
+  defaultHooksPath,
+  findNewestJsonlFile,
+  inspectCheckpointHeartbeatHook,
+  loadRuntimeConfig,
+  mergeCheckpointHeartbeatHook,
+  readCheckpointMarker,
+  readSchedulerMarker,
+  releaseHeartbeatClaim,
+  writeCheckpointMarker,
+  writeSchedulerMarker,
+} = require('./codex-checkpoint-runtime');
 const DB_ENV_KEYS = new Set(['DATABASE_URL', 'AQUIFER_DB_URL', 'AQUIFER_SCHEMA', 'AQUIFER_TENANT_ID']);
 
 const VALUE_FLAGS = new Set([
@@ -16,7 +46,23 @@ const VALUE_FLAGS = new Set([
   'except-session-id',
   'file-path',
   'finalizer-model',
+  'checkpoint-every-messages',
+  'checkpoint-every-user-messages',
+  'checkpoint-check-interval-ms',
+  'checkpoint-check-interval-minutes',
+  'checkpoint-claim-ttl-ms',
+  'checkpoint-claim-dir',
+  'checkpoint-marker-dir',
+  'checkpoint-scheduler-dir',
+  'checkpoint-spool-dir',
+  'checkpoint-quiet-ms',
+  'hook-event-name',
+  'hooks-path',
   'idle-ms',
+  'max-checkpoint-bytes',
+  'max-checkpoint-chars',
+  'max-checkpoint-messages',
+  'max-checkpoint-prompt-tokens',
   'max-candidates',
   'max-recovery-bytes',
   'max-recovery-chars',
@@ -27,6 +73,8 @@ const VALUE_FLAGS = new Set([
   'reason',
   'scope-kind',
   'scope-key',
+  'active-scope-key',
+  'active-scope-path',
   'session-id',
   'session-key',
   'sessions-dir',
@@ -36,6 +84,11 @@ const VALUE_FLAGS = new Set([
   'summary-json',
   'summary-text',
   'verdict',
+  'workspace',
+  'workspace-path',
+  'project',
+  'project-key',
+  'repo-path',
 ]);
 
 function parseArgs(argv) {
@@ -109,7 +162,11 @@ function buildRecoveryOptions(flags = {}, env = process.env) {
     agentId: flags['agent-id'] || envDefault(env, 'CODEX_AQUIFER_AGENT_ID', 'AQUIFER_AGENT_ID') || 'main',
     source: flags.source || envDefault(env, 'CODEX_AQUIFER_SOURCE', 'AQUIFER_SOURCE') || 'codex',
     sessionKey: flags['session-key'] || envDefault(env, 'CODEX_AQUIFER_SESSION_KEY') || 'codex:cli',
+    workspace: flags.workspace || flags['workspace-path'] || envDefault(env, 'CODEX_AQUIFER_WORKSPACE', 'CODEX_WORKSPACE') || undefined,
+    project: flags.project || flags['project-key'] || envDefault(env, 'CODEX_AQUIFER_PROJECT', 'CODEX_PROJECT') || undefined,
+    repoPath: flags['repo-path'] || envDefault(env, 'CODEX_AQUIFER_REPO_PATH', 'CODEX_REPO_PATH') || undefined,
     codexHome: flags['codex-home'] || envDefault(env, 'CODEX_HOME') || undefined,
+    hooksPath: flags['hooks-path'] || undefined,
     stateDir: flags['state-dir'] || undefined,
     sessionsDir: flags['sessions-dir'] || undefined,
     maxRecoveryCandidates: parseIntFlag(flags['max-candidates'], 1),
@@ -122,6 +179,7 @@ function buildRecoveryOptions(flags = {}, env = process.env) {
     includeJsonlPreviews: flags['include-jsonl-previews'] === true,
     includeDeferredRecovery: flags['include-deferred'] === true,
     excludeNewest: flags['include-current'] === true ? false : true,
+    strictWrapperEnv: flags['strict-wrapper-env'] === true,
   };
   for (const [key, value] of Object.entries(opts)) {
     if (value === undefined) delete opts[key];
@@ -129,6 +187,10 @@ function buildRecoveryOptions(flags = {}, env = process.env) {
   return opts;
 }
 
+function addDoctorCheck(checks, name, status, detail, extra = {}) {
+  checks.push({ name, status, detail, ...extra });
+}
+
 function shellQuote(value) {
   return `'${String(value || '').replace(/'/g, `'\\''`)}'`;
 }
@@ -266,6 +328,91 @@ function compactCandidate(candidate = {}) {
   };
 }
 
+function compactDoctorOptions(opts = {}) {
+  return {
+    agentId: opts.agentId || 'main',
+    source: opts.source || 'codex',
+    sessionKey: opts.sessionKey || 'codex:cli',
+    workspace: opts.workspace || null,
+    project: opts.project || null,
+    repoPath: opts.repoPath || null,
+    codexHome: opts.codexHome || null,
+    hooksPath: opts.hooksPath || null,
+    sessionsDir: opts.sessionsDir || null,
+    stateDir: opts.stateDir || null,
+    excludeNewest: opts.excludeNewest !== false,
+    includeDeferredRecovery: opts.includeDeferredRecovery === true,
+    maxRecoveryCandidates: opts.maxRecoveryCandidates || null,
+  };
+}
+
+async function buildDoctorReport(aquifer, opts = {}, env = process.env) {
+  const checks = [];
+  const hasWrapperEnv = Boolean(
+    env.CODEX_AQUIFER_AGENT_ID
+      || env.CODEX_AQUIFER_SOURCE
+      || env.CODEX_AQUIFER_SESSION_KEY
+      || env.CODEX_HOME
+      || env.CODEX_ENV_PATH,
+  );
+  if (hasWrapperEnv) {
+    addDoctorCheck(checks, 'wrapper_env', 'ok', 'Codex wrapper env is present.');
+  } else if (opts.strictWrapperEnv) {
+    addDoctorCheck(checks, 'wrapper_env', 'fail', 'Strict wrapper env requested, but no CODEX_AQUIFER_* or CODEX_HOME env was found.');
+  } else {
+    addDoctorCheck(checks, 'wrapper_env', 'warn', 'Using CLI defaults; pass --strict-wrapper-env for live wrapper deployment checks.');
+  }
+
+  if (opts.excludeNewest === false) {
+    addDoctorCheck(checks, 'current_transcript_guard', 'fail', 'Current/newest transcript exclusion is disabled.');
+  } else {
+    addDoctorCheck(checks, 'current_transcript_guard', 'ok', 'Newest transcript exclusion is enabled.');
+  }
+
+  const heartbeatHook = inspectCheckpointHeartbeatHook(opts);
+  addDoctorCheck(
+    checks,
+    'checkpoint_heartbeat_hook',
+    heartbeatHook.status,
+    heartbeatHook.detail,
+    { hooksPath: heartbeatHook.hooksPath, installed: heartbeatHook.installed },
+  );
+
+  let candidates = [];
+  try {
+    candidates = await listDbEligibleCandidates(aquifer, {
+      ...opts,
+      idleMs: opts.idleMs ?? 0,
+      includeJsonlPreviews: true,
+      maxRecoveryCandidates: opts.maxRecoveryCandidates || 1,
+    });
+    addDoctorCheck(
+      checks,
+      'sessionstart_preflight',
+      'ok',
+      `Metadata-only recovery scan completed; eligibleCandidates=${candidates.length}.`,
+      { eligibleCandidates: candidates.length },
+    );
+  } catch (err) {
+    addDoctorCheck(
+      checks,
+      'sessionstart_preflight',
+      'fail',
+      err && err.message ? err.message : String(err),
+    );
+  }
+
+  const status = checks.some(check => check.status === 'fail')
+    ? 'fail'
+    : checks.some(check => check.status === 'warn') ? 'warn' : 'ok';
+  return {
+    status,
+    checks,
+    options: compactDoctorOptions(opts),
+    candidates: candidates.map(compactCandidate),
+  };
+}
+
 function parseIdList(value) {
   if (!value || value === true) return new Set();
   return new Set(String(value).split(',').map(part => part.trim()).filter(Boolean));
@@ -467,6 +614,42 @@ async function cmdDecision(aquifer, flags, opts) {
   console.log(`Recovery ${verdict}: ${candidate.sessionId}`);
 }
 
+async function cmdDoctor(aquifer, flags, opts, env = process.env) {
+  const report = await buildDoctorReport(aquifer, opts, env);
+  printDoctorReport(report, flags);
+  return report;
+}
+
+function printDoctorReport(report = {}, flags = {}) {
+  if (flags.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(`Codex recovery doctor: ${report.status}`);
+    for (const check of report.checks || []) {
+      console.log(`- ${check.status} ${check.name}: ${check.detail}`);
+    }
+  }
+  if (report.status === 'fail') process.exitCode = 1;
+}
+
+async function cmdDoctorInitFailure(flags, opts, err, env = process.env) {
+  let report = await buildDoctorReport(null, opts, env);
+  report = {
+    ...report,
+    status: 'fail',
+    checks: [
+      {
+        name: 'aquifer_init',
+        status: 'fail',
+        detail: err && err.message ? err.message : String(err),
+      },
+      ...(report.checks || []),
+    ],
+  };
+  printDoctorReport(report, flags);
+  return report;
+}
+
 async function main(argv = process.argv.slice(2)) {
   const args = parseArgs(argv);
   const command = args._[0] || 'help';
@@ -478,9 +661,35 @@ async function main(argv = process.argv.slice(2)) {
   node scripts/codex-recovery.js hook-context [options]
   node scripts/codex-recovery.js preview [options]
   node scripts/codex-recovery.js prompt --session-id ID [options]
+  node scripts/codex-recovery.js checkpoint-prompt --file-path FILE --scope-key KEY [options]
+  node scripts/codex-recovery.js checkpoint-tick --scope-key KEY [--file-path FILE|--sessions-dir DIR] [options]
+  node scripts/codex-recovery.js checkpoint-heartbeat --hook-stdin --scope-key KEY [options]
+  node scripts/codex-recovery.js checkpoint-heartbeat-hook --scope-key KEY [--hooks-path FILE] [--apply]
   node scripts/codex-recovery.js finalize --session-id ID --summary-stdin [options]
   node scripts/codex-recovery.js decision --session-id ID --verdict declined|deferred [options]
-  node scripts/codex-recovery.js decision --all --verdict declined|deferred [options]`);
+  node scripts/codex-recovery.js decision --all --verdict declined|deferred [options]
+  node scripts/codex-recovery.js doctor [--strict-wrapper-env] [--json]`);
+    return;
+  }
+
+  if (command === 'doctor') {
+    try {
+      await withAquifer(async (aquifer) => {
+        await cmdDoctor(aquifer, args.flags, opts);
+      });
+    } catch (err) {
+      await cmdDoctorInitFailure(args.flags, opts, err);
+    }
+    return;
+  }
+
+  if (command === 'checkpoint-heartbeat') {
+    await cmdCheckpointHeartbeat(null, args.flags, opts);
+    return;
+  }
+
+  if (command === 'checkpoint-heartbeat-hook') {
+    await cmdCheckpointHeartbeatHook(args.flags, opts);
     return;
   }
 
@@ -495,6 +704,12 @@ async function main(argv = process.argv.slice(2)) {
       case 'prompt':
         await cmdPrompt(aquifer, args.flags, opts);
         break;
+      case 'checkpoint-prompt':
+        await cmdCheckpointPrompt(aquifer, args.flags, opts);
+        break;
+      case 'checkpoint-tick':
+        await cmdCheckpointTick(aquifer, args.flags, opts);
+        break;
       case 'finalize':
         await cmdFinalize(aquifer, args.flags, opts);
         break;
@@ -508,16 +723,46 @@ async function main(argv = process.argv.slice(2)) {
 }
 
 module.exports = {
+  buildDoctorReport,
   buildRecoveryOptions,
   cmdDecision,
+  cmdDoctor,
+  cmdDoctorInitFailure,
   cmdFinalize,
   cmdHookContext,
+  cmdCheckpointHeartbeat,
+  cmdCheckpointHeartbeatHook,
+  cmdCheckpointPrompt,
+  cmdCheckpointTick,
   cmdPrompt,
+  acquireHeartbeatClaim,
+  checkpointDueFromMarker,
+  checkpointHeartbeatCommand,
+  checkpointCheckIntervalMs,
+  checkpointEveryMessages,
+  checkpointEveryUserMessages,
+  checkpointQuietMs,
+  checkpointClaimDir,
+  checkpointClaimTtlMs,
+  checkpointMarkerDir,
+  checkpointSchedulerDir,
+  checkpointSpoolDir,
+  defaultHooksPath,
+  findNewestJsonlFile,
+  inspectCheckpointHeartbeatHook,
+  loadRuntimeConfig,
   loadCodexEnv,
+  main,
+  mergeCheckpointHeartbeatHook,
   parseArgs,
+  readCheckpointMarker,
+  readSchedulerMarker,
+  releaseHeartbeatClaim,
   renderFinalizeCommand,
   renderHookContext,
   selectCandidate,
+  writeCheckpointMarker,
+  writeSchedulerMarker,
 };
 
 if (require.main === module) {