Merge pull request #14 from d3cker/codex/bot-runtime-sidebar

feat: show live bot runtime status in TUI sidebar

Author: d3cker

AGENTS.md

@@ -28,7 +28,7 @@ steps, project setup, headless operation, and removal.
 | [docs/architecture.md](docs/architecture.md) | Component responsibilities, a short issue-to-PR overview, configuration ownership, scheduler ownership, and shared state. | Start here to understand how the system is divided before locating implementation code. |
 | [docs/bot-workflow.md](docs/bot-workflow.md) | Eight Mermaid diagrams and detailed implementation notes: startup and polling; discovery and routing; task phases; sessions and questions; media helpers; verification and publication; feedback, merging, and tab closure; status, retries, and recovery. Includes links to the source for each area. | Use for exact execution order, state transitions, checkpoint behavior, failure paths, and tracing a bot task from issue to merged PR. |
 | [docs/configuration.md](docs/configuration.md) | The standard `.opencode/automation.json` format, defaults, setup flags, configuration tracking across Git branches, authors, triggers, checks, base branches, model capabilities, media helpers, custom prompts, signatures, and auto-merge settings. | Use when adding or changing user-facing configuration, defaults, or setup examples. |
-| [docs/runtime.md](docs/runtime.md) | User-visible behavior while the bot runs: GitHub questions and permission replies, branch selection, media inputs, prompt loading, follow-up comments, session tabs, and routine management commands. | Use when changing issue conversations, session continuation, runtime tools, or TUI behavior. |
+| [docs/runtime.md](docs/runtime.md) | User-visible behavior while the bot runs: GitHub questions and permission replies, branch selection, media inputs, prompt loading, follow-up comments, session tabs, runtime sidebar/status freshness, and routine management commands. | Use when changing issue conversations, session continuation, runtime tools, or TUI behavior. |
 | [docs/advanced.md](docs/advanced.md) | Separate scheduler/dispatcher setup, multiple repositories, custom RPC jobs, full options, timeouts, management and retry commands, persistence, reconciliation, locks, and known limits. | Use for low-level configuration, operational troubleshooting, recovery, or ownership/concurrency changes. |
 | [docs/installation.md](docs/installation.md) | Loader registration, config-directory precedence, prerequisites, source installation, project-local installation, upgrade conflicts, testing on another machine, and migration limits. | Use when working on packaging, installers, registration, upgrades, or deployment troubleshooting. |
 | [docs/releases.md](docs/releases.md) | Feature-to-devel and devel-to-release PR checks, automatic patch versions, manual npm version/tag releases, exact changelog notes, publication recovery, README commits on release, automatic release-to-devel synchronization, and promotion PRs into protected main. | Use for CI triggers, versioning, packaging, GitHub Release publication, branch permissions, or recovery after a failed release. |
@@ -68,7 +68,9 @@ the installation block without making remote writes. Keep its markers intact.
   runtime installation, and communication with the owner. `src/prompt.ts` loads
   instructions; `prompts/bot.md` contains the bundled bot instructions.
 - `src/tui.ts`, `src/ui.ts`, and `src/activity.ts` implement terminal integration
-  and task activity. `src/rpc.ts` defines RPC contracts; `src/manage.ts` exposes
+  and task activity. `src/sidebar.ts` renders the runtime panel;
+  `src/runtime-panel.ts` owns polling, freshness and presentation;
+  `src/monitor.ts` defines read-only monitoring schemas. `src/rpc.ts` defines RPC contracts; `src/manage.ts` exposes
   management operations.
 - `src/setup.ts`, `src/wizard.ts`, `src/install.ts`, and `scripts/` cover setup and
   installation. `examples/` contains configuration examples; `test/` contains

CHANGELOG.md

@@ -24,6 +24,12 @@ include the full version, for example `## 0.7.0-beta.1`.
 
 ### Added
 
+- Add a live BOT RUNTIME sidebar and `/botstatus` report with dispatcher operations,
+  scheduler scans/retries, queue counts and selected-task details. Keep stale and
+  unavailable readings explicit; monitor through read-only owner-scoped RPC.
+- Validate native sidebar rendering, reactive updates and narrow layouts as part
+  of the standard check command using pinned TUI/Bun development dependencies.
+
 - `/restartworkflow` and the matching CLI/RPC command resume a stopped task from
   its saved stage, preserving worktrees, sessions, PRs, and feedback. Checkpoint
   continuation requests across restarts without bypassing checks or permissions.

README.md

@@ -249,6 +249,11 @@ installations are not removed by `npm uninstall --global`.
 - **Merging:** approve the bot's PR or post a configured merge phrase. The author
   must be allowed and have repository write access. Set `autoMerge.enabled` to
   `false` to disable this. `signature` controls the signature on new bot messages.
+- **Runtime status:** the right sidebar's **BOT RUNTIME** panel shows dispatcher
+  work, GitHub discovery, scheduled scans, queue counts and the selected task.
+  `/botstatus` opens a full text report. Status refreshes every five seconds;
+  unavailable or stale readings are marked explicitly. See
+  [runtime panel details](docs/runtime.md#runtime-status-sidebar).
 - **Progress:** use `/bot` in the TUI, or the CLI's `status`, `scan`, `pause`, and
   `resume` commands from the target repository. Closing a PR closes its bot tabs
   while retaining session history. Authorized issue comments can continue work

docs/advanced.md

@@ -105,6 +105,23 @@ and unrecognized running-session errors produce errors. Recovery does not run a
 scan, resume a paused scheduler, or restart the service.
 Unlike `retry`, recovery can be queued while a different task is working.
 
+### Read-only runtime monitoring
+
+`automation.github.monitor` accepts `{}` and returns the owner directory,
+worker operation, optional active task key, scanning flag, last scan start/finish,
+optional redacted scan error, and enriched activity snapshots. It does not trigger
+work or write the queue. Worker operations are `idle`, `reconciling`, `executing`,
+`merging`, `maintenance`, or `stopped`; these are live diagnostics, not task phases.
+Scan finish means an attempt ended, including failed attempts; inspect `scanError`.
+Timing resets when the dispatcher is recreated.
+
+`automation.scheduler.status` supplies job `running`, `paused`, `nextAt`, failure
+count, error and last start/finish. The sidebar and `/botstatus` combine these APIs.
+Each poll has a four-second bound; failures retain marked stale data. The existing
+`activity` RPC/events still drive tab notifications and their ten-second fallback.
+Full task history remains available through `status`; see the
+[runtime sidebar](runtime.md#runtime-status-sidebar) for display and selection rules.
+
 ## Persistence and reconciliation
 
 The queue stores analysis decisions and clarification dialogue, comment ID, session ID, phase, pinned base branch,

docs/architecture.md

@@ -14,6 +14,8 @@ loads a generic scheduler, a GitHub dispatcher, and a terminal UI component.
 - **Terminal UI:** subscribes to activity events and polls for missed updates.
   Opens background tabs, closes task tabs after PR closure while retaining
   session history, and exposes `/bot` and `/restartworkflow` task selectors.
+  A read-only runtime sidebar and `/botstatus` combine live dispatcher diagnostics,
+  scheduler state and task snapshots, marking stale or unavailable data.
 
 ## Workflow
 
@@ -61,3 +63,10 @@ session continues and the replacement owner reconciles its saved identity.
 
 See [advanced configuration](advanced.md) for retry commands, limits, and RPC
 settings, and the [README](../README.md) for installation and user-facing behavior.
+
+Runtime monitoring is observational: `automation.github.monitor` exposes the
+owner's current worker operation, active task, scan timing/error, and enriched
+activity snapshots. Scheduler status retains its existing RPC. The TUI polls both
+independently every five seconds through the connected client; it does not infer
+worker activity from queue status alone. These live diagnostics do not add durable
+workflow phases or replace the existing ownership keepalive.

docs/bot-workflow.md

@@ -50,6 +50,12 @@ flowchart TD
     Stop[Owner reload or shutdown] --> Cleanup[Stop timers and local waits, settle writes, dispose RPC, release locks]
     Cleanup --> Preserve[Preserve durable queue and healthy worktree execution]
     Preserve --> Load
+    View[Runtime sidebar or botstatus] -.-> Monitor[Read dispatcher monitor and scheduler status every five seconds]
+    Monitor -.-> RPC
+    Monitor -.-> State
+    Monitor --> Fresh{Both readings available and fresh?}
+    Fresh -->|Yes| Display[Show live operations, queue and selected task]
+    Fresh -->|No| Stale[Mark unavailable or retained stale readings]
 ```
 
 - Easy configuration puts state under the shared Git directory at
@@ -469,6 +475,11 @@ flowchart TD
     UI --> Busy{Associated tab busy?}
     Busy -->|Yes| Defer[Retry closure on a later snapshot]
     Busy -->|No| Tabs[Close known task and helper tabs once, preserve sessions and worktrees]
+    Status[Independent monitor polling every five seconds] --> Sidebar[Append BOT RUNTIME to existing sidebar]
+    Selected[Selected session changes] --> Sidebar
+    Sidebar --> Details[Show owner operations and matching task, or active task fallback]
+    Status --> Missing[On failure retain last readings and mark stale]
+    Missing --> Sidebar
 ```
 
 Merge eligibility requires `done`, a tracked nonclosed PR, a saved commit, no
@@ -519,7 +530,17 @@ worktrees. A manually reopened tab is not repeatedly closed in the same TUI inst
 
 Sources: [dispatcher.ts — workOnce, mergeOnce, scanOnce](../src/dispatcher.ts),
 [approval.ts](../src/approval.ts), [github.ts — mergeApproved](../src/github.ts),
-[ui.ts](../src/ui.ts), [activity.ts](../src/activity.ts).
+[ui.ts](../src/ui.ts), [activity.ts](../src/activity.ts),
+[sidebar.ts](../src/sidebar.ts), [runtime-panel.ts](../src/runtime-panel.ts).
+
+The runtime sidebar has an independent five-second observation loop with a
+four-second request bound and one-second local countdown updates. It combines
+`automation.github.monitor` with scheduler `status`; requests never advance a
+phase. It reports actual in-process worker/scan activity rather than deriving it
+from `ready`. Last successful readings remain visible with stale warnings after
+errors or 15 seconds without fresh data. `/botstatus` exposes a text report even
+without a sidebar. See [runtime panel details](runtime.md#runtime-status-sidebar)
+for task selection, cache observations and display limits.
 
 ## 8. Status, retries, and recovery
 

docs/installation.md

@@ -95,6 +95,22 @@ registers the server/UI loaders, and runs the wizard. Existing configuration and
 queues are preserved on upgrades. Do not combine global and project-local copies.
 No package is published to npm; `private: true` blocks accidental publication.
 
+## TUI rendering and source validation
+
+The runtime sidebar uses the host's OpenTUI/Solid APIs and semantic theme tokens.
+The package declares OpenTUI and Solid peer dependencies; server entrypoint imports
+stay independent of renderer initialization. A sidebar update requires both the
+owner plugin's monitor RPC and an updated/reopened TUI. An older or unavailable
+owner is shown as unavailable rather than silently idle. The integration follows
+the [OpenCode CLI plugin API](https://opencode.ai/v2/docs/build/plugins/cli/).
+
+For development, `npm ci` installs pinned renderer, theme and Bun test dependencies.
+`npm run check` includes `npm run test:tui`, which renders the actual sidebar using
+Bun's native OpenTUI support and checks live updates, stale readings, tab selection
+and a narrow layout. Bun is needed for this native renderer test, not for the
+Node-based management CLI. Package validation still imports the server and TUI
+entrypoints in an isolated Node installation without initializing a renderer.
+
 ## Testing and migration
 
 Use a separate test repository when testing on another machine. Independent

docs/releases.md

@@ -10,7 +10,7 @@ modify its files with the Contents API, or bypass its protection rules.
 | Event | Result |
 | --- | --- |
 | Commit/push on a feature branch without an open PR | No CI run and no package build. |
-| Open, reopen, or update a PR targeting `devel` or `release` | Full CI on Node 22 and 24, including build and isolated package installation. |
+| Open, reopen, or update a PR targeting `devel` or `release` | Full CI on Node 22 and 24, including native TUI rendering with the pinned Bun test dependency, build and isolated package installation. |
 | Merge a feature PR into `devel` | Accumulate changes without publication. |
 | Merge a same-repository `devel` → `release` PR | Automatic patch version, tag, publication, README commit on `release`, main promotion PR, and automatic merge back into `devel`. |
 | Close a PR without merging | No publication. |

docs/runtime.md

@@ -216,6 +216,56 @@ Pausing stops scheduled scans; it does not cancel accepted tasks or active sessi
 Do not run independent bots on two machines against the same issues: they do not
 share queue ownership across machines.
 
+## Runtime status sidebar
+
+The **BOT RUNTIME** section is appended to the existing right sidebar, preserving
+OpenCode's context information. Open the TUI in the configured primary owner
+checkout. Switching task tabs changes the task details while the scheduler and
+dispatcher rows continue to describe that owner project.
+
+The panel shows:
+
+- Dispatcher activity: idle, reconciling state, executing a task's actual phase,
+  checking merges, maintenance, or stopped. An active task key is shown separately.
+- GitHub discovery: scanning, the time the last scan finished, and any scan error.
+- Scheduler jobs: running, paused, next run time or retry delay, and errors.
+  Pausing polling can coexist with an already-running scan or task.
+- Queue counts: ready/retry-wait excluding the active task, waiting for replies, blocked/failed and published
+  tasks, excluding closed/merged PRs. Scheduled does not mean a model is executing.
+- Task details: issue, phase, round, observed main-session status, task/base branches,
+  model, queued feedback, allocated media helper count for the current session,
+  failed attempts, recovery request, PR state and any task/merge error.
+- Separate freshness information for dispatcher and scheduler readings.
+
+Task selection prefers the displayed session (including saved earlier-round and
+helper IDs), then the dispatcher's active task, then an open waiting/blocked task,
+then scheduled work, then the last known task. Main-session running/idle comes
+from the TUI's session cache when that session is available; otherwise the panel
+says `not observed`. Media counts do not claim that those helpers are running and
+do not count native implementation subagents.
+
+Read-only snapshots refresh on startup and every five seconds, with a four-second
+request deadline and no overlapping refreshes. Countdown labels update locally
+every second. No model is prompted and polling does not restart jobs or repair
+queue state. A failed request retains the last successful snapshot with a stale
+warning; readings older than 15 seconds are also marked stale. Dispatcher and
+scheduler failures are independent, so a partial failure keeps the other component
+visible. Initial/unavailable data is never presented as a healthy idle service.
+
+Use `/botstatus` for a text report, including every known task and scheduler job,
+when the sidebar is hidden or more detail is needed. The sidebar shows up to three
+scheduler jobs and truncates long labels/errors. `/bot` opens task sessions;
+`/restartworkflow` remains the separate explicit recovery action.
+
+The TUI and owner plugin must both contain the monitor API. With an older server,
+an unloaded/unconfigured owner, a direct worktree-only launch, or a failed RPC,
+the panel reports unavailable status. Load the configured owner and update both
+sides as needed; reopen TUI clients after installation. Monitoring uses the
+connected OpenCode client, so it also works with a remote service when the correct
+owner location and updated plugin are available there. Live worker/scan diagnostics
+reset when the owner is recreated; task checkpoints and scheduler history remain
+durable as before.
+
 ## Interrupted sessions and workflow recovery
 
 If you manually continue a timed-out or interrupted bot session in the TUI,