@shadowforge0/aquifer-memory 1.6.0 → 1.7.0

package/core/memory-records.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const crypto = require('crypto');
+const { resolveApplicableRecords } = require('./memory-bootstrap');
 
 function requireField(obj, field) {
   if (!obj || obj[field] === undefined || obj[field] === null || obj[field] === '') {
@@ -24,10 +25,10 @@ function advisoryLockKeys(namespace, value) {
 const BOOTSTRAP_ORDER_SQL = `
          CASE m.memory_type
            WHEN 'constraint' THEN 0
-           WHEN 'preference' THEN 1
-           WHEN 'state' THEN 2
-           WHEN 'open_loop' THEN 3
-           WHEN 'decision' THEN 4
+           WHEN 'state' THEN 1
+           WHEN 'open_loop' THEN 2
+           WHEN 'decision' THEN 3
+           WHEN 'preference' THEN 4
            WHEN 'fact' THEN 5
            WHEN 'conclusion' THEN 6
            WHEN 'entity_note' THEN 7
@@ -46,6 +47,123 @@ const BOOTSTRAP_ORDER_SQL = `
          m.accepted_at DESC NULLS LAST,
          m.id ASC`;
 
+const CURRENT_TYPE_PRIORITY = {
+  constraint: 0,
+  state: 1,
+  open_loop: 2,
+  decision: 3,
+  preference: 4,
+  fact: 5,
+  conclusion: 6,
+  entity_note: 7,
+};
+
+const CURRENT_AUTHORITY_PRIORITY = {
+  user_explicit: 0,
+  executable_evidence: 1,
+  manual: 2,
+  system: 3,
+  verified_summary: 4,
+  llm_inference: 5,
+  raw_transcript: 6,
+};
+
+function parseTime(value) {
+  const parsed = Date.parse(value || '');
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function normalizeScopePath(activeScopePath, activeScopeKey) {
+  const source = Array.isArray(activeScopePath)
+    ? activeScopePath
+    : (typeof activeScopePath === 'string' ? activeScopePath.split(',') : null);
+  if (source && source.length > 0) {
+    const seen = new Set();
+    const path = [];
+    for (const value of source) {
+      const key = String(value || '').trim();
+      if (!key || seen.has(key)) continue;
+      seen.add(key);
+      path.push(key);
+    }
+    if (path.length > 0) return path;
+  }
+  if (activeScopeKey) return [String(activeScopeKey).trim()].filter(Boolean);
+  return ['global'];
+}
+
+function compareRecordIdAsc(a, b) {
+  const left = a.memoryId ?? a.memory_id ?? a.id ?? null;
+  const right = b.memoryId ?? b.memory_id ?? b.id ?? null;
+  const leftNum = Number(left);
+  const rightNum = Number(right);
+  if (Number.isFinite(leftNum) && Number.isFinite(rightNum) && leftNum !== rightNum) {
+    return leftNum - rightNum;
+  }
+  return String(left ?? '').localeCompare(String(right ?? ''));
+}
+
+function normalizeCurrentMemoryRow(row = {}) {
+  const memoryId = row.memoryId ?? row.memory_id ?? row.id ?? null;
+  const evidenceRefsValue = row.evidenceRefs ?? row.evidence_refs ?? [];
+  const evidenceRefs = Array.isArray(evidenceRefsValue) ? evidenceRefsValue : [];
+  return {
+    ...row,
+    memoryId: memoryId === null ? null : String(memoryId),
+    canonicalKey: row.canonicalKey ?? row.canonical_key ?? null,
+    memoryType: row.memoryType ?? row.memory_type ?? null,
+    scopeKey: row.scopeKey ?? row.scope_key ?? null,
+    scopeKind: row.scopeKind ?? row.scope_kind ?? null,
+    inheritanceMode: row.inheritanceMode ?? row.inheritance_mode ?? row.scope_inheritance_mode ?? null,
+    visibleInBootstrap: row.visibleInBootstrap ?? row.visible_in_bootstrap ?? false,
+    visibleInRecall: row.visibleInRecall ?? row.visible_in_recall ?? false,
+    acceptedAt: row.acceptedAt ?? row.accepted_at ?? null,
+    validFrom: row.validFrom ?? row.valid_from ?? null,
+    validTo: row.validTo ?? row.valid_to ?? null,
+    staleAfter: row.staleAfter ?? row.stale_after ?? null,
+    evidenceRefs,
+    evidence_refs: evidenceRefs,
+  };
+}
+
+function currentScopePriority(record, positions) {
+  return positions.get(record.scopeKey ?? record.scope_key) ?? -1;
+}
+
+function sortCurrentMemoryRecords(a, b, positions) {
+  const leftScope = currentScopePriority(a, positions);
+  const rightScope = currentScopePriority(b, positions);
+  if (rightScope !== leftScope) return rightScope - leftScope;
+
+  const leftType = CURRENT_TYPE_PRIORITY[a.memoryType ?? a.memory_type] ?? 99;
+  const rightType = CURRENT_TYPE_PRIORITY[b.memoryType ?? b.memory_type] ?? 99;
+  if (leftType !== rightType) return leftType - rightType;
+
+  const leftAuthority = CURRENT_AUTHORITY_PRIORITY[a.authority] ?? 99;
+  const rightAuthority = CURRENT_AUTHORITY_PRIORITY[b.authority] ?? 99;
+  if (leftAuthority !== rightAuthority) return leftAuthority - rightAuthority;
+
+  const leftAccepted = parseTime(a.acceptedAt ?? a.accepted_at);
+  const rightAccepted = parseTime(b.acceptedAt ?? b.accepted_at);
+  if (leftAccepted !== rightAccepted) return (rightAccepted ?? 0) - (leftAccepted ?? 0);
+
+  return compareRecordIdAsc(a, b);
+}
+
+function isCurrentProjectionRow(row, asOf) {
+  if ((row.status || 'candidate') !== 'active') return false;
+  if (row.visibleInBootstrap !== true && row.visibleInRecall !== true) return false;
+  const at = parseTime(asOf);
+  if (at === null) return true;
+  const validFrom = parseTime(row.validFrom ?? row.valid_from);
+  const validTo = parseTime(row.validTo ?? row.valid_to);
+  const staleAfter = parseTime(row.staleAfter ?? row.stale_after);
+  if (validFrom !== null && validFrom > at) return false;
+  if (validTo !== null && validTo <= at) return false;
+  if (staleAfter !== null && staleAfter <= at) return false;
+  return true;
+}
+
 function createMemoryRecords({ pool, schema, defaultTenantId, inTransaction = false }) {
   const scopes = `${schema}.scopes`;
   const versions = `${schema}.versions`;
@@ -534,6 +652,103 @@ function createMemoryRecords({ pool, schema, defaultTenantId, inTransaction = fa
     return result.rows;
   }
 
+  async function currentProjection(input = {}) {
+    const tenantId = input.tenantId || defaultTenantId;
+    let activeScopePath = normalizeScopePath(input.activeScopePath, input.activeScopeKey);
+    let activeScopeKey = input.activeScopeKey || activeScopePath[activeScopePath.length - 1] || null;
+    if (input.scopeId && !input.activeScopeKey && !input.activeScopePath) {
+      const scopeResult = await pool.query(
+        `SELECT scope_key FROM ${scopes} WHERE tenant_id = $1 AND id = $2 LIMIT 1`,
+        [tenantId, input.scopeId],
+      );
+      const scopedKey = scopeResult.rows[0]?.scope_key || null;
+      if (scopedKey) {
+        activeScopePath = [scopedKey];
+        activeScopeKey = scopedKey;
+      }
+    }
+    const limit = Math.max(1, Math.min(100, input.limit || 50));
+    const fetchLimit = Math.max(limit + 1, Math.min(200, Math.max(limit * 4, 40)));
+    const asOf = input.asOf || new Date().toISOString();
+    const params = [tenantId, activeScopePath, asOf];
+    const where = [
+      `m.tenant_id = $1`,
+      `m.status = 'active'`,
+      `s.scope_key = ANY($2::text[])`,
+      `(m.visible_in_bootstrap = true OR m.visible_in_recall = true)`,
+      `(m.valid_from IS NULL OR m.valid_from <= $3::timestamptz)`,
+      `(m.valid_to IS NULL OR m.valid_to > $3::timestamptz)`,
+      `(m.stale_after IS NULL OR m.stale_after > $3::timestamptz)`,
+    ];
+
+    if (input.scopeId) {
+      params.push(input.scopeId);
+      where.push(`m.scope_id = $${params.length}`);
+    }
+
+    params.push(fetchLimit);
+    const limitParam = `$${params.length}`;
+    const evidenceRefsSelect = input.includeEvidenceRefs === true
+      ? `COALESCE((
+           SELECT jsonb_agg(
+             jsonb_build_object(
+               'id', e.id,
+               'sourceKind', e.source_kind,
+               'sourceRef', e.source_ref,
+               'relationKind', e.relation_kind,
+               'weight', e.weight,
+               'metadata', e.metadata
+             )
+             ORDER BY e.id ASC
+           )
+           FROM ${evidenceRefs} e
+           WHERE e.tenant_id = m.tenant_id
+             AND e.owner_kind = 'memory_record'
+             AND e.owner_id = m.id
+         ), '[]'::jsonb)`
+      : `'[]'::jsonb`;
+
+    const result = await pool.query(
+      `SELECT
+         m.*,
+         s.scope_kind,
+         s.scope_key,
+         s.inheritance_mode AS scope_inheritance_mode,
+         ${evidenceRefsSelect} AS evidence_refs
+       FROM ${memories} m
+       JOIN ${scopes} s ON s.id = m.scope_id
+       WHERE ${where.join(' AND ')}
+       ORDER BY array_position($2::text[], s.scope_key) DESC NULLS LAST,
+                ${BOOTSTRAP_ORDER_SQL}
+       LIMIT ${limitParam}`,
+      params,
+    );
+
+    const positions = new Map(activeScopePath.map((key, index) => [key, index]));
+    const applicable = resolveApplicableRecords(
+      result.rows
+        .map(normalizeCurrentMemoryRow)
+        .filter(row => isCurrentProjectionRow(row, asOf)),
+      { activeScopeKey, activeScopePath },
+    ).sort((left, right) => sortCurrentMemoryRecords(left, right, positions));
+
+    const selected = applicable.slice(0, limit);
+    const truncated = applicable.length > limit;
+    return {
+      memories: selected,
+      meta: {
+        source: 'memory_records',
+        servingContract: 'current_memory_v1',
+        count: selected.length,
+        activeScopeKey,
+        activeScopePath,
+        asOf,
+        truncated,
+        degraded: truncated,
+      },
+    };
+  }
+
   async function withTransaction(fn) {
     if (inTransaction) {
       return fn(api, { transactional: true });
@@ -572,6 +787,7 @@ function createMemoryRecords({ pool, schema, defaultTenantId, inTransaction = fa
     updateMemoryStatusIfCurrent,
     updateFactAssertionStatus,
     listActive,
+    currentProjection,
     withTransaction,
   };
 

package/core/session-finalization.js

@@ -40,6 +40,20 @@ function summarizeMemoryResults(results = [], extra = {}) {
   };
 }
 
+function decorateCandidates(candidates = [], input = {}) {
+  const candidatePayload = input.candidatePayload && typeof input.candidatePayload === 'object'
+    ? input.candidatePayload
+    : null;
+  if (!candidatePayload) return candidates;
+  return candidates.map(candidate => ({
+    ...candidate,
+    payload: {
+      ...(candidate.payload || {}),
+      ...candidatePayload,
+    },
+  }));
+}
+
 function normalizeFinalizationInput(input = {}, defaults = {}) {
   const tenantId = input.tenantId || defaults.defaultTenantId || 'default';
   return {
@@ -227,7 +241,7 @@ function createSessionFinalization({
           phase: base.phase,
         },
       }];
-      const candidates = Array.isArray(input.candidates)
+      const rawCandidates = Array.isArray(input.candidates)
         ? input.candidates
         : promotion.extractCandidates({
             sessionId: base.sessionId,
@@ -239,6 +253,7 @@ function createSessionFinalization({
             authority: input.authority || 'verified_summary',
             evidenceRefs,
           });
+      const candidates = decorateCandidates(rawCandidates, input);
 
       const memoryResults = candidates.length > 0
         ? await promotion.promote(candidates, {

package/docs/getting-started.md

@@ -83,9 +83,15 @@ For first rollout, keep `AQUIFER_MEMORY_SERVING_MODE=legacy`. Switch to `curated
 | Start MCP server | `npx aquifer mcp` |
 | Search memory | `npx aquifer recall "auth middleware"` |
 | Plan curated compaction | `npx aquifer compact --cadence daily --period-start 2026-04-27T00:00:00Z --period-end 2026-04-28T00:00:00Z` |
+| Generate a timer synthesis prompt | `npx aquifer operator compaction daily --include-synthesis-prompt --json` |
+| Apply reviewed timer synthesis candidates | `npx aquifer operator compaction daily --synthesis-summary-file /tmp/timer-summary.json --apply --promote-candidates --json` |
 | Show stats | `npx aquifer stats` |
 | Enrich pending sessions | `npx aquifer backfill` |
 
+Timer synthesis is an operator-reviewed candidate workflow. The prompt output
+and summary JSON do not become active curated memory unless the apply step is
+run with `--promote-candidates`.
+
 The default public serving mode is `legacy`. To test scoped curated memory serving, set `AQUIFER_MEMORY_SERVING_MODE=curated` plus `AQUIFER_MEMORY_ACTIVE_SCOPE_KEY` or `AQUIFER_MEMORY_ACTIVE_SCOPE_PATH`. Rollback is config-only: set the serving mode back to `legacy` and restart the MCP/CLI process.
 
 ## If something fails

package/docs/setup.md

@@ -213,6 +213,45 @@ Do **not** use the OpenClaw plugin (`consumers/openclaw-plugin.js`) for tool del
 
 Curated serving rollback is config-only: set `AQUIFER_MEMORY_SERVING_MODE=legacy` and restart the MCP/CLI process. No destructive database rollback is required.
 
+## Operator compaction and timer synthesis
+
+Compaction jobs are operator-safe by default. A dry-run plans lifecycle updates
+and candidate output without writing active memory:
+
+```bash
+npx aquifer operator compaction daily --include-synthesis-prompt --json
+```
+
+If an operator or external model reviews that prompt and returns timer synthesis
+JSON, attach it back to the plan with:
+
+```bash
+npx aquifer operator compaction daily \
+  --synthesis-summary-file /tmp/timer-summary.json \
+  --apply \
+  --promote-candidates \
+  --json
+```
+
+The summary file must match the normal structured summary shape, for example:
+
+```json
+{
+  "summaryText": "Reviewed timer synthesis.",
+  "structuredSummary": {
+    "states": [
+      { "state": "The reviewed state that should continue into current memory." }
+    ],
+    "decisions": [],
+    "open_loops": []
+  }
+}
+```
+
+Without `--promote-candidates`, synthesis output is recorded as candidate
+ledger material only. The prompt and summary file are producer material; active
+curated memory still requires the explicit promotion gate.
+
 ## Release verification gates
 
 For the publish-surface checks:
@@ -222,13 +261,15 @@ node --test test/package-surface.test.js test/mcp-manifest.test.js
 npm pack --dry-run --json
 ```
 
-For the real DB-backed MCP integration gate:
+For the real DB-backed release gate:
 
 ```bash
-AQUIFER_TEST_DB_URL="postgresql://..." node --test test/consumer-mcp.integration.test.js
+AQUIFER_TEST_DB_URL="postgresql://..." npm run test:release:db
 ```
 
-That DB-backed test is the release proof that the stdio MCP server, current MCP manifest, and PostgreSQL path still line up on a live database.
+That DB-backed test is the release proof that the stdio MCP server, CLI
+consumer, Codex finalization serving path, current MCP manifest, and PostgreSQL
+path still line up on a live database.
 
 ## Troubleshooting
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shadowforge0/aquifer-memory",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "PG-native long-term memory for AI agents. Turn-level embedding, hybrid RRF ranking, optional knowledge graph. MCP server, CLI, and library API.",
   "main": "index.js",
   "files": [
@@ -67,7 +67,7 @@
   "scripts": {
     "test": "node --test test/*.test.js",
     "test:integration": "node --test test/integration.test.js",
-    "test:release:package": "node --test test/package-surface.test.js test/mcp-manifest.test.js",
+    "test:release:package": "node --test test/package-surface.test.js test/mcp-manifest.test.js test/v1-serving-cutover.test.js test/v1-current-memory-contract.test.js test/consumer-codex.test.js test/codex-handoff.test.js",
     "test:release:db": "node -e \"if (!process.env.AQUIFER_TEST_DB_URL) { console.error('AQUIFER_TEST_DB_URL is required for test:release:db'); process.exit(1); }\" && node --test test/consumer-mcp.integration.test.js test/consumer-cli.integration.test.js test/codex-finalization-serving.integration.test.js",
     "lint": "eslint index.js core/*.js consumers/cli.js consumers/mcp.js consumers/claude-code.js consumers/codex.js consumers/codex-handoff.js consumers/openclaw-plugin.js consumers/opencode.js consumers/shared/*.js consumers/default/*.js consumers/default/prompts/*.js consumers/openclaw-ext/*.js pipeline/*.js pipeline/consolidation/*.js scripts/*.js test/*.js",
     "hooks:install": "git config core.hooksPath .githooks"

package/scripts/codex-recovery.js

@@ -36,6 +36,11 @@ const VALUE_FLAGS = new Set([
   'summary-json',
   'summary-text',
   'verdict',
+  'workspace',
+  'workspace-path',
+  'project',
+  'project-key',
+  'repo-path',
 ]);
 
 function parseArgs(argv) {
@@ -109,6 +114,9 @@ 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,
     stateDir: flags['state-dir'] || undefined,
     sessionsDir: flags['sessions-dir'] || undefined,
@@ -122,6 +130,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 +138,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 +279,81 @@ 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,
+    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.');
+  }
+
+  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 +555,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';
@@ -480,7 +604,19 @@ async function main(argv = process.argv.slice(2)) {
   node scripts/codex-recovery.js prompt --session-id ID [options]
   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;
   }
 
@@ -508,12 +644,16 @@ async function main(argv = process.argv.slice(2)) {
 }
 
 module.exports = {
+  buildDoctorReport,
   buildRecoveryOptions,
   cmdDecision,
+  cmdDoctor,
+  cmdDoctorInitFailure,
   cmdFinalize,
   cmdHookContext,
   cmdPrompt,
   loadCodexEnv,
+  main,
   parseArgs,
   renderFinalizeCommand,
   renderHookContext,