@shadowforge0/aquifer-memory 1.8.1 → 1.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shadowforge0/aquifer-memory",
-  "version": "1.8.1",
+  "version": "1.9.1",
   "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": [
@@ -18,6 +18,7 @@
     "consumers/codex-active-checkpoint.js",
     "consumers/codex-current-memory.js",
     "consumers/codex-handoff.js",
+    "consumers/openclaw-install.js",
     "consumers/openclaw-plugin.js",
     "consumers/opencode.js",
     "consumers/shared/",
@@ -71,9 +72,9 @@
   "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/local-backend.test.js test/scope-attribution.test.js test/v1-checkpoint-ledger-schema.test.js test/v1-finalization-envelope-schema.test.js test/v1-evidence-items.test.js test/v1-curated-semantic-recall.test.js test/session-checkpoints.test.js test/session-checkpoint-producer.test.js test/session-checkpoint-planner.test.js test/storage-checkpoint-ranges.test.js test/v1-serving-cutover.test.js test/v1-current-memory-contract.test.js test/v1-scope-inheritance.golden.test.js test/v1-bootstrap-determinism.test.js test/consumer-codex.test.js test/codex-recovery-script.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/v1-evidence-items.test.js 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 core/backends/*.js consumers/cli.js consumers/mcp.js consumers/claude-code.js consumers/codex.js consumers/codex-active-checkpoint.js consumers/codex-current-memory.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",
+    "test:release:package": "node --test test/package-surface.test.js test/mcp-manifest.test.js test/local-backend.test.js test/scope-attribution.test.js test/doctor.test.js test/finalization-inspector.test.js test/memory-explain.test.js test/memory-review.test.js test/operator-observability.test.js test/storage-finalization-status.test.js test/cli-parseargs.test.js test/v1-checkpoint-ledger-schema.test.js test/v1-finalization-envelope-schema.test.js test/v1-memory-review-resolutions-schema.test.js test/v1-evidence-items.test.js test/v1-curated-semantic-recall.test.js test/session-checkpoints.test.js test/session-checkpoint-producer.test.js test/session-checkpoint-planner.test.js test/storage-checkpoint-ranges.test.js test/v1-serving-cutover.test.js test/v1-current-memory-contract.test.js test/v1-assistant-shaping-memory.test.js test/v1-assistant-shaping-review-explain.test.js test/v1-scope-inheritance.golden.test.js test/v1-bootstrap-determinism.test.js test/consumer-codex.test.js test/codex-recovery-script.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-concurrency=1 test/v1-evidence-items.test.js test/memory-review.integration.test.js 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 core/backends/*.js consumers/cli.js consumers/mcp.js consumers/claude-code.js consumers/codex.js consumers/codex-active-checkpoint.js consumers/codex-current-memory.js consumers/codex-handoff.js consumers/openclaw-install.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"
   },
   "dependencies": {

package/schema/004-completion.sql

@@ -9,8 +9,8 @@
 --   * consumer_profiles table — consumer schema registry with composite primary key
 --     (tenant_id, consumer_id, version) for future multi-tenant safety
 --
--- All identifiers stay parameterised on ${schema} so P4 schema rename
--- (miranda → aquifer) is a one-line config change rather than a DDL rewrite.
+-- All identifiers stay parameterised on ${schema} so schema renames remain a
+-- config change rather than a DDL rewrite.
 
 -- Ensure pg_trgm available (used by existing migrations; re-declared for independent
 -- run safety).
@@ -141,8 +141,8 @@ CREATE TRIGGER trg_consumer_profiles_updated_at
   EXECUTE FUNCTION ${schema}.set_updated_at();
 
 -- timeline_events: append-only event log keyed by (tenant, agent, occurred_at).
--- category vocabulary is consumer-owned (focus/todo/mood/handoff/narrative/cli
--- for Miranda default), event shape is strict core. idempotency_key UNIQUE
+-- category vocabulary is consumer-owned, event shape is strict core.
+-- idempotency_key UNIQUE
 -- across the table to make caller-driven dedupe safe.
 CREATE TABLE IF NOT EXISTS ${schema}.timeline_events (
   id                          BIGSERIAL    PRIMARY KEY,

package/schema/010-v1-finalization-review.sql

@@ -43,6 +43,78 @@ ALTER TABLE ${schema}.fact_assertions_v1
     'tombstoned','quarantined','archived','incorrect'
   ));
 
+ALTER TABLE ${schema}.memory_records
+  DROP CONSTRAINT IF EXISTS memory_records_lifecycle_consistency_check;
+
+ALTER TABLE ${schema}.memory_records
+  ADD CONSTRAINT memory_records_lifecycle_consistency_check
+  CHECK (
+    (valid_to IS NULL OR valid_from IS NULL OR valid_to > valid_from)
+    AND (revoked_at IS NULL OR accepted_at IS NULL OR revoked_at >= accepted_at)
+    AND (superseded_at IS NULL OR accepted_at IS NULL OR superseded_at >= accepted_at)
+    AND NOT (revoked_at IS NOT NULL AND superseded_at IS NOT NULL)
+    AND (status <> 'active' OR (
+      revoked_at IS NULL
+      AND superseded_at IS NULL
+      AND superseded_by IS NULL
+    ))
+    AND (status <> 'superseded' OR superseded_at IS NOT NULL)
+    AND (status <> 'revoked' OR revoked_at IS NOT NULL)
+  ) NOT VALID;
+
+ALTER TABLE ${schema}.fact_assertions_v1
+  DROP CONSTRAINT IF EXISTS fact_assertions_v1_lifecycle_consistency_check;
+
+ALTER TABLE ${schema}.fact_assertions_v1
+  ADD CONSTRAINT fact_assertions_v1_lifecycle_consistency_check
+  CHECK (
+    (valid_to IS NULL OR valid_from IS NULL OR valid_to > valid_from)
+    AND (revoked_at IS NULL OR accepted_at IS NULL OR revoked_at >= accepted_at)
+    AND (superseded_at IS NULL OR accepted_at IS NULL OR superseded_at >= accepted_at)
+    AND NOT (revoked_at IS NOT NULL AND superseded_at IS NOT NULL)
+    AND (status <> 'active' OR (
+      revoked_at IS NULL
+      AND superseded_at IS NULL
+      AND superseded_by IS NULL
+    ))
+    AND (status <> 'superseded' OR superseded_at IS NOT NULL)
+    AND (status <> 'revoked' OR revoked_at IS NOT NULL)
+  ) NOT VALID;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.memory_records'::regclass
+       AND conname = 'memory_records_superseded_by_tenant_fk'
+  ) THEN
+    ALTER TABLE ${schema}.memory_records
+      ADD CONSTRAINT memory_records_superseded_by_tenant_fk
+      FOREIGN KEY (tenant_id, superseded_by)
+      REFERENCES ${schema}.memory_records (tenant_id, id)
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.fact_assertions_v1'::regclass
+       AND conname = 'fact_assertions_v1_superseded_by_tenant_fk'
+  ) THEN
+    ALTER TABLE ${schema}.fact_assertions_v1
+      ADD CONSTRAINT fact_assertions_v1_superseded_by_tenant_fk
+      FOREIGN KEY (tenant_id, superseded_by)
+      REFERENCES ${schema}.fact_assertions_v1 (tenant_id, id)
+      NOT VALID;
+  END IF;
+END;
+$$;
+
 -- =========================================================================
 -- Row-level finalization lineage
 -- =========================================================================

package/schema/019-v1-memory-review-resolutions.sql

@@ -0,0 +1,53 @@
+-- Aquifer v1 memory review resolution ledger
+-- Requires: 007-v1-foundation.sql
+--
+-- This migration is additive. Review resolutions close or defer operator queue
+-- items without mutating memory_records or rewriting feedback history.
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_records_tenant_id_id
+  ON ${schema}.memory_records (tenant_id, id);
+
+CREATE INDEX IF NOT EXISTS idx_feedback_memory_review_latest
+  ON ${schema}.feedback (tenant_id, target_id, feedback_type, created_at DESC, id DESC)
+  WHERE target_kind = 'memory_record';
+
+CREATE TABLE IF NOT EXISTS ${schema}.memory_review_resolutions (
+  id                        BIGSERIAL    PRIMARY KEY,
+  tenant_id                 TEXT         NOT NULL DEFAULT 'default',
+  memory_id                 BIGINT       NOT NULL,
+  canonical_key             TEXT         NOT NULL CHECK (btrim(canonical_key) <> ''),
+  scope_id                  BIGINT,
+  resolution                TEXT         NOT NULL
+                                CHECK (resolution IN ('resolved','ignored','deferred')),
+  reason                    TEXT,
+  actor_kind                TEXT         NOT NULL DEFAULT 'user'
+                                CHECK (actor_kind IN ('user','agent','system','curator')),
+  actor_id                  TEXT,
+  issue_feedback_types      TEXT[]       NOT NULL DEFAULT '{}'::text[],
+  resolved_through_feedback_id BIGINT,
+  resolved_through_feedback_at TIMESTAMPTZ,
+  defer_until               TIMESTAMPTZ,
+  metadata                  JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  resolved_at               TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  created_at                TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  FOREIGN KEY (tenant_id, memory_id)
+    REFERENCES ${schema}.memory_records (tenant_id, id) ON DELETE RESTRICT,
+  FOREIGN KEY (scope_id)
+    REFERENCES ${schema}.scopes(id) ON DELETE SET NULL,
+  CHECK (jsonb_typeof(metadata) = 'object'),
+  CHECK (defer_until IS NULL OR resolution = 'deferred'),
+  CHECK (defer_until IS NULL OR defer_until > resolved_at)
+);
+
+CREATE INDEX IF NOT EXISTS idx_memory_review_resolutions_memory_latest
+  ON ${schema}.memory_review_resolutions (tenant_id, memory_id, resolved_at DESC, id DESC);
+
+CREATE INDEX IF NOT EXISTS idx_memory_review_resolutions_canonical_latest
+  ON ${schema}.memory_review_resolutions (tenant_id, canonical_key, resolved_at DESC, id DESC);
+
+CREATE INDEX IF NOT EXISTS idx_memory_review_resolutions_defer_until
+  ON ${schema}.memory_review_resolutions (tenant_id, defer_until)
+  WHERE resolution = 'deferred' AND defer_until IS NOT NULL;
+
+COMMENT ON TABLE ${schema}.memory_review_resolutions IS
+  'Append-only operator ledger for memory review queue resolutions. Does not mutate curated memory truth.';

package/schema/020-v1-assistant-shaping-memory.sql

@@ -0,0 +1,30 @@
+-- Aquifer v1 assistant-shaping memory layer
+-- Requires: 007-v1-foundation.sql
+-- Usage: replace ${schema} with actual schema name
+--
+-- Adds a product-level memory type for user-facing assistant shaping:
+-- response style, retrieval policy, interaction boundaries, and tool routing.
+-- This remains curated memory, not a host/persona-specific schema concept.
+
+ALTER TABLE ${schema}.memory_records
+  DROP CONSTRAINT IF EXISTS memory_records_memory_type_check;
+
+ALTER TABLE ${schema}.memory_records
+  ADD CONSTRAINT memory_records_memory_type_check
+  CHECK (memory_type IN (
+    'assistant_shaping',
+    'fact','state','decision','preference','constraint',
+    'entity_note','open_loop','conclusion'
+  ));
+
+CREATE INDEX IF NOT EXISTS idx_memory_records_assistant_shaping_bootstrap
+  ON ${schema}.memory_records (tenant_id, scope_id, status, accepted_at DESC, id)
+  WHERE status = 'active'
+    AND memory_type = 'assistant_shaping'
+    AND visible_in_bootstrap;
+
+COMMENT ON CONSTRAINT memory_records_memory_type_check ON ${schema}.memory_records IS
+  'Allowed curated memory types. assistant_shaping stores user-facing assistant behavior and retrieval policy, not host-specific persona code.';
+
+COMMENT ON INDEX ${schema}.idx_memory_records_assistant_shaping_bootstrap IS
+  'Fast path for high-priority assistant-shaping memories during bootstrap materialization.';

package/scripts/backfill-canonical-key.js

@@ -32,7 +32,7 @@ function printUsageAndExit(code = 0) {
     'Usage: node scripts/backfill-canonical-key.js --schema <name> [options]',
     '',
     'Required:',
-    '  --schema <name>        Target schema (e.g. miranda, jenny)',
+    '  --schema <name>        Target schema (e.g. aquifer, app_memory)',
     '  --agent <id>           Limit to one agent (or use --all-agents)',
     '',
     'Optional:',

package/scripts/codex-checkpoint-commands.js

@@ -21,6 +21,7 @@ const {
   defaultHooksPath,
   findNewestJsonlFile,
   isoAt,
+  listCheckpointSpool,
   loadRuntimeConfig,
   mergeCheckpointHeartbeatHook,
   readCheckpointMarker,
@@ -215,6 +216,32 @@ function emitCheckpointHeartbeatResult(result, flags = {}) {
   if (flags.json) console.log(JSON.stringify(result, null, 2));
 }
 
+async function cmdCheckpointSpoolStatus(aquifer, flags, opts) {
+  const result = listCheckpointSpool(flags, opts);
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result;
+  }
+  const lines = [
+    `Spool: ${result.spoolDir}`,
+    `Pending proposals: ${result.count} across ${result.sessionCount} sessions`,
+  ];
+  if (result.latestMtime) lines.push(`Latest: ${result.latestMtime}`);
+  for (const row of result.files) {
+    const covered = row.coverage?.coveredUntilMessageIndex;
+    lines.push([
+      `- ${row.fileName}`,
+      `session=${row.sessionId || '?'}`,
+      `mtime=${row.mtime || '?'}`,
+      `bytes=${row.bytes || 0}`,
+      `coveredUntilMessageIndex=${covered ?? '?'}`,
+      `promptChars=${row.promptChars || 0}`,
+    ].join(' '));
+  }
+  console.log(lines.join('\n'));
+  return result;
+}
+
 async function cmdCheckpointHeartbeat(aquifer, flags, opts, hookInputArg) {
   const hookInput = hookInputArg || (flags['hook-stdin'] === true ? readHookInputFromStdin() : {});
   const input = checkpointHeartbeatInput(flags, hookInput);
@@ -457,6 +484,7 @@ module.exports = {
   cmdCheckpointHeartbeat,
   cmdCheckpointHeartbeatHook,
   cmdCheckpointPrompt,
+  cmdCheckpointSpoolStatus,
   cmdCheckpointTick,
   emitCheckpointHeartbeatResult,
   parseScopePath,

package/scripts/codex-checkpoint-runtime.js

@@ -377,6 +377,114 @@ function spoolCheckpointProposal(dir, prepared = {}, meta = {}) {
   return { filePath, createdAt: payload.createdAt };
 }
 
+function summarizeCheckpointSpoolFile(filePath) {
+  const parsed = readJsonFile(filePath);
+  let stat;
+  try {
+    stat = fs.statSync(filePath);
+  } catch {
+    return null;
+  }
+  if (!parsed || parsed.kind !== 'codex_active_checkpoint_pending_v1') {
+    return {
+      filePath,
+      fileName: path.basename(filePath),
+      bytes: stat.size,
+      mtime: stat.mtime.toISOString(),
+      parseable: !!parsed,
+      kind: parsed?.kind || null,
+      ignored: true,
+    };
+  }
+  return {
+    filePath,
+    fileName: path.basename(filePath),
+    bytes: stat.size,
+    mtime: stat.mtime.toISOString(),
+    parseable: true,
+    ignored: false,
+    kind: parsed.kind,
+    createdAt: parsed.createdAt || null,
+    sessionId: parsed.sessionId || null,
+    source: parsed.source || null,
+    hookEventName: parsed.hookEventName || null,
+    triggerKind: parsed.triggerKind || null,
+    threshold: parsed.threshold || null,
+    coverage: parsed.coverage || null,
+    guards: parsed.guards || null,
+    hasPrompt: typeof parsed.prompt === 'string' && parsed.prompt.length > 0,
+    promptChars: typeof parsed.prompt === 'string' ? parsed.prompt.length : 0,
+  };
+}
+
+function listCheckpointSpool(flags = {}, opts = {}) {
+  const dir = checkpointSpoolDir(flags, opts);
+  const limit = Math.max(1, Math.min(200, parseIntFlag(flags.limit, 20)));
+  let entries = [];
+  try {
+    entries = fs.readdirSync(dir);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return {
+        status: 'ok',
+        spoolDir: dir,
+        count: 0,
+        returned: 0,
+        sessionCount: 0,
+        totalBytes: 0,
+        latestMtime: null,
+        files: [],
+        sessions: [],
+      };
+    }
+    throw err;
+  }
+  const sessionFilter = flags['session-id'] && flags['session-id'] !== true
+    ? String(flags['session-id'])
+    : null;
+  const rows = entries
+    .filter(fileName => fileName.endsWith('.json'))
+    .map(fileName => summarizeCheckpointSpoolFile(path.join(dir, fileName)))
+    .filter(Boolean)
+    .filter(row => !sessionFilter || row.sessionId === sessionFilter)
+    .sort((a, b) => String(b.mtime || '').localeCompare(String(a.mtime || '')));
+  const validRows = rows.filter(row => !row.ignored);
+  const sessions = new Map();
+  for (const row of validRows) {
+    const sessionId = row.sessionId || 'unknown';
+    const current = sessions.get(sessionId) || {
+      sessionId,
+      count: 0,
+      latestMtime: null,
+      maxCoveredUntilMessageIndex: null,
+    };
+    current.count += 1;
+    current.latestMtime = !current.latestMtime || String(row.mtime).localeCompare(current.latestMtime) > 0
+      ? row.mtime
+      : current.latestMtime;
+    const covered = row.coverage?.coveredUntilMessageIndex;
+    if (Number.isFinite(Number(covered))) {
+      current.maxCoveredUntilMessageIndex = Math.max(
+        current.maxCoveredUntilMessageIndex ?? Number(covered),
+        Number(covered),
+      );
+    }
+    sessions.set(sessionId, current);
+  }
+  return {
+    status: 'ok',
+    spoolDir: dir,
+    count: rows.length,
+    returned: Math.min(rows.length, limit),
+    sessionCount: sessions.size,
+    totalBytes: rows.reduce((sum, row) => sum + Number(row.bytes || 0), 0),
+    latestMtime: rows[0]?.mtime || null,
+    files: rows.slice(0, limit),
+    sessions: Array.from(sessions.values())
+      .sort((a, b) => String(b.latestMtime || '').localeCompare(String(a.latestMtime || ''))),
+  };
+}
+
 function shellQuote(value) {
   return `'${String(value || '').replace(/'/g, `'\\''`)}'`;
 }
@@ -506,6 +614,7 @@ module.exports = {
   inspectCheckpointHeartbeatHook,
   isoAt,
   loadRuntimeConfig,
+  listCheckpointSpool,
   mergeCheckpointHeartbeatHook,
   readCheckpointMarker,
   readHooksConfig,

package/scripts/codex-recovery.js

@@ -11,6 +11,7 @@ const {
   cmdCheckpointHeartbeat,
   cmdCheckpointHeartbeatHook,
   cmdCheckpointPrompt,
+  cmdCheckpointSpoolStatus,
   cmdCheckpointTick,
 } = require('./codex-checkpoint-commands');
 const {
@@ -29,6 +30,7 @@ const {
   defaultHooksPath,
   findNewestJsonlFile,
   inspectCheckpointHeartbeatHook,
+  listCheckpointSpool,
   loadRuntimeConfig,
   mergeCheckpointHeartbeatHook,
   readCheckpointMarker,
@@ -38,6 +40,7 @@ const {
   writeSchedulerMarker,
 } = require('./codex-checkpoint-runtime');
 const DB_ENV_KEYS = new Set(['DATABASE_URL', 'AQUIFER_DB_URL', 'AQUIFER_SCHEMA', 'AQUIFER_TENANT_ID']);
+const DECISION_VERDICTS = ['declined', 'deferred', 'skipped'];
 
 const VALUE_FLAGS = new Set([
   'agent-id',
@@ -59,6 +62,7 @@ const VALUE_FLAGS = new Set([
   'hook-event-name',
   'hooks-path',
   'idle-ms',
+  'limit',
   'max-checkpoint-bytes',
   'max-checkpoint-chars',
   'max-checkpoint-messages',
@@ -575,8 +579,8 @@ async function cmdFinalize(aquifer, flags, opts) {
 
 async function cmdDecision(aquifer, flags, opts) {
   const verdict = flags.verdict;
-  if (!['declined', 'deferred'].includes(verdict)) {
-    throw new Error('decision requires --verdict declined|deferred');
+  if (!DECISION_VERDICTS.includes(verdict)) {
+    throw new Error(`decision requires --verdict ${DECISION_VERDICTS.join('|')}`);
   }
   const candidates = await listOperationalCandidates(aquifer, opts);
   if (flags.all === true) {
@@ -664,10 +668,11 @@ async function main(argv = process.argv.slice(2)) {
   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-spool-status [--json] [--limit N] [--session-id ID]
   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 --session-id ID --verdict declined|deferred|skipped [options]
+  node scripts/codex-recovery.js decision --all --verdict declined|deferred|skipped [options]
   node scripts/codex-recovery.js doctor [--strict-wrapper-env] [--json]`);
     return;
   }
@@ -693,6 +698,11 @@ async function main(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (command === 'checkpoint-spool-status') {
+    await cmdCheckpointSpoolStatus(null, args.flags, opts);
+    return;
+  }
+
   await withAquifer(async (aquifer) => {
     switch (command) {
       case 'preview':
@@ -733,6 +743,7 @@ module.exports = {
   cmdCheckpointHeartbeat,
   cmdCheckpointHeartbeatHook,
   cmdCheckpointPrompt,
+  cmdCheckpointSpoolStatus,
   cmdCheckpointTick,
   cmdPrompt,
   acquireHeartbeatClaim,
@@ -750,6 +761,7 @@ module.exports = {
   defaultHooksPath,
   findNewestJsonlFile,
   inspectCheckpointHeartbeatHook,
+  listCheckpointSpool,
   loadRuntimeConfig,
   loadCodexEnv,
   main,

package/scripts/diagnose-fts-zh.js

@@ -27,7 +27,7 @@ const SCHEMA = process.env.AQUIFER_SCHEMA || 'public';
 
 const DEFAULT_QUERIES = [
   // latin
-  'afterburn', 'bootstrap', 'session', 'recall', 'entity', 'OpenCode', 'Jenny', 'Aquifer',
+  'afterburn', 'bootstrap', 'session', 'recall', 'entity', 'OpenCode', 'ExampleUser', 'Aquifer',
   // CJK short tokens — 最容易暴露 tokenizer 問題
   '記憶', '時區', '去重', '架構', '修復',
   // CJK phrase

package/scripts/extract-insights-from-recent-sessions.js

@@ -17,7 +17,7 @@
  *     [--days 14] \
  *     [--max-sessions 50] \
  *     [--types preference,pattern,frustration,workflow] \
- *     [--schema miranda] \
+ *     [--schema aquifer] \
  *     [--tenant-id default] \
  *     [--dry-run]
  *
@@ -71,7 +71,7 @@ function parseArgs(argv) {
     days: 14,
     maxSessions: 50,
     types: ['preference', 'pattern', 'frustration', 'workflow'],
-    schema: process.env.AQUIFER_SCHEMA || 'miranda',
+    schema: process.env.AQUIFER_SCHEMA || 'aquifer',
     tenantId: process.env.AQUIFER_TENANT_ID || 'default',
     dryRun: false,
   };
@@ -109,8 +109,8 @@ themes. Returning only 2-3 on a rich window means you're under-extracting.
 Returning 0 is only correct when the window is genuinely sparse.
 
 ## Insight types
-- preference: stable user preference (e.g. "MK prefers terse responses with no trailing summaries")
-- pattern: recurring behaviour or decision (e.g. "MK runs /develop before any non-trivial schema change")
+- preference: stable user preference (e.g. "The user prefers terse responses with no trailing summaries")
+- pattern: recurring behaviour or decision (e.g. "The user runs a planning workflow before non-trivial schema changes")
 - frustration: repeated pain point (e.g. "Cron jobs.json prompt parse keeps breaking on minor LLM output drift")
 - workflow: reusable procedure that worked (e.g. "Aquifer release: pack tarball -> bump gateway pkg -> migrate -> restart")