# Admin Runtime Health / Runtime Action Panel ## Purpose The user-facing page title is **Runtime Action Panel**. It is the action-first operator surface for Blueprint Runtime current activity, role activity, next action, health, and handoff exports. `Admin Runtime Health` remains the compatibility name for the route/API/backend contract where broad renames would create churn. It is not a generic infrastructure uptime page. It renders Runtime-owned workflow truth so an admin can quickly answer: - whether Runtime is healthy, degraded, blocked, waiting, or unavailable. - which gate is active. - which chunk/work package is active. - which run mode is active: `single_chunk` or `full_orchestration`. - which authority mode is active: `manual` or `autonomous`. - whether validation, leases, dispatcher state, human actions, consultant checkpoints, and recent events are healthy. - what the recommended next action is. ## Canonical Source The canonical Runtime surface is: ```bash node ai/runtime/dist/cli.js runtime health-snapshot --json ``` The Runtime API method is: ```text runtime.healthSnapshot ``` The frontend must not reconstruct workflow truth from scattered APIs. The backend Admin GraphQL query maps the Runtime snapshot into GraphQL fields, and the frontend renders that data only. ## Backend Surface The backend exposes: ```graphql query AdminRuntimeHealth { adminRuntimeHealth { ... } } ``` The resolver is admin-guarded and read-only. Non-admin users must not be able to access the query. Runtime daemon absence must return a degraded/unavailable snapshot instead of an opaque page failure. The backend must not use shell scorecard wrappers as the canonical proof surface for this dashboard. ## Frontend Surface The page is: ```text Admin -> Health /admin/health ``` The visible page title is `Runtime Action Panel`. The page intentionally omits the older `Admin` eyebrow and generic `Health, activity, and operator handoff` subtitle; the first content cards explain current role/activity context. The compact navigation/tab label may remain `Health` because it points to the existing `/admin/health` compatibility route. The page is visible only for admin users and uses the existing authenticated admin visibility conventions. It contains no approval, retry, close, commit, lifecycle transition, dispatcher execution, or consultant import controls. MVP refresh behavior is page-load plus manual refresh only. Polling, streaming, alerts, mutation buttons, and long-term analytics are deferred. ## Redaction The default snapshot is redacted and bounded. Raw details are an admin/debug drill-down and must remain redacted by default. Do not expose secrets, bearer tokens, passwords, full local runtime internals, or unbounded historical audit data through the dashboard. ## Run Mode And Authority Mode Runtime owns these fields: - `orchestration_mode`: `single_chunk`, `full_orchestration`, or `unknown`. - `authority_mode`: `manual`, `autonomous`, or `unknown`. This is the user-facing Authority value. - `authority_basis`: for example `operator_approved` or `deemed`. This explains why the authority mode applies. - `authority_label`: for example `manual_operator_approval` or `authority_to_continue_autonomously`. `deemed` is an autonomous authority basis/source, not a top-level user-facing authority mode. Runtime details preserve `authority_label`, `audit_label`, and `answer_source` for audit/debug surfaces; the dashboard should show one primary Authority value. The UI may display these fields, but must not infer them from chunk markdown, work-package text, route state, or frontend-only conditions. ## Healthy Waiting Waiting for a human, manual consultant review, or an approval boundary can be healthy. The dashboard must visually distinguish healthy waiting from blocked, failed, stale, degraded, unavailable, or unknown states. ## Work Context Selection Runtime owns current work-context selection. The dashboard must render the Runtime snapshot instead of choosing a work package itself. Selection rules: - When a chunk is active, the work package that references that chunk is the current work package. ## Role Activity Runtime owns role activity projection under `role_activity`. Canonical rules: - Coordination owner and execution owner are distinct. - The frontend must not infer role activity from owner strings, file paths, labels, or route state. - Active/waiting role states must be evidence-backed by Runtime Health, lifecycle, dispatcher, approval, validation, or work-package state. - Insufficiently evidenced role activity is represented as idle or omitted rather than guessed. - The dashboard may render role activity as read-only status cards/lists only. - The role roster may include potential workflow roles even when idle, but it must not mark scheduled, expected, assigned, waiting, passed, or review-ready roles as actively working unless Runtime evidence says they are active. - Live in-between work belongs to `runtime_work_session` / `runtime_work_step` or an equivalent Runtime-owned projection. It must not be faked by reactivating lifecycle gates after implementation or QA has actually stopped. - Active/blinking indicators require Runtime-provided fresh liveness evidence. Stale, unknown, completed, failed, scheduled, expected, waiting, and passed states are non-active for animation purposes. - When no chunk is active, a work package at `Ready For Human Review` is a current review/close boundary, not active implementation. - Active package files that have no remaining chunks or report an end-of-queue final review boundary are reported as stale/overlapping work-package records and must not silently replace the current work package. - Long-running umbrella packages remain visible as overlap context but must not replace a focused current work package. - `current_gate` is Runtime-provided. No active chunk is `idle` or a review boundary, never `skipped` unless Runtime explicitly reports a skipped state. The snapshot exposes this under `details.work_package_context` so operators can see the selected package and any overlapping active work-package records without changing lifecycle authority. ## State Vocabulary Runtime owns dashboard-facing state vocabulary and exposes the current policy under `details.state_vocabulary`. Canonical scope rules: - Requirement, Planning, and Consultant Review are plan/work-package scoped gates. - Implementation, QA, Human Review, and Close/Commit are chunk/workflow-cycle scoped gates. - Validation is a runtime/system health dimension and may be degraded even when no chunk is active. - Skipped means explicitly skipped by Runtime policy, not merely inactive. - Idle/no-active-chunk means no current work for that gate. - Healthy waiting states are not failures. Frontend components may format labels for display, but must not infer these states from raw markdown, route state, or frontend-only conditions. ## Live Transport And Socket Diagnostics Socket.IO is a live invalidation transport only. `runtime_health.changed` events tell the frontend which canonical GraphQL query family may be stale; the dashboard must refetch `adminRuntimeHealth` before changing Runtime truth on screen. Page reachability, GraphQL/backend reachability, Runtime availability, Socket.IO namespace reachability, and authenticated admin room membership are different facts. The dashboard must use Runtime/backend-owned socket diagnostics for connected devices and room membership, including mobile/PWA clients over MagicDNS or Tailscale. A browser or PWA that can load `/admin/health` has not therefore proven it joined `admin.runtime_health`. The connection banner is app-shell state and may reflect browser/backend/socket or Runtime availability. It is not a substitute for Runtime Health snapshot truth or the Socket.IO device registry. ## Operator / Assistant Messages The Health page may render a bounded `Operator / Assistant Messages` window for operator prompts, assistant answers, assistant work updates, Runtime progress notes, and operator question/answer artifacts. Retention and ownership rules: - Direct operator/assistant message records are context-only records owned by Runtime message-stream producers. The direct JSONL stream retains the latest 3000 records. - Repository-controlled runners and prompt boundaries should write operationally useful operator prompts, assistant inline answers, and assistant work updates with `node ai/runtime/dist/cli.js runtime message-record`. - Runtime progress notes are owned by the Runtime progress-note subsystem and retain their own latest bounded set. - Operator question and answer files remain owned by the operator-question lifecycle. The Health projection must not delete, rewrite, or compact those artifacts. - The backend Health projection exposes only the latest 100 combined messages and reads only bounded file contents from each source. - Source-specific historical retention may differ, but the dashboard projection must stay bounded, redacted, and read-only. - Message records are operator context, not workflow authority. They must not mutate lifecycle state, approvals, dispatcher state, service truth, or Runtime Health truth. - Passive freshness is Runtime State Journal invalidation plus GraphQL refetch. Socket.IO payloads are invalidation-only and must not become message truth. ## Validation Use Runtime CLI/API and app validation: ```bash node ai/runtime/dist/cli.js runtime health-snapshot --json node ai/runtime/dist/cli.js summary validate --chunk --json node ai/runtime/dist/cli.js validate --tier fast node ai/runtime/dist/cli.js validate --tier full yarn build:backend yarn workspace backend test:e2e yarn codegen yarn test:frontend --watch=false yarn build:frontend ``` Shell scorecard wrappers are compatibility-only and must not be used as the canonical Health dashboard validation surface. ## Deferred Work - Mutation controls. - Approval or close/commit actions. - Retry controls. - Consultant response import controls. - Polling, streaming, alerting, and historical analytics. - Unredacted local-development detail mode. - Angular Router cutover, tracked separately by chunk `000138`.