Deliberationv4.6.1

Session persistence

Session persistence

An opt-in, single-user local store that records each /consensus and /ask-all run so it can be fetched, re-run, and annotated later. Default OFF - nothing is written to disk unless sessions.persist is true. Implemented in core/sessions.js (synchronous, zero-dep); the store directory is resolved by resolveSessionsDir in core/paths.js; config is validated by resolveSessions in server/openrouter/config.js; the MCP wiring lives in server/mcp/index.js.

Three paths write through one chokepoint (persistRun): the server-side consensus tool, ask-all, and session-revisit (child record). The host-driven consensus-step loop (the live /consensus) also persists ONE record on a terminal transition - converged or unresolved - via persistConsensusStep. It takes the loop entry with an atomic loopStore.take() BEFORE the synchronous write, so a concurrent/retried terminal call finds nothing and cannot double-write (at-most-one, lock-free); the record's question is the ORIGINAL prompt stashed at init, not the final revision. On a write failure it emits a CONTENT-FREE persist_failed event to the debug log (fs errno or "write_failed", plus the ephemeral loop id - never err.message) and returns persisted:false with no sessionId.

Configuration

json
"sessions": { "persist": false, "maxRecords": 200, "maxAgeDays": 30, "captureText": false }
Key Type Default Meaning
persist boolean false Save each run and return a sessionId. Non-boolean degrades to false + warning.
maxRecords integer 200 Keep at most this many newest records. -1 = unlimited (never trim by count). 0/invalid -> default + warning.
maxAgeDays integer 30 Delete records older than this. -1 = unlimited (never delete by age). 0/invalid -> default + warning.
captureText boolean false Also store each provider's raw RESPONSE body (opinion.text). OFF (default) = summaries only (question + verdict/criticalIssues); the body is dropped at persistRun for every path. ON (and persist on) stores the body, secret-scrubbed (mandatory) then best-effort PII (email) stripped, then capped. Non-boolean degrades to false + warning. The metrics-only debug log NEVER receives body text either way.

Validation soft-degrades: a bad value never rejects the config, it falls back to the default and the reason rides the same consensusWarnings channel the bridge already surfaces.

Store layout

  • One JSON file per session at <dir>/<id>.json, where <dir> is DELIBERATION_SESSIONS if set, else <XDG cache>/deliberation/sessions (macOS/Linux ~/.cache/...; Windows %LOCALAPPDATA%\...).
  • Written atomically: the temp file is created with mode 0600 directly (no world-readable window), then renamed into place; a failed rename removes the temp.
  • No global lock - each file is independent. The only read-modify-write is session-annotate on one file, documented last-writer-wins (fine for a local single-user stdio server).
  • Retention runs after every write: delete by age, then trim by count (both honoring -1 = unlimited). Orphaned <id>.json.tmp.<pid>.<ts> fragments older than an hour are also reaped.

Record shape (schemaVersion: 1)

text
{ id, parentId|null, schemaVersion: 1, createdAt: <ISO>,
  tool: "consensus"|"ask-all", question, expert|null,
  files: [{ path|dir|file_id|file_url, mode? }]|null,   // attachment REFS, never bodies
  opinions: [{ provider, model, text?,                  // text = RESPONSE body, present ONLY when sessions.captureText is on
               verdict?, criticalIssues? }],            // verdict/criticalIssues on consensus LOOP opinions
  blindVerdict|null, verdict|null,                      // verdict = loop enum (null in synthesize mode)
  synthesis?|null, synthesizeAlways?,                   // synthesis = free-text (synthesize runs)
  arbiter: { mode, provider }|null, warnings: [], annotations: [{ note, at }],
  converged?, confidence?, rounds? }                    // consensus LOOP summary

A single stamp - no dual-version support (pre-1.0, no users). readSession returns the object as-is and nothing branches on schemaVersion. The loop fields (verdict/criticalIssues/converged/confidence/rounds) are populated only for a consensus LOOP run; a synthesizeAlways run carries synthesis instead; ask-all omits all of them. (tool is "consensus" for both consensus modes; synthesizeAlways records the mode so session-revisit replays it.)

Before writing, scrubSecrets redacts common key shapes (OpenAI sk-, OpenRouter sk-or-, Anthropic sk-ant-, xAI xai-, GitHub gh[pousr]_, AWS AKIA, Google AIza, Slack xox[baprs]-, Stripe [sr]k_(live|test)_, and Bearer tokens), multi-line private key blocks ([REDACTED_PRIVATE_KEY]), compact serialized JWT tokens ([REDACTED_JWT]), and syntax-aware key-value secrets in JSON, YAML, .env, and Shell assignments (api_key, secret_key, client_secret, access_token, auth_token, refresh_token, private_key, password, passwd mapped to [REDACTED]) in the question, opinion/verdict text, each critical-issue description, warnings, annotation notes, and the file path/dir strings; the question and each opinion/verdict are capped at ~100 KB, and an opinion verdict is whitelisted to the closed enum (anything else is coerced to null) so no free text rides the unscrubbed verdict field. Scrubbing is best-effort - user transcript text may still carry secrets in unrecognized shapes.

Opinion RESPONSE bodies (opinion.text) are persisted ONLY under the opt-in sessions.captureText (default off); persistRun drops the field for every path when it is off, so the default record holds only the question + verdict/issue summaries. When on, the body is secret-scrubbed (the mandatory primary control, always run) and then passed through a best-effort stripPII (email addresses only; RFC-bounded so it stays linear on long provider text) as defense-in-depth - NOT a guarantee, never the gate. captureText is forward-gating: turning it off stops new capture but does not strip records already on disk (they age out via retention, or delete the store dir to purge).

Tools

Each takes its own input schema (no prompt), and reports "session persistence is disabled (set sessions.persist)" when off.

Tool Input Effect
session-get { sessionId } Return the record, or a not-found message. Read-only.
session-revisit { sessionId, cwd? } Re-run the record's original question (and its file refs) with the CURRENT providers/config, write a CHILD record (parentId = original id), return the new sessionId + result. Re-run, not snapshot-replay. A consensus record replays its mode - the full multi-round LOOP, or the single synthesis pass. (Records written before the tool merge are unsupported - pre-1.0, no users.)
session-annotate { sessionId, note } Append { note, at } to the record's audit trail and rewrite the file.

When persist is on, consensus, ask-all, and the consensus-step terminal transition also include a top-level sessionId in their result (consensus-step adds persisted and, on the host-driven loop, the ephemeral loopSessionId).

Walkthrough: record -> review -> revisit -> annotate

With sessions.persist: true, one decision flows through all three tools. Tool calls are shown in their real arg shape; ids are illustrative.

  1. Record. Run a panel and the result carries a sessionId:

    text
    /ask-all Should we cache provider results in-process or in Redis?
    -> { results: [...], sessionId: "019c5af2-1a2b-7c3d-8e4f-aa12" }
  2. Review the stored decision later:

    text
    session-get { "sessionId": "019c5af2-1a2b-7c3d-8e4f-aa12" }
    -> { session: {
         tool: "ask-all", question: "Should we cache provider results ...",
         opinions: [ { provider: "codex", verdict: null, text: "..." },
                     { provider: "gemini", verdict: null, text: "..." } ],
         verdict: null, annotations: [] } }

    (A consensus loop record also carries per-opinion verdict, a final verdict, and converged/confidence/rounds; a synthesizeAlways record carries synthesis.)

  3. Revisit - re-ask the SAME question against today's providers/config. This writes a CHILD record linked by parentId and returns a new id (it re-runs; it does not replay the stored answer). A consensus record replays its mode (the loop, or a synthesize pass):

    text
    session-revisit { "sessionId": "019c5af2-1a2b-7c3d-8e4f-aa12" }
    -> { results: [...], sessionId: "019c6b00-3d4e-7f50-9a61-bb34" }   // parentId = 019c5af2-...
  4. Annotate either record with the real-world outcome - appended to the audit trail with a timestamp, never overwriting prior notes:

    text
    session-annotate { "sessionId": "019c5af2-1a2b-7c3d-8e4f-aa12",
                        "note": "Shipped in-process LRU; revisit after Redis lands." }
    -> { session: { ..., annotations: [ { note: "Shipped in-process LRU; ...", at: "2026-06-17T..." } ] } }
    text
    019c5af2 (ask-all)  --parentId-->  019c6b00 (revisit)
       |
       +-- annotations: [ "Shipped in-process LRU; ..." @ 2026-06-17 ]

Finding a past session

There is no enumeration tool, so a sessionId comes from one of three places:

  1. The sessionId in the original /ask-all or /consensus result.
  2. The store on disk: ls ~/.cache/deliberation/sessions/ - one <sessionId>.json per run. The exact dir is what /deliberation:doctor prints, and DELIBERATION_SESSIONS overrides it.
  3. /deliberation:analyze - reviews recent runs in aggregate (verdict agreement, Lens B).

Rendered from TECHNICAL.md in the repository.

Type to search the site.