Repository navigation
feat(terminal): settings switch and off notices for dashboard.terminal.enabled - #31967
DcXiaoBing wants to merge 1 commit into
Conversation
f5a0441 to
554b705
Compare
Code change approver recommendation: A person should decideWhy: 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):
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 |
|
Agreed on the decision-entry finding: 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:
The branch is also behind @bolichen97 @iamwhatever @buluoray @CrysisDeu — could one of you rule? (AI-assisted, author-reviewed.) |
554b705 to
550db9c
Compare
550db9c to
4277874
Compare
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
4277874 to
04c7bb4
Compare
|
@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 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 |
Problem / Motivation
Goal: A dashboard whose terminal is turned off by
dashboard.terminal.enabled: falsetells 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!commandcomposer 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
security_policy.jsonallow_terminalin the dashboard (The policy setting that says "no terminal" does not stop the dashboard terminal #30367).boot.allow_terminalanywhere the gateway does not already read it: the dashboard only reflects_is_enabled()'s answer (fix(governance): make boot.allow_terminal refuse the dashboard terminal #34071).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 oneGET /api/terminal/sessionslook before redialling; an explicitenabled: falseparks the connection (disabledByConfig), writes theterminal-enabledquery 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 ownterminalEnabledreads 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_enabledcache before the config watcher's poll would store the pre-flip value as fresh.Notices naming
dashboard.terminal.enabledand Settings → Display → Terminal: newTerminalOffNoticestrip 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'sis_viewer && is_owner) through the existingPATCH /api/config/kirocrewpath;dashboard.terminal.enabledjoins_EDITABLE_CONFIG(core_config_schema.py, comment rewritten) andsections_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 (embedprop).docs/decisions/2026-11-06-the-terminal-switch-is-editable-from-settings.mdrecords this as a proposal accepted at this review;docs/system-specs/modules/learn-cron-dashboard.mdparagraphs 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/sessionsaddslocked_by_policyto 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, andPATCH dashboard.terminal.enabled=trueis refused with 403 under the lock (falsestays writable). The PATCH refusal and the off-click both write the lock into theterminal-enabledcache, 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_symbolasserts the applier symbol exists so the switch cannot ship without it.Backwards compatibility
Compatible:
dashboard.terminal.enabledkeeps its meaning and default; config.json andkirocrew config setremain 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;sawOpenresets per dial.App.terminalEnabledFlag.test.tsx(extended) andApp.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 cachedenabled: falsewith 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):disabledByConfigrenders 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_specentry, applier symbol present (fix(terminal): end every terminal session when the panel is switched off #31579), PATCHtruerefused with 403 under a policy lock whilefalseis accepted;test_terminal_policy_gate.pyunchanged and green.locked_by_policyreaches 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 gainedlocked_by_policy: false(the field is now always present).I18N_BASE_REF=<base> npm run i18n:checkpasses; every new key has anen.context.jsonnote; 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/terminaland 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) withsecurity_policy.jsonboot.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.Turning it off while a shell is running asks first (count from the gateway registry):
Tabs restored from storage after the flip: the dock strip takes the panel's slot and links to the switch.
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.
Popout window, config variant:
Policy lock (
allow_terminalrefused insecurity_policy.json): the switch is disabled with the policy note; the popout says policy instead of configuration.Related Issues
Fixes #31652
Related: #31579 (merged, provides the live teardown), #34071 (policy lock), #26768, #30367
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)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.