@shadowforge0/aquifer-memory 1.8.1 → 1.9.0

package/docs/getting-started.md

@@ -73,20 +73,40 @@ Or run the server directly:
 DATABASE_URL=... EMBED_PROVIDER=ollama npx aquifer mcp
 ```
 
-For first rollout, keep `AQUIFER_MEMORY_SERVING_MODE=legacy`. Switch to `curated` only when you want `session_recall` and `session_bootstrap` to serve active curated memory; `evidence_recall` remains the explicit evidence/debug tool in both modes. Rollback is just setting env or config back to `legacy`.
+For first rollout, keep `AQUIFER_MEMORY_SERVING_MODE=legacy`. Switch to `curated` only when you want compatibility `session_recall` and `session_bootstrap` to serve active curated memory. Use `memory_recall` for explicit current-memory lookup, `historical_recall` for the historical/session plane, and `evidence_recall` for the audit/debug lane. Rollback is just setting env or config back to `legacy`.
+
+## Connect OpenClaw
+
+For OpenClaw, use the host installer instead of wiring each consumer by hand:
+
+```bash
+npm install --prefix "$OPENCLAW_HOME" @shadowforge0/aquifer-memory@latest
+node "$OPENCLAW_HOME/node_modules/@shadowforge0/aquifer-memory/consumers/cli.js" install-openclaw --openclaw-home "$OPENCLAW_HOME"
+```
+
+The installer links and enables the optional OpenClaw extension, updates `plugins.load.paths` / `plugins.entries["aquifer-memory"]`, and points `mcp.servers.aquifer` at the package's `consumers/mcp.js` while preserving existing MCP env values. For source checkouts, `scripts/install-openclaw.sh` first installs the current package into `$OPENCLAW_HOME/node_modules`, then runs the same packaged installer.
+
+Run with `--dry-run --json` to verify the active package version, extension path, plugin config, and MCP target without changing files.
 
 ## Most common commands
 
 | Goal | Command |
 |---|---|
 | Verify setup | `npx aquifer quickstart` |
+| Run read-only diagnostics | `npx aquifer doctor --json` |
 | Start MCP server | `npx aquifer mcp` |
+| Install/update OpenClaw wiring | `node "$OPENCLAW_HOME/node_modules/@shadowforge0/aquifer-memory/consumers/cli.js" install-openclaw --openclaw-home "$OPENCLAW_HOME"` |
 | Search memory | `npx aquifer recall "auth middleware"` |
+| Explain current-memory selection | `npx aquifer explain bootstrap --active-scope-key project:aquifer --json` |
+| Inspect finalization ledger | `npx aquifer finalization list --status finalized --json` |
+| Inspect operator ledgers | `npx aquifer operator status --json` |
+| Review current-memory feedback issues | `npx aquifer review queue --scope-key project:aquifer --json` |
 | 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` |
+| Resolve a reviewed memory issue | `npx aquifer review resolve --memory-id 42 --resolution resolved --reason "verified current" --expected-latest-issue-feedback-id 9 --json` |
 
 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
@@ -102,4 +122,17 @@ If you see `type "vector" does not exist`, `pgvector` is not installed.
 
 If recall returns no results, the embedding endpoint is usually unreachable or misconfigured.
 
+For continuity or operator questions, use the read-only governance commands
+first: `doctor`, `finalization list|inspect`, `explain bootstrap|memory`, and
+`operator status|inspect`. Use `review queue|inspect` when curated memory
+feedback has marked visible current-memory rows as `incorrect`, `stale`,
+`scope_mismatch`, or similar issue types. These commands diagnose the DB and
+serving state without changing memory truth, finalization status, MCP tools, or
+operator leases. The review surface does not print raw transcripts, feedback
+notes, feedback metadata, or memory payloads; `review queue|inspect` still uses
+the normal Aquifer migration gate because it depends on the resolution ledger
+schema. After human review, `review resolve` appends a resolution ledger row
+only; it does not edit current memory truth, and newer issue feedback makes the
+item show up in the queue again.
+
 If you want the full setup matrix, host-specific examples, and advanced configuration for summarization, entities, reranking, or operations, continue to [docs/setup.md](setup.md).

package/docs/setup.md

@@ -49,7 +49,7 @@ Aquifer reads configuration from three sources (in priority order):
 2. Environment variables (see below)
 3. Programmatic overrides via `createAquifer()`
 
-Default public serving mode is `legacy`. Opt into `curated` only when you want `session_recall` and `session_bootstrap` to read active curated memory. `evidence_recall` remains the explicit audit/debug lane in both modes, and rollback is just setting env or config back to `legacy`.
+Default public serving mode is `legacy`. Opt into `curated` only when you want compatibility `session_recall` and `session_bootstrap` to read active curated memory. Use `memory_recall` for explicit current-memory lookup, `historical_recall` for the historical/session plane, and `evidence_recall` for the audit/debug lane. Rollback is just setting env or config back to `legacy`.
 
 Backend profiles are explicit. `postgres` is the full backend and remains required for semantic recall, migrations, curated memory, and operator workflows. `local` is a zero-config starter profile with JSON-file persistence, raw session writes, lexical recall, bootstrap, stats, and export. It is intentionally degraded and does not create embeddings or run operator workflows:
 
@@ -76,7 +76,8 @@ AQUIFER_BACKEND=local npx aquifer backend-info --json
   "memory": {
     "servingMode": "legacy",
     "activeScopeKey": "project:aquifer",
-    "activeScopePath": ["global", "project:aquifer"]
+    "activeScopePath": ["global", "project:aquifer"],
+    "allowedScopeKeys": ["global", "project:aquifer"]
   },
   "embed": {
     "baseUrl": "http://localhost:11434/v1",
@@ -113,6 +114,7 @@ export AQUIFER_MEMORY_SERVING_MODE="legacy"
 # export AQUIFER_MEMORY_SERVING_MODE="curated"
 # export AQUIFER_MEMORY_ACTIVE_SCOPE_KEY="project:aquifer"
 # export AQUIFER_MEMORY_ACTIVE_SCOPE_PATH="global,project:aquifer"
+# export AQUIFER_MEMORY_ALLOWED_SCOPE_KEYS="global,project:aquifer"
 
 # Optional Codex active-session checkpoint heartbeat policy.
 # Command flags still take precedence over these env vars.
@@ -123,6 +125,34 @@ export AQUIFER_MEMORY_SERVING_MODE="legacy"
 
 Copy `.env.example` from the repo root for a full annotated list.
 
+### Curated scope contract
+
+Current-memory serving uses two separate scope concepts. `activeScopePath` is
+the ordered inheritance path used by bootstrap, recall, and explain. Broader
+entries can feed defaults into narrower scopes only when they appear in that
+path. `allowedScopeKeys` is the caller boundary. If a runtime request asks for
+an `activeScopeKey`, `activeScopePath`, `scopeKey`, or resolved `scopeId`
+outside `allowedScopeKeys`, Aquifer rejects the request before reading current
+memory rows. When `activeScopePath` is omitted, it defaults to `global` plus the
+configured `activeScopeKey`, or to `global` alone when no active scope is
+configured. When `allowedScopeKeys` is omitted, it defaults to that active scope
+path.
+
+Serving inheritance is deterministic:
+
+- `defaultable`: broader rows are defaults, narrower rows with the same
+  `canonicalKey` win.
+- `exclusive`: currently an explicit narrowest-wins alias for serving. It keeps
+  the producer label visible in explain output but does not add a separate
+  runtime behavior.
+- `additive`: all applicable rows are merged after scope filtering.
+- `non_inheritable`: only the exact active scope can serve the row.
+
+`aquifer explain bootstrap|memory --json` returns selected/excluded reasons
+and a `scopeInheritance` block for each row. Non-selected rows retain safe
+identity and reason fields but redact `canonicalKey`, `title`, and `summary`,
+so explain remains diagnostic instead of becoming a cross-scope content probe.
+
 ## Step 4: Verify everything works
 
 ```bash
@@ -141,6 +171,25 @@ npx aquifer mcp
 
 The server starts on stdio and waits for MCP client connections. There is no visible output on success — the server is ready when the process stays running without error.
 
+### OpenClaw host install/update
+
+OpenClaw should be updated through one host-level installer, not by editing each Aquifer consumer path separately:
+
+```bash
+npm install --prefix "$OPENCLAW_HOME" @shadowforge0/aquifer-memory@latest
+node "$OPENCLAW_HOME/node_modules/@shadowforge0/aquifer-memory/consumers/cli.js" install-openclaw --openclaw-home "$OPENCLAW_HOME"
+```
+
+The command links `$OPENCLAW_HOME/extensions/aquifer-memory` to the package's OpenClaw extension, enables `plugins.entries["aquifer-memory"]`, adds the extension to `plugins.load.paths`, and updates `openclaw.json` so `mcp.servers.aquifer` runs the same package's `consumers/mcp.js`. Existing `mcp.servers.aquifer.env` values are preserved, and `openclaw.json` is backed up before writing.
+
+For a source checkout, run the repo wrapper:
+
+```bash
+bash scripts/install-openclaw.sh "$OPENCLAW_HOME"
+```
+
+That wrapper installs the current package into `$OPENCLAW_HOME/node_modules` before delegating to the packaged installer. Use `--dry-run --json` to inspect the package version, extension link, plugin config, and MCP target without changing files. `--link-current-package` is a development-only escape hatch for wiring a source checkout directly.
+
 ### Verify with the library API (optional)
 
 If you want to test the library directly instead of the CLI:
@@ -203,33 +252,25 @@ Add to `.claude.json` (project-level) 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`.
+Tools appear as `mcp__aquifer__memory_recall`, `mcp__aquifer__historical_recall`, `mcp__aquifer__session_recall`, `mcp__aquifer__evidence_recall`, `mcp__aquifer__session_feedback`, `mcp__aquifer__memory_feedback`, `mcp__aquifer__memory_stats`, `mcp__aquifer__memory_pending`, `mcp__aquifer__feedback_stats`, `mcp__aquifer__session_bootstrap`.
 
-`evidence_recall` is an explicit audit/debug tool. Use `session_recall` for normal memory lookup; broad evidence searches require an audit boundary filter such as `agentId`, `source`, or `dateFrom/dateTo`, unless the caller explicitly opts into unsafe debug mode.
+Use `memory_recall` for explicit current-memory lookup, `historical_recall` for older session detail, and compatibility `session_recall` when the host should follow the configured serving mode. `evidence_recall` is the explicit audit/debug tool; broad evidence searches require an audit boundary filter such as `agentId`, `source`, or `dateFrom/dateTo`, unless the caller explicitly opts into unsafe debug mode.
 
 ### OpenClaw
 
-Add to `openclaw.json`:
+Install or update Aquifer inside the OpenClaw host root, then let the installer
+wire both the MCP server and the optional extension from the same package root:
 
-```json
-{
-  "mcp": {
-    "servers": {
-      "aquifer": {
-        "command": "node",
-        "args": ["/absolute/path/to/aquifer/consumers/mcp.js"],
-        "env": {
-          "DATABASE_URL": "postgresql://...",
-          "AQUIFER_EMBED_BASE_URL": "http://localhost:11434/v1",
-          "AQUIFER_EMBED_MODEL": "bge-m3"
-        }
-      }
-    }
-  }
-}
+```bash
+npm install --prefix "$OPENCLAW_HOME" @shadowforge0/aquifer-memory@latest
+node "$OPENCLAW_HOME/node_modules/@shadowforge0/aquifer-memory/consumers/cli.js" install-openclaw --openclaw-home "$OPENCLAW_HOME"
 ```
 
-Tools materialize as `aquifer__session_recall`, `aquifer__evidence_recall`, `aquifer__session_bootstrap`, `aquifer__session_feedback`, `aquifer__memory_feedback`, `aquifer__feedback_stats`, `aquifer__memory_stats`, `aquifer__memory_pending`.
+The installer preserves existing `mcp.servers.aquifer.env` values and backs up
+`openclaw.json` before writing. Use `--dry-run --json` to inspect package
+version, MCP target, and extension link without changing files.
+
+Tools materialize as `aquifer__memory_recall`, `aquifer__historical_recall`, `aquifer__session_recall`, `aquifer__evidence_recall`, `aquifer__session_feedback`, `aquifer__memory_feedback`, `aquifer__memory_stats`, `aquifer__memory_pending`, `aquifer__feedback_stats`, `aquifer__session_bootstrap`.
 
 Do **not** use the OpenClaw plugin (`consumers/openclaw-plugin.js`) for tool delivery. The plugin is retained for session capture via `before_reset` only.
 
@@ -274,6 +315,45 @@ 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.
 
+## Read-only governance diagnostics
+
+Use the governance commands before running write paths when continuity or
+operator state looks wrong:
+
+```bash
+npx aquifer doctor --json
+npx aquifer finalization list --status failed --json
+npx aquifer finalization inspect --id 42 --json
+npx aquifer explain bootstrap --active-scope-key project:aquifer --json
+npx aquifer explain memory --query "serving contract" --active-scope-key project:aquifer --json
+npx aquifer review queue --scope-key project:aquifer --json
+npx aquifer review inspect --memory-id 42 --json
+npx aquifer review resolve --memory-id 42 --resolution resolved --reason "verified current" --expected-latest-issue-feedback-id 9 --json
+npx aquifer operator status --json
+npx aquifer operator inspect --run-id 42 --kind compaction --json
+```
+
+`doctor` reports package/runtime, backend, DB/schema/tenant readiness,
+migration readiness, serving mode, MCP tool count, session/finalization
+backlog, and stale operator claims. Host checks are scoped: OpenClaw wiring is
+checked only with `--host openclaw` or `--openclaw-home`, and Codex checkpoint
+hook state is checked only with `--host codex`.
+
+The finalization, explain, review queue/inspect, and operator inspect commands
+read committed ledger and current-memory projection material only. `review
+queue|inspect` derives its worklist from curated memory feedback events on
+active visible memory records and uses the normal Aquifer migration gate because
+it depends on the resolution ledger schema. It summarizes feedback counts and
+safe identity fields; it does not print raw transcripts, feedback notes,
+feedback metadata, evidence text, or memory payloads. `review resolve` is
+append-only: it records a resolution snapshot through the latest issue feedback
+id, leaves `memory_records` and feedback history untouched, and lets newer
+issue feedback reopen the item. These commands do not promote memory, mutate
+finalization status, reclaim leases, or change the ten-tool MCP surface.
+Explain output is also redacted for non-selected rows: it reports safe identity,
+selection reason, and scope inheritance details, but not hidden, shadowed,
+out-of-scope, inactive, or trimmed row content.
+
 ## Release verification gates
 
 For the publish-surface checks:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shadowforge0/aquifer-memory",
-  "version": "1.8.1",
+  "version": "1.9.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": [
@@ -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-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/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/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,