Skip to content

feat(terminal): settings switch and off notices for dashboard.terminal.enabled - #31967

Open
DcXiaoBing wants to merge 1 commit into
kirodotdev:mainfrom
DcXiaoBing:fix/terminal-off-notice-settings-switch
Open

DcXiaoBing wants to merge 1 commit into
kirodotdev:mainfrom
DcXiaoBing:fix/terminal-off-notice-settings-switch

Conversation

@DcXiaoBing

@DcXiaoBing DcXiaoBing commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A dashboard whose terminal is turned off by dashboard.terminal.enabled: false tells the user why and offers a Settings switch to turn it back on, instead of opening an empty panel that never connects.

With the flag false, the Terminal rail entry hides only when the boot probe gets an explicit enabled: false; a loading, failed or timed-out probe reads as enabled, so the button stays, the panel opens, the WebSocket upgrade is refused with a 403 the browser cannot show, and the tab redials quietly ten times before "Terminal disconnected". The only text that names the key is the !command composer path. Settings → Display → Terminal shows no state for the flag and has no way to change it (#31652; proposal in #31652 (comment)).

Why it matters

The owner of a host with the flag false (set by hand or by an earlier build) cannot learn from the dashboard what is wrong or how to fix it; diagnosing it took reading the gateway source and the security event log. Every popout window and every tab restored from ui-prefs hits the same dead end.

Not a goal

What changed (motivation → approach → change)

Goal → approach: keep the existing hide-when-explicitly-off behaviour and the pinned test intent ("a transient failure must not hide an enabled terminal"), make the refused connection learn the flag instead of guessing, and give the flag one writer in the client so a stale server answer cannot overwrite it. Alternatives considered and dropped: showing the entry points when off and explaining on click (reverses the existing hide rule); a read-only hint in Settings with the flag left config-file-only (leaves no remedy in the UI).

Change:

  • website/src/utils/terminalRegistry.ts: a close that never opened triggers one GET /api/terminal/sessions look before redialling; an explicit enabled: false parks the connection (disabledByConfig), writes the terminal-enabled query cache and stops the backoff; a failed or refused look keeps the backoff as today. Connections parked this way redial automatically when the flag turns true again.

  • website/src/shell/boot/terminalRestore.ts, shell/appShell.tsx: the registry flag has a single writer, the probe's mirror of the query cache; the shell's own terminalEnabled reads that flag. Nothing that writes the cache (the look, the Settings PATCH) issues a refetch: a refetch landing inside the gateway's 30 s _is_enabled cache before the config watcher's poll would store the pre-flip value as fresh.

  • Notices naming dashboard.terminal.enabled and Settings → Display → Terminal: new TerminalOffNotice strip in the dock slot while restored tabs exist (App.tsx), the popout window (TerminalPopoutFrame.tsx, which now runs the probe and does not mint a tab or return to main while off), the tab banner (CliPanel.tsx, replacing "Terminal disconnected" for this case), and the existing composer, Run-yourself and guide texts.

  • pages/settings/DisplayPanel.tsx: owner-only "Terminal panel" switch (owner from the people route's is_viewer && is_owner) through the existing PATCH /api/config/kirocrew path; dashboard.terminal.enabled joins _EDITABLE_CONFIG (core_config_schema.py, comment rewritten) and sections_dashboard.py; a confirm step when shells are live; a message for the 409 config.local.json overlay case; hidden on the embed settings page (embed prop).

  • docs/decisions/2026-11-06-the-terminal-switch-is-editable-from-settings.md records this as a proposal accepted at this review; docs/system-specs/modules/learn-cron-dashboard.md paragraphs updated. Note for the First Principles lane: this reverses the "config-file-only" note for one key; the decision entry ships in this PR, there is no prior RFC on main, so a maintainer ruling is needed here.

  • Policy-locked state (boot.allow_terminal: false, fix(governance): make boot.allow_terminal refuse the dashboard terminal #34071): GET /api/terminal/sessions adds locked_by_policy to its explicit-false answer; the notices then name the organization policy instead of the config key, the Settings row is disabled with the existing policy note, and PATCH dashboard.terminal.enabled=true is refused with 403 under the lock (false stays writable). The PATCH refusal and the off-click both write the lock into the terminal-enabled cache, so a page that cached a config-off answer learns the lock without a refetch.

  • Live teardown comes from fix(terminal): end every terminal session when the panel is switched off #31579 (merged): test_live_applier_symbol asserts the applier symbol exists so the switch cannot ship without it.

Backwards compatibility

Compatible: dashboard.terminal.enabled keeps its meaning and default; config.json and kirocrew config set remain valid writers; every surface that is hidden on an explicit false today stays hidden; the three existing off-state strings are reworded, not removed; no route or response shape changes.

Removes nothing: the "Terminal disconnected" banner is still shown for every close that is not an explicit configuration refusal.

Tests

  • terminalRegistry.disabledByConfig.test.ts (new): look on a never-opened close; explicit false parks the tab and writes the cache; 500 / 403 / rejected look keeps the backoff; an opened-then-dropped socket does no look; sawOpen resets per dial.
  • App.terminalEnabledFlag.test.tsx (extended) and App.terminalOffNotice.test.tsx (new): the three existing cases keep their expectations; end-to-end 500 probe → refused socket → look → cache write → rail hidden and notice shown; a cached explicit false survives a later non-OK refetch.
  • terminalRestore.probe.test.ts (new): the probe never overwrites a cached enabled: false with a failed answer.
  • TerminalPopoutFrameCov80.test.tsx (extended): fresh popout on an enabled host still mints; explicit false shows the notice and never returns to main, including when the last tab is removed.
  • DisplayPanel.terminalEnabled.test.tsx (new): owner sees the switch, non-owner and embed page do not; confirm when shells are live; 409 overlay message.
  • CliPanelCoverage.test.tsx (extended): disabledByConfig renders the status notice, not the disconnected banner.
  • test/test_config_patch_terminal_enabled.py (new): owner PATCH flips the key, non-owner is refused, _editable_config_spec entry, applier symbol present (fix(terminal): end every terminal session when the panel is switched off #31579), PATCH true refused with 403 under a policy lock while false is accepted; test_terminal_policy_gate.py unchanged and green.
  • Policy lock (frontend): list locked_by_policy reaches the cache and the registry; notices show the policy text; Settings row disabled with the policy note; the 403 and the off-click both preserve the lock in the cache; a deferred refused-dial look that resolves after a newer connection opened is dropped (socket-identity guard).
  • TerminalRegistryCoverage.test.tsx: 8 existing backoff tests now stub the look (500) and await it; no assertion weakened. T1's list fixture gained locked_by_policy: false (the field is now always present).
  • i18n: I18N_BASE_REF=<base> npm run i18n:check passes; every new key has an en.context.json note; pseudolocale regenerated.

Proof: not provable -- frontend test (prove.py runs Python only); the Python-side change is a schema entry whose tests are new.

Manual verification

Still required before marking ready: on a host with dashboard.terminal.enabled: false, (1) open the dashboard with a restored tab and confirm the strip names the key and links to Settings; (2) open /popout/terminal and confirm the notice; (3) flip the switch in Settings → Display → Terminal with a live shell and confirm the confirm dialog, the shell ending, and the tab reconnecting after switching back on; (4) with security_policy.json boot.allow_terminal: false, confirm the policy wording and the disabled row.

Screenshots / video

Config off (dashboard.terminal.enabled: false): the Settings row is the one place the terminal still appears; the rail button and dock are gone.

Settings > Display > Terminal row with the Terminal panel switch off; no Terminal button in the rail

Turning it off while a shell is running asks first (count from the gateway registry):

Confirm dialog: 1 terminal shell is running, Turn off and end shells

Tabs restored from storage after the flip: the dock strip takes the panel's slot and links to the switch.

Dock strip: The Terminal is turned off by this dashboard's configuration, with Open Terminal settings

Same state with a side-panel terminal tab: its socket is refused, the tab shows the banner with Open Terminal settings and Reconnect, the dock strip below.

Side-panel terminal tab banner and dock strip together

Popout window, config variant:

Popout notice, configuration variant

Policy lock (allow_terminal refused in security_policy.json): the switch is disabled with the policy note; the popout says policy instead of configuration.

Settings row locked by security policy Popout notice, policy variant

Related Issues

Fixes #31652
Related: #31579 (merged, provides the live teardown), #34071 (policy lock), #26768, #30367

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.


Drafted with AI assistance (Kiro Crew); five red-team rounds across three model families before and after opening; reviewed by the author.

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 7, 2026
@DcXiaoBing
DcXiaoBing force-pushed the fix/terminal-off-notice-settings-switch branch from f5a0441 to 554b705 Compare November 10, 2026 20:39
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 10, 2026
@DcXiaoBing
DcXiaoBing marked this pull request as ready for review November 10, 2026 22:11
@DcXiaoBing
DcXiaoBing requested review from a team and KiroCrewCaptain as code owners November 10, 2026 22:11
@DcXiaoBing
DcXiaoBing requested a review from buluoray November 10, 2026 22:11
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider raised 1 possible problem and estimates a 72% chance that this change introduces a defect; a person should check it.

The code looks sound: the PATCH is owner-gated and refuses turning the terminal on under a security-policy lock, and the browser's refused-dial check and cache handling hold up. But the PR adds an immutable decision entry, 'Decided by: proposal, accepted at the review', that names no maintainer. That breaks rule 4 of docs/decisions/README.md, and the PR itself says a maintainer ruling is still needed. The entry reverses the config-file-only status of dashboard.terminal.enabled, letting an owner dashboard session turn the unsandboxed shell back on. That needs a maintainer's on-record decision before it merges. No CI tests had run on this head.

Things to check (possible problems the decider raised; at this confidence many turn out to be fine):

  • The PR adds a decision entry that names no maintainer. It reverses the documented config-file-only stance on dashboard.terminal.enabled (rewritten comment in core_config_schema.py), so an owner dashboard session can now turn the unsandboxed shell back on where before only the config file could. The (docs/decisions/2026-11-06-the-terminal-switch-is-editable-from-settings.md, high)

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 554b705f2c · 2160 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 11, 2026
@DcXiaoBing

Copy link
Copy Markdown
Contributor Author

Agreed on the decision-entry finding: Decided by: proposal, accepted at the review names no maintainer, so as written the entry breaks docs/decisions/README.md rule 4. The code review points (owner-gated PATCH, policy-lock refusal, refused-dial handling) match what the PR intends.

This is a product proposal, not a decision: we are not maintainers. The proposal and its reasoning are on the issue (#31652 (comment)). What the PR needs is a maintainer ruling, on this PR, on one question:

Should dashboard.terminal.enabled become editable from Settings (owner-only switch, policy lock honoured), reversing the config-file-only stance?

  • Yes → I update the entry's Decided by: to name the maintainer and cite that comment; nothing else in the PR changes.
  • No → I drop the Settings switch and the decision entry and keep only the notices on the hidden/refused paths (dock strip, popout, tab banner), which the issue's bug report needs regardless.

The branch is also behind main (one trivial conflict in website/src/i18n/pluralKeys.json); I will rebase in the same push as the entry fix so the lanes run once.

@bolichen97 @iamwhatever @buluoray @CrysisDeu — could one of you rule? (AI-assisted, author-reviewed.)

@DcXiaoBing
DcXiaoBing force-pushed the fix/terminal-off-notice-settings-switch branch from 554b705 to 550db9c Compare November 16, 2026 23:00
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 16, 2026
@DcXiaoBing
DcXiaoBing force-pushed the fix/terminal-off-notice-settings-switch branch from 550db9c to 4277874 Compare November 17, 2026 18:48
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 17, 2026
Hide the Terminal entry points only on an explicit `enabled: false`,
and tell the user why on every path that dead-ended silently: a dock
strip while restored tabs exist, the popout window, the tab banner,
and the composer, Run-yourself and guide texts, each naming
`dashboard.terminal.enabled` and Settings -> Display -> Terminal.

A refused WebSocket upgrade is a bodyless close the browser cannot
tell from a drop, so the registry follows a close that never opened
with one look at GET /api/terminal/sessions before redialling; an
explicit false parks the tab, writes the terminal-enabled query cache
and stops the chain, while a failed or refused look keeps the backoff.
The registry flag has one writer, the shell probe's mirror of that
cache, and no writer of the cache issues a refetch: a refetch landing
inside the gateway's 30 s gate cache before the config watcher's poll
would store the pre-flip bit as a fresh answer.

Settings -> Display -> Terminal gets an owner-only Terminal panel
switch on the config PATCH path the other Terminal rows use. Off
confirms when the gateway lists live shells; the live config applier
ends them and expires the gate cache, so the switch adds
no route and no teardown. The embed Settings page carries no row.

A security policy whose boot.allow_terminal is false refuses the
terminal the same way (kirodotdev#34071), so the list route's explicit-false
answer says `locked_by_policy: true`: the notices then name the
organization's policy, the Settings row is disabled with the
locked-by-policy note, and the config PATCH refuses the enable with
403 `terminal_locked_by_policy`; the switch writes that refusal into
the same cache, so a row opened on a cached config-off answer locks
without a refetch. Turning the terminal off stays writable.

Fixes kirodotdev#31652
@DcXiaoBing
DcXiaoBing force-pushed the fix/terminal-off-notice-settings-switch branch from 4277874 to 04c7bb4 Compare November 17, 2026 19:11
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 17, 2026
@DcXiaoBing

Copy link
Copy Markdown
Contributor Author

@bolichen97 could you take a look when you have a moment? You have been working in the terminal code (#33979), so you are probably the right person to ask.

The one open question is the product call in my earlier comment (#31967 (comment)): should dashboard.terminal.enabled be settable from Settings (owner-only, policy lock honoured)?

If that needs more discussion, I can split this PR. The off-state notices (dock strip, popout, tab banner, policy-locked wording) are the bug fix for #31652 and need no decision, so they could land on their own while the Settings switch and its decision entry wait for a ruling.

The branch is behind main again (19 files, mostly i18n appends); I will rebase once there is a direction, so CI runs once. (AI-assisted, author-reviewed.)

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Terminal: with dashboard.terminal.enabled: false the panel opens, the shell never connects, and nothing tells the user why

2 participants