nixos-config/docs/research/intent-board-state-workflow-ui-2026-09-11.md

Intent Board: code, workflow, and live UI audit

Date: 2026-09-11. Investigator: the primary Codex conversation, without delegated research. Scope: assessment only. No production cards, configuration, jobs, deployments, or implementation files were changed.

Assessment

The board is a functioning orchestration application with significant implemented capability, but its end-to-end guarantees and user-facing state model lag behind that capability. It can dispatch work, split goals into dependency-aware children, review results, collect telemetry, and arrange deployments. It cannot yet consistently tell the operator what has actually succeeded, why work stopped, or which recovery action will work.

The most consequential findings are not cosmetic: review rejection can be parsed as approval; the deployment runner does not select the reviewed revision; and manual bookkeeping can become supposedly trusted deployment evidence. These behaviors are reproducible in isolated diagnostics. They do not establish that a wrong production deployment has occurred.

My recommendation is to stabilize outcome semantics, revision provenance, and recovery before adding further agents or workflow states. Preserve the existing intent/worker separation, isolated builder worktrees, deterministic operator validation, and report links.

Evidence and method

• Read current board frontend, API, worker branches, completion watcher, orchestration, fanout, telemetry, tests, Nix wiring, and relevant builder/deployment code.
• Used the existing Graphify graph for navigation: BFS query board intent phase review worker, 101 matching/traversed nodes, output capped at 37 nodes. Outcome: useful navigation, not current-source proof. Graph dated September 7; no graph metadata updated.
• Inspected the live application in Chromium through Playwright at http://127.0.0.1:8060/, on blunix, around 18:45–18:49 CEST. Desktop 1440×1000 and mobile 390×844; light and dark appearances. Opened read-only intent and review dialogs, tested keyboard focus across polling, and simulated a failed API request inside that browser only. Browser routing blocked all methods other than GET/HEAD. No mutation request was attempted.
• The HTTPS front door https://intent-board.0ff.space/ returned 401 without authentication. Browser inspection used the local backend; authenticated reverse-proxy/browser behavior was not tested.
• Served HTML and installed trigger, worker, completion watcher, fanout, orchestration, and deployment runner matched the examined repository files by SHA-256.
• Existing tests: 279 board/telemetry tests and 38 subtests passed; seven selected builder deployment/deferred-deployment tests passed. No system build or activation.
• Additional temporary diagnostics reproduced action/transition mismatches, review parsing, unpinned deployment command construction, interleaved state overwrite, incomplete downstream queue inspection, and a research-transition exception. Subprocess calls in deployment/review probes were mocked; no model was invoked.
• Historical audit docs/research/intent-board-architektur-ux-evaluation.md was context, not evidence of current behavior.

Temporary evidence: /tmp/intent-board-browser-audit.json, /tmp/intent-board-audit-live.json, /tmp/intent-board-family-telemetry.json, /tmp/intent-board-audit-probes.py, and screenshots /tmp/intent-board-{desktop,dark,mobile,intent}.png. Temporary files are not durable project artifacts.

Actual architecture

Intent and research-intent Markdown files provide titles and source documents. Runtime JSON overlays phases, results, relationships, profiles, and actions. Manual ideas and planning drafts originate in runtime state. The API merges these sources; it does not reconstruct a complete event history from Git.

The frontend projects many backend phases into seven lifecycle groups. It renders server-provided actions but independently derives lifecycle grouping, family progress, and status labels. These separate derivations are a major source of inconsistency.

The trigger creates files in the board inbox. The board worker executes research/review/operator/planning/inspection work or forwards implementation work into the separate agent-codex builder queues. Two builder lanes run through separate instances and isolated Git worktrees. Completion records return to the board watcher. Positive review creates a persistent deployment request; a separate runner performs the switch and reports back. Telemetry is stored separately in SQLite.

This separation has useful boundaries: model output is validated before operator decisions are applied, ordinary builder jobs request deferred deployment, and the deployment runner fixes its allowed host and repository. However, a request containing a commit is not equivalent to a deployment built from that commit.

Sources: board-agent/trigger.py:401, :1230; worker.py:935, :1089, :2001; completion_watcher.py:203; orchestration.py:585; agent-codex/deploy_runner.py:63. Paths below are relative to hosts/blunix/localServices/ unless otherwise stated.

Live snapshot and representative cases

The API snapshot had 50 cards: 28 archived, six planned, five deployed, two in implementation, two failed inspectors, one inspector question, two negative reviews, two completed research cards, one waiting parent, and one blocked parent. These are backend phase counts, not visible top-level card counts.

1. full-system-audit-remediation: parent blocked, one of five children successful. mariadb-bind-local has a deployment completion; codeberg-mirror-disable and nix-gc-daily have negative reviews. The two remaining children are no_changes. Despite this, the parent displays “Kinder laufen” and an active wave, derived from children retaining implementation phases. The waiting/running presentation contradicts terminal outcomes.
2. lldap-fail2ban-protection: the builder report says it could not read the required logs or use web search and therefore did not implement a guessed filter. This is a missing-capability/evidence outcome. The card is in implementation with no_changes, offering only Archive.
3. gotosocial-orphaned-data-cleanup: the report challenges the task's source premise and contains a non-fast-forward push rejection. This should distinguish a task clarification from a publication failure. It is also no_changes with only Archive.
4. board-session-usage-indicator: waiting parent, zero of three children successful. One child needs input and two are planned/dependency-blocked. The parent appears in Running with green “Status: abgeschlossen,” describing the completed operator job rather than the unfinished goal.
5. board-intent-operator-orchestration: the inspector stored repo_status=partial and evidence, but the card exposes “inspected” and an old Builder report rather than a diagnosis report. Some stored evidence claims fields are absent that are present in current code. Its observation revision/freshness must be visible; this does not prove what was present when that older inspection ran.
6. researcher-live-eval-tooling: phase deployed, negative review_decision, and no deployment status. It still offers Repair. This is an observed contradictory record, not proof that the current runner deployed a rejected revision.
7. board-nested-child-intents and board-reviewer-visual-verification: failed inspection records remain visible with parse-related error details. Recent parser changes mean these historical messages are not evidence that the same output still fails today. Recovery still needs clear revalidation and a usable result view.

State-by-state workflow and information needs

Backend state/path	What happens	Current presentation / gap	Information and next action needed
idea	Manual runtime-only card	Backlog; no visible conversion into a planning draft	Refine into intent, edit idea, archive/delete
entwurf_laeuft	Planner intake runs	Running with conversation	Queued vs executing, last activity, runtime, failure recovery
entwurf_frage	Planner waits for answer	Needs attention; conversation and reply controls	Concrete question, retained answer, clear responsibility
entwurf_fehlgeschlagen	Intake failed	Needs attention; retry available	Failure category and whether retry can resolve it
Draft → geplant	Wrapper writes Markdown and replaces draft card	Ready; original transcript no longer exposed as a draft	Stable identity/link to the conversation that produced the intent
geplant	Intent available; no automatic ordinary build	Ready; Operator, two Builder choices, Diagnose	Acceptance criteria, dependency readiness, recommended primary action and why
operator_angefordert / operator_laeuft	Read-only operator returns direct/split/needs-human decision	Running	Queued/executing, decision and source revision
Operator direct	Scheduler queues implementation	Running	Chosen lane/profile, rationale, immutable attempt identity
Operator split → wartet_auf_kinder	Children dispatched as dependencies and capacity allow	Running; nested children and verbose badges	Distinguish runnable, queued, executing, blocked, and waiting-on-user counts
durch_kinder_blockiert	At least one child failed/rejected	Needs attention parent; can still say children running	Actual blocking cause per child and recovery that preserves the family
operator_klaerung_noetig	Operator needs help or failed	Needs attention	Required human decision, editable answer/replan path
in_umsetzung / in_umsetzung_leicht	Work handed to separate builder lane	Running or Needs attention depending on last status	Queue position, executing job, capability requirements, last activity
Builder committed → review	Completion queues review of recorded commit	Running	Review pending/running, exact source and result revision
Builder limit_reached	Automatic escalation while ladder remains; otherwise terminal	Escalation badges, then Needs attention	Attempts used, next profile, total budget, exhausted reason
Builder no_changes	Usually no phase change	Needs attention, often Archive only	Structured already-satisfied / needs-input / forbidden / publish-failed outcomes
aufteilen_angefordert → aufgeteilt	Legacy splitter writes children	Running → Done, even though children may remain unfinished	“Decomposed; child work outstanding,” not goal completion
Review → planung_mit_feedback	Negative result stored	Needs attention; often green “abgeschlossen”	Explicit rejected verdict, blocking findings, repair/replan choice
Review → bereit_fuer_deployment	Positive result immediately queues deployment	Ready to deploy	Whether deployment is automatic, queued, running, or awaiting a person
Deployment → deployed	Runner success accepted by watcher	Done	Actual activated revision/system generation and task-relevant health evidence
Deployment failure	Watcher routes to fixer failure	Needs attention	Deployment-specific error, retained artifact, retry-deploy vs repair distinction
klaerung_reparatur / inspector_laeuft	Typed inspection or repair request	Running	Clearly distinguish diagnosis from code mutation
Inspection completion	Result stored; original phase restored unless question	Often only “inspected”	Readable diagnosis, checked revision/time, evidence and required action
inspector_rueckfrage / fixer_rueckfrage	User answer persists; new session continues	Needs attention with answer box	Correct role label; avoid generic “answer the Fixer” for inspection
fixer_laeuft	Isolated implementation repair	Running	Attempt limit, exact target, changes, separate review required
Fixer not_applicable	Remains klaerung_reparatur	Falls into Running although terminal	Explain no applicable repair and offer routing/replanning
Fixer/inspector failure	Error retained	Needs attention; Archive can be offered but rejected	Action list must agree with transition validation
Research requested/running/finished/failed	Separate research lifecycle; no Builder trigger	Ready/Running/Done/Needs attention	Source intent, report, retry-research, use findings to create linked intent
archiviert	Bookkeeping, not cancellation	Archived; all archived cards expanded	Reactivate, archive provenance, cancellation semantics, retained family visibility

Sources: trigger.py:360, :925, :1399, :1507; worker.py:1851, :2001; completion_watcher.py:350; board.html:816, :924, :1210, :1302.

Priority findings

P1 — Negative review text can release deployment

worker.py:1450 searches the entire report for an approval phrase before searching for rejection. Both isolated inputs returned bereit_fuer_deployment:

• Not ready for deployment. Decision: back to planning.
• Nicht bereit für Deployment. Entscheidung: zurück zur Planung.

The positive branch of process_job immediately queues deployment (worker.py:2177 vicinity). Negation and quoted prior decisions are enough to undermine the gate; no malicious input is required. Use one validated structured verdict bound to a full commit hash, reject conflicting/ambiguous results, and separate report prose from the decision. Add negative/quoted/multiple-verdict cases.

P1 — The deployment request is pinned; the build is not

agent-codex/deploy_runner.py:63 accepts a request with commit_hash but fetches/fast-forwards dev and runs switch --flake path:<shared-repo>#blunix. The hash does not select or verify the build source. _write_completion (:161) reports the requested hash afterward.

A mocked command-trace reproduction confirmed that the requested hash appeared in none of the executed commands. If another commit reaches dev before deployment, it can be included without the corresponding review having completed. The mutable checkout also weakens reproducibility. Fix by building an immutable reviewed revision or a separately reviewed integration revision and recording the actual activated closure/revision. Merely comparing request/completion metadata does not close this gap.

P1 — Mutable display state can masquerade as deployment evidence

An isolated planung_mit_feedback → deployed transition succeeded without a commit or deploy job. deployment_evidence() then returned status=deployed, source “trusted board wrapper state.” apply_routing_recommendation() also assigns phases directly instead of using the transition dispatcher: recommending in_umsetzung sets that phase while queuing zero jobs.

These do not directly execute unauthorized system changes in the reproduction; they create false progress/evidence and bypass action semantics. Separate operational facts from manual classification. Derive deployed status from a verified deployment record, and apply routing through the same validated command path used for ordinary actions. Sources: trigger.py:1453, :1491, :1760.

P1 — Shared state updates are not transactional across processes

trigger.py has a process-local threading lock. Worker state writers (worker.py:514, :544), fanout, failure handler, metrics, and operator scheduling maintain separate read/modify/write implementations. The operator lock is separate; it is not a lock shared by all writers. Multiple writers use the same .tmp filename.

An isolated legal interleaving—trigger reads state, worker records completion, trigger saves its older snapshot—lost the completion field. This establishes the vulnerability, not an observed production incident. Atomic rename alone does not make the whole transaction atomic. Use one cross-process transaction mechanism, ideally a shared SQLite state/event store or a single writer, with unique temporary files if JSON remains.

P1/P2 — Recovery semantics are missing, not just buttons

builder.py:815 classifies anything without a recognized success record or the string NICHT committed as no_changes. apply_commit():930 reports push failures in different prose. The live GoToSocial case shows the resulting misclassification.

available_actions() omits Diagnose for implementation phases; repair_eligible() excludes no_changes. Consequently these cards can be stranded with only Archive. Failed inspector cards conversely advertise Archive, but update_phase() rejects it until a reset to planned; the UI offers no such reset. Archived cards have no ordinary Reactivate action. route_next is an implemented task type without a normal action that requests it.

Return structured execution and publication outcomes from the harness, then derive both actions and state from those outcomes. Distinguish task clarification, missing tools/evidence, genuine no-op, failed checks, failed publication, and deployment failure. An infrastructure error should not automatically ask a code-writing Fixer to change the project.

P2 — Queue/replay guarantees are incomplete

• builder_trigger_blocked() (trigger.py:1202) examines board queues only. After handoff, a downstream builder-processing record is not seen; an isolated same-card/lane probe returned no block. The operator scheduler does inspect downstream queues, so the two dispatch paths disagree. This is a guard gap; downstream serialization may limit simultaneous execution but does not establish duplicate-request prevention.
• Completion records move to consumed before processing (completion_watcher.py:62, :529). A crash between those steps leaves a consumed-but-unapplied result; the shown main loop does not replay it. This crash window was inspected, not triggered in production.
• A research reset from failed to requested writes state and then raises UnboundLocalError because job_id is initialized later in the non-research branch (trigger.py:1598 vicinity). Reproduced in temporary state.
• Queue IDs based on slug and integer seconds and updates without current-attempt checks deserve explicit duplicate/stale-completion tests.

P2 — The UI confuses job completion, goal success, and deployment

statusLabel() maps done to completed regardless of a negative review. Family status treats an implementation phase as active even with terminal no_changes. Lifecycle grouping prioritizes some phase labels over contradictory failure data. Child cards appear only inside their parent, so a child needing attention can be hidden in the Running column.

Have the server emit a single typed display state and explanation: goal state, current job state, last outcome, blocking actor, next action. Preserve both family navigation and a flat “needs my attention” view. Count children separately from parent goals.

P2 — Diagnosis and provenance exist but are not adequately displayed

The API exposes repository evidence, deployment status, timestamps, profiles, and relationships, but much is never rendered. Inspector result summaries are not exposed as a readable report. The telemetry endpoint provides up to 20 runs; the dialog renders only current_pipeline. A Builder report is hidden once a review report exists. Review files are keyed by slug and overwritten, limiting accessible per-attempt provenance. Draft completion preserves its conversation in state, but ordinary intent serialization does not surface it.

Provide an intent detail view with Overview, Attempts, Evidence, Conversation, and Changes. Bind each observation to its source revision and time. Keep current recommendation distinct from old failures and old review verdicts.

Browser and interaction findings

The desktop board is legible at the individual-card level, and dark mode is implemented consistently through theme variables. Native dialogs, keyboard handlers on report links, escaped text rendering, orphan fallback, and preservation of clarification text are useful foundations. No uncaught page error appeared during successful loading and read-only dialog use.

The screen gives scarce space to current work:

• Eight tracks including Agents; content spans 2014 pixels. At 1440 pixels, Done and Archived are outside the initial viewport.
• Agents occupies the first 260 pixels; Backlog another 230 pixels despite being empty. On a 390-pixel phone, initial content is mostly settings and test controls; actual work starts offscreen at x=538.
• The archived column was 5113 pixels tall; Needs attention 4382; Running 3128. Families expand all children and long operator explanations. There is no search, filtering, collapse, or urgency sorting.
• Dense colored family cards contain repeated parent/child identifiers, raw phase keys, mixed German/English labels, and three or more competing action buttons. This makes a hierarchy that is technically present difficult to scan.
• Prominent install/uninstall smoke-test controls occupy the main header. Everyday priority and freshness information is absent there.
• Intent/review dialogs show raw Markdown. They are useful evidence viewers but do not emphasize decision, outstanding criteria, or next action. The tested intent title also duplicated the “Intent:” prefix.
• A focused card Intent link became BODY after the five-second rerender. The edit guard protects input/select/textarea focus, not button or report-link navigation.
• Blocking the next board GET in the browser left the prior board displayed without a stale/offline indicator or live alert. The catch logs only to console.

Suggested direction: move Agents configuration into a settings drawer; show attention/running/ready summaries first; use collapsible families and a searchable archive; provide a list view at narrow widths; preserve keyed DOM nodes and keyboard focus; show last successful refresh and reconnect state. These are product recommendations from observed behavior, not a formal accessibility conformance audit.

Metrics, operations, and maintainability

The live remediation family telemetry had ten jobs and reported 1,632,046 total tokens, of which 1,435,501 were cached input tokens, and 459.007 seconds of summed job duration. These are reported counters, not audited invoices or end-to-end elapsed time. Its reported cost aggregate was $0.9061986; coverage of missing costs is not indicated, so it must not be presented as a verified full pipeline cost.

Negative reviews and no_changes jobs had success=true in telemetry while the family remained blocked. That can sensibly mean a model call completed, but it must not be used as goal-success rate. The current dialog does not show the stored dollar cost and does not provide an attempt-history selector. Additional useful measures are time waiting for people, queue delay, time to accepted outcome, rework rate, verified deployment rate, missing-measurement coverage, and cost per accepted outcome.

All six live runtime configurations selected Claude at observation time. The user reports exhausted Claude session credits; the board does not expose provider availability in this view. Starting work should explain unavailable capability/quota and preserve the immutable chosen profile. The Codex UI currently lists only Default and gpt-5.6-luna; allowed model/configuration values are duplicated across frontend, orchestration, and Nix defaults.

The implementation spans roughly 14,000 lines across the board's Python/HTML files, including about 5,300 lines of tests. The concern is duplicated state rules, not line count itself. Documentation still describes the original single-transition pilot, dragging, and an automatic correction loop even though the current worker stores negative review results and exposes manual Repair. Tests preserve several old behaviors, including no-change staying in its phase, and many frontend assertions inspect source strings rather than browser behavior.

The inspected Restic configuration backs up LDAP, Headscale, and Forgejo dump paths, not /var/lib/board-agent. This is a backup coverage question, not proof that no other backup exists. Runtime state, queue/acknowledgment records, and telemetry need a documented consistency-aware restore procedure. Loaders that silently substitute an empty board for malformed state should expose degraded state rather than make old intents look newly ready.

Sources: board.html:1117, :1152, :1564, :1667; telemetry.py:315; completion_watcher.py:267; worker.py:101; restic.nix:7; trigger.py:229; README.md:1.

Recommended implementation order

1. Repair the release boundary: structured review verdict, immutable deployment source, actual deployed revision evidence, no deployment claims from bookkeeping.
2. Introduce structured builder/publication outcomes and one shared transition/action contract. Cover every terminal outcome with a valid continuation; fix research reset and action mismatches.
3. Make state transactions and completion acknowledgment/replay reliable; enforce attempt identity and shared queue occupancy across both dispatch paths.
4. Make the board truthful: separate goal/job/deployment state; show explicit blockers and next actor; put diagnosis and per-attempt evidence in one detail view.
5. Improve layout and interaction: collapse settings/families/archive, attention-first list, search, mobile presentation, focus preservation, stale-data indicator.
6. Add invariant-focused tests and operational metrics: rejected verdict never releases; activated revision equals reviewed revision; advertised action is valid; every terminal failure is recoverable; concurrent updates survive; replay is idempotent; blocked children surface in attention.

There is no need for a framework rewrite to begin this work. A shared state/transition layer and small browser regression suite would address more risk than adding new roles.

Uncertainties and product decisions

No production phase transitions, real retries, cancellation, repairs, model calls, deployment, destructive actions, or restore exercises were performed. Historical rows may reflect older code or manual intervention. The board snapshot is a point-in-time sample, and the two security-sensitive code findings were not tied to an incident. Authentication was checked only through the unauthenticated HTTPS response and configuration. No broad dependency/security audit or formal accessibility certification was attempted.

The main product decision is whether positive review should automatically deploy or should wait for explicit release. Current code automatically queues deployment, while “Ready to deploy” suggests a waiting gate. Either policy can be coherent, but the interface, authorization model, and evidence must say the same thing. A second decision is whether the default view serves a person managing goals or a person debugging agent infrastructure; today it heavily favors the latter.

Implementation follow-up — September 12 (not yet activated)

The user selected automatic deployment after approval. The working-tree changes implement structured commit-bound verdicts, immutable deployment builds, exact activated-closure comparison, a deployment retry without another model run, and refusal of automatic rollback from the last verified deployment. Manual result-state assignment can no longer bypass worker evidence.

Board state now uses a shared cross-process transaction boundary, a durable queue outbox and claim markers. Completion processing records acknowledgments after transactional application and checks pipeline/attempt identity. The research-reset failure and archived-family scheduling were corrected. Failed publication preserves unpublished work; its location is shown as evidence.

The UI separates goal state from job outcome, surfaces blocked children and unverified legacy deployments, and adds search, archive/attention views, collapsible families, separate settings, detailed evidence/history/conversation views, focus preservation and stale-data warnings. These changes were exercised in Chromium with isolated fixtures and the earlier read-only live snapshot.

Regression verification: 419 Python tests and 38 subtests passed. Both Nix script bundles were built; flake evaluation was checked without building the VM checks or activating a system. The repeatable test_board_browser.cjs test checks desktop/mobile layout, filtering, dialogs, keyboard focus and API failure handling. It never sends live mutation requests or invokes a model.

Limits remain explicit: activation and live post-deployment smoke testing are pending; old cards are not bulk-certified or restarted. Historical missing attempt data cannot be recreated. Quota availability is not probed, and changing model choices does not validate provider access. Restic coverage added here is for board metadata and the deployment ledger, not a coordinated queue/SQLite restore. A linked research-to-implementation planner flow and exhaustive accessibility/production crash testing remain follow-up work. The original audit above describes the observed pre-change system, not a claim that every suggested product extension has been completed.

Final validation caveat: a later all-host nix flake check --no-build rerun, including a retry outside the sandbox, failed while evaluating tnix because a referenced cached flake source was no longer valid. This is not a passing final all-host check; the earlier successful evaluation and script-bundle builds do not replace resolution of that environment/input issue before a full rollout. The scoped final blunix evaluation subsequently passed with eval-cache=false, producing rbh29vyl8lwnj0dw3ssjx3scwna8klfz-nixos-system-blunix-26.11.20260910.8ce4ef6.drv. No system was activated. Unrelated flake.lock and journald edits must be excluded from any board-only activation snapshot.