stack/docs/plans/2026-11-03_console-decisions-implementation.md

General Console Decisions Implementation Plan

For agentic workers: Use superpowers:subagent-driven-development or superpowers:executing-plans task by task. Do not dispatch further agents from an implementation task.

Goal: Let a signed-in user answer every eligible human-routed decision through working option buttons, under approved REQ-WEB-2.

Architecture: Extend the existing broker Console preview/resolve protocol and one-use HTTP confirmation flow to ordinary decisions with two to nine choices. Keep grant execution, authentication and audit in their existing owners.

Tech Stack: Node.js ES modules, SQLite broker, existing Console JavaScript and Chromium test harness; no new dependencies.

Spec: docs/plans/2026-11-03_request-to-product-design.md, implementation stage 1. Jason authorized GPT agents for these tasks on 2026-11-03 after the design handoff.

Global Constraints

• Root stays bootstrap-only; add no root files.
• Preserve the exact CONSOLE_VERBS pair and existing OIDC/session/origin authentication checks.
• Human Console answers are recorded as via=console with the verified subject; agent broker answers retain their real role/run.
• Grant requests keep their concrete rights summary, confirmation, single-use execution and refusal behavior.
• Ordinary choices can have two to nine options, and any valid option key; no terminal is required to answer them.
• Reuse one-use, session/business/decision/choice/digest-bound confirmations; never automatically replay an uncertain resolution.
• Do not modify hard-wait lists, role authority, approved PRD policy or live instance configuration in this task.
• Work only in the T3-prepared isolated checkout. No other worktrees, subagents, pushes, merges, host operations or PR creation.
• Tests precede changed product behavior. Commit locally only after the affected suites pass. Record exact failures and inherited limitations honestly.

Review Focus

• A three-option product-intake choice must resolve its selected option, not be interpreted as approve/deny.
• A decision closed or changed while its confirmation is open must not submit an old choice.
• Browser refresh, navigation, cancellation and a second click must not leak or replay confirmations.
• The visible receipt must describe a recorded ordinary choice without claiming a grant started or a denial stopped all work.
• Generic resolution must never start an unbound grant, resolve another role's decision or cross a business/session boundary.

Task 1: General Console decision answers

Files:

• Modify: packages/bus/src/broker.mjs (#consoleResolution, Console preview/resolve and decision view callers).
• Modify: packages/webui/src/decision-http.mjs (preview validation, chosen-option confirmation and response).
• Modify: packages/webui/src/public/bus.js (answer panel, event handlers, receipts, inbox/help copy).
• Modify as needed: packages/webui/src/public/shell.css and packages/webui/README.md for this behavior only.
• Tests: packages/bus/tests/console-decide.test.mjs, packages/webui/tests/decision-http.test.mjs, packages/webui/tests/decide-sso.test.mjs, packages/webui/tests/decide-browser.test.mjs, and existing Console view tests affected by the changed contract/copy.

Interfaces:

• Consumes: existing decision.preview.console({id}), decision.resolve.console({id,choice,digest}), POST /api/decisions/:id/confirmation and /resolve; preserve their authentication and transport ownership.

• Produces: an authoritative preview options list from the broker for ordinary human-routed choices. Keep existing grant-specific approve, deny and grant fields usable for grant requests. The HTTP confirmation carries the selected key/text plus enough kind/context to render an accurate receipt.

• Subsequent intake work can raise a normal three-choice decision and rely on these existing endpoints; it must not add another decision channel.

• The digest binds the current decision, business, question/action, option list and authorization/grant context. A stale context is refused transactionally.

• Step 1: Establish the current targeted baseline. Read the production paths and existing tests; run the Console broker/HTTP/SSO/browser tests named below before changes. Record baseline failures without weakening assertions.

• Step 2: Add meaningful failing cases. Cover a three-choice ordinary human-routed decision; select the third option through the signed-in browser; assert exactly one decision resolution and its Console subject audit event, notification of the raiser, and zero grant execution. Also cover ordinary two-choice PRD approval and non-yes/no keys. Keep distinct denial tests for nonhuman/other-role routes and existing grant constraints.

• Step 3: Observe the intended failures. Run the newly added tests before implementing; failures must show the grant-only eligibility/UI restriction, not fixture or module-loading errors.

• Step 4: Extend the broker and HTTP protocol. Expose the real options for ordinary eligible decisions, validate the selected key from that list at both confirmation and transactional resolve, and preserve grant-specific fields/checks. Keep old grant requests and their executor behavior working.

• Step 5: Extend the Console. Render one working answer button per option; retain a review/confirm/cancel flow. Use selected option text for ordinary confirmation and receipts, preserve grant wording only for grants, and replace terminal-only help where Console answers are available. Keep read-only/signed-out state explanations and optional CLI fallback accurate.

• Step 6: Cover lifecycle edges. Exercise stale or already-closed decisions, duplicate answer clicks, cancellation, session expiry, navigation, business binding and uncertain HTTP outcomes; ensure invalid/missing grant bindings cannot start grant code. Extend existing tests rather than add a parallel harness.

• Step 7: Verify. Run targeted tests with node --test packages/bus/tests/console-decide.test.mjs and node --test packages/webui/tests/decision-http.test.mjs packages/webui/tests/decide-sso.test.mjs packages/webui/tests/decide-browser.test.mjs; then the full bus and WebUI package test commands. A pass is zero failures; report all skips and any unavailable browser prerequisite. Do not repeat passing full suites without a new change or unresolved concern.

• Step 8: Document and commit. Update relevant Console docs and append this task's own BUILD-LOG/SESSIONS evidence. Keep logs append-only. Commit only this task's tested changes locally, with #1839 and Vikunja #797 references. Write the report at the controller-specified path and return commit IDs, one-line test evidence and any concerns.