fix(tui): complete launcher integration and rationale

.agents/notes/implemented/architecture/2026-07-28-tui-palette-single-source.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-28-tui-palette-single-source.md
+2026-07-28-tui-palette-single-source.md: 7027e650bfb94dca7608342b10c994b255f48d2d
+2026-07-28-tui-palette-single-source.zh.md: a956a916c01feceedc7b6b6715bee6ceb8b80e7f

.agents/notes/implemented/architecture/2026-07-28-tui-palette-single-source.md

@@ -0,0 +1,57 @@
+# Agent Note: One palette table, one role per meaning, printable by `/palette`
+
+Status: implemented
+
+English | [中文](2026-07-28-tui-palette-single-source.zh.md)
+
+## Problem
+
+The palette had fifteen roles built from escape codes written inline in `createPalette`, and three pairs of them resolved to the same SGR parameters: `added`/`success` were both `32`, `removed`/`error` both `31`, and on a light scheme `muted`/`dim` were both `90`. A reader picking `added` or `muted` believed they had chosen a distinct tone; they had chosen an alias. Nothing enumerated the roles, so no reader could compare them, and the codes existed only as literals at their use site.
+
+That hid a real defect for as long as it took a user to notice it. `dim` deliberately substituted ANSI 90 on light schemes, on the recorded theory that "SGR 2 lightens text on a light background." But lightening is precisely what a recessed tone must do, and ANSI 90 is a fixed hue: on a light theme whose default foreground is a soft gray, bright black is *heavier* than ordinary text. Every surface the TUI called dim — tool-card bodies, the timing footer, injected context, dialog chrome — therefore rendered as the most prominent text on screen, inverting the one relationship the role exists to express. The role named `dim` was the least dim thing in the transcript.
+
+Nothing prevented the inversion from being introduced, and nothing revealed it afterwards. There was no listing to compare tones in, and terminal captures report escape codes rather than rendered luminance, so reading `\x1b[90m` and concluding "gray, therefore recessed" is a mistake a reader repeats indefinitely without a rendered sample to check against.
+
+A second hazard was latent in the same design. SGR has no color stack: a nested span's close emits `39` (default foreground), not the enclosing color, so wrapping colored text in a second color silently drops the outer color for the remainder of the line. Only the type `(text: string) => string` guarded that, which is to say nothing guarded it.
+
+## Decision
+
+`paletteSpec(scheme)` is the single table of every SGR code the TUI may emit. Each entry carries `open`, `close`, and a `purpose` string. `createPalette` derives its wrappers by iterating `COLOR_ROLES` and `ATTRIBUTE_ROLES` over that table, and the `/palette` command prints it, so a role cannot exist in the palette without appearing in the listing or the reverse. No component writes an escape sequence of its own. The startup banner's brand gradient stays the one deliberate exception, since fixed brand color is its point.
+
+`close` MUST reset every SGR group `open` sets. This is stated on `ansi` because the roles that violated it did so silently: `dim` opened `2;39` while closing only `22`, leaking a foreground reset past its own span.
+
+Roles that resolved to the same escape are merged rather than kept as aliases. `muted` folds into `dim`, `added` into `success`, and `removed` into `error`, leaving seven colors and five attributes. `accent` becomes ANSI 95, the tone this terminal actually reads as emphasis, and the single-use `accent2` is deleted rather than kept as a second accent.
+
+`dim` is `2;39` closing `22;39` on both schemes. SGR 2 fades relative to whatever foreground the terminal is using, which is the only way to land *below* `text` on a light and a dark theme with one code; `39` pins the starting foreground to the default so the tone does not inherit a caller's color. Only `code` still varies by scheme, because ANSI 36 is genuinely hard to read on a light background.
+
+Colors and attributes are separately typed. A `ColorRole` takes `Colorable` and returns `Colored`; an `AttributeRole` is generic and preserves its argument's type. So `bold(accent(x))` and `accent(bold(x))` both compile, `accent(error(x))` does not, and — because the brand survives an attribute layer — neither does `dim(bold(success(x)))`.
+
+## Alternatives considered
+
+**Keep ANSI 90 for `dim` and adjust the surfaces that looked wrong.** Rejected: the surfaces were right and the tone was wrong. Every consumer of `dim` wanted the same thing, so the fix belongs in the one role, not in each caller.
+
+**Plain SGR 2 without the `39`.** Considered; the user compared both rendered against their own background. Both read as genuinely dim, and `2` alone is the smaller change, but `2;39` guarantees the span starts from the default foreground rather than inheriting a caller's color, which matters wherever `dim` wraps content that may already be styled.
+
+**Keep `muted` and `dim` as separate names against future differentiation.** Rejected: they resolved to one escape on one of the two supported schemes, and a name that sometimes aliases another is worse than one name. Reintroducing a second recessed tone is a new decision, to be made when a consumer needs it.
+
+**Enforce the no-nested-color rule by convention and review.** Rejected: the rule is mechanically checkable and the failure is invisible — a dropped outer color looks like a rendering quirk, not a bug. The brands cost two type aliases and caught four deliberate violations in a compile check.
+
+**A runtime guard that strips or rejects nested colors.** Rejected: it moves a statically decidable error to run time and would have to allocate on every styled span, in the render hot path.
+
+**Print the palette to stdout from a script instead of a TUI command.** Rejected: the point is to see the tones the *running* TUI produces in the *user's* terminal, under the scheme it actually resolved. A script cannot report the live scheme, and this specific bug was invisible outside the real terminal.
+
+## Consequences
+
+The listing is now the fastest way to find a palette defect: `/palette` shows every role painted by its own code beside the SGR pair it reports, so a tone that misbehaves is visible next to its neighbours instead of inferred from escape numbers. It also reports the resolved scheme, which surfaced that scheme detection is not stable across launches — an unrelated bug this change makes observable but does not fix.
+
+Four role names disappear from the palette, and `muted` leaves the public extension `TuiTheme`; an extension that wants a recessed tone uses `dim`. Merging the diff pair means `success` and `error` each carry two meanings, which is honest about there being one green and one red rather than implying a diff-specific palette.
+
+The brands introduce a small friction: an array literal seeded with a colored string infers `Colored[]`, so two call sites now annotate `string[]` explicitly. That is the cost of the guarantee, and it appears at declaration sites rather than in styling expressions.
+
+`accent` moving to 95 repaints twenty-four call sites, including Markdown headings and links, dialog borders, and the prompt. That is a visible change to surfaces beyond the reported defect, made because a single emphasis color is the point of the reduction.
+
+## Testing
+
+`packages/ui/tui/tests/tui.spec.ts` asserts `/palette` prints every name and `purpose` in `paletteSpec` and that each row carries the spec's own open code, so a role added to the table without a listing entry, or a listing that reports one code while rendering another, fails. Verified by construction: truncating the attribute loop makes the test fail rather than pass silently.
+
+The scheme-detection test previously pinned `dim` changing between schemes, which is no longer true; it now pins scheme-independent `dim` alongside the `code` role that does vary. The blank-row and running-glyph tests carry the new SGR pairs. The no-nested-color rule is verified by compiling deliberate violations against the project's own tsconfig, where the four color-over-color expressions are rejected and the five legal attribute compositions are not.

.agents/notes/implemented/architecture/2026-07-28-tui-palette-single-source.zh.md

@@ -0,0 +1,57 @@
+# Agent Note: 单一调色板表、每种含义一个角色，并可通过 `/palette` 打印
+
+Status: implemented
+
+[English](2026-07-28-tui-palette-single-source.md) | 中文
+
+## Problem
+
+调色板原有十五个角色，其转义码直接写在 `createPalette` 中，其中三对角色解析为相同的 SGR 参数：`added`/`success` 都是 `32`，`removed`/`error` 都是 `31`，而在浅色配色方案中，`muted`/`dim` 都是 `90`。读者选择 `added` 或 `muted` 时，会以为自己选了不同的色调，实际上选到的只是别名。没有任何地方枚举这些角色，因此读者无法比较它们，而这些转义码也仅以字面量存在于使用处。
+
+这个设计一直掩盖着一个真实缺陷，直到用户亲眼发现。`dim` 在浅色配色方案中刻意改用 ANSI 90，依据是记录中「SGR 2（dim）会让浅色背景上的文本变淡」的理由。但变淡恰恰是弱化色调必须做的事，而 ANSI 90 是固定色相：如果浅色主题的默认前景色是柔和的灰色，亮黑色就会比普通文本*更重*。因此，TUI 中所有称作 dim 的界面——工具卡片正文、计时页脚、注入的上下文、对话框边框——都会渲染为屏幕上最醒目的文本，颠倒了该角色本应表达的唯一关系。名为 `dim` 的角色反而成了 transcript（文本记录）中最不弱化的内容。
+
+这个颠倒既没有防范机制，发生后也没有显现机制。没有可供比较色调的清单，而终端捕获记录的是转义码而非渲染亮度，因此看到 `\x1b[90m` 就断定「这是灰色，所以会弱化」，是读者在没有渲染样例可供核对时会不断重复的错误。
+
+同一设计中还潜藏着第二个风险。SGR 没有颜色栈：嵌套区段的关闭码会发出 `39`（默认前景色），而不是外层颜色，因此用第二种颜色包裹已经着色的文本，会悄然丢弃该行剩余部分的外层颜色。唯一的防护只是类型 `(text: string) => string`，也就是说实际上毫无防护。
+
+## Decision
+
+`paletteSpec(scheme)` 是 TUI 可以发出的所有 SGR 码的唯一表。每个条目都包含 `open`、`close` 和一个 `purpose` 字符串。`createPalette` 遍历该表的 `COLOR_ROLES` 与 `ATTRIBUTE_ROLES` 来派生包装函数，`/palette` 命令则打印该表，因此一个角色不可能只存在于调色板中却不出现在清单里，反之亦然。任何组件都不会自行写入转义序列。启动横幅的品牌渐变色是唯一的有意例外，因为固定品牌色本来就是它的目的。
+
+`close` 必须重置 `open` 设置的每一个 SGR 组。该要求在 `ansi` 上明确说明，因为此前违反要求的角色没有显露问题：`dim` 以 `2;39` 开启，却只以 `22` 关闭，导致前景色重置越过其自身区段而泄漏。
+
+解析为同一转义码的角色会合并，而不是作为别名保留。`muted` 并入 `dim`，`added` 并入 `success`，`removed` 并入 `error`，最终留下七种颜色和五种属性。`accent` 改为 ANSI 95，这是该终端中实际呈现为强调色的色调；仅使用一次的 `accent2` 则直接删除，不再作为第二种强调色保留。
+
+在两种配色方案中，`dim` 都以 `2;39` 开启、以 `22;39` 关闭。SGR 2 会相对于终端当前使用的前景色减淡，这是仅用一个代码就在浅色和深色主题中落到 `text` *之下*的唯一方式；`39` 将起始前景色固定为默认值，使该色调不会继承调用方的颜色。只有 `code` 仍然随配色方案而变化，因为 ANSI 36 在浅色背景上确实难以辨认。
+
+颜色与属性分别采用不同的类型。`ColorRole` 接受 `Colorable` 并返回 `Colored`；`AttributeRole` 是泛型，会保留实参的类型。因此 `bold(accent(x))` 和 `accent(bold(x))` 都能编译，`accent(error(x))` 不能；而且——由于品牌标记可以穿过一层属性——`dim(bold(success(x)))` 同样不能编译。
+
+## Alternatives considered
+
+**保留 ANSI 90 作为 `dim`，并调整显示异常的界面。**否决：界面没有问题，错的是色调。`dim` 的所有消费方都需要同一种效果，因此修复应落在这个角色本身，而不是每个调用方中。
+
+**不带 `39` 的纯 SGR 2。**考虑过；用户在自己的背景上比较了两者的渲染效果。两者看起来都确实弱化，单独使用 `2` 也是更小的改动，但 `2;39` 可以保证区段从默认前景色开始，而不是继承调用方的颜色；当 `dim` 包裹可能已有样式的内容时，这一点很重要。
+
+**保留 `muted` 与 `dim` 两个名称，以备日后加以区分。**否决：它们在两种受支持的配色方案之一中解析为同一个转义码，而一个有时成为其他名称别名的名称，还不如只保留一个名称。重新引入第二种弱化色调是一项新决策，应等到消费方确有需要时再作出。
+
+**通过约定和评审来执行禁止嵌套颜色的规则。**否决：这条规则可以机械检查，而且故障不可见——外层颜色丢失看起来会像渲染异常，而不是缺陷。品牌类型的代价只是两个类型别名，却在编译检查中捕获了四处刻意构造的违规。
+
+**在运行时剥离或拒绝嵌套颜色的防护。**否决：这会把一个可静态判定的错误推迟到运行时，并且必须在渲染热路径中为每个带样式的区段分配内存。
+
+**通过脚本将调色板打印到 stdout，而不是使用 TUI 命令。**否决：目的是在*运行中的* TUI 所实际解析出的配色方案下，查看它在*用户自己的*终端中产生的色调。脚本无法报告实时配色方案，而这个特定缺陷在真实终端之外不可见。
+
+## Consequences
+
+现在，清单是发现调色板缺陷最快的方式：`/palette` 会用每个角色自身的代码绘制该角色，并在旁边显示其报告的 SGR 码对，因此表现异常的色调会直接出现在邻近角色旁边，而不必根据转义码数字推断。它还会报告解析出的配色方案，由此揭示配色方案检测在多次启动之间并不稳定——这是本次变更令其可观察、但并未修复的无关缺陷。
+
+调色板中消失了四个角色名称，`muted` 也从公共扩展 `TuiTheme` 中移除；需要弱化色调的扩展应使用 `dim`。合并差异对意味着 `success` 和 `error` 各自承载两种含义，这如实反映了系统只有一种绿色和一种红色，而不会暗示另有差异专用调色板。
+
+品牌类型带来了一点不便：如果数组字面量以着色字符串开头，便会推断为 `Colored[]`，因此现在有两个调用点需要显式标注 `string[]`。这是该保证的代价，而且它出现在声明位置，而不是样式表达式中。
+
+`accent` 改为 95 后，二十四个调用点随之重新着色，包括 Markdown 标题和链接、对话框边框以及提示行。这是报告缺陷之外其他界面的可见变化；作出这一改动，是因为精简的目的正是只保留一种强调色。
+
+## Testing
+
+`packages/ui/tui/tests/tui.spec.ts` 断言 `/palette` 会打印每个名称和 `purpose`（均来自 `paletteSpec`），并且每一行都包含规格自身的开启码，因此在表中添加角色却没有清单条目，或清单报告的代码与渲染使用的代码不同，都会导致测试失败。构造验证也已完成：截断属性循环会让测试失败，而不会静默通过。
+
+配色方案检测测试此前固定了 `dim` 会随配色方案变化的行为，但现在已不再如此；该测试现在同时固定与配色方案无关的 `dim`，以及确实会变化的 `code` 角色。空白行测试与运行状态字形测试包含新的 SGR 码对。禁止嵌套颜色的规则通过项目自身的 tsconfig 编译刻意构造的违规来验证，其中四个颜色叠加颜色的表达式会被拒绝，五个合法的属性组合则不会。