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
"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>isDELIBERATION_SESSIONSif set, else<XDG cache>/deliberation/sessions(macOS/Linux~/.cache/...; Windows%LOCALAPPDATA%\...). - Written atomically: the temp file is created with mode
0600directly (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-annotateon 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)
{ 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 summaryA 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.
-
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" } -
Review the stored decision later:
textsession-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
consensusloop record also carries per-opinionverdict, a finalverdict, andconverged/confidence/rounds; asynthesizeAlwaysrecord carriessynthesis.) -
Revisit - re-ask the SAME question against today's providers/config. This writes a CHILD record linked by
parentIdand returns a new id (it re-runs; it does not replay the stored answer). Aconsensusrecord replays its mode (the loop, or a synthesize pass):textsession-revisit { "sessionId": "019c5af2-1a2b-7c3d-8e4f-aa12" } -> { results: [...], sessionId: "019c6b00-3d4e-7f50-9a61-bb34" } // parentId = 019c5af2-... -
Annotate either record with the real-world outcome - appended to the audit trail with a timestamp, never overwriting prior notes:
textsession-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..." } ] } }text019c5af2 (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:
- The
sessionIdin the original/ask-allor/consensusresult. - The store on disk:
ls ~/.cache/deliberation/sessions/- one<sessionId>.jsonper run. The exact dir is what/deliberation:doctorprints, andDELIBERATION_SESSIONSoverrides it. /deliberation:analyze- reviews recent runs in aggregate (verdict agreement, Lens B).