Dashboard
Dashboard
A local, read-only web page that draws each Deliberation run as a state graph while it
runs and after it ends: which state is running, what each provider was sent and returned,
status, timing, and tokens. It also shows the effective config, provider health, models,
and usage stats. Default OFF. Nothing in the dashboard changes Deliberation state, and
only the unified deliberation server is instrumented (the standalone /ask-* bridge
servers write nothing).
Each MCP host session runs its own stdio server process, so the processes write a shared on-disk journal and the dashboard is a separate process that reads it. It can start after a run began and still show all of it, a crashed MCP process leaves its events on disk, and the journal is the history.
| Unit | Does |
|---|---|
core/journal.js |
Builds and appends journal events; per-kind key whitelist; secret scrub and text cap on content fields; retention; a no-op while dashboard.enabled is off |
core/redact.js |
redact(value): masks PII in every string of a JSON value (see Redaction) |
server/dashboard/index.js |
CLI entry (deliberation-mcp dashboard), pidfile, browser opener, health and stats wiring |
server/dashboard/server.js |
HTTP routes, Host/Origin and token checks, security headers, SSE |
server/dashboard/runs.js |
Run index over the journal plus legacy session records; run status, abandoned detection |
server/dashboard/tail.js |
Byte-offset tailer for SSE (fs.watch plus a 5 s stat sweep) |
server/dashboard/ui/ |
Static page: ES modules, CSS, inline SVG. No build step, no dependency, works offline |
server/dashboard/ui/telemetry.js |
Pure debate convergence trajectory and provider latency breakdown analytics |
server/dashboard/analyzer.js |
Pure Analyzer report over journal runs: models that agree more than they add, per-project health, request size vs latency and timeouts (see Analyzer) |
server/dashboard/stop.js |
dashboard --stop: signals the pidfile's pid only when it is provably the dashboard |
core/project.js |
resolveProject(dir): the calling project (grouped by git remote org/repo, then the checkout as a workspace) for run_start; normalizeProject upgrades runs recorded before workspaces |
Configuration
"dashboard": { "enabled": false, "capture": "metadata", "showPII": false, "port": 7717, "maxRuns": 200, "maxAgeDays": 30 }| Key | Type | Default | Meaning |
|---|---|---|---|
enabled |
boolean | false |
Master switch. Off: no journal is written and deliberation-mcp dashboard exits 1 naming this key. Read per event, so a config hot-reload applies to the next run. |
capture |
"metadata" | "content" |
"metadata" |
metadata: states, timings, tokens, verdicts, error kinds. content: also prompts, requests, responses, arbiter text, and final reports. |
showPII |
boolean | false |
Off: every API body and SSE payload is redacted before it leaves the dashboard process. On: served as stored. Applies to existing journal files; nothing on disk is rewritten. |
port |
integer | 7717 |
Port on 127.0.0.1. --port N overrides it (--port 0 picks a free port). |
maxRuns |
integer | 200 |
Keep at most this many newest run files. -1 = unlimited. |
maxAgeDays |
integer | 30 |
Delete run files older than this. -1 = unlimited. |
Invalid values soft-degrade to the default with a warning, like sessions. Retention runs
when a run ends, when the MCP server starts, and when the dashboard starts.
Journal
One file per run: <XDG cache>/deliberation/runs/<runId>.jsonl (override with
DELIBERATION_RUNS), mode 0600 in a 0700 directory. Every line is one event:
{ v: 1, kind, runId, at, seq, ...fields } (at epoch ms, seq a per-run counter).
Writes are synchronous whole-line appends by the one process that owns the run, and a
failed write is swallowed: journaling never fails a delegation (the same contract as the
debug log, whose ALLOWED_KEYS whitelist is unchanged and still excludes all content).
| Kind | Metadata fields | Content fields (capture: "content" only) |
|---|---|---|
run_start |
tool, pid, procStartedAt, expert, workflow (single | fanout | consensus-step | consensus), providers[], project ({id, name, root, ws}) |
prompt |
state |
state, round, status, verdicts[] ({provider, verdict, categories[]}, on adjudicate) |
none |
call_start |
callId, provider, model, role (peer | arbiter | blind | single), round, timeoutMs, reasoningEffort, promptChars, fileCount, orientationFiles, fileBytes, grantedMs, hostCapMs, ceilingSource (own | shared | outer | host), sharedBy[], sharedLimitMs |
request |
call_end |
callId, provider, model, ms, usage, isError, errorKind, errorCode, verdict, criticalIssues[].category |
response, criticalIssues[].description |
arbiter |
action (record_blind | submit_adjudication | submit_revision), round, verdict, decisions[] ({source, category, action}, consensus-step adjudication only) |
text, decisions[].description, decisions[].reason |
run_end |
status (converged | unresolved | done | error), stopReason, rounds, droppedProviders[] |
finalReport |
Keys outside this whitelist are dropped at write. Content fields pass scrubSecrets and
then capText (100 KB) before the write, the same privacy contract as sessions. The
analyzer fields are also shape-checked at write: project keeps only its three strings
plus ws when it is 12 hex chars,
the size and ceiling fields only finite numbers or null, ceilingSource only its four
values.
project is core/project.js resolveProject of the tool call's cwd argument, or
the server's own cwd when the call passes none. It walks up to the nearest .git (the
checkout) and groups runs in two levels:
- Repo group (
id,name). The main git dir'sconfigis read for theoriginremote, else the first remote.nameis the remote path (org/repo, the full path for nested GitLab groups) andidis 12 hex chars of a SHA-256 ofhost/path, so every clone, worktree, or/tmpcheckout of one remote shares a group. scp (git@host:org/repo),ssh://andhttps://URLs are parsed; credentials and.gitare dropped, and the raw URL and host are never stored. Without a usable remote (none, or a local path orfile://) the group is the main git dir as before:idhashes its real path andnameis the main repo's folder. A linked worktree reads its main repo's config; a submodule is its own repo; no git at all falls back to the directory. - Workspace (
root,ws).rootis the checkout path;wsis 12 hex chars of a SHA-256 of its real path. A call from a subdir counts as its checkout.
Stat and read only, no git spawn, never throws. root is an absolute path on disk;
serving masks the home dir (Redaction) unless showPII is on, and the URL only ever carries
the ids. Runs recorded before ws existed are normalized when the dashboard reads them
(normalizeProject): if the recorded root still exists it is resolved again and joins
its remote group; otherwise the run keeps its old group and gets a ws from the root path.
Nothing in the journal is rewritten.
Request size (promptChars, fileCount, orientationFiles, fileBytes) is measured
on the request as callProvider sends it: after orientation files are attached and after
consensus builds its peer or arbiter prompt, because that is what the provider has to read.
Persona text and the grounding note added inside each bridge are not counted (a constant
per provider). fileBytes is the sum of stat sizes of {path} attachments, and null,
never a partial sum, when any attachment is a {dir}, an upload id, a URL, fails to stat,
or there are more than 50.
Effective ceiling (grantedMs, ceilingSource) is what one attempt was actually
given: min(timeoutMs, deadlineAt - now, host budget left). ceilingSource names where
the winning limit came from, by origin rather than by which number happens to be smallest:
own (the provider's configured timeout, including the deadline callProvider builds from
it), shared (the fan-out deadline, which follows the slowest SELECTED peer; sharedBy
names that peer, even one that was never dispatched, and sharedLimitMs its limit),
outer (a caller budget such as consensus.maxWallMs), or host (MCP_TOOL_TIMEOUT,
whose value is hostCapMs). Ties go to the host, then to the deadline.
Where events come from:
core/orchestrate.jscallProvider, which every provider call passes through, emitscall_startandcall_end(errors included; a retry is a newcallId).server/mcp/index.jsemitsrun_start/run_endforask-all,ask-one, theask-*tools, the eight expert tools, andconsensus; the server-side loop also emitsstateper transition.consensus-step:initopens the run with the loopsessionIdas itsrunId; each action emitsstate, the three host actions also emitarbiter, and a terminal transition emitsrun_end./ask-allispanelplus N parallelask-onecalls.panelopens afanoutrun and returns itsrunId(only when the journal is on);ask-oneand theask-*tools accept an optionalrunIdand join that run. Only ids thatpanelopened in the same server process are joined; any other id is ignored and the call becomes its ownsinglerun.panelstays side-effect-free toward providers: the journal line is a local write.
Run status and abandoned runs
Status is derived when the index is read (deriveStatus(events, now, isAlive) in
server/dashboard/runs.js), never cached: a run whose writer died never changes its file,
so a cached status could not age. The index caches only the events and the fields that do
not depend on time. The first rule that matches wins:
| # | Run | Status |
|---|---|---|
| 1 | Has a run_end |
Its status and stopReason. |
| 2 | fanout, every provider run_start lists has a latest call with a call_end |
done. Calls pair by callId, so a retry still in flight after an errored first attempt keeps the run open. |
| 3 | fanout, at least one call_start, none still open, nothing written for 60 s |
done, with the listed providers that were never called in undispatched (drawn as skipped branches, not failures). |
| 4 | fanout, no call_start 20 minutes after it started |
abandoned, stopReason: "never-dispatched". |
| 5 | consensus-step, last event older than the loop store TTL (30 minutes) |
abandoned, stopReason: "expired": the host stopped driving it and its loop state is gone. |
| 6 | Anything else | running while the MCP process that wrote it is alive, else abandoned. |
Rule 6 reads pid and procStartedAt from run_start: the run is abandoned when that pid
is gone, or is alive with a different start time (pid reuse). The pid-reuse check reads
/proc/<pid>/stat, so it runs on Linux only; elsewhere a reused pid still reads as alive.
A late ask-one that joins a fan-out after rule 3 fired moves it back to running, and
the UI follows the server's status for fan-outs rather than deciding on its own. An
abandoned run keeps the last state it reached. errors counts a call's final attempt: an
errored attempt followed by a retry for the same provider, role and round is not an
error. Legacy session-store records are listed too, flagged legacy (summary only, no
step graph).
Routes and SSE
GET and HEAD only; any other method gets 405.
| Route | Returns |
|---|---|
/ |
The page. |
/assets/* |
Static UI files, resolved inside the UI directory; a path that escapes it is rejected. |
/api/runs |
Run index; filters ?q=, ?tool=, ?provider=, ?status=, ?since=, ?project=<id> (a repo group with all its workspaces; unknown = runs with no project), ?ws=<id> (one workspace; wins over ?project=). While showPII is off, ?q= matches the redacted prompt, so a search cannot confirm a masked value. |
/api/runs/:id |
All events of one run (or the legacy record); id must match ^[A-Za-z0-9-]+$. |
/api/config |
Effective config. For every API key env var, only its name and whether it is set; credentials in URLs are stripped. |
/api/health |
Provider health from the checks panel uses (unavailable, needsLogin), models, reasoning effort, askAll / consensus eligibility. |
/api/stats |
The analyze report plus runs, tokens, and errors per day. Reads the debug log, so it cannot be filtered by project. |
/api/analyzer |
The Analyzer report (see Analyzer). ?days= 1-365 (default 30), ?project=<id>, ?ws=<id> (12 hex; 400 otherwise); at most 2000 runs per report. |
/api/events |
Server-Sent Events stream of new journal events. |
The tailer keeps a byte offset per run file and reads only appended bytes; a partial last
line waits until it is complete. Each SSE message id is <runId>:<offset>. On reconnect
the browser sends it back as Last-Event-ID and that run resumes from the offset; a
malformed id is ignored. A comment line every 15 s keeps the connection open, and a client
more than 1 MB behind is dropped, then reconnects and resumes the same way.
Analyzer
The Analyzer tab (server/dashboard/analyzer.js, /api/analyzer) reads journal metadata
only. Its thresholds are exported as C and quoted in the page.
Models: agreement vs findings. Consensus rounds only: plain ask-all answers are never
parsed into verdicts, and per-voice verdicts with issue categories exist only on
state: "adjudicate" events. A voice counts in a round when its verdict is non-null; a
round counts when it has two or more such voices and is not a unanimous APPROVE with no
issues. Per model:
addsNothing- its issue categories are all among the other voices' categories that round.loneDissent- it objected (REQUEST_CHANGES or REJECT) with a verdict no other voice gave. A lone APPROVE while the others object is a missed finding, not a contribution, so it does not count.acceptedRate- of its rounds that carry arbiter decisions, how many had at least one of its issues accepted (joined on the voice id:codex,gemini,grok,openrouter:<alias>; a decision naming no voice is ignored). Onlyconsensus-steprecords decisions; rounds of the server-sideconsensusloop have none and never count as "zero accepted".slowShare- rounds where its time was at least 1.2x the median of the other responders.errorRate- errored peer calls.
Speed and errors use only calls whose ceiling this config controls (own, shared) and
are not cached: a host cap or a run budget makes every voice look slow. A model is a
drop candidate when it has at least 10 rounds, adds nothing in 80% or more, dissents
alone in 10% or fewer, had an issue accepted in 5% or fewer of at least 10 decision rounds,
and is slow in 60% of rounds or errors in 20% of 10+ calls. Without enough decision rounds
it is shown as unconfirmed, never as a candidate. The six categories are coarse, so this
is advice; the page names the config key (models.<alias>.consensus: false or
providers.<name>.enabled: false) and never writes it.
Projects. Per repo group (project.id): runs, run statuses, calls, timeouts, errors,
p50/p95 of successful non-cached calls, top three error kinds, and the same numbers per
workspace in workspaces[] (ws, root). Runs without a project group under (unknown).
The page shows a group as org/repo (path) when it has one workspace; with more, a toggle
expands the workspace rows. Clicking a name sets the project filter, which the Runs and
Analyzer tabs share: a whole group or one workspace.
Request size vs latency. Per provider and model, split text-only (size = promptChars)
from file-bearing (size = promptChars + fileBytes; null fileBytes is skipped and
counted). Buckets <8k, 8-32k, >32k chars, each with calls, timeouts, near-ceiling
rate (successes above 90% of grantedMs), p50/p95, and the median ceiling. A least-squares
fit of ms on size over successes gives ms per 1k chars and r. Timed-out calls are censored
(their real latency is unknown), so a fit or a p95 over successes understates large
requests; the advice accounts for that. Per bucket, using only own/shared calls:
- Fewer than 20 calls: no number. If more than 5% timed out, an early warning that the provider's timeout is likely too low.
- More than 5% timeouts or more than 10% near the ceiling:
censored. Suggested ceiling = 1.5 x max(the largestgrantedMsamong those calls, the current configured value), so it always exceeds what they got. It names the provider's timeout key, or forsharedthe key of the peer insharedBy. If the host cap (hostCapMs - 5000) leaves no room above that, it says to raiseMCP_TOOL_TIMEOUTinstead. - Otherwise, r >= 0.5: a ceiling of 1.25 x p95, capped by the host cap.
- Otherwise: no size effect shown.
host timeouts are listed separately ("raise MCP_TOOL_TIMEOUT"), outer timeouts are
reported but never advised on, and calls recorded before these fields existed are skipped
and counted.
Redaction
Secrets (API-key shapes) are scrubbed at write time at every capture level, so they never
reach the journal. PII is redacted at serve time by core/redact.js while showPII is
off: email addresses, the home directory and the OS user's home paths (/home/<user>,
/Users/<user>, C:\Users\<user>; the user name elsewhere is left alone), IPv4 and IPv6
addresses, and 12-digit account ids. Values under runId, callId, sessionId,
loopSessionId and id are never redacted, because a UUID can end in 12 digits. The SSE
id: line is not redacted either. Redaction is pattern-based and best-effort; it
reduces what a browser receives, and the journal on disk keeps the unredacted text for
capture: "content".
Capture gates what is served
dashboard.capture is read on every request. Unless it is "content", the server strips
content fields (the content keys of JOURNAL_KEYS, plus the legacy session record's
question, synthesis, opinion text, critical-issue descriptions and annotation notes)
before redaction from /api/runs/:id and the SSE stream, and ?q= matches only runId,
tool and provider. Journal files written earlier under content keep their text on disk.
Threat model
The dashboard serves prompt and response text over HTTP on the local machine. The defenses, in request order:
- Loopback bind. The server listens on
127.0.0.1only; nothing off the machine can connect. - Host and Origin checks (DNS rebinding). A request whose
Hostis not127.0.0.1:<port>orlocalhost:<port>gets 403, and so does one carrying anOriginthat is not one of those two. A web page on another domain that rebinds its name to127.0.0.1still sends its ownHost, so it is refused. - Per-start token, swapped for a cookie. Each start generates a 32-byte random token.
The printed URL carries it as
?t=<token>; the first request with a valid token gets adlb_dashcookie (HttpOnly; SameSite=Strict; Path=/) and a small page that refreshes to/. It is not a 302: the browser arrives from thefile://opener page, a redirect keeps that navigation cross-site, and Chrome would withhold the Strict cookie from the redirectedGET /(a 401 on the first open). The refresh starts from the dashboard's own origin, so the cookie is sent. Requests with neither a valid token nor the cookie get 401. Comparison is constant-time. - The token is in the printed URL. Anyone who sees that line (terminal scrollback, a
shared screen, a pasted log) can open the dashboard until it restarts. It is also stored
in the
0600pidfile<XDG cache>/deliberation/dashboard.json, which is how a second launch reprints the live URL. Restarting the dashboard issues a new token. - The cookie reaches every local port. Browsers scope cookies by host, not port, so
dlb_dashis also sent to any other service on127.0.0.1. A web page cannot use that to read dashboard data: a cross-port fetch carries its ownOriginand is refused, andX-Content-Type-Options: nosniffstops a page from loading the JSON as a script. The local service itself can, though: it receives the cookie value, so it can replay the token server-side (for examplecurl -H "Host: 127.0.0.1:<port>"with the cookie, or with?t=<token>) and read everything the dashboard serves. This is accepted because any process listening on the machine is already inside the same-machine trust boundary; the design scope is a single-user laptop. The cookie is only issued after you open the tokenized URL, and restarting the dashboard rotates the token, which invalidates it. On a shared multi-user machine, do not enable the dashboard, and do not usecapture: "content". - Token off argv. The browser is opened through a
0600redirect file next to the pidfile (dashboard-open.html); the opener gets that file's path, so the token never appears in a process list. - Headers.
Content-Security-Policy: default-src 'self'; frame-ancestors 'none',X-Content-Type-Options: nosniff,Referrer-Policy: no-referrer, andCache-Control: no-storeon/api/*. The UI renders run content withtextContentonly, never as HTML, and keeps only preferences and a metadata-only run index inlocalStorage. - Secrets scrubbed at write, PII redacted at serve (see Redaction).
Out of scope: another account on the same machine with read access to your cache
directory (the journal and pidfile are 0600 in a 0700 directory), and anything that
already runs as your user. Remote sessions (Claude Code on the web) cannot use the
dashboard: localhost there is the remote container.
Running it
deliberation-mcp dashboard [--port N] [--no-open] # npm package
node server/mcp/index.js dashboard [--port N] [--no-open] # from a checkout
deliberation-mcp dashboard --stop # stop it
bash scripts/commands/dashboard-restart.sh [--port N] [--no-open] # stop, start, print the new URL
npm run dashboard:restart # the same, from a checkoutIt prints exactly one line, Deliberation dashboard: http://127.0.0.1:<port>/?t=<token>,
opens the browser unless --no-open, and keeps running. It exits 1 with
dashboard is disabled: set dashboard.enabled to true in <config path> when the switch is
off, and with port <n> is in use; pass --port on a port conflict. A second launch while
one is live reprints the live URL and exits 0. In Claude Code, /deliberation:dashboard
starts it detached and prints the URL, and /deliberation:dashboard restart restarts it.
The npm bundle ships the UI as dist/dashboard-ui/ (copied by prepack); a checkout
serves server/dashboard/ui/.
--stop signals the pid in the pidfile only when that pid is provably this dashboard: it
is alive, its command line runs a dashboard entrypoint (server/mcp/index.js,
deliberation-mcp/dist/index.js, bin/deliberation-mcp, or the recorded argv[1]) at the
script position with dashboard right after it, and it started within 2 s of the
procStartedAt the dashboard wrote into the pidfile (Linux /proc/<pid>/stat with
btime; macOS ps -o lstart). The token probe proves a listener, not a pid, so it never
authorizes a signal. Outcomes: no pidfile or a dead pid, exit 0 (a stale pidfile is
removed); alive but not provably the dashboard (including a pidfile written before this
version), exit 2, pidfile kept, nothing signalled; proven, SIGTERM, then after 5 s SIGKILL
only if the same checks still hold. Windows is not supported (exit 1). The restart script
exits 3 when --stop left a process alone, and starts nothing in that case. /deliberation:reload-mcp
stops the dashboard the same way.