@shadowforge0/aquifer-memory 1.7.0 → 1.8.0

package/.env.example

@@ -1,4 +1,7 @@
 DATABASE_URL=postgresql://aquifer:aquifer@localhost:5432/aquifer
+AQUIFER_BACKEND=postgres
+# AQUIFER_BACKEND=local
+# AQUIFER_LOCAL_PATH=.aquifer/aquifer.local.json
 AQUIFER_SCHEMA=aquifer
 AQUIFER_TENANT_ID=default
 
@@ -9,6 +12,11 @@ AQUIFER_MEMORY_SERVING_MODE=legacy
 # AQUIFER_MEMORY_ACTIVE_SCOPE_KEY=project:example
 # AQUIFER_MEMORY_ACTIVE_SCOPE_PATH=global,project:example
 
+# Optional Codex active-session checkpoint heartbeat policy.
+# AQUIFER_CODEX_CHECKPOINT_CHECK_INTERVAL_MINUTES=10
+# AQUIFER_CODEX_CHECKPOINT_EVERY_MESSAGES=20
+# AQUIFER_CODEX_CHECKPOINT_QUIET_MS=3000
+
 AQUIFER_EMBED_BASE_URL=http://localhost:11434/v1
 AQUIFER_EMBED_MODEL=bge-m3
 # EMBED_PROVIDER=ollama

package/README.md

@@ -74,11 +74,15 @@ Keep `AQUIFER_MEMORY_SERVING_MODE=legacy` for first rollout. Switch to `curated`
 | Goal | Command |
 |---|---|
 | Verify setup | `npx aquifer quickstart` |
+| Inspect selected backend capabilities without DB connection | `AQUIFER_BACKEND=local npx aquifer backend-info --json` |
 | Start the MCP server | `npx aquifer mcp` |
 | Search memory manually | `npx aquifer recall "auth middleware"` |
 | Plan curated memory 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` |
+| Generate a finalized-session checkpoint prompt | `npx aquifer operator checkpoint --scope-key project:aquifer --min-finalizations 10 --include-synthesis-prompt --json` |
+| Heartbeat-check an active Codex session for checkpoint work | `npx aquifer codex-recovery checkpoint-heartbeat --hook-stdin --scope-key project:aquifer` |
+| Preview a Codex UserPromptSubmit heartbeat hook install | `npx aquifer codex-recovery checkpoint-heartbeat-hook --scope-key project:aquifer --hooks-path "$CODEX_HOME/hooks.json" --json` |
 | Inspect storage health | `npx aquifer stats` |
 | Enrich pending sessions | `npx aquifer backfill` |
 
@@ -86,6 +90,15 @@ Timer synthesis output is candidate material until an operator applies it with
 `--promote-candidates`; it does not become active curated memory from the
 prompt or summary file alone.
 
+Checkpoint output follows the same boundary. `operator checkpoint` plans from
+finalized session summaries and only writes `checkpoint_runs` when you pass an
+explicit reviewed synthesis summary with `--apply`. `codex-recovery
+checkpoint-heartbeat` is the active-session hook heartbeat for Codex JSONL
+files: it first checks a tiny local scheduler marker, reads the transcript only
+when the time window is due, then writes local spool process material only when
+the message threshold is also due. It does not print prompt text by default and
+does not write DB memory.
+
 Need LLM summarization, the knowledge graph, OpenAI embeddings, reranking, or operations details? See [docs/setup.md](docs/setup.md) and [Environment Variables](#environment-variables).
 
 ---
@@ -139,6 +152,8 @@ Sessions, summaries, turn-level embeddings, entity graph — all live in one dat
 | Variable | Required? | Purpose | Example |
 |----------|-----------|---------|---------|
 | `DATABASE_URL` | Yes | PostgreSQL connection string | `postgresql://user:pass@localhost:5432/mydb` |
+| `AQUIFER_BACKEND` | No | Backend profile selector: `postgres` full backend or explicit degraded `local` starter | `postgres` |
+| `AQUIFER_LOCAL_PATH` | No | Local starter JSON store path | `.aquifer/aquifer.local.json` |
 | `AQUIFER_SCHEMA` | No | PG schema name (default: `aquifer`) | `memory` |
 | `AQUIFER_TENANT_ID` | No | Multi-tenant key (default: `default`) | `my-app` |
 | `AQUIFER_EMBED_BASE_URL` | Yes (for recall) | Embedding API base URL | `http://localhost:11434/v1` |
@@ -157,6 +172,10 @@ Sessions, summaries, turn-level embeddings, entity graph — all live in one dat
 | `AQUIFER_MEMORY_SERVING_MODE` | No | Public serving mode: `legacy` default, or opt-in `curated` | `curated` |
 | `AQUIFER_MEMORY_ACTIVE_SCOPE_KEY` | No | Default active curated scope for recall/bootstrap | `project:aquifer` |
 | `AQUIFER_MEMORY_ACTIVE_SCOPE_PATH` | No | Ordered curated scope path for inheritance | `global,project:aquifer` |
+| `AQUIFER_CODEX_CHECKPOINT_CHECK_INTERVAL_MINUTES` | No | Active Codex checkpoint heartbeat time gate (default: `10`) | `10` |
+| `AQUIFER_CODEX_CHECKPOINT_EVERY_MESSAGES` | No | Active Codex checkpoint message delta gate (default: `20`) | `20` |
+| `AQUIFER_CODEX_CHECKPOINT_EVERY_USER_MESSAGES` | No | Optional user-message delta gate | `10` |
+| `AQUIFER_CODEX_CHECKPOINT_QUIET_MS` | No | Quiet period before reading due transcripts (default: `3000`) | `3000` |
 | `AQUIFER_MIGRATIONS_MODE` | No | Startup handshake mode: `apply` (default), `check`, `off` | `apply` |
 | `AQUIFER_MIGRATION_LOCK_TIMEOUT_MS` | No | Advisory-lock wait before `AQ_MIGRATION_LOCK_TIMEOUT` (default 30000) | `30000` |
 | `AQUIFER_INSIGHTS_DEDUP_MODE` | No | Insights semantic dedup mode: `off` (default), `shadow`, `enforce` — env wins over code for this field only, so operators can kill-switch without redeploy | `shadow` |
@@ -219,6 +238,53 @@ Add to your project's `.claude.json` or user-level MCP config:
 
 Tools appear as `mcp__aquifer__session_recall`, `mcp__aquifer__evidence_recall`, `mcp__aquifer__session_bootstrap`, `mcp__aquifer__session_feedback`, `mcp__aquifer__memory_feedback`, `mcp__aquifer__feedback_stats`, `mcp__aquifer__memory_stats`, `mcp__aquifer__memory_pending`.
 
+For Codex long sessions, Aquifer exposes a UserPromptSubmit-friendly heartbeat
+command instead of installing a daemon:
+
+```bash
+npx aquifer codex-recovery checkpoint-heartbeat \
+  --hook-stdin \
+  --scope-key project:aquifer
+```
+
+Run that from a host hook with Codex hook JSON on stdin. The heartbeat uses a
+time-first gate: if the local marker says the next check is not due, it exits
+without validating or reading the transcript. When due, it validates the
+`transcript_path` realpath under the Codex sessions directory, waits for the
+quiet period, checks the configured message delta, and writes a local spool file
+for later review. Scheduler, claim, and spool files live under the Codex state
+directory by default; they are process-control files, not DB memory.
+
+Heartbeat policy resolves as command flags first, then Aquifer env/config, then
+defaults. The default policy is 10 minutes, 20 safe messages, no user-message
+gate, 3000 ms quiet period, and 60000 ms claim TTL. In config files this lives at
+`codex.checkpoint`:
+
+```json
+{
+  "codex": {
+    "checkpoint": {
+      "checkIntervalMinutes": 10,
+      "everyMessages": 20,
+      "quietMs": 3000
+    }
+  }
+}
+```
+
+To prepare the Codex hook entry, generate or apply the merged `hooks.json`:
+
+```bash
+npx aquifer codex-recovery checkpoint-heartbeat-hook \
+  --scope-key project:aquifer \
+  --hooks-path "$CODEX_HOME/hooks.json" \
+  --json
+```
+
+The hook installer is dry-run by default. Add `--apply` only after reviewing the
+merged `UserPromptSubmit` command. `codex-recovery doctor --json` reports whether
+the heartbeat hook is present.
+
 ### OpenClaw
 
 Add to `openclaw.json` under `mcp.servers`:

package/aquifer.config.example.json

@@ -1,4 +1,14 @@
 {
+  "storage": {
+    "backend": "postgres",
+    "postgres": {
+      "url": "postgresql://user:password@localhost:5432/mydb",
+      "max": 10
+    },
+    "local": {
+      "path": ".aquifer/aquifer.local.json"
+    }
+  },
   "db": {
     "url": "postgresql://user:password@localhost:5432/mydb",
     "max": 10
@@ -14,6 +24,15 @@
     "activeScopeKey": null,
     "activeScopePath": null
   },
+  "codex": {
+    "checkpoint": {
+      "checkIntervalMinutes": 10,
+      "everyMessages": 20,
+      "everyUserMessages": null,
+      "quietMs": 3000,
+      "claimTtlMs": 60000
+    }
+  },
   "embed": {
     "baseUrl": "http://localhost:11434/v1",
     "model": "bge-m3",

package/consumers/cli.js

@@ -10,6 +10,7 @@
  *   aquifer recall <query> [options]    Search sessions
  *   aquifer backfill [options]          Enrich pending sessions
  *   aquifer stats [options]             Show database statistics
+ *   aquifer backend-info [--json]       Show selected backend capabilities
  *   aquifer export [options]            Export sessions
  *   aquifer operator ...                Run operator-safe consolidation jobs
  *   aquifer mcp                         Start MCP server
@@ -17,7 +18,9 @@
 
 const fs = require('fs');
 const { createAquiferFromConfig } = require('./shared/factory');
+const { loadConfig } = require('./shared/config');
 const { formatRecallResults } = require('./shared/recall-format');
+const { backendCapabilities } = require('../core/backends/capabilities');
 
 function formatDate(value, fallback) {
   if (!value) return fallback;
@@ -109,6 +112,7 @@ function buildQuickstartSetupHints(env, detected, err) {
     if (!hasDb) {
       hints.push('If you expect local defaults, make sure PostgreSQL is running on localhost:5432.');
       hints.push('Otherwise set DATABASE_URL or AQUIFER_DB_URL explicitly and run quickstart again.');
+      hints.push('To inspect the degraded local starter profile without PostgreSQL, run `AQUIFER_BACKEND=local aquifer backend-info --json`.');
     }
     return hints;
   }
@@ -124,6 +128,7 @@ function buildQuickstartSetupHints(env, detected, err) {
     if (!hasDb) hints.push('PostgreSQL was not autodetected and no DATABASE_URL is set.');
     if (!hasEmbed) hints.push('No embedding provider was autodetected and no embed env is set.');
     hints.push('Try `docker compose up -d`, then run `npx aquifer quickstart` again.');
+    hints.push('To inspect the degraded local starter profile without PostgreSQL, run `AQUIFER_BACKEND=local aquifer backend-info --json`.');
   }
 
   hints.push(`Raw error: ${message}`);
@@ -176,8 +181,8 @@ function parseArgs(argv) {
     'verdict', 'feedback-type', 'note', 'db', 'since', 'min-messages', 'lookback-days', 'max-chars',
     'out', 'active-scope-key', 'active-scope-path', 'cadence', 'period-start', 'period-end',
     'policy-version', 'worker-id', 'apply-token', 'claim-lease-seconds', 'snapshot-as-of',
-    'scope-key', 'scope-keys', 'scope-kind', 'context-key', 'topic-key', 'authority', 'input',
-    'synthesis-summary', 'synthesis-summary-file',
+    'scope-id', 'scope-key', 'scope-keys', 'scope-kind', 'context-key', 'topic-key', 'authority', 'input',
+    'synthesis-summary', 'synthesis-summary-file', 'min-finalizations', 'checkpoint-key',
   ]);
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--') { args._.push(...argv.slice(i + 1)); break; }
@@ -381,15 +386,122 @@ async function cmdStats(aquifer, args) {
   if (args.flags.json) {
     console.log(JSON.stringify(stats, null, 2));
   } else {
+    console.log(`Backend: ${stats.backendKind || 'unknown'} (${stats.backendProfile || 'unknown'})`);
+    console.log(`Serving mode: ${stats.serving?.mode || 'legacy'}`);
+    console.log(`Active scope: ${stats.serving?.activeScopePath?.join(' > ') || stats.serving?.activeScopeKey || 'none'}`);
     console.log(`Sessions: ${stats.sessionTotal} (${Object.entries(stats.sessions).map(([k, v]) => `${k}: ${v}`).join(', ')})`);
     console.log(`Summaries: ${stats.summaries}`);
     console.log(`Turn embeddings: ${stats.turnEmbeddings}`);
     console.log(`Entities: ${stats.entities}`);
+    if (stats.memoryRecords) {
+      console.log(`Memory records: ${stats.memoryRecords.total} (${stats.memoryRecords.active} active, ${stats.memoryRecords.visibleInRecall} recall-visible, ${stats.memoryRecords.visibleInBootstrap} bootstrap-visible)`);
+      if (stats.memoryRecords.latest) console.log(`Memory record range: ${formatDate(stats.memoryRecords.earliest, '?')} — ${formatDate(stats.memoryRecords.latest, '?')}`);
+    }
+    if (stats.sessionFinalizations?.available) {
+      const statusText = Object.entries(stats.sessionFinalizations.statuses || {})
+        .map(([status, count]) => `${status}: ${count}`)
+        .join(', ') || 'none';
+      console.log(`Session finalizations: ${stats.sessionFinalizations.total} (${statusText})`);
+      if (stats.sessionFinalizations.latestFinalizedAt) console.log(`Latest finalization: ${formatDate(stats.sessionFinalizations.latestFinalizedAt, '?')}`);
+    }
     if (stats.earliest) console.log(`Range: ${formatDate(stats.earliest, '?')} — ${formatDate(stats.latest, '?')}`);
+    if ((stats.serving?.mode || 'legacy') !== 'curated') {
+      console.log('Warning: legacy serving returns session/evidence material; configure curated serving with an active scope for current-memory answers.');
+    }
+  }
+}
+
+function selectedBackendInfo(opts = {}) {
+  const config = loadConfig(opts);
+  const backendKind = config.storage.backend;
+  const capabilities = backendCapabilities(backendKind);
+  return {
+    backendKind,
+    backendProfile: capabilities.profile,
+    label: capabilities.label,
+    summary: capabilities.summary,
+    capabilities: capabilities.capabilities,
+    storage: {
+      localPath: config.storage.local.path,
+      postgresUrlConfigured: Boolean(config.storage.postgres.url || config.db.url),
+    },
+    upgradeHint: capabilities.upgradeHint,
+  };
+}
+
+async function cmdBackendInfo(args) {
+  const info = selectedBackendInfo();
+  if (args.flags.json) {
+    console.log(JSON.stringify(info, null, 2));
+    return;
+  }
+
+  console.log(`Backend: ${info.label} (${info.backendKind}/${info.backendProfile})`);
+  console.log(info.summary);
+  console.log(`PostgreSQL URL configured: ${info.storage.postgresUrlConfigured ? 'yes' : 'no'}`);
+  if (info.backendKind === 'local') {
+    console.log(`Local path: ${info.storage.localPath}`);
+  }
+  if (info.upgradeHint) {
+    console.log(`Upgrade: ${info.upgradeHint}`);
+  }
+  console.log('Capabilities:');
+  for (const [name, status] of Object.entries(info.capabilities)) {
+    console.log(`  ${name}: ${status}`);
+  }
+}
+
+async function cmdLocalQuickstart(aquifer) {
+  const cfg = aquifer.getConfig();
+  console.log('Aquifer quickstart — verifying local starter backend.\n');
+
+  console.log('1/5  Preparing local store...');
+  await aquifer.init();
+  console.log(`     OK — ${cfg.backendPath}\n`);
+
+  const sessionId = `quickstart-local-${Date.now()}`;
+  console.log('2/5  Committing test session...');
+  await aquifer.commit(sessionId, [
+    { role: 'user', content: 'Aquifer local starter can store a session without PostgreSQL.' },
+    { role: 'assistant', content: 'Local starter uses JSON persistence and degraded lexical recall.' },
+  ], { agentId: 'quickstart', source: 'quickstart' });
+  console.log('     OK\n');
+
+  console.log('3/5  Checking degraded enrich path...');
+  const enrichResult = await aquifer.enrich(sessionId, {
+    agentId: 'quickstart',
+    skipSummary: true,
+    skipEntities: true,
+  });
+  console.log(`     OK — ${enrichResult.turnsEmbedded} turns embedded (local starter is lexical only)\n`);
+
+  console.log('4/5  Recalling "JSON persistence"...');
+  const results = await aquifer.recall('JSON persistence', { agentId: 'quickstart', limit: 3 });
+  if (results.length === 0) {
+    printQuickstartFailure('local starter could not recall its own test session.', [
+      'The write step succeeded, but lexical recall returned no matches.',
+    ]);
+    process.exitCode = 1;
+    return;
   }
+  console.log(`     OK — ${results.length} result(s), top score: ${results[0].score?.toFixed(3)}\n`);
+
+  console.log('5/5  Cleaning up test data...');
+  if (typeof aquifer.deleteSession === 'function') {
+    await aquifer.deleteSession(sessionId, { agentId: 'quickstart' });
+  }
+  console.log('     OK\n');
+
+  console.log('✓ Aquifer local starter is working.');
+  console.log('  This backend is degraded: use PostgreSQL quickstart for semantic recall, migrations, curated memory, and operator workflows.');
 }
 
 async function cmdQuickstart(aquifer) {
+  if (aquifer.getConfig().backendKind === 'local') {
+    await cmdLocalQuickstart(aquifer);
+    return;
+  }
+
   console.log('Aquifer quickstart — verifying end-to-end setup.\n');
 
   // 1. Migrate
@@ -514,6 +626,51 @@ async function cmdOperator(aquifer, args) {
   const operatorVerb = args._[1] || 'compaction';
   const cadenceVerbs = new Set(['manual', 'daily', 'weekly', 'monthly']);
 
+  if (operatorVerb === 'checkpoint') {
+    const synthesisSummary = readSynthesisSummaryFromFlags(args.flags);
+    const result = await aquifer.checkpoints.runProducer({
+      scopeId: args.flags['scope-id'] || undefined,
+      scopeKind: args.flags['scope-kind'] || undefined,
+      scopeKey: args.flags['scope-key'] || undefined,
+      source: args.flags.source || undefined,
+      agentId: args.flags['agent-id'] || undefined,
+      minFinalizations: args.flags['min-finalizations']
+        ? parsePositiveInt(args.flags['min-finalizations'], 10)
+        : undefined,
+      limit: parsePositiveInt(args.flags.limit, 50),
+      checkpointKey: args.flags['checkpoint-key'] || undefined,
+      policyVersion: args.flags['policy-version'] || undefined,
+      force: args.flags.force === true,
+      apply: args.flags.apply === true,
+      finalize: args.flags.finalize === true,
+      includeSynthesisPrompt: args.flags['include-synthesis-prompt'] === true,
+      synthesisSummary,
+    });
+
+    if (args.flags.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    console.log(result.due
+      ? `Checkpoint due for ${result.scope.scopeKey}: ${result.sourceFinalizationCount} finalized source(s).`
+      : `Checkpoint not ready for ${result.scope.scopeKey}: ${result.sourceFinalizationCount}/${result.minFinalizations} finalized source(s).`);
+    if (result.range) {
+      console.log(`Range: finalization ${result.range.fromFinalizationIdExclusive} -> ${result.range.toFinalizationIdInclusive}`);
+    }
+    if (result.synthesisPrompt) {
+      console.log('\nCheckpoint synthesis prompt:\n');
+      console.log(result.synthesisPrompt);
+    }
+    if (result.run) {
+      console.log(`Run: #${result.run.id} status=${result.run.status}`);
+    } else if (result.runInput) {
+      console.log(`Run input prepared: status=${result.runInput.status}`);
+      console.log('Mode: dry-run only. Re-run with --apply and an explicit synthesis summary to write checkpoint_runs.');
+    }
+    return;
+  }
+
   if (operatorVerb === 'archive-distill') {
     const inputPath = args.flags.input || args._[2];
     if (!inputPath) {
@@ -544,7 +701,7 @@ async function cmdOperator(aquifer, args) {
   }
 
   if (operatorVerb !== 'compaction' && operatorVerb !== 'compact' && !cadenceVerbs.has(operatorVerb)) {
-    console.error('Usage: aquifer operator <compaction|archive-distill> [...]');
+    console.error('Usage: aquifer operator <compaction|checkpoint|archive-distill> [...]');
     process.exit(1);
   }
 
@@ -650,6 +807,7 @@ async function main() {
 Commands:
    quickstart                  Verify end-to-end setup (migrate → commit → enrich → recall)
    migrate                     Run database migrations
+  backend-info                Show selected backend capabilities without connecting to a database
   recall <query>              Search sessions (requires embed config)
   evidence-recall <query>     Search legacy session/evidence plane explicitly
   feedback                    Record trust feedback on a session
@@ -661,7 +819,7 @@ Commands:
   stats                       Show database statistics
   export                      Export sessions as JSONL
   bootstrap                   Show recent session context (for new session start)
-  codex-recovery ...          Inspect or run Codex SessionStart recovery flow
+  codex-recovery ...          Inspect or run Codex recovery/checkpoint flows
    ingest-opencode             Import sessions from OpenCode's local SQLite DB
    mcp                         Start MCP server
 
@@ -697,7 +855,10 @@ Options:
   --include-synthesis-prompt  Include timer synthesis prompt in operator output
   --synthesis-summary JSON    Timer synthesis summary JSON to attach to a compaction plan
   --synthesis-summary-file P  Read timer synthesis summary JSON from file
+  --min-finalizations N       Min finalized session summaries before checkpoint proposal
+  --checkpoint-key KEY        Explicit checkpoint key when applying checkpoint producer output
   --scope-key A,B             Limit compaction snapshot to specific scope keys
+  --scope-id ID               Target scope row id for checkpoint producer
   --scope-kind KIND           Explicit synthesis target scope kind
   --snapshot-as-of ISO        Read active snapshot as of a specific instant
   --claim-lease-seconds N     Override compaction apply lease
@@ -711,6 +872,11 @@ Operator examples:
   aquifer operator compaction daily --include-synthesis-prompt --json
   aquifer operator compaction manual --period-start 2026-04-27T00:00:00Z --period-end 2026-04-28T00:00:00Z --apply
   aquifer operator compaction daily --synthesis-summary-file /tmp/timer-summary.json --apply --promote-candidates --json
+  aquifer operator checkpoint --scope-key project:aquifer --min-finalizations 10 --include-synthesis-prompt --json
+  aquifer operator checkpoint --scope-id 7 --synthesis-summary-file /tmp/checkpoint-summary.json --apply --finalize --json
+  AQUIFER_BACKEND=local aquifer backend-info --json
+  aquifer codex-recovery checkpoint-heartbeat --hook-stdin --scope-key project:aquifer
+  aquifer codex-recovery checkpoint-heartbeat-hook --scope-key project:aquifer --hooks-path "$CODEX_HOME/hooks.json" --json
   aquifer operator archive-distill --input /tmp/archive-snapshot.json --json`);
     process.exit(0);
   }
@@ -743,6 +909,14 @@ Operator examples:
     return;
   }
 
+  if (command === 'backend-info') {
+    if (args.flags.config) {
+      process.env.AQUIFER_CONFIG = args.flags.config;
+    }
+    await cmdBackendInfo(args);
+    return;
+  }
+
   // All other commands need an Aquifer instance
   const configOverrides = {};
   if (args.flags.config) {
@@ -755,15 +929,18 @@ Operator examples:
   // Production commands (migrate, mcp, recall, ...) stay strict — they expect
   // the operator to have set env explicitly.
   if (command === 'quickstart') {
-    const { autodetectForQuickstart } = require('./shared/autodetect');
-    quickstartDetected = await autodetectForQuickstart(process.env);
-    if (Object.keys(quickstartDetected).length > 0) {
-      console.log('Autodetected localhost services (env not set):');
-      for (const [k, v] of Object.entries(quickstartDetected)) {
-        console.log(`  ${k}=${v}`);
-        process.env[k] = v;
+    const selected = loadConfig({ overrides: configOverrides });
+    if (selected.storage.backend !== 'local') {
+      const { autodetectForQuickstart } = require('./shared/autodetect');
+      quickstartDetected = await autodetectForQuickstart(process.env);
+      if (Object.keys(quickstartDetected).length > 0) {
+        console.log('Autodetected localhost services (env not set):');
+        for (const [k, v] of Object.entries(quickstartDetected)) {
+          console.log(`  ${k}=${v}`);
+          process.env[k] = v;
+        }
+        console.log('  Export these in your shell (or MCP client env) to make them permanent.\n');
       }
-      console.log('  Export these in your shell (or MCP client env) to make them permanent.\n');
     }
   }
 
@@ -837,6 +1014,9 @@ Operator examples:
 // Export for testing; execute only when run directly
 module.exports = {
   parseArgs,
+  selectedBackendInfo,
+  cmdBackendInfo,
+  cmdLocalQuickstart,
   cmdOperator,
   readSynthesisSummaryFromFlags,
 };

package/consumers/codex-active-checkpoint.js

@@ -0,0 +1,186 @@
+'use strict';
+
+const {
+    buildCheckpointCoverageFromView,
+    hashSnapshot,
+    promptSafeSynthesisInput,
+    stableJson,
+} = require('../core/session-checkpoint-producer');
+const { compactCurrentMemorySnapshot } = require('./codex-current-memory');
+
+function positiveInt(value, fallback, max = 100000) {
+    const n = Number(value === undefined || value === null || value === '' ? fallback : value);
+    if (!Number.isFinite(n)) return fallback;
+    return Math.max(1, Math.min(max, Math.trunc(n)));
+}
+
+function buildActiveCheckpointScopeEnvelope(opts = {}) {
+    const envelope = opts.scopeEnvelope || opts.scope_envelope;
+    if (envelope && typeof envelope === 'object') return envelope;
+    const scopeKey = String(opts.activeScopeKey || opts.scopeKey || opts.scope_key || '').trim();
+    if (!scopeKey) {
+        throw new Error('active session checkpoint requires activeScopeKey or scopeKey');
+    }
+    const scopeKind = String(opts.activeScopeKind || opts.scopeKind || opts.scope_kind || 'project').trim();
+    const slotId = scopeKind === 'host_runtime' ? 'host' : (
+        ['workspace', 'project', 'repo', 'task', 'session'].includes(scopeKind) ? scopeKind : 'target'
+    );
+    const promotable = !['session', 'task'].includes(slotId);
+    const slot = {
+        id: slotId,
+        slot: slotId,
+        scopeKind,
+        scopeKey,
+        label: scopeKey,
+        promotable,
+        allowedScopeKeys: promotable ? ['global', scopeKey] : ['global'],
+    };
+    if (!promotable) {
+        throw new Error(`active session checkpoint target scope is not promotable: ${scopeKind}`);
+    }
+    return {
+        policyVersion: 'scope_envelope_v1',
+        activeSlotId: slot.id,
+        activeScopeKey: scopeKey,
+        allowedScopeKeys: slot.allowedScopeKeys,
+        slots: [slot],
+        scopeById: { [slot.id]: slot },
+    };
+}
+
+function buildActiveSessionCheckpointInput(view = {}, opts = {}) {
+    if (!view || view.status !== 'ok') {
+        throw new Error(`active session checkpoint requires an ok transcript view; got ${view && view.status ? view.status : 'missing'}`);
+    }
+    const messageCount = Number.isFinite(Number(view.counts?.safeMessageCount))
+        ? Number(view.counts.safeMessageCount)
+        : (Array.isArray(view.messages) ? view.messages.length : 0);
+    const userCount = Number(view.counts?.userCount || view.messages?.filter?.(m => m.role === 'user').length || 0);
+    const everyMessages = positiveInt(opts.checkpointEveryMessages || opts.everyMessages, 20, 1000);
+    const everyUserMessages = opts.checkpointEveryUserMessages || opts.everyUserMessages
+        ? positiveInt(opts.checkpointEveryUserMessages || opts.everyUserMessages, 10, 1000)
+        : null;
+    const force = opts.force === true;
+    const due = force
+        || messageCount >= everyMessages
+        || (everyUserMessages !== null && userCount >= everyUserMessages);
+    const base = {
+        kind: 'codex_active_session_checkpoint_input_v1',
+        policyVersion: opts.policyVersion || 'codex_active_session_checkpoint_v1',
+        sourceOfTruth: 'codex_sanitized_live_transcript_view',
+        triggerKind: opts.triggerKind || 'message_count',
+        promotion: {
+            default: 'checkpoint_proposal_only',
+            requires: 'handoff_or_operator_review',
+        },
+        guards: {
+            checkpointIsProcessMaterial: true,
+            activeMemoryCommitExcluded: true,
+            dbWriteExcluded: true,
+            rawToolOutputExcluded: true,
+            debugIdsExcluded: true,
+        },
+        threshold: {
+            everyMessages,
+            everyUserMessages,
+            messageCount,
+            userCount,
+            due,
+        },
+        targetScope: {
+            activeScopeKey: opts.activeScopeKey || opts.scopeKey || null,
+            activeScopePath: opts.activeScopePath || null,
+        },
+        scopeEnvelope: buildActiveCheckpointScopeEnvelope(opts),
+        coverage: buildCheckpointCoverageFromView(view, opts),
+        transcript: {
+            sessionId: view.sessionId || null,
+            charCount: view.charCount ?? String(view.text || '').length,
+            fullCharCount: view.fullCharCount ?? view.counts?.fullCharCount ?? view.charCount ?? String(view.text || '').length,
+            approxPromptTokens: view.approxPromptTokens || Math.ceil(String(view.text || '').length / 3),
+            fullApproxPromptTokens: view.fullApproxPromptTokens || view.counts?.fullApproxPromptTokens || null,
+            truncated: Boolean(view.truncated || view.transcriptWindow?.truncated),
+            transcriptWindow: view.transcriptWindow || null,
+            text: view.text || '',
+        },
+        currentMemory: compactCurrentMemorySnapshot(opts.currentMemory || null, opts),
+    };
+    return {
+        ...base,
+        inputHash: hashSnapshot(base),
+    };
+}
+
+function buildActiveSessionCheckpointPrompt(checkpointInput = {}, opts = {}) {
+    if (!checkpointInput || checkpointInput.kind !== 'codex_active_session_checkpoint_input_v1') {
+        throw new Error('buildActiveSessionCheckpointPrompt requires an active session checkpoint input');
+    }
+    const promptInput = promptSafeSynthesisInput(checkpointInput);
+    const maxFacts = Math.max(1, Math.min(24, opts.maxFacts || 8));
+    return [
+        'You are producing an Aquifer active-session checkpoint proposal for Codex.',
+        'Use only the <active_checkpoint_input> block. Do not use hidden tool output, injected context, or debug material.',
+        'This checkpoint is process material for later handoff. It is not active current memory and must not be treated as final truth.',
+        'Return compact JSON with this shape:',
+        '{"summaryText":"...","structuredSummary":{"facts":[],"decisions":[],"open_loops":[],"preferences":[],"constraints":[],"conclusions":[],"entity_notes":[],"states":[]},"coverage":{"coordinateSystem":"codex_sanitized_view_v1","coveredUntilMessageIndex":0,"coveredUntilChar":0}}',
+        `Keep facts/decisions/open_loops concrete and scoped. Use at most ${maxFacts} facts.`,
+        'Preserve the coverage object so a later handoff can skip the already-covered transcript prefix.',
+        '',
+        '<active_checkpoint_input>',
+        stableJson(promptInput),
+        '</active_checkpoint_input>',
+    ].join('\n');
+}
+
+async function prepareActiveSessionCheckpoint(aquifer, opts = {}, deps = {}) {
+    const materializeRecoveryTranscriptView = deps.materializeRecoveryTranscriptView;
+    const resolveCurrentMemoryForFinalization = deps.resolveCurrentMemoryForFinalization || (async () => null);
+    const view = opts.view || (opts.filePath && typeof materializeRecoveryTranscriptView === 'function'
+        ? materializeRecoveryTranscriptView({
+            filePath: opts.filePath,
+            sessionId: opts.sessionId,
+        }, {
+            ...opts,
+            maxRecoveryBytes: opts.maxCheckpointBytes ?? opts.maxRecoveryBytes,
+            maxRecoveryMessages: opts.maxCheckpointMessages ?? opts.maxRecoveryMessages,
+            maxRecoveryChars: opts.maxCheckpointChars ?? opts.maxRecoveryChars,
+            maxRecoveryPromptTokens: opts.maxCheckpointPromptTokens ?? opts.maxRecoveryPromptTokens,
+        })
+        : null);
+    if (!view || view.status !== 'ok') {
+        return {
+            status: view?.status || 'missing_view',
+            reason: view?.reason || null,
+            view,
+        };
+    }
+    const currentMemory = await resolveCurrentMemoryForFinalization(aquifer, opts);
+    const checkpointInput = buildActiveSessionCheckpointInput(view, {
+        ...opts,
+        currentMemory,
+    });
+    if (!checkpointInput.threshold.due) {
+        return {
+            status: 'not_ready',
+            due: false,
+            checkpointInput,
+            view,
+            currentMemory,
+        };
+    }
+    return {
+        status: 'needs_agent_checkpoint',
+        due: true,
+        outputSchemaVersion: 'codex_active_session_checkpoint_v1',
+        checkpointInput,
+        view,
+        currentMemory,
+        prompt: buildActiveSessionCheckpointPrompt(checkpointInput, opts),
+    };
+}
+
+module.exports = {
+    buildActiveSessionCheckpointInput,
+    buildActiveSessionCheckpointPrompt,
+    prepareActiveSessionCheckpoint,
+};