design(mcpx): elicitation broker hygiene — owner-only store, bounded retention, redacted events, review-first answering #1675

Summary

The elicitation broker is where mcpx puts the most sensitive data it handles — questions routed to a human precisely because an agent should not hold them (password/credential-shaped fields, per elicit.Route), sampling prompts "stored exactly as sent", and the answers — and it is the least protected store in the daemon. On current main the broker DB sits in a 0755 directory any local user can read, no row is ever deleted, and the full question and answer are broadcast as event-bus data to every subscriber. The one human surface over the store, mcpx elicit, prints raw URLs with no domain emphasis or punycode warning, pre-fills "..." instead of schema defaults, and answers with no review step. This design gives the broker an owner-only home with migration for existing installs, a documented retention bound, summary-only event payloads, and a review-first answering surface.

Design doc: files/designs/code-mcpx-elicitation-broker-hygiene.md in the keep-the-four-repos-healthy goal workspace (full audit, alternatives, risks, open questions).

No Drew direction decision needed: origin dezren39/darwin-nix#255's acceptance is explicit (owner-only store verified on disk; pruning with a documented bound), the owner-only precedent is already in-tree (internal/artifacts and the state dir at 0o700), and the judgment calls (dedicated 0700 subdir rather than tightening the shared logs dir; summary-only events; retention defaults of 30 days / 1000 terminal rows) are recorded in the design doc.

Current state (verified on main d39e611, 2026-10-28)

• Both broker open sites create the shared <state>/logs dir with defaults.PublicDirMode (0755, internal/defaults/defaults.json:214): internal/daemon/hooks.go OpenBroker (~L288-294) and internal/cli/elicit.go broker() (~L37-44). elicit.Open (internal/elicit/elicit.go ~L155) creates elicit.db (+ WAL/SHM) with default modes. Gaps elicitation-state-storage-protected and elicitation-server-follow-best-practices (internal/conformance/coverage_clientfeatures.go, origin mcpx: elicitation storage is readable by any local user and never pruned; elicitation UI and response validation rows dezren39/darwin-nix#255).
• internal/elicit/elicit.go contains no DELETE: expireOverdue (~L437) only transitions pending → expired. Every question, answer, and sampling request accumulates forever. Gap sampling-messages-not-retained-between-requests.
• Full payloads on the bus: events.ElicitOpened with Data: mustJSON(req) and events.ElicitAnswered with Data: mustJSON(ans) at internal/daemon/hooks.go ~L164-171, internal/daemon/consumer.go ~L325/424/505, internal/daemon/routes_proto.go ~L669, internal/daemon/server.go ~L1395. No in-tree consumer reads answer content from the bus — askers use Broker.Await. Gaps sampling-both-handle-sensitive-data (client + server).
• renderQuestion (internal/cli/elicit.go ~L201-232) already shows the asking server/tool; what is missing is exactly the fix(id): coalesce LogSync ingest batches (#241) #255 UI slice: URL domain emphasis + punycode warning, schema defaults pre-filled (today exampleFor ~L275-285 emits "..."), and a review step before an answer is relayed. Six gaps: elicitation-app-review-modify-responses, elicitation-client-form-review-modify-responses, elicitation-client-url-show-domain-and-consent, elicitation-client-handle-urls-carefully, elicitation-client-highlight-domain, elicitation-client-warn-punycode.
• Explicitly NOT this design: validating answers against requestedSchema — the client slice is mcpx: Phase 3 of #1481 — validate elicitation form answers against requestedSchema in client.answer #1484 (Phase 3 of design design(mcpx): JSON Schema validation of tool input and output — one validator at the client choke point #1481, queued); the server-relay slice (elicitation-server-validate-received-data) stays open on nix#255 until mcpx: Phase 3 of #1481 — validate elicitation form answers against requestedSchema in client.answer #1484's as-built shape is known. Also distinct: the tasks store's own 0755 dir creation (internal/tasks/tasks.go:149) belongs to design(mcpx): tasks, finished — one task store for MCP and /v1, and a client that can call task-required tools #1554's store, not this one.

Proposal (phased; each phase independently landable)

1. Phase 1 — owner-only store. One path helper in internal/elicit; the store moves to a dedicated state subdir at 0700, DB files 0600; a legacy logs/elicit.db is migrated on open with pending questions preserved; modes are tightened on open for pre-existing installs and failure to tighten is an error. Both open sites use the helper.
2. Phase 2 — bounded retention + redacted events (gated on Phase 1). Terminal rows pruned on open by age + count bounds from defaults.json (30 days / 1000 rows, recorded defaults); pending rows never pruned. ElicitOpened/ElicitAnswered payloads become summary-only (id, server, tool, mode, audience, state, expiry — never message/schema/url/content) at all publish sites, with a tree-wide consumer audit.
3. Phase 3 — review-first answering surface + truth-up (gated on Phases 1–2). URL domain emphasis + punycode warning; schema defaults pre-filled in form rendering; interactive render-and-confirm for mcpx elicit answer with a script-preserving opt-out (non-interactive behaviour unchanged). Retire the six elicit-ui gaps; completion evidence on mcpx: elicitation storage is readable by any local user and never pruned; elicitation UI and response validation rows dezren39/darwin-nix#255 — commenting, not closing (its validation acceptance is only partly this design's).

Open questions (stay questions; not filed)

• Should the logs directory itself go owner-only later (log index can carry tool-call arguments)? Its own design if evidence appears.
• Should sampling rows get a different retention bound than form answers? One bound until size evidence argues otherwise.
• Does the OpenCode plugin (out-of-tree) read bus payload fields Phase 2 removes? To confirm in Phase 2 triage; the fix is routing it through the broker read path, not restoring the leak.
• Full TUI edit-in-place for answers vs render-and-confirm? Evidence from actual use first.

Acceptance (design level)

• Phases 1–3 filed as sub-issues of this issue and landed.
• Fresh and upgraded installs: elicit.db + its directory owner-only, verified on disk; a question pending across the upgrade is still answerable.
• Terminal history bounded by the documented age/count limits; pending never pruned.
• No bus event carries a question's message/schema/URL or an answer's content.
• mcpx elicit shows the asking server, the URL domain called out (punycode warning where applicable), defaults pre-filled, and an interactive review before relay.
• mcpx: elicitation storage is readable by any local user and never pruned; elicitation UI and response validation rows dezren39/darwin-nix#255 carries the completion evidence with its remaining validation slice named honestly.

agent-note:v1 — filed by repo design architect (dedicated code job, pass 8, 2026-10-28)

• task: design origination for the nix#255 elicitation/sampling hygiene cluster, audited against main d39e611
• outcome: design doc written (files/designs/code-mcpx-elicitation-broker-hygiene.md in the keep-the-four-repos-healthy goal workspace); 3 phases to be filed as sub-issues and enqueued as triage packets
• dedupe: searched code issues 2026-10-28 (elicit storage, elicit.db, punycode, broker store, prune elicitation) — no existing issue covers this scope; mcpx: Phase 3 of #1481 — validate elicitation form answers against requestedSchema in client.answer #1484 owns only the requestedSchema-validation slice